micra.js 1.0.0 → 2.0.0

package/src/core/mount.ts

@@ -17,6 +17,7 @@ import type {
   ComponentInstance,
   EventHandler,
   InternalInstance,
+  MicraElement,
   StateRecord,
   UnsubFn,
 } from '../types'
@@ -97,16 +98,46 @@ export function mount<S extends StateRecord>(
 
   // Expression state: proxy that falls back to instance methods so expressions
   // like `data-text="formatDate(item.date)"` can call component methods.
+  //
+  // Instance methods are returned BOUND to the instance — directive expressions
+  // call them as bare identifiers via `with()`, which would normally lose `this`.
+  // Bound copies are memoized per method name so repeated reads are cheap.
+  //
+  // Both traps reject Object.prototype names ('constructor', 'toString', ...) —
+  // accessing them via a directive expression returns undefined instead of
+  // leaking the prototype.
+  const boundMethods = new Map<string, Function>()
   const exprState = new Proxy(rawState, {
     get(target, key: string) {
-      if (key in target)   return target[key]
-      if (key in instance) return instance[key]
+      if (Object.prototype.hasOwnProperty.call(target, key)) return target[key]
+      if (Object.prototype.hasOwnProperty.call(instance, key) &&
+          typeof instance[key] === 'function') {
+        const cached = boundMethods.get(key)
+        if (cached) return cached
+        const bound = (instance[key] as Function).bind(instance)
+        boundMethods.set(key, bound)
+        return bound
+      }
       return undefined
     },
+    has(target, key: string) {
+      if (typeof key !== 'string') return false
+      if (Object.prototype.hasOwnProperty.call(target, key)) return true
+      return Object.prototype.hasOwnProperty.call(instance, key) &&
+             typeof instance[key] === 'function'
+    },
   })
 
+  let warnedReentry = false
   instance.render = function () {
-    if (isRendering) return
+    if (instance.__micraDestroyed) return
+    if (isRendering) {
+      if (!warnedReentry) {
+        warn('render() re-entry detected — mutation inside a directive expression is ignored. Move state writes to a method.')
+        warnedReentry = true
+      }
+      return
+    }
     isRendering = true
     try {
       applyDirectives(root, exprState, rawState, instance)
@@ -122,7 +153,27 @@ export function mount<S extends StateRecord>(
 
   // ── Destroy ───────────────────────────────────────────────────────────────
   instance.destroy = function () {
+    if (instance.__micraDestroyed) return
+    instance.__micraDestroyed = true
+
+    // Remove every DOM listener attached by bindDataOn / bindAtEvents / bindModels.
+    instance.__micraListeners?.forEach(({ el, type, fn }) => el.removeEventListener(type, fn))
+    instance.__micraListeners = []
+
+    // Clear per-element flags & cached directive scan so a future re-mount of the same DOM works.
+    const clearFlags = (el: Element) => {
+      const m = el as MicraElement
+      delete m.__micraEvents
+      delete m.__micraAtBound
+      delete m.__micraModel
+      delete m.__micraCache
+    }
+    clearFlags(root)
+    root.querySelectorAll('*').forEach(clearFlags)
+
     instance.__micraSubs?.forEach(unsub => unsub())
+    instance.__micraSubs = []
+
     if (typeof (definition as Record<string, unknown>).onDestroy === 'function')
       (definition.onDestroy as () => void).call(instance)
     _instances.delete(root)

package/src/dom/directives.ts

@@ -15,9 +15,12 @@
 
 import type {
   CachedBinding,
+  CachedIfBinding,
+  CachedPairBinding,
   DirectiveCache,
   InternalInstance,
   MicraElement,
+  MicraTemplate,
   StateRecord,
 } from '../types'
 import { evalExpr, warn } from '../utils/expr'
@@ -31,21 +34,60 @@ 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) ?? '')
 }
 
-function applyIf(el: Element, expr: string, state: StateRecord): void {
+/**
+ * data-if — true mount/unmount. When the expression is falsy, the element is
+ * detached from the DOM and a Comment placeholder takes its slot. When truthy,
+ * the element is re-inserted where the placeholder is.
+ *
+ * Side effect: when an element is detached, its `data-ref` is gone from
+ * `this.refs` and its `data-model` listener still exists on the (detached)
+ * node — listeners survive detach.
+ *
+ * Use `data-show` when you want the cheap display:none toggle instead.
+ */
+function applyIf(binding: CachedIfBinding, state: StateRecord): void {
+  const el = binding.el as HTMLElement
+  const truthy = !!evalExpr(binding.expr, state)
+  if (truthy) {
+    // If a placeholder is currently in the DOM in the element's slot, swap back.
+    const ph = binding.placeholder
+    if (ph && ph.parentNode) ph.parentNode.replaceChild(el, ph)
+  } else {
+    // Only detach if currently attached somewhere. Standalone elements
+    // (no parent — common in unit tests) are a no-op.
+    const parent = el.parentNode
+    if (parent) {
+      if (!binding.placeholder) binding.placeholder = document.createComment('if')
+      parent.replaceChild(binding.placeholder, el)
+    }
+  }
+}
+
+/**
+ * data-show — visibility toggle via `style.display`. Element stays in the DOM.
+ */
+function applyShow(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 +118,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 +169,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'),
+    if:    pick('data-if') as CachedIfBinding[],
     show:  pick('data-show'),
-    bind:  pick('data-bind'),
+    bind:  pickPairs('data-bind'),
     model: pick('data-model'),
-    class: pick('data-class'),
+    class: pickPairs('data-class'),
   }
 }
 
@@ -161,13 +221,15 @@ function applyFromList(
   state: StateRecord,
   rawState: StateRecord,
 ): void {
+  // data-if runs first so subsequent directives don't write into a tree that's
+  // about to be detached this tick.
+  cache.if.forEach(b => applyIf(b, state))
   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.show.forEach(b => applyShow(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 +238,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'),
+    if:    pick('data-if') as CachedIfBinding[],
     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 +261,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

@@ -53,7 +53,10 @@ export function renderList<S extends StateRecord>(
 
     const marker = tmpl.__micraMarker
     const keyMap = tmpl.__micraNodes
-    const parent = marker.parentNode!
+    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) return
 
     // Empty / non-array: clear all rendered rows
     if (!Array.isArray(items)) {
@@ -86,10 +89,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,15 +3,28 @@
  *
  * 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 { queryOwn, queryAll } from './query'
+import { warn } from '../utils/expr'
+import { queryOwn, queryOwnAll, 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, '*')
+    : queryOwnAll(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/dom/query.ts

@@ -25,7 +25,21 @@ export function queryAll(root: ParentNode, sel: string): Element[] {
  * owned by that nested component, not by root's component — so we skip it.
  */
 export function queryOwn(root: Element, attr: string): Element[] {
-  return queryAll(root, `[${attr}]`).filter(el => {
+  return filterOwn(root, queryAll(root, `[${attr}]`))
+}
+
+/**
+ * Like queryOwn but accepts an arbitrary CSS selector. Used by bindAtEvents
+ * which scans `*` for `@`-prefixed attribute names (no attribute selector exists
+ * for those).
+ */
+export function queryOwnAll(root: Element, sel: string): Element[] {
+  return filterOwn(root, queryAll(root, sel))
+}
+
+/** @internal Shared subtree-ownership filter. */
+function filterOwn(root: Element, els: Element[]): Element[] {
+  return els.filter(el => {
     let node: Element | null = el.parentElement
     while (node && node !== root) {
       if (node.hasAttribute('data-component')) return false

package/src/index.ts

@@ -17,7 +17,7 @@
  *   - SSR-friendly: Micra.start() is safe to call multiple times
  *   - Directive cache: O(1) re-renders after first mount
  *
- * Size target: < 5 KB minified+gzipped
+ * Size target: < 5.5 KB minified+gzipped
  *
  * @module Micra
  */

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,26 @@ export interface CachedBinding {
   expr: string
 }
 
+/**
+ * @internal data-if binding — like CachedBinding but also carries the
+ * placeholder Comment that takes the element's slot in the DOM while the
+ * element is detached (unmounted).
+ */
+export interface CachedIfBinding extends CachedBinding {
+  placeholder?: Comment
+}
+
+/**
+ * @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.
@@ -138,11 +168,11 @@ export interface CachedBinding {
 export interface DirectiveCache {
   text:  CachedBinding[]
   html:  CachedBinding[]
-  if:    CachedBinding[]
+  if:    CachedIfBinding[]
   show:  CachedBinding[]
-  bind:  CachedBinding[]
+  bind:  CachedPairBinding[]
   model: CachedBinding[]
-  class: CachedBinding[]
+  class: CachedPairBinding[]
 }
 
 /**
@@ -153,5 +183,7 @@ export interface DirectiveCache {
 export interface InternalInstance<S extends StateRecord = StateRecord>
   extends ComponentInstance<S> {
   __micraSubs?: UnsubFn[]
+  __micraListeners?: TrackedListener[]
+  __micraDestroyed?: true
   [key: string]: unknown
 }