micra.js 1.0.0 → 1.1.0

package/src/dom/directives.ts

@@ -15,9 +15,11 @@
 
 import type {
   CachedBinding,
+  CachedPairBinding,
   DirectiveCache,
   InternalInstance,
   MicraElement,
+  MicraTemplate,
   StateRecord,
 } from '../types'
 import { evalExpr, warn } from '../utils/expr'
@@ -31,6 +33,13 @@ function applyText(el: Element, expr: string, state: StateRecord): void {
   if (el.textContent !== text) el.textContent = text
 }
 
+/**
+ * data-html — writes the expression value as innerHTML.
+ *
+ * ⚠️ XSS WARNING: the value is rendered as raw HTML. Never bind untrusted
+ * input here — use `data-text` (textContent) instead. See docs/directives.md
+ * for the full security model.
+ */
 function applyHtml(el: Element, expr: string, state: StateRecord): void {
   el.innerHTML = String(evalExpr(expr, state) ?? '')
 }
@@ -39,13 +48,13 @@ 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)
+function applyBind(
+  el: Element,
+  pairs: ReadonlyArray<readonly [string, string]>,
+  state: StateRecord,
+): void {
+  for (const [attr, valExpr] of pairs) {
+    const val = evalExpr(valExpr, state)
 
     if (attr === 'class') {
       (el as HTMLElement).className = String(val ?? '')
@@ -76,26 +85,42 @@ function applyBind(el: Element, expr: string, state: StateRecord): void {
  * @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
+function applyClass(
+  el: Element,
+  pairs: ReadonlyArray<readonly [string, string]>,
+  state: StateRecord,
+): void {
+  for (const [cls, valExpr] of pairs) {
     el.classList.toggle(cls, Boolean(evalExpr(valExpr, state)))
   }
 }
 
+/** @internal Parse a comma+colon spec like `href:url, disabled:loading` once. */
+function parsePairs(expr: string): Array<readonly [string, string]> {
+  const out: Array<readonly [string, string]> = []
+  for (const part of expr.split(',')) {
+    const colonIdx = part.indexOf(':')
+    if (colonIdx === -1) continue
+    const left  = part.slice(0, colonIdx).trim()
+    const right = part.slice(colonIdx + 1).trim()
+    if (!left) continue
+    out.push([left, right])
+  }
+  return out
+}
+
 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])
-  }
+  const stateVal = rawState[key]
+  const desired = stateVal == null ? '' : String(stateVal)
+  // Only write when out of sync. This is a no-op during live typing (the input
+  // event already drove state to match el.value) but still propagates
+  // programmatic resets such as `this.state.q = ''` on focused inputs.
+  if (html.value !== desired) html.value = desired
   // listener is attached separately in events.ts — this only syncs the value
 }
 
@@ -111,14 +136,16 @@ function buildCache(root: Element): DirectiveCache {
       .filter(el => !el.closest('template'))
       .map(el => ({ el, expr: el.getAttribute(attr)! }))
   }
+  const pickPairs = (attr: string): CachedPairBinding[] =>
+    pick(attr).map(b => ({ ...b, pairs: parsePairs(b.expr) }))
   return {
     text:  pick('data-text'),
     html:  pick('data-html'),
     if:    pick('data-if'),
     show:  pick('data-show'),
-    bind:  pick('data-bind'),
+    bind:  pickPairs('data-bind'),
     model: pick('data-model'),
-    class: pick('data-class'),
+    class: pickPairs('data-class'),
   }
 }
 
@@ -165,9 +192,9 @@ function applyFromList(
   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.bind.forEach(b => applyBind(b.el, b.pairs, state))
   cache.model.forEach(b => applyModel(b.el, b.expr.trim(), rawState))
-  cache.class.forEach(b => applyClass(b.el, b.expr, state))
+  cache.class.forEach(b => applyClass(b.el, b.pairs, state))
 }
 
 /** @internal Scan a DocumentFragment (no-key each clone) — returns a DirectiveCache. */
@@ -176,14 +203,16 @@ function buildFragmentList(frag: DocumentFragment): DirectiveCache {
     queryAll(frag, `[${attr}]`)
       .filter(el => !el.closest('template'))
       .map(el => ({ el, expr: el.getAttribute(attr)! }))
+  const pickPairs = (attr: string): CachedPairBinding[] =>
+    pick(attr).map(b => ({ ...b, pairs: parsePairs(b.expr) }))
   return {
     text:  pick('data-text'),
     html:  pick('data-html'),
     if:    pick('data-if'),
     show:  pick('data-show'),
-    bind:  pick('data-bind'),
+    bind:  pickPairs('data-bind'),
     model: pick('data-model'),
-    class: pick('data-class'),
+    class: pickPairs('data-class'),
   }
 }
 
@@ -197,10 +226,24 @@ function buildFragmentList(frag: DocumentFragment): DirectiveCache {
  */
 export function validateDirectives(root: Element): void {
   queryOwn(root, 'data-each').forEach(el => {
-    if (!el.hasAttribute('data-key')) {
+    const tmpl = el as MicraTemplate
+    if (!el.hasAttribute('data-key') && !tmpl.__micraNoKeyWarned) {
+      tmpl.__micraNoKeyWarned = true
       warn(`data-each="${el.getAttribute('data-each')}" has no data-key — keyed diff disabled. Add data-key="id" for better performance.`)
     }
   })
+
+  // data-bind="class:..." replaces className wholesale, which fights with
+  // data-class on the same element. Warn so the developer picks one.
+  const bindEls = queryOwn(root, 'data-bind')
+  if ((root as HTMLElement).hasAttribute?.('data-bind') && !bindEls.includes(root)) bindEls.unshift(root)
+  for (const el of bindEls) {
+    const spec = el.getAttribute('data-bind') ?? ''
+    const hasClassBind = spec.split(',').some(p => p.trim().split(':')[0]?.trim() === 'class')
+    if (hasClassBind && el.hasAttribute('data-class')) {
+      warn(`element has both data-bind="class:..." and data-class — they fight on every render. Use one.`)
+    }
+  }
 }
 
 // Re-export warn for use in other modules

package/src/dom/each.ts

@@ -86,10 +86,19 @@ function renderKeyed<S extends StateRecord>(
 ): void {
   const nextKeys  = new Set<unknown>()
   const nextNodes: MicraElement[] = []
+  let warnedNullKey = false
+  let warnedDupKey  = false
 
   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}`)
+    if (key == null && !warnedNullKey) {
+      warn(`data-key="${keyAttr}" is null/undefined on item at index ${index}`)
+      warnedNullKey = true
+    }
+    if (nextKeys.has(key) && !warnedDupKey) {
+      warn(`data-key="${keyAttr}" has duplicate value ${JSON.stringify(key)} — rows will collide`)
+      warnedDupKey = true
+    }
     nextKeys.add(key)
 
     let node = keyMap.get(key) as MicraElement | undefined

package/src/dom/events.ts

@@ -3,16 +3,29 @@
  *
  * Responsibilities:
  *   - Bind `data-on="event:method"` listeners (once per element)
- *   - Bind `@event="method"` shorthand (scanned once per component root)
+ *   - Bind `@event="method"` shorthand (once per element)
+ *   - Bind `data-model` two-way input listeners (once per element)
  *
- * LLM NOTE: Listeners are attached exactly once. The `__micraEvents` and
- * `__micraAtScanned` flags prevent duplicate bindings on re-renders.
+ * LLM NOTE: Every listener attached here is also recorded in
+ * instance.__micraListeners so destroy() can remove it cleanly.
+ * Re-render skips already-bound elements via per-element __micra* flags.
  */
 
 import type { InternalInstance, MicraElement, StateRecord } from '../types'
-import { evalExpr, warn } from '../utils/expr'
+import { warn } from '../utils/expr'
 import { queryOwn, queryAll } from './query'
 
+/** @internal Attach a DOM listener and track it on the instance for destroy(). */
+function track<S extends StateRecord>(
+  instance: InternalInstance<S>,
+  el: Element,
+  type: string,
+  fn: EventListener,
+): void {
+  el.addEventListener(type, fn)
+  ;(instance.__micraListeners ??= []).push({ el, type, fn })
+}
+
 // ── data-on ───────────────────────────────────────────────────────────────────
 
 /**
@@ -50,7 +63,7 @@ export function bindDataOn<S extends StateRecord>(
 
       const [evName, ...mods] = evSpec.split('.')
 
-      el.addEventListener(evName!, (e: Event) => {
+      track(instance, el, evName!, (e: Event) => {
         if (mods.includes('prevent')) e.preventDefault()
         if (mods.includes('stop')) e.stopPropagation()
         if (mods.includes('self') && e.target !== el) return
@@ -67,7 +80,7 @@ export function bindDataOn<S extends StateRecord>(
 
 /**
  * Bind `@event="method"` shorthand attributes (Stimulus-style).
- * Scanned once per component root (guarded by `__micraAtScanned`).
+ * Bound once per element via `__micraAtBound` — re-renders are no-ops.
  * Supports the same modifiers as data-on: `@click.prevent="submit"`.
  *
  * @example
@@ -78,18 +91,25 @@ export function bindAtEvents<S extends StateRecord>(
   root: Element,
   instance: InternalInstance<S>,
 ): void {
-  const mRoot = root as MicraElement
-  if (mRoot.__micraAtScanned) return
-  mRoot.__micraAtScanned = true
+  const isFragment = root.nodeType === 11
+  const all = isFragment
+    ? queryAll(root as unknown as ParentNode, '*')
+    : queryAll(root, '*')
+
+  // Include root itself for the regular-element case
+  if (!isFragment && !all.includes(root)) all.unshift(root)
 
-  const all = queryAll(root, '*')
   for (const el of all) {
+    const mEl = el as MicraElement
+    if (mEl.__micraAtBound) continue
+
+    let bound = false
     for (const attr of Array.from(el.attributes)) {
       if (!attr.name.startsWith('@')) continue
       const [evSpec, ...rest] = attr.name.slice(1).split('.')
       const method = attr.value.trim()
 
-      el.addEventListener(evSpec!, (e: Event) => {
+      track(instance, el, evSpec!, (e: Event) => {
         if (rest.includes('prevent')) e.preventDefault()
         if (rest.includes('stop')) e.stopPropagation()
         if (rest.includes('self') && e.target !== el) return
@@ -98,7 +118,9 @@ export function bindAtEvents<S extends StateRecord>(
         if (typeof fn === 'function') (fn as (e: Event) => void).call(instance, e)
         else warn(`method "${method}" not found`)
       })
+      bound = true
     }
+    if (bound) mEl.__micraAtBound = true
   }
 }
 
@@ -108,6 +130,9 @@ export function bindAtEvents<S extends StateRecord>(
  * Two-way binding: `data-model="key"` wires <input>/<select>/<textarea>
  * to `state[key]`. Binding is attached once per element.
  *
+ * Numeric inputs (`type="number"` / `type="range"`) write numbers, not strings.
+ * Checkbox inputs write booleans. Everything else writes strings.
+ *
  * @example
  * <input data-model="search">   // updates state.search on every keystroke
  * <select data-model="sortBy">  // updates state.sortBy on change
@@ -128,18 +153,23 @@ export function bindModels<S extends StateRecord>(
 
     const key = (el as HTMLInputElement).dataset['model'] ?? ''
     const tag = el.tagName
+    const inputEl = el as HTMLInputElement
+    const inputType = inputEl.type
 
     const update = () => {
-      const val = tag === 'INPUT' && (el as HTMLInputElement).type === 'checkbox'
-        ? (el as HTMLInputElement).checked
-        : (el as HTMLInputElement).value
+      let val: unknown
+      if (tag === 'INPUT' && inputType === 'checkbox') {
+        val = inputEl.checked
+      } else if (tag === 'INPUT' && (inputType === 'number' || inputType === 'range')) {
+        // Empty string → NaN; preserve raw empty as null so state stays "unfilled"
+        val = inputEl.value === '' ? null : inputEl.valueAsNumber
+      } else {
+        val = inputEl.value
+      }
       ;(instance.state as StateRecord)[key] = val
     }
 
-    el.addEventListener(tag === 'SELECT' || (el as HTMLInputElement).type === 'radio'
-      ? 'change'
-      : 'input',
-      update,
-    )
+    const evType = tag === 'SELECT' || inputType === 'radio' ? 'change' : 'input'
+    track(instance, el, evType, update)
   }
 }

package/src/types.ts

@@ -105,12 +105,21 @@ export type ComponentDefinition<S extends StateRecord = StateRecord> = {
 export interface MicraElement extends HTMLElement {
   __micraModel?: true       // data-model listener bound
   __micraEvents?: true      // data-on listeners bound
-  __micraAtScanned?: true   // @event shorthand scanned (set on component root)
+  __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
 }
 
+/**
+ * @internal A DOM listener tracked for cleanup on destroy().
+ */
+export interface TrackedListener {
+  el: Element
+  type: string
+  fn: EventListener
+}
+
 /**
  * @internal Extended HTMLTemplateElement with keyed-diff state.
  */
@@ -118,6 +127,7 @@ export interface MicraTemplate extends HTMLTemplateElement {
   __micraMarker?: Comment
   __micraNodes: Map<unknown, MicraElement>
   __micraList: ChildNode[]
+  __micraNoKeyWarned?: true
 }
 
 /**
@@ -128,6 +138,17 @@ export interface CachedBinding {
   expr: string
 }
 
+/**
+ * @internal Per-element directive binding with pre-parsed pairs.
+ * Used by `data-bind` and `data-class` — both share the
+ * `name:expression[, name:expression…]` syntax.
+ */
+export interface CachedPairBinding {
+  el: Element
+  expr: string
+  pairs: ReadonlyArray<readonly [string, string]>
+}
+
 /**
  * @internal Directive scan result — built once per Element, reused every render.
  * This is the core of the performance optimization.
@@ -140,9 +161,9 @@ export interface DirectiveCache {
   html:  CachedBinding[]
   if:    CachedBinding[]
   show:  CachedBinding[]
-  bind:  CachedBinding[]
+  bind:  CachedPairBinding[]
   model: CachedBinding[]
-  class: CachedBinding[]
+  class: CachedPairBinding[]
 }
 
 /**
@@ -153,5 +174,7 @@ export interface DirectiveCache {
 export interface InternalInstance<S extends StateRecord = StateRecord>
   extends ComponentInstance<S> {
   __micraSubs?: UnsubFn[]
+  __micraListeners?: TrackedListener[]
+  __micraDestroyed?: true
   [key: string]: unknown
 }

package/src/utils/expr.ts

@@ -5,9 +5,20 @@
  *   - Compile expression strings into cached functions
  *   - Evaluate them against a state object
  *   - Fast-path for simple property lookups
+ *   - Shadow non-state identifiers so directive expressions cannot reach
+ *     globals like `window`, `fetch`, `constructor`, etc. A small whitelist
+ *     of utility globals (Math, JSON, Date, ...) remains accessible.
  *
  * LLM NOTE: This module is PURE. It does not touch the DOM or mutate state.
- * All side effects are isolated to console.warn on invalid expressions.
+ *
+ * Security model:
+ *   Directive expressions are JavaScript — they are compiled via `new Function`
+ *   and run with full JS capability except that bare identifiers must resolve
+ *   to either a state key, a component instance method, or one of
+ *   ALLOWED_GLOBALS. This blocks the `constructor.constructor("...")()` chain
+ *   and accidental access to `window` / `document` / `fetch`. It does NOT
+ *   sandbox method calls — if a component method itself touches `window`,
+ *   that still works. Treat directive templates as trusted code regardless.
  */
 
 import type { StateRecord } from '../types'
@@ -18,12 +29,105 @@ import type { StateRecord } from '../types'
 
 // LLM NOTE: exprCache is module-level (shared across all components).
 // This is intentional — most apps reuse the same expressions.
-const exprCache = new Map<string, (state: StateRecord) => unknown>()
+type Compiled = (state: object, safe: object) => unknown
+const exprCache = new Map<string, Compiled>()
+// 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>()
 
 // Simple identifier or dot-path: "count", "user.name", "item.email"
 // Matches: letter/$/_ followed by word chars, optionally with .property chains
 const SIMPLE_PATH = /^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$/
 
+// ── Safe scope ────────────────────────────────────────────────────────────────
+
+/**
+ * Globals reachable from directive expressions. Anything else (window, fetch,
+ * constructor, eval, ...) is shadowed by SAFE_OUTER and resolves to undefined.
+ */
+const ALLOWED_GLOBALS = new Set<string>([
+  'Math', 'JSON', 'Date', 'String', 'Number', 'Boolean', 'Array', 'Object',
+  'parseInt', 'parseFloat', 'isNaN', 'isFinite', 'NaN', 'Infinity', 'undefined',
+])
+
+/**
+ * Outer `with()` scope. Its `has` trap claims every non-whitelisted identifier
+ * is "in scope" so the JS engine resolves the read on this Proxy (which returns
+ * undefined) instead of walking up to the global object. Whitelisted names fall
+ * through to globalThis.
+ */
+// Sentinel parameter names used by the compiled function. SAFE_OUTER must NOT
+// shadow them, or `with($s)` would resolve to `undefined` via SAFE_OUTER.
+const PARAM_S = '$s'
+const PARAM_SAFE = '$safe'
+
+const SAFE_OUTER: object = new Proxy(Object.create(null) as object, {
+  has(_target, key): boolean {
+    if (typeof key !== 'string') return false
+    if (key === PARAM_S || key === PARAM_SAFE) return false
+    return !ALLOWED_GLOBALS.has(key)
+  },
+  get(): undefined {
+    return undefined
+  },
+})
+
+/**
+ * @internal Per-state safe wrappers — one per source state object. WeakMap so
+ * short-lived itemStates get GC'd with their wrappers.
+ */
+const safeWrapCache = new WeakMap<object, object>()
+
+/**
+ * @internal Pre-computed names that live on `Object.prototype`
+ * (constructor, toString, hasOwnProperty, ...). Used by safeStateHas to detect
+ * built-in keys without re-walking the chain on every call.
+ */
+const OBJ_PROTO_KEYS = new Set<string>(Object.getOwnPropertyNames(Object.prototype))
+
+/**
+ * Wrap a state object so its `has` trap reports only "real" keys — own
+ * properties or keys reachable up to (but not including) `Object.prototype`.
+ * This blocks `'constructor' in state` from leaking the prototype.
+ */
+function safeStateWrap(state: object): object {
+  const cached = safeWrapCache.get(state)
+  if (cached) return cached
+  const wrapped = new Proxy(state, {
+    has(target, key) {
+      return safeStateHas(target, key)
+    },
+    get(target, key) {
+      return Reflect.get(target, key)
+    },
+  })
+  safeWrapCache.set(state, wrapped)
+  return wrapped
+}
+
+/**
+ * Return true iff `key` is reachable on `state` without walking into
+ * `Object.prototype`. Works for plain objects, prototype-chained objects, and
+ * Proxies with their own `has` trap.
+ */
+function safeStateHas(state: object, key: PropertyKey): boolean {
+  if (typeof key !== 'string') return false
+  if (!Reflect.has(state, key)) return false
+  // Identifiers that are NOT on Object.prototype are always safe — accept them
+  // immediately without walking the chain.
+  if (!OBJ_PROTO_KEYS.has(key)) return true
+  // Built-in Object.prototype names (constructor, toString, hasOwnProperty, ...)
+  // are only accepted when they have been explicitly placed on the state chain.
+  let obj: object | null = state
+  while (obj && obj !== Object.prototype) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) return true
+    obj = Object.getPrototypeOf(obj) as object | null
+  }
+  return false
+}
+
+// ── evalExpr ──────────────────────────────────────────────────────────────────
+
 /**
  * Evaluate a JS expression string against a state object.
  *
@@ -37,9 +141,12 @@ const SIMPLE_PATH = /^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$/
  * evalExpr('price * qty', { price: 9.99, qty: 3 })   // → 29.97
  */
 export function evalExpr(expr: string, state: StateRecord): unknown {
-  // Fast-path: simple property access — no Function() needed
+  // Fast-path: simple property access — no Function() needed.
+  // Still guarded so bare access to Object.prototype names returns undefined.
   if (SIMPLE_PATH.test(expr)) {
-    return expr.split('.').reduce<unknown>((obj, key) =>
+    const parts = expr.split('.')
+    if (!safeStateHas(state, parts[0]!)) return undefined
+    return parts.reduce<unknown>((obj, key) =>
       obj != null ? (obj as StateRecord)[key] : undefined,
       state,
     )
@@ -47,9 +154,10 @@ export function evalExpr(expr: string, state: StateRecord): unknown {
 
   if (!exprCache.has(expr)) {
     try {
+      // Two with() statements: $s wins for state keys; $safe shadows globals.
       exprCache.set(
         expr,
-        new Function('$s', `with($s){return (${expr})}`) as (s: StateRecord) => unknown,
+        new Function('$s', '$safe', `with($safe){with($s){return (${expr})}}`) as Compiled,
       )
     } catch {
       warn(`invalid expression "${expr}"`)
@@ -58,8 +166,12 @@ export function evalExpr(expr: string, state: StateRecord): unknown {
   }
 
   try {
-    return exprCache.get(expr)!(state)
-  } catch {
+    return exprCache.get(expr)!(safeStateWrap(state), SAFE_OUTER)
+  } catch (e) {
+    if (!warnedRuntime.has(expr)) {
+      warnedRuntime.add(expr)
+      warn(`runtime error in "${expr}": ${(e as Error).message}`)
+    }
     return undefined
   }
 }