micra.js 2.3.0 → 2.3.2

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.3.0
+npm install micra.js@^2.3.2
 ```
 
 ```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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/dist/micra.min.js"></script>
 <script>
   Micra.define('search-bar', {
     state: { query: '' },
@@ -542,7 +542,7 @@ the same page. Twelve lines of glue, written once.
 <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 src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/dist/micra.min.js"></script>
 <script>
   Micra.define('counter', {
     state: { count: 0 },
@@ -586,6 +586,101 @@ Full reference with state-survival patterns, `hx-vals`/`hx-include`
 bridging, and per-component loading state lives in
 `docs/recipes/htmx.md`.
 
+## Recipe 12 — Rails + Micra (importmap, CSRF, Turbo Drive)
+
+Pin Micra in `config/importmap.rb`, boot it once in the layout — that's
+the whole integration. CSRF works automatically (Micra reads
+`<meta name="csrf-token">` that Rails already ships). Turbo Drive needs
+a `turbo:load` mirror so the second navigation doesn't ghost.
+
+```ruby
+# config/importmap.rb
+pin "micra",
+    to: "https://cdn.jsdelivr.net/npm/micra.js@2.3.2/dist/micra.esm.js",
+    preload: true
+```
+
+```erb
+<%# app/views/layouts/application.html.erb — inside <head> %>
+<%= csrf_meta_tags %>
+<%= javascript_importmap_tags %>
+<script type="module">
+  import * as Micra from "micra"
+  window.Micra = Micra
+  document.addEventListener("DOMContentLoaded", () => Micra.start())
+  document.addEventListener("turbo:load",        () => Micra.start())
+</script>
+```
+
+```erb
+<%# app/views/tasks/index.html.erb %>
+<section data-component="tasks-board"
+         data-initial-tasks='<%= @tasks.as_json(only: %i[id title done]).to_json %>'>
+  <form @submit.prevent="add">
+    <input data-model="draft" placeholder="New task…" />
+    <button data-bind="disabled:!draft.trim()">Add</button>
+  </form>
+  <template data-each="tasks" data-key="id">
+    <li data-class="done:item.done">
+      <input type="checkbox" data-bind="checked:item.done" @change="toggle" />
+      <span data-text="item.title"></span>
+      <button @click="remove" data-bind="data-id:item.id">×</button>
+    </li>
+  </template>
+</section>
+```
+
+```js
+// app/javascript/application.js
+import * as Micra from "micra"
+
+Micra.define("tasks-board", {
+  state: { tasks: [], draft: "" },
+  onCreate() { this.state.tasks = JSON.parse(this.prop("initialTasks") || "[]") },
+  async add() {
+    const task = await this.fetch("/tasks", { method: "POST", body: { title: this.state.draft.trim() } })
+    this.state.tasks = [...this.state.tasks, task]
+    this.state.draft = ""
+  },
+  async toggle(e) {
+    const id = Number(e.currentTarget.closest("li").querySelector("[data-id]").dataset.id)
+    const next = !this.state.tasks.find(t => t.id === id).done
+    const task = await this.fetch(`/tasks/${id}`, { method: "PATCH", body: { done: next } })
+    this.state.tasks = this.state.tasks.map(t => t.id === id ? task : t)
+  },
+  async remove(e) {
+    const id = Number(e.currentTarget.dataset.id)
+    await this.fetch(`/tasks/${id}`, { method: "DELETE" })
+    this.state.tasks = this.state.tasks.filter(t => t.id !== id)
+  },
+})
+```
+
+Rules of thumb:
+
+- **CSRF is automatic** — keep `<%= csrf_meta_tags %>` in the layout.
+  `this.fetch()` sends `X-CSRF-Token` on every non-GET request.
+- **Add `turbo:load`** alongside `DOMContentLoaded` if you have Turbo
+  Drive enabled (default since Rails 7). Without it, only the first
+  page load wires up.
+- **JSON in `data-*` attributes does NOT auto-parse.** Non-primitive
+  props (`@tasks.as_json.to_json`) are strings client-side — call
+  `JSON.parse(this.prop('initialTasks'))` in `onCreate`. Primitives
+  (numbers, booleans) auto-cast through `this.prop()`.
+- **Turbo Frames** that swap their own `innerHTML` and contain a
+  `[data-component]` will leave the cached scan pointing at gone DOM.
+  Same footgun as htmx — keep `data-component` outside the frame, or
+  destroy+remount on `turbo:frame-render`.
+- The optional **`micra-rails`** gem adds an ERB helper
+  (`micra_component`) and a one-shot installer. Its importmap pin can lag
+  the latest Micra.js release between gem versions (override it in your
+  own `config/importmap.rb`), and the `micra_state.to_html` example in
+  its README doesn't compile — see `docs/recipes/rails.md` §2 for
+  workarounds.
+
+Full reference with Turbo Streams cleanup, no-flicker hydration pattern,
+and the Stimulus-vs-Micra split is in `docs/recipes/rails.md`.
+
 ---
 
 # Anti-pattern reference (what LLMs gravitate to — DO NOT)
@@ -622,9 +717,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.3.0/dist/micra.min.js"></script>
+<script src="https://unpkg.com/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/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.3.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.2/dist/micra.min.js"></script>
 ```
 
 This exposes a global `Micra` object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micra.js",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Lightweight reactive UI framework for server-rendered pages — reactive state, directives, event bus. < 5 KB gzip.",
   "type": "module",
   "main": "./dist/micra.cjs.js",
@@ -30,7 +30,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "docs:sync": "rm -rf site/dist && mkdir -p site/dist && cp -R dist/* site/dist/",
+    "docs:sync": "rm -rf site/dist && mkdir -p site/dist && cp -R dist/* site/dist/ && cp llms.txt llms-full.txt site/",
     "docs:build": "npm run build && npm run docs:sync",
     "docs:dev": "npm run docs:sync && npx serve -p 4321 site"
   },

package/src/core/mount.ts

@@ -175,7 +175,7 @@ export function mount<S extends StateRecord, M>(
       const mRoot = root as MicraElement;
       const scan =
         mRoot.__micraScan ?? (mRoot.__micraScan = scanComponent(root));
-      applyDirectives(scan, exprState, rawState, instance);
+      applyDirectives(scan, exprState, rawState);
       renderList(scan.each, exprState, rawState, instance, triggerKey);
       bindDataOn(scan.on, instance);
       bindAtEvents(scan.atEvents, instance);

package/src/core/reactive.ts

@@ -36,6 +36,10 @@ export function createReactiveState<S extends StateRecord>(obj: S, schedule: ()
  * Return a debounce function that defers `render` to the next microtask.
  * Multiple calls within the same tick collapse to a single render.
  *
+ * Uses `queueMicrotask` so each batch enqueues a single microtask instead of
+ * allocating a Promise + reaction job. `flush` is hoisted out of the hot path
+ * so it isn't re-created on every schedule() call.
+ *
  * @example
  * const schedule = createScheduler(render)
  * schedule()  // defers render
@@ -43,9 +47,10 @@ export function createReactiveState<S extends StateRecord>(obj: S, schedule: ()
  */
 export function createScheduler(render: () => void): () => void {
   let pending = false
+  const flush = () => { pending = false; render() }
   return function schedule() {
     if (pending) return
     pending = true
-    Promise.resolve().then(() => { pending = false; render() })
+    queueMicrotask(flush)
   }
 }

package/src/dom/directives.ts

@@ -14,7 +14,6 @@
 
 import type {
   CachedIfBinding,
-  InternalInstance,
   ScanIndex,
   StateRecord,
 } from '../types'
@@ -147,11 +146,10 @@ function applyModel(
  * @param state    - Expression state (may include item/index for each rows)
  * @param rawState - Raw (non-proxy) state for model sync
  */
-export function applyDirectives<S extends StateRecord>(
+export function applyDirectives(
   scan: ScanIndex,
   state: StateRecord,
   rawState: StateRecord,
-  _instance: InternalInstance<S>,
 ): void {
   // data-if runs first so subsequent directives don't write into a tree that's
   // about to be detached this tick.

package/src/dom/each.ts

@@ -106,8 +106,25 @@ function createRowNode<S extends StateRecord>(
 ): MicraElement {
   const frag = tmpl.content.cloneNode(true) as DocumentFragment
   let node: MicraElement
-  if (frag.childNodes.length === 1) {
-    node = frag.firstElementChild as MicraElement
+  // Single-root detection must ignore whitespace-only text nodes — a
+  // pretty-printed `<template>\n  <tr>…</tr>\n</template>` is still one root.
+  // Wrapping a lone <tr> in <micra-each-item> would put invalid content
+  // inside <tbody> and break `tbody > tr` selectors. Only TOP-LEVEL child
+  // nodes are scanned (O(1-ish), not O(subtree)); NBSP counts as meaningful
+  // (it renders), so it keeps the wrapper. Comments beside the root are
+  // dropped — they don't render and aren't worth a wrapper in <tbody>.
+  const first = frag.firstElementChild as MicraElement | null
+  // meaningful = any char with code > 32 (NBSP included; \t \n \f \r and
+  // space excluded) in a top-level text node
+  const single =
+    !!first &&
+    !first.nextElementSibling &&
+    !Array.prototype.some.call(
+      frag.childNodes,
+      (c: Node) => c.nodeType === 3 && /[^\x00- ]/.test(c.textContent!),
+    )
+  if (single) {
+    node = first!
   } else {
     node = document.createElement('micra-each-item') as MicraElement
     node.style.display = 'contents'
@@ -156,7 +173,6 @@ function renderKeyed<S extends StateRecord>(
 
     if (!node) {
       node = createRowNode(tmpl, state, instance)
-      node.__micraKey = key
       keyMap.set(key, node)
     } else if (canSkipUnchanged && node.__micraItem === item && node.__micraIndex === index) {
       // Item reference and index are unchanged, and no other state key changed
@@ -177,7 +193,7 @@ function renderKeyed<S extends StateRecord>(
     // Use the cached scan if present (created above on first sight of this key);
     // older paths may pass a node we haven't scanned yet.
     const rowScan = node.__micraScan ?? (node.__micraScan = scanComponent(node))
-    applyDirectives(rowScan, itemState, rawState, instance)
+    applyDirectives(rowScan, itemState, rawState)
     nextNodes.push(node)
   }
 
@@ -292,7 +308,7 @@ function renderNoKey<S extends StateRecord>(
     itemState.item = item
     itemState.index = i
     itemState.$index = i
-    applyDirectives(node.__micraScan!, itemState, rawState, instance)
+    applyDirectives(node.__micraScan!, itemState, rawState)
     nextList[i] = node
   }
 
@@ -311,10 +327,9 @@ function renderNoKey<S extends StateRecord>(
       itemState.item = item
       itemState.index = i
       itemState.$index = i
-      node.__micraEach = true
       node.__micraItem = item
       node.__micraIndex = i
-      applyDirectives(node.__micraScan!, itemState, rawState, instance)
+      applyDirectives(node.__micraScan!, itemState, rawState)
       nextList[i] = node
       frag.append(node)
     }

package/src/dom/scan.ts

@@ -5,9 +5,9 @@
  * traversal that classifies every directive attribute in a single visit.
  *
  * Boundaries:
- *   - REJECT (skip subtree) on nested [data-component] — same semantics as
- *     the old `filterOwn` helper, but applied during the walk so we don't
- *     even *visit* those nodes.
+ *   - REJECT (skip subtree) on nested [data-component] — a parent component
+ *     never processes directives owned by a nested child. Applied during the
+ *     walk so we don't even *visit* those nodes.
  *   - <template> contents are not visited (browser TreeWalker default).
  *     `<template data-each>` itself IS visited and classified into scan.each;
  *     its children are processed by each.ts on every render — fresh rows

package/src/types.ts

@@ -199,8 +199,6 @@ export interface MicraElement extends HTMLElement {
   __micraModel?: true       // data-model listener bound
   __micraEvents?: true      // data-on listeners bound
   __micraAtBound?: true     // @event shorthand bound (per-element)
-  __micraKey?: unknown      // keyed-diff key
-  __micraEach?: true        // belongs to a no-key each list
   __micraScan?: ScanIndex   // single-pass scan result (cached after 1st render)
   __micraItem?: StateRecord  // keyed row: last-rendered item ref (for skip check)
   __micraIndex?: number      // keyed row: last-rendered index (for skip check)

package/src/utils/expr.ts

@@ -52,10 +52,9 @@ const SIMPLE_PATH = /^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$/
  * 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',
-])
+const ALLOWED_GLOBALS = new Set<string>(
+  'Math,JSON,Date,String,Number,Boolean,Array,Object,parseInt,parseFloat,isNaN,isFinite,NaN,Infinity,undefined'.split(','),
+)
 
 /**
  * Outer `with()` scope. Its `has` trap claims every non-whitelisted identifier

package/src/dom/query.ts

@@ -1,50 +0,0 @@
-/**
- * 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 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
-      node = node.parentElement
-    }
-    return true
-  })
-}