sv5ui 1.5.0 → 1.6.0

package/dist/Form/form.context.svelte.d.ts

@@ -0,0 +1,64 @@
+import { SvelteSet } from 'svelte/reactivity';
+import { type FormError, type FormErrorWithId, type FormErrorEvent, type FormFieldRegistryEntry, type FormInputEvents, type FormSchema, type FormSubmitEvent, type FormValidateOpts, type NestedFormEntry } from './form.types.js';
+export declare const FORM_CONTEXT_KEY: unique symbol;
+export declare function getFormContext<T = unknown>(): FormContext<T> | undefined;
+export interface FormContextOptions<T> {
+    getState: () => T;
+    getSchema: () => FormSchema | undefined;
+    getCustomValidate: () => ((state: T) => FormError[] | Promise<FormError[]>) | undefined;
+    getValidateOn: () => FormInputEvents[];
+    getValidateOnInputDelay: () => number;
+    getDisabled: () => boolean;
+    getLoadingAuto: () => boolean;
+    getTransform: () => boolean;
+    getName: () => string | undefined;
+    getOnSubmit: () => ((event: FormSubmitEvent<unknown>) => void | Promise<void>) | undefined;
+    getOnError: () => ((event: FormErrorEvent) => void) | undefined;
+}
+export declare class FormContext<T = unknown> {
+    #private;
+    errors: FormErrorWithId[];
+    loading: boolean;
+    submitCount: number;
+    dirtyFields: SvelteSet<string>;
+    touchedFields: SvelteSet<string>;
+    blurredFields: SvelteSet<string>;
+    formId: string | number;
+    constructor(opts: FormContextOptions<T>, formId: string | number, parentCtx?: FormContext);
+    get dirty(): boolean;
+    get disabled(): boolean;
+    /**
+     * Current state. For nested forms, read the sub-tree from parent state by name.
+     * Falls back to `{}` if the parent hasn't initialized the sub-object yet —
+     * avoids crashing downstream validators when consumers forget to prefill it.
+     */
+    get state(): T;
+    getErrors(name?: string | RegExp): FormErrorWithId[];
+    setErrors(errs: FormError[], name?: string | RegExp): void;
+    clear(name?: string | RegExp): void;
+    /**
+     * Reset all form tracking state: errors, dirty/touched/blurred field sets,
+     * and submitCount. Does NOT modify `state` (caller owns that). Cascades to
+     * nested forms.
+     */
+    reset(): void;
+    registerField(name: string, entry: FormFieldRegistryEntry): void;
+    unregisterField(name: string): void;
+    attachChild(childFormId: string | number, entry: NestedFormEntry): void;
+    detachChild(childFormId: string | number): void;
+    onFocus(name: string): void;
+    onBlur(name: string): void;
+    onChange(name: string): void;
+    onInput(name: string, eager?: boolean): void;
+    validate(opts?: FormValidateOpts): Promise<T | false>;
+    /**
+     * Run full validation and fire onsubmit / onerror.
+     *
+     * @param sourceEvent - Real SubmitEvent from the `<form>` submit handler,
+     *   forwarded to the user's onsubmit / onerror so they can read `submitter`,
+     *   `preventDefault`, etc. When called programmatically (via the public API),
+     *   a fresh SubmitEvent is synthesized.
+     */
+    submit(sourceEvent?: SubmitEvent): Promise<void>;
+    dispose(): void;
+}

package/dist/Form/form.context.svelte.js

@@ -0,0 +1,478 @@
+import { getContext } from 'svelte';
+import { SvelteSet } from 'svelte/reactivity';
+import { FormValidationException } from './form.types.js';
+import { getAtPath, setAtPath, validateSchema } from './validate-schema.js';
+// ==================== CONTEXT KEY ====================
+export const FORM_CONTEXT_KEY = Symbol('sv5ui:form');
+export function getFormContext() {
+    return getContext(FORM_CONTEXT_KEY);
+}
+// ==================== HELPERS ====================
+function matchesName(errorName, target) {
+    if (!errorName)
+        return false;
+    return errorName === target || errorName.startsWith(target + '.');
+}
+function matchesTarget(errorName, target) {
+    if (!errorName)
+        return false;
+    if (target instanceof RegExp)
+        return target.test(errorName);
+    return matchesName(errorName, target);
+}
+function addFormPath(error, formPath) {
+    if (!formPath || !error.name)
+        return error;
+    return { ...error, name: `${formPath}.${error.name}` };
+}
+// ==================== FORM CONTEXT CLASS ====================
+export class FormContext {
+    // ---------- Reactive state ----------
+    errors = $state([]);
+    loading = $state(false);
+    submitCount = $state(0);
+    dirtyFields = new SvelteSet();
+    touchedFields = new SvelteSet();
+    blurredFields = new SvelteSet();
+    // ---------- Non-reactive internals ----------
+    // These maps are intentionally plain (not SvelteMap): they are private and
+    // never read from reactive contexts (templates / $derived), so reactivity
+    // would only add proxy overhead without any subscriber to notify.
+    formId;
+    #opts;
+    #parentCtx;
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #fieldRegistry = new Map();
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #nestedForms = new Map();
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #timers = new Map();
+    #transformedState = null;
+    #disposed = false;
+    /**
+     * Re-entrancy guard for submit(). Independent of `loading` because users
+     * can set `loadingAuto: false` (which keeps `loading` at `false` during
+     * an in-flight submit). Without a separate flag, rapid clicks would
+     * concurrently run the validation pipeline and double-count submitCount.
+     */
+    #submitting = false;
+    /**
+     * Cached Set view of `validateOn` for O(1) membership lookup on every
+     * event handler (onBlur / onInput / onChange / onFocus). Rebuilt lazily
+     * when the underlying array reference changes.
+     */
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #validateOnSet = new Set();
+    #validateOnRef = null;
+    constructor(opts, formId, parentCtx) {
+        this.#opts = opts;
+        this.formId = formId;
+        this.#parentCtx = parentCtx;
+    }
+    // ==================== GETTERS ====================
+    get dirty() {
+        return this.dirtyFields.size > 0;
+    }
+    get disabled() {
+        return this.#opts.getDisabled() || this.loading;
+    }
+    /**
+     * Current state. For nested forms, read the sub-tree from parent state by name.
+     * Falls back to `{}` if the parent hasn't initialized the sub-object yet —
+     * avoids crashing downstream validators when consumers forget to prefill it.
+     */
+    get state() {
+        const name = this.#opts.getName();
+        if (this.#parentCtx && name) {
+            const sub = getAtPath(this.#parentCtx.state, name);
+            return (sub ?? {});
+        }
+        return this.#opts.getState();
+    }
+    // ==================== ERROR QUERIES ====================
+    getErrors(name) {
+        if (!name)
+            return this.errors;
+        return this.errors.filter((e) => matchesTarget(e.name, name));
+    }
+    setErrors(errs, name) {
+        const resolved = this.#resolveErrorIds(errs);
+        if (!name) {
+            this.errors = resolved;
+        }
+        else {
+            const kept = this.errors.filter((e) => !matchesTarget(e.name, name));
+            this.errors = [...kept, ...resolved];
+        }
+        // Cascade to nested forms so errors set on the parent propagate to the
+        // child's own `errors` array. Each child receives only the errors whose
+        // names fall under its path, with the path prefix stripped.
+        for (const form of this.#nestedForms.values()) {
+            if (!form.name)
+                continue;
+            if (name && !matchesTarget(form.name, name))
+                continue;
+            const childErrs = errs
+                .filter((e) => e.name && matchesName(e.name, form.name))
+                .map((e) => ({
+                ...e,
+                name: e.name.slice(form.name.length + 1) || undefined
+            }));
+            form.setErrors(childErrs);
+        }
+    }
+    clear(name) {
+        if (!name) {
+            this.errors = [];
+            // Cascade to nested forms
+            for (const form of this.#nestedForms.values()) {
+                form.clear();
+            }
+            return;
+        }
+        this.errors = this.errors.filter((e) => !matchesTarget(e.name, name));
+        // Cascade to matching nested forms. Reuses `matchesTarget` where the
+        // "error name" is the child form's path — if `name` equals the path
+        // or targets a field inside the path, we clear the whole child.
+        for (const form of this.#nestedForms.values()) {
+            if (form.name && matchesTarget(form.name, name)) {
+                form.clear();
+            }
+        }
+    }
+    /**
+     * Reset all form tracking state: errors, dirty/touched/blurred field sets,
+     * and submitCount. Does NOT modify `state` (caller owns that). Cascades to
+     * nested forms.
+     */
+    reset() {
+        this.errors = [];
+        this.dirtyFields.clear();
+        this.touchedFields.clear();
+        this.blurredFields.clear();
+        this.submitCount = 0;
+        // Cascade to nested forms
+        for (const form of this.#nestedForms.values()) {
+            form.reset();
+        }
+    }
+    // ==================== FIELD REGISTRY ====================
+    registerField(name, entry) {
+        this.#fieldRegistry.set(name, entry);
+    }
+    unregisterField(name) {
+        this.#fieldRegistry.delete(name);
+    }
+    // ==================== NESTED FORMS ====================
+    attachChild(childFormId, entry) {
+        this.#nestedForms.set(childFormId, entry);
+    }
+    detachChild(childFormId) {
+        this.#nestedForms.delete(childFormId);
+    }
+    // ==================== EVENT HANDLERS ====================
+    onFocus(name) {
+        this.touchedFields.add(name);
+        if (this.#getValidateOnSet().has('focus')) {
+            void this.#validateField(name);
+        }
+    }
+    onBlur(name) {
+        this.touchedFields.add(name);
+        this.blurredFields.add(name);
+        if (this.#getValidateOnSet().has('blur')) {
+            void this.#validateField(name);
+        }
+    }
+    onChange(name) {
+        this.touchedFields.add(name);
+        this.dirtyFields.add(name);
+        if (this.#getValidateOnSet().has('change')) {
+            void this.#validateField(name);
+        }
+    }
+    onInput(name, eager = false) {
+        this.touchedFields.add(name);
+        this.dirtyFields.add(name);
+        if (!this.#getValidateOnSet().has('input'))
+            return;
+        const entryEager = this.#fieldRegistry.get(name)?.eagerValidation;
+        if (!eager && !entryEager && !this.blurredFields.has(name))
+            return;
+        this.#debounceField(name);
+    }
+    /**
+     * Returns a cached Set for validateOn lookups. Invalidates the cache when
+     * the underlying array reference from `getValidateOn()` changes, so prop
+     * updates still take effect.
+     */
+    #getValidateOnSet() {
+        const arr = this.#opts.getValidateOn();
+        if (arr !== this.#validateOnRef) {
+            this.#validateOnRef = arr;
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity
+            this.#validateOnSet = new Set(arr);
+        }
+        return this.#validateOnSet;
+    }
+    // ==================== VALIDATION CORE ====================
+    // The validation pipeline inherently has 6 sequential stages (nested → custom →
+    // schema → merge → scope → transform) mirroring Nuxt UI's Form.vue. Decomposing
+    // further would fragment the logic across helpers without reducing real complexity.
+    // eslint-disable-next-line complexity
+    async validate(opts = {}) {
+        const state = this.state;
+        const names = opts.name ? (Array.isArray(opts.name) ? opts.name : [opts.name]) : undefined;
+        // 1. Nested forms validation (when opts.nested is true). Runs in two modes:
+        //
+        //    (a) Full-form validate — `names` is undefined: every child validates
+        //        everything it owns, results contribute to `nestedResults` for
+        //        merging into the transformed state in stage 6.
+        //
+        //    (b) Field-scoped validate — `names` has values: only children whose
+        //        path is a prefix of, or equals, any requested name are called,
+        //        and they receive only the matching sub-name(s). E.g. parent
+        //        validate({ name: 'address.street', nested: true }) reaches a
+        //        child form named 'address' and calls child.validate({ name:
+        //        'street', nested: true }).
+        let nestedErrors = [];
+        const nestedResults = [];
+        if (opts.nested) {
+            for (const form of this.#nestedForms.values()) {
+                // Figure out which of the requested names belong to this child.
+                let childNames;
+                if (names) {
+                    if (!form.name)
+                        continue;
+                    const formPath = form.name;
+                    const matched = [];
+                    for (const n of names) {
+                        if (n === formPath) {
+                            // targeting whole child — pass undefined (full)
+                            matched.length = 0;
+                            matched.push('');
+                            break;
+                        }
+                        if (matchesName(n, formPath)) {
+                            matched.push(n.slice(formPath.length + 1));
+                        }
+                    }
+                    if (matched.length === 0)
+                        continue;
+                    childNames = matched[0] === '' ? undefined : matched;
+                }
+                try {
+                    const result = await form.validate({
+                        name: childNames,
+                        silent: false,
+                        nested: true,
+                        transform: opts.transform
+                    });
+                    if (result !== false) {
+                        nestedResults.push({ name: form.name, value: result });
+                    }
+                }
+                catch (err) {
+                    if (err instanceof FormValidationException) {
+                        nestedErrors = nestedErrors.concat(err.errors.map((e) => addFormPath(e, form.name)));
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+        }
+        // 2. Custom validate
+        let customErrors = [];
+        const customValidate = this.#opts.getCustomValidate();
+        if (customValidate) {
+            try {
+                const result = await customValidate(state);
+                customErrors = result ?? [];
+            }
+            catch (err) {
+                customErrors = [
+                    {
+                        message: err instanceof Error ? err.message : 'Custom validation failed'
+                    }
+                ];
+            }
+        }
+        // 3. Schema validation. Reset transformed state first — a previous
+        // successful run may have populated it, and we don't want that leaking
+        // into stage 6 if the current run fails validation.
+        let schemaErrors = [];
+        const schema = this.#opts.getSchema();
+        if (schema) {
+            this.#transformedState = null;
+            try {
+                const result = await validateSchema(state, schema);
+                if (result.errors) {
+                    schemaErrors = result.errors;
+                }
+                else {
+                    this.#transformedState = result.value ?? null;
+                }
+            }
+            catch (err) {
+                schemaErrors = [
+                    {
+                        message: err instanceof Error ? err.message : 'Schema validation failed'
+                    }
+                ];
+            }
+        }
+        else {
+            this.#transformedState = null;
+        }
+        // 4. Merge and resolve error ids
+        const allErrors = this.#resolveErrorIds([...customErrors, ...schemaErrors, ...nestedErrors]);
+        // 5. Scope by field names if requested (field-level validation)
+        if (names) {
+            const scoped = this.#filterErrorsByNames(allErrors, names);
+            const untouched = this.errors.filter((e) => !this.#matchesAnyName(e, names));
+            const scopedMatching = allErrors.filter((e) => this.#matchesAnyName(e, names));
+            this.errors = [...untouched, ...scopedMatching];
+            if (scoped.length > 0) {
+                if (opts.silent)
+                    return false;
+                throw new FormValidationException(this.formId, scoped);
+            }
+        }
+        else {
+            this.errors = allErrors;
+            if (allErrors.length > 0) {
+                if (opts.silent)
+                    return false;
+                throw new FormValidationException(this.formId, allErrors);
+            }
+        }
+        // 6. Apply transform (merge nested results into either the schema-
+        // transformed state or a shallow clone of the current state). Runs for
+        // both full-form and field-scoped validation so that a field-level
+        // validate of a nested path still produces a transformed payload.
+        if (opts.transform) {
+            const base = this.#transformedState ??
+                { ...state };
+            for (const nr of nestedResults) {
+                if (nr.name) {
+                    setAtPath(base, nr.name, nr.value);
+                }
+                else if (nr.value && typeof nr.value === 'object') {
+                    Object.assign(base, nr.value);
+                }
+            }
+            return base;
+        }
+        return state;
+    }
+    // ==================== SUBMIT ====================
+    /**
+     * Run full validation and fire onsubmit / onerror.
+     *
+     * @param sourceEvent - Real SubmitEvent from the `<form>` submit handler,
+     *   forwarded to the user's onsubmit / onerror so they can read `submitter`,
+     *   `preventDefault`, etc. When called programmatically (via the public API),
+     *   a fresh SubmitEvent is synthesized.
+     */
+    async submit(sourceEvent) {
+        // Re-entrancy guard: independent of `loading` so double-submit is blocked
+        // even when `loadingAuto: false`.
+        if (this.#submitting)
+            return;
+        this.#submitting = true;
+        this.submitCount++;
+        const loadingAuto = this.#opts.getLoadingAuto();
+        if (loadingAuto)
+            this.loading = true;
+        const event = sourceEvent ?? new SubmitEvent('submit');
+        try {
+            const data = await this.validate({
+                nested: true,
+                transform: this.#opts.getTransform()
+            });
+            if (data === false)
+                return;
+            const onsubmit = this.#opts.getOnSubmit();
+            const submitEvent = Object.assign(event, { data });
+            await onsubmit?.(submitEvent);
+            this.dirtyFields.clear();
+        }
+        catch (err) {
+            if (err instanceof FormValidationException) {
+                const onerror = this.#opts.getOnError();
+                const errorEvent = Object.assign(event, { errors: err.errors });
+                onerror?.(errorEvent);
+                return;
+            }
+            throw err;
+        }
+        finally {
+            if (loadingAuto)
+                this.loading = false;
+            this.#submitting = false;
+        }
+    }
+    // ==================== DISPOSAL ====================
+    dispose() {
+        this.#disposed = true;
+        for (const t of this.#timers.values())
+            clearTimeout(t);
+        this.#timers.clear();
+        this.#fieldRegistry.clear();
+        this.#nestedForms.clear();
+        // Clear reactive state too — handles the edge case where a consumer
+        // retains a reference to the context after component unmount.
+        this.errors = [];
+        this.loading = false;
+        this.submitCount = 0;
+        this.dirtyFields.clear();
+        this.touchedFields.clear();
+        this.blurredFields.clear();
+        this.#transformedState = null;
+        this.#submitting = false;
+    }
+    // ==================== PRIVATE: VALIDATION HELPERS ====================
+    #validateField(name) {
+        return this.validate({ name, silent: true });
+    }
+    #resolveErrorIds(errs) {
+        // Skip allocation when there's nothing to enrich — most FormErrorWithId
+        // upgrades are no-ops because the error's name isn't in the registry.
+        return errs.map((err) => {
+            if (!err.name)
+                return err;
+            const id = this.#fieldRegistry.get(err.name)?.id;
+            if (id === undefined)
+                return err;
+            return { ...err, id };
+        });
+    }
+    #matchesAnyName(error, names) {
+        if (!error.name)
+            return false;
+        for (const n of names) {
+            if (matchesName(error.name, n))
+                return true;
+            const pattern = this.#fieldRegistry.get(n)?.pattern;
+            if (pattern && pattern.test(error.name))
+                return true;
+        }
+        return false;
+    }
+    #filterErrorsByNames(all, names) {
+        return all.filter((e) => this.#matchesAnyName(e, names));
+    }
+    #debounceField(name) {
+        const delay = this.#fieldRegistry.get(name)?.validateOnInputDelay ??
+            this.#opts.getValidateOnInputDelay();
+        const existing = this.#timers.get(name);
+        if (existing)
+            clearTimeout(existing);
+        this.#timers.set(name, setTimeout(() => {
+            this.#timers.delete(name);
+            if (!this.#disposed)
+                void this.#validateField(name);
+        }, delay));
+    }
+}