entasis 0.10.2 → 0.12.0

package/dist/components/Form/Field/field.messages.js

@@ -0,0 +1,64 @@
+import { isEmptyValue } from '../../../utils/values.js';
+const override = (value, fallback) => value === undefined ? fallback : typeof value === 'string' ? () => value : value;
+/**
+ * The catalog messages for one field type, with the entry's overrides applied. A checkbox or
+ * switch is "required" when it must be on, a PinInput that is too short is incomplete, and a
+ * password uses the password wording.
+ */
+export const resolveFieldMessages = (t, type, overrides = {}) => {
+    const required = type === 'checkbox'
+        ? t.fieldMustBeChecked
+        : type === 'switch'
+            ? t.fieldMustBeOn
+            : t.fieldRequired;
+    const incomplete = override(overrides.incomplete, t.fieldIncomplete);
+    const defaultTooShort = type === 'password' ? t.passwordTooShort : type === 'pin' ? incomplete : t.fieldTooShort;
+    return {
+        required: overrides.required ?? required,
+        invalid: overrides.invalid ?? t.fieldInvalid,
+        email: overrides.email ?? t.fieldInvalidEmail,
+        url: overrides.url ?? t.fieldInvalidUrl,
+        tooShort: override(overrides.tooShort, defaultTooShort),
+        tooLong: override(overrides.tooLong, t.fieldTooLong),
+        rangeUnderflow: override(overrides.rangeUnderflow, t.fieldRangeUnderflow),
+        rangeOverflow: override(overrides.rangeOverflow, t.fieldRangeOverflow),
+        incomplete
+    };
+};
+const formatRequirement = (requirement, locale) => {
+    if (typeof requirement === 'number')
+        return requirement;
+    if (requirement instanceof Date)
+        return requirement.toLocaleDateString(locale);
+    return String(requirement);
+};
+/**
+ * Turns one validation issue into the catalog message for what failed. A missing value (a type
+ * mismatch on `null`, an empty string or array) reads as required; anything unrecognised reads as
+ * invalid, so library wording never reaches the user.
+ */
+export const describeFieldIssue = (issue, messages, locale = 'en') => {
+    switch (issue.type) {
+        case 'non_empty':
+            return messages.required;
+        case 'email':
+            return messages.email;
+        case 'url':
+            return messages.url;
+        case 'min_length':
+            return typeof issue.input === 'string'
+                ? messages.tooShort(Number(issue.requirement))
+                : messages.required;
+        case 'max_length':
+            return typeof issue.input === 'string'
+                ? messages.tooLong(Number(issue.requirement))
+                : messages.invalid;
+        case 'min_value':
+            return messages.rangeUnderflow(formatRequirement(issue.requirement, locale));
+        case 'max_value':
+            return messages.rangeOverflow(formatRequirement(issue.requirement, locale));
+    }
+    return issue.kind === 'schema' && isEmptyValue(issue.input)
+        ? messages.required
+        : messages.invalid;
+};

package/dist/components/Form/Field/field.state.svelte.d.ts

@@ -1,94 +1,171 @@
-import type { FieldValue, InputType } from './field.js';
+import type { FieldType, FieldValue } from './field.js';
 import * as v from 'valibot';
 import type { Attachment } from 'svelte/attachments';
 import type { FormState } from '../Form/form.state.svelte.js';
 import type { Density, Sizes } from '../../../types/theme.js';
+import { type FieldMessageOverrides, type FieldMessages } from './field.messages.js';
 export type FieldValidationResult = string | string[] | boolean | null | undefined;
-type FieldStateStaticOptions<T extends InputType> = {
+/** What `onValidate` may return: a result now, or a promise of one. */
+export type FieldValidatorResult = FieldValidationResult | Promise<FieldValidationResult>;
+/**
+ * When a field validates on its own, besides a submit: `'submit'` waits for the first submit
+ * attempt (edited fields then re-validate on every change), `'blur'` validates when focus
+ * leaves the field, `'change'` validates on every accepted change.
+ */
+export type ValidationMode = 'submit' | 'blur' | 'change';
+type FieldStateStaticOptions<T extends FieldType> = {
     type: T;
     name?: string;
     required?: boolean;
     disabled?: boolean;
+    /** Refuses user edits while the control stays focusable, validated and submitted. */
+    readOnly?: boolean;
     size?: Sizes;
     density?: Density;
     visible?: boolean;
-    onValidate?: (value: FieldValue<T>) => FieldValidationResult;
+    /** Per-field overrides for the catalog validation messages. */
+    messages?: FieldMessageOverrides;
+    /** Minimum length of a text value; a shorter, non-empty value reports `tooShort`. */
+    minLength?: number;
+    /** Maximum length of a text value; a longer value reports `tooLong`. */
+    maxLength?: number;
+    onValidate?: (value: FieldValue<T>) => FieldValidatorResult;
+    /** Overrides the Form's `validationMode` for this field. */
+    validationMode?: ValidationMode;
+    /** Milliseconds a change waits before the validation it triggers runs; submits do not wait. */
+    validationDebounce?: number;
     onValueChange?: (value: FieldValue<T> | null) => void;
     id: string;
 };
-type FieldStateBindableOptions<T extends InputType> = {
+type FieldStateBindableOptions<T extends FieldType> = {
     value?: FieldValue<T> | null;
     errors: string[] | boolean;
     focused: boolean;
 };
-export type FieldState<T extends InputType> = ReturnType<typeof createFieldState<T>>;
+export type FieldState<T extends FieldType> = ReturnType<typeof createFieldState<T>>;
 export type FieldControlAttributes = {
     id: string;
     name: string;
     disabled: boolean | undefined;
     required: boolean | undefined;
+    readonly: boolean | undefined;
     'aria-invalid': 'true' | undefined;
     'aria-describedby': string | undefined;
 };
-export declare const createFieldState: <T extends InputType>(options: FieldStateBindableOptions<T> & FieldStateStaticOptions<T>) => {
+/** The disabled and read-only state a group (a Form, a FormGroup, a fieldset Field) hands down. */
+export type FieldGroupState = {
+    readonly disabled: boolean;
+    readonly readOnly: boolean;
+};
+/**
+ * Makes every field created below the calling component disabled or read-only while the group is.
+ * Nested groups combine: a field is disabled when it, or any group around it, is. Call during
+ * component initialisation.
+ */
+export declare const provideFieldGroup: (own: {
+    readonly disabled?: boolean;
+    readonly readOnly?: boolean;
+}) => FieldGroupState;
+export declare const createFieldState: <T extends FieldType>(options: FieldStateBindableOptions<T> & FieldStateStaticOptions<T>) => {
     name: string;
     size: Sizes;
     density: Density;
+    disabled: boolean;
+    readOnly: boolean;
+    messages: FieldMessages;
     form?: FormState;
     node: HTMLElement | null;
     rootNode: HTMLElement | null;
     labelId: string;
     errorId: string;
+    /** Id Field gives the rendered description, referenced from the control's `aria-describedby`. */
+    descriptionId: string;
+    /** Id Field gives the rendered helper text, referenced from the control's `aria-describedby`. */
+    helperId: string;
+    /** Messages from validation (and from `errors`), without those an app set from outside. */
+    validationMessages: string[];
+    /** Every message shown: validation errors first, then the ones set from outside. */
     errorMessages: string[];
     hasError: boolean;
+    /** Validation failed. Unlike `hasError`, errors set from outside do not count. */
+    hasValidationError: boolean;
+    /** True once focus has left the field after entering it (popups the field opened included). */
+    touched: boolean;
+    /** The value differs from the initial one; empty values (`null`, `''`, `[]`) count as equal. */
+    dirty: boolean;
+    /** The field holds a value: text, a selection, a file; for a checkbox or switch, on. */
+    filled: boolean;
+    /** Description, helper and error ids for the control's `aria-describedby`, errors last. */
+    describedBy: string[];
     control: Attachment<HTMLElement>;
+    /** @internal Field attaches this to the rendered description. */
+    descriptionPart: Attachment<HTMLElement>;
+    /** @internal Field attaches this to the rendered helper text. */
+    helperPart: Attachment<HTMLElement>;
     get controlAttrs(): FieldControlAttributes;
+    /** True while an async `onValidate` is pending; the field is neither valid nor invalid then. */
+    get validating(): boolean;
+    /** Errors an app set from outside; they clear on the field's next accepted change. */
+    get externalErrors(): string[];
+    /** When this field validates by itself: its own mode, else its Field's, else the Form's. */
+    get activeValidationMode(): ValidationMode;
+    /** Milliseconds a change waits before the validation it triggers. */
+    get activeValidationDebounce(): number;
+    /** @internal Field forwards the validation timing its props declare. */
+    configureValidation: (timing: {
+        mode?: ValidationMode;
+        debounce?: number;
+    }) => void;
+    /** The value the field started with, the baseline for `dirty`; reset re-captures it. */
+    get initialValue(): FieldValue<T> | null | undefined;
     /** Updates the control value and publishes one callback for an accepted change. */
     setValue: (nextValue: FieldValue<T> | null | undefined) => void;
     /** @internal Applies parent/Form state without echoing a control change callback. */
     syncValue: (nextValue: FieldValue<T> | null | undefined) => void;
-    checkSchema(value?: FieldValue<T> | null | undefined): v.SafeParseResult<{
-        number: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        select: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        color: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        date: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        file: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        files: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        "slider-range": v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        datetime: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        slider: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        rating: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        voice: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        time: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        text: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        password: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        email: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        url: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        textarea: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        phone: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        "rich-text": v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        switch: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        checkbox: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        checkboxes: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        tag: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        "tag-group": v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        keyvalue: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        pin: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        radio: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        combobox: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        calendar: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-        "calendar-range": v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
-    }[T]>;
+    /**
+     * Restores a value, the initial one by default, as the new untouched baseline: no value
+     * callback, no errors, not dirty, not touched.
+     */
+    reset: (nextValue?: FieldValue<T> | null | undefined) => void;
+    /**
+     * Shows errors an app set from outside, a server response say, next to the validation
+     * ones. They stay through validation and clear on the next accepted change of the value.
+     */
+    setExternalErrors: (messages: string | string[] | null | undefined) => void;
+    /** Removes the errors an app set from outside. */
+    clearExternalErrors: () => void;
+    /** Resolves once no async validator is in flight. */
+    settle: () => Promise<void>;
+    /** Validates, and waits for async validators. Resolves to `[hasError, parsedValue]`. */
+    validateAsync: (value?: FieldValue<T> | null | undefined) => Promise<readonly [boolean, unknown]>;
+    /**
+     * Moves focus to the control without activating it, as clicking a label does: a Switch is
+     * not toggled, a Select does not open. Returns whether something took focus.
+     */
+    focusControl: () => boolean;
+    /** The registered definition behind an app-defined input type, if this field has one. */
+    get definition(): import("../Form/form.registry.js").RegisteredFormInputDefinition | undefined;
+    checkSchema(value?: FieldValue<T> | null | undefined): v.SafeParseResult<v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>;
     get isValid(): boolean;
+    /** Validates a value, writes the errors, and remembers the locale they were written in. */
     validate: (value?: FieldValue<T> | null | undefined) => readonly [boolean, unknown];
+    /** @internal The validation `validate` wraps. */
+    runValidation: (value: FieldValue<T> | null | undefined) => readonly [boolean, unknown];
     value?: FieldValue<T> | null | undefined;
     errors: string[] | boolean;
     focused: boolean;
     type: T;
     required?: boolean;
-    disabled?: boolean;
     visible?: boolean;
-    onValidate?: ((value: FieldValue<T>) => FieldValidationResult) | undefined;
+    /** Minimum length of a text value; a shorter, non-empty value reports `tooShort`. */
+    minLength?: number;
+    /** Maximum length of a text value; a longer value reports `tooLong`. */
+    maxLength?: number;
+    onValidate?: ((value: FieldValue<T>) => FieldValidatorResult) | undefined;
+    /** Overrides the Form's `validationMode` for this field. */
+    validationMode?: ValidationMode;
+    /** Milliseconds a change waits before the validation it triggers runs; submits do not wait. */
+    validationDebounce?: number;
     onValueChange?: ((value: FieldValue<T> | null) => void) | undefined;
     id: string;
 };