@svgrid/grid 1.2.23 → 1.2.25

package/dist/createToggle.svelte.d.ts

@@ -0,0 +1,43 @@
+/**
+ * createToggle - the HEADLESS core behind <SvToggleButton>, in the same spirit
+ * as `createSvGrid`: a tiny controlled state machine (a single pressed on/off
+ * bit + ARIA) exposed as **prop-getters** you spread onto YOUR OWN markup. No
+ * styles, no DOM assumptions.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createToggle } from '@svgrid/grid'
+ *   let pressed = $state(false)
+ *   const t = createToggle({ pressed: () => pressed, onChange: (v) => (pressed = v) })
+ * </script>
+ * <button {...t.buttonProps()}>Bold</button>
+ * ```
+ *
+ * The styled <SvToggleButton> is just one renderer over this core.
+ */
+/** Reactive inputs are passed as getters so the core tracks live prop changes
+ *  (the same controlled pattern used across the SvGrid UI kit). */
+export type ToggleConfig = {
+    pressed: () => boolean;
+    onChange?: (pressed: boolean) => void;
+    disabled?: () => boolean;
+    ariaLabel?: () => string | undefined;
+};
+export type ToggleButtonProps = {
+    type: 'button';
+    'aria-pressed': boolean;
+    'aria-label': string | undefined;
+    disabled: boolean;
+    'data-pressed': '' | undefined;
+    onclick: () => void;
+};
+export type Toggle = {
+    /** Current pressed state. */
+    readonly pressed: boolean;
+    readonly disabled: boolean;
+    /** Flip pressed (no-op when disabled). */
+    toggle: () => void;
+    /** Spread onto the button element. */
+    buttonProps: () => ToggleButtonProps;
+};
+export declare function createToggle(config: ToggleConfig): Toggle;

package/dist/createToggle.svelte.js

@@ -0,0 +1,39 @@
+/**
+ * createToggle - the HEADLESS core behind <SvToggleButton>, in the same spirit
+ * as `createSvGrid`: a tiny controlled state machine (a single pressed on/off
+ * bit + ARIA) exposed as **prop-getters** you spread onto YOUR OWN markup. No
+ * styles, no DOM assumptions.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createToggle } from '@svgrid/grid'
+ *   let pressed = $state(false)
+ *   const t = createToggle({ pressed: () => pressed, onChange: (v) => (pressed = v) })
+ * </script>
+ * <button {...t.buttonProps()}>Bold</button>
+ * ```
+ *
+ * The styled <SvToggleButton> is just one renderer over this core.
+ */
+export function createToggle(config) {
+    const pressed = () => config.pressed();
+    const disabled = () => config.disabled?.() ?? false;
+    function toggle() {
+        if (disabled())
+            return;
+        config.onChange?.(!pressed());
+    }
+    return {
+        get pressed() { return pressed(); },
+        get disabled() { return disabled(); },
+        toggle,
+        buttonProps: () => ({
+            type: 'button',
+            'aria-pressed': pressed(),
+            'aria-label': config.ariaLabel?.(),
+            disabled: disabled(),
+            'data-pressed': pressed() ? '' : undefined,
+            onclick: toggle,
+        }),
+    };
+}

package/dist/createTree.svelte.d.ts

@@ -0,0 +1,96 @@
+/**
+ * createTree - the HEADLESS core behind <SvTree>, in the same spirit as
+ * `createSvGrid` for the grid: a runes-based state machine (expand/collapse,
+ * single-select highlight, cascading tri-state checkboxes, full keyboard) with
+ * **prop-getters** you spread onto YOUR OWN markup. The visible tree is
+ * flattened into `rows` so roving-focus keyboard nav stays a flat index walk.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createTree } from '@svgrid/grid'
+ *   let selected = $state<string | null>(null)
+ *   const tree = createTree({ nodes: () => nodes, selected: () => selected, onSelect: (id) => (selected = id) })
+ * </script>
+ * <div {...tree.treeProps()}>
+ *   {#each tree.rows as row (row.node.id)}
+ *     <div {...tree.itemProps(row)}>{row.node.label}</div>
+ *   {/each}
+ * </div>
+ * ```
+ *
+ * The styled <SvTree> is just one renderer over this core. The cascade math
+ * (`treeDescendantIds`, `treeCheckState`) is exported as pure functions.
+ */
+export type TreeNode = {
+    id: string;
+    label: string;
+    children?: TreeNode[];
+    disabled?: boolean;
+};
+export type CheckState = 'checked' | 'indeterminate' | 'unchecked';
+/** A single visible (flattened) tree row. */
+export type TreeRow = {
+    node: TreeNode;
+    depth: number;
+    hasChildren: boolean;
+    open: boolean;
+    parentId: string | null;
+    index: number;
+};
+/** All descendant ids of `node` (pure, depth-first). */
+export declare function treeDescendantIds(node: TreeNode): string[];
+/** Tri-state check status of `node` given the set of checked ids (pure). */
+export declare function treeCheckState(node: TreeNode, checked: ReadonlySet<string>): CheckState;
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type TreeConfig = {
+    nodes: () => ReadonlyArray<TreeNode>;
+    selected?: () => string | null;
+    onSelect?: (id: string) => void;
+    /** Seed the internally-managed expanded set (read once). */
+    expandedIds?: () => string[] | undefined;
+    onToggle?: (id: string, expanded: boolean) => void;
+    checkable?: () => boolean;
+    checked?: () => string[];
+    onCheck?: (ids: string[]) => void;
+    ariaLabel?: () => string | undefined;
+};
+export declare function createTree(config: TreeConfig): {
+    /** Internally-managed set of expanded node ids. */
+    readonly expanded: Set<string>;
+    /** Selected node id (single-select highlight). */
+    readonly selected: string | null;
+    /** Flattened list of visible rows. */
+    readonly rows: TreeRow[];
+    /** Roving-focus row index. */
+    readonly activeIndex: number;
+    /** Monotonic counter; changes only on keyboard navigation. */
+    readonly focusTick: number;
+    isExpanded: (id: string) => boolean;
+    isSelected: (id: string) => boolean;
+    checkStateOf: (node: TreeNode) => CheckState;
+    toggle: (id: string) => void;
+    toggleExpand: (node: TreeNode) => void;
+    select: (id: string) => void;
+    toggleCheck: (node: TreeNode) => void;
+    setActive: (i: number, focus?: boolean) => void;
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Spread onto the tree container element. */
+    treeProps: () => {
+        role: "tree";
+        'aria-label': string | undefined;
+        'aria-multiselectable': boolean;
+    };
+    /** Spread onto the treeitem element for a flattened `row`. */
+    itemProps: (row: TreeRow) => {
+        role: "treeitem";
+        'aria-level': number;
+        'aria-selected': boolean;
+        'aria-expanded': boolean | undefined;
+        'aria-checked': "true" | "mixed" | "false" | undefined;
+        'data-row': number;
+        tabindex: number;
+        onclick: () => void;
+        onkeydown: (e: KeyboardEvent) => void;
+    };
+};
+export type Tree = ReturnType<typeof createTree>;

package/dist/createTree.svelte.js

@@ -0,0 +1,194 @@
+/** All descendant ids of `node` (pure, depth-first). */
+export function treeDescendantIds(node) {
+    const ids = [];
+    const walk = (n) => { for (const c of n.children ?? []) {
+        ids.push(c.id);
+        walk(c);
+    } };
+    walk(node);
+    return ids;
+}
+/** Tri-state check status of `node` given the set of checked ids (pure). */
+export function treeCheckState(node, checked) {
+    if (!node.children?.length)
+        return checked.has(node.id) ? 'checked' : 'unchecked';
+    const desc = treeDescendantIds(node);
+    const on = desc.filter((id) => checked.has(id)).length;
+    if (on === 0 && !checked.has(node.id))
+        return 'unchecked';
+    if (on === desc.length)
+        return 'checked';
+    return 'indeterminate';
+}
+function findNode(list, id) {
+    for (const n of list) {
+        if (n.id === id)
+            return n;
+        if (n.children) {
+            const f = findNode(n.children, id);
+            if (f)
+                return f;
+        }
+    }
+    return null;
+}
+export function createTree(config) {
+    const nodes = () => config.nodes();
+    const checkable = () => config.checkable?.() ?? false;
+    const selected = () => config.selected?.() ?? null;
+    // Internal expanded set, seeded from the prop once (then self-managed).
+    let expanded = $state(new Set());
+    let seeded = false;
+    $effect(() => {
+        if (!seeded) {
+            seeded = true;
+            const ids = config.expandedIds?.();
+            if (ids)
+                expanded = new Set(ids);
+        }
+    });
+    const rows = $derived.by(() => {
+        const out = [];
+        const walk = (list, depth, parentId) => {
+            for (const node of list) {
+                const hasChildren = !!node.children?.length;
+                const open = expanded.has(node.id);
+                out.push({ node, depth, hasChildren, open, parentId, index: out.length });
+                if (hasChildren && open)
+                    walk(node.children, depth + 1, node.id);
+            }
+        };
+        walk(nodes(), 0, null);
+        return out;
+    });
+    let active = $state(0);
+    $effect(() => { if (active >= rows.length)
+        active = Math.max(0, rows.length - 1); });
+    const checkedSet = $derived(new Set(config.checked?.() ?? []));
+    // Roving focus target; `focusTick` bumps only on keyboard moves.
+    let focusTick = $state(0);
+    function setActive(i, focus = false) { active = i; if (focus)
+        focusTick++; }
+    const checkStateOf = (node) => treeCheckState(node, checkedSet);
+    const isExpanded = (id) => expanded.has(id);
+    const isSelected = (id) => id === selected();
+    function toggleExpand(node) {
+        if (!node.children?.length)
+            return;
+        const next = new Set(expanded);
+        const willOpen = !next.has(node.id);
+        willOpen ? next.add(node.id) : next.delete(node.id);
+        expanded = next;
+        config.onToggle?.(node.id, willOpen);
+    }
+    const toggle = (id) => { const n = findNode(nodes(), id); if (n)
+        toggleExpand(n); };
+    function select(node) {
+        if (node.disabled)
+            return;
+        config.onSelect?.(node.id);
+    }
+    const selectId = (id) => { const n = findNode(nodes(), id); if (n)
+        select(n); };
+    function toggleCheck(node) {
+        if (node.disabled)
+            return;
+        const next = new Set(checkedSet);
+        const ids = [node.id, ...treeDescendantIds(node)];
+        const currentlyOn = checkStateOf(node) === 'checked';
+        for (const id of ids)
+            currentlyOn ? next.delete(id) : next.add(id);
+        config.onCheck?.([...next]);
+    }
+    function onKeydown(e) {
+        const item = rows[active];
+        if (!item)
+            return;
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                setActive(Math.min(active + 1, rows.length - 1), true);
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                setActive(Math.max(active - 1, 0), true);
+                break;
+            case 'ArrowRight':
+                e.preventDefault();
+                if (item.hasChildren && !item.open)
+                    toggleExpand(item.node);
+                else if (item.hasChildren && item.open)
+                    setActive(Math.min(active + 1, rows.length - 1), true);
+                break;
+            case 'ArrowLeft':
+                e.preventDefault();
+                if (item.hasChildren && item.open)
+                    toggleExpand(item.node);
+                else if (item.parentId) {
+                    const pi = rows.findIndex((r) => r.node.id === item.parentId);
+                    if (pi >= 0)
+                        setActive(pi, true);
+                }
+                break;
+            case 'Enter':
+                e.preventDefault();
+                select(item.node);
+                break;
+            case ' ':
+                e.preventDefault();
+                checkable() ? toggleCheck(item.node) : select(item.node);
+                break;
+            case 'Home':
+                e.preventDefault();
+                setActive(0, true);
+                break;
+            case 'End':
+                e.preventDefault();
+                setActive(rows.length - 1, true);
+                break;
+        }
+    }
+    return {
+        /** Internally-managed set of expanded node ids. */
+        get expanded() { return expanded; },
+        /** Selected node id (single-select highlight). */
+        get selected() { return selected(); },
+        /** Flattened list of visible rows. */
+        get rows() { return rows; },
+        /** Roving-focus row index. */
+        get activeIndex() { return active; },
+        /** Monotonic counter; changes only on keyboard navigation. */
+        get focusTick() { return focusTick; },
+        isExpanded,
+        isSelected,
+        checkStateOf,
+        toggle,
+        toggleExpand,
+        select: selectId,
+        toggleCheck,
+        setActive,
+        onKeydown,
+        /** Spread onto the tree container element. */
+        treeProps: () => ({
+            role: 'tree',
+            'aria-label': config.ariaLabel?.(),
+            'aria-multiselectable': checkable(),
+        }),
+        /** Spread onto the treeitem element for a flattened `row`. */
+        itemProps: (row) => {
+            const cs = checkable() ? checkStateOf(row.node) : 'unchecked';
+            const ariaChecked = checkable() ? (cs === 'checked' ? 'true' : cs === 'indeterminate' ? 'mixed' : 'false') : undefined;
+            return {
+                role: 'treeitem',
+                'aria-level': row.depth + 1,
+                'aria-selected': row.node.id === selected(),
+                'aria-expanded': row.hasChildren ? row.open : undefined,
+                'aria-checked': ariaChecked,
+                'data-row': row.index,
+                tabindex: row.index === active ? 0 : -1,
+                onclick: () => { setActive(row.index); select(row.node); },
+                onkeydown: onKeydown,
+            };
+        },
+    };
+}

package/dist/editor-contract.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The shared "editor contract" for the SvGrid UI kit.
+ *
+ * Every value-bearing editor (inputs, selects, pickers) accepts this common set
+ * of props so forms, validation and accessibility behave IDENTICALLY across the
+ * kit - the same spirit as the grid's headless core, applied to the editors.
+ * Components spread their own `value` / options / behavior on top of this base.
+ *
+ * Framework-free (no Svelte, no DOM) so it can be unit-tested and reused.
+ */
+export type EditorSize = 'sm' | 'md' | 'lg';
+/** Props shared by every value-bearing editor in the kit. */
+export type SvEditorProps = {
+    /** Disable interaction + form submission. */
+    disabled?: boolean;
+    /** Read-only: the value is shown but not editable. */
+    readonly?: boolean;
+    /** Required for validation (adds `aria-required` + participates in validity). */
+    required?: boolean;
+    /** Marks the control invalid (`aria-invalid` + error styling). */
+    invalid?: boolean;
+    /** Error message; when set it is announced via `aria-describedby` and shown. */
+    error?: string;
+    /** Control size / density. */
+    size?: EditorSize;
+    /** Form field name; the editor emits a hidden input carrying its value. */
+    name?: string;
+    /** Root/control element id (the error-text id derives from it). */
+    id?: string;
+    /** Accessible name when there is no visible `<label>`. */
+    ariaLabel?: string;
+};
+/** Stable DOM id for an editor's error text, for `aria-describedby` wiring. */
+export declare const editorErrorId: (id?: string) => string | undefined;
+/** A subset of {@link SvEditorProps} that drives ARIA on the focusable control. */
+export type EditorAriaState = Pick<SvEditorProps, 'id' | 'invalid' | 'required' | 'error' | 'ariaLabel'>;
+/**
+ * ARIA attributes for the focusable control of an editor, derived from its state.
+ * Spread onto the input/button/combobox:
+ * `<input {...editorAria({ id, invalid, required, error, ariaLabel })} />`
+ * Undefined values are omitted by Svelte, so unset props add no attributes.
+ */
+export declare function editorAria(state: EditorAriaState): {
+    'aria-invalid': 'true' | undefined;
+    'aria-required': 'true' | undefined;
+    'aria-describedby': string | undefined;
+    'aria-label': string | undefined;
+};

package/dist/editor-contract.js

@@ -0,0 +1,26 @@
+/**
+ * The shared "editor contract" for the SvGrid UI kit.
+ *
+ * Every value-bearing editor (inputs, selects, pickers) accepts this common set
+ * of props so forms, validation and accessibility behave IDENTICALLY across the
+ * kit - the same spirit as the grid's headless core, applied to the editors.
+ * Components spread their own `value` / options / behavior on top of this base.
+ *
+ * Framework-free (no Svelte, no DOM) so it can be unit-tested and reused.
+ */
+/** Stable DOM id for an editor's error text, for `aria-describedby` wiring. */
+export const editorErrorId = (id) => (id ? `${id}__error` : undefined);
+/**
+ * ARIA attributes for the focusable control of an editor, derived from its state.
+ * Spread onto the input/button/combobox:
+ * `<input {...editorAria({ id, invalid, required, error, ariaLabel })} />`
+ * Undefined values are omitted by Svelte, so unset props add no attributes.
+ */
+export function editorAria(state) {
+    return {
+        'aria-invalid': state.invalid ? 'true' : undefined,
+        'aria-required': state.required ? 'true' : undefined,
+        'aria-describedby': state.error ? editorErrorId(state.id) : undefined,
+        'aria-label': state.ariaLabel,
+    };
+}

package/dist/index.d.ts

@@ -9,6 +9,30 @@ export { default as SvGridDropdown } from './SvGridDropdown.svelte';
 export { default as SvCalendar, type CalendarValue, type CalendarPreset, type CalendarAnimation } from './SvCalendar.svelte';
 export { default as SvTimePicker, type TimeValue } from './SvTimePicker.svelte';
 export { default as SvDateTimePicker, type DateTimeValue } from './SvDateTimePicker.svelte';
+export { editorAria, editorErrorId, type SvEditorProps, type EditorSize, type EditorAriaState } from './editor-contract';
+export { createListbox, toSelectedArray, type Listbox, type ListboxConfig, type ListboxValue, type ListboxRootProps, type OptionProps, } from './createListbox.svelte';
+export { createCombobox, type Combobox, type ComboboxConfig, type ComboboxValue } from './createCombobox.svelte';
+export { createDropdownList, type DropdownList, type DropdownListConfig, type DropdownValue } from './createDropdownList.svelte';
+export { createAutocomplete, type Autocomplete, type AutocompleteConfig } from './createAutocomplete.svelte';
+export { createTagsInput, type TagsInput, type TagsInputConfig } from './createTagsInput.svelte';
+export { createCountryInput, type CountryInput, type CountryInputConfig } from './createCountryInput.svelte';
+export { createNumberInput, type NumberInputConfig, type NumberInputCore } from './createNumberInput.svelte';
+export { createMaskedInput, type MaskedInputConfig, type MaskedInputCore } from './createMaskedInput.svelte';
+export { createPhoneInput, type PhoneInputConfig, type PhoneInputCore } from './createPhoneInput.svelte';
+export { createColorInput, normalizeHex, type ColorInputConfig, type ColorInputCore } from './createColorInput.svelte';
+export { createPasswordInput, passwordStrength, STRENGTH_LABELS, type PasswordInputConfig, type PasswordInputCore } from './createPasswordInput.svelte';
+export { createToggle, type Toggle, type ToggleConfig, type ToggleButtonProps } from './createToggle.svelte';
+export { createSwitch, type Switch, type SwitchConfig, type SwitchProps } from './createSwitch.svelte';
+export { createCheckbox, type Checkbox, type CheckboxConfig, type CheckboxBoxProps } from './createCheckbox.svelte';
+export { createRadioGroup, type RadioGroup, type RadioGroupConfig, type RadioProps, type RadioGroupProps } from './createRadioGroup.svelte';
+export { createRating, type Rating, type RatingConfig, type RatingFill, type RatingRootProps, type RatingStarProps } from './createRating.svelte';
+export { createCalendar, normalizeCalendarValue, type Calendar, type CalendarConfig, type CalendarDayState, type CalendarNavDir, type CalendarNameFormat, type DisplayMode } from './createCalendar.svelte';
+export { createTimePicker, parseTimeValue, type TimePicker, type TimePickerConfig, type TimeSelection, type TimeFormat, type DialTick } from './createTimePicker.svelte';
+export { createDateTimePicker, type DateTimePicker, type DateTimePickerConfig, type DropDownDisplayMode, type DateTimeTab } from './createDateTimePicker.svelte';
+export { createTabs, type Tabs, type TabsConfig, type TabsOrientation, type TabsActivation } from './createTabs.svelte';
+export { createTree, treeDescendantIds, treeCheckState, type Tree, type TreeConfig, type TreeRow, type CheckState } from './createTree.svelte';
+export { createSlider, type Slider, type SliderConfig, type SliderValue, type SliderOrientation, type SliderThumb, type SliderPoint } from './createSlider.svelte';
+export { createGauge, type Gauge, type GaugeConfig, type GaugePoint } from './createGauge.svelte';
 export { default as SvButton } from './SvButton.svelte';
 export { default as SvRepeatButton } from './SvRepeatButton.svelte';
 export { default as SvToggleButton } from './SvToggleButton.svelte';

package/dist/index.js

@@ -9,6 +9,37 @@ export { default as SvGridDropdown } from './SvGridDropdown.svelte';
 export { default as SvCalendar } from './SvCalendar.svelte';
 export { default as SvTimePicker } from './SvTimePicker.svelte';
 export { default as SvDateTimePicker } from './SvDateTimePicker.svelte';
+// UI kit - shared editor contract (common props + a11y wiring for every editor)
+export { editorAria, editorErrorId } from './editor-contract';
+// UI kit - headless cores (state + prop-getters you render yourself, like createSvGrid)
+export { createListbox, toSelectedArray, } from './createListbox.svelte';
+// Selection family cores
+export { createCombobox } from './createCombobox.svelte';
+export { createDropdownList } from './createDropdownList.svelte';
+export { createAutocomplete } from './createAutocomplete.svelte';
+export { createTagsInput } from './createTagsInput.svelte';
+export { createCountryInput } from './createCountryInput.svelte';
+// Text-input family cores
+export { createNumberInput } from './createNumberInput.svelte';
+export { createMaskedInput } from './createMaskedInput.svelte';
+export { createPhoneInput } from './createPhoneInput.svelte';
+export { createColorInput, normalizeHex } from './createColorInput.svelte';
+export { createPasswordInput, passwordStrength, STRENGTH_LABELS } from './createPasswordInput.svelte';
+// Buttons & toggles family cores
+export { createToggle } from './createToggle.svelte';
+export { createSwitch } from './createSwitch.svelte';
+export { createCheckbox } from './createCheckbox.svelte';
+export { createRadioGroup } from './createRadioGroup.svelte';
+export { createRating } from './createRating.svelte';
+// Date & time family cores
+export { createCalendar, normalizeCalendarValue } from './createCalendar.svelte';
+export { createTimePicker, parseTimeValue } from './createTimePicker.svelte';
+export { createDateTimePicker } from './createDateTimePicker.svelte';
+// Layout & range family cores
+export { createTabs } from './createTabs.svelte';
+export { createTree, treeDescendantIds, treeCheckState } from './createTree.svelte';
+export { createSlider } from './createSlider.svelte';
+export { createGauge } from './createGauge.svelte';
 // UI kit - Group B (buttons & toggles)
 export { default as SvButton } from './SvButton.svelte';
 export { default as SvRepeatButton } from './SvRepeatButton.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgrid/grid",
-  "version": "1.2.23",
+  "version": "1.2.25",
   "description": "SvGrid - a headless-first, Svelte 5-native data grid engine and render component.",
   "author": "jQWidgets <boikom@jqwidgets.com>",
   "license": "MIT",

package/src/SvAutoComplete.svelte

@@ -3,9 +3,13 @@
    * SvAutoComplete - a free-text input with a live-filtered suggestion list.
    * Unlike SvComboBox, it accepts ANY value (the text), suggestions are just
    * shortcuts. Parity: Smart `smart-input` (autocomplete). Emits the text string.
+   *
+   * One styled renderer over the headless `createAutocomplete` core; only
+   * portal/measure render concerns live here.
    */
   import { anchoredRect, portalToBody, type AnchoredRect } from './popover'
-  import { filterOptions, type ListOption } from './list-option'
+  import { type ListOption } from './list-option'
+  import { createAutocomplete } from './createAutocomplete.svelte'
 
   type Props = {
     value?: string
@@ -22,38 +26,31 @@
 
   let { value = '', onChange, suggestions = [], minChars = 1, placeholder, disabled = false, name, size = 'md', ariaLabel }: Props = $props()
 
-  const asOptions = $derived<ListOption[]>(
-    suggestions.map((s) => (typeof s === 'string' ? { value: s, label: s } : s)),
-  )
-
-  let open = $state(false)
-  let active = $state(0)
   let fieldEl = $state<HTMLInputElement | null>(null)
   let panelEl = $state<HTMLDivElement | null>(null)
   let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
 
-  const filtered = $derived(value.length >= minChars ? filterOptions(asOptions, value).slice(0, 10) : [])
+  const ac = createAutocomplete({
+    value: () => value,
+    onChange: (v) => onChange?.(v),
+    suggestions: () => suggestions,
+    minChars: () => minChars,
+    disabled: () => disabled,
+    ariaLabel: () => ariaLabel,
+    focusInput: () => fieldEl?.focus(),
+  })
 
   function updatePos() {
     if (!fieldEl) return
-    rect = anchoredRect(fieldEl.getBoundingClientRect(), { estimatedHeight: Math.min(filtered.length, 8) * 34 + 8 })
-  }
-  function maybeOpen() { open = filtered.length > 0; if (open) { active = 0; updatePos() } }
-  function pick(o: ListOption | undefined) { if (!o) return; onChange?.(String(o.value)); open = false; fieldEl?.focus() }
-  function onInput(e: Event) { onChange?.((e.currentTarget as HTMLInputElement).value); queueMicrotask(maybeOpen) }
-  function onKeydown(e: KeyboardEvent) {
-    if (!open) { if (e.key === 'ArrowDown') { queueMicrotask(maybeOpen) } return }
-    if (e.key === 'ArrowDown') { e.preventDefault(); active = Math.min(active + 1, filtered.length - 1) }
-    else if (e.key === 'ArrowUp') { e.preventDefault(); active = Math.max(active - 1, 0) }
-    else if (e.key === 'Enter') { e.preventDefault(); pick(filtered[active]) }
-    else if (e.key === 'Escape') { open = false }
+    rect = anchoredRect(fieldEl.getBoundingClientRect(), { estimatedHeight: Math.min(ac.filtered.length, 8) * 34 + 8 })
   }
 
   $effect(() => {
-    if (!open) return
+    if (!ac.open) return
+    updatePos()
     const rp = () => updatePos()
     window.addEventListener('scroll', rp, true); window.addEventListener('resize', rp)
-    const od = (e: PointerEvent) => { const t = e.target as Node | null; if (t && (fieldEl?.contains(t) || panelEl?.contains(t))) return; open = false }
+    const od = (e: PointerEvent) => { const t = e.target as Node | null; if (t && (fieldEl?.contains(t) || panelEl?.contains(t))) return; ac.close() }
     document.addEventListener('pointerdown', od, true)
     return () => { window.removeEventListener('scroll', rp, true); window.removeEventListener('resize', rp); document.removeEventListener('pointerdown', od, true) }
   })
@@ -63,23 +60,15 @@
   bind:this={fieldEl}
   class="sv-ac sv-ac--{size}"
   type="text"
-  role="combobox"
-  aria-expanded={open}
-  aria-autocomplete="list"
-  value={value}
   {placeholder}
-  {disabled}
-  aria-label={ariaLabel}
-  oninput={onInput}
-  onfocus={maybeOpen}
-  onkeydown={onKeydown}
+  {...ac.inputProps()}
 />
 
-{#if open}
-  <div bind:this={panelEl} class="sv-ddl__panel" use:portalToBody style:position="fixed" style:top={`${rect.top}px`} style:left={`${rect.left}px`} style:min-width={`${rect.width}px`} role="listbox">
-    {#each filtered as opt, i (opt.value)}
+{#if ac.open}
+  <div bind:this={panelEl} class="sv-ddl__panel" use:portalToBody style:position="fixed" style:top={`${rect.top}px`} style:left={`${rect.left}px`} style:min-width={`${rect.width}px`} {...ac.listboxProps()}>
+    {#each ac.filtered as opt, i (opt.value)}
       <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
-      <div class="sv-ddl__opt" class:is-active={i === active} role="option" tabindex="-1" aria-selected={i === active} data-idx={i} onclick={() => pick(opt)} onpointermove={() => (active = i)}>{opt.label}</div>
+      <div class="sv-ddl__opt" class:is-active={ac.isActive(i)} {...ac.optionProps(i)}>{opt.label}</div>
     {/each}
   </div>
 {/if}