micra.js 2.1.0 → 2.2.1

package/src/dom/scan.ts

@@ -0,0 +1,189 @@
+/**
+ * src/dom/scan.ts — Single-pass directive/event/ref scanner.
+ *
+ * Replaces 10+ querySelectorAll calls per render with ONE TreeWalker
+ * 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.
+ *   - <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.
+ *
+ * Hot-path notes:
+ *   - We read `el.attributes` once and switch by suffix. No allocations per
+ *     non-matching attr.
+ *   - Pair-parsing (`data-bind`, `data-class`) happens here, once, at scan
+ *     time. Reused on every render.
+ */
+
+import type { CachedIfBinding, CachedPairBinding, ScanIndex } from "../types";
+
+function emptyScan(): ScanIndex {
+  return {
+    text: [],
+    html: [],
+    if: [],
+    show: [],
+    bind: [],
+    model: [],
+    class: [],
+    each: [],
+    on: [],
+    atEvents: [],
+    refs: [],
+  };
+}
+
+/** @internal Parse `name:expr, name2:expr2` once at scan time. */
+function parsePairs(expr: string): Array<readonly [string, string]> {
+  const out: Array<readonly [string, string]> = [];
+  for (const part of expr.split(",")) {
+    const colon = part.indexOf(":");
+    if (colon === -1) continue;
+    const left = part.slice(0, colon).trim();
+    const right = part.slice(colon + 1).trim();
+    if (!left) continue;
+    out.push([left, right]);
+  }
+  return out;
+}
+
+/** @internal Classify every relevant attribute on one element. */
+function classify(el: Element, scan: ScanIndex): void {
+  // <template data-each> is the only directive we permit on a <template>.
+  // Other directives on a <template> would be meaningless (the content lives
+  // in template.content, not template.children).
+  if (el.tagName === "TEMPLATE") {
+    if (el.hasAttribute("data-each")) scan.each.push(el);
+    return;
+  }
+
+  const attrs = el.attributes;
+  let atEventSeen = false;
+
+  for (let i = 0; i < attrs.length; i++) {
+    const a = attrs[i]!;
+    const name = a.name;
+
+    // Fast path: most attribute names aren't ours. First-char check rejects
+    // the common case (id, class, style, href, …) without a string compare.
+    const first = name.charCodeAt(0);
+
+    if (first === 64 /* '@' */) {
+      // @event="method" or @event.modifier="method"
+      if (!atEventSeen) {
+        scan.atEvents.push(el);
+        atEventSeen = true;
+      }
+      continue;
+    }
+
+    // data-X attributes
+    if (
+      first === 100 /* d */ &&
+      name.length >= 6 &&
+      name.charCodeAt(4) === 45 /* '-' */
+    ) {
+      // 'data-' prefix
+      const rest = name.slice(5);
+      switch (rest) {
+        case "text":
+          scan.text.push({ el, expr: a.value });
+          break;
+        case "html":
+          scan.html.push({ el, expr: a.value });
+          break;
+        case "if":
+          scan.if.push({ el, expr: a.value } as CachedIfBinding);
+          break;
+        case "show":
+          scan.show.push({ el, expr: a.value });
+          break;
+        case "bind": {
+          const pairs = parsePairs(a.value);
+          scan.bind.push({ el, expr: a.value, pairs } as CachedPairBinding);
+          break;
+        }
+        case "model":
+          scan.model.push({ el, expr: a.value });
+          break;
+        case "class": {
+          const pairs = parsePairs(a.value);
+          scan.class.push({ el, expr: a.value, pairs } as CachedPairBinding);
+          break;
+        }
+        case "on":
+          scan.on.push(el);
+          break;
+        case "ref":
+          scan.refs.push(el);
+          break;
+        // data-key, data-each, data-component, data-* user attrs — ignored here
+      }
+    }
+  }
+}
+
+/** @internal Shared filter: stop descending into nested components. */
+const NESTED_COMPONENT_FILTER: NodeFilter = {
+  acceptNode(node: Node): number {
+    if ((node as Element).hasAttribute("data-component"))
+      return NodeFilter.FILTER_REJECT;
+    return NodeFilter.FILTER_ACCEPT;
+  },
+};
+
+/**
+ * Scan an Element subtree owned by one component. Skips nested
+ * [data-component] subtrees entirely. Visits the root itself.
+ *
+ * Cached on `el.__micraScan` after the first call — subsequent renders
+ * are free.
+ */
+export function scanComponent(root: Element): ScanIndex {
+  const scan = emptyScan();
+
+  // Always classify root itself first — the TreeWalker's filter would
+  // REJECT it if it had `data-component` (which it normally does for a
+  // mounted component). The filter is for *descendants*.
+  classify(root, scan);
+
+  const walker = document.createTreeWalker(
+    root,
+    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;
+}
+
+/**
+ * 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

@@ -28,6 +28,8 @@ export type {
   UnsubFn,
   EventHandler,
   FetchOptions,
+  ComponentMethods,
+  ComponentBuiltins,
   ComponentInstance,
   ComponentDefinition,
 } from './types'

package/src/types.ts

@@ -32,14 +32,23 @@ export interface FetchOptions {
 }
 
 /**
- * The `this` context inside component methods and lifecycle hooks.
- * `S` is inferred from the component's `state` object.
+ * User-defined methods on a component definition. Any function-shaped property
+ * other than `state`, `onCreate`, `onDestroy` is treated as a method.
  *
- * @example
- * // state: { count: 0 } → S = { count: number }
- * increment() { this.state.count++ }  // count is number ✓
+ * LLM NOTE: this type is used as a structural HINT only — `M` in
+ * ComponentDefinition is unconstrained so TS can infer it from the literal
+ * without rejecting non-function siblings like `state`. The `[key: string]`
+ * shape here just documents intent.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ComponentMethods = Record<string, (...args: any[]) => any>
+
+/**
+ * Built-in slots every instance gets: state, refs, $el, and the methods Micra
+ * itself injects (render, destroy, prop, fetch, emit, on). Kept separate from
+ * `M` so user methods can't accidentally shadow these names.
  */
-export interface ComponentInstance<S extends StateRecord = StateRecord> {
+export interface ComponentBuiltins<S extends StateRecord = StateRecord> {
   /** The root DOM element this component is mounted on. */
   readonly $el: HTMLElement
   /** Reactive state — any assignment triggers a batched re-render. */
@@ -68,11 +77,40 @@ export interface ComponentInstance<S extends StateRecord = StateRecord> {
   on<T = unknown>(event: string, handler: EventHandler<T>): UnsubFn
 }
 
+/**
+ * The `this` context inside component methods and lifecycle hooks.
+ * `S` is inferred from the component's `state` object; `M` is inferred from
+ * the methods on the same definition object. Both `this.state.X` and
+ * `this.someMethod()` are fully typed inside method bodies.
+ *
+ * @example
+ * Micra.define('counter', {
+ *   state: { count: 0 },
+ *   inc() {
+ *     this.state.count++   // this.state.count: number ✓
+ *     this.dec()           // this.dec: () => void ✓
+ *     // this.foo()        // ❌ Property 'foo' does not exist
+ *   },
+ *   dec() { this.state.count-- },
+ * })
+ */
+export type ComponentInstance<
+  S extends StateRecord = StateRecord,
+  M = ComponentMethods,
+> = ComponentBuiltins<S> & M
+
 /**
  * Component definition passed to `Micra.define` or `Micra.mount`.
  *
- * `S` is inferred from the `state` property — all methods receive
- * `this: ComponentInstance<S>` automatically via `ThisType<>`.
+ * Both `S` (state shape) and `M` (method set) are inferred from the literal.
+ * All methods and lifecycle hooks receive `this: ComponentInstance<S, M>` via
+ * `ThisType<>` — so `this.state.X` and `this.someMethod()` are both typed.
+ *
+ * LLM NOTE: `M` is intentionally unconstrained here. A constraint like
+ * `M extends ComponentMethods` would force every property in the literal to
+ * be a function — which would reject `state`. Without the constraint, TS
+ * structurally infers `M` as "everything in the literal except the known
+ * lifecycle/state keys", which is exactly what we want.
  *
  * @example
  * Micra.define('counter', {
@@ -80,21 +118,23 @@ export interface ComponentInstance<S extends StateRecord = StateRecord> {
  *   inc() { this.state.count++ },  // this.state.count: number ✓
  * })
  */
-export type ComponentDefinition<S extends StateRecord = StateRecord> = {
+export type ComponentDefinition<
+  S extends StateRecord = StateRecord,
+  M = ComponentMethods,
+> = {
   /** Initial flat state. Becomes reactive on mount. */
   state?: S
   /**
    * Called once after mount in a microtask — safe for async data fetching.
    * @example async onCreate() { this.state.data = await this.fetch('/api/data') }
    */
-  onCreate?: () => void | Promise<void>
+  onCreate?(): void | Promise<void>
   /**
    * Called on destroy — clean up DOM listeners, timers, etc.
    * Event bus subscriptions added via `this.on()` are cleaned up automatically.
    */
-  onDestroy?: () => void
-  [method: string]: unknown
-} & ThisType<ComponentInstance<S>>
+  onDestroy?(): void
+} & M & ThisType<ComponentInstance<S, M>>
 
 // ── Internal types ────────────────────────────────────────────────────────────
 // These are NOT exported from src/index.ts.
@@ -108,7 +148,10 @@ export interface MicraElement extends HTMLElement {
   __micraAtBound?: true     // @event shorthand bound (per-element)
   __micraKey?: unknown      // keyed-diff key
   __micraEach?: true        // belongs to a no-key each list
-  __micraCache?: DirectiveCache  // cached directive scan result
+  __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)
 }
 
 /**
@@ -126,7 +169,7 @@ export interface TrackedListener {
 export interface MicraTemplate extends HTMLTemplateElement {
   __micraMarker?: Comment
   __micraNodes: Map<unknown, MicraElement>
-  __micraList: ChildNode[]
+  __micraList: MicraElement[]
   __micraNoKeyWarned?: true
 }
 
@@ -159,13 +202,16 @@ export interface CachedPairBinding {
 }
 
 /**
- * @internal Directive scan result — built once per Element, reused every render.
- * This is the core of the performance optimization.
+ * @internal Single-pass scan result — built once per Element via one TreeWalker
+ * traversal, reused every render. This is the core of the performance
+ * optimization: instead of 10+ querySelectorAll calls per render, the scanner
+ * classifies every directive/event/ref attribute in a single DOM walk.
  *
- * LLM NOTE: DirectiveCache is built lazily on first render and stored on the
- * element. It avoids repeated querySelectorAll calls on every re-render.
+ * LLM NOTE: ScanIndex is built lazily on first render and stored on
+ * `el.__micraScan`. Subsequent renders skip the scan entirely.
  */
-export interface DirectiveCache {
+export interface ScanIndex {
+  // Directives — applied on every render
   text:  CachedBinding[]
   html:  CachedBinding[]
   if:    CachedIfBinding[]
@@ -173,15 +219,27 @@ export interface DirectiveCache {
   bind:  CachedPairBinding[]
   model: CachedBinding[]
   class: CachedPairBinding[]
+  // Lists — <template data-each>
+  each:  Element[]
+  // Events — bound once per element
+  on:    Element[]          // [data-on]
+  atEvents: Element[]       // any element with at least one @-prefixed attribute
+  // Refs — collected into instance.refs every render
+  refs:  Element[]          // [data-ref]
 }
 
 /**
  * @internal Full instance as seen inside the runtime — extends the public
- * interface with private bookkeeping slots and an index signature for
+ * built-ins with private bookkeeping slots and an index signature for
  * dynamic method dispatch.
+ *
+ * Note: internally we don't carry the user-method generic `M`. Internal modules
+ * dispatch methods by string name (`instance[methodName]()`), which is what
+ * the index signature is for. The public `mount()` return value re-projects
+ * to `ComponentInstance<S, M>` so callers get full type inference.
  */
 export interface InternalInstance<S extends StateRecord = StateRecord>
-  extends ComponentInstance<S> {
+  extends ComponentBuiltins<S> {
   __micraSubs?: UnsubFn[]
   __micraListeners?: TrackedListener[]
   __micraDestroyed?: 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)