Rendering update (#278)

* Updated components/rendering.
* Reordered sections.
* Expanded first section.
Co-authored-by: Steve Orvell <[email protected]>

Author: Arthur Evans

packages/lit-dev-content/samples/docs/templates/compose/my-page.ts

@@ -1,15 +1,6 @@
 import {LitElement, html} from 'lit';
 import {customElement, property} from 'lit/decorators.js';
 
-function headerTemplate(title: string) {
-  return html`<header>${title}</header>`;
-}
-function articleTemplate(text: string) {
-  return html`<article>${text}</article>`;
-}
-function footerTemplate() {
-  return html`<footer>Your footer here.</footer>`;
-}
 
 @customElement('my-page')
 class MyPage extends LitElement {
@@ -20,11 +11,23 @@ class MyPage extends LitElement {
     text: 'Some witty text.',
   };
 
+  headerTemplate() {
+    return html`<header>${this.article.title}</header>`;
+  }
+
+  articleTemplate() {
+    return html`<article>${this.article.text}</article>`;
+  }
+
+  footerTemplate() {
+    return html`<footer>Your footer here.</footer>`;
+  }
+
   render() {
     return html`
-      ${headerTemplate(this.article.title)}
-      ${articleTemplate(this.article.text)}
-      ${footerTemplate()}
+      ${this.headerTemplate()}
+      ${this.articleTemplate()}
+      ${this.footerTemplate()}
     `;
   }
 }

packages/lit-dev-content/site/docs/components/rendering.md

@@ -8,102 +8,77 @@ eleventyNavigation:
 
 Add a template to your component to define what it should render. Templates can include _expressions_, which are placeholders for dynamic content.
 
-```ts
-render() {
-  return html`<div>Hello, ${name}.</div>`;
-}
-```
-
-## When templates render
-
-A Lit component renders its template initially when it's added to the DOM on a page. After the initial render, any change to the component's reactive properties triggers an update cycle, re-rendering the component.
-
-The update cycle is _asynchronous_, so changes to multiple properties are batched into a single update. And when Lit updates, it only re-renders the changed portions of the DOM.
+To define a template for a Lit component, add a `render()` method:
 
-For more information about the update cycle, see [What happens when properties change](/docs/components/properties/#update-cycle).
+{% playground-example "docs/templates/define" "my-element.ts" %}
 
-## DOM encapsulation
+Write your template in HTML inside a JavaScript [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) using Lit's `html` tag function.
 
-Lit uses shadow DOM to encapsulate the DOM a component renders. Shadow DOM provides three benefits:
+Lit templates can include JavaScript _expressions_. You can use expressions to set text content, attributes, properties, and event listeners. The `render()` method can also include any JavaScript—for example, you can create local variables for use in expressions.
 
-* DOM scoping. DOM APIs like `document.querySelector` won't find elements in the
-  component's shadow DOM, so it's harder for global scripts to accidentally break your component.
-* Style scoping. You can write encapsulated styles for your shadow DOM that don't
-  affect the rest of the  page. No need for conventions like BEM to associate styles with your component.
-* Composition. The component's shadow DOM (managed by the component) is separate from the component's children. You can choose how children are rendered in your templated DOM. Component users can add and remove children using standard DOM APIs without accidentally breaking anything in your shadow DOM.
+Typically, the component's `render()` method returns a single `TemplateResult` object (the same type returned by the `html` tag function). However, it can return anything that Lit can render:
 
-For more information about shadow DOM, see [Shadow DOM v1: Self-Contained Web Components
-](https://developers.google.com/web/fundamentals/web-components/shadowdom) on Web Fundamentals.
+*   Primitive values like string, number, or boolean.
+*   `TemplateResult` objects created by the `html` function.
+*   DOM Nodes.
+*   Arrays or iterables of any of the supported types.
 
-<div class="alert alert-info">
+For more information about writing templates, see [Templates](/docs/templates/overview/).
 
-Where native shadow DOM isn't available on older browsers, Lit can optionally use the [Shady DOM polyfill](https://github.com/webcomponents/polyfills/tree/master/packages/shadydom) to provide emulated shadow DOM support.
+## Writing a good render() method
 
-</div>
+To take best advantage of Lit's functional rendering model, your `render()` method should follow these guidelines:
 
-## Define a template
+* Avoid changing the component's state.
+* Avoid producing any side effects.
+* Use only the component's properties as input.
+* Return the same result when given the same property values.
 
-To define a template for a Lit component, add a `render()` method:
+Following these guidelines keeps the template deterministic, and makes it easier to reason about the code.
 
-{% playground-example "docs/templates/define" "my-element.ts" %}
+In most cases you should avoid making DOM updates outside of `render()`. Instead, express the component's template as a function of its state, and capture its state in properties.
 
-*   Write your template in HTML inside a JavaScript [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) by enclosing the raw HTML in back-ticks (<code>``</code>).
+For example, if your component needs to update its UI when it receives an event, have the event listener set a reactive property that is used in `render()`, rather than manipulate the DOM directly.
 
-*   Tag your template literal with the [`html`](TODO_HREF) tag function.
+For more information, see [Reactive properties](/docs/components/properties/).
 
-*   The component's `render` method can return anything that Lit can render. Typically, it returns a single `TemplateResult` object (the same type returned by the `html` tag function).
+## Composing templates
 
-Lit templates can include JavaScript _expressions_. You can use expressions to set text content, attributes, properties, and event listeners.
+You can compose Lit templates from other templates. The following example composes a template for a component called `<my-page>` from smaller templates for the page's header, footer, and main content:
 
-For more information, see [Templates overview](/docs/templates/overview/).
+{% playground-example "docs/templates/compose" "my-page.ts" %}
 
-### Design a performant template
+In this example, the individual templates are defined as instance methods, so a subclass could extend this component and override one or more templates.
 
-During an update, only the parts of the DOM that change are re-rendered. Although Lit templates look like string interpolation, Lit parses and creates static HTML once, and then only updates changed values in expressions after that, making updates very efficient.
+{% todo %}
 
-To take best advantage of Lit's functional rendering model, follow these guidelines for implementing your `render()` method:
+Move example to composition section, add xref.
 
-* Does not change the component's state.
-* Does not have any side effects.
-* Only depends on the component's properties.
-* Returns the same result when given the same property values.
+{% endtodo %}
 
-Also, avoid making DOM updates outside of `render()`. Instead, express the component's template as a function of its state, and capture its state in properties.
+You can also compose templates by importing other elements and using them in your template:
 
-The following code manipulates the rendered DOM. This is usually an anti-pattern:
+{% playground-ide "docs/templates/composeimports" %}
 
-```ts
-// Anti-pattern. Avoid!
-constructor() {
-  super();
-  this.loadStuff().then((content) => {
-    this.shadowRoot.querySelector('#message')
-      .innerHTML = content;
-  });
-}
-render() {
-  return html`
-    <p id="message">Loading</p>
-  `;
-}
-```
 
-You can improve the template by declaring the message as a _reactive property_, and using an expression in the template instead of setting the text imperatively. Declaring a reactive property tells your component to re-render its template when the property changes.
+## When templates render
 
-{% playground-example "docs/templates/design" "update-properties.ts" %}
+A Lit component renders its template initially when it's added to the DOM on a page. After the initial render, any change to the component's reactive properties triggers an update cycle, re-rendering the component.
 
-For more information, see [Reactive properties](/docs/components/properties/).
+Lit batches updates to maximize performance and efficiency. Setting multiple properties at once triggers only one update, performed asynchronously at microtask timing.
 
-## Compose a template from other templates
+During an update, only the parts of the DOM that change are re-rendered. Although Lit templates look like string interpolation, Lit parses and creates static HTML once, and then only updates changed values in expressions after that, making updates very efficient.
 
-You can compose Lit templates from other templates. The following example composes a template for an component called `<my-page>` from smaller templates for the page's header, footer, and main content:
+For more information about the update cycle, see [What happens when properties change](/docs/components/properties/#when-properties-change).
 
-{% playground-example "docs/templates/compose" "my-page.ts" %}
+## DOM encapsulation
 
-You can also compose templates by importing other elements and using them in your template:
+Lit uses shadow DOM to encapsulate the DOM a component renders. Shadow DOM lets an element create its own, isolated DOM tree that's separate from the main document tree. It's a core feature of the web components specifications that enables interoperability, style encapsulation, and other benefits.
 
-{% playground-ide "docs/templates/composeimports" %}
+For more information about shadow DOM, see [Shadow DOM v1: Self-Contained Web Components
+](https://developers.google.com/web/fundamentals/web-components/shadowdom) on Web Fundamentals.
 
+For more information about working with shadow DOM in your component, see [Working with shadow DOM](/docs/components/shadow-dom/).
 
 ## See also
 
@@ -113,4 +88,3 @@ You can also compose templates by importing other elements and using them in you
 * [Template expressions](/docs/templates/overview/)
 
 
-

packages/lit-dev-content/site/docs/components/shadow-dom.md

@@ -6,7 +6,7 @@ eleventyNavigation:
   order: 6
 ---
 
-Lit components use [shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom) to encapsulate their DOM. Shadow DOM provides a way to add a separate isolated and encapsulated DOM tree to an element. DOM encapsulation is the key to unlocking interoperability with any other code, including other web components or Lit component, functioning on the page.
+Lit components use [shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom) to encapsulate their DOM. Shadow DOM provides a way to add a separate isolated and encapsulated DOM tree to an element. DOM encapsulation is the key to unlocking interoperability with any other code—including other web components or Lit components—functioning on the page.
 
 Shadow DOM provides three benefits: