@hyperfixi/reactivity 2.4.0

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import { HyperfixiPlugin } from '@hyperfixi/core';
+
+/**
+ * Signal/effect reactive core.
+ *
+ * Models three dependency kinds for v1:
+ *   - `global`  — `$name` variables in `context.globals`
+ *   - `element` — `^name` DOM-scoped variables (per-element storage)
+ *   - `dom`     — DOM properties read via `input`/`change` listeners
+ *
+ * Inspired by upstream _hyperscript 0.9.91's `src/core/runtime/reactivity.js`
+ * but reimplemented in TypeScript against hyperfixi's types. Batched via
+ * `queueMicrotask` so synchronous writes coalesce into a single flush. Cycle
+ * detection halts at >100 consecutive triggers (matching upstream).
+ *
+ * External packages never see `Effect` or `Reactive` directly — they hold
+ * the disposer returned by `createEffect()` and call it when the owning
+ * element is cleaned up.
+ */
+type DepKind = 'global' | 'element' | 'dom';
+interface Dep {
+    readonly key: string;
+    readonly kind: DepKind;
+    readonly name: string;
+    readonly element: Element | null;
+}
+declare class Effect {
+    private readonly r;
+    readonly expression: () => unknown | Promise<unknown>;
+    readonly handler: (value: unknown) => void | Promise<void>;
+    readonly element: Element | null;
+    readonly dependencies: Map<string, Dep>;
+    private lastValue;
+    private _stopped;
+    private _consecutiveTriggers;
+    constructor(r: Reactive, expression: () => unknown | Promise<unknown>, handler: (value: unknown) => void | Promise<void>, element: Element | null);
+    get stopped(): boolean;
+    /**
+     * Run the effect for the first time: collect dependencies, subscribe, call
+     * handler with the initial value. Errors in expression evaluation are caught
+     * and silently swallowed (matches upstream's tolerance).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Re-run the effect after a notify. Cycle-detects (halts at 101 consecutive
+     * triggers). If the new value is Object.is-equal to the last, the handler
+     * is skipped. If the owning element has disconnected, the effect stops
+     * itself and returns.
+     */
+    run(): Promise<void>;
+    resetTriggerCount(): void;
+    /**
+     * Stop the effect and remove it from all dependency subscriptions. Safe to
+     * call multiple times.
+     */
+    stop(): void;
+}
+declare class Reactive {
+    private currentEffect;
+    private pending;
+    private scheduled;
+    private globalSubs;
+    private elementState;
+    private getElementState;
+    /**
+     * Internal helper invoked by Effect — installs `this` as the current effect,
+     * runs the expression, then restores the previous current-effect pointer.
+     * Track* methods (called from read-paths) consult `currentEffect` to know
+     * which effect to subscribe.
+     */
+    _runWithEffect(e: Effect, fn: () => unknown | Promise<unknown>): Promise<unknown>;
+    trackGlobal(name: string): void;
+    trackElement(el: Element, name: string): void;
+    trackDomProperty(el: Element, prop: string): void;
+    notifyGlobal(name: string): void;
+    notifyElement(el: Element, name: string): void;
+    /**
+     * Create + initialize an effect. Returns a disposer that stops the effect.
+     * Callers are expected to register the disposer with the core runtime's
+     * cleanup registry so it fires on element removal.
+     */
+    createEffect(expression: () => unknown | Promise<unknown>, handler: (value: unknown) => void | Promise<void>, owner: Element | null): () => void;
+    /**
+     * Stop all effects owned by an element. Called by the reactivity plugin's
+     * cleanup hook registered via `runtime.getCleanupRegistry()`.
+     */
+    stopElementEffects(el: Element): void;
+    /**
+     * Internal: remove an effect's entries from all subscriber sets. Called by
+     * `Effect.stop()`.
+     */
+    _unsubscribeEffect(e: Effect): void;
+    /**
+     * Whether `el` is a `dom-scope="isolated"` boundary. Walks of `^var`
+     * lookups stop at boundary elements that don't define the var, so nested
+     * components don't accidentally read or write each other's state.
+     */
+    private isIsolationBoundary;
+    /**
+     * Walk up the DOM tree from `lookupRoot`, returning the first element whose
+     * state has `name` defined. Stops at any `dom-scope="isolated"` boundary
+     * that doesn't itself define the var. Returns `null` if no owner is found.
+     */
+    private findCaretOwner;
+    /**
+     * Read a DOM-scoped variable. Walks up from `lookupRoot`, tracking each
+     * element visited as an `element` dep (so writes at any ancestor notify
+     * dependent effects). Stops at any `dom-scope="isolated"` boundary that
+     * doesn't itself define the var.
+     */
+    readCaret(lookupRoot: Element, name: string): unknown;
+    /**
+     * Write a DOM-scoped variable. If `target` is provided, writes there
+     * directly; otherwise walks up from `lookupRoot` to find the existing owner,
+     * falling back to `lookupRoot` itself if no owner exists.
+     */
+    writeCaret(lookupRoot: Element, name: string, value: unknown, target?: Element): void;
+    private schedule;
+    private flush;
+}
+declare const reactive: Reactive;
+
+/**
+ * Lightweight local type stubs — mirror the speech package pattern of
+ * avoiding tight coupling to `@hyperfixi/core` internals. Commands and
+ * evaluators consume raw shapes via these structural types.
+ */
+interface ASTNode {
+    type: string;
+    name?: string;
+    value?: unknown;
+    start?: number;
+    end?: number;
+    line?: number;
+    column?: number;
+    [k: string]: unknown;
+}
+
+/**
+ * `^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.
+ */
+
+interface CaretVarNode extends ASTNode {
+    type: 'caretVar';
+    name: string;
+    onTarget: ASTNode | null;
+}
+
+/**
+ * `live ... end` — reactive block. Body re-runs whenever any dependency read
+ * during its execution changes.
+ *
+ * Upstream syntax:
+ *   live [commandList] end
+ *
+ * Each command in the body is re-executed as a single effect. The entire
+ * body shares one effect instance; its dependency set is the union of every
+ * read performed during body execution.
+ */
+
+interface LiveFeatureNode extends ASTNode {
+    type: 'liveFeature';
+    body: ASTNode[];
+}
+
+/**
+ * `when <expr> [or <expr>]* changes [commandList] end` — observer feature.
+ *
+ * Runs the body when any watched expression's value changes (Object.is
+ * semantics). One effect is created per watched expression so writes to a
+ * given dep only re-run that watcher.
+ */
+
+interface WhenFeatureNode extends ASTNode {
+    type: 'whenFeature';
+    watched: ASTNode[];
+    body: ASTNode[];
+}
+
+/**
+ * `bind X [to|and|with] Y` — two-way binding.
+ *
+ * Creates two effects (registration order is load-bearing — both initialize
+ * via `queueMicrotask` and run in registration order):
+ *   1. DOM → var: read DOM, write var. DOM "wins" on init.
+ *   2. var → DOM: read var, write DOM. Fires on programmatic var writes
+ *      after init. On its own initial run, var === DOM (Effect 1 just synced
+ *      them), so the write is a no-op.
+ *
+ * Two binding forms:
+ *
+ *   1. Auto-detected (DOM side is a bare element expression):
+ *
+ *        bind $name to #input          -- detects `value`
+ *        bind $checked to me           -- detects `checked` on a checkbox
+ *
+ *      Auto-detected property by element type:
+ *        - INPUT[type=checkbox|radio]      → `checked`
+ *        - INPUT[type=number|range]        → `valueAsNumber`
+ *        - INPUT|TEXTAREA|SELECT           → `value`
+ *        - contenteditable="true"          → `textContent`
+ *        - Custom elements with own `value` → `value`
+ *
+ *   2. Explicit property (DOM side is a member or possessive expression):
+ *
+ *        bind $color to #picker's value    -- possessive (preferred — reads in any language)
+ *        bind $color to #picker.value      -- dot (JS-style alternative)
+ *        bind $text to #div's textContent  -- non-form properties: var→DOM only
+ *
+ *      For form-like elements, both directions work. For non-form elements
+ *      (e.g., binding a div's `textContent`), only var→DOM fires — there are
+ *      no input/change events to drive DOM→var, so user mutations of the
+ *      property via devtools won't propagate back.
+ */
+
+interface BindFeatureNode extends ASTNode {
+    type: 'bindFeature';
+    left: ASTNode;
+    right: ASTNode;
+}
+
+/**
+ * @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);
+ * ```
+ */
+
+/**
+ * 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.
+ */
+declare const reactivityPlugin: HyperfixiPlugin & {
+    version: string;
+};
+
+export { type BindFeatureNode, type CaretVarNode, type LiveFeatureNode, type WhenFeatureNode, reactivityPlugin as default, reactive, reactivityPlugin };