micra.js 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,81 @@ All notable changes to Micra.js will be documented in this file. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning follows
 [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] — 2026-05-30
+
+### TypeScript — type-safe event bus
+
+- **New augmentable `MicraEvents` interface.** Declare your app's events
+  once and `Micra.emit` / `Micra.on` / `this.emit` / `this.on` enforce
+  payload types and arity at the call site:
+
+  ```ts
+  declare module 'micra.js' {
+    interface MicraEvents {
+      'cart:updated': { count: number }
+      'modal:close':  void
+    }
+  }
+
+  Micra.emit('cart:updated', { count: 3 })   // ✓
+  Micra.emit('cart:updated', { count: '3' }) // ✗ type error
+  Micra.emit('modal:close')                  // ✓ void → no args
+  ```
+
+- Events that are NOT declared in `MicraEvents` keep the previous
+  behaviour — payload typed as `unknown`, optional argument. Untyped
+  code keeps compiling unchanged.
+- New exported types: `MicraEvents`, `EventPayload<K>`, `EmitArgs<K>`.
+- Bundle stays at **5.4 KB gzip** — types only, no runtime change.
+
+### Breaking — types only
+
+- The legacy `on<T>(event, handler)` generic now infers `T` as the
+  event *key*, not the handler payload. Code that explicitly passed a
+  payload type via the generic (`Micra.on<User>('user:updated', h)`)
+  still compiles, but `h`'s parameter falls back to `unknown` unless
+  the event is declared in `MicraEvents`. Migration: register the
+  event via `declare module 'micra.js'` and drop the explicit generic.
+  No runtime impact.
+
+### Performance — non-keyed `data-each` now reuses DOM nodes
+
+- **Non-keyed `<template data-each>` no longer re-renders the whole list
+  on every update.** The new path keeps the first `min(prev, next)` row
+  nodes in place — only the length delta is touched (tail removed when
+  the list shrinks, new rows cloned when it grows). Each retained row
+  gets a fresh `itemState` and a re-applied directive pass through its
+  cached `__micraScan`, so content updates correctly without the
+  remove/re-clone overhead.
+- Row identity is now stable across renders for the no-key path: event
+  listeners bound via `data-on` / `@event` / `data-model` survive
+  re-renders without re-binding, and DOM-level state (focus, scroll,
+  CSS transitions) is preserved on retained rows.
+- Items that didn't change (same reference + same index) skip
+  `applyDirectives` entirely when only the `data-each` source array is
+  the trigger for this render cycle — same `canSkipUnchanged`
+  optimisation the keyed path already had.
+- Bundle: **5.5 KB gzip** (raised guard from 5.4 → 5.5 to give the
+  shared row-creation helper room; net code is slightly smaller after
+  factoring `createRowNode` out of both keyed and non-keyed paths).
+
+### Breaking — non-keyed multi-root rows now wrap in `<micra-each-item>`
+
+- Templates whose `data-each` content has more than one top-level node
+  now render each row inside a `<micra-each-item style="display:contents">`
+  wrapper, mirroring the keyed path's existing behaviour. The wrapper is
+  visually inert (CSS `display:contents` opts out of the box model) but
+  it does add one node to the parse tree.
+- Impact:
+  - **CSS:** child selectors that targeted `parent > .row` will now
+    match `parent > micra-each-item` instead. Use descendant selectors
+    (`parent .row`) or update the rules.
+  - **Invalid HTML contexts:** templates whose rows are `<tr>` / `<td>` /
+    `<li>` inside `<tbody>` / `<tr>` / `<ul>` cannot legally have a
+    wrapper between the parent and the row. Hoist the wrapper into the
+    template (so the row is single-rooted) or use a `data-key`.
+- Single-root templates are unchanged — by far the common case.
+
 ## [2.2.1] — 2026-05-28
 
 ### Performance — batched first list render

package/README.md

@@ -182,6 +182,7 @@ this.on(event, handler)
 - Recipes:
   - [Todo app](./docs/recipes/todo-app.md)
   - [Server-sent events (SSE)](./docs/recipes/sse.md)
+  - [htmx bridge](./docs/recipes/htmx.md)
 
 ## Code generation with LLMs
 

package/dist/core/bus.d.ts

@@ -10,23 +10,25 @@
  * Component instances subscribe via `instance.on()` which auto-registers
  * the unsub token in `instance.__micraSubs` for cleanup on destroy().
  */
-import type { EventHandler, UnsubFn } from '../types';
+import type { EmitArgs, EventPayload, UnsubFn } from '../types';
 /**
  * Subscribe to a named event. Returns an unsubscribe function.
+ * Payload is typed via the `MicraEvents` interface (augmentable).
  *
  * @example
  * const unsub = on('user:login', (user) => console.log(user))
  * unsub()  // stop listening
  */
-export declare function on<T = unknown>(event: string, handler: EventHandler<T>): UnsubFn;
+export declare function on<K extends string>(event: K, handler: (payload: EventPayload<K>) => void): UnsubFn;
 /**
  * Unsubscribe a specific handler from an event.
  */
-export declare function off(event: string, handler: EventHandler): void;
+export declare function off<K extends string>(event: K, handler: (payload: EventPayload<K>) => void): void;
 /**
  * Publish an event to all subscribers. Errors are caught per-handler.
+ * Payload is typed via the `MicraEvents` interface (augmentable).
  *
  * @example
  * emit('user:updated', { id: 1, name: 'Alice' })
  */
-export declare function emit(event: string, payload?: unknown): void;
+export declare function emit<K extends string>(event: K, ...args: EmitArgs<K>): void;

package/dist/dom/each.d.ts

@@ -4,7 +4,8 @@
  * Responsibilities:
  *   - Process `<template data-each="items" data-key="id">` elements
  *   - Keyed diff: reuse/reorder DOM nodes by key — O(n) with a Map
- *   - Non-keyed fallback: full replace (no key → warn in dev, full re-render)
+ *   - Non-keyed fallback: length-based positional reuse — min(old, new) rows
+ *     are kept as-is, the tail is removed or new rows are appended
  *   - Apply directives to each row with a scoped itemState
  *
  * LLM NOTE: renderList() is called on every render cycle AFTER applyDirectives().
@@ -12,7 +13,9 @@
  * Each row node gets its own ScanIndex cached on `node.__micraScan` so
  * re-renders of that row don't re-walk the DOM.
  * Keyed mode (data-key present) mutates the DOM in-place — nodes are
- * created once and reused. Non-keyed mode removes all nodes and re-clones.
+ * created once and reused. Non-keyed mode also reuses existing nodes
+ * positionally: only the length delta is touched, the rest gets a fresh
+ * itemState and re-applies directives.
  */
 import type { InternalInstance, StateRecord } from '../types';
 /**

package/dist/dom/scan.d.ts

@@ -10,7 +10,8 @@
  *     even *visit* those nodes.
  *   - <template> contents are not visited (browser TreeWalker default).
  *     `<template data-each>` itself IS visited and classified into scan.each;
- *     its children are processed by each.ts on every render via scanFragment.
+ *     its children are processed by each.ts on every render — fresh rows
+ *     are wrapped in a per-row element and scanned via scanComponent.
  *
  * Hot-path notes:
  *   - We read `el.attributes` once and switch by suffix. No allocations per
@@ -27,8 +28,3 @@ import type { ScanIndex } from "../types";
  * are free.
  */
 export declare function scanComponent(root: Element): ScanIndex;
-/**
- * Scan a DocumentFragment (no-key each clone). Not cached — these fragments
- * are temporary and re-cloned every render.
- */
-export declare function scanFragment(frag: DocumentFragment): ScanIndex;

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  *
  * @module Micra
  */
-export type { StateRecord, UnsubFn, EventHandler, FetchOptions, ComponentMethods, ComponentBuiltins, ComponentInstance, ComponentDefinition, } from './types';
+export type { StateRecord, UnsubFn, EventHandler, EventPayload, EmitArgs, MicraEvents, FetchOptions, ComponentMethods, ComponentBuiltins, ComponentInstance, ComponentDefinition, } from './types';
 export { FetchError } from './utils/fetch';
 export { define, defineComponent, instances, registry, debug } from './core/registry';
 export { mount } from './core/mount';

package/dist/micra.cjs.js

@@ -1,4 +1,4 @@
-/* Micra.js v2.2.1 — https://github.com/micra-js/micra — MIT */
+/* Micra.js v2.3.0 — https://github.com/micra-js/micra — MIT */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -227,8 +227,9 @@ function off(event, handler) {
   set.delete(handler);
   if (set.size === 0) _bus.delete(event);
 }
-function emit(event, payload) {
+function emit(event, ...args) {
   var _a;
+  const payload = args[0];
   (_a = _bus.get(event)) == null ? void 0 : _a.forEach((h) => {
     try {
       h(payload);
@@ -535,20 +536,6 @@ function scanComponent(root) {
   }
   return scan;
 }
-function scanFragment(frag) {
-  const scan = emptyScan();
-  const walker = document.createTreeWalker(
-    frag,
-    NodeFilter.SHOW_ELEMENT,
-    NESTED_COMPONENT_FILTER
-  );
-  let node = walker.nextNode();
-  while (node) {
-    classify(node, scan);
-    node = walker.nextNode();
-  }
-  return scan;
-}
 
 // src/dom/each.ts
 function renderList(templates, state, rawState, instance, triggerKey) {
@@ -579,10 +566,28 @@ function renderList(templates, state, rawState, instance, triggerKey) {
     if (keyAttr) {
       renderKeyed(tmpl, items, keyAttr, marker, keyMap, state, rawState, instance, canSkipUnchanged);
     } else {
-      renderNoKey(tmpl, items, marker, state, rawState, instance);
+      renderNoKey(tmpl, items, marker, state, rawState, instance, canSkipUnchanged);
     }
   }
 }
+function createRowNode(tmpl, state, instance) {
+  const frag = tmpl.content.cloneNode(true);
+  let node;
+  if (frag.childNodes.length === 1) {
+    node = frag.firstElementChild;
+  } else {
+    node = document.createElement("micra-each-item");
+    node.style.display = "contents";
+    node.append(frag);
+  }
+  const rowScan = scanComponent(node);
+  node.__micraScan = rowScan;
+  node._itemState = Object.create(state);
+  bindDataOn(rowScan.on, instance);
+  bindAtEvents(rowScan.atEvents, instance);
+  bindModels(rowScan.model, instance);
+  return node;
+}
 function renderKeyed(tmpl, items, keyAttr, marker, keyMap, state, rawState, instance, canSkipUnchanged) {
   var _a;
   const nextKeys = /* @__PURE__ */ new Set();
@@ -602,22 +607,9 @@ function renderKeyed(tmpl, items, keyAttr, marker, keyMap, state, rawState, inst
     nextKeys.add(key);
     let node = keyMap.get(key);
     if (!node) {
-      const frag = tmpl.content.cloneNode(true);
-      if (frag.childNodes.length === 1) {
-        node = frag.firstElementChild;
-      } else {
-        node = document.createElement("micra-each-item");
-        node.style.display = "contents";
-        node.append(frag);
-      }
+      node = createRowNode(tmpl, state, instance);
       node.__micraKey = key;
       keyMap.set(key, node);
-      const rowScan2 = scanComponent(node);
-      node.__micraScan = rowScan2;
-      bindDataOn(rowScan2.on, instance);
-      bindAtEvents(rowScan2.atEvents, instance);
-      bindModels(rowScan2.model, instance);
-      node._itemState = Object.create(state);
     } else if (canSkipUnchanged && node.__micraItem === item && node.__micraIndex === index) {
       nextNodes.push(node);
       continue;
@@ -695,29 +687,51 @@ function reorderKeyed(nextNodes, prevList, marker) {
     anchor = node;
   }
 }
-function renderNoKey(tmpl, items, marker, state, rawState, instance) {
-  tmpl.__micraList.forEach((n) => n.remove());
-  tmpl.__micraList = [];
-  const frag = document.createDocumentFragment();
-  for (const [index, item] of items.entries()) {
-    const clone = tmpl.content.cloneNode(true);
-    const itemState = Object.assign(
-      Object.create(state),
-      { item, index, $index: index }
-    );
-    const fragScan = scanFragment(clone);
-    applyDirectives(fragScan, itemState, rawState, instance);
-    bindDataOn(fragScan.on, instance);
-    bindAtEvents(fragScan.atEvents, instance);
-    bindModels(fragScan.model, instance);
-    const nodes = Array.from(clone.childNodes);
-    nodes.forEach((n) => {
-      n.__micraEach = true;
-      frag.append(n);
-    });
-    tmpl.__micraList.push(...nodes);
+function renderNoKey(tmpl, items, marker, state, rawState, instance, canSkipUnchanged) {
+  const prevList = tmpl.__micraList;
+  const prevLen = prevList.length;
+  const nextLen = items.length;
+  const reuseLen = nextLen < prevLen ? nextLen : prevLen;
+  const nextList = new Array(nextLen);
+  for (let i = 0; i < reuseLen; i++) {
+    const node = prevList[i];
+    const item = items[i];
+    if (canSkipUnchanged && node.__micraItem === item && node.__micraIndex === i) {
+      nextList[i] = node;
+      continue;
+    }
+    node.__micraItem = item;
+    node.__micraIndex = i;
+    const itemState = node._itemState;
+    itemState.item = item;
+    itemState.index = i;
+    itemState.$index = i;
+    applyDirectives(node.__micraScan, itemState, rawState, instance);
+    nextList[i] = node;
+  }
+  for (let i = nextLen; i < prevLen; i++) {
+    prevList[i].remove();
+  }
+  if (nextLen > prevLen) {
+    const frag = document.createDocumentFragment();
+    for (let i = prevLen; i < nextLen; i++) {
+      const node = createRowNode(tmpl, state, instance);
+      const item = items[i];
+      const itemState = node._itemState;
+      itemState.item = item;
+      itemState.index = i;
+      itemState.$index = i;
+      node.__micraEach = true;
+      node.__micraItem = item;
+      node.__micraIndex = i;
+      applyDirectives(node.__micraScan, itemState, rawState, instance);
+      nextList[i] = node;
+      frag.append(node);
+    }
+    const anchor = prevLen > 0 ? nextList[prevLen - 1] : marker;
+    anchor.after(frag);
   }
-  marker.after(frag);
+  tmpl.__micraList = nextList;
 }
 
 // src/dom/refs.ts