sibujs 1.2.0 → 1.3.0

package/dist/ui.d.cts

@@ -1,5 +1,153 @@
 export { B as BoundFieldProps, C as CustomElementOptions, F as FieldConfig, a as FocusTrap, b as FormConfig, c as FormField, d as FormReturn, I as IntersectionResult, M as MaskOptions, T as Toast, e as ToastInstance, V as ValidatorFn, f as VirtualList, g as VirtualListProps, h as announce, i as aria, j as bindAttrs, k as bindBoolAttr, l as bindData, m as bindField, n as creditCardMask, o as custom, p as dateMask, q as defineElement, r as dialog, s as email, t as eventBus, u as focus, v as form, w as hotkey, x as infiniteScroll, y as inputMask, z as intersection, A as lazyLoad, D as matchesPattern, E as max, G as maxLength, H as min, J as minLength, K as pagination, L as phoneMask, N as removeScopedStyle, O as required, P as scopedStyle, Q as ssnMask, R as svgElement, S as timeMask, U as toast, W as withScopedStyle, X as zipMask } from './customElement-D2DJp_xn.cjs';
-export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as composable, d as compose, e as createGuard, f as createSlots, g as defineComponent, h as defineSlottedComponent, i as defineStrictComponent, v as validateProps, j as validators, w as withBoundary, k as withDefaults, l as withProps, m as withWrapper } from './contracts-DOrhwbke.cjs';
+export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as composable, d as compose, e as createGuard, f as createSlots, g as defineComponent, h as defineSlottedComponent, i as defineStrictComponent, v as validateProps, j as validators, w as withBoundary, k as withDefaults, l as withProps, m as withWrapper } from './contracts-DDrwxvJ-.cjs';
+
+interface FormActionHandle<TArgs extends unknown[], TResult> {
+    /** Invoke the action. Rejections become `error()`, resolutions `result()`. */
+    run: (...args: TArgs) => Promise<void>;
+    /** True while the underlying promise is unresolved. */
+    pending: () => boolean;
+    /** Last caught error, or `null`. */
+    error: () => unknown;
+    /** Last resolved value, or `null`. */
+    result: () => TResult | null;
+    /** Clear result and error without affecting an in-flight call. */
+    reset: () => void;
+    /**
+     * A ready-to-attach submit handler for `<form>` elements. Calls
+     * `e.preventDefault()`, builds a `FormData`, and passes it to the
+     * underlying action. Only available when `TArgs = [FormData]`.
+     */
+    onSubmit: (e: Event) => void;
+}
+/**
+ * Wrap an async function into a reactive form-action handle.
+ *
+ * @example
+ * ```ts
+ * const save = formAction(async (data: FormData) => {
+ *   const res = await fetch("/api/save", { method: "POST", body: data });
+ *   if (!res.ok) throw new Error("Save failed");
+ *   return res.json();
+ * });
+ *
+ * form({
+ *   on: { submit: save.onSubmit },
+ *   nodes: [
+ *     input({ name: "title" }),
+ *     button({ disabled: save.pending, nodes: () => (save.pending() ? "Saving..." : "Save") }),
+ *     when(() => save.error() != null, () => div({ class: "error", nodes: () => String(save.error()) })),
+ *   ],
+ * });
+ * ```
+ */
+declare function formAction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>): FormActionHandle<TArgs, TResult>;
+
+interface FocusManagerOptions {
+    /** CSS selector for focusable descendants. Default matches common form/link controls. */
+    selector?: string;
+    /** Wrap focus from last→first and first→last. Default `true`. */
+    loop?: boolean;
+}
+interface FocusManagerHandle {
+    /** Move focus to the first focusable descendant. */
+    focusFirst: () => void;
+    /** Move focus to the last focusable descendant. */
+    focusLast: () => void;
+    /** Move focus to the next focusable descendant relative to `document.activeElement`. */
+    focusNext: () => void;
+    /** Move focus to the previous focusable descendant relative to `document.activeElement`. */
+    focusPrev: () => void;
+    /** Return the currently focusable descendants, in order. */
+    items: () => HTMLElement[];
+}
+/**
+ * Build a focus manager scoped to a container. The manager offers
+ * `focusFirst` / `focusLast` / `focusNext` / `focusPrev` helpers that
+ * walk the focusable descendants in DOM order. It is the building
+ * block for custom listboxes, toolbars, and menus.
+ *
+ * This is a DOM-read utility — the item list is fetched fresh on every
+ * call so dynamic content is handled automatically.
+ */
+declare function createFocusManager(container: HTMLElement, options?: FocusManagerOptions): FocusManagerHandle;
+interface ListboxOptions {
+    /** Whether the listbox is multi-select. Default `false`. */
+    multiple?: boolean;
+    /** CSS selector for option elements. Default `[role="option"]`. */
+    optionSelector?: string;
+    /** Called when the user commits a selection. */
+    onSelect?: (value: string) => void;
+}
+interface ListboxHandle {
+    /** Reactive value: the currently-active (highlighted) option value. */
+    activeValue: () => string | null;
+    /** Reactive value: the currently-selected option value (single-select) or CSV (multiple). */
+    selectedValue: () => string | null;
+    /** Stable id that can be used as `aria-activedescendant` on the trigger. */
+    activeDescendantId: () => string | null;
+    /** Cleanup: removes listeners. */
+    dispose: () => void;
+}
+/**
+ * Build an ARIA listbox on top of an existing container element. The
+ * listbox wires:
+ *   - `role="listbox"` + `aria-multiselectable` on the container
+ *   - keyboard navigation (Arrow keys, Home, End, Enter, Space)
+ *   - `aria-activedescendant` tracking
+ *   - option highlight via `data-highlighted`
+ *
+ * Each option must expose a `data-value` attribute. Options get a
+ * stable `id` on mount so the container's `aria-activedescendant`
+ * can point at the active one.
+ *
+ * @example
+ * ```ts
+ * const container = ul({ nodes: [
+ *   li({ role: "option", "data-value": "a", nodes: "Apple" }),
+ *   li({ role: "option", "data-value": "b", nodes: "Banana" }),
+ * ]}) as HTMLElement;
+ *
+ * const lb = createListbox(container, { onSelect: v => console.log(v) });
+ * ```
+ */
+declare function createListbox(container: HTMLElement, options?: ListboxOptions): ListboxHandle;
+interface DialogAriaOptions {
+    /** Labelled-by id — the dialog title's id. */
+    labelledBy?: string;
+    /** Described-by id — the dialog description's id. */
+    describedBy?: string;
+    /** Modal dialog (true) or alertdialog (false for "alert"). Default `true`. */
+    modal?: boolean;
+    /** Use `role="alertdialog"` instead of `role="dialog"`. */
+    alert?: boolean;
+}
+interface DialogAriaHandle {
+    /** Auto-generated id that should be put on the title element. */
+    titleId: string;
+    /** Auto-generated id that should be put on the description element. */
+    descriptionId: string;
+}
+/**
+ * Apply the ARIA attributes needed for an accessible dialog to an
+ * existing element. Returns stable ids that the caller can pass to the
+ * title and description children so `aria-labelledby` / `aria-describedby`
+ * resolve correctly.
+ *
+ * Does NOT handle focus trapping — use `FocusTrap` or `createFocusManager`
+ * for that. Does NOT handle escape-to-close — wire that in the caller.
+ * The primitive is intentionally tight: it only owns the ARIA surface.
+ *
+ * @example
+ * ```ts
+ * const dlg = document.createElement("div");
+ * const aria = createDialogAria(dlg, { alert: false });
+ * dlg.append(
+ *   h2({ id: aria.titleId, nodes: "Delete?" }),
+ *   p({ id: aria.descriptionId, nodes: "This cannot be undone." }),
+ * );
+ * ```
+ */
+declare function createDialogAria(element: HTMLElement, options?: DialogAriaOptions): DialogAriaHandle;
 
 /**
  * lazyEffect creates an effect that only activates when the target element
@@ -25,4 +173,106 @@ export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V
  */
 declare function lazyEffect(element: HTMLElement, effectFn: () => void, options?: IntersectionObserverInit): () => void;
 
-export { lazyEffect };
+/**
+ * Declarative, disposable timers.
+ *
+ * The native `setInterval` / `setTimeout` are easy to leak if the owning
+ * component is destroyed before they fire. These helpers return a handle
+ * with a `stop()` function plus (for interval) `pause()` / `resume()`, and
+ * optionally integrate with the sibujs disposal lifecycle through the
+ * returned cleanup.
+ *
+ * Neither helper depends on any reactive context — they're pure JS with
+ * nicer ergonomics for UIs that need to start and stop timers safely.
+ */
+interface IntervalHandle {
+    /** Stop the interval. Safe to call multiple times. */
+    stop: () => void;
+    /** Pause (preserving remaining ticks until `resume()`). */
+    pause: () => void;
+    /** Resume a paused interval. */
+    resume: () => void;
+    /** Whether the interval is currently running. */
+    isRunning: () => boolean;
+}
+/**
+ * Like `setInterval(fn, ms)` but returns a handle that can be stopped,
+ * paused, and resumed without leaking closures.
+ *
+ * @example
+ * ```ts
+ * const tick = interval(() => setCount(c => c + 1), 1000);
+ * // later
+ * tick.pause();
+ * tick.resume();
+ * tick.stop();
+ * ```
+ */
+declare function interval(fn: () => void, ms: number): IntervalHandle;
+interface TimeoutHandle {
+    /** Cancel the pending timeout. No-op if already fired. */
+    cancel: () => void;
+    /** Whether the callback has run or been cancelled. */
+    isPending: () => boolean;
+}
+/**
+ * Like `setTimeout(fn, ms)` but returns a handle with an explicit `cancel()`.
+ *
+ * @example
+ * ```ts
+ * const t = timeout(() => setVisible(false), 3000);
+ * // cancel on user interaction
+ * input({ on: { focus: () => t.cancel() } });
+ * ```
+ */
+declare function timeout(fn: () => void, ms: number): TimeoutHandle;
+
+/**
+ * hover attaches reactive hover tracking to an element. Uses `pointerenter`
+ * and `pointerleave` so it works on touch devices where a sustained press
+ * triggers a hover state.
+ *
+ * @param target Element to track
+ * @returns `{ hovered, dispose }` — reactive boolean plus cleanup
+ *
+ * @example
+ * ```ts
+ * const el = div({ class: "card" });
+ * const h = hover(el);
+ * effect(() => { el.classList.toggle("lifted", h.hovered()); });
+ * ```
+ */
+declare function hover(target: HTMLElement): {
+    hovered: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * scrollLock stacks body scroll locks — useful when a modal / drawer / sheet
+ * stack is open and background scroll must be suppressed.
+ *
+ * Each `lock()` call increments an internal counter and applies
+ * `overflow: hidden` + preserves the scrollbar-width padding to prevent
+ * layout shift. Calling `unlock()` decrements; when the counter hits zero
+ * the previous body style is restored.
+ *
+ * Safe to call from multiple concurrent overlays — the last one to unlock
+ * releases the lock.
+ *
+ * @example
+ * ```ts
+ * const lock = scrollLock();
+ * lock.lock();
+ * // ... modal open
+ * lock.unlock();
+ * ```
+ */
+interface ScrollLockHandle {
+    /** Activate a lock. Idempotent per-handle if called twice. */
+    lock: () => void;
+    /** Release this handle's lock. Idempotent. */
+    unlock: () => void;
+}
+declare function scrollLock(): ScrollLockHandle;
+
+export { type DialogAriaHandle, type DialogAriaOptions, type FocusManagerHandle, type FocusManagerOptions, type FormActionHandle, type IntervalHandle, type ListboxHandle, type ListboxOptions, type ScrollLockHandle, type TimeoutHandle, createDialogAria, createFocusManager, createListbox, formAction, hover, interval, lazyEffect, scrollLock, timeout };

package/dist/ui.d.ts

@@ -1,5 +1,153 @@
 export { B as BoundFieldProps, C as CustomElementOptions, F as FieldConfig, a as FocusTrap, b as FormConfig, c as FormField, d as FormReturn, I as IntersectionResult, M as MaskOptions, T as Toast, e as ToastInstance, V as ValidatorFn, f as VirtualList, g as VirtualListProps, h as announce, i as aria, j as bindAttrs, k as bindBoolAttr, l as bindData, m as bindField, n as creditCardMask, o as custom, p as dateMask, q as defineElement, r as dialog, s as email, t as eventBus, u as focus, v as form, w as hotkey, x as infiniteScroll, y as inputMask, z as intersection, A as lazyLoad, D as matchesPattern, E as max, G as maxLength, H as min, J as minLength, K as pagination, L as phoneMask, N as removeScopedStyle, O as required, P as scopedStyle, Q as ssnMask, R as svgElement, S as timeMask, U as toast, W as withScopedStyle, X as zipMask } from './customElement-D2DJp_xn.js';
-export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as composable, d as compose, e as createGuard, f as createSlots, g as defineComponent, h as defineSlottedComponent, i as defineStrictComponent, v as validateProps, j as validators, w as withBoundary, k as withDefaults, l as withProps, m as withWrapper } from './contracts-DOrhwbke.js';
+export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as composable, d as compose, e as createGuard, f as createSlots, g as defineComponent, h as defineSlottedComponent, i as defineStrictComponent, v as validateProps, j as validators, w as withBoundary, k as withDefaults, l as withProps, m as withWrapper } from './contracts-DDrwxvJ-.js';
+
+interface FormActionHandle<TArgs extends unknown[], TResult> {
+    /** Invoke the action. Rejections become `error()`, resolutions `result()`. */
+    run: (...args: TArgs) => Promise<void>;
+    /** True while the underlying promise is unresolved. */
+    pending: () => boolean;
+    /** Last caught error, or `null`. */
+    error: () => unknown;
+    /** Last resolved value, or `null`. */
+    result: () => TResult | null;
+    /** Clear result and error without affecting an in-flight call. */
+    reset: () => void;
+    /**
+     * A ready-to-attach submit handler for `<form>` elements. Calls
+     * `e.preventDefault()`, builds a `FormData`, and passes it to the
+     * underlying action. Only available when `TArgs = [FormData]`.
+     */
+    onSubmit: (e: Event) => void;
+}
+/**
+ * Wrap an async function into a reactive form-action handle.
+ *
+ * @example
+ * ```ts
+ * const save = formAction(async (data: FormData) => {
+ *   const res = await fetch("/api/save", { method: "POST", body: data });
+ *   if (!res.ok) throw new Error("Save failed");
+ *   return res.json();
+ * });
+ *
+ * form({
+ *   on: { submit: save.onSubmit },
+ *   nodes: [
+ *     input({ name: "title" }),
+ *     button({ disabled: save.pending, nodes: () => (save.pending() ? "Saving..." : "Save") }),
+ *     when(() => save.error() != null, () => div({ class: "error", nodes: () => String(save.error()) })),
+ *   ],
+ * });
+ * ```
+ */
+declare function formAction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>): FormActionHandle<TArgs, TResult>;
+
+interface FocusManagerOptions {
+    /** CSS selector for focusable descendants. Default matches common form/link controls. */
+    selector?: string;
+    /** Wrap focus from last→first and first→last. Default `true`. */
+    loop?: boolean;
+}
+interface FocusManagerHandle {
+    /** Move focus to the first focusable descendant. */
+    focusFirst: () => void;
+    /** Move focus to the last focusable descendant. */
+    focusLast: () => void;
+    /** Move focus to the next focusable descendant relative to `document.activeElement`. */
+    focusNext: () => void;
+    /** Move focus to the previous focusable descendant relative to `document.activeElement`. */
+    focusPrev: () => void;
+    /** Return the currently focusable descendants, in order. */
+    items: () => HTMLElement[];
+}
+/**
+ * Build a focus manager scoped to a container. The manager offers
+ * `focusFirst` / `focusLast` / `focusNext` / `focusPrev` helpers that
+ * walk the focusable descendants in DOM order. It is the building
+ * block for custom listboxes, toolbars, and menus.
+ *
+ * This is a DOM-read utility — the item list is fetched fresh on every
+ * call so dynamic content is handled automatically.
+ */
+declare function createFocusManager(container: HTMLElement, options?: FocusManagerOptions): FocusManagerHandle;
+interface ListboxOptions {
+    /** Whether the listbox is multi-select. Default `false`. */
+    multiple?: boolean;
+    /** CSS selector for option elements. Default `[role="option"]`. */
+    optionSelector?: string;
+    /** Called when the user commits a selection. */
+    onSelect?: (value: string) => void;
+}
+interface ListboxHandle {
+    /** Reactive value: the currently-active (highlighted) option value. */
+    activeValue: () => string | null;
+    /** Reactive value: the currently-selected option value (single-select) or CSV (multiple). */
+    selectedValue: () => string | null;
+    /** Stable id that can be used as `aria-activedescendant` on the trigger. */
+    activeDescendantId: () => string | null;
+    /** Cleanup: removes listeners. */
+    dispose: () => void;
+}
+/**
+ * Build an ARIA listbox on top of an existing container element. The
+ * listbox wires:
+ *   - `role="listbox"` + `aria-multiselectable` on the container
+ *   - keyboard navigation (Arrow keys, Home, End, Enter, Space)
+ *   - `aria-activedescendant` tracking
+ *   - option highlight via `data-highlighted`
+ *
+ * Each option must expose a `data-value` attribute. Options get a
+ * stable `id` on mount so the container's `aria-activedescendant`
+ * can point at the active one.
+ *
+ * @example
+ * ```ts
+ * const container = ul({ nodes: [
+ *   li({ role: "option", "data-value": "a", nodes: "Apple" }),
+ *   li({ role: "option", "data-value": "b", nodes: "Banana" }),
+ * ]}) as HTMLElement;
+ *
+ * const lb = createListbox(container, { onSelect: v => console.log(v) });
+ * ```
+ */
+declare function createListbox(container: HTMLElement, options?: ListboxOptions): ListboxHandle;
+interface DialogAriaOptions {
+    /** Labelled-by id — the dialog title's id. */
+    labelledBy?: string;
+    /** Described-by id — the dialog description's id. */
+    describedBy?: string;
+    /** Modal dialog (true) or alertdialog (false for "alert"). Default `true`. */
+    modal?: boolean;
+    /** Use `role="alertdialog"` instead of `role="dialog"`. */
+    alert?: boolean;
+}
+interface DialogAriaHandle {
+    /** Auto-generated id that should be put on the title element. */
+    titleId: string;
+    /** Auto-generated id that should be put on the description element. */
+    descriptionId: string;
+}
+/**
+ * Apply the ARIA attributes needed for an accessible dialog to an
+ * existing element. Returns stable ids that the caller can pass to the
+ * title and description children so `aria-labelledby` / `aria-describedby`
+ * resolve correctly.
+ *
+ * Does NOT handle focus trapping — use `FocusTrap` or `createFocusManager`
+ * for that. Does NOT handle escape-to-close — wire that in the caller.
+ * The primitive is intentionally tight: it only owns the ARIA surface.
+ *
+ * @example
+ * ```ts
+ * const dlg = document.createElement("div");
+ * const aria = createDialogAria(dlg, { alert: false });
+ * dlg.append(
+ *   h2({ id: aria.titleId, nodes: "Delete?" }),
+ *   p({ id: aria.descriptionId, nodes: "This cannot be undone." }),
+ * );
+ * ```
+ */
+declare function createDialogAria(element: HTMLElement, options?: DialogAriaOptions): DialogAriaHandle;
 
 /**
  * lazyEffect creates an effect that only activates when the target element
@@ -25,4 +173,106 @@ export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V
  */
 declare function lazyEffect(element: HTMLElement, effectFn: () => void, options?: IntersectionObserverInit): () => void;
 
-export { lazyEffect };
+/**
+ * Declarative, disposable timers.
+ *
+ * The native `setInterval` / `setTimeout` are easy to leak if the owning
+ * component is destroyed before they fire. These helpers return a handle
+ * with a `stop()` function plus (for interval) `pause()` / `resume()`, and
+ * optionally integrate with the sibujs disposal lifecycle through the
+ * returned cleanup.
+ *
+ * Neither helper depends on any reactive context — they're pure JS with
+ * nicer ergonomics for UIs that need to start and stop timers safely.
+ */
+interface IntervalHandle {
+    /** Stop the interval. Safe to call multiple times. */
+    stop: () => void;
+    /** Pause (preserving remaining ticks until `resume()`). */
+    pause: () => void;
+    /** Resume a paused interval. */
+    resume: () => void;
+    /** Whether the interval is currently running. */
+    isRunning: () => boolean;
+}
+/**
+ * Like `setInterval(fn, ms)` but returns a handle that can be stopped,
+ * paused, and resumed without leaking closures.
+ *
+ * @example
+ * ```ts
+ * const tick = interval(() => setCount(c => c + 1), 1000);
+ * // later
+ * tick.pause();
+ * tick.resume();
+ * tick.stop();
+ * ```
+ */
+declare function interval(fn: () => void, ms: number): IntervalHandle;
+interface TimeoutHandle {
+    /** Cancel the pending timeout. No-op if already fired. */
+    cancel: () => void;
+    /** Whether the callback has run or been cancelled. */
+    isPending: () => boolean;
+}
+/**
+ * Like `setTimeout(fn, ms)` but returns a handle with an explicit `cancel()`.
+ *
+ * @example
+ * ```ts
+ * const t = timeout(() => setVisible(false), 3000);
+ * // cancel on user interaction
+ * input({ on: { focus: () => t.cancel() } });
+ * ```
+ */
+declare function timeout(fn: () => void, ms: number): TimeoutHandle;
+
+/**
+ * hover attaches reactive hover tracking to an element. Uses `pointerenter`
+ * and `pointerleave` so it works on touch devices where a sustained press
+ * triggers a hover state.
+ *
+ * @param target Element to track
+ * @returns `{ hovered, dispose }` — reactive boolean plus cleanup
+ *
+ * @example
+ * ```ts
+ * const el = div({ class: "card" });
+ * const h = hover(el);
+ * effect(() => { el.classList.toggle("lifted", h.hovered()); });
+ * ```
+ */
+declare function hover(target: HTMLElement): {
+    hovered: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * scrollLock stacks body scroll locks — useful when a modal / drawer / sheet
+ * stack is open and background scroll must be suppressed.
+ *
+ * Each `lock()` call increments an internal counter and applies
+ * `overflow: hidden` + preserves the scrollbar-width padding to prevent
+ * layout shift. Calling `unlock()` decrements; when the counter hits zero
+ * the previous body style is restored.
+ *
+ * Safe to call from multiple concurrent overlays — the last one to unlock
+ * releases the lock.
+ *
+ * @example
+ * ```ts
+ * const lock = scrollLock();
+ * lock.lock();
+ * // ... modal open
+ * lock.unlock();
+ * ```
+ */
+interface ScrollLockHandle {
+    /** Activate a lock. Idempotent per-handle if called twice. */
+    lock: () => void;
+    /** Release this handle's lock. Idempotent. */
+    unlock: () => void;
+}
+declare function scrollLock(): ScrollLockHandle;
+
+export { type DialogAriaHandle, type DialogAriaOptions, type FocusManagerHandle, type FocusManagerOptions, type FormActionHandle, type IntervalHandle, type ListboxHandle, type ListboxOptions, type ScrollLockHandle, type TimeoutHandle, createDialogAria, createFocusManager, createListbox, formAction, hover, interval, lazyEffect, scrollLock, timeout };