micra.js 2.3.2 → 2.4.0

package/dist/utils/expr.d.ts

@@ -1,37 +1,44 @@
 /**
- * src/utils/expr.ts — JS expression evaluator.
+ * src/utils/expr.ts — CSP-safe JS-expression evaluator.
  *
- * Responsibilities:
- *   - Compile expression strings into cached functions
- *   - Evaluate them against a state object
- *   - Fast-path for simple property lookups
- *   - Shadow non-state identifiers so directive expressions cannot reach
- *     globals like `window`, `fetch`, `constructor`, etc. A small whitelist
- *     of utility globals (Math, JSON, Date, ...) remains accessible.
+ * Directive expressions (`data-text="count > 0"`, `data-class="x:a === b"`, …)
+ * are parsed into a small AST and walked by an interpreter. There is NO
+ * `new Function` / `eval` anywhere — so Micra runs under a strict
+ * Content-Security-Policy (`default-src 'self'`, no `unsafe-eval`).
  *
  * LLM NOTE: This module is PURE. It does not touch the DOM or mutate state.
  *
  * Security model:
- *   Directive expressions are JavaScript — they are compiled via `new Function`
- *   and run with full JS capability except that bare identifiers must resolve
- *   to either a state key, a component instance method, or one of
- *   ALLOWED_GLOBALS. This blocks the `constructor.constructor("...")()` chain
- *   and accidental access to `window` / `document` / `fetch`. It does NOT
- *   sandbox method calls — if a component method itself touches `window`,
- *   that still works. Treat directive templates as trusted code regardless.
+ *   The interpreter can only reach: top-level state keys, component methods,
+ *   and a whitelist of utility globals (Math, JSON, Date, …). A bare
+ *   identifier that is none of those resolves to `undefined` — `window`,
+ *   `document`, `fetch`, `eval`, `constructor` are unreachable *by
+ *   construction* (there is no scope that contains them), not by shadowing.
+ *   Member access additionally refuses the prototype-escape property names
+ *   (`__proto__`, `constructor`, `prototype`), closing the
+ *   `item.constructor.constructor("…")()` chain that the old `with()`-based
+ *   evaluator left open. Method calls still run real JS — if a component
+ *   method touches `window`, that works; treat directive templates as
+ *   trusted code regardless.
+ *
+ * Grammar (precedence low→high):
+ *   ternary ?:  |  ||  |  &&  |  == != === !==  |  < <= > >=  |  + -  |
+ *   * / %  |  unary ! -  |  call() / member.  |  primary
+ *   primary = number | string | true | false | null | undefined |
+ *             identifier | ( expr )
  */
 import type { StateRecord } from '../types';
 /**
- * Evaluate a JS expression string against a state object.
+ * Evaluate an 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.
+ * Cached by string. Simple dot-paths take a fast path that skips tokenizing.
+ * Parse errors warn once and thereafter resolve to `undefined`; runtime
+ * errors (e.g. calling a non-function) warn once per expression.
  *
  * @example
- * evalExpr('count > 0', { count: 5 })   // → true
- * evalExpr('user.name', { user: { name: 'Alice' } }) // → 'Alice'
- * evalExpr('price * qty', { price: 9.99, qty: 3 })   // → 29.97
+ * evalExpr('count > 0', { count: 5 })                 // → true
+ * evalExpr('user.name', { user: { name: 'Alice' } })  // → 'Alice'
+ * evalExpr('price * qty', { price: 9.99, qty: 3 })     // → 29.97
  */
 export declare function evalExpr(expr: string, state: StateRecord): unknown;
 /** @internal Consistent warning prefix. */

package/llms-full.txt

@@ -2,12 +2,12 @@
 
 This file follows the llmstxt.org "expanded" convention: it inlines code recipes so LLMs that crawl this URL get a complete training surface in one read. The short version is `llms.txt` in the same directory.
 
-> Lightweight reactive TypeScript framework for server-rendered apps and small SaaS frontends. ~5 KB gzip. No build step required.
+> Lightweight reactive TypeScript framework for server-rendered apps and small SaaS frontends. ~7 KB gzip. No build step required.
 
 ## Install
 
 ```bash
-npm install micra.js@^2.3.2
+npm install micra.js@^2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.0/dist/micra.min.js"></script>
 ```
 
 This exposes a global `Micra` object.
@@ -30,7 +30,7 @@ This exposes a global `Micra` object.
 ## When to use Micra.js
 
 - Server-rendered pages (Rails, Laravel, Django, Phoenix, etc.) needing a small amount of reactivity
-- Bundle-size-sensitive (~5 KB vs 45+ KB React)
+- Bundle-size-sensitive (~7 KB vs 45+ KB React)
 - No build step desired — drop a `<script>` tag
 - Existing HTML that just needs reactive enhancement
 
@@ -131,7 +131,7 @@ Modifiers: `.prevent`, `.stop`, `.self` (event-only — no key modifiers).
 - Whitelisted globals: `Math`, `JSON`, `Date`, `String`, `Number`, `Boolean`, `Array`, `Object`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `NaN`, `Infinity`, `undefined`
 - Inside `data-each`: `item`, `index`, `$index`
 
-Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeout`) resolves to `undefined` by design — security shadowing.
+Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeout`) resolves to `undefined` by design. Expressions are parsed + interpreted (no `new Function`/`eval`), so Micra runs under a strict CSP. Inside `@event` you may also pass arguments: `@click="select(item.id)"`, `@input="set($event.target.value)"`.
 
 ---
 
@@ -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.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.0/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.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.0/dist/micra.min.js"></script>
 <script>
   Micra.define('counter', {
     state: { count: 0 },
@@ -596,7 +596,7 @@ 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",
+    to: "https://cdn.jsdelivr.net/npm/micra.js@2.4.0/dist/micra.esm.js",
     preload: true
 ```
 
@@ -717,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.2/dist/micra.min.js"></script>
+<script src="https://unpkg.com/micra.js@2.4.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.3.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.0/dist/micra.min.js"></script>
 ```
 
 # Final checklist

package/llms.txt

@@ -1,13 +1,13 @@
 # Micra.js
 
-> Lightweight reactive TypeScript framework for server-rendered apps and small SaaS frontends. ~5 KB gzip. No build step required.
+> Lightweight reactive TypeScript framework for server-rendered apps and small SaaS frontends. ~7 KB gzip. No build step required.
 >
 > **For LLM code generation:** read the expanded version at https://github.com/denisfl/micra.js/blob/master/llms-full.txt — it includes 10 full inline recipes and an anti-pattern reference. The recipes are the canonical answers to common requests like "build a todo app" or "build a search-with-debounce".
 
 ## When to use Micra.js instead of React/Vue
 
 - You have a server-rendered page (Laravel, Rails, Django, etc.) and need a small amount of reactivity
-- Bundle size matters (~5 KB gzip vs ~45 KB React)
+- Bundle size matters (~7 KB gzip vs ~45 KB React)
 - You don't need a full SPA or client-side routing
 - You want to drop a `<script>` tag and go
 - You need reactive directives on existing HTML without rewriting templates
@@ -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.2/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.4.0/dist/micra.min.js"></script>
 ```
 
 This exposes a global `Micra` object.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "micra.js",
-  "version": "2.3.2",
-  "description": "Lightweight reactive UI framework for server-rendered pages — reactive state, directives, event bus. < 5 KB gzip.",
+  "version": "2.4.0",
+  "description": "Lightweight reactive UI framework for server-rendered pages — reactive state, directives, event bus. < 7 KB gzip.",
   "type": "module",
   "main": "./dist/micra.cjs.js",
   "module": "./dist/micra.esm.js",

package/src/core/mount.ts

@@ -153,6 +153,10 @@ export function mount<S extends StateRecord, M>(
       );
     },
   });
+  // Exposed for events.ts so `@click="select(item.id)"` can evaluate the call
+  // against component state + methods. Row elements eval against their own
+  // `_itemState` (which prototype-chains to this); non-row elements use this.
+  instance.__micraExpr = exprState;
 
   let warnedReentry = false;
   instance.render = function () {

package/src/dom/events.ts

@@ -20,7 +20,7 @@ import type {
   MicraElement,
   StateRecord,
 } from '../types'
-import { warn } from '../utils/expr'
+import { evalExpr, warn } from '../utils/expr'
 
 /** @internal Attach a DOM listener and track it on the instance for destroy(). */
 function track<S extends StateRecord>(
@@ -33,6 +33,38 @@ function track<S extends StateRecord>(
   ;(instance.__micraListeners ??= []).push({ el, type, fn })
 }
 
+/**
+ * Run an event handler. Two shapes, both used by `data-on` and `@event`:
+ *   - bare method name   `save`            → instance.save(e)
+ *   - call expression    `select(item.id)` → evaluated against an event scope
+ *     (row `item` if inside `data-each`, `$event`/`event`, component methods).
+ *     Call expressions are the recommended form for `@event`; in `data-on` the
+ *     handler separator is `,` so multi-argument calls there are not supported.
+ */
+function runHandler<S extends StateRecord>(
+  instance: InternalInstance<S>,
+  el: Element,
+  value: string,
+  e: Event,
+): void {
+  if (value.includes('(')) {
+    // Build the scope: nearest ancestor-or-self row itemState (it already
+    // prototype-chains to the component's expr scope), else the expr scope.
+    let base: StateRecord | undefined
+    for (let n: Element | null = el; n && !base; n = n.parentElement) {
+      base = (n as MicraElement)._itemState
+    }
+    const scope = Object.create(base ?? instance.__micraExpr ?? null) as StateRecord
+    scope['$event'] = e
+    scope['event'] = e
+    evalExpr(value, scope) // performs the call; return value ignored
+    return
+  }
+  const fn = instance[value]
+  if (typeof fn === 'function') (fn as (e: Event) => void).call(instance, e)
+  else warn(`method "${value}" not found`)
+}
+
 // ── data-on ───────────────────────────────────────────────────────────────────
 
 /**
@@ -62,15 +94,13 @@ export function bindDataOn<S extends StateRecord>(
       if (!evSpec || !method) continue
 
       const [evName, ...mods] = evSpec.split('.')
+      const handler = method.trim()
 
       track(instance, el, 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`)
+        runHandler(instance, el, handler, e)
       })
     }
   }
@@ -101,16 +131,13 @@ export function bindAtEvents<S extends StateRecord>(
     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()
+      const handler = attr.value.trim()
 
       track(instance, el, 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`)
+        runHandler(instance, el, handler, e)
       })
       bound = true
     }

package/src/index.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.5 KB minified+gzipped
+ * Size target: < 7 KB minified+gzipped
  *
  * @module Micra
  */

package/src/types.ts

@@ -294,5 +294,6 @@ export interface InternalInstance<S extends StateRecord = StateRecord>
   __micraSubs?: UnsubFn[]
   __micraListeners?: TrackedListener[]
   __micraDestroyed?: true
+  __micraExpr?: StateRecord  // expression scope (state + bound methods) for @event call args
   [key: string]: unknown
 }