micra.js 1.0.0

package/src/core/reactive.ts

@@ -0,0 +1,50 @@
+/**
+ * src/core/reactive.ts — Reactive state proxy and batch scheduler.
+ *
+ * Responsibilities:
+ *   - Wrap a plain state object in a Proxy that notifies on writes
+ *   - Batch multiple synchronous mutations into a single microtask render
+ *
+ * LLM NOTE: Both functions are PURE constructors — they have no side effects
+ * beyond setting up a Proxy / Promise chain. No DOM access here.
+ */
+
+import type { StateRecord } from '../types'
+
+/**
+ * Wrap `obj` in a shallow Proxy. Any property write calls `schedule()`.
+ * Arrays: replace, don't mutate — `state.items = [...state.items, x]`.
+ *
+ * @example
+ * const raw = { count: 0 }
+ * const state = createReactiveState(raw, render)
+ * state.count = 5  // triggers render() in next microtask
+ */
+export function createReactiveState<S extends StateRecord>(obj: S, schedule: () => void): S {
+  return new Proxy(obj, {
+    set(target, key: string, value: unknown) {
+      // Cast through StateRecord — TypeScript cannot write through a generic index
+      ;(target as StateRecord)[key] = value
+      schedule()
+      return true
+    },
+  })
+}
+
+/**
+ * Return a debounce function that defers `render` to the next microtask.
+ * Multiple calls within the same tick collapse to a single render.
+ *
+ * @example
+ * const schedule = createScheduler(render)
+ * schedule()  // defers render
+ * schedule()  // no-op — already pending
+ */
+export function createScheduler(render: () => void): () => void {
+  let pending = false
+  return function schedule() {
+    if (pending) return
+    pending = true
+    Promise.resolve().then(() => { pending = false; render() })
+  }
+}

package/src/core/registry.ts

@@ -0,0 +1,100 @@
+/**
+ * src/core/registry.ts — Component definition registry and instance store.
+ *
+ * Responsibilities:
+ *   - Store named component definitions (define / registry)
+ *   - Store live component instances keyed by root HTMLElement (instances)
+ *
+ * LLM NOTE: Both maps are module-level singletons (one per page load).
+ * They are intentionally mutable from mount.ts and start.ts.
+ */
+
+import type {
+  ComponentDefinition,
+  ComponentInstance,
+  InternalInstance,
+  StateRecord,
+} from '../types'
+
+// Named definition map — populated by define()
+export const _registry  = new Map<string, ComponentDefinition>()
+
+// Live instance map — populated by mount(), cleared by instance.destroy()
+export const _instances = new Map<HTMLElement, InternalInstance>()
+
+// ── Public accessors ──────────────────────────────────────────────────────────
+
+/**
+ * Register a component definition under `name`.
+ *
+ * @example
+ * define('counter', { state: { count: 0 }, inc() { this.state.count++ } })
+ */
+export function define<S extends StateRecord>(
+  name: string,
+  definition: ComponentDefinition<S>,
+): void {
+  _registry.set(name, definition as ComponentDefinition)
+}
+
+/**
+ * Type-helper — returns `definition` unchanged but lets TypeScript infer `S`
+ * from the `state` literal so all methods are typed with the correct `this`.
+ *
+ * Use this when defining a component outside a `define()` call.
+ *
+ * @example
+ * const counter = defineComponent({
+ *   state: { count: 0 },
+ *   increment() { this.state.count++ },  // this.state: { count: number } ✓
+ * })
+ * Micra.define('counter', counter)
+ */
+export function defineComponent<S extends StateRecord>(
+  definition: ComponentDefinition<S>,
+): ComponentDefinition<S> {
+  return definition
+}
+
+/**
+ * Returns a read-only view of all live instances (keyed by root element).
+ * Useful for DevTools / debugging.
+ */
+export function instances(): ReadonlyMap<HTMLElement, ComponentInstance> {
+  return _instances
+}
+
+/**
+ * Returns a read-only view of all registered component definitions.
+ * Useful for DevTools / debugging.
+ */
+export function registry(): ReadonlyMap<string, ComponentDefinition> {
+  return _registry
+}
+
+/**
+ * Print all live component instances to the browser console.
+ * Shows component name, root element, and current state for each instance.
+ *
+ * @example
+ * // In browser DevTools console:
+ * Micra.debug()
+ * // [Micra] 3 live component(s)
+ * //   counter   $el: <div>  state: { count: 5 }
+ * //   user-list $el: <div>  state: { users: [...], loading: false }
+ */
+export function debug(): void {
+  if (_instances.size === 0) {
+    console.log('[Micra] No live components.')
+    return
+  }
+  console.group(`[Micra] ${_instances.size} live component(s)`)
+  for (const [el, instance] of _instances) {
+    const name = el.getAttribute('data-component') ?? '(unnamed)'
+    console.group(`%c${name}`, 'font-weight:bold;color:#6366f1')
+    console.log('$el  ', el)
+    console.log('state', { ...instance.state })
+    console.groupEnd()
+  }
+  console.groupEnd()
+}

package/src/core/start.ts

@@ -0,0 +1,42 @@
+/**
+ * src/core/start.ts — Auto-mount via [data-component].
+ *
+ * Responsibilities:
+ *   - Scan the DOM (or a subtree) for [data-component] elements
+ *   - Mount each using the registered definition
+ *   - Skip already-mounted elements (safe to call multiple times)
+ *   - Warn clearly when a component name is not registered
+ *
+ * LLM NOTE: start() is SSR-friendly — calling it multiple times is safe
+ * because mount() checks _instances before re-mounting.
+ */
+
+import { warn } from '../utils/expr'
+import { _registry, _instances } from './registry'
+import { mount } from './mount'
+
+/**
+ * Scan for `[data-component]` elements and auto-mount registered definitions.
+ *
+ * Pass a subtree root to limit the scan (e.g., after a partial SSR update):
+ * `Micra.start(document.getElementById('panel'))`
+ *
+ * @example
+ * // Mount everything on the page (called once after DOM ready)
+ * Micra.start()
+ *
+ * // Re-mount after injecting new HTML
+ * Micra.start(document.querySelector('#dynamic-section'))
+ */
+export function start(root: Document | HTMLElement = document): void {
+  root.querySelectorAll<HTMLElement>('[data-component]').forEach(el => {
+    if (_instances.has(el)) return  // already mounted — skip
+    const name = el.getAttribute('data-component')!
+    const def  = _registry.get(name)
+    if (!def) {
+      warn(`component "${name}" not defined. Call Micra.define('${name}', {...}) first.`)
+      return
+    }
+    mount(el, def)
+  })
+}

package/src/dom/directives.ts

@@ -0,0 +1,207 @@
+/**
+ * src/dom/directives.ts — Apply DOM directives to a component subtree.
+ *
+ * Responsibilities:
+ *   - data-text, data-html, data-if, data-show, data-bind, data-model
+ *   - data-class (additive class toggling)
+ *   - Directive result cache (built once per element, reused on re-renders)
+ *
+ * LLM NOTE: applyDirectives() is called on every render. The directive cache
+ * (DirectiveCache on el.__micraCache) avoids repeated querySelectorAll on
+ * re-renders — cache is built lazily on the first call for each root element.
+ *
+ * Important: this module does NOT handle data-each — see dom/each.ts.
+ */
+
+import type {
+  CachedBinding,
+  DirectiveCache,
+  InternalInstance,
+  MicraElement,
+  StateRecord,
+} from '../types'
+import { evalExpr, warn } from '../utils/expr'
+import { queryOwn, queryAll } from './query'
+
+// ── Directive appliers ────────────────────────────────────────────────────────
+// Each function is PURE relative to state — reads state, writes DOM.
+
+function applyText(el: Element, expr: string, state: StateRecord): void {
+  const text = String(evalExpr(expr, state) ?? '')
+  if (el.textContent !== text) el.textContent = text
+}
+
+function applyHtml(el: Element, expr: string, state: StateRecord): void {
+  el.innerHTML = String(evalExpr(expr, state) ?? '')
+}
+
+function applyIf(el: Element, expr: string, state: StateRecord): void {
+  (el as HTMLElement).style.display = evalExpr(expr, state) ? '' : 'none'
+}
+
+function applyBind(el: Element, expr: string, state: StateRecord): void {
+  for (const pair of expr.split(',')) {
+    const colonIdx = pair.indexOf(':')
+    if (colonIdx === -1) continue
+    const attr    = pair.slice(0, colonIdx).trim()
+    const valExpr = pair.slice(colonIdx + 1).trim()
+    const val     = evalExpr(valExpr, state)
+
+    if (attr === 'class') {
+      (el as HTMLElement).className = String(val ?? '')
+    } else if (attr === 'value') {
+      if (document.activeElement !== el)
+        (el as HTMLInputElement).value = String(val ?? '')
+    } else if (attr === 'style') {
+      if (typeof val === 'object' && val !== null) {
+        Object.assign((el as HTMLElement).style, val)
+      } else {
+        el.setAttribute('style', String(val ?? ''))
+      }
+    } else if (typeof val === 'boolean') {
+      val ? el.setAttribute(attr, '') : el.removeAttribute(attr)
+    } else {
+      val == null ? el.removeAttribute(attr) : el.setAttribute(attr, String(val))
+    }
+  }
+}
+
+/**
+ * data-class="active:isActive, disabled:count === 0"
+ * Parses comma-separated `className:expression` pairs and toggles classes additively.
+ * Unlike data-bind="class:expr" this does NOT replace the full className.
+ *
+ * Syntax mirrors data-bind — split by comma, then by first colon.
+ *
+ * @example
+ * <div data-class="active:tab === 'home', hidden:!loaded">
+ */
+function applyClass(el: Element, expr: string, state: StateRecord): void {
+  for (const pair of expr.split(',')) {
+    const colonIdx = pair.indexOf(':')
+    if (colonIdx === -1) continue
+    const cls     = pair.slice(0, colonIdx).trim()
+    const valExpr = pair.slice(colonIdx + 1).trim()
+    if (!cls) continue
+    el.classList.toggle(cls, Boolean(evalExpr(valExpr, state)))
+  }
+}
+
+function applyModel(
+  el: Element,
+  key: string,
+  rawState: StateRecord,
+): void {
+  const html = el as HTMLInputElement
+  if (document.activeElement !== el) {
+    html.value = rawState[key] == null ? '' : String(rawState[key])
+  }
+  // listener is attached separately in events.ts — this only syncs the value
+}
+
+// ── Directive cache ───────────────────────────────────────────────────────────
+
+/** @internal Collect all directive bindings for a root element. Built once. */
+function buildCache(root: Element): DirectiveCache {
+  const pick = (attr: string): CachedBinding[] => {
+    const els = queryOwn(root, attr)
+    // Include root itself
+    if ((root as HTMLElement).hasAttribute?.(attr)) els.unshift(root)
+    return els
+      .filter(el => !el.closest('template'))
+      .map(el => ({ el, expr: el.getAttribute(attr)! }))
+  }
+  return {
+    text:  pick('data-text'),
+    html:  pick('data-html'),
+    if:    pick('data-if'),
+    show:  pick('data-show'),
+    bind:  pick('data-bind'),
+    model: pick('data-model'),
+    class: pick('data-class'),
+  }
+}
+
+// ── Main entry point ──────────────────────────────────────────────────────────
+
+/**
+ * Apply all non-each directives to a component subtree.
+ *
+ * For regular Elements: directive bindings are cached in `el.__micraCache`
+ * after the first call — subsequent re-renders skip querySelectorAll entirely.
+ *
+ * For DocumentFragments (no-key each clones): always re-scan because these
+ * fragments are new clones on every render.
+ *
+ * @param root     - Component root Element or DocumentFragment (no-key each clone)
+ * @param state    - Expression state (may include item/index for each rows)
+ * @param rawState - Raw (non-proxy) state for model sync
+ * @param instance - Component instance (unused here, kept for future hooks)
+ */
+export function applyDirectives<S extends StateRecord>(
+  root: Element | DocumentFragment,
+  state: StateRecord,
+  rawState: StateRecord,
+  _instance: InternalInstance<S>,
+): void {
+  // DocumentFragments are temporary clones — always scan, never cache
+  if (root.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+    applyFromList(buildFragmentList(root as DocumentFragment), state, rawState)
+    return
+  }
+
+  const el = root as MicraElement
+  if (!el.__micraCache) el.__micraCache = buildCache(el)
+  applyFromList(el.__micraCache, state, rawState)
+}
+
+/** @internal Apply a pre-built cache / binding list to current state. */
+function applyFromList(
+  cache: DirectiveCache,
+  state: StateRecord,
+  rawState: StateRecord,
+): void {
+  cache.text.forEach(b => applyText(b.el, b.expr, state))
+  cache.html.forEach(b => applyHtml(b.el, b.expr, state))
+  cache.if.forEach(b => applyIf(b.el, b.expr, state))
+  cache.show.forEach(b => applyIf(b.el, b.expr, state))
+  cache.bind.forEach(b => applyBind(b.el, b.expr, state))
+  cache.model.forEach(b => applyModel(b.el, b.expr.trim(), rawState))
+  cache.class.forEach(b => applyClass(b.el, b.expr, state))
+}
+
+/** @internal Scan a DocumentFragment (no-key each clone) — returns a DirectiveCache. */
+function buildFragmentList(frag: DocumentFragment): DirectiveCache {
+  const pick = (attr: string): CachedBinding[] =>
+    queryAll(frag, `[${attr}]`)
+      .filter(el => !el.closest('template'))
+      .map(el => ({ el, expr: el.getAttribute(attr)! }))
+  return {
+    text:  pick('data-text'),
+    html:  pick('data-html'),
+    if:    pick('data-if'),
+    show:  pick('data-show'),
+    bind:  pick('data-bind'),
+    model: pick('data-model'),
+    class: pick('data-class'),
+  }
+}
+
+// ── Dev warning helper ────────────────────────────────────────────────────────
+
+/**
+ * Validate directive usage and emit dev warnings.
+ * Called once after the initial render of a component.
+ *
+ * @internal
+ */
+export function validateDirectives(root: Element): void {
+  queryOwn(root, 'data-each').forEach(el => {
+    if (!el.hasAttribute('data-key')) {
+      warn(`data-each="${el.getAttribute('data-each')}" has no data-key — keyed diff disabled. Add data-key="id" for better performance.`)
+    }
+  })
+}
+
+// Re-export warn for use in other modules
+export { warn }

package/src/dom/each.ts

@@ -0,0 +1,167 @@
+/**
+ * src/dom/each.ts — Keyed and non-keyed list rendering (data-each).
+ *
+ * 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)
+ *   - Apply directives to each row with a scoped itemState
+ *
+ * LLM NOTE: renderList() is called on every render cycle AFTER applyDirectives().
+ * Only <template> elements with data-each are processed.
+ * 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.
+ */
+
+import type { InternalInstance, MicraElement, MicraTemplate, StateRecord } from '../types'
+import { evalExpr, warn } from '../utils/expr'
+import { applyDirectives } from './directives'
+import { bindDataOn, bindAtEvents } from './events'
+import { queryOwn, queryAll } from './query'
+
+/**
+ * Process all `<template data-each>` elements owned by `root`.
+ * Scoped itemState makes `item`, `index`, `$index` available in row expressions.
+ *
+ * @param root      - Component root Element
+ * @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)
+ */
+export function renderList<S extends StateRecord>(
+  root: Element,
+  state: StateRecord,
+  rawState: StateRecord,
+  instance: InternalInstance<S>,
+): void {
+  queryOwn(root, 'data-each').forEach(tmplEl => {
+    if (tmplEl.tagName !== 'TEMPLATE') return
+    const tmpl = tmplEl as MicraTemplate
+
+    const itemsExpr = tmpl.getAttribute('data-each')!
+    const keyAttr   = tmpl.getAttribute('data-key') ?? null
+    const items     = evalExpr(itemsExpr, state)
+
+    // Ensure marker comment + internal state are initialized
+    if (!tmpl.__micraMarker) {
+      const m = document.createComment(`each:${itemsExpr}`)
+      tmpl.after(m)
+      tmpl.__micraMarker = m
+      tmpl.__micraNodes  = new Map()
+      tmpl.__micraList   = []
+    }
+
+    const marker = tmpl.__micraMarker
+    const keyMap = tmpl.__micraNodes
+    const parent = marker.parentNode!
+
+    // Empty / non-array: clear all rendered rows
+    if (!Array.isArray(items)) {
+      tmpl.__micraList.forEach(n => n.remove())
+      tmpl.__micraList = []
+      keyMap.clear()
+      return
+    }
+
+    if (keyAttr) {
+      renderKeyed(tmpl, items as StateRecord[], keyAttr, marker, keyMap, parent, state, rawState, instance)
+    } else {
+      renderNoKey(tmpl, items as StateRecord[], marker, parent, state, rawState, instance)
+    }
+  })
+}
+
+// ── Keyed diff ────────────────────────────────────────────────────────────────
+
+function renderKeyed<S extends StateRecord>(
+  tmpl: MicraTemplate,
+  items: StateRecord[],
+  keyAttr: string,
+  marker: Comment,
+  keyMap: Map<unknown, MicraElement>,
+  parent: Node,
+  state: StateRecord,
+  rawState: StateRecord,
+  instance: InternalInstance<S>,
+): void {
+  const nextKeys  = new Set<unknown>()
+  const nextNodes: MicraElement[] = []
+
+  for (const [index, item] of items.entries()) {
+    const key = item[keyAttr]
+    if (key == null) warn(`data-key="${keyAttr}" is null/undefined on item at index ${index}`)
+    nextKeys.add(key)
+
+    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.__micraKey = key
+      keyMap.set(key, node)
+      // Bind data-on and @event handlers on the freshly created node (once)
+      bindDataOn(node, instance)
+      bindAtEvents(node, instance)
+    }
+
+    const itemState = Object.assign(
+      Object.create(state) as StateRecord,
+      { item, index, $index: index },
+    )
+    applyDirectives(node, itemState, rawState, instance)
+    nextNodes.push(node)
+  }
+
+  // Remove stale nodes
+  for (const [key, node] of keyMap) {
+    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
+  }
+
+  tmpl.__micraList = nextNodes
+}
+
+// ── Non-keyed (full re-render) ─────────────────────────────────────────────────
+
+function renderNoKey<S extends StateRecord>(
+  tmpl: MicraTemplate,
+  items: StateRecord[],
+  marker: Comment,
+  parent: Node,
+  state: StateRecord,
+  rawState: StateRecord,
+  instance: InternalInstance<S>,
+): void {
+  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) as DocumentFragment
+    const itemState = Object.assign(
+      Object.create(state) as StateRecord,
+      { item, index, $index: index },
+    )
+    applyDirectives(clone, itemState, rawState, instance)
+    bindDataOn(clone as unknown as Element, instance)
+    bindAtEvents(clone as unknown as Element, instance)
+
+    const nodes = Array.from(clone.childNodes) as MicraElement[]
+    nodes.forEach(n => { n.__micraEach = true; frag.append(n) })
+    tmpl.__micraList.push(...nodes)
+  }
+  parent.insertBefore(frag, marker.nextSibling)
+}