sibujs 4.4.0 → 4.6.0

package/dist/{chunk-SKPTERHP.js → chunk-XRRZKZYX.js}

@@ -1,9 +1,13 @@
 import {
-  registerDisposer
-} from "./chunk-QKRPLZ2V.js";
+  adoptThenable
+} from "./chunk-5HZXGZ6T.js";
 import {
   signal
-} from "./chunk-NVNJH22U.js";
+} from "./chunk-D33YTSX5.js";
+import {
+  registerDisposer,
+  reportError
+} from "./chunk-NYNYSPK7.js";
 
 // src/ui/transition.ts
 function transition(element, options = {}) {
@@ -32,6 +36,15 @@ function transition(element, options = {}) {
       resolvePrev();
     }
   }
+  function complete(callback, name, resolve) {
+    try {
+      callback?.();
+    } catch (error) {
+      reportError(error, { phase: "async", name, node: element });
+    } finally {
+      resolve();
+    }
+  }
   function enter() {
     return new Promise((resolve) => {
       cancelPending();
@@ -44,8 +57,7 @@ function transition(element, options = {}) {
         activeTimer = null;
         pendingResolve = null;
         if (enterClass) element.classList.remove(enterClass);
-        onEnterDone?.();
-        resolve();
+        complete(onEnterDone, "transition(onEnterDone)", resolve);
       };
       if (duration > 0) {
         pendingResolve = resolve;
@@ -66,8 +78,7 @@ function transition(element, options = {}) {
         activeTimer = null;
         pendingResolve = null;
         if (leaveClass) element.classList.remove(leaveClass);
-        onLeaveDone?.();
-        resolve();
+        complete(onLeaveDone, "transition(onLeaveDone)", resolve);
       };
       if (duration > 0) {
         pendingResolve = resolve;
@@ -274,18 +285,29 @@ async function sequence(steps) {
 function TransitionGroup(options) {
   const [elements, setElements] = signal([]);
   const positions = /* @__PURE__ */ new Map();
+  function runCallback(name, callback, el) {
+    const report = (error) => reportError(error, { phase: "async", name: `TransitionGroup.${name}`, node: el });
+    try {
+      adoptThenable(callback(el))?.then(void 0, report);
+    } catch (error) {
+      report(error);
+    }
+  }
   function add(el) {
     setElements((prev) => [...prev, el]);
-    if (options.enter) {
-      options.enter(el);
-    }
+    if (options.enter) runCallback("enter", options.enter, el);
   }
   async function remove(el) {
-    if (options.leave) {
-      await options.leave(el);
+    try {
+      if (options.leave) {
+        await adoptThenable(options.leave(el));
+      }
+    } catch (error) {
+      reportError(error, { phase: "async", name: "TransitionGroup.leave", node: el });
+    } finally {
+      positions.delete(el);
+      setElements((prev) => prev.filter((e) => e !== el));
     }
-    positions.delete(el);
-    setElements((prev) => prev.filter((e) => e !== el));
   }
   function track(newElements) {
     const oldPositions = /* @__PURE__ */ new Map();
@@ -297,17 +319,13 @@ function TransitionGroup(options) {
     const currentSet = new Set(elements());
     for (const el of newElements) {
       if (!currentSet.has(el)) {
-        if (options.enter) {
-          options.enter(el);
-        }
+        if (options.enter) runCallback("enter", options.enter, el);
       }
     }
     const newSet = new Set(newElements);
     for (const el of elements()) {
       if (!newSet.has(el)) {
-        if (options.leave) {
-          options.leave(el);
-        }
+        if (options.leave) runCallback("leave", options.leave, el);
       }
     }
     setElements(newElements);
@@ -317,7 +335,7 @@ function TransitionGroup(options) {
         if (oldRect && typeof el.getBoundingClientRect === "function") {
           const newRect = el.getBoundingClientRect();
           if (oldRect.left !== newRect.left || oldRect.top !== newRect.top) {
-            options.move(el);
+            runCallback("move", options.move, el);
           }
         }
       }
@@ -368,9 +386,13 @@ function springSignal(initial, options) {
   let target = initial;
   let rafId = null;
   let lastTime = 0;
+  let disposed = false;
+  const canAnimate = () => typeof requestAnimationFrame === "function";
   const REF_DT_MS = 1e3 / 60;
   const MAX_STEP_RATIO = 4;
   function tick(now) {
+    rafId = null;
+    if (disposed) return;
     if (lastTime === 0) lastTime = now;
     const rawDt = now - lastTime;
     lastTime = now;
@@ -383,23 +405,27 @@ function springSignal(initial, options) {
     if (Math.abs(current - target) < precision && Math.abs(velocity) < precision) {
       current = target;
       velocity = 0;
-      rafId = null;
       lastTime = 0;
       setValue(current);
       return;
     }
     setValue(current);
+    if (disposed || rafId !== null) return;
     rafId = requestAnimationFrame(tick);
   }
+  function cancelFrame() {
+    if (rafId !== null) {
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+  }
   function set(newTarget) {
+    if (disposed) return;
     target = newTarget;
-    if (prefersReducedMotion()) {
+    if (!canAnimate() || prefersReducedMotion()) {
       current = newTarget;
       velocity = 0;
-      if (rafId !== null) {
-        cancelAnimationFrame(rafId);
-        rafId = null;
-      }
+      cancelFrame();
       lastTime = 0;
       setValue(current);
       return;
@@ -410,10 +436,8 @@ function springSignal(initial, options) {
     }
   }
   function dispose() {
-    if (rafId !== null) {
-      cancelAnimationFrame(rafId);
-      rafId = null;
-    }
+    disposed = true;
+    cancelFrame();
     lastTime = 0;
   }
   return [value, set, dispose];

package/dist/{contracts-DBdg9J_a.d.cts → contracts-DRIuclVT.d.cts}

@@ -32,7 +32,15 @@ declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (compon
  * Button("Click"); // type="button", disabled=false automatically
  * ```
  */
-declare function withDefaults<P extends object>(component: Component<P>, defaults: Partial<P>): Component<Partial<P>>;
+/**
+ * Props accepted by a {@link withDefaults} component: every key that has a
+ * default becomes optional; every other key keeps its original required or
+ * optional status.
+ */
+type WithDefaultsProps<P, D> = Omit<P, keyof D> & Partial<Pick<P, Extract<keyof P, keyof D>>>;
+declare function withDefaults<P extends object, const D extends Partial<P> = Partial<P>>(component: Component<P>, defaults: D & {
+    [K in Exclude<keyof D, keyof P>]: never;
+}): Component<WithDefaultsProps<P, D>>;
 /**
  * Composes multiple HOC wrappers into a single wrapper.
  * Applied from right to left (like function composition).
@@ -257,4 +265,4 @@ declare function assertType<T>(value: unknown, validator: Validator<T>, label?:
  */
 declare function createGuard<T>(validator: Validator<T>): (value: unknown) => value is T;
 
-export { type ComponentProps as C, type PropDef as P, RenderProp as R, type Validator as V, type PropSchema as a, assertType as b, compose as c, createGuard as d, createSlots as e, defineComponent as f, defineSlottedComponent as g, defineStrictComponent as h, validators as i, withDefaults as j, withProps as k, withWrapper as l, validateProps as v, withBoundary as w };
+export { type ComponentProps as C, type PropDef as P, RenderProp as R, type Validator as V, type WithDefaultsProps as W, type PropSchema as a, assertType as b, compose as c, createGuard as d, createSlots as e, defineComponent as f, defineSlottedComponent as g, defineStrictComponent as h, validators as i, withDefaults as j, withProps as k, withWrapper as l, validateProps as v, withBoundary as w };

package/dist/{contracts-DBdg9J_a.d.ts → contracts-DRIuclVT.d.ts}

@@ -32,7 +32,15 @@ declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (compon
  * Button("Click"); // type="button", disabled=false automatically
  * ```
  */
-declare function withDefaults<P extends object>(component: Component<P>, defaults: Partial<P>): Component<Partial<P>>;
+/**
+ * Props accepted by a {@link withDefaults} component: every key that has a
+ * default becomes optional; every other key keeps its original required or
+ * optional status.
+ */
+type WithDefaultsProps<P, D> = Omit<P, keyof D> & Partial<Pick<P, Extract<keyof P, keyof D>>>;
+declare function withDefaults<P extends object, const D extends Partial<P> = Partial<P>>(component: Component<P>, defaults: D & {
+    [K in Exclude<keyof D, keyof P>]: never;
+}): Component<WithDefaultsProps<P, D>>;
 /**
  * Composes multiple HOC wrappers into a single wrapper.
  * Applied from right to left (like function composition).
@@ -257,4 +265,4 @@ declare function assertType<T>(value: unknown, validator: Validator<T>, label?:
  */
 declare function createGuard<T>(validator: Validator<T>): (value: unknown) => value is T;
 
-export { type ComponentProps as C, type PropDef as P, RenderProp as R, type Validator as V, type PropSchema as a, assertType as b, compose as c, createGuard as d, createSlots as e, defineComponent as f, defineSlottedComponent as g, defineStrictComponent as h, validators as i, withDefaults as j, withProps as k, withWrapper as l, validateProps as v, withBoundary as w };
+export { type ComponentProps as C, type PropDef as P, RenderProp as R, type Validator as V, type WithDefaultsProps as W, type PropSchema as a, assertType as b, compose as c, createGuard as d, createSlots as e, defineComponent as f, defineSlottedComponent as g, defineStrictComponent as h, validators as i, withDefaults as j, withProps as k, withWrapper as l, validateProps as v, withBoundary as w };

package/dist/{customElement-CNZxEB9G.d.ts → customElement-MmInOW1U.d.cts}

@@ -28,6 +28,16 @@ interface FormReturn<T extends object> {
     handleSubmit: (onSubmit: (values: T) => void | Promise<void>) => (e?: Event) => void;
     reset: () => void;
     setError: (field: keyof T, message: string) => void;
+    /**
+     * Release the form's derived graph: every field `error` and the `errors`,
+     * `isValid`, `isDirty`, `touched` and `values` aggregates. Call it when the
+     * form's owner goes away, e.g. `onCleanup(f.dispose, formElement)`.
+     *
+     * Afterwards the derived accessors are inert — they return their last
+     * settled values and never recompute — while field `value()`/`set()` keep
+     * working as plain signals. Idempotent.
+     */
+    dispose: () => void;
 }
 /**
  * Require a non-empty value. Rejects `null`, `undefined`, `""` and `[]`.
@@ -148,6 +158,17 @@ interface VirtualListProps<T> {
 }
 /**
  * VirtualList renders only visible items for efficient large-list rendering.
+ *
+ * Scope — it virtualizes ONE axis:
+ *   - vertical only, inside a container of fixed `containerHeight`;
+ *   - every item has the same fixed `itemHeight`;
+ *   - on each scroll or `items()` change the visible window is disposed and
+ *     re-rendered through `renderItem` (no keyed reuse of item nodes);
+ *   - no horizontal virtualization, frozen rows/columns or sticky headers.
+ *
+ * Two-axis content (spreadsheets, large grids with frozen headers) needs its
+ * own windowing, typically a keyed `each()` over the visible row indices with a
+ * nested keyed `each()` over the visible column indices.
  */
 declare function VirtualList<T>(props: VirtualListProps<T>): HTMLElement;
 
@@ -228,6 +249,12 @@ declare function FocusTrap(nodes: HTMLElement, options?: {
  * Supports two calling styles:
  * - String combo:   hotkey("ctrl+shift+z", handler)
  * - Explicit flags: hotkey("z", handler, { ctrl: true, shift: true })
+ *
+ * Combo modifiers: `ctrl`/`control`, `shift`, `alt`/`option`,
+ * `meta`/`cmd`/`command`, and `mod` — Cmd on Apple platforms, Ctrl
+ * everywhere else. An unknown modifier throws, because dropping it would
+ * make the shortcut fire on the bare key. The `+` key is written as a
+ * trailing plus: `hotkey("+", h)`, `hotkey("ctrl++", h)`.
  */
 declare function hotkey(combo: string, handler: (e: KeyboardEvent) => void, options?: {
     ctrl?: boolean;
@@ -302,6 +329,12 @@ declare function bindAttrs(el: HTMLElement, attrs: Record<string, AttributeSourc
  * Reactively toggle a boolean attribute (like disabled, readonly, hidden).
  * When the value is truthy the attribute is present (set to ""),
  * when falsy the attribute is removed entirely.
+ *
+ * `aria-*` names are the exception, as in every attribute writer: ARIA states
+ * are "true"/"false" tokens, and a missing state means "not applicable" rather
+ * than `false`, so `bindBoolAttr(el, "aria-busy", false)` writes
+ * `aria-busy="false"`. This helper cannot remove an ARIA attribute; use
+ * `bindAttribute(el, "aria-busy", () => (busy() ? true : null))` for that.
  * Returns a teardown function to stop reactive tracking.
  *
  * The attribute NAME is policed too: `bindBoolAttr(el, "onclick", true)` would
@@ -403,14 +436,7 @@ declare function infiniteScroll(options: {
     dispose: () => void;
 };
 
-/**
- * pagination provides reactive pagination state and controls.
- */
-declare function pagination(options: {
-    totalItems: () => number;
-    pageSize?: number;
-    initialPage?: number;
-}): {
+interface PaginationResult {
     page: () => number;
     pageSize: () => number;
     totalPages: () => number;
@@ -419,11 +445,34 @@ declare function pagination(options: {
     goTo: (page: number) => void;
     startIndex: () => number;
     endIndex: () => number;
-};
+    /**
+     * Release the subscriptions to `totalItems`. Call it when the pagination is
+     * discarded before the state it reads. Afterwards the accessors return their
+     * last values and the controls no longer move the page. Idempotent.
+     */
+    dispose: () => void;
+}
+/**
+ * pagination provides reactive pagination state and controls.
+ *
+ * It subscribes to the caller's `totalItems` getter, which usually lives longer
+ * than the pagination itself (a store, a query result). Call `dispose()` when
+ * the pagination is no longer used, e.g. `onUnmount(pager.dispose, el)`.
+ */
+declare function pagination(options: {
+    totalItems: () => number;
+    pageSize?: number;
+    initialPage?: number;
+}): PaginationResult;
 
 /**
  * eventBus creates a typed publish/subscribe event system.
  * No reactive state needed -- pure event dispatching.
+ *
+ * `emit()` delivers to the handlers registered when it starts. A throwing
+ * handler is reported through the runtime error pipeline and the remaining
+ * handlers still run. Handlers added during delivery receive the next event;
+ * handlers removed (or cleared) during delivery are skipped for the rest of it.
  */
 declare function eventBus<T extends object>(): {
     on: <K extends keyof T>(event: K, handler: (data: T[K]) => void) => () => void;
@@ -458,4 +507,4 @@ declare function defineElement(name: string, component: (props: Record<string, u
  */
 declare function svgElement(tag: string, props?: Record<string, unknown>, ...nodes: (SVGElement | string)[]): SVGElement;
 
-export { type AttributeSource as A, type BoundFieldProps as B, type CustomElementOptions as C, intersection as D, lazyLoad as E, type FieldConfig as F, matchesPattern as G, max as H, type IntersectionResult as I, maxLength as J, min as K, minLength as L, type MaskOptions as M, pagination as N, phoneMask as O, removeScopedStyle as P, required as Q, scopedStyle as R, ssnMask as S, type Toast as T, svgElement as U, type ValidatorFn as V, timeMask as W, toast as X, withScopedStyle as Y, zipMask as Z, __resetDialogStack as _, type AttributeValue as a, FocusTrap as b, type FormConfig as c, type FormField as d, type FormReturn as e, type ToastInstance as f, VirtualList as g, type VirtualListProps as h, announce as i, aria as j, bindAttrs as k, bindBoolAttr as l, bindData as m, bindField as n, creditCardMask as o, custom as p, dateMask as q, defineElement as r, dialog as s, email as t, eventBus as u, focus as v, form as w, hotkey as x, infiniteScroll as y, inputMask as z };
+export { zipMask as $, type AttributeSource as A, type BoundFieldProps as B, type CustomElementOptions as C, intersection as D, lazyLoad as E, type FieldConfig as F, matchesPattern as G, max as H, type IntersectionResult as I, maxLength as J, min as K, minLength as L, type MaskOptions as M, pagination as N, phoneMask as O, type PaginationResult as P, removeScopedStyle as Q, required as R, scopedStyle as S, type Toast as T, ssnMask as U, type ValidatorFn as V, svgElement as W, timeMask as X, toast as Y, withScopedStyle as Z, __resetDialogStack as _, type AttributeValue as a, FocusTrap as b, type FormConfig as c, type FormField as d, type FormReturn as e, type ToastInstance as f, VirtualList as g, type VirtualListProps as h, announce as i, aria as j, bindAttrs as k, bindBoolAttr as l, bindData as m, bindField as n, creditCardMask as o, custom as p, dateMask as q, defineElement as r, dialog as s, email as t, eventBus as u, focus as v, form as w, hotkey as x, infiniteScroll as y, inputMask as z };

package/dist/{customElement-CNZxEB9G.d.cts → customElement-MmInOW1U.d.ts}

@@ -28,6 +28,16 @@ interface FormReturn<T extends object> {
     handleSubmit: (onSubmit: (values: T) => void | Promise<void>) => (e?: Event) => void;
     reset: () => void;
     setError: (field: keyof T, message: string) => void;
+    /**
+     * Release the form's derived graph: every field `error` and the `errors`,
+     * `isValid`, `isDirty`, `touched` and `values` aggregates. Call it when the
+     * form's owner goes away, e.g. `onCleanup(f.dispose, formElement)`.
+     *
+     * Afterwards the derived accessors are inert — they return their last
+     * settled values and never recompute — while field `value()`/`set()` keep
+     * working as plain signals. Idempotent.
+     */
+    dispose: () => void;
 }
 /**
  * Require a non-empty value. Rejects `null`, `undefined`, `""` and `[]`.
@@ -148,6 +158,17 @@ interface VirtualListProps<T> {
 }
 /**
  * VirtualList renders only visible items for efficient large-list rendering.
+ *
+ * Scope — it virtualizes ONE axis:
+ *   - vertical only, inside a container of fixed `containerHeight`;
+ *   - every item has the same fixed `itemHeight`;
+ *   - on each scroll or `items()` change the visible window is disposed and
+ *     re-rendered through `renderItem` (no keyed reuse of item nodes);
+ *   - no horizontal virtualization, frozen rows/columns or sticky headers.
+ *
+ * Two-axis content (spreadsheets, large grids with frozen headers) needs its
+ * own windowing, typically a keyed `each()` over the visible row indices with a
+ * nested keyed `each()` over the visible column indices.
  */
 declare function VirtualList<T>(props: VirtualListProps<T>): HTMLElement;
 
@@ -228,6 +249,12 @@ declare function FocusTrap(nodes: HTMLElement, options?: {
  * Supports two calling styles:
  * - String combo:   hotkey("ctrl+shift+z", handler)
  * - Explicit flags: hotkey("z", handler, { ctrl: true, shift: true })
+ *
+ * Combo modifiers: `ctrl`/`control`, `shift`, `alt`/`option`,
+ * `meta`/`cmd`/`command`, and `mod` — Cmd on Apple platforms, Ctrl
+ * everywhere else. An unknown modifier throws, because dropping it would
+ * make the shortcut fire on the bare key. The `+` key is written as a
+ * trailing plus: `hotkey("+", h)`, `hotkey("ctrl++", h)`.
  */
 declare function hotkey(combo: string, handler: (e: KeyboardEvent) => void, options?: {
     ctrl?: boolean;
@@ -302,6 +329,12 @@ declare function bindAttrs(el: HTMLElement, attrs: Record<string, AttributeSourc
  * Reactively toggle a boolean attribute (like disabled, readonly, hidden).
  * When the value is truthy the attribute is present (set to ""),
  * when falsy the attribute is removed entirely.
+ *
+ * `aria-*` names are the exception, as in every attribute writer: ARIA states
+ * are "true"/"false" tokens, and a missing state means "not applicable" rather
+ * than `false`, so `bindBoolAttr(el, "aria-busy", false)` writes
+ * `aria-busy="false"`. This helper cannot remove an ARIA attribute; use
+ * `bindAttribute(el, "aria-busy", () => (busy() ? true : null))` for that.
  * Returns a teardown function to stop reactive tracking.
  *
  * The attribute NAME is policed too: `bindBoolAttr(el, "onclick", true)` would
@@ -403,14 +436,7 @@ declare function infiniteScroll(options: {
     dispose: () => void;
 };
 
-/**
- * pagination provides reactive pagination state and controls.
- */
-declare function pagination(options: {
-    totalItems: () => number;
-    pageSize?: number;
-    initialPage?: number;
-}): {
+interface PaginationResult {
     page: () => number;
     pageSize: () => number;
     totalPages: () => number;
@@ -419,11 +445,34 @@ declare function pagination(options: {
     goTo: (page: number) => void;
     startIndex: () => number;
     endIndex: () => number;
-};
+    /**
+     * Release the subscriptions to `totalItems`. Call it when the pagination is
+     * discarded before the state it reads. Afterwards the accessors return their
+     * last values and the controls no longer move the page. Idempotent.
+     */
+    dispose: () => void;
+}
+/**
+ * pagination provides reactive pagination state and controls.
+ *
+ * It subscribes to the caller's `totalItems` getter, which usually lives longer
+ * than the pagination itself (a store, a query result). Call `dispose()` when
+ * the pagination is no longer used, e.g. `onUnmount(pager.dispose, el)`.
+ */
+declare function pagination(options: {
+    totalItems: () => number;
+    pageSize?: number;
+    initialPage?: number;
+}): PaginationResult;
 
 /**
  * eventBus creates a typed publish/subscribe event system.
  * No reactive state needed -- pure event dispatching.
+ *
+ * `emit()` delivers to the handlers registered when it starts. A throwing
+ * handler is reported through the runtime error pipeline and the remaining
+ * handlers still run. Handlers added during delivery receive the next event;
+ * handlers removed (or cleared) during delivery are skipped for the rest of it.
  */
 declare function eventBus<T extends object>(): {
     on: <K extends keyof T>(event: K, handler: (data: T[K]) => void) => () => void;
@@ -458,4 +507,4 @@ declare function defineElement(name: string, component: (props: Record<string, u
  */
 declare function svgElement(tag: string, props?: Record<string, unknown>, ...nodes: (SVGElement | string)[]): SVGElement;
 
-export { type AttributeSource as A, type BoundFieldProps as B, type CustomElementOptions as C, intersection as D, lazyLoad as E, type FieldConfig as F, matchesPattern as G, max as H, type IntersectionResult as I, maxLength as J, min as K, minLength as L, type MaskOptions as M, pagination as N, phoneMask as O, removeScopedStyle as P, required as Q, scopedStyle as R, ssnMask as S, type Toast as T, svgElement as U, type ValidatorFn as V, timeMask as W, toast as X, withScopedStyle as Y, zipMask as Z, __resetDialogStack as _, type AttributeValue as a, FocusTrap as b, type FormConfig as c, type FormField as d, type FormReturn as e, type ToastInstance as f, VirtualList as g, type VirtualListProps as h, announce as i, aria as j, bindAttrs as k, bindBoolAttr as l, bindData as m, bindField as n, creditCardMask as o, custom as p, dateMask as q, defineElement as r, dialog as s, email as t, eventBus as u, focus as v, form as w, hotkey as x, infiniteScroll as y, inputMask as z };
+export { zipMask as $, type AttributeSource as A, type BoundFieldProps as B, type CustomElementOptions as C, intersection as D, lazyLoad as E, type FieldConfig as F, matchesPattern as G, max as H, type IntersectionResult as I, maxLength as J, min as K, minLength as L, type MaskOptions as M, pagination as N, phoneMask as O, type PaginationResult as P, removeScopedStyle as Q, required as R, scopedStyle as S, type Toast as T, ssnMask as U, type ValidatorFn as V, svgElement as W, timeMask as X, toast as Y, withScopedStyle as Z, __resetDialogStack as _, type AttributeValue as a, FocusTrap as b, type FormConfig as c, type FormField as d, type FormReturn as e, type ToastInstance as f, VirtualList as g, type VirtualListProps as h, announce as i, aria as j, bindAttrs as k, bindBoolAttr as l, bindData as m, bindField as n, creditCardMask as o, custom as p, dateMask as q, defineElement as r, dialog as s, email as t, eventBus as u, focus as v, form as w, hotkey as x, infiniteScroll as y, inputMask as z };