entasis 0.11.0 → 0.12.0

package/dist/components/Form/Form/form.state.svelte.js

@@ -1,9 +1,10 @@
-import { setContext, untrack } from 'svelte';
+import { setContext, tick, untrack } from 'svelte';
 import { on } from 'svelte/events';
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import { flattenFormInputs, getFormValueInputType } from './form.js';
 import { getFormInputDefinition } from './form.registry.js';
 import { isFieldVisible } from './visibility.js';
+const toMessages = (messages) => (Array.isArray(messages) ? messages : messages ? [messages] : []).filter((message) => typeof message === 'string' && message !== '');
 const focusableControl = 'input:not([disabled]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"]), [contenteditable="true"]';
 const enterNavigationInputTypes = new Set([
     'text',
@@ -46,6 +47,7 @@ const supportedInputTypes = new Set([
     'keyvalue',
     'pin',
     'select',
+    'select-multiple',
     'radio',
     'combobox',
     'calendar',
@@ -67,11 +69,58 @@ export class FormState {
     valueCache = $state({});
     configuredValues = new SvelteMap();
     defaultValues = new SvelteMap();
+    initialValues = new SvelteMap();
     publishedValue;
     submitPromise = null;
+    // Server errors by field name, kept for fields that register after they were set.
+    externalErrors = new SvelteMap();
+    revealAfterSubmit = false;
+    revealFieldAfterSubmit = null;
+    /** How many times the form was validated to submit; fields re-validate on edit after the first. */
+    submitCount = $state(0);
     value = $derived.by(() => this.getVisibleValue());
+    /** When fields validate by themselves; a field's own `validationMode` takes precedence. */
+    get validationMode() {
+        return this.options.validationMode ?? 'submit';
+    }
+    /** Milliseconds an edit waits before the validation it triggers; a field's own value wins. */
+    get validationDebounce() {
+        return this.options.validationDebounce ?? 0;
+    }
+    /** True when any field differs from its initial value. */
+    get dirty() {
+        for (const field of this.fields.values())
+            if (field.dirty)
+                return true;
+        return false;
+    }
+    /** True when focus has entered and left any field. */
+    get touched() {
+        for (const field of this.fields.values())
+            if (field.touched)
+                return true;
+        return false;
+    }
+    /** True while an async validator of any field is pending. */
+    get validating() {
+        for (const field of this.fields.values())
+            if (field.validating)
+                return true;
+        return false;
+    }
     constructor(options) {
         this.options = options;
+        let appliedErrors = false;
+        $effect(() => {
+            const errors = this.options.errors;
+            untrack(() => {
+                // Mounting with errors shows them without taking focus; later ones reveal the first.
+                if (errors === undefined && !appliedErrors)
+                    return;
+                this.applyExternalErrors(errors, appliedErrors);
+                appliedErrors = true;
+            });
+        });
         $effect(() => {
             const inputs = this.options.inputs;
             const externalValue = this.options.value;
@@ -109,9 +158,14 @@ export class FormState {
         }
         const registeredField = field;
         this.fields.set(field.name, registeredField);
+        const serverErrors = this.externalErrors.get(field.name);
+        if (serverErrors)
+            field.setExternalErrors(serverErrors);
         return () => {
             if (this.fields.get(field.name) !== registeredField)
                 return;
+            if (field.initialValue !== undefined)
+                this.initialValues.set(field.name, field.initialValue);
             if (this.getFieldDefinition(field.name))
                 this.setCachedValue(field.name, field.value);
             else
@@ -141,8 +195,25 @@ export class FormState {
         if (currentIndex === -1)
             return;
         event.preventDefault();
-        const lastFieldIndex = navigableFields.length - 1;
-        if (currentIndex === lastFieldIndex) {
+        this.advance(navigableFields, currentIndex);
+    };
+    /**
+     * Moves on from `field` as Enter does in a text field: the last navigable field submits the
+     * form; any other field validates and, when valid, hands focus to the next field, or keeps it
+     * while invalid. Controls that do not reach Form's Enter handling (checkboxes, radios) call it
+     * from their own Enter key. Returns false when `field` is not a visible, enabled field of this
+     * form, so the caller can fall back to the native behaviour.
+     */
+    advanceFrom = (field) => {
+        const navigableFields = this.getNavigableFields();
+        const currentIndex = navigableFields.findIndex((entry) => entry.field === field);
+        if (currentIndex === -1)
+            return false;
+        this.advance(navigableFields, currentIndex);
+        return true;
+    };
+    advance(navigableFields, currentIndex) {
+        if (currentIndex === navigableFields.length - 1) {
             void this.submit();
             return;
         }
@@ -152,8 +223,18 @@ export class FormState {
             currentField.focusTarget.focus();
             return;
         }
-        navigableFields[currentIndex + 1]?.focusTarget.focus();
-    };
+        const moveOn = () => {
+            if (currentField.field.hasValidationError)
+                currentField.focusTarget.focus();
+            else
+                navigableFields[currentIndex + 1]?.focusTarget.focus();
+        };
+        // An async validator decides before focus moves on.
+        if (currentField.field.validating)
+            void currentField.field.settle().then(moveOn);
+        else
+            moveOn();
+    }
     isInputVisible(name) {
         return this.getActiveFieldDefinitions().some((field) => field.name === name);
     }
@@ -163,37 +244,241 @@ export class FormState {
     isGroupVisible(group) {
         return isFieldVisible(group, this.valueCache);
     }
-    validate = () => {
-        let firstErroredField = null;
-        const validatedValue = {};
+    /**
+     * Validates every visible, enabled field synchronously and returns the validated value, or
+     * false after revealing the first invalid field. Disabled fields are skipped and left out of
+     * the value. It does not wait for async validators: use `validateAsync` or `submit` for those.
+     */
+    validate = (options = {}) => {
+        const reveal = options.reveal !== false;
+        if (reveal)
+            this.submitCount += 1;
+        const pass = this.collect();
+        if (pass.firstErrored)
+            return this.fail(pass.firstErrored, reveal);
+        this.hasError = false;
+        return pass.value;
+    };
+    /** Like `validate`, and waits for the async validators of every field to settle. */
+    validateAsync = async (options = {}) => this.validateStaged(options);
+    /**
+     * @internal `validate` that returns a promise only when an async validator is pending, for
+     * callers that must keep their synchronous timing otherwise.
+     */
+    validateStaged = (options = {}) => {
+        const reveal = options.reveal !== false;
+        if (reveal)
+            this.submitCount += 1;
+        return this.stage(reveal);
+    };
+    /**
+     * Validates one field now and returns whether it is valid. A field that is not a visible
+     * field of this form reads as invalid; a disabled one skips validation and reads as valid.
+     * A field whose async validator is still running reads as invalid: use `validateAsync` to wait.
+     * It neither scrolls nor focuses, and does not count as a submit attempt.
+     */
+    validateField = (name) => {
+        const field = this.fields.get(name);
+        if (!field || !this.isInputVisible(name))
+            return false;
+        const [hasError] = field.validate();
+        // A pending async validator has not accepted the value yet.
+        return !hasError && !field.validating;
+    };
+    submit = () => {
+        if (this.submitPromise)
+            return this.submitPromise;
+        this.submitCount += 1;
+        const staged = this.stage(true);
+        if (!(staged instanceof Promise)) {
+            if (staged === false)
+                return Promise.resolve(false);
+            this.submitPromise = this.submitValidatedValue(staged);
+            return this.submitPromise;
+        }
+        // Async validators are pending: the form is busy until they settle and the handler ran.
+        this.submitPromise = (async () => {
+            this.loading = true;
+            try {
+                const value = await staged;
+                if (value === false)
+                    return false;
+                return await this.submitValidatedValue(value);
+            }
+            finally {
+                this.loading = false;
+                this.submitPromise = null;
+                const invalid = this.revealFieldAfterSubmit;
+                this.revealFieldAfterSubmit = null;
+                if (invalid)
+                    void tick().then(() => this.revealField(invalid));
+            }
+        })();
+        return this.submitPromise;
+    };
+    /**
+     * Shows errors from outside the form, a server response say, under their fields. They replace
+     * the errors set before, survive validation and clear when the field's value next changes.
+     * Keys are field names; a value is a message or a list of them. Reveals the first field in
+     * render order that has one.
+     */
+    setErrors(errors) {
+        this.applyExternalErrors(errors, true);
+    }
+    /**
+     * Restores every field to its initial value, or to `value` where it gives one, and makes that
+     * the new baseline: errors, touched, dirty and the submit count clear, and fields do not
+     * report the change as an edit. The form's `onValueChange` runs once if the visible value
+     * changed.
+     */
+    reset(value) {
+        const previousValue = this.value;
+        const given = value;
+        const nextCache = { ...this.valueCache };
+        const restored = [];
+        for (const { name } of flattenFormInputs(this.options.inputs)) {
+            const field = this.fields.get(name);
+            let next;
+            if (given && hasOwn(given, name)) {
+                next = given[name];
+                this.initialValues.set(name, next);
+                this.defaultValues.set(name, next);
+            }
+            else if (field && field.initialValue !== undefined) {
+                next = field.initialValue;
+            }
+            else if (this.initialValues.has(name)) {
+                next = this.initialValues.get(name);
+            }
+            else if (this.defaultValues.has(name)) {
+                next = this.defaultValues.get(name);
+            }
+            else {
+                continue;
+            }
+            nextCache[name] = next;
+            if (field)
+                restored.push([field, next]);
+        }
+        this.externalErrors.clear();
+        this.revealAfterSubmit = false;
+        this.valueCache = nextCache;
+        for (const [field, next] of restored)
+            field.reset(next);
+        this.submitCount = 0;
+        this.hasError = false;
+        const nextValue = this.value;
+        if (areValuesEqual(previousValue, nextValue))
+            return;
+        this.publishedValue = nextValue;
+        this.options.value = nextValue;
+        this.options.onValueChange?.(nextValue);
+    }
+    /** @internal A field whose value changed drops its server errors from the form's record. */
+    forgetExternalErrors(name) {
+        this.externalErrors.delete(name);
+    }
+    applyExternalErrors(errors, reveal) {
+        const next = new SvelteMap();
+        for (const [name, messages] of Object.entries(errors ?? {})) {
+            const list = toMessages(messages);
+            if (list.length > 0)
+                next.set(name, list);
+        }
+        this.externalErrors = next;
+        for (const field of this.fields.values())
+            field.setExternalErrors(next.get(field.name));
+        if (next.size === 0)
+            return;
+        this.hasError = true;
+        if (!reveal)
+            return;
+        // A form that disables itself while submitting cannot focus yet: reveal once it is done.
+        if (this.loading)
+            this.revealAfterSubmit = true;
+        else
+            this.revealExternalErrors();
+    }
+    revealExternalErrors() {
+        for (const definition of this.getActiveFieldDefinitions()) {
+            const field = this.fields.get(definition.name);
+            if (field && field.externalErrors.length > 0 && !field.disabled) {
+                this.revealField(field);
+                return;
+            }
+        }
+    }
+    // One validation pass, in render order: disabled fields are skipped, as in a native form.
+    collect() {
+        const pass = { value: {}, firstErrored: null, validating: [], snapshot: [] };
         for (const definition of this.getActiveFieldDefinitions()) {
             const field = this.fields.get(definition.name);
             if (!field) {
                 throw new Error(`Form field "${definition.name}" is visible but not registered.`);
             }
+            if (field.disabled)
+                continue;
+            pass.snapshot.push([field, field.value]);
             const [hasFieldError, parsedValue] = field.validate();
             if (hasFieldError) {
-                firstErroredField ??= field;
+                pass.firstErrored ??= field;
                 continue;
             }
-            validatedValue[definition.name] = parsedValue;
+            if (field.validating)
+                pass.validating.push(field);
+            pass.value[definition.name] = parsedValue;
         }
-        this.hasError = firstErroredField !== null;
-        if (firstErroredField) {
-            this.revealField(firstErroredField);
-            return false;
+        return pass;
+    }
+    fail(field, reveal) {
+        this.hasError = true;
+        // A form that disables itself while submitting cannot focus yet: reveal once it is done.
+        if (reveal && this.loading && field.disabled)
+            this.revealFieldAfterSubmit = field;
+        else if (reveal)
+            this.revealField(field);
+        return false;
+    }
+    // The fields the pass validated, in render order: a form that disables itself while it
+    // submits must still honour what their validators decided.
+    firstInvalidField(pass) {
+        for (const [field] of pass.snapshot) {
+            if (field.hasValidationError)
+                return field;
         }
-        return validatedValue;
-    };
-    submit = () => {
-        if (this.submitPromise)
-            return this.submitPromise;
-        const validatedValue = this.validate();
-        if (validatedValue === false)
-            return Promise.resolve(false);
-        this.submitPromise = this.submitValidatedValue(validatedValue);
-        return this.submitPromise;
-    };
+        return null;
+    }
+    // A validation pass that returns at once when no async validator is pending, so a plain form
+    // keeps validating and submitting synchronously.
+    stage(reveal, attempt = 0) {
+        const pass = this.collect();
+        if (pass.firstErrored) {
+            // An async field that renders before the sync error may still turn out invalid: it
+            // leads, so focus waits for its result.
+            const order = pass.snapshot.map(([field]) => field);
+            const errorIndex = order.indexOf(pass.firstErrored);
+            const earlier = pass.validating.filter((field) => order.indexOf(field) < errorIndex);
+            if (earlier.length === 0)
+                return this.fail(pass.firstErrored, reveal);
+            const firstErrored = pass.firstErrored;
+            return Promise.all(earlier.map((field) => field.settle())).then(() => this.fail(this.firstInvalidField(pass) ?? firstErrored, reveal));
+        }
+        if (pass.validating.length === 0) {
+            this.hasError = false;
+            return pass.value;
+        }
+        return Promise.all(pass.validating.map((field) => field.settle())).then(() => {
+            const invalid = this.firstInvalidField(pass);
+            if (invalid)
+                return this.fail(invalid, reveal);
+            // A field edited while the validators ran is validated again before the value is used.
+            const edited = pass.snapshot.some(([field, value]) => !Object.is(field.value, value));
+            if (edited && attempt < 2)
+                return this.stage(reveal, attempt + 1);
+            this.hasError = false;
+            return pass.value;
+        });
+    }
     async submitValidatedValue(validatedValue) {
         this.loading = true;
         try {
@@ -203,6 +488,10 @@ export class FormState {
         finally {
             this.loading = false;
             this.submitPromise = null;
+            if (this.revealAfterSubmit) {
+                this.revealAfterSubmit = false;
+                void tick().then(() => this.revealExternalErrors());
+            }
         }
     }
     reconcileInputs(inputs, externalValue, isExternalUpdate) {
@@ -375,7 +664,11 @@ export class FormState {
         return navigableFields;
     }
     getFieldFocusTarget(field) {
-        return field.node ?? field.rootNode?.querySelector(focusableControl) ?? null;
+        // A roving group (radios) has one Tab stop, the checked option, which is where focus belongs.
+        return (field.node ??
+            field.rootNode?.querySelector('[role="radio"][tabindex="0"]:not([disabled])') ??
+            field.rootNode?.querySelector(focusableControl) ??
+            null);
     }
     isEnterNavigationEvent(event) {
         if (event.key !== 'Enter' ||

package/dist/components/Form/Form/index.d.ts

@@ -3,7 +3,9 @@ export { Ask, ask } from '../Ask/index.js';
 export type { AskButton, AskDialogOptions, AskOptions, AskProps, AskResult } from '../Ask/index.js';
 export type { FormLayout, FormProps, FormVariant } from './form.props.js';
 export { FormState } from './form.state.svelte.js';
+export type { FormValidateOptions } from './form.state.svelte.js';
+export type { ValidationMode } from '../Field/field.state.svelte.js';
 export { registerFormInputs, type FormInputDefinitions } from './form.registry.js';
 export type { FieldLabelPosition } from '../Field/field.js';
 export { formTheme, setFormTheme, useFormTheme, type FormTheme, type FormThemeProps } from './form.theme.js';
-export type { FormInput, FormAction, FormActionInput, FormCustomInput, FormInputAction, FormInputState, FormFieldController, FormFieldInput, FormFieldEntry, FormInputComponentProps, FormInputDefinition, FormInputRegistry, FormRegisteredInput, FormGroup, FormGroupColumns, FormGroupInputs, FormInputsWithState, FormInputs, FormRenderableInput, FormValueInput, FlattenFormInputs, InferFormValue, LiveFormValue, FormSubmitHandler, MaybePromise } from './form.js';
+export type { FormInput, FormAction, FormActionInput, FormCustomInput, FormInputAction, FormInputState, FormFieldController, FormFieldInput, FormFieldEntry, FormInputComponentProps, FormInputDefinition, FormInputRegistry, FormRegisteredInput, FormGroup, FormGroupColumns, FormGroupInputs, FormErrors, FormInputsWithState, FormInputs, FormRenderableInput, FormValueInput, FlattenFormInputs, InferFormValue, LiveFormValue, FormSubmitHandler, MaybePromise } from './form.js';