solarite 0.1.0 → 0.2.0

package/docs/index.md

@@ -1,27 +1,34 @@
 ---
-title:  Solarite Documentation
-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">
+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"><script async defer src="https://buttons.github.io/buttons.js"></script>
 
 ---
 
-<!-- To create documentation: (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. -->
 
-# Solarite Docs
+<!-- Playgrounds that don't have a lowercase language name will not have a preview. -->
 
-Solarite is a small (10KB min+gzip), fast, compilation-free JavaScript web component library that closely follows modern web standards.
+# Solarite
 
-This project is currently in ALPHA stage and not yet recommended for production code.  This documentations is also incomplete.
+Solarite is a small (8KB min+gzip), fast, compilation-free JavaScript library for creating elements and web components.  Features:
 
-If using Visual Studio Code, the Leet-Html extension is recommended to syntax highlight html inside template strings.
+- Minimal DOM updates when rendering.
+- 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 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.
 
 ```javascript
-// Type here to edit this code!
-import {Solarite, r} from '/src/solarite/Solarite.js';
+import {r} from './dist/Solarite.js';
 
-class ShoppingList extends Solarite {
+class ShoppingList extends HTMLElement {
 	constructor(items=[]) {
 		super();
 		this.items = items;
+		this.render();
 	}
 
 	addItem() {
@@ -34,318 +41,406 @@ class ShoppingList extends Solarite {
 		this.render();
 	}
 
-	render() {
-		this.html = r`
-			<shopping-list>
-				<style>
-					:host input { width: 50px }
-				</style>
-				<button onclick=${this.addItem}>Add Item</button>
-				${this.items.map(item => r`
-					<div style="display: flex; flex-direction: row">
-						<input value=${item.name} oninput=${[item, 'name']} placeholder="Name">
-						<input value=${item.qty} oninput=${[item, 'qty']}>
-						<button onclick=${[this.removeItem, item]}>x</button>
-					</div>			   
-				`)}
-				<pre>items = ${() => JSON.stringify(this.items, null, 4)}</pre>
-			</shopping-list>`
+	render() { 
+		// Think of r(this) as like:
+		// this.outerHTML = `<shopping-list>...` 
+		// but rendering only minimal DOM updates when the html changes.
+		r(this)`
+        <shopping-list>
+            <style> /* scoped styles */
+                :host input { width: 80px }
+            </style>
+
+            <button onclick=${this.addItem}>Add Item</button>
+
+            ${this.items.map(item => r`
+                <div>
+                    <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>			 
+            `)}
+
+            <pre>items = ${JSON.stringify(this.items, null, 4)}</pre>
+        </shopping-list>`
 	}
 }
-document.body.append(new ShoppingList()); // adds a child named <shopping-list>
+
+customElements.define('shopping-list', ShoppingList);
+document.body.append(new ShoppingList()); // add <shopping-list> element
 ```
 
-==TODO Does it re-render all Items on update?== 
+To use, import one of these pre-bundled es6 modules into your project:
 
-## Features
+- [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
 
-==TODO: Show benchmark==
+Or get Solarite from GitHub or NPM:
 
-- No custom build steps and no dependencies.  Not even Node.js.  Just `import` Solarite.js or Solarite.min.js.
-- Creates native HTML Elements and Web Components which can be used anywhere in your document and alongside other libraries.
-- No need to set up state.  Instead, use any regular variables or data structures in html templates.
-- Minimal updates on render
-- Local (scoped) styles
-- Two-way form element binding.
-- Optional shadow DOM (coming soon)
-- Optional JSX support (coming soon)
-- MIT license.  Free for commercial use.  No attribution needed.
+- [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`
 
-## Using
+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.
 
-Import one of these pre-bundled es6 modules into your project:
+## Concepts
 
-- [RedComponent.js](https://cdn.jsdelivr.net/gh/Vorticode/Solarite/dist/Solarite.js) - 76KB
-- [RedComponent.min.js](https://cdn.jsdelivr.net/gh/Vorticode/Solarite/dist/Solarite.js) - 21KB / 7KB gzipped
+### Regular Elements
 
-==TODO: NPM==
+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.
 
-## Examples
+```javascript
+import {r} from './dist/Solarite.js';
 
-## Concepts
+let button = r({
+    count: 0,
 
-### Creating Web Components
+    inc() {
+        this.count++;
+        this.render();
+    },
 
-In this minimal example, we make a new class called `MyComponent` and provide a `render()` function to set its html.
+    render() {
+        r(this)`<button onclick=${this.inc}>I've been clicked ${this.count} times.</button>`
+    }
+});
+document.body.append(button);
+```
 
-All browsers require custom web component names to have a dash in the middle.  Red Component looks at the case of the class name and converts it to a name with dashes.  If it can't find at least one place to put a dash, it will append `-element` to the end.
+If you want multiple instances of such an element, the code above can be wrapped in a function:
 
 ```javascript
-import {Solarite, r} from '../dist/Solarite.js';
+import {r} from './dist/Solarite.js';
 
-class MyComponent extends Solarite {
-	name = 'Red Component';
-	render() { 
-		this.html = r`<my-component>Hello <b>${this.name}!<b></my-component>`
-	}
-}
+function createButton(text) {
+	return r({
+		count: 0,
 
-document.body.append(new MyComponent());
-```
+		inc() {
+			this.count++;
+			this.render();
+		},
 
-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.
+		render() {
+			r(this)`<button onclick=${this.inc}>${this.count} ${text}</button>`
+		}
+	})
+}
+document.body.append(createButton('clicks'));
+document.body.append(createButton('tickles'));
+```
 
-Note that the template strings use the `r` prefix.  This `r` parses the html into a data structure that Red Component can use.
+### Web Components
 
-Alternatively, instead of instantiating the element in JavaScript, we could can instantiate the element directly from html.  This only works if we first call `MyComponent.define()` so so that our element's tag name is mapped to our class: 
+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.
 
-```html2
-<script>  
-	// ... 
-	// document.body.append(new MyComponent());
-	MyComponent.define()
-</script>
+All browsers require web component tag names to have at least one dash in the middle.  
 
-<my-component></my-component>
-```
+```javascript
+import {r} from './dist/Solarite.js';
 
-Internally, the `define()` function calculates the tag name from the class name and then calls the built-in [customElements.define()](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define).
+class MyComponent extends HTMLElement {
+	name = 'Solarite';
+    
+    constructor() {
+        super(); // JavaScript requires a super() call for sub-class construtors.
+        this.render();
+    }
+    
+	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>`
+	}
+}
 
-If you want the component to have a tag name that's different than the name derived from the class name, you can pass a different name to `define()`:
+// Register the <my-component> tag name with the browser.
+// Browsers require this for all web components.
+customElements.define('my-component', MyComponent);
 
-```javascript2
-MyComponent.define('my-awesome-component')
+document.body.append(new MyComponent());
 ```
 
-### The render() function, r, and this.html
+Alternatively, instead of instantiating the element in JavaScript, we could can instantiate the element directly from html:
 
-The `r` function, when used as part of a template literal, converts the html and embedded expressions into a data structure.  When that data structure is assigned to `this.html`, it updates the content of the web component.  You can think of this like assigning to the browser's built-in `this.outerHTML` property, except in this case instead of replacing all of the content, only the changed elements are replaced, which is much faster.
+```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!
 
-The render() function is called automatically when an element is added to the DOM via [connectedCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Web_components#connectedcallback).
+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.
 
-Unlike other frameworks Red Component does not re-render automatically when data changes, so you should call the render() function manually as needed.  This is a deliberate design choice to reduce "magic," since in some cases you may want to update internal data without rendering.
+### Rendering
 
+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 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.  You could instead just assign the html for the child elements to `this.html`.  But then you will have to set any attributes on your web component some other way.
+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:
 
 ```javascript
-import {Solarite, r} from '../dist/Solarite.js';
+import {r} from './dist/Solarite.js';
 
-class MyComponent extends Solarite {
+class MyComponent extends HTMLElement {
 	name = 'Solarite';
 	render() { 
 		// With optional element tags:
-		// this.html = r`<my-component>Hello <b>${this.name}!<b></my-component>`
+		// r(this)`<my-component class="big">Hello <b>${this.name}!<b></my-component>`
 		
 		// Without optional element tags:
-		this.html = r`Hello <b>${this.name}!<b>`
+		r(this)`Hello <b>${this.name}!<b>`;
+        this.setAttribute('class', 'big');
 	}
 }
-
+customElements.define('my-component', MyComponent);
 document.body.append(new MyComponent());
 ```
 
-If you do provide the outer tag, its name must exactly match the "dashes" version of the class name, or a custom name if you pass one to `define()`.
-
-### Inheriting from existing DOM elements.
+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()`.
 
-Suppose you want to use a custom component for each `<tr>` in a `<table>`.  Html won't allow you to put just any element as a child of table or tbody.  In this case you can make your web component inherit from the browser's built in `<tr>` element:
+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 {Solarite, r} from '../dist/Solarite.js';
-
-class LineItem extends Solarite('tr') {
-	constructor(user) {
-		super();
-		this.user = user;
-	}
-						   
-	render() { 
-		this.html = r`
-			<tr>			   
-				<td>${this.user.name}</td>
-				<td>${this.user.email}</td>
-			</tr>`
-	}
-}
-LineItem.define();
+import {r} from './dist/Solarite.js';
 
-let table = document.createElement('table')
-for (let i=0; i<10; i++) {
-	let user = {name: 'User ' + i, email: 'user'+i+'@example.com'};
-	table.append(new LineItem(user));
-}
-document.body.append(table)
-```
-
-### Loops
-
-Just as in some of the examples above, loops can be written with the build-in [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) function:
+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>`;
 
-```javascript
-import {Solarite, r} from '../dist/Solarite.js';
 
-class TodoList extends Solarite {
-	render() { 
-		this.html = r`
-			<todo-list>
-				${this.items.map(item => 
-					r`${item}<br>`
-				)}
-			</todo-list>`
+let icon1 = r({
+	render() {
+		r(this)`<div>${folderIcon}</div>`
 	}
-}
+});
+document.body.append(icon1);
 
-let list = new TodoList();
-list.items = ['one', 'two', 'three'];
-document.body.append(list); // calls render() if it hasn't been called already.
 
-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();
 ```
 
-Note that nested template literals must also have the `r` prefix. Otherwise they'll be rendered as escaped text instead of HTML elements.
+Folder icon comes from [Google](https://icon-sets.iconify.design/material-symbols/folder-outline/).
 
-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.
+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
 
-Attributes can be specified by inserting expressions inside a tag.  An expression can be part or all of an attribute value, or a string specifying multiple whole attributes.  For example:
+Dynamic attributes can be specified by inserting expressions inside a tag.  An expression can be part or all of an attribute value, or a string specifying multiple whole attributes.  For example:
 
 ```javascript
-import {Solarite, r} from '../dist/Solarite.js';
+import {r} from './dist/Solarite.js';
 
 let style = 'width: 100px; height: 40px; background: orange';
 let isEditable = true;
 let height = 40;
 
-class AttributeDemo extends Solarite {
+let attributeDemo = r({
 	render() { 
-		this.html = r`
-			<attribute-demo class="big">
-				
-				<div style=${style}>Look at me</div>
+		r(this)`
+        <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: ${height}px; background: gray">Look at me</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>`
-	}
-}
-document.body.append(new AttributeDemo());
+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 {Solarite, r} from '../dist/Solarite.js';
+import {r} from './dist/Solarite.js';
 
-class EventDemo extends Solarite {
-    showMessage(message) {
-        alert(message);
-    }
-    
+class EventDemo extends HTMLElement {
+	constructor() {
+		super();
+		this.render();
+	}
+	
+	showMessage(message) {
+		alert(message);
+	}
+	
 	render() { 
-		this.html = r`
-			<event-demo>
-				<div onclick=${()=>alert('I was clicked!')}>Click me</div>
-				<div onclick=${[this.showMessage, 'I too was clicked!']}>Click me</div>
-			</event-demo>`
+		r(this)`
+		<event-demo>
+			<button onclick=${(ev, el)=>alert('Element ' + el.tagName + ' clicked!')}>Click me</button>
+			<button onclick=${[this.showMessage, 'I too was clicked!']}>Click me too!</button>
+		</event-demo>`
 	}
-}
+} 
+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, Red Component can see that the function hasn't changed, and it doesn't need to be unbound and rebound.  But the performance difference is negligible in most cases.
+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
 
-==TODO: This demo should use auto-rendering==
-
-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 {Solarite, r} from '../dist/Solarite.js';
+import {r} from './dist/Solarite.js';
 
-class BindingDemo extends Solarite {
+class BindingDemo extends HTMLElement {
    
 	constructor() {
-		super();
+        super();
         this.count = 0;
-        // autoRender(this, 'count');
+        this.render();
     }
     
 	render() { 
-		this.html = r`
-			<binding-demo>
-				<input type="number" value=${this.count} oninput=${[this, 'count']}>
-				<pre>count is ${this.count}</pre>
-				<button onclick=${()=>this.count=0}>Reset</button>
-			</binding-demo>`
+		r(this)`
+        <binding-demo>
+            <input type="number" value=${this.count} 
+                oninput=${ev => {
+                    this.count = ev.target.value;
+                    this.render();
+                }}>
+            <pre>count is ${this.count}</pre>
+            <button onclick=${()=> { 
+                this.count = 0;
+                this.render();
+            }}>Reset</button>
+        </binding-demo>`
 	}
 }
+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.
 
-### Ids
-
-Any element in the html with an `id` or `data-id` attribute is automatically bound to a property with the same name on the root element.  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 {Solarite, r} from '../dist/Solarite.js';
+import {r} from './dist/Solarite.js';
 
-class RaceTeam extends Solarite {
-    constructor() {
+class BindingDemo extends HTMLElement {
+   
+	constructor() {
         super();
-        
-        // Id's are not set until render() is first called.
+        this.count = 0;
         this.render();
-        
-        // No need to render() again since we're changing the DOM manually.
-        this.driver.value = 'Mario'; 
     }
     
-	render() { this.html = r`
-		<race-team>
-            <input id="driver" value="Vermin Supreme">
-            <div data-id="car">Cutlas Supreme</div>
-            <div data-id="instructor.name">Lightning McQueen</div>
-        </race-team>`
+	render() { 
+		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>`
 	}
 }
-let rt = new RaceTeam();
-document.body.append(rt);
-rt.car.style.border = '1px solid green';
+customElements.define('binding-demo', BindingDemo);
 
+document.body.append(new BindingDemo());
 ```
 
-Ids that match built-in HTMLElement attribute names such as `title` or `disabled` are not allowed.
+
+
+### 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();
+```
+
+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
 
@@ -353,71 +448,436 @@ Html with `style` elements will be rewritten so that the `:host` selector applie
 
 These local, "scoped" styles are implemented by:
 
-1. Adding a `data-style` attribute to the root element with a unique, incrementing id value.
+1. Adding a `data-style` attribute to the root element with a unique, incrementing id value for each instance.
 2. Replacing any `:host` selectors inside the style with `element-name[data-style="1"]`.  For example the `:host` selector below becomes `fancy-text[data-style="1"]`.
 
 ```javascript
-import {Solarite, r} from '../dist/Solarite.js';
+import {r} from './dist/Solarite.js';
 
-class FancyText extends Solarite {
+class FancyText extends HTMLElement {
 	render() { 
-        return r`
+        r(this)`
         <fancy-text>
             <style>
-                :host { border: 10px dashed red } /* style for <fancy-text> */
-                :host p { text-shadow: 0 0 5px orange } 
+                :host { display: block; border: 10px dashed red } 
+                :host p { text-shadow: 0 0 3px #f40 } 
+            </style>
+            <p>I have a red border and shadow!</p>
+        </fancy-text>`
+        
+        /* The code above is rewritten as:
+        <fancy-text data-style="1">
+            <style>
+                fancy-text[data-style="1"] { display: block; border: 10px dashed red } 
+                fancy-text[data-style="1"] p { text-shadow: 0 0 3px #f40 } 
             </style>
             <p>I have a red border and shadow!</p>
         </fancy-text>`
+        */
+	}
+}
+customElements.define('fancy-text', FancyText);
+let el = new FancyText();
+el.render();
+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.
+
+### Child Components
+
+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';
+
+class NotesItem extends HTMLElement {
+	// Constructor receives item object from attributes.
+	constructor({item}, children) {
+		super();
+		this.item = item;
+		this.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>
+		</notes-item>`
+	}
+}
+customElements.define('notes-item', NotesItem);
+
+class NotesList extends HTMLElement {
+	render() { 
+		r(this)`
+		<notes-list>
+			${this.items.map(item => // Pass item object to NotesItem constructor:
+				r`<notes-item item=${item}"></notes-item>`
+			)}
+		</notes-list>`
 	}
 }
-document.body.append(new FancyText());
+customElements.define('notes-list', NotesList);
+
+let list = new NotesList();
+list.items = [
+	{
+		name: 'English',
+		description: 'See spot run.'
+	},
+	
+	{
+		name: 'Science',
+		description: 'Snails are mollusks.'
+	}
+]
+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 if shadown-dom is used, the element will not rewrite the `:host` selector in styles, as  browsers natively support the `:host` selector when inside shadow DOM.
+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.
 
-### Sub Components
+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.
 
-And constructors
+```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>`
+	}
+}
+```
 
-Calling render() on a parent component will call it on sub-components too.
 
-### Slots
 
 ### The r() function
 
-### Classless Elements
+The `r()` function renders templates and elements.  There are multiple ways to use the `r()` function:
+
+```JavaScript
+import {r} from './dist/Solarite.js';
+
+// 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');           
 
-### Watches (Experimental)
+// r(html:string):HTMLElement
+// Create single HTMLElement.
+let el2 = r('<b>Hello</b>');
 
-## Reference
+// 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.
+
+Suppose you want to use a custom component for each `<tr>` in a `<table>`.  Html won't allow you to put just any element as a child of table or tbody.  In this case you can make your web component inherit from the browser's built in `<tr>` element, by passing it as the third argument to `customElements.define`:
+
+```javascript
+import {r} from './dist/Solarite.js';
+
+class LineItem extends HTMLElement {
+	constructor(user) {
+		super();
+		this.user = user;
+        this.render();
+	}
+						   
+	render() { 
+		r(this)`			   
+            <th>${this.user.name}</td>
+            <td>${this.user.email}</td>`
+	}
+}
+
+customElements.define('line-item', LineItem, HTMLTableRowElement);
+
+let table = document.createElement('table')
+for (let i=0; i<10; i++) {
+	let user = {name: 'User ' + i, email: 'user'+i+'@example.com'};
+	table.append(new LineItem(user));
+}
+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:
+
+1. `render()` is automatically called when the element is added to the DOM, via a `connectedCallback()` function in the Solarite parent class.
+2. `customElements.define()` is automatically called when an element is instantiated via `new`.  It defines the element name based on the class name, by converting the class name to a tag name with dashes, because browsers require all custom elements to have at least one dash within the name.  If it can't find at least one place to put a dash, it will append `-element` to the end.
+
+If you want the component to have a tag name that's different than the name derived from the class name, you can pass a different name to `define()`:
+
+```javascript
+import {r, Solarite} from './dist/Solarite.js';
+
+class TodoList extends Solarite {
+	render() { 
+		r(this)`
+        <todo-list>
+            ${this.items.map(item => 
+                r`${item}<br>`
+            )}
+        </todo-list>`
+	}
+}
+// This is called automatically when we extend from Solarite:
+//customElements.define('todo-list', TodoList);
+
+let list = new TodoList();
+list.items = ['one', 'two', 'three'];
+//list.render(); render() is called automatically when appended to body.
+document.body.append(list);
+
+list.items[1] = '2';
+list.render();
+```
 
 ## How it works
 
-Suppose you're looping over an array of 100 objects and printing them to a list or table.  Something like this:
-
-```html2
- <ul>
-	 ${tasks().map((task, index) => (
-	 <li key={index} class={task.completed ? "completed" : ""}>
-		 <input
-				type="checkbox"
-				checked={task.completed}
-				onChange={() => toggleTask(index)}
-		 />
-		 {task.text}
-		 <button onClick={() => deleteTask(index)}>Delete</button>
-	 </li>
-	 ))}
-</ul>
+Suppose you're looping over an array of 10 objects and printing them to a list or table:
+
+```javascript
+import {r} from './dist/Solarite.js';
+
+class MyTasks extends HTMLElement {
+	tasks = [];
+	
+	deleteTask(index) {
+		this.tasks.splice(index, 1);
+		this.render();
+	}
+	
+	render() {
+		r(this)`
+		<div>
+			 ${this.tasks.map((task, index) =>  r`
+				<div>
+					 ${task}
+					 <button onclick=${() => this.deleteTask(index)}>Delete</button>
+				 </div>`
+			 )}
+		</div>`;
+	}
+}
+customElements.define('my-tasks', MyTasks);
+
+let myTasks = new MyTasks();
+for (let i=0; i<10; i++)
+	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 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>
 ```
 
-The code gets the array of raw strings created by tasks.map() using a template literal function.  Then it creates a hash of each of those.  Then it compares those hashes with the hashes from the last time rendering happened, and only update elements associated with the changed hashes.
 
-## Differences from other Libraries
 
-### React
+## Upcoming Features
 
-### Lit.js
+These are possible features to come:
 
-### Solid.js
+1. Optional shadow DOM support
+2. Optional JSX support
+3. Option to render automatically when properties change, without calling render()
+4. Faster rendering performance.