micra.js 2.2.0 → 2.3.0

package/llms-full.txt

@@ -7,7 +7,7 @@ This file follows the llmstxt.org "expanded" convention: it inlines code recipes
 ## Install
 
 ```bash
-npm install micra.js@^2.2.0
+npm install micra.js@^2.3.0
 ```
 
 ```ts
@@ -17,7 +17,7 @@ import * as Micra from 'micra.js'
 Or CDN (no build step):
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 ```
 
 This exposes a global `Micra` object.
@@ -146,7 +146,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <button @click="inc">+</button>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('counter', {
     state: { count: 0 },
@@ -190,7 +190,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   </footer>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('todo-app', {
     state: {
@@ -262,7 +262,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="filtered().length === 0">No matches.</p>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('users-table', {
     state: {
@@ -303,7 +303,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="success">Invitation sent ✓</p>
 </form>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('invite-form', {
     state: { email: '', loading: false, error: '', success: false },
@@ -345,7 +345,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   </div>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('open-modal-btn', {
     open() {
@@ -394,7 +394,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <section data-if="tab === 'security'">Security content</section>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('tabs', {
     state: { tab: 'overview' },
@@ -414,7 +414,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <button @click="upgrade" data-if="plan !== 'enterprise'">Upgrade</button>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('user-card', {
     state: { name: '', plan: '' },
@@ -445,7 +445,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="!loading && results.length === 0 && query">No results.</p>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('search', {
     state: { query: '', results: [], loading: false },
@@ -479,7 +479,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="loading">Loading chart…</p>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('revenue-chart', {
     state: { loading: true },
@@ -511,7 +511,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="!loading && rows.length === 0">No results.</p>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 <script>
   Micra.define('search-bar', {
     state: { query: '' },
@@ -533,6 +533,59 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
 </script>
 ```
 
+## Recipe 11 — htmx bridge (server-driven HTML swaps + Micra islands)
+
+Wire htmx for server-driven DOM swaps and Micra for local reactivity on
+the same page. Twelve lines of glue, written once.
+
+```html
+<main hx-get="/page/home" hx-trigger="load" hx-swap="innerHTML"></main>
+
+<script src="https://cdn.jsdelivr.net/npm/htmx.org@2/dist/htmx.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
+<script>
+  Micra.define('counter', {
+    state: { count: 0 },
+    inc() { this.state.count++ },
+  })
+
+  Micra.start()  // initial mount
+
+  // Mount new [data-component] arriving via htmx swap.
+  document.body.addEventListener('htmx:afterSettle', (e) => {
+    Micra.start(e.target)
+  })
+
+  // Destroy Micra instances inside HTML about to be replaced.
+  document.body.addEventListener('htmx:beforeSwap', (e) => {
+    Micra.instances().forEach((inst, root) => {
+      if (e.target.contains(root)) inst.destroy()
+    })
+  })
+
+  // Bridge server-sent HX-Trigger events into the Micra bus.
+  document.body.addEventListener('htmx:trigger', (e) => {
+    const d = e.detail
+    if (typeof d === 'string') return Micra.emit(d)
+    for (const [k, v] of Object.entries(d)) Micra.emit(k, v)
+  })
+</script>
+```
+
+Rules of thumb:
+
+- **Never put `hx-swap` directly on a `[data-component]` element that
+  swaps its own `innerHTML`** — the cached directive scan points at gone
+  DOM. Use a wrapper as the swap target.
+- **`Micra.start()` is idempotent**, so re-scanning a subtree that
+  contains already-mounted siblings is safe.
+- **Always scope to `e.target`** in the bridge, not `document` — scanning
+  the whole page on every swap is wasteful.
+
+Full reference with state-survival patterns, `hx-vals`/`hx-include`
+bridging, and per-component loading state lives in
+`docs/recipes/htmx.md`.
+
 ---
 
 # Anti-pattern reference (what LLMs gravitate to — DO NOT)
@@ -569,9 +622,9 @@ import { ref, computed } from 'vue'
 import Alpine from 'alpinejs'
 
 // ❌ unpkg CDN — blocked by Claude artifacts and most AI sandbox CSPs
-<script src="https://unpkg.com/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://unpkg.com/micra.js@2.3.0/dist/micra.min.js"></script>
 // ✅ Use jsDelivr instead — it auto-mirrors npm and is CSP-allowlisted everywhere
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 ```
 
 # Final checklist

package/llms.txt

@@ -25,7 +25,7 @@ import * as Micra from 'micra.js'
 Or via CDN (no build step):
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.0/dist/micra.min.js"></script>
 ```
 
 This exposes a global `Micra` object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micra.js",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Lightweight reactive UI framework for server-rendered pages — reactive state, directives, event bus. < 5 KB gzip.",
   "type": "module",
   "main": "./dist/micra.cjs.js",
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "build": "node build.mjs",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
     "dev": "node build.mjs --watch",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/core/bus.ts

@@ -11,41 +11,50 @@
  * the unsub token in `instance.__micraSubs` for cleanup on destroy().
  */
 
-import type { EventHandler, UnsubFn } from '../types'
+import type { EmitArgs, EventHandler, EventPayload, UnsubFn } from '../types'
 
 // Module-level bus state — one bus per page load.
 const _bus = new Map<string, Set<EventHandler>>()
 
 /**
  * Subscribe to a named event. Returns an unsubscribe function.
+ * Payload is typed via the `MicraEvents` interface (augmentable).
  *
  * @example
  * const unsub = on('user:login', (user) => console.log(user))
  * unsub()  // stop listening
  */
-export function on<T = unknown>(event: string, handler: EventHandler<T>): UnsubFn {
+export function on<K extends string>(
+  event: K,
+  handler: (payload: EventPayload<K>) => void,
+): UnsubFn {
   if (!_bus.has(event)) _bus.set(event, new Set())
   _bus.get(event)!.add(handler as EventHandler)
-  return () => off(event, handler as EventHandler)
+  return () => off(event, handler)
 }
 
 /**
  * Unsubscribe a specific handler from an event.
  */
-export function off(event: string, handler: EventHandler): void {
+export function off<K extends string>(
+  event: K,
+  handler: (payload: EventPayload<K>) => void,
+): void {
   const set = _bus.get(event)
   if (!set) return
-  set.delete(handler)
+  set.delete(handler as EventHandler)
   if (set.size === 0) _bus.delete(event)
 }
 
 /**
  * Publish an event to all subscribers. Errors are caught per-handler.
+ * Payload is typed via the `MicraEvents` interface (augmentable).
  *
  * @example
  * emit('user:updated', { id: 1, name: 'Alice' })
  */
-export function emit(event: string, payload?: unknown): void {
+export function emit<K extends string>(event: K, ...args: EmitArgs<K>): void {
+  const payload = args[0]
   _bus.get(event)?.forEach(h => {
     try { h(payload) } catch (e) { console.error(`[Micra] bus error [${event}]:`, e) }
   })

package/src/core/mount.ts

@@ -17,8 +17,10 @@ import type {
   ComponentInstance,
   ComponentMethods,
   EventHandler,
+  EventPayload,
   InternalInstance,
   MicraElement,
+
   StateRecord,
   UnsubFn,
 } from "../types";
@@ -95,11 +97,11 @@ export function mount<S extends StateRecord, M>(
   instance.fetch = micraFetch;
   instance.emit = busEmit;
 
-  instance.on = <T = unknown>(
-    event: string,
-    handler: EventHandler<T>,
+  instance.on = <K extends string>(
+    event: K,
+    handler: (payload: EventPayload<K>) => void,
   ): UnsubFn => {
-    const unsub = busOn(event, handler);
+    const unsub = busOn(event, handler as EventHandler);
     if (!instance.__micraSubs) instance.__micraSubs = [];
     instance.__micraSubs.push(unsub);
     return unsub;
@@ -107,8 +109,14 @@ export function mount<S extends StateRecord, M>(
 
   // ── Render ────────────────────────────────────────────────────────────────
   let isRendering = false;
+  // Track which state key triggered the current render cycle.
+  // 'MULTIPLE' means more than one key was written before the microtask fired.
+  let _triggerKey: string | null | "MULTIPLE" = null;
   const schedule = createScheduler(() => instance.render());
-  instance.state = createReactiveState(rawState, schedule) as S;
+  instance.state = createReactiveState(rawState, schedule, (key) => {
+    if (_triggerKey === null) _triggerKey = key;
+    else if (_triggerKey !== key) _triggerKey = "MULTIPLE";
+  }) as S;
 
   // Expression state: proxy that falls back to instance methods so expressions
   // like `data-text="formatDate(item.date)"` can call component methods.
@@ -149,6 +157,8 @@ export function mount<S extends StateRecord, M>(
   let warnedReentry = false;
   instance.render = function () {
     if (instance.__micraDestroyed) return;
+    const triggerKey = _triggerKey;
+    _triggerKey = null;
     if (isRendering) {
       if (!warnedReentry) {
         warn(
@@ -166,7 +176,7 @@ export function mount<S extends StateRecord, M>(
       const scan =
         mRoot.__micraScan ?? (mRoot.__micraScan = scanComponent(root));
       applyDirectives(scan, exprState, rawState, instance);
-      renderList(scan.each, exprState, rawState, instance);
+      renderList(scan.each, exprState, rawState, instance, triggerKey);
       bindDataOn(scan.on, instance);
       bindAtEvents(scan.atEvents, instance);
       bindModels(scan.model, instance);
@@ -187,7 +197,7 @@ export function mount<S extends StateRecord, M>(
     );
     instance.__micraListeners = [];
 
-    // Clear per-element flags & cached directive scan so a future re-mount of the same DOM works.
+    // Clear per-element flags & cached scan so a future re-mount of the same DOM works.
     const clearFlags = (el: Element) => {
       const m = el as MicraElement;
       delete m.__micraEvents;

package/src/core/reactive.ts

@@ -20,11 +20,12 @@ import type { StateRecord } from '../types'
  * const state = createReactiveState(raw, render)
  * state.count = 5  // triggers render() in next microtask
  */
-export function createReactiveState<S extends StateRecord>(obj: S, schedule: () => void): S {
+export function createReactiveState<S extends StateRecord>(obj: S, schedule: () => void, onKey?: (key: string) => 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
+      onKey?.(key)
       schedule()
       return true
     },

package/src/dom/directives.ts

@@ -36,7 +36,8 @@ function applyText(el: Element, expr: string, state: StateRecord): void {
  * for the full security model.
  */
 function applyHtml(el: Element, expr: string, state: StateRecord): void {
-  el.innerHTML = String(evalExpr(expr, state) ?? '')
+  const html = String(evalExpr(expr, state) ?? '')
+  if (el.innerHTML !== html) el.innerHTML = html
 }
 
 /**
@@ -72,7 +73,9 @@ function applyIf(binding: CachedIfBinding, state: StateRecord): void {
  * 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'
+  const desired = evalExpr(expr, state) ? '' : 'none'
+  const htmlEl = el as HTMLElement
+  if (htmlEl.style.display !== desired) htmlEl.style.display = desired
 }
 
 function applyBind(