entasis 0.10.2 → 0.12.0

package/dist/components/Form/Autocomplete/Autocomplete.svelte

@@ -0,0 +1,418 @@
+<script lang="ts">
+	// Free text with suggestions. The value is the text in the input and the input submits it, so
+	// a suggestion is a shortcut for typing, never a requirement. The list, its keyboard model,
+	// async source and announcements are Combobox's controller; this file adds what only free
+	// text needs: the text as the value, and inline completion that previews the highlighted
+	// suggestion in the input without committing it.
+	import { tick, untrack } from 'svelte';
+	import { useI18n } from '../../../i18n/context.svelte.js';
+	import { createBindableValue } from '../../../utils/state.svelte.js';
+	import Field from '../Field/Field.svelte';
+	import { createFieldState } from '../Field/field.state.svelte.js';
+	import Popover from '../../Popover/Popover.svelte';
+	import type { PopoverApi } from '../../Popover/popover.api.js';
+	import ComboboxPopup from '../Combobox/ComboboxPopup.svelte';
+	import { ComboboxController } from '../Combobox/combobox.state.svelte.js';
+	import { flattenItems } from '../Combobox/combobox.items.js';
+	import type { ComboboxFilter } from '../Combobox/combobox.props.js';
+	import { completeInline, normalizeSource } from './autocomplete.items.js';
+	import type { AutocompleteProps } from './autocomplete.props.js';
+	import { useAutocompleteTheme } from './autocomplete.theme.js';
+
+	let {
+		defaultValue = null,
+		value = $bindable(),
+		errors = $bindable([]),
+		focused = $bindable(false),
+		open = $bindable(),
+		defaultOpen = false,
+		onOpenChange,
+		onAfterOpen,
+		onAfterClose,
+		required = false,
+		size = 'normal',
+		density = 'normal',
+		placeholder = '',
+		items,
+		mode = 'list',
+		autoHighlight = false,
+		openOnFocus = false,
+		shouldFilter = true,
+		filter,
+		limit,
+		loop,
+		onSelect,
+		onHighlightChange,
+		loadingText,
+		emptyText,
+		autocomplete = 'off',
+		separators = true,
+		item,
+		inputAttrs,
+		i18n,
+		theme,
+		disabled,
+		readOnly,
+		messages,
+		name,
+		onValidate,
+		onValueChange,
+		visible,
+		prefix,
+		suffix,
+		description,
+		...rest
+	}: AutocompleteProps = $props();
+	if (value === undefined) value = untrack(() => defaultValue);
+
+	const id = $props.id();
+	const t = $derived(useI18n(i18n));
+	const openState = createBindableValue(
+		() => open,
+		(next) => {
+			open = next;
+		},
+		() => defaultOpen
+	);
+	let loading = $state(false);
+
+	const field = createFieldState({
+		id,
+		get value() {
+			return value;
+		},
+		set value(v) {
+			value = v;
+		},
+		get errors() {
+			return errors;
+		},
+		set errors(v: string[] | boolean) {
+			errors = v;
+		},
+		get focused() {
+			return focused;
+		},
+		set focused(v: boolean) {
+			focused = v;
+		},
+		onValueChange: (v) => {
+			onValueChange?.(v);
+		},
+		get disabled() {
+			return disabled;
+		},
+		set disabled(v: boolean | undefined) {
+			disabled = v;
+		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
+		get required() {
+			return required;
+		},
+		get name() {
+			return name;
+		},
+		set name(v: string | undefined) {
+			name = v;
+		},
+		get onValidate() {
+			return onValidate;
+		},
+		get visible() {
+			return visible;
+		},
+		type: 'text'
+	});
+
+	// Only a name the app gave, directly or through Form, is submitted, as for a native input.
+	const submittedName = $derived(
+		field.name === `${field.type}-input-${field.id}` ? undefined : field.name
+	);
+
+	const text = $derived(field.value ?? '');
+	const source = $derived(normalizeSource(items));
+	// Inline and none modes list the suggestions as given; list and both narrow them to the text.
+	const everything: ComboboxFilter = () => true;
+	const narrowing = $derived(shouldFilter && (mode === 'list' || mode === 'both'));
+
+	const controller = new ComboboxController({
+		id,
+		field,
+		items: () => source,
+		filter: () => (narrowing ? filter : everything),
+		limit: () => limit,
+		messages: () => t,
+		loadingText: () => loadingText,
+		noOptionsText: () => emptyText,
+		query: {
+			get: () => text,
+			set: (next) => {
+				field.setValue(next);
+			}
+		},
+		// The text is a value here, not a search draft: a prefilled or just chosen text does not
+		// ask the source anything until the list is open for it.
+		searching: () => openState.value,
+		loading: {
+			get: () => loading,
+			set: (next) => {
+				loading = next;
+			}
+		},
+		open: {
+			get: () => openState.value,
+			set: (next) => {
+				openState.value = next;
+			}
+		},
+		onOpenChange: () => onOpenChange,
+		openOnFocus: () => openOnFocus,
+		autoHighlight: () => autoHighlight,
+		loop: () => loop,
+		onHighlightChange: () => onHighlightChange,
+		onSelect: (option, event) => {
+			previewing = null;
+			field.setValue(option.label);
+			controller.close({ reason: 'item-press', event });
+			// The caret goes to the end of the chosen text once it is in the input.
+			void tick().then(() => {
+				const input = inputElement();
+				if (input && input.ownerDocument.activeElement === input) {
+					input.setSelectionRange(input.value.length, input.value.length);
+				}
+			});
+			onSelect?.({ item: option, value: option.label, event });
+		}
+	});
+
+	// -- Inline completion ----------------------------------------------------------------
+	// While a suggestion is previewed the input shows its label but the value stays the typed
+	// text, so `previewing.typed` is what Escape, blur and a closing list put back.
+
+	const inputElement = () => field.node as HTMLInputElement | null;
+	const inlineEnabled = $derived(
+		(mode === 'both' || mode === 'inline') && !field.readOnly && !field.disabled
+	);
+	let previewing: { typed: string; text: string } | null = null;
+	// Deleting the completion (or accepting it) must not bring it straight back.
+	let holdCompletion = false;
+	// The highlight change an ArrowUp or ArrowDown caused: the only kind that may replace the text
+	// with a suggestion that does not continue it.
+	let keyed: object | null = null;
+	let composing = $state(false);
+	let syncedText = untrack(() => text);
+
+	const restorePreview = () => {
+		if (!previewing) return;
+		const { typed } = previewing;
+		previewing = null;
+		const input = inputElement();
+		if (!input) return;
+		input.value = typed;
+		if (input.ownerDocument.activeElement === input)
+			input.setSelectionRange(typed.length, typed.length);
+	};
+
+	// Keeps the input in step with the highlight: the highlighted suggestion is previewed while
+	// keys or typing drive it. A hover leaves the text alone.
+	$effect(() => {
+		const current = text;
+		const highlighted = controller.nav.highlighted;
+		const details = controller.nav.highlightDetails;
+		const listed = controller.expanded;
+		const isFocused = field.focused;
+		const enabled = inlineEnabled;
+		const busy = composing;
+		untrack(() => {
+			const edited = current !== syncedText;
+			syncedText = current;
+			if (edited && previewing) {
+				// The value moved on without the user's keys (the parent set it): drop the preview.
+				const input = inputElement();
+				if (input) input.value = current;
+				previewing = null;
+			}
+			if (busy) return;
+			if (!enabled || !listed || !isFocused || highlighted === undefined) {
+				restorePreview();
+				return;
+			}
+			const reason = details === keyed ? 'keyboard' : details.reason;
+			if (reason === 'pointer') return;
+			const option = flattenItems(controller.view.items).find(
+				(entry) => entry.value === highlighted
+			);
+			const input = inputElement();
+			if (!option || !input) {
+				restorePreview();
+				return;
+			}
+			const typed = previewing?.typed ?? current;
+			const completion = completeInline(option.label, typed, t.locale);
+			// The list's own choice (the first match as you type) only completes what was typed;
+			// arrow keys may land anywhere.
+			if (!completion || (reason === 'list' && (!completion.continues || holdCompletion))) {
+				restorePreview();
+				return;
+			}
+			if (
+				input.value !== completion.text ||
+				input.selectionStart !== completion.selectionStart ||
+				input.selectionEnd !== completion.selectionEnd
+			) {
+				input.value = completion.text;
+				input.setSelectionRange(completion.selectionStart, completion.selectionEnd);
+			}
+			previewing = { typed, text: completion.text };
+		});
+	});
+
+	/** Makes the previewed text the typed text, as when the caret moves into it. */
+	const acceptPreview = () => {
+		const input = inputElement();
+		if (!previewing || !input) return;
+		const accepted = input.value;
+		previewing = null;
+		holdCompletion = true;
+		field.setValue(accepted);
+	};
+
+	// -- Input events ---------------------------------------------------------------------
+
+	const oninput = (event: Event & { currentTarget: HTMLInputElement }) => {
+		inputAttrs?.oninput?.(event);
+		const inputType = event instanceof InputEvent ? event.inputType : '';
+		holdCompletion = inputType.startsWith('delete');
+		// What is in the input is now the typed text, previewed or not.
+		previewing = null;
+		field.setValue(event.currentTarget.value);
+		if (!field.readOnly) controller.onInput(event);
+	};
+
+	const onkeydown = (event: KeyboardEvent & { currentTarget: HTMLInputElement }) => {
+		inputAttrs?.onkeydown?.(event);
+		if (event.defaultPrevented) return;
+		const plain = !event.ctrlKey && !event.metaKey && !event.altKey && !event.shiftKey;
+		if (previewing && !event.isComposing) {
+			if (event.key === 'Escape') {
+				// One Escape puts the typed text back and closes the list.
+				restorePreview();
+			} else if (
+				event.key === 'Tab' ||
+				(plain && ['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key))
+			) {
+				acceptPreview();
+			}
+		}
+		// Home and End move the caret in a text field; they do not jump through the list.
+		if ((event.key === 'Home' || event.key === 'End') && !event.shiftKey) return;
+		if (event.key !== 'Escape') holdCompletion = false;
+		controller.onKeydown(event);
+		const moved = controller.nav.highlightDetails;
+		if (moved.event === event) keyed = moved;
+	};
+
+	const classes = $derived(useAutocompleteTheme(theme));
+</script>
+
+<Popover
+	haspopup="listbox"
+	closeOnClickOutside={false}
+	closeOnEscape={false}
+	focusOnClose={false}
+	fitTrigger
+	position="bottom"
+	size="small"
+	open={controller.visible}
+	onAfterOpen={() => onAfterOpen?.()}
+	onAfterClose={() => onAfterClose?.()}
+>
+	<ComboboxPopup
+		{controller}
+		{classes}
+		{size}
+		{density}
+		{separators}
+		{item}
+		{i18n}
+		isSelected={() => false}
+	/>
+	{#snippet trigger(popover: PopoverApi)}
+		<Field
+			{density}
+			{field}
+			{size}
+			{description}
+			{prefix}
+			{suffix}
+			theme={{
+				...(theme || {}),
+				inputContainer: {
+					...(theme?.inputContainer || {}),
+					base: classes.inputContainer({
+						class: theme?.inputContainer?.base,
+						size,
+						disabled: field.disabled
+					})
+				}
+			}}
+			{...rest}
+			anchor={popover.reference}
+		>
+			<input
+				data-1p-ignore={autocomplete === 'off' ? '' : undefined}
+				{...inputAttrs}
+				type="text"
+				{id}
+				name={submittedName}
+				value={text}
+				{placeholder}
+				{autocomplete}
+				required={field.required}
+				readonly={field.readOnly}
+				disabled={field.disabled}
+				bind:this={field.node}
+				bind:focused={field.focused}
+				role="combobox"
+				aria-expanded={controller.expanded}
+				aria-controls={controller.expanded ? controller.listboxId : undefined}
+				aria-autocomplete={mode}
+				aria-activedescendant={controller.activeDescendant}
+				aria-haspopup="listbox"
+				aria-invalid={controller.error !== null || undefined}
+				class={classes.input({ size, hasValue: text !== '', disabled: field.disabled })}
+				{oninput}
+				{onkeydown}
+				onfocus={(event) => {
+					inputAttrs?.onfocus?.(event);
+					controller.onFocus(event);
+				}}
+				onpointerdown={(event) => {
+					inputAttrs?.onpointerdown?.(event);
+					if (!event.defaultPrevented) controller.onPointerDown();
+				}}
+				onclick={(event) => {
+					inputAttrs?.onclick?.(event);
+					if (!event.defaultPrevented) controller.onClick(event);
+				}}
+				oncompositionstart={(event) => {
+					inputAttrs?.oncompositionstart?.(event);
+					composing = true;
+				}}
+				oncompositionend={(event) => {
+					inputAttrs?.oncompositionend?.(event);
+					composing = false;
+				}}
+			/>
+			<!-- Persistent, so it exists before the first announcement: result counts and status. -->
+			<span class="sr-only" {...controller.announcer.regionAttrs}>
+				{controller.announcer.message}
+			</span>
+		</Field>
+	{/snippet}
+</Popover>

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

@@ -0,0 +1,4 @@
+import type { AutocompleteProps } from './autocomplete.props.js';
+declare const Autocomplete: import("svelte").Component<AutocompleteProps, {}, "value" | "errors" | "focused" | "open">;
+type Autocomplete = ReturnType<typeof Autocomplete>;
+export default Autocomplete;

package/dist/components/Form/Autocomplete/autocomplete.items.d.ts

@@ -0,0 +1,30 @@
+import type { ComboboxItems, ComboboxItemsSource, ComboboxOption } from '../Combobox/combobox.props.js';
+import type { AutocompleteItem, AutocompleteItems, AutocompleteItemsSource } from './autocomplete.props.js';
+/** A plain-text suggestion is an option whose value and label are that text. */
+export declare const toOption: (item: AutocompleteItem) => ComboboxOption;
+/**
+ * Suggestions as options: strings become `{ value, label }`, everything else is passed through.
+ * A value listed more than once (within or across groups) keeps its first entry, since rows and
+ * option ids are keyed by value; a group left empty by that is dropped.
+ */
+export declare const normalizeItems: (items: AutocompleteItems) => ComboboxItems;
+/** The Combobox list's source for these suggestions; functions have their results normalized. */
+export declare const normalizeSource: (source: AutocompleteItemsSource | undefined) => ComboboxItemsSource | undefined;
+/** What previewing a suggestion over the typed text writes into the input. */
+export type InlineCompletion = {
+    /** The text the input shows while the suggestion is previewed. */
+    text: string;
+    /** Where the previewed (not yet typed) part starts; selected, so typing replaces it. */
+    selectionStart: number;
+    /** The end of the text. */
+    selectionEnd: number;
+    /** Whether the suggestion continues what was typed, rather than replacing it. */
+    continues: boolean;
+};
+/**
+ * The input text for previewing `label` over what was `typed`. A label that continues the typed
+ * text completes it, with the added part selected so the next key replaces it. Any other label
+ * replaces the text outright, with the caret at its end. `null` when the suggestion reads the
+ * same as the typed text.
+ */
+export declare const completeInline: (label: string, typed: string, locale: string) => InlineCompletion | null;

package/dist/components/Form/Autocomplete/autocomplete.items.js

@@ -0,0 +1,64 @@
+// Pure helpers behind Autocomplete: suggestions as the Combobox list expects them, and the text
+// an inline completion writes into the input.
+import { createListFilter } from '../../../utils/listFilter.js';
+const isGroup = (entry) => typeof entry === 'object' && 'items' in entry && Array.isArray(entry.items);
+/** A plain-text suggestion is an option whose value and label are that text. */
+export const toOption = (item) => typeof item === 'string' ? { value: item, label: item } : item;
+/**
+ * Suggestions as options: strings become `{ value, label }`, everything else is passed through.
+ * A value listed more than once (within or across groups) keeps its first entry, since rows and
+ * option ids are keyed by value; a group left empty by that is dropped.
+ */
+export const normalizeItems = (items) => {
+    const seen = new Set();
+    const fresh = (option) => {
+        if (seen.has(option.value))
+            return false;
+        seen.add(option.value);
+        return true;
+    };
+    const result = [];
+    for (const entry of items) {
+        if (isGroup(entry)) {
+            const options = entry.items.map(toOption).filter(fresh);
+            if (options.length > 0 || entry.items.length === 0)
+                result.push({ ...entry, items: options });
+        }
+        else {
+            const option = toOption(entry);
+            if (fresh(option))
+                result.push(option);
+        }
+    }
+    return result;
+};
+/** The Combobox list's source for these suggestions; functions have their results normalized. */
+export const normalizeSource = (source) => {
+    if (source === undefined)
+        return undefined;
+    if (typeof source !== 'function')
+        return normalizeItems(source);
+    return async (query, request) => normalizeItems((await source(query ?? '', request)) ?? []);
+};
+/**
+ * The input text for previewing `label` over what was `typed`. A label that continues the typed
+ * text completes it, with the added part selected so the next key replaces it. Any other label
+ * replaces the text outright, with the caret at its end. `null` when the suggestion reads the
+ * same as the typed text.
+ */
+export const completeInline = (label, typed, locale) => {
+    const filter = createListFilter({ locale });
+    // A suggestion that reads the same as the text has nothing to preview.
+    if (filter.equals(label, typed))
+        return null;
+    const continues = typed !== '' && label.length > typed.length && filter.startsWith(label, typed);
+    // The typed letters stay as typed, so deleting the completion leaves exactly what was typed.
+    const keepsTyping = continues && filter.equals(label.slice(0, typed.length), typed);
+    const text = keepsTyping ? typed + label.slice(typed.length) : label;
+    return {
+        text,
+        selectionStart: keepsTyping ? typed.length : text.length,
+        selectionEnd: text.length,
+        continues
+    };
+};

package/dist/components/Form/Autocomplete/autocomplete.mcp.d.ts

@@ -0,0 +1 @@
+export declare const autocompleteDescription = "\n# Autocomplete Component\n\nA text input with suggestions. The value is the text in the input, and the input submits it in a native form, so a suggestion is a shortcut for typing and never a requirement. Use it for search boxes, city or email-domain entry and anywhere people may type something that is not in the list. To make people pick from the list, use Combobox instead (its value is the chosen option, not text).\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Autocomplete } from 'entasis/autocomplete';\n\tlet value = $state('');\n</script>\n\n<Autocomplete\n\tlabel=\"Email domain\"\n\titems={['gmail.com', 'outlook.com', 'proton.me']}\n\tbind:value\n/>\n```\n\n## Props\n\n### Core Props\n\n- **items**: `AutocompleteItemsSource` (required)\n  - Suggestions: strings, `{ value, label, description?, disabled?, data? }` options, `{ label?, items }` groups of either (mixed freely), or a function `(query: string, { signal }) => MaybePromise<AutocompleteItems>`. A value listed more than once keeps its first entry. A function runs only while the list is open (typing opens it), never for a prefilled or just chosen text\n  - A string suggestion is an option whose value and label are that text\n  - For arrays: narrowed client-side with a case- and accent-insensitive match on the label, in the active I18n locale\n  - For functions: called after a 100ms pause in typing with the text and `{ signal }`. The signal is aborted when a newer text replaces the request, and a response that is not the latest is ignored. Results are shown as returned (the function filters)\n- **value**: `string | null` (bindable) / **defaultValue**: the text in the input\n- **onValueChange**: `(value: string | null) => void` runs for each edit the user makes and when a suggestion fills in\n- **onSelect**: `({ item, value, event }) => void` runs after a suggestion is chosen with a click or Enter. `item` is the chosen option (a string suggestion arrives as `{ value, label }`), `value` is its label, the text now in the input\n\n### Mode\n\n- **mode**: `'list' | 'both' | 'inline' | 'none'` (default `'list'`)\n  - `'list'`: suggestions are filtered by the text; the text changes only when one is chosen\n  - `'both'`: filtered, and the input previews the highlighted suggestion (inline completion)\n  - `'inline'`: not filtered, and the input previews the highlighted suggestion\n  - `'none'`: not filtered, and the text never changes until one is chosen\n  - Also sets `aria-autocomplete`\n- **autoHighlight**: `boolean | 'always'` (default `false`). `true` highlights the first match while text is typed, `'always'` also while the text is empty, `false` highlights nothing until an arrow key moves it, so Enter keeps the typed text. Use `true` with `mode=\"both\"` or `\"inline\"` to complete as you type\n- **shouldFilter**: `boolean` (default `true`), **filter**: `(option, query) => boolean`, **limit**: `number`. Narrowing of static suggestions, as in Command\n- **loop**: `'wrap' | 'input' | false` (default `'wrap'`). With `'input'` the end of the list returns to no highlight, and the text to what was typed\n\n### Inline completion\n\nWith `mode=\"both\"` or `\"inline\"` the highlighted suggestion is previewed in the input while the value stays the typed text.\n\n- A suggestion that continues the typed text completes it: the typed letters stay as typed and the added part is selected, so the next key replaces it, and Backspace removes it and leaves the typed text\n- A suggestion that does not continue the text (it only contains it) is previewed only when an arrow key lands on it, replacing the text, with the caret at the end\n- Hovering a suggestion never changes the text\n- Escape puts the typed text back and closes the list. Focus leaving the field puts the typed text back too, so a native submit sends what was typed\n- Enter chooses the previewed suggestion (value becomes its label). ArrowLeft, ArrowRight, Home, End and Tab accept the preview as the typed text\n- Deleting the completion, or the letters before it, does not bring it back until you type again\n- Not applied while `readOnly`, disabled or composing with an IME\n\n### Open state\n\n- **open**: `boolean` (bindable) / **defaultOpen**. The list only renders while there is something to show (suggestions, a loading or error message, or the \"no options\" message for the typed text)\n- **onOpenChange**: `(open, details) => void` runs before the list opens or closes. `details` carries `reason`, `event`, `interaction` and `cancel()`\n- **onAfterOpen** / **onAfterClose**: `() => void` fire once after the transition\n- **openOnFocus**: `boolean` (default `false`). Opens the list on focus before anything is typed: static arrays list every suggestion, functions are called with an empty text\n\n### Field Props\n\n- **required**, **disabled**, **readOnly**, **name**, **size**, **density**, **errors**, **focused**, **description**, **onValidate**, **messages**, **form**, **prefix**, **suffix**, **label**\n- **placeholder**: `string`\n- **autocomplete**: browser autofill hint (default `'off'`: the component offers its own suggestions)\n- **loadingText** / **emptyText**: replace the \"Loading...\" and \"No options found\" messages\n- **item**: `Snippet<[ComboboxOption]>` custom row renderer; **separators**: `boolean` between groups\n- **inputAttrs**: native attributes for the input (`inputmode`, `maxlength`, event handlers that run first, where `preventDefault()` cancels the built-in behaviour); the component keeps id, name, value and ARIA state\n- **onHighlightChange**: `({ value, reason, event }) => void`\n\n## Examples\n\n### Async suggestions\n\n```svelte\n<script lang=\"ts\">\n\tconst cities = async (query: string, { signal }: { signal: AbortSignal }) => {\n\t\tconst response = await fetch(`/api/cities?q=${encodeURIComponent(query)}`, { signal });\n\t\treturn response.json(); // string[] or { value, label }[]\n\t};\n</script>\n\n<Autocomplete label=\"City\" items={cities} bind:value />\n```\n\n### Inline completion\n\n```svelte\n<Autocomplete label=\"Fruit\" mode=\"both\" autoHighlight items={['Apple', 'Apricot', 'Banana']} bind:value />\n```\n\n### Native form\n\n```svelte\n<form onsubmit={(event) => { event.preventDefault(); console.log(new FormData(event.currentTarget).get('city')); }}>\n\t<Autocomplete name=\"city\" label=\"City\" items={cities} />\n\t<Button type=\"submit\">Search</Button>\n</form>\n```\n\n## Accessibility\n\n- **role=\"combobox\"** on the input with **aria-autocomplete** set to the mode, **aria-expanded**, **aria-controls** and **aria-activedescendant**; the list is a **role=\"listbox\"** of options and groups only\n- ArrowDown/ArrowUp open a closed list (with every suggestion) and move the highlight; Enter chooses the highlighted suggestion and otherwise does nothing, so the form's Enter handling and submit still work; Escape closes the list and keeps focus (a second Escape clears the text); Home and End stay on the caret\n- Clicking the already-focused input toggles the list. A press inside the list never moves focus off the input\n- One persistent visually hidden live region next to the input announces result counts, the empty state, loading and errors after typing settles\n- Read-only: the list opens and can be browsed, the text cannot change and still submits\n\n## Notes\n\n- **Native forms**: the input itself carries `name` and submits the text (nothing when there is no name or the field is disabled); `required` blocks a native submit while empty. Free text is kept when focus leaves\n- **Reset**: a native form reset returns the text the field mounted with\n- **Race conditions**: older requests are aborted and only the latest response updates the list\n- **Styling hooks**: while the list is open, the field it is anchored to carries `data-popup-side` and the panel `data-side`; option rows are `MenuOption` rows themed with `setMenuOptionTheme`\n\n## Theme Customization\n\nTheme parts: **input**, **inputContainer**, **loading**, **error**, **noOptions**, **group**, **groupLabel**, **separator**. They start from Combobox's look and have their own registry key, `autocomplete`.\n\n```svelte\n<script>\n\timport { setAutocompleteTheme } from 'entasis/autocomplete';\n\n\tsetAutocompleteTheme({\n\t\tinputContainer: { base: 'rounded-lg border-2' },\n\t\tnoOptions: { base: 'italic' }\n\t});\n</script>\n```\n";

package/dist/components/Form/Autocomplete/autocomplete.mcp.js

@@ -0,0 +1,134 @@
+export const autocompleteDescription = `
+# Autocomplete Component
+
+A text input with suggestions. The value is the text in the input, and the input submits it in a native form, so a suggestion is a shortcut for typing and never a requirement. Use it for search boxes, city or email-domain entry and anywhere people may type something that is not in the list. To make people pick from the list, use Combobox instead (its value is the chosen option, not text).
+
+## Basic Usage
+
+\`\`\`svelte
+<script>
+	import { Autocomplete } from './index.ts';
+	let value = $state('');
+</script>
+
+<Autocomplete
+	label="Email domain"
+	items={['gmail.com', 'outlook.com', 'proton.me']}
+	bind:value
+/>
+\`\`\`
+
+## Props
+
+### Core Props
+
+- **items**: \`AutocompleteItemsSource\` (required)
+  - Suggestions: strings, \`{ value, label, description?, disabled?, data? }\` options, \`{ label?, items }\` groups of either (mixed freely), or a function \`(query: string, { signal }) => MaybePromise<AutocompleteItems>\`. A value listed more than once keeps its first entry. A function runs only while the list is open (typing opens it), never for a prefilled or just chosen text
+  - A string suggestion is an option whose value and label are that text
+  - For arrays: narrowed client-side with a case- and accent-insensitive match on the label, in the active I18n locale
+  - For functions: called after a 100ms pause in typing with the text and \`{ signal }\`. The signal is aborted when a newer text replaces the request, and a response that is not the latest is ignored. Results are shown as returned (the function filters)
+- **value**: \`string | null\` (bindable) / **defaultValue**: the text in the input
+- **onValueChange**: \`(value: string | null) => void\` runs for each edit the user makes and when a suggestion fills in
+- **onSelect**: \`({ item, value, event }) => void\` runs after a suggestion is chosen with a click or Enter. \`item\` is the chosen option (a string suggestion arrives as \`{ value, label }\`), \`value\` is its label, the text now in the input
+
+### Mode
+
+- **mode**: \`'list' | 'both' | 'inline' | 'none'\` (default \`'list'\`)
+  - \`'list'\`: suggestions are filtered by the text; the text changes only when one is chosen
+  - \`'both'\`: filtered, and the input previews the highlighted suggestion (inline completion)
+  - \`'inline'\`: not filtered, and the input previews the highlighted suggestion
+  - \`'none'\`: not filtered, and the text never changes until one is chosen
+  - Also sets \`aria-autocomplete\`
+- **autoHighlight**: \`boolean | 'always'\` (default \`false\`). \`true\` highlights the first match while text is typed, \`'always'\` also while the text is empty, \`false\` highlights nothing until an arrow key moves it, so Enter keeps the typed text. Use \`true\` with \`mode="both"\` or \`"inline"\` to complete as you type
+- **shouldFilter**: \`boolean\` (default \`true\`), **filter**: \`(option, query) => boolean\`, **limit**: \`number\`. Narrowing of static suggestions, as in Command
+- **loop**: \`'wrap' | 'input' | false\` (default \`'wrap'\`). With \`'input'\` the end of the list returns to no highlight, and the text to what was typed
+
+### Inline completion
+
+With \`mode="both"\` or \`"inline"\` the highlighted suggestion is previewed in the input while the value stays the typed text.
+
+- A suggestion that continues the typed text completes it: the typed letters stay as typed and the added part is selected, so the next key replaces it, and Backspace removes it and leaves the typed text
+- A suggestion that does not continue the text (it only contains it) is previewed only when an arrow key lands on it, replacing the text, with the caret at the end
+- Hovering a suggestion never changes the text
+- Escape puts the typed text back and closes the list. Focus leaving the field puts the typed text back too, so a native submit sends what was typed
+- Enter chooses the previewed suggestion (value becomes its label). ArrowLeft, ArrowRight, Home, End and Tab accept the preview as the typed text
+- Deleting the completion, or the letters before it, does not bring it back until you type again
+- Not applied while \`readOnly\`, disabled or composing with an IME
+
+### Open state
+
+- **open**: \`boolean\` (bindable) / **defaultOpen**. The list only renders while there is something to show (suggestions, a loading or error message, or the "no options" message for the typed text)
+- **onOpenChange**: \`(open, details) => void\` runs before the list opens or closes. \`details\` carries \`reason\`, \`event\`, \`interaction\` and \`cancel()\`
+- **onAfterOpen** / **onAfterClose**: \`() => void\` fire once after the transition
+- **openOnFocus**: \`boolean\` (default \`false\`). Opens the list on focus before anything is typed: static arrays list every suggestion, functions are called with an empty text
+
+### Field Props
+
+- **required**, **disabled**, **readOnly**, **name**, **size**, **density**, **errors**, **focused**, **description**, **onValidate**, **messages**, **form**, **prefix**, **suffix**, **label**
+- **placeholder**: \`string\`
+- **autocomplete**: browser autofill hint (default \`'off'\`: the component offers its own suggestions)
+- **loadingText** / **emptyText**: replace the "Loading..." and "No options found" messages
+- **item**: \`Snippet<[ComboboxOption]>\` custom row renderer; **separators**: \`boolean\` between groups
+- **inputAttrs**: native attributes for the input (\`inputmode\`, \`maxlength\`, event handlers that run first, where \`preventDefault()\` cancels the built-in behaviour); the component keeps id, name, value and ARIA state
+- **onHighlightChange**: \`({ value, reason, event }) => void\`
+
+## Examples
+
+### Async suggestions
+
+\`\`\`svelte
+<script lang="ts">
+	const cities = async (query: string, { signal }: { signal: AbortSignal }) => {
+		const response = await fetch(\`/api/cities?q=\${encodeURIComponent(query)}\`, { signal });
+		return response.json(); // string[] or { value, label }[]
+	};
+</script>
+
+<Autocomplete label="City" items={cities} bind:value />
+\`\`\`
+
+### Inline completion
+
+\`\`\`svelte
+<Autocomplete label="Fruit" mode="both" autoHighlight items={['Apple', 'Apricot', 'Banana']} bind:value />
+\`\`\`
+
+### Native form
+
+\`\`\`svelte
+<form onsubmit={(event) => { event.preventDefault(); console.log(new FormData(event.currentTarget).get('city')); }}>
+	<Autocomplete name="city" label="City" items={cities} />
+	<Button type="submit">Search</Button>
+</form>
+\`\`\`
+
+## Accessibility
+
+- **role="combobox"** on the input with **aria-autocomplete** set to the mode, **aria-expanded**, **aria-controls** and **aria-activedescendant**; the list is a **role="listbox"** of options and groups only
+- ArrowDown/ArrowUp open a closed list (with every suggestion) and move the highlight; Enter chooses the highlighted suggestion and otherwise does nothing, so the form's Enter handling and submit still work; Escape closes the list and keeps focus (a second Escape clears the text); Home and End stay on the caret
+- Clicking the already-focused input toggles the list. A press inside the list never moves focus off the input
+- One persistent visually hidden live region next to the input announces result counts, the empty state, loading and errors after typing settles
+- Read-only: the list opens and can be browsed, the text cannot change and still submits
+
+## Notes
+
+- **Native forms**: the input itself carries \`name\` and submits the text (nothing when there is no name or the field is disabled); \`required\` blocks a native submit while empty. Free text is kept when focus leaves
+- **Reset**: a native form reset returns the text the field mounted with
+- **Race conditions**: older requests are aborted and only the latest response updates the list
+- **Styling hooks**: while the list is open, the field it is anchored to carries \`data-popup-side\` and the panel \`data-side\`; option rows are \`MenuOption\` rows themed with \`setMenuOptionTheme\`
+
+## Theme Customization
+
+Theme parts: **input**, **inputContainer**, **loading**, **error**, **noOptions**, **group**, **groupLabel**, **separator**. They start from Combobox's look and have their own registry key, \`autocomplete\`.
+
+\`\`\`svelte
+<script>
+	import { setAutocompleteTheme } from './index.ts';
+
+	setAutocompleteTheme({
+		inputContainer: { base: 'rounded-lg border-2' },
+		noOptions: { base: 'italic' }
+	});
+</script>
+\`\`\`
+`;