@svgrid/grid 2.1.21 → 2.1.23

package/dist/createForm.svelte.d.ts

@@ -0,0 +1,62 @@
+/**
+ * createForm - the HEADLESS core behind <SvForm>: values / errors / touched
+ * state, required + rule + custom validation (validate-on-blur-then-live), and a
+ * submit that validates every field first. No markup, no controls - you render
+ * the fields however you like and read/write through the core.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createForm } from '@svgrid/grid'
+ *   const form = createForm({ fields: () => fields, onSubmit: (v) => save(v) })
+ * </script>
+ * <form onsubmit={(e) => { e.preventDefault(); form.submit() }}>
+ *   {#each fields as f}
+ *     <input value={form.value(f.name) ?? ''}
+ *       oninput={(e) => form.setValue(f.name, e.currentTarget.value)}
+ *       onblur={() => form.handleBlur(f.name)} />
+ *     {#if form.error(f.name)}<span>{form.error(f.name)}</span>{/if}
+ *   {/each}
+ * </form>
+ * ```
+ */
+import { type FormEntry } from './form-field';
+export type FormConfig = {
+    /** The schema - a mix of flat fields and titled sections. */
+    fields: () => ReadonlyArray<FormEntry>;
+    /** Seed values on creation. */
+    initial?: Record<string, any>;
+    /** Called with the (visible-field) values on a valid submit. May be async;
+     *  `submitting` stays true until the returned promise settles. */
+    onSubmit?: (values: Record<string, any>) => void | Promise<void>;
+    onChange?: (values: Record<string, any>) => void;
+};
+export declare function createForm(config: FormConfig): {
+    readonly values: Record<string, any>;
+    readonly submitting: boolean;
+    readonly isDirty: boolean;
+    value: (name: string) => any;
+    error: (name: string) => string | undefined;
+    isTouched: (name: string) => boolean;
+    hasError: (name: string) => boolean;
+    isValidating: (name: string) => boolean;
+    isFieldDirty: (name: string) => boolean;
+    isVisible: (name: string) => boolean;
+    isDisabled: (name: string) => boolean;
+    entries: () => readonly FormEntry[];
+    arrayItems: (name: string) => Record<string, any>[];
+    itemValue: (name: string, i: number, field: string) => any;
+    itemError: (name: string, i: number, field: string) => string | undefined;
+    addItem: (name: string, item?: Record<string, any>) => void;
+    removeItem: (name: string, i: number) => void;
+    moveItem: (name: string, from: number, to: number) => void;
+    setItemValue: (name: string, i: number, field: string, v: any) => void;
+    handleItemBlur: (name: string, i: number, field: string) => void;
+    setValue: (name: string, v: any) => void;
+    handleBlur: (name: string) => void;
+    validateField: (name: string) => boolean;
+    validateFields: (names: string[]) => Promise<boolean>;
+    submit: () => Promise<boolean>;
+    reset: (next?: Record<string, any>) => void;
+    setErrors: (map: Record<string, string>) => void;
+};
+export type Form = ReturnType<typeof createForm>;

package/dist/createForm.svelte.js

@@ -0,0 +1,374 @@
+/**
+ * createForm - the HEADLESS core behind <SvForm>: values / errors / touched
+ * state, required + rule + custom validation (validate-on-blur-then-live), and a
+ * submit that validates every field first. No markup, no controls - you render
+ * the fields however you like and read/write through the core.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createForm } from '@svgrid/grid'
+ *   const form = createForm({ fields: () => fields, onSubmit: (v) => save(v) })
+ * </script>
+ * <form onsubmit={(e) => { e.preventDefault(); form.submit() }}>
+ *   {#each fields as f}
+ *     <input value={form.value(f.name) ?? ''}
+ *       oninput={(e) => form.setValue(f.name, e.currentTarget.value)}
+ *       onblur={() => form.handleBlur(f.name)} />
+ *     {#if form.error(f.name)}<span>{form.error(f.name)}</span>{/if}
+ *   {/each}
+ * </form>
+ * ```
+ */
+import { flattenFields } from './form-field';
+import { runRules } from './validators';
+/** Deep-ish equality for dirty tracking: identity for primitives, structural
+ *  (JSON) for arrays/objects. Good enough for form values. */
+function eq(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a && b && typeof a === 'object' && typeof b === 'object') {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+/** Resolve a `boolean | (values) => boolean` field flag. */
+function resolveFlag(flag, dflt, values) {
+    if (flag == null)
+        return dflt;
+    return typeof flag === 'function' ? !!flag(values) : !!flag;
+}
+export function createForm(config) {
+    let values = $state({ ...(config.initial ?? {}) });
+    let errors = $state({});
+    let touched = $state({});
+    let submitting = $state(false);
+    let validating = $state({});
+    // Baseline for dirty tracking + reset. Rebased when `reset(next)` is passed.
+    let baseline = { ...(config.initial ?? {}) };
+    // Async-validation bookkeeping: debounce timers + a per-field run sequence so
+    // only the latest response wins (stale responses are dropped).
+    const asyncTimers = new Map();
+    const asyncSeq = new Map();
+    // The flat field list (sections flattened) drives all values/validation.
+    const flat = () => flattenFields(config.fields());
+    const fieldOf = (name) => flat().find((f) => f.name === name);
+    const isVisible = (name) => resolveFlag(fieldOf(name)?.visible, true, values);
+    const isDisabled = (name) => resolveFlag(fieldOf(name)?.disabled, false, values);
+    function setError(name, err) {
+        const next = { ...errors };
+        if (err)
+            next[name] = err;
+        else
+            delete next[name];
+        errors = next;
+    }
+    /** The synchronous checks: required, then declarative rules, then a sync
+     *  `validate`. Returns the first error message, or null. `ctx` is the values
+     *  object rules/validate see - the form values, or a single item for array
+     *  rows (so within-row cross-field rules work). */
+    function syncError(field, v, ctx = values) {
+        if (field.required && (v == null || v === '' || (Array.isArray(v) && !v.length)))
+            return `${field.label} is required`;
+        if (field.rules) {
+            const e = runRules(v, field.rules, ctx);
+            if (e)
+                return e;
+        }
+        if (field.validate) {
+            const e = field.validate(v, ctx);
+            if (e)
+                return e;
+        }
+        return null;
+    }
+    function cancelAsync(name) {
+        const t = asyncTimers.get(name);
+        if (t) {
+            clearTimeout(t);
+            asyncTimers.delete(name);
+        }
+        // Bump the sequence so any in-flight response is treated as stale.
+        asyncSeq.set(name, (asyncSeq.get(name) ?? 0) + 1);
+        if (validating[name])
+            validating = { ...validating, [name]: false };
+    }
+    /** Run a field's async validator now (guarded against stale responses). */
+    async function runAsync(name) {
+        const field = fieldOf(name);
+        if (!field?.asyncValidate || !isVisible(name))
+            return true;
+        if (syncError(field, values[name]))
+            return false; // sync error already shown
+        const seq = (asyncSeq.get(name) ?? 0) + 1;
+        asyncSeq.set(name, seq);
+        validating = { ...validating, [name]: true };
+        try {
+            const err = await field.asyncValidate(values[name], values);
+            if (asyncSeq.get(name) !== seq)
+                return true; // superseded - ignore
+            setError(name, err ?? null);
+            return !err;
+        }
+        finally {
+            if (asyncSeq.get(name) === seq)
+                validating = { ...validating, [name]: false };
+        }
+    }
+    function scheduleAsync(name) {
+        const field = fieldOf(name);
+        if (!field?.asyncValidate)
+            return;
+        const prev = asyncTimers.get(name);
+        if (prev)
+            clearTimeout(prev);
+        asyncTimers.set(name, setTimeout(() => { asyncTimers.delete(name); runAsync(name); }, field.asyncDebounce ?? 300));
+    }
+    function validateField(name) {
+        const field = fieldOf(name);
+        if (!field)
+            return true;
+        // Hidden fields never block submit; clear any stale error + pending check.
+        if (!isVisible(name)) {
+            setError(name, null);
+            cancelAsync(name);
+            return true;
+        }
+        if (field.type === 'array')
+            return validateArray(field);
+        const err = syncError(field, values[name]);
+        setError(name, err);
+        if (err) {
+            cancelAsync(name);
+            return false;
+        }
+        // Sync passed - kick off the debounced async check if there is one.
+        if (field.asyncValidate)
+            scheduleAsync(name);
+        return true;
+    }
+    // --- Field arrays (repeatable groups) -----------------------------------
+    const arrayItems = (name) => Array.isArray(values[name]) ? values[name] : [];
+    const itemValue = (name, i, field) => arrayItems(name)[i]?.[field];
+    const itemError = (name, i, field) => errors[`${name}.${i}.${field}`];
+    function clearNamespacedErrors(name) {
+        const prefix = `${name}.`;
+        const next = { ...errors };
+        let changed = false;
+        for (const k of Object.keys(next))
+            if (k.startsWith(prefix)) {
+                delete next[k];
+                changed = true;
+            }
+        if (changed)
+            errors = next;
+    }
+    function setItems(name, next) {
+        values = { ...values, [name]: next };
+        config.onChange?.(values);
+    }
+    function addItem(name, item) {
+        const seed = item ?? Object.fromEntries((fieldOf(name)?.itemFields ?? []).map((f) => [f.name, undefined]));
+        setItems(name, [...arrayItems(name), seed]);
+    }
+    function removeItem(name, i) {
+        const items = arrayItems(name).slice();
+        items.splice(i, 1);
+        clearNamespacedErrors(name); // item indices shift - drop stale keys
+        setItems(name, items);
+    }
+    function moveItem(name, from, to) {
+        const items = arrayItems(name).slice();
+        if (from < 0 || from >= items.length || to < 0 || to >= items.length)
+            return;
+        const [it] = items.splice(from, 1);
+        items.splice(to, 0, it);
+        clearNamespacedErrors(name);
+        setItems(name, items);
+    }
+    function setItemValue(name, i, field, v) {
+        setItems(name, arrayItems(name).map((it, ix) => (ix === i ? { ...it, [field]: v } : it)));
+        if (touched[`${name}.${i}.${field}`])
+            validateItemField(name, i, field);
+    }
+    function handleItemBlur(name, i, field) {
+        touched = { ...touched, [`${name}.${i}.${field}`]: true };
+        validateItemField(name, i, field);
+    }
+    function validateItemField(name, i, fieldName) {
+        const itemField = fieldOf(name)?.itemFields?.find((f) => f.name === fieldName);
+        if (!itemField)
+            return true;
+        const item = arrayItems(name)[i] ?? {};
+        const err = syncError(itemField, item[fieldName], item);
+        setError(`${name}.${i}.${fieldName}`, err);
+        return !err;
+    }
+    function validateArray(field) {
+        const name = field.name;
+        const items = arrayItems(name);
+        let arrErr = null;
+        if (field.required && items.length === 0)
+            arrErr = `${field.label} is required`;
+        else if (field.minItems != null && items.length < field.minItems)
+            arrErr = `Add at least ${field.minItems} item(s)`;
+        else if (field.maxItems != null && items.length > field.maxItems)
+            arrErr = `At most ${field.maxItems} item(s)`;
+        setError(name, arrErr);
+        let ok = !arrErr;
+        clearNamespacedErrors(name); // rebuild fresh per-item errors
+        for (let i = 0; i < items.length; i++)
+            for (const itf of field.itemFields ?? [])
+                if (!validateItemField(name, i, itf.name))
+                    ok = false;
+        return ok;
+    }
+    function setValue(name, v) {
+        values = { ...values, [name]: v };
+        config.onChange?.(values);
+        // Re-validate live once the field has been blurred at least once.
+        if (touched[name])
+            validateField(name);
+    }
+    function handleBlur(name) {
+        touched = { ...touched, [name]: true };
+        validateField(name);
+    }
+    async function submit() {
+        let ok = true;
+        const t = { ...touched };
+        for (const f of flat()) {
+            if (!isVisible(f.name))
+                continue;
+            t[f.name] = true;
+            if (!validateField(f.name))
+                ok = false;
+        }
+        touched = t;
+        if (!ok)
+            return false;
+        // Await async validators (run now, skipping their debounce). Any failure blocks.
+        const asyncFields = flat().filter((f) => f.asyncValidate && isVisible(f.name));
+        if (asyncFields.length) {
+            for (const f of asyncFields) {
+                const timer = asyncTimers.get(f.name);
+                if (timer) {
+                    clearTimeout(timer);
+                    asyncTimers.delete(f.name);
+                }
+            }
+            const results = await Promise.all(asyncFields.map((f) => runAsync(f.name)));
+            if (results.some((r) => !r))
+                return false;
+        }
+        // Exclude hidden fields from the submitted payload; keep any non-field keys.
+        const payload = { ...values };
+        for (const f of flat())
+            if (!isVisible(f.name))
+                delete payload[f.name];
+        submitting = true;
+        try {
+            await config.onSubmit?.(payload);
+        }
+        finally {
+            submitting = false;
+        }
+        return true;
+    }
+    /** Validate a subset of fields by name (sync + their async validators). Used
+     *  to gate a wizard step before advancing. Returns true when all pass. */
+    async function validateFields(names) {
+        let ok = true;
+        const t = { ...touched };
+        for (const name of names) {
+            if (!isVisible(name))
+                continue;
+            t[name] = true;
+            if (!validateField(name))
+                ok = false;
+        }
+        touched = t;
+        if (!ok)
+            return false;
+        const asyncNames = names.filter((n) => fieldOf(n)?.asyncValidate && isVisible(n));
+        if (asyncNames.length) {
+            for (const n of asyncNames) {
+                const timer = asyncTimers.get(n);
+                if (timer) {
+                    clearTimeout(timer);
+                    asyncTimers.delete(n);
+                }
+            }
+            const results = await Promise.all(asyncNames.map((n) => runAsync(n)));
+            if (results.some((r) => !r))
+                return false;
+        }
+        return true;
+    }
+    /** Restore values to the baseline (or a new one), clearing errors + touched. */
+    function reset(next) {
+        if (next)
+            baseline = { ...next };
+        values = { ...baseline };
+        errors = {};
+        touched = {};
+        config.onChange?.(values);
+    }
+    /** Inject errors (e.g. server-side validation after submit) and mark those
+     *  fields touched so the messages show. Empty message clears a field's error. */
+    function setErrors(map) {
+        const nextErr = { ...errors };
+        const nextTouched = { ...touched };
+        for (const [k, msg] of Object.entries(map)) {
+            if (msg) {
+                nextErr[k] = msg;
+                nextTouched[k] = true;
+            }
+            else
+                delete nextErr[k];
+        }
+        errors = nextErr;
+        touched = nextTouched;
+    }
+    const isFieldDirty = (name) => !eq(values[name], baseline[name]);
+    return {
+        get values() { return values; },
+        get submitting() { return submitting; },
+        get isDirty() {
+            const keys = new Set([...Object.keys(values), ...Object.keys(baseline)]);
+            for (const k of keys)
+                if (!eq(values[k], baseline[k]))
+                    return true;
+            return false;
+        },
+        value: (name) => values[name],
+        error: (name) => errors[name],
+        isTouched: (name) => !!touched[name],
+        hasError: (name) => !!errors[name],
+        isValidating: (name) => !!validating[name],
+        isFieldDirty,
+        isVisible,
+        isDisabled,
+        entries: () => config.fields(),
+        // Field arrays
+        arrayItems,
+        itemValue,
+        itemError,
+        addItem,
+        removeItem,
+        moveItem,
+        setItemValue,
+        handleItemBlur,
+        setValue,
+        handleBlur,
+        validateField,
+        validateFields,
+        submit,
+        reset,
+        setErrors,
+    };
+}

package/dist/createMenu.svelte.d.ts

@@ -0,0 +1,88 @@
+/**
+ * createMenu - the HEADLESS core behind <SvMenuList> / <SvMenu>, in the same
+ * spirit as `createListbox`: a runes-based state machine for ONE menu level -
+ * roving focus over enabled items, submenu open/collapse, and the full WAI-ARIA
+ * menu keyboard contract (arrows, Home/End, Enter/Space, Escape, Tab, and
+ * rtl-aware ArrowLeft/Right) - with **prop-getters** you spread onto your own
+ * markup. No styles, no DOM assumptions.
+ *
+ * A menu tree is recursive, so you create one core per nesting level (exactly
+ * what the recursive <SvMenuList> does). The styled component is just one
+ * renderer over this core.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMenu, type MenuItem } from '@svgrid/grid'
+ *   let listEl = $state<HTMLElement | null>(null)
+ *   const menu = createMenu({
+ *     items: () => items,
+ *     onSelect: (it) => run(it),
+ *     onClose: () => close(),
+ *     focusItem: (i) => queueMicrotask(() => listEl?.querySelector(`[data-mi="${i}"]`)?.focus()),
+ *   })
+ * </script>
+ * <div bind:this={listEl} {...menu.listProps()}>
+ *   {#each items as item, i}
+ *     <button {...menu.itemProps(i)}>{item.label}</button>
+ *   {/each}
+ * </div>
+ * ```
+ */
+import type { MenuItem } from './menu-item';
+import type { EditorDir } from './editor-contract';
+/** Reactive inputs are getters so the core tracks live prop changes (the same
+ *  controlled pattern as `createListbox`). */
+export type MenuConfig = {
+    items: () => ReadonlyArray<MenuItem>;
+    /** Report the chosen leaf item (a non-parent menuitem). */
+    onSelect: (item: MenuItem) => void;
+    /** Close the WHOLE menu tree - a leaf was chosen, or Escape / Tab / dismissal. */
+    onClose: () => void;
+    /** This level is a submenu: enables ArrowLeft (or ArrowRight under rtl) to
+     *  collapse back into the opener. The root level has nowhere to collapse. */
+    submenu?: () => boolean;
+    /** Collapse just THIS submenu level and refocus the item that opened it. */
+    onCollapse?: () => void;
+    /** Text direction; under `rtl` the open/collapse arrow keys swap. */
+    dir?: () => EditorDir | undefined;
+    /** DOM focus hook, invoked ONLY on keyboard navigation (never on hover) so the
+     *  core stays DOM-free. Receives the item index that should take focus. */
+    focusItem?: (index: number) => void;
+};
+export type MenuItemProps = {
+    role: 'menuitem';
+    'data-mi': number;
+    tabindex: 0 | -1;
+    'aria-haspopup': 'menu' | undefined;
+    'aria-expanded': boolean | undefined;
+    'aria-disabled': true | undefined;
+    disabled: boolean | undefined;
+    onkeydown: (event: KeyboardEvent) => void;
+    onpointerenter: () => void;
+    onclick: () => void;
+};
+export declare function createMenu(config: MenuConfig): {
+    readonly active: number;
+    readonly openSub: number;
+    /** Enabled (focusable) item indices. */
+    readonly focusables: number[];
+    isActive: (i: number) => boolean;
+    isSubOpen: (i: number) => boolean;
+    itemTabIndex: (i: number) => 0 | -1;
+    move: (delta: number) => void;
+    first: () => void;
+    last: () => void;
+    /** Highlight + DOM-focus item `i` (e.g. to refocus a submenu's opener). */
+    focus: (i: number) => void;
+    hover: (i: number) => void;
+    choose: (item: MenuItem) => void;
+    onItemKeydown: (e: KeyboardEvent, i: number) => void;
+    /** Spread onto the menu container element. */
+    listProps: () => {
+        role: "menu";
+    };
+    /** Spread onto the menuitem element at `i`. */
+    itemProps: (i: number) => MenuItemProps;
+};
+export type Menu = ReturnType<typeof createMenu>;
+export type { MenuItem };

package/dist/createMenu.svelte.js

@@ -0,0 +1,153 @@
+import { enabledIndices, wrapMove } from './list-nav';
+let uid = 0;
+export function createMenu(config) {
+    const items = () => config.items();
+    const submenu = () => config.submenu?.() ?? false;
+    const rtl = () => (config.dir?.() ?? 'ltr') === 'rtl';
+    // -1 = nothing focused yet (the first enabled item is the tab stop).
+    let active = $state(-1);
+    let openSub = $state(-1);
+    // Real (non-separator, non-disabled) item indices, for roving focus.
+    const focusables = $derived(enabledIndices(items().length, (i) => {
+        const it = items()[i];
+        return !it || it.separator === true || it.disabled === true;
+    }));
+    /** Move focus to item `i` (keyboard): highlight it, close any open submenu at
+     *  this level, and drive real DOM focus through the host's hook. */
+    function focus(i) {
+        active = i;
+        openSub = -1;
+        config.focusItem?.(i);
+    }
+    function move(delta) {
+        const next = wrapMove(focusables, active, delta);
+        if (next >= 0)
+            focus(next);
+    }
+    function first() {
+        const f = focusables[0];
+        if (f != null)
+            focus(f);
+    }
+    function last() {
+        const l = focusables.at(-1);
+        if (l != null)
+            focus(l);
+    }
+    /** Hover highlight: sets active WITHOUT stealing DOM focus, and opens a parent
+     *  item's submenu (mirrors the pointerenter behaviour). */
+    function hover(i) {
+        const it = items()[i];
+        if (!it || it.disabled || it.separator)
+            return;
+        active = i;
+        openSub = it.children?.length ? i : -1;
+    }
+    function choose(item) {
+        if (item.disabled || item.separator)
+            return;
+        if (item.children?.length) {
+            openSub = items().indexOf(item);
+            return;
+        }
+        item.onSelect?.();
+        config.onSelect(item);
+        config.onClose();
+    }
+    function onItemKeydown(e, i) {
+        const item = items()[i];
+        // Open this item's submenu (ArrowRight, or ArrowLeft under rtl).
+        const openThis = () => {
+            if (item?.children?.length) {
+                e.preventDefault();
+                openSub = i;
+            }
+        };
+        // Collapse just THIS list back into its parent (opposite key under rtl).
+        const collapseThis = () => {
+            if (submenu()) {
+                e.preventDefault();
+                config.onCollapse?.();
+            }
+        };
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                move(1);
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                move(-1);
+                break;
+            case 'Home':
+                e.preventDefault();
+                first();
+                break;
+            case 'End':
+                e.preventDefault();
+                last();
+                break;
+            case 'ArrowRight':
+                (rtl() ? collapseThis : openThis)();
+                break;
+            case 'ArrowLeft':
+                (rtl() ? openThis : collapseThis)();
+                break;
+            case 'Enter':
+            case ' ':
+                e.preventDefault();
+                if (item)
+                    choose(item);
+                break;
+            case 'Escape':
+                e.preventDefault();
+                config.onClose();
+                break;
+            // Tab leaves the menu entirely (WAI-ARIA menu-button pattern): close the
+            // whole tree rather than trapping focus inside a portalled panel.
+            case 'Tab':
+                config.onClose();
+                break;
+        }
+    }
+    function itemTabIndex(i) {
+        return active === i || (active === -1 && i === focusables[0]) ? 0 : -1;
+    }
+    return {
+        get active() { return active; },
+        get openSub() { return openSub; },
+        /** Enabled (focusable) item indices. */
+        get focusables() { return focusables; },
+        isActive: (i) => i === active,
+        isSubOpen: (i) => i === openSub,
+        itemTabIndex,
+        move,
+        first,
+        last,
+        /** Highlight + DOM-focus item `i` (e.g. to refocus a submenu's opener). */
+        focus,
+        hover,
+        choose,
+        onItemKeydown,
+        /** Spread onto the menu container element. */
+        listProps: () => ({ role: 'menu' }),
+        /** Spread onto the menuitem element at `i`. */
+        itemProps: (i) => {
+            const it = items()[i];
+            const hasKids = !!it?.children?.length;
+            return {
+                role: 'menuitem',
+                'data-mi': i,
+                tabindex: itemTabIndex(i),
+                'aria-haspopup': hasKids ? 'menu' : undefined,
+                'aria-expanded': hasKids ? openSub === i : undefined,
+                'aria-disabled': it?.disabled ? true : undefined,
+                disabled: it?.disabled,
+                onkeydown: (e) => onItemKeydown(e, i),
+                onpointerenter: () => hover(i),
+                onclick: () => { if (it)
+                    choose(it); },
+            };
+        },
+    };
+}