sibujs 4.5.0 → 4.7.0

package/dist/tagFactory-DVoDpHye.d.cts

@@ -1,215 +0,0 @@
-declare const __accessor: unique symbol;
-/**
- * A reactive signal getter returned by signal(), derived(), and similar primitives.
- *
- * Pass an Accessor directly into reactive prop positions — never call it there:
- * ```ts
- * const [count, setCount] = signal(0);
- *
- * div(count)                       // ✓ reactive — Accessor passed directly
- * div(() => count())               // ✓ reactive — explicit arrow wrapper
- * div(count())                     // ✗ static  — evaluated once, not reactive
- * ```
- */
-type Accessor<T> = (() => T) & {
-    readonly [__accessor]?: never;
-};
-type SetState<T> = (next: T | ((prev: T) => T)) => void;
-type StateTuple<T> = [Accessor<T>, SetState<T>];
-/** Options for signal */
-interface SignalOptions<T = unknown> {
-    /** Debug name for devtools inspection. Only used in development. */
-    name?: string;
-    /** Custom equality function. Defaults to Object.is(). */
-    equals?: (prev: T, next: T) => boolean;
-}
-/**
- * signal creates a reactive signal that holds a value of type T.
- * Returns a tuple: [getter, setter].
- *
- * @param initial Initial value
- * @param options Optional config: `{ name: "count" }` for devtools labeling
- * @returns A `[getter, setter]` tuple. Calling the getter inside a reactive
- * context subscribes to the signal; the setter accepts a value or an updater.
- */
-declare function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>;
-/**
- * A valueless reactive token standing in for state SibuJS does not own.
- *
- * See {@link external}.
- */
-interface ExternalSource {
-    /**
-     * Declare, from inside a reactive computation, that it reads the external
-     * state this source represents. Call it in the same places you would read a
-     * signal — the top of a binding getter, a `derived()` body, an `effect()`.
-     *
-     * Outside a tracking context it is a no-op, exactly like reading a signal.
-     */
-    track(): void;
-    /**
-     * Declare that the external state changed. Every consumer that called
-     * {@link ExternalSource.track} is invalidated.
-     *
-     * Participates in `batch()` like any signal write: inside a batch, consumers
-     * are notified once when the outermost batch flushes.
-     */
-    invalidate(): void;
-}
-/**
- * Create a reactive source for state that lives outside SibuJS — a domain
- * engine, a media element, a canvas scene, an editor document, a cache a
- * socket writes into.
- *
- * The pattern is two lines: `track()` where you read, `invalidate()` after you
- * mutate.
- *
- * ```ts
- * import { Chess } from "chess.js";
- * import { external } from "sibujs";
- *
- * const game = new Chess();      // owns the rules and the mutable state
- * const moved = external();      // owns "something changed"
- *
- * ctx.text("@status", () => {
- *   moved.track();               // this binding reads the engine
- *   return game.isCheckmate() ? "Checkmate" : `${game.turn()} to move`;
- * });
- *
- * game.move({ from: "e2", to: "e4" });
- * moved.invalidate();            // every consumer above re-reads
- * ```
- *
- * **One source is one invalidation domain.** Every consumer of a source
- * re-runs on every `invalidate()`, so the granularity of your updates is
- * exactly the granularity of your sources: one for a whole engine is the
- * cheapest to write, several (`board`, `clock`, `history`) let an update touch
- * only what it affects. See `docs/architecture/external-state.md` for the
- * trade-offs and when subdividing is worth it.
- *
- * Ownership, disposal and error routing are the consumer's, not the source's:
- * a disposed binding or effect is never invalidated, and a consumer that
- * throws is reported through the normal runtime error pipeline with its own
- * phase and node.
- *
- * @param options `name` labels the source in devtools (development only).
- */
-declare function external(options?: {
-    name?: string;
-}): ExternalSource;
-
-/**
- * derived creates a derived reactive signal whose value updates when dependencies change.
- *
- * Uses lazy pull-based evaluation with a single dirty flag:
- * - When a dependency changes, the computed is marked dirty (no re-evaluation).
- * - Dirtiness propagates downstream via propagateDirty.
- * - The getter only re-evaluates when actually read (pull-based).
- * - On re-evaluation, dependencies are re-tracked via retrack() so that
- *   derived-of-derived chains propagate correctly without paying the full
- *   Set-delete + re-add cost of track()'s cleanup phase.
- *
- * STABILIZATION — why a dirty flag is enough:
- *
- * A dirty computed does NOT imply a changed value. Downstream effects are
- * enqueued by `propagateDirty` at write time, before this computed has had a
- * chance to recompute and compare. Rather than adding a three-color
- * (CLEAN/CHECK/DIRTY) propagation pass — which an earlier revision measured as
- * a regression on every benchmark, because the extra state has nothing to skip
- * when values genuinely change — the engine settles the question lazily at
- * DRAIN time: `cs._validate` recomputes a dirty computed and `cs.__v` is bumped
- * ONLY when the new value differs under this computed's comparator. The
- * scheduler compares that version against what each subscriber last observed
- * and suppresses the run when nothing changed (see `depsChanged` in
- * ../../reactivity/track-core.ts).
- *
- * That keeps the cheap boolean dirty flag AND makes `equals` actually stop
- * propagation, with recomputation still fully lazy: `_validate` only ever runs
- * when an effect is genuinely about to observe the value.
- *
- * DISPOSAL — a derived subscribes to its sources when it is created, and those
- * edges live as long as the sources do. A derived created per mount (one per
- * virtualized row, say) must be released when its owner goes away:
- * `flag.dispose()`, or `onCleanup(flag.dispose, rowNode)` to tie it to a node.
- * A disposed accessor is inert: it keeps returning the last value it settled,
- * never recomputes, never re-subscribes, and never wakes downstream readers.
- * Disposal is idempotent.
- *
- * ERRORS — a recomputation that throws is thrown to the next reader, in that
- * reader's context: a binding reports it with its node (so the nearest
- * `ErrorBoundary` can claim it), an effect reports it, a direct caller can catch
- * it, and a derived reading another derived passes it on. A live derived stays
- * dirty and recomputes on the following read; a derived that disposed itself
- * during the failing run returns its frozen value afterwards.
- *
- * @returns An accessor for the computed value. It recomputes lazily on read
- * after any dependency changes, and carries `dispose()` to release its source
- * subscriptions.
- */
-declare function derived<T>(getter: () => T, options?: {
-    name?: string;
-    /** Custom equality — when the recomputed value equals the previous,
-     *  downstream subscribers are not notified. Defaults to `Object.is`. */
-    equals?: (a: T, b: T) => boolean;
-}): DerivedAccessor<T>;
-/** Accessor returned by {@link derived}: read it like any getter, release it with `dispose()`. */
-type DerivedAccessor<T> = Accessor<T> & {
-    /** Release every source subscription. The accessor then returns its last settled value. Idempotent. */
-    dispose: () => void;
-};
-
-/**
- * Canonical disposer/teardown signature used across the framework.
- *
- * Returned by `effect()`, `track()`, widget `bind()` methods, and other
- * subscription/lifecycle helpers. All disposers MUST be idempotent — calling
- * twice should be a no-op rather than an error.
- */
-type Dispose = () => void;
-type NodeChild = Node | Element | Text | Comment | string | number | boolean | (() => NodeChild) | null | undefined;
-type NodeChildren = NodeChild | NodeChild[] | NodeChild[][] | (() => NodeChild | NodeChild[]);
-
-declare const SVG_NS = "http://www.w3.org/2000/svg";
-interface TagProps {
-    id?: string;
-    class?: string | (() => string) | Record<string, boolean | (() => boolean)>;
-    style?: Record<string, string | number | (() => string | number)> | string | (() => string);
-    ref?: {
-        current: Element | null;
-    };
-    nodes?: NodeChildren;
-    on?: Record<string, (ev: Event) => void>;
-    /** Called with the element after creation — useful for imperative bindings */
-    onElement?: (el: HTMLElement) => void;
-    [attr: string]: unknown;
-}
-/**
- * Factory for creating HTML or SVG elements with reactive props and nodes.
- *
- * Calling conventions:
- *
- *   tag()                         empty element
- *   tag("text")                   element with text content
- *   tag(42)                       element with numeric text content
- *   tag([childA, childB])         element with children (array)
- *   tag(node)                     element wrapping a single existing node
- *   tag(getter)                   element with a reactive child
- *   tag("className", children)    positional: class + children
- *   tag({ ...props })             full props object (children via props.nodes)
- *   tag({ ...props }, children)   props + children (no need for `nodes:` key!)
- *
- * The last form is the "deeply-nested shorthand" the codebase favours:
- *
- *   div({ class: "card" }, [
- *     h1({ class: "title" }, "Hello"),
- *     p({ class: "body" }, "World"),
- *     div({ class: "row" }, [
- *       span({ id: "x" }, "child"),
- *     ]),
- *   ])
- *
- * `children` overrides `props.nodes` when both are present.
- */
-declare const tagFactory: (tag: string, ns?: string) => (first?: TagProps | NodeChildren, second?: NodeChildren) => Element;
-
-export { type Accessor as A, type DerivedAccessor as D, type ExternalSource as E, type NodeChild as N, SVG_NS as S, type TagProps as T, type NodeChildren as a, type Dispose as b, type SignalOptions as c, derived as d, external as e, signal as s, tagFactory as t };

package/dist/tagFactory-DVoDpHye.d.ts

@@ -1,215 +0,0 @@
-declare const __accessor: unique symbol;
-/**
- * A reactive signal getter returned by signal(), derived(), and similar primitives.
- *
- * Pass an Accessor directly into reactive prop positions — never call it there:
- * ```ts
- * const [count, setCount] = signal(0);
- *
- * div(count)                       // ✓ reactive — Accessor passed directly
- * div(() => count())               // ✓ reactive — explicit arrow wrapper
- * div(count())                     // ✗ static  — evaluated once, not reactive
- * ```
- */
-type Accessor<T> = (() => T) & {
-    readonly [__accessor]?: never;
-};
-type SetState<T> = (next: T | ((prev: T) => T)) => void;
-type StateTuple<T> = [Accessor<T>, SetState<T>];
-/** Options for signal */
-interface SignalOptions<T = unknown> {
-    /** Debug name for devtools inspection. Only used in development. */
-    name?: string;
-    /** Custom equality function. Defaults to Object.is(). */
-    equals?: (prev: T, next: T) => boolean;
-}
-/**
- * signal creates a reactive signal that holds a value of type T.
- * Returns a tuple: [getter, setter].
- *
- * @param initial Initial value
- * @param options Optional config: `{ name: "count" }` for devtools labeling
- * @returns A `[getter, setter]` tuple. Calling the getter inside a reactive
- * context subscribes to the signal; the setter accepts a value or an updater.
- */
-declare function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>;
-/**
- * A valueless reactive token standing in for state SibuJS does not own.
- *
- * See {@link external}.
- */
-interface ExternalSource {
-    /**
-     * Declare, from inside a reactive computation, that it reads the external
-     * state this source represents. Call it in the same places you would read a
-     * signal — the top of a binding getter, a `derived()` body, an `effect()`.
-     *
-     * Outside a tracking context it is a no-op, exactly like reading a signal.
-     */
-    track(): void;
-    /**
-     * Declare that the external state changed. Every consumer that called
-     * {@link ExternalSource.track} is invalidated.
-     *
-     * Participates in `batch()` like any signal write: inside a batch, consumers
-     * are notified once when the outermost batch flushes.
-     */
-    invalidate(): void;
-}
-/**
- * Create a reactive source for state that lives outside SibuJS — a domain
- * engine, a media element, a canvas scene, an editor document, a cache a
- * socket writes into.
- *
- * The pattern is two lines: `track()` where you read, `invalidate()` after you
- * mutate.
- *
- * ```ts
- * import { Chess } from "chess.js";
- * import { external } from "sibujs";
- *
- * const game = new Chess();      // owns the rules and the mutable state
- * const moved = external();      // owns "something changed"
- *
- * ctx.text("@status", () => {
- *   moved.track();               // this binding reads the engine
- *   return game.isCheckmate() ? "Checkmate" : `${game.turn()} to move`;
- * });
- *
- * game.move({ from: "e2", to: "e4" });
- * moved.invalidate();            // every consumer above re-reads
- * ```
- *
- * **One source is one invalidation domain.** Every consumer of a source
- * re-runs on every `invalidate()`, so the granularity of your updates is
- * exactly the granularity of your sources: one for a whole engine is the
- * cheapest to write, several (`board`, `clock`, `history`) let an update touch
- * only what it affects. See `docs/architecture/external-state.md` for the
- * trade-offs and when subdividing is worth it.
- *
- * Ownership, disposal and error routing are the consumer's, not the source's:
- * a disposed binding or effect is never invalidated, and a consumer that
- * throws is reported through the normal runtime error pipeline with its own
- * phase and node.
- *
- * @param options `name` labels the source in devtools (development only).
- */
-declare function external(options?: {
-    name?: string;
-}): ExternalSource;
-
-/**
- * derived creates a derived reactive signal whose value updates when dependencies change.
- *
- * Uses lazy pull-based evaluation with a single dirty flag:
- * - When a dependency changes, the computed is marked dirty (no re-evaluation).
- * - Dirtiness propagates downstream via propagateDirty.
- * - The getter only re-evaluates when actually read (pull-based).
- * - On re-evaluation, dependencies are re-tracked via retrack() so that
- *   derived-of-derived chains propagate correctly without paying the full
- *   Set-delete + re-add cost of track()'s cleanup phase.
- *
- * STABILIZATION — why a dirty flag is enough:
- *
- * A dirty computed does NOT imply a changed value. Downstream effects are
- * enqueued by `propagateDirty` at write time, before this computed has had a
- * chance to recompute and compare. Rather than adding a three-color
- * (CLEAN/CHECK/DIRTY) propagation pass — which an earlier revision measured as
- * a regression on every benchmark, because the extra state has nothing to skip
- * when values genuinely change — the engine settles the question lazily at
- * DRAIN time: `cs._validate` recomputes a dirty computed and `cs.__v` is bumped
- * ONLY when the new value differs under this computed's comparator. The
- * scheduler compares that version against what each subscriber last observed
- * and suppresses the run when nothing changed (see `depsChanged` in
- * ../../reactivity/track-core.ts).
- *
- * That keeps the cheap boolean dirty flag AND makes `equals` actually stop
- * propagation, with recomputation still fully lazy: `_validate` only ever runs
- * when an effect is genuinely about to observe the value.
- *
- * DISPOSAL — a derived subscribes to its sources when it is created, and those
- * edges live as long as the sources do. A derived created per mount (one per
- * virtualized row, say) must be released when its owner goes away:
- * `flag.dispose()`, or `onCleanup(flag.dispose, rowNode)` to tie it to a node.
- * A disposed accessor is inert: it keeps returning the last value it settled,
- * never recomputes, never re-subscribes, and never wakes downstream readers.
- * Disposal is idempotent.
- *
- * ERRORS — a recomputation that throws is thrown to the next reader, in that
- * reader's context: a binding reports it with its node (so the nearest
- * `ErrorBoundary` can claim it), an effect reports it, a direct caller can catch
- * it, and a derived reading another derived passes it on. A live derived stays
- * dirty and recomputes on the following read; a derived that disposed itself
- * during the failing run returns its frozen value afterwards.
- *
- * @returns An accessor for the computed value. It recomputes lazily on read
- * after any dependency changes, and carries `dispose()` to release its source
- * subscriptions.
- */
-declare function derived<T>(getter: () => T, options?: {
-    name?: string;
-    /** Custom equality — when the recomputed value equals the previous,
-     *  downstream subscribers are not notified. Defaults to `Object.is`. */
-    equals?: (a: T, b: T) => boolean;
-}): DerivedAccessor<T>;
-/** Accessor returned by {@link derived}: read it like any getter, release it with `dispose()`. */
-type DerivedAccessor<T> = Accessor<T> & {
-    /** Release every source subscription. The accessor then returns its last settled value. Idempotent. */
-    dispose: () => void;
-};
-
-/**
- * Canonical disposer/teardown signature used across the framework.
- *
- * Returned by `effect()`, `track()`, widget `bind()` methods, and other
- * subscription/lifecycle helpers. All disposers MUST be idempotent — calling
- * twice should be a no-op rather than an error.
- */
-type Dispose = () => void;
-type NodeChild = Node | Element | Text | Comment | string | number | boolean | (() => NodeChild) | null | undefined;
-type NodeChildren = NodeChild | NodeChild[] | NodeChild[][] | (() => NodeChild | NodeChild[]);
-
-declare const SVG_NS = "http://www.w3.org/2000/svg";
-interface TagProps {
-    id?: string;
-    class?: string | (() => string) | Record<string, boolean | (() => boolean)>;
-    style?: Record<string, string | number | (() => string | number)> | string | (() => string);
-    ref?: {
-        current: Element | null;
-    };
-    nodes?: NodeChildren;
-    on?: Record<string, (ev: Event) => void>;
-    /** Called with the element after creation — useful for imperative bindings */
-    onElement?: (el: HTMLElement) => void;
-    [attr: string]: unknown;
-}
-/**
- * Factory for creating HTML or SVG elements with reactive props and nodes.
- *
- * Calling conventions:
- *
- *   tag()                         empty element
- *   tag("text")                   element with text content
- *   tag(42)                       element with numeric text content
- *   tag([childA, childB])         element with children (array)
- *   tag(node)                     element wrapping a single existing node
- *   tag(getter)                   element with a reactive child
- *   tag("className", children)    positional: class + children
- *   tag({ ...props })             full props object (children via props.nodes)
- *   tag({ ...props }, children)   props + children (no need for `nodes:` key!)
- *
- * The last form is the "deeply-nested shorthand" the codebase favours:
- *
- *   div({ class: "card" }, [
- *     h1({ class: "title" }, "Hello"),
- *     p({ class: "body" }, "World"),
- *     div({ class: "row" }, [
- *       span({ id: "x" }, "child"),
- *     ]),
- *   ])
- *
- * `children` overrides `props.nodes` when both are present.
- */
-declare const tagFactory: (tag: string, ns?: string) => (first?: TagProps | NodeChildren, second?: NodeChildren) => Element;
-
-export { type Accessor as A, type DerivedAccessor as D, type ExternalSource as E, type NodeChild as N, SVG_NS as S, type TagProps as T, type NodeChildren as a, type Dispose as b, type SignalOptions as c, derived as d, external as e, signal as s, tagFactory as t };