balises 0.5.0 → 0.7.0

package/README.md

@@ -4,7 +4,7 @@
   <img alt="balises" src="./assets/logo.svg" width="280">
 </picture>
 
-### A minimal reactive HTML templating library for building websites and web components. ~3.0KB gzipped.
+### A minimal reactive HTML templating library for building websites and web components. ~2.8KB gzipped.
 
 Balises gives you reactive signals and HTML templates without the framework overhead. Works great with custom elements, vanilla JavaScript projects, or anywhere you need dynamic UIs but don't want to pull in React.
 
@@ -29,10 +29,12 @@ Ultimately it turns out that I am quite happy with the result! It is quite perfo
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Building Web Components](#building-web-components)
-- [Composable Function Components](#composable-function-components)
+- [Function Components](#function-components)
+- [Async Generators](#async-generators)
+  - [DOM Preservation on Restart](#dom-preservation-on-restart)
 - [Template Syntax](#template-syntax)
 - [Reactivity API](#reactivity-api)
+- [Web Components](#web-components)
 - [Tree-Shaking / Modular Imports](#tree-shaking--modular-imports)
 - [Benchmarks](#benchmarks)
 
@@ -61,9 +63,116 @@ document.body.appendChild(fragment);
 // Call dispose() when done to clean up subscriptions
 ```
 
-## Building Web Components
+## Function Components
 
-Balises works naturally with the Web Components API. Just render templates in `connectedCallback` and clean up in `disconnectedCallback`.
+The recommended way to build UIs with balises is using function components - plain functions that receive props and return templates. This pattern is simpler than web components and better for composition.
+
+```ts
+import { html, store } from "balises";
+
+// Define a reusable component as a function
+function Counter({ state, onIncrement }) {
+  return html`
+    <div class="counter">
+      <span>Count: ${() => state.count}</span>
+      <button @click=${onIncrement}>+1</button>
+    </div>
+  `;
+}
+
+// Create shared state
+const state = store({ count: 0 });
+
+// Compose components together
+const { fragment, dispose } = html`
+  <div class="app">
+    <h1>My App</h1>
+    ${Counter({ state, onIncrement: () => state.count++ })}
+    ${Counter({ state, onIncrement: () => (state.count += 10) })}
+  </div>
+`.render();
+
+document.body.appendChild(fragment);
+```
+
+Pass the store itself (not individual values) so reactivity works.
+
+Wrap expressions in functions like `${() => state.count}` to track dependencies.
+
+## Async Generators
+
+Async generator functions handle loading states and async data flows. The generator automatically restarts when any tracked signal changes.
+
+**Note:** Async generators are opt-in via `balises/async` to keep the base bundle small.
+
+```ts
+import { html as baseHtml, signal } from "balises";
+import asyncPlugin from "balises/async";
+
+const html = baseHtml.with(asyncPlugin);
+const userId = signal(1);
+
+html`
+  ${async function* () {
+    const id = userId.value; // Track dependency - restarts when userId changes
+
+    yield html`<div class="loading">Loading...</div>`;
+
+    const user = await fetch(`/api/users/${id}`).then((r) => r.json());
+    yield html`<div class="profile">${user.name}</div>`;
+  }}
+`.render();
+
+// Changing userId restarts the generator automatically
+userId.value = 2;
+```
+
+Async generators replace the entire yielded content on each yield. For surgical updates within a stable DOM structure, use reactive bindings (`${() => state.value}`) instead.
+
+### DOM Preservation on Restart
+
+When a signal changes, the generator restarts and normally replaces the DOM. To preserve existing DOM and enable surgical updates via reactive bindings, return the `settled` parameter:
+
+```ts
+import { html as baseHtml, signal, store } from "balises";
+import asyncPlugin, { type RenderedContent } from "balises/async";
+
+const html = baseHtml.with(asyncPlugin);
+const userId = signal(1);
+const state = store({ user: null, loading: false });
+
+html`
+  ${async function* (settled?: RenderedContent) {
+    const id = userId.value;
+
+    if (settled) {
+      // Restart: update state, preserve existing DOM
+      state.loading = true;
+      const user = await fetch(`/api/users/${id}`).then((r) => r.json());
+      state.user = user;
+      state.loading = false;
+      return settled;
+    }
+
+    // First load: render with reactive bindings
+    yield html`<div class="skeleton">Loading...</div>`;
+    const user = await fetch(`/api/users/${id}`).then((r) => r.json());
+    state.user = user;
+    return html`
+      <div class="profile">
+        <h2>${() => state.user?.name}</h2>
+        <span>${() => (state.loading ? "Updating..." : "")}</span>
+      </div>
+    `;
+  }}
+`.render();
+```
+
+The `settled` parameter is `undefined` on first run, and contains an opaque handle to the previous render on restarts. Returning it preserves existing DOM nodes and reactive bindings.
+
+## Web Components
+
+For reusable widgets that need encapsulation or browser-native lifecycle, balises works naturally with the Web Components API:
 
 ```ts
 import { html, signal, effect } from "balises";
@@ -109,21 +218,6 @@ Use it in your HTML:
 
 You can build entire apps this way, or just add interactive widgets to existing pages. No build step required if you use it from a CDN.
 
-## Composable Function Components
-
-You can also use plain functions that return templates. Pass the store and access its properties in function wrappers to keep things reactive:
-
-```ts
-function Counter({ state }) {
-  return html`
-    <button @click=${() => state.count++}>${() => state.count}</button>
-  `;
-}
-
-const state = store({ count: 0 });
-html`<div>${Counter({ state })}</div>`.render();
-```
-
 ## Template Syntax
 
 The `html` tagged template creates reactive DOM fragments. When you interpolate a signal, that specific part of the DOM updates automatically when the signal changes.
@@ -170,44 +264,63 @@ html`
 
 ### Efficient List Rendering with `each()`
 
-When rendering lists that change frequently, use `each()` for keyed reconciliation. It caches templates by key so items can be reordered, added, or removed without recreating the DOM nodes:
+When rendering lists that change frequently, use `each()` for keyed reconciliation. It caches templates by key so items can be reordered, added, or removed without recreating the DOM nodes.
+
+**Note:** The `each()` function is opt-in via the `balises/each` import to keep the base bundle small. Use `html.with(eachPlugin)` to enable keyed list support.
+
+**Two forms:**
+
+1. **Two-arg form** (object reference as key): Render receives raw item. DOM reused only when same object reference appears.
+2. **Three-arg form** (explicit key function): Render receives `ReadonlySignal<T>`. DOM reused when keys match, even with new object references.
 
 ```ts
-import { html, signal, each } from "balises";
+import { html as baseHtml, signal } from "balises";
+import eachPlugin, { each } from "balises/each";
 
-const items = signal([
-  { id: 1, name: signal("Alice") },
-  { id: 2, name: signal("Bob") },
+const html = baseHtml.with(eachPlugin);
+
+// Three-arg form: explicit key, receives ReadonlySignal
+// DOM is preserved when keys match (ideal for API data)
+const users = signal([
+  { id: 1, name: "Alice" },
+  { id: 2, name: "Bob" },
 ]);
 
 html`
   <ul>
     ${each(
-      items,
-      (item) => item.id,
-      (item) => html`<li>${item.name}</li>`,
+      users,
+      (user) => user.id,
+      (userSignal) => html`<li>${() => userSignal.value.name}</li>`,
     )}
   </ul>
 `.render();
 
-// Append: only creates one new node
-items.value = [...items.value, { id: 3, name: signal("Carol") }];
+// Refetch from API - DOM preserved, content updated via signal
+users.value = [
+  { id: 1, name: "Alicia" }, // Same key, new object - DOM preserved!
+  { id: 2, name: "Bobby" },
+  { id: 3, name: "Carol" }, // New key - new DOM created
+];
 
-// Update content: surgical update, no list diffing
-items.value[0].name.value = "Alicia";
+// Two-arg form: object reference as key, receives raw item
+const items = signal([{ name: "Item 1" }, { name: "Item 2" }]);
 
-// Reorder: moves existing nodes, no recreation
-items.value = [...items.value].reverse();
+html`
+  <ul>
+    ${each(items, (item) => html`<li>${item.name}</li>`)}
+  </ul>
+`.render();
 ```
 
 Signatures:
 
 ```ts
-each(list, keyFn, renderFn); // keyed by keyFn(item, index)
-each(list, renderFn); // keyed by object reference or index
+each(list, keyFn, renderFn); // Three-arg: keyFn extracts key, renderFn receives ReadonlySignal<T>
+each(list, renderFn); // Two-arg: object reference as key, renderFn receives raw T
 ```
 
-If you want to update item content without triggering list reconciliation, nest signals inside your items (like `name: signal("Alice")` above).
+**Important:** When using the three-arg form, access item properties through `itemSignal.value` and wrap in `() => ...` for reactive updates.
 
 ## Reactivity API
 
@@ -235,6 +348,16 @@ count.value = count.value + 1;
 count.value = count.value * 2;
 ```
 
+**Reading without tracking dependencies:**
+
+```ts
+const count = signal(0);
+
+// peek() reads without creating a dependency
+// Useful in event handlers where you don't want reactivity
+button.onclick = () => console.log(count.peek());
+```
+
 ### `computed<T>(fn)`
 
 Derives a value from other signals. Automatically tracks dependencies.
@@ -414,7 +537,7 @@ doubled.dispose(); // Stops tracking, frees memory
 You can import just what you need to keep bundle size down:
 
 ```ts
-// Full library (~3.0KB gzipped)
+// Full library (~2.8KB gzipped)
 import { html, signal, computed, effect } from "balises";
 
 // Signals only (no HTML templating - use in any JS project)
@@ -428,6 +551,31 @@ import { store } from "balises/signals/store";
 import { batch, scope } from "balises/signals/context";
 ```
 
+### Template Plugins
+
+The `each()` and async generator features are provided as opt-in plugins to keep the base bundle minimal. Use `html.with()` to compose plugins:
+
+```ts
+// With each() support for keyed lists
+import { html as baseHtml } from "balises";
+import eachPlugin, { each } from "balises/each";
+
+const html = baseHtml.with(eachPlugin);
+
+// With async generator support
+import { html as baseHtml } from "balises";
+import asyncPlugin from "balises/async";
+
+const html = baseHtml.with(asyncPlugin);
+
+// With both plugins
+import { html as baseHtml } from "balises";
+import eachPlugin, { each } from "balises/each";
+import asyncPlugin from "balises/async";
+
+const html = baseHtml.with(eachPlugin, asyncPlugin);
+```
+
 ### Using as a Standalone Signals Library
 
 The reactivity system is completely independent of the HTML templating. You can use just the signals in Node.js, Electron, or any JavaScript environment:
@@ -541,23 +689,23 @@ Performance comparison of Balises against other popular reactive libraries. Benc
 ┌───────┬───────────────────┬───────┬───────────────┬──────────────────┐
 │ Rank  │ Library           │ Score │ Avg Time (μs) │ vs Fastest       │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #1 🏆 │ preact@1.12.1     │ 0.000 │ 47.70         │ 1.00x (baseline) │
+│ #1 🏆 │ preact@1.12.1     │ 0.000 │ 63.51         │ 1.00x (baseline) │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #2    │ balises@0.4.1     │ 0.027 │ 70.32         │ 1.47x            │
+│ #2    │ balises@0.6.0     │ 0.023 │ 86.17         │ 1.36x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #3    │ vue@3.5.26        │ 0.098 │ 78.02         │ 1.64x            │
+│ #3    │ vue@3.5.26        │ 0.093 │ 95.06         │ 1.50x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #4    │ maverick@6.0.0    │ 0.155 │ 92.49         │ 1.94x            │
+│ #4    │ maverick@6.0.0    │ 0.143 │ 122.79        │ 1.93x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #5    │ usignal@0.10.0    │ 0.205 │ 105.46        │ 2.21x            │
+│ #5    │ usignal@0.10.0    │ 0.180 │ 134.11        │ 2.11x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #6    │ angular@19.2.17   │ 0.219 │ 122.42        │ 2.57x            │
+│ #6    │ angular@19.2.17   │ 0.201 │ 154.19        │ 2.43x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #7    │ solid@1.9.10      │ 0.376 │ 217.29        │ 4.56x            │
+│ #7    │ solid@1.9.10      │ 0.340 │ 260.44        │ 4.10x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #8    │ mobx@6.15.0       │ 0.913 │ 638.92        │ 13.40x           │
+│ #8    │ mobx@6.15.0       │ 0.857 │ 896.48        │ 14.12x           │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #9    │ hyperactiv@0.11.3 │ 1.000 │ 683.44        │ 14.33x           │
+│ #9    │ hyperactiv@0.11.3 │ 1.000 │ 1029.95       │ 16.22x           │
 └───────┴───────────────────┴───────┴───────────────┴──────────────────┘
 ```
 
@@ -567,21 +715,21 @@ Performance comparison of Balises against other popular reactive libraries. Benc
 ┌───────────────────┬───────────────┬─────────────┬────────────────┬────────────────────┬─────────────┬──────────────┬──────────┐
 │ Library           │ S1: 1: Layers │ S2: 2: Wide │ S3: 3: Diamond │ S4: 4: Conditional │ S5: 5: List │ S6: 6: Batch │ Avg Rank │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ preact@1.12.1     │ #1 🏆         │ #1 🏆       │ #2             │ #1 🏆              │ #2          │ #2           │ 1.5      │
+│ preact@1.12.1     │ #1 🏆         │ #2          │ #2             │ #1 🏆              │ #1 🏆       │ #2           │ 1.5      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ balises@0.4.1     │ #2            │ #2          │ #1 🏆          │ #2                 │ #1 🏆       │ #1 🏆        │ 1.5      │
+│ balises@0.6.0     │ #3            │ #1 🏆       │ #1 🏆          │ #2                 │ #2          │ #1 🏆        │ 1.7      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ vue@3.5.26        │ #3            │ #3          │ #3             │ #3                 │ #3          │ #5           │ 3.3      │
+│ vue@3.5.26        │ #2            │ #3          │ #5             │ #3                 │ #3          │ #5           │ 3.5      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ maverick@6.0.0    │ #4            │ #5          │ #5             │ #4                 │ #5          │ #4           │ 4.5      │
+│ maverick@6.0.0    │ #5            │ #5          │ #4             │ #4                 │ #4          │ #4           │ 4.3      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ usignal@0.10.0    │ #5            │ #4          │ #4             │ #5                 │ #8          │ #7           │ 5.5      │
+│ usignal@0.10.0    │ #4            │ #4          │ #3             │ #5                 │ #8          │ #7           │ 5.2      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ angular@19.2.17   │ #6            │ #6          │ #7             │ #6                 │ #4          │ #3           │ 5.3      │
+│ angular@19.2.17   │ #6            │ #6          │ #6             │ #6                 │ #5          │ #3           │ 5.3      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ solid@1.9.10      │ #7            │ #8          │ #6             │ #7                 │ #6          │ #6           │ 6.7      │
+│ solid@1.9.10      │ #7            │ #8          │ #7             │ #7                 │ #7          │ #6           │ 7.0      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ mobx@6.15.0       │ #9            │ #7          │ #8             │ #8                 │ #7          │ #8           │ 7.8      │
+│ mobx@6.15.0       │ #9            │ #7          │ #8             │ #8                 │ #6          │ #8           │ 7.7      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
 │ hyperactiv@0.11.3 │ #8            │ #9          │ #9             │ #9                 │ #9          │ #9           │ 8.8      │
 └───────────────────┴───────────────┴─────────────┴────────────────┴────────────────────┴─────────────┴──────────────┴──────────┘
@@ -602,7 +750,7 @@ Performance comparison of Balises against other popular reactive libraries. Benc
 - These are synthetic benchmarks measuring pure reactivity - real apps should consider the whole picture (ecosystem, docs, community, etc.)
 - Lower rank = better performance
 
-_Last updated: 2026-01-02_
+_Last updated: 2026-01-04_
 
 <!-- BENCHMARK_RESULTS_END -->