Refine API and refactor

README.md

@@ -10,11 +10,47 @@
 
 LitElement uses [lit-html](https://github.com/Polymer/lit-html) to render into the
 element's [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)
-and [Polymer's](https://github.com/Polymer/polymer)
-[PropertiesMixin](https://github.com/Polymer/polymer/blob/master/lib/mixins/properties-mixin.js)
-to help manage element properties and attributes. LitElement reacts to changes in properties
+and adds API help manage element properties and attributes. LitElement reacts to changes in properties
 and renders declaratively using `lit-html`.
 
+  * **Setup properties:** LitElement supports observable properties which may trigger an
+  update when set. These properties can be written in a few ways:
+
+    * As class fields with the `@property()` [decorator](https://github.com/tc39/proposal-decorators#decorators),
+    if you're using a compiler that supports them, like TypeScript or Babel.
+    * With a static `properties` getter.
+    * By manually writing getters and setters. This can be useful if tasks should
+    be performed when a property is set, for example validation. You can call `invalidate()`
+    in the setter to trigger an update.
+
+    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`: Describes how and if 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 a string, the string value is observed (e.g `attribute: 'foo-bar'`).
+    * `type`: Describes 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`: Describes 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.
+    * `shouldInvalidate`: Describes if setting a property should trigger
+    invalidation and updating. This function takes the `newValue` and `oldValue` and
+    returns true if invalidation should occur. If not present, a strict identity
+    check is used. This is useful if a property should be considered dirty only
+    if some condition is met, like if a key of an object value changes.
+
   * **React to changes:** LitElement reacts to changes in properties and attributes by
   asynchronously rendering, ensuring changes are batched. This reduces overhead
   and maintains consistent state.
@@ -68,10 +104,10 @@ and renders declaratively using `lit-html`.
 ## Minimal Example
 
   1. Create a class that extends `LitElement`.
-  1. Implement a static `properties` getter that returns the element's properties
-  (which automatically become observed attributes).
-  1. Then implement a `_render(props)` method and use the element's
-current properties (props) to return a `lit-html` template result to render
+  1. Use a `@property` decorator to create a property (or implement a static `properties`
+  getter that returns the element's properties). (which automatically become observed attributes).
+  1. Then implement a `render()` method and use the element's
+current properties to return a `lit-html` template result to render
 into the element. This is the only method that must be implemented by subclasses.
 
 ```html
@@ -81,11 +117,12 @@ into the element. This is the only method that must be implemented by subclasses
 
     class MyElement extends LitElement {
 
-      static get properties() { return { mood: String }}
+      @property({type: String})
+      mood = 'happy';
 
-      _render({mood}) {
+      render() {
         return html`<style> .mood { color: green; } </style>
-          Web Components are <span class="mood">${mood}</span>!`;
+          Web Components are <span class="mood">${this.mood}</span>!`;
       }
 
     }
@@ -99,41 +136,71 @@ into the element. This is the only method that must be implemented by subclasses
 ## API Documentation
 
 See the [source](https://github.com/PolymerLabs/lit-element/blob/master/src/lit-element.ts#L90)
- for detailed API info, here are some highlights. Note, the leading underscore
- is used to indicate that these methods are
- [protected](https://en.wikipedia.org/wiki/Class_(computer_programming)#Member_accessibility);
- they are not private and can and should be implemented by subclasses.
- These methods generally are called as part of the rendering lifecycle and should
- not be called in user code unless otherwise indicated.
-
-  * `_createRoot()`: Implement to customize where the
+ for detailed API info, here are some highlights.
+
+  * `createRenderRoot()` (protected): Implement to customize where the
   element's template is rendered by returning an element into which to
   render. By default this creates a shadowRoot for the element.
   To render into the element's childNodes, return `this`.
 
-  * `_firstRendered()`: Called after the element DOM is rendered for the first time.
-
-  * `_shouldRender(props, changedProps, prevProps)`: Implement to control if rendering
-  should occur when property values change or `invalidate` is called.
+  * `shouldUpdate(changedProperties)` (protected): Implement to control if updating and rendering
+  should occur when property values change or `invalidate` is called. The `changedProps`
+  argument is an object with keys for the changed properties pointing to their previous values.
   By default, this method always returns true, but this can be customized as
-  an optimization to avoid rendering work when changes occur which should not be rendered.
-
-  * `_render(props)`: Implement to describe the element's DOM using `lit-html`. Ideally,
-  the `_render` implementation is a pure function using only `props` to describe
-  the element template. This is the only method that must be implemented by subclasses.
-
-  * `_didRender(props, changedProps, prevProps)`: Called after element DOM has been rendered.
-  Implement to directly control rendered DOM. Typically this is not needed as `lit-html`
-  can be used in the `_render` method to set properties, attributes, and
-  event listeners. However, it is sometimes useful for calling methods on
-  rendered elements, for example focusing an input:
-  `this.shadowRoot.querySelector('input').focus()`.
-
-  * `renderComplete`: Returns a promise which resolves after the element next renders.
-
-  * `_requestRender`: Call to request the element to asynchronously re-render regardless
+  an optimization to avoid updating work when changes occur, which should not be rendered.
+
+  * `update()` (protected): This method calls `render()` and then uses `lit-html` to
+  render the template DOM. Override to customize how the element renders DOM. Note,
+  during `update()` setting properties does not trigger `invalidate()`, allowing
+  property values to be computed and validated.
+
+  * `render()` (protected): Implement to describe the element's DOM using `lit-html`. Ideally,
+  the `render` implementation is a pure function using only the element's current properties
+  to describe the element template. This is the only method that must be implemented by subclasses.
+  Note, since `render()` is called by `update()` setting properties does not trigger
+  `invalidate()`, allowing property values to be computed and validated.
+
+  * `finishUpdate(changedProperties): Promise?` (protected): Called after element DOM has been updated and
+  before the `updateComplete` promise is resolved. Implement to directly control rendered DOM.
+  Typically this is not needed as `lit-html` can be used in the `render` method
+  to set properties, attributes, and event listeners. However, it is sometimes useful
+  for calling methods on rendered elements, for example focusing an input:
+  `this.shadowRoot.querySelector('input').focus()`. The `changedProps` argument is an object
+  with keys for the changed properties pointing to their previous values. If this function
+  returns a `Promise`, it will be *awaited* before resolving the `updateComplete` promise.
+  Setting properties in `finishUpdate()` does trigger `invalidate()` and blocks
+  the `updateComplete` promise.
+
+  * `finishFirstUpdate(changedProperties): Promise?` (protected) Called after element DOM has been
+  updated the first time. This method can be useful for capturing references to rendered static
+  nodes that must be directly acted upon, for example in `finishUpdate`.
+
+  * `updateComplete`: Returns a promise which resolves after the element next renders.
+
+  * `invalidate`: Call to request the element to asynchronously update regardless
   of whether or not any property changes are pending.
 
+## Update Lifecycle
+
+* When the element is first connected or a property is set (e.g. `element.foo = 5`)
+  and the property's `shouldInvalidate(value, oldValue)` returns true. Then
+  * `invalidate()` tries to update the element after waiting a [microtask](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/) (at the end
+  of the event loop, before the next paint). Then
+    * `shouldUpdate(changedProps)` is called and if this returns true which it
+      does by default:
+      * `update(changedProps)` is called to update the element.
+        Note, setting properties inside `update()` will set their values but
+        will *not* trigger `invalidate()`. This calls
+        * `render()` which should return a `lit-html` TemplateResult
+          (e.g. <code>html\`Hello ${world}\`</code>)
+      * `finishUpdate(changedProps)` is then called to do post update/render tasks.
+        Note, setting properties here will trigger `invalidate()` and block
+        the `updateComplete` promise.
+    * `updateComplete` promise is resolved only if the element is
+      not in an invalid state.
+* Any code awaiting the element's `updateComplete` promise runs and observes
+  the element in the updated state.
+
 ## Bigger Example
 
 ```JavaScript
@@ -142,25 +209,23 @@ import {LitElement, html} from '@polymer/lit-element';
 class MyElement extends LitElement {
 
   // Public property API that triggers re-render (synced with attributes)
-  static get properties() {
-    return {
-      foo: String,
-      whales: Number
-    }
-  }
+  @property()
+  foo = 'foo';
+
+  @property({type: Number})
+  whales = 5;
 
   constructor() {
     super();
-    this.foo = 'foo';
     this.addEventListener('click', async (e) => {
       this.whales++;
-      await this.renderComplete;
+      await this.updateComplete;
       this.dispatchEvent(new CustomEvent('whales', {detail: {whales: this.whales}}))
     });
   }
 
   // Render method should return a `TemplateResult` using the provided lit-html `html` tag function
-  _render({foo, whales}) {
+  render() {
     return html`
       <style>
         :host {
@@ -170,8 +235,8 @@ class MyElement extends LitElement {
           display: none;
         }
       </style>
-      <h4>Foo: ${foo}</h4>
-      <div>whales: ${'🐳'.repeat(whales)}</div>
+      <h4>Foo: ${this.foo}</h4>
+      <div>whales: ${'🐳'.repeat(this.whales)}</div>
       <slot></slot>
     `;
   }

demo/lit-element.html

@@ -11,38 +11,61 @@
   <meta name="viewport" content="width=device-width, minimum-scale=1.0, initial-scale=1.0, user-scalable=yes">
   <title>lit-element demo</title>
   <script src="../node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
+  <script type="module" src = "./ts-element.js"></script>
 </head>
 <body>
+    <my-element bar="5" whales="5" foobar="17">Hi</my-element>
+    <hr>
+    <ts-element message="Yo" more-info="person"></ts-element>
+
   <script type="module">
     import { LitElement, html } from '../lit-element.js';
 
+    class Inner extends LitElement {
+      render() {
+        return html`Hello world`;
+      }
+    }
+
+    customElements.define('x-inner', Inner);
+
     class MyElement extends LitElement {
 
       static get properties() {
         return {
-          foo: String,
-          bar: Number,
-          whales: Number
+          nug: {},
+          zot: {},
+          foo: {},
+          bar: {},
+          whales: {type: Number},
+          fooBar: {type: {fromAttribute: parseInt, toAttribute: (value) => value + '-attr'}, reflect: true}
         }
       }
 
+      // a custom getter/setter can be created to customize property processing
+      get zot() { return this.getAttribute('zot'); }
+
+      set zot(value) {
+        this.setAttribute('zot', value);
+        this.invalidate();
+      }
+
+
       constructor() {
         super();
         this.foo = 'foo';
+        this.nug = [1, 2, 3];
         this.whales = 0;
         this.addEventListener('click', async (e) => {
           this.whales++;
-          await this.renderComplete;
+          await this.updateComplete;
           this.dispatchEvent(new CustomEvent('whales', {detail: {whales: this.whales}}))
           console.log(this.shadowRoot.querySelector('.count').textContent);
         });
       }
 
-      _firstRendered() {
-        console.log('first rendered!');
-      }
-
-      _render({foo, bar, whales}) {
+      render() {
+        const {foo, bar, whales, fooBar, nug} = this;
         return html`
           <style>
             :host {
@@ -69,16 +92,36 @@ <h4 on-click="${(e) => console.log(this, e.target)}">Foo: ${foo}, Bar: ${bar}</h
           <div class="count">
             whales: ${'🐳'.repeat(whales)}
           </div>
+          <ul>
+          ${nug.map(n => html`<li>${n}</li>`)}
+          </ul>
+          <x-inner></x-inner>
         `;
       }
 
-      _didRender() {
-        console.log('didRender!');
+      update(changedProps) {
+        super.update(changedProps);
+        console.log('updated!', changedProps);
       }
 
+      async finishUpdate(changedProps) {
+        if (!this._inner) {
+          this._inner = this.shadowRoot.querySelector('x-inner');
+        }
+        await this._inner.updateComplete;
+      }
     }
 
+    addEventListener('WebComponentsReady', function() { console.log('wcr - module')})
+
+    console.log('defined class');
     customElements.define('my-element', MyElement);
+    console.log('get', customElements.get('my-element'));
+
+    (async () => {
+      const x = document.querySelector('my-element');
+      await x.updateComplete;
+      console.log(x.shadowRoot.querySelector('x-inner').shadowRoot.textContent);
+    })();
   </script>
-  <my-element bar="5" whales="5">Hi</my-element>
 </body></html>