entasis 0.11.0 → 0.12.0

package/dist/components/Form/DateInput/DateInput.svelte

@@ -7,7 +7,7 @@
 	import FieldActionButton from '../Field/FieldActionButton.svelte';
 	import { createFieldState } from '../Field/field.state.svelte.js';
 	import { calendarBlankIcon } from '../../Icons/calendarBlank.js';
-	import type { PopoverState } from '../../Popover/popover.state.svelte.js';
+	import type { PopoverApi } from '../../Popover/popover.api.js';
 	import type { DateInputProps } from './dateInput.props.js';
 	import { useDateInputTheme } from './dateInput.theme.js';
 	import { useI18n } from '../../../i18n/context.svelte.js';
@@ -31,6 +31,8 @@
 		required = false,
 		theme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		onValueChange,
@@ -75,6 +77,12 @@
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
@@ -242,7 +250,7 @@
 	onValueChange={handleCalendarChange}
 	class={classes.popover({ class: theme?.popover?.base })}
 >
-	{#snippet trigger(popover: PopoverState)}
+	{#snippet trigger(popover: PopoverApi)}
 		<Field
 			{field}
 			size={rest.size}
@@ -258,7 +266,7 @@
 				}
 			}}
 			{...rest}
-			{@attach popover.reference}
+			anchor={popover.reference}
 		>
 			<input
 				data-1p-ignore

package/dist/components/Form/DateInput/dateInput.mcp.d.ts

@@ -1 +1 @@
-export declare const dateInputDescription = "\n# DateInput\n\nMasked native text entry composed with Field and DateSelector. The bindable value is a native `Date | null`.\n\n## Import\n\n```svelte\n<script lang=\"ts\">\n  import { DateInput } from './index.ts';\n</script>\n```\n\n## Usage\n\n```svelte\n<script lang=\"ts\">\n  let value = $state<Date | null>(null);\n</script>\n\n<DateInput label=\"Start date\" bind:value />\n```\n\n## Date formatting\n\nUse `format` with `dd`, `mm`, `yy`, and `yyyy` segments. Supported values include `dd/mm/yyyy`, `mm/dd/yyyy`, `mm/yyyy`, and `yyyy/mm/dd`. The `separator` prop replaces the slash in the rendered mask.\n\n## Selector options\n\n- `presets`: date shortcuts shaped as `{ label, value }`.\n- `disabledDates`: individual dates or inclusive date ranges.\n- `minDate` / `maxDate`: calendar selection bounds.\n- `calendarView`: `'single' | 'double'`.\n- `mobileSheet`: renders the DateSelector as a bottom sheet below 768px.\n- `closeOnSelect`: closes after choosing a date; defaults to `false`.\n- `onSelect`: the pick event -- fires only when a date is chosen from the selector or its\n  presets; `onValueChange` is the value state change and reports both typed and picked dates.\n\n```svelte\n<DateInput\n  label=\"Delivery date\"\n  bind:value\n  minDate={new Date()}\n  presets={[\n    { label: 'Tomorrow', value: new Date(2026, 6, 16) },\n    { label: 'Next week', value: new Date(2026, 6, 22) }\n  ]}\n/>\n```\n\nThe selector never opens on focus, so tabbing through the field does not pop it. Open it with ArrowDown while the input has focus, or from the full-height calendar button (which carries `aria-haspopup=\"dialog\"`, `aria-expanded`, and `aria-controls`). It stays open after selection unless `closeOnSelect` is enabled. Calendar days support arrow, Home/End, and PageUp/PageDown navigation.\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";
+export declare const dateInputDescription = "\n# DateInput\n\nMasked native text entry composed with Field and DateSelector. The bindable value is a native `Date | null`.\n\n## Import\n\n```svelte\n<script lang=\"ts\">\n  import { DateInput } from './index.ts';\n</script>\n```\n\n## Usage\n\n```svelte\n<script lang=\"ts\">\n  let value = $state<Date | null>(null);\n</script>\n\n<DateInput label=\"Start date\" bind:value />\n```\n\n## Date formatting\n\nUse `format` with `dd`, `mm`, `yy`, and `yyyy` segments. Supported values include `dd/mm/yyyy`, `mm/dd/yyyy`, `mm/yyyy`, and `yyyy/mm/dd`. The `separator` prop replaces the slash in the rendered mask.\n\n## Selector options\n\n- `presets`: date shortcuts shaped as `{ label, value }`.\n- `disabledDates`: individual dates or inclusive date ranges.\n- `minDate` / `maxDate`: calendar selection bounds.\n- `calendarView`: `'single' | 'double'`.\n- `mobileSheet`: renders the DateSelector as a bottom sheet below 768px.\n- `closeOnSelect`: closes after choosing a date; defaults to `false`.\n- `onSelect`: the pick event -- fires only when a date is chosen from the selector or its\n  presets; `onValueChange` is the value state change and reports both typed and picked dates.\n\n```svelte\n<DateInput\n  label=\"Delivery date\"\n  bind:value\n  minDate={new Date()}\n  presets={[\n    { label: 'Tomorrow', value: new Date(2026, 6, 16) },\n    { label: 'Next week', value: new Date(2026, 6, 22) }\n  ]}\n/>\n```\n\nThe selector never opens on focus, so tabbing through the field does not pop it. Open it with ArrowDown while the input has focus, or from the full-height calendar button (which carries `aria-haspopup=\"dialog\"`, `aria-expanded`, and `aria-controls`). It stays open after selection unless `closeOnSelect` is enabled. Calendar days support arrow, Home/End, and PageUp/PageDown navigation.\n\n## Disabled and read-only\n\n- **disabled**: boolean - Disable the input and the calendar button; a disabled field leaves Form values and posts nothing.\n- **readOnly**: boolean - The input stays focusable and is announced as read-only; typing and selector picks are refused, and the value still validates and submits. A read-only Form, FormGroup or fieldset Field makes it read-only too.\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";

package/dist/components/Form/DateInput/dateInput.mcp.js

@@ -50,6 +50,11 @@ Use \`format\` with \`dd\`, \`mm\`, \`yy\`, and \`yyyy\` segments. Supported val
 
 The selector never opens on focus, so tabbing through the field does not pop it. Open it with ArrowDown while the input has focus, or from the full-height calendar button (which carries \`aria-haspopup="dialog"\`, \`aria-expanded\`, and \`aria-controls\`). It stays open after selection unless \`closeOnSelect\` is enabled. Calendar days support arrow, Home/End, and PageUp/PageDown navigation.
 
+## Disabled and read-only
+
+- **disabled**: boolean - Disable the input and the calendar button; a disabled field leaves Form values and posts nothing.
+- **readOnly**: boolean - The input stays focusable and is announced as read-only; typing and selector picks are refused, and the value still validates and submits. A read-only Form, FormGroup or fieldset Field makes it read-only too.
+
 ## State contract
 
 - **value**: current bindable editable value.

package/dist/components/Form/DateSelector/DateSelector.svelte

@@ -39,6 +39,7 @@
 		maxDate,
 		disabledDates = [],
 		disabled = false,
+		readOnly = false,
 		calendarLabel,
 		i18n,
 		id,
@@ -130,7 +131,7 @@
 	}
 
 	function commitValue(nextValue: DateSelectorValue<Mode>, isSelectionComplete = true) {
-		if (disabled) return;
+		if (disabled || readOnly) return;
 		const normalizedValue = normalizeValue(nextValue);
 		if (!isValueSelected(normalizedValue)) {
 			valueState.value = normalizedValue;
@@ -188,6 +189,7 @@
 	{id}
 	open={openState.value}
 	onOpenChange={setOpen}
+	label={calendarLabel ?? t.chooseDates}
 	{position}
 	{offset}
 	{mobileSheet}
@@ -203,7 +205,7 @@
 						variant={isValueSelected(preset.value) ? 'soft' : 'ghost'}
 						size="small"
 						fullWidth
-						{disabled}
+						disabled={disabled || readOnly}
 						class={classes.preset()}
 						onclick={() => commitValue(preset.value)}
 					>
@@ -224,6 +226,7 @@
 			{maxDate}
 			{disabledDates}
 			{disabled}
+			{readOnly}
 			label={calendarLabel ?? t.chooseDates}
 			theme={mergedCalendarTheme}
 			onValueChange={handleCalendarChange}

package/dist/components/Form/DateSelector/DateSelectorInput.svelte

@@ -24,6 +24,8 @@
 		mode = 'date' as Mode,
 		required = false,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		onValueChange,
@@ -89,6 +91,12 @@
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
@@ -152,6 +160,7 @@
 			{calendarLabel}
 			id={selectorId}
 			disabled={field.disabled}
+			readOnly={field.readOnly}
 			theme={theme?.selector}
 			{calendarTheme}
 		/>

package/dist/components/Form/DateSelector/dateSelector.mcp.d.ts

@@ -1 +1 @@
-export declare const dateSelectorDescription = "\n# DateSelector\n\nPopover calendar composition for selecting one date, a range, or multiple dates. It uses Entasis's Popover, CalendarPrimitive, Button, and transitionSize attachment.\n`DateSelector` is the raw popover primitive; `DateSelectorInput` wraps it in the standard field\nchrome (label, description, errors, form registration) and extends InputProps \u2014 field type 'date'\nfor `mode=\"date\"`, 'calendar-range' for `mode=\"range\"` (`mode=\"multiple\"` has no field type and\nstays primitive-only).\n\n## Import\n\n```svelte\n<script lang=\"ts\">\n  import { DateSelector, DateSelectorInput } from './index.ts';\n</script>\n```\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  let value = $state<Date | null>(null);\n</script>\n\n<!-- Field variant: label/description/errors like every other form input -->\n<DateSelectorInput\n\tlabel=\"Due date\"\n\tdescription=\"We'll remind you the day before\"\n\tbind:value\n/>\n\n<!-- Raw popover primitive -->\n<DateSelector bind:value />\n```\n\n## DateSelectorInput (field variant)\n\nAccepts every field prop from InputProps \u2014 `label`, `description`, `name`, `required`, `errors`,\n`onValidate`, `helper`, snippets, \u2026 \u2014 plus the selector props (`mode`, `presets`, `trigger`,\n`closeOnSelect`, `position`, `minDate`/`maxDate`, \u2026). `theme` is split: `theme.selector` for the\npopover parts, `theme.field` for the field wrapper.\n\n## Selection modes\n\n- `mode=\"date\"` binds `Date | null`.\n- `mode=\"range\"` binds `[Date | null, Date | null] | null`.\n- `mode=\"multiple\"` binds `Date[]`.\n\nThe selector stays open after selection by default. Set `closeOnSelect` to close after a date, a complete range, or a multiple-date change.\n\n## Presets\n\n```svelte\n<DateSelector\n  bind:value\n  presets={[\n    { label: 'Today', value: new Date() },\n    { label: 'Tomorrow', value: new Date(2026, 6, 16) }\n  ]}\n/>\n```\n\nEach preset value must match the active mode. Presets follow the same `closeOnSelect` policy as calendar selection.\n\n## Custom trigger\n\nThe `trigger` prop follows Popover's trigger contract. A trigger snippet receives `PopoverState`; attach `popover.reference` to the trigger element and call `popover.toggle()`.\n\n## Calendar configuration\n\nUse `view`, `weekStartsOnMonday`, `weekdayLength`, `locale`, `minDate`, `maxDate`, and `disabledDates` to configure the embedded calendar. Set `mobileSheet` to render the selector as a bottom sheet below 768px.\n\nThe content container animates intrinsic height changes. Month navigation uses a direction-aware slide and respects reduced-motion preferences.\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n- **open**: bindable popover visibility.\n- **defaultOpen**: initializes an uncontrolled selector once.\n- **onOpenChange**: receives the new boolean once for each opening or closing interaction.\n\nSelecting the current date or preset does not emit another value callback. With closeOnSelect,\nthat selection can still close the popover and emit one onOpenChange callback.\n\n";
+export declare const dateSelectorDescription = "\n# DateSelector\n\nPopover calendar composition for selecting one date, a range, or multiple dates. It uses Entasis's Popover, CalendarPrimitive, Button, and transitionSize attachment.\n`DateSelector` is the raw popover primitive; `DateSelectorInput` wraps it in the standard field\nchrome (label, description, errors, form registration) and extends InputProps \u2014 field type 'date'\nfor `mode=\"date\"`, 'calendar-range' for `mode=\"range\"` (`mode=\"multiple\"` has no field type and\nstays primitive-only).\n\n## Import\n\n```svelte\n<script lang=\"ts\">\n  import { DateSelector, DateSelectorInput } from './index.ts';\n</script>\n```\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  let value = $state<Date | null>(null);\n</script>\n\n<!-- Field variant: label/description/errors like every other form input -->\n<DateSelectorInput\n\tlabel=\"Due date\"\n\tdescription=\"We'll remind you the day before\"\n\tbind:value\n/>\n\n<!-- Raw popover primitive -->\n<DateSelector bind:value />\n```\n\n## DateSelectorInput (field variant)\n\nAccepts every field prop from InputProps \u2014 `label`, `description`, `name`, `required`, `errors`,\n`onValidate`, `helper`, snippets, \u2026 \u2014 plus the selector props (`mode`, `presets`, `trigger`,\n`closeOnSelect`, `position`, `minDate`/`maxDate`, \u2026). `theme` is split: `theme.selector` for the\npopover parts, `theme.field` for the field wrapper.\n\n## Selection modes\n\n- `mode=\"date\"` binds `Date | null`.\n- `mode=\"range\"` binds `[Date | null, Date | null] | null`.\n- `mode=\"multiple\"` binds `Date[]`.\n\nThe selector stays open after selection by default. Set `closeOnSelect` to close after a date, a complete range, or a multiple-date change.\n\n## Presets\n\n```svelte\n<DateSelector\n  bind:value\n  presets={[\n    { label: 'Today', value: new Date() },\n    { label: 'Tomorrow', value: new Date(2026, 6, 16) }\n  ]}\n/>\n```\n\nEach preset value must match the active mode. Presets follow the same `closeOnSelect` policy as calendar selection.\n\n## Custom trigger\n\nThe `trigger` prop follows Popover's trigger contract. A trigger snippet receives `PopoverApi` (from `entasis/popover`); attach `popover.reference` to the trigger element and call `popover.toggle()`.\n\n## Calendar configuration\n\nUse `view`, `weekStartsOnMonday`, `weekdayLength`, `locale`, `minDate`, `maxDate`, and `disabledDates` to configure the embedded calendar. Set `readOnly` to let the popup open while refusing date and preset choices. Set `mobileSheet` to render the selector as a bottom sheet below 768px.\n\nThe content container animates intrinsic height changes. Month navigation uses a direction-aware slide and respects reduced-motion preferences.\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n- **open**: bindable popover visibility.\n- **defaultOpen**: initializes an uncontrolled selector once.\n- **onOpenChange**: receives the new boolean once for each opening or closing interaction.\n\nSelecting the current date or preset does not emit another value callback. With closeOnSelect,\nthat selection can still close the popover and emit one onOpenChange callback.\n\n";

package/dist/components/Form/DateSelector/dateSelector.mcp.js

@@ -64,11 +64,11 @@ Each preset value must match the active mode. Presets follow the same \`closeOnS
 
 ## Custom trigger
 
-The \`trigger\` prop follows Popover's trigger contract. A trigger snippet receives \`PopoverState\`; attach \`popover.reference\` to the trigger element and call \`popover.toggle()\`.
+The \`trigger\` prop follows Popover's trigger contract. A trigger snippet receives \`PopoverApi\` (from \`entasis/popover\`); attach \`popover.reference\` to the trigger element and call \`popover.toggle()\`.
 
 ## Calendar configuration
 
-Use \`view\`, \`weekStartsOnMonday\`, \`weekdayLength\`, \`locale\`, \`minDate\`, \`maxDate\`, and \`disabledDates\` to configure the embedded calendar. Set \`mobileSheet\` to render the selector as a bottom sheet below 768px.
+Use \`view\`, \`weekStartsOnMonday\`, \`weekdayLength\`, \`locale\`, \`minDate\`, \`maxDate\`, and \`disabledDates\` to configure the embedded calendar. Set \`readOnly\` to let the popup open while refusing date and preset choices. Set \`mobileSheet\` to render the selector as a bottom sheet below 768px.
 
 The content container animates intrinsic height changes. Month navigation uses a direction-aware slide and respects reduced-motion preferences.
 

package/dist/components/Form/DateSelector/dateSelector.props.d.ts

@@ -55,6 +55,8 @@ export type DateSelectorProps<Mode extends DateSelectorMode = 'date'> = {
     disabledDates?: (Date | [Date, Date])[];
     /** Disables calendar and default-trigger interaction. */
     disabled?: boolean;
+    /** The calendar opens and browses, but choosing a date or preset is refused. */
+    readOnly?: boolean;
     /** Accessible label for the calendar. */
     calendarLabel?: string;
     /** Stable id for the selector popover. */

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

@@ -1,7 +1,131 @@
+<script lang="ts" module>
+	import type { Attachment } from 'svelte/attachments';
+	import { on } from 'svelte/events';
+	// Roles that take aria-required / aria-readonly (ARIA 1.2, plus slider from 1.3, which axe
+	// accepts). Native inputs keep their own `required` and `readonly` attributes instead.
+	const ARIA_REQUIRED_ROLES = new Set([
+		'checkbox',
+		'combobox',
+		'gridcell',
+		'listbox',
+		'radiogroup',
+		'searchbox',
+		'slider',
+		'spinbutton',
+		'switch',
+		'textbox',
+		'tree',
+		'treegrid'
+	]);
+	const ARIA_READONLY_ROLES = new Set([
+		'checkbox',
+		'combobox',
+		'grid',
+		'gridcell',
+		'listbox',
+		'radiogroup',
+		'searchbox',
+		'slider',
+		'spinbutton',
+		'switch',
+		'textbox',
+		'treegrid'
+	]);
+	// Input types whose native `readonly` attribute the browser honours.
+	const TEXT_ENTRY_INPUT_TYPES = new Set([
+		'date',
+		'datetime-local',
+		'email',
+		'month',
+		'number',
+		'password',
+		'search',
+		'tel',
+		'text',
+		'time',
+		'url',
+		'week'
+	]);
+	// Presses on these keep their own behaviour instead of focusing the field's control.
+	const INTERACTIVE =
+		'a[href], button, input, select, textarea, label, summary, [contenteditable]:not([contenteditable="false"]), [tabindex], [role="button"], [role="link"], [role="checkbox"], [role="switch"], [role="radio"], [role="slider"], [role="option"], [role="tab"], [role="menuitem"]';
+
+	const splitIds = (value: string | null) => value?.split(/\s+/).filter(Boolean) ?? [];
+
+	const acceptsNativeReadOnly = (element: Element) =>
+		element instanceof HTMLTextAreaElement ||
+		(element instanceof HTMLInputElement && TEXT_ENTRY_INPUT_TYPES.has(element.type));
+
+	const isTextEntry = (element: Element) =>
+		acceptsNativeReadOnly(element) || (element as HTMLElement).isContentEditable;
+
+	const roleOf = (element: Element): string | undefined => {
+		const explicit = splitIds(element.getAttribute('role'))[0];
+		if (explicit) return explicit;
+		if (element instanceof HTMLTextAreaElement) return 'textbox';
+		if (element instanceof HTMLSelectElement) {
+			return element.multiple || element.size > 1 ? 'listbox' : 'combobox';
+		}
+		if (element instanceof HTMLInputElement) {
+			if (element.type === 'checkbox') return 'checkbox';
+			if (element.type === 'range') return 'slider';
+			if (element.type === 'number') return 'spinbutton';
+			if (TEXT_ENTRY_INPUT_TYPES.has(element.type)) return 'textbox';
+		}
+		return undefined;
+	};
+
+	const isNativeFormControl = (element: Element) =>
+		element instanceof HTMLInputElement ||
+		element instanceof HTMLSelectElement ||
+		element instanceof HTMLTextAreaElement;
+
+	const restoreAttribute = (element: Element, name: string, value: string | null) => {
+		if (value === null) element.removeAttribute(name);
+		else element.setAttribute(name, value);
+	};
+
+	// Sets an attribute and returns its undo. A control's own template can write the same
+	// attribute (aria-readonly on Rating, aria-required on Switch); once that template removes it,
+	// the undo must not bring back a value this effect captured earlier, so it only restores
+	// while the attribute still holds what was set here.
+	const claimAttribute = (element: Element, name: string, value: string) => {
+		const initial = element.getAttribute(name);
+		element.setAttribute(name, value);
+		return () => {
+			if (element.getAttribute(name) === value) restoreAttribute(element, name, initial);
+		};
+	};
+
+	/**
+	 * Attachment for a label that is not a native <label> (labelFor={false}): clicking it focuses
+	 * the field's control without activating it, and leaves a text selection alone. A control that
+	 * renders its own label outside Field's label slot (Switch's inline label) attaches it too.
+	 */
+	export const focusFromLabel =
+		(field: { focusControl: () => boolean }): Attachment<HTMLElement> =>
+		(labelNode) =>
+			on(labelNode, 'click', (event) => {
+				if (event.defaultPrevented) return;
+				const target = event.target instanceof Element ? event.target : null;
+				const interactive = target?.closest(INTERACTIVE);
+				if (interactive && interactive !== labelNode && labelNode.contains(interactive)) return;
+				const selection = labelNode.ownerDocument.getSelection();
+				if (selection && !selection.isCollapsed && labelNode.contains(selection.anchorNode)) return;
+				field.focusControl();
+			});
+</script>
+
 <script lang="ts" generics="Type extends FieldType">
+	import { untrack } from 'svelte';
 	import Slot from '../../Slot/Slot.svelte';
+	import { presence } from '../../../utils/stateAttributes.js';
 	import type { FieldType, FieldProps } from './field.js';
-	import { useFieldTheme } from './field.theme.js';
+	import { easingBezierStrings } from '../../../transitions/easingFunctions.js';
+	import { prefersReducedMotion } from '../../../utils/motion.svelte.js';
+	import { provideFieldGroup } from './field.state.svelte.js';
+	import { useFieldMotion, useFieldTheme } from './field.theme.js';
+	import { fieldNativeForm, setFieldFormAttribute } from './fieldNativeForm.svelte.js';
 
 	let {
 		class: className = '',
@@ -22,12 +146,55 @@
 		theme,
 		field,
 		as = 'div',
+		anchor,
 		labelFor = field.id,
 		fieldAttrs,
+		form,
+		validationMode,
+		validationDebounce,
 		...attachments
 	}: FieldProps<Type> = $props();
 
+	// Controls forward their `validationMode` and `validationDebounce` props here.
+	$effect.pre(() => {
+		field.configureValidation({ mode: validationMode, debounce: validationDebounce });
+	});
+
+	// Hidden inputs rendered inside the field read the `form` prop through its controller.
+	untrack(() => setFieldFormAttribute(field, () => form));
+
+	// A fieldset Field is a group, like a FormGroup: a field rendered inside it shares its
+	// disabled and read-only state.
+	if (untrack(() => as) === 'fieldset') {
+		provideFieldGroup({
+			get disabled() {
+				return field.disabled;
+			},
+			get readOnly() {
+				return field.readOnly;
+			}
+		});
+	}
+
 	const classes = $derived(useFieldTheme(theme));
+	// Errors fade and grow in. The duration and easing come from the Theme's motion tokens, which
+	// are zero under reduced motion, so nothing animates then. Leaving is instant: a cleared error
+	// must not linger in the accessibility tree.
+	const resolveMotion = useFieldMotion();
+	const errorMotion = $derived(resolveMotion(theme?.motion));
+	const errorEnter: Attachment<HTMLElement> = (node) => {
+		const { duration, easing } = errorMotion.in;
+		if (!duration || prefersReducedMotion() || typeof node.animate !== 'function') return;
+		const height = node.offsetHeight;
+		const animation = node.animate(
+			[
+				{ opacity: 0, height: '0px', overflow: 'hidden' },
+				{ opacity: 1, height: `${height}px`, overflow: 'hidden' }
+			],
+			{ duration, easing: easingBezierStrings[easing ?? 'cubicOut'], fill: 'none' }
+		);
+		return () => animation.cancel();
+	};
 	const resolvedLabelPosition = $derived(
 		label || actions || header ? labelPosition : ('top' as const)
 	);
@@ -36,42 +203,66 @@
 		const control = field.node ?? field.rootNode;
 		if (!control) return;
 
-		const initialInvalid = control.getAttribute('aria-invalid');
 		const initialDescribedBy = control.getAttribute('aria-describedby');
 		const initialLabelledBy = control.getAttribute('aria-labelledby');
-		const currentDescribedByIds =
-			control.getAttribute('aria-describedby')?.split(/\s+/).filter(Boolean) ?? [];
-		let describedByIds = currentDescribedByIds.filter((id) => id !== field.errorId);
-		if (field.hasError) {
-			control.setAttribute('aria-invalid', 'true');
-			describedByIds = [...describedByIds, field.errorId];
-		}
+		const undo: (() => void)[] = [];
 
+		if (field.hasError) undo.push(claimAttribute(control, 'aria-invalid', 'true'));
+
+		// The app's own ids come first, then the description, the helper and the errors.
+		const fieldDescriptionIds = new Set([field.descriptionId, field.helperId, field.errorId]);
+		const describedByIds = [
+			...splitIds(initialDescribedBy).filter((id) => !fieldDescriptionIds.has(id)),
+			...field.describedBy
+		];
 		if (describedByIds.length === 0) control.removeAttribute('aria-describedby');
 		else control.setAttribute('aria-describedby', describedByIds.join(' '));
 
-		const currentLabelledByIds =
-			control.getAttribute('aria-labelledby')?.split(/\s+/).filter(Boolean) ?? [];
-		// A control that declared its own labelledby (Switch's inline label) keeps it; only the
-		// id this effect adds is subject to removal.
-		const ownedByControl = initialLabelledBy?.split(/\s+/).includes(field.labelId) ?? false;
-		let labelledByIds = currentLabelledByIds.filter((id) => id !== field.labelId || ownedByControl);
-		if (label && labelFor === false && as !== 'fieldset') {
-			labelledByIds = [...labelledByIds, field.labelId];
-		}
-
+		// A control that declared its own labelledby (Switch's inline label) keeps it, and the label
+		// id is listed once even then; only the id this effect adds is subject to removal. An
+		// aria-label on the control names it instead of the field label.
+		const labelledByIds = splitIds(initialLabelledBy);
+		const namedByControl = Boolean(control.getAttribute('aria-label')?.trim());
+		const linksLabel = label && labelFor === false && as !== 'fieldset' && !namedByControl;
+		if (linksLabel && !labelledByIds.includes(field.labelId)) labelledByIds.push(field.labelId);
 		if (labelledByIds.length === 0) control.removeAttribute('aria-labelledby');
 		else control.setAttribute('aria-labelledby', labelledByIds.join(' '));
 
+		// Native controls carry `required` themselves; a role-based control announces it.
+		const role = roleOf(control);
+		if (field.required && !isNativeFormControl(control) && role && ARIA_REQUIRED_ROLES.has(role)) {
+			undo.push(claimAttribute(control, 'aria-required', 'true'));
+		}
+		if (field.readOnly) {
+			if (acceptsNativeReadOnly(control)) undo.push(claimAttribute(control, 'readonly', ''));
+			else if (role && ARIA_READONLY_ROLES.has(role)) {
+				undo.push(claimAttribute(control, 'aria-readonly', 'true'));
+			}
+		}
+
 		return () => {
-			if (initialInvalid === null) control.removeAttribute('aria-invalid');
-			else control.setAttribute('aria-invalid', initialInvalid);
-			if (initialDescribedBy === null) control.removeAttribute('aria-describedby');
-			else control.setAttribute('aria-describedby', initialDescribedBy);
-			if (initialLabelledBy === null) control.removeAttribute('aria-labelledby');
-			else control.setAttribute('aria-labelledby', initialLabelledBy);
+			for (const restore of undo) restore();
+			restoreAttribute(control, 'aria-describedby', initialDescribedBy);
+			restoreAttribute(control, 'aria-labelledby', initialLabelledBy);
 		};
 	});
+
+	const labelClick: Attachment<HTMLElement> = (labelNode) => focusFromLabel(field)(labelNode);
+
+	// A press on the container around a text control (its padding, an icon, a chip) focuses the
+	// control instead of blurring it; buttons and other controls inside keep their own behaviour.
+	const focusFromContainer: Attachment<HTMLElement> = (container) =>
+		on(container, 'mousedown', (event) => {
+			if (event.button !== 0 || event.defaultPrevented || field.disabled) return;
+			const control = field.node;
+			const target = event.target;
+			if (!control || !(target instanceof Element) || !isTextEntry(control)) return;
+			if (control.contains(target)) return;
+			const interactive = target.closest(INTERACTIVE);
+			if (interactive && container.contains(interactive)) return;
+			event.preventDefault();
+			if (control.ownerDocument.activeElement !== control) control.focus();
+		});
 </script>
 
 <!-- Suffixed id: the bare field.id belongs to the control element, so <label for={field.id}>
@@ -79,6 +270,15 @@
 <svelte:element
 	this={as}
 	data-label-position={resolvedLabelPosition}
+	data-invalid={presence(field.hasError)}
+	data-disabled={presence(field.disabled)}
+	data-readonly={presence(field.readOnly)}
+	data-focused={presence(field.focused)}
+	data-filled={presence(field.filled)}
+	data-dirty={presence(field.dirty)}
+	data-touched={presence(field.touched)}
+	data-validating={presence(field.validating)}
+	{...as === 'fieldset' ? { disabled: field.disabled || undefined } : {}}
 	class={classes.root({
 		className,
 		density,
@@ -89,6 +289,7 @@
 	{...fieldAttrs}
 	id="{field.id}-field"
 	{...attachments}
+	{@attach fieldNativeForm(field)}
 >
 	{#if label || actions || header}
 		{#if as === 'fieldset'}
@@ -105,7 +306,12 @@
 			>
 				<Slot
 					as="span"
-					class={classes.label({ size, hasError: field.hasError, required: field.required })}
+					class={classes.label({
+						size,
+						hasError: field.hasError,
+						required: field.required,
+						disabled: field.disabled
+					})}
 					render={label}
 				/>
 				<Slot class={classes.actions({ density })} render={actions} />
@@ -123,8 +329,14 @@
 				<Slot
 					as={labelFor === false ? 'span' : 'label'}
 					attrs={labelFor === false ? { id: field.labelId } : { id: field.labelId, for: labelFor }}
-					class={classes.label({ size, hasError: field.hasError, required: field.required })}
+					class={classes.label({
+						size,
+						hasError: field.hasError,
+						required: field.required,
+						disabled: field.disabled
+					})}
 					render={label}
+					{@attach labelFor === false ? labelClick : undefined}
 				/>
 				<Slot class={classes.actions({ density })} render={actions} />
 			</Slot>
@@ -136,6 +348,8 @@
 			hasError: field.hasError,
 			labelPosition: resolvedLabelPosition
 		})}
+		{@attach focusFromContainer}
+		{@attach anchor}
 	>
 		<Slot render={prefix} class={classes.prefix({ density })} />
 		{@render children()}
@@ -143,15 +357,27 @@
 	</div>
 	{#if description || helper || footer}
 		<Slot render={footer} class={classes.footer({ density, labelPosition: resolvedLabelPosition })}>
-			<Slot class={classes.description({ size })} render={description} />
-			<Slot class={classes.helper({ size })} render={helper} />
+			<Slot
+				class={classes.description({ size, disabled: field.disabled })}
+				render={description}
+				attrs={{ id: field.descriptionId }}
+				{@attach field.descriptionPart}
+			/>
+			<Slot
+				class={classes.helper({ size, disabled: field.disabled })}
+				render={helper}
+				attrs={{ id: field.helperId }}
+				{@attach field.helperPart}
+			/>
 		</Slot>
 	{/if}
 	{#if field.hasError}
+		<!-- One live-region model: an alert, announced when the errors appear. -->
 		<Slot
 			render={errorsContainer}
 			class={classes.errorsContainer({ size, labelPosition: resolvedLabelPosition })}
-			attrs={{ id: field.errorId, role: 'alert', 'aria-live': 'polite' }}
+			attrs={{ id: field.errorId, role: 'alert' }}
+			{@attach errorEnter}
 		>
 			{#each field.errorMessages as err, index (index)}
 				<Slot render={error} class={classes.error({ size })}>

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

@@ -1,3 +1,12 @@
+import type { Attachment } from 'svelte/attachments';
+/**
+ * Attachment for a label that is not a native <label> (labelFor={false}): clicking it focuses
+ * the field's control without activating it, and leaves a text selection alone. A control that
+ * renders its own label outside Field's label slot (Switch's inline label) attaches it too.
+ */
+export declare const focusFromLabel: (field: {
+    focusControl: () => boolean;
+}) => Attachment<HTMLElement>;
 import type { FieldType, FieldProps } from './field.js';
 declare function $$render<Type extends FieldType>(): {
     props: FieldProps<Type>;

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

@@ -0,0 +1,29 @@
+<script lang="ts">
+	// Renderless provider: every field rendered inside shares the group's disabled and read-only
+	// state (combined with any group around it). Form uses it for FormGroup fieldsets.
+	import type { Snippet } from 'svelte';
+	import { provideFieldGroup } from './field.state.svelte.js';
+
+	let {
+		disabled = false,
+		readOnly = false,
+		children
+	}: {
+		/** Disables every field inside the group. */
+		disabled?: boolean;
+		/** Makes every field inside the group read-only. */
+		readOnly?: boolean;
+		children: Snippet;
+	} = $props();
+
+	provideFieldGroup({
+		get disabled() {
+			return disabled;
+		},
+		get readOnly() {
+			return readOnly;
+		}
+	});
+</script>
+
+{@render children()}

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

@@ -0,0 +1,11 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    /** Disables every field inside the group. */
+    disabled?: boolean;
+    /** Makes every field inside the group read-only. */
+    readOnly?: boolean;
+    children: Snippet;
+};
+declare const FieldGroup: import("svelte").Component<$$ComponentProps, {}, "">;
+type FieldGroup = ReturnType<typeof FieldGroup>;
+export default FieldGroup;