micra.js 2.2.0 → 2.3.0

package/src/dom/each.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 {
@@ -24,22 +27,24 @@ import type {
 import { evalExpr, warn } from '../utils/expr'
 import { applyDirectives } from './directives'
 import { bindDataOn, bindAtEvents, bindModels } from './events'
-import { scanComponent, scanFragment } from './scan'
+import { scanComponent } from './scan'
 
 /**
  * Process all `<template data-each>` elements found by the scanner.
  * Scoped itemState makes `item`, `index`, `$index` available in row expressions.
  *
- * @param templates - Pre-scanned list of <template data-each> elements
- * @param state     - Expression state (proxy merging rawState + instance)
- * @param rawState  - Raw (non-proxy) state — used for model binding
- * @param instance  - Component instance (for event binding)
+ * @param templates  - Pre-scanned list of <template data-each> elements
+ * @param state      - Expression state (proxy merging rawState + instance)
+ * @param rawState   - Raw (non-proxy) state — used for model binding
+ * @param instance   - Component instance (for event binding)
+ * @param triggerKey - Which state key triggered this render (null = initial, 'MULTIPLE' = batch)
  */
 export function renderList<S extends StateRecord>(
   templates: Element[],
   state: StateRecord,
   rawState: StateRecord,
   instance: InternalInstance<S>,
+  triggerKey: string | null | 'MULTIPLE',
 ): void {
   for (const tmplEl of templates) {
     if (tmplEl.tagName !== 'TEMPLATE') continue
@@ -60,10 +65,9 @@ export function renderList<S extends StateRecord>(
 
     const marker = tmpl.__micraMarker
     const keyMap = tmpl.__micraNodes
-    const parent = marker.parentNode
     // The template (and its marker) is currently detached — likely a data-if
     // ancestor unmounted this subtree. Nothing to do until it returns.
-    if (!parent) continue
+    if (!marker.parentNode) continue
 
     // Empty / non-array: clear all rendered rows
     if (!Array.isArray(items)) {
@@ -73,14 +77,51 @@ export function renderList<S extends StateRecord>(
       continue
     }
 
+    // canSkipUnchanged: true when only this list's state key changed — rows
+    // whose item reference and index are both unchanged can skip applyDirectives.
+    const canSkipUnchanged = triggerKey !== null &&
+                             triggerKey !== 'MULTIPLE' &&
+                             triggerKey === itemsExpr
+
     if (keyAttr) {
-      renderKeyed(tmpl, items as StateRecord[], keyAttr, marker, keyMap, parent, state, rawState, instance)
+      renderKeyed(tmpl, items as StateRecord[], keyAttr, marker, keyMap, state, rawState, instance, canSkipUnchanged)
     } else {
-      renderNoKey(tmpl, items as StateRecord[], marker, parent, state, rawState, instance)
+      renderNoKey(tmpl, items as StateRecord[], marker, state, rawState, instance, canSkipUnchanged)
     }
   }
 }
 
+// ── Row node creation (shared by both paths) ──────────────────────────────────
+
+/**
+ * Clone the template into a fresh row node, wrapping multi-root content in
+ * `<micra-each-item style="display:contents">` so the row always corresponds
+ * to a single, stable DOM element. Scans, binds listeners once, and caches
+ * an empty itemState prototyped from `state` (filled in by the caller).
+ */
+function createRowNode<S extends StateRecord>(
+  tmpl: MicraTemplate,
+  state: StateRecord,
+  instance: InternalInstance<S>,
+): MicraElement {
+  const frag = tmpl.content.cloneNode(true) as DocumentFragment
+  let node: MicraElement
+  if (frag.childNodes.length === 1) {
+    node = frag.firstElementChild as MicraElement
+  } else {
+    node = document.createElement('micra-each-item') as MicraElement
+    node.style.display = 'contents'
+    node.append(frag)
+  }
+  const rowScan = scanComponent(node)
+  node.__micraScan = rowScan
+  node._itemState = Object.create(state) as StateRecord
+  bindDataOn(rowScan.on, instance)
+  bindAtEvents(rowScan.atEvents, instance)
+  bindModels(rowScan.model, instance)
+  return node
+}
+
 // ── Keyed diff ────────────────────────────────────────────────────────────────
 
 function renderKeyed<S extends StateRecord>(
@@ -89,10 +130,10 @@ function renderKeyed<S extends StateRecord>(
   keyAttr: string,
   marker: Comment,
   keyMap: Map<unknown, MicraElement>,
-  parent: Node,
   state: StateRecord,
   rawState: StateRecord,
   instance: InternalInstance<S>,
+  canSkipUnchanged: boolean,
 ): void {
   const nextKeys  = new Set<unknown>()
   const nextNodes: MicraElement[] = []
@@ -114,30 +155,25 @@ function renderKeyed<S extends StateRecord>(
     let node = keyMap.get(key) as MicraElement | undefined
 
     if (!node) {
-      // Clone template and wrap multi-root fragments in a display:contents element
-      const frag = tmpl.content.cloneNode(true) as DocumentFragment
-      if (frag.childNodes.length === 1) {
-        node = frag.firstElementChild as MicraElement
-      } else {
-        node = document.createElement('micra-each-item') as MicraElement
-        node.style.display = 'contents'
-        node.append(frag)
-      }
+      node = createRowNode(tmpl, state, instance)
       node.__micraKey = key
       keyMap.set(key, node)
-      // Bind data-on / @event / data-model listeners once per row node.
-      // Scan the row, cache the scan on the node for future re-renders.
-      const rowScan = scanComponent(node)
-      node.__micraScan = rowScan
-      bindDataOn(rowScan.on, instance)
-      bindAtEvents(rowScan.atEvents, instance)
-      bindModels(rowScan.model, instance)
+    } else if (canSkipUnchanged && node.__micraItem === item && node.__micraIndex === index) {
+      // Item reference and index are unchanged, and no other state key changed
+      // this cycle — the DOM already reflects the latest values. Skip re-render.
+      nextNodes.push(node)
+      continue
     }
 
-    const itemState = Object.assign(
-      Object.create(state) as StateRecord,
-      { item, index, $index: index },
-    )
+    node.__micraItem  = item
+    node.__micraIndex = index
+
+    // Reuse the cached itemState, just update the per-row values.
+    const itemState = node._itemState!
+    itemState.item = item
+    itemState.index = index
+    itemState.$index = index
+
     // Use the cached scan if present (created above on first sight of this key);
     // older paths may pass a node we haven't scanned yet.
     const rowScan = node.__micraScan ?? (node.__micraScan = scanComponent(node))
@@ -150,47 +186,142 @@ function renderKeyed<S extends StateRecord>(
     if (!nextKeys.has(key)) { node.remove(); keyMap.delete(key) }
   }
 
-  // Insert / reorder nodes after marker (insertBefore is no-op if already in place)
-  let cursor: Node = marker
-  for (const node of nextNodes) {
-    if (cursor.nextSibling !== node) parent.insertBefore(node, cursor.nextSibling)
-    cursor = node
+  const prevList = tmpl.__micraList
+  if (prevList.length === 0) {
+    // First render (or refill after a clear): every node is new and already in
+    // order — batch into one fragment so the DOM takes a single insertion
+    // instead of N anchor.after() calls. Skips LIS entirely.
+    if (nextNodes.length) {
+      const frag = document.createDocumentFragment()
+      for (const node of nextNodes) frag.append(node)
+      marker.after(frag)
+    }
+  } else {
+    // Skip DOM reorder when list order is unchanged (pure JS array compare, no DOM reads).
+    let orderChanged = nextNodes.length !== prevList.length
+    if (!orderChanged) {
+      for (let i = 0; i < nextNodes.length; i++) {
+        if (nextNodes[i] !== prevList[i]) { orderChanged = true; break }
+      }
+    }
+    if (orderChanged) reorderKeyed(nextNodes, prevList, marker)
   }
 
   tmpl.__micraList = nextNodes
 }
 
-// ── Non-keyed (full re-render) ─────────────────────────────────────────────────
+// ── Keyed list reorder (LIS) ───────────────────────────────────────────────────
 
+/**
+ * Move DOM nodes to match `nextNodes` order using the minimum number of moves.
+ *
+ * Computes the Longest Increasing Subsequence of each node's position in prevList —
+ * nodes in the LIS keep their place. Only the others are re-inserted via anchor.after().
+ *
+ * Complexity: O(n log n) for LIS, O(k) DOM operations where k = nodes that moved.
+ * For a 2-node swap this means 2 DOM ops instead of n.
+ */
+function reorderKeyed(nextNodes: MicraElement[], prevList: MicraElement[], marker: Comment): void {
+  const prevPos = new Map<MicraElement, number>()
+  for (let i = 0; i < prevList.length; i++) prevPos.set(prevList[i]!, i)
+
+  const n = nextNodes.length
+  const tails: number[] = []     // patience sort: smallest tail at each LIS length
+  const tailIdx: number[] = []   // index into nextNodes for each tail
+  const prev: number[] = new Array(n).fill(-1)
+
+  for (let i = 0; i < n; i++) {
+    const p = prevPos.get(nextNodes[i]!)
+    if (p === undefined) continue  // new node — always moved
+    let lo = 0, hi = tails.length
+    while (lo < hi) { const m = (lo + hi) >> 1; tails[m]! < p ? lo = m + 1 : hi = m }
+    if (lo > 0) prev[i] = tailIdx[lo - 1]!
+    tails[lo] = p
+    tailIdx[lo] = i
+  }
+
+  // Reconstruct stable (non-moving) set from LIS parent chain
+  const stable = new Set<number>()
+  let idx: number = tailIdx[tails.length - 1]!
+  while (idx >= 0) { stable.add(idx); idx = prev[idx]! }
+
+  // Move unstable nodes into position; stable (LIS) nodes serve as anchors
+  let anchor: ChildNode = marker
+  for (let i = 0; i < n; i++) {
+    const node = nextNodes[i]!
+    if (stable.has(i)) { anchor = node; continue }
+    anchor.after(node)
+    anchor = node
+  }
+}
+
+// ── Non-keyed (positional reuse) ──────────────────────────────────────────────
+
+/**
+ * Diff a non-keyed list by length: reuse the first min(prev, next) DOM nodes,
+ * remove the tail when the list shrinks, clone fresh rows for the growth delta.
+ * Multi-root template rows are wrapped in `<micra-each-item style="display:contents">`
+ * — same as keyed mode — so the reused list is one DOM node per row.
+ */
 function renderNoKey<S extends StateRecord>(
   tmpl: MicraTemplate,
   items: StateRecord[],
   marker: Comment,
-  parent: Node,
   state: StateRecord,
   rawState: StateRecord,
   instance: InternalInstance<S>,
+  canSkipUnchanged: boolean,
 ): void {
-  tmpl.__micraList.forEach(n => n.remove())
-  tmpl.__micraList = []
+  const prevList = tmpl.__micraList
+  const prevLen = prevList.length
+  const nextLen = items.length
+  const reuseLen = nextLen < prevLen ? nextLen : prevLen
+  const nextList: MicraElement[] = new Array(nextLen)
 
-  const frag = document.createDocumentFragment()
-  for (const [index, item] of items.entries()) {
-    const clone = tmpl.content.cloneNode(true) as DocumentFragment
-    const itemState = Object.assign(
-      Object.create(state) as StateRecord,
-      { item, index, $index: index },
-    )
-    // Fresh clone each render → fresh scan each render (uncached).
-    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) as MicraElement[]
-    nodes.forEach(n => { n.__micraEach = true; frag.append(n) })
-    tmpl.__micraList.push(...nodes)
+  // 1. Reuse [0, reuseLen): refresh itemState, re-apply directives in place.
+  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
+  }
+
+  // 2. Shrink: remove tail nodes [nextLen, prevLen).
+  for (let i = nextLen; i < prevLen; i++) {
+    prevList[i]!.remove()
   }
-  parent.insertBefore(frag, marker.nextSibling)
+
+  // 3. Grow: clone and attach fresh rows for [prevLen, nextLen).
+  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)
+    }
+    // Insert after the last reused node, or the marker if the list was empty.
+    const anchor: ChildNode = prevLen > 0 ? nextList[prevLen - 1]! : marker
+    anchor.after(frag)
+  }
+
+  tmpl.__micraList = nextList
 }

package/src/dom/refs.ts

@@ -26,6 +26,7 @@ export function collectRefs<S extends StateRecord>(
   els: Element[],
   instance: InternalInstance<S>,
 ): void {
+  if (!els.length) return
   instance.refs = {}
   for (const el of els) {
     const name = (el as MicraElement).dataset['ref']

package/src/dom/scan.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
@@ -166,24 +167,3 @@ export function scanComponent(root: Element): ScanIndex {
   return scan;
 }
 
-/**
- * Scan a DocumentFragment (no-key each clone). Not cached — these fragments
- * are temporary and re-cloned every render.
- */
-export function scanFragment(frag: DocumentFragment): ScanIndex {
-  const scan = emptyScan();
-
-  const walker = document.createTreeWalker(
-    frag,
-    NodeFilter.SHOW_ELEMENT,
-    NESTED_COMPONENT_FILTER,
-  );
-
-  let node: Element | null = walker.nextNode() as Element | null;
-  while (node) {
-    classify(node, scan);
-    node = walker.nextNode() as Element | null;
-  }
-
-  return scan;
-}

package/src/index.ts

@@ -27,6 +27,9 @@ export type {
   StateRecord,
   UnsubFn,
   EventHandler,
+  EventPayload,
+  EmitArgs,
+  MicraEvents,
   FetchOptions,
   ComponentMethods,
   ComponentBuiltins,

package/src/types.ts

@@ -22,6 +22,53 @@ export type UnsubFn = () => void
 /** Event bus handler. Generic `T` types the payload. */
 export type EventHandler<T = unknown> = (payload: T) => void
 
+/**
+ * Type-safe event bus registry. Empty by default — augment it via
+ * declaration merging to type your application's events.
+ *
+ * @example
+ * declare module 'micra.js' {
+ *   interface MicraEvents {
+ *     'cart:updated': { count: number }
+ *     'user:login':   { id: number; name: string }
+ *     'modal:close':  void
+ *   }
+ * }
+ *
+ * Micra.emit('cart:updated', { count: 3 })       // ✓ typed
+ * Micra.emit('cart:updated', { count: '3' })     // ✗ type error
+ * Micra.on('user:login', user => user.id)        // user: { id, name }
+ *
+ * Events not present in the interface fall back to `unknown` payload —
+ * fully backward-compatible with untyped usage.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface MicraEvents {}
+
+/**
+ * Resolves the payload type for an event key. For keys registered in
+ * `MicraEvents` returns the declared payload; for any other string key
+ * returns `unknown` (preserving backward compatibility).
+ */
+export type EventPayload<K extends string> = K extends keyof MicraEvents
+  ? MicraEvents[K]
+  : unknown
+
+/**
+ * Tuple of arguments passed to `emit` after the event name. When the
+ * payload type for a known event includes `undefined` (or the payload is
+ * declared as `void`), the argument is optional. For known events with a
+ * required payload, the argument is required. Unknown events accept any
+ * optional payload (backward compat).
+ */
+export type EmitArgs<K extends string> = K extends keyof MicraEvents
+  ? [MicraEvents[K]] extends [void]
+    ? [payload?: undefined]
+    : undefined extends MicraEvents[K]
+      ? [payload?: MicraEvents[K]]
+      : [payload: MicraEvents[K]]
+  : [payload?: unknown]
+
 /** Options for `this.fetch()`. For GET/HEAD extra keys become query params. */
 export interface FetchOptions {
   method?: string
@@ -71,10 +118,16 @@ export interface ComponentBuiltins<S extends StateRecord = StateRecord> {
   prop<T>(name: string, defaultVal: T): T
   /** Fetch helper: CSRF header, JSON body, query params, typed errors. */
   fetch(url: string, options?: FetchOptions): Promise<unknown>
-  /** Publish an event on the global bus. */
-  emit(event: string, payload?: unknown): void
-  /** Subscribe to the global bus. Subscription is auto-removed on destroy(). */
-  on<T = unknown>(event: string, handler: EventHandler<T>): UnsubFn
+  /**
+   * Publish an event on the global bus.
+   * Payload is typed via the `MicraEvents` interface (augmentable).
+   */
+  emit<K extends string>(event: K, ...args: EmitArgs<K>): void
+  /**
+   * Subscribe to the global bus. Subscription is auto-removed on destroy().
+   * Handler payload is typed via the `MicraEvents` interface (augmentable).
+   */
+  on<K extends string>(event: K, handler: (payload: EventPayload<K>) => void): UnsubFn
 }
 
 /**
@@ -149,6 +202,9 @@ export interface MicraElement extends HTMLElement {
   __micraKey?: unknown      // keyed-diff key
   __micraEach?: true        // belongs to a no-key each list
   __micraScan?: ScanIndex   // single-pass scan result (cached after 1st render)
+  __micraItem?: StateRecord  // keyed row: last-rendered item ref (for skip check)
+  __micraIndex?: number      // keyed row: last-rendered index (for skip check)
+  _itemState?: StateRecord  // keyed row: reused itemState (avoids Object.create per render)
 }
 
 /**
@@ -166,7 +222,7 @@ export interface TrackedListener {
 export interface MicraTemplate extends HTMLTemplateElement {
   __micraMarker?: Comment
   __micraNodes: Map<unknown, MicraElement>
-  __micraList: ChildNode[]
+  __micraList: MicraElement[]
   __micraNoKeyWarned?: true
 }
 

package/src/utils/expr.ts

@@ -29,8 +29,15 @@ import type { StateRecord } from '../types'
 
 // LLM NOTE: exprCache is module-level (shared across all components).
 // This is intentional — most apps reuse the same expressions.
-type Compiled = (state: object, safe: object) => unknown
-const exprCache = new Map<string, Compiled>()
+
+// Compiled fn for complex expressions; pre-split parts for simple dot-paths.
+// Storing parts once avoids the SIMPLE_PATH regex test + split on every evalExpr call.
+type CompiledFn = (state: object, safe: object) => unknown
+type CachedEntry =
+  | { kind: 'fn';   fn:    CompiledFn }
+  | { kind: 'path'; parts: string[]   }
+
+const exprCache = new Map<string, CachedEntry>()
 // Expressions whose runtime error we have already warned about. Prevents log spam
 // when the same `data-text="item.naame"` typo fires every render.
 const warnedRuntime = new Set<string>()
@@ -141,32 +148,38 @@ function safeStateHas(state: object, key: PropertyKey): boolean {
  * evalExpr('price * qty', { price: 9.99, qty: 3 })   // → 29.97
  */
 export function evalExpr(expr: string, state: StateRecord): unknown {
+  let cached = exprCache.get(expr)
+
+  if (!cached) {
+    // Determine once whether this is a simple dot-path and cache the result.
+    if (SIMPLE_PATH.test(expr)) {
+      cached = { kind: 'path', parts: expr.split('.') }
+    } else {
+      try {
+        cached = {
+          kind: 'fn',
+          fn: new Function('$s', '$safe', `with($safe){with($s){return (${expr})}}`) as CompiledFn,
+        }
+      } catch {
+        warn(`invalid expression "${expr}"`)
+        cached = { kind: 'fn', fn: () => undefined }
+      }
+    }
+    exprCache.set(expr, cached)
+  }
+
   // Fast-path: simple property access — no Function() needed.
   // Still guarded so bare access to Object.prototype names returns undefined.
-  if (SIMPLE_PATH.test(expr)) {
-    const parts = expr.split('.')
-    if (!safeStateHas(state, parts[0]!)) return undefined
-    return parts.reduce<unknown>((obj, key) =>
-      obj != null ? (obj as StateRecord)[key] : undefined,
+  if (cached.kind === 'path') {
+    if (!safeStateHas(state, cached.parts[0]!)) return undefined
+    return cached.parts.reduce<unknown>(
+      (obj, key) => (obj != null ? (obj as StateRecord)[key] : undefined),
       state,
     )
   }
 
-  if (!exprCache.has(expr)) {
-    try {
-      // Two with() statements: $s wins for state keys; $safe shadows globals.
-      exprCache.set(
-        expr,
-        new Function('$s', '$safe', `with($safe){with($s){return (${expr})}}`) as Compiled,
-      )
-    } catch {
-      warn(`invalid expression "${expr}"`)
-      exprCache.set(expr, () => undefined)
-    }
-  }
-
   try {
-    return exprCache.get(expr)!(safeStateWrap(state), SAFE_OUTER)
+    return cached.fn(safeStateWrap(state), SAFE_OUTER)
   } catch (e) {
     if (!warnedRuntime.has(expr)) {
       warnedRuntime.add(expr)