micra.js 2.2.1 → 2.3.1

package/CHANGELOG.md

@@ -4,6 +4,124 @@ 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.1] — 2026-05-30
+
+### Performance
+
+- **Batch scheduler now uses `queueMicrotask` instead of
+  `Promise.resolve().then(...)`.** Each render batch enqueues a single
+  microtask instead of allocating a Promise plus a reaction job, and the
+  flush callback is hoisted out of the hot path so it isn't re-created on
+  every `schedule()` call. Behaviour is identical — same microtask timing,
+  same write-collapsing. No public-API change.
+
+### Internal — dead-code removal
+
+- Removed the `src/dom/query.ts` module (`queryAll` / `queryOwn` /
+  `queryOwnAll` / `filterOwn`). It had no importers since the 2.2.0
+  single-pass scan replaced per-render `querySelectorAll` calls with one
+  `TreeWalker` traversal — esbuild already tree-shook it out of the
+  bundle, so this is a source-only cleanup.
+- Removed two dead bookkeeping writes: `node.__micraEach` and
+  `node.__micraKey` were assigned during list rendering but never read
+  (keys live in the keyed-diff `Map`; the no-key path doesn't tag rows).
+  Dropped the matching fields from `MicraElement`.
+- Dropped the unused `instance` parameter from `applyDirectives` — it was
+  never referenced in the body.
+
+### Docs
+
+- New [Rails + Micra recipe](https://github.com/denisfl/micra.js/blob/master/docs/recipes/rails.md)
+  (`docs/recipes/rails.md` + a site page): manual importmap integration,
+  the `micra-rails` gem with its caveats, a Tasks board demonstrating SSR
+  props / CSRF-attached `this.fetch` / cross-component bus, and the Turbo
+  Drive / Streams / Frames mount-and-cleanup story.
+- README gains a **TypeScript** section spelling out what's checked
+  end-to-end (state, methods, event payloads) versus what isn't (the
+  expression strings inside `data-*` attributes).
+- Landing page gains **Speed** (cross-library benchmark cards) and **AI
+  sandboxes** (copy-the-LLM-prompt) sections.
+
+### Bundle
+
+- **5.5 KB gzip** (5582 bytes) — a few bytes lighter than 2.3.0 after the
+  dead-code removal.
+
+## [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

@@ -71,6 +71,48 @@ npm install micra.js
 import * as Micra from "micra.js";
 ```
 
+### TypeScript
+
+The npm package ships its own `dist/index.d.ts` — no `@types/micra.js` package
+needed. Inside every method body and lifecycle hook, both `this.state.X` and
+`this.someMethod()` are fully checked at the call site (both `state` and the
+method set are inferred from the literal you pass to `Micra.define`).
+
+```ts
+import * as Micra from "micra.js";
+
+Micra.define("counter", {
+  state: { count: 0 },
+  inc() {
+    this.state.count++;   // ✓ number
+    this.dec();           // ✓ inferred sibling method
+    // this.foo();        // ✗ Property 'foo' does not exist
+  },
+  dec() { this.state.count--; },
+});
+
+// Type-safe event bus via declaration merging
+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
+```
+
+**What's checked:** imports, state shape, method names, event-bus payloads,
+lifecycle hooks, refs, `Micra.mount()` return type.
+
+**What's not:** the expression strings inside `data-text="…"` / `@click="…"`
+attributes — those are plain HTML to the IDE and validated only at mount
+time. Same trade-off as Alpine.js `x-*` and petite-vue `v-*`; the
+alternatives are JSX or a single-file-component compiler, neither of which
+Micra ships.
+
 ## Basic usage
 
 A counter mounted automatically from `data-component`:
@@ -182,6 +224,8 @@ 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)
+  - [Rails + Micra](./docs/recipes/rails.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/core/reactive.d.ts

@@ -23,6 +23,10 @@ export declare function createReactiveState<S extends StateRecord>(obj: S, sched
  * Return a debounce function that defers `render` to the next microtask.
  * Multiple calls within the same tick collapse to a single render.
  *
+ * Uses `queueMicrotask` so each batch enqueues a single microtask instead of
+ * allocating a Promise + reaction job. `flush` is hoisted out of the hot path
+ * so it isn't re-created on every schedule() call.
+ *
  * @example
  * const schedule = createScheduler(render)
  * schedule()  // defers render

package/dist/dom/directives.d.ts

@@ -11,7 +11,7 @@
  *
  * Important: this module does NOT handle data-each — see dom/each.ts.
  */
-import type { InternalInstance, ScanIndex, StateRecord } from '../types';
+import type { ScanIndex, StateRecord } from '../types';
 import { warn } from '../utils/expr';
 /**
  * Apply all non-each directives to a component subtree.
@@ -23,7 +23,7 @@ import { warn } from '../utils/expr';
  * @param state    - Expression state (may include item/index for each rows)
  * @param rawState - Raw (non-proxy) state for model sync
  */
-export declare function applyDirectives<S extends StateRecord>(scan: ScanIndex, state: StateRecord, rawState: StateRecord, _instance: InternalInstance<S>): void;
+export declare function applyDirectives(scan: ScanIndex, state: StateRecord, rawState: StateRecord): void;
 /**
  * Validate directive usage and emit dev warnings.
  * Called once after the initial render of a component, with the already-built

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

@@ -5,12 +5,13 @@
  * traversal that classifies every directive attribute in a single visit.
  *
  * Boundaries:
- *   - REJECT (skip subtree) on nested [data-component] — same semantics as
- *     the old `filterOwn` helper, but applied during the walk so we don't
- *     even *visit* those nodes.
+ *   - REJECT (skip subtree) on nested [data-component] — a parent component
+ *     never processes directives owned by a nested child. Applied during the
+ *     walk so we don't 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.1 — 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);
@@ -252,13 +253,14 @@ function createReactiveState(obj, schedule, onKey) {
 }
 function createScheduler(render) {
   let pending = false;
+  const flush = () => {
+    pending = false;
+    render();
+  };
   return function schedule() {
     if (pending) return;
     pending = true;
-    Promise.resolve().then(() => {
-      pending = false;
-      render();
-    });
+    queueMicrotask(flush);
   };
 }
 
@@ -324,7 +326,7 @@ function applyModel(el, key, rawState) {
   const desired = stateVal == null ? "" : String(stateVal);
   if (html.value !== desired) html.value = desired;
 }
-function applyDirectives(scan, state, rawState, _instance) {
+function applyDirectives(scan, state, rawState) {
   for (const b of scan.if) applyIf(b, state);
   for (const b of scan.text) applyText(b.el, b.expr, state);
   for (const b of scan.html) applyHtml(b.el, b.expr, state);
@@ -535,20 +537,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 +567,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 +608,8 @@ 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.__micraKey = key;
+      node = createRowNode(tmpl, state, instance);
       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;
@@ -629,7 +621,7 @@ function renderKeyed(tmpl, items, keyAttr, marker, keyMap, state, rawState, inst
     itemState.index = index;
     itemState.$index = index;
     const rowScan = (_a = node.__micraScan) != null ? _a : node.__micraScan = scanComponent(node);
-    applyDirectives(rowScan, itemState, rawState, instance);
+    applyDirectives(rowScan, itemState, rawState);
     nextNodes.push(node);
   }
   for (const [key, node] of keyMap) {
@@ -695,29 +687,50 @@ 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);
-  }
-  marker.after(frag);
+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);
+    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.__micraItem = item;
+      node.__micraIndex = i;
+      applyDirectives(node.__micraScan, itemState, rawState);
+      nextList[i] = node;
+      frag.append(node);
+    }
+    const anchor = prevLen > 0 ? nextList[prevLen - 1] : marker;
+    anchor.after(frag);
+  }
+  tmpl.__micraList = nextList;
 }
 
 // src/dom/refs.ts
@@ -809,7 +822,7 @@ function mount(selector, definition) {
     try {
       const mRoot2 = root;
       const scan = (_a2 = mRoot2.__micraScan) != null ? _a2 : mRoot2.__micraScan = scanComponent(root);
-      applyDirectives(scan, exprState, rawState, instance);
+      applyDirectives(scan, exprState, rawState);
       renderList(scan.each, exprState, rawState, instance, triggerKey);
       bindDataOn(scan.on, instance);
       bindAtEvents(scan.atEvents, instance);