@svgrid/grid 1.2.34 → 2.0.0

package/dist/createListbox.svelte.d.ts

@@ -22,7 +22,7 @@
  *
  * The styled <SvListBox> is just one renderer over this core.
  */
-import type { ListOption } from './list-option';
+import { type ListOption } from './list-option';
 export type ListboxValue = string | number | Array<string | number> | null;
 /** Reactive inputs are passed as getters so the core tracks live prop changes
  *  (the same controlled pattern Svelte headless libraries use). */
@@ -33,6 +33,11 @@ export type ListboxConfig = {
     multiple?: () => boolean;
     disabled?: () => boolean;
     ariaLabel?: () => string | undefined;
+    id?: () => string | undefined;
+    invalid?: () => boolean;
+    required?: () => boolean;
+    error?: () => string | undefined;
+    hint?: () => string | undefined;
 };
 export type OptionProps = {
     role: 'option';
@@ -47,10 +52,14 @@ export type OptionProps = {
 };
 export type ListboxRootProps = {
     role: 'listbox';
+    id: string | undefined;
     'aria-multiselectable': boolean;
     'aria-label': string | undefined;
     'aria-disabled': boolean;
     'aria-activedescendant': string | undefined;
+    'aria-invalid': 'true' | undefined;
+    'aria-required': 'true' | undefined;
+    'aria-describedby': string | undefined;
     tabindex: number;
     onkeydown: (e: KeyboardEvent) => void;
 };

package/dist/createListbox.svelte.js

@@ -1,3 +1,29 @@
+/**
+ * createListbox - the HEADLESS core behind <SvListBox>, in the same spirit as
+ * `createSvGrid` for the grid: a runes-based state machine (roving active index,
+ * single/multi selection, full keyboard) with **prop-getters** you spread onto
+ * YOUR OWN markup. No styles, no DOM assumptions - render it however you like.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createListbox } from '@svgrid/grid'
+ *   let value = $state<string | null>(null)
+ *   const lb = createListbox({
+ *     options: () => options, value: () => value,
+ *     onChange: (v) => (value = v),
+ *   })
+ * </script>
+ * <ul {...lb.rootProps()}>
+ *   {#each options as opt, i}
+ *     <li {...lb.optionProps(i)}>{opt.label}</li>
+ *   {/each}
+ * </ul>
+ * ```
+ *
+ * The styled <SvListBox> is just one renderer over this core.
+ */
+import { createTypeaheadBuffer, isTypeaheadKey, nextTypeaheadIndex } from './list-option';
+import { editorAria } from './editor-contract';
 let uid = 0;
 /** Normalize a listbox value to an array (pure). */
 export function toSelectedArray(value, multiple) {
@@ -52,6 +78,14 @@ export function createListbox(config) {
     }
     const first = () => { active = enabledIdx[0] ?? 0; };
     const last = () => { active = enabledIdx.at(-1) ?? 0; };
+    // Type-ahead: typing a label prefix jumps the active highlight to it.
+    const typeahead = createTypeaheadBuffer();
+    function onTypeahead(char) {
+        const buffer = typeahead.push(char.toLowerCase());
+        const next = nextTypeaheadIndex(opts(), buffer, active);
+        if (next >= 0)
+            active = next;
+    }
     function onKeydown(e) {
         if (disabled())
             return;
@@ -77,8 +111,19 @@ export function createListbox(config) {
                 e.preventDefault();
                 pick(active);
                 break;
+            default: if (isTypeaheadKey(e))
+                onTypeahead(e.key);
         }
     }
+    // Editor-contract ARIA state, folded onto the focusable listbox root.
+    const ariaState = () => ({
+        id: config.id?.(),
+        invalid: config.invalid?.(),
+        required: config.required?.(),
+        error: config.error?.(),
+        hint: config.hint?.(),
+        ariaLabel: config.ariaLabel?.(),
+    });
     return {
         get activeIndex() { return active; },
         get selectedValues() { return selected; },
@@ -92,10 +137,12 @@ export function createListbox(config) {
         onKeydown,
         rootProps: () => ({
             role: 'listbox',
+            id: config.id?.(),
             'aria-multiselectable': multiple(),
-            'aria-label': config.ariaLabel?.(),
             'aria-disabled': disabled(),
             'aria-activedescendant': opts()[active] ? optionId(active) : undefined,
+            // aria-label + aria-invalid/required/describedby from the editor contract.
+            ...editorAria(ariaState()),
             tabindex: disabled() ? -1 : 0,
             onkeydown: onKeydown,
         }),

package/dist/createMaskedInput.svelte.d.ts

@@ -7,6 +7,11 @@ export type MaskedInputConfig = {
     placeholder?: () => string | undefined;
     disabled?: () => boolean;
     readonly?: () => boolean;
+    id?: () => string | undefined;
+    invalid?: () => boolean;
+    required?: () => boolean;
+    error?: () => string | undefined;
+    hint?: () => string | undefined;
     ariaLabel?: () => string | undefined;
 };
 export declare function createMaskedInput(config: MaskedInputConfig): {
@@ -18,13 +23,17 @@ export declare function createMaskedInput(config: MaskedInputConfig): {
     readonly complete: boolean;
     /** Spread onto the text input element. */
     inputProps: () => {
+        oninput: (e: Event) => void;
+        'aria-invalid': "true" | undefined;
+        'aria-required': "true" | undefined;
+        'aria-describedby': string | undefined;
+        'aria-label': string | undefined;
+        id: string | undefined;
         value: string;
         type: "text";
         placeholder: string;
         disabled: boolean;
         readonly: boolean;
-        'aria-label': string | undefined;
-        oninput: (e: Event) => void;
     };
 };
 export type MaskedInputCore = ReturnType<typeof createMaskedInput>;

package/dist/createMaskedInput.svelte.js

@@ -16,6 +16,7 @@
  * The styled <SvMaskedInput> is just one renderer over this core.
  */
 import { applyMask, unmask, isMaskComplete } from './datetime/mask';
+import { editorAria } from './editor-contract';
 export function createMaskedInput(config) {
     const mask = () => config.mask?.() ?? '';
     const disabled = () => config.disabled?.() ?? false;
@@ -41,6 +42,14 @@ export function createMaskedInput(config) {
         el.value = masked;
         config.onChange?.(masked, raw, m ? isMaskComplete(masked, m) : true);
     }
+    const ariaState = () => ({
+        id: config.id?.(),
+        invalid: config.invalid?.(),
+        required: config.required?.(),
+        error: config.error?.(),
+        hint: config.hint?.(),
+        ariaLabel: config.ariaLabel?.(),
+    });
     return {
         /** The current masked display text. */
         get masked() { return text; },
@@ -50,12 +59,13 @@ export function createMaskedInput(config) {
         get complete() { return mask() ? isMaskComplete(text, mask()) : true; },
         /** Spread onto the text input element. */
         inputProps: () => ({
+            id: config.id?.(),
             value: text,
             type: 'text',
             placeholder: config.placeholder?.() ?? mask(),
             disabled: disabled(),
             readonly: readonly(),
-            'aria-label': config.ariaLabel?.(),
+            ...editorAria(ariaState()),
             oninput: onInput,
         }),
     };

package/dist/createNumberInput.svelte.d.ts

@@ -17,6 +17,7 @@ export type NumberInputConfig = {
     invalid?: () => boolean;
     required?: () => boolean;
     error?: () => string | undefined;
+    hint?: () => string | undefined;
     ariaLabel?: () => string | undefined;
 };
 export declare function createNumberInput(config: NumberInputConfig): {

package/dist/createNumberInput.svelte.js

@@ -115,6 +115,7 @@ export function createNumberInput(config) {
         invalid: config.invalid?.(),
         required: config.required?.(),
         error: config.error?.(),
+        hint: config.hint?.(),
         ariaLabel: config.ariaLabel?.(),
     });
     return {

package/dist/createPasswordInput.svelte.d.ts

@@ -1,20 +1,3 @@
-/**
- * createPasswordInput - the HEADLESS core behind <SvPasswordInput>: a runes-based
- * state machine that owns the reveal toggle + a 4-level strength heuristic,
- * exposed as **prop-getters** you spread onto YOUR OWN markup. No styles, no DOM.
- *
- * ```svelte
- * <script lang="ts">
- *   import { createPasswordInput } from '@svgrid/grid'
- *   let value = $state('')
- *   const pw = createPasswordInput({ value: () => value, onChange: (v) => (value = v) })
- * </script>
- * <input {...pw.inputProps()} />
- * <button {...pw.toggleProps()}>{pw.revealed ? 'Hide' : 'Show'}</button>
- * ```
- *
- * The styled <SvPasswordInput> is just one renderer over this core.
- */
 export declare const STRENGTH_LABELS: string[];
 /** Score a password 0-4 by length + character-class variety (pure). */
 export declare function passwordStrength(v: string): number;
@@ -25,27 +8,42 @@ export type PasswordInputConfig = {
     placeholder?: () => string | undefined;
     disabled?: () => boolean;
     readonly?: () => boolean;
-    ariaLabel?: () => string | undefined;
     autocomplete?: () => string | undefined;
+    /** Accessible label for the reveal toggle when the value is hidden. */
+    showLabel?: () => string | undefined;
+    /** Accessible label for the reveal toggle when the value is shown. */
+    hideLabel?: () => string | undefined;
+    /** Strength labels indexed 0-4 (index 0 unused; 1..4 = weak..strong). */
+    strengthLabels?: () => readonly string[];
+    id?: () => string | undefined;
+    invalid?: () => boolean;
+    required?: () => boolean;
+    error?: () => string | undefined;
+    hint?: () => string | undefined;
+    ariaLabel?: () => string | undefined;
 };
 export declare function createPasswordInput(config: PasswordInputConfig): {
     /** Whether the value is currently shown as plain text. */
     readonly revealed: boolean;
     /** Strength score, 0-4. */
     readonly strength: number;
-    /** Human label for the strength score. */
+    /** Human label for the strength score (localizable via `strengthLabels`). */
     readonly strengthLabel: string | undefined;
     toggle: () => boolean;
     /** Spread onto the text/password input element. */
     inputProps: () => {
+        oninput: (e: Event) => void;
+        'aria-invalid': "true" | undefined;
+        'aria-required': "true" | undefined;
+        'aria-describedby': string | undefined;
+        'aria-label': string | undefined;
+        id: string | undefined;
         value: string;
         type: "text" | "password";
         placeholder: string | undefined;
         disabled: boolean;
         readonly: boolean;
         autocomplete: AutoFill;
-        'aria-label': string | undefined;
-        oninput: (e: Event) => void;
     };
     /** Spread onto the reveal (show/hide) toggle button. */
     toggleProps: () => {

package/dist/createPasswordInput.svelte.js

@@ -15,6 +15,7 @@
  *
  * The styled <SvPasswordInput> is just one renderer over this core.
  */
+import { editorAria } from './editor-contract';
 export const STRENGTH_LABELS = ['', 'Weak', 'Fair', 'Good', 'Strong'];
 /** Score a password 0-4 by length + character-class variety (pure). */
 export function passwordStrength(v) {
@@ -40,29 +41,40 @@ export function createPasswordInput(config) {
         config.onChange?.(e.currentTarget.value);
     }
     const toggle = () => (revealed = !revealed);
+    const ariaState = () => ({
+        id: config.id?.(),
+        invalid: config.invalid?.(),
+        required: config.required?.(),
+        error: config.error?.(),
+        hint: config.hint?.(),
+        ariaLabel: config.ariaLabel?.(),
+    });
     return {
         /** Whether the value is currently shown as plain text. */
         get revealed() { return revealed; },
         /** Strength score, 0-4. */
         get strength() { return strength; },
-        /** Human label for the strength score. */
-        get strengthLabel() { return STRENGTH_LABELS[strength]; },
+        /** Human label for the strength score (localizable via `strengthLabels`). */
+        get strengthLabel() { return (config.strengthLabels?.() ?? STRENGTH_LABELS)[strength]; },
         toggle,
         /** Spread onto the text/password input element. */
         inputProps: () => ({
+            id: config.id?.(),
             value: config.value(),
             type: (revealed ? 'text' : 'password'),
             placeholder: config.placeholder?.(),
             disabled: disabled(),
             readonly: readonly(),
             autocomplete: (config.autocomplete?.() ?? 'current-password'),
-            'aria-label': config.ariaLabel?.(),
+            ...editorAria(ariaState()),
             oninput: onInput,
         }),
         /** Spread onto the reveal (show/hide) toggle button. */
         toggleProps: () => ({
             type: 'button',
-            'aria-label': revealed ? 'Hide password' : 'Show password',
+            'aria-label': revealed
+                ? (config.hideLabel?.() ?? 'Hide password')
+                : (config.showLabel?.() ?? 'Show password'),
             'aria-pressed': revealed,
             disabled: disabled(),
             tabindex: -1,

package/dist/createPhoneInput.svelte.d.ts

@@ -1,16 +1,27 @@
+/** Emitted alongside the phone value: parsed parts + per-country validity. */
+export type PhoneParts = {
+    country: string;
+    dial: string;
+    national: string;
+    valid: boolean;
+    complete: boolean;
+};
 /** Reactive inputs are passed as getters so the core tracks live prop changes. */
 export type PhoneInputConfig = {
     value: () => string;
-    onChange?: (value: string, parts: {
-        country: string;
-        dial: string;
-        national: string;
-    }) => void;
+    onChange?: (value: string, parts: PhoneParts) => void;
     /** Default country ISO code. */
     country?: () => string;
     disabled?: () => boolean;
     readonly?: () => boolean;
     placeholder?: () => string | undefined;
+    /** Accessible name for the country `<select>` (localizable). */
+    countryLabel?: () => string | undefined;
+    id?: () => string | undefined;
+    invalid?: () => boolean;
+    required?: () => boolean;
+    error?: () => string | undefined;
+    hint?: () => string | undefined;
     ariaLabel?: () => string | undefined;
 };
 export declare function createPhoneInput(config: PhoneInputConfig): {
@@ -24,6 +35,10 @@ export declare function createPhoneInput(config: PhoneInputConfig): {
     readonly displayNational: string;
     /** The full emitted value (`+<dial><digits>`). */
     readonly value: string;
+    /** Whether the national number is a plausible length for the country. */
+    readonly valid: boolean;
+    /** Whether a non-empty number matches the country's expected length. */
+    readonly complete: boolean;
     /** Spread onto the country `<select>` element. */
     selectProps: () => {
         value: string;
@@ -33,14 +48,18 @@ export declare function createPhoneInput(config: PhoneInputConfig): {
     };
     /** Spread onto the national number input element. */
     inputProps: () => {
+        'aria-label': string;
+        oninput: (e: Event) => void;
+        'aria-invalid': "true" | undefined;
+        'aria-required': "true" | undefined;
+        'aria-describedby': string | undefined;
+        id: string | undefined;
         value: string;
         type: "tel";
         inputmode: "tel";
         placeholder: string;
         disabled: boolean;
         readonly: boolean;
-        'aria-label': string;
-        oninput: (e: Event) => void;
     };
 };
 export type PhoneInputCore = ReturnType<typeof createPhoneInput>;

package/dist/createPhoneInput.svelte.js

@@ -17,8 +17,9 @@
  *
  * The styled <SvPhoneInput> is just one renderer over this core.
  */
-import { COUNTRIES, COUNTRY_BY_CODE, flagEmoji } from './countries';
+import { COUNTRIES, COUNTRY_BY_CODE, flagEmoji, phoneDigitsValid } from './countries';
 import { applyMask } from './datetime/mask';
+import { editorAria } from './editor-contract';
 /** Best-effort parse: strip to the longest matching dial code. */
 function matchCountry(v) {
     return [...COUNTRIES].sort((a, b) => b.dial.length - a.dial.length).find((c) => v.startsWith(c.dial));
@@ -58,8 +59,12 @@ export function createPhoneInput(config) {
             }
         }
     });
+    // Per-country length validity: empty is valid (required handles emptiness);
+    // a non-empty number must match the country's expected national length.
+    const complete = $derived(national.length > 0 && phoneDigitsValid(iso, national));
+    const valid = $derived(national.length === 0 || phoneDigitsValid(iso, national));
     function emit() {
-        config.onChange?.(`${dial}${national}`, { country: iso, dial, national });
+        config.onChange?.(`${dial}${national}`, { country: iso, dial, national, valid, complete });
     }
     function onNumberInput(e) {
         const raw = e.currentTarget.value.replace(/\D/g, '');
@@ -72,6 +77,14 @@ export function createPhoneInput(config) {
         lastVal = `${dial}${national}`;
         emit();
     }
+    const ariaState = () => ({
+        id: config.id?.(),
+        invalid: config.invalid?.(),
+        required: config.required?.(),
+        error: config.error?.(),
+        hint: config.hint?.(),
+        ariaLabel: config.ariaLabel?.(),
+    });
     return {
         /** Selected country ISO code. */
         get iso() { return iso; },
@@ -83,21 +96,29 @@ export function createPhoneInput(config) {
         get displayNational() { return displayNational; },
         /** The full emitted value (`+<dial><digits>`). */
         get value() { return `${dial}${national}`; },
+        /** Whether the national number is a plausible length for the country. */
+        get valid() { return valid; },
+        /** Whether a non-empty number matches the country's expected length. */
+        get complete() { return complete; },
         /** Spread onto the country `<select>` element. */
         selectProps: () => ({
             value: iso,
             disabled: disabled(),
-            'aria-label': 'Country',
+            'aria-label': config.countryLabel?.() ?? 'Country',
             onchange: onCountryChange,
         }),
         /** Spread onto the national number input element. */
         inputProps: () => ({
+            id: config.id?.(),
             value: displayNational,
             type: 'tel',
             inputmode: 'tel',
             placeholder: config.placeholder?.() ?? 'Phone number',
             disabled: disabled(),
             readonly: readonly(),
+            // aria-invalid/required/describedby come from the editor contract; the
+            // aria-label default stays 'Phone number' so the field is always named.
+            ...editorAria(ariaState()),
             'aria-label': config.ariaLabel?.() ?? 'Phone number',
             oninput: onNumberInput,
         }),

package/dist/createPopoverSelect.svelte.d.ts

@@ -0,0 +1,86 @@
+/**
+ * createPopoverSelect - the shared HEADLESS engine behind the kit's dropdown
+ * selects (SvMultiSelect, SvTreeSelect, SvGridSelect and any future one). It
+ * owns the parts every anchored-panel select repeats: open/close state, the
+ * `anchoredRect` positioning (reposition on scroll/resize), outside/Escape
+ * dismissal via the shared layer stack, a roving `active` index over the visible
+ * items, the WAI-ARIA combobox wiring (`aria-expanded` / `aria-controls` /
+ * `aria-activedescendant` + stable option ids), and focus management (focus
+ * moves into the panel on open, back to the trigger on close).
+ *
+ * The component owns its own `bind:this` refs and item rendering; it passes the
+ * refs in as getters and spreads the returned prop-getters onto its trigger,
+ * panel and items. Runes-based, like `createListbox`.
+ */
+import { type AnchoredRect } from './popover';
+export type PopoverSelectConfig = {
+    /** Number of currently-visible/navigable items (post-filter). */
+    itemCount: () => number;
+    /** Whether item `i` is disabled (skipped by roving, not selectable). */
+    disabled?: (index: number) => boolean;
+    /** Commit the item at `index` (Enter or a click the component forwards). */
+    onSelect: (index: number) => void;
+    /** Notified whenever the open state changes. */
+    onOpenChange?: (open: boolean) => void;
+    /** The trigger element (component owns `bind:this`, passes a getter). */
+    getTrigger: () => HTMLElement | null;
+    /** The panel element. */
+    getPanel: () => HTMLElement | null;
+    /** Element focused when the panel opens (e.g. a search input). Defaults to the
+     *  panel itself. Its id-holder also carries `aria-activedescendant`. */
+    getInitialFocus?: () => HTMLElement | null;
+    /** Estimated panel height, for the flip-up decision. Default 280. */
+    estimatedHeight?: () => number;
+    /** Minimum panel width. Default 200. */
+    minWidth?: () => number;
+    /** Close after a selection (single-select). Default true. */
+    closeOnSelect?: () => boolean;
+    /** Active index to start on when opening (e.g. the selected row). Default 0. */
+    initialActive?: () => number;
+    /** Handle a key the core doesn't (e.g. tree ArrowLeft/Right). Return true if
+     *  handled to stop the core's default handling. */
+    onExtraKey?: (event: KeyboardEvent, active: number) => boolean;
+    idPrefix?: string;
+};
+export declare function createPopoverSelect(config: PopoverSelectConfig): {
+    open: boolean;
+    active: number;
+    readonly rect: AnchoredRect;
+    /** Stable id of the panel element (for aria-controls / labelling). */
+    panelId: string;
+    /** Stable id of the option at `i` (for aria-activedescendant + item id). */
+    optionId: (i: number) => string;
+    activeDescendant: () => string | undefined;
+    openPanel: () => void;
+    closePanel: () => void;
+    toggle: () => void;
+    move: (delta: number) => void;
+    first: () => void;
+    last: () => void;
+    selectActive: () => void;
+    updatePos: () => void;
+    onPanelKeydown: (e: KeyboardEvent) => void;
+    /** True when item `i` is the roving-active one. */
+    isActive: (i: number) => boolean;
+    /** Spread onto the trigger button. */
+    triggerProps: () => {
+        'aria-haspopup': "listbox";
+        'aria-expanded': boolean;
+        'aria-controls': string | undefined;
+        onkeydown: (e: KeyboardEvent) => void;
+    };
+    /** Attributes for the element that OWNS focus + activedescendant (the panel,
+     *  or a search input). Pass the ARIA role the panel should expose. */
+    focusOwnerProps: (role?: "listbox" | "tree" | "grid") => {
+        role: "listbox" | "grid" | "tree";
+        'aria-activedescendant': string | undefined;
+        onkeydown: (e: KeyboardEvent) => void;
+    };
+    /** Spread onto the item element at `i`. */
+    itemProps: (i: number) => {
+        id: string;
+        'data-active': string | undefined;
+        onpointermove: () => void;
+    };
+};
+export type PopoverSelect = ReturnType<typeof createPopoverSelect>;