entasis 0.10.2 → 0.12.0

package/dist/components/Form/KeyValueInput/KeyValueInput.svelte

@@ -28,6 +28,8 @@
 		i18n,
 		theme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		onValueChange,
@@ -88,6 +90,12 @@
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
@@ -126,10 +134,12 @@
 	});
 
 	const atMaxRows = $derived(maxRows !== undefined && rows.length >= maxRows);
+	// Rows keep their own text, so a read-only field locks them rather than refusing edits late.
+	const locked = $derived(field.disabled || field.readOnly);
 
 	// Append a fresh empty row. Never mutates the array in place.
 	const addRow = async () => {
-		if (disabled || atMaxRows) return;
+		if (locked || atMaxRows) return;
 
 		const row = { id: nextId(), key: '', value: '' };
 		rows = [...rows, row];
@@ -139,7 +149,7 @@
 
 	// Remove a row by id. Never mutates the array in place; early-returns when disabled.
 	const removeRow = (rowId: string) => {
-		if (disabled) return;
+		if (locked) return;
 		rows = rows.filter((row) => row.id !== rowId);
 	};
 
@@ -270,8 +280,9 @@
 					bind:value={row.key}
 					{@attach (node) => registerInput(row.id, 'key', node)}
 					placeholder={keyPlaceholder ?? t.keyLabel}
-					{disabled}
-					class={classes.input({ size, disabled })}
+					disabled={field.disabled}
+					readonly={field.readOnly}
+					class={classes.input({ size, disabled: field.disabled })}
 					onkeydown={(event) => handleKeydown(event, row, 'key')}
 				/>
 				<input
@@ -281,15 +292,16 @@
 					bind:value={row.value}
 					{@attach (node) => registerInput(row.id, 'value', node)}
 					placeholder={valuePlaceholder ?? t.valueLabel}
-					{disabled}
-					class={classes.input({ size, disabled })}
+					disabled={field.disabled}
+					readonly={field.readOnly}
+					class={classes.input({ size, disabled: field.disabled })}
 					onkeydown={(event) => handleKeydown(event, row, 'value')}
 				/>
 				<button
 					type="button"
 					aria-label={t.remove(row.key || t.keyLabel)}
-					{disabled}
-					class={classes.removeButton({ size, disabled })}
+					disabled={locked}
+					class={classes.removeButton({ size, disabled: locked })}
 					onclick={() => removeRow(row.id)}
 				>
 					{@render xIcon({ size: 16 })}
@@ -299,8 +311,8 @@
 	</ul>
 	<button
 		type="button"
-		disabled={disabled || atMaxRows}
-		class={classes.addButton({ size, disabled: disabled || atMaxRows })}
+		disabled={locked || atMaxRows}
+		class={classes.addButton({ size, disabled: locked || atMaxRows })}
 		onclick={() => void addRow()}
 	>
 		{@render plusIcon({ size: 16 })}

package/dist/components/Form/KeyValueInput/keyValueInput.mcp.d.ts

@@ -1 +1 @@
-export declare const keyValueInputDescription = "\n# KeyValueInput Component\n\nAn editable list of key/value string pairs. Each row renders a key text input, a value text input, and a remove button; a full-width Add button below the rows appends a new empty pair. There is no dropdown, no async, and no option list \u2014 just plain text entry.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { KeyValueInput } from 'entasis/key-value-input';\n\tlet value = $state(null);\n</script>\n\n<KeyValueInput bind:value={value} />\n```\n\n## Props\n\n### Core Props\n\n- **value**: `KeyValuePair[] | null` (default: `null`, bindable)\n  - The current list of `{ key, value }` pairs. `null` is treated as an empty list.\n  - The array is never mutated in place \u2014 every add/remove assigns a fresh array.\n  - Replacing `value` updates the editor rows without emitting `onValueChange`. Use `defaultValue` to initialize an uncontrolled editor once.\n\n### Content Props\n\n- **keyPlaceholder**: `string` (optional)\n  - Placeholder for the key input. Defaults to the localized \"Key\" label.\n\n- **valuePlaceholder**: `string` (optional)\n  - Placeholder for the value input. Defaults to the localized \"Value\" label.\n\n- **addLabel**: `string` (optional)\n  - Label for the Add button. Defaults to the localized \"Add\" label.\n\n### Behavior Props\n\n- **maxRows**: `number` (optional)\n  - Maximum number of rows. Once reached, the Add button is disabled. There is no minimum.\n\n### Field Props\n\n- **required**: `boolean` (default: `false`)\n- **disabled**: `boolean`\n- **size**: `'small' | 'normal' | 'large'` (default: `'normal'`)\n- **name**: `string`\n- **errors**: `string[] | boolean` (bindable)\n- **focused**: `boolean` (bindable)\n- **description**: `string`\n\n### Event Props\n\n- **onValueChange**: `(value: KeyValuePair[]) => void`\n  - Called when the pairs change.\n\n- **onValidate**: `(value: KeyValuePair[]) => string[] | boolean`\n  - Custom validation function.\n\n### i18n / Theme Props\n\n- **i18n**: `Partial<Messages>`\n  - Per-instance message overrides merged over the global catalog (`add`, `keyLabel`, `valueLabel`, `remove`).\n\n- **theme**: `KeyValueInputThemeProps`\n  - Customize styling for: inputContainer, row, input, removeButton, addButton.\n\n## Examples\n\n### Empty (Start With Add)\n\n```svelte\n<script>\n\tlet value = $state(null);\n</script>\n\n<KeyValueInput bind:value={value} />\n```\n\n### Pre-filled Value\n\n```svelte\n<script>\n\tlet value = $state([\n\t\t{ key: 'Content-Type', value: 'application/json' },\n\t\t{ key: 'Accept', value: '*/*' }\n\t]);\n</script>\n\n<KeyValueInput bind:value={value} />\n```\n\n### Limited Number of Rows\n\n```svelte\n<KeyValueInput maxRows={3} bind:value={value} />\n```\n\n### Custom Placeholders\n\n```svelte\n<KeyValueInput keyPlaceholder=\"Header\" valuePlaceholder=\"Value\" addLabel=\"Add header\" bind:value={value} />\n```\n\n### Object Output\n\nThe value is an array of pairs; convert it to a plain object with `Object.fromEntries`:\n\n```svelte\n<script>\n\tlet value = $state([{ key: 'a', value: '1' }]);\n\tconst object = $derived(Object.fromEntries((value ?? []).map((p) => [p.key, p.value])));\n</script>\n\n<KeyValueInput bind:value={value} />\n<pre>{JSON.stringify(object)}</pre>\n```\n\n## Keyboard Interactions\n\n- **Enter** (in a non-empty value input): Prevents the enclosing form from submitting, appends a new empty row, and focuses its key input.\n- **Enter** (in a key or empty value input): Prevents the enclosing form from submitting without adding a row.\n- **Arrow Right** (at the end of an input): Moves to the next input and places the caret at its start.\n- **Arrow Left** (at the start of an input): Moves to the previous input and places the caret at its end.\n- **Arrow Up / Arrow Down**: Moves to the same field in the previous or next row while preserving the caret offset when possible.\n- **Backspace** (in an empty input): Moves to the previous input. When the entire row is empty, removes the row and focuses the previous row's value input when available.\n\n## Accessibility\n\n- The rows collection is a real list (`role=\"list\"` / `role=\"listitem\"`), not a listbox.\n- Each row's remove control is a real `<button type=\"button\">` with an `aria-label` of \"Remove <key>\" (falling back to the \"Key\" label when the key is empty).\n- The Add button is a real `<button type=\"button\">`.\n- Inputs use `autocomplete=\"off\"` and `data-1p-ignore`.\n\n## Notes\n\n- **Stable-id keying**: Rows are keyed by a stable per-instance uid, not by the key string. Keys can be empty or duplicated while typing, and duplicate/empty keys in a keyed `{#each}` would crash the renderer.\n- **Controlled values**: Parent value replacements update the editor. User edits publish one change callback; unchanged pairs do not publish another callback.\n- **Fresh arrays**: Add and remove always assign a new array so binding, reactivity, and form updates fire correctly.\n- **Animations**: Rows animate on reorder (`animate:flip`) and on enter/leave (`transition:scale`).\n- **maxRows**: Disables the Add button once the row count reaches `maxRows`.\n- **Object output**: Use `Object.fromEntries((value ?? []).map((p) => [p.key, p.value]))` to get a plain object.\n\n## Theme Customization\n\nThe KeyValueInput uses a theme object customizable via the `theme` prop or a global theme.\n\n### Theme Structure\n\n- **inputContainer**: The vertical stack holding the rows and Add button (no border/background of its own).\n- **row**: The animated flex wrapper around each key/value/remove trio.\n- **input**: The bordered key and value text inputs.\n- **removeButton**: The square remove (X) button.\n- **addButton**: The full-width Add button.\n\n### Global Theme Setting\n\n```svelte\n<script>\n\timport { setKeyValueInputTheme } from 'entasis/key-value-input';\n\n\tsetKeyValueInputTheme({\n\t\taddButton: {\n\t\t\tbase: 'rounded-lg border-2'\n\t\t}\n\t});\n</script>\n```\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 keyValueInputDescription = "\n# KeyValueInput Component\n\nAn editable list of key/value string pairs. Each row renders a key text input, a value text input, and a remove button; a full-width Add button below the rows appends a new empty pair. There is no dropdown, no async, and no option list \u2014 just plain text entry.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { KeyValueInput } from 'entasis/key-value-input';\n\tlet value = $state(null);\n</script>\n\n<KeyValueInput bind:value={value} />\n```\n\n## Props\n\n### Core Props\n\n- **value**: `KeyValuePair[] | null` (default: `null`, bindable)\n  - The current list of `{ key, value }` pairs. `null` is treated as an empty list.\n  - The array is never mutated in place \u2014 every add/remove assigns a fresh array.\n  - Replacing `value` updates the editor rows without emitting `onValueChange`. Use `defaultValue` to initialize an uncontrolled editor once.\n\n### Content Props\n\n- **keyPlaceholder**: `string` (optional)\n  - Placeholder for the key input. Defaults to the localized \"Key\" label.\n\n- **valuePlaceholder**: `string` (optional)\n  - Placeholder for the value input. Defaults to the localized \"Value\" label.\n\n- **addLabel**: `string` (optional)\n  - Label for the Add button. Defaults to the localized \"Add\" label.\n\n### Behavior Props\n\n- **maxRows**: `number` (optional)\n  - Maximum number of rows. Once reached, the Add button is disabled. There is no minimum.\n\n### Field Props\n\n- **required**: `boolean` (default: `false`)\n- **disabled**: `boolean`\n- **readOnly**: `boolean` - Rows stay focusable and readable but cannot be edited, added or removed; the value still validates and submits\n- **size**: `'small' | 'normal' | 'large'` (default: `'normal'`)\n- **name**: `string`\n- **errors**: `string[] | boolean` (bindable)\n- **focused**: `boolean` (bindable)\n- **description**: `string`\n\n### Event Props\n\n- **onValueChange**: `(value: KeyValuePair[]) => void`\n  - Called when the pairs change.\n\n- **onValidate**: `(value: KeyValuePair[]) => string[] | boolean`\n  - Custom validation function.\n\n### i18n / Theme Props\n\n- **i18n**: `Partial<Messages>`\n  - Per-instance message overrides merged over the global catalog (`add`, `keyLabel`, `valueLabel`, `remove`).\n\n- **theme**: `KeyValueInputThemeProps`\n  - Customize styling for: inputContainer, row, input, removeButton, addButton.\n\n## Examples\n\n### Empty (Start With Add)\n\n```svelte\n<script>\n\tlet value = $state(null);\n</script>\n\n<KeyValueInput bind:value={value} />\n```\n\n### Pre-filled Value\n\n```svelte\n<script>\n\tlet value = $state([\n\t\t{ key: 'Content-Type', value: 'application/json' },\n\t\t{ key: 'Accept', value: '*/*' }\n\t]);\n</script>\n\n<KeyValueInput bind:value={value} />\n```\n\n### Limited Number of Rows\n\n```svelte\n<KeyValueInput maxRows={3} bind:value={value} />\n```\n\n### Custom Placeholders\n\n```svelte\n<KeyValueInput keyPlaceholder=\"Header\" valuePlaceholder=\"Value\" addLabel=\"Add header\" bind:value={value} />\n```\n\n### Object Output\n\nThe value is an array of pairs; convert it to a plain object with `Object.fromEntries`:\n\n```svelte\n<script>\n\tlet value = $state([{ key: 'a', value: '1' }]);\n\tconst object = $derived(Object.fromEntries((value ?? []).map((p) => [p.key, p.value])));\n</script>\n\n<KeyValueInput bind:value={value} />\n<pre>{JSON.stringify(object)}</pre>\n```\n\n## Keyboard Interactions\n\n- **Enter** (in a non-empty value input): Prevents the enclosing form from submitting, appends a new empty row, and focuses its key input.\n- **Enter** (in a key or empty value input): Prevents the enclosing form from submitting without adding a row.\n- **Arrow Right** (at the end of an input): Moves to the next input and places the caret at its start.\n- **Arrow Left** (at the start of an input): Moves to the previous input and places the caret at its end.\n- **Arrow Up / Arrow Down**: Moves to the same field in the previous or next row while preserving the caret offset when possible.\n- **Backspace** (in an empty input): Moves to the previous input. When the entire row is empty, removes the row and focuses the previous row's value input when available.\n\n## Accessibility\n\n- The rows collection is a real list (`role=\"list\"` / `role=\"listitem\"`), not a listbox.\n- Each row's remove control is a real `<button type=\"button\">` with an `aria-label` of \"Remove <key>\" (falling back to the \"Key\" label when the key is empty).\n- The Add button is a real `<button type=\"button\">`.\n- Inputs use `autocomplete=\"off\"` and `data-1p-ignore`.\n\n## Notes\n\n- **Stable-id keying**: Rows are keyed by a stable per-instance uid, not by the key string. Keys can be empty or duplicated while typing, and duplicate/empty keys in a keyed `{#each}` would crash the renderer.\n- **Controlled values**: Parent value replacements update the editor. User edits publish one change callback; unchanged pairs do not publish another callback.\n- **Fresh arrays**: Add and remove always assign a new array so binding, reactivity, and form updates fire correctly.\n- **Animations**: Rows animate on reorder (`animate:flip`) and on enter/leave (`transition:scale`).\n- **maxRows**: Disables the Add button once the row count reaches `maxRows`.\n- **Object output**: Use `Object.fromEntries((value ?? []).map((p) => [p.key, p.value]))` to get a plain object.\n\n## Theme Customization\n\nThe KeyValueInput uses a theme object customizable via the `theme` prop or a global theme.\n\n### Theme Structure\n\n- **inputContainer**: The vertical stack holding the rows and Add button (no border/background of its own).\n- **row**: The animated flex wrapper around each key/value/remove trio.\n- **input**: The bordered key and value text inputs.\n- **removeButton**: The square remove (X) button.\n- **addButton**: The full-width Add button.\n\n### Global Theme Setting\n\n```svelte\n<script>\n\timport { setKeyValueInputTheme } from 'entasis/key-value-input';\n\n\tsetKeyValueInputTheme({\n\t\taddButton: {\n\t\t\tbase: 'rounded-lg border-2'\n\t\t}\n\t});\n</script>\n```\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/KeyValueInput/keyValueInput.mcp.js

@@ -43,6 +43,7 @@ An editable list of key/value string pairs. Each row renders a key text input, a
 
 - **required**: \`boolean\` (default: \`false\`)
 - **disabled**: \`boolean\`
+- **readOnly**: \`boolean\` - Rows stay focusable and readable but cannot be edited, added or removed; the value still validates and submits
 - **size**: \`'small' | 'normal' | 'large'\` (default: \`'normal'\`)
 - **name**: \`string\`
 - **errors**: \`string[] | boolean\` (bindable)

package/dist/components/Form/MultiStepForm/MultiStepForm.svelte

@@ -36,7 +36,9 @@
 		submitButtonProps = {},
 		defaultValue = {},
 		value = $bindable(),
-		onValueChange
+		onValueChange,
+		validationMode,
+		validationDebounce
 	}: MultiStepFormProps<I> = $props();
 	const valueState = createBindableValue(
 		() => value,
@@ -127,7 +129,7 @@
 		class={classes.multiStepFormHeader({ variant })}
 	>
 		{#if showMeter}
-			<Meter value={[form.progress]} steps={form.meterSteps} />
+			<Meter value={[form.progress]} />
 		{/if}
 	</Slot>
 	<div class={classes.multiStepFormContent()}>
@@ -142,7 +144,7 @@
 					<FormCardSurfaceBoundary isOwned={isCard}>
 						<Form
 							inputs={item.inputs}
-							onSubmit={() => form.submit()}
+							onSubmit={(stepValue) => form.submitStep(index, stepValue)}
 							bind:form={() => form.getForm(index), (nextForm) => form.setForm(index, nextForm)}
 							bind:value={
 								() => form.getStepValue(index), (nextValue) => form.setStepValue(index, nextValue)
@@ -151,6 +153,8 @@
 							title={item.title}
 							description={item.description}
 							{variant}
+							{validationMode}
+							{validationDebounce}
 							theme={formTheme}
 						/>
 					</FormCardSurfaceBoundary>
@@ -160,10 +164,13 @@
 		{@render children?.(form)}
 	</div>
 	<Slot render={footer} payload={form} class={classes.multiStepFormFooter({ variant })}>
+		<!-- A submitting form marks its buttons `loading`, never natively `disabled`: the pressed
+		     button keeps keyboard focus instead of dropping it to the page body, and Button still
+		     refuses activation while loading. -->
 		<Button
 			{...previousButton.forwardedProps}
 			prefix={arrowLeftIcon}
-			disabled={form.activeStep === 0 || form.loading || previousButton.disabled}
+			disabled={form.activeStep === 0 || previousButton.disabled}
 			loading={form.loading || previousButton.loading}
 			onclick={goToPreviousStep}
 		>
@@ -172,7 +179,7 @@
 		<Button
 			{...activeButton.forwardedProps}
 			suffix={form.isLastStep ? arrowCircleUpIcon : arrowRightIcon}
-			disabled={form.loading || activeButton.disabled}
+			disabled={activeButton.disabled}
 			loading={form.loading || activeButton.loading}
 			onclick={submitCurrentStep}
 		>

package/dist/components/Form/MultiStepForm/multiStepForm.mcp.d.ts

@@ -1 +1 @@
-export declare const multiStepFormDescription = "\n# MultiStepForm\n\nMultiStepForm owns one Form per step, displays them through Stepper, validates visited steps before navigation, and validates every step before final submission. Field names must be unique across steps.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n\timport {\n\t\tMultiStepForm,\n\t\ttype FormStep,\n\t\ttype MergedMultiStepFormInputs\n\t} from 'entasis/multi-step-form';\n\timport type { FormInputs, InferFormValue, LiveFormValue } from 'entasis/form';\n\n\tconst accountInputs = {\n\t\tname: { type: 'text', label: 'Name', required: true },\n\t\temail: { type: 'email', label: 'Email', required: true }\n\t} satisfies FormInputs;\n\tconst preferenceInputs = {\n\t\tnewsletter: { type: 'switch', label: 'Newsletter' }\n\t} satisfies FormInputs;\n\n\tconst items: [\n\t\tFormStep<typeof accountInputs>,\n\t\tFormStep<typeof preferenceInputs>\n\t] = [\n\t\t{\n\t\t\ttitle: 'Account',\n\t\t\tinputs: accountInputs\n\t\t},\n\t\t{\n\t\t\ttitle: 'Preferences',\n\t\t\tinputs: preferenceInputs\n\t\t}\n\t];\n\n\ttype Inputs = MergedMultiStepFormInputs<typeof items>;\n\tlet value = $state<LiveFormValue<Inputs>>({});\n\tlet submitted = $state<InferFormValue<Inputs> | null>(null);\n</script>\n\n<MultiStepForm\n\t{items}\n\tbind:value\n\tonSubmitForm={(validatedValue) => {\n\t\tsubmitted = validatedValue;\n\t}}\n/>\n```\n\n## Props\n\n- **items** (required): ordered FormStep array. Duplicate field names across steps throw.\n- **value** (bindable): controlled partial values merged across all steps, synchronized in both directions.\n- **defaultValue**: initial merged values when value is omitted.\n- **onValueChange**: called when the merged live value changes.\n- **onSubmitForm**: called with the validated merged payload on the final step only.\n- **onSubmitStep**: receives one `{ value, step, index }` payload after the step's onBeforeChange. `value` contains validated values from visited steps; unvisited keys remain optional. Return false to block advancing.\n- **showMeter**: whether to render the progress meter. Defaults to true.\n- **meterColor**: meter color token. Defaults to neutral.\n- **previousText**, **nextText**, **submitText**: navigation labels.\n- **variant**: visual presentation of the multi-step shell. Card renders one shared Card surface around the fixed meter, transitioning step content, and navigation footer. Header, meter, step fields, and footer share one horizontal inset in every variant. Each step reuses Form's card spacing and edge-to-edge separator rules without creating another Card surface. Supports plain, sectioned, and card; defaults to plain.\n- **previousButtonProps**, **nextButtonProps**, **submitButtonProps**: Button props. Custom click handlers are composed with internal behavior; disabled and loading protection cannot be overridden.\n- **class**: additional classes on the root.\n- **theme**: MultiStepForm theme overrides plus optional nested form theme overrides.\n\nThe **header**, **children**, and **footer** snippets receive the MultiStepFormState instance directly. Supplying a header or footer replaces that region's default meter or controls. In the card variant, header and footer content remains inside the shared card while only the active step content transitions.\n\n## FormStep\n\n```ts\ntype FormStep<I extends FormInputs> = {\n\ttitle?: string;\n\tdescription?: string;\n\tinputs: I;\n\tonBeforeChange?: (context: {\n\t\tvalue: InferFormValue<I>;\n\t\tform: FormState<I>;\n\t\tnext: () => void;\n\t}) => void | Promise<void>;\n};\n```\n\nWhen onBeforeChange is present, navigation remains blocked unless the hook calls next(). After permission is granted, onSubmitStep may still block by returning false.\n\n## Submission behavior\n\n- Next validates every visited step. Hooks do not run and the active step does not change when validation fails.\n- Final submission validates every step before calling onSubmitForm; partial invalid data is never submitted.\n- Enter follows Form's field-navigation behavior. A terminal Enter validates the current and visited steps, advances when permitted, and submits from the final step.\n- Rejected hooks and submit handlers propagate their errors, while loading always resets.\n- Concurrent calls to submit() share one active promise.\n\n## MultiStepFormState\n\n- **steps**: current step definitions.\n- **stepper**: bound Stepper state, including value, next(), and previous().\n- **value**: merged live partial value.\n- **loading**: true while a navigation or final-submit hook is pending.\n- **isLastStep**: whether the current step is final.\n- **progress** and **meterSteps**: values used by the default meter.\n- **submit()**: validates and advances or submits, returning the validated visited-step payload or false. The final-step result is the complete validated payload.\n";
+export declare const multiStepFormDescription = "\n# MultiStepForm\n\nMultiStepForm owns one Form per step, displays them through Stepper, validates visited steps before navigation, and validates every step before final submission. Field names must be unique across steps.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n\timport {\n\t\tMultiStepForm,\n\t\ttype FormStep,\n\t\ttype MergedMultiStepFormInputs\n\t} from 'entasis/multi-step-form';\n\timport type { FormInputs, InferFormValue, LiveFormValue } from 'entasis/form';\n\n\tconst accountInputs = {\n\t\tname: { type: 'text', label: 'Name', required: true },\n\t\temail: { type: 'email', label: 'Email', required: true }\n\t} satisfies FormInputs;\n\tconst preferenceInputs = {\n\t\tnewsletter: { type: 'switch', label: 'Newsletter' }\n\t} satisfies FormInputs;\n\n\tconst items: [\n\t\tFormStep<typeof accountInputs>,\n\t\tFormStep<typeof preferenceInputs>\n\t] = [\n\t\t{\n\t\t\ttitle: 'Account',\n\t\t\tinputs: accountInputs\n\t\t},\n\t\t{\n\t\t\ttitle: 'Preferences',\n\t\t\tinputs: preferenceInputs\n\t\t}\n\t];\n\n\ttype Inputs = MergedMultiStepFormInputs<typeof items>;\n\tlet value = $state<LiveFormValue<Inputs>>({});\n\tlet submitted = $state<InferFormValue<Inputs> | null>(null);\n</script>\n\n<MultiStepForm\n\t{items}\n\tbind:value\n\tonSubmitForm={(validatedValue) => {\n\t\tsubmitted = validatedValue;\n\t}}\n/>\n```\n\n## Props\n\n- **items** (required): ordered FormStep array. Duplicate field names across steps throw.\n- **value** (bindable): controlled partial values merged across all steps, synchronized in both directions.\n- **defaultValue**: initial merged values when value is omitted.\n- **onValueChange**: called when the merged live value changes.\n- **onSubmitForm**: called with the validated merged payload on the final step only.\n- **onSubmitStep**: receives one `{ value, step, index }` payload after the step's onBeforeChange. `value` contains validated values from visited steps; unvisited keys remain optional. Return false to block advancing.\n- **showMeter**: whether to render the progress meter. Defaults to true.\n- **meterColor**: meter color token. Defaults to neutral.\n- **previousText**, **nextText**, **submitText**: navigation labels.\n- **variant**: visual presentation of the multi-step shell. Card renders one shared Card surface around the fixed meter, transitioning step content, and navigation footer. Header, meter, step fields, and footer share one horizontal inset in every variant. Each step reuses Form's card spacing and edge-to-edge separator rules without creating another Card surface. Supports plain, sectioned, and card; defaults to plain.\n- **validationMode**, **validationDebounce**: when fields validate by themselves, for every step; see Form.\n- **previousButtonProps**, **nextButtonProps**, **submitButtonProps**: Button props. Custom click handlers are composed with internal behavior; disabled and loading protection cannot be overridden. While a step submits the buttons are marked loading, never natively disabled, so the pressed button keeps keyboard focus.\n- **class**: additional classes on the root.\n- **theme**: MultiStepForm theme overrides plus optional nested form theme overrides.\n\nThe **header**, **children**, and **footer** snippets receive the MultiStepFormState instance directly. Supplying a header or footer replaces that region's default meter or controls. In the card variant, header and footer content remains inside the shared card while only the active step content transitions.\n\n## FormStep\n\n```ts\ntype FormStep<I extends FormInputs> = {\n\ttitle?: string;\n\tdescription?: string;\n\tinputs: I;\n\tonBeforeChange?: (context: {\n\t\tvalue: InferFormValue<I>;\n\t\tform: FormState<I>;\n\t\tnext: () => void;\n\t}) => void | Promise<void>;\n};\n```\n\nWhen onBeforeChange is present, navigation remains blocked unless the hook calls next(). After permission is granted, onSubmitStep may still block by returning false.\n\n## Submission behavior\n\n- Next validates every visited step, and waits for async validators (the buttons show a spinner meanwhile). Hooks do not run and the active step does not change when validation fails.\n- Disabled fields skip validation and are left out of the merged payload.\n- Final submission validates every step before calling onSubmitForm; partial invalid data is never submitted.\n- Enter follows Form's field-navigation behavior. A terminal Enter validates the current and visited steps, advances when permitted, and submits from the final step.\n- Rejected hooks and submit handlers propagate their errors, while loading always resets.\n- Concurrent calls to submit() share one active promise.\n\n## MultiStepFormState\n\n- **steps**: current step definitions.\n- **stepper**: bound Stepper state, including value, next(), and previous().\n- **value**: merged live partial value.\n- **loading**: true while async validators or a navigation or final-submit hook is pending.\n- **isLastStep**: whether the current step is final.\n- **progress** and **meterSteps**: values used by the default meter.\n- **submit()**: validates and advances or submits, returning the validated visited-step payload or false. The final-step result is the complete validated payload.\n";

package/dist/components/Form/MultiStepForm/multiStepForm.mcp.js

@@ -62,7 +62,8 @@ MultiStepForm owns one Form per step, displays them through Stepper, validates v
 - **meterColor**: meter color token. Defaults to neutral.
 - **previousText**, **nextText**, **submitText**: navigation labels.
 - **variant**: visual presentation of the multi-step shell. Card renders one shared Card surface around the fixed meter, transitioning step content, and navigation footer. Header, meter, step fields, and footer share one horizontal inset in every variant. Each step reuses Form's card spacing and edge-to-edge separator rules without creating another Card surface. Supports plain, sectioned, and card; defaults to plain.
-- **previousButtonProps**, **nextButtonProps**, **submitButtonProps**: Button props. Custom click handlers are composed with internal behavior; disabled and loading protection cannot be overridden.
+- **validationMode**, **validationDebounce**: when fields validate by themselves, for every step; see Form.
+- **previousButtonProps**, **nextButtonProps**, **submitButtonProps**: Button props. Custom click handlers are composed with internal behavior; disabled and loading protection cannot be overridden. While a step submits the buttons are marked loading, never natively disabled, so the pressed button keeps keyboard focus.
 - **class**: additional classes on the root.
 - **theme**: MultiStepForm theme overrides plus optional nested form theme overrides.
 
@@ -87,7 +88,8 @@ When onBeforeChange is present, navigation remains blocked unless the hook calls
 
 ## Submission behavior
 
-- Next validates every visited step. Hooks do not run and the active step does not change when validation fails.
+- Next validates every visited step, and waits for async validators (the buttons show a spinner meanwhile). Hooks do not run and the active step does not change when validation fails.
+- Disabled fields skip validation and are left out of the merged payload.
 - Final submission validates every step before calling onSubmitForm; partial invalid data is never submitted.
 - Enter follows Form's field-navigation behavior. A terminal Enter validates the current and visited steps, advances when permitted, and submits from the final step.
 - Rejected hooks and submit handlers propagate their errors, while loading always resets.
@@ -98,7 +100,7 @@ When onBeforeChange is present, navigation remains blocked unless the hook calls
 - **steps**: current step definitions.
 - **stepper**: bound Stepper state, including value, next(), and previous().
 - **value**: merged live partial value.
-- **loading**: true while a navigation or final-submit hook is pending.
+- **loading**: true while async validators or a navigation or final-submit hook is pending.
 - **isLastStep**: whether the current step is final.
 - **progress** and **meterSteps**: values used by the default meter.
 - **submit()**: validates and advances or submits, returning the validated visited-step payload or false. The final-step result is the complete validated payload.

package/dist/components/Form/MultiStepForm/multiStepForm.props.d.ts

@@ -4,6 +4,7 @@ import type { Snippet } from 'svelte';
 import type { FlattenFormInputs, FormInputs, FormInputsWithState, InferFormValue, LiveFormValue } from '../Form/form.js';
 import type { FormState } from '../Form/form.state.svelte.js';
 import type { FormProps } from '../Form/form.props.js';
+import type { ValidationMode } from '../Field/field.state.svelte.js';
 import type { MultiStepFormState } from './multiStepForm.state.svelte.js';
 import type { MultiStepFormThemeProps } from './multiStepForm.theme.js';
 import type { ButtonProps } from '../../Button/index.js';
@@ -71,6 +72,10 @@ export type MultiStepFormProps<I extends MultiStepFormItems = FormStep[]> = With
         /** Theme overrides passed to each step Form component. */
         form?: FormProps<FormInputs>['theme'];
     };
+    /** When fields validate by themselves; see `Form`. Applies to every step. */
+    validationMode?: ValidationMode;
+    /** Milliseconds an edit waits before the validation it triggers; see `Form`. */
+    validationDebounce?: number;
     /** Props spread onto the previous-step button. */
     previousButtonProps?: ButtonProps;
     /** Props spread onto the next-step button. */