Merge branch 'master' into rewrite-expression-parser

.gitignore

@@ -11,4 +11,7 @@ dist
 
 # misc
 .DS_Store
-npm-debug.log
+npm-debug.log
+
+# Analyzer output used in the docs
+analysis.json

CONTRIBUTING.md

@@ -149,3 +149,14 @@ to run tests on a subset of available browsers, or to run tests remotely using S
 
 See the [`web-component-tester` README](https://github.com/Polymer/web-component-tester) for
 information on configuring the tool.
+
+### Viewing the source documentation locally
+
+You can view the updates you make to the source documentation locally with the following steps.
+Make sure to rerun step 1 after every change you make.
+
+1. Run `polymer analyze > analysis.json`
+
+1. Run `polymer serve`
+
+1. Open `http://127.0.0.1:PORT/components/polymer/` to view the documentation

README.md

@@ -27,6 +27,9 @@ Polymer 2.0 is released, and will be the future focus of Polymer development goi
 
 👀 **Looking for Polymer v1.x?** Please see the [the v1 branch](https://github.com/Polymer/polymer/tree/1.x).
 
+⁉️ **Looking to use Polymer with npm?** Polymer 1.x and 2.x both use `bower` for version management, but v3 and on will use `npm`. Please see our [v3 announcement](https://www.polymer-project.org/blog/2017-08-22-npm-modules.html) and [v3 hand-on](https://www.polymer-project.org/blog/2017-08-23-hands-on-30-preview.html) to use a preview version of v3.
+Versions before 3.0 are also published to npm "as-is" and are generally unsupported. These packages are for advanced users who configure their own tooling to work around the differences between Bower and npm packages, like package folder layout.
+
 ## Overview
 
 Polymer is a lightweight library built on top of the web standards-based [Web Components](http://webcomponents.org/) APIs, and makes it easier to build your very own custom HTML elements. Creating reusable custom elements - and using elements built by others - can make building complex web applications easier and more efficient. By being based on the Web Components API's built in the browser (or [polyfilled](https://github.com/webcomponents/webcomponentsjs) where needed), Polymer elements are interoperable at the browser level, and can be used with other frameworks or libraries that work with modern browsers.

bower.json

@@ -26,6 +26,7 @@
   "devDependencies": {
     "web-component-tester": "^6.0.0",
     "test-fixture": "PolymerElements/test-fixture#3.0.0-rc.1",
+    "iron-component-page": "PolymerElements/iron-component-page#^3.0.1",
     "perf-tester": "polymerlabs/perf-tester"
   },
   "private": true,

gulpfile.js

@@ -24,7 +24,7 @@ const size = require('gulp-size');
 const lazypipe = require('lazypipe');
 const closure = require('google-closure-compiler').gulp();
 const minimalDocument = require('./util/minimalDocument.js');
-const dom5 = require('dom5');
+const dom5 = require('dom5/lib/index-next');
 const parse5 = require('parse5');
 const replace = require('gulp-replace');
 

lib/legacy/legacy-element-mixin.html

@@ -164,6 +164,7 @@
        *
        * @return {void}
        * @override
+       * @suppress {invalidCasts}
        */
       _initializeProperties() {
         let proto = Object.getPrototypeOf(this);
@@ -172,7 +173,7 @@
           this._registered();
         }
         super._initializeProperties();
-        this.root = this;
+        this.root = /** @type {HTMLElement} */(this);
         this.created();
       }
 

lib/mixins/element-mixin.html

@@ -610,6 +610,9 @@
        *
        * These properties are retained unless a value of `null` is set.
        *
+       * Note: This function does not support updating CSS mixins.
+       * You can not dynamically change the value of an `@apply`.
+       *
        * @param {Object=} properties Bag of custom property key/values to
        *   apply to this element.
        * @return {void}