entasis 0.11.0 → 0.12.0

package/dist/components/Form/Select/select.mcp.d.ts

@@ -1 +1 @@
-export declare const selectDescription = "\n# Select Component\n\nA custom (non-native) selection field: a combobox trigger opening a listbox popover, with full\nkeyboard navigation, grouped options, and Field/Form integration. Like a native select (and\nRadix's item-aligned or Base UI's `alignItemWithTrigger` position), the listbox opens over the\ntrigger with the selected option sitting on the value.\n\n## Basic Usage\n\n```svelte\n<Select\n\tlabel=\"Country\"\n\tbind:value={country}\n\titems={[\n\t\t{ value: 'us', label: 'United States' },\n\t\t{ value: 'uk', label: 'United Kingdom' },\n\t\t{ value: 'ca', label: 'Canada' }\n\t]}\n/>\n```\n\n## Grouped options\n\nFlat options and `{ label, items }` groups can be mixed freely; separators render between groups.\n\n```svelte\n<Select\n\tlabel=\"Timezone\"\n\tbind:value={tz}\n\titems={[\n\t\t{ label: 'Europe', items: [{ value: 'paris', label: 'Paris' }, { value: 'berlin', label: 'Berlin' }] },\n\t\t{ label: 'America', items: [{ value: 'nyc', label: 'New York' }, { value: 'la', label: 'Los Angeles' }] }\n\t]}\n/>\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string (bindable) - Selected value\n- **items**: (SelectOption | SelectOptionGroup)[] - Flat `{ value, label, disabled? }` options and/or `{ label, items }` groups\n- **placeholder**: string (default: 'Select an option') - Trigger text when no selection\n- **separators**: boolean (default: true) - Render separators between consecutive groups\n- **alignItemWithTrigger**: boolean (default: true) - Open over the trigger with the selected option (the first enabled one when nothing is selected) on the trigger's middle and its text on the value text. A list taller than the viewport is capped 8px from the edges and pre-scrolled so the option stays on the trigger; a trigger too close to the bottom for four rows gives up the alignment and the panel rises into view. Wheel and touch scrolling outside the panel are blocked while it is open, so the trigger cannot move away from it. `false` opens a dropdown below the trigger instead, capped at ~240px\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder\n- **description**: string | Snippet - Helper text\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable the trigger\n- **size**: 'small' | 'normal' | 'large' - Trigger and dropdown size\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)\n- **name**: string - Form field name; also renders a hidden input for native form posts\n\n### Bindable Props\n- **value**: string - Selected value\n- **errors**: string[] - Validation errors\n- **focused**: boolean - Trigger focus state\n\n### Callbacks\n- **onValueChange**: (value) => void - Fires when the selection changes\n- **onValidate**: (value) => string[] | boolean - Custom validation\n\n### Advanced Props\n- **theme**: SelectThemeProps - Theme overrides (input, inputContainer, value, triggerIcon, content, group, groupLabel, item, itemIndicator, separator)\n\n## Keyboard\n\n- Closed: ArrowDown / ArrowUp / Enter / Space open the dropdown, anchored on the selected option\n- Open: ArrowDown / ArrowUp move the highlight (wrap-around), Home / End jump, Enter / Space select, Escape closes, Tab closes and moves focus on\n- Type-ahead: typing letters while the trigger has focus moves the highlight to the next option whose label starts with the typed text\n- Disabled options are skipped by the highlight\n\n## Accessibility\n\nARIA 1.2 select-only combobox pattern: the trigger is a `role=\"combobox\"` button with\n`aria-haspopup=\"listbox\"`, `aria-expanded`, and `aria-controls`; DOM focus stays on the\ntrigger while `aria-activedescendant` tracks the highlighted `role=\"option\"` (virtual focus).\nThe selected option shows a check indicator and `aria-selected`.\n\nThe trigger always has an accessible name: `label` names it through the Field label (a string\nlabel as a `<label for>`, a snippet through `aria-labelledby`), and without one the trigger\nfalls back to `placeholder`, then to the catalog's \"Select an option\". Pass `label` whenever\nan unlabelled select sits in a toolbar or filter row, so the name says which control it is\nrather than repeating the placeholder.\n\n## Notes\n\n- Selection re-focuses the trigger (matches native select behavior)\n- Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land\n- The list scrolls (ScrollArea) beyond the viewport when item-aligned, beyond ~240px as a dropdown; the highlight scrolls into view on keyboard nav\n- The panel covers the trigger while open, so clicking outside (not the trigger) closes it, as with a native select\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";
+export declare const selectDescription = "\n# Select Component\n\nA custom (non-native) selection field: a combobox trigger opening a listbox popover, with full\nkeyboard navigation, type-to-select, grouped options, read-only and multiple selection, browser\nautofill and Field/Form integration. Like a native select (and Radix's item-aligned or Base UI's\n`alignItemWithTrigger` position), the listbox opens over the trigger with the selected option\nsitting on the value.\n\n## Basic Usage\n\n```svelte\n<Select\n\tlabel=\"Country\"\n\tbind:value={country}\n\titems={[\n\t\t{ value: 'us', label: 'United States' },\n\t\t{ value: 'uk', label: 'United Kingdom' },\n\t\t{ value: 'ca', label: 'Canada' }\n\t]}\n/>\n```\n\n## Grouped options\n\nFlat options and `{ label, items }` groups can be mixed freely; separators render between groups.\n\n```svelte\n<Select\n\tlabel=\"Timezone\"\n\tbind:value={tz}\n\titems={[\n\t\t{ label: 'Europe', items: [{ value: 'paris', label: 'Paris' }, { value: 'berlin', label: 'Berlin' }] },\n\t\t{ label: 'America', items: [{ value: 'nyc', label: 'New York' }, { value: 'la', label: 'Los Angeles' }] }\n\t]}\n/>\n```\n\n## Multiple selection\n\n`multiple` makes the Select hold a list of values (field type `select-multiple`). The list stays\nopen while options are toggled with a click, Enter or Space, the listbox is `aria-multiselectable`,\nevery selected option shows its check, and `value` is an array in item order.\n\n```svelte\n<Select\n\tmultiple\n\tlabel=\"Toppings\"\n\tbind:value={toppings}\n\titems={[\n\t\t{ value: 'olives', label: 'Olives' },\n\t\t{ value: 'basil', label: 'Basil' },\n\t\t{ value: 'ham', label: 'Ham' }\n\t]}\n/>\n```\n\nThe trigger lists the first two selected labels and counts the rest (`Olives, Basil +1`); pass\n`formatValue` to write your own text. The list opens on the first selected option in item order.\nA native form submits one hidden input per value under the same `name` (read them with\n`FormData.getAll`), and a required multiple Select needs at least one value. In a Form, use\n`type: 'select-multiple'`.\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string | null (bindable) - Selected value; with `multiple`, a (readonly) string array in item order\n- **multiple**: boolean (default: false) - Hold several values; the list stays open while options are toggled\n- **formatValue**: (options: SelectOption[]) => string - With `multiple`, the text the trigger shows for the selected options (default: two labels and `+N`)\n- **clearable**: boolean (default: false) - Adds a button that clears the selection (`null`, or `[]` with `multiple`) and returns focus to the trigger; hidden while empty, read-only or disabled\n- **id**: string - Id of the trigger button, so an external `<label for>` can name it; without a `label` the trigger's placeholder fallback steps aside when such a label exists\n- **autocomplete**: string - Autofill token (`country`, `address-level1`...). Renders a visually hidden text input the browser can autofill; the filled text selects the option whose value matches, else whose label matches (ignoring case and accents). Autofill never opens the list and is ignored while disabled or read-only\n- **items**: readonly (SelectOption | SelectOptionGroup)[] - Flat `{ value, label, disabled? }` options and/or `{ label, items }` groups; readonly arrays and `as const` data are accepted\n- **placeholder**: string (default: 'Select an option') - Trigger text when no selection\n- **separators**: boolean (default: true) - Render separators between consecutive groups\n- **alignItemWithTrigger**: boolean (default: true) - Open over the trigger with the selected option (the first enabled one when nothing is selected) on the trigger's middle and its text on the value text. A list taller than the viewport is capped 8px from the edges and pre-scrolled so the option stays on the trigger, and a `max-height` the theme puts on the `list` slot caps it further; a trigger too close to the bottom for four rows gives up the alignment and the panel rises into view. Wheel and touch scrolling outside the panel are blocked while it is open, so the trigger cannot move away from it. Only a mouse or keyboard open aligns: a list opened by touch is a dropdown below the trigger. `false` opens a dropdown below the trigger always, capped at 240px or the room left beside the trigger\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder\n- **description**: string | Snippet - Helper text\n- **required**: boolean - Mark as required. A native form is blocked from submitting while nothing is selected (the browser's report moves to the trigger); a disabled Select is not required\n- **disabled**: boolean - Disable the trigger; the hidden inputs are disabled too, so a native form post leaves the value out\n- **readOnly**: boolean - The list opens and can be browsed (arrows, Home, End, typing, hover), but no option can be chosen and the value cannot change. The trigger carries `aria-readonly` and `data-readonly` (the popup does not), typing on the closed trigger picks nothing, `clearable` hides its button, and the value is still submitted by a native form\n- **open**: boolean (bindable) - Whether the list is open\n- **defaultOpen**: boolean (default: false) - Initial open state when `open` is not provided\n- **size**: 'small' | 'normal' | 'large' - Trigger and dropdown size\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)\n- **name**: string - Form field name; also renders a hidden input per value for native form posts (disabled while the Select is disabled; a read-only Select still submits)\n\n### Bindable Props\n- **value**: string - Selected value\n- **errors**: string[] - Validation errors\n- **focused**: boolean - Trigger focus state\n\n### Callbacks\n- **onValueChange**: (value) => void - Fires when the selection changes: the new string or `null`, or with `multiple` the new array (once per toggle)\n- **onValidate**: (value) => string[] | boolean - Custom validation\n- **onOpenChange**: (open, details) => void - Runs before the list opens or closes. `details` carries `reason` (`'trigger-press'`, `'list-navigation'` for an arrow-key open, `'item-press'`, `'escape-key'`, `'outside-press'` (a press outside the list), `'focus-out'`, `'close-press'`, `'imperative-action'`), the originating `event`, the `trigger`, the `interaction` (`'mouse'`, `'touch'`, `'pen'`, `'keyboard'`, `'programmatic'`) and `cancel()`, which keeps the list as it is. Setting `open` from outside is silent\n- **onAfterOpen** / **onAfterClose**: () => void - Once per open and close, after the transition (right away when none plays)\n\n### Advanced Props\n- **triggerAttrs**: native attributes for the trigger button (handlers run before the built-in ones; `preventDefault()` cancels them)\n- **theme**: SelectThemeProps - Theme overrides (input, inputContainer, value, triggerIcon, content, list, listbox, group, groupLabel, separator). The `list` slot is the scrolling list: its `dropdown` variant carries the 240px cap of a dropdown, and a `max-height` you put on it caps an item-aligned list too\n\n## Keyboard\n\n- Closed: ArrowDown / ArrowUp / Enter / Space open the dropdown, anchored on the selected option (the first selected one with `multiple`)\n- Open: ArrowDown / ArrowUp move the highlight (wrap-around), Home / End jump, Enter / Space select (toggle with `multiple`), Escape closes, Tab closes and moves focus on\n- Type-ahead: typing letters while the trigger has focus moves the highlight to the next option whose label starts with the typed text. Space continues the search while characters are buffered (`united s` reaches United States) and selects only when the search is over. The buffer clears after a second and whenever the list closes\n- Typing on a closed trigger picks the matching option without opening the list, as a native select does, with one `onValueChange` (not with `multiple` or `readOnly`)\n- Disabled options are skipped by the highlight and the type-ahead\n\n## Styling hooks\n\nThe trigger, 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 (`[data-highlighted]`).\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 trigger button and the field container around it: present while the list is open.\n- `data-placeholder`: On the trigger: present while no value is chosen and the placeholder shows.\n- `data-disabled`: On the trigger: present while disabled. On an option: present while it is disabled.\n- `data-readonly`: On the trigger: present while `readOnly`.\n- `data-popup-side`: On the field container: `none` while the list is placed over the trigger, otherwise the side it sits on.\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 selected.\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: `none` while it is placed over the trigger (aligned on the selected option), otherwise the side of the trigger it sits on.\n\n**CSS variables** (set on the list panel's positioned wrapper and inherited by the list; the mobile sheet has none)\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 `selectDataAttributes` and `selectCssVariables` (from `entasis/select`) list each name with its meaning.\n\n## Accessibility\n\nARIA 1.2 select-only combobox pattern: the trigger is a `role=\"combobox\"` button with\n`aria-haspopup=\"listbox\"`, `aria-expanded`, and `aria-controls`; DOM focus stays on the\ntrigger while `aria-activedescendant` tracks the highlighted `role=\"option\"` (virtual focus).\nThe selected option shows a check indicator and `aria-selected`.\n\nThe scrolling viewport is the listbox (`role=\"listbox\"`, `tabindex=\"-1\"`), so the list scrolls\ninside the element that owns the options and no extra scroll group or tab stop appears when it\noverflows. The listbox owns only options and `role=\"group\"` sets: bare options sit directly under\nit, a group exists only for a labelled set. Group separators are `role=\"presentation\"`, group\nlabels are `aria-hidden` (each group is named through `aria-label`), and the scrollbars are\n`aria-hidden` and sit outside the listbox. `multiple` adds `aria-multiselectable`.\n\nThe trigger is the only tab stop; the label focuses it without opening the list. Touch\nscreen readers move focus onto options instead of using the virtual cursor, so focus entering the\npanel keeps the list open (it closes when focus leaves both the trigger and the panel), Escape on a\nfocused option closes it and returns focus to the trigger, and a visually hidden \"Close\" button at\nthe end of the panel gives users with no Escape key a way out.\n\nThe trigger always has an accessible name: `label` names it through the Field label (a string\nlabel as a `<label for>`, a snippet through `aria-labelledby`), and without one the trigger\nfalls back to `placeholder`, then to the catalog's \"Select an option\". Pass `label` whenever\nan unlabelled select sits in a toolbar or filter row, so the name says which control it is\nrather than repeating the placeholder.\n\n## Notes\n\n- Selection re-focuses the trigger (matches native select behavior); with `multiple` the list stays open and focus stays on the trigger\n- Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land. A list opened from outside (`open`, `defaultOpen`) moves focus to the trigger, so Escape, the arrow keys and clicking away work the same, and it is measured afresh each time it opens\n- A `<label for>` pointing at `id` names the trigger and focuses it on click\n- The list scrolls (ScrollArea) beyond the viewport when item-aligned, beyond 240px as a dropdown (less when there is less room beside the trigger: the dropdown list is capped by the Popover's `--available-height`, so it never runs under an on-screen keyboard or over its trigger); the highlight scrolls into view on keyboard nav\n- While the dropdown is open, the input container carries `data-popup-side` (`bottom`, `top`, or `none` when item-aligned) and the panel `data-side`, so a theme can flatten the corner where they meet\n- The trigger carries `data-placeholder` while nothing is selected and `data-readonly` while read-only\n- Option rows are lean: a titled row with a check, using MenuOption's theme, and each option's id comes from a map, so a list of a thousand options opens without a search per row. Option ids are numbered in the order they are first needed, so values that would collide once sanitised (`a.b`, `a_b`) never share an id\n- The panel covers the trigger while open, so clicking outside (not the trigger) closes it, as with a native select\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n- **open**: bindable disclosure state; **defaultOpen** initial state; **onOpenChange** reports every user-driven change before it happens and may cancel it; **onAfterOpen** / **onAfterClose** fire once per open and close.\n\n";

package/dist/components/Form/Select/select.mcp.js

@@ -2,9 +2,10 @@ export const selectDescription = `
 # Select Component
 
 A custom (non-native) selection field: a combobox trigger opening a listbox popover, with full
-keyboard navigation, grouped options, and Field/Form integration. Like a native select (and
-Radix's item-aligned or Base UI's \`alignItemWithTrigger\` position), the listbox opens over the
-trigger with the selected option sitting on the value.
+keyboard navigation, type-to-select, grouped options, read-only and multiple selection, browser
+autofill and Field/Form integration. Like a native select (and Radix's item-aligned or Base UI's
+\`alignItemWithTrigger\` position), the listbox opens over the trigger with the selected option
+sitting on the value.
 
 ## Basic Usage
 
@@ -35,25 +36,58 @@ Flat options and \`{ label, items }\` groups can be mixed freely; separators ren
 />
 \`\`\`
 
+## Multiple selection
+
+\`multiple\` makes the Select hold a list of values (field type \`select-multiple\`). The list stays
+open while options are toggled with a click, Enter or Space, the listbox is \`aria-multiselectable\`,
+every selected option shows its check, and \`value\` is an array in item order.
+
+\`\`\`svelte
+<Select
+	multiple
+	label="Toppings"
+	bind:value={toppings}
+	items={[
+		{ value: 'olives', label: 'Olives' },
+		{ value: 'basil', label: 'Basil' },
+		{ value: 'ham', label: 'Ham' }
+	]}
+/>
+\`\`\`
+
+The trigger lists the first two selected labels and counts the rest (\`Olives, Basil +1\`); pass
+\`formatValue\` to write your own text. The list opens on the first selected option in item order.
+A native form submits one hidden input per value under the same \`name\` (read them with
+\`FormData.getAll\`), and a required multiple Select needs at least one value. In a Form, use
+\`type: 'select-multiple'\`.
+
 ## Props
 
 Extends all Field component props plus:
 
 ### Core Props
-- **value**: string (bindable) - Selected value
-- **items**: (SelectOption | SelectOptionGroup)[] - Flat \`{ value, label, disabled? }\` options and/or \`{ label, items }\` groups
+- **value**: string | null (bindable) - Selected value; with \`multiple\`, a (readonly) string array in item order
+- **multiple**: boolean (default: false) - Hold several values; the list stays open while options are toggled
+- **formatValue**: (options: SelectOption[]) => string - With \`multiple\`, the text the trigger shows for the selected options (default: two labels and \`+N\`)
+- **clearable**: boolean (default: false) - Adds a button that clears the selection (\`null\`, or \`[]\` with \`multiple\`) and returns focus to the trigger; hidden while empty, read-only or disabled
+- **id**: string - Id of the trigger button, so an external \`<label for>\` can name it; without a \`label\` the trigger's placeholder fallback steps aside when such a label exists
+- **autocomplete**: string - Autofill token (\`country\`, \`address-level1\`...). Renders a visually hidden text input the browser can autofill; the filled text selects the option whose value matches, else whose label matches (ignoring case and accents). Autofill never opens the list and is ignored while disabled or read-only
+- **items**: readonly (SelectOption | SelectOptionGroup)[] - Flat \`{ value, label, disabled? }\` options and/or \`{ label, items }\` groups; readonly arrays and \`as const\` data are accepted
 - **placeholder**: string (default: 'Select an option') - Trigger text when no selection
 - **separators**: boolean (default: true) - Render separators between consecutive groups
-- **alignItemWithTrigger**: boolean (default: true) - Open over the trigger with the selected option (the first enabled one when nothing is selected) on the trigger's middle and its text on the value text. A list taller than the viewport is capped 8px from the edges and pre-scrolled so the option stays on the trigger; a trigger too close to the bottom for four rows gives up the alignment and the panel rises into view. Wheel and touch scrolling outside the panel are blocked while it is open, so the trigger cannot move away from it. \`false\` opens a dropdown below the trigger instead, capped at ~240px
+- **alignItemWithTrigger**: boolean (default: true) - Open over the trigger with the selected option (the first enabled one when nothing is selected) on the trigger's middle and its text on the value text. A list taller than the viewport is capped 8px from the edges and pre-scrolled so the option stays on the trigger, and a \`max-height\` the theme puts on the \`list\` slot caps it further; a trigger too close to the bottom for four rows gives up the alignment and the panel rises into view. Wheel and touch scrolling outside the panel are blocked while it is open, so the trigger cannot move away from it. Only a mouse or keyboard open aligns: a list opened by touch is a dropdown below the trigger. \`false\` opens a dropdown below the trigger always, capped at 240px or the room left beside the trigger
 
 ### Field Props (inherited)
 - **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder
 - **description**: string | Snippet - Helper text
-- **required**: boolean - Mark as required
-- **disabled**: boolean - Disable the trigger
+- **required**: boolean - Mark as required. A native form is blocked from submitting while nothing is selected (the browser's report moves to the trigger); a disabled Select is not required
+- **disabled**: boolean - Disable the trigger; the hidden inputs are disabled too, so a native form post leaves the value out
+- **readOnly**: boolean - The list opens and can be browsed (arrows, Home, End, typing, hover), but no option can be chosen and the value cannot change. The trigger carries \`aria-readonly\` and \`data-readonly\` (the popup does not), typing on the closed trigger picks nothing, \`clearable\` hides its button, and the value is still submitted by a native form
+- **open**: boolean (bindable) - Whether the list is open
+- **defaultOpen**: boolean (default: false) - Initial open state when \`open\` is not provided
 - **size**: 'small' | 'normal' | 'large' - Trigger and dropdown size
 - **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)
-- **name**: string - Form field name; also renders a hidden input for native form posts
+- **name**: string - Form field name; also renders a hidden input per value for native form posts (disabled while the Select is disabled; a read-only Select still submits)
 
 ### Bindable Props
 - **value**: string - Selected value
@@ -61,18 +95,51 @@ Extends all Field component props plus:
 - **focused**: boolean - Trigger focus state
 
 ### Callbacks
-- **onValueChange**: (value) => void - Fires when the selection changes
+- **onValueChange**: (value) => void - Fires when the selection changes: the new string or \`null\`, or with \`multiple\` the new array (once per toggle)
 - **onValidate**: (value) => string[] | boolean - Custom validation
+- **onOpenChange**: (open, details) => void - Runs before the list opens or closes. \`details\` carries \`reason\` (\`'trigger-press'\`, \`'list-navigation'\` for an arrow-key open, \`'item-press'\`, \`'escape-key'\`, \`'outside-press'\` (a press outside the list), \`'focus-out'\`, \`'close-press'\`, \`'imperative-action'\`), the originating \`event\`, the \`trigger\`, the \`interaction\` (\`'mouse'\`, \`'touch'\`, \`'pen'\`, \`'keyboard'\`, \`'programmatic'\`) and \`cancel()\`, which keeps the list as it is. Setting \`open\` from outside is silent
+- **onAfterOpen** / **onAfterClose**: () => void - Once per open and close, after the transition (right away when none plays)
 
 ### Advanced Props
-- **theme**: SelectThemeProps - Theme overrides (input, inputContainer, value, triggerIcon, content, group, groupLabel, item, itemIndicator, separator)
+- **triggerAttrs**: native attributes for the trigger button (handlers run before the built-in ones; \`preventDefault()\` cancels them)
+- **theme**: SelectThemeProps - Theme overrides (input, inputContainer, value, triggerIcon, content, list, listbox, group, groupLabel, separator). The \`list\` slot is the scrolling list: its \`dropdown\` variant carries the 240px cap of a dropdown, and a \`max-height\` you put on it caps an item-aligned list too
 
 ## Keyboard
 
-- Closed: ArrowDown / ArrowUp / Enter / Space open the dropdown, anchored on the selected option
-- Open: ArrowDown / ArrowUp move the highlight (wrap-around), Home / End jump, Enter / Space select, Escape closes, Tab closes and moves focus on
-- Type-ahead: typing letters while the trigger has focus moves the highlight to the next option whose label starts with the typed text
-- Disabled options are skipped by the highlight
+- Closed: ArrowDown / ArrowUp / Enter / Space open the dropdown, anchored on the selected option (the first selected one with \`multiple\`)
+- Open: ArrowDown / ArrowUp move the highlight (wrap-around), Home / End jump, Enter / Space select (toggle with \`multiple\`), Escape closes, Tab closes and moves focus on
+- Type-ahead: typing letters while the trigger has focus moves the highlight to the next option whose label starts with the typed text. Space continues the search while characters are buffered (\`united s\` reaches United States) and selects only when the search is over. The buffer clears after a second and whenever the list closes
+- Typing on a closed trigger picks the matching option without opening the list, as a native select does, with one \`onValueChange\` (not with \`multiple\` or \`readOnly\`)
+- Disabled options are skipped by the highlight and the type-ahead
+
+## Styling hooks
+
+The trigger, 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 (\`[data-highlighted]\`).
+
+Attributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.
+
+**Data attributes**
+- \`data-popup-open\`: On the trigger button and the field container around it: present while the list is open.
+- \`data-placeholder\`: On the trigger: present while no value is chosen and the placeholder shows.
+- \`data-disabled\`: On the trigger: present while disabled. On an option: present while it is disabled.
+- \`data-readonly\`: On the trigger: present while \`readOnly\`.
+- \`data-popup-side\`: On the field container: \`none\` while the list is placed over the trigger, otherwise the side it sits on.
+- \`data-highlighted\`: On an option: present while the keyboard or the pointer highlights it.
+- \`data-selected\`: On an option: present while it is selected.
+- \`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: \`none\` while it is placed over the trigger (aligned on the selected option), otherwise the side of the trigger it sits on.
+
+**CSS variables** (set on the list panel's positioned wrapper and inherited by the list; the mobile sheet has none)
+- \`--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 \`selectDataAttributes\` and \`selectCssVariables\` (from \`entasis/select\`) list each name with its meaning.
 
 ## Accessibility
 
@@ -81,6 +148,19 @@ ARIA 1.2 select-only combobox pattern: the trigger is a \`role="combobox"\` butt
 trigger while \`aria-activedescendant\` tracks the highlighted \`role="option"\` (virtual focus).
 The selected option shows a check indicator and \`aria-selected\`.
 
+The scrolling viewport is the listbox (\`role="listbox"\`, \`tabindex="-1"\`), so the list scrolls
+inside the element that owns the options and no extra scroll group or tab stop appears when it
+overflows. The listbox owns only options and \`role="group"\` sets: bare options sit directly under
+it, a group exists only for a labelled set. Group separators are \`role="presentation"\`, group
+labels are \`aria-hidden\` (each group is named through \`aria-label\`), and the scrollbars are
+\`aria-hidden\` and sit outside the listbox. \`multiple\` adds \`aria-multiselectable\`.
+
+The trigger is the only tab stop; the label focuses it without opening the list. Touch
+screen readers move focus onto options instead of using the virtual cursor, so focus entering the
+panel keeps the list open (it closes when focus leaves both the trigger and the panel), Escape on a
+focused option closes it and returns focus to the trigger, and a visually hidden "Close" button at
+the end of the panel gives users with no Escape key a way out.
+
 The trigger always has an accessible name: \`label\` names it through the Field label (a string
 label as a \`<label for>\`, a snippet through \`aria-labelledby\`), and without one the trigger
 falls back to \`placeholder\`, then to the catalog's "Select an option". Pass \`label\` whenever
@@ -89,9 +169,13 @@ rather than repeating the placeholder.
 
 ## Notes
 
-- Selection re-focuses the trigger (matches native select behavior)
-- Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land
-- The list scrolls (ScrollArea) beyond the viewport when item-aligned, beyond ~240px as a dropdown; the highlight scrolls into view on keyboard nav
+- Selection re-focuses the trigger (matches native select behavior); with \`multiple\` the list stays open and focus stays on the trigger
+- Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land. A list opened from outside (\`open\`, \`defaultOpen\`) moves focus to the trigger, so Escape, the arrow keys and clicking away work the same, and it is measured afresh each time it opens
+- A \`<label for>\` pointing at \`id\` names the trigger and focuses it on click
+- The list scrolls (ScrollArea) beyond the viewport when item-aligned, beyond 240px as a dropdown (less when there is less room beside the trigger: the dropdown list is capped by the Popover's \`--available-height\`, so it never runs under an on-screen keyboard or over its trigger); the highlight scrolls into view on keyboard nav
+- While the dropdown is open, the input container carries \`data-popup-side\` (\`bottom\`, \`top\`, or \`none\` when item-aligned) and the panel \`data-side\`, so a theme can flatten the corner where they meet
+- The trigger carries \`data-placeholder\` while nothing is selected and \`data-readonly\` while read-only
+- Option rows are lean: a titled row with a check, using MenuOption's theme, and each option's id comes from a map, so a list of a thousand options opens without a search per row. Option ids are numbered in the order they are first needed, so values that would collide once sanitised (\`a.b\`, \`a_b\`) never share an id
 - The panel covers the trigger while open, so clicking outside (not the trigger) closes it, as with a native select
 
 ## State contract
@@ -99,5 +183,6 @@ rather than repeating the placeholder.
 - **value**: current bindable editable value.
 - **defaultValue**: initial value used only when \`value\` is omitted.
 - **onValueChange**: called with the new value when the component changes it.
+- **open**: bindable disclosure state; **defaultOpen** initial state; **onOpenChange** reports every user-driven change before it happens and may cancel it; **onAfterOpen** / **onAfterClose** fire once per open and close.
 
 `;

package/dist/components/Form/Select/select.props.d.ts

@@ -1,9 +1,11 @@
 import type { Density } from '../../../types/theme.js';
 import type { Messages } from '../../../i18n/en.js';
+import type { OpenChangeHandler } from '../../../utils/openChange.js';
 import type { InputProps } from '../Field/field.js';
+import type { FieldValidatorResult } from '../Field/field.state.svelte.js';
 import type { SelectThemeProps } from './select.theme.js';
-import type { HTMLButtonAttributes } from 'svelte/elements';
-export type SelectTriggerAttributes = Omit<HTMLButtonAttributes, 'aria-activedescendant' | 'aria-controls' | 'aria-expanded' | 'aria-haspopup' | 'aria-required' | 'class' | 'disabled' | 'id' | 'role' | 'type'>;
+import type { HTMLButtonAttributes, HTMLInputAttributes } from 'svelte/elements';
+export type SelectTriggerAttributes = Omit<HTMLButtonAttributes, 'aria-activedescendant' | 'aria-controls' | 'aria-expanded' | 'aria-haspopup' | 'aria-multiselectable' | 'aria-readonly' | 'aria-required' | 'class' | 'disabled' | 'id' | 'role' | 'type'>;
 export type SelectOption = {
     /** Option value submitted when this item is chosen. */
     value: string;
@@ -16,15 +18,22 @@ export type SelectOptionGroup = {
     /** Optional group label rendered above the group's options. */
     label?: string;
     /** The options of the group. */
-    items: SelectOption[];
+    items: readonly SelectOption[];
 };
-/** Flat options and `{ label, items }` groups can be mixed freely. */
-export type SelectItems = (SelectOption | SelectOptionGroup)[];
-export type SelectProps = InputProps<'select'> & {
+/**
+ * Flat options and `{ label, items }` groups can be mixed freely. Readonly arrays are accepted,
+ * so `as const` data type-checks.
+ */
+export type SelectItems = readonly (SelectOption | SelectOptionGroup)[];
+/** Props shared by the single and the multiple Select. */
+type SelectSharedProps = {
     /** Text shown in the trigger when no value is selected. */
     placeholder?: string;
-    /** Theme overrides for the select trigger, dropdown, options, and field container. */
-    theme?: SelectThemeProps & InputProps<'select'>['theme'];
+    /**
+     * Id of the trigger button, which an external `<label for>` can target. Defaults to a
+     * generated id.
+     */
+    id?: string;
     /** Items to display — flat `{ value, label }` entries and/or `{ label, items }` groups. */
     items?: SelectItems;
     /**
@@ -37,13 +46,81 @@ export type SelectProps = InputProps<'select'> & {
     /**
      * Open over the trigger with the selected option (or the first, when nothing is selected) on
      * the value, its text lined up with the value's, like a native select. A list taller than the
-     * viewport is capped and pre-scrolled to keep the option there. `false` opens a dropdown below
-     * the trigger instead.
+     * viewport is capped and pre-scrolled to keep the option there, and a `max-height` the theme
+     * puts on the list caps it further. Only mouse and keyboard opens align: a list opened by
+     * touch is a dropdown below the trigger. `false` opens a dropdown below the trigger always.
      * @default true
      */
     alignItemWithTrigger?: boolean;
+    /**
+     * Adds a button that clears the selection, shown while something is selected and the Select
+     * is neither disabled nor read-only. Clearing sets a single Select to `null` and a multiple
+     * Select to `[]`, then returns focus to the trigger.
+     * @default false
+     */
+    clearable?: boolean;
+    /**
+     * Autofill token, such as `country` or `address-level1`. The Select then renders a visually
+     * hidden text input the browser can autofill; the filled text selects the option whose value
+     * matches, else whose label matches (ignoring case and accents). Autofill does not open the
+     * list and is ignored while disabled or read-only.
+     */
+    autocomplete?: HTMLInputAttributes['autocomplete'];
     /** Native attributes applied to the combobox trigger button. */
     triggerAttrs?: SelectTriggerAttributes;
     /** Per-instance i18n overrides merged over the global catalog. */
     i18n?: Partial<Messages>;
+    /** Controls whether the list is open; bindable for two-way control. */
+    open?: boolean;
+    /** Initial open state when `open` is not provided. */
+    defaultOpen?: boolean;
+    /**
+     * Called before the list opens or closes, with the requested state and the change details:
+     * `reason` (`'trigger-press'`, `'list-navigation'`, `'item-press'`, `'escape-key'`,
+     * `'outside-press'`, `'focus-out'`, `'close-press'`, `'imperative-action'`…), the originating `event`, the
+     * `trigger` element, the `interaction` type and `cancel()`. Calling `details.cancel()` keeps
+     * the list as it is. Inside the callback, `open` still holds the previous state.
+     */
+    onOpenChange?: OpenChangeHandler;
+    /** Called once per open, after the open transition finishes. */
+    onAfterOpen?: () => void;
+    /** Called once per close, after the close transition finishes. */
+    onAfterClose?: () => void;
+};
+/** The value a Select holds: a string or `null`, or a list of strings when `multiple`. */
+export type SelectValue<Multiple extends boolean = false> = Multiple extends true ? readonly string[] | null : string | null;
+/**
+ * Props of Select. The `Multiple` parameter follows the `multiple` prop: a single Select (the
+ * default) holds a string or `null`; `<Select multiple>` holds a list of values in item order
+ * (field type `select-multiple`), stays open while options are toggled, and a native form submits
+ * one hidden input per value under the same `name`.
+ */
+export type SelectProps<Multiple extends boolean = false> = Omit<InputProps<'select'>, 'value' | 'defaultValue' | 'onValueChange' | 'onValidate' | 'theme'> & SelectSharedProps & {
+    /**
+     * Makes the Select hold several values: `value` is an array in item order (`readonly`
+     * arrays are accepted), `onValueChange` receives the new array, and the list stays open
+     * while options are toggled with a click, Enter or Space.
+     * @default false
+     */
+    multiple?: Multiple;
+    /** The selected value, bindable: a string or `null`, or an array when `multiple`. */
+    value?: SelectValue<Multiple>;
+    /** Initial value when `value` is omitted. */
+    defaultValue?: SelectValue<Multiple>;
+    /** Called whenever the selection changes, with the new value (the values in item order when `multiple`). */
+    onValueChange?: (value: Multiple extends true ? string[] | null : string | null) => void;
+    /**
+     * Validates the value; messages or true mark it invalid, false/null/undefined accept it.
+     * It may return a promise, as for every field.
+     */
+    onValidate?: (value: Multiple extends true ? string[] : string) => FieldValidatorResult;
+    /**
+     * With `multiple`: the text the trigger shows for the selected options, which arrive in
+     * item order. The default lists the first two labels followed by `+N` for the rest
+     * (`Apple, Banana +2`).
+     */
+    formatValue?: (options: SelectOption[]) => string;
+    /** Theme overrides for the select trigger, dropdown, options, and field container. */
+    theme?: SelectThemeProps & InputProps<'select'>['theme'];
 };
+export {};

package/dist/components/Form/Select/select.state.svelte.d.ts

@@ -1,54 +1,115 @@
+import { type OpenChangeHandler, type OpenChangeInit } from '../../../utils/openChange.js';
 import type { SelectItems, SelectOption } from './select.props.js';
+type SelectValue = string | readonly string[] | null | undefined;
 interface SelectStateOptions {
     id: string;
     /** Items list — reactive getter bridged from the component props. */
     items: SelectItems | undefined;
-    /** Selected value — reactive getter/setter bridged to the field state. */
-    value: string | null | undefined;
+    /**
+     * Selected value — reactive getter/setter bridged to the field state: a string or `null`, or
+     * the array of values when `multiple`.
+     */
+    value: SelectValue;
+    /** The Select holds a list of values and stays open while options are toggled. */
+    multiple?: boolean;
     disabled: boolean | undefined;
+    /** Browsable but unchangeable: the list opens, nothing is committed. */
+    readOnly?: boolean;
     /** The trigger button — reactive getter bridged to `field.node`, refocused after selection. */
     triggerEl: HTMLElement | null;
     /** Open over the trigger with the selected option on the value, like a native select. */
     alignItemWithTrigger: boolean;
-    /** The trigger's value text, the option list root, and its scrolling viewport. */
+    /** The trigger's value text, the option list root, and its scrolling viewport (the listbox). */
     valueEl: HTMLElement | null;
     listEl: HTMLElement | null;
     viewportEl: HTMLElement | null;
+    /** The panel's content: the listbox and the close button, the elements focus may rest in. */
+    contentEl?: HTMLElement | null;
+    /** Where the open state lives (a bindable prop); the state keeps its own when absent. */
+    openState?: {
+        get: () => boolean;
+        set: (open: boolean) => void;
+    };
+    /** Runs before every open or close and may cancel it. */
+    onOpenChange?: OpenChangeHandler;
 }
 export declare class SelectState {
     #private;
     id: string;
     items: SelectItems | undefined;
-    value: string | null | undefined;
+    value: SelectValue;
+    multiple: boolean | undefined;
     disabled: boolean | undefined;
+    readOnly: boolean | undefined;
     triggerEl: HTMLElement | null;
     alignItemWithTrigger: boolean;
     valueEl: HTMLElement | null;
     listEl: HTMLElement | null;
     viewportEl: HTMLElement | null;
-    isOpen: boolean;
+    contentEl: HTMLElement | null | undefined;
+    openState: SelectStateOptions['openState'];
+    onOpenChange: OpenChangeHandler | undefined;
     listboxId: string;
+    get isOpen(): boolean;
+    set isOpen(open: boolean);
+    /**
+     * The list is a dropdown below the trigger rather than item-aligned: the prop says so, or a
+     * finger opened it (the alignment is for mouse and keyboard).
+     */
+    get dropdown(): boolean;
     /** All options, flattened across groups — render order. */
     flatOptions: SelectOption[];
     /** Options as rendered: consecutive bare options bundled into one unlabeled group. */
     renderGroups: {
         label?: string;
-        items: SelectOption[];
+        items: readonly SelectOption[];
     }[];
-    selectedOption: SelectOption | null;
+    /** The enabled values in render order: what the highlight and the typeahead move over. */
+    enabledValues: string[];
+    /** The selected values, in the order the value holds them. */
+    selectedValues: string[];
+    /** The selected values as a set, so a row asks whether it is selected in constant time. */
+    selectedSet: Set<string>;
+    /** The selected options in render order (the value of a single Select, at most one). */
+    selectedOptions: SelectOption[];
+    /** The first selected option in render order: what the trigger shows for a single Select. */
+    selectedOption: SelectOption;
+    /**
+     * The option the list opens on: the first enabled selected one in render order, found in one
+     * pass over the options (a Set lookup per option, never a search per selected value).
+     */
+    anchorOption: SelectOption | undefined;
     /** Keyboard navigation: value-driven virtual focus — DOM focus stays on the trigger. */
     nav: {
         readonly highlighted: string | undefined;
+        readonly highlightDetails: import("../../../utils/useListNavigation.svelte.js").HighlightDetails;
         readonly activeDescendant: string | undefined;
-        setHighlighted: (value: string | undefined) => void;
-        highlight: (value: string | undefined) => void;
-        move: (delta: number) => void;
-        first: () => void;
-        last: () => void;
+        optionId: (value: string) => string | undefined;
+        typeahead: {
+            readonly isTyping: boolean;
+            reset: () => void;
+        } | null;
+        setHighlighted: (value: string | undefined, details?: import("../../../utils/useListNavigation.svelte.js").HighlightDetails) => void;
+        pointerHighlight: (value: string | undefined, event?: MouseEvent | PointerEvent) => boolean;
+        highlight: (value: string | undefined, details?: import("../../../utils/useListNavigation.svelte.js").HighlightDetails) => void;
+        move: (delta: number, details?: import("../../../utils/useListNavigation.svelte.js").HighlightDetails) => void;
+        first: (details?: import("../../../utils/useListNavigation.svelte.js").HighlightDetails) => void;
+        last: (details?: import("../../../utils/useListNavigation.svelte.js").HighlightDetails) => void;
+        reanchor: () => void;
+        scrollToHighlighted: () => void;
         onKeydown: (event: KeyboardEvent) => void;
     };
     constructor(options: SelectStateOptions);
+    /**
+     * DOM id of an option. Each value gets the next number the first time it is asked for, so
+     * values that would collide once sanitised ('a.b', 'a_b') never share an id, and a lookup costs
+     * the same however long the list is.
+     */
     optionId: (value: string) => string;
+    /** Whether `value` is selected. */
+    isSelected: (value: string) => boolean;
+    /** Whether a node is the trigger or inside the panel: focus there keeps the list open. */
+    contains: (node: EventTarget | null) => boolean;
     /**
      * Popover `positionPanel`: places the open panel over the trigger with the selected option (or
      * the first one) on the value, and sizes and scrolls the list to keep it there. `null` falls
@@ -62,12 +123,42 @@ export declare class SelectState {
         y: number;
         minWidth: number;
     } | null;
-    open: () => void;
-    close: () => void;
-    toggle: () => void;
+    /**
+     * Opens or closes the list. `onOpenChange` runs first and may cancel; returns whether the
+     * change went through (or was already the state).
+     */
+    setOpen: (next: boolean, init?: OpenChangeInit) => boolean;
+    open: (init?: OpenChangeInit) => boolean;
+    close: (init?: OpenChangeInit) => boolean;
+    toggle: (init?: OpenChangeInit) => boolean;
+    /**
+     * Chooses an option: a single Select takes it, closes and refocuses the trigger; a multiple
+     * Select toggles it and stays open. A read-only Select commits nothing.
+     */
+    activate: (value: string, event?: Event) => void;
+    /** @deprecated Use `activate`. */
     selectValue: (value: string) => void;
-    /** Keydown handler for the trigger — closed: open on ArrowUp/Down/Enter/Space; open:
-     *  Escape/Tab close, Enter/Space select, arrows/Home/End delegate to the navigation hook. */
+    /** Empties the selection: `null` for a single Select, `[]` for a multiple one. */
+    clear: () => void;
+    /**
+     * A label elsewhere on the page was clicked: the browser forwards the click to the trigger, which
+     * should take focus, as a label focuses a native select, rather than toggle the list.
+     */
+    noteLabelClick: () => void;
+    /** Whether the click now arriving at the trigger is a label's: consumed once. */
+    consumeLabelClick: () => boolean;
+    /** A press on the trigger: remembers the pointer type so a touch open can be told from a mouse one. */
+    onTriggerPointerDown: (event: PointerEvent) => void;
+    /** Focus left the trigger: the list closes, unless focus moved into the panel (a screen reader's cursor). */
+    onTriggerBlur: (event: FocusEvent) => void;
+    /** Focus left the panel: the list closes unless it went back to the trigger or stayed inside. */
+    onPanelFocusOut: (event: FocusEvent) => void;
+    /** Keys while focus rests in the panel (a screen reader moved it onto an option). */
+    onPanelKeydown: (event: KeyboardEvent) => void;
+    /** The visually hidden close button, for touch screen-reader users with no Escape key. */
+    onCloseButton: (event: MouseEvent) => void;
+    /** Keydown handler for the trigger — closed: open on ArrowUp/Down/Enter/Space and type to pick;
+     *  open: Escape/Tab close, Enter/Space choose, arrows/Home/End/typing move the highlight. */
     onTriggerKeydown: (event: KeyboardEvent) => void;
 }
 export {};