entasis 0.13.3 → 0.13.5

package/dist/components/Code/Code.svelte

@@ -108,8 +108,13 @@
 	{/if}
 
 	<!-- ScrollArea owns both axes: horizontal (long lines) natively, vertical when maxHeight caps
-	     the height. Its viewport is the focusable native scroll region (keyboard + focus ring). -->
-	<ScrollArea type="hover" class="flex max-h-[var(--code-max-height)] flex-col rounded-b-lg">
+	     the height or a height-bound flex column (a Dialog body) shrinks the block: `min-h-0` lets
+	     it shrink below its content, so it scrolls under the kept header instead of the root
+	     clipping its last lines. Its viewport is the focusable native scroll region. -->
+	<ScrollArea
+		type="hover"
+		class="flex max-h-[var(--code-max-height)] min-h-0 flex-col rounded-b-lg"
+	>
 		{@render codeBody()}
 	</ScrollArea>
 

package/dist/components/Code/CodeTheme.svelte

@@ -52,11 +52,22 @@
 		--code-token-property: color-mix(in oklab, var(--color-info) 70%, var(--color-neutral));
 	}
 
-	/* The pre stays transparent so the container background shows through. */
+	/* The pre stays transparent so the container background shows through. Code owns its layout
+	   too: an app stylesheet may style every `pre.th-code` (edytor's `code.css` sets `white-space:
+	   pre`, `tab-size` and `overflow-x`, unlayered, so it beats utilities), and these selectors
+	   are scoped under the Code root so they win. The ScrollArea scrolls, never the pre. */
 	:global([data-slot='code'] pre.th-code) {
 		margin: 0;
+		overflow: visible;
 		background-color: transparent;
 		color: var(--code-token-plain);
+		white-space: pre;
+		word-break: normal;
+		tab-size: var(--code-tab-size, 2);
+	}
+
+	:global([data-slot='code'] pre.th-code[data-wrap]) {
+		white-space: pre-wrap;
 	}
 
 	/* Token classes emitted by TanStack Highlight (`th-token th-<role>`), mapped to our roles. */

package/dist/components/Code/code.highlighter.js

@@ -16,11 +16,11 @@ function getHighlighter() {
 // Applied to the highlighter's `<pre>`. Scrolling is owned by the wrapping ScrollArea (see
 // Code.svelte), so the pre itself does not scroll: when not wrapping it takes its natural
 // (max-content) width so the ScrollArea sees the horizontal overflow; when wrapping it fills
-// and soft-wraps. `has-[.th-line]:px-0` lets the gutter sit flush against the edge. A narrow
+// and soft-wraps (its white-space is set in CodeTheme.svelte). `has-[.th-line]:px-0` lets the gutter sit flush against the edge. A narrow
 // block (under 28rem) tightens its padding, as its text steps down (see `code.theme.ts`).
 const preClass = (wrap) => [
     'px-4 py-3.5 @max-md:px-3 @max-md:py-2.5 outline-none has-[.th-line]:px-0',
-    wrap ? 'w-full whitespace-pre-wrap break-words' : 'w-max'
+    wrap ? 'w-full break-words' : 'w-max'
 ].join(' ');
 /**
  * Highlights `code` to a `<pre class="th-code"><code>…</code></pre>` HTML string

package/dist/components/Code/code.mcp.d.ts

@@ -1 +1 @@
-export declare const codeDescription = "\n# Code Component\n\nDisplays a syntax-highlighted code block with an optional header (language label\n+ copy button), line numbers, and header/footer slots. Highlighting is powered by\nTanStack Highlight with every language bundled (synchronous, SSR-safe) and a CSS-variable token palette, so colors\nadapt to light and dark automatically from the design tokens.\n\n## Basic Usage\n\n```svelte\n<Code language=\"typescript\" code={`const hello: string = 'world';`} />\n```\n\n## Props\n\n### Core Props\n- **code**: string (required) - Source code to highlight. Also what the copy button writes to the clipboard.\n- **language**: string (default: 'text') - Language id (`ts`, `svelte`, `css`, `shell`, `json`, `python`, \u2026). Aliases like `typescript`, `js`, `bash` resolve automatically; every language TanStack Highlight ships is bundled, and unknown ids fall back to plain text.\n- **title**: string - Header label. Defaults to the language's display name (e.g. \"TypeScript\").\n\n### Display Props\n- **showLineNumbers**: boolean (default: false) - Renders a line-number gutter.\n- **showHeader**: boolean (default: true) - Renders the default header row (title + copy button). Set to false to show only the code block. Ignored when a custom `header` snippet is provided.\n- **copyable**: boolean (default: true) - Shows the copy-to-clipboard button. In the header when one is shown, otherwise a floating button in the top-right corner that appears on hover.\n- **wrap**: boolean (default: false) - Soft-wraps long lines instead of scrolling horizontally.\n- **maxHeight**: number | string (default: none) - Caps the block height and makes it vertically scrollable (via ScrollArea). A number is pixels; a string is used as-is (e.g. `'20rem'`).\n- **tabSize**: number (default: 2) - Tab width in spaces.\n\n### Styling Props\n- **class**: string - Additional CSS classes on the root element.\n- **theme**: CodeThemeProps - Theme overrides for the `code`, `header`, `title`, `container`, and `footer` parts.\n\n### Slots\n- **header**: Snippet<[CodeHeaderPayload]> - Replaces the default header row. Receives `{ language, label, copied, copy }`.\n- **footer**: Snippet - Optional footer row (e.g. a token count or a run button).\n\n## Examples\n\n### With a title and line numbers\n```svelte\n<Code\n  language=\"svelte\"\n  title=\"Counter.svelte\"\n  showLineNumbers\n  code={svelteSource}\n/>\n```\n\n### Custom header\n```svelte\n<Code language=\"json\" code={json}>\n  {#snippet header({ label, copied, copy })}\n    <div class=\"flex items-center justify-between px-3 py-1.5\">\n      <span>{label}</span>\n      <button onclick={copy}>{copied ? 'Copied!' : 'Copy'}</button>\n    </div>\n  {/snippet}\n</Code>\n```\n\n### With a footer\n```svelte\n<Code language=\"bash\" code={installCmd}>\n  {#snippet footer()}\n    <span>Run in your project root</span>\n  {/snippet}\n</Code>\n```\n\n## Theming\n\nThe block chrome (border, header, footer, container) is styled with cva parts and\nuses `bg-neutral-muted` / `text-neutral/70` for the header and footer.\nThe syntax colors are NOT part of cva \u2014 they come from the highlighter's `th-*` token classes plus the\ncolocated `CodeTheme.svelte`, which maps each `--code-token-*` variable onto our\n`--color-*` design tokens (keyword \u2192 primary, string \u2192 success, number \u2192 warning,\nfunction \u2192 info, tag \u2192 danger, \u2026) and re-tunes a few roles under the dark selector.\n\n### Theme Structure\n- **root**: Root container (border, radius, background).\n- **header**: Header row (language label + copy button).\n- **title**: The language/title label text.\n- **container**: The scrollable code area wrapping the highlighted `<pre>`.\n- **footer**: Optional footer row.\n\n### Theme Type Definition\n\n```typescript\nimport type { CodeThemeProps } from 'entasis/code';\n\nconst customTheme: CodeThemeProps = {\n  root: { base: 'rounded-xl raised-4' },\n  header: { base: 'bg-primary text-primary-contrast px-4 py-2' }\n};\n```\n\n## Accessibility\n- The copy button carries an `aria-label` that reflects its state (\"Copy\" / \"Copied\").\n- Clipboard access is guarded (`navigator.clipboard`) and only runs client-side.\n\n## Notes\n- The highlighter is a singleton constructed at module load \u2014 SSR-safe, no top-level await.\n- Copied state resets automatically after 2 seconds and whenever `code` or `language` changes.\n";
+export declare const codeDescription = "\n# Code Component\n\nDisplays a syntax-highlighted code block with an optional header (language label\n+ copy button), line numbers, and header/footer slots. Highlighting is powered by\nTanStack Highlight with every language bundled (synchronous, SSR-safe) and a CSS-variable token palette, so colors\nadapt to light and dark automatically from the design tokens.\n\n## Basic Usage\n\n```svelte\n<Code language=\"typescript\" code={`const hello: string = 'world';`} />\n```\n\n## Props\n\n### Core Props\n- **code**: string (required) - Source code to highlight. Also what the copy button writes to the clipboard.\n- **language**: string (default: 'text') - Language id (`ts`, `svelte`, `css`, `shell`, `json`, `python`, \u2026). Aliases like `typescript`, `js`, `bash` resolve automatically; every language TanStack Highlight ships is bundled, and unknown ids fall back to plain text.\n- **title**: string - Header label. Defaults to the language's display name (e.g. \"TypeScript\").\n\n### Display Props\n- **showLineNumbers**: boolean (default: false) - Renders a line-number gutter.\n- **showHeader**: boolean (default: true) - Renders the default header row (title + copy button). Set to false to show only the code block. Ignored when a custom `header` snippet is provided.\n- **copyable**: boolean (default: true) - Shows the copy-to-clipboard button. In the header when one is shown, otherwise a floating button in the top-right corner that appears on hover.\n- **wrap**: boolean (default: false) - Soft-wraps long lines instead of scrolling horizontally. Code sets its `<pre>`'s `white-space` and `tab-size` itself, scoped under its root, so an app stylesheet that styles every `pre.th-code` (edytor's `code.css` does) changes neither.\n- **maxHeight**: number | string (default: none) - Caps the block height and makes it vertically scrollable (via ScrollArea). A number is pixels; a string is used as-is (e.g. `'20rem'`).\n- **tabSize**: number (default: 2) - Tab width in spaces.\n\nIn a height-bound flex column (a Dialog or Drawer body, `flex min-h-0 flex-1 flex-col`), a Code taller than the room left shrinks to it and scrolls inside: the header and footer stay put and every line stays reachable. To keep its full height and let the column scroll instead, pass `class=\"shrink-0\"`.\n\n### Styling Props\n- **class**: string - Additional CSS classes on the root element.\n- **theme**: CodeThemeProps - Theme overrides for the `code`, `header`, `title`, `container`, and `footer` parts.\n\n### Slots\n- **header**: Snippet<[CodeHeaderPayload]> - Replaces the default header row. Receives `{ language, label, copied, copy }`.\n- **footer**: Snippet - Optional footer row (e.g. a token count or a run button).\n\n## Examples\n\n### With a title and line numbers\n```svelte\n<Code\n  language=\"svelte\"\n  title=\"Counter.svelte\"\n  showLineNumbers\n  code={svelteSource}\n/>\n```\n\n### Custom header\n```svelte\n<Code language=\"json\" code={json}>\n  {#snippet header({ label, copied, copy })}\n    <div class=\"flex items-center justify-between px-3 py-1.5\">\n      <span>{label}</span>\n      <button onclick={copy}>{copied ? 'Copied!' : 'Copy'}</button>\n    </div>\n  {/snippet}\n</Code>\n```\n\n### With a footer\n```svelte\n<Code language=\"bash\" code={installCmd}>\n  {#snippet footer()}\n    <span>Run in your project root</span>\n  {/snippet}\n</Code>\n```\n\n## Theming\n\nThe block chrome (border, header, footer, container) is styled with cva parts and\nuses `bg-neutral-muted` / `text-neutral/70` for the header and footer.\nThe syntax colors are NOT part of cva \u2014 they come from the highlighter's `th-*` token classes plus the\ncolocated `CodeTheme.svelte`, which maps each `--code-token-*` variable onto our\n`--color-*` design tokens (keyword \u2192 primary, string \u2192 success, number \u2192 warning,\nfunction \u2192 info, tag \u2192 danger, \u2026) and re-tunes a few roles under the dark selector.\n\n### Theme Structure\n- **root**: Root container (border, radius, background).\n- **header**: Header row (language label + copy button).\n- **title**: The language/title label text.\n- **container**: The scrollable code area wrapping the highlighted `<pre>`.\n- **footer**: Optional footer row.\n\n### Theme Type Definition\n\n```typescript\nimport type { CodeThemeProps } from 'entasis/code';\n\nconst customTheme: CodeThemeProps = {\n  root: { base: 'rounded-xl raised-4' },\n  header: { base: 'bg-primary text-primary-contrast px-4 py-2' }\n};\n```\n\n## Accessibility\n- The copy button carries an `aria-label` that reflects its state (\"Copy\" / \"Copied\").\n- Clipboard access is guarded (`navigator.clipboard`) and only runs client-side.\n\n## Notes\n- The highlighter is a singleton constructed at module load \u2014 SSR-safe, no top-level await.\n- Copied state resets automatically after 2 seconds and whenever `code` or `language` changes.\n";

package/dist/components/Code/code.mcp.js

@@ -23,10 +23,12 @@ adapt to light and dark automatically from the design tokens.
 - **showLineNumbers**: boolean (default: false) - Renders a line-number gutter.
 - **showHeader**: boolean (default: true) - Renders the default header row (title + copy button). Set to false to show only the code block. Ignored when a custom \`header\` snippet is provided.
 - **copyable**: boolean (default: true) - Shows the copy-to-clipboard button. In the header when one is shown, otherwise a floating button in the top-right corner that appears on hover.
-- **wrap**: boolean (default: false) - Soft-wraps long lines instead of scrolling horizontally.
+- **wrap**: boolean (default: false) - Soft-wraps long lines instead of scrolling horizontally. Code sets its \`<pre>\`'s \`white-space\` and \`tab-size\` itself, scoped under its root, so an app stylesheet that styles every \`pre.th-code\` (edytor's \`code.css\` does) changes neither.
 - **maxHeight**: number | string (default: none) - Caps the block height and makes it vertically scrollable (via ScrollArea). A number is pixels; a string is used as-is (e.g. \`'20rem'\`).
 - **tabSize**: number (default: 2) - Tab width in spaces.
 
+In a height-bound flex column (a Dialog or Drawer body, \`flex min-h-0 flex-1 flex-col\`), a Code taller than the room left shrinks to it and scrolls inside: the header and footer stay put and every line stays reachable. To keep its full height and let the column scroll instead, pass \`class="shrink-0"\`.
+
 ### Styling Props
 - **class**: string - Additional CSS classes on the root element.
 - **theme**: CodeThemeProps - Theme overrides for the \`code\`, \`header\`, \`title\`, \`container\`, and \`footer\` parts.

package/dist/components/Code/code.theme.js

@@ -9,20 +9,21 @@ const defaultCode = cva({
 const defaultCodeFloatingCopy = cva({
     base: 'absolute top-2 right-2 z-10 opacity-0 transition-opacity focus-within:opacity-100 group-hover:opacity-100'
 });
+// Header and footer never shrink: in a height-bound column the code scrolls between them.
 const defaultCodeHeader = cva({
-    base: 'flex items-center justify-between gap-md border-b border-neutral-muted bg-surface-raised px-lg py-sm text-xs text-neutral/70'
+    base: 'flex shrink-0 items-center justify-between gap-md border-b border-neutral-muted bg-surface-raised px-lg py-sm text-xs text-neutral/70'
 });
 const defaultCodeTitle = cva({
     base: 'font-mono'
 });
 const defaultCodeContainer = cva({
     // The scroll + padding live on the inner highlighter <pre> (classes added by codeToHtml)
-    // so the focusable node is the scroller; the container is just the surface. `tab-size` is
-    // driven by a CSS var set on the root (defaults to 2).
-    base: 'min-w-0 bg-surface text-sm @max-md:text-xs [&_pre]:!bg-transparent [&_pre]:[tab-size:var(--code-tab-size,2)] [&_code]:font-mono'
+    // so the focusable node is the scroller; the container is just the surface. The pre's
+    // white-space and `tab-size` (from `--code-tab-size` on the root) live in CodeTheme.svelte.
+    base: 'min-w-0 bg-surface text-sm @max-md:text-xs [&_pre]:!bg-transparent [&_code]:font-mono'
 });
 const defaultCodeFooter = cva({
-    base: 'flex items-center justify-between gap-md border-t border-neutral-muted bg-surface-raised px-lg py-sm text-xs text-neutral/70'
+    base: 'flex shrink-0 items-center justify-between gap-md border-t border-neutral-muted bg-surface-raised px-lg py-sm text-xs text-neutral/70'
 });
 export const codeTheme = {
     root: defaultCode,

package/dist/components/Form/Ask/Ask.svelte

@@ -144,25 +144,35 @@
 		closeOnClickOutside={false}
 		swipeToDismiss={false}
 		theme={{
-			header: { base: '-mx-4 px-4' },
-			footer: { base: 'border-neutral-muted -mx-4 mt-2 border-t px-4 pt-3' }
+			header: { base: '-mx-4 shrink-0 px-4' },
+			footer: { base: 'border-neutral-muted -mx-4 mt-2 shrink-0 border-t px-4 pt-3' }
 		}}
 		onAfterClose={() => finishClose(askState)}
 	>
-		<Form
-			inputs={askState.options.inputs}
-			onSubmit={(value) => completeAskSubmission(askState, value)}
-			bind:value={askState.value}
-			bind:form={askState.form}
-			class={askState.options.class}
-			size={askState.options.size}
-			density={askState.options.density}
-			variant={askState.options.variant}
-			layout={askState.options.layout}
-			validationMode={askState.options.validationMode}
-			validationDebounce={askState.options.validationDebounce}
-			theme={askState.options.theme}
-		/>
+		<!-- The form is the body, and the only part that scrolls: with `scroll: 'inner'` the card is
+		     capped to the viewport, so a tall form shrinks here and the title, description and
+		     buttons stay on screen. It runs to the card's edges (`-mx-4 px-4`, like the header and
+		     footer) with a little room above and below, so a full-width field's focus ring is never
+		     clipped. With `scroll: 'outer'` nothing caps it and it never scrolls. -->
+		<div
+			data-slot="ask-body"
+			class="-mx-4 -my-1 min-h-0 overflow-y-auto overscroll-contain px-4 py-1"
+		>
+			<Form
+				inputs={askState.options.inputs}
+				onSubmit={(value) => completeAskSubmission(askState, value)}
+				bind:value={askState.value}
+				bind:form={askState.form}
+				class={askState.options.class}
+				size={askState.options.size}
+				density={askState.options.density}
+				variant={askState.options.variant}
+				layout={askState.options.layout}
+				validationMode={askState.options.validationMode}
+				validationDebounce={askState.options.validationDebounce}
+				theme={askState.options.theme}
+			/>
+		</div>
 
 		{#snippet footer()}
 			<!-- The button row lays itself out against the dialog footer's own width, not the

package/dist/components/Form/Ask/ask.mcp.d.ts

@@ -1 +1 @@
-export declare const askDescription = "\n# Ask\n\nImport from `entasis/ask`.\n\nMount Ask to host programmatic requests created by ask. Requests use the existing Form inputs and validation boundary inside Dialog, including input types the app registered with registerFormInputs (see Form), so a request can arrive as plain data. AskResult reports submitted and value; cancellation preserves the current form value. Submission failures reject the request. Fields validate as in Form (validationMode and validationDebounce are accepted, async validators are awaited), disabled fields are left out of the result, and Confirm marks itself loading rather than natively disabled while the form submits, so it keeps keyboard focus. Mount the host before requesting a form.\n";
+export declare const askDescription = "\n# Ask\n\nImport from `entasis/ask`.\n\nMount Ask to host programmatic requests created by ask. Requests use the existing Form inputs and validation boundary inside Dialog, including input types the app registered with registerFormInputs (see Form), so a request can arrive as plain data. AskResult reports submitted and value; cancellation preserves the current form value. Submission failures reject the request. Fields validate as in Form (validationMode and validationDebounce are accepted, async validators are awaited), disabled fields are left out of the result, and Confirm marks itself loading rather than natively disabled while the form submits, so it keeps keyboard focus. Mount the host before requesting a form. A form taller than the viewport scrolls in its own body (`data-slot=\"ask-body\"`), so the title, description and buttons stay on screen; pass `dialog: { scroll: 'outer' }` to scroll the whole card instead.\n";

package/dist/components/Form/Ask/ask.mcp.js

@@ -3,5 +3,5 @@ export const askDescription = `
 
 Import from \`entasis/ask\`.
 
-Mount Ask to host programmatic requests created by ask. Requests use the existing Form inputs and validation boundary inside Dialog, including input types the app registered with registerFormInputs (see Form), so a request can arrive as plain data. AskResult reports submitted and value; cancellation preserves the current form value. Submission failures reject the request. Fields validate as in Form (validationMode and validationDebounce are accepted, async validators are awaited), disabled fields are left out of the result, and Confirm marks itself loading rather than natively disabled while the form submits, so it keeps keyboard focus. Mount the host before requesting a form.
+Mount Ask to host programmatic requests created by ask. Requests use the existing Form inputs and validation boundary inside Dialog, including input types the app registered with registerFormInputs (see Form), so a request can arrive as plain data. AskResult reports submitted and value; cancellation preserves the current form value. Submission failures reject the request. Fields validate as in Form (validationMode and validationDebounce are accepted, async validators are awaited), disabled fields are left out of the result, and Confirm marks itself loading rather than natively disabled while the form submits, so it keeps keyboard focus. Mount the host before requesting a form. A form taller than the viewport scrolls in its own body (\`data-slot="ask-body"\`), so the title, description and buttons stay on screen; pass \`dialog: { scroll: 'outer' }\` to scroll the whole card instead.
 `;

package/dist/components/Form/Ask/ask.props.d.ts

@@ -16,7 +16,10 @@ export type AskOptions<I extends FormInputs> = Pick<FormProps<I>, 'inputs' | 'va
     confirm: AskButton;
     /** Cancel action label or protected Button presentation props. */
     cancel: AskButton;
-    /** Dialog presentation options. Dismissal behavior remains owned by Ask. */
+    /**
+     * Dialog presentation options. Dismissal behavior remains owned by Ask. With `scroll: 'inner'`
+     * (the default) only the form scrolls, so the header and the buttons stay on screen.
+     */
     dialog?: AskDialogOptions;
 };
 export type AskResult<I extends FormInputs> = {

package/dist/components/Form/Form/form.mcp.d.ts

@@ -1 +1 @@
-export declare const formDescription = "\n# Form\n\nForm renders configured entasis fields inside a div, owns their state and validation, and submits programmatically. It provides managed Enter-key navigation and submission, but not native form events, browser constraint validation, or FormData behavior. For a plain <form> (a SvelteKit form action), use the controls directly: each submits its name and value through hidden inputs, follows the form's reset, and accepts a form prop when it sits outside the form.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n\timport {\n\t\tForm,\n\t\ttype FormState,\n\t\ttype InferFormValue,\n\t\ttype LiveFormValue\n\t} from 'entasis/form';\n\n\tconst inputs = {\n\t\tidentity: {\n\t\t\ttype: 'group',\n\t\t\tlabel: 'Identity',\n\t\t\tdescription: 'Core account details',\n\t\t\tcolumns: 2,\n\t\t\tinputs: {\n\t\t\t\tname: { type: 'text', label: 'Name', required: true },\n\t\t\t\temail: { type: 'email', label: 'Email', required: true }\n\t\t\t}\n\t\t}\n\t} as const;\n\n\tlet value = $state<LiveFormValue<typeof inputs>>({ name: 'Ada' });\n\tlet form = $state<FormState<typeof inputs>>();\n\tlet submitted = $state<InferFormValue<typeof inputs> | null>(null);\n</script>\n\n<Form\n\t{inputs}\n\tbind:value\n\tbind:form\n\tvariant=\"card\"\n\tlayout=\"horizontal\"\n\tsize=\"small\"\n\tdensity=\"normal\"\n\tactions={[\n\t\t{\n\t\t\tchildren: 'Save',\n\t\t\tonAction: (payload) => payload.submit()\n\t\t}\n\t]}\n\tonSubmit={(validatedValue) => {\n\t\tsubmitted = validatedValue;\n\t}}\n/>\n```\n\n## Props\n\n- **inputs** (required): ordered object keyed by entry name. Entries may be value-bearing fields, visual groups, action-button rows, or custom snippets. Only fields contribute keys to the live and validated values.\n- **value** (bindable): controlled partial live value. Visible mounted fields are published; hidden fields are omitted. A supplied top-level value takes precedence over an input's configured value.\n- **defaultValue**: initial partial live value when value is omitted.\n- **onValueChange**: called once when a user changes the visible live value. Parent value updates do not emit it.\n- **form** (bindable): the FormState instance.\n- **onSubmit**: called with the validated visible payload. Its return value is ignored; rejected promises propagate.\n- **size**: small, normal (default), or large. Controls Form typography and becomes the fallback size for fields and actions. An explicit field or action size takes precedence.\n- **density**: compact, normal (default), or comfortable. Controls gaps between the Form header, fields, footer, and actions independently from size.\n- **variant**: plain (default), sectioned, or card. All variants consume the shared Card typography. Plain remains transparent without separators. Sectioned stays transparent and adds edge-to-edge separators between the header, visible top-level fields or groups, and footer. Card adds the same separators inside the Card surface and inset; Card header/footer padding applies only to that variant. Separators do not appear between fields inside a group.\n- **layout**: vertical (default) or horizontal. Horizontal keeps one field per row and places labels to the left once each field is at least 32rem wide; fields remain stacked in narrower forms.\n- **actions**: optional array of Button props. Each action's onAction receives the live FormState, so a submit action calls form.submit(). Actions are disabled while the form is submitting; their own loading and disabled props are composed with that protection.\n- **validationMode**: submit (default), blur, or change. When a field validates by itself besides a submit: submit waits for the first submit attempt and then re-validates each edited field, blur validates when focus leaves the field, change validates on every accepted change. A field that shows an error always re-validates as it is edited. A field's own validationMode takes precedence, and mounting never validates.\n- **validationDebounce**: milliseconds an edit waits before the validation it triggers, so an async onValidate is not called on every keystroke. Submit and blur validate at once. A field's own validationDebounce takes precedence.\n- **errors**: errors from outside the form, for example a SvelteKit ActionData, keyed by field name with one message or a list of them. They show under their fields, survive validation, do not block a submit (the server re-checks), and clear when that field's value next changes. Changing the prop replaces the errors; the first errored field in render order is revealed.\n- **disabled**: disables every field, for example disabled={form.loading} while a submission runs. Disabled fields skip validation and, as in a native form, are left out of the submitted value. The root carries data-disabled. A disabled option inside an enabled radio or checkbox group is different: when selected it stays in that field's value, while a plain native <form> leaves it out of its submission.\n- **readOnly**: makes every field read-only. Values stay focusable, validated and submitted, but users cannot change them. The root carries data-readonly.\n- **class**: additional classes on the root div.\n- **theme**: Form theme overrides for root, header, title, description, group, group label/description/fields, top-level items, custom entries, footer, and actions. Global Card typography and section-rhythm changes flow into all Form variants before Form-specific overrides are composed; Card surface changes apply only to the card variant.\n\nThe **header**, **title**, **description**, **children**, and **footer** snippets each receive the FormState instance directly. No-argument snippets remain valid.\n\nField wrapper attributes and native control attributes have separate owners. Use fieldAttrs for the shared Field wrapper. Controls expose a typed bag for their actual native element, such as inputAttrs on TextInput, textareaAttrs on TextArea, and triggerAttrs on the custom Select's combobox button.\n\n## FormState\n\n- **value**: current visible partial value.\n- **loading**: true while a submission is pending: async validators first, then the handler.\n- **hasError**: true after validation fails or errors are set from outside; reset after successful validation.\n- **dirty**: true when any field differs from its initial value (null, an empty string and an empty list count as equal).\n- **touched**: true once focus has entered and left any field.\n- **validating**: true while an async onValidate of any field is pending.\n- **submitCount**: how many times the form was validated to submit.\n- **validate(options?)**: validates every visible, enabled field synchronously and returns the validated visible payload, or false after revealing the first invalid field. Disabled fields are skipped and left out of the payload. Pass { reveal: false } to check quietly: no scrolling, no focus, and the call does not count as a submit attempt. It does not wait for async validators.\n- **validateAsync(options?)**: like validate, and waits for async validators; returns a promise.\n- **validateField(name)**: validates one field now and returns whether it is valid. It neither scrolls nor focuses. A name that is not a visible field returns false; a disabled field skips validation and returns true; a field whose async validator is still running returns false, so use validateAsync to wait.\n- **submit()**: returns a promise of the validated visible payload, or false. It waits for pending async validators. Concurrent calls share the active promise.\n- **setErrors(errors)**: shows errors from outside the form under their fields, replacing those set before; setErrors({}) clears them. Call it from onSubmit with the server response. The first errored field in render order is revealed once the submission ends.\n- **reset(value?)**: restores every field to its initial value, or to value where it gives one, and makes that the new baseline. Errors, touched, dirty and the submit count clear, fields do not echo onValueChange, and the form's onValueChange runs once if the visible value changed. Conditional visibility is evaluated again.\n- **advanceFrom(field)**: moves on from a registered field as Enter does in a text field: the last navigable field submits, any other validates and focuses the next field when valid. Returns false when the field is hidden, disabled or not part of this form. Controls that own Enter themselves, such as checkboxes and radios, call it from their key handler and fall back to the native form otherwise.\n\n## Enter-key behavior\n\nOn an enabled, editable single-line input, Enter validates the current field. A valid field moves focus to the next visible enabled field, while an invalid field remains focused and displays its errors. Enter on a valid final navigable field calls form.submit(). Multiline editors and controls that already own Enter, such as selects and combobox menus, keep their native component behavior. A control that owns Enter can continue the flow with form.advanceFrom(field). Modified, repeated, and IME-composition Enter events are ignored.\n\n## Programmatic Dialog forms\n\nMount one Ask host near the application root, then call ask() from any client-side event. Both exports come from entasis/form:\n\n```svelte\n<script lang=\"ts\">\n\timport { Ask, ask } from 'entasis/form';\n\n\tconst inputs = {\n\t\tname: { type: 'text', label: 'Name', required: true },\n\t\temail: { type: 'email', label: 'Email', required: true }\n\t} as const;\n\n\tasync function editProfile() {\n\t\tconst outcome = await ask({\n\t\t\ttitle: 'Edit profile',\n\t\t\tdescription: 'Review the account details.',\n\t\t\tinputs,\n\t\t\tvalue: { name: 'Ada' },\n\t\t\tconfirm: 'Save',\n\t\t\tcancel: 'Cancel'\n\t\t});\n\n\t\tif (outcome.submitted) {\n\t\t\t// outcome.value is InferFormValue<typeof inputs>\n\t\t} else {\n\t\t\t// outcome.value is the partial, visible live value at cancellation\n\t\t}\n\t}\n</script>\n\n<Ask />\n```\n\nAskOptions accepts inputs, value, onSubmit, class, size, density, variant, layout, theme, validationMode, and validationDebounce with the same contracts as Form. Disabled fields are left out of the result. title is required for the Dialog's accessible name. confirm and cancel accept a string or Button presentation props plus text. Their click, loading, link, and native type behavior is owned by Ask. Set type on the mounted Ask host for its default Dialog type; a request's optional dialog object may override type and also accepts responsive, size, and scroll.\n\nValidation failures keep the Dialog open and focus the first invalid field. A successful submission resolves with the validated visible payload. Cancel, the close button, and Escape resolve with submitted: false and the current partial visible value. Outside-click and swipe dismissal are disabled. While submission is active, all close paths and actions are protected. Rejected onSubmit promises reject ask() after the Dialog closes. Concurrent ask() calls render as independent stacked Dialogs. Calling ask() during SSR or without one mounted host rejects clearly.\n\n## Visibility and values\n\nThe visible prop may be a boolean or a predicate receiving the complete private value cache:\n\n```svelte\n<Form\n\tinputs={{\n\t\tcontactMethod: {\n\t\t\ttype: 'select',\n\t\t\tlabel: 'Contact method',\n\t\t\titems: [\n\t\t\t\t{ label: 'Email', value: 'email' },\n\t\t\t\t{ label: 'Phone', value: 'phone' }\n\t\t\t]\n\t\t},\n\t\tphone: {\n\t\t\ttype: 'phone',\n\t\t\tlabel: 'Phone',\n\t\t\tvisible: (value) => value.contactMethod === 'phone'\n\t\t}\n\t}}\n/>\n```\n\nHidden field values are preserved privately and restored when shown again. Hidden fields are excluded from value, validation, and submission. Removing an input definition removes its cached value.\n\n## Field label position\n\nAll configured inputs inherit the Form layout through the shared Field wrapper. Set labelPosition: 'top' or 'left' on an individual input to override the Form layout without affecting value inference:\n\n```ts\nexport const inputs = {\n\tname: { type: 'text', label: 'Name' },\n\tnotes: { type: 'textarea', label: 'Notes', labelPosition: 'top' }\n} as const;\n```\n\nThe left position becomes a two-column label/control layout once the field is at least 32rem wide and remains stacked in narrower forms. The breakpoint is a container query against the field, so a form in a narrow drawer stacks on any screen. Form uses layout rather than orientation so controls such as Slider retain their own orientation prop.\n\n## Visual groups\n\nA group renders a transparent semantic fieldset with a required legend label and an optional description. Its label and description use the same size scale as ordinary fields; grouping does not add another card or padded container:\n\n```ts\nimport type { InferFormValue } from 'entasis/form';\n\nexport const inputs = {\n\tcontact: {\n\t\ttype: 'group',\n\t\tlabel: 'Contact details',\n\t\tdescription: 'How we can reach you',\n\t\tcolumns: 1,\n\t\tinputs: {\n\t\t\temail: { type: 'email', label: 'Email', required: true },\n\t\t\tphone: { type: 'phone', label: 'Phone' }\n\t\t}\n\t}\n} as const;\n\ntype Value = InferFormValue<typeof inputs>;\n// { email: string; phone: string | null }\n```\n\nSet disabled on a group to disable every field inside it, as a native disabled fieldset does (the fieldset renders disabled and data-disabled), or readOnly to make them read-only (data-readonly). A field is disabled or read-only when it, its group, or the Form is.\n\nThe group key is visual only and never appears in value or submission output. Descendant field names remain top-level, so duplicate names across groups are rejected. Group visibility hides all descendants, preserves field values in the private cache, and makes inferred field keys optional. In a vertical form layout, set columns to 1, 2, 3, or 4 to control the equal-width grid; the count is a container query against the form width (2 columns from 42rem, 3 from 56rem, 4 from 72rem), and groups collapse to one column in narrower forms. Horizontal form layouts ignore columns and always render group entries in one column. A child class may span tracks when an entry needs more room. Groups may contain fields, action rows, and custom snippets; nested groups are intentionally unsupported.\n\n## Custom value fields\n\nUse type: 'field' when Form must own a value but a custom control must render it. fieldType selects the existing FieldState schema and inferred value type. The snippet receives that registered FieldState controller:\n\n```svelte\n{#snippet handleControl(field)}\n\t<input\n\t\t{...field.controlAttrs}\n\t\t{@attach field.control}\n\t\tbind:value={field.value}\n\t/>\n{/snippet}\n\n<Form\n\tinputs={{\n\t\thandle: {\n\t\t\ttype: 'field',\n\t\t\tfieldType: 'text',\n\t\t\tlabel: 'Handle',\n\t\t\trequired: true,\n\t\t\tsnippet: handleControl\n\t\t}\n\t}}\n/>\n```\n\nThe controller exposes value, disabled, required, validation state, accessible ids, controlAttrs, and the control attachment. The entry participates in bind:value, visibility, validation, submission, and InferFormValue through the same FieldState owner as built-in controls.\n\n## App-defined input types\n\nAn app can add its own input types to every Form and ask() dialog, by name, so entries stay plain data that serializes (JSON from a server, a tool call, a database). Two steps, once per app.\n\nType it: augment `FormInputRegistry` with the value the input holds and the props its entries take.\n\n```ts\n// doc-fence: skip (imports a sibling component; tooling/component-contract/consumer-form-input.ts checks this exact setup against the package)\nimport { registerFormInputs } from 'entasis/form';\nimport MoneyInput from './MoneyInput.svelte';\n\nexport type Money = { amount: number; currency: string };\n\ndeclare module 'entasis/form' {\n\tinterface FormInputRegistry {\n\t\tmoney: { value: Money; props: { currencies?: string[] } };\n\t}\n}\n\nregisterFormInputs({\n\tmoney: {\n\t\tcomponent: MoneyInput,\n\t\tisEmpty: (value) => value?.amount === undefined,\n\t\tvalidate: (value) => (value.amount < 0 ? 'Must not be negative' : null)\n\t}\n});\n```\n\nRegister it: call registerFormInputs at the top level of a module the server and the browser both load before a form renders, such as one the root layout imports. Its keys are checked against the registry; built-in type names are refused, and registering a type again replaces it.\n\nThe component renders the control alone. Form wraps it in Field (label, description, errors) and hands it the field it registered, typed from the registry, plus the entry's own props:\n\n```svelte\n<!-- doc-fence: skip -->\n<!-- Needs the money registration above; tooling/component-contract/consumer-money-input.svelte is the checked copy. -->\n<script lang=\"ts\">\n\timport type { FormInputComponentProps } from 'entasis/form';\n\n\tlet { field, currencies = ['EUR'] }: FormInputComponentProps<'money'> = $props();\n\tconst currency = $derived(field.value?.currency ?? currencies[0] ?? 'EUR');\n</script>\n\n<input\n\ttype=\"number\"\n\t{...field.controlAttrs}\n\t{@attach field.control}\n\tvalue={field.value?.amount ?? ''}\n\toninput={(event) => field.setValue({ amount: Number(event.currentTarget.value), currency })}\n/>\n```\n\nEntries then use the type like a built-in one, in Form inputs, groups, and ask():\n\n```ts\n// doc-fence: skip (needs the money registration above)\nconst result = await ask({\n\ttitle: 'Set a price',\n\tconfirm: 'Save',\n\tcancel: 'Cancel',\n\tinputs: { price: { type: 'money', label: 'Price', required: true, currencies: ['EUR', 'USD'] } }\n});\nif (result.submitted) result.value.price; // Money\n```\n\nEvery Field entry option applies (label, description, required, disabled, readOnly, messages, size, density, visible, defaultValue, onValidate, onValueChange, slots); any other key goes to the component. required rejects what isEmpty reports empty (by default null, undefined, an empty string, or an array with no values) with the catalog required message, and isEmpty also decides whether the field reads as filled; validate runs for every entry of the type, before the entry's own onValidate. The value takes part in bind:value, visibility, validation, submission, and InferFormValue like a built-in input's. An entry whose type is neither built-in nor registered throws when the form reads it.\n\n## Non-value entries\n\nUse type: 'action' to place a labelled row of buttons in the ordered inputs flow. It accepts optional label and description content plus the same Form-aware action objects as the top-level actions prop. Its label position follows the Form layout unless labelPosition overrides it. Form size is the default button size, action density follows the Form, and loading or disabled protection cannot be overridden while the Form is submitting.\n\nUse type: 'custom' to place a snippet in the flow. The snippet receives the live public FormState and owns its own surface and padding; Form adds neither. Both entry types support class and visible, may appear at the top level or inside a group, and are omitted from bind:value, validation, and inferred submission output:\n\n```svelte\n{#snippet accountStatus(form)}\n\t<p>{Object.keys(form.value).length} visible values</p>\n{/snippet}\n\n<Form\n\tinputs={{\n\t\tname: { type: 'text', label: 'Name', required: true },\n\t\tstatus: { type: 'custom', snippet: accountStatus },\n\t\tcontrols: {\n\t\t\ttype: 'action',\n\t\t\tlabel: 'Account actions',\n\t\t\tdescription: 'Validate or save this account.',\n\t\t\tactions: [\n\t\t\t\t{ children: 'Validate', variant: 'soft', onAction: (payload) => payload.validate() },\n\t\t\t\t{ children: 'Save', onAction: (payload) => payload.submit() }\n\t\t\t]\n\t\t}\n\t}}\n/>\n```\n\nFor this configuration, InferFormValue contains name only; status and controls are presentation keys.\n\n## Validation\n\nBuilt-in validation uses the field schema. Every 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 (for a checkbox or switch, that it must be on), and email, URL, length, range and incomplete-code failures each have their own message. Override them per entry with messages:\n\n```ts\nimport type { FormInputs } from 'entasis/form';\n\nexport const inputs = {\n\tname: { type: 'text', label: 'Name', required: true, messages: { required: 'Enter your name' } },\n\tcode: {\n\t\ttype: 'pin',\n\t\tlabel: 'Code',\n\t\tlength: 6,\n\t\trequired: true,\n\t\tmessages: { incomplete: (length) => 'Enter the ' + length + '-digit code' }\n\t}\n} satisfies FormInputs;\n```\n\nonValidate may return:\n\n- false, null, undefined, an empty string, or an empty array for valid input;\n- true for the catalog's generic invalid message;\n- a string for one error, shown verbatim;\n- a string array for multiple errors.\n\nValidation runs on submission. Failed submission scrolls to and focuses the first invalid control in render order. Disabled fields, directly or through a disabled group or Form, skip validation and are left out of the submitted value, as in a native form; entries that declare disabled become optional keys in InferFormValue. Read-only fields still validate and submit.\n\n### When fields validate\n\nvalidationMode on the Form, or on one entry, picks when a field validates by itself:\n\n```ts\nimport type { FormInputs } from 'entasis/form';\n\nexport const inputs = {\n\tusername: { type: 'text', label: 'Username', required: true, validationMode: 'change' },\n\temail: { type: 'email', label: 'Email', required: true }\n} satisfies FormInputs;\n// <Form {inputs} validationMode=\"blur\" />: email validates when focus leaves it,\n// username validates on every change.\n```\n\nsubmit (the default) validates on a submit attempt, and from then on re-validates each edited field. blur validates when focus leaves the field, including a popup the field opened. change validates on every accepted change, including values synced from a parent. Whatever the mode, a field that shows an error re-validates as it is edited, and a blur that settles the value (trimming, say) validates the settled value. validationDebounce delays the validation an edit triggers; submit and blur never wait.\n\n### Async validators\n\nonValidate may return a promise. While it is pending the field is neither valid nor invalid: no aria-invalid and no data-invalid, and its root carries data-validating. A result for an older value is dropped, a rejected promise marks the field invalid with the generic message, and unmounting cancels the work. submit() waits for pending validators before it calls onSubmit (loading is true meanwhile); validate() stays synchronous, so use validateAsync() to wait.\n\n```ts\nimport type { FormInputs } from 'entasis/form';\n\ndeclare function isTaken(username: string): Promise<boolean>;\n\nexport const inputs = {\n\tusername: {\n\t\ttype: 'text',\n\t\tlabel: 'Username',\n\t\trequired: true,\n\t\tonValidate: async (username) => ((await isTaken(username)) ? 'That username is taken' : null)\n\t}\n} satisfies FormInputs;\n```\n\n### Server errors\n\nPass the errors of a failed save as the errors prop or call form.setErrors(). They show under their fields, are not wiped by validation, do not block a re-submit, and clear on that field's next change:\n\n```svelte\n<script lang=\"ts\">\n\timport { Form, type FormState, type FormInputs } from 'entasis/form';\n\n\tconst inputs = {\n\t\temail: { type: 'email', label: 'Email', required: true }\n\t} satisfies FormInputs;\n\n\tlet form = $state<FormState<typeof inputs>>();\n</script>\n\n<Form\n\t{inputs}\n\tbind:form\n\tonSubmit={async (value) => {\n\t\tconst response = await fetch('/api/signup', { method: 'POST', body: JSON.stringify(value) });\n\t\tif (!response.ok) form?.setErrors({ email: 'Already registered' });\n\t}}\n/>\n```\n\n### Dirty, touched and reset\n\nEvery field reports touched, dirty and filled (data-touched, data-dirty and data-filled on its root); form.dirty and form.touched are true when any field is. form.reset() returns every field to its initial value and clears errors, touched and dirty; form.reset(value) restores the given values instead and makes them the new baseline.\n\nErrors fade and grow in; reduced motion and the Theme motion tokens apply (the field theme motion slot).\n\n## Supported input types\n\ntext, email, url, password, number, rating, voice, slider, slider-range, textarea, rich-text, select, select-multiple, combobox, radio, checkboxes, checkbox, switch, phone, calendar, calendar-range, date, datetime, color, file, files, tag-group, tag, keyvalue, pin, and time.\n\nAlternative displays are display: 'selector' for date and calendar-range, and display: 'picker' for color.\n\nfield is the custom value-bearing entry. group, action, and custom are structural visual nodes rather than value-bearing input types.\n";
+export declare const formDescription = "\n# Form\n\nForm renders configured entasis fields inside a div, owns their state and validation, and submits programmatically. It provides managed Enter-key navigation and submission, but not native form events, browser constraint validation, or FormData behavior. For a plain <form> (a SvelteKit form action), use the controls directly: each submits its name and value through hidden inputs, follows the form's reset, and accepts a form prop when it sits outside the form.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n\timport {\n\t\tForm,\n\t\ttype FormState,\n\t\ttype InferFormValue,\n\t\ttype LiveFormValue\n\t} from 'entasis/form';\n\n\tconst inputs = {\n\t\tidentity: {\n\t\t\ttype: 'group',\n\t\t\tlabel: 'Identity',\n\t\t\tdescription: 'Core account details',\n\t\t\tcolumns: 2,\n\t\t\tinputs: {\n\t\t\t\tname: { type: 'text', label: 'Name', required: true },\n\t\t\t\temail: { type: 'email', label: 'Email', required: true }\n\t\t\t}\n\t\t}\n\t} as const;\n\n\tlet value = $state<LiveFormValue<typeof inputs>>({ name: 'Ada' });\n\tlet form = $state<FormState<typeof inputs>>();\n\tlet submitted = $state<InferFormValue<typeof inputs> | null>(null);\n</script>\n\n<Form\n\t{inputs}\n\tbind:value\n\tbind:form\n\tvariant=\"card\"\n\tlayout=\"horizontal\"\n\tsize=\"small\"\n\tdensity=\"normal\"\n\tactions={[\n\t\t{\n\t\t\tchildren: 'Save',\n\t\t\tonAction: (payload) => payload.submit()\n\t\t}\n\t]}\n\tonSubmit={(validatedValue) => {\n\t\tsubmitted = validatedValue;\n\t}}\n/>\n```\n\n## Props\n\n- **inputs** (required): ordered object keyed by entry name. Entries may be value-bearing fields, visual groups, action-button rows, or custom snippets. Only fields contribute keys to the live and validated values.\n- **value** (bindable): controlled partial live value. Visible mounted fields are published; hidden fields are omitted. A supplied top-level value takes precedence over an input's configured value.\n- **defaultValue**: initial partial live value when value is omitted.\n- **onValueChange**: called once when a user changes the visible live value. Parent value updates do not emit it.\n- **form** (bindable): the FormState instance.\n- **onSubmit**: called with the validated visible payload. Its return value is ignored; rejected promises propagate.\n- **size**: small, normal (default), or large. Controls Form typography and becomes the fallback size for fields and actions. An explicit field or action size takes precedence.\n- **density**: compact, normal (default), or comfortable. Controls gaps between the Form header, fields, footer, and actions independently from size.\n- **variant**: plain (default), sectioned, or card. All variants consume the shared Card typography. Plain remains transparent without separators. Sectioned stays transparent and adds edge-to-edge separators between the header, visible top-level fields or groups, and footer. Card adds the same separators inside the Card surface and inset; Card header/footer padding applies only to that variant. Separators do not appear between fields inside a group.\n- **layout**: vertical (default) or horizontal. Horizontal keeps one field per row and places labels to the left once each field is at least 32rem wide; fields remain stacked in narrower forms.\n- **actions**: optional array of Button props. Each action's onAction receives the live FormState, so a submit action calls form.submit(). Actions are disabled while the form is submitting; their own loading and disabled props are composed with that protection.\n- **validationMode**: submit (default), blur, or change. When a field validates by itself besides a submit: submit waits for the first submit attempt and then re-validates each edited field, blur validates when focus leaves the field, change validates on every accepted change. A field that shows an error always re-validates as it is edited. A field's own validationMode takes precedence, and mounting never validates.\n- **validationDebounce**: milliseconds an edit waits before the validation it triggers, so an async onValidate is not called on every keystroke. Submit and blur validate at once. A field's own validationDebounce takes precedence.\n- **errors**: errors from outside the form, for example a SvelteKit ActionData, keyed by field name with one message or a list of them. They show under their fields, survive validation, do not block a submit (the server re-checks), and clear when that field's value next changes. Changing the prop replaces the errors; the first errored field in render order is revealed.\n- **disabled**: disables every field, for example disabled={form.loading} while a submission runs. Disabled fields skip validation and, as in a native form, are left out of the submitted value. The root carries data-disabled. A disabled option inside an enabled radio or checkbox group is different: when selected it stays in that field's value, while a plain native <form> leaves it out of its submission.\n- **readOnly**: makes every field read-only. Values stay focusable, validated and submitted, but users cannot change them. The root carries data-readonly.\n- **class**: additional classes on the root div.\n- **theme**: Form theme overrides for root, header, title, description, group, group label/description/fields, top-level items, custom entries, footer, and actions. Global Card typography and section-rhythm changes flow into all Form variants before Form-specific overrides are composed; Card surface changes apply only to the card variant.\n\nThe **header**, **title**, **description**, **children**, and **footer** snippets each receive the FormState instance directly. No-argument snippets remain valid.\n\nField wrapper attributes and native control attributes have separate owners. Use fieldAttrs for the shared Field wrapper. Controls expose a typed bag for their actual native element, such as inputAttrs on TextInput, textareaAttrs on TextArea, and triggerAttrs on the custom Select's combobox button.\n\n## FormState\n\n- **value**: current visible partial value.\n- **loading**: true while a submission is pending: async validators first, then the handler.\n- **hasError**: true after validation fails or errors are set from outside; reset after successful validation.\n- **dirty**: true when any field differs from its initial value (null, an empty string and an empty list count as equal).\n- **touched**: true once focus has entered and left any field.\n- **validating**: true while an async onValidate of any field is pending.\n- **submitCount**: how many times the form was validated to submit.\n- **validate(options?)**: validates every visible, enabled field synchronously and returns the validated visible payload, or false after revealing the first invalid field. Disabled fields are skipped and left out of the payload. Pass { reveal: false } to check quietly: no scrolling, no focus, and the call does not count as a submit attempt. It does not wait for async validators.\n- **validateAsync(options?)**: like validate, and waits for async validators; returns a promise.\n- **validateField(name)**: validates one field now and returns whether it is valid. It neither scrolls nor focuses. A name that is not a visible field returns false; a disabled field skips validation and returns true; a field whose async validator is still running returns false, so use validateAsync to wait.\n- **submit()**: returns a promise of the validated visible payload, or false. It waits for pending async validators. Concurrent calls share the active promise.\n- **setErrors(errors)**: shows errors from outside the form under their fields, replacing those set before; setErrors({}) clears them. Call it from onSubmit with the server response. The first errored field in render order is revealed once the submission ends.\n- **reset(value?)**: restores every field to its initial value, or to value where it gives one, and makes that the new baseline. Errors, touched, dirty and the submit count clear, fields do not echo onValueChange, and the form's onValueChange runs once if the visible value changed. Conditional visibility is evaluated again.\n- **advanceFrom(field)**: moves on from a registered field as Enter does in a text field: the last navigable field submits, any other validates and focuses the next field when valid. Returns false when the field is hidden, disabled or not part of this form. Controls that own Enter themselves, such as checkboxes and radios, call it from their key handler and fall back to the native form otherwise.\n\n## Enter-key behavior\n\nOn an enabled, editable single-line input, Enter validates the current field. A valid field moves focus to the next visible enabled field, while an invalid field remains focused and displays its errors. Enter on a valid final navigable field calls form.submit(). Multiline editors and controls that already own Enter, such as selects and combobox menus, keep their native component behavior. A control that owns Enter can continue the flow with form.advanceFrom(field). Modified, repeated, and IME-composition Enter events are ignored.\n\n## Programmatic Dialog forms\n\nMount one Ask host near the application root, then call ask() from any client-side event. Both exports come from entasis/form:\n\n```svelte\n<script lang=\"ts\">\n\timport { Ask, ask } from 'entasis/form';\n\n\tconst inputs = {\n\t\tname: { type: 'text', label: 'Name', required: true },\n\t\temail: { type: 'email', label: 'Email', required: true }\n\t} as const;\n\n\tasync function editProfile() {\n\t\tconst outcome = await ask({\n\t\t\ttitle: 'Edit profile',\n\t\t\tdescription: 'Review the account details.',\n\t\t\tinputs,\n\t\t\tvalue: { name: 'Ada' },\n\t\t\tconfirm: 'Save',\n\t\t\tcancel: 'Cancel'\n\t\t});\n\n\t\tif (outcome.submitted) {\n\t\t\t// outcome.value is InferFormValue<typeof inputs>\n\t\t} else {\n\t\t\t// outcome.value is the partial, visible live value at cancellation\n\t\t}\n\t}\n</script>\n\n<Ask />\n```\n\nAskOptions accepts inputs, value, onSubmit, class, size, density, variant, layout, theme, validationMode, and validationDebounce with the same contracts as Form. Disabled fields are left out of the result. title is required for the Dialog's accessible name. confirm and cancel accept a string or Button presentation props plus text. Their click, loading, link, and native type behavior is owned by Ask. Set type on the mounted Ask host for its default Dialog type; a request's optional dialog object may override type and also accepts responsive, size, and scroll. With scroll 'inner' (the default) the form is the Dialog's only scrolling part: a form taller than the viewport scrolls inside its body (`data-slot=\"ask-body\"`) while the title, description and Confirm/Cancel row stay on screen, and the body keeps room around its fields so a focus ring is never clipped. With scroll 'outer' the whole card grows and the page behind it scrolls instead.\n\nValidation failures keep the Dialog open and focus the first invalid field. A successful submission resolves with the validated visible payload. Cancel, the close button, and Escape resolve with submitted: false and the current partial visible value. Outside-click and swipe dismissal are disabled. While submission is active, all close paths and actions are protected. Rejected onSubmit promises reject ask() after the Dialog closes. Concurrent ask() calls render as independent stacked Dialogs. Calling ask() during SSR or without one mounted host rejects clearly.\n\n## Visibility and values\n\nThe visible prop may be a boolean or a predicate receiving the complete private value cache:\n\n```svelte\n<Form\n\tinputs={{\n\t\tcontactMethod: {\n\t\t\ttype: 'select',\n\t\t\tlabel: 'Contact method',\n\t\t\titems: [\n\t\t\t\t{ label: 'Email', value: 'email' },\n\t\t\t\t{ label: 'Phone', value: 'phone' }\n\t\t\t]\n\t\t},\n\t\tphone: {\n\t\t\ttype: 'phone',\n\t\t\tlabel: 'Phone',\n\t\t\tvisible: (value) => value.contactMethod === 'phone'\n\t\t}\n\t}}\n/>\n```\n\nHidden field values are preserved privately and restored when shown again. Hidden fields are excluded from value, validation, and submission. Removing an input definition removes its cached value.\n\n## Field label position\n\nAll configured inputs inherit the Form layout through the shared Field wrapper. Set labelPosition: 'top' or 'left' on an individual input to override the Form layout without affecting value inference:\n\n```ts\nexport const inputs = {\n\tname: { type: 'text', label: 'Name' },\n\tnotes: { type: 'textarea', label: 'Notes', labelPosition: 'top' }\n} as const;\n```\n\nThe left position becomes a two-column label/control layout once the field is at least 32rem wide and remains stacked in narrower forms. The breakpoint is a container query against the field, so a form in a narrow drawer stacks on any screen. Form uses layout rather than orientation so controls such as Slider retain their own orientation prop.\n\n## Visual groups\n\nA group renders a transparent semantic fieldset with a required legend label and an optional description. Its label and description use the same size scale as ordinary fields; grouping does not add another card or padded container:\n\n```ts\nimport type { InferFormValue } from 'entasis/form';\n\nexport const inputs = {\n\tcontact: {\n\t\ttype: 'group',\n\t\tlabel: 'Contact details',\n\t\tdescription: 'How we can reach you',\n\t\tcolumns: 1,\n\t\tinputs: {\n\t\t\temail: { type: 'email', label: 'Email', required: true },\n\t\t\tphone: { type: 'phone', label: 'Phone' }\n\t\t}\n\t}\n} as const;\n\ntype Value = InferFormValue<typeof inputs>;\n// { email: string; phone: string | null }\n```\n\nSet disabled on a group to disable every field inside it, as a native disabled fieldset does (the fieldset renders disabled and data-disabled), or readOnly to make them read-only (data-readonly). A field is disabled or read-only when it, its group, or the Form is.\n\nThe group key is visual only and never appears in value or submission output. Descendant field names remain top-level, so duplicate names across groups are rejected. Group visibility hides all descendants, preserves field values in the private cache, and makes inferred field keys optional. In a vertical form layout, set columns to 1, 2, 3, or 4 to control the equal-width grid; the count is a container query against the form width (2 columns from 42rem, 3 from 56rem, 4 from 72rem), and groups collapse to one column in narrower forms. Horizontal form layouts ignore columns and always render group entries in one column. A child class may span tracks when an entry needs more room. Groups may contain fields, action rows, and custom snippets; nested groups are intentionally unsupported.\n\n## Custom value fields\n\nUse type: 'field' when Form must own a value but a custom control must render it. fieldType selects the existing FieldState schema and inferred value type. The snippet receives that registered FieldState controller:\n\n```svelte\n{#snippet handleControl(field)}\n\t<input\n\t\t{...field.controlAttrs}\n\t\t{@attach field.control}\n\t\tbind:value={field.value}\n\t/>\n{/snippet}\n\n<Form\n\tinputs={{\n\t\thandle: {\n\t\t\ttype: 'field',\n\t\t\tfieldType: 'text',\n\t\t\tlabel: 'Handle',\n\t\t\trequired: true,\n\t\t\tsnippet: handleControl\n\t\t}\n\t}}\n/>\n```\n\nThe controller exposes value, disabled, required, validation state, accessible ids, controlAttrs, and the control attachment. The entry participates in bind:value, visibility, validation, submission, and InferFormValue through the same FieldState owner as built-in controls.\n\n## App-defined input types\n\nAn app can add its own input types to every Form and ask() dialog, by name, so entries stay plain data that serializes (JSON from a server, a tool call, a database). Two steps, once per app.\n\nType it: augment `FormInputRegistry` with the value the input holds and the props its entries take.\n\n```ts\n// doc-fence: skip (imports a sibling component; tooling/component-contract/consumer-form-input.ts checks this exact setup against the package)\nimport { registerFormInputs } from 'entasis/form';\nimport MoneyInput from './MoneyInput.svelte';\n\nexport type Money = { amount: number; currency: string };\n\ndeclare module 'entasis/form' {\n\tinterface FormInputRegistry {\n\t\tmoney: { value: Money; props: { currencies?: string[] } };\n\t}\n}\n\nregisterFormInputs({\n\tmoney: {\n\t\tcomponent: MoneyInput,\n\t\tisEmpty: (value) => value?.amount === undefined,\n\t\tvalidate: (value) => (value.amount < 0 ? 'Must not be negative' : null)\n\t}\n});\n```\n\nRegister it: call registerFormInputs at the top level of a module the server and the browser both load before a form renders, such as one the root layout imports. Its keys are checked against the registry; built-in type names are refused, and registering a type again replaces it.\n\nThe component renders the control alone. Form wraps it in Field (label, description, errors) and hands it the field it registered, typed from the registry, plus the entry's own props:\n\n```svelte\n<!-- doc-fence: skip -->\n<!-- Needs the money registration above; tooling/component-contract/consumer-money-input.svelte is the checked copy. -->\n<script lang=\"ts\">\n\timport type { FormInputComponentProps } from 'entasis/form';\n\n\tlet { field, currencies = ['EUR'] }: FormInputComponentProps<'money'> = $props();\n\tconst currency = $derived(field.value?.currency ?? currencies[0] ?? 'EUR');\n</script>\n\n<input\n\ttype=\"number\"\n\t{...field.controlAttrs}\n\t{@attach field.control}\n\tvalue={field.value?.amount ?? ''}\n\toninput={(event) => field.setValue({ amount: Number(event.currentTarget.value), currency })}\n/>\n```\n\nEntries then use the type like a built-in one, in Form inputs, groups, and ask():\n\n```ts\n// doc-fence: skip (needs the money registration above)\nconst result = await ask({\n\ttitle: 'Set a price',\n\tconfirm: 'Save',\n\tcancel: 'Cancel',\n\tinputs: { price: { type: 'money', label: 'Price', required: true, currencies: ['EUR', 'USD'] } }\n});\nif (result.submitted) result.value.price; // Money\n```\n\nEvery Field entry option applies (label, description, required, disabled, readOnly, messages, size, density, visible, defaultValue, onValidate, onValueChange, slots); any other key goes to the component. required rejects what isEmpty reports empty (by default null, undefined, an empty string, or an array with no values) with the catalog required message, and isEmpty also decides whether the field reads as filled; validate runs for every entry of the type, before the entry's own onValidate. The value takes part in bind:value, visibility, validation, submission, and InferFormValue like a built-in input's. An entry whose type is neither built-in nor registered throws when the form reads it.\n\n## Non-value entries\n\nUse type: 'action' to place a labelled row of buttons in the ordered inputs flow. It accepts optional label and description content plus the same Form-aware action objects as the top-level actions prop. Its label position follows the Form layout unless labelPosition overrides it. Form size is the default button size, action density follows the Form, and loading or disabled protection cannot be overridden while the Form is submitting.\n\nUse type: 'custom' to place a snippet in the flow. The snippet receives the live public FormState and owns its own surface and padding; Form adds neither. Both entry types support class and visible, may appear at the top level or inside a group, and are omitted from bind:value, validation, and inferred submission output:\n\n```svelte\n{#snippet accountStatus(form)}\n\t<p>{Object.keys(form.value).length} visible values</p>\n{/snippet}\n\n<Form\n\tinputs={{\n\t\tname: { type: 'text', label: 'Name', required: true },\n\t\tstatus: { type: 'custom', snippet: accountStatus },\n\t\tcontrols: {\n\t\t\ttype: 'action',\n\t\t\tlabel: 'Account actions',\n\t\t\tdescription: 'Validate or save this account.',\n\t\t\tactions: [\n\t\t\t\t{ children: 'Validate', variant: 'soft', onAction: (payload) => payload.validate() },\n\t\t\t\t{ children: 'Save', onAction: (payload) => payload.submit() }\n\t\t\t]\n\t\t}\n\t}}\n/>\n```\n\nFor this configuration, InferFormValue contains name only; status and controls are presentation keys.\n\n## Validation\n\nBuilt-in validation uses the field schema. Every 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 (for a checkbox or switch, that it must be on), and email, URL, length, range and incomplete-code failures each have their own message. Override them per entry with messages:\n\n```ts\nimport type { FormInputs } from 'entasis/form';\n\nexport const inputs = {\n\tname: { type: 'text', label: 'Name', required: true, messages: { required: 'Enter your name' } },\n\tcode: {\n\t\ttype: 'pin',\n\t\tlabel: 'Code',\n\t\tlength: 6,\n\t\trequired: true,\n\t\tmessages: { incomplete: (length) => 'Enter the ' + length + '-digit code' }\n\t}\n} satisfies FormInputs;\n```\n\nonValidate may return:\n\n- false, null, undefined, an empty string, or an empty array for valid input;\n- true for the catalog's generic invalid message;\n- a string for one error, shown verbatim;\n- a string array for multiple errors.\n\nValidation runs on submission. Failed submission scrolls to and focuses the first invalid control in render order. Disabled fields, directly or through a disabled group or Form, skip validation and are left out of the submitted value, as in a native form; entries that declare disabled become optional keys in InferFormValue. Read-only fields still validate and submit.\n\n### When fields validate\n\nvalidationMode on the Form, or on one entry, picks when a field validates by itself:\n\n```ts\nimport type { FormInputs } from 'entasis/form';\n\nexport const inputs = {\n\tusername: { type: 'text', label: 'Username', required: true, validationMode: 'change' },\n\temail: { type: 'email', label: 'Email', required: true }\n} satisfies FormInputs;\n// <Form {inputs} validationMode=\"blur\" />: email validates when focus leaves it,\n// username validates on every change.\n```\n\nsubmit (the default) validates on a submit attempt, and from then on re-validates each edited field. blur validates when focus leaves the field, including a popup the field opened. change validates on every accepted change, including values synced from a parent. Whatever the mode, a field that shows an error re-validates as it is edited, and a blur that settles the value (trimming, say) validates the settled value. validationDebounce delays the validation an edit triggers; submit and blur never wait.\n\n### Async validators\n\nonValidate may return a promise. While it is pending the field is neither valid nor invalid: no aria-invalid and no data-invalid, and its root carries data-validating. A result for an older value is dropped, a rejected promise marks the field invalid with the generic message, and unmounting cancels the work. submit() waits for pending validators before it calls onSubmit (loading is true meanwhile); validate() stays synchronous, so use validateAsync() to wait.\n\n```ts\nimport type { FormInputs } from 'entasis/form';\n\ndeclare function isTaken(username: string): Promise<boolean>;\n\nexport const inputs = {\n\tusername: {\n\t\ttype: 'text',\n\t\tlabel: 'Username',\n\t\trequired: true,\n\t\tonValidate: async (username) => ((await isTaken(username)) ? 'That username is taken' : null)\n\t}\n} satisfies FormInputs;\n```\n\n### Server errors\n\nPass the errors of a failed save as the errors prop or call form.setErrors(). They show under their fields, are not wiped by validation, do not block a re-submit, and clear on that field's next change:\n\n```svelte\n<script lang=\"ts\">\n\timport { Form, type FormState, type FormInputs } from 'entasis/form';\n\n\tconst inputs = {\n\t\temail: { type: 'email', label: 'Email', required: true }\n\t} satisfies FormInputs;\n\n\tlet form = $state<FormState<typeof inputs>>();\n</script>\n\n<Form\n\t{inputs}\n\tbind:form\n\tonSubmit={async (value) => {\n\t\tconst response = await fetch('/api/signup', { method: 'POST', body: JSON.stringify(value) });\n\t\tif (!response.ok) form?.setErrors({ email: 'Already registered' });\n\t}}\n/>\n```\n\n### Dirty, touched and reset\n\nEvery field reports touched, dirty and filled (data-touched, data-dirty and data-filled on its root); form.dirty and form.touched are true when any field is. form.reset() returns every field to its initial value and clears errors, touched and dirty; form.reset(value) restores the given values instead and makes them the new baseline.\n\nErrors fade and grow in; reduced motion and the Theme motion tokens apply (the field theme motion slot).\n\n## Supported input types\n\ntext, email, url, password, number, rating, voice, slider, slider-range, textarea, rich-text, select, select-multiple, combobox, radio, checkboxes, checkbox, switch, phone, calendar, calendar-range, date, datetime, color, file, files, tag-group, tag, keyvalue, pin, and time.\n\nAlternative displays are display: 'selector' for date and calendar-range, and display: 'picker' for color.\n\nfield is the custom value-bearing entry. group, action, and custom are structural visual nodes rather than value-bearing input types.\n";

package/dist/components/Form/Form/form.mcp.js

@@ -132,7 +132,7 @@ Mount one Ask host near the application root, then call ask() from any client-si
 <Ask />
 \`\`\`
 
-AskOptions accepts inputs, value, onSubmit, class, size, density, variant, layout, theme, validationMode, and validationDebounce with the same contracts as Form. Disabled fields are left out of the result. title is required for the Dialog's accessible name. confirm and cancel accept a string or Button presentation props plus text. Their click, loading, link, and native type behavior is owned by Ask. Set type on the mounted Ask host for its default Dialog type; a request's optional dialog object may override type and also accepts responsive, size, and scroll.
+AskOptions accepts inputs, value, onSubmit, class, size, density, variant, layout, theme, validationMode, and validationDebounce with the same contracts as Form. Disabled fields are left out of the result. title is required for the Dialog's accessible name. confirm and cancel accept a string or Button presentation props plus text. Their click, loading, link, and native type behavior is owned by Ask. Set type on the mounted Ask host for its default Dialog type; a request's optional dialog object may override type and also accepts responsive, size, and scroll. With scroll 'inner' (the default) the form is the Dialog's only scrolling part: a form taller than the viewport scrolls inside its body (\`data-slot="ask-body"\`) while the title, description and Confirm/Cancel row stay on screen, and the body keeps room around its fields so a focus ring is never clipped. With scroll 'outer' the whole card grows and the page behind it scrolls instead.
 
 Validation failures keep the Dialog open and focus the first invalid field. A successful submission resolves with the validated visible payload. Cancel, the close button, and Escape resolve with submitted: false and the current partial visible value. Outside-click and swipe dismissal are disabled. While submission is active, all close paths and actions are protected. Rejected onSubmit promises reject ask() after the Dialog closes. Concurrent ask() calls render as independent stacked Dialogs. Calling ask() during SSR or without one mounted host rejects clearly.
 

package/dist/components/Sidebar/sidebar-layout.js

@@ -59,6 +59,8 @@ export function getSidebarPanelPeekClass(variant) {
  * ones for floating and split (the panel's own gutter spaces the pair).
  */
 export function getSidebarActivityBarContainerClass(side, frame, variant) {
-    return cx('inset-y-0 z-30 hidden w-[var(--sidebar-activity-offset,3rem)] md:flex', frame === 'viewport' ? 'fixed h-window' : 'absolute h-full', side === 'left' ? 'left-0' : 'right-0', variant === 'inset' && 'py-md', (variant === 'floating' || variant === 'split') &&
+    // Above the panel in every state, a peek (`z-40`) included: an edge-revealed panel slides in
+    // from past the screen edge and must come out from under the rail, never across it.
+    return cx('inset-y-0 z-[45] hidden w-[var(--sidebar-activity-offset,3rem)] md:flex', frame === 'viewport' ? 'fixed h-window' : 'absolute h-full', side === 'left' ? 'left-0' : 'right-0', variant === 'inset' && 'py-md', (variant === 'floating' || variant === 'split') &&
         (side === 'left' ? 'py-md pl-md' : 'py-md pr-md'));
 }

package/dist/components/Timeline/Timeline.svelte

@@ -15,7 +15,7 @@
 		size = 'normal',
 		density = 'normal',
 		color = 'neutral',
-		connectorColor = 'neutral',
+		connectorColor,
 		showConnectors = true,
 		scrollFade = true,
 		i18n,

package/dist/components/Timeline/TimelineEntry.svelte

@@ -1,4 +1,5 @@
 <script lang="ts" generics="Item extends TimelineItem = TimelineItem">
+	import { checkIcon } from '../Icons/check.js';
 	import Slot from '../Slot/Slot.svelte';
 	import Spinner from '../Spinner/Spinner.svelte';
 	import type { Density, Sizes } from '../../types/theme.js';
@@ -64,6 +65,8 @@
 	data-density={density}
 	data-first={entry.isFirst ? 'true' : undefined}
 	data-last={entry.isLast ? 'true' : undefined}
+	data-progress={entry.item.progress}
+	aria-current={entry.item.progress === 'current' ? 'step' : undefined}
 	class={classes.item({
 		orientation: entry.orientation,
 		placement,
@@ -107,9 +110,11 @@
 			<span
 				data-slot="timeline-connector"
 				data-color={entry.connectorColor}
+				data-progress={entry.item.progress}
 				class={classes.connector({
 					orientation: entry.orientation,
-					color: entry.connectorColor
+					color: entry.connectorColor,
+					progress: entry.item.progress ?? 'none'
 				})}
 			></span>
 		{/if}
@@ -182,7 +187,12 @@
 	<span
 		data-slot="timeline-marker"
 		data-color={entry.color}
-		class={classes.marker({ size, color: entry.color })}
+		data-progress={entry.item.loading ? undefined : entry.item.progress}
+		class={classes.marker({
+			size,
+			color: entry.color,
+			progress: entry.item.loading ? 'none' : (entry.item.progress ?? 'none')
+		})}
 	>
 		{#if entry.item.loading}
 			<span data-slot="timeline-loading" class={classes.loading({ size })}>
@@ -190,6 +200,10 @@
 			</span>
 		{:else if entry.item.icon}
 			<Slot render={entry.item.icon} />
+		{:else if entry.item.progress === 'done'}
+			{@render checkIcon()}
+		{:else if entry.item.progress === 'upcoming'}
+			<span data-slot="timeline-step-number">{entry.index + 1}</span>
 		{:else}
 			<span data-slot="timeline-dot"></span>
 		{/if}

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

@@ -1,3 +1,3 @@
 export { default as Timeline } from './Timeline.svelte';
-export type { TimelineItem, TimelineItemPayload, TimelineOrientation, TimelinePlacement, TimelineProps, TimelineSide, TimelineVariant } from './timeline.props.js';
+export type { TimelineItem, TimelineItemPayload, TimelineOrientation, TimelinePlacement, TimelineProgress, TimelineProps, TimelineSide, TimelineVariant } from './timeline.props.js';
 export { timelineTheme, setTimelineTheme, useTimelineTheme, type TimelineTheme, type TimelineThemeProps } from './timeline.theme.js';

package/dist/components/Timeline/timeline.items.d.ts

@@ -11,4 +11,4 @@ export type ResolvedTimelineItem<Item extends TimelineItem> = Readonly<{
     isFirst: boolean;
     isLast: boolean;
 }>;
-export declare function resolveTimelineItems<Item extends TimelineItem>(items: readonly Item[], orientation: TimelineOrientation, placement: TimelinePlacement, color: Colors, connectorColor: Colors): readonly ResolvedTimelineItem<Item>[];
+export declare function resolveTimelineItems<Item extends TimelineItem>(items: readonly Item[], orientation: TimelineOrientation, placement: TimelinePlacement, color: Colors, connectorColor: Colors | undefined): readonly ResolvedTimelineItem<Item>[];

package/dist/components/Timeline/timeline.items.js

@@ -17,6 +17,7 @@ export function resolveTimelineItems(items, orientation, placement, color, conne
         const side = placement === 'alternate'
             ? (timelineItem.side ?? (index % 2 === 0 ? 'end' : 'start'))
             : placement;
+        const itemColor = timelineItem.color ?? color;
         let key = `index:${index}`;
         if (explicitId !== undefined) {
             key = `id:${typeof explicitId}:${explicitId}`;
@@ -27,8 +28,12 @@ export function resolveTimelineItems(items, orientation, placement, color, conne
             index,
             side,
             orientation,
-            color: timelineItem.color ?? color,
-            connectorColor: timelineItem.connectorColor ?? connectorColor,
+            color: itemColor,
+            // A progress band reads as one stroke: its connectors follow the step's own color
+            // unless a connector color is set on the item or the root.
+            connectorColor: timelineItem.connectorColor ??
+                connectorColor ??
+                (timelineItem.progress ? itemColor : 'neutral'),
             isFirst: index === 0,
             isLast: index === items.length - 1
         };

package/dist/components/Timeline/timeline.mcp.d.ts

@@ -1 +1 @@
-export declare const timelineDescription = "\n# Timeline\n\nRender an ordered sequence of dated or descriptive events on a vertical or horizontal axis. Timeline owns the semantic list, item surfaces, axis anchors, markers, connectors, responsive alternate collapse, and horizontal overflow behavior. Input order is always render order.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  const items: TimelineItem[] = [\n    {\n      id: 'placed',\n      date: 'Mar 15, 2024',\n      datetime: '2024-03-15',\n      title: 'Order placed',\n      description: 'Your order has been received.'\n    },\n    {\n      id: 'payment',\n      date: 'Mar 16, 2024',\n      datetime: '2024-03-16',\n      title: 'Payment confirmed',\n      color: 'success'\n    }\n  ];\n</script>\n\n<Timeline {items} />\n```\n\nThe default configuration is a vertical timeline with all content on the logical end side of the axis.\n\n## Props\n\n### Data and layout\n\n- **items**: `readonly Item[]` (required) \u2014 entries in display order. `Item` must extend `TimelineItem`.\n- **orientation**: `'vertical' | 'horizontal'` (default: `'vertical'`) \u2014 direction of the sequence axis.\n- **placement**: `'start' | 'end' | 'alternate'` (default: `'end'`) \u2014 logical side used for item surfaces. Alternate placement starts on `end`, then alternates by array index.\n- **variant**: `'ghost' | 'card' | 'outline' | 'soft'` (default: `'ghost'`) \u2014 global surface treatment for all entries.\n- **size**: `'small' | 'normal' | 'large'` (default: `'normal'`) \u2014 title and description typography, marker and icon scale, and loading Spinner scale.\n- **density**: `'compact' | 'normal' | 'comfortable'` (default: `'normal'`) \u2014 item gaps, surface padding, connector spacing, and horizontal item minimum width.\n- **color**: Entasis semantic color (default: `'neutral'`) \u2014 default marker and outline or soft surface accent.\n- **connectorColor**: Entasis semantic color (default: `'neutral'`) \u2014 default outgoing connector color.\n- **showConnectors**: `boolean` (default: `true`) \u2014 shows connector segments between markers.\n- **scrollFade**: `boolean` (default: `true`) \u2014 applies the shared logical horizontal scroll fade only while a horizontal timeline actually overflows.\n- **i18n**: `Partial<Messages>` \u2014 per-instance translations merged over the global i18n catalog.\n\n### Custom rendering\n\n- **item**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the content inside each Timeline-owned variant surface.\n- **marker**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the marker visual inside the Timeline-owned axis anchor.\n- **opposite**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the opposite track in alternate placement. Its default renderer is the item date. TypeScript rejects this prop with fixed `start` or `end` placement.\n\n### Root element\n\n- **ref**: `HTMLOListElement | null` (bindable) \u2014 reference to the root `<ol>`.\n- **class**: `string` \u2014 additional root classes.\n- **theme**: `TimelineThemeProps` \u2014 per-instance overrides for Timeline theme parts.\n- Native ordered-list attributes and Svelte attachments are forwarded to the root.\n\n## Item shape\n\n```ts\ntype TimelineItem = {\n  id?: string | number;\n  title: Slot;\n  date?: Slot;\n  datetime?: string;\n  description?: Slot;\n  icon?: Slot;\n  loading?: boolean;\n  color?: Colors;\n  connectorColor?: Colors;\n  side?: 'start' | 'end';\n};\n```\n\n- `title` is required. `title`, `date`, `description`, and `icon` accept a string or snippet.\n- `id` is optional. Use a stable explicit ID when entries can reorder; otherwise Timeline uses the array index as identity.\n- `datetime` adds the machine-readable value to a default `<time>` element when `date` is present.\n- `icon` replaces the default dot inside the default marker.\n- `loading` replaces the default marker visual with a color- and size-aware Spinner.\n- `color` overrides the root color for this marker and its outline or soft surface.\n- `connectorColor` overrides the root color for this item's outgoing connector. It has no effect on the final item.\n- `side` overrides alternate parity for one item. It is not valid with fixed placement.\n\n## Placement and dates\n\nFixed `start` and `end` placement keeps every surface on one logical side. The default content renders the date before the title inside each surface.\n\n`placement=\"alternate\"` creates an opposite track and starts the first item on `end`. Its default opposite renderer displays the date. Set `item.side` to place a specific alternate item on `start` or `end` without changing the array order.\n\n```svelte\n<Timeline items={milestones} placement=\"alternate\" variant=\"card\" />\n```\n\nTimeline treats dates as display content. It does not parse, format, compare, or sort them. It also has no completed, current, or pending status model. Put status meaning in the title or description and use semantic color or a custom marker only as supporting presentation.\n\n## Generic snippets and defaults\n\nApplication item types can extend `TimelineItem`. The extended type remains available as `payload.item` in all three renderer snippets.\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  type Release = TimelineItem & {\n    version: string;\n    href: string;\n  };\n\n  const releases: Release[] = [\n    { id: 'v2', title: 'Version 2 released', version: '2.0.0', href: '/releases/v2' }\n  ];\n</script>\n\n<Timeline items={releases}>\n  {#snippet item({ item, defaultContent })}\n    <a href={item.href} class=\"block\">\n      {@render defaultContent()}\n      <span class=\"text-neutral/70 text-xs\">{item.version}</span>\n    </a>\n  {/snippet}\n</Timeline>\n```\n\nEvery snippet receives:\n\n```ts\ntype TimelineItemPayload<Item extends TimelineItem> = Readonly<{\n  item: Item;\n  index: number;\n  side: 'start' | 'end';\n  orientation: 'vertical' | 'horizontal';\n  color: Colors;\n  connectorColor: Colors;\n  isFirst: boolean;\n  isLast: boolean;\n  defaultContent: Snippet;\n  defaultMarker: Snippet;\n  defaultOpposite: Snippet;\n}>;\n```\n\nCall `defaultContent()`, `defaultMarker()`, or `defaultOpposite()` to wrap or extend the matching default renderer. A custom `marker` snippet that does not call `defaultMarker()` owns its complete marker visual, including loading presentation. Timeline still owns the `<ol>`, each `<li>`, axis and connector geometry, marker anchor, opposite track, and variant surface.\n\n## Responsive alternate layout\n\nA vertical alternate timeline uses its own inline-size container. Below `40rem`, it moves the axis to the logical start edge, places every main surface on the end side, and places opposite content before the main surface. DOM and input order do not change. Per-item `side` values remain in the payload, but their visual side effect is suspended while the layout is collapsed.\n\n## Horizontal overflow\n\nHorizontal entries stay on one axis and use density-controlled minimum widths. They do not wrap or compress; the root uses native horizontal scrolling. Timeline measures real overflow with `ResizeObserver`, applies `scroll-fade-x` only when needed, and makes the ordered list keyboard-focusable only while it overflows. The fade and native scrolling use logical inline direction and work in LTR and RTL layouts.\n\n## Variants\n\n- `ghost`: no surface chrome.\n- `card`: neutral raised surface with a quiet ring and shadow.\n- `outline`: transparent surface with a ring in the resolved item color.\n- `soft`: muted surface in the resolved item color.\n\nThe variant is global. Timeline does not support per-item variant overrides.\n\n## Runtime validation\n\nTimeline throws a descriptive `TypeError` when:\n\n- two items have the same explicit `id`;\n- an item supplies `side` while placement is fixed to `start` or `end`.\n\nThe ID check preserves number and string identity, so `1` and `'1'` are different IDs. TypeScript separately rejects `opposite` with fixed placement.\n\n## Accessibility\n\n- The root is an ordered list and every event is a list item.\n- Axis anchors, markers, and connectors are decorative and hidden from assistive technology. Do not use marker color or shape as the only status signal.\n- A default loading marker has a localized polite status announcement outside the decorative axis.\n- A default date with `datetime` renders as a semantic `<time>` element.\n- An overflowing horizontal timeline becomes a native keyboard scroll region; a non-overflowing timeline adds no tab stop.\n\n## Theme parts\n\n`root`, `item`, `opposite`, `axis`, `connector`, `marker`, `content`, `date`, `titleRow`, `title`, `description`, and `loading`.\n\nTimeline is display-only. It has no selection, navigation, event callbacks, animation state, bindable controller, date processing, or built-in progress status.\n";
+export declare const timelineDescription = "\n# Timeline\n\nRender an ordered sequence of dated or descriptive events on a vertical or horizontal axis. Timeline owns the semantic list, item surfaces, axis anchors, markers, connectors, responsive alternate collapse, and horizontal overflow behavior. Input order is always render order.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  const items: TimelineItem[] = [\n    {\n      id: 'placed',\n      date: 'Mar 15, 2024',\n      datetime: '2024-03-15',\n      title: 'Order placed',\n      description: 'Your order has been received.'\n    },\n    {\n      id: 'payment',\n      date: 'Mar 16, 2024',\n      datetime: '2024-03-16',\n      title: 'Payment confirmed',\n      color: 'success'\n    }\n  ];\n</script>\n\n<Timeline {items} />\n```\n\nThe default configuration is a vertical timeline with all content on the logical end side of the axis.\n\n## Props\n\n### Data and layout\n\n- **items**: `readonly Item[]` (required) \u2014 entries in display order. `Item` must extend `TimelineItem`.\n- **orientation**: `'vertical' | 'horizontal'` (default: `'vertical'`) \u2014 direction of the sequence axis.\n- **placement**: `'start' | 'end' | 'alternate'` (default: `'end'`) \u2014 logical side used for item surfaces. Alternate placement starts on `end`, then alternates by array index.\n- **variant**: `'ghost' | 'card' | 'outline' | 'soft'` (default: `'ghost'`) \u2014 global surface treatment for all entries.\n- **size**: `'small' | 'normal' | 'large'` (default: `'normal'`) \u2014 title and description typography, marker and icon scale, and loading Spinner scale.\n- **density**: `'compact' | 'normal' | 'comfortable'` (default: `'normal'`) \u2014 item gaps, surface padding, connector spacing, and horizontal item minimum width.\n- **color**: Entasis semantic color (default: `'neutral'`) \u2014 default marker and outline or soft surface accent.\n- **connectorColor**: Entasis semantic color \u2014 default outgoing connector color. When omitted, an item with `progress` uses its own resolved color for its connector, and every other item uses `'neutral'`.\n- **showConnectors**: `boolean` (default: `true`) \u2014 shows connector segments between markers.\n- **scrollFade**: `boolean` (default: `true`) \u2014 applies the shared logical horizontal scroll fade only while a horizontal timeline actually overflows.\n- **i18n**: `Partial<Messages>` \u2014 per-instance translations merged over the global i18n catalog.\n\n### Custom rendering\n\n- **item**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the content inside each Timeline-owned variant surface.\n- **marker**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the marker visual inside the Timeline-owned axis anchor.\n- **opposite**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the opposite track in alternate placement. Its default renderer is the item date. TypeScript rejects this prop with fixed `start` or `end` placement.\n\n### Root element\n\n- **ref**: `HTMLOListElement | null` (bindable) \u2014 reference to the root `<ol>`.\n- **class**: `string` \u2014 additional root classes.\n- **theme**: `TimelineThemeProps` \u2014 per-instance overrides for Timeline theme parts.\n- Native ordered-list attributes and Svelte attachments are forwarded to the root.\n\n## Item shape\n\n```ts\ntype TimelineItem = {\n  id?: string | number;\n  title: Slot;\n  date?: Slot;\n  datetime?: string;\n  description?: Slot;\n  icon?: Slot;\n  loading?: boolean;\n  color?: Colors;\n  connectorColor?: Colors;\n  progress?: 'done' | 'current' | 'upcoming';\n  side?: 'start' | 'end';\n};\n```\n\n- `title` is required. `title`, `date`, `description`, and `icon` accept a string or snippet.\n- `id` is optional. Use a stable explicit ID when entries can reorder; otherwise Timeline uses the array index as identity.\n- `datetime` adds the machine-readable value to a default `<time>` element when `date` is present.\n- `icon` replaces the default dot inside the default marker.\n- `loading` replaces the default marker visual with a color- and size-aware Spinner.\n- `color` overrides the root color for this marker and its outline or soft surface.\n- `connectorColor` overrides the root color for this item's outgoing connector. It has no effect on the final item.\n- `side` overrides alternate parity for one item. It is not valid with fixed placement.\n- `progress` marks a step of a process (`TimelineProgress`). See Step progress below.\n\n## Placement and dates\n\nFixed `start` and `end` placement keeps every surface on one logical side. The default content renders the date before the title inside each surface.\n\n`placement=\"alternate\"` creates an opposite track and starts the first item on `end`. Its default opposite renderer displays the date. Set `item.side` to place a specific alternate item on `start` or `end` without changing the array order.\n\n```svelte\n<Timeline items={milestones} placement=\"alternate\" variant=\"card\" />\n```\n\nTimeline treats dates as display content. It does not parse, format, compare, or sort them.\n\n## Step progress\n\nGive each item a `progress` to draw a process's progress band, such as a file's six stages, so a reader sees at a glance what is done, what is under way, and what is to come:\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  const steps: TimelineItem[] = [\n    { id: 'opened', title: 'Opened', progress: 'done' },\n    { id: 'documents', title: 'Documents', progress: 'done' },\n    { id: 'appraisal', title: 'Appraisal', progress: 'current' },\n    { id: 'report', title: 'Report', progress: 'upcoming' }\n  ];\n</script>\n\n<Timeline items={steps} orientation=\"horizontal\" color=\"primary\" />\n```\n\n- `done`: the marker is filled with the item color and carries a check. Its outgoing connector is solid.\n- `current`: the marker is a ring in the item color around a point. The `<li>` gets `aria-current=\"step\"`. Its outgoing connector is faint.\n- `upcoming`: the marker is a quiet neutral ring carrying the step number (the item's position, from 1). Its outgoing connector is faint.\n- Markers keep the size's marker scale. Progress connectors are 2px thick instead of the hairline, so the done part of the band stands out.\n- An item `icon` replaces the check, the point, or the number, and keeps the progress ring and fill. `loading` replaces the whole marker with the Spinner.\n- `progress` is per item: Timeline does not derive it from an index, so a host may mark any combination.\n- The step's state is not announced by the markers, which stay decorative. Put it in the item's own text (for example \"Step 3 of 6, done\") or an `item` snippet. `aria-current=\"step\"` on the current item is the only state Timeline adds.\n- The `marker` snippet still replaces every marker: read `payload.item.progress` and call `defaultMarker()` for the steps it leaves alone. Theme overrides reach the `progress` variant of the `marker` and `connector` parts, for example `theme={{ connector: { progress: { done: 'bg-success' } } }}`.\n- Styling hooks: `data-progress` on the item, its marker and its outgoing connector.\n\n## Generic snippets and defaults\n\nApplication item types can extend `TimelineItem`. The extended type remains available as `payload.item` in all three renderer snippets.\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  type Release = TimelineItem & {\n    version: string;\n    href: string;\n  };\n\n  const releases: Release[] = [\n    { id: 'v2', title: 'Version 2 released', version: '2.0.0', href: '/releases/v2' }\n  ];\n</script>\n\n<Timeline items={releases}>\n  {#snippet item({ item, defaultContent })}\n    <a href={item.href} class=\"block\">\n      {@render defaultContent()}\n      <span class=\"text-neutral/70 text-xs\">{item.version}</span>\n    </a>\n  {/snippet}\n</Timeline>\n```\n\nEvery snippet receives:\n\n```ts\ntype TimelineItemPayload<Item extends TimelineItem> = Readonly<{\n  item: Item;\n  index: number;\n  side: 'start' | 'end';\n  orientation: 'vertical' | 'horizontal';\n  color: Colors;\n  connectorColor: Colors;\n  isFirst: boolean;\n  isLast: boolean;\n  defaultContent: Snippet;\n  defaultMarker: Snippet;\n  defaultOpposite: Snippet;\n}>;\n```\n\nCall `defaultContent()`, `defaultMarker()`, or `defaultOpposite()` to wrap or extend the matching default renderer. A custom `marker` snippet that does not call `defaultMarker()` owns its complete marker visual, including loading presentation. Timeline still owns the `<ol>`, each `<li>`, axis and connector geometry, marker anchor, opposite track, and variant surface.\n\n## Responsive alternate layout\n\nA vertical alternate timeline uses its own inline-size container. Below `40rem`, it moves the axis to the logical start edge, places every main surface on the end side, and places opposite content before the main surface. DOM and input order do not change. Per-item `side` values remain in the payload, but their visual side effect is suspended while the layout is collapsed.\n\n## Horizontal overflow\n\nHorizontal entries stay on one axis and use density-controlled minimum widths. They do not wrap or compress; the root uses native horizontal scrolling. Timeline measures real overflow with `ResizeObserver`, applies `scroll-fade-x` only when needed, and makes the ordered list keyboard-focusable only while it overflows. The fade and native scrolling use logical inline direction and work in LTR and RTL layouts.\n\n## Variants\n\n- `ghost`: no surface chrome.\n- `card`: neutral raised surface with a quiet ring and shadow.\n- `outline`: transparent surface with a ring in the resolved item color.\n- `soft`: muted surface in the resolved item color.\n\nThe variant is global. Timeline does not support per-item variant overrides.\n\n## Runtime validation\n\nTimeline throws a descriptive `TypeError` when:\n\n- two items have the same explicit `id`;\n- an item supplies `side` while placement is fixed to `start` or `end`.\n\nThe ID check preserves number and string identity, so `1` and `'1'` are different IDs. TypeScript separately rejects `opposite` with fixed placement.\n\n## Accessibility\n\n- The root is an ordered list and every event is a list item.\n- Axis anchors, markers, and connectors are decorative and hidden from assistive technology. Do not use marker color or shape as the only status signal.\n- An item with `progress: 'current'` carries `aria-current=\"step\"`.\n- A default loading marker has a localized polite status announcement outside the decorative axis.\n- A default date with `datetime` renders as a semantic `<time>` element.\n- An overflowing horizontal timeline becomes a native keyboard scroll region; a non-overflowing timeline adds no tab stop.\n\n## Theme parts\n\n`root`, `item`, `opposite`, `axis`, `connector`, `marker`, `content`, `date`, `titleRow`, `title`, `description`, and `loading`.\n\nTimeline is display-only. It has no selection, navigation, event callbacks, animation state, bindable controller, or date processing. Step `progress` is presentation the host sets per item, not a state Timeline advances.\n";

package/dist/components/Timeline/timeline.mcp.js

@@ -43,7 +43,7 @@ The default configuration is a vertical timeline with all content on the logical
 - **size**: \`'small' | 'normal' | 'large'\` (default: \`'normal'\`) — title and description typography, marker and icon scale, and loading Spinner scale.
 - **density**: \`'compact' | 'normal' | 'comfortable'\` (default: \`'normal'\`) — item gaps, surface padding, connector spacing, and horizontal item minimum width.
 - **color**: Entasis semantic color (default: \`'neutral'\`) — default marker and outline or soft surface accent.
-- **connectorColor**: Entasis semantic color (default: \`'neutral'\`) — default outgoing connector color.
+- **connectorColor**: Entasis semantic color — default outgoing connector color. When omitted, an item with \`progress\` uses its own resolved color for its connector, and every other item uses \`'neutral'\`.
 - **showConnectors**: \`boolean\` (default: \`true\`) — shows connector segments between markers.
 - **scrollFade**: \`boolean\` (default: \`true\`) — applies the shared logical horizontal scroll fade only while a horizontal timeline actually overflows.
 - **i18n**: \`Partial<Messages>\` — per-instance translations merged over the global i18n catalog.
@@ -74,6 +74,7 @@ type TimelineItem = {
   loading?: boolean;
   color?: Colors;
   connectorColor?: Colors;
+  progress?: 'done' | 'current' | 'upcoming';
   side?: 'start' | 'end';
 };
 \`\`\`
@@ -86,6 +87,7 @@ type TimelineItem = {
 - \`color\` overrides the root color for this marker and its outline or soft surface.
 - \`connectorColor\` overrides the root color for this item's outgoing connector. It has no effect on the final item.
 - \`side\` overrides alternate parity for one item. It is not valid with fixed placement.
+- \`progress\` marks a step of a process (\`TimelineProgress\`). See Step progress below.
 
 ## Placement and dates
 
@@ -97,7 +99,36 @@ Fixed \`start\` and \`end\` placement keeps every surface on one logical side. T
 <Timeline items={milestones} placement="alternate" variant="card" />
 \`\`\`
 
-Timeline treats dates as display content. It does not parse, format, compare, or sort them. It also has no completed, current, or pending status model. Put status meaning in the title or description and use semantic color or a custom marker only as supporting presentation.
+Timeline treats dates as display content. It does not parse, format, compare, or sort them.
+
+## Step progress
+
+Give each item a \`progress\` to draw a process's progress band, such as a file's six stages, so a reader sees at a glance what is done, what is under way, and what is to come:
+
+\`\`\`svelte
+<script lang="ts">
+  import { Timeline, type TimelineItem } from './index.ts';
+
+  const steps: TimelineItem[] = [
+    { id: 'opened', title: 'Opened', progress: 'done' },
+    { id: 'documents', title: 'Documents', progress: 'done' },
+    { id: 'appraisal', title: 'Appraisal', progress: 'current' },
+    { id: 'report', title: 'Report', progress: 'upcoming' }
+  ];
+</script>
+
+<Timeline items={steps} orientation="horizontal" color="primary" />
+\`\`\`
+
+- \`done\`: the marker is filled with the item color and carries a check. Its outgoing connector is solid.
+- \`current\`: the marker is a ring in the item color around a point. The \`<li>\` gets \`aria-current="step"\`. Its outgoing connector is faint.
+- \`upcoming\`: the marker is a quiet neutral ring carrying the step number (the item's position, from 1). Its outgoing connector is faint.
+- Markers keep the size's marker scale. Progress connectors are 2px thick instead of the hairline, so the done part of the band stands out.
+- An item \`icon\` replaces the check, the point, or the number, and keeps the progress ring and fill. \`loading\` replaces the whole marker with the Spinner.
+- \`progress\` is per item: Timeline does not derive it from an index, so a host may mark any combination.
+- The step's state is not announced by the markers, which stay decorative. Put it in the item's own text (for example "Step 3 of 6, done") or an \`item\` snippet. \`aria-current="step"\` on the current item is the only state Timeline adds.
+- The \`marker\` snippet still replaces every marker: read \`payload.item.progress\` and call \`defaultMarker()\` for the steps it leaves alone. Theme overrides reach the \`progress\` variant of the \`marker\` and \`connector\` parts, for example \`theme={{ connector: { progress: { done: 'bg-success' } } }}\`.
+- Styling hooks: \`data-progress\` on the item, its marker and its outgoing connector.
 
 ## Generic snippets and defaults
 
@@ -177,6 +208,7 @@ The ID check preserves number and string identity, so \`1\` and \`'1'\` are diff
 
 - The root is an ordered list and every event is a list item.
 - Axis anchors, markers, and connectors are decorative and hidden from assistive technology. Do not use marker color or shape as the only status signal.
+- An item with \`progress: 'current'\` carries \`aria-current="step"\`.
 - A default loading marker has a localized polite status announcement outside the decorative axis.
 - A default date with \`datetime\` renders as a semantic \`<time>\` element.
 - An overflowing horizontal timeline becomes a native keyboard scroll region; a non-overflowing timeline adds no tab stop.
@@ -185,5 +217,5 @@ The ID check preserves number and string identity, so \`1\` and \`'1'\` are diff
 
 \`root\`, \`item\`, \`opposite\`, \`axis\`, \`connector\`, \`marker\`, \`content\`, \`date\`, \`titleRow\`, \`title\`, \`description\`, and \`loading\`.
 
-Timeline is display-only. It has no selection, navigation, event callbacks, animation state, bindable controller, date processing, or built-in progress status.
+Timeline is display-only. It has no selection, navigation, event callbacks, animation state, bindable controller, or date processing. Step \`progress\` is presentation the host sets per item, not a state Timeline advances.
 `;

package/dist/components/Timeline/timeline.props.d.ts

@@ -9,6 +9,12 @@ export type TimelineOrientation = 'vertical' | 'horizontal';
 export type TimelinePlacement = 'start' | 'end' | 'alternate';
 export type TimelineSide = 'start' | 'end';
 export type TimelineVariant = 'ghost' | 'card' | 'outline' | 'soft';
+/**
+ * Where a step stands in a process: finished, under way, or still to come. Drives the default
+ * marker (a filled check, a ring with a point, a quiet numbered ring) and the outgoing connector
+ * (solid after a finished step, faint after the others).
+ */
+export type TimelineProgress = 'done' | 'current' | 'upcoming';
 export type TimelineItem = {
     /** Stable identity. Use an explicit ID when the array can reorder. */
     id?: string | number;
@@ -28,6 +34,13 @@ export type TimelineItem = {
     color?: Colors;
     /** Outgoing connector color. Ignored on the final item. */
     connectorColor?: Colors;
+    /**
+     * Step progress. A `done` step draws a filled check and a solid outgoing connector, the
+     * `current` step a ring with a point and `aria-current="step"`, an `upcoming` step a quiet ring
+     * with its step number; the connectors after `current` and `upcoming` steps stay faint. An
+     * `icon` replaces the check, the point or the number; `loading` replaces the whole marker.
+     */
+    progress?: TimelineProgress;
     /** Logical side override. Valid only when placement is alternate. */
     side?: TimelineSide;
 };
@@ -69,7 +82,10 @@ export type TimelineProps<Item extends TimelineItem = TimelineItem> = WithAttach
     density?: Density;
     /** Default semantic item accent. */
     color?: Colors;
-    /** Default outgoing connector accent. */
+    /**
+     * Default outgoing connector accent. When omitted, an item with `progress` takes its own
+     * color for its connector, and every other item takes `neutral`.
+     */
     connectorColor?: Colors;
     /** Shows connector segments between markers. */
     showConnectors?: boolean;

package/dist/components/Timeline/timeline.theme.d.ts

@@ -109,6 +109,12 @@ export declare const timelineTheme: {
             readonly info: "";
             readonly neutral: "";
         };
+        progress: {
+            none: string;
+            done: string;
+            current: string;
+            upcoming: string;
+        };
     }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     marker: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
@@ -125,6 +131,12 @@ export declare const timelineTheme: {
             readonly info: "";
             readonly neutral: "";
         };
+        progress: {
+            none: string;
+            done: string;
+            current: string;
+            upcoming: string;
+        };
     }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     content: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         orientation: {
@@ -336,6 +348,12 @@ export declare const setTimelineTheme: (theme: InferComponentTheme<{
             readonly info: "";
             readonly neutral: "";
         };
+        progress: {
+            none: string;
+            done: string;
+            current: string;
+            upcoming: string;
+        };
     }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     marker: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
@@ -352,6 +370,12 @@ export declare const setTimelineTheme: (theme: InferComponentTheme<{
             readonly info: "";
             readonly neutral: "";
         };
+        progress: {
+            none: string;
+            done: string;
+            current: string;
+            upcoming: string;
+        };
     }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     content: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         orientation: {
@@ -561,6 +585,12 @@ export declare const useTimelineTheme: import("../../utils/cva/theme.ts").UseCom
             readonly info: "";
             readonly neutral: "";
         };
+        progress: {
+            none: string;
+            done: string;
+            current: string;
+            upcoming: string;
+        };
     }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     marker: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
@@ -577,6 +607,12 @@ export declare const useTimelineTheme: import("../../utils/cva/theme.ts").UseCom
             readonly info: "";
             readonly neutral: "";
         };
+        progress: {
+            none: string;
+            done: string;
+            current: string;
+            upcoming: string;
+        };
     }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     content: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         orientation: {

package/dist/components/Timeline/timeline.theme.js

@@ -248,6 +248,8 @@ const defaultAxis = cva({
         isLast: false
     }
 });
+// `progress` is the step the connector leaves: solid after a done step, faint after the
+// current and upcoming ones, so the band reads as finished up to the current step.
 const defaultConnector = cva({
     base: 'pointer-events-none absolute z-0 bg-color/35',
     variants: {
@@ -255,11 +257,22 @@ const defaultConnector = cva({
             vertical: 'left-1/2 top-[calc(var(--timeline-marker-size)/2)] h-full w-px -translate-x-1/2',
             horizontal: 'start-[calc(var(--timeline-marker-size)/2)] top-1/2 h-px w-full -translate-y-1/2'
         },
-        color: colorVariants
+        color: colorVariants,
+        progress: {
+            none: '',
+            done: 'bg-color',
+            current: 'bg-color/20',
+            upcoming: 'bg-color/20'
+        }
     },
+    compoundVariants: [
+        { orientation: 'vertical', progress: ['done', 'current', 'upcoming'], class: 'w-0.5' },
+        { orientation: 'horizontal', progress: ['done', 'current', 'upcoming'], class: 'h-0.5' }
+    ],
     defaultVariants: {
         orientation: 'vertical',
-        color: 'neutral'
+        color: 'neutral',
+        progress: 'none'
     }
 });
 const defaultMarker = cva({
@@ -270,11 +283,21 @@ const defaultMarker = cva({
             normal: 'size-[1.125rem]',
             large: 'size-[1.375rem]'
         },
-        color: colorVariants
+        color: colorVariants,
+        // A done step is filled with its check, the current one ringed around its point, an
+        // upcoming one a quiet ring around its step number. The number is a glyph drawn to the
+        // marker, like the check, so it scales with the marker size rather than the type ramp.
+        progress: {
+            none: '',
+            done: 'bg-color text-color-contrast ring-color',
+            current: 'ring-2 ring-color',
+            upcoming: 'text-neutral/70 ring-neutral-muted font-medium leading-none tabular-nums text-[length:calc(var(--timeline-marker-size)*0.55)]'
+        }
     },
     defaultVariants: {
         size: 'normal',
-        color: 'neutral'
+        color: 'neutral',
+        progress: 'none'
     }
 });
 const defaultContent = cva({

package/dist/generated/componentContract.d.ts

@@ -1098,7 +1098,7 @@ export declare const componentInventory: readonly [{
     readonly id: "timeline";
     readonly subpath: "entasis/timeline";
     readonly sourceIndex: "src/lib/components/Timeline/index.ts";
-    readonly exportedSymbols: readonly ["Timeline", "TimelineItem", "TimelineItemPayload", "TimelineOrientation", "TimelinePlacement", "TimelineProps", "TimelineSide", "TimelineTheme", "TimelineThemeProps", "TimelineVariant", "setTimelineTheme", "timelineTheme", "useTimelineTheme"];
+    readonly exportedSymbols: readonly ["Timeline", "TimelineItem", "TimelineItemPayload", "TimelineOrientation", "TimelinePlacement", "TimelineProgress", "TimelineProps", "TimelineSide", "TimelineTheme", "TimelineThemeProps", "TimelineVariant", "setTimelineTheme", "timelineTheme", "useTimelineTheme"];
     readonly docs: readonly [{
         readonly id: "timeline";
         readonly route: "/components/timeline";

package/dist/generated/componentContract.js

@@ -2811,6 +2811,7 @@ export const componentInventory = [
             'TimelineItemPayload',
             'TimelineOrientation',
             'TimelinePlacement',
+            'TimelineProgress',
             'TimelineProps',
             'TimelineSide',
             'TimelineTheme',

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "entasis",
-	"version": "0.13.3",
+	"version": "0.13.5",
 	"license": "MIT",
 	"scripts": {
 		"dev": "vite dev",