entasis 0.11.0 → 0.12.0

package/dist/components/Form/Combobox/combobox.items.d.ts

@@ -0,0 +1,28 @@
+import type { ComboboxFilter, ComboboxItems, ComboboxOption, ComboboxOptionGroup } from './combobox.props.js';
+export declare const isOptionGroup: (entry: ComboboxOption | ComboboxOptionGroup) => entry is ComboboxOptionGroup;
+/** Every option, flattened across groups, in render order. */
+export declare const flattenItems: (items: ComboboxItems) => ComboboxOption[];
+/** Options a keyboard or pointer can act on: everything except disabled options. */
+export declare const selectableOptions: (items: ComboboxItems) => ComboboxOption[];
+export type RenderGroup = {
+    label?: string;
+    items: ComboboxOption[];
+};
+/** Items as rendered: consecutive bare options bundled into one unlabeled group. */
+export declare const toRenderGroups: (items: ComboboxItems) => RenderGroup[];
+/** The default match: a case- and accent-insensitive substring of the label, in `locale`. */
+export declare const createOptionMatcher: (locale: string) => ComboboxFilter;
+type NarrowOptions = {
+    /** Keeps an option when it returns `true`; an empty query matches everything. */
+    match?: ComboboxFilter;
+    /** Leaves out options that are already taken (TagsInput's selected tags). */
+    exclude?: (option: ComboboxOption) => boolean;
+    /** Stop once this many options are kept. The rest of the list is never compared. */
+    limit?: number;
+};
+/**
+ * Narrows `items` to the options that match `query`, keeping their groups (a group with no
+ * match disappears) and stopping once `limit` options are kept, across groups.
+ */
+export declare const narrowItems: (items: ComboboxItems, query: string, { match, exclude, limit }?: NarrowOptions) => ComboboxItems;
+export {};

package/dist/components/Form/Combobox/combobox.items.js

@@ -0,0 +1,68 @@
+// Pure helpers over the options a Combobox or TagsInput lists: groups, matching and limits.
+import { createListFilter } from '../../../utils/listFilter.js';
+export const isOptionGroup = (entry) => 'items' in entry && Array.isArray(entry.items);
+/** Every option, flattened across groups, in render order. */
+export const flattenItems = (items) => items.flatMap((entry) => (isOptionGroup(entry) ? entry.items : [entry]));
+/** Options a keyboard or pointer can act on: everything except disabled options. */
+export const selectableOptions = (items) => flattenItems(items).filter((option) => !option.disabled);
+/** Items as rendered: consecutive bare options bundled into one unlabeled group. */
+export const toRenderGroups = (items) => {
+    const groups = [];
+    let bare = null;
+    for (const entry of items) {
+        if (isOptionGroup(entry)) {
+            bare = null;
+            groups.push({ label: entry.label, items: entry.items });
+        }
+        else {
+            if (!bare) {
+                bare = { items: [] };
+                groups.push(bare);
+            }
+            bare.items.push(entry);
+        }
+    }
+    return groups;
+};
+/** The default match: a case- and accent-insensitive substring of the label, in `locale`. */
+export const createOptionMatcher = (locale) => {
+    const filter = createListFilter({ locale });
+    return (option, query) => filter.contains(option.label, query);
+};
+/**
+ * Narrows `items` to the options that match `query`, keeping their groups (a group with no
+ * match disappears) and stopping once `limit` options are kept, across groups.
+ */
+export const narrowItems = (items, query, { match, exclude, limit } = {}) => {
+    let remaining = limit !== undefined && limit >= 0 ? limit : Infinity;
+    const keep = (option) => {
+        if (remaining <= 0)
+            return false;
+        if (exclude?.(option))
+            return false;
+        if (query !== '' && match && !match(option, query))
+            return false;
+        remaining -= 1;
+        return true;
+    };
+    const result = [];
+    for (const entry of items) {
+        if (remaining <= 0)
+            break;
+        if (isOptionGroup(entry)) {
+            const kept = [];
+            for (const option of entry.items) {
+                if (remaining <= 0)
+                    break;
+                if (keep(option))
+                    kept.push(option);
+            }
+            if (kept.length > 0)
+                result.push({ ...entry, items: kept });
+        }
+        else if (keep(entry)) {
+            result.push(entry);
+        }
+    }
+    return result;
+};

package/dist/components/Form/Combobox/combobox.mcp.d.ts

@@ -1 +1 @@
-export declare const comboboxDescription = "\n# Combobox Component\n\nA searchable dropdown component that supports both static arrays and async option loading. Provides keyboard navigation, debounced search, and full ARIA accessibility. Use it when users need to search and select from a large list of options.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Combobox } from 'entasis/combobox';\n\tlet value = $state(null);\n\tconst items = [\n\t\t{ value: 'us', label: 'United States', description: 'North America' },\n\t\t{ value: 'uk', label: 'United Kingdom', description: 'Europe' }\n\t];\n</script>\n\n<Combobox\n\tplaceholder=\"Search countries...\"\n\titems={items}\n\tbind:value={value}\n/>\n```\n\n## Props\n\n### Core Props\n\n- **items**: `ComboboxOption[] | ((searchValue?: string) => MaybePromise<ComboboxOption[]>)` (required)\n  - Array of options or async function that returns options based on search value\n  - For arrays: filtered client-side\n  - For functions: called with search value, returns Promise or array\n\n- **value**: `string | null` (bindable)\n  - Selected option value\n- **defaultValue**: `string | null` (default: `null`)\n  - Initial selected value when `value` is omitted\n\n- **searchValue**: `string` (default: `''`, bindable)\n  - Current search input value\n\n- **loading**: `boolean` (default: `false`, bindable)\n  - Loading state (managed automatically for async options)\n\n### Behavior Props\n\n- **showAllOnFocus**: `boolean` (default: `false`)\n  - Show all options when input is focused, even without typing\n\n- **getValueOption**: `(value: string) => MaybePromise<ComboboxOption | null | undefined>`\n  - Function to get option data for a value when not in loaded options\n  - Useful for async options with pre-selected values\n\n- **placeholder**: `string` (default: `''`)\n  - Input placeholder text\n\n- **loadingText**: `string` (default: `'Loading...'`)\n  - Text displayed while loading options\n\n- **noOptionsText**: `string` (default: `'No options found'`)\n  - Text displayed when no options match\n\n### Field Props\n\n- **required**: `boolean` (default: `false`)\n- **disabled**: `boolean`\n- **size**: `'small' | 'normal' | 'large'` (default: `'normal'`)\n- **density**: `'compact' | 'normal' | 'comfortable'` (default: `'normal'`) - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)\n- **name**: `string`\n- **errors**: `string[] | boolean` (bindable)\n- **focused**: `boolean` (bindable)\n- **description**: `string`\n\n### Event Props\n\n- **onValueChange**: `({ value, option }: { value: string | null; option: ComboboxOption | null }) => void`\n  - Called when selection changes\n  - Receives a named payload with both the value and full option object\n\n- **onValidate**: `(value: string) => string[] | boolean`\n  - Custom validation function\n\n### Slot Props\n\n- **prefix**: `Snippet | false` (default: magnifying glass icon)\n  - Prefix content. Set to `false` to hide default icon\n\n- **suffix**: `Snippet`\n  - Suffix content (clear button shown automatically when value exists)\n\n### Theme Props\n\n- **theme**: `ComboboxThemeProps`\n  - Customize styling for: input, inputContainer, loading, error, noOptions\n  - Option rows are `MenuOption` components: style them globally with `setMenuOptionTheme` from `entasis/menu-option`\n\n## Examples\n\n### Array Options (Client-side Filtering)\n\n```svelte\n<script>\n\tlet value = $state(null);\n\tconst countries = [\n\t\t{ value: 'us', label: 'United States' },\n\t\t{ value: 'uk', label: 'United Kingdom' }\n\t];\n</script>\n\n<Combobox\n\titems={countries}\n\tbind:value={value}\n\tplaceholder=\"Search countries...\"\n/>\n```\n\n### Async Options (API Call)\n\n```svelte\n<script lang=\"ts\">\n\tlet value = $state(null);\n\tconst getOptions = async (searchValue?: string) => {\n\t\tconst response = await fetch(`/api/search?q=${searchValue}`);\n\t\treturn response.json();\n\t};\n</script>\n\n<Combobox\n\titems={getOptions}\n\tbind:value={value}\n\tplaceholder=\"Search async...\"\n/>\n```\n\n### Show All Options on Focus\n\n```svelte\n<Combobox\n\titems={countries}\n\tshowAllOnFocus={true}\n\tbind:value={value}\n/>\n```\n\n### Pre-selected Value with Async Options\n\n```svelte\n<script lang=\"ts\">\n\timport type { ComboboxOption } from 'entasis/combobox';\n\tlet value = $state<string | null>('us');\n\tconst getValueOption = async (value: string): Promise<ComboboxOption> => {\n\t\treturn { value, label: 'United States' };\n\t};\n\tconst getOptions = async (searchValue?: string): Promise<ComboboxOption[]> => {\n\t\tconst response = await fetch(`/api/countries?q=${searchValue ?? ''}`);\n\t\treturn response.json();\n\t};\n</script>\n\n<Combobox\n\titems={getOptions}\n\tbind:value={value}\n\tgetValueOption={getValueOption}\n/>\n```\n\n## State Management\n\n- **value**: Bindable string (option value) or null\n- **searchValue**: Bindable string for search input\n- **loading**: Bindable boolean, automatically managed for async options\n- **errors**: Bindable array or boolean for validation errors\n- **focused**: Bindable boolean for focus state\n\n## Accessibility\n\n- Full ARIA combobox pattern implementation\n- **role=\"combobox\"** on input\n- **role=\"listbox\"** on options container\n- **role=\"option\"** on each option\n- **aria-expanded**, **aria-controls**, **aria-activedescendant** for state\n- **aria-autocomplete=\"list\"** for search behavior\n- Keyboard navigation: ArrowDown/Up (wraps around), Enter (select), Escape (close), Home/End (first/last)\n- Screen reader announcements for loading and error states\n\n## Notes\n\n- **Debouncing**: Search is debounced by 100ms to reduce API calls\n- **Race Conditions**: Handled automatically - only latest async request updates state\n- **Option Format**: Options must have `value` (string) and `label` (string). Optional `description` displays below label\n- **Keyboard Navigation**: Wraps around - ArrowDown at bottom goes to top, ArrowUp at top goes to bottom\n- **Empty States**: Shows loading text, error message, or no options text appropriately\n- **Clear Button**: Automatically shown when value exists, uses the shared field action button hitbox\n- **Default Prefix**: Magnifying glass icon shown by default unless `prefix={false}` or custom snippet provided\n\n## Theme Customization\n\nThe Combobox component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **input**: Input element styles\n- **inputContainer**: Input container wrapper styles\n- **loading**: Loading state indicator styles\n- **error**: Error message styles\n- **noOptions**: No options found message styles\n\nOption rows are rendered with the shared `MenuOption` component (parts: root, title, description, prefix, suffix, content) and are themed through `setMenuOptionTheme` from `entasis/menu-option`, not through the Combobox theme.\n\n### Available Variants\n\n**input**:\n- base: Base classes applied to the input element\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - disabled: boolean - Disabled state styling\n\n**inputContainer**:\n- base: Base classes for the input container\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Size-based styling\n  - disabled: boolean - Disabled state styling\n\n**loading**:\n- base: Base classes for loading indicator\n\n**error**:\n- base: Base classes for error message\n\n**noOptions**:\n- base: Base classes for no options message\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Combobox\n  items={items}\n  bind:value={value}\n  theme={{\n    inputContainer: {\n      base: 'border-2 rounded-lg',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    },\n    noOptions: {\n      base: 'italic'\n    }\n  }}\n/>\n```\n\n**Custom Option Styling** (option rows use the shared MenuOption theme):\n```svelte\n<script lang=\"ts\">\n  import { setMenuOptionTheme } from '../../MenuOption/index.ts';\n\n  let value = $state<string | null>(null);\n  const items = [\n    { value: 'us', label: 'United States', description: 'North America' },\n    { value: 'uk', label: 'United Kingdom', description: 'Europe' }\n  ];\n\n  setMenuOptionTheme({\n    root: {\n      base: 'rounded-md transition-colors'\n    },\n    title: {\n      base: 'font-semibold'\n    },\n    description: {\n      base: 'text-sm text-neutral/70'\n    }\n  });\n</script>\n\n<Combobox items={items} bind:value={value} />\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setComboboxTheme } from './index.ts';\n  \n  setComboboxTheme({\n    inputContainer: {\n      base: 'rounded-lg border-2 transition-all',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    },\n    loading: {\n      base: 'italic'\n    }\n  });\n</script>\n```\n";
+export declare const comboboxDescription = "\n# Combobox Component\n\nA searchable dropdown component that supports both static arrays and async option loading. Provides keyboard navigation, debounced search, and full ARIA accessibility. Use it when users need to search and select from a large list of options.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Combobox } from 'entasis/combobox';\n\tlet value = $state(null);\n\tconst items = [\n\t\t{ value: 'us', label: 'United States', description: 'North America' },\n\t\t{ value: 'uk', label: 'United Kingdom', description: 'Europe' }\n\t];\n</script>\n\n<Combobox\n\tplaceholder=\"Search countries...\"\n\titems={items}\n\tbind:value={value}\n/>\n```\n\n## Props\n\n### Core Props\n\n- **items**: `ComboboxItems | ((searchValue: string | undefined, request: { signal: AbortSignal }) => MaybePromise<ComboboxItems>)` (required)\n  - Array of options (and groups) or a function that returns them for the search text\n  - `ComboboxItems` is `(ComboboxOption | { label?: string; items: ComboboxOption[] })[]`; flat options and groups can be mixed. `ComboboxOption` is `{ value; label; description?; disabled?; data? }`\n  - For arrays: filtered client-side with a case- and accent-insensitive match on the label, in the active I18n locale (\"eclair\" finds \"\u00C9clair\")\n  - For functions: called (after a 100ms pause in typing) with the search text and `{ signal }`. The signal is aborted when a newer search replaces the request, and a response that is not the latest is ignored, so a slow answer never overwrites a newer list. The last results stay visible, marked busy, while the next request loads\n\n- **value**: `string | null` (bindable)\n  - Selected option value\n- **defaultValue**: `string | null` (default: `null`)\n  - Initial selected value when `value` is omitted\n\n- **searchValue**: `string` (default: `''`, bindable)\n  - Current search input value (a draft: it is never submitted by a native form)\n\n- **open**: `boolean` (bindable) / **defaultOpen**: `boolean` (default: `false`)\n  - Whether the options list is open. The list only renders while there is something to show (options, 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` (`'input-change'`, `'escape-key'`, `'item-press'`, `'list-navigation'`, `'trigger-press'`, `'trigger-focus'`, `'focus-out'`), `event`, `interaction` and `cancel()`; a cancelled change leaves the list as it was\n  - **onAfterOpen** / **onAfterClose**: `() => void` fire once after the open or close transition\n\n- **loading**: `boolean` (default: `false`, bindable)\n  - Loading state (managed automatically for async options)\n\n### Behavior Props\n\n- **openOnFocus**: `boolean` (default: `false`)\n  - Open the list when the input receives focus, even before typing: static arrays list every option, `items` functions are called with an empty search\n- **showAllOnFocus**: `boolean` (deprecated alias of `openOnFocus`, kept for one minor)\n\n- **filter**: `(option, searchValue) => boolean` - Custom match for static arrays (functions filter themselves)\n- **limit**: `number` - Show at most this many matches; matching stops once the limit is reached, across groups\n\n- **autoHighlight**: `boolean | 'always'` (default: `'always'`)\n  - `'always'` keeps the first match (or the selected option while the text is empty) highlighted; `true` only while text is typed; `false` highlights nothing until an arrow key or the pointer moves it\n- **loop**: `'wrap' | 'input' | false` (default: `'wrap'`) - Past either end of the list: continue at the other end, land on no highlight first (focus stays in the input), or stop\n- **separators**: `boolean` (default: `true`) - Separators between consecutive groups\n- **item**: `Snippet<[ComboboxOption]>` - Custom row renderer, replaces the title and description layout\n- **readOnly**: `boolean` - The list opens and can be browsed, but the value cannot change: choosing does nothing, the clear button is hidden, the input is natively `readonly`. The value still submits\n\n- **getValueOption**: `(value: string) => MaybePromise<ComboboxOption | null | undefined>`\n  - Function to get option data for a value when not in loaded options\n  - Useful for async options with pre-selected values\n\n- **placeholder**: `string` (default: `''`)\n  - Input placeholder text\n\n- **loadingText**: `string` (default: `'Loading...'`)\n  - Text displayed while loading options\n\n- **noOptionsText**: `string` (default: `'No options found'`)\n  - Text displayed when no options match\n\n### Field Props\n\n- **required**: `boolean` (default: `false`)\n- **disabled**: `boolean`\n- **size**: `'small' | 'normal' | 'large'` (default: `'normal'`)\n- **density**: `'compact' | 'normal' | 'comfortable'` (default: `'normal'`) - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)\n- **name**: `string`\n- **errors**: `string[] | boolean` (bindable)\n- **focused**: `boolean` (bindable)\n- **description**: `string`\n\n### Event Props\n\n- **onValueChange**: `({ value, option }: { value: string | null; option: ComboboxOption | null }) => void`\n  - Called when selection changes\n  - Receives a named payload with both the value and full option object\n\n- **onHighlightChange**: `({ value, reason, event }) => void`\n  - Called when the highlighted option changes. `value` is the option's value or `undefined`; `reason` is `'keyboard'`, `'pointer'` or `'list'` (results changed, or the list opened); `event` is the KeyboardEvent or pointer event, absent for `'list'`\n\n- **onValidate**: `(value: string) => string[] | boolean`\n  - Custom validation function\n\n### Slot Props\n\n- **prefix**: `Snippet | false` (default: magnifying glass icon)\n  - Prefix content. Set to `false` to hide default icon\n\n- **suffix**: `Snippet`\n  - Suffix content (clear button shown automatically when value exists)\n\n### Theme Props\n\n- **theme**: `ComboboxThemeProps`\n  - Customize styling for: input, inputContainer, loading, error, noOptions\n  - Option rows are `MenuOption` components: style them globally with `setMenuOptionTheme` from `entasis/menu-option`\n\n## Examples\n\n### Array Options (Client-side Filtering)\n\n```svelte\n<script>\n\tlet value = $state(null);\n\tconst countries = [\n\t\t{ value: 'us', label: 'United States' },\n\t\t{ value: 'uk', label: 'United Kingdom' }\n\t];\n</script>\n\n<Combobox\n\titems={countries}\n\tbind:value={value}\n\tplaceholder=\"Search countries...\"\n/>\n```\n\n### Async Options (API Call)\n\n```svelte\n<script lang=\"ts\">\n\tlet value = $state(null);\n\tconst getOptions = async (searchValue?: string) => {\n\t\tconst response = await fetch(`/api/search?q=${searchValue}`);\n\t\treturn response.json();\n\t};\n</script>\n\n<Combobox\n\titems={getOptions}\n\tbind:value={value}\n\tplaceholder=\"Search async...\"\n/>\n```\n\n### Open on Focus\n\n```svelte\n<Combobox\n\titems={countries}\n\topenOnFocus\n\tbind:value={value}\n/>\n```\n\n### Pre-selected Value with Async Options\n\n```svelte\n<script lang=\"ts\">\n\timport type { ComboboxOption } from 'entasis/combobox';\n\tlet value = $state<string | null>('us');\n\tconst getValueOption = async (value: string): Promise<ComboboxOption> => {\n\t\treturn { value, label: 'United States' };\n\t};\n\tconst getOptions = async (searchValue?: string): Promise<ComboboxOption[]> => {\n\t\tconst response = await fetch(`/api/countries?q=${searchValue ?? ''}`);\n\t\treturn response.json();\n\t};\n</script>\n\n<Combobox\n\titems={getOptions}\n\tbind:value={value}\n\tgetValueOption={getValueOption}\n/>\n```\n\n### Groups, Disabled Options and Custom Rows\n\n```svelte\n<Combobox\n\topenOnFocus\n\titems={[\n\t\t{ label: 'Europe', items: [{ value: 'fr', label: 'France' }, { value: 'de', label: 'Germany' }] },\n\t\t{ label: 'Asia', items: [{ value: 'cn', label: 'China', disabled: true }] }\n\t]}\n\tbind:value={value}\n>\n\t{#snippet item(option)}\n\t\t<span>{option.label}</span>\n\t{/snippet}\n</Combobox>\n```\n\n### Abortable Async Options\n\n```svelte\n<script lang=\"ts\">\n\tconst getOptions = async (searchValue: string | undefined, { signal }: { signal: AbortSignal }) => {\n\t\tconst response = await fetch(`/api/countries?q=${searchValue ?? ''}`, { signal });\n\t\treturn response.json();\n\t};\n</script>\n\n<Combobox items={getOptions} bind:value={value} />\n```\n\n## State Management\n\n- **value**: Bindable string (option value) or null\n- **searchValue**: Bindable string for search input\n- **loading**: Bindable boolean, automatically managed for async options\n- **open**: Bindable boolean for the list\n- **errors**: Bindable array or boolean for validation errors\n- **focused**: Bindable boolean for focus state\n\n## Styling hooks\n\nThe input, the field container, the list panel and every option carry state attributes. `data-highlighted` and `data-selected` are written as `\"true\"`; match them by presence.\n\nAttributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.\n\n**Data attributes**\n- `data-popup-open`: On the input and the field container around it: present while the list (or its empty, loading or error status) shows.\n- `data-popup-side`: On the field container: the side of the field the list sits on.\n- `data-disabled`: On the input: present while disabled. On an option: present while it is disabled.\n- `data-highlighted`: On an option: present while the keyboard or the pointer highlights it.\n- `data-selected`: On an option: present while it is the value.\n- `data-open`: On the list panel: present while open.\n- `data-closed`: On the list panel: present while its exit transition plays.\n- `data-entering`: On the list panel: present while the enter transition plays.\n- `data-exiting`: On the list panel: present while the exit transition plays.\n- `data-side`: On the list panel: the side of the field it sits on after flipping.\n- `data-align`: On the list panel: `start`, `center` or `end`.\n\n**CSS variables** (set on the list panel's positioned wrapper and inherited by the list)\n- `--available-width`: The width in px the panel can take before it reaches the viewport edges, minus 20px.\n- `--available-height`: The room in px between the trigger and the viewport edge on the panel's side, minus 20px. Cap a scrolling list with `max-height: min(240px, var(--available-height))`.\n- `--anchor-width`: The trigger's width in px, snapped to the device pixel grid.\n- `--anchor-height`: The trigger's height in px, snapped to the device pixel grid.\n- `--transform-origin`: The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.\n\nThe typed maps `comboboxDataAttributes` and `comboboxCssVariables` (from `entasis/combobox`) list each name with its meaning.\n\n## Accessibility\n\n- Full ARIA combobox pattern implementation\n- **role=\"combobox\"** on input\n- **role=\"listbox\"** on options container\n- **role=\"option\"** on each option\n- **aria-expanded**, **aria-controls**, **aria-activedescendant** for state\n- **aria-autocomplete=\"list\"** for search behavior\n- Keyboard navigation: ArrowDown/ArrowUp open a closed list (with every option) and then move the highlight, Enter selects, Escape closes the list and keeps focus in the input (a second Escape clears the typed text), Home/End jump to the first/last option\n- Clicking the already-focused input toggles the list; choosing an option, Clear and Escape all keep focus in the input\n- The listbox owns only options and groups; the loading, error and \"no options\" messages sit beside it, and `aria-expanded` is true while options are listed\n- One persistent visually hidden live region (`role=\"status\"`) next to the input announces result counts (\"3 results available\"), the empty state, loading and errors after typing settles\n- The highlight follows the selected option when the list opens and when the text is cleared\n\n## Notes\n\n- **Debouncing**: Search is debounced by 100ms to reduce API calls\n- **Race Conditions**: Handled automatically - older requests are aborted and only the latest response updates state\n- **Native forms**: The search box carries no `name`. A hidden input beside it submits the selected value under `name` (nothing when there is no name or the field is disabled); `required` blocks a native submit while nothing is selected\n- **Closing**: Escape, choosing an option, or focus leaving the field closes the list; the rows stay on screen through the exit transition\n- **Option Format**: Options must have `value` (string) and `label` (string). Optional `description` displays below label\n- **Keyboard Navigation**: Wraps around by default - ArrowDown at bottom goes to top, ArrowUp at top goes to bottom (see `loop`)\n- **Groups and disabled options**: Disabled options are dimmed and skipped by the keyboard; groups render like Select's (`role=\"group\"` with a hidden label, presentational separators)\n- **Empty States**: Shows loading text, error message, or no options text appropriately\n- **Clear Button**: Automatically shown when value exists, uses the shared field action button hitbox\n- **Default Prefix**: Magnifying glass icon shown by default unless `prefix={false}` or custom snippet provided\n- **List height**: The option list scrolls beyond 200px, or beyond the room left between the field and the viewport edge (the Popover's `--available-height`), so it shrinks above an on-screen keyboard instead of running under it\n- **Styling hooks**: While the list is open, the field it is anchored to carries `data-popup-side` (`bottom` or `top`) and the panel `data-side`\n\n## Theme Customization\n\nThe Combobox component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **input**: Input element styles\n- **inputContainer**: Input container wrapper styles\n- **loading**: Loading state indicator styles\n- **error**: Error message styles\n- **noOptions**: No options found message styles\n- **group**, **groupLabel**, **separator**: Group container, group label and the divider between groups\n\nOption rows are rendered with the shared `MenuOption` component (parts: root, title, description, prefix, suffix, content) and are themed through `setMenuOptionTheme` from `entasis/menu-option`, not through the Combobox theme.\n\n### Available Variants\n\n**input**:\n- base: Base classes applied to the input element\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - disabled: boolean - Disabled state styling\n\n**inputContainer**:\n- base: Base classes for the input container\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Size-based styling\n  - disabled: boolean - Disabled state styling\n\n**loading**:\n- base: Base classes for loading indicator\n\n**error**:\n- base: Base classes for error message\n\n**noOptions**:\n- base: Base classes for no options message\n\n**group**, **groupLabel**, **separator**:\n- base: Base classes for a labelled group, its label and the divider between groups\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Combobox\n  items={items}\n  bind:value={value}\n  theme={{\n    inputContainer: {\n      base: 'border-2 rounded-lg',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    },\n    noOptions: {\n      base: 'italic'\n    }\n  }}\n/>\n```\n\n**Custom Option Styling** (option rows use the shared MenuOption theme):\n```svelte\n<script lang=\"ts\">\n  import { setMenuOptionTheme } from '../../MenuOption/index.ts';\n\n  let value = $state<string | null>(null);\n  const items = [\n    { value: 'us', label: 'United States', description: 'North America' },\n    { value: 'uk', label: 'United Kingdom', description: 'Europe' }\n  ];\n\n  setMenuOptionTheme({\n    root: {\n      base: 'rounded-md transition-colors'\n    },\n    title: {\n      base: 'font-semibold'\n    },\n    description: {\n      base: 'text-sm text-neutral/70'\n    }\n  });\n</script>\n\n<Combobox items={items} bind:value={value} />\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setComboboxTheme } from './index.ts';\n  \n  setComboboxTheme({\n    inputContainer: {\n      base: 'rounded-lg border-2 transition-all',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    },\n    loading: {\n      base: 'italic'\n    }\n  });\n</script>\n```\n";

package/dist/components/Form/Combobox/combobox.mcp.js

@@ -26,10 +26,11 @@ A searchable dropdown component that supports both static arrays and async optio
 
 ### Core Props
 
-- **items**: \`ComboboxOption[] | ((searchValue?: string) => MaybePromise<ComboboxOption[]>)\` (required)
-  - Array of options or async function that returns options based on search value
-  - For arrays: filtered client-side
-  - For functions: called with search value, returns Promise or array
+- **items**: \`ComboboxItems | ((searchValue: string | undefined, request: { signal: AbortSignal }) => MaybePromise<ComboboxItems>)\` (required)
+  - Array of options (and groups) or a function that returns them for the search text
+  - \`ComboboxItems\` is \`(ComboboxOption | { label?: string; items: ComboboxOption[] })[]\`; flat options and groups can be mixed. \`ComboboxOption\` is \`{ value; label; description?; disabled?; data? }\`
+  - For arrays: filtered client-side with a case- and accent-insensitive match on the label, in the active I18n locale ("eclair" finds "Éclair")
+  - For functions: called (after a 100ms pause in typing) with the search text and \`{ signal }\`. The signal is aborted when a newer search replaces the request, and a response that is not the latest is ignored, so a slow answer never overwrites a newer list. The last results stay visible, marked busy, while the next request loads
 
 - **value**: \`string | null\` (bindable)
   - Selected option value
@@ -37,15 +38,31 @@ A searchable dropdown component that supports both static arrays and async optio
   - Initial selected value when \`value\` is omitted
 
 - **searchValue**: \`string\` (default: \`''\`, bindable)
-  - Current search input value
+  - Current search input value (a draft: it is never submitted by a native form)
+
+- **open**: \`boolean\` (bindable) / **defaultOpen**: \`boolean\` (default: \`false\`)
+  - Whether the options list is open. The list only renders while there is something to show (options, 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\` (\`'input-change'\`, \`'escape-key'\`, \`'item-press'\`, \`'list-navigation'\`, \`'trigger-press'\`, \`'trigger-focus'\`, \`'focus-out'\`), \`event\`, \`interaction\` and \`cancel()\`; a cancelled change leaves the list as it was
+  - **onAfterOpen** / **onAfterClose**: \`() => void\` fire once after the open or close transition
 
 - **loading**: \`boolean\` (default: \`false\`, bindable)
   - Loading state (managed automatically for async options)
 
 ### Behavior Props
 
-- **showAllOnFocus**: \`boolean\` (default: \`false\`)
-  - Show all options when input is focused, even without typing
+- **openOnFocus**: \`boolean\` (default: \`false\`)
+  - Open the list when the input receives focus, even before typing: static arrays list every option, \`items\` functions are called with an empty search
+- **showAllOnFocus**: \`boolean\` (deprecated alias of \`openOnFocus\`, kept for one minor)
+
+- **filter**: \`(option, searchValue) => boolean\` - Custom match for static arrays (functions filter themselves)
+- **limit**: \`number\` - Show at most this many matches; matching stops once the limit is reached, across groups
+
+- **autoHighlight**: \`boolean | 'always'\` (default: \`'always'\`)
+  - \`'always'\` keeps the first match (or the selected option while the text is empty) highlighted; \`true\` only while text is typed; \`false\` highlights nothing until an arrow key or the pointer moves it
+- **loop**: \`'wrap' | 'input' | false\` (default: \`'wrap'\`) - Past either end of the list: continue at the other end, land on no highlight first (focus stays in the input), or stop
+- **separators**: \`boolean\` (default: \`true\`) - Separators between consecutive groups
+- **item**: \`Snippet<[ComboboxOption]>\` - Custom row renderer, replaces the title and description layout
+- **readOnly**: \`boolean\` - The list opens and can be browsed, but the value cannot change: choosing does nothing, the clear button is hidden, the input is natively \`readonly\`. The value still submits
 
 - **getValueOption**: \`(value: string) => MaybePromise<ComboboxOption | null | undefined>\`
   - Function to get option data for a value when not in loaded options
@@ -77,6 +94,9 @@ A searchable dropdown component that supports both static arrays and async optio
   - Called when selection changes
   - Receives a named payload with both the value and full option object
 
+- **onHighlightChange**: \`({ value, reason, event }) => void\`
+  - Called when the highlighted option changes. \`value\` is the option's value or \`undefined\`; \`reason\` is \`'keyboard'\`, \`'pointer'\` or \`'list'\` (results changed, or the list opened); \`event\` is the KeyboardEvent or pointer event, absent for \`'list'\`
+
 - **onValidate**: \`(value: string) => string[] | boolean\`
   - Custom validation function
 
@@ -132,12 +152,12 @@ A searchable dropdown component that supports both static arrays and async optio
 />
 \`\`\`
 
-### Show All Options on Focus
+### Open on Focus
 
 \`\`\`svelte
 <Combobox
 	items={countries}
-	showAllOnFocus={true}
+	openOnFocus
 	bind:value={value}
 />
 \`\`\`
@@ -164,14 +184,73 @@ A searchable dropdown component that supports both static arrays and async optio
 />
 \`\`\`
 
+### Groups, Disabled Options and Custom Rows
+
+\`\`\`svelte
+<Combobox
+	openOnFocus
+	items={[
+		{ label: 'Europe', items: [{ value: 'fr', label: 'France' }, { value: 'de', label: 'Germany' }] },
+		{ label: 'Asia', items: [{ value: 'cn', label: 'China', disabled: true }] }
+	]}
+	bind:value={value}
+>
+	{#snippet item(option)}
+		<span>{option.label}</span>
+	{/snippet}
+</Combobox>
+\`\`\`
+
+### Abortable Async Options
+
+\`\`\`svelte
+<script lang="ts">
+	const getOptions = async (searchValue: string | undefined, { signal }: { signal: AbortSignal }) => {
+		const response = await fetch(\`/api/countries?q=\${searchValue ?? ''}\`, { signal });
+		return response.json();
+	};
+</script>
+
+<Combobox items={getOptions} bind:value={value} />
+\`\`\`
+
 ## State Management
 
 - **value**: Bindable string (option value) or null
 - **searchValue**: Bindable string for search input
 - **loading**: Bindable boolean, automatically managed for async options
+- **open**: Bindable boolean for the list
 - **errors**: Bindable array or boolean for validation errors
 - **focused**: Bindable boolean for focus state
 
+## Styling hooks
+
+The input, the field container, the list panel and every option carry state attributes. \`data-highlighted\` and \`data-selected\` are written as \`"true"\`; match them by presence.
+
+Attributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.
+
+**Data attributes**
+- \`data-popup-open\`: On the input and the field container around it: present while the list (or its empty, loading or error status) shows.
+- \`data-popup-side\`: On the field container: the side of the field the list sits on.
+- \`data-disabled\`: On the input: present while disabled. On an option: present while it is disabled.
+- \`data-highlighted\`: On an option: present while the keyboard or the pointer highlights it.
+- \`data-selected\`: On an option: present while it is the value.
+- \`data-open\`: On the list panel: present while open.
+- \`data-closed\`: On the list panel: present while its exit transition plays.
+- \`data-entering\`: On the list panel: present while the enter transition plays.
+- \`data-exiting\`: On the list panel: present while the exit transition plays.
+- \`data-side\`: On the list panel: the side of the field it sits on after flipping.
+- \`data-align\`: On the list panel: \`start\`, \`center\` or \`end\`.
+
+**CSS variables** (set on the list panel's positioned wrapper and inherited by the list)
+- \`--available-width\`: The width in px the panel can take before it reaches the viewport edges, minus 20px.
+- \`--available-height\`: The room in px between the trigger and the viewport edge on the panel's side, minus 20px. Cap a scrolling list with \`max-height: min(240px, var(--available-height))\`.
+- \`--anchor-width\`: The trigger's width in px, snapped to the device pixel grid.
+- \`--anchor-height\`: The trigger's height in px, snapped to the device pixel grid.
+- \`--transform-origin\`: The panel corner facing the trigger, mirrored in right-to-left documents; the point the panel scales from.
+
+The typed maps \`comboboxDataAttributes\` and \`comboboxCssVariables\` (from \`entasis/combobox\`) list each name with its meaning.
+
 ## Accessibility
 
 - Full ARIA combobox pattern implementation
@@ -180,18 +259,26 @@ A searchable dropdown component that supports both static arrays and async optio
 - **role="option"** on each option
 - **aria-expanded**, **aria-controls**, **aria-activedescendant** for state
 - **aria-autocomplete="list"** for search behavior
-- Keyboard navigation: ArrowDown/Up (wraps around), Enter (select), Escape (close), Home/End (first/last)
-- Screen reader announcements for loading and error states
+- Keyboard navigation: ArrowDown/ArrowUp open a closed list (with every option) and then move the highlight, Enter selects, Escape closes the list and keeps focus in the input (a second Escape clears the typed text), Home/End jump to the first/last option
+- Clicking the already-focused input toggles the list; choosing an option, Clear and Escape all keep focus in the input
+- The listbox owns only options and groups; the loading, error and "no options" messages sit beside it, and \`aria-expanded\` is true while options are listed
+- One persistent visually hidden live region (\`role="status"\`) next to the input announces result counts ("3 results available"), the empty state, loading and errors after typing settles
+- The highlight follows the selected option when the list opens and when the text is cleared
 
 ## Notes
 
 - **Debouncing**: Search is debounced by 100ms to reduce API calls
-- **Race Conditions**: Handled automatically - only latest async request updates state
+- **Race Conditions**: Handled automatically - older requests are aborted and only the latest response updates state
+- **Native forms**: The search box carries no \`name\`. A hidden input beside it submits the selected value under \`name\` (nothing when there is no name or the field is disabled); \`required\` blocks a native submit while nothing is selected
+- **Closing**: Escape, choosing an option, or focus leaving the field closes the list; the rows stay on screen through the exit transition
 - **Option Format**: Options must have \`value\` (string) and \`label\` (string). Optional \`description\` displays below label
-- **Keyboard Navigation**: Wraps around - ArrowDown at bottom goes to top, ArrowUp at top goes to bottom
+- **Keyboard Navigation**: Wraps around by default - ArrowDown at bottom goes to top, ArrowUp at top goes to bottom (see \`loop\`)
+- **Groups and disabled options**: Disabled options are dimmed and skipped by the keyboard; groups render like Select's (\`role="group"\` with a hidden label, presentational separators)
 - **Empty States**: Shows loading text, error message, or no options text appropriately
 - **Clear Button**: Automatically shown when value exists, uses the shared field action button hitbox
 - **Default Prefix**: Magnifying glass icon shown by default unless \`prefix={false}\` or custom snippet provided
+- **List height**: The option list scrolls beyond 200px, or beyond the room left between the field and the viewport edge (the Popover's \`--available-height\`), so it shrinks above an on-screen keyboard instead of running under it
+- **Styling hooks**: While the list is open, the field it is anchored to carries \`data-popup-side\` (\`bottom\` or \`top\`) and the panel \`data-side\`
 
 ## Theme Customization
 
@@ -205,6 +292,7 @@ The theme object contains the following parts:
 - **loading**: Loading state indicator styles
 - **error**: Error message styles
 - **noOptions**: No options found message styles
+- **group**, **groupLabel**, **separator**: Group container, group label and the divider between groups
 
 Option rows are rendered with the shared \`MenuOption\` component (parts: root, title, description, prefix, suffix, content) and are themed through \`setMenuOptionTheme\` from \`entasis/menu-option\`, not through the Combobox theme.
 
@@ -231,6 +319,9 @@ Option rows are rendered with the shared \`MenuOption\` component (parts: root,
 **noOptions**:
 - base: Base classes for no options message
 
+**group**, **groupLabel**, **separator**:
+- base: Base classes for a labelled group, its label and the divider between groups
+
 ### Usage Examples
 
 **Basic Theme Override**:

package/dist/components/Form/Combobox/combobox.props.d.ts

@@ -3,6 +3,8 @@ import type { Messages } from '../../../i18n/en.js';
 import type { InputProps } from '../Field/field.js';
 import type { ComboboxThemeProps } from './combobox.theme.js';
 import type { Snippet } from 'svelte';
+import type { OpenChangeHandler } from '../../../utils/openChange.js';
+import type { HighlightReason, ListLoop } from '../../../utils/useListNavigation.svelte.js';
 export type MaybePromise<T> = T | Promise<T>;
 export type ComboboxOption = {
     /** Unique value submitted when this option is selected. */
@@ -11,51 +13,143 @@ export type ComboboxOption = {
     label: string;
     /** Supporting text rendered below the option label in the dropdown. */
     description?: string;
+    /** Dims the option and keeps it out of keyboard navigation: it cannot be highlighted or selected. */
+    disabled?: boolean;
     /** Optional arbitrary metadata attached to the option. */
     data?: Record<string, unknown>;
 };
+export type ComboboxOptionGroup = {
+    /** Optional group label rendered above the group's options. */
+    label?: string;
+    /** The options of the group. */
+    items: ComboboxOption[];
+};
+/** Flat options and `{ label, items }` groups can be mixed freely, as in Select. */
+export type ComboboxItems = (ComboboxOption | ComboboxOptionGroup)[];
+/** Second argument of an `items` function. */
+export type ComboboxItemsRequest = {
+    /**
+     * Aborted when a newer search replaces this request (or the list is no longer wanted). Pass it
+     * to `fetch` to cancel the network call; results of an aborted request are ignored either way.
+     */
+    signal: AbortSignal;
+};
+/** The options, or a function that returns the options for the current search text. */
+export type ComboboxItemsSource = ComboboxItems | ((searchValue: string | undefined, request: ComboboxItemsRequest) => MaybePromise<ComboboxItems>);
+/** Decides whether an option matches the search text. */
+export type ComboboxFilter = (option: ComboboxOption, searchValue: string) => boolean;
 export type ComboboxValueChangePayload = {
     value: string | null;
     option: ComboboxOption | null;
 };
-export type ComboboxProps = Omit<InputProps<'combobox'>, 'prefix' | 'onValueChange'> & {
-    /** Called when the selection changes with its value and resolved option context. */
-    onValueChange?: (payload: ComboboxValueChangePayload) => void;
+/** Why the highlighted option changed: the keyboard, the pointer, or the list changing underneath it. */
+export type ComboboxHighlightReason = HighlightReason;
+export type ComboboxHighlightChangePayload = {
+    /** The highlighted option's value, or `undefined` when nothing is highlighted. */
+    value: string | undefined;
+    /** `'keyboard'` for keys, `'pointer'` for hover, `'list'` when results changed or the list opened. */
+    reason: ComboboxHighlightReason;
+    /** The keyboard or pointer event behind the change; absent for `'list'`. */
+    event?: Event;
+};
+/**
+ * Props shared by Combobox and TagsInput: the searchable list behind them. Both read the same
+ * options, open state and highlight model.
+ */
+export type ComboboxListProps = {
     /** Bindable text currently typed in the search input. */
     searchValue?: string;
     /** Bindable flag indicating async options are being fetched. */
     loading?: boolean;
-    /** Hint text shown in the search input when no option is selected. */
-    placeholder?: string;
-    /** Static array or function returning items filtered by the current search value. */
-    items: ComboboxOption[] | ((searchValue?: string) => MaybePromise<ComboboxOption[]>);
+    /**
+     * Whether the options list is open. Bindable. The list only shows while there is something to
+     * show (options, a loading or error message, or a "no options" message for the typed text).
+     */
+    open?: boolean;
+    /** Initial open state when `open` is omitted. */
+    defaultOpen?: boolean;
+    /**
+     * Called before the list opens or closes, with the requested state and the change details:
+     * `reason` (`'input-change'`, `'escape-key'`, `'item-press'`, `'list-navigation'`,
+     * `'trigger-press'`, `'trigger-focus'`, `'focus-out'`…), the originating `event`, the
+     * `interaction` type and `cancel()`. Calling `details.cancel()` keeps the list as it is.
+     */
+    onOpenChange?: OpenChangeHandler;
+    /** Called once per open, after the open transition finishes. */
+    onAfterOpen?: () => void;
+    /** Called once per close, after the close transition finishes. */
+    onAfterClose?: () => void;
+    /**
+     * Open the list when the input receives focus, even before anything is typed: static arrays
+     * list every option, `items` functions are called with an empty search.
+     * @default false
+     */
+    openOnFocus?: boolean;
+    /** @deprecated Use `openOnFocus`. Kept as an alias for one minor. */
+    showAllOnFocus?: boolean;
+    /**
+     * Static array, or a function returning the options for the current search text. The function
+     * receives `{ signal }` as its second argument: it is aborted when a newer search replaces the
+     * request, and a response that is not the latest is ignored.
+     */
+    items?: ComboboxItemsSource;
+    /**
+     * Decides whether an option matches the typed text, for static arrays. Defaults to a case- and
+     * accent-insensitive substring match on the label, compared in the active I18n locale
+     * ("eclair" finds "Éclair"). Functions passed as `items` filter themselves.
+     */
+    filter?: ComboboxFilter;
+    /** Shows at most this many matching options. Matching stops once the limit is reached. */
+    limit?: number;
+    /**
+     * Which option is highlighted without keyboard input. `'always'` (default for Combobox) keeps
+     * the first match, or the selected option while the text is empty, highlighted; `true` does so
+     * only while text is typed; `false` highlights nothing until an arrow key or the pointer moves
+     * it, so Enter acts on the typed text.
+     */
+    autoHighlight?: boolean | 'always';
+    /**
+     * What moving past either end of the list does: `'wrap'` continues at the other end (default),
+     * `'input'` lands on no highlight first (focus stays in the input) and wraps from there, and
+     * `false` stops at the end.
+     * @default 'wrap'
+     */
+    loop?: ListLoop;
+    /** Called when the highlighted option changes, with the value, why it moved and the event behind it. */
+    onHighlightChange?: (payload: ComboboxHighlightChangePayload) => void;
+    /** Render a separator between consecutive groups. @default true */
+    separators?: boolean;
+    /** Custom row renderer: receives the option. Overrides the default title and description layout. */
+    item?: Snippet<[ComboboxOption]>;
     /**
      * Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height).
      * @default 'normal'
      */
     density?: Density;
-    /** When true, shows all options on focus without a search query (static arrays only). */
-    showAllOnFocus?: boolean;
     /**
      * Function to get the label for a value when the option is not yet loaded.
      * Useful for async options where the default value might not be in the initial options list.
      */
     getValueOption?: (value: string) => MaybePromise<ComboboxOption | null | undefined>;
+    /** Text to display when loading options. Defaults to "Loading...". */
+    loadingText?: string;
+    /** Text to display when no options are found or available. Defaults to "No options found". */
+    noOptionsText?: string;
+    /** Per-instance i18n overrides merged over the global catalog. */
+    i18n?: Partial<Messages>;
+};
+export type ComboboxProps = Omit<InputProps<'combobox'>, 'prefix' | 'onValueChange' | 'density'> & ComboboxListProps & {
+    /** Static array, or a function returning the options for the current search text. */
+    items: ComboboxItemsSource;
+    /** Called when the selection changes with its value and resolved option context. */
+    onValueChange?: (payload: ComboboxValueChangePayload) => void;
+    /** Hint text shown in the search input when no option is selected. */
+    placeholder?: string;
     /**
      * Prefix content. Set to `false` to hide the default magnifying glass icon.
      * If not provided, the magnifying glass icon is shown by default.
      */
     prefix?: Snippet | false;
-    /**
-     * Text to display when loading options. Defaults to "Loading...".
-     */
-    loadingText?: string;
-    /**
-     * Text to display when no options are found or available. Defaults to "No options found".
-     */
-    noOptionsText?: string;
     /** Theme overrides for the combobox dropdown, options, and field parts. */
     theme?: ComboboxThemeProps & InputProps<'combobox'>['theme'];
-    /** Per-instance i18n overrides merged over the global catalog. */
-    i18n?: Partial<Messages>;
 };