balises 0.7.2 → 0.8.1

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. ~2.8KB gzipped.
+### A minimal reactive HTML templating library for building websites and web components. ~3.2KB 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.
 
@@ -268,19 +268,12 @@ When rendering lists that change frequently, use `each()` for keyed reconciliati
 
 **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 as baseHtml, signal } from "balises";
 import eachPlugin, { each } from "balises/each";
 
 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" },
@@ -302,25 +295,15 @@ users.value = [
   { id: 2, name: "Bobby" },
   { id: 3, name: "Carol" }, // New key - new DOM created
 ];
-
-// Two-arg form: object reference as key, receives raw item
-const items = signal([{ name: "Item 1" }, { name: "Item 2" }]);
-
-html`
-  <ul>
-    ${each(items, (item) => html`<li>${item.name}</li>`)}
-  </ul>
-`.render();
 ```
 
-Signatures:
+Signature:
 
 ```ts
-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
+each(list, keyFn, renderFn); // keyFn extracts key, renderFn receives ReadonlySignal<T>
 ```
 
-**Important:** When using the three-arg form, access item properties through `itemSignal.value` and wrap in `() => ...` for reactive updates.
+**Important:** Access item properties through `itemSignal.value` and wrap in `() => ...` for reactive updates.
 
 ## Reactivity API
 
@@ -523,6 +506,34 @@ count.value = 1; // logs "count changed to 1"
 unsubscribe(); // Stop listening
 ```
 
+### `.is(value)`
+
+Checks equality with O(1) update performance - ideal for selection patterns.
+
+When you have a signal representing a selected item (like `selectedId`), using `.is()` inside computed/templates creates optimized subscriptions. Only computeds checking the **previous** or **new** value are notified on change, not all of them.
+
+```ts
+import { html, signal } from "balises";
+
+const selected = signal<number | null>(null);
+
+// In a list of 1000 rows, only 2 rows update when selection changes
+// (the previously selected and newly selected)
+function Row({ id, label }) {
+  return html`
+    <tr class=${() => (selected.is(id) ? "danger" : "")}>
+      <td>${id}</td>
+      <td>${label}</td>
+    </tr>
+  `;
+}
+
+selected.value = 5; // Only row 5 gets "danger" class
+selected.value = 10; // Only rows 5 and 10 update
+```
+
+Works on both `Signal` and `Computed`. Uses `Object.is()` for equality checks.
+
 ### `.dispose()`
 
 Stops a computed from tracking dependencies and frees memory.
@@ -537,7 +548,7 @@ doubled.dispose(); // Stops tracking, frees memory
 You can import just what you need to keep bundle size down:
 
 ```ts
-// Full library (~2.8KB gzipped)
+// Full library (~3.2KB gzipped)
 import { html, signal, computed, effect } from "balises";
 
 // Signals only (no HTML templating - use in any JS project)
@@ -689,23 +700,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 │ 64.17         │ 1.00x (baseline) │
+│ #1 🏆 │ preact@1.12.1     │ 0.000 │ 64.93         │ 1.00x (baseline) │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #2    │ balises@0.7.0     │ 0.033 │ 85.48         │ 1.33x            │
+│ #2    │ balises@0.8.0     │ 0.052 │ 100.43        │ 1.55x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #3    │ vue@3.5.26        │ 0.095 │ 94.27         │ 1.47x            │
+│ #3    │ vue@3.5.26        │ 0.093 │ 96.74         │ 1.49x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #4    │ maverick@6.0.0    │ 0.146 │ 124.89        │ 1.95x            │
+│ #4    │ maverick@6.0.0    │ 0.149 │ 130.58        │ 2.01x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #5    │ usignal@0.10.0    │ 0.175 │ 133.48        │ 2.08x            │
+│ #5    │ usignal@0.10.0    │ 0.188 │ 148.47        │ 2.29x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #6    │ angular@19.2.17   │ 0.214 │ 169.86        │ 2.65x            │
+│ #6    │ angular@19.2.17   │ 0.211 │ 165.34        │ 2.55x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #7    │ solid@1.9.10      │ 0.343 │ 260.01        │ 4.05x            │
+│ #7    │ solid@1.9.10      │ 0.373 │ 320.23        │ 4.93x            │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #8    │ mobx@6.15.0       │ 0.854 │ 910.41        │ 14.19x           │
+│ #8    │ mobx@6.15.0       │ 0.836 │ 971.67        │ 14.97x           │
 ├───────┼───────────────────┼───────┼───────────────┼──────────────────┤
-│ #9    │ hyperactiv@0.11.3 │ 1.000 │ 1051.12       │ 16.38x           │
+│ #9    │ hyperactiv@0.11.3 │ 1.000 │ 1144.91       │ 17.63x           │
 └───────┴───────────────────┴───────┴───────────────┴──────────────────┘
 ```
 
@@ -715,21 +726,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 🏆              │ #1 🏆       │ #2           │ 1.3      │
+│ preact@1.12.1     │ #1 🏆         │ #1 🏆       │ #2             │ #1 🏆              │ #1 🏆       │ #1 🏆        │ 1.2      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ balises@0.7.0     │ #3            │ #2          │ #1 🏆          │ #2                 │ #2          │ #1 🏆        │ 1.8      │
+│ balises@0.8.0     │ #3            │ #2          │ #1 🏆          │ #2                 │ #2          │ #2           │ 2.0      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ vue@3.5.26        │ #2            │ #3          │ #5             │ #3                 │ #3          │ #5           │ 3.5      │
+│ vue@3.5.26        │ #2            │ #3          │ #5             │ #3                 │ #3          │ #4           │ 3.3      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ maverick@6.0.0    │ #5            │ #5          │ #4             │ #4                 │ #4          │ #4           │ 4.3      │
+│ maverick@6.0.0    │ #4            │ #5          │ #4             │ #4                 │ #4          │ #5           │ 4.3      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ usignal@0.10.0    │ #4            │ #4          │ #3             │ #5                 │ #8          │ #6           │ 5.0      │
+│ usignal@0.10.0    │ #5            │ #4          │ #3             │ #5                 │ #8          │ #6           │ 5.2      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ angular@19.2.17   │ #6            │ #6          │ #6             │ #6                 │ #5          │ #3           │ 5.3      │
+│ angular@19.2.17   │ #6            │ #6          │ #6             │ #6                 │ #6          │ #3           │ 5.5      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
 │ solid@1.9.10      │ #7            │ #8          │ #7             │ #7                 │ #7          │ #7           │ 7.2      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
-│ mobx@6.15.0       │ #9            │ #7          │ #8             │ #8                 │ #6          │ #8           │ 7.7      │
+│ mobx@6.15.0       │ #9            │ #7          │ #8             │ #8                 │ #5          │ #8           │ 7.5      │
 ├───────────────────┼───────────────┼─────────────┼────────────────┼────────────────────┼─────────────┼──────────────┼──────────┤
 │ hyperactiv@0.11.3 │ #8            │ #9          │ #9             │ #9                 │ #9          │ #9           │ 8.8      │
 └───────────────────┴───────────────┴─────────────┴────────────────┴────────────────────┴─────────────┴──────────────┴──────────┘
@@ -750,7 +761,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-05_
+_Last updated: 2026-01-10_
 
 <!-- BENCHMARK_RESULTS_END -->