micra.js 1.0.0 → 2.0.0

package/README.md

@@ -27,7 +27,7 @@ Use it when you want:
   <button @click="increment">+</button>
 </div>
 
-<script src="https://unpkg.com/micra.js/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js/dist/micra.min.js"></script>
 <script>
   Micra.define('counter', {
     state: { count: 0 },
@@ -44,7 +44,7 @@ Use it when you want:
 ### CDN
 
 ```html
-<script src="https://unpkg.com/micra.js/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js/dist/micra.min.js"></script>
 ```
 
 ### npm
@@ -54,7 +54,7 @@ npm install micra.js
 ```
 
 ```ts
-import * as Micra from 'micra'
+import * as Micra from 'micra.js'
 ```
 
 ## Basic usage
@@ -71,7 +71,7 @@ A counter mounted automatically from `data-component`:
 ```
 
 ```ts
-import * as Micra from 'micra'
+import * as Micra from 'micra.js'
 
 Micra.define('counter', {
   state: { count: 0 },
@@ -164,3 +164,6 @@ this.on(event, handler)
 - [SSR](./docs/ssr.md)
 - [Examples](./docs/examples.md)
 - [API reference](./docs/api-reference.md)
+- Recipes:
+  - [Todo app](./docs/recipes/todo-app.md)
+  - [Server-sent events (SSE)](./docs/recipes/sse.md)

package/dist/dom/events.d.ts

@@ -3,10 +3,12 @@
  *
  * 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, StateRecord } from '../types';
 /**
@@ -22,7 +24,7 @@ import type { InternalInstance, StateRecord } from '../types';
 export declare function bindDataOn<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;
 /**
  * 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
@@ -34,6 +36,9 @@ export declare function bindAtEvents<S extends StateRecord>(root: Element, insta
  * 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

package/dist/dom/query.d.ts

@@ -21,3 +21,9 @@ export declare function queryAll(root: ParentNode, sel: string): Element[];
  * owned by that nested component, not by root's component — so we skip it.
  */
 export declare function queryOwn(root: Element, attr: string): Element[];
+/**
+ * Like queryOwn but accepts an arbitrary CSS selector. Used by bindAtEvents
+ * which scans `*` for `@`-prefixed attribute names (no attribute selector exists
+ * for those).
+ */
+export declare function queryOwnAll(root: Element, sel: string): Element[];

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

@@ -1,4 +1,4 @@
-/* Micra.js v1.0.0 — https://github.com/micra-js/micra — MIT */
+/* Micra.js v2.0.0 — https://github.com/micra-js/micra — MIT */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -66,9 +66,9 @@ async function micraFetch(url, options = {}) {
     }
     if (Object.keys(params).length)
       finalUrl += (url.includes("?") ? "&" : "?") + new URLSearchParams(params);
-  } else {
+  } else if (options.body !== void 0) {
     headers["Content-Type"] = "application/json";
-    body = JSON.stringify(options.body !== void 0 ? options.body : options);
+    body = JSON.stringify(options.body);
   }
   const res = await fetch(finalUrl, {
     method,
@@ -115,10 +115,69 @@ function debug() {
 
 // src/utils/expr.ts
 var exprCache = /* @__PURE__ */ new Map();
+var warnedRuntime = /* @__PURE__ */ new Set();
 var SIMPLE_PATH = /^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$/;
+var ALLOWED_GLOBALS = /* @__PURE__ */ new Set([
+  "Math",
+  "JSON",
+  "Date",
+  "String",
+  "Number",
+  "Boolean",
+  "Array",
+  "Object",
+  "parseInt",
+  "parseFloat",
+  "isNaN",
+  "isFinite",
+  "NaN",
+  "Infinity",
+  "undefined"
+]);
+var PARAM_S = "$s";
+var PARAM_SAFE = "$safe";
+var SAFE_OUTER = new Proxy(/* @__PURE__ */ Object.create(null), {
+  has(_target, key) {
+    if (typeof key !== "string") return false;
+    if (key === PARAM_S || key === PARAM_SAFE) return false;
+    return !ALLOWED_GLOBALS.has(key);
+  },
+  get() {
+    return void 0;
+  }
+});
+var safeWrapCache = /* @__PURE__ */ new WeakMap();
+var OBJ_PROTO_KEYS = new Set(Object.getOwnPropertyNames(Object.prototype));
+function safeStateWrap(state) {
+  const cached = safeWrapCache.get(state);
+  if (cached) return cached;
+  const wrapped = new Proxy(state, {
+    has(target, key) {
+      return safeStateHas(target, key);
+    },
+    get(target, key) {
+      return Reflect.get(target, key);
+    }
+  });
+  safeWrapCache.set(state, wrapped);
+  return wrapped;
+}
+function safeStateHas(state, key) {
+  if (typeof key !== "string") return false;
+  if (!Reflect.has(state, key)) return false;
+  if (!OBJ_PROTO_KEYS.has(key)) return true;
+  let obj = state;
+  while (obj && obj !== Object.prototype) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) return true;
+    obj = Object.getPrototypeOf(obj);
+  }
+  return false;
+}
 function evalExpr(expr, state) {
   if (SIMPLE_PATH.test(expr)) {
-    return expr.split(".").reduce(
+    const parts = expr.split(".");
+    if (!safeStateHas(state, parts[0])) return void 0;
+    return parts.reduce(
       (obj, key) => obj != null ? obj[key] : void 0,
       state
     );
@@ -127,7 +186,7 @@ function evalExpr(expr, state) {
     try {
       exprCache.set(
         expr,
-        new Function("$s", `with($s){return (${expr})}`)
+        new Function("$s", "$safe", `with($safe){with($s){return (${expr})}}`)
       );
     } catch {
       warn(`invalid expression "${expr}"`);
@@ -135,8 +194,12 @@ function evalExpr(expr, state) {
     }
   }
   try {
-    return exprCache.get(expr)(state);
-  } catch {
+    return exprCache.get(expr)(safeStateWrap(state), SAFE_OUTER);
+  } catch (e) {
+    if (!warnedRuntime.has(expr)) {
+      warnedRuntime.add(expr);
+      warn(`runtime error in "${expr}": ${e.message}`);
+    }
     return void 0;
   }
 }
@@ -152,8 +215,10 @@ function on(event, handler) {
   return () => off(event, handler);
 }
 function off(event, handler) {
-  var _a;
-  (_a = _bus.get(event)) == null ? void 0 : _a.delete(handler);
+  const set = _bus.get(event);
+  if (!set) return;
+  set.delete(handler);
+  if (set.size === 0) _bus.delete(event);
 }
 function emit(event, payload) {
   var _a;
@@ -194,7 +259,13 @@ function queryAll(root, sel) {
   return Array.from(root.querySelectorAll(sel));
 }
 function queryOwn(root, attr) {
-  return queryAll(root, `[${attr}]`).filter((el) => {
+  return filterOwn(root, queryAll(root, `[${attr}]`));
+}
+function queryOwnAll(root, sel) {
+  return filterOwn(root, queryAll(root, sel));
+}
+function filterOwn(root, els) {
+  return els.filter((el) => {
     let node = el.parentElement;
     while (node && node !== root) {
       if (node.hasAttribute("data-component")) return false;
@@ -214,15 +285,25 @@ function applyHtml(el, expr, state) {
   var _a;
   el.innerHTML = String((_a = evalExpr(expr, state)) != null ? _a : "");
 }
-function applyIf(el, expr, state) {
+function applyIf(binding, state) {
+  const el = binding.el;
+  const truthy = !!evalExpr(binding.expr, state);
+  if (truthy) {
+    const ph = binding.placeholder;
+    if (ph && ph.parentNode) ph.parentNode.replaceChild(el, ph);
+  } else {
+    const parent = el.parentNode;
+    if (parent) {
+      if (!binding.placeholder) binding.placeholder = document.createComment("if");
+      parent.replaceChild(binding.placeholder, el);
+    }
+  }
+}
+function applyShow(el, expr, state) {
   el.style.display = evalExpr(expr, state) ? "" : "none";
 }
-function applyBind(el, expr, state) {
-  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();
+function applyBind(el, pairs, state) {
+  for (const [attr, valExpr] of pairs) {
     const val = evalExpr(valExpr, state);
     if (attr === "class") {
       el.className = String(val != null ? val : "");
@@ -242,21 +323,28 @@ function applyBind(el, expr, state) {
     }
   }
 }
-function applyClass(el, expr, state) {
-  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, pairs, state) {
+  for (const [cls, valExpr] of pairs) {
     el.classList.toggle(cls, Boolean(evalExpr(valExpr, state)));
   }
 }
+function parsePairs(expr) {
+  const out = [];
+  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, key, rawState) {
   const html = el;
-  if (document.activeElement !== el) {
-    html.value = rawState[key] == null ? "" : String(rawState[key]);
-  }
+  const stateVal = rawState[key];
+  const desired = stateVal == null ? "" : String(stateVal);
+  if (html.value !== desired) html.value = desired;
 }
 function buildCache(root) {
   const pick = (attr) => {
@@ -265,14 +353,15 @@ function buildCache(root) {
     if ((_a = root.hasAttribute) == null ? void 0 : _a.call(root, attr)) els.unshift(root);
     return els.filter((el) => !el.closest("template")).map((el) => ({ el, expr: el.getAttribute(attr) }));
   };
+  const pickPairs = (attr) => pick(attr).map((b) => ({ ...b, pairs: parsePairs(b.expr) }));
   return {
     text: pick("data-text"),
     html: pick("data-html"),
     if: pick("data-if"),
     show: pick("data-show"),
-    bind: pick("data-bind"),
+    bind: pickPairs("data-bind"),
     model: pick("data-model"),
-    class: pick("data-class")
+    class: pickPairs("data-class")
   };
 }
 function applyDirectives(root, state, rawState, _instance) {
@@ -285,35 +374,56 @@ function applyDirectives(root, state, rawState, _instance) {
   applyFromList(el.__micraCache, state, rawState);
 }
 function applyFromList(cache, state, rawState) {
+  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));
 }
 function buildFragmentList(frag) {
   const pick = (attr) => queryAll(frag, `[${attr}]`).filter((el) => !el.closest("template")).map((el) => ({ el, expr: el.getAttribute(attr) }));
+  const pickPairs = (attr) => pick(attr).map((b) => ({ ...b, pairs: parsePairs(b.expr) }));
   return {
     text: pick("data-text"),
     html: pick("data-html"),
     if: pick("data-if"),
     show: pick("data-show"),
-    bind: pick("data-bind"),
+    bind: pickPairs("data-bind"),
     model: pick("data-model"),
-    class: pick("data-class")
+    class: pickPairs("data-class")
   };
 }
 function validateDirectives(root) {
+  var _a, _b;
   queryOwn(root, "data-each").forEach((el) => {
-    if (!el.hasAttribute("data-key")) {
+    const tmpl = el;
+    if (!el.hasAttribute("data-key") && !tmpl.__micraNoKeyWarned) {
+      tmpl.__micraNoKeyWarned = true;
       warn(`data-each="${el.getAttribute("data-each")}" has no data-key \u2014 keyed diff disabled. Add data-key="id" for better performance.`);
     }
   });
+  const bindEls = queryOwn(root, "data-bind");
+  if (((_a = root.hasAttribute) == null ? void 0 : _a.call(root, "data-bind")) && !bindEls.includes(root)) bindEls.unshift(root);
+  for (const el of bindEls) {
+    const spec = (_b = el.getAttribute("data-bind")) != null ? _b : "";
+    const hasClassBind = spec.split(",").some((p) => {
+      var _a2;
+      return ((_a2 = p.trim().split(":")[0]) == null ? void 0 : _a2.trim()) === "class";
+    });
+    if (hasClassBind && el.hasAttribute("data-class")) {
+      warn(`element has both data-bind="class:..." and data-class \u2014 they fight on every render. Use one.`);
+    }
+  }
 }
 
 // src/dom/events.ts
+function track(instance, el, type, fn) {
+  var _a;
+  el.addEventListener(type, fn);
+  ((_a = instance.__micraListeners) != null ? _a : instance.__micraListeners = []).push({ el, type, fn });
+}
 function bindDataOn(root, instance) {
   var _a, _b;
   const isFragment = root.nodeType === 11;
@@ -329,7 +439,7 @@ function bindDataOn(root, instance) {
       const [evSpec, method] = part.trim().split(":");
       if (!evSpec || !method) continue;
       const [evName, ...mods] = evSpec.split(".");
-      el.addEventListener(evName, (e) => {
+      track(instance, el, evName, (e) => {
         if (mods.includes("prevent")) e.preventDefault();
         if (mods.includes("stop")) e.stopPropagation();
         if (mods.includes("self") && e.target !== el) return;
@@ -341,16 +451,18 @@ function bindDataOn(root, instance) {
   }
 }
 function bindAtEvents(root, instance) {
-  const mRoot = root;
-  if (mRoot.__micraAtScanned) return;
-  mRoot.__micraAtScanned = true;
-  const all = queryAll(root, "*");
+  const isFragment = root.nodeType === 11;
+  const all = isFragment ? queryAll(root, "*") : queryOwnAll(root, "*");
+  if (!isFragment && !all.includes(root)) all.unshift(root);
   for (const el of all) {
+    const mEl = el;
+    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) => {
+      track(instance, el, evSpec, (e) => {
         if (rest.includes("prevent")) e.preventDefault();
         if (rest.includes("stop")) e.stopPropagation();
         if (rest.includes("self") && e.target !== el) return;
@@ -358,7 +470,9 @@ function bindAtEvents(root, instance) {
         if (typeof fn === "function") fn.call(instance, e);
         else warn(`method "${method}" not found`);
       });
+      bound = true;
     }
+    if (bound) mEl.__micraAtBound = true;
   }
 }
 function bindModels(root, instance) {
@@ -371,14 +485,22 @@ function bindModels(root, instance) {
     mEl.__micraModel = true;
     const key = (_a = el.dataset["model"]) != null ? _a : "";
     const tag = el.tagName;
+    const inputEl = el;
+    const inputType = inputEl.type;
     const update = () => {
-      const val = tag === "INPUT" && el.type === "checkbox" ? el.checked : el.value;
+      let val;
+      if (tag === "INPUT" && inputType === "checkbox") {
+        val = inputEl.checked;
+      } else if (tag === "INPUT" && (inputType === "number" || inputType === "range")) {
+        val = inputEl.value === "" ? null : inputEl.valueAsNumber;
+      } else {
+        val = inputEl.value;
+      }
+      ;
       instance.state[key] = val;
     };
-    el.addEventListener(
-      tag === "SELECT" || el.type === "radio" ? "change" : "input",
-      update
-    );
+    const evType = tag === "SELECT" || inputType === "radio" ? "change" : "input";
+    track(instance, el, evType, update);
   }
 }
 
@@ -401,6 +523,7 @@ function renderList(root, state, rawState, instance) {
     const marker = tmpl.__micraMarker;
     const keyMap = tmpl.__micraNodes;
     const parent = marker.parentNode;
+    if (!parent) return;
     if (!Array.isArray(items)) {
       tmpl.__micraList.forEach((n) => n.remove());
       tmpl.__micraList = [];
@@ -417,9 +540,18 @@ function renderList(root, state, rawState, instance) {
 function renderKeyed(tmpl, items, keyAttr, marker, keyMap, parent, state, rawState, instance) {
   const nextKeys = /* @__PURE__ */ new Set();
   const nextNodes = [];
+  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)} \u2014 rows will collide`);
+      warnedDupKey = true;
+    }
     nextKeys.add(key);
     let node = keyMap.get(key);
     if (!node) {
@@ -522,15 +654,35 @@ function mount(selector, definition) {
   let isRendering = false;
   const schedule = createScheduler(() => instance.render());
   instance.state = createReactiveState(rawState, schedule);
+  const boundMethods = /* @__PURE__ */ new Map();
   const exprState = new Proxy(rawState, {
     get(target, key) {
-      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].bind(instance);
+        boundMethods.set(key, bound);
+        return bound;
+      }
       return void 0;
+    },
+    has(target, key) {
+      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 \u2014 mutation inside a directive expression is ignored. Move state writes to a method.");
+        warnedReentry = true;
+      }
+      return;
+    }
     isRendering = true;
     try {
       applyDirectives(root, exprState, rawState, instance);
@@ -544,8 +696,22 @@ function mount(selector, definition) {
     }
   };
   instance.destroy = function() {
-    var _a2;
-    (_a2 = instance.__micraSubs) == null ? void 0 : _a2.forEach((unsub) => unsub());
+    var _a2, _b;
+    if (instance.__micraDestroyed) return;
+    instance.__micraDestroyed = true;
+    (_a2 = instance.__micraListeners) == null ? void 0 : _a2.forEach(({ el, type, fn }) => el.removeEventListener(type, fn));
+    instance.__micraListeners = [];
+    const clearFlags = (el) => {
+      const m = el;
+      delete m.__micraEvents;
+      delete m.__micraAtBound;
+      delete m.__micraModel;
+      delete m.__micraCache;
+    };
+    clearFlags(root);
+    root.querySelectorAll("*").forEach(clearFlags);
+    (_b = instance.__micraSubs) == null ? void 0 : _b.forEach((unsub) => unsub());
+    instance.__micraSubs = [];
     if (typeof definition.onDestroy === "function")
       definition.onDestroy.call(instance);
     _instances.delete(root);