Merge pull request #1789 from Polymer/2-master-merge

Merge changes from master

app/1.0/blog.yaml

@@ -1,4 +1,12 @@
 ---
+- title: "Please Welcome Polymer 1.7"
+  path: /1.0/blog/2016-10-03-1.7-release
+  published: 2016-10-06
+  author: polymer-team
+  description: "Polymer 1.7 provides forward compatibility features, plus a few bug fixes."
+  tags:
+     - blog
+     - announcements
 - title: "Polymer 2.0 Preview"
   path: /1.0/blog/2016-09-09-polymer-2.0
   published: 2016-09-09

app/1.0/blog/2016-09-09-polymer-2.0.md

@@ -92,4 +92,4 @@ For more detailed documentation on the `2.0` branch as it evolves, see the [READ
 
 Over the next couple months, we’ll be continuing to iterate on the API. We’ll also be upgrading the [elements built by the Polymer team](https://elements.polymer-project.org) to be built on top of 2.0.
 
-We'll also be talking a bunch more about Polymer 2.0 at the upcoming [Polymer Summit](https://www.polymer-project.org/summit). Looking forward to hearing what you think!
+We'll also be talking a bunch more about Polymer 2.0 at the upcoming <a href="/summit/" target="_blank">Polymer Summit</a>. Looking forward to hearing what you think!

app/1.0/blog/2016-10-03-1.7-release.md

@@ -0,0 +1,29 @@
+---
+title:  "1.7 Release"
+
+---
+_We announce significant releases here on the blog, highlighting the major new features as well as breaking changes. As always, we'd love to get your feedback, issues, and PR's, so tweet us [@polymer](https://twitter.com/polymer) or contribute to the [Github](https://github.com/Polymer)._
+
+The primary goal of the upcoming Polymer 2.0 release is to take advantage of native, cross-browser support for Web Components. With this in mind, we're pleased to release Polymer 1.7, which introduces features allowing you to use 2.0-compatible syntax in 1.x elements.
+
+## Polymer 1.7
+
+Polymer 1.7.0 provides forward compatibility features that let you build elements that run under both 1.0 and 2.0. 
+
+While you can use these features now, the team intends to release a tool to help automate these changes. If you have a large project, you might want to wait for the migration tool to be available.
+
+The new syntax is not required for current Polymer 1.x elements, but using the new syntax will make it easier to port elements to 2.0, which requires it.
+
+### `<slot>` element 
+
+Elements can opt-in to using the new `<slot>` element and `::slotted()` CSS selector from shadow DOM v1.
+
+These replace the `<content>` element and `::content` selector in shadow DOM v0. The v1 API is somewhat more restrictive, so you should read up on the details before making changes.
+
+### `html` selector in `<style is="custom-style">`, `:host > * ` selector in elements
+
+Polymer 2.0 removes support for the `:root` selector. In a `custom-style` element, you can use `html` where you used to use `:root`. Inside an element, you can use `:host > *`.
+
+Polymer 1.7 adds support for using the `html` selector in a custom-style element, so you can use the 2.0-compatible syntax. (The `:host > *` syntax was already supported.)
+
+For more details, read the full release notes here: <a href="https://www.polymer-project.org/1.0/docs/release-notes#v-1-7-0">Release 1.7.0</a>

app/1.0/blog/es6.md

@@ -281,7 +281,6 @@ As you've seen, defining custom elements and/or Polymer elements using classes i
 ### Additional resources
 
 - [Using ES6 with Polymer](https://www.youtube.com/watch?v=bX3_tN23M_Y) video from Polymer Summit 2015
-- [Polymer Starter Kit](https://github.com/PolymerElements/polymer-starter-kit/blob/master/docs/add-es2015-support-babel.md) support/recipe
 - [BabelJS](https://babeljs.io/)—transpiler for ES6 -> ES5
 - [ES6 In Depth articles](https://hacks.mozilla.org/category/es6-in-depth/) on Mozilla Hacks
 - [Custom Elements 101](http://www.html5rocks.com/en/tutorials/webcomponents/customelements/) on html5rocks

app/1.0/blog/routing/demo1.html

@@ -37,9 +37,13 @@
                 // Route objects are composed of the `path` that we want to
                 // match on, the `prefix`, which is everything that has already
                 // been matched by someone else before it got to us, and
-                // a queryParams object, which represents the ?key=value part
+                // an __queryParams object, which represents the ?key=value part
                 // of the URL.
-                return {path: '/store/garden', prefix: '', queryParams: {}}
+                // __queryParams is preceded by underscores because unless you're
+                // doing the power-user thing of generating your own route objects,
+                // you want to access query params directly from the <app-route>
+                // element.
+                return {path: '/store/garden', prefix: '', __queryParams: {}}
               }
             }
           }

app/1.0/docs/devguide/data-binding.md

@@ -198,18 +198,13 @@ because the binding causes issues on one or more browsers.
 
 You need to use attribute bindings to affect the following properties:
 
-| Attribute | Property | Notes
-
+| Attribute | Property | Notes |
+| --------- | -------- | ----- |
 | `class` | `classList`, `className` | Maps to two properties with different formats.
-
 | `style` | `style` | By specification, `style` is considered a read-only reference to a `CSSStyleDeclaration` object.
-
 | `href` | `href` |
-
 | `for` | `htmlFor` |
-
 | `data-*` |  `dataset` | Custom data attributes (attribute names starting with `data-`) are stored on the `dataset` property.
-
 | `value` | `value` | Only for `<input type="number">`.
 
 **Note:** data binding to the `value` property doesn't work on IE for ***numeric input types***. For

app/1.0/docs/devguide/data-system.md

@@ -324,7 +324,7 @@ Related tasks:
 Sometimes an element has two paths that point to the same object.
 
 For example, an element has two properties, `users` (an array) and `selectedUser` (an object). When
-a user is selected, `selectedUser` refers one of the objects in the array.
+a user is selected, `selectedUser` refers to one of the objects in the array.
 
 
 ![A user-list element and an array with four items labeled \[0\] through \[3\]. The user-list has two properties, users and selectedUser. The users property is connected to the array by an arrow labeled 1. The selectedUser property is connected to the array item, \[1\] by an arrow labeled 2.](/images/1.0/data-system/linked-paths-new.png)

app/1.0/docs/devguide/events.md

@@ -148,7 +148,7 @@ Example: { .caption }
 ## Property change events {#property-changes}
 
 You can configure an element to fire a non-bubbling DOM event when a specified
-property changes. For more information, see [Change notification events](#change-events).
+property changes. For more information, see [Change notification events](data-system#change-events).
 
 ## Event retargeting {#retargeting}
 

app/1.0/docs/devguide/local-dom.md

@@ -236,7 +236,7 @@ Polymer.dom(this.root).appendChild(toLocal);
 // Insert to the local DOM
 var toInsert = document.createElement('div');
 var beforeNode = Polymer.dom(this.root).childNodes[0];
-Polymer.dom(this.root).insertBefore(toLocal, beforeNode);
+Polymer.dom(this.root).insertBefore(toInsert, beforeNode);
 ```
 
 You can use the [automatic node finding](#node-finding) feature to locate

app/1.0/docs/devguide/observers.md

@@ -129,12 +129,12 @@ Handling of undefined values **depends on the number of properties being observe
     (that is, they don't have the value `undefined`).
 
 *   **For a single property observer**, the rules are identical to a simple observer: the observer
-    is called *each time* an observable change is made to of the dependencies, **even if the new
+    is called *each time* an observable change is made to one of the dependencies, **even if the new
     value for the path is <code>undefined</code>.**
 
 
 *   <strong>A multi-property observer</strong> is called <em>each time</em> an observable change is
-    made to of the dependencies, <strong><em>unless</em> the new value for one of the paths is
+    made to one of the dependencies, <strong><em>unless</em> the new value for one of the paths is
     <code>undefined</code>.</strong>
 
 Complex observers should only depend on their declared dependencies.

app/1.0/docs/release-notes.md

@@ -11,6 +11,120 @@ title: Release notes
   }
 </style>
 
+
+## [Release 1.7.0](https://github.com/polymer/polymer/tree/v1.7.0) (2016-09-29) {#v-1-7-0}
+
+This release includes forward compatibility features that let you build elements that run under
+both Polymer 1.7+ and Polymer 2.0.
+
+The syntax changes described here are **not required** for current Polymer 1.x elements, but using
+the new syntax makes for an easier transition to 2.x. The Polymer team plans to provide a
+tool to automate these and other changes required for moving from 1.x to 2.0, so if you have a large
+project, you may want to wait for an announcement about the migration tool.
+
+### Shadow DOM v1 slots
+
+To provide a smooth migration path from Polymer 1.x to 2.x, this release lets you
+opt-in to using the new `<slot>` element, and `::slotted()` CSS selector from shadow DOM v1 in place
+of the `<content>` element and `::content` selector from shadow DOM v0. (This release doesn't
+actually add support for shadow DOM v1, it just lets you use a forward-compatible syntax.)
+)
+
+To update an element:
+
+*   Each `<content>` insertion point must be changed to `<slot>`.
+*   Insertion points that selected content using <code>&lt;content select="<var>selector</var>"&gt;</code>
+    must be changed to named slots: <code>&lt;slot name="<var>slot_name</var>"&gt;</code>. Note that
+    in shadow DOM v1, distributed content can _only_ be selected by slot name, not by tag name,
+    attributes or CSS classes.
+*   Users of your element must use the matching new <code>slot="<var>slot_name</var>"</code>
+    attribute to distribute content into a named slot.
+*   Any `::content` CSS selectors must be replaced with <code>::slotted(<var>selector</var>)</code>,
+    where <var>selector</var> is [compound selector](https://drafts.csswg.org/selectors-4/#compound)
+    that identifies a **top-level distributed child**. That is, `::slotted(.foo)` is equivalent to
+    `::content > .foo`.
+
+In Polymer 1.7, elements written with slots are re-written at runtime into the
+equivalent `<content>` elements and style rules, to work with shadow DOM v0.
+
+As written:
+{.caption}
+
+```html
+<dom-module id="x-forward-compat">
+  <template>
+    <style>
+      #container ::slotted(.foo) {
+        color: red;
+      }
+      #namedContainer ::slotted(*) {
+        border: 2px solid black;
+      }
+    </style>
+    <div id="namedContainer">
+      <slot name="named"></slot>
+    </div>
+    <div id="container">
+      <slot></slot>
+    </div>
+  </template>
+</dom-module>
+```
+
+After runtime transform:
+{.caption}
+
+```html
+<dom-module id="x-forward-compat">
+  <template>
+    <style>
+      #container ::content > .foo {
+        color: red;
+      }
+      #namedContainer ::content > * {
+        border: 2px solid black;
+      }
+    </style>
+    <div id="namedContainer">
+      <content select="[slot=named]"></content>
+    </div>
+    <div id="container">
+      <content></content>
+    </div>
+  </template>
+</dom-module>
+```
+
+Note that Polymer doesn't transform code that _uses_ this element.
+Anywhere you're using `x-forward-compat`, you'd have to change to the new slot syntax:
+
+```
+<x-forward-compat>
+  <h2 slot="named">I'm the named content</h2>
+  <span>This content goes to the default slot.</span>
+</x-forward-compat>
+```
+
+For more details about transitioning to `<slot>`, see the
+[2.0-preview README](https://github.com/Polymer/polymer/blob/2.0-preview/README.md#distribution).
+
+### Alternatives for `:root` selector
+
+Another Polymer 2.x change is removing the `:root` selector and replacing it with `html` in `<style is="custom-style">`, and `:host > *` in element styles.
+
+This release allows for using both `html` and `:root` in `<style is="custom-style">`, and using both `:root` and `:host > *` in element styles
+
+Bug fixes:
+
+[#3676](https://github.com/Polymer/polymer/issues/3676). The `preserve-content` attribute does not protect style tags nested in templates.
+
+[#3836](https://github.com/Polymer/polymer/issues/3836). `var()` functions rewritten incorrectly with `useNativeCSSProperties=true`.
+
+[#3957](https://github.com/Polymer/polymer/issues/3957). VoiceOver/iOS: Anchors do not fire tap.
+
+[#3965](https://github.com/Polymer/polymer/issues/3965). Performance regression on IE11.
+
+
 ## [Release 1.6.1](https://github.com/polymer/polymer/tree/v1.6.1) (2016-08-01) {#v-1-6-1}
 
 New features:
@@ -60,7 +174,7 @@ Bug fixes:
 
 -   [#3779](https://github.com/Polymer/polymer/issues/3779).
     When an attribute and a property are present at upgrade time,
-    the property should win. 
+    the property should win.
 
 -   [#3677](https://github.com/Polymer/polymer/issues/3677).
     Firing `value-changed` should not cause repeated value change on the

app/1.0/start/index.html

@@ -16,38 +16,12 @@
     min-width: 60%;
   }
 
-  .iframe-wrapper {
-    position: relative;
-    height: auto;
-    overflow: hidden;
-    /**
-     * There's a "responsive iframe" hack that adds a bottom badding of 56.25%
-     * to get the right aspect ratio for the video. However, because of the
-     * flexbox, this would end up too tall and add extra black borders which we
-     * don't need; decreasing the padding fixes that.
-     */
-    padding-bottom: 33%;
-  }
-
-  iframe {
-    position: absolute;
-    top: 0;
-    left: 0;
-    width: 100%;
-    height: 100%;
-  }
-
   @media (max-width: 1000px) {
     .example-code {
       width: 100%;
       margin-bottom: 40px;
     }
 
-    .iframe-wrapper {
-      /* use the correct aspect ratio for the video */
-      padding-bottom: 56.25%;
-    }
-
     /* The devguide has a left nav, which means we need to rejigger
      * the media breakpoints to account for that. */
     section {
@@ -73,8 +47,6 @@
     <h1>Get Started</h1>
     <div class="flex">
       <p>Ready to dive in? You're moments away from building your first element or your first app.</p>
-      <p>From here, you can also learn more about Polymer and the App Toolbox, watch some Polycasts, and set yourself up with the Polymer CLI.</p>
-      <!-- <a href="" class="blue-button vertical">Get the code</a> -->
     </div>
   </div>
 </section>
@@ -83,28 +55,25 @@ <h1>Get Started</h1>
   <div class="section-columns">
     <div class="flex">
       <h2 class="underline">Use Elements</h2>
-      <p>The easiest way to dip your toe in the Web Components pool is to grab some elements and try them out.</p>
-      <p>The Polymer Element Catalog houses several collections of Web Components that you can use in your apps.</p>
-      <p>The elements in the catalog have been built with Polymer, but – since Web Components are inherently interoperable – can be used on any site.</p>
+      <p>Get started using Web Components in your apps.</p>
+      <p>Browse the Polymer Element Catalog for interoperable elements that can be used on any site.</p>
       <a href="https://elements.polymer-project.org/" target="_blank" class="blue-button vertical full-width">Browse elements</a>
       <a href="https://elements.polymer-project.org/guides/using-elements" target="_blank" class="blue-button vertical full-width flat">Learn more</a>
     </div>
 
     <div class="flex">
       <h2 class="underline">Build Elements</h2>
-      <p>If you're ready to create your own elements, the Polymer library has you covered.</p>
-      <p>Custom elements are ideal for extending HTML semantics, branding and polishing your UI, or embedding rich functionality in your site.</p>
-      <p>Build elements for your own use, to share with your organization or to save the world, one widget at a time.</p>
+      <p>Ready to create your own elements? The Polymer library has you covered.</p>
+      <p>With custom elements, you can extend HTML semantics, brand and polish your UI, or embed rich functionality in your site.</p>
       <a href="/1.0/start/first-element/intro" class="blue-button vertical full-width">Build an element</a>
       <a href="/1.0/docs/devguide/feature-overview" class="blue-button vertical full-width flat">Learn more</a>
       <!-- <a href="/1.0/tools/" class="blue-button">Using the tools</a> -->
     </div>
 
     <div class="flex">
       <h2 class="underline">Build Apps</h2>
-      <p>You can also use Web Components to build apps from the ground up.</p>
-      <p>The Polymer App Toolbox helps you build Progressive Web Apps using Web Components and a set of complementary new web platform features.</p>
-      <p>Use the pieces of the Toolbox individually, or use them together to deliver truly modern apps that launch quickly, respond instantly and work from anywhere.</p>
+      <p>Build Progressive Web Apps from the ground up with Web Components.</p>
+      <p>Use the pieces of the Polymer App Toolbox to deliver fast, responsive apps that work from anywhere.</p>
       <a href="/1.0/start/toolbox/set-up" class="blue-button vertical full-width">Build an app</a>
       <a href="/1.0/toolbox/" class="blue-button vertical full-width flat">Learn more</a>
     </div>
@@ -125,7 +94,7 @@ <h2>Watch the Polycasts</h2>
           </google-youtube>
       </div>
       <div>
-        <p>Ready to get your hands dirty and revolutionize the modern web? Join Rob Dodson from the Chrome Developer Relations team as he explores the ins and outs of Polymer, a new library that's pushing the boundaries of what's possible in the browser. Learn about the basic building blocks that make up a Polymer application, and see how to compose those elements into buttery smooth mobile experiences. The future of front end development is all here, on the Polycasts playlist!</p>
+        <p>Join Rob Dodson from the Chrome Developer Relations team for Polycasts, a comprehensive set of videos exploring the ins and outs of Polymer. Start a new Polymer project from scratch, add functionality to your elements, or get a crash course on understanding data binding. Create accessible components, and localize them for your target audience.</p>
         <a href="https://www.youtube.com/playlist?list=PLOU2XLYxmsII5c3Mgw6fNYCzaWrsM3sMN" class="blue-button">Watch more</a>
       </div>
     </div>

app/1.0/toolbox/app-layout.md

@@ -387,7 +387,7 @@ with drawer and header.
 
 ## Responsive navigation pattern
 
-In many cases, you'll want to switch you navigation based on the screen size. One common pattern
+In many cases, you'll want to switch your navigation based on the screen size. One common pattern
 uses navigation tabs on desktop, which are replaced by a navigation drawer on mobile, as in the
 [Shop app](https://shop.polymer-project.org/).
 

app/1.0/toolbox/case-study.md

@@ -5,13 +5,13 @@ title: "Case study: the Shop app"
 <!-- toc -->
 
 
-Shop is a full-featured e-commerce Progressive web app demo built using the
+Shop is a full-featured e-commerce Progressive Web App demo built using the
 Toolbox. You can try it out here:
 
 <a href="https://shop.polymer-project.org/" class="blue-button">Launch Shop demo
 </a>
 
-This case studies shows how Shop uses the App Toolbox to deliver a great
+This case study shows how Shop uses the App Toolbox to deliver a great
 user experience.
 
 ## App structure

app/1.0/toolbox/server.md

@@ -19,7 +19,7 @@ Your server logic can deliver the appropriate build for each browser.
 
 ## PRPL pattern
 
-To optimize delivery, the Toolbox uses the _PRPL pattern, which
+To optimize delivery, the Toolbox uses the _PRPL pattern_, which
 stands for:
 
 *  Push critical resources for the initial route.