@svgrid/grid 1.2.34 → 2.0.1

package/dist/server-group-model.js

@@ -0,0 +1,263 @@
+export function serverGroupRows(state) {
+    return (state?.displayRows ?? []).map((r) => ({ ...('data' in r ? r.data : {}), __group: r }));
+}
+/**
+ * Build the `serverGroup` prop for `<SvGrid>` from a controller, so the grid's
+ * built-in tree keyboard (ArrowRight / ArrowLeft expand / collapse) and treegrid
+ * a11y work with no app-level key handling. Reads the `__group` marker that
+ * `serverGroupRows` attaches. Usage: `<SvGrid ... serverGroup={serverGroupNav(ctl)} />`.
+ */
+export function serverGroupNav(ctl) {
+    return {
+        isGroup: (row) => row.__group?.kind === 'group',
+        level: (row) => row.__group?.level ?? 0,
+        expanded: (row) => row.__group?.kind === 'group' ? row.__group.expanded : false,
+        onToggle: (row) => {
+            if (row.__group?.kind === 'group')
+                ctl.toggleGroup(row.__group);
+            else if (row.__group?.kind === 'more')
+                ctl.loadMoreChildren(row.__group.path);
+        },
+    };
+}
+const keyOf = (path) => JSON.stringify(path);
+export function createServerGroupModel(source, options) {
+    let groupBy = [...(options.groupBy ?? [])];
+    const aggregations = options.aggregations ?? [];
+    const pageSize = options.pageSize ?? 200;
+    const treeData = !!options.treeData;
+    if (treeData && (!options.getRowId || !options.hasChildren)) {
+        throw new Error('createServerGroupModel: treeData requires getRowId and hasChildren');
+    }
+    const getRowId = options.getRowId;
+    const hasChildren = options.hasChildren;
+    const groupFooters = !!options.groupFooters;
+    const skeletonRows = Math.max(0, options.skeletonRows ?? 3);
+    let sortModel = [];
+    let filterModel = {};
+    const nodes = new Map();
+    const expanded = new Set(); // path keys
+    // Generation guard: bumped on any tree reset so every fetch in flight for the
+    // previous shape is discarded when it lands (the classic stale-response bug).
+    let generation = 0;
+    let disposed = false;
+    const rootKey = keyOf([]);
+    function ensureNode(key) {
+        let node = nodes.get(key);
+        if (!node) {
+            node = { loaded: false, loading: false, error: null, count: 0, children: [] };
+            nodes.set(key, node);
+        }
+        return node;
+    }
+    // Walk the loaded tree from the root, splicing expanded groups' children in.
+    function flatten() {
+        const out = [];
+        const walk = (path) => {
+            const node = nodes.get(keyOf(path));
+            if (!node?.loaded)
+                return;
+            for (const child of node.children) {
+                if (child.kind === 'leaf') {
+                    out.push({ kind: 'leaf', id: child.id, level: child.level, data: child.data });
+                    continue;
+                }
+                const cid = keyOf(child.path);
+                const cnode = nodes.get(cid);
+                const isExp = expanded.has(cid);
+                out.push({
+                    kind: 'group',
+                    id: cid,
+                    path: child.path,
+                    field: child.field,
+                    key: child.key,
+                    level: child.level,
+                    expanded: isExp,
+                    loading: !!cnode?.loading,
+                    aggregates: child.aggregates,
+                    data: child.data,
+                });
+                if (isExp) {
+                    if (cnode?.loaded) {
+                        walk(child.path);
+                        // Subtotal row after the group's children.
+                        if (groupFooters) {
+                            out.push({
+                                kind: 'footer',
+                                id: cid + 'footer',
+                                level: child.level + 1,
+                                path: child.path,
+                                key: child.key,
+                                aggregates: child.aggregates,
+                                data: child.data,
+                            });
+                        }
+                    }
+                    else if (cnode?.loading) {
+                        // First block in flight: placeholder skeleton rows.
+                        for (let i = 0; i < skeletonRows; i += 1) {
+                            out.push({ kind: 'skeleton', id: cid + 'sk' + i, level: child.level + 1 });
+                        }
+                    }
+                }
+            }
+            // Intra-group paging: emit a "load more" affordance when only part of this
+            // node's children have been fetched.
+            if (node.children.length < node.count) {
+                out.push({
+                    kind: 'more',
+                    id: keyOf([...path, 'more']),
+                    level: path.length,
+                    path,
+                    remaining: node.count - node.children.length,
+                    loading: node.loading,
+                });
+            }
+        };
+        walk([]);
+        return out;
+    }
+    function emit() {
+        if (disposed)
+            return;
+        const root = nodes.get(rootKey);
+        options.onChange({
+            displayRows: flatten(),
+            groupBy: [...groupBy],
+            loading: !!root?.loading && !root?.loaded,
+            error: root?.error ?? null,
+            sortModel,
+            filterModel,
+            expandedGroups: [...expanded],
+        });
+    }
+    // append=false loads the first block of a node's children (on expand);
+    // append=true fetches the NEXT block and concatenates (intra-group paging).
+    async function fetchNode(path, append = false) {
+        if (disposed)
+            return;
+        const gen = generation;
+        const key = keyOf(path);
+        const node = ensureNode(key);
+        if (node.loading)
+            return; // a fetch for this node is already in flight
+        node.loading = true;
+        node.error = null;
+        emit();
+        const level = path.length;
+        const groupField = groupBy[level];
+        const startRow = append ? node.children.length : 0;
+        try {
+            const res = await source.getRows({
+                startRow,
+                endRow: startRow + pageSize,
+                pageIndex: Math.floor(startRow / pageSize),
+                pageSize,
+                sortModel,
+                filterModel,
+                groupBy,
+                groupKeys: path,
+                aggregations,
+            });
+            if (disposed || gen !== generation)
+                return; // stale: the tree was reset
+            node.count = res.rowCount;
+            const block = res.rows.map((data, i) => {
+                // A row is an expandable "group" when: (tree mode) the source says it has
+                // children, or (grouping mode) we are above the innermost groupBy level.
+                const isGroup = treeData ? hasChildren(data) : level < groupBy.length;
+                if (isGroup) {
+                    const gk = treeData
+                        ? getRowId(data)
+                        : ((v) => (v == null ? '' : String(v)))(data[groupField]);
+                    const aggregates = {};
+                    for (const a of aggregations)
+                        aggregates[a.col] = data[a.col];
+                    return { kind: 'group', path: [...path, gk], field: treeData ? '' : groupField, key: gk, level, aggregates, data };
+                }
+                const id = treeData && getRowId ? `${key}:${getRowId(data)}` : `${key}:${startRow + i}`;
+                return { kind: 'leaf', id, level, data };
+            });
+            node.children = append ? [...node.children, ...block] : block;
+            node.loaded = true;
+            node.loading = false;
+            emit();
+        }
+        catch (err) {
+            if (disposed || gen !== generation)
+                return;
+            node.error = err;
+            if (!append)
+                node.loaded = false;
+            node.loading = false;
+            emit();
+        }
+    }
+    // Clear the cache and reload the root plus any still-expanded paths (in
+    // parallel; flatten only descends into loaded nodes, so children appear as
+    // each level lands).
+    function resetTree() {
+        generation += 1;
+        nodes.clear();
+        void fetchNode([]);
+        for (const k of expanded)
+            void fetchNode(JSON.parse(k));
+    }
+    function expandGroup(path) {
+        const key = keyOf(path);
+        if (expanded.has(key))
+            return;
+        expanded.add(key);
+        const node = nodes.get(key);
+        if (!node?.loaded && !node?.loading)
+            void fetchNode(path);
+        else
+            emit();
+    }
+    function collapseGroup(path) {
+        if (expanded.delete(keyOf(path)))
+            emit();
+    }
+    return {
+        refresh: resetTree,
+        setSort(next) {
+            sortModel = next;
+            resetTree();
+        },
+        setFilter(next) {
+            filterModel = next;
+            resetTree();
+        },
+        setGroupBy(next) {
+            groupBy = [...next];
+            expanded.clear();
+            resetTree();
+        },
+        toggleGroup(row) {
+            if (expanded.has(row.id))
+                collapseGroup(row.path);
+            else
+                expandGroup(row.path);
+        },
+        expandGroup,
+        collapseGroup,
+        loadMoreChildren: (path) => void fetchNode(path, true),
+        isExpanded: (path) => expanded.has(keyOf(path)),
+        getState() {
+            const root = nodes.get(rootKey);
+            return {
+                displayRows: flatten(),
+                groupBy: [...groupBy],
+                loading: !!root?.loading && !root?.loaded,
+                error: root?.error ?? null,
+                sortModel,
+                filterModel,
+                expandedGroups: [...expanded],
+            };
+        },
+        dispose() {
+            disposed = true;
+            generation += 1;
+        },
+    };
+}

package/dist/toast-store.svelte.d.ts

@@ -0,0 +1,41 @@
+export type ToastVariant = 'info' | 'success' | 'warning' | 'error';
+export type ToastOptions = {
+    variant?: ToastVariant;
+    /** Auto-dismiss after N ms. `0` = sticky (dismiss manually). Default 4000. */
+    duration?: number;
+    /** Show the dismiss (x) button. Default true. */
+    dismissible?: boolean;
+    /** Optional bold title above the message. */
+    title?: string;
+};
+export type Toast = {
+    id: number;
+    message: string;
+    variant: ToastVariant;
+    duration: number;
+    dismissible: boolean;
+    title?: string;
+};
+type VariantOptions = Omit<ToastOptions, 'variant'>;
+export type ToastFn = {
+    (message: string, options?: ToastOptions): number;
+    info: (message: string, options?: VariantOptions) => number;
+    success: (message: string, options?: VariantOptions) => number;
+    warning: (message: string, options?: VariantOptions) => number;
+    error: (message: string, options?: VariantOptions) => number;
+};
+/** Live reactive list of active toasts (read inside a component/effect). */
+export declare const toastStore: {
+    readonly toasts: Toast[];
+};
+/** Show a toast. Returns its id. Has `.info/.success/.warning/.error` helpers. */
+export declare const toast: ToastFn;
+/** Dismiss a toast by id. */
+export declare const dismissToast: (id: number) => void;
+/** Remove every toast (and cancel their timers). */
+export declare const clearToasts: () => void;
+/** Pause a toast's auto-dismiss countdown (e.g. while hovered). */
+export declare const pauseToast: (id: number) => void;
+/** Resume a paused toast's countdown with the time it had left. */
+export declare const resumeToast: (id: number) => void;
+export {};

package/dist/toast-store.svelte.js

@@ -0,0 +1,113 @@
+/**
+ * toast-store - the headless model behind <SvToaster>: a singleton reactive
+ * queue of transient notifications with auto-dismiss timers, plus the `toast()`
+ * API you call from anywhere. Every toast is also pushed to the shared ARIA
+ * live region via `announce()`, so screen-reader users hear it even though the
+ * visual toast is off to the side.
+ *
+ * ```ts
+ * import { toast } from '@svgrid/grid'
+ * toast.success('Saved')
+ * toast.error('Could not save', { duration: 0 }) // sticky
+ * ```
+ *
+ * Mount a single <SvToaster /> once near the app root to render the queue.
+ */
+import { announce } from './a11y/live-region';
+function createToastStore() {
+    const toasts = $state([]);
+    const timers = new Map();
+    // Remaining ms + when the current run started, so hovering can pause/resume
+    // the auto-dismiss countdown instead of losing it.
+    const meta = new Map();
+    let seq = 0;
+    function schedule(id, ms) {
+        meta.set(id, { remaining: ms, startedAt: Date.now() });
+        timers.set(id, setTimeout(() => dismiss(id), ms));
+    }
+    /** Pause a toast's auto-dismiss (e.g. on hover), banking the time left. */
+    function pause(id) {
+        const timer = timers.get(id);
+        const m = meta.get(id);
+        if (!timer || !m)
+            return;
+        clearTimeout(timer);
+        timers.delete(id);
+        m.remaining = Math.max(0, m.remaining - (Date.now() - m.startedAt));
+    }
+    /** Resume a paused toast with the banked time remaining. */
+    function resume(id) {
+        const m = meta.get(id);
+        if (!m || timers.has(id) || m.remaining <= 0)
+            return;
+        m.startedAt = Date.now();
+        timers.set(id, setTimeout(() => dismiss(id), m.remaining));
+    }
+    function dismiss(id) {
+        const i = toasts.findIndex((t) => t.id === id);
+        if (i >= 0)
+            toasts.splice(i, 1);
+        const timer = timers.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            timers.delete(id);
+        }
+        meta.delete(id);
+    }
+    function clear() {
+        for (const timer of timers.values())
+            clearTimeout(timer);
+        timers.clear();
+        meta.clear();
+        toasts.splice(0, toasts.length);
+    }
+    function push(message, options = {}) {
+        const id = ++seq;
+        const variant = options.variant ?? 'info';
+        const duration = options.duration ?? 4000;
+        const entry = {
+            id,
+            message,
+            variant,
+            duration,
+            dismissible: options.dismissible ?? true,
+            title: options.title,
+        };
+        toasts.push(entry);
+        // Errors/warnings interrupt (assertive); info/success are polite.
+        announce(entry.title ? `${entry.title}: ${message}` : message, {
+            assertive: variant === 'error' || variant === 'warning',
+        });
+        if (duration > 0)
+            schedule(id, duration);
+        return id;
+    }
+    const toast = push;
+    toast.info = (m, o = {}) => push(m, { ...o, variant: 'info' });
+    toast.success = (m, o = {}) => push(m, { ...o, variant: 'success' });
+    toast.warning = (m, o = {}) => push(m, { ...o, variant: 'warning' });
+    toast.error = (m, o = {}) => push(m, { ...o, variant: 'error' });
+    return {
+        get toasts() {
+            return toasts;
+        },
+        toast,
+        dismiss,
+        clear,
+        pause,
+        resume,
+    };
+}
+const store = createToastStore();
+/** Live reactive list of active toasts (read inside a component/effect). */
+export const toastStore = { get toasts() { return store.toasts; } };
+/** Show a toast. Returns its id. Has `.info/.success/.warning/.error` helpers. */
+export const toast = store.toast;
+/** Dismiss a toast by id. */
+export const dismissToast = (id) => store.dismiss(id);
+/** Remove every toast (and cancel their timers). */
+export const clearToasts = () => store.clear();
+/** Pause a toast's auto-dismiss countdown (e.g. while hovered). */
+export const pauseToast = (id) => store.pause(id);
+/** Resume a paused toast's countdown with the time it had left. */
+export const resumeToast = (id) => store.resume(id);

package/dist/tree-select.d.ts

@@ -0,0 +1,19 @@
+/**
+ * tree-select - pure tree helpers behind <SvTreeSelect>: flatten the visible
+ * rows for the current expansion state (so keyboard nav is a flat index), and
+ * resolve the path from root to a value (for the trigger label). Framework-free
+ * + pure so they are unit-tested directly.
+ */
+import type { TreeSelectNode } from './ui-app.types';
+export type FlatRow = {
+    node: TreeSelectNode;
+    depth: number;
+    hasChildren: boolean;
+    expanded: boolean;
+};
+/** The rows currently visible given the `expanded` set, in display order. */
+export declare function flattenVisible(nodes: ReadonlyArray<TreeSelectNode>, expanded: ReadonlySet<string | number>, depth?: number): FlatRow[];
+/** Path of nodes from a root down to `value`, or null if not found. */
+export declare function findNodePath(nodes: ReadonlyArray<TreeSelectNode>, value: string | number): TreeSelectNode[] | null;
+/** Every value that has children (useful for "expand all"). */
+export declare function branchValues(nodes: ReadonlyArray<TreeSelectNode>): Array<string | number>;

package/dist/tree-select.js

@@ -0,0 +1,40 @@
+/** The rows currently visible given the `expanded` set, in display order. */
+export function flattenVisible(nodes, expanded, depth = 0) {
+    const rows = [];
+    for (const node of nodes) {
+        const hasChildren = !!node.children && node.children.length > 0;
+        const isExpanded = expanded.has(node.value);
+        rows.push({ node, depth, hasChildren, expanded: isExpanded });
+        if (hasChildren && isExpanded) {
+            rows.push(...flattenVisible(node.children, expanded, depth + 1));
+        }
+    }
+    return rows;
+}
+/** Path of nodes from a root down to `value`, or null if not found. */
+export function findNodePath(nodes, value) {
+    for (const node of nodes) {
+        if (node.value === value)
+            return [node];
+        if (node.children) {
+            const sub = findNodePath(node.children, value);
+            if (sub)
+                return [node, ...sub];
+        }
+    }
+    return null;
+}
+/** Every value that has children (useful for "expand all"). */
+export function branchValues(nodes) {
+    const out = [];
+    const walk = (list) => {
+        for (const n of list) {
+            if (n.children && n.children.length) {
+                out.push(n.value);
+                walk(n.children);
+            }
+        }
+    };
+    walk(nodes);
+    return out;
+}

package/dist/ui-app.types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared item shapes for the app-UI components that have no headless core
+ * (SvBreadcrumb, SvStepper). Kept in a plain .ts so they can be exported from a
+ * component's module script by re-export - a bare `export type` DECLARATION in a
+ * `<script module>` trips the Svelte/Vite parser, but a re-export is fine.
+ */
+/** One crumb in a breadcrumb trail. `href` renders a link; `onClick` a button. */
+export type BreadcrumbItem = {
+    label: string;
+    href?: string;
+    onClick?: () => void;
+    /** Optional leading icon (any string: emoji, char, or a font-icon class glyph). */
+    icon?: string;
+};
+/** One step in a stepper. */
+export type StepItem = {
+    label: string;
+    description?: string;
+    /** Marks the step skippable (shown as "Optional"). */
+    optional?: boolean;
+};
+/** One option in a multi-select. */
+export type MultiSelectOption = {
+    value: string | number;
+    label: string;
+    disabled?: boolean;
+};
+/** A node in a tree-select. */
+export type TreeSelectNode = {
+    value: string | number;
+    label: string;
+    children?: TreeSelectNode[];
+    disabled?: boolean;
+};
+/** A column shown in a grid-select dropdown. */
+export type GridSelectColumn = {
+    /** Key into each option row. */
+    field: string;
+    header: string;
+    /** Any CSS grid track size (e.g. '1fr', '80px'). Default '1fr'. */
+    width?: string;
+};
+/** One action in a command palette (SvCommand). */
+export type CommandItem = {
+    id: string;
+    label: string;
+    /** Right-aligned hint / description. */
+    hint?: string;
+    /** Section header this command groups under. */
+    group?: string;
+    /** Leading glyph (emoji / char). */
+    icon?: string;
+    /** Right-aligned keyboard shortcut hint, e.g. "⌘S". */
+    shortcut?: string;
+    /** Extra searchable terms beyond the label. */
+    keywords?: string;
+    disabled?: boolean;
+    /** Run when chosen. */
+    onRun?: () => void;
+};
+/** One step in a guided tour. */
+export type TourStep = {
+    /** Element to spotlight: a CSS selector or the element itself. Omit for a
+     *  centered, target-less step (intro / outro). */
+    target?: string | HTMLElement;
+    title?: string;
+    content: string;
+};
+/** One entry in a timeline. */
+export type TimelineItem = {
+    id?: string | number;
+    title: string;
+    description?: string;
+    /** Right-aligned timestamp/label. */
+    time?: string;
+    /** Marker colour (any CSS colour). Defaults to the accent. */
+    color?: string;
+    /** Optional leading glyph inside the marker (emoji / char). */
+    icon?: string;
+};

package/dist/ui-app.types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared item shapes for the app-UI components that have no headless core
+ * (SvBreadcrumb, SvStepper). Kept in a plain .ts so they can be exported from a
+ * component's module script by re-export - a bare `export type` DECLARATION in a
+ * `<script module>` trips the Svelte/Vite parser, but a re-export is fine.
+ */
+export {};

package/dist/validators.d.ts

@@ -0,0 +1,43 @@
+/**
+ * validators - a declarative, framework-free validation-rule library for SvForm
+ * (and any editor). Each rule builder returns a `Validator`: a pure function
+ * `(value, allValues?) => errorMessage | null`. Compose them per field; the form
+ * runs them in order and shows the first failure. Parity: Smart `smart.validator`
+ * (required / email / pattern / min / max / range / stringLength / compare ...).
+ *
+ * ```ts
+ * import { rules } from '@svgrid/grid'
+ * const field = { name: 'email', label: 'Email', rules: [rules.required(), rules.email()] }
+ * ```
+ */
+export type Validator = (value: any, values?: Record<string, any>) => string | null | undefined;
+export type RuleOptions = {
+    message?: string;
+};
+export type CompareOp = '==' | '===' | '!=' | '<' | '<=' | '>' | '>=';
+/** Empty for validation purposes: null/undefined, '', or an empty array. */
+export declare function isEmptyValue(v: any): boolean;
+/** The declarative rule builders. Every builder skips empty values (except
+ *  `required`) so optional fields validate format only when filled. */
+export declare const rules: {
+    required: (o?: RuleOptions) => Validator;
+    email: (o?: RuleOptions) => Validator;
+    url: (o?: RuleOptions) => Validator;
+    zipCode: (o?: RuleOptions) => Validator;
+    pattern: (re: RegExp, o?: RuleOptions) => Validator;
+    numeric: (o?: RuleOptions) => Validator;
+    integer: (o?: RuleOptions) => Validator;
+    min: (n: number, o?: RuleOptions) => Validator;
+    max: (n: number, o?: RuleOptions) => Validator;
+    range: (lo: number, hi: number, o?: RuleOptions) => Validator;
+    minLength: (n: number, o?: RuleOptions) => Validator;
+    maxLength: (n: number, o?: RuleOptions) => Validator;
+    stringLength: (lo: number, hi: number, o?: RuleOptions) => Validator;
+    oneOf: (allowed: ReadonlyArray<string | number>, o?: RuleOptions) => Validator;
+    /** Compare against another field's value (cross-field): e.g. confirm password. */
+    compare: (otherField: string, op?: CompareOp, o?: RuleOptions) => Validator;
+    /** Wrap an arbitrary predicate/function as a rule. */
+    custom: (fn: Validator) => Validator;
+};
+/** Run a list of rules against a value; return the first error message, or null. */
+export declare function runRules(value: any, ruleList: ReadonlyArray<Validator> | undefined, values?: Record<string, any>): string | null;

package/dist/validators.js

@@ -0,0 +1,53 @@
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+const URL_RE = /^(https?:\/\/)?([\w-]+\.)+[\w-]{2,}(\/\S*)?$/i;
+const ZIP_RE = /^\d{5}(-\d{4})?$/;
+/** Empty for validation purposes: null/undefined, '', or an empty array. */
+export function isEmptyValue(v) {
+    return v == null || v === '' || (Array.isArray(v) && v.length === 0);
+}
+function compareOk(a, b, op) {
+    switch (op) {
+        case '==': return a == b; // eslint-disable-line eqeqeq
+        case '===': return a === b;
+        case '!=': return a != b; // eslint-disable-line eqeqeq
+        case '<': return Number(a) < Number(b);
+        case '<=': return Number(a) <= Number(b);
+        case '>': return Number(a) > Number(b);
+        case '>=': return Number(a) >= Number(b);
+    }
+}
+/** The declarative rule builders. Every builder skips empty values (except
+ *  `required`) so optional fields validate format only when filled. */
+export const rules = {
+    required: (o) => (v) => isEmptyValue(v) ? o?.message ?? 'This field is required' : null,
+    email: (o) => (v) => isEmptyValue(v) || EMAIL_RE.test(String(v)) ? null : o?.message ?? 'Enter a valid email address',
+    url: (o) => (v) => isEmptyValue(v) || URL_RE.test(String(v)) ? null : o?.message ?? 'Enter a valid URL',
+    zipCode: (o) => (v) => isEmptyValue(v) || ZIP_RE.test(String(v)) ? null : o?.message ?? 'Enter a valid ZIP code',
+    pattern: (re, o) => (v) => isEmptyValue(v) || re.test(String(v)) ? null : o?.message ?? 'Invalid format',
+    numeric: (o) => (v) => isEmptyValue(v) || !isNaN(Number(v)) ? null : o?.message ?? 'Must be a number',
+    integer: (o) => (v) => isEmptyValue(v) || Number.isInteger(Number(v)) ? null : o?.message ?? 'Must be a whole number',
+    min: (n, o) => (v) => isEmptyValue(v) || Number(v) >= n ? null : o?.message ?? `Must be at least ${n}`,
+    max: (n, o) => (v) => isEmptyValue(v) || Number(v) <= n ? null : o?.message ?? `Must be at most ${n}`,
+    range: (lo, hi, o) => (v) => isEmptyValue(v) || (Number(v) >= lo && Number(v) <= hi) ? null : o?.message ?? `Must be between ${lo} and ${hi}`,
+    minLength: (n, o) => (v) => isEmptyValue(v) || String(v).length >= n ? null : o?.message ?? `Must be at least ${n} characters`,
+    maxLength: (n, o) => (v) => isEmptyValue(v) || String(v).length <= n ? null : o?.message ?? `Must be at most ${n} characters`,
+    stringLength: (lo, hi, o) => (v) => isEmptyValue(v) || (String(v).length >= lo && String(v).length <= hi)
+        ? null
+        : o?.message ?? `Must be ${lo}-${hi} characters`,
+    oneOf: (allowed, o) => (v) => isEmptyValue(v) || allowed.includes(v) ? null : o?.message ?? 'Invalid choice',
+    /** Compare against another field's value (cross-field): e.g. confirm password. */
+    compare: (otherField, op = '===', o) => (v, values) => compareOk(v, values?.[otherField], op) ? null : o?.message ?? 'Values do not match',
+    /** Wrap an arbitrary predicate/function as a rule. */
+    custom: (fn) => fn,
+};
+/** Run a list of rules against a value; return the first error message, or null. */
+export function runRules(value, ruleList, values) {
+    if (!ruleList)
+        return null;
+    for (const rule of ruleList) {
+        const err = rule(value, values);
+        if (err)
+            return err;
+    }
+    return null;
+}