@hyperfixi/reactivity 2.4.0

package/src/caret-var.test.ts

@@ -0,0 +1,137 @@
+/**
+ * caret-var unit tests — `^name` read/write and inherited scope walking.
+ * The parse layer is exercised via the integration test; here we test the
+ * storage semantics in isolation via the Reactive API.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Reactive } from './signals';
+
+describe('caret-var storage', () => {
+  let r: Reactive;
+
+  beforeEach(() => {
+    r = new Reactive();
+  });
+
+  it('read returns undefined for an untouched name', () => {
+    const el = document.createElement('div');
+    expect(r.readCaret(el, 'any')).toBeUndefined();
+  });
+
+  it('write then read on the same element', () => {
+    const el = document.createElement('div');
+    r.writeCaret(el, 'counter', 1);
+    expect(r.readCaret(el, 'counter')).toBe(1);
+  });
+
+  it('inherited scope: child reads parent var', () => {
+    const grand = document.createElement('section');
+    const parent = document.createElement('article');
+    const child = document.createElement('p');
+    grand.appendChild(parent);
+    parent.appendChild(child);
+    r.writeCaret(grand, 'theme', 'dark');
+    expect(r.readCaret(child, 'theme')).toBe('dark');
+    expect(r.readCaret(parent, 'theme')).toBe('dark');
+    expect(r.readCaret(grand, 'theme')).toBe('dark');
+  });
+
+  it('write without explicit target updates the inherited owner', () => {
+    const outer = document.createElement('div');
+    const inner = document.createElement('span');
+    outer.appendChild(inner);
+    r.writeCaret(outer, 'x', 'a');
+    // From inner, no explicit target → walks up, finds outer as owner, updates it.
+    r.writeCaret(inner, 'x', 'b');
+    expect(r.readCaret(outer, 'x')).toBe('b');
+    expect(r.readCaret(inner, 'x')).toBe('b'); // inherited
+  });
+
+  it('shadowing requires explicit target to create a local owner', () => {
+    const outer = document.createElement('div');
+    const inner = document.createElement('span');
+    outer.appendChild(inner);
+    r.writeCaret(outer, 'x', 'outer-val');
+    // Explicit target = inner → creates a new owner on inner, shadowing outer.
+    r.writeCaret(inner, 'x', 'inner-val', inner);
+    expect(r.readCaret(inner, 'x')).toBe('inner-val');
+    expect(r.readCaret(outer, 'x')).toBe('outer-val');
+  });
+
+  it('write with explicit target bypasses inheritance walk', () => {
+    const parent = document.createElement('div');
+    const child = document.createElement('span');
+    parent.appendChild(child);
+    // Write from child but target parent explicitly.
+    r.writeCaret(child, 'pinned', 'yes', parent);
+    expect(r.readCaret(parent, 'pinned')).toBe('yes');
+    expect(r.readCaret(child, 'pinned')).toBe('yes'); // inherits
+  });
+
+  describe('dom-scope="isolated" boundary', () => {
+    it('read stops at an isolation boundary that does not define the var', () => {
+      const outer = document.createElement('div');
+      const boundary = document.createElement('article');
+      boundary.setAttribute('dom-scope', 'isolated');
+      const inner = document.createElement('span');
+      outer.appendChild(boundary);
+      boundary.appendChild(inner);
+
+      r.writeCaret(outer, 'theme', 'dark');
+      // Inner can't see outer's theme — boundary blocks the walk.
+      expect(r.readCaret(inner, 'theme')).toBeUndefined();
+      expect(r.readCaret(boundary, 'theme')).toBeUndefined();
+      // Outer itself is unaffected.
+      expect(r.readCaret(outer, 'theme')).toBe('dark');
+    });
+
+    it('boundary itself can define the var (read returns boundary value)', () => {
+      const outer = document.createElement('div');
+      const boundary = document.createElement('article');
+      boundary.setAttribute('dom-scope', 'isolated');
+      const inner = document.createElement('span');
+      outer.appendChild(boundary);
+      boundary.appendChild(inner);
+
+      r.writeCaret(outer, 'theme', 'dark');
+      r.writeCaret(boundary, 'theme', 'light', boundary);
+      // Inner sees boundary's local theme; outer's is shadowed.
+      expect(r.readCaret(inner, 'theme')).toBe('light');
+      expect(r.readCaret(boundary, 'theme')).toBe('light');
+      expect(r.readCaret(outer, 'theme')).toBe('dark');
+    });
+
+    it('write from inside boundary falls back to lookupRoot when no owner is reachable', () => {
+      const outer = document.createElement('div');
+      const boundary = document.createElement('article');
+      boundary.setAttribute('dom-scope', 'isolated');
+      const inner = document.createElement('span');
+      outer.appendChild(boundary);
+      boundary.appendChild(inner);
+
+      // Outer has count, but inner is inside the boundary — write from inner
+      // should NOT reach outer; it should land on inner (lookupRoot fallback).
+      r.writeCaret(outer, 'count', 99);
+      r.writeCaret(inner, 'count', 1);
+      expect(r.readCaret(inner, 'count')).toBe(1);
+      // Inner's value is on inner itself; outer's stays.
+      expect(r.readCaret(outer, 'count')).toBe(99);
+    });
+
+    it('two sibling boundaries hold independent ^var state', () => {
+      const root = document.createElement('div');
+      const a = document.createElement('article');
+      a.setAttribute('dom-scope', 'isolated');
+      const b = document.createElement('article');
+      b.setAttribute('dom-scope', 'isolated');
+      root.appendChild(a);
+      root.appendChild(b);
+
+      r.writeCaret(a, 'count', 1);
+      r.writeCaret(b, 'count', 2);
+      expect(r.readCaret(a, 'count')).toBe(1);
+      expect(r.readCaret(b, 'count')).toBe(2);
+    });
+  });
+});

package/src/caret-var.ts

@@ -0,0 +1,125 @@
+/**
+ * `^name` — DOM-scoped inherited variable.
+ *
+ * Upstream syntax:
+ *   ^counter              → read from nearest ancestor that has `counter` set
+ *   ^counter on #target   → read from (or near) #target
+ *   set ^counter to 42    → write to owner (or lookupRoot if not yet defined)
+ *
+ * Parse side: register `^` as a Pratt prefix operator. The handler consumes
+ * the identifier token and an optional `on <target>` clause, emitting a
+ * `caretVar` AST node.
+ *
+ * Eval side: `caretVar` node evaluator calls `reactive.readCaret(anchor,
+ * name)` which walks the DOM tree for the owner and records deps as it goes.
+ */
+
+import type { ASTNode, ExecutionContext } from './types';
+import { reactive } from './signals';
+
+export interface CaretVarNode extends ASTNode {
+  type: 'caretVar';
+  name: string;
+  onTarget: ASTNode | null;
+}
+
+interface CaretVarRuntime {
+  execute(node: ASTNode, ctx: ExecutionContext): Promise<unknown>;
+}
+
+/**
+ * Coerce a runtime-evaluated `on <target>` result to a single Element.
+ * Selector expressions resolve to an array of matched elements; bare
+ * `me`/`it`/`you`/identifier references resolve to single Elements. Take the
+ * first element of an array, or the value itself if it's already an Element.
+ */
+function coerceToElement(value: unknown): Element | null {
+  if (value instanceof Element) return value;
+  if (Array.isArray(value) && value[0] instanceof Element) return value[0];
+  return null;
+}
+
+/**
+ * Pratt prefix handler for `^`. Consumes the following identifier token and
+ * an optional `on <expr>` clause.
+ */
+export function parseCaretPrefix(token: unknown, ctx: unknown): ASTNode {
+  // `ctx` is hyperfixi's PrattContext: { peek, advance, parseExpr, isStopToken, atEnd }.
+  const pctx = ctx as {
+    peek(): { value?: string; kind?: string } | undefined;
+    advance(): { value: string; kind?: string };
+    parseExpr(minBp: number): ASTNode;
+  };
+  const ident = pctx.advance();
+  if (!ident || !ident.value) {
+    throw new Error("Expected identifier after '^'");
+  }
+  let onTarget: ASTNode | null = null;
+  const next = pctx.peek();
+  if (next && next.value === 'on') {
+    pctx.advance(); // consume 'on'
+    // Binding power 86 — higher than standard comparisons so `^x on me` doesn't
+    // over-consume into surrounding expressions.
+    onTarget = pctx.parseExpr(86);
+  }
+  const startTok = token as { start?: number; end?: number; line?: number; column?: number };
+  return {
+    type: 'caretVar',
+    name: ident.value,
+    onTarget,
+    start: startTok?.start ?? 0,
+    end: startTok?.end ?? 0,
+    line: startTok?.line,
+    column: startTok?.column,
+  } as CaretVarNode;
+}
+
+/**
+ * Build a node evaluator for `caretVar` bound to a specific runtime. The
+ * evaluator walks up from the resolved anchor element, tracking every element
+ * visited so writes at any ancestor notify dependent effects.
+ *
+ * Capturing `runtime` via a factory closure (matching live/when/bind) keeps
+ * the evaluator independent of any module-scope state.
+ */
+export function makeEvaluateCaretVar(
+  runtime: CaretVarRuntime
+): (node: ASTNode, ctx: unknown) => Promise<unknown> {
+  return async function evaluateCaretVar(node, ctx) {
+    const n = node as CaretVarNode;
+    const context = ctx as ExecutionContext;
+    let anchor: Element | null = (context.me as Element | null) ?? null;
+
+    if (n.onTarget) {
+      const resolved = await runtime.execute(n.onTarget, context);
+      const el = coerceToElement(resolved);
+      if (el) anchor = el;
+    }
+
+    if (!anchor) return undefined;
+    return reactive.readCaret(anchor, n.name);
+  };
+}
+
+/**
+ * Build a node writer for `caretVar` bound to a specific runtime. Used by the
+ * core `set` command via `parserExtensions.registerNodeWriter`.
+ */
+export function makeWriteCaretVar(
+  runtime: CaretVarRuntime
+): (node: ASTNode, value: unknown, ctx: unknown) => Promise<void> {
+  return async function writeCaretVar(node, value, ctx) {
+    const n = node as CaretVarNode;
+    const context = ctx as ExecutionContext;
+    const anchor: Element | null = (context.me as Element | null) ?? null;
+    if (!anchor) return;
+
+    let target: Element | undefined;
+    if (n.onTarget) {
+      const resolved = await runtime.execute(n.onTarget, context);
+      const el = coerceToElement(resolved);
+      if (el) target = el;
+    }
+    reactive.writeCaret(anchor, n.name, value, target);
+  };
+}

package/src/index.ts

@@ -0,0 +1,132 @@
+/**
+ * @hyperfixi/reactivity — signal-based reactive features for hyperfixi.
+ *
+ * Adds four constructs from upstream _hyperscript 0.9.90:
+ *
+ *   live [commandList] end                       reactive block — body re-runs
+ *                                                when tracked reads change.
+ *
+ *   when <expr> [or <expr>]* changes             observer — body runs when any
+ *     [commandList] end                          watched expression changes.
+ *
+ *   bind <var> to <element>                      two-way DOM ⇄ var binding.
+ *
+ *   ^name [on <target>]                          DOM-scoped inherited variable
+ *                                                (read + write with `^`).
+ *
+ * Install:
+ *
+ * ```ts
+ * import { createRuntime, installPlugin } from '@hyperfixi/core';
+ * import { reactivityPlugin } from '@hyperfixi/reactivity';
+ *
+ * const runtime = createRuntime();
+ * installPlugin(runtime, reactivityPlugin);
+ * ```
+ */
+
+import type { HyperfixiPlugin, HyperfixiPluginContext } from '@hyperfixi/core';
+import { reactive } from './signals';
+import { parseCaretPrefix, makeEvaluateCaretVar, makeWriteCaretVar } from './caret-var';
+import { parseLiveFeature, makeEvaluateLiveFeature } from './live';
+import { parseWhenFeature, makeEvaluateWhenFeature } from './when';
+import { parseBindFeature, makeEvaluateBindFeature } from './bind';
+
+export { reactive } from './signals';
+export type { CaretVarNode } from './caret-var';
+export type { LiveFeatureNode } from './live';
+export type { WhenFeatureNode } from './when';
+export type { BindFeatureNode } from './bind';
+
+/**
+ * The plugin object. Install once at app startup; re-installing is idempotent
+ * (guarded via a `parserExtensions.hasFeature('live')` check).
+ *
+ * Registers:
+ *   - Features: `live`, `when`, `bind` (top-level features with `end` bodies)
+ *   - Prefix op: `^` (primary expression for DOM-scoped vars)
+ *   - Node evaluators: `liveFeature`, `whenFeature`, `bindFeature`, `caretVar`
+ *   - A node writer for `caretVar` so `set ^X to Y` flows through `reactive.writeCaret`
+ *   - Global read/write hooks so `$name` reads track and writes notify
+ *
+ * Effect cleanup: each effect-creating evaluator calls
+ * `context.registerCleanup(owner, stop, ...)` so the core runtime tears effects
+ * down when their owning element is cleaned up. There is no separate plugin-level
+ * cleanup hook; `reactive.stopElementEffects(el)` is exposed for explicit teardown
+ * by tests and consumers that manage element lifecycle outside the runtime.
+ */
+export const reactivityPlugin: HyperfixiPlugin & { version: string } = {
+  name: '@hyperfixi/reactivity',
+  version: '2.3.1',
+  install(ctx: HyperfixiPluginContext) {
+    const { parserExtensions, runtime } = ctx;
+
+    // Idempotency: the parser-extension registry is process-singleton, so
+    // re-installing into a fresh runtime would otherwise stack additional
+    // global read/write hooks on every call. `snapshot()`/`restore()` clears
+    // the feature registry — when tests roll back the registry, this guard
+    // re-enables a fresh install.
+    if (parserExtensions.hasFeature('live')) return;
+
+    // Parser hooks — three block features plus a primary-expression caret.
+    parserExtensions.registerFeature('live', parseLiveFeature as never);
+    parserExtensions.registerFeature('when', parseWhenFeature as never);
+    parserExtensions.registerFeature('bind', parseBindFeature as never);
+    parserExtensions.registerPrefixOperator('^', 85, parseCaretPrefix as never);
+
+    // Runtime evaluators. Features capture `runtime` so effect re-runs can
+    // dispatch body commands without going through module-scope state.
+    parserExtensions.registerNodeEvaluator(
+      'liveFeature',
+      makeEvaluateLiveFeature(runtime as never) as never
+    );
+    parserExtensions.registerNodeEvaluator(
+      'whenFeature',
+      makeEvaluateWhenFeature(runtime as never) as never
+    );
+    parserExtensions.registerNodeEvaluator(
+      'bindFeature',
+      makeEvaluateBindFeature(runtime as never) as never
+    );
+    parserExtensions.registerNodeEvaluator(
+      'caretVar',
+      makeEvaluateCaretVar(runtime as never) as never
+    );
+
+    // Caret-var write: lets the core `set` command dispatch `set ^X to Y`
+    // through `reactive.writeCaret`. Resolves `on <target>` via the captured
+    // runtime — no global-scope indirection.
+    parserExtensions.registerNodeWriter('caretVar', makeWriteCaretVar(runtime as never) as never);
+
+    // Global-write hook: notify the reactive graph whenever `$name` is set.
+    // The returned disposer is intentionally discarded — the install-time
+    // idempotency guard above is the sole gate against double-registration.
+    parserExtensions.registerGlobalWriteHook((name: string, _value: unknown, _context: unknown) => {
+      reactive.notifyGlobal(name);
+    });
+
+    // Global-read hook: track the read against the current effect (if any)
+    // so effects re-run when the global changes.
+    parserExtensions.registerGlobalReadHook((name: string, _context: unknown) => {
+      reactive.trackGlobal(name);
+    });
+
+    // Local hooks — analogous to globals, but keyed by `context.me` so each
+    // element holds independent state. A `set :foo to ...` running in a
+    // handler with `me=button1` notifies effects subscribed to (button1, 'foo');
+    // a `set :foo` in a different `me` won't reach them. This matches how
+    // locals already work — they're never cross-context — and lets two
+    // components hold independent `:foo` state without interference.
+    parserExtensions.registerLocalWriteHook((name: string, _value: unknown, context) => {
+      const owner = (context as { me?: Element | null }).me ?? null;
+      if (owner) reactive.notifyElement(owner, name);
+    });
+
+    parserExtensions.registerLocalReadHook((name: string, context) => {
+      const owner = (context as { me?: Element | null }).me ?? null;
+      if (owner) reactive.trackElement(owner, name);
+    });
+  },
+};
+
+export default reactivityPlugin;