micra.js 2.3.0 → 2.3.1

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to Micra.js will be documented in this file. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning follows
 [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.1] — 2026-05-30
+
+### Performance
+
+- **Batch scheduler now uses `queueMicrotask` instead of
+  `Promise.resolve().then(...)`.** Each render batch enqueues a single
+  microtask instead of allocating a Promise plus a reaction job, and the
+  flush callback is hoisted out of the hot path so it isn't re-created on
+  every `schedule()` call. Behaviour is identical — same microtask timing,
+  same write-collapsing. No public-API change.
+
+### Internal — dead-code removal
+
+- Removed the `src/dom/query.ts` module (`queryAll` / `queryOwn` /
+  `queryOwnAll` / `filterOwn`). It had no importers since the 2.2.0
+  single-pass scan replaced per-render `querySelectorAll` calls with one
+  `TreeWalker` traversal — esbuild already tree-shook it out of the
+  bundle, so this is a source-only cleanup.
+- Removed two dead bookkeeping writes: `node.__micraEach` and
+  `node.__micraKey` were assigned during list rendering but never read
+  (keys live in the keyed-diff `Map`; the no-key path doesn't tag rows).
+  Dropped the matching fields from `MicraElement`.
+- Dropped the unused `instance` parameter from `applyDirectives` — it was
+  never referenced in the body.
+
+### Docs
+
+- New [Rails + Micra recipe](https://github.com/denisfl/micra.js/blob/master/docs/recipes/rails.md)
+  (`docs/recipes/rails.md` + a site page): manual importmap integration,
+  the `micra-rails` gem with its caveats, a Tasks board demonstrating SSR
+  props / CSRF-attached `this.fetch` / cross-component bus, and the Turbo
+  Drive / Streams / Frames mount-and-cleanup story.
+- README gains a **TypeScript** section spelling out what's checked
+  end-to-end (state, methods, event payloads) versus what isn't (the
+  expression strings inside `data-*` attributes).
+- Landing page gains **Speed** (cross-library benchmark cards) and **AI
+  sandboxes** (copy-the-LLM-prompt) sections.
+
+### Bundle
+
+- **5.5 KB gzip** (5582 bytes) — a few bytes lighter than 2.3.0 after the
+  dead-code removal.
+
 ## [2.3.0] — 2026-05-30
 
 ### TypeScript — type-safe event bus

package/README.md

@@ -71,6 +71,48 @@ npm install micra.js
 import * as Micra from "micra.js";
 ```
 
+### TypeScript
+
+The npm package ships its own `dist/index.d.ts` — no `@types/micra.js` package
+needed. Inside every method body and lifecycle hook, both `this.state.X` and
+`this.someMethod()` are fully checked at the call site (both `state` and the
+method set are inferred from the literal you pass to `Micra.define`).
+
+```ts
+import * as Micra from "micra.js";
+
+Micra.define("counter", {
+  state: { count: 0 },
+  inc() {
+    this.state.count++;   // ✓ number
+    this.dec();           // ✓ inferred sibling method
+    // this.foo();        // ✗ Property 'foo' does not exist
+  },
+  dec() { this.state.count--; },
+});
+
+// Type-safe event bus via declaration merging
+declare module "micra.js" {
+  interface MicraEvents {
+    "cart:updated": { count: number };
+    "modal:close":  void;
+  }
+}
+
+Micra.emit("cart:updated", { count: 3 });    // ✓
+Micra.emit("cart:updated", { count: "3" });  // ✗ type error
+Micra.emit("modal:close");                   // ✓ void → no args
+```
+
+**What's checked:** imports, state shape, method names, event-bus payloads,
+lifecycle hooks, refs, `Micra.mount()` return type.
+
+**What's not:** the expression strings inside `data-text="…"` / `@click="…"`
+attributes — those are plain HTML to the IDE and validated only at mount
+time. Same trade-off as Alpine.js `x-*` and petite-vue `v-*`; the
+alternatives are JSX or a single-file-component compiler, neither of which
+Micra ships.
+
 ## Basic usage
 
 A counter mounted automatically from `data-component`:
@@ -183,6 +225,7 @@ this.on(event, handler)
   - [Todo app](./docs/recipes/todo-app.md)
   - [Server-sent events (SSE)](./docs/recipes/sse.md)
   - [htmx bridge](./docs/recipes/htmx.md)
+  - [Rails + Micra](./docs/recipes/rails.md)
 
 ## Code generation with LLMs
 

package/dist/core/reactive.d.ts

@@ -23,6 +23,10 @@ export declare function createReactiveState<S extends StateRecord>(obj: S, sched
  * 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

package/dist/dom/directives.d.ts

@@ -11,7 +11,7 @@
  *
  * Important: this module does NOT handle data-each — see dom/each.ts.
  */
-import type { InternalInstance, ScanIndex, StateRecord } from '../types';
+import type { ScanIndex, StateRecord } from '../types';
 import { warn } from '../utils/expr';
 /**
  * Apply all non-each directives to a component subtree.
@@ -23,7 +23,7 @@ import { warn } from '../utils/expr';
  * @param state    - Expression state (may include item/index for each rows)
  * @param rawState - Raw (non-proxy) state for model sync
  */
-export declare function applyDirectives<S extends StateRecord>(scan: ScanIndex, state: StateRecord, rawState: StateRecord, _instance: InternalInstance<S>): void;
+export declare function applyDirectives(scan: ScanIndex, state: StateRecord, rawState: StateRecord): void;
 /**
  * Validate directive usage and emit dev warnings.
  * Called once after the initial render of a component, with the already-built

package/dist/dom/scan.d.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/dist/micra.cjs.js

@@ -1,4 +1,4 @@
-/* Micra.js v2.3.0 — https://github.com/micra-js/micra — MIT */
+/* Micra.js v2.3.1 — https://github.com/micra-js/micra — MIT */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -253,13 +253,14 @@ function createReactiveState(obj, schedule, onKey) {
 }
 function createScheduler(render) {
   let pending = false;
+  const flush = () => {
+    pending = false;
+    render();
+  };
   return function schedule() {
     if (pending) return;
     pending = true;
-    Promise.resolve().then(() => {
-      pending = false;
-      render();
-    });
+    queueMicrotask(flush);
   };
 }
 
@@ -325,7 +326,7 @@ function applyModel(el, key, rawState) {
   const desired = stateVal == null ? "" : String(stateVal);
   if (html.value !== desired) html.value = desired;
 }
-function applyDirectives(scan, state, rawState, _instance) {
+function applyDirectives(scan, state, rawState) {
   for (const b of scan.if) applyIf(b, state);
   for (const b of scan.text) applyText(b.el, b.expr, state);
   for (const b of scan.html) applyHtml(b.el, b.expr, state);
@@ -608,7 +609,6 @@ function renderKeyed(tmpl, items, keyAttr, marker, keyMap, state, rawState, inst
     let node = keyMap.get(key);
     if (!node) {
       node = createRowNode(tmpl, state, instance);
-      node.__micraKey = key;
       keyMap.set(key, node);
     } else if (canSkipUnchanged && node.__micraItem === item && node.__micraIndex === index) {
       nextNodes.push(node);
@@ -621,7 +621,7 @@ function renderKeyed(tmpl, items, keyAttr, marker, keyMap, state, rawState, inst
     itemState.index = index;
     itemState.$index = index;
     const rowScan = (_a = node.__micraScan) != null ? _a : node.__micraScan = scanComponent(node);
-    applyDirectives(rowScan, itemState, rawState, instance);
+    applyDirectives(rowScan, itemState, rawState);
     nextNodes.push(node);
   }
   for (const [key, node] of keyMap) {
@@ -706,7 +706,7 @@ function renderNoKey(tmpl, items, marker, state, rawState, instance, canSkipUnch
     itemState.item = item;
     itemState.index = i;
     itemState.$index = i;
-    applyDirectives(node.__micraScan, itemState, rawState, instance);
+    applyDirectives(node.__micraScan, itemState, rawState);
     nextList[i] = node;
   }
   for (let i = nextLen; i < prevLen; i++) {
@@ -721,10 +721,9 @@ function renderNoKey(tmpl, items, marker, state, rawState, instance, canSkipUnch
       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);
     }
@@ -823,7 +822,7 @@ function mount(selector, definition) {
     try {
       const mRoot2 = root;
       const scan = (_a2 = mRoot2.__micraScan) != null ? _a2 : mRoot2.__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);