More docs updates

docs/components.html

@@ -303,7 +303,7 @@ <h2 id="a-hreffunction-componentfunction-componenta"><a href="#function-componen
 }
 
 innerHTML(document.body, html`&lt;${MyComponent} someProp=&quot;value&quot; /&gt;`);</code></pre>
-<p><a name="class component"></a></p>
+<p><a name="class-component"></a></p>
 <hr></hr>
 <h2 id="a-hrefclass-componentclass-componenta"><a href="#class-component">Class Component</a></h2>
 <p>The stateful class component, which is used by importing the <code>Component</code> class.</p>
@@ -334,14 +334,21 @@ <h2 id="a-hrefclass-componentclass-componenta"><a href="#class-component">Class
 Components.</p>
 <p><a name="component-props"></a></p>
 <h3 id="a-hrefcomponent-propsupropsua"><a href="#component-props"><u>Props</u></a></h3>
-<p>These are incoming values that map to the props you set using the element
-attributes. Like in React, there will be a <code>children</code> prop automatically added
-which maps to the passed in child elements. You can access props on
-<code>this.props</code> or in the <code>render(props) {}</code> method.</p>
+<p>Incoming attribute values which are mapped into a <code>props</code> object, <code>children</code> is
+a special property which is provided that maps to the VTree <code>childNodes</code>. You
+can access props on <code>this.props</code> or in the <code>render(props) {}</code> method.</p>
 <p><a name="component-state"></a></p>
 <h3 id="a-hrefcomponent-stateustateua"><a href="#component-state"><u>State</u></a></h3>
-<h4 id="forceupdate">forceUpdate</h4>
+<p>A mutable object that can be updated with <code>setState</code>. You can also manually
+modify this object and call <code>forceUpdate</code> to simulate what <code>setState</code> does.
+This notion of state is what makes a component reactive. Without it, components
+only re-render when their parent has rendered.</p>
 <h4 id="setstate">setState</h4>
+<p>This is the most common way of updating state that is local to a component. You
+use it to update the <code>state</code> object and trigger a re-render.</p>
+<h4 id="forceupdate">forceUpdate</h4>
+<p>Calling this function schedules a re-render of the current component. It is
+useful to call this when you know the state has changed and want it reflected.</p>
 <p><a name="lifecycle-hooks"></a></p>
 <h3 id="a-hreflifecycle-hooksulifecycle-hooksua"><a href="#lifecycle-hooks"><u>Lifecycle hooks</u></a></h3>
 <p>The following hooks will be called during the respective mounting and

packages/diffhtml-website/config.json

@@ -19,7 +19,7 @@
       "release": "#release",
       "Internals": "#internals",
       "VERSION": "#version",
-      "Config options": "#config-options"
+      "Options": "#options"
     }],
 
     "Parser": ["parser.html", {

packages/diffhtml-website/pages/api.md

@@ -36,7 +36,7 @@ Transaction, invokes [middleware](/middleware.html), compares old and new markup
 | ----------- | -----------
 | **mount**   | DOM Node or VTree to sync or patch the **childNodes** of.
 | **input**   | New markup to replace into **mount**.
-| **options** | **[Config options](#config-options)**, `inner` is always `true`
+| **options** | **[Config options](#options)**, `inner` is always `true`
 
 <a name="inner-html-examples"></a>
 
@@ -72,7 +72,7 @@ but this can sometimes result in unexpected behavior.
 | ----------- | -----------
 | **mount**   | DOM Node or VTree to sync or patch.
 | **input**   | New markup to replace into **mount**.
-| **options** | **[Config options](#config-options)**, `inner` is always `false`
+| **options** | **[Config options](#options)**, `inner` is always `false`
 
 <a name="outer-html-examples"></a>
 
@@ -105,7 +105,7 @@ All middleware run during this, so features like components and logging work.
 | Name        | Description
 | ----------- | -----------
 | **input**   | New markup to replace into **mount**.
-| **options** | **[Config options](#config-options)**, `inner` and `executeScripts` have no effect
+| **options** | **[Config options](#options)**, `inner` and `executeScripts` have no effect
 
 <a name="to-string-examples"></a>
 
@@ -548,30 +548,40 @@ Property which indicates the current running version of diffHTML.
 console.log(VERSION);
 ```
 
-<a name="config-options"></a>
+<a name="options"></a>
 
 ---
 
-## <a href="#config-options">Config options</a>
+## <a href="#options">Options</a>
 
-- [`inner`](#config-options-inner)
-- [`tasks`](#config-options-tasks)
-- [`executeScripts`](#config-options-execute-scripts)
-- [`parser`](#config-options-parser)
+Allows configuring runtime rendering behavior. These options are accessible via
+`transaction.config` and can be set via query string, environment variables, or
+passing a config object to `innerHTML`, `outerHTML`, and `toString`.
 
-<a name="config-options-inner" />
+In the case of query string and environment variables, uppercase the variables
+and prefix with `DIFF_`. So `inner` becomes `DIFF_INNER`. For `parser` use a
+JSON string: `JSON.stringify({ parser: { strict: true } })`.
 
-### <a href="#config-options-inner">inner `Boolean`</a>
+- [`inner`](#options-inner)
+- [`tasks`](#options-tasks)
+- [`executeScripts`](#options-execute-scripts)
+- [`parser`](#options-parser)
+
+<a name="options-inner" />
+
+---
+
+### <a href="#options-inner">inner `Boolean`</a>
 
 Determines if the Transaction should update the DOM Node or just its children.
 Setting this to `true` will emulate the behavior of `innerHTML` and setting it
 to `false` emulates `outerHTML`. You cannot set this using `innerHTML` or
 `outerHTML`, and it has no effect with `toString` so it is only useful if you
 manually create Transactions which is an advanced use case.
 
-<a name="config-options-tasks" />
+<a name="options-tasks" />
 
-### <a href="#config-options-tasks">tasks `Function[]`</a>
+### <a href="#options-tasks">tasks `Function[]`</a>
 
 Manipulate the tasks which run. This can allow you to do interesting things
 with the core API. You can do API changes like providing a stream or generator
@@ -621,9 +631,9 @@ innerHTML(document.body, `<h1>Hello world</h1>`, {
 });
 ```
 
-<a name="config-options-execute-scripts" />
+<a name="options-execute-scripts" />
 
-### <a href="#config-options-execute-scripts">executeScripts `Boolean`</a>
+### <a href="#options-execute-scripts">executeScripts `Boolean`</a>
 
 Control whether or not newly appended scripts are executed or not. When
 enabled, tricks the browser by setting the `type` property to `no-execute` when
@@ -644,9 +654,9 @@ innerHTML(document.body, `<script>window.alert('here')</script>`, {
 
 ```
 
-<a name="config-options-parser" />
+<a name="options-parser" />
 
-### <a href="#config-options-parser">parser `Object`</a>
+### <a href="#options-parser">parser `Object`</a>
 
 These options modify the parser by making it more strict or changing which
 elements are treated as block or self closing.

packages/diffhtml-website/pages/components.md

@@ -37,7 +37,7 @@ function MyComponent(props) {
 innerHTML(document.body, html`<${MyComponent} someProp="value" />`);
 ```
 
-<a name="class component"></a>
+<a name="class-component"></a>
 
 ---
 
@@ -82,19 +82,29 @@ Components.
 
 ### <a href="#component-props"><u>Props</u></a>
 
-These are incoming values that map to the props you set using the element
-attributes. Like in React, there will be a `children` prop automatically added
-which maps to the passed in child elements. You can access props on
-`this.props` or in the `render(props) {}` method.
+Incoming attribute values which are mapped into a `props` object, `children` is
+a special property which is provided that maps to the VTree `childNodes`. You
+can access props on `this.props` or in the `render(props) {}` method.
 
 <a name="component-state"></a>
 
 ### <a href="#component-state"><u>State</u></a>
 
-#### forceUpdate
+A mutable object that can be updated with `setState`. You can also manually
+modify this object and call `forceUpdate` to simulate what `setState` does.
+This notion of state is what makes a component reactive. Without it, components
+only re-render when their parent has rendered.
 
 #### setState
 
+This is the most common way of updating state that is local to a component. You
+use it to update the `state` object and trigger a re-render.
+
+#### forceUpdate
+
+Calling this function schedules a re-render of the current component. It is
+useful to call this when you know the state has changed and want it reflected.
+
 <a name="lifecycle-hooks"></a>
 
 ### <a href="#lifecycle-hooks"><u>Lifecycle hooks</u></a>

packages/diffhtml-website/public/scripts/promises-keyframe.js

@@ -0,0 +1,35 @@
+import { html, innerHTML, addTransitionState } from 'https://diffhtml.org/core';
+
+const duration = 3000;
+
+addTransitionState('attributeChanged', (domNode, attrName, oldValue, newValue) => {
+  if (attrName !== 'id') {
+    return;
+  }
+
+  const frames = [
+    { transform: 'translateX(0)' },
+    { transform: 'translateX(-50%)' },
+  ];
+
+  domNode.animate(frames, { duration }).finished;
+});
+
+const promisesKeyframe = document.querySelector('#promises-keyframe');
+
+let frame = 0;
+
+function renderFrame(number) {
+  innerHTML(promisesKeyframe, html`
+    <div id="frame-${number}">
+      <span>${String(number)}</span>
+    </div>
+  `);
+}
+
+setInterval(() => {
+  frame++;
+  renderFrame(frame);
+}, duration);
+
+renderFrame(frame);