Merge branch 'master' into remove-render-helpers

Author: Steven Orvell

README.md

@@ -23,31 +23,32 @@ and renders declaratively using `lit-html`.
     be performed when a property is set, for example validation. Call `requestUpdate(name, oldValue)`
     in the setter to trigger an update and use any configured property options.
 
-    Properties can be given an options argument which is an object that describes how to
+    Properties can be given an `options` argument which is an object that describes how to
     process the property. This can be done either in the `@property({...})` decorator or in the
     object returned from the `properties` getter, e.g. `static get properties { return { foo: {...} }`.
 
     Property options include:
 
     * `attribute`: Indicates how and whether the property becomes an observed attribute.
-    If the value is `false`, the property is not added to `observedAttributes`.
-    If true or absent, the lowercased property name is observed (e.g. `fooBar` becomes `foobar`).
+    If the value is `false`, the property is not added to the static `observedAttributes` getter.
+    If `true` or absent, the lowercased property name is observed (e.g. `fooBar` becomes `foobar`).
     If a string, the string value is observed (e.g `attribute: 'foo-bar'`).
     * `type`: Indicates how to serialize and deserialize the attribute to/from a property.
-    If this value is a function, it is used to deserialize the attribute value
-    a the property value. If it's an object, it can have keys for `fromAttribute` and
-    `toAttribute` where `fromAttribute` is the deserialize function and `toAttribute`
-    is a serialize function used to set the property to an attribute. If no `toAttribute`
-    function is provided and `reflect` is set to `true`, the property value is set
-    directly to the attribute.
-    * `reflect`: Indicates if the property should reflect to an attribute.
-    If `true`, when the property is set, the attribute is set using the
-    attribute name determined according to the rules for the `attribute`
-    propety option and the value of the property serialized using the rules from
-    the `type` property option.
-    * `hasChanged`: A function that indicates if a property should be considered
-    changed when it is set. The function should take the `newValue` and `oldValue`
-    and return `true` if an update should be requested.
+    The value can be a function used for both serialization and deserialization, or it can
+    be an object with individual functions via the optional keys, `fromAttribute` and `toAttribute`.
+    `type` defaults to the `String` constructor, and so does the `toAttribute` and `fromAttribute`
+    keys.
+    * `reflect`: Indicates whether the property should reflect to its associated
+    attribute (as determined by the attribute option).
+    If `true`, when the property is set, the attribute which name is determined
+    according to the rules for the `attribute` property option, will be set to the
+    value of the property serialized using the rules from the `type` property option.
+    Note, `type: Boolean` has special handling by default which means that truthy
+    values result in the presense of the attribute, where as falsy values result
+    in the absense of the attribute.
+    * `hasChanged`: A function that indicates whether a property should be considered
+    changed when it is set and thus result in an update. The function should take the
+    `newValue` and `oldValue` and return `true` if an update should be requested.
 
   * **React to changes:** LitElement reacts to changes in properties and attributes by
   asynchronously rendering, ensuring changes are batched. This reduces overhead
@@ -161,7 +162,7 @@ into the element. This is the only method that must be implemented by subclasses
 
   * `update(changedProperties)` (protected): This method calls `render()` and then uses `lit-html`
   in order to render the template DOM. It also updates any reflected attributes based on
-  property values. Setting properties inside this method will *not* trigger another update..
+  property values. Setting properties inside this method will *not* trigger another update.
 
   * `firstUpdated(changedProperties)`: (protected) Called after the element's DOM has been
   updated the first time, immediately before `updated()` is called.
@@ -175,8 +176,8 @@ into the element. This is the only method that must be implemented by subclasses
 
   * `updateComplete`: Returns a Promise that resolves when the element has completed
   updating. The Promise value is a boolean that is `true` if the element completed the
-  update without triggering another update. This happens if a property is set inside
-  `updated()`. This getter can be implemented to await additional state.
+  update without triggering another update. The Promise result is `false` if a
+  property was set inside `updated()`. This getter can be implemented to await additional state.
   For example, it is sometimes useful to await a rendered element before fulfilling
   this Promise. To do this, first await `super.updateComplete` then any subsequent state.
 
@@ -195,14 +196,15 @@ into the element. This is the only method that must be implemented by subclasses
 
 ## Advanced: Update Lifecycle
 
-* When the element is first connected or a property is set (e.g. `element.foo = 5`)
-and the property's `hasChanged(value, oldValue)` returns `true`.
+* A property is set (e.g. `element.foo = 5`).
+* If the property's `hasChanged(value, oldValue)` returns `false`, the element does not
+update. If it returns `true`, `requestUpdate()` is called to schedule an update.
 * `requestUpdate()`: Updates the element after awaiting a [microtask](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/) (at the end
 of the event loop, before the next paint).
 * `shouldUpdate(changedProperties)`: The update proceeds if this returns `true`, which
 it does by default.
 * `update(changedProperties)`: Updates the element. Setting properties inside this
-method will *not* trigger the element to update.
+method will *not* trigger another update.
   * `render()`: Returns a `lit-html` TemplateResult (e.g. <code>html\`Hello ${world}\`</code>)
   to render element DOM. Setting properties inside this method will *not* trigger
   the element to update.
@@ -273,3 +275,8 @@ Chrome, Safari, Opera, Firefox, Edge. In addition, Internet Explorer 11 is also
 
 ## Known Issues
 
+* On very old versions of Safari (<=9) or Chrome (<=41), properties created for native
+platform properties like (`id` or `name`) may not have default values set in the element constructor.
+On these browsers native properties appear on instances and therefore their default value
+will overwrite any element default (e.g. if the element sets this.id = 'id' in the constructor,
+the 'id' will become '' since this is the native platform default).

package-lock.json

@@ -23,23 +23,23 @@
   "devDependencies": {
     "@types/chai": "^4.0.1",
     "@types/mocha": "^5.2.4",
-    "@webcomponents/webcomponentsjs": "^2.1.0",
+    "@webcomponents/webcomponentsjs": "^2.1.1",
     "chai": "^4.0.2",
     "mocha": "^5.0.5",
     "rollup": "^0.64.1",
     "rollup-plugin-filesize": "^4.0.1",
-    "rollup-plugin-node-resolve": "^3.3.0",
+    "rollup-plugin-node-resolve": "^3.4.0",
     "rollup-plugin-terser": "^1.0.1",
     "tslint": "^5.7.0",
     "typedoc": "^0.8.0",
-    "typescript": "^3.0.1",
+    "typescript": "^3.0.3",
     "uglify-es": "^3.3.9",
     "wct-browser-legacy": "^1.0.1",
     "web-component-tester": "^6.8.0"
   },
   "typings": "lit-element.d.ts",
   "dependencies": {
-    "lit-html": "^0.11.0"
+    "lit-html": "^0.11.2"
   },
   "publishConfig": {
     "access": "public"

package.json

@@ -59,7 +59,7 @@ export interface PropertyDeclaration<T = any> {
    * Indicates if the property should reflect to an attribute.
    * If `true`, when the property is set, the attribute is set using the
    * attribute name determined according to the rules for the `attribute`
-   * propety option and the value of the property serialized using the rules from
+   * property option and the value of the property serialized using the rules from
    * the `type` property option.
    */
   reflect?: boolean;
@@ -325,7 +325,12 @@ export abstract class UpdatingElement extends HTMLElement {
    * Fixes any properties set on the instance before upgrade time.
    * Otherwise these would shadow the accessor and break these properties.
    * The properties are stored in a Map which is played back after the constructor
-   * runs.
+   * runs. Note, on very old versions of Safari (<=9) or Chrome (<=41), properties
+   * created for native platform properties like (`id` or `name`) may not have default
+   * values set in the element constructor. On these browsers native properties
+   * appear on instances and therefore their default value will overwrite any element
+   * default (e.g. if the element sets this.id = 'id' in the constructor, the 'id'
+   * will become '' since this is the native platform default).
    */
   private _saveInstanceProperties() {
     for (const [p] of (this.constructor as typeof UpdatingElement)._classProperties) {
@@ -520,13 +525,13 @@ export abstract class UpdatingElement extends HTMLElement {
   }
 
   /**
-   * Returns a Promise that resolves when the element has completed updating
-   * that resolves to a boolean value that is `true` if the element completed
-   * the update without triggering another update. This happens if a property
-   * is set in `updated()`. This getter can be implemented to await additional
-   * state. For example, it is sometimes useful to await a rendered element before
-   * fulfilling this Promise. To do this, first await `super.updateComplete`
-   * then any subsequent state.
+   * Returns a Promise that resolves when the element has completed updating.
+   * The Promise value is a boolean that is `true` if the element completed the
+   * update without triggering another update. The Promise result is `false` if a
+   * property was set inside `updated()`. This getter can be implemented to await
+   * additional state. For example, it is sometimes useful to await a rendered
+   * element before fulfilling this Promise. To do this, first await
+   * `super.updateComplete` then any subsequent state.
    *
    * @returns {Promise} The Promise returns a boolean that indicates if the
    * update resolved without triggering another update.