entasis 0.10.2 → 0.12.0

package/dist/components/Form/Field/FieldHiddenInputs.svelte

@@ -0,0 +1,187 @@
+<script lang="ts" generics="T extends FieldType">
+	import { DEV } from 'esm-env';
+	import { tick } from 'svelte';
+	import type { Attachment } from 'svelte/attachments';
+	import { useI18n } from '../../../i18n/context.svelte.js';
+	import { getFirstTabbable } from '../../../utils/focus.js';
+	import { createListFilter } from '../../../utils/listFilter.js';
+	import type { FieldType, FieldValue } from './field.js';
+	import { getFieldFormAttribute } from './fieldNativeForm.svelte.js';
+	import type { FieldHiddenInputsProps } from './fieldHiddenInputs.props.js';
+
+	let {
+		field,
+		value,
+		checked,
+		name,
+		required,
+		disabled,
+		form,
+		id,
+		autocomplete,
+		options,
+		onAutofill,
+		readOnly
+	}: FieldHiddenInputsProps<T> = $props();
+
+	const t = $derived(useI18n());
+
+	// FieldState names an unnamed field `${type}-input-${id}` so Form wiring stays unique. Only a
+	// name the app gave, directly or through Form, is submitted, as for a native control.
+	const submittedName = $derived(
+		name ?? (field.name === `${field.type}-input-${field.id}` ? undefined : field.name)
+	);
+	const isRequired = $derived(Boolean(required ?? field.required));
+	const isDisabled = $derived(Boolean(disabled ?? field.disabled));
+	const isReadOnly = $derived(Boolean(readOnly ?? field.readOnly));
+	const formId = $derived(form ?? getFieldFormAttribute(field));
+	const reportId = $derived(id ?? `${field.id}-input`);
+	const values = $derived(
+		(Array.isArray(value) ? value : value == null ? [] : [value]).map((entry) => String(entry))
+	);
+	const mode = $derived(
+		checked !== undefined ? 'checked' : autocomplete ? 'autofill' : ('values' as const)
+	);
+	const isEmpty = $derived(mode === 'checked' ? !checked : values.every((entry) => entry === ''));
+	// What the browser treats as a missing value, and so a blocked submit.
+	const isMissing = $derived(isRequired && !isDisabled && isEmpty);
+
+	const focusControl = () => {
+		const control = field.node?.isConnected ? field.node : null;
+		(control ?? (field.rootNode && getFirstTabbable(field.rootNode)))?.focus();
+	};
+
+	// A blocked native submit (or reportValidity) focuses the first invalid control. When that is
+	// one of these inputs, the report belongs to the field: it shows its own error and its control
+	// takes focus. Firefox hides its bubble when the reported input loses focus, which only works
+	// once its focus has settled, so the hand-off waits a task. A silent checkValidity() focuses
+	// nothing, so it changes nothing here.
+	const handOffReport = (event: FocusEvent & { currentTarget: HTMLInputElement }) => {
+		const input = event.currentTarget;
+		field.validate();
+		setTimeout(() => {
+			if (input.ownerDocument.activeElement === input) focusControl();
+		});
+	};
+
+	// While a value is missing, the reportable input also carries a blank custom error. Chromium
+	// and WebKit trim the message before showing their bubble, so a blank one shows nothing over
+	// the field's own error, and the constraint never lapses: every submit stays blocked.
+	const blankNativeReport: Attachment<HTMLInputElement> = (input) => {
+		input.setCustomValidity(isMissing ? ' ' : '');
+	};
+
+	// The inputs sit beside the control: a button may not contain interactive content, and a
+	// click on an input inside it reaches the button as a second activation.
+	const besideControl: Attachment<HTMLInputElement> = (input) => {
+		if (DEV && input.parentElement?.closest('button')) {
+			console.warn(
+				'FieldHiddenInputs is rendered inside a <button>. Render it beside the control instead.'
+			);
+		}
+	};
+
+	// The checkbox only mirrors the field: a change that reaches it directly is undone.
+	const keepChecked = (event: Event & { currentTarget: HTMLInputElement }) => {
+		event.currentTarget.checked = Boolean(checked);
+	};
+
+	const matchOption = (text: string): string | undefined => {
+		if (!options) return text;
+		const byValue = options.find((option) => option.value === text);
+		if (byValue) return byValue.value;
+		const byLabel = options.find((option) => option.label === text);
+		if (byLabel) return byLabel.value;
+		const filter = createListFilter({ locale: t.locale });
+		return options.find((option) => option.label !== undefined && filter.equals(option.label, text))
+			?.value;
+	};
+
+	// The browser fills the text it knows (often a label such as "Canada"); it becomes the field's
+	// value only when it names an option. Afterwards the input shows the field's value again,
+	// whatever was typed into it.
+	const applyAutofill = async (event: Event & { currentTarget: HTMLInputElement }) => {
+		const input = event.currentTarget;
+		const text = input.value.trim();
+		if (text && text !== values[0] && !isDisabled && !isReadOnly) {
+			const match = matchOption(text);
+			if (match !== undefined) {
+				if (onAutofill) onAutofill(match);
+				// Autofill is offered to single-value text fields, whose value is the option value.
+				else field.setValue(match as FieldValue<T>);
+			}
+		}
+		await tick();
+		input.value = values[0] ?? '';
+	};
+</script>
+
+{#if mode === 'checked'}
+	<input
+		type="checkbox"
+		id={reportId}
+		name={submittedName}
+		value={values[0] ?? 'on'}
+		{checked}
+		required={isRequired}
+		disabled={isDisabled}
+		form={formId}
+		tabindex={-1}
+		aria-hidden="true"
+		class="sr-only"
+		data-field-hidden-input=""
+		onchange={keepChecked}
+		onfocus={handOffReport}
+		{@attach blankNativeReport}
+		{@attach besideControl}
+	/>
+{:else if mode === 'autofill'}
+	<input
+		type="text"
+		id={reportId}
+		name={submittedName}
+		value={values[0] ?? ''}
+		{autocomplete}
+		required={isRequired}
+		disabled={isDisabled}
+		form={formId}
+		tabindex={-1}
+		aria-hidden="true"
+		class="sr-only"
+		data-field-hidden-input=""
+		oninput={applyAutofill}
+		onchange={applyAutofill}
+		onfocus={handOffReport}
+		{@attach blankNativeReport}
+		{@attach besideControl}
+	/>
+{:else}
+	{#each values as entry, index (index)}
+		<input
+			type="hidden"
+			name={submittedName}
+			value={entry}
+			disabled={isDisabled}
+			form={formId}
+			data-field-hidden-input=""
+		/>
+	{/each}
+	{#if isMissing}
+		<!-- Submits nothing (no name): it only stands for the missing value, so the browser blocks
+		     the submit and reports it. -->
+		<input
+			id={reportId}
+			value=""
+			autocomplete="off"
+			required
+			form={formId}
+			tabindex={-1}
+			aria-hidden="true"
+			class="sr-only"
+			data-field-hidden-input=""
+			onfocus={handOffReport}
+			{@attach blankNativeReport}
+			{@attach besideControl}
+		/>
+	{/if}
+{/if}

package/dist/components/Form/Field/FieldHiddenInputs.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { FieldType } from './field.js';
+import type { FieldHiddenInputsProps } from './fieldHiddenInputs.props.js';
+declare function $$render<T extends FieldType>(): {
+    props: FieldHiddenInputsProps<T>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends FieldType> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends FieldType>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends FieldType>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const FieldHiddenInputs: $$IsomorphicComponent;
+type FieldHiddenInputs<T extends FieldType> = InstanceType<typeof FieldHiddenInputs<T>>;
+export default FieldHiddenInputs;

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

@@ -1,9 +1,12 @@
 import type { WithSlot } from '../../Slot/slot.js';
 import type { Snippet } from 'svelte';
-import type { HTMLAttributes } from 'svelte/elements';
-import type { FieldState } from './field.state.svelte.js';
+import type { Attachment } from 'svelte/attachments';
+import type { HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
+import type { FieldState, FieldValidatorResult, ValidationMode } from './field.state.svelte.js';
+import type { FieldMessageOverrides } from './field.messages.js';
 import type { FieldThemeProps } from './field.theme.js';
 import type { Density, Sizes } from '../../../types/theme.js';
+import type { FormInputRegistry } from '../Form/form.js';
 export type KeyValuePair = {
     key: string;
     value: string;
@@ -22,21 +25,50 @@ export type DateInputType = 'datetime' | 'date';
 export type TimeInputType = 'time';
 export type BooleanInputType = 'switch' | 'checkbox';
 export type SingleOptionInputType = 'select' | 'radio' | 'combobox';
-export type MultipleChoiceInputType = 'checkboxes';
+export type MultipleChoiceInputType = 'checkboxes' | 'select-multiple';
 export type FileInputType = 'file' | 'files';
 export type CalendarInputType = 'calendar' | 'calendar-range';
 export type ColorInputType = 'color';
 export type FieldLabelPosition = 'top' | 'left';
 export type FieldAttributes = Omit<HTMLAttributes<HTMLElement>, 'class' | 'id'>;
+/**
+ * Native attributes a button-rooted control (Checkbox, Switch) accepts through `inputAttrs`, such
+ * as `aria-label`, `aria-describedby`, `title`, `data-*` and event handlers. The control keeps its
+ * identity, role, state and form attributes. An `aria-label` here names the control instead of the
+ * field label.
+ */
+export type FieldButtonAttributes = Omit<HTMLButtonAttributes, 'class' | 'disabled' | 'form' | 'id' | 'name' | 'role' | 'type' | 'value' | 'aria-checked' | 'aria-disabled' | 'aria-readonly' | 'aria-required'>;
 export type InputType = FileInputType | SliderRangeInputType | DateInputType | ColorInputType | NumberInputType | RatingInputType | VoiceInputType | TimeInputType | TextInputType | RichTextInputType | BooleanInputType | MultipleChoiceInputType | TagInputType | TagGroupInputType | KeyValueInputType | PinInputType | SingleOptionInputType | CalendarInputType;
-export type FieldValue<T extends InputType> = T extends 'file' ? File : T extends 'files' ? File[] : T extends DateInputType ? Date : T extends SliderRangeInputType ? number[] : T extends NumberInputType ? number : T extends RatingInputType ? number : T extends VoiceInputType ? Blob : T extends TimeInputType ? number : T extends TextInputType ? string : T extends RichTextInputType ? string : T extends PinInputType ? string : T extends BooleanInputType ? boolean : T extends MultipleChoiceInputType ? string[] : T extends TagInputType ? string[] : T extends TagGroupInputType ? string | string[] | null : T extends KeyValueInputType ? KeyValuePair[] : T extends SingleOptionInputType ? string : T extends 'calendar' ? Date : T extends 'calendar-range' ? [Date | null, Date | null] : T extends ColorInputType ? string : never;
-export type InputProps<T extends InputType> = WithSlot<{
+/** Input types an app registered: the keys of its `FormInputRegistry` augmentation. */
+export type RegisteredInputType = Extract<keyof FormInputRegistry, string>;
+/** Every type a field can carry: the built-in inputs and the ones an app registered. */
+export type FieldType = InputType | RegisteredInputType;
+type RegisteredInputValue<T extends RegisteredInputType> = FormInputRegistry[T] extends {
+    value: infer Value;
+} ? Value : unknown;
+export type FieldValue<T extends FieldType> = T extends RegisteredInputType ? RegisteredInputValue<T> : T extends 'file' ? File : T extends 'files' ? File[] : T extends DateInputType ? Date : T extends SliderRangeInputType ? number[] : T extends NumberInputType ? number : T extends RatingInputType ? number : T extends VoiceInputType ? Blob : T extends TimeInputType ? number : T extends TextInputType ? string : T extends RichTextInputType ? string : T extends PinInputType ? string : T extends BooleanInputType ? boolean : T extends MultipleChoiceInputType ? string[] : T extends TagInputType ? string[] : T extends TagGroupInputType ? string | string[] | null : T extends KeyValueInputType ? KeyValuePair[] : T extends SingleOptionInputType ? string : T extends 'calendar' ? Date : T extends 'calendar-range' ? [Date | null, Date | null] : T extends ColorInputType ? string : never;
+export type InputProps<T extends FieldType> = WithSlot<{
     /** Form field name, used as the key when the input is part of a Form. */
     name?: string;
     /** Marks the field as required for validation and shows the required indicator. */
     required?: boolean;
-    /** Disables the input, preventing interaction and focus. */
+    /**
+     * Disables the input, preventing interaction and focus. A disabled Form, FormGroup or
+     * fieldset Field around the input disables it too; disabled fields skip validation.
+     */
     disabled?: boolean;
+    /**
+     * Shows the value without letting the user change it: the control stays focusable and is
+     * announced as read-only, and the value still validates and submits. A read-only Form or
+     * FormGroup around the input makes it read-only too.
+     */
+    readOnly?: boolean;
+    /**
+     * Id of the native `<form>` the field submits with when it is rendered outside that form,
+     * like the HTML `form` attribute. The field's native controls and hidden inputs join that
+     * form, and its reset returns the field to its initial value.
+     */
+    form?: string;
     /** Geometry and typography of the field control and label. */
     size?: Sizes;
     /** Internal spacing between field regions, labels, and adornments. */
@@ -45,8 +77,31 @@ export type InputProps<T extends InputType> = WithSlot<{
     labelPosition?: FieldLabelPosition;
     /** Whether the field is rendered; when false the field is hidden from the form. */
     visible?: boolean;
-    /** Validates the value; messages or true mark it invalid, false/null/undefined accept it. */
-    onValidate?: (value: FieldValue<T>) => string | string[] | boolean | null | undefined;
+    /**
+     * Validates the value; messages or true mark it invalid, false/null/undefined accept it.
+     * It may return a promise: the field reads as neither valid nor invalid while the promise
+     * is pending, submit waits for it, and a result for an older value is dropped. A rejected
+     * promise marks the field invalid with the generic message.
+     */
+    onValidate?: (value: FieldValue<T>) => FieldValidatorResult;
+    /**
+     * When the field validates by itself, overriding the Form's `validationMode`: `'submit'`
+     * (the default) waits for the first submit attempt and then re-validates every edit,
+     * `'blur'` validates when focus leaves the field, `'change'` validates on every change.
+     * A field that shows an error always re-validates as it is edited.
+     */
+    validationMode?: ValidationMode;
+    /**
+     * Milliseconds an edit waits before the validation it triggers runs, so an async
+     * `onValidate` is not called on every keystroke. Submit and blur validate at once.
+     */
+    validationDebounce?: number;
+    /**
+     * Replaces catalog validation messages for this field: a string, or a function for the
+     * messages that receive a limit, as in `{ required: 'Enter your name' }` or
+     * `{ tooShort: (min) => 'Use ' + min + ' characters or more' }`.
+     */
+    messages?: FieldMessageOverrides;
     /** Called whenever the field value changes. */
     onValueChange?: (value: FieldValue<T> | null) => void;
     /** Native attributes applied to the Field wrapper. */
@@ -61,12 +116,21 @@ export type InputProps<T extends InputType> = WithSlot<{
     defaultValue?: FieldValue<T> | null;
     /** Validation errors to display; `true` marks the field as errored without a message. */
     errors?: string[] | boolean;
-    /** Whether the field currently holds focus, bindable with `bind:focused`. */
+    /**
+     * Whether focus is inside the field, including popups it opened, bindable with
+     * `bind:focused`.
+     */
     focused?: boolean;
 }, 'header' | 'label' | 'suffix' | 'prefix' | 'actions' | 'description' | 'helper' | 'footer' | 'error' | 'errorsContainer'>;
-export type FieldProps<T extends InputType> = Omit<InputProps<T>, 'type' | 'name' | 'required' | 'disabled' | 'visible' | 'onValidate' | 'onValueChange' | 'defaultValue' | 'value' | 'errors' | 'focused'> & {
+export type FieldProps<T extends FieldType> = Omit<InputProps<T>, 'type' | 'name' | 'required' | 'disabled' | 'readOnly' | 'messages' | 'visible' | 'onValidate' | 'onValueChange' | 'defaultValue' | 'value' | 'errors' | 'focused'> & {
     /** Native wrapper element; use fieldset for a group of controls. */
     as?: string;
+    /**
+     * Attachment applied to the input container, the visible box, rather than the field root
+     * (which also holds the label and description). Pass a popover's `reference` here so its panel
+     * opens against the box, not below the description.
+     */
+    anchor?: Attachment<HTMLElement>;
     /** Control ID associated with the label, or false for an aria-labelledby label. */
     labelFor?: string | false;
     /** Custom control content composed with the shared field controller. */
@@ -76,3 +140,4 @@ export type FieldProps<T extends InputType> = Omit<InputProps<T>, 'type' | 'name
 };
 export declare const fieldStructure = "\n<Field>\n\t<Header>\n\t\t<Label />\n\t\t<Actions />\n\t</Header>\n\t<InputContainer>\n\t\t<Prefix />\n\t\t<Input />\n\t\t<Suffix />\n\t</InputContainer>\n\t<Footer>\n\t\t<Description />\n\t\t<Helper />\n\t</Footer>\n    <ErrorsContainer>\n        <Error />\n    </ErrorsContainer>\n</Field>\n";
 export declare const llmDescription = "\nThe field component is a versatile wrapper component for form inputs.\nThe field component is used to wrap form inputs and provide a consistent look and feel.\nIt's also used to provide a consistent way to handle errors and validation.\nUse it directly with createFieldState for standalone custom controls, or use a Form\ntype: 'field' entry to receive a registered controller in a snippet.\n\nThe field component is composed of the following parts:\n- Header\n- InputContainer\n- Footer\n- ErrorsContainer\n- Error\n- Description\n- Helper\n\nTo customize the field component, you can use the following snippets:\n\n- header: it is the wrapper for the label and actions.\n- label: it is the label for the field.\n- actions: it is the actions for the field.\n- footer: it is the wrapper for the description and helper.\n- errorsContainer: it is the wrapper for the error.\n- error: it is the error for the field.\n- description: it is the description for the field.\n- helper: it is the helper for the field.\n\nCompose snippets with the field controller captured in the parent component.\n\n";
+export {};

package/dist/components/Form/Field/field.mcp.d.ts

@@ -1 +1 @@
-export declare const fieldDescription = "\n# Field\n\nImport Field, createFieldState, and the FieldState type from entasis/field. Field is the shared\nvalidation and accessibility owner used by Entasis form controls. It renders field structure\naround a custom control and does not create another form or validation system.\n\n## Controller\n\ncreateFieldState receives id, type, value, errors, and focused. Use getter/setter properties\nfor values bound to component props; plain initial values also work for standalone controls.\nOptional name, required, disabled, visible, size, density, onValidate, and onValueChange\nconfigure the same owner used by built-in controls.\n\nThe controller exposes value, setValue(value), validate(), checkSchema(value), isValid,\nerrors, errorMessages, hasError, focused, disabled, required, size, and density.\nUse bind:value on field.value or call field.setValue for user edits. Accepted changes publish\none onValueChange callback each. Unchanged values and parent state synchronization do not\npublish callbacks. Disabled controllers reject user edits.\n\nSpread field.controlAttrs on the native control and attach field.control to register its node.\nThe attributes provide id, name, disabled, required, aria-invalid, and aria-describedby.\nThe controller exposes id, labelId, and errorId for more specialized controls. Field connects\nits label and error messages to this control, preserving unrelated accessible descriptions.\n\nfieldSchemas exports the built-in optional and required schemas. onValidate supplements that\nschema: a message, message array, or true means invalid; false, null, or undefined means valid.\nOptional empty values skip custom validation. validate returns a tuple containing the error\nflag and schema-normalized value.\n\n## Wrapper props\n\n- field: the shared FieldState controller.\n- children: custom control content.\n- as: native wrapper element; defaults to div. Use fieldset for grouped controls.\n- labelFor: associated control ID, or false for aria-labelledby; defaults to field.id.\n- size: small, normal, or large control geometry and label typography.\n- density: compact, normal, or comfortable internal spacing, independent of size.\n- labelPosition: top or left; left switches to side labels once the field itself is at least 32rem wide (a container query on the field, not the viewport).\n- fieldAttrs: native attributes for the wrapper. Put native control attributes on the control.\n- class and theme: wrapper classes and Field part overrides.\n\nSlots include header, label, actions, prefix, suffix, footer, description, helper,\nerrorsContainer, and error. Field renders required indicators and validation errors.\n\n## Form participation\n\nA Form input with type: 'field' supplies fieldType and a snippet accepting FieldState<fieldType>.\nThe entry inherits InputProps, including defaultValue, required, disabled, size, density,\nonValidate, and onValueChange. The controller receives the resolved Form size and density.\nIts value participates in inferred values, validation, submission, and Form bind:value.\nThe existing type: 'custom' entry remains display-only and contributes no value key.\n";
+export declare const fieldDescription = "\n# Field\n\nImport Field, FieldHiddenInputs, createFieldState, and the FieldState type from entasis/field. Field is the shared\nvalidation and accessibility owner used by Entasis form controls. It renders field structure\naround a custom control and does not create another form or validation system.\n\n## Controller\n\ncreateFieldState receives id, type, value, errors, and focused. Use getter/setter properties\nfor values bound to component props; plain initial values also work for standalone controls.\nOptional name, required, disabled, readOnly, visible, size, density, messages, minLength,\nmaxLength, onValidate, validationMode, validationDebounce, and onValueChange configure the same\nowner used by built-in controls.\n\nThe controller exposes value, setValue(value), validate(), checkSchema(value), isValid,\nerrors, errorMessages, hasError, hasValidationError, focused, touched, dirty, filled,\ninitialValue, reset(value?), focusControl(), validating, validateAsync(), settle(),\nexternalErrors, setExternalErrors(messages), clearExternalErrors(), disabled, readOnly,\nrequired, messages, size, and density.\nUse bind:value on field.value or call field.setValue for user edits. Accepted changes publish\none onValueChange callback each. Unchanged values and parent state synchronization do not\npublish callbacks. Disabled and read-only controllers reject user edits.\n\nSpread field.controlAttrs on the native control and attach field.control to register its node.\nThe attributes provide id, name, disabled, required, readonly, aria-invalid, and\naria-describedby. The controller exposes id, labelId, descriptionId, helperId, errorId, and\ndescribedBy for more specialized controls. Field connects its label, description, helper text\nand error messages to this control, preserving the app's own accessible descriptions: the\ncontrol's aria-describedby lists the app's ids, then the description, the helper, and the\nerrors last. Errors render in one role=\"alert\" container.\n\n## Disabled and read-only\n\ndisabled and readOnly are effective states: a field is disabled when it is, or when a disabled\nForm, a disabled FormGroup, or a Field rendered as=\"fieldset\" around it is; read-only works the\nsame way. A disabled field rejects edits and skips validation (errors an app set on it stay\nvisible). A read-only field stays focusable, rejects user edits, and still validates and\nsubmits. Field marks a read-only native text input or textarea with the readonly attribute, and\na role-based control (checkbox, switch, slider, combobox, radiogroup, listbox, spinbutton,\ntextbox) with aria-readonly. RatingInput's readonly prop is a deprecated alias of readOnly.\n\n## Validation messages\n\nEvery validation message a user sees comes from the i18n catalog in the active locale, never\nfrom the validation library. An empty required field shows one required message; a required\ncheckbox or switch says it must be on. Email and URL failures, text shorter than minLength or\nlonger than maxLength, values below or above a range, and incomplete codes each have their own\nmessage. true from onValidate shows the catalog's invalid message; strings from onValidate are\nshown verbatim.\n\nmessages overrides any of them per field: required, invalid, email, url, tooShort(min),\ntooLong(max), rangeUnderflow(min), rangeOverflow(max), and incomplete(length). Each is a\nstring, or a function receiving the limit for the parameterized ones. field.messages holds the\nresolved messages, for custom rules that report a range or length:\n\n```svelte\n<script lang=\"ts\">\n\timport { createFieldState } from 'entasis/field';\n\n\tconst field = createFieldState({\n\t\tid: 'nickname',\n\t\ttype: 'text',\n\t\trequired: true,\n\t\tminLength: 3,\n\t\tmessages: { required: 'Pick a nickname', tooShort: (min) => 'Use ' + min + ' letters or more' },\n\t\tvalue: '',\n\t\terrors: [],\n\t\tfocused: false\n\t});\n</script>\n```\n\n## Validation timing, async validators and external errors\n\nvalidationMode picks when the field validates by itself: submit (the default, from the Form)\nvalidates on a submit attempt and then re-validates each edit, blur when focus leaves the field,\nchange on every accepted change. A field showing an error always re-validates as it is edited,\nand mounting never validates. validationDebounce (milliseconds) delays the validation an edit\ntriggers. Both can be set on the Form, on an entry, or as Field props that controls forward.\n\nonValidate may return a promise. While it is pending the field is neither valid nor invalid\n(no aria-invalid, no data-invalid, data-validating on the root) and validating is true; a\nresult for an older value is dropped, a rejection marks the field invalid with the generic\nmessage, and unmounting cancels it. validate() stays synchronous; validateAsync() and settle()\nwait for pending validators.\n\nsetExternalErrors(messages) shows errors an app got from outside, such as a server response.\nerrorMessages lists the validation errors first, then these. validate() leaves them alone and\nthey do not count as hasValidationError, so they never block a submit; they clear on the\nfield's next accepted value change, reset(), or clearExternalErrors().\n\n## Interaction state\n\nFocus is tracked on the Field root, so every control reports it, including those with several\nfocusable parts: focused is true while focus is anywhere in the field or in a popup the field\nopened (a listbox, a date picker), and becomes false when focus leaves both. Leaving sets\ntouched. focused also clears when the focused control becomes disabled or leaves the document,\nwhere Chromium sends no blur.\n\ndirty is true while the value differs from initialValue, the first settled value; null, an\nempty string and an empty array count as equal, Dates compare by time, arrays and plain objects\nby content. filled is true while the field holds a value (a checked checkbox or switch; a\nregistered type's isEmpty decides for app-defined types). reset(value?) restores the initial\nvalue, or a new one, as the untouched baseline without a value callback, and clears errors and\nany pending validation.\n\nThe Field root carries data-invalid, data-disabled, data-readonly, data-focused, data-filled,\ndata-dirty, data-touched, and data-validating as presence attributes for styling, next to\ndata-label-position. A new error fades and grows in under the Theme's motion tokens; reduced\nmotion plays nothing.\n\n## Wrapper props\n\n- field: the shared FieldState controller.\n- children: custom control content.\n- as: native wrapper element; defaults to div. Use fieldset for grouped controls; a fieldset\n  Field renders disabled when the field is and shares its disabled and read-only state with\n  fields inside it.\n- labelFor: associated control ID, or false for aria-labelledby; defaults to field.id. A\n  labelFor={false} label focuses the control when clicked, without toggling or opening it. An\n  aria-label on the control names it instead, so the label is not linked.\n- size: small, normal, or large control geometry and label typography.\n- density: compact, normal, or comfortable internal spacing, independent of size.\n- labelPosition: top or left; left switches to side labels once the field itself is at least 32rem wide (a container query on the field, not the viewport).\n- fieldAttrs: native attributes for the wrapper. Put native control attributes on the control.\n- anchor: an attachment applied to the input box rather than the wrapper. Pass a popover's\n  `reference` here so its panel opens against the box, not below the description.\n- class and theme: wrapper classes and Field part overrides.\n\nSlots include header, label, actions, prefix, suffix, footer, description, helper,\nerrorsContainer, and error. Field renders required indicators and validation errors. A press on\nthe input container around a text control (its padding, an icon, a chip) focuses the control;\nbuttons and other controls inside keep their own behaviour.\n\nRequired role-based controls (checkbox, switch, radiogroup, slider, combobox) receive\naria-required from Field; native inputs keep their required attribute. Button-rooted controls\n(Checkbox, Switch) accept inputAttrs typed as FieldButtonAttributes.\n\n## Native forms\n\nEvery Field control also works inside a plain <form>, such as a SvelteKit form action.\n\n- form: the id of the native form a field submits with when it is rendered outside that form,\n  like the HTML form attribute. Every input prop type accepts it; Field gives it to the field's\n  native controls and hidden inputs.\n- Reset: a native reset of the field's form (a type=\"reset\" button or form.reset()) returns the\n  field to the value it mounted with, clears its errors, and publishes one onValueChange. A reset\n  that another listener cancels changes nothing. Disabled and read-only fields keep their value.\n\nFieldHiddenInputs renders the inputs a custom control submits through, beside the control and\nnever inside a button. Pass the field, plus value (a string or number for one input, an array for\none input per entry, null for none) or checked (one checkbox submitting value, default \"on\", only\nwhile checked). name, required, disabled and form default to the field's; a generated field name\nis never submitted. A required, empty field blocks the native submit: the browser's report moves\nto the field's control, which shows the field's own error instead of the browser bubble.\nautocomplete renders the single value as a text input the browser can autofill; the filled text\nis matched against options (by value, then label, then label ignoring case and accents) and\ncommitted with field.setValue, or handed to onAutofill. Read-only and disabled fields ignore\nautofill.\n\n```svelte\n<script lang=\"ts\">\n\timport { Field, FieldHiddenInputs, createFieldState } from 'entasis/field';\n\n\tconst plans = ['free', 'pro'];\n\tconst field = createFieldState({\n\t\tid: 'plan',\n\t\ttype: 'select',\n\t\tname: 'plan',\n\t\tvalue: 'free',\n\t\terrors: [],\n\t\tfocused: false\n\t});\n\tconst nextPlan = () => plans[(plans.indexOf(field.value ?? '') + 1) % plans.length];\n</script>\n\n<Field {field} label=\"Plan\" labelFor={false}>\n\t<button type=\"button\" {@attach field.control} onclick={() => field.setValue(nextPlan())}>\n\t\t{field.value}\n\t</button>\n\t<FieldHiddenInputs {field} value={field.value} />\n</Field>\n```\n\n## Form participation\n\nA Form input with type: 'field' supplies fieldType and a snippet accepting FieldState<fieldType>.\nThe entry inherits InputProps, including defaultValue, required, disabled, readOnly, messages,\nsize, density, onValidate, and onValueChange. The controller receives the resolved Form size and\ndensity. Its value participates in inferred values, validation, submission, and Form bind:value.\nThe existing type: 'custom' entry remains display-only and contributes no value key.\n";

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

@@ -1,7 +1,7 @@
 export const fieldDescription = `
 # Field
 
-Import Field, createFieldState, and the FieldState type from entasis/field. Field is the shared
+Import Field, FieldHiddenInputs, createFieldState, and the FieldState type from entasis/field. Field is the shared
 validation and accessibility owner used by Entasis form controls. It renders field structure
 around a custom control and does not create another form or validation system.
 
@@ -9,45 +9,185 @@ around a custom control and does not create another form or validation system.
 
 createFieldState receives id, type, value, errors, and focused. Use getter/setter properties
 for values bound to component props; plain initial values also work for standalone controls.
-Optional name, required, disabled, visible, size, density, onValidate, and onValueChange
-configure the same owner used by built-in controls.
+Optional name, required, disabled, readOnly, visible, size, density, messages, minLength,
+maxLength, onValidate, validationMode, validationDebounce, and onValueChange configure the same
+owner used by built-in controls.
 
 The controller exposes value, setValue(value), validate(), checkSchema(value), isValid,
-errors, errorMessages, hasError, focused, disabled, required, size, and density.
+errors, errorMessages, hasError, hasValidationError, focused, touched, dirty, filled,
+initialValue, reset(value?), focusControl(), validating, validateAsync(), settle(),
+externalErrors, setExternalErrors(messages), clearExternalErrors(), disabled, readOnly,
+required, messages, size, and density.
 Use bind:value on field.value or call field.setValue for user edits. Accepted changes publish
 one onValueChange callback each. Unchanged values and parent state synchronization do not
-publish callbacks. Disabled controllers reject user edits.
+publish callbacks. Disabled and read-only controllers reject user edits.
 
 Spread field.controlAttrs on the native control and attach field.control to register its node.
-The attributes provide id, name, disabled, required, aria-invalid, and aria-describedby.
-The controller exposes id, labelId, and errorId for more specialized controls. Field connects
-its label and error messages to this control, preserving unrelated accessible descriptions.
+The attributes provide id, name, disabled, required, readonly, aria-invalid, and
+aria-describedby. The controller exposes id, labelId, descriptionId, helperId, errorId, and
+describedBy for more specialized controls. Field connects its label, description, helper text
+and error messages to this control, preserving the app's own accessible descriptions: the
+control's aria-describedby lists the app's ids, then the description, the helper, and the
+errors last. Errors render in one role="alert" container.
 
-fieldSchemas exports the built-in optional and required schemas. onValidate supplements that
-schema: a message, message array, or true means invalid; false, null, or undefined means valid.
-Optional empty values skip custom validation. validate returns a tuple containing the error
-flag and schema-normalized value.
+## Disabled and read-only
+
+disabled and readOnly are effective states: a field is disabled when it is, or when a disabled
+Form, a disabled FormGroup, or a Field rendered as="fieldset" around it is; read-only works the
+same way. A disabled field rejects edits and skips validation (errors an app set on it stay
+visible). A read-only field stays focusable, rejects user edits, and still validates and
+submits. Field marks a read-only native text input or textarea with the readonly attribute, and
+a role-based control (checkbox, switch, slider, combobox, radiogroup, listbox, spinbutton,
+textbox) with aria-readonly. RatingInput's readonly prop is a deprecated alias of readOnly.
+
+## Validation messages
+
+Every validation message a user sees comes from the i18n catalog in the active locale, never
+from the validation library. An empty required field shows one required message; a required
+checkbox or switch says it must be on. Email and URL failures, text shorter than minLength or
+longer than maxLength, values below or above a range, and incomplete codes each have their own
+message. true from onValidate shows the catalog's invalid message; strings from onValidate are
+shown verbatim.
+
+messages overrides any of them per field: required, invalid, email, url, tooShort(min),
+tooLong(max), rangeUnderflow(min), rangeOverflow(max), and incomplete(length). Each is a
+string, or a function receiving the limit for the parameterized ones. field.messages holds the
+resolved messages, for custom rules that report a range or length:
+
+\`\`\`svelte
+<script lang="ts">
+	import { createFieldState } from './index.ts';
+
+	const field = createFieldState({
+		id: 'nickname',
+		type: 'text',
+		required: true,
+		minLength: 3,
+		messages: { required: 'Pick a nickname', tooShort: (min) => 'Use ' + min + ' letters or more' },
+		value: '',
+		errors: [],
+		focused: false
+	});
+</script>
+\`\`\`
+
+## Validation timing, async validators and external errors
+
+validationMode picks when the field validates by itself: submit (the default, from the Form)
+validates on a submit attempt and then re-validates each edit, blur when focus leaves the field,
+change on every accepted change. A field showing an error always re-validates as it is edited,
+and mounting never validates. validationDebounce (milliseconds) delays the validation an edit
+triggers. Both can be set on the Form, on an entry, or as Field props that controls forward.
+
+onValidate may return a promise. While it is pending the field is neither valid nor invalid
+(no aria-invalid, no data-invalid, data-validating on the root) and validating is true; a
+result for an older value is dropped, a rejection marks the field invalid with the generic
+message, and unmounting cancels it. validate() stays synchronous; validateAsync() and settle()
+wait for pending validators.
+
+setExternalErrors(messages) shows errors an app got from outside, such as a server response.
+errorMessages lists the validation errors first, then these. validate() leaves them alone and
+they do not count as hasValidationError, so they never block a submit; they clear on the
+field's next accepted value change, reset(), or clearExternalErrors().
+
+## Interaction state
+
+Focus is tracked on the Field root, so every control reports it, including those with several
+focusable parts: focused is true while focus is anywhere in the field or in a popup the field
+opened (a listbox, a date picker), and becomes false when focus leaves both. Leaving sets
+touched. focused also clears when the focused control becomes disabled or leaves the document,
+where Chromium sends no blur.
+
+dirty is true while the value differs from initialValue, the first settled value; null, an
+empty string and an empty array count as equal, Dates compare by time, arrays and plain objects
+by content. filled is true while the field holds a value (a checked checkbox or switch; a
+registered type's isEmpty decides for app-defined types). reset(value?) restores the initial
+value, or a new one, as the untouched baseline without a value callback, and clears errors and
+any pending validation.
+
+The Field root carries data-invalid, data-disabled, data-readonly, data-focused, data-filled,
+data-dirty, data-touched, and data-validating as presence attributes for styling, next to
+data-label-position. A new error fades and grows in under the Theme's motion tokens; reduced
+motion plays nothing.
 
 ## Wrapper props
 
 - field: the shared FieldState controller.
 - children: custom control content.
-- as: native wrapper element; defaults to div. Use fieldset for grouped controls.
-- labelFor: associated control ID, or false for aria-labelledby; defaults to field.id.
+- as: native wrapper element; defaults to div. Use fieldset for grouped controls; a fieldset
+  Field renders disabled when the field is and shares its disabled and read-only state with
+  fields inside it.
+- labelFor: associated control ID, or false for aria-labelledby; defaults to field.id. A
+  labelFor={false} label focuses the control when clicked, without toggling or opening it. An
+  aria-label on the control names it instead, so the label is not linked.
 - size: small, normal, or large control geometry and label typography.
 - density: compact, normal, or comfortable internal spacing, independent of size.
 - labelPosition: top or left; left switches to side labels once the field itself is at least 32rem wide (a container query on the field, not the viewport).
 - fieldAttrs: native attributes for the wrapper. Put native control attributes on the control.
+- anchor: an attachment applied to the input box rather than the wrapper. Pass a popover's
+  \`reference\` here so its panel opens against the box, not below the description.
 - class and theme: wrapper classes and Field part overrides.
 
 Slots include header, label, actions, prefix, suffix, footer, description, helper,
-errorsContainer, and error. Field renders required indicators and validation errors.
+errorsContainer, and error. Field renders required indicators and validation errors. A press on
+the input container around a text control (its padding, an icon, a chip) focuses the control;
+buttons and other controls inside keep their own behaviour.
+
+Required role-based controls (checkbox, switch, radiogroup, slider, combobox) receive
+aria-required from Field; native inputs keep their required attribute. Button-rooted controls
+(Checkbox, Switch) accept inputAttrs typed as FieldButtonAttributes.
+
+## Native forms
+
+Every Field control also works inside a plain <form>, such as a SvelteKit form action.
+
+- form: the id of the native form a field submits with when it is rendered outside that form,
+  like the HTML form attribute. Every input prop type accepts it; Field gives it to the field's
+  native controls and hidden inputs.
+- Reset: a native reset of the field's form (a type="reset" button or form.reset()) returns the
+  field to the value it mounted with, clears its errors, and publishes one onValueChange. A reset
+  that another listener cancels changes nothing. Disabled and read-only fields keep their value.
+
+FieldHiddenInputs renders the inputs a custom control submits through, beside the control and
+never inside a button. Pass the field, plus value (a string or number for one input, an array for
+one input per entry, null for none) or checked (one checkbox submitting value, default "on", only
+while checked). name, required, disabled and form default to the field's; a generated field name
+is never submitted. A required, empty field blocks the native submit: the browser's report moves
+to the field's control, which shows the field's own error instead of the browser bubble.
+autocomplete renders the single value as a text input the browser can autofill; the filled text
+is matched against options (by value, then label, then label ignoring case and accents) and
+committed with field.setValue, or handed to onAutofill. Read-only and disabled fields ignore
+autofill.
+
+\`\`\`svelte
+<script lang="ts">
+	import { Field, FieldHiddenInputs, createFieldState } from './index.ts';
+
+	const plans = ['free', 'pro'];
+	const field = createFieldState({
+		id: 'plan',
+		type: 'select',
+		name: 'plan',
+		value: 'free',
+		errors: [],
+		focused: false
+	});
+	const nextPlan = () => plans[(plans.indexOf(field.value ?? '') + 1) % plans.length];
+</script>
+
+<Field {field} label="Plan" labelFor={false}>
+	<button type="button" {@attach field.control} onclick={() => field.setValue(nextPlan())}>
+		{field.value}
+	</button>
+	<FieldHiddenInputs {field} value={field.value} />
+</Field>
+\`\`\`
 
 ## Form participation
 
 A Form input with type: 'field' supplies fieldType and a snippet accepting FieldState<fieldType>.
-The entry inherits InputProps, including defaultValue, required, disabled, size, density,
-onValidate, and onValueChange. The controller receives the resolved Form size and density.
-Its value participates in inferred values, validation, submission, and Form bind:value.
+The entry inherits InputProps, including defaultValue, required, disabled, readOnly, messages,
+size, density, onValidate, and onValueChange. The controller receives the resolved Form size and
+density. Its value participates in inferred values, validation, submission, and Form bind:value.
 The existing type: 'custom' entry remains display-only and contributes no value key.
 `;

package/dist/components/Form/Field/field.messages.d.ts

@@ -0,0 +1,47 @@
+import type { BaseIssue } from 'valibot';
+import type { Messages } from '../../../i18n/en.js';
+import type { FieldType } from './field.js';
+/** The validation messages a field shows, resolved for the active locale. */
+export type FieldMessages = {
+    /** A required field left empty; for a checkbox or switch, left off. */
+    required: string;
+    /** A value rejected without a more specific message, including `true` from `onValidate`. */
+    invalid: string;
+    /** A value that is not an email address. */
+    email: string;
+    /** A value that is not a URL. */
+    url: string;
+    /** Text shorter than the field's minimum length. */
+    tooShort: (min: number) => string;
+    /** Text longer than the field's maximum length. */
+    tooLong: (max: number) => string;
+    /** A value below the field's minimum. */
+    rangeUnderflow: (min: number | string) => string;
+    /** A value above the field's maximum. */
+    rangeOverflow: (max: number | string) => string;
+    /** A code with fewer characters than its length, such as a partly entered PinInput. */
+    incomplete: (length: number) => string;
+};
+type MessageOverride<Message> = Message extends (...args: infer Args) => string ? string | ((...args: Args) => string) : string;
+/**
+ * Per-entry message overrides, the entasis form of a per-constraint error message: a string, or
+ * for the parameterized messages a function receiving the same constraint value.
+ */
+export type FieldMessageOverrides = {
+    [Key in keyof FieldMessages]?: MessageOverride<FieldMessages[Key]>;
+};
+/**
+ * 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 declare const resolveFieldMessages: (t: Messages, type: FieldType, overrides?: FieldMessageOverrides) => FieldMessages;
+/** The part of a validation issue the message mapping reads. */
+export type FieldIssue = Pick<BaseIssue<unknown>, 'kind' | 'type' | 'input' | '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 declare const describeFieldIssue: (issue: FieldIssue, messages: FieldMessages, locale?: string) => string;
+export {};