micra.js 1.0.0

package/src/dom/events.ts

@@ -0,0 +1,145 @@
+/**
+ * src/dom/events.ts — DOM event binding.
+ *
+ * Responsibilities:
+ *   - Bind `data-on="event:method"` listeners (once per element)
+ *   - Bind `@event="method"` shorthand (scanned once per component root)
+ *
+ * LLM NOTE: Listeners are attached exactly once. The `__micraEvents` and
+ * `__micraAtScanned` flags prevent duplicate bindings on re-renders.
+ */
+
+import type { InternalInstance, MicraElement, StateRecord } from '../types'
+import { evalExpr, warn } from '../utils/expr'
+import { queryOwn, queryAll } from './query'
+
+// ── data-on ───────────────────────────────────────────────────────────────────
+
+/**
+ * Bind `data-on="event:method[,event2:method2]"` listeners.
+ * Listeners are bound once — re-render calls are no-ops for already-bound elements.
+ *
+ * Supports modifiers: `click.prevent`, `click.stop`, `click.self`.
+ *
+ * @example
+ * <button data-on="click:save">Save</button>
+ * <form  data-on="submit.prevent:handleSubmit">
+ */
+export function bindDataOn<S extends StateRecord>(
+  root: Element,
+  instance: InternalInstance<S>,
+): void {
+  const isFragment = root.nodeType === 11
+  const els = isFragment
+    ? queryAll(root as unknown as ParentNode, '[data-on]')
+    : queryOwn(root, 'data-on')
+
+  // Include root itself if it carries data-on (e.g., the keyed item IS the button)
+  if (!isFragment && (root as HTMLElement).hasAttribute?.('data-on') && !els.includes(root))
+    els.unshift(root)
+
+  for (const el of els) {
+    const mEl = el as MicraElement
+    if (mEl.__micraEvents) continue
+    mEl.__micraEvents = true
+
+    const spec = mEl.dataset['on'] ?? ''
+    for (const part of spec.split(',')) {
+      const [evSpec, method] = part.trim().split(':') as [string, string]
+      if (!evSpec || !method) continue
+
+      const [evName, ...mods] = evSpec.split('.')
+
+      el.addEventListener(evName!, (e: Event) => {
+        if (mods.includes('prevent')) e.preventDefault()
+        if (mods.includes('stop')) e.stopPropagation()
+        if (mods.includes('self') && e.target !== el) return
+
+        const fn = instance[method.trim()]
+        if (typeof fn === 'function') (fn as (e: Event) => void).call(instance, e)
+        else warn(`method "${method.trim()}" not found`)
+      })
+    }
+  }
+}
+
+// ── @event shorthand ──────────────────────────────────────────────────────────
+
+/**
+ * Bind `@event="method"` shorthand attributes (Stimulus-style).
+ * Scanned once per component root (guarded by `__micraAtScanned`).
+ * Supports the same modifiers as data-on: `@click.prevent="submit"`.
+ *
+ * @example
+ * <button @click="increment">+</button>
+ * <form @submit.prevent="handleSubmit">
+ */
+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 all = queryAll(root, '*')
+  for (const el of all) {
+    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) => {
+        if (rest.includes('prevent')) e.preventDefault()
+        if (rest.includes('stop')) e.stopPropagation()
+        if (rest.includes('self') && e.target !== el) return
+
+        const fn = instance[method]
+        if (typeof fn === 'function') (fn as (e: Event) => void).call(instance, e)
+        else warn(`method "${method}" not found`)
+      })
+    }
+  }
+}
+
+// ── data-model ────────────────────────────────────────────────────────────────
+
+/**
+ * Two-way binding: `data-model="key"` wires <input>/<select>/<textarea>
+ * to `state[key]`. Binding is attached once per element.
+ *
+ * @example
+ * <input data-model="search">   // updates state.search on every keystroke
+ * <select data-model="sortBy">  // updates state.sortBy on change
+ */
+export function bindModels<S extends StateRecord>(
+  root: Element,
+  instance: InternalInstance<S>,
+): void {
+  const isFragment = root.nodeType === 11
+  const els = isFragment
+    ? queryAll(root as unknown as ParentNode, '[data-model]')
+    : queryOwn(root, 'data-model')
+
+  for (const el of els) {
+    const mEl = el as MicraElement
+    if (mEl.__micraModel) continue
+    mEl.__micraModel = true
+
+    const key = (el as HTMLInputElement).dataset['model'] ?? ''
+    const tag = el.tagName
+
+    const update = () => {
+      const val = tag === 'INPUT' && (el as HTMLInputElement).type === 'checkbox'
+        ? (el as HTMLInputElement).checked
+        : (el as HTMLInputElement).value
+      ;(instance.state as StateRecord)[key] = val
+    }
+
+    el.addEventListener(tag === 'SELECT' || (el as HTMLInputElement).type === 'radio'
+      ? 'change'
+      : 'input',
+      update,
+    )
+  }
+}

package/src/dom/query.ts

@@ -0,0 +1,36 @@
+/**
+ * src/dom/query.ts — DOM query helpers.
+ *
+ * LLM NOTE: These are utility functions with no side effects.
+ * queryOwn is the critical function that prevents a parent component from
+ * accidentally processing directives belonging to a nested child component.
+ */
+
+/**
+ * querySelectorAll wrapper — returns a typed array.
+ */
+export function queryAll(root: ParentNode, sel: string): Element[] {
+  return Array.from(root.querySelectorAll(sel))
+}
+
+/**
+ * Like querySelectorAll, but EXCLUDES elements that live inside a nested
+ * `[data-component]` subtree.
+ *
+ * This is what prevents a parent component's render() from clobbering
+ * the DOM managed by a child component.
+ *
+ * LLM NOTE: The walk goes up parentElement until it hits `root` or null.
+ * If any ancestor (between el and root) has data-component, the element is
+ * 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 => {
+    let node: Element | null = el.parentElement
+    while (node && node !== root) {
+      if (node.hasAttribute('data-component')) return false
+      node = node.parentElement
+    }
+    return true
+  })
+}

package/src/dom/refs.ts

@@ -0,0 +1,35 @@
+/**
+ * src/dom/refs.ts — data-ref collection.
+ *
+ * Responsibilities:
+ *   - After each render, scan for `[data-ref]` elements (owned by this component)
+ *   - Populate `instance.refs` so methods can do `this.refs.chart` etc.
+ *
+ * LLM NOTE: This module is PURE relative to state — it only reads DOM attributes
+ * and writes to instance.refs. It does NOT trigger renders.
+ */
+
+import type { InternalInstance, MicraElement, StateRecord } from '../types'
+import { queryOwn } from './query'
+
+/**
+ * Collect all `[data-ref="name"]` elements owned by this component root into
+ * `instance.refs`.
+ *
+ * Called once after the initial render and again on every re-render (refs may
+ * point to newly created elements after an each-list update).
+ *
+ * @example
+ * // HTML: <canvas data-ref="chart">
+ * // JS:   this.refs.chart  →  HTMLCanvasElement
+ */
+export function collectRefs<S extends StateRecord>(
+  root: Element,
+  instance: InternalInstance<S>,
+): void {
+  instance.refs = {}
+  for (const el of queryOwn(root, 'data-ref')) {
+    const name = (el as MicraElement).dataset['ref']
+    if (name) instance.refs[name] = el as HTMLElement
+  }
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Micra.js — Lightweight reactive framework for small sites and simple SaaS.
+ *
+ * Public surface — re-exports only.
+ *
+ * Features:
+ *   - JS expressions in directives  (data-if="count > 0")
+ *   - Keyed list diffing             (data-each="items" data-key="id")
+ *   - Auto-mount via data-component  (Micra.define + Micra.start)
+ *   - Props from SSR data-attributes (this.prop('page'))
+ *   - Built-in fetch helper          (this.fetch('/api/...'))
+ *   - Global event bus               (Micra.on / Micra.emit)
+ *   - DOM refs                       (data-ref="chart" → this.refs.chart)
+ *   - Additive class toggling        (data-class="active:isActive")
+ *   - @event shorthand               (@click="increment")
+ *   - Lifecycle: onCreate, onDestroy
+ *   - 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
+ *
+ * @module Micra
+ */
+
+// ── Public types ──────────────────────────────────────────────────────────────
+export type {
+  StateRecord,
+  UnsubFn,
+  EventHandler,
+  FetchOptions,
+  ComponentInstance,
+  ComponentDefinition,
+} from './types'
+
+// ── Errors ────────────────────────────────────────────────────────────────────
+export { FetchError } from './utils/fetch'
+
+// ── Public API ────────────────────────────────────────────────────────────────
+export { define, defineComponent, instances, registry, debug } from './core/registry'
+export { mount } from './core/mount'
+export { start } from './core/start'
+export { on, off, emit } from './core/bus'

package/src/types.ts

@@ -0,0 +1,157 @@
+/**
+ * src/types.ts — All Micra.js type definitions.
+ *
+ * Public types are re-exported from src/index.ts.
+ * Internal types (MicraElement, MicraTemplate, InternalInstance) are used by
+ * implementation modules but are NOT part of the public API.
+ */
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+/**
+ * Constraint for component state objects.
+ * Use any plain object: `{ count: 0, items: [] as User[] }`.
+ */
+// LLM NOTE: intentionally wide — S is always inferred from the literal `state`
+// property, so the actual type is precise (e.g. { count: number }), not Record.
+export type StateRecord = Record<string, unknown>
+
+/** Returns an unsubscribe function. */
+export type UnsubFn = () => void
+
+/** Event bus handler. Generic `T` types the payload. */
+export type EventHandler<T = unknown> = (payload: T) => void
+
+/** Options for `this.fetch()`. For GET/HEAD extra keys become query params. */
+export interface FetchOptions {
+  method?: string
+  headers?: Record<string, string>
+  /** POST/PUT/PATCH body — serialized as JSON. */
+  body?: unknown
+  [key: string]: unknown
+}
+
+/**
+ * The `this` context inside component methods and lifecycle hooks.
+ * `S` is inferred from the component's `state` object.
+ *
+ * @example
+ * // state: { count: 0 } → S = { count: number }
+ * increment() { this.state.count++ }  // count is number ✓
+ */
+export interface ComponentInstance<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. */
+  state: S
+  /**
+   * DOM refs: collect elements with `data-ref="name"` → `this.refs.name`.
+   * @example <canvas data-ref="chart"> → this.refs.chart
+   */
+  refs: Record<string, HTMLElement>
+  /** Force a synchronous re-render. Normally not needed — state mutations batch automatically. */
+  render(): void
+  /** Unmount: clean up event bus subscriptions and call onDestroy. */
+  destroy(): void
+  /**
+   * Read a `data-*` attribute from the root element with auto-cast.
+   * Casts "true"/"false" → boolean, numeric strings → number.
+   * @example this.prop('perPage', 10) // data-per-page="20" → 20
+   */
+  prop(name: string): string | undefined
+  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
+}
+
+/**
+ * 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<>`.
+ *
+ * @example
+ * Micra.define('counter', {
+ *   state: { count: 0 },
+ *   inc() { this.state.count++ },  // this.state.count: number ✓
+ * })
+ */
+export type ComponentDefinition<S extends StateRecord = StateRecord> = {
+  /** 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>
+  /**
+   * 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>>
+
+// ── Internal types ────────────────────────────────────────────────────────────
+// These are NOT exported from src/index.ts.
+
+/**
+ * @internal Extended HTMLElement with Micra bookkeeping slots.
+ */
+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)
+  __micraKey?: unknown      // keyed-diff key
+  __micraEach?: true        // belongs to a no-key each list
+  __micraCache?: DirectiveCache  // cached directive scan result
+}
+
+/**
+ * @internal Extended HTMLTemplateElement with keyed-diff state.
+ */
+export interface MicraTemplate extends HTMLTemplateElement {
+  __micraMarker?: Comment
+  __micraNodes: Map<unknown, MicraElement>
+  __micraList: ChildNode[]
+}
+
+/**
+ * @internal Per-element directive binding (element + expression string).
+ */
+export interface CachedBinding {
+  el: Element
+  expr: string
+}
+
+/**
+ * @internal Directive scan result — built once per Element, reused every render.
+ * This is the core of the performance optimization.
+ *
+ * LLM NOTE: DirectiveCache is built lazily on first render and stored on the
+ * element. It avoids repeated querySelectorAll calls on every re-render.
+ */
+export interface DirectiveCache {
+  text:  CachedBinding[]
+  html:  CachedBinding[]
+  if:    CachedBinding[]
+  show:  CachedBinding[]
+  bind:  CachedBinding[]
+  model: CachedBinding[]
+  class: CachedBinding[]
+}
+
+/**
+ * @internal Full instance as seen inside the runtime — extends the public
+ * interface with private bookkeeping slots and an index signature for
+ * dynamic method dispatch.
+ */
+export interface InternalInstance<S extends StateRecord = StateRecord>
+  extends ComponentInstance<S> {
+  __micraSubs?: UnsubFn[]
+  [key: string]: unknown
+}

package/src/utils/expr.ts

@@ -0,0 +1,72 @@
+/**
+ * src/utils/expr.ts — JS expression evaluator.
+ *
+ * Responsibilities:
+ *   - Compile expression strings into cached functions
+ *   - Evaluate them against a state object
+ *   - Fast-path for simple property lookups
+ *
+ * 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.
+ */
+
+import type { StateRecord } from '../types'
+
+// ── Expression cache ──────────────────────────────────────────────────────────
+// Compiled functions are keyed by expression string — Function() is only called
+// once per unique expression across the entire app lifetime.
+
+// 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>()
+
+// 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_$]*)*$/
+
+/**
+ * Evaluate a JS expression string against a state object.
+ *
+ * Results are cached by expression string — repeated evaluations hit the cache.
+ * Uses a fast-path for simple dot-paths (e.g. "count", "user.name") that avoids
+ * Function() overhead.
+ *
+ * @example
+ * evalExpr('count > 0', { count: 5 })   // → true
+ * evalExpr('user.name', { user: { name: 'Alice' } }) // → 'Alice'
+ * 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
+  if (SIMPLE_PATH.test(expr)) {
+    return expr.split('.').reduce<unknown>((obj, key) =>
+      obj != null ? (obj as StateRecord)[key] : undefined,
+      state,
+    )
+  }
+
+  if (!exprCache.has(expr)) {
+    try {
+      exprCache.set(
+        expr,
+        new Function('$s', `with($s){return (${expr})}`) as (s: StateRecord) => unknown,
+      )
+    } catch {
+      warn(`invalid expression "${expr}"`)
+      exprCache.set(expr, () => undefined)
+    }
+  }
+
+  try {
+    return exprCache.get(expr)!(state)
+  } catch {
+    return undefined
+  }
+}
+
+// ── Dev warnings ──────────────────────────────────────────────────────────────
+
+/** @internal Consistent warning prefix. */
+export function warn(msg: string): void {
+  console.warn(`[Micra] ${msg}`)
+}

package/src/utils/fetch.ts

@@ -0,0 +1,100 @@
+/**
+ * src/utils/fetch.ts — HTTP fetch helper.
+ *
+ * Responsibilities:
+ *   - Auto-attach CSRF token from <meta name="csrf-token">
+ *   - Serialize POST/PUT/PATCH body as JSON
+ *   - Serialize GET/HEAD options as query params
+ *   - Throw a typed FetchError on non-2xx responses
+ *   - Return parsed JSON or text
+ *
+ * LLM NOTE: This module is PURE (no DOM side effects beyond reading a meta tag).
+ * It wraps the native fetch() API with SaaS-friendly defaults.
+ */
+
+import type { FetchOptions } from '../types'
+
+// ── CSRF ──────────────────────────────────────────────────────────────────────
+
+/** Read CSRF token from <meta name="csrf-token"> (Rails, Laravel, Django…). */
+function getCSRF(): string | null {
+  return document.querySelector('meta[name="csrf-token"]')?.getAttribute('content') ?? null
+}
+
+// ── Typed error ───────────────────────────────────────────────────────────────
+
+/**
+ * Thrown by `this.fetch()` when the server returns a non-2xx status.
+ *
+ * @example
+ * try {
+ *   await this.fetch('/api/data')
+ * } catch (e) {
+ *   if (e instanceof FetchError && e.status === 404) { ... }
+ * }
+ */
+export class FetchError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly response: Response,
+  ) {
+    super(message)
+    this.name = 'FetchError'
+  }
+}
+
+// ── Fetch helper ──────────────────────────────────────────────────────────────
+
+/**
+ * Fetch wrapper with SaaS defaults.
+ *
+ * - GET/HEAD: extra `options` keys become URL query params
+ * - POST/PUT/PATCH/DELETE: `options.body` is JSON-serialized
+ * - Attaches X-CSRF-Token header automatically
+ * - Returns parsed JSON if Content-Type is application/json, else text
+ *
+ * @example
+ * // GET with params → /api/users?page=2&status=active
+ * const data = await this.fetch('/api/users', { page: 2, status: 'active' })
+ *
+ * // POST with JSON body
+ * await this.fetch('/api/invite', { method: 'POST', body: { email, role } })
+ */
+export async function micraFetch(url: string, options: FetchOptions = {}): Promise<unknown> {
+  const method  = ((options.method as string | undefined) ?? 'GET').toUpperCase()
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    ...(options.headers as Record<string, string> | undefined),
+  }
+
+  const csrf = getCSRF()
+  if (csrf) headers['X-CSRF-Token'] = csrf
+
+  let finalUrl = url
+  let body: string | undefined
+
+  if (method === 'GET' || method === 'HEAD') {
+    const params: Record<string, string> = {}
+    for (const [k, v] of Object.entries(options)) {
+      if (k !== 'method' && k !== 'headers' && v != null) params[k] = String(v)
+    }
+    if (Object.keys(params).length)
+      finalUrl += (url.includes('?') ? '&' : '?') + new URLSearchParams(params)
+  } else {
+    headers['Content-Type'] = 'application/json'
+    body = JSON.stringify(options.body !== undefined ? options.body : options)
+  }
+
+  const res = await fetch(finalUrl, {
+    method,
+    headers,
+    ...(body !== undefined ? { body } : {}),
+  })
+
+  if (!res.ok)
+    throw new FetchError(`[Micra] fetch: ${method} ${url} → ${res.status}`, res.status, res)
+
+  const ct = res.headers.get('content-type') ?? ''
+  return ct.includes('application/json') ? res.json() : res.text()
+}