hyper-element 0.11.1 → 0.12.0

package/README.md

@@ -1,639 +1,1033 @@
 # hyper-element
 
-Combining the best of [hyperHTML] and [Custom Elements]!
+[![npm version](https://img.shields.io/npm/v/hyper-element.svg)](https://www.npmjs.com/package/hyper-element)
+[![npm package size](https://img.shields.io/bundlephobia/minzip/hyper-element)](https://bundlephobia.com/package/hyper-element)
+[![CI](https://github.com/codemeasandwich/hyper-element/actions/workflows/publish.yml/badge.svg)](https://github.com/codemeasandwich/hyper-element/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/codemeasandwich/hyper-element)
+[![ES6+](https://img.shields.io/badge/ES6+-supported-blue.svg)](https://caniuse.com/es6)
 
-[![npm version](https://badge.fury.io/js/hyper-element.svg)](https://www.npmjs.com/package/hyper-element)
-[![CDN link](https://img.shields.io/badge/CDN_link-hyper--element-red.svg)](https://cdn.jsdelivr.net/npm/hyper-element@latest/source/bundle.min.js)
-[![gzip size](http://img.badgesize.io/https://cdn.jsdelivr.net/npm/hyper-element@latest/source/bundle.min.js?compression=gzip)](https://cdn.jsdelivr.net/npm/hyper-element@latest/source/bundle.min.js)
+Combining the best of [hyperHTML] and [Custom Elements]! Your new custom-element will be rendered with the super fast **hyperHTML** and will react to tag attribute and store changes.
 
+### If you like it, please [★ it on github](https://github.com/codemeasandwich/hyper-element)
 
-Your new custom-element will be rendered with the super fast [hyperHTML] and will react to tag attribute and store changes.
-
-## why hyper-element
+# Installation
 
+## npm
 
-* hyper-element is fast & small
-    * With only 1 dependency: [hyperHTML]
-* With a completely stateless approach, setting and reseting the view is trivial
-* Simple yet powerful [Api](#api)
-* Built in [template](#templates) system to customise the rendered output
-* Inline style objects supported (similar to React)
-* First class support for [data stores](#example-of-connecting-to-a-data-store)
-* Pass `function` to other custom hyper-elements via there tag attribute
+```bash
+npm install hyper-element
+```
 
-# [Live Demo](https://jsfiddle.net/codemeasandwich/k25e6ufv/)
+### ES6 Modules
 
-### If you like it, please [★ it on github](https://github.com/codemeasandwich/hyper-element)
+```js
+import hyperElement from 'hyper-element';
 
----
+customElements.define(
+  'my-elem',
+  class extends hyperElement {
+    render(Html) {
+      Html`Hello ${this.attrs.who}!`;
+    }
+  }
+);
+```
 
-- [Define a Custom Element](#define-a-custom-element)
-- [Api](#api)
-  * [Define your element](#define-your-element)
-    + [render](#render)
-      + [Html](#html)
-      + [Html.wire](#htmlwire)
-      + [Html.lite](#htmllite)
-    + [setup](#setup)
-    + [this](#this)
-  * [Advanced attributes](#advanced-attributes)
-  * [Templates](#templates)
-  * [Fragments](#fragments)
-    + [fragment templates](#fragment-templates)
-    + [Async fragment templates](#asynchronous-fragment-templates)
-  * [Styling](#styling)
-- [Connecting to a data store](#example-of-connecting-to-a-data-store)
-  * [backbone](#backbone)
-  * [mobx](#mobx)
-  * [redux](#redux)
+### CommonJS
 
----
+```js
+const hyperElement = require('hyper-element');
 
-# Define a custom-element
+customElements.define(
+  'my-elem',
+  class extends hyperElement {
+    render(Html) {
+      Html`Hello ${this.attrs.who}!`;
+    }
+  }
+);
+```
 
-```js
-document.registerElement("my-elem", class extends hyperElement{
+## CDN (Browser)
 
-  render(Html){
-    Html`hello ${this.attrs.who}`
-  }// END render
+For browser environments without a bundler, include both hyperHTML and hyper-element via CDN:
 
-})// END my-elem
+```html
+<script src="https://cdn.jsdelivr.net/npm/hyperhtml@latest/index.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/hyper-element@latest/build/hyperElement.min.js"></script>
 ```
 
-If using **webpack**
+The `hyperElement` class will be available globally on `window.hyperElement`.
 
-```
-const hyperElement from "hyper-element"
-```
+## Browser Support
+
+hyper-element requires native ES6 class support and the Custom Elements v1 API:
+
+| Browser | Version |
+| ------- | ------- |
+| Chrome  | 67+     |
+| Firefox | 63+     |
+| Safari  | 10.1+   |
+| Edge    | 79+     |
+
+For older browsers, a [Custom Elements polyfill](https://github.com/webcomponents/polyfills/tree/master/packages/custom-elements) may be required.
 
-To use your element in brower
+## Why hyper-element
+
+- hyper-element is fast & small
+  - With only 1 dependency: [hyperHTML]
+- With a completely stateless approach, setting and reseting the view is trivial
+- Simple yet powerful [Interface](#interface)
+- Built in [template](#templates) system to customise the rendered output
+- Inline style objects supported (similar to React)
+- First class support for [data stores](#connecting-to-a-data-store)
+- Pass `function` to other custom hyper-elements via there tag attribute
+
+# [Live Demo](https://jsfiddle.net/codemeasandwich/k25e6ufv/)
+
+## Live Examples
+
+| Example              | Description                         | Link                                                       |
+| -------------------- | ----------------------------------- | ---------------------------------------------------------- |
+| Hello World          | Basic element creation              | [CodePen](https://codepen.io/codemeasandwich/pen/VOQpqz)   |
+| Attach a Store       | Store integration with setup()      | [CodePen](https://codepen.io/codemeasandwich/pen/VOQWeN)   |
+| Templates            | Using the template system           | [CodePen](https://codepen.io/codemeasandwich/pen/LoQLrK)   |
+| Child Element Events | Passing functions to child elements | [CodePen](https://codepen.io/codemeasandwich/pen/rgdvPX)   |
+| Async Fragments      | Loading content asynchronously      | [CodePen](https://codepen.io/codemeasandwich/pen/MdQrVd)   |
+| Styling              | React-style inline styles           | [CodePen](https://codepen.io/codemeasandwich/pen/RmQVKY)   |
+| Full Demo            | Complete feature demonstration      | [JSFiddle](https://jsfiddle.net/codemeasandwich/k25e6ufv/) |
+
+---
+
+- [Browser Support](#browser-support)
+- [Define a Custom Element](#define-a-custom-element)
+- [Lifecycle](#lifecycle)
+- [Interface](#interface)
+  - [render](#render)
+  - [Html](#html)
+  - [Html.wire](#htmlwire)
+  - [Html.lite](#htmllite)
+  - [setup](#setup)
+  - [this](#this)
+- [Advanced Attributes](#advanced-attributes)
+- [Templates](#templates)
+  - [Basic Syntax](#basic-template-syntax)
+  - [Conditionals](#conditionals-if)
+  - [Negation](#negation-unless)
+  - [Iteration](#iteration-each)
+- [Fragments](#fragments)
+- [Styling](#styling)
+- [Connecting to a Data Store](#connecting-to-a-data-store)
+  - [Backbone](#backbone)
+  - [MobX](#mobx)
+  - [Redux](#redux)
+- [Best Practices](#best-practices)
+- [Development](#development)
+
+---
+
+# Define a custom-element
 
 ```html
 <!DOCTYPE html>
 <html>
-<head>
-  <script src="https://cdn.jsdelivr.net/npm/webcomponentsjs@latest/lite.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/hyperhtml@latest/index.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/hyper-element@latest/source/bundle.min.js"></script>
-</head>
-<body>
-  <my-elem who="world"></my-elem>
-</body>
-<html>
+  <head>
+    <script src="https://cdn.jsdelivr.net/npm/hyperhtml@latest/index.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/hyper-element@latest/build/hyperElement.min.js"></script>
+  </head>
+  <body>
+    <my-elem who="world"></my-elem>
+    <script>
+      customElements.define(
+        'my-elem',
+        class extends hyperElement {
+          render(Html) {
+            Html`hello ${this.attrs.who}`;
+          }
+        }
+      );
+    </script>
+  </body>
+</html>
 ```
 
 Output
 
 ```html
-<my-elem who="world">
-    hello world
-</my-elem>
+<my-elem who="world"> hello world </my-elem>
 ```
 
-# Api
+**Live Example of [helloworld](https://codepen.io/codemeasandwich/pen/VOQpqz)**
+
+---
+
+# Lifecycle
+
+When a hyper-element is connected to the DOM, it goes through the following initialization sequence:
+
+1. Element connected to DOM
+2. Unique identifier created
+3. MutationObserver attached (watches for attribute/content changes)
+4. Fragment methods defined (methods starting with capital letters)
+5. Attributes and dataset attached to `this`
+6. `setup()` called (if defined)
+7. Initial `render()` called
+
+After initialization, the element will automatically re-render when:
+
+- Attributes change
+- Content mutations occur (innerHTML/textContent changes)
+- Store updates trigger `onStoreChange()`
+
+---
+
+# Interface
 
 ## Define your element
 
-There are 2 functions. `render` is *required* and `setup` is *optional*
+There are 2 functions. `render` is _required_ and `setup` is _optional_
 
-### render
+## render
 
-This is what will be displayed with in your element. Use the `Html` to define your content
+This is what will be displayed within your element. Use the `Html` to define your content.
 
-#### Html
+```js
+render(Html, store) {
+  Html`
+    <h1>
+      Last updated at ${new Date().toLocaleTimeString()}
+    </h1>
+  `;
+}
+```
+
+The second argument `store` contains the value returned from your store function (if using `setup()`).
+
+---
+
+## Html
 
 The primary operation is to describe the complete inner content of the element.
 
 ```js
-render(Html,store){
-
-    Html`
-      <h1>
-          Lasted updated at ${new Date().toLocaleTimeString()}
-      </h1>
-    `
-}// END render
+render(Html, store) {
+  Html`
+    <h1>
+      Last updated at ${new Date().toLocaleTimeString()}
+    </h1>
+  `;
+}
 ```
 
 The `Html` has a primary operation and two utilities: `.wire` & `.lite`
 
 ---
 
-#### Html.wire
+## Html.wire
+
+Create reusable sub-elements with object/id binding for efficient rendering.
 
-The `.wire` is for creating reusable sub-element
+The wire takes two arguments `Html.wire(obj, id)`:
 
-The wire can take two arguments `Html.wire(obj,id)`
-1. a refrive object to match with the create node. Allowing for reuse of the exiting node.
-2. a string to identify the markup used. Allowing the markup template to be generated only once.
+1. A reference object to match with the created node, allowing reuse of the existing node
+2. A string to identify the markup used, allowing the template to be generated only once
 
-Example of displaying a list of users from an array
+### Example: Rendering a List
 
 ```js
-    Html`
-      <ul>
-          ${users.map(user => Html.wire(user,":user_list_item")`<li>${user.name}</li>`)}
-      </ul>
-    `
+Html`
+  <ul>
+    ${users.map((user) => Html.wire(user, ':user_list_item')`<li>${user.name}</li>`)}
+  </ul>
+`;
 ```
 
-An **anti-pattern** is to inline the markup as a string
+### Anti-pattern: Inlining Markup as Strings
 
-BAD example: ✗
+**BAD example:** ✗
 
 ```js
-    Html`
-      <ul>
-          ${users.map(user => `<li>${user.name}</li>`)}
-      </ul>
-    `
+Html`
+  <ul>
+    ${users.map((user) => `<li>${user.name}</li>`)}
+  </ul>
+`;
 ```
 
-This will create a new node for every element on every render. The is have a **Negative impact on performance** and output will **Not be sanitized**. So DONT do this!
+This creates a new node for every element on every render, causing:
 
----
+- **Negative impact on performance**
+- **Output will not be sanitized** - potential XSS vulnerability
 
-#### Html.lite
+### Block Syntax
 
-The `.lite` is for creating once off sub-element
+The Html function supports block syntax for iteration and conditionals directly in tagged template literals:
 
-Example of wrapping the [jQuary date picker](https://jqueryui.com/datepicker/)
+| Syntax                                | Description           |
+| ------------------------------------- | --------------------- |
+| `{+each ${array}}...{-each}`          | Iterate over arrays   |
+| `{+if ${condition}}...{-if}`          | Conditional rendering |
+| `{+if ${condition}}...{else}...{-if}` | Conditional with else |
+| `{+unless ${condition}}...{-unless}`  | Negated conditional   |
 
-```js
+#### {+each} - Iteration
 
-onSelect(dateText, inst){
-  console.log("selected time "+dateText)
-} // END onSelect
+For cleaner list rendering, use the `{+each}...{-each}` syntax:
 
-Date(lite){
-  const inputElem = lite`<input type="text"/>`
-  $(inputElem).datepicker({onSelect:this.onSelect});
-  return {
-    any: inputElem,
-    once:true
-  }
-} // END Date
+```js
+Html`<ul>{+each ${users}}<li>{name}</li>{-each}</ul>`;
+```
 
-render(Html){
-  Html` Pick a date ${{Date:Html.lite}} `
-} // END render
+This is equivalent to:
 
+```js
+Html`<ul>${users.map((user) => Html.wire(user, ':id')`<li>${user.name}</li>`)}</ul>`;
 ```
 
----
+The `{+each}` syntax automatically calls `Html.wire()` for each item, ensuring efficient DOM reuse.
 
+**Available variables inside {+each}:**
 
-### setup
+| Syntax               | Description                               |
+| -------------------- | ----------------------------------------- |
+| `{name}`             | Access item property                      |
+| `{address.city}`     | Nested property access                    |
+| `{...}` or `{ ... }` | Current item value (see formatting below) |
+| `{@}`                | Current array index (0-based)             |
 
-The `setup` function wires up an external data-source. This is done with the `attachStore` argument that binds a data source to your renderer.
+**Formatting rules for `{...}` output:**
 
-#### Connect a data source
+| Type                                | Output                                                |
+| ----------------------------------- | ----------------------------------------------------- |
+| Primitive (string, number, boolean) | `toString()` and HTML escaped                         |
+| Array                               | `.join(",")`                                          |
+| Object                              | `JSON.stringify()`                                    |
+| Function                            | Called with no args, return value follows these rules |
 
-Example of re-rendering when the mouse moves. Will pass mouse values to render
+**Examples:**
 
 ```js
-// getMouseValues(){ ... }
+// Multiple properties
+Html`<ul>{+each ${users}}<li>{name} ({age})</li>{-each}</ul>`;
+
+// Using index
+Html`<ol>{+each ${items}}<li>{@}: {title}</li>{-each}</ol>`;
+
+// Nested arrays with {+each {property}}
+const categories = [
+  { name: 'Fruits', items: [{ title: 'Apple' }, { title: 'Banana' }] },
+  { name: 'Veggies', items: [{ title: 'Carrot' }] },
+];
+Html`
+  {+each ${categories}}
+    <section>
+      <h3>{name}</h3>
+      <ul>{+each {items}}<li>{title}</li>{-each}</ul>
+    </section>
+  {-each}
+`;
+```
 
-setup(attachStore){
+#### {+if} - Conditionals
 
-    // the getMouseValues function will be call before each render and pass to render
-    const onStoreChange = attachStore(getMouseValues)
+Render content based on a condition:
 
-    // call next on every mouse event
-    onMouseMove(onStoreChange)
+```js
+Html`{+if ${isLoggedIn}}<p>Welcome back!</p>{-if}`;
 
-    // cleanup logic
-    return ()=> console.warn("On remove, do component cleanup here")
-}// END setup
+// With else
+Html`{+if ${isLoggedIn}}<p>Welcome back!</p>{else}<p>Please log in</p>{-if}`;
 ```
 
-#### re-rendering without a data source
+#### {+unless} - Negated Conditionals
 
-Example of re-rendering every second
+Render content when condition is falsy (opposite of {+if}):
 
 ```js
-setup(attachStore){
-    setInterval(attachStore(), 1000);
-}// END setup
+Html`{+unless ${hasErrors}}<p>Form is valid</p>{-unless}`;
+
+// With else
+Html`{+unless ${isValid}}Invalid input!{else}Looking good!{-unless}`;
 ```
 
-#### Set initial values to pass to every render
+---
+
+## Html.lite
 
-Example of hard coding an object that will be used on **every** render
+Create once-off sub-elements for integrating external libraries.
+
+### Example: Wrapping jQuery DatePicker
 
 ```js
-setup(attachStore){
-    attachStore({max_levels:3})
-}// END setup
+customElements.define(
+  'date-picker',
+  class extends hyperElement {
+    onSelect(dateText, inst) {
+      console.log('selected time ' + dateText);
+    }
+
+    Date(lite) {
+      const inputElem = lite`<input type="text"/>`;
+      $(inputElem).datepicker({ onSelect: this.onSelect });
+      return {
+        any: inputElem,
+        once: true,
+      };
+    }
+
+    render(Html) {
+      Html`Pick a date ${{ Date: Html.lite }}`;
+    }
+  }
+);
 ```
 
-#### How to cleanup
+The `once: true` option ensures the fragment is only generated once, preventing the datepicker from being reinitialized on every render.
+
+---
+
+## setup
 
-Any logic you wish to run when the **element** is removed from the page should be returned as a function from the `setup` function
+The `setup` function wires up an external data-source. This is done with the `attachStore` argument that binds a data source to your renderer.
 
 ```js
-// listen to a WebSocket
-setup(attachStore){
+setup(attachStore) {
+  // the getMouseValues function will be called before each render and passed to render
+  const onStoreChange = attachStore(getMouseValues);
 
-  let newSocketValue;
-  const onStoreChange = attachStore(()=> newSocketValue);
-  const ws = new WebSocket("ws://127.0.0.1/data");
+  // call onStoreChange on every mouse event
+  onMouseMove(onStoreChange);
 
-  ws.onmessage = ({data}) => {
-    newSocketValue = JSON.parse(data);
-    onStoreChange()
-  }
+  // cleanup logic
+  return () => console.warn('On remove, do component cleanup here');
+}
+```
+
+**Live Example of [attach a store](https://codepen.io/codemeasandwich/pen/VOQWeN)**
 
-  // Return way to unsubscribe
-  return ws.close.bind(ws)
-}// END setup
+### Re-rendering Without a Data Source
 
-render(Html,incomingMessage){
-  // ...
-}// END render
+You can trigger re-renders without any external data:
+
+```js
+setup(attachStore) {
+  setInterval(attachStore(), 1000); // re-render every second
+}
 ```
 
-Returning a "teardown function" from `setup` address's the problem of needing a reference to the resource you want to release.
+### Set Initial Values
 
-> If the "teardown function" was a public function. We would need to store the reference to the resource somewhere. So the teardown can access it when needed.
+Pass static data to every render:
 
-With this approach there is no leaking of references.
+```js
+setup(attachStore) {
+  attachStore({ max_levels: 3 }); // passed to every render
+}
+```
 
-#### ✎ To subscribe to 2 events
+### Cleanup on Removal
+
+Return a function from `setup` to run cleanup when the element is removed from the DOM:
 
 ```js
-setup(attachStore){
+setup(attachStore) {
+  let newSocketValue;
+  const onStoreChange = attachStore(() => newSocketValue);
+  const ws = new WebSocket('ws://127.0.0.1/data');
 
-  const onStoreChange = attachStore(user);
+  ws.onmessage = ({ data }) => {
+    newSocketValue = JSON.parse(data);
+    onStoreChange();
+  };
+
+  // Return cleanup function
+  return ws.close.bind(ws);
+}
+```
 
-  mobx.autorun(onStoreChange);       // update when changed (real-time feedback)
-  setInterval(onStoreChange, 1000);  // update every second (update "the time is now ...")
+### Multiple Subscriptions
 
-}// END setup
+You can trigger re-renders from multiple sources:
 
+```js
+setup(attachStore) {
+  const onStoreChange = attachStore(user);
+
+  mobx.autorun(onStoreChange); // update when changed (real-time feedback)
+  setInterval(onStoreChange, 1000); // update every second (update "the time is now ...")
+}
 ```
 
 ---
 
-### this
-
-* **this.attrs** : the attributes on the tag `<my-elem min="0" max="10" />` = `{ min:0, max:10 }`
-    * Casting types supported: `Number`
-* **this.store** : the value returned from the store function. *!only updated before each render*
-* **this.wrappedContent** : the text content embedded between your tag `<my-elem>Hi!</my-elem>` = `"Hi!"`
-* **this.element** : a reference to your created element
-* **this.dataset**: this allows reading and writing to all the custom data attributes `data-*` set on the element.
-    * Data will be parsed to try and cast them to Javascript types
-    * Casting types supported: `Object`, `Array`, `Number` & `Boolean`
-    * `dataset` is a **live reflection**. Changes on this object will update matching data attribute on its element.
-        * e.g. `<my-elem data-users='["ann","bob"]'></my-elem>` to `this.dataset.users // ["ann","bob"]`
-    * ⚠ For performance! The `dataset` works by reference. To update an attribute you must use **assignment** on the `dataset`
-        * Bad: `this.dataset.user.name = ""` ✗
-        * Good: `this.dataset.user = {name:""}` ✓
+## this
 
----
+Available properties and methods on `this`:
 
-## Advanced attributes
+| Property              | Description                                                                 |
+| --------------------- | --------------------------------------------------------------------------- |
+| `this.attrs`          | Attributes on the tag. `<my-elem min="0" max="10" />` = `{ min:0, max:10 }` |
+| `this.store`          | Value returned from the store function. _Only updated before each render_   |
+| `this.wrappedContent` | Text content between your tags. `<my-elem>Hi!</my-elem>` = `"Hi!"`          |
+| `this.element`        | Reference to your created DOM element                                       |
+| `this.dataset`        | Read/write access to all `data-*` attributes                                |
 
-### Dynamic attributes with custom-element children
+### this.attrs
 
-Being able to set attributes at run-time should be the same for dealing with a native element and ones defined by hyper-element.
+Attributes are automatically type-coerced:
 
-**⚠ To support dynamic attributes on custom elements YOU MUST USE `customElements.define` which requires native ES6 support! Use the native source `/source/hyperElement.js` NOT `/source/bundle.js`**
+| Input     | Output    | Type   |
+| --------- | --------- | ------ |
+| `"42"`    | `42`      | Number |
+| `"3.14"`  | `3.14`    | Number |
+| `"hello"` | `"hello"` | String |
 
-This is what allows for the passing any dynamic attributes from parent to child custom element! You can also pass a `function` to a child element(that extends hyperElement).
+### this.dataset
 
-**Example:**
+The dataset provides proxied access to `data-*` attributes with automatic JSON parsing:
 
-In you document:
+| Attribute Value          | `this.dataset` Value | Type    |
+| ------------------------ | -------------------- | ------- |
+| `data-count="42"`        | `42`                 | Number  |
+| `data-active="true"`     | `true`               | Boolean |
+| `data-active="false"`    | `false`              | Boolean |
+| `data-users='["a","b"]'` | `["a", "b"]`         | Array   |
+| `data-config='{"x":1}'`  | `{ x: 1 }`           | Object  |
+
+**Example:**
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/hyper-element@latest/source/hyperElement.js"></script>
-<users-elem />
+<my-elem data-users='["ann","bob"]'></my-elem>
 ```
 
-Implementation:
+```js
+this.dataset.users; // ["ann", "bob"]
+```
+
+The `dataset` is a **live reflection**. Changes update the matching data attribute on the element:
 
 ```js
-window.customElements.define("a-user",class extends hyperElement{
-  render(Html){
-    const onClick = () => this.attrs.hi("Hello from "+this.attrs.name);
-    Html`${this.attrs.name} <button onclick=${onClick}>Say hi!</button>`
-  }
-})
+this.dataset.user = { name: 'Alice' }; // Updates data-user attribute
+```
+
+---
+
+## Advanced Attributes
 
-window.customElements.define("users-elem",class extends hyperElement{
-  onHi(val){
-    console.log("hi was clicked",val)
+### Dynamic Attributes with Custom-element Children
+
+Being able to set attributes at run-time should be the same for dealing with a native element and ones defined by hyper-element.
+
+**⚠ To support dynamic attributes on custom elements YOU MUST USE `customElements.define` which requires native ES6 support! Use `/build/hyperElement.min.js`.**
+
+This is what allows for the passing any dynamic attributes from parent to child custom element! You can also pass a `function` to a child element (that extends hyperElement).
+
+**Example:**
+
+```js
+window.customElements.define(
+  'a-user',
+  class extends hyperElement {
+    render(Html) {
+      const onClick = () => this.attrs.hi('Hello from ' + this.attrs.name);
+      Html`${this.attrs.name} <button onclick=${onClick}>Say hi!</button>`;
+    }
   }
-  render(Html){
-    Html`<a-user hi=${this.onHi} name="Beckett" />`
+);
+
+window.customElements.define(
+  'users-elem',
+  class extends hyperElement {
+    onHi(val) {
+      console.log('hi was clicked', val);
+    }
+    render(Html) {
+      Html`<a-user hi=${this.onHi} name="Beckett" />`;
+    }
   }
-})
+);
 ```
 
-Output:
+**Live Example of passing an [onclick to a child element](https://codepen.io/codemeasandwich/pen/rgdvPX)**
 
-```html
-<users-elem>
-  <a-user update="fn-bgzvylhphgvpwtv" name="Beckett">
-     Beckett <button>Say hi!</button>
-  </a-user>
-</users-elem>
-```
+---
 
-## Templates
+# Templates
 
-You can declare markup to be used as a template within the custom element
+Unlike standard Custom Elements which typically discard or replace their innerHTML, hyper-element's template system **preserves** the markup inside your element and uses it as a reusable template. This means your custom element primarily holds logic, while the template markup between the tags defines how data should be rendered.
 
 To enable templates:
 
-1. Add an attribute "templates" to your custom element
+1. Add a `template` attribute to your custom element
 2. Define the template markup within your element
+3. Call `Html.template(data)` in your render method to populate the template
 
 **Example:**
 
-In you document:
-
-```Html
-<my-list template data-json='[{"name":"ann","url":""},{"name":"bob","url":""}]' >
+```html
+<my-list template data-json='[{"name":"ann","url":""},{"name":"bob","url":""}]'>
   <div>
     <a href="{url}">{name}</a>
   </div>
 </my-list>
 ```
 
-Implementation:
-
 ```js
-document.registerElement("my-list",class extends hyperElement{
-
-      render(Html){
-        Html`
-        ${this.dataset.json.map(user => Html.template(user))}
-        `
-      }// END render
- })// END my-list
+customElements.define(
+  'my-list',
+  class extends hyperElement {
+    render(Html) {
+      Html`${this.dataset.json.map((user) => Html.template(user))}`;
+    }
+  }
+);
 ```
 
 Output:
-```Html
-<my-list template data-json='[{"name":"ann","url":""},{"name":"bob","url":""}]' >
-    <div>
-      <a href="">ann</a>
-    </div>
-    <div>
-      <a href="">bob</a>
-    </div>
+
+```html
+<my-list template data-json='[{"name":"ann","url":""},{"name":"bob","url":""}]'>
+  <div>
+    <a href="">ann</a>
+  </div>
+  <div>
+    <a href="">bob</a>
+  </div>
 </my-list>
 ```
 
-## Fragments
+**Live Example of using [templates](https://codepen.io/codemeasandwich/pen/LoQLrK)**
+
+---
 
-Fragments are pieces of content that can be loaded *asynchronously*.
+## Basic Template Syntax
 
-You define one with a class property starting with a **capital letter**.
+| Syntax                             | Description                           |
+| ---------------------------------- | ------------------------------------- |
+| `{variable}`                       | Simple interpolation                  |
+| `{+if condition}...{-if}`          | Conditional rendering                 |
+| `{+if condition}...{else}...{-if}` | Conditional with else                 |
+| `{+unless condition}...{-unless}`  | Negative conditional (opposite of if) |
+| `{+each items}...{-each}`          | Iteration over arrays                 |
+| `{@}`                              | Current index in each loop (0-based)  |
 
-To use one within your renderer. Pass an object with a property matching the fragment name and any values needed.
+---
 
-The fragment function should return an object with the following properties
+## Conditionals: {+if}
 
-* **placeholder:** the placeholder to show while resolving the fragment
-* **once:** Only generate the fragment once.
-    * Default: `false`. The fragment function will be run on every render!
+Show content based on a condition:
 
-and **one** of the following as the fragment's result:
+```html
+<status-elem template>{+if active}Online{else}Offline{-if}</status-elem>
+```
 
-* **text:** An escaped string to output  
-* **any:** An type of content
-* **html:** A html string to output, **(Not sanitised)**
-* **template:** A [template](#fragment-templates) string to use, **(Is sanitised)**
-    * **values:** A set of values to be used in the **template**
+```js
+customElements.define(
+  'status-elem',
+  class extends hyperElement {
+    render(Html) {
+      Html`${Html.template({ active: true })}`;
+    }
+  }
+);
+```
 
-**Example:**
+Output: `Online`
 
-Implementation:
+---
+
+## Negation: {+unless}
+
+Show content when condition is falsy (opposite of +if):
+
+```html
+<warning-elem template>{+unless valid}Invalid input!{-unless}</warning-elem>
+```
 
 ```js
-document.registerElement("my-friends",class extends hyperElement{
+customElements.define(
+  'warning-elem',
+  class extends hyperElement {
+    render(Html) {
+      Html`${Html.template({ valid: false })}`;
+    }
+  }
+);
+```
+
+Output: `Invalid input!`
 
-      FriendCount(user){
-        return {
+---
 
-          once:true,
+## Iteration: {+each}
 
-          placeholder: "loading your number of friends",
+Loop over arrays:
 
-          text:fetch("/user/"+user.userId+"/friends")
-              .then(b => b.json())
-              .then(friends => `you have ${friends.count} friends`)
-              .catch(err => "problem loading friends")
-        }// END return
-      }// END FriendCount
+```html
+<list-elem template>
+  <ul>
+    {+each items}
+    <li>{name}</li>
+    {-each}
+  </ul>
+</list-elem>
+```
 
-      render(Html){
-        const userId = this.attrs.myId
-        Html`<h2> ${{FriendCount:userId}} </h2>`
-      }// END render
- })// END my-friends
+```js
+customElements.define(
+  'list-elem',
+  class extends hyperElement {
+    render(Html) {
+      Html`${Html.template({ items: [{ name: 'Ann' }, { name: 'Bob' }] })}`;
+    }
+  }
+);
 ```
 
 Output:
 
 ```html
-<my-friends myId="1234">
-  <h2> loading your number of friends </h2>
-</my-friends>
+<ul>
+  <li>Ann</li>
+  <li>Bob</li>
+</ul>
 ```
-then
+
+### Special Variables in {+each}
+
+- `{@}` - The current index (0-based)
 
 ```html
-<my-friends myId="1234">
-  <h2> you have 635 friends </h2>
-</my-friends>
+<nums-elem template>{+each numbers}{@}: {number}, {-each}</nums-elem>
 ```
 
-### fragment templates
+```js
+customElements.define(
+  'nums-elem',
+  class extends hyperElement {
+    render(Html) {
+      Html`${Html.template({ numbers: ['a', 'b', 'c'] })}`;
+    }
+  }
+);
+```
 
-You can use the [template](#templates) syntax with in a fragment
+Output: `0: a, 1: b, 2: c, `
 
-* The template will use the values pass to it from the render or using a "values" property to match the template string
+---
 
-**e.g.** assigning values to template from with in the **fragment function**
-* `Foo(values){ return{ template:"<p>{txt}</p>", values:{txt:"Ipsum"} }}`
-* with `` Html`${{Foo:{}}}` ``
+# Fragments
 
-**or** assigning values to template from with in the **render function**
-* `Foo(values){ return{ template:"<p>{txt}</p>" }}`
-* with `` Html`${{Foo:{txt:"Ipsum"}}}` ``
+Fragments are pieces of content that can be loaded _asynchronously_.
 
-*Note: the different is whether or not a "values" is returned from the fragment function*
+You define one with a class property starting with a **capital letter**.
 
-**output**
+The fragment function should return an object with:
 
-`<p>Ipsum</p>`
+- **placeholder:** the placeholder to show while resolving
+- **once:** Only generate the fragment once (default: `false`)
 
-**Example:**
+And **one** of the following as the result:
+
+- **text:** An escaped string to output
+- **any:** Any type of content
+- **html:** A html string to output **(not sanitised)**
+- **template:** A template string to use **(is sanitised)**
 
-Implementation:
+**Example:**
 
 ```js
-document.registerElement("click-me",class extends hyperElement{
-      Button(){
-        return {
-          template:`<button type="button" class="btn"
-                        onclick={onclick}>{text}</button>`
-        }// END return
-      }// END Button
-      render(Html){
-        Html`Try ${{Button:{
-                  text:"Click Me",
-                  onclick:()=>alert("Hello!")
-              }}}`
-      }// END render
- })// END click-me
+customElements.define(
+  'my-friends',
+  class extends hyperElement {
+    FriendCount(user) {
+      return {
+        once: true,
+        placeholder: 'loading your number of friends',
+        text: fetch('/user/' + user.userId + '/friends')
+          .then((b) => b.json())
+          .then((friends) => `you have ${friends.count} friends`)
+          .catch((err) => 'problem loading friends'),
+      };
+    }
+
+    render(Html) {
+      const userId = this.attrs.myId;
+      Html`<h2> ${{ FriendCount: userId }} </h2>`;
+    }
+  }
+);
 ```
 
-Output:
+**Live Example of using an [asynchronous fragment](https://codepen.io/codemeasandwich/pen/MdQrVd)**
 
-```html
-<click-me>
-  Try <button type="button" class="btn">Click Me</button>
-</click-me>
+---
+
+# Styling
+
+Supports an object as the style attribute. Compatible with React's implementation.
+
+**Example:** of centering an element
+
+```js
+render(Html) {
+  const style = {
+    position: 'absolute',
+    top: '50%',
+    left: '50%',
+    marginRight: '-50%',
+    transform: 'translate(-50%, -50%)',
+  };
+  Html`<div style=${style}> center </div>`;
+}
 ```
 
-#### Asynchronous fragment templates
+**Live Example of [styling](https://codepen.io/codemeasandwich/pen/RmQVKY)**
 
-You can also return a [promise] as your `template` property.
+---
 
-Rewritting the *my-friends* example
+# Connecting to a Data Store
 
-**Example:**
+hyper-element integrates with any state management library via `setup()`. The pattern is:
 
-Implementation:
+1. Call `attachStore()` with a function that returns your state
+2. Subscribe to your store and call the returned function when state changes
+
+## Backbone
 
 ```js
-document.registerElement("my-friends",class extends hyperElement{
+var user = new (Backbone.Model.extend({
+  defaults: {
+    name: 'Guest User',
+  },
+}))();
+
+customElements.define(
+  'my-profile',
+  class extends hyperElement {
+    setup(attachStore) {
+      user.on('change', attachStore(user.toJSON.bind(user)));
+      // OR user.on("change", attachStore(() => user.toJSON()));
+    }
 
-      FriendCount(user){
+    render(Html, { name }) {
+      Html`Profile: ${name}`;
+    }
+  }
+);
+```
 
-        const templatePromise = fetch("/user/"+user.userId+"/friends")
-                                  .then(b => b.json())
-                                  .then(friends => ({
-                                          template:`you have {count} friends`,
-                                          values:{count:friends.count}
-                                        })
-                                  }) // END .then
-                                  .catch(err=>({ template:`problem loading friends` })
+## MobX
 
-        return {
-          once: true,
-          placeholder: "loading your number of friends",
-          template: templatePromise
-        } // END return
-      }// END FriendCount
+```js
+const user = observable({
+  name: 'Guest User',
+});
+
+customElements.define(
+  'my-profile',
+  class extends hyperElement {
+    setup(attachStore) {
+      mobx.autorun(attachStore(user));
+    }
 
-      render(Html){
-        const userId = this.attrs.myId
-        Html`<h2> ${{FriendCount:userId}} </h2>`
-      }// END render
- }) //END my-friends
+    render(Html, { name }) {
+      Html`Profile: ${name}`;
+    }
+  }
+);
 ```
 
-In this example, the values returned from the promise are used. As the "values" from a fragment function(if provided) takes priority over values passed in from render.
+## Redux
 
-Output:
+```js
+customElements.define(
+  'my-profile',
+  class extends hyperElement {
+    setup(attachStore) {
+      store.subscribe(attachStore(store.getState));
+    }
 
-```html
-<my-friends myId="1234">
-  <h2> you have 635 friends </h2>
-</my-friends>
+    render(Html, { user }) {
+      Html`Profile: ${user.name}`;
+    }
+  }
+);
 ```
 
+---
 
-## Styling
+# Best Practices
 
-Supports an object as the style attribute. Compatible with React's implementation.
+## Always Use Html.wire for Lists
 
-**Example:** of centering an element
+When rendering lists, always use `Html.wire()` to ensure proper DOM reuse and prevent XSS vulnerabilities:
 
 ```js
+// GOOD - Safe and efficient
+Html`<ul>${users.map((u) => Html.wire(u, ':item')`<li>${u.name}</li>`)}</ul>`;
 
-  render(Html){
-    const style= {
-      position: "absolute",
-      top: "50%", left: "50%",  
-      marginRight: "-50%",  
-      transform: "translate(-50%, -50%)"
-    }//END style
-    Html`<div style=${style}> center </div>`
-  }//END render
+// BAD - XSS vulnerability and poor performance
+Html`<ul>${users.map((u) => `<li>${u.name}</li>`)}</ul>`;
+```
+
+## Dataset Updates Require Assignment
+
+The `dataset` works by reference. To update an attribute you must use **assignment**:
+
+```js
+// BAD - mutation doesn't trigger attribute update
+this.dataset.user.name = '';
 
+// GOOD - assignment triggers attribute update
+this.dataset.user = { name: '' };
 ```
 
-# Example of connecting to a data store
+## Type Coercion Reference
+
+| Source         | Supported Types                |
+| -------------- | ------------------------------ |
+| `this.attrs`   | Number                         |
+| `this.dataset` | Object, Array, Number, Boolean |
 
-## backbone
+## Cleanup Resources in setup()
+
+Always return a cleanup function when using resources that need disposal:
 
 ```js
-var user = new (Backbone.Model.extend({
-    defaults: {
-        name: 'Guest User',
-    }
-}));//END Backbone.Model.extend
+setup(attachStore) {
+  const interval = setInterval(attachStore(), 1000);
+  return () => clearInterval(interval); // Cleanup on removal
+}
+```
+
+---
+
+# Development
+
+## Prerequisites
+
+- **Node.js** 20 or higher
+- **npm** (comes with Node.js)
+
+## Setup
 
+1. Clone the repository:
 
-document.registerElement("my-profile", class extends hyperElement{
+   ```bash
+   git clone https://github.com/codemeasandwich/hyper-element.git
+   cd hyper-element
+   ```
 
-  setup(attachStore){
-    user.on("change",attachStore(user.toJSON.bind(user)));
-    // OR user.on("change",attachStore(()=>user.toJSON()));
-  }//END setup
+2. Install dependencies:
 
-  render(Html,{name}){
-    Html`Profile: ${name}`
-  }//END render
-})//END my-profile
+   ```bash
+   npm install
+   ```
+
+   This also installs the pre-commit hooks automatically via the `prepare` script.
+
+## Available Scripts
+
+| Command               | Description                                       |
+| --------------------- | ------------------------------------------------- |
+| `npm run build`       | Build minified production bundle with source maps |
+| `npm test`            | Run Playwright tests with coverage                |
+| `npm run test:ui`     | Run tests with Playwright UI for debugging        |
+| `npm run test:headed` | Run tests in headed browser mode                  |
+| `npm run kitchensink` | Start local dev server for examples               |
+| `npm run lint`        | Run ESLint to check for code issues               |
+| `npm run format`      | Check Prettier formatting                         |
+| `npm run format:fix`  | Auto-fix Prettier formatting issues               |
+| `npm run release`     | Run the release script (maintainers only)         |
+
+## Project Structure
+
+```
+hyper-element/
+├── src/                     # Source files (ES modules)
+│   ├── core/                # Core utilities
+│   ├── attributes/          # Attribute handling
+│   ├── template/            # Template processing
+│   ├── html/                # HTML rendering
+│   ├── lifecycle/           # Lifecycle hooks
+│   └── hyperElement.js      # Main export
+├── build/
+│   ├── hyperElement.min.js  # Minified production build
+│   └── hyperElement.min.js.map
+├── kitchensink/             # Test suite
+│   ├── kitchensink.spec.js  # Playwright test runner
+│   └── *.html               # Test case files
+├── example/                 # Example project
+├── docs/                    # Documentation
+├── .hooks/                  # Git hooks
+│   ├── pre-commit           # Main hook orchestrator
+│   ├── commit-msg           # Commit message validator
+│   └── pre-commit.d/        # Modular validation scripts
+└── scripts/
+    └── publish.sh           # Release script
 ```
 
-## mobx
+## Building
 
-```js
-const user = observable({
-  name: 'Guest User'
-})//END observable
+The build process uses [esbuild](https://esbuild.github.io/) for fast, minimal output:
 
+```bash
+npm run build
+```
+
+This produces:
+
+- `build/hyperElement.min.js` - Minified bundle (~6.2 KB)
+- `build/hyperElement.min.js.map` - Source map for debugging
+
+## Pre-commit Hooks
 
-document.registerElement("my-profile", class extends hyperElement{
+The project uses a modular pre-commit hook system located in `.hooks/`. When you commit, the following checks run automatically:
 
-  setup(attachStore){
-    mobx.autorun(attachStore(user));
-  }// END setup
+1. **ESLint** - Code quality checks
+2. **Prettier** - Code formatting
+3. **Build** - Ensures the build succeeds
+4. **Coverage** - Enforces 100% test coverage
+5. **JSDoc** - Documentation validation
+6. **Docs** - Documentation completeness
 
-  render(Html,{name}){
-    Html`Profile: ${name}`
-  }// END render
-})//END my-profile
+If any check fails, the commit is blocked until the issue is fixed.
+
+### Installing Hooks Manually
+
+If hooks weren't installed automatically:
+
+```bash
+npm run hooks:install
 ```
 
-## redux
+## Code Style
 
-```js
-document.registerElement("my-profile", class extends hyperElement{
+- **Prettier** for formatting (2-space indent, single quotes, trailing commas)
+- **ESLint** for code quality
+- All files are automatically checked on commit
 
-  setup(attachStore){
-    store.subcribe(attachStore(store.getState)
-  }// END setup
+Run formatting manually:
 
-  render(Html,{user}){
-    Html`Profile: ${user.name}`
-  }// END render
-})// END my-profile
+```bash
+npm run format:fix
 ```
-[shadow-dom]:https://developers.google.com/web/fundamentals/web-components/shadowdom
-[innerHTML]:https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML
-[hyperHTML]:https://viperhtml.js.org/hyper.html
-[Custom Elements]:https://developer.mozilla.org/en-US/docs/Web/Web_Components/Custom_Elements
-[Test system]:https://jsfiddle.net/codemeasandwich/k25e6ufv/36/
-[promise]:https://scotch.io/tutorials/javascript-promises-for-dummies#understanding-promises
+
+## Testing
+
+See [kitchensink/README.md](kitchensink/README.md) for the full testing guide.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+---
+
+[shadow-dom]: https://developers.google.com/web/fundamentals/web-components/shadowdom
+[innerHTML]: https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML
+[hyperHTML]: https://viperhtml.js.org/hyper.html
+[Custom Elements]: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Custom_Elements
+[Test system]: https://jsfiddle.net/codemeasandwich/k25e6ufv/36/
+[promise]: https://scotch.io/tutorials/javascript-promises-for-dummies#understanding-promises