sibujs 1.4.0 → 2.0.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-import { T as TagProps, N as NodeChildren, a as NodeChild } from './tagFactory-DaJ0YWX6.cjs';
-export { S as SVG_NS, t as tagFactory } from './tagFactory-DaJ0YWX6.cjs';
+import { T as TagProps, N as NodeChildren, a as NodeChild } from './tagFactory-S17H2qxu.cjs';
+export { D as Dispose, S as SVG_NS, t as tagFactory } from './tagFactory-S17H2qxu.cjs';
 import { R as ReactiveSignal } from './signal-BnWpq6WB.cjs';
+export { T as TrustedHTML, t as trustHTML } from './ssr-CrVNy6Pa.cjs';
 
 type reactive<T> = T | (() => T);
 interface AnchorProps extends TagProps {
@@ -319,14 +320,12 @@ declare function each<T>(getArray: () => T[], render: (item: () => T, index: ()
  *
  * @example
  * ```ts
- * div({
- *   nodes: [
- *     Fragment([
- *       p({ nodes: "First" }),
- *       p({ nodes: "Second" }),
- *     ])
- *   ]
- * });
+ * div([
+ *   Fragment([
+ *     p("First"),
+ *     p("Second"),
+ *   ])
+ * ]);
  * ```
  *
  * @param nodes Array of child nodes to include in the fragment
@@ -338,6 +337,10 @@ declare function Fragment(nodes: NodeChildren[]): DocumentFragment;
  * Portal renders nodes into a DOM node outside the parent component hierarchy.
  * Useful for modals, tooltips, dropdowns, and overlays.
  *
+ * Cleanup integrates with `dispose()` / `registerDisposer()` so portals
+ * are properly torn down when the anchor is disposed by `when()`, `match()`,
+ * `each()`, or manual `dispose(anchor)`.
+ *
  * @param nodes Function that returns the content to render
  * @param target Target DOM element (defaults to document.body)
  * @returns A Comment anchor node in the original position
@@ -345,11 +348,11 @@ declare function Fragment(nodes: NodeChildren[]): DocumentFragment;
  * @example
  * ```ts
  * // Render modal at document.body
- * Portal(() => div({ class: "modal", nodes: "Modal content" }));
+ * Portal(() => div("modal", "Modal content"));
  *
  * // Render into specific container
  * const overlay = document.getElementById("overlay-root")!;
- * Portal(() => div({ nodes: "Tooltip" }), overlay);
+ * Portal(() => div("Tooltip"), overlay);
  * ```
  */
 declare function Portal(nodes: () => HTMLElement, target?: HTMLElement): Comment;
@@ -382,7 +385,7 @@ declare function unregisterComponent(name: string): void;
  * @example
  * ```ts
  * registerComponent("Widget", MyWidget);
- * div({ nodes: [resolveComponent("Widget")] });
+ * div([resolveComponent("Widget")]);
  * ```
  */
 declare function resolveComponent(name: string): HTMLElement;
@@ -418,7 +421,7 @@ declare function getSlot(slots: Slots | undefined, name?: string): SlotFn | unde
  * @example
  * ```ts
  * const [visible, setVisible] = signal(true);
- * div({ nodes: [show(() => visible(), span({ nodes: "I toggle!" }))] });
+ * div([show(() => visible(), span("I toggle!"))]);
  * ```
  */
 declare function show<T extends Element>(condition: () => boolean, element: T): T;
@@ -435,8 +438,8 @@ declare function show<T extends Element>(condition: () => boolean, element: T):
  * ```ts
  * when(
  *   () => isLoggedIn(),
- *   () => div({ nodes: "Welcome!" }),
- *   () => div({ nodes: "Please log in" })
+ *   () => div("Welcome!"),
+ *   () => div("Please log in")
  * );
  * ```
  */
@@ -459,7 +462,7 @@ declare function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBr
  *     error: () => ErrorMessage(),
  *     success: () => Content(),
  *   },
- *   () => div({ nodes: "Unknown status" })
+ *   () => div("Unknown status")
  * );
  * ```
  */
@@ -527,8 +530,7 @@ type ActionFn<T = void> = (element: HTMLElement, param: T) => (() => void) | und
  *     action(el, clickOutside, () => setOpen(false));
  *     action(el, longPress, { duration: 500, callback: onLongPress });
  *   },
- *   nodes: "Content",
- * });
+ * }, "Content");
  * ```
  */
 declare function action<T>(element: HTMLElement, actionFn: ActionFn<T>, param: T): void;
@@ -636,10 +638,10 @@ declare function setGlobalErrorHandler(handler: ErrorHandler): void;
  * ```ts
  * function Field(labelText: string) {
  *   const id = createId("field");
- *   return div({ nodes: [
- *     label({ for: id, nodes: labelText }),
+ *   return div([
+ *     label({ for: id }, labelText),
  *     input({ id }),
- *   ]});
+ *   ]);
  * }
  * ```
  */
@@ -681,9 +683,9 @@ declare const __accessor: unique symbol;
  * ```ts
  * const [count, setCount] = signal(0);
  *
- * div({ nodes: count })           // ✓ reactive — Accessor passed directly
- * div({ nodes: () => count() })   // ✓ reactive — explicit arrow wrapper
- * div({ nodes: count() })         // ✗ static  — evaluated once, not reactive
+ * div(count)                       // ✓ reactive — Accessor passed directly
+ * div(() => count())               // ✓ reactive — explicit arrow wrapper
+ * div(count())                     // ✗ static  — evaluated once, not reactive
  * ```
  */
 type Accessor<T> = (() => T) & {
@@ -733,14 +735,29 @@ interface EffectOptions {
  * ```
  */
 declare function on<T>(deps: () => T, handler: (value: T, prev: T | undefined) => void): () => void;
+/** Registers a function to run before the effect re-runs or is disposed.
+ *  Called with the same signature inside every invocation. */
+type OnCleanup = (fn: () => void) => void;
+/** The user's effect body — may accept an `onCleanup` callback to register
+ *  teardown that runs before the next re-run or on dispose. */
+type EffectBody = (onCleanup: OnCleanup) => void;
 /**
  * effect runs the provided effectFn immediately and re-runs it whenever
  * any reactive dependency changes.
  * Returns a cleanup function to stop further executions.
  *
  * In SSR mode, effect is a no-op — side effects should not run on the server.
+ *
+ * @example addEventListener pattern with built-in teardown:
+ * ```ts
+ * effect((onCleanup) => {
+ *   const handler = (e: Event) => { ... };
+ *   window.addEventListener("resize", handler);
+ *   onCleanup(() => window.removeEventListener("resize", handler));
+ * });
+ * ```
  */
-declare function effect(effectFn: () => void, options?: EffectOptions): () => void;
+declare function effect(effectFn: EffectBody | (() => void), options?: EffectOptions): () => void;
 
 /**
  * derived creates a derived reactive signal whose value updates when dependencies change.
@@ -754,6 +771,9 @@ declare function effect(effectFn: () => void, options?: EffectOptions): () => vo
  */
 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;
 }): Accessor<T>;
 
 /**
@@ -903,16 +923,23 @@ declare function reactiveArray<T>(initial?: T[]): [Accessor<readonly T[]>, Array
 /**
  * Deep equality comparison for objects and arrays.
  * Falls back to Object.is for primitives.
- * Handles circular references and common built-in types (Date, RegExp).
+ * Handles circular references, shared sub-references, and common
+ * built-in types (Date, RegExp, Map, Set, ArrayBuffer, TypedArrays).
+ *
+ * The `seen` parameter tracks `(a, b)` pairs — not just `a` — so that
+ * a shared sub-object compared against two different partners is always
+ * fully checked, while genuine cycles (same a-with-same-b revisited)
+ * still terminate.
  */
-declare function deepEqual(a: unknown, b: unknown, seen?: Set<unknown>): boolean;
+declare function deepEqual(a: unknown, b: unknown, seen?: Map<object, Set<object>>): boolean;
 /**
  * Like signal but uses deep equality comparison instead of Object.is.
  * This prevents unnecessary re-renders when setting an object/array
  * to a structurally identical value.
  *
  * @param initial Initial value
- * @returns Tuple [getter, setter]
+ * @returns Tuple [getter, setter] — same shape as `signal()`, preserving
+ *          the `Accessor<T>` brand on the getter.
  *
  * @example
  * ```ts
@@ -921,7 +948,7 @@ declare function deepEqual(a: unknown, b: unknown, seen?: Set<unknown>): boolean
  * setUser({ name: "Bob", age: 25 });   // Notifies — different value
  * ```
  */
-declare function deepSignal<T>(initial: T): [() => T, (next: T | ((prev: T) => T)) => void];
+declare function deepSignal<T>(initial: T): [Accessor<T>, (next: T | ((prev: T) => T)) => void];
 
 /**
  * Creates a writable computed value — a derived getter paired with
@@ -1017,7 +1044,7 @@ declare function asyncDerived<T>(factory: () => Promise<T>, initial: T): AsyncDe
  *     console.log("Component was removed");
  *   });
  *
- *   return div({ nodes: "Hello" });
+ *   return div("Hello");
  * }
  * ```
  */
@@ -1036,7 +1063,8 @@ type CleanupFn = () => void;
 declare function onMount(callback: () => undefined | CleanupFn, element?: HTMLElement): void;
 /**
  * Runs a callback when the given element is removed from the DOM.
- * Uses MutationObserver to watch for disconnection.
+ * Uses a shared MutationObserver to watch for disconnection, plus
+ * `registerDisposer` so explicit dispose() paths also trigger the callback.
  *
  * @param callback Function to run on unmount
  * @param element The element to watch for removal
@@ -1054,7 +1082,7 @@ declare function onUnmount(callback: CleanupFn, element: HTMLElement): void;
  * ```ts
  * function RealtimeBar(siteId: string) {
  *   const ws = new WebSocket(`/ws/sites/${siteId}/realtime`);
- *   const root = div({ nodes: "Realtime data..." });
+ *   const root = div("Realtime data...");
  *   onCleanup(() => ws.close(), root);
  *   return root;
  * }
@@ -1063,36 +1091,56 @@ declare function onUnmount(callback: CleanupFn, element: HTMLElement): void;
 declare function onCleanup(callback: CleanupFn, element: Node): void;
 
 /**
- * Context API for SibuJS — provides dependency injection across
- * component trees without prop drilling.
+ * Context API for SibuJS — a reactive global value that any component
+ * can read without prop drilling.
+ *
+ * Note: this is a **global reactive store**, not a subtree-scoped DI
+ * system. Calling `provide()` sets the value for ALL consumers, not
+ * just descendants of the provider. For most apps this is sufficient
+ * — use separate `context()` instances for independent scopes.
  *
  * @example
  * ```ts
  * // Create a context with a default value
  * const ThemeContext = context("light");
  *
- * // Provide a value at a parent level
- * function App() {
- *   ThemeContext.provide("dark");
- *   return div({ nodes: [Child()] });
- * }
+ * // Set the value (global — affects all consumers)
+ * ThemeContext.provide("dark");
  *
- * // Consume the value anywhere below
+ * // Read reactively from any component
  * function Child() {
  *   const theme = ThemeContext.use(); // reactive getter
- *   return div({ nodes: () => `Theme: ${theme()}` });
+ *   return div(() => `Theme: ${theme()}`);
  * }
  * ```
  */
 interface Context<T> {
-    /** Provide a value for this context. Overrides any parent provider. */
-    provide(value: T): void;
+    /**
+     * Set the context value globally. Affects all consumers.
+     *
+     * Returns a `restore` function that re-sets the context to the value it
+     * had *before* this `provide` call. Useful for scoped overrides:
+     *
+     * ```ts
+     * const restore = Theme.provide("dark");
+     * try { renderChild(); } finally { restore(); }
+     * ```
+     *
+     * Callers that don't need scoping can ignore the return value — existing
+     * semantics are preserved.
+     */
+    provide(value: T): () => void;
     /** Get a reactive getter for the current context value. */
     use(): () => T;
     /** Get the current value directly (non-reactive). */
     get(): T;
     /** Update the provided value reactively. */
     set(value: T): void;
+    /**
+     * Run `fn` with the context temporarily set to `value`, then restore the
+     * previous value (even if `fn` throws). Returns the result of `fn`.
+     */
+    withContext<R>(value: T, fn: () => R): R;
 }
 /**
  * Creates a new context with an optional default value.
@@ -1148,6 +1196,11 @@ declare function strictEffect(fn: () => void): () => void;
  * During server-side rendering, side effects (effect, watch, onMount)
  * should not run. This module provides a flag to enable/disable SSR mode.
  *
+ * Concurrency: on Node we back the flag with AsyncLocalStorage so
+ * simultaneous requests get independent SSR scopes. On runtimes without
+ * AsyncLocalStorage (browser, some edge runtimes) we fall back to a
+ * module-global boolean.
+ *
  * Usage:
  *   enableSSR();        // Call before rendering on the server
  *   renderToString(...);
@@ -1155,13 +1208,30 @@ declare function strictEffect(fn: () => void): () => void;
  *
  * Or use the scoped helper:
  *   withSSR(() => renderToString(...));
+ *   runInSSRContext(() => renderToString(...));
+ */
+/**
+ * Per-request SSR store. Currently holds the SSR flag plus a
+ * suspense-id counter so concurrent streaming renders never collide.
  */
+interface SSRStore {
+    ssr: boolean;
+    suspenseIdCounter: number;
+}
+/** Returns the active store (ALS or fallback). */
+declare function getSSRStore(): SSRStore;
 /** Returns true when running in SSR mode. */
 declare function isSSR(): boolean;
 /** Enable SSR mode. Side effects (effect, watch, onMount) become no-ops. */
 declare function enableSSR(): void;
 /** Disable SSR mode. Side effects resume normal behavior. */
 declare function disableSSR(): void;
+/**
+ * Run `fn` inside a fresh request-scoped SSR context. On Node this uses
+ * AsyncLocalStorage so concurrent requests never share state; elsewhere
+ * it falls back to mutating the module-global store.
+ */
+declare function runInSSRContext<T>(fn: () => T): T;
 /**
  * Run a function in SSR mode. Automatically enables/disables SSR around the callback.
  * Returns whatever the callback returns.
@@ -1243,10 +1313,12 @@ declare function nextTick(): Promise<void>;
  * input({ on: { input: e => setQuery(e.target.value) } });
  *
  * // heavy list reads deferredQuery() and updates one frame later
- * each(() => heavyFilter(items, deferredQuery()), row => li({ nodes: row.name }));
+ * each(() => heavyFilter(items, deferredQuery()), row => li(row.name));
  * ```
  */
-declare function defer<T>(getter: () => T): () => T;
+declare function defer<T>(getter: () => T): (() => T) & {
+    dispose: () => void;
+};
 interface TransitionState {
     pending: () => boolean;
     start: (fn: () => void | Promise<void>) => void;
@@ -1296,6 +1368,7 @@ declare function untracked<T>(fn: () => T): T;
  */
 declare function bindDynamic(el: HTMLElement, nameGetter: string | (() => string), valueGetter: string | (() => unknown)): () => void;
 
+declare function takePendingError(node: Element): Error | undefined;
 type Component = () => HTMLElement;
 type LazyImport = () => Promise<{
     default: Component;
@@ -1312,7 +1385,7 @@ type LazyImport = () => Promise<{
  * // Use inside Suspense for custom loading UI
  * Suspense({
  *   nodes: () => LazyDashboard(),
- *   fallback: () => div({ nodes: "Loading dashboard..." }),
+ *   fallback: () => div("Loading dashboard..."),
  * });
  *
  * // Or use standalone — shows default "Loading..." text
@@ -1330,7 +1403,7 @@ declare function lazy(importFn: LazyImport): Component;
  * ```ts
  * Suspense({
  *   nodes: () => LazyChart(),
- *   fallback: () => div({ nodes: "Loading chart..." }),
+ *   fallback: () => div("Loading chart..."),
  * });
  * ```
  *
@@ -1370,7 +1443,7 @@ interface ErrorBoundaryProps {
      * const [route, setRoute] = signal("/");
      * ErrorBoundary({
      *   resetKeys: [route],
-     *   nodes: () => div({ nodes: riskyPageFor(route()) }),
+     *   nodes: () => div(riskyPageFor(route())),
      * });
      * ```
      */
@@ -1429,13 +1502,13 @@ interface ErrorDisplayProps {
  *
  * @example
  * ```ts
- * button({
- *   on: { click: async () => {
+ * button(
+ *   { on: { click: async () => {
  *     try { await save(); }
  *     catch (err) { mount(ErrorDisplay({ error: err, onRetry: save }), errorHost); }
- *   }},
- *   nodes: "Save",
- * });
+ *   }}},
+ *   "Save",
+ * );
  * ```
  */
 declare function ErrorDisplay(props: ErrorDisplayProps): Element;
@@ -1461,4 +1534,4 @@ interface LoadingProps {
  */
 declare function Loading(props?: LoadingProps): HTMLElement;
 
-export { type Accessor, type ActionFn, type AnchorProps, type ArrayActions, type AsyncDerivedState, type AudioProps, type ButtonProps, type Context, DynamicComponent, type EffectOptions, ErrorBoundary, type ErrorBoundaryProps, ErrorDisplay, type ErrorDisplayProps, type ErrorSeverity, type FormProps, Fragment, type ImgProps, type InputProps, type InputType, KeepAlive, type KeepAliveOptions, type LabelProps, Loading, type LoadingProps, type LongPressOptions, type MediaProps, NodeChild, NodeChildren, type OptionProps, Portal, type Ref, type SelectProps, type SignalOptions, type SlotFn, type Slots, type StoreActions, Suspense, type SuspenseProps, TagProps, type TextareaProps, type TypedTagFunction, type VideoProps, __resetIdCounter, a, abbr, action, address, area, array, article, aside, asyncDerived, audio, autoResize, b, base, batch, bdi, bdo, bindDynamic, blockquote, body, br, button, canvas, caption, catchError, catchErrorAsync, center, checkLeaks, circle, cite, clickOutside, clipPath, code, col, colgroup, context, copyOnClick, createId, customElement, data, datalist, dd, deepEqual, deepSignal, defer, defs, del, derived, details, dfn, dialog, disableSSR, dispose, div, dl, dt, each, effect, ellipse, em, embed, enableSSR, enqueueBatchedSignal, fieldset, figcaption, figure, font, footer, form, g, getSlot, h1, h2, h3, h4, h5, h6, head, header, hr, html, i, iframe, img, input, ins, isBatching, isSSR, kbd, label, lazy, legend, li, line, linearGradient, link, longPress, main, map, mark, marker, marquee, mask, match, math, menu, meta, meter, mount, nav, nextTick, noscript, object, ol, on, onCleanup, onMount, onUnmount, optgroup, option, output, p, param, path, pattern, picture, polygon, polyline, portal, pre, progress, q, radialGradient, reactiveArray, rect, ref, registerComponent, registerDisposer, resolveComponent, rp, rt, ruby, s, samp, script, section, select, setGlobalErrorHandler, show, signal, slot, small, source, span, stop, store, strict, strictEffect, strong, style, sub, summary, sup, svg, symbol, table, tbody, td, template, text, textarea, tfoot, th, thead, time, title, tr, track, transition, trapFocus, tspan, u, ul, unregisterComponent, untracked, use, var_, video, watch, when, withSSR, writable };
+export { type Accessor, type ActionFn, type AnchorProps, type ArrayActions, type AsyncDerivedState, type AudioProps, type ButtonProps, type Context, DynamicComponent, type EffectBody, type EffectOptions, ErrorBoundary, type ErrorBoundaryProps, ErrorDisplay, type ErrorDisplayProps, type ErrorSeverity, type FormProps, Fragment, type ImgProps, type InputProps, type InputType, KeepAlive, type KeepAliveOptions, type LabelProps, Loading, type LoadingProps, type LongPressOptions, type MediaProps, NodeChild, NodeChildren, type OnCleanup, type OptionProps, Portal, type Ref, type SSRStore, type SelectProps, type SignalOptions, type SlotFn, type Slots, type StoreActions, Suspense, type SuspenseProps, TagProps, type TextareaProps, type TypedTagFunction, type VideoProps, __resetIdCounter, a, abbr, action, address, area, array, article, aside, asyncDerived, audio, autoResize, b, base, batch, bdi, bdo, bindDynamic, blockquote, body, br, button, canvas, caption, catchError, catchErrorAsync, center, checkLeaks, circle, cite, clickOutside, clipPath, code, col, colgroup, context, copyOnClick, createId, customElement, data, datalist, dd, deepEqual, deepSignal, defer, defs, del, derived, details, dfn, dialog, disableSSR, dispose, div, dl, dt, each, effect, ellipse, em, embed, enableSSR, enqueueBatchedSignal, fieldset, figcaption, figure, font, footer, form, g, getSSRStore, getSlot, h1, h2, h3, h4, h5, h6, head, header, hr, html, i, iframe, img, input, ins, isBatching, isSSR, kbd, label, lazy, legend, li, line, linearGradient, link, longPress, main, map, mark, marker, marquee, mask, match, math, menu, meta, meter, mount, nav, nextTick, noscript, object, ol, on, onCleanup, onMount, onUnmount, optgroup, option, output, p, param, path, pattern, picture, polygon, polyline, portal, pre, progress, q, radialGradient, reactiveArray, rect, ref, registerComponent, registerDisposer, resolveComponent, rp, rt, ruby, runInSSRContext, s, samp, script, section, select, setGlobalErrorHandler, show, signal, slot, small, source, span, stop, store, strict, strictEffect, strong, style, sub, summary, sup, svg, symbol, table, takePendingError, tbody, td, template, text, textarea, tfoot, th, thead, time, title, tr, track, transition, trapFocus, tspan, u, ul, unregisterComponent, untracked, use, var_, video, watch, when, withSSR, writable };