solarite 0.1.1 → 0.2.1

package/docs/index.md

@@ -1,26 +1,26 @@
 ---
 title:  Solarite JS Library
-append-head:  <script src="docs/js/ui/DarkToggle.js"></script><script type="module" src="docs/js/documentation.js"></script><link rel="stylesheet" href="docs/media/documentation.css"><link rel="stylesheet" href="docs/media/eternium.css"><link rel="icon" href="docs/media/solarite-machine.webp" type="image/webp">
+append-head:  <script src="docs/js/ui/DarkToggle.js"></script><script type="module" src="docs/js/documentation.js"></script><link rel="stylesheet" href="docs/media/documentation.css"><link rel="stylesheet" href="docs/media/eternium.css"><link rel="icon" href="docs/media/solarite-machine.webp" type="image/webp"><script async defer src="https://buttons.github.io/buttons.js"></script>
 
 ---
 
-<!-- To convert documentation to html: (1) Open in Typora.  (2) Select the GitHub theme. (3) Export as html with styles to index.html. -->
+<!-- To convert documentation to html: (1) Open in Typora.  (2) Select the GitHub theme, or go to Settings -> Export -> Html -> Theme -> Github. (3) Export as html with styles to index.html. -->
+
+<!-- Playgrounds that don't have a lowercase language name will not have a preview. -->
 
 # Solarite
 
-Solarite is a small (8KB min+gzip), fast, compilation-free JavaScript library to enhance your vanilla web components.  Features:
+Solarite is a small (8KB min+gzip), fast, compilation-free JavaScript library for creating elements and web components.  Features:
 
-- Very similar to writing native Web Components.
 - Minimal DOM updates when rendering.
-- No magic:  Rendering only when you want it, via the manually invoked render() method.
+- No magic:  Renderer only when you want via the manually invoked `render()` method.
+- No setting up state variables.  Render any regular variable or data structure.
 - Local scoped styles:  Inherit external styles but define new styles that apply only to the web component and its children.
 - Elements with `id` or `data-id` attributes become class properties.
-- Attributes are passed as constructor arguments to nested Solarite components.
+- Attributes are passed as constructor arguments to nested components.
 - Single file.  No build steps and no dependencies.  Not even Node.js.  Just `import` Solarite.js or Solarite.min.js into your vanilla JavaScript and start coding.
 - MIT license.  Free for commercial use.  No attribution needed.
 
-With Solarite there's no need to set up state like with other frameworks.  Instead, use any regular variables or data structures in html templates.  Call `render()` manually and it will update changed elements synchronously.
-
 ```javascript
 import {r} from './dist/Solarite.js';
 
@@ -55,16 +55,10 @@ class ShoppingList extends HTMLElement {
 
             ${this.items.map(item => r`
                 <div>
-                    <input placeholder="Name" value=${item.name} 
-                        oninput=${e => {
-                            item.name = e.target.value; 
-                            this.render()
-                        }}>
-                    <input type="number" value=${item.qty}
-                        oninput=${e => {
-                            item.qty = e.target.value; 
-                            this.render()
-                        }}>
+                    <input placeholder="Item" oninput=${this.render}
+                        value=${[item, 'name']}> <!-- 2-way binding -->
+                    <input type="number" oninput=${this.render}
+                        value=${[item, 'qty']}>
                     <button onclick=${()=>this.removeItem(item)}>x</button>
                 </div>			 
             `)}
@@ -78,26 +72,71 @@ customElements.define('shopping-list', ShoppingList);
 document.body.append(new ShoppingList()); // add <shopping-list> element
 ```
 
-This project is currently in BETA stage and not yet recommended for production code.
-
 To use, import one of these pre-bundled es6 modules into your project:
 
-- [Solarite.js](https://cdn.jsdelivr.net/gh/Vorticode/Solarite/dist/Solarite.js) - 87KB
-- [Solarite.min.js](https://cdn.jsdelivr.net/gh/Vorticode/Solarite/dist/Solarite.js) - 24KB / 8KB gzipped
+- [Solarite.js](https://cdn.jsdelivr.net/gh/Vorticode/Solarite/dist/Solarite.js) - 85KB
+- [Solarite.min.js](https://cdn.jsdelivr.net/gh/Vorticode/Solarite/dist/Solarite.min.js) - 24KB / 8KB gzipped
 
 Or get Solarite from GitHub or NPM:
 
-- [Solarite GitHub Repository](https://github.com/Vorticode/solarite)
+- [Solarite GitHub Repository](https://github.com/Vorticode/solarite)  <a class="github-button" href="https://github.com/vorticode/solarite" data-color-scheme="no-preference: light; light: light; dark: dark;" data-icon="octicon-star" data-size="small" data-show-count="true" aria-label="Star vorticode/solarite on GitHub">Star</a>
 - `git clone https://github.com/Vorticode/solarite.git`
 - `npm install solarite`
 
+This project is currently in BETA stage.  Tip:  A JetBrains IDE like [WebStorm](https://www.jetbrains.com/webstorm/), [PhpStorm](https://www.jetbrains.com/phpstorm/), or [IDEA](https://www.jetbrains.com/idea/) will syntax highlight the html template strings.
+
 ## Concepts
 
+### Regular Elements
+
+The `r()` function can create elements.  Pass any object with a `render()` function as the first argument.  This object can optionally have additional properties and methods, which become bound to the resulting element.  When `render()` is called, only the changed nodes will be updated.
+
+```javascript
+import {r} from './dist/Solarite.js';
+
+let button = r({
+    count: 0,
+
+    inc() {
+        this.count++;
+        this.render();
+    },
+
+    render() {
+        r(this)`<button onclick=${this.inc}>I've been clicked ${this.count} times.</button>`
+    }
+});
+document.body.append(button);
+```
+
+If you want multiple instances of such an element, the code above can be wrapped in a function:
+
+```javascript
+import {r} from './dist/Solarite.js';
+
+function createButton(text) {
+	return r({
+		count: 0,
+
+		inc() {
+			this.count++;
+			this.render();
+		},
+
+		render() {
+			r(this)`<button onclick=${this.inc}>${this.count} ${text}</button>`
+		}
+	})
+}
+document.body.append(createButton('clicks'));
+document.body.append(createButton('tickles'));
+```
+
 ### Web Components
 
-In this minimal example, we make a new class called `MyComponent` which extends from `HTMLElement` like other web components.  We provide a `render()` function to set its html, and a constructor to call it when a new instance is created.
+Solarite can also create [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).  In this minimal example, we make a new class called `MyComponent` which extends from `HTMLElement` like any other web component.  We provide a `render()` function to set its html, and a constructor to call it when a new instance is created.
 
-All browsers require custom web component tag names to have at least one dash in the middle.  
+All browsers require web component tag names to have at least one dash in the middle.  
 
 ```javascript
 import {r} from './dist/Solarite.js';
@@ -106,34 +145,42 @@ class MyComponent extends HTMLElement {
 	name = 'Solarite';
     
     constructor() {
-        super();
+        super(); // JavaScript requires a super() call for sub-class construtors.
         this.render();
     }
     
-	render() { 
-		r(this)`<my-component>Hello <b>${this.name}!<b></my-component>`
+	render() {
+        // This is how we'd create a web component using vanilla JavaScript
+        // without Solarite.  But this recreates all children on every render!
+        //this.innerHTML = `Hello <b>${this.name}!<b>`;
+        
+        // Using Solarite's r() function performs minimal updates on render.
+		r(this)`<my-component>Hello <b>${this.name}!</b></my-component>`
 	}
 }
 
+// Register the <my-component> tag name with the browser.
+// Browsers require this for all web components.
 customElements.define('my-component', MyComponent);
+
 document.body.append(new MyComponent());
 ```
 
 Alternatively, instead of instantiating the element in JavaScript, we could can instantiate the element directly from html:
 
-```html
+```Html
 <my-component></my-component>
 ```
 
-JavaScript veterans will realize that other than the `r()` function, this is highly similar to one might create vanilla JavaScript web components.  This is by design!  
+JavaScript veterans will realize that other than the `r()` function, this is highly similar to one might create vanilla JavaScript web components.  This is by design!
 
-Tip:  A JetBrains IDE like [WebStorm](https://www.jetbrains.com/webstorm/), [PhpStorm](https://www.jetbrains.com/phpstorm/), or [IDEA](https://www.jetbrains.com/idea/) will syntax highlight the html template strings.
+Since these are just regular web components, they can define the [connectedCallback()](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-dom.html#connectedcallback) and [disconnectedCallback()](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-dom.html#disconnectedcallback) methods that will be called when they're added and removed from the DOM, respectively.  These functions are only supported for web components and not regular elements.
 
-### render() and r()
+### Rendering
 
-The `r` function, when used as part of a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) , converts the html and embedded expressions into a Solarite `Template`.  This is a data structure used by Solarite to store processed html and expressions.  The call to `r(this)` then renders that `Template` as web component's attributes and children.  You can think of this like assigning to the browser's built-in `this.outerHTML` property, except updates are much faster because only the changed elements are replaced, instead of all nodes.
+The `r` function, when used as a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) , converts the html and embedded expressions into a Solarite `Template`.  This is a data structure used by Solarite to store processed html and expressions.  The call to `r(this)` then renders that `Template` as an element's attributes and children.  You can think of this like assigning to the browser's built-in `this.outerHTML` property, except updates are much faster because only the changed elements are replaced, instead of all nodes.
 
-Unlike other frameworks, Solarite does not re-render automatically when data changes, so you should call the `render()` function manually.  This is a deliberate design choice to reduce magic, since in some cases you may want to update internal data without rendering.
+Unlike other frameworks, Solarite does not re-render automatically when data changes, so you should call the `render()` function manually.  This is a deliberate design choice to reduce unexpected side effects, since in some cases you may want to update internal data without rendering.
 
 Wrapping the web component's html in its tag name is optional.  But without it you then must set any attributes on your web component manually, as seen in this example:
 
@@ -155,42 +202,47 @@ customElements.define('my-component', MyComponent);
 document.body.append(new MyComponent());
 ```
 
-If you do wrap the components html in its tag, that tag name must exactly match the tag name passed to customElements.define().
-
-### Loops
+If you do wrap the web component's html in its tag, that tag name must exactly match the tag name passed to `customElements.define()`.
 
-As previously seen, loops can be written with JavaScript's [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) function:
+Note that by default, `r()` will render expressions as text, with escaped html entities.  To render as html, wrap a variable in the `r()` function:
 
 ```javascript
 import {r} from './dist/Solarite.js';
 
-class TodoList extends HTMLElement {
-	render() { 
-		r(this)`
-        <todo-list>
-            ${this.items.map(item => 
-                r`${item}<br>`
-            )}
-        </todo-list>`
+let folderIcon = `
+<svg width="10em" height="10em" viewBox="0 0 24 24">
+	<path fill="currentColor" d="M2 4h8l2 2h10v14H2V4Zm2 2v12h16V8h-8.825l-2-2H4Zm0 12V6v12Z"/>
+</svg>`;
+
+
+let icon1 = r({
+	render() {
+		r(this)`<div>${folderIcon}</div>`
 	}
-}
-customElements.define('todo-list', TodoList);
+});
+document.body.append(icon1);
 
-let list = new TodoList();
-list.items = ['one', 'two', 'three'];
-list.render();
-document.body.append(list);
 
-list.items[1] = '2';
-list.render();
+let icon2 = r({
+	render() { // string wrapped in r()
+		r(this)`<div>${r(folderIcon)}</div>`
+	}
+});
+document.body.append(icon2);
 
-list.items.splice(1, 0, 'two and a half');
-list.render();
 ```
 
-When we change an element or add another element to the `items` list, calling `render()` only redraws the changed or new element.  The other list items are not modified.
+Folder icon comes from [Google](https://icon-sets.iconify.design/material-symbols/folder-outline/).
 
-Note that nested template literals must also have the `r` prefix. Otherwise they'll be rendered as escaped text instead of HTML elements.
+These types of objects can be returned by in expressions with `r` tagged template literals:
+
+1. strings and numbers.
+2. boolean true, which will be rendered as 'true'
+3. false, null, and undefined, which will be rendered as empty string.
+4. Solarite Templates created by `r`-tagged template literals.
+5. DOM Nodes, including other web components.
+6. Arrays of any of the above.
+7. Functions that return any of the above.
 
 ### Attributes
 
@@ -203,34 +255,57 @@ let style = 'width: 100px; height: 40px; background: orange';
 let isEditable = true;
 let height = 40;
 
-class AttributeDemo extends HTMLElement {
+let attributeDemo = r({
 	render() { 
 		r(this)`
-        <attribute-demo class="big">
-
+        <div class="big">
             <div style=${style}>Look at me</div>
-
             <div style="${'width: 100px'}; height: ${height}px; background: gray">Look at me</div>
+            <div style="width: 100px; height: 40px; background: brown" ${'title="I have a title"'}>Hover me</div>
+            <div style="width: 100px; height: 40px; background: red" contenteditable=${isEditable} >Edit me</div>
+        </div>`
+	}
+});
 
-            <div style="width: 100px; height: 40px; background: red" ${'title="I have a title"'}>Hover me</div>
+document.body.append(attributeDemo);
 
-            <div style="width: 100px; height: 40px; background: brown" contenteditable=${isEditable} >Edit me</div>
-        </attribute-demo>`
-	}
-}
-customElements.define('attribute-demo', AttributeDemo);
-let ad = new AttributeDemo();
-ad.render();
-document.body.append(ad);
+style = 'width: 100px; height: 40px; background: green';
+setTimeout(attributeDemo.render, 2000);
 ```
 
 Expressions can also toggle the presence of an attribute.  In the last div above, if `isEditable` is false, null, or undefined, the contenteditable attribute will be removed.
 
 Note that attributes can also be assigned to the root element, such as `class="big"` on the `<attribute-demo>` tag above.
 
+### Id's
+
+Any element in the html with an `id` or `data-id` attribute is automatically bound to a property with the same name on the class instance.  But this only happens after `render()` is first called:
+
+```javascript
+import {r} from './dist/Solarite.js';
+
+let raceTeam = r({    
+	render() { 
+        r(this)`
+		<div>
+            <input id="driver" value="Mario">
+            <div data-id="car">Cutlas Supreme</div>
+            <div data-id="instructor.name">Lightning McQueen</div>
+        </div>`
+	}
+});
+document.body.append(raceTeam);
+
+raceTeam.driver.value = 'Luigi'; 
+raceTeam.car.style.border = '1px solid green';
+// We don't need to call render() because we're editing the DOM Directly.
+```
+
+Id's that have values matching built-in HTMLElement attribute names such as `title` or `disabled` are not allowed.
+
 ### Events
 
-Listen for events by assigning a function expression to any event attribute.  Or by passing an array where the first item is a function and subsequent items are arguments to that function.
+To intercept events, set the value of an event attribute like `onclick` to a function.  Alternatively, set the value to an array where the first item is a function and subsequent items are arguments to that function.
 
 ```javascript
 import {r} from './dist/Solarite.js';
@@ -257,13 +332,13 @@ customElements.define('event-demo', EventDemo);
 document.body.append(new EventDemo());
 ```
 
-Event binding with an array containing a function and its arguments is slightly faster, since when `render()` is called, Solarite can see that the function hasn't changed, and it doesn't need to be unbound and rebound.  But the performance difference is usually negligible.
+Event binding with an array containing a function and its arguments is slightly faster, since the function isn't recreated when `render()` is called, and it doesn't need to be unbound and rebound.  But the performance difference is usually negligible.
 
 Make sure to put your events inside `${...}` expressions, because classic events can't reference variables in the current scope.
 
 ### Two-Way Binding
 
-Form elements can update the properties that provide their values if an event attribute such as `oninput` is assigned the path to a property to update:
+Form elements can update the properties that provide their values if an event attribute such as `oninput` is assigned a function to perform the update:
 
 ```javascript
 import {r} from './dist/Solarite.js';
@@ -297,46 +372,75 @@ customElements.define('binding-demo', BindingDemo);
 document.body.append(new BindingDemo());
 ```
 
-In addition to `<input>`,  `<select>` and `<textarea>` can also use the `value` attribute to set their value on render.  Likewise so can any custom web components that define a `value` property.
+In addition to `<input>`,  `<select>` and `<textarea>` can also use the `value` attribute to set their value on render.  Likewise so can any custom web component that defines a `value` property.
 
-### Id's
-
-Any element in the html with an `id` or `data-id` attribute is automatically bound to a property with the same name on the class instance.  But this only happens after `render()` is first called:
+A shorthand way to do two-way binding is to pass a property path as the value expression.  Here with `value=${[this, 'count']}`.  When a user types in the input, Solarite listens to the `oninput` listener and updates `this.count`.  Note that we still need a second `oninput` attribute if we want to trigger rendering.
 
 ```javascript
 import {r} from './dist/Solarite.js';
 
-class RaceTeam extends HTMLElement {
-    constructor() {
+class BindingDemo extends HTMLElement {
+   
+	constructor() {
         super();
-        
-        // Id's are not set until render() is first called.
+        this.count = 0;
         this.render();
-        
-        // Change the value of the input.
-        // No need to render() again since we're changing the DOM manually.
-        this.driver.value = 'Luigi'; 
     }
     
 	render() { 
-        r(this)`
-		<race-team>
-            <input id="driver" value="Mario">
-            <div data-id="car">Cutlas Supreme</div>
-            <div data-id="instructor.name">Lightning McQueen</div>
-        </race-team>`
+		r(this)`
+        <binding-demo>
+            <input type="number" value=${[this, 'count']}
+                oninput=${() => this.render()}>
+            <pre>count is ${this.count}</pre>
+            <button onclick=${()=> { 
+                this.count = 0;
+                this.render();
+            }}>Reset</button>
+        </binding-demo>`
 	}
 }
-customElements.define('race-team', RaceTeam);
-let raceTeam = new RaceTeam();
-document.body.append(raceTeam);
+customElements.define('binding-demo', BindingDemo);
+
+document.body.append(new BindingDemo());
+```
 
 
-raceTeam.car.style.border = '1px solid green';
 
+### Loops
+
+As previously seen, loops can be written with JavaScript's [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) function:
+
+```javascript
+import {r} from './dist/Solarite.js';
+
+class TodoList extends HTMLElement {
+	render() { 
+		r(this)`
+        <todo-list>
+            ${this.items.map(item => 
+                r`${item}<br>`
+            )}
+        </todo-list>`
+	}
+}
+customElements.define('todo-list', TodoList);
+
+let list = new TodoList();
+list.items = ['one', 'two', 'three'];
+list.render();
+document.body.append(list);
+
+list.items[1] = '2';
+list.render();
+
+list.items.splice(1, 0, 'two and a half');
+list.render();
 ```
 
-Id's that have values matching built-in HTMLElement attribute names such as `title` or `disabled` are not allowed.
+When we change an element or add another element to the `items` list, calling `render()` only redraws the changed or new element.  The other list items are not modified.
+
+Note that nested template literals must also have the `r` prefix. Otherwise they'll be rendered as escaped text instead of HTML elements.
 
 ### Scoped Styles
 
@@ -361,7 +465,7 @@ class FancyText extends HTMLElement {
             <p>I have a red border and shadow!</p>
         </fancy-text>`
         
-        /* This is rewritten as:
+        /* The code above is rewritten as:
         <fancy-text data-style="1">
             <style>
                 fancy-text[data-style="1"] { display: block; border: 10px dashed red } 
@@ -380,9 +484,9 @@ document.body.append(el);
 
 Note that if shadow-dom is used, the element will not replace the `:host` selector in styles, as  browsers natively support the `:host` selector when inside shadow DOM.
 
-### Sub Components
+### Child Components
 
-When one Solarite component is embedded within another, its attributes and children are passed as arguments to the constructor:
+When one web component is embedded within another, its attributes and children are passed as arguments to the constructor:
 
 ```javascript
 import {r} from './dist/Solarite.js';
@@ -395,7 +499,10 @@ class NotesItem extends HTMLElement {
 		this.render();
 	}
 	
-	render() { 
+	render({item}={}) {
+        // If item passed to the constructor has changed.
+        if (item)
+	        this.item = item;
 		r(this)`
 		<notes-item>
 		   <b>${this.item.name}</b> - ${this.item.description}<br>
@@ -430,35 +537,79 @@ list.items = [
 ]
 list.render();
 document.body.append(list);
+
+list.items[0].name = 'PhysEd';
+
+// list.items[0] has changed, 
+// so this will call render() on the first NotesItem, 
+// passing the new item object to its render() function.
+list.render();
+
 ```
 
-Note that calling `render()` on a parent component will call it on sub-components too.
+Calling `render()` on a parent component will call `render()` on child components if the attributes passed to the child component have changed.  The new attributes will be passed as an object as the first argument to the child component's `render()` function.  The `render()` function can then decide what to do with that data, and if it should re-render itself by calling `r(this)`, which will in turn call `render()` on its own child web components.
 
-### Classless Elements
+In the above code, we alternatively could've created the `<notes-item>` element via the `new` keyword, but doing so would cause all `NotesItem` components to be recreated on every render.
 
-The `r()` function can also create elements outside of a class.  Pass a function that returns a `Template` as the first argument.  Optionally set the second argument to an object of additional properties and methods.
+```JavaScript
+class NotesList extends HTMLElement {
+	render() { 
+		r(this)`
+		<notes-list>
+			${this.items.map(item => // Pass item object to NotesItem constructor:
+				new NotesItem({item: item})
+			)}
+		</notes-list>`
+	}
+}
+```
 
-```javascript
+
+
+### The r() function
+
+The `r()` function renders templates and elements.  There are multiple ways to use the `r()` function:
+
+```JavaScript
 import {r} from './dist/Solarite.js';
 
-let count = 0;
-let button = r(
-    	// Render function
-		() => r`
-			<button onclick=${(ev, self) => {
-				count++;
-				self.render();
-			}}>I've been clicked ${count} times</button>`,
-    
-    	// User-defined function
-		{
-			inc() {
-				count++;
-				this.render();
-			}
-		}
-	);
+// r`string`
+// Convert the html to a Template that can later be used to create nodes.
+let template = r`Hello ${"World"}!`;
+
+// r(HTMLElement, Template)
+// Render the template created by #1 to the <body> tag.
+r(document.body, template);  
+
+// r(Template):Node|HTMLElement
+// Render Template created by #1 creating a standaline HTML Element
+let el = r(template);
+
+// r(HTMLElement)`string`
+// Create template and render its nodes to el.
+r(el)`<b>${'Hi'}</b>`;
+
+// r(html:string):TextNode
+// Create single text node.
+let textNode = r('Hello');           
+
+// r(html:string):HTMLElement
+// Create single HTMLElement.
+let el2 = r('<b>Hello</b>');
+
+// r(html:string):DocumentFragment
+// Create document fragment because there's more than one node.
+let fragment = r('Hello <u>Goodbye</u>');
+
+// r(function():Template, Object<string, function|*>):HTMLElement
+// Crete a button element, with the fist function being the render function.
+let button = r({
+    render() {
+        r(this)`<button>Submit</button>`
+    }
+});
 document.body.append(button);
+
 ```
 
 ### Extending Other DOM Elements.
@@ -492,6 +643,70 @@ for (let i=0; i<10; i++) {
 document.body.append(table);
 ```
 
+### Manual DOM Ops
+
+You can perform manual DOM operations on your elements in these cases:
+
+1. Modify any attributes that are not created by expressions, on any nodes not created by expressions.
+2. Add/remove nodes that:
+   1. Are not created by an expression
+   2. Are not directly before or after an expression that creates nodes.
+   3. Do not have any attributes created by expressions.
+3. Modify any node, as long as you restore its previous position and attributes before `render()` is called again.
+
+This example creates a list inside a `div` element and demonstrates which manual DOM operations are allowed.
+
+```javascript
+import {r} from './dist/Solarite.js';
+
+let list = r({
+    items: [],
+
+    add() {
+        this.items.push('Item ' + this.items.length);
+        this.render();
+    },
+
+    render() {
+        r(this)`<div>
+        	<button onclick=${this.add}>Add Item</button>
+        	<hr>
+        	${this.items.map(item => r`
+        		<p>${item}</p>
+        	`)}
+        </div>`
+    }
+});
+
+document.body.append(list);
+
+// Set attributes not created by expressions.  This is allowed. 
+list.setAttribute('title', 'DOM manipuulation demo');
+list.querySelector('button').setAttribute('title', 'Click me');
+
+// Remove the <hr> element.
+// This is fine, because the hr element isn't part of an expression.
+// And isn't adjacent to an expression, because there's a whitespace
+// node between the <hr> and the expression.
+// You could also put a comment node between them.
+list.querySelector('hr').remove();
+list.render();
+
+// Remove the first <p> element and add it back again.
+// This is fine, because we put it back the way it was before render()
+list.add();
+let p = list.querySelector('p');
+list.append(p); // put it back.
+list.render();
+
+// Remove the first <p> element.
+// This will cause an error because we're modifying nodes created by an expression.
+// list.querySelector('p').remove();
+// list.render();
+```
+
+
+
 ### The Solarite Class (Experimental)
 
 Instead of inheriting from HTMLElement, you can inherit from the `Solarite` class, which will add a little bit of magic to your web component:
@@ -546,8 +761,8 @@ class MyTasks extends HTMLElement {
 		<div>
 			 ${this.tasks.map((task, index) =>  r`
 				<div>
-					 ${task.text}
-					 <button onClick=${() => this.deleteTask(index)}>Delete</button>
+					 ${task}
+					 <button onclick=${() => this.deleteTask(index)}>Delete</button>
 				 </div>`
 			 )}
 		</div>`;
@@ -557,17 +772,112 @@ customElements.define('my-tasks', MyTasks);
 
 let myTasks = new MyTasks();
 for (let i=0; i<10; i++)
-	myTasks.tasks.push({
-		text: 'Item ' + i,
-		completed: false
-	});
+	myTasks.tasks.push('Item ' + i);
 myTasks.render();
 document.body.append(myTasks);
 ```
 
 When `render()` is called:
 
-1. Solarite's `r()` function gets the array of raw strings created by tasks.map() using a template literal function.  
-2. It then creates a hash of the values of each item in the array.  
+1. Solarite's `r()` function gets the array of raw strings created by `tasks.map()` using a template literal function.  
+2. It then creates a hash of the value of every `${...}` expression given to the `r()` function.
 3. Then it compares those hashes with the hashes from the last time rendering happened, and only update elements and attributes given values that have changed.
 
+Solarite uses [WebReflection/udomdiff](https://github.com/WebReflection/udomdiff) to compare DOM nodes to update.
+
+## Examples
+
+This is the time example from Lit.js implemented with Solarite:
+
+```html
+<script type="module">
+import {r, getArg} from './dist/Solarite.js';
+
+const replay = r`<svg enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#000000"><title>Replay</title><g><rect fill="none" height="24" width="24"/><rect fill="none" height="24" width="24"/><rect fill="none" height="24" width="24"/></g><g><g/><path d="M12,5V1L7,6l5,5V7c3.31,0,6,2.69,6,6s-2.69,6-6,6s-6-2.69-6-6H4c0,4.42,3.58,8,8,8s8-3.58,8-8S16.42,5,12,5z"/></g></svg>`;
+const pause = r`<svg height="24px" viewBox="0 0 24 24" width="24px" fill="#000000"><title>Pause</title><path d="M0 0h24v24H0V0z" fill="none"/><path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z"/></svg>`;
+const play = r`<svg height="24px" viewBox="0 0 24 24" width="24px" fill="#000000"><title>Play</title><path d="M0 0h24v24H0V0z" fill="none"/><path d="M10 8.64L15.27 12 10 15.36V8.64M8 5v14l11-7L8 5z"/></svg>`;
+
+class MyTimer extends HTMLElement {
+  
+    constructor({duration}={}) {
+        super();
+        this.duration = getArg(this, 'duration', duration)*1;
+        this.end = null;
+        this.remaining = this.duration * 1000;
+        this.render();
+    }
+
+    render() {
+        const min = Math.floor(this.remaining / 60000);
+        const sec = pad(min, Math.floor((this.remaining / 1000) % 60));
+        const hun = pad(true, Math.floor((this.remaining % 1000) / 10));
+        r(this)`
+        <my-timer>
+          ${min ? `${min}:${sec}` : `${sec}.${hun}`}
+          <footer>
+            <style>
+            :host { display: inline-block; min-width: 90px; font-size: 30px; text-align: center; padding: 0.2em; margin: 0.2em 0.1em;
+                footer { user-select: none }        
+            }
+            </style>
+            ${
+              this.remaining === 0
+                ? ''
+                : this.running
+                ? r`<span onclick=${this.pause}>${pause}</span>`
+                : r`<span onclick=${this.start}>${play}</span>`
+            }
+            <span onclick=${this.reset}>${replay}</span>
+          </footer>
+        </my-timer>`;
+    }
+
+    start() {
+        this.end = Date.now() + this.remaining;
+        this.tick();
+    }
+
+    pause() {
+        this.end = null;
+        this.render();
+    }
+
+    reset() {
+        this.remaining = this.duration * 1000;
+        this.end = this.running ? Date.now() + this.remaining : null;
+        this.render();
+    }
+
+    tick() {
+        if (this.running) {
+            this.remaining = Math.max(0, this.end - Date.now());
+            this.render();
+            requestAnimationFrame(() => this.tick());
+        }
+    }
+
+    get running() {
+        return this.end && this.remaining;
+    }
+}
+customElements.define('my-timer', MyTimer);
+
+function pad(pad, val) {
+    return pad ? String(val).padStart(2, '0') : val;
+}
+</script>
+<my-timer duration="7"></my-timer>
+<my-timer duration="60"></my-timer>
+<my-timer duration="300"></my-timer>
+```
+
+
+
+## Upcoming Features
+
+These are possible features to come:
+
+1. Optional shadow DOM support
+2. Optional JSX support
+3. Option to render automatically when properties change, without calling render()
+4. Faster rendering performance.