sibujs 4.12.0 → 4.13.1

package/dist/widgets.d.ts

@@ -1,285 +1,117 @@
-interface ComboboxOptions<T> {
-    items: T[];
-    filterFn?: (item: T, query: string) => boolean;
-    itemToString?: (item: T) => string;
-}
-declare function combobox<T>(options: ComboboxOptions<T>): {
-    query: () => string;
-    setQuery: (q: string) => void;
-    filteredItems: () => T[];
-    selectedItem: () => T | null;
-    select: (item: T) => void;
-    highlightedIndex: () => number;
-    highlightNext: () => void;
-    highlightPrev: () => void;
-    selectHighlighted: () => void;
-    isOpen: () => boolean;
-    open: () => void;
-    close: () => void;
-    /** WAI-ARIA Combobox 1.2 wiring: `role=combobox` on input,
-     *  `aria-expanded`/`aria-controls`/`aria-activedescendant`, listbox option
-     *  ids, Down/Up/Enter/Escape/Home/End. Returns dispose. */
-    bind: (els: {
-        input: HTMLInputElement;
-        listbox: HTMLElement;
-        option: (item: T, index: number) => HTMLElement | null;
-    }) => () => void;
-};
-
-interface TabsOptions {
-    tabs: Array<{
-        id: string;
-        label: string;
-        disabled?: boolean;
-    }>;
-    defaultTab?: string;
-}
-interface TabsAriaBinding {
-    /** WAI-ARIA Tabs pattern — wires `role`/`aria-*` and arrow/Home/End keys
-     *  to the provided tablist + per-tab elements. Returns dispose. */
-    bind: (els: {
-        tablist: HTMLElement;
-        tabs: Record<string, HTMLElement>;
-        panels?: Record<string, HTMLElement>;
-    }) => () => void;
-}
-declare function tabs(options: TabsOptions): {
-    activeTab: () => string;
-    setActiveTab: (id: string) => void;
-    tabs: () => Array<{
-        id: string;
-        label: string;
-        disabled?: boolean;
-        isActive: boolean;
-    }>;
-    nextTab: () => void;
-    prevTab: () => void;
-    isActive: (id: string) => boolean;
-    bind: TabsAriaBinding["bind"];
-};
-
-interface AccordionOptions {
-    items: Array<{
-        id: string;
-        label: string;
-    }>;
-    multiple?: boolean;
-    defaultExpanded?: string[];
-}
-interface AccordionAriaBinding {
-    /** WAI-ARIA Accordion pattern — wires `aria-expanded`/`aria-controls`,
-     *  Enter/Space toggle, and panel `role=region`. Returns dispose.
-     *  Pass `root` (any stable container element) to anchor the WeakMap
-     *  idempotency key — without it, double-bind detection falls back to
-     *  the first trigger and breaks if items re-render. */
-    bind: (els: {
-        root?: HTMLElement;
-        triggers: Record<string, HTMLElement>;
-        panels: Record<string, HTMLElement>;
-    }) => () => void;
-}
-declare function accordion(options: AccordionOptions): {
-    items: () => Array<{
-        id: string;
-        label: string;
-        isExpanded: boolean;
-    }>;
-    toggle: (id: string) => void;
-    expand: (id: string) => void;
-    collapse: (id: string) => void;
-    expandAll: () => void;
-    collapseAll: () => void;
-    isExpanded: (id: string) => boolean;
-    bind: AccordionAriaBinding["bind"];
-};
+export { A as AccordionAriaBinding, a as AccordionOptions, C as ComboboxOptions, D as DatePickerOptions, F as FileUploadOptions, S as SelectOptions, b as SetContentOptions, T as TabsAriaBinding, c as TabsOptions, d as accordion, e as combobox, f as contentEditable, g as datePicker, h as fileUpload, p as popover, s as select, t as tabs, i as tooltip } from './datePicker-DxuxWpgF.js';
 
 /**
- * popover provides simple state management for positioned floating content.
- * Manages open/close/toggle without any DOM coupling.
+ * Whether a `sibujs/widgets` widget already acted on this key event. Page-level
+ * shortcuts test it so a key the user pressed INSIDE a widget (an arrow in a
+ * select menu, Escape in a popover) does not also trigger the page's binding.
+ *
+ * @param event Any event; only key events are ever claimed.
+ * @returns `true` when a widget consumed the event.
+ *
+ * @example
+ * ```ts
+ * document.addEventListener("keydown", (e) => {
+ *   if (isWidgetKeyEvent(e)) return; // the dropdown already handled it
+ *   if (e.key === "ArrowLeft") nudgeSelectedLayer(-1, 0);
+ *   if (e.key === "Escape") deselect();
+ * });
+ * ```
  */
-declare function popover(): {
-    isOpen: () => boolean;
-    open: () => void;
-    close: () => void;
-    toggle: () => void;
-    /** WAI-ARIA non-modal dialog wiring: `role=dialog`, `aria-expanded` on
-     *  trigger, Escape closes, click-outside closes. Returns dispose. */
-    bind: (els: {
-        trigger: HTMLElement;
-        popover: HTMLElement;
-        labelledBy?: HTMLElement;
-    }) => () => void;
-};
+declare function isWidgetKeyEvent(event: Event): boolean;
+/**
+ * Name of the widget that claimed `event` (`"selectMenu"`, `"tabs"`, …), or
+ * `null` when no widget did.
+ *
+ * @param event Any event.
+ * @returns The claiming widget's name, or `null`.
+ */
+declare function widgetKeyOwner(event: Event): string | null;
 
-interface SelectOptions<T> {
-    items: T[];
-    multiple?: boolean;
+interface SelectMenuOptions<T> {
+    /** The options, in display order. A getter makes the list reactive. */
+    items: T[] | (() => T[]);
+    /**
+     * The selected item, CONTROLLED: read through this getter, changed only by
+     * the app in response to `onChange`. Omit it for an uncontrolled menu that
+     * keeps its own selection (seeded by `defaultValue`).
+     */
+    value?: () => T | null | undefined;
+    /** Initial selection of an uncontrolled menu. */
+    defaultValue?: T | null;
+    /** Called when the user commits an option (Enter, Space, click, Tab, Alt+Up). */
+    onChange?: (item: T) => void;
+    /** Text used by typeahead. Defaults to `String(item)`. */
     itemToString?: (item: T) => string;
-    /** Optional predicate marking items as disabled — such items are skipped
-     *  by `highlightNext`/`highlightPrev`/typeahead and rejected by `select`. */
+    /** Disabled options are skipped by navigation and typeahead and cannot be committed. */
     isDisabled?: (item: T) => boolean;
+    /** Identity of two items, used to find the selected one. Defaults to `Object.is`. */
+    isEqual?: (a: T, b: T) => boolean;
+    /** How far PageUp / PageDown move the active option. Defaults to 10. */
+    pageSize?: number;
 }
-/**
- * Selection state for a list — single or multiple, with keyboard-friendly
- * helpers. Headless: it owns state, not markup.
- *
- * @param options Item list, selection mode, and comparison strategy.
- * @returns A handle exposing `selectedItem`/`selectedItems` accessors and the
- * `select`, `deselect`, `toggle` and `clear` operations.
- */
-declare function select<T>(options: SelectOptions<T>): {
-    selectedItems: () => T[];
-    selectedItem: () => T | null;
-    select: (item: T) => void;
-    deselect: (item: T) => void;
-    toggle: (item: T) => void;
-    isSelected: (item: T) => boolean;
+interface SelectMenuElements<T> {
+    /** The element that shows the value and opens the list — usually a `<button>`. */
+    trigger: HTMLElement;
+    /** The popup list. Hidden while the menu is closed. */
+    listbox: HTMLElement;
+    /** The element rendering `item`, or null when it is not in the DOM. */
+    option: (item: T, index: number) => HTMLElement | null;
+}
+interface SelectMenu<T> {
+    /** The committed selection. */
+    value: () => T | null;
+    /** Whether the popup list is showing. */
     isOpen: () => boolean;
-    open: () => void;
+    /**
+     * Show the list. The active option is the selected one (or the first enabled
+     * option); pass `"first"` or `"last"` to start from an end instead.
+     */
+    open: (activeAt?: "selected" | "first" | "last") => void;
+    /** Hide the list without changing the selection. */
     close: () => void;
-    highlightedIndex: () => number;
-    highlightNext: () => void;
-    highlightPrev: () => void;
-    selectHighlighted: () => void;
-    clear: () => void;
-    /** WAI-ARIA Listbox wiring: `role=listbox`, `aria-multiselectable`,
-     *  `aria-selected`/`aria-activedescendant`, arrow + Home/End/Enter/Space
-     *  + typeahead. Returns dispose. */
-    bind: (els: {
-        listbox: HTMLElement;
-        option: (item: T, index: number) => HTMLElement | null;
-        itemToString?: (item: T) => string;
-    }) => () => void;
-};
-
-/**
- * tooltip manages tooltip visibility with optional show delay.
- * Timer cleanup is handled via closure variables per the framework convention.
- */
-declare function tooltip(options?: {
-    delay?: number;
-    hideDelay?: number;
-}): {
-    isVisible: () => boolean;
-    show: () => void;
-    hide: () => void;
-    content: () => string;
-    setContent: (text: string) => void;
-    /** WAI-ARIA Tooltip pattern — wires `role=tooltip`, `aria-describedby`,
-     *  Escape-to-dismiss, and pointer hover-grace per WCAG 1.4.13. */
-    bind: (els: {
-        trigger: HTMLElement;
-        tooltip: HTMLElement;
-    }) => () => void;
-};
-
-interface FileUploadOptions {
-    accept?: string;
-    multiple?: boolean;
-    maxSize?: number;
-    onFiles?: (files: File[]) => void;
-}
-declare function fileUpload(options?: FileUploadOptions): {
-    files: () => File[];
-    addFiles: (fileList: FileList | File[]) => void;
-    removeFile: (index: number) => void;
-    clear: () => void;
-    errors: () => string[];
-    isDragOver: () => boolean;
-    setDragOver: (v: boolean) => void;
-    /** Wires native file input + drop zone with proper labeling, hint
-     *  description, and keyboard activation. Returns dispose. */
-    bind: (els: {
-        input: HTMLInputElement;
-        dropZone?: HTMLElement;
-        hint?: HTMLElement;
-        errorRegion?: HTMLElement;
-    }) => () => void;
-};
-
-/**
- * Options for `setContent`.
- *
- * WARNING: passing `sanitize: false` bypasses the built-in protection and
- * requires the caller to guarantee the HTML has already been sanitized with
- * a trusted library. Any untrusted input that reaches `setContent` with
- * `sanitize: false` is an XSS vector.
- */
-interface SetContentOptions {
-    /** Raw HTML to assign. Sanitized by default (tags are stripped). */
-    html?: string;
-    /** Plain text. Always safe — assigned via `textContent`. */
-    text?: string;
+    /** Open when closed, close when open. */
+    toggle: () => void;
+    /** Index of the option the keyboard is on (visual focus), or -1. */
+    active: () => number;
+    /** The item at {@link active}, or null. */
+    activeItem: () => T | null;
+    /** Move visual focus to `index` (ignored for a disabled or missing option). */
+    setActive: (index: number) => void;
+    /** Commit `item` as if the user picked it: calls `onChange`, closes the list. */
+    select: (item: T) => void;
     /**
-     * When true (default), `html` is run through the framework's HTML
-     * stripper before assignment — tags are removed, only text content is
-     * preserved. Set to `false` ONLY when `html` has already been sanitized
-     * with a dedicated library (e.g. DOMPurify).
+     * WAI-ARIA APG "select-only combobox" wiring. The trigger gets
+     * `role=combobox`, `aria-haspopup=listbox`, `aria-expanded`, `aria-controls`
+     * and `aria-activedescendant`; the listbox and options get their roles,
+     * ids, `aria-selected` and `aria-disabled`. Keyboard, pointer, outside click
+     * and focus return are handled. Returns dispose, which restores every
+     * attribute it touched.
      */
-    sanitize?: boolean;
+    bind: (els: SelectMenuElements<T>) => () => void;
 }
 /**
- * contentEditable provides reactive binding for contenteditable elements.
+ * Headless "select-only combobox": a button that opens a popup list of options
+ * whose content is arbitrary DOM — a font name in its own typeface, a swatch,
+ * an icon — which a native `<select>` cannot render.
+ *
+ * Follows the WAI-ARIA APG select-only combobox pattern: focus stays on the
+ * trigger and the list is navigated through `aria-activedescendant`.
  *
- * Uses the modern Selection/Range API instead of the deprecated
- * document.execCommand. Formatting is applied by wrapping the current
- * selection in the appropriate inline element.
+ * Keys it acts on are claimed (see `isWidgetKeyEvent`), so a page-level
+ * shortcut handler can leave them alone.
  *
- * @param element Optional editor element to scope formatting to. When provided,
- *   `bold()`/`italic()`/`underline()` ignore any selection that lives outside it
- *   — otherwise a selection elsewhere on the page could be mutated, since the
- *   Selection API is global.
+ * @param options Items, selection (controlled or not) and item helpers.
+ * @returns Menu state and a `bind()` that wires it to your markup.
+ *
+ * @example
+ * ```ts
+ * const menu = selectMenu({ items: FONTS, value: () => font(), onChange: setFont, itemToString: (f) => f.label });
+ * const optionEls = FONTS.map((f) => li({ style: { fontFamily: f.css } }, f.label));
+ * const list = ul(optionEls);
+ * const trigger = button(() => menu.value()?.label ?? "Choose a font");
+ * menu.bind({ trigger, listbox: list, option: (_f, i) => optionEls[i] });
+ * ```
  */
-declare function contentEditable(element?: HTMLElement): {
-    content: () => string;
-    /**
-     * Update the reactive content value.
-     *
-     * - `setContent("<b>x</b>")` — LEGACY: treated as `{ html, sanitize: true }`.
-     *   The HTML is stripped to text by default to prevent XSS. Prefer the
-     *   options form below.
-     * - `setContent({ text: "hello" })` — plain text, always safe.
-     * - `setContent({ html, sanitize: true })` — sanitized HTML (default).
-     * - `setContent({ html, sanitize: false })` — raw HTML; the caller MUST
-     *   have pre-sanitized it with a trusted library (e.g. DOMPurify).
-     */
-    setContent: (input: string | SetContentOptions) => void;
-    isFocused: () => boolean;
-    setFocused: (v: boolean) => void;
-    bold: () => void;
-    italic: () => void;
-    underline: () => void;
-};
-
-interface DatePickerOptions {
-    initialDate?: Date;
-    minDate?: Date;
-    maxDate?: Date;
-}
-declare function datePicker(options?: DatePickerOptions): {
-    selectedDate: () => Date | null;
-    select: (date: Date) => void;
-    viewDate: () => Date;
-    setViewDate: (date: Date) => void;
-    nextMonth: () => void;
-    prevMonth: () => void;
-    nextYear: () => void;
-    prevYear: () => void;
-    daysInMonth: () => Array<{
-        date: Date;
-        isCurrentMonth: boolean;
-        isToday: boolean;
-        isSelected: boolean;
-        isDisabled: boolean;
-    }>;
-    isDateDisabled: (date: Date) => boolean;
-    isSelected: (date: Date) => boolean;
-    /** WAI-ARIA Date Picker dialog grid wiring: `role=grid`, arrow nav,
-     *  PageUp/Down (month), Shift+PageUp/Down (year), Home/End. */
-    bind: (els: {
-        grid: HTMLElement;
-        cell: (date: Date) => HTMLElement | null;
-    }) => () => void;
-};
+declare function selectMenu<T>(options: SelectMenuOptions<T>): SelectMenu<T>;
 
-export { type AccordionAriaBinding, type AccordionOptions, type ComboboxOptions, type DatePickerOptions, type FileUploadOptions, type SelectOptions, type SetContentOptions, type TabsAriaBinding, type TabsOptions, accordion, combobox, contentEditable, datePicker, fileUpload, popover, select, tabs, tooltip };
+export { type SelectMenu, type SelectMenuElements, type SelectMenuOptions, isWidgetKeyEvent, selectMenu, widgetKeyOwner };