@svgrid/grid 1.2.33 → 2.0.0

package/dist/createTabs.svelte.js

@@ -19,13 +19,22 @@ export function createTabs(config) {
             return;
         config.onChange?.(tid);
     }
+    function close(tid) {
+        const t = tabs().find((x) => x.id === tid);
+        if (t?.closable)
+            config.onClose?.(tid);
+    }
     function onKeydown(e) {
         const list = enabled;
         if (!list.length)
             return;
         const idx = list.findIndex((t) => t.id === active);
-        const fwd = orientation() === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
-        const back = orientation() === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
+        const horiz = orientation() === 'horizontal';
+        // Under horizontal RTL the Left/Right arrows swap so focus follows the
+        // visual order (Right moves to the previous tab).
+        const rtlH = horiz && config.dir?.() === 'rtl';
+        const fwd = horiz ? (rtlH ? 'ArrowLeft' : 'ArrowRight') : 'ArrowDown';
+        const back = horiz ? (rtlH ? 'ArrowRight' : 'ArrowLeft') : 'ArrowUp';
         let next = null;
         if (e.key === fwd)
             next = list[(idx + 1) % list.length]?.id ?? null;
@@ -40,6 +49,11 @@ export function createTabs(config) {
             select(active);
             return;
         }
+        else if (e.key === 'Delete') {
+            e.preventDefault();
+            close(active);
+            return;
+        }
         else
             return;
         if (next) {
@@ -58,6 +72,7 @@ export function createTabs(config) {
         get focusTick() { return focusTick; },
         isActive: (tid) => tid === active,
         select,
+        close,
         onKeydown,
         /** Spread onto the tablist container element. */
         tablistProps: () => ({

package/dist/createTagsInput.svelte.d.ts

@@ -27,6 +27,15 @@ export type TagsInputConfig = {
     unique?: () => boolean;
     max?: () => number;
     ariaLabel?: () => string | undefined;
+    /** Accessible label for the draft input (localizable). */
+    addLabel?: () => string | undefined;
+    /** Accessible label prefix for a chip's remove button (localizable). */
+    removeLabel?: () => string | undefined;
+    id?: () => string | undefined;
+    invalid?: () => boolean;
+    required?: () => boolean;
+    error?: () => string | undefined;
+    hint?: () => string | undefined;
 };
 export declare function createTagsInput(config: TagsInputConfig): {
     /** Current tags (controlled value). */
@@ -38,8 +47,11 @@ export declare function createTagsInput(config: TagsInputConfig): {
     setDraft: (v: string) => void;
     /** Spread onto the container element. */
     rootProps: () => {
-        role: "group";
+        'aria-invalid': "true" | undefined;
+        'aria-required': "true" | undefined;
+        'aria-describedby': string | undefined;
         'aria-label': string | undefined;
+        role: "group";
     };
     /** Spread onto the text <input>. */
     inputProps: () => {

package/dist/createTagsInput.svelte.js

@@ -18,11 +18,20 @@
  * </div>
  * ```
  */
+import { editorAria } from './editor-contract';
 export function createTagsInput(config) {
     const disabled = () => config.disabled?.() ?? false;
     const unique = () => config.unique?.() ?? true;
     const max = () => config.max?.() ?? Infinity;
     const tags = () => config.value();
+    const ariaState = () => ({
+        id: config.id?.(),
+        invalid: config.invalid?.(),
+        required: config.required?.(),
+        error: config.error?.(),
+        hint: config.hint?.(),
+        ariaLabel: config.ariaLabel?.(),
+    });
     let draft = $state('');
     function add(raw) {
         const tag = raw.trim();
@@ -67,14 +76,14 @@ export function createTagsInput(config) {
         /** Spread onto the container element. */
         rootProps: () => ({
             role: 'group',
-            'aria-label': config.ariaLabel?.(),
+            ...editorAria(ariaState()),
         }),
         /** Spread onto the text <input>. */
         inputProps: () => ({
             type: 'text',
             value: draft,
             disabled: disabled(),
-            'aria-label': config.ariaLabel?.() ?? 'Add tag',
+            'aria-label': config.addLabel?.() ?? config.ariaLabel?.() ?? 'Add tag',
             oninput: onInput,
             onkeydown: onKeydown,
             onblur: onBlur,
@@ -86,7 +95,7 @@ export function createTagsInput(config) {
         /** Spread onto a chip's remove <button> at `index`. */
         removeProps: (index) => ({
             type: 'button',
-            'aria-label': `Remove ${tags()[index] ?? ''}`,
+            'aria-label': `${config.removeLabel?.() ?? 'Remove'} ${tags()[index] ?? ''}`.trim(),
             onclick: () => removeAt(index),
         }),
     };

package/dist/createToggle.svelte.d.ts

@@ -21,11 +21,20 @@ export type ToggleConfig = {
     pressed: () => boolean;
     onChange?: (pressed: boolean) => void;
     disabled?: () => boolean;
+    id?: () => string | undefined;
+    invalid?: () => boolean;
+    required?: () => boolean;
+    error?: () => string | undefined;
+    hint?: () => string | undefined;
     ariaLabel?: () => string | undefined;
 };
 export type ToggleButtonProps = {
     type: 'button';
+    id: string | undefined;
     'aria-pressed': boolean;
+    'aria-invalid': 'true' | undefined;
+    'aria-required': 'true' | undefined;
+    'aria-describedby': string | undefined;
     'aria-label': string | undefined;
     disabled: boolean;
     'data-pressed': '' | undefined;

package/dist/createToggle.svelte.js

@@ -15,6 +15,7 @@
  *
  * The styled <SvToggleButton> is just one renderer over this core.
  */
+import { editorAria } from './editor-contract';
 export function createToggle(config) {
     const pressed = () => config.pressed();
     const disabled = () => config.disabled?.() ?? false;
@@ -23,16 +24,26 @@ export function createToggle(config) {
             return;
         config.onChange?.(!pressed());
     }
+    // The validation/label ARIA is derived from the editor contract state.
+    const ariaState = () => ({
+        id: config.id?.(),
+        invalid: config.invalid?.(),
+        required: config.required?.(),
+        error: config.error?.(),
+        hint: config.hint?.(),
+        ariaLabel: config.ariaLabel?.(),
+    });
     return {
         get pressed() { return pressed(); },
         get disabled() { return disabled(); },
         toggle,
         buttonProps: () => ({
             type: 'button',
+            id: config.id?.(),
             'aria-pressed': pressed(),
-            'aria-label': config.ariaLabel?.(),
             disabled: disabled(),
             'data-pressed': pressed() ? '' : undefined,
+            ...editorAria(ariaState()),
             onclick: toggle,
         }),
     };

package/dist/createTree.svelte.d.ts

@@ -26,6 +26,9 @@ export type TreeNode = {
     label: string;
     children?: TreeNode[];
     disabled?: boolean;
+    /** Marks a node whose children are loaded on demand (shows an expand arrow
+     *  even with no children yet; the renderer loads them on first expand). */
+    lazy?: boolean;
 };
 export type CheckState = 'checked' | 'indeterminate' | 'unchecked';
 /** A single visible (flattened) tree row. */
@@ -41,6 +44,18 @@ export type TreeRow = {
 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;
+/** Where a dragged node lands relative to the drop target. */
+export type TreeDropPosition = 'before' | 'after' | 'inside';
+/** True if `id` is inside `node`'s subtree (used to block invalid drops). */
+export declare function treeContains(node: TreeNode, id: string): boolean;
+/**
+ * Return a NEW node tree with `dragId` moved before/after/inside `targetId`
+ * (pure - the caller sets it back as the controlled `nodes`). No-ops on invalid
+ * moves (self, or into own descendant).
+ */
+export declare function moveTreeNode(nodes: ReadonlyArray<TreeNode>, dragId: string, targetId: string, position: TreeDropPosition): TreeNode[];
+/** Sort siblings (recursively) by a comparator (pure). */
+export declare function sortTreeNodes(nodes: ReadonlyArray<TreeNode>, compare: (a: TreeNode, b: TreeNode) => number): TreeNode[];
 /** Reactive inputs are passed as getters so the core tracks live prop changes. */
 export type TreeConfig = {
     nodes: () => ReadonlyArray<TreeNode>;
@@ -53,6 +68,10 @@ export type TreeConfig = {
     checked?: () => string[];
     onCheck?: (ids: string[]) => void;
     ariaLabel?: () => string | undefined;
+    /** Text direction; under `'rtl'` the Left/Right expand/collapse keys swap. */
+    dir?: () => import('./editor-contract').EditorDir | undefined;
+    /** Filter query: show only matching nodes + their ancestors, auto-expanded. */
+    filter?: () => string | undefined;
 };
 export declare function createTree(config: TreeConfig): {
     /** Internally-managed set of expanded node ids. */

package/dist/createTree.svelte.js

@@ -32,6 +32,61 @@ function findNode(list, id) {
     }
     return null;
 }
+/** True if `id` is inside `node`'s subtree (used to block invalid drops). */
+export function treeContains(node, id) {
+    return node.children?.some((c) => c.id === id || treeContains(c, id)) ?? false;
+}
+/**
+ * Return a NEW node tree with `dragId` moved before/after/inside `targetId`
+ * (pure - the caller sets it back as the controlled `nodes`). No-ops on invalid
+ * moves (self, or into own descendant).
+ */
+export function moveTreeNode(nodes, dragId, targetId, position) {
+    if (dragId === targetId)
+        return [...nodes];
+    const dragged = findNode(nodes, dragId);
+    if (!dragged)
+        return [...nodes];
+    if (dragId === targetId || treeContains(dragged, targetId))
+        return [...nodes];
+    const without = (list) => {
+        const out = [];
+        for (const n of list) {
+            if (n.id === dragId)
+                continue;
+            out.push(n.children ? { ...n, children: without(n.children) } : n);
+        }
+        return out;
+    };
+    const insert = (list) => {
+        const out = [];
+        for (const n of list) {
+            if (n.id === targetId) {
+                if (position === 'before') {
+                    out.push(dragged, n);
+                }
+                else if (position === 'after') {
+                    out.push(n, dragged);
+                }
+                else
+                    out.push({ ...n, children: [...(n.children ?? []), dragged] });
+            }
+            else if (n.children) {
+                out.push({ ...n, children: insert(n.children) });
+            }
+            else
+                out.push(n);
+        }
+        return out;
+    };
+    return insert(without(nodes));
+}
+/** Sort siblings (recursively) by a comparator (pure). */
+export function sortTreeNodes(nodes, compare) {
+    return [...nodes]
+        .sort(compare)
+        .map((n) => (n.children ? { ...n, children: sortTreeNodes(n.children, compare) } : n));
+}
 export function createTree(config) {
     const nodes = () => config.nodes();
     const checkable = () => config.checkable?.() ?? false;
@@ -47,14 +102,41 @@ export function createTree(config) {
                 expanded = new Set(ids);
         }
     });
+    // When filtering, precompute which nodes to show (a match, or an ancestor of a
+    // match) and which to force-open so matches are revealed.
+    const filterInfo = $derived.by(() => {
+        const q = config.filter?.()?.trim().toLowerCase();
+        if (!q)
+            return null;
+        const visible = new Set();
+        const forceOpen = new Set();
+        const walk = (node) => {
+            let childMatch = false;
+            for (const c of node.children ?? [])
+                childMatch = walk(c) || childMatch;
+            const selfMatch = node.label.toLowerCase().includes(q);
+            if (selfMatch || childMatch) {
+                visible.add(node.id);
+                if (childMatch)
+                    forceOpen.add(node.id);
+            }
+            return selfMatch || childMatch;
+        };
+        for (const n of nodes())
+            walk(n);
+        return { visible, forceOpen };
+    });
     const rows = $derived.by(() => {
         const out = [];
+        const fi = filterInfo;
         const walk = (list, depth, parentId) => {
             for (const node of list) {
-                const hasChildren = !!node.children?.length;
-                const open = expanded.has(node.id);
+                if (fi && !fi.visible.has(node.id))
+                    continue;
+                const hasChildren = !!node.children?.length || !!node.lazy;
+                const open = fi ? fi.forceOpen.has(node.id) || expanded.has(node.id) : expanded.has(node.id);
                 out.push({ node, depth, hasChildren, open, parentId, index: out.length });
-                if (hasChildren && open)
+                if (open && node.children?.length)
                     walk(node.children, depth + 1, node.id);
             }
         };
@@ -73,7 +155,9 @@ export function createTree(config) {
     const isExpanded = (id) => expanded.has(id);
     const isSelected = (id) => id === selected();
     function toggleExpand(node) {
-        if (!node.children?.length)
+        // Lazy nodes have no children *yet* - they must still be expandable so the
+        // toggle fires onToggle and the host can fetch children on demand.
+        if (!node.children?.length && !node.lazy)
             return;
         const next = new Set(expanded);
         const willOpen = !next.has(node.id);
@@ -104,6 +188,24 @@ export function createTree(config) {
         const item = rows[active];
         if (!item)
             return;
+        // "expand" opens the node or steps into the first child; "collapse" closes it
+        // or jumps to the parent. Under RTL the physical Left/Right keys are swapped.
+        const expand = () => {
+            if (item.hasChildren && !item.open)
+                toggleExpand(item.node);
+            else if (item.hasChildren && item.open)
+                setActive(Math.min(active + 1, rows.length - 1), true);
+        };
+        const collapse = () => {
+            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);
+            }
+        };
+        const rtl = config.dir?.() === 'rtl';
         switch (e.key) {
             case 'ArrowDown':
                 e.preventDefault();
@@ -115,20 +217,11 @@ export function createTree(config) {
                 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);
+                (rtl ? collapse : expand)();
                 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);
-                }
+                (rtl ? expand : collapse)();
                 break;
             case 'Enter':
                 e.preventDefault();

package/dist/debounce.d.ts

@@ -0,0 +1,11 @@
+/**
+ * debounce - coalesce rapid calls into one trailing call after `ms` of quiet.
+ * Used for remote search in the async dropdowns (SvMultiSelect/GridSelect/...),
+ * but general-purpose. Returns the debounced function with `cancel()` (drop the
+ * pending call) and `flush()` (run it now). Framework-free + pure.
+ */
+export type Debounced<A extends unknown[]> = ((...args: A) => void) & {
+    cancel: () => void;
+    flush: () => void;
+};
+export declare function debounce<A extends unknown[]>(fn: (...args: A) => void, ms: number): Debounced<A>;

package/dist/debounce.js

@@ -0,0 +1,30 @@
+export function debounce(fn, ms) {
+    let timer = null;
+    let pending = null;
+    const run = () => {
+        timer = null;
+        const args = pending;
+        pending = null;
+        if (args)
+            fn(...args);
+    };
+    const debounced = ((...args) => {
+        pending = args;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(run, ms);
+    });
+    debounced.cancel = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        pending = null;
+    };
+    debounced.flush = () => {
+        if (timer) {
+            clearTimeout(timer);
+            run();
+        }
+    };
+    return debounced;
+}

package/dist/duration.d.ts

@@ -0,0 +1,15 @@
+/**
+ * duration - pure parse/format helpers behind <SvDurationInput>. The canonical
+ * value is a number of MINUTES; these convert to/from the human forms people
+ * type ("1h 30m", "1:30", "90"). Framework-free + pure so they are unit-tested
+ * directly.
+ */
+/**
+ * Parse a human duration to minutes, or `null` if unparseable. Accepts:
+ * - `h:mm`         e.g. "1:30" -> 90
+ * - unit form      e.g. "1h 30m", "1.5h", "45m" -> 90 / 90 / 45
+ * - a bare number  e.g. "90" -> 90 (treated as minutes)
+ */
+export declare function parseDuration(input: string): number | null;
+/** Format minutes as `h:mm` (colon) or `Nh Nm` (units). Empty for invalid input. */
+export declare function formatDuration(minutes: number, style?: 'colon' | 'units'): string;

package/dist/duration.js

@@ -0,0 +1,51 @@
+/**
+ * duration - pure parse/format helpers behind <SvDurationInput>. The canonical
+ * value is a number of MINUTES; these convert to/from the human forms people
+ * type ("1h 30m", "1:30", "90"). Framework-free + pure so they are unit-tested
+ * directly.
+ */
+/**
+ * Parse a human duration to minutes, or `null` if unparseable. Accepts:
+ * - `h:mm`         e.g. "1:30" -> 90
+ * - unit form      e.g. "1h 30m", "1.5h", "45m" -> 90 / 90 / 45
+ * - a bare number  e.g. "90" -> 90 (treated as minutes)
+ */
+export function parseDuration(input) {
+    const s = input.trim().toLowerCase();
+    if (!s)
+        return null;
+    const colon = s.match(/^(\d+):(\d{1,2})$/);
+    if (colon) {
+        const mm = parseInt(colon[2], 10);
+        if (mm > 59)
+            return null;
+        return parseInt(colon[1], 10) * 60 + mm;
+    }
+    const units = s.match(/\d+(?:\.\d+)?\s*[hm]/g);
+    if (units && units.join('').replace(/\s/g, '').length === s.replace(/\s/g, '').length) {
+        let total = 0;
+        for (const part of units) {
+            const m = part.match(/(\d+(?:\.\d+)?)\s*([hm])/);
+            const n = parseFloat(m[1]);
+            total += m[2] === 'h' ? n * 60 : n;
+        }
+        return Math.round(total);
+    }
+    const num = Number(s);
+    return Number.isFinite(num) ? Math.round(num) : null;
+}
+/** Format minutes as `h:mm` (colon) or `Nh Nm` (units). Empty for invalid input. */
+export function formatDuration(minutes, style = 'colon') {
+    if (!Number.isFinite(minutes) || minutes < 0)
+        return '';
+    const h = Math.floor(minutes / 60);
+    const m = Math.round(minutes % 60);
+    if (style === 'units') {
+        if (h && m)
+            return `${h}h ${m}m`;
+        if (h)
+            return `${h}h`;
+        return `${m}m`;
+    }
+    return `${h}:${String(m).padStart(2, '0')}`;
+}

package/dist/editor-contract.d.ts

@@ -2,13 +2,16 @@
  * 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.
+ * of props so forms, validation, accessibility, direction (RTL) and localization
+ * 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';
+/** Text direction. `'auto'` defers to the surrounding document/CSS. */
+export type EditorDir = 'ltr' | 'rtl' | 'auto';
 /** Props shared by every value-bearing editor in the kit. */
 export type SvEditorProps = {
     /** Disable interaction + form submission. */
@@ -21,23 +24,62 @@ export type SvEditorProps = {
     invalid?: boolean;
     /** Error message; when set it is announced via `aria-describedby` and shown. */
     error?: string;
+    /** Visible field label, rendered above the control and wired via `for`/`id`. */
+    label?: string;
+    /** Helper text shown under the control and announced via `aria-describedby`. */
+    hint?: string;
     /** Control size / density. */
     size?: EditorSize;
+    /**
+     * Text direction. `'rtl'` mirrors layout for Arabic/Hebrew/etc.; `'auto'` (the
+     * default) inherits from the surrounding document so a page-level `dir` wins.
+     */
+    dir?: EditorDir;
     /** 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). */
+    /** Root/control element id (the label/hint/error ids derive from it). */
     id?: string;
-    /** Accessible name when there is no visible `<label>`. */
+    /** Accessible name when there is no visible `label`. */
     ariaLabel?: string;
 };
+/**
+ * The interaction surface an editor exposes when embedded as a grid cell editor.
+ * Standalone usage ignores these; the grid supplies them so every editor shares
+ * one commit / cancel / move contract (Enter commits, Escape cancels, Tab moves)
+ * instead of each cell-editor re-implementing key handling. Consumed in Phase 2
+ * (the editor registry).
+ */
+export type EditorInteraction<V = unknown> = {
+    /** Commit the current value and stop editing (Enter, option pick, blur-commit). */
+    onCommit?: (value: V) => void;
+    /** Abandon the edit and restore the previous value (Escape). */
+    onCancel?: () => void;
+    /** Commit, then move to the adjacent cell (Tab = 1, Shift+Tab = -1). */
+    onCommitAndMove?: (value: V, direction: 1 | -1) => void;
+    /** Ask the surrounding popover/panel to close without committing. */
+    onRequestClose?: () => void;
+    /** True while mounted inside a grid cell (lets an editor tune autofocus etc.). */
+    inCell?: boolean;
+};
 /** Stable DOM id for an editor's error text, for `aria-describedby` wiring. */
 export declare const editorErrorId: (id?: string) => string | undefined;
+/** Stable DOM id for an editor's hint text, for `aria-describedby` wiring. */
+export declare const editorHintId: (id?: string) => string | undefined;
+/**
+ * Generate a stable-per-instance element id. Call ONCE per component instance
+ * (e.g. `const uid = provided ?? nextEditorId()`) so label/hint/error wiring
+ * always has an anchor even when the consumer passes no `id`.
+ */
+export declare const nextEditorId: (prefix?: string) => string;
 /** A subset of {@link SvEditorProps} that drives ARIA on the focusable control. */
-export type EditorAriaState = Pick<SvEditorProps, 'id' | 'invalid' | 'required' | 'error' | 'ariaLabel'>;
+export type EditorAriaState = Pick<SvEditorProps, 'id' | 'invalid' | 'required' | 'error' | 'hint' | '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 })} />`
+ * `<input {...editorAria({ id, invalid, required, error, hint, ariaLabel })} />`
+ *
+ * `aria-describedby` points at the error text (when invalid) and/or the hint
+ * text - both ids derive from `id`, so pass a stable `id` (see {@link nextEditorId}).
  * Undefined values are omitted by Svelte, so unset props add no attributes.
  */
 export declare function editorAria(state: EditorAriaState): {
@@ -46,3 +88,16 @@ export declare function editorAria(state: EditorAriaState): {
     'aria-describedby': string | undefined;
     'aria-label': string | undefined;
 };
+/**
+ * Merge a component's default message strings with a consumer's `messages`
+ * override, so every editor can be fully localized from the outside.
+ *
+ * ```ts
+ * const M = { clear: 'Clear', noResults: 'No results' }
+ * const messages = resolveMessages(M, props.messages) // Partial override
+ * ```
+ *
+ * Undefined/empty overrides fall back to the default, so a partial `messages`
+ * object only replaces the keys it sets.
+ */
+export declare function resolveMessages<T extends Record<string, string>>(defaults: T, overrides?: Partial<T> | null): T;

package/dist/editor-contract.js

@@ -2,25 +2,65 @@
  * 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.
+ * of props so forms, validation, accessibility, direction (RTL) and localization
+ * 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);
+/** Stable DOM id for an editor's hint text, for `aria-describedby` wiring. */
+export const editorHintId = (id) => (id ? `${id}__hint` : undefined);
+let _autoId = 0;
+/**
+ * Generate a stable-per-instance element id. Call ONCE per component instance
+ * (e.g. `const uid = provided ?? nextEditorId()`) so label/hint/error wiring
+ * always has an anchor even when the consumer passes no `id`.
+ */
+export const nextEditorId = (prefix = 'sv-ed') => `${prefix}-${_autoId++}`;
 /**
  * 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 })} />`
+ * `<input {...editorAria({ id, invalid, required, error, hint, ariaLabel })} />`
+ *
+ * `aria-describedby` points at the error text (when invalid) and/or the hint
+ * text - both ids derive from `id`, so pass a stable `id` (see {@link nextEditorId}).
  * Undefined values are omitted by Svelte, so unset props add no attributes.
  */
 export function editorAria(state) {
+    const described = [
+        state.error ? editorErrorId(state.id) : undefined,
+        state.hint ? editorHintId(state.id) : undefined,
+    ].filter(Boolean);
     return {
         'aria-invalid': state.invalid ? 'true' : undefined,
         'aria-required': state.required ? 'true' : undefined,
-        'aria-describedby': state.error ? editorErrorId(state.id) : undefined,
+        'aria-describedby': described.length ? described.join(' ') : undefined,
         'aria-label': state.ariaLabel,
     };
 }
+/**
+ * Merge a component's default message strings with a consumer's `messages`
+ * override, so every editor can be fully localized from the outside.
+ *
+ * ```ts
+ * const M = { clear: 'Clear', noResults: 'No results' }
+ * const messages = resolveMessages(M, props.messages) // Partial override
+ * ```
+ *
+ * Undefined/empty overrides fall back to the default, so a partial `messages`
+ * object only replaces the keys it sets.
+ */
+export function resolveMessages(defaults, overrides) {
+    if (!overrides)
+        return defaults;
+    const out = { ...defaults };
+    for (const k in overrides) {
+        const v = overrides[k];
+        if (v != null && v !== '')
+            out[k] = v;
+    }
+    return out;
+}