sibujs 4.12.0 → 4.13.1

package/dist/datePicker-DxuxWpgF.d.cts

@@ -0,0 +1,285 @@
+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"];
+};
+
+/**
+ * popover provides simple state management for positioned floating content.
+ * Manages open/close/toggle without any DOM coupling.
+ */
+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;
+};
+
+interface SelectOptions<T> {
+    items: T[];
+    multiple?: boolean;
+    itemToString?: (item: T) => string;
+    /** Optional predicate marking items as disabled — such items are skipped
+     *  by `highlightNext`/`highlightPrev`/typeahead and rejected by `select`. */
+    isDisabled?: (item: T) => boolean;
+}
+/**
+ * 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;
+    isOpen: () => boolean;
+    open: () => void;
+    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;
+    /**
+     * 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).
+     */
+    sanitize?: boolean;
+}
+/**
+ * contentEditable provides reactive binding for contenteditable elements.
+ *
+ * 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.
+ *
+ * @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.
+ */
+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;
+};
+
+export { type AccordionAriaBinding as A, type ComboboxOptions as C, type DatePickerOptions as D, type FileUploadOptions as F, type SelectOptions as S, type TabsAriaBinding as T, type AccordionOptions as a, type SetContentOptions as b, type TabsOptions as c, accordion as d, combobox as e, contentEditable as f, datePicker as g, fileUpload as h, tooltip as i, popover as p, select as s, tabs as t };

package/dist/datePicker-DxuxWpgF.d.ts

@@ -0,0 +1,285 @@
+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"];
+};
+
+/**
+ * popover provides simple state management for positioned floating content.
+ * Manages open/close/toggle without any DOM coupling.
+ */
+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;
+};
+
+interface SelectOptions<T> {
+    items: T[];
+    multiple?: boolean;
+    itemToString?: (item: T) => string;
+    /** Optional predicate marking items as disabled — such items are skipped
+     *  by `highlightNext`/`highlightPrev`/typeahead and rejected by `select`. */
+    isDisabled?: (item: T) => boolean;
+}
+/**
+ * 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;
+    isOpen: () => boolean;
+    open: () => void;
+    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;
+    /**
+     * 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).
+     */
+    sanitize?: boolean;
+}
+/**
+ * contentEditable provides reactive binding for contenteditable elements.
+ *
+ * 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.
+ *
+ * @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.
+ */
+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;
+};
+
+export { type AccordionAriaBinding as A, type ComboboxOptions as C, type DatePickerOptions as D, type FileUploadOptions as F, type SelectOptions as S, type TabsAriaBinding as T, type AccordionOptions as a, type SetContentOptions as b, type TabsOptions as c, accordion as d, combobox as e, contentEditable as f, datePicker as g, fileUpload as h, tooltip as i, popover as p, select as s, tabs as t };