entasis 0.11.0 → 0.12.0

package/dist/components/Command/Command.svelte

@@ -10,6 +10,8 @@
 	import { magnifyingGlassIcon } from '../Icons/magnifyingGlass.js';
 	import { useDefaultColor } from '../Theme/theme.state.svelte.js';
 	import { useI18n } from '../../i18n/context.svelte.js';
+	import { useLiveAnnouncer } from '../../utils/useLiveAnnouncer.svelte.js';
+	import { untrack } from 'svelte';
 
 	let {
 		items,
@@ -30,6 +32,9 @@
 		showInput = true,
 		shouldFilter = true,
 		filter,
+		limit,
+		autoHighlight,
+		loop,
 		onSelect,
 		onHighlightChange,
 		empty,
@@ -65,9 +70,13 @@
 	);
 
 	const id = $props.id();
+	const t = $derived(useI18n());
 
 	const command = new CommandState<Value>({
 		id,
+		get locale() {
+			return t.locale;
+		},
 		get items() {
 			return items;
 		},
@@ -104,6 +113,15 @@
 		get filter() {
 			return filter;
 		},
+		get limit() {
+			return limit;
+		},
+		get autoHighlight() {
+			return autoHighlight;
+		},
+		get loop() {
+			return loop;
+		},
 		get onOpenChange() {
 			return onOpenChange;
 		},
@@ -123,12 +141,39 @@
 
 	const classes = $derived(useCommandTheme(theme));
 	const resolvedColor = $derived(useDefaultColor());
-	const t = $derived(useI18n());
 	const resolvedTitle = $derived(title ?? t.commandPalette);
 	const resolvedPlaceholder = $derived(placeholder ?? t.commandPlaceholder);
 	const resolvedEmpty = $derived(empty ?? t.noResults);
+	const resolvedEmptyText = $derived(typeof empty === 'string' ? empty : t.noResults);
+
+	// A Button's `onclick={open}` hands its click event over: the change is then a trigger press.
+	const slotPayload = {
+		open: (event?: Event) => command.open(event ? { reason: 'trigger-press', event } : undefined),
+		close: (event?: Event) => command.close(event ? { reason: 'close-press', event } : undefined)
+	};
 
-	const slotPayload = { open: () => command.open(), close: () => command.close() };
+	// Result counts and the empty state reach screen readers through one persistent region,
+	// announced after typing settles (a region that mounts already filled is skipped).
+	const announcer = useLiveAnnouncer(id, 'live');
+	const resultCount = $derived(
+		command.visibleGroups.reduce((count, group) => count + group.items.length, 0)
+	);
+	$effect(() => {
+		const searching = searchState.value.trim() !== '';
+		const message = command.isEmpty
+			? resolvedEmptyText
+			: searching
+				? t.resultsCount(resultCount)
+				: '';
+		return untrack(() => {
+			if (!message) {
+				announcer.reset();
+				return;
+			}
+			const timer = setTimeout(() => announcer.announce(message), 250);
+			return () => clearTimeout(timer);
+		});
+	});
 
 	// Dialog mode: the content mounts on each open and the Dialog does no focus management of
 	// its own, so grab focus for the search input once the mount settles ({@attach} on the input).
@@ -157,6 +202,7 @@
 		{size}
 		{density}
 		title={item ? undefined : it.label}
+		description={item || !it.description ? undefined : it.description}
 		prefix={item ? undefined : it.icon}
 		suffix={item || !it.shortcut ? undefined : shortcut}
 		children={item ? customRow : undefined}
@@ -169,8 +215,8 @@
 			id: command.optionId(it.value),
 			'data-value': it.value,
 			tabindex: -1,
-			onpointermove: () => {
-				if (!it.disabled) command.setHighlighted(it.value);
+			onpointermove: (event: PointerEvent) => {
+				if (!it.disabled) command.pointerHighlight(it.value, event);
 			}
 		}}
 	/>
@@ -188,7 +234,7 @@
 						type="text"
 						role="combobox"
 						aria-autocomplete="list"
-						aria-expanded="true"
+						aria-expanded={!command.isEmpty}
 						aria-controls={command.listId}
 						aria-activedescendant={command.highlighted !== undefined
 							? command.optionId(command.highlighted)
@@ -207,17 +253,12 @@
 		{/if}
 
 		<!-- The empty/no-results message lives OUTSIDE the listbox: a listbox may only own
-		     `option`/`group` nodes (aria-required-children), and a status message is not either of
-		     those. `role="status"` also announces it politely when filtering empties the list.
+		     `option`/`group` nodes (aria-required-children). The live region below announces it.
 		     It takes the list's `flex-1` so the box keeps the exact same layout as a filled list. -->
 		{#if command.isEmpty}
-			<Slot
-				render={resolvedEmpty}
-				class="flex-1 {classes.empty({ size })}"
-				attrs={{ role: 'status' }}
-				payload={slotPayload}
-			/>
+			<Slot render={resolvedEmpty} class="flex-1 {classes.empty({ size })}" payload={slotPayload} />
 		{/if}
+		<span class="sr-only" {...announcer.regionAttrs}>{announcer.message}</span>
 
 		<!-- Kept mounted while empty (hidden) so `aria-controls`/`aria-activedescendant` ids on the
 		     combobox input always resolve; `hidden` keeps it out of the flex layout. -->
@@ -269,7 +310,8 @@
 
 {#if dialog}
 	<Dialog
-		bind:open={() => openState.value, command.setOpen}
+		open={openState.value}
+		onOpenChange={(next, details) => command.setOpen(next, details)}
 		type="modal"
 		title={resolvedTitle}
 		theme={commandDialogTheme}

package/dist/components/Command/command.mcp.d.ts

@@ -1 +1 @@
-export declare const commandDescription = "\n# Command Component\n\nA command palette: a searchable, keyboard-navigable list of grouped commands. Renders inline by\ndefault, or inside a modal Dialog (\u2318K style) with `dialog`.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Command } from 'entasis/command';\n\timport { calendarIcon } from 'entasis/icons/calendar';\n\n\tconst items = [\n\t\t{\n\t\t\theading: 'Suggestions',\n\t\t\titems: [\n\t\t\t\t{ value: 'calendar', label: 'Calendar', icon: calendarIcon },\n\t\t\t\t{ value: 'search-emoji', label: 'Search Emoji' },\n\t\t\t\t{ value: 'calculator', label: 'Calculator', disabled: true }\n\t\t\t]\n\t\t},\n\t\t{\n\t\t\theading: 'Settings',\n\t\t\titems: [\n\t\t\t\t{ value: 'profile', label: 'Profile', shortcut: '\u2318P' },\n\t\t\t\t{ value: 'settings', label: 'Settings', shortcut: '\u2318S' }\n\t\t\t]\n\t\t}\n\t];\n</script>\n\n<Command {items} onSelect={(value) => console.log(value)} />\n```\n\n## Dialog Mode (\u2318K palette)\n\n```svelte\n<Command dialog shortcut=\"k\" {items} onSelect={run}>\n\t{#snippet trigger({ open })}\n\t\t<Button variant=\"outline\" onclick={open}>Search... \u2318K</Button>\n\t{/snippet}\n\t{#snippet footer({ close })}\n\t\t<div class=\"border-neutral-muted text-neutral/70 border-t px-3 py-2 text-xs\">\n\t\t\t\u21B5 Select \u00B7 Esc Close\n\t\t</div>\n\t{/snippet}\n</Command>\n```\n\n## Props\n\n### Core Props\n- **items**: CommandGroup[] (required)\n  - `CommandGroup`: `{ heading?: string; items: CommandItem[]; class?: string }`\n  - `CommandItem`: `{ value: string; label: string; icon?: Slot; shortcut?: string; keywords?: string[]; disabled?: boolean; href?: string; onSelect?: (value) => void; class?: string }`\n  - Items with `href` render as `<a>` and navigate on click/Enter.\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Typography and spacing scale.\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the option rows (paddings, gaps, min-height).\n\n### Dialog Mode Props\n- **dialog**: boolean (default: false) - Render inside a modal Dialog instead of inline.\n- **open**: boolean (bindable, default: false) - Dialog open state.\n- **defaultOpen**: boolean (default: false) - Initial dialog state when open is omitted.\n- **onOpenChange**: (open: boolean) => void - Fires once after a component-owned open state change.\n- **shortcut**: string | false (default: false) - \u2318/Ctrl + key toggles the dialog (e.g. 'k').\n- **closeOnSelect**: boolean (default: true) - Close the dialog when an item is selected.\n\n### Selection Props\n- **value**: string | null (bindable, default: null) - Value of the selected command.\n- **defaultValue**: string | null (default: null) - Initial selected value when value is omitted.\n- **onValueChange**: (value: string | null) => void - Fires once when the selected value changes.\n  Selecting the same command again is silent; use onSelect for every activation.\n\n### Search / Filtering Props\n- **search**: string (bindable, default: '') - Search query.\n- **defaultSearch**: string (default: '') - Initial query when search is omitted.\n- **onSearchChange**: (search: string) => void - Fires once when the query changes.\n- **placeholder**: string (default: 'Type a command or search...')\n- **showInput**: boolean (default: true) - Render the search input row.\n- **shouldFilter**: boolean (default: true) - Filter internally; set false to filter externally.\n- **filter**: (item, search) => boolean - Custom match predicate (defaults to case-insensitive\n  substring match on label + keywords + value).\n\n### Event Props\n- **onSelect**: (value: string) => void - Activation callback: fires for every selected item (after the item's own onSelect), including a repeat selection of the already-selected command.\n- Callback-naming decision: Command owns a selected-value state, so the state change keeps the\n  `value`/`defaultValue`/`onValueChange` trio and `onSelect` stays the pick event \u2014 the\n  `onSelect` name is reserved for \"the user picked this item\", never for a value change.\n- **onHighlightChange**: (value: string | undefined) => void - Fires when the highlighted option moves.\n\n### Content Props (Slots)\n- **empty**: Slot (default: 'No results found.') - Empty-state content.\n- **item**: Snippet<[CommandItem]> - Custom row renderer, replaces icon/label/shortcut layout.\n- **trigger**: Slot<{ open, close }> - Dialog trigger; call `open()` on click. Dialog mode only.\n- **footer**: Slot<{ open, close }> - Bar rendered below the list (e.g. shortcut hints).\n\n### Advanced Props\n- **theme**: CommandThemeProps - Overrides for parts: command, inputWrapper, inputGroup, inputIcon,\n  input, list, empty, group, groupHeading, separator, item, shortcut.\n- **class**: string - Classes for the palette root.\n\n## Keyboard\n\n- **ArrowDown / ArrowUp**: move the highlight, wrapping around both ends.\n- **Home / End**: jump to first / last selectable item.\n- **Enter**: select the highlighted item (navigates for href items).\n- **Escape**: closes the dialog (dialog mode).\n- **\u2318/Ctrl + shortcut**: toggles the dialog (dialog mode with `shortcut` set).\n\n## Accessibility\n\n- The input is a `role=\"combobox\"` with `aria-activedescendant` pointing at the highlighted option.\n- The list is a `role=\"listbox\"`; rows are `role=\"option\"` with `aria-selected`/`aria-disabled`.\n- Pointer movement highlights rows; the highlight re-anchors to the first result while typing.\n\n## Notes\n\n- Filtering happens per group; groups with no matching items are hidden and separators stay contiguous.\n- Dialog mode reuses the Dialog component (modal type) with padding stripped and its close button hidden.\n- Disabled items render dimmed and are skipped by keyboard navigation.\n\n## Motion\n\n- In `dialog` mode the palette rides the Dialog's **motion** slot: `commandDialogTheme.motion`\n  drops it in from just above its resting place on `duration: 'fast'`.\n- Retune it with `<Theme components={{ dialog: { motion } }}>` or `setDialogTheme({ motion })`;\n  reduced motion collapses it to 0.\n";
+export declare const commandDescription = "\n# Command Component\n\nA command palette: a searchable, keyboard-navigable list of grouped commands. Renders inline by\ndefault, or inside a modal Dialog (\u2318K style) with `dialog`.\n\n## Basic Usage\n\n```svelte\n<script>\n\timport { Command } from 'entasis/command';\n\timport { calendarIcon } from 'entasis/icons/calendar';\n\n\tconst items = [\n\t\t{\n\t\t\theading: 'Suggestions',\n\t\t\titems: [\n\t\t\t\t{ value: 'calendar', label: 'Calendar', icon: calendarIcon },\n\t\t\t\t{ value: 'search-emoji', label: 'Search Emoji' },\n\t\t\t\t{ value: 'calculator', label: 'Calculator', disabled: true }\n\t\t\t]\n\t\t},\n\t\t{\n\t\t\theading: 'Settings',\n\t\t\titems: [\n\t\t\t\t{ value: 'profile', label: 'Profile', shortcut: '\u2318P' },\n\t\t\t\t{ value: 'settings', label: 'Settings', shortcut: '\u2318S' }\n\t\t\t]\n\t\t}\n\t];\n</script>\n\n<Command {items} onSelect={(value) => console.log(value)} />\n```\n\n## Dialog Mode (\u2318K palette)\n\n```svelte\n<Command dialog shortcut=\"k\" {items} onSelect={run}>\n\t{#snippet trigger({ open })}\n\t\t<Button variant=\"outline\" onclick={open}>Search... \u2318K</Button>\n\t{/snippet}\n\t{#snippet footer({ close })}\n\t\t<div class=\"border-neutral-muted text-neutral/70 border-t px-3 py-2 text-xs\">\n\t\t\t\u21B5 Select \u00B7 Esc Close\n\t\t</div>\n\t{/snippet}\n</Command>\n```\n\n## Props\n\n### Core Props\n- **items**: CommandGroup[] (required)\n  - `CommandGroup`: `{ heading?: string; items: CommandItem[]; class?: string }`\n  - `CommandItem`: `{ value: string; label: string; description?: string; icon?: Slot; shortcut?: string; keywords?: string[]; disabled?: boolean; href?: string; onSelect?: (value) => void; class?: string }`. `description` renders as a second line under the label and is not searched.\n  - Items with `href` render as `<a>` and navigate on click/Enter.\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Typography and spacing scale.\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the option rows (paddings, gaps, min-height).\n\n### Dialog Mode Props\n- **dialog**: boolean (default: false) - Render inside a modal Dialog instead of inline.\n- **open**: boolean (bindable, default: false) - Dialog open state.\n- **defaultOpen**: boolean (default: false) - Initial dialog state when open is omitted.\n- **onOpenChange**: (open: boolean, details) => void - Runs before a library action opens or closes the dialog. `details` has `reason` ('trigger-press' for the shortcut and the trigger, 'item-press' after a selection, 'escape-key', 'outside-press', 'imperative-action'), `event`, `interaction` and `cancel()`; a cancelled change leaves the dialog as it was. External `open` updates are silent.\n- **shortcut**: string | false (default: false) - \u2318/Ctrl + key toggles the dialog (e.g. 'k').\n- **closeOnSelect**: boolean (default: true) - Close the dialog when an item is selected.\n\n### Selection Props\n- **value**: string | null (bindable, default: null) - Value of the selected command.\n- **defaultValue**: string | null (default: null) - Initial selected value when value is omitted.\n- **onValueChange**: (value: string | null) => void - Fires once when the selected value changes.\n  Selecting the same command again is silent; use onSelect for every activation.\n\n### Search / Filtering Props\n- **search**: string (bindable, default: '') - Search query.\n- **defaultSearch**: string (default: '') - Initial query when search is omitted.\n- **onSearchChange**: (search: string) => void - Fires once when the query changes.\n- **placeholder**: string (default: 'Type a command or search...')\n- **showInput**: boolean (default: true) - Render the search input row.\n- **shouldFilter**: boolean (default: true) - Filter internally; set false to filter externally.\n- **limit**: number - Show at most this many items across groups; matching stops once the limit is reached (while `shouldFilter` is on).\n- **autoHighlight**: boolean | 'always' (default: 'always') - `'always'` keeps the first match highlighted, `true` only while a search 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, or stop.\n- **filter**: (item, search) => boolean - Custom match predicate (defaults to a case- and\n  accent-insensitive substring match on label + keywords + value, compared with\n  `Intl.Collator` in the active I18n locale, so \"eclair\" finds \"\u00C9clair\"; in Spanish \"n\" does\n  not find \"\u00F1\", which is a letter of its own there).\n\n### Event Props\n- **onSelect**: (value: string) => void - Activation callback: fires for every selected item (after the item's own onSelect), including a repeat selection of the already-selected command.\n- Callback-naming decision: Command owns a selected-value state, so the state change keeps the\n  `value`/`defaultValue`/`onValueChange` trio and `onSelect` stays the pick event \u2014 the\n  `onSelect` name is reserved for \"the user picked this item\", never for a value change.\n- **onHighlightChange**: (value: string | undefined) => void - Fires when the highlighted option moves.\n\n### Content Props (Slots)\n- **empty**: Slot (default: 'No results found.') - Empty-state content.\n- **item**: Snippet<[CommandItem]> - Custom row renderer, replaces icon/label/shortcut layout.\n- **trigger**: Slot<{ open, close }> - Dialog trigger; call `open()` on click. Dialog mode only.\n- **footer**: Slot<{ open, close }> - Bar rendered below the list (e.g. shortcut hints).\n\n### Advanced Props\n- **theme**: CommandThemeProps - Overrides for parts: command, inputWrapper, inputGroup, inputIcon,\n  input, list, empty, group, groupHeading, separator, item, shortcut.\n- **class**: string - Classes for the palette root.\n\n## Keyboard\n\n- **ArrowDown / ArrowUp**: move the highlight, wrapping around both ends.\n- **Home / End**: jump to first / last selectable item.\n- **Enter**: select the highlighted item (navigates for href items).\n- **Escape**: closes the dialog (dialog mode); `onOpenChange` can cancel it.\n- **\u2318/Ctrl + shortcut**: toggles the dialog (dialog mode with `shortcut` set).\n\n## Accessibility\n\n- The input is a `role=\"combobox\"` with `aria-activedescendant` pointing at the highlighted option; `aria-expanded` follows the results (false while the search matches nothing and the list is hidden).\n- A persistent visually hidden live region (`role=\"status\"`) announces result counts and the empty state after typing settles; the visible empty message is plain text.\n- The list is a `role=\"listbox\"`; rows are `role=\"option\"` with `aria-selected`/`aria-disabled`.\n- Pointer movement highlights rows; the highlight re-anchors to the first result while typing.\n\n## Notes\n\n- Filtering happens per group; groups with no matching items are hidden and separators stay contiguous.\n- Dialog mode reuses the Dialog component (modal type) with padding stripped and its close button hidden.\n- Disabled items render dimmed and are skipped by keyboard navigation.\n\n## Motion\n\n- In `dialog` mode the palette rides the Dialog's **motion** slot: `commandDialogTheme.motion`\n  drops it in from just above its resting place on `duration: 'fast'`.\n- Retune it with `<Theme components={{ dialog: { motion } }}>` or `setDialogTheme({ motion })`;\n  reduced motion collapses it to 0.\n";

package/dist/components/Command/command.mcp.js

@@ -53,7 +53,7 @@ default, or inside a modal Dialog (⌘K style) with \`dialog\`.
 ### Core Props
 - **items**: CommandGroup[] (required)
   - \`CommandGroup\`: \`{ heading?: string; items: CommandItem[]; class?: string }\`
-  - \`CommandItem\`: \`{ value: string; label: string; icon?: Slot; shortcut?: string; keywords?: string[]; disabled?: boolean; href?: string; onSelect?: (value) => void; class?: string }\`
+  - \`CommandItem\`: \`{ value: string; label: string; description?: string; icon?: Slot; shortcut?: string; keywords?: string[]; disabled?: boolean; href?: string; onSelect?: (value) => void; class?: string }\`. \`description\` renders as a second line under the label and is not searched.
   - Items with \`href\` render as \`<a>\` and navigate on click/Enter.
 - **size**: 'small' | 'normal' | 'large' (default: 'normal') - Typography and spacing scale.
 - **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the option rows (paddings, gaps, min-height).
@@ -62,7 +62,7 @@ default, or inside a modal Dialog (⌘K style) with \`dialog\`.
 - **dialog**: boolean (default: false) - Render inside a modal Dialog instead of inline.
 - **open**: boolean (bindable, default: false) - Dialog open state.
 - **defaultOpen**: boolean (default: false) - Initial dialog state when open is omitted.
-- **onOpenChange**: (open: boolean) => void - Fires once after a component-owned open state change.
+- **onOpenChange**: (open: boolean, details) => void - Runs before a library action opens or closes the dialog. \`details\` has \`reason\` ('trigger-press' for the shortcut and the trigger, 'item-press' after a selection, 'escape-key', 'outside-press', 'imperative-action'), \`event\`, \`interaction\` and \`cancel()\`; a cancelled change leaves the dialog as it was. External \`open\` updates are silent.
 - **shortcut**: string | false (default: false) - ⌘/Ctrl + key toggles the dialog (e.g. 'k').
 - **closeOnSelect**: boolean (default: true) - Close the dialog when an item is selected.
 
@@ -79,8 +79,13 @@ default, or inside a modal Dialog (⌘K style) with \`dialog\`.
 - **placeholder**: string (default: 'Type a command or search...')
 - **showInput**: boolean (default: true) - Render the search input row.
 - **shouldFilter**: boolean (default: true) - Filter internally; set false to filter externally.
-- **filter**: (item, search) => boolean - Custom match predicate (defaults to case-insensitive
-  substring match on label + keywords + value).
+- **limit**: number - Show at most this many items across groups; matching stops once the limit is reached (while \`shouldFilter\` is on).
+- **autoHighlight**: boolean | 'always' (default: 'always') - \`'always'\` keeps the first match highlighted, \`true\` only while a search 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, or stop.
+- **filter**: (item, search) => boolean - Custom match predicate (defaults to a case- and
+  accent-insensitive substring match on label + keywords + value, compared with
+  \`Intl.Collator\` in the active I18n locale, so "eclair" finds "Éclair"; in Spanish "n" does
+  not find "ñ", which is a letter of its own there).
 
 ### Event Props
 - **onSelect**: (value: string) => void - Activation callback: fires for every selected item (after the item's own onSelect), including a repeat selection of the already-selected command.
@@ -105,12 +110,13 @@ default, or inside a modal Dialog (⌘K style) with \`dialog\`.
 - **ArrowDown / ArrowUp**: move the highlight, wrapping around both ends.
 - **Home / End**: jump to first / last selectable item.
 - **Enter**: select the highlighted item (navigates for href items).
-- **Escape**: closes the dialog (dialog mode).
+- **Escape**: closes the dialog (dialog mode); \`onOpenChange\` can cancel it.
 - **⌘/Ctrl + shortcut**: toggles the dialog (dialog mode with \`shortcut\` set).
 
 ## Accessibility
 
-- The input is a \`role="combobox"\` with \`aria-activedescendant\` pointing at the highlighted option.
+- The input is a \`role="combobox"\` with \`aria-activedescendant\` pointing at the highlighted option; \`aria-expanded\` follows the results (false while the search matches nothing and the list is hidden).
+- A persistent visually hidden live region (\`role="status"\`) announces result counts and the empty state after typing settles; the visible empty message is plain text.
 - The list is a \`role="listbox"\`; rows are \`role="option"\` with \`aria-selected\`/\`aria-disabled\`.
 - Pointer movement highlights rows; the highlight re-anchors to the first result while typing.
 

package/dist/components/Command/command.props.d.ts

@@ -3,6 +3,8 @@ import type { Density, Sizes } from '../../types/index.js';
 import type { Slot, WithSlot } from '../Slot/slot.js';
 import type { WithAttachments } from '../../types/props.js';
 import type { CommandThemeProps } from './command.theme.js';
+import type { OpenChangeHandler } from '../../utils/openChange.js';
+import type { ListLoop } from '../../utils/useListNavigation.svelte.js';
 /** A selectable command. `value` is the filter key + `onSelect` payload; `label` is the visible
  *  (and searchable) text. For rich rows (avatars, etc.) pass an `item` snippet to `<Command>`. */
 export type CommandItem<Value extends string = string> = {
@@ -10,6 +12,8 @@ export type CommandItem<Value extends string = string> = {
     value: Value;
     /** Visible label. Also matched against the search query (alongside `value`/`keywords`). */
     label: string;
+    /** Secondary line under the label (a command's summary, a file's path). Not searched. */
+    description?: string;
     /** Leading icon — a string or a snippet (typically an icon snippet from `$lib/components/Icons`). */
     icon?: Slot;
     /** Trailing keybind hint, e.g. `⌘K`. */
@@ -36,10 +40,13 @@ export type CommandGroup<Value extends string = string> = {
 };
 /** Payload passed to the `trigger`, `footer`, and `empty` slots. */
 export type CommandSlotPayload = {
-    /** Opens the palette dialog (dialog mode only). */
-    open: () => void;
+    /**
+     * Opens the palette dialog (dialog mode only). Pass it straight to `onclick`: the click is
+     * reported as the change's event, with the reason `'trigger-press'`.
+     */
+    open: (event?: Event) => void;
     /** Closes the palette dialog (dialog mode only). */
-    close: () => void;
+    close: (event?: Event) => void;
 };
 export type CommandProps<Value extends string = string> = WithAttachments<WithSlot<{
     /**
@@ -61,9 +68,14 @@ export type CommandProps<Value extends string = string> = WithAttachments<WithSl
     /** Initial dialog open state when `open` is omitted. */
     defaultOpen?: boolean;
     /**
-     * Fires once after a library action changes the dialog state. External updates are silent.
+     * Called before a library action opens or closes the dialog, with the requested state and
+     * the change details: `reason` (`'trigger-press'` for the shortcut and the trigger,
+     * `'item-press'` after a selection, `'escape-key'`, `'outside-press'`,
+     * `'imperative-action'`…), the originating `event`, the `interaction` type and `cancel()`.
+     * Calling `details.cancel()` keeps the dialog as it is. External `open` updates are silent.
+     * Dialog mode only.
      */
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: OpenChangeHandler;
     /**
      * ⌘/Ctrl + this key toggles the dialog (e.g. `'k'`). `false` disables. Dialog mode only.
      */
@@ -110,9 +122,30 @@ export type CommandProps<Value extends string = string> = WithAttachments<WithSl
      */
     shouldFilter?: boolean;
     /**
-     * Custom match predicate. Defaults to a case-insensitive substring match on `label` + `keywords` + `value`.
+     * Custom match predicate. Defaults to a case- and accent-insensitive substring match on
+     * `label` + `keywords` + `value`, compared with `Intl.Collator` in the active I18n locale,
+     * so "eclair" finds "Éclair".
      */
     filter?: (item: CommandItem<Value>, search: string) => boolean;
+    /**
+     * Shows at most this many items (across groups). Matching stops once the limit is reached,
+     * so the rest of a long list is never compared. Applies while `shouldFilter` is on.
+     */
+    limit?: number;
+    /**
+     * Which item is highlighted without keyboard input. `'always'` (default) keeps the first
+     * match highlighted; `true` does so only while a search is typed; `false` highlights
+     * nothing until an arrow key or the pointer moves it, so Enter does nothing until then.
+     * @default 'always'
+     */
+    autoHighlight?: boolean | 'always';
+    /**
+     * What moving past either end of the list does: `'wrap'` continues at the other end,
+     * `'input'` lands on no highlight first (focus stays in the input) and wraps from there,
+     * `false` stops at the end.
+     * @default 'wrap'
+     */
+    loop?: ListLoop;
     /**
      * Activation callback: fires for every selected item, after the item's own
      * `onSelect`, including when the same item is selected again.

package/dist/components/Command/command.state.svelte.d.ts

@@ -1,18 +1,24 @@
 import type { Attachment } from 'svelte/attachments';
 import type { CommandGroup, CommandItem, CommandProps } from './command.props.js';
-type CommandOptions<Value extends string = string> = Pick<CommandProps<Value>, 'items' | 'dialog' | 'shortcut' | 'closeOnSelect' | 'shouldFilter' | 'filter' | 'onSelect' | 'onHighlightChange' | 'onOpenChange' | 'onValueChange' | 'onSearchChange'> & {
+import { type OpenChangeDetails, type OpenChangeInit } from '../../utils/openChange.js';
+type CommandOptions<Value extends string = string> = Pick<CommandProps<Value>, 'items' | 'dialog' | 'shortcut' | 'closeOnSelect' | 'shouldFilter' | 'filter' | 'limit' | 'autoHighlight' | 'loop' | 'onSelect' | 'onHighlightChange' | 'onOpenChange' | 'onValueChange' | 'onSearchChange'> & {
     id: string;
     isOpen: boolean;
     /** Live search query. */
     search: string;
     /** Value of the selected command, or null when nothing has been selected. */
     value: Value | null;
+    /** Locale the default filter compares text in: the active I18n locale. */
+    locale?: string;
 };
 declare const BoundCommandOptions: new <Options extends object>(options: Options) => Options;
 export declare class CommandState<Value extends string = string> extends BoundCommandOptions<CommandOptions<Value>> {
     private triggerElement;
     listId: string;
-    /** Groups whose items match the current search query (or all groups when filtering is off). */
+    /**
+     * Groups whose items match the current search query (or all groups when filtering is off),
+     * cut off after `limit` items.
+     */
     filteredGroups: CommandGroup<Value>[];
     /** Groups that actually render — those with at least one (possibly disabled) item. Filtering
      *  here keeps separators contiguous (no orphan separator before the first visible group when an
@@ -24,22 +30,41 @@ export declare class CommandState<Value extends string = string> extends BoundCo
     /** Keyboard navigation: value-driven virtual focus (see useListNavigation). */
     nav: {
         readonly highlighted: Value | undefined;
+        readonly highlightDetails: import("../../utils/useListNavigation.svelte.js").HighlightDetails;
         readonly activeDescendant: string | undefined;
-        setHighlighted: (value: Value | undefined) => void;
-        highlight: (value: Value | undefined) => void;
-        move: (delta: number) => void;
-        first: () => void;
-        last: () => void;
+        optionId: (value: Value) => string | undefined;
+        typeahead: {
+            readonly isTyping: boolean;
+            reset: () => void;
+        } | null;
+        setHighlighted: (value: Value | undefined, details?: import("../../utils/useListNavigation.svelte.js").HighlightDetails) => void;
+        pointerHighlight: (value: Value | undefined, event?: MouseEvent | PointerEvent) => boolean;
+        highlight: (value: Value | 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;
     };
     /** Value of the currently highlighted (keyboard-active) option. */
     get highlighted(): Value | undefined;
     constructor(options: CommandOptions<Value>);
     trigger: Attachment<HTMLElement>;
+    /** DOM id of a command's option row, unique per value. */
     optionId: (value: string) => string;
+    /**
+     * Case- and accent-insensitive substring match on `label`, `keywords` and `value`, compared in
+     * the active locale.
+     */
     defaultMatch: (item: CommandItem<Value>, query: string) => boolean;
     /** Set the highlight without scrolling — used by pointermove on rows. */
     setHighlighted: (value: Value | undefined) => void;
+    /**
+     * Pointer hover highlight: ignores moves that did not change the pointer position (Safari
+     * fires one when keyboard scrolling slides a row under a resting pointer).
+     */
+    pointerHighlight: (value: Value | undefined, event?: MouseEvent | PointerEvent) => void;
     /** Move the highlight by `delta` selectable items, wrapping around both ends. */
     move: (delta: number) => void;
     select: (item: CommandItem<Value>) => void;
@@ -50,10 +75,14 @@ export declare class CommandState<Value extends string = string> extends BoundCo
     selectHighlighted: () => boolean;
     setValue: (value: Value | null) => void;
     setSearch: (search: string) => void;
-    open: () => void;
-    close: () => void;
-    toggle: () => void;
-    setOpen: (open: boolean) => void;
+    open: (input?: OpenChangeDetails | OpenChangeInit | Event) => void;
+    close: (input?: OpenChangeDetails | OpenChangeInit | Event) => void;
+    toggle: (input?: OpenChangeDetails | OpenChangeInit | Event) => void;
+    /**
+     * Asks to open or close the palette. `onOpenChange(open, details)` runs first and may cancel;
+     * returns `false` when it did.
+     */
+    setOpen: (open: boolean, input?: OpenChangeDetails | OpenChangeInit | Event) => boolean;
     onKeydown: (event: KeyboardEvent) => void;
 }
 export {};

package/dist/components/Command/command.state.svelte.js

@@ -1,6 +1,9 @@
+import { createItemMatcher } from '../../utils/match.js';
 import { createBindableStateClass } from '../../utils/state.svelte.js';
 import { useListNavigation } from '../../utils/useListNavigation.svelte.js';
 import { untrack } from 'svelte';
+import { elementById } from '../../utils/id.js';
+import { requestOpenChange, resolveOpenChangeDetails } from '../../utils/openChange.js';
 // `bind()` copies the option accessors onto the instance; this typed base is what declares
 // them on `this`. A generic class cannot call a mixin factory in its `extends` clause, and
 // merging an interface into the class declaration would be unsafe declaration merging.
@@ -8,15 +11,35 @@ const BoundCommandOptions = createBindableStateClass();
 export class CommandState extends BoundCommandOptions {
     triggerElement = $state(null);
     listId = $derived(`${this.id}-list`);
-    /** Groups whose items match the current search query (or all groups when filtering is off). */
+    /**
+     * Groups whose items match the current search query (or all groups when filtering is off),
+     * cut off after `limit` items.
+     */
     filteredGroups = $derived.by(() => {
         const query = this.search.trim();
-        if (!this.shouldFilter || query === '')
+        const limit = this.shouldFilter ? this.limit : undefined;
+        if (!this.shouldFilter || (query === '' && limit === undefined))
             return this.items;
         const match = this.filter ?? this.defaultMatch;
-        return this.items
-            .map((group) => ({ ...group, items: group.items.filter((item) => match(item, query)) }))
-            .filter((group) => group.items.length > 0);
+        // Matching stops once the limit is reached: the rest of a long list is never compared.
+        let remaining = limit !== undefined && limit >= 0 ? limit : Infinity;
+        const groups = [];
+        for (const group of this.items) {
+            if (remaining <= 0)
+                break;
+            const kept = [];
+            for (const item of group.items) {
+                if (remaining <= 0)
+                    break;
+                if (query !== '' && !match(item, query))
+                    continue;
+                kept.push(item);
+                remaining -= 1;
+            }
+            if (kept.length > 0)
+                groups.push({ ...group, items: kept });
+        }
+        return groups;
     });
     /** Groups that actually render — those with at least one (possibly disabled) item. Filtering
      *  here keeps separators contiguous (no orphan separator before the first visible group when an
@@ -26,12 +49,20 @@ export class CommandState extends BoundCommandOptions {
     navItems = $derived(this.visibleGroups.flatMap((group) => group.items).filter((item) => !item.disabled));
     isEmpty = $derived(this.visibleGroups.length === 0);
     /** Keyboard navigation: value-driven virtual focus (see useListNavigation). */
-    nav = useListNavigation({
-        values: () => this.navItems.map((item) => item.value),
-        optionId: (value) => this.optionId(value),
-        onHighlightChange: (value) => this.onHighlightChange?.(value),
-        onSelect: (value) => this.selectValue(value)
-    });
+    nav = ((state) => useListNavigation({
+        values: () => state.navItems.map((item) => item.value),
+        get autoHighlight() {
+            return state.autoHighlight ?? 'always';
+        },
+        get loop() {
+            return state.loop ?? 'wrap';
+        },
+        query: () => state.search,
+        // Each value gets its own numbered id, so values such as a.b and a_b never collide.
+        idPrefix: `${state.id}-opt`,
+        onHighlightChange: (value) => state.onHighlightChange?.(value),
+        onSelect: (value) => state.selectValue(value)
+    }))(this);
     /** Value of the currently highlighted (keyboard-active) option. */
     get highlighted() {
         return this.nav.highlighted;
@@ -46,7 +77,7 @@ export class CommandState extends BoundCommandOptions {
             const onKeydown = (event) => {
                 if (event.key.toLowerCase() === key && (event.metaKey || event.ctrlKey)) {
                     event.preventDefault();
-                    untrack(() => this.toggle());
+                    untrack(() => this.toggle({ reason: 'trigger-press', event }));
                 }
             };
             window.addEventListener('keydown', onKeydown);
@@ -70,15 +101,24 @@ export class CommandState extends BoundCommandOptions {
             };
         });
     };
-    optionId = (value) => `${this.id}-opt-${value.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
-    defaultMatch = (item, query) => {
-        const haystack = `${item.label} ${item.keywords?.join(' ') ?? ''} ${item.value}`.toLowerCase();
-        return haystack.includes(query.toLowerCase());
-    };
+    /** DOM id of a command's option row, unique per value. */
+    optionId = (value) => this.nav.optionId(value);
+    /**
+     * Case- and accent-insensitive substring match on `label`, `keywords` and `value`, compared in
+     * the active locale.
+     */
+    defaultMatch = $derived(createItemMatcher({ locale: this.locale }));
     /** Set the highlight without scrolling — used by pointermove on rows. */
     setHighlighted = (value) => {
         this.nav.setHighlighted(value);
     };
+    /**
+     * Pointer hover highlight: ignores moves that did not change the pointer position (Safari
+     * fires one when keyboard scrolling slides a row under a resting pointer).
+     */
+    pointerHighlight = (value, event) => {
+        this.nav.pointerHighlight(value, event);
+    };
     /** Move the highlight by `delta` selectable items, wrapping around both ends. */
     move = (delta) => {
         this.nav.move(delta);
@@ -92,7 +132,7 @@ export class CommandState extends BoundCommandOptions {
         item.onSelect?.(item.value);
         this.onSelect?.(item.value);
         if (this.dialog && this.closeOnSelect)
-            this.close();
+            this.close({ reason: 'item-press' });
     };
     /** Select an item by value. Link items are clicked so navigation happens natively
      *  (SvelteKit intercepts the click); their own `onclick` runs `select()`. */
@@ -101,7 +141,7 @@ export class CommandState extends BoundCommandOptions {
         if (!item)
             return;
         if (item.href)
-            document.getElementById(this.optionId(item.value))?.click();
+            elementById(this.triggerElement, this.optionId(item.value))?.click();
         else
             this.select(item);
     };
@@ -124,20 +164,27 @@ export class CommandState extends BoundCommandOptions {
         this.search = search;
         this.onSearchChange?.(search);
     };
-    open = () => {
-        this.setOpen(true);
+    open = (input) => {
+        this.setOpen(true, input);
     };
-    close = () => {
-        this.setOpen(false);
+    close = (input) => {
+        this.setOpen(false, input);
     };
-    toggle = () => {
-        this.setOpen(!this.isOpen);
+    toggle = (input) => {
+        this.setOpen(!this.isOpen, input);
     };
-    setOpen = (open) => {
+    /**
+     * Asks to open or close the palette. `onOpenChange(open, details)` runs first and may cancel;
+     * returns `false` when it did.
+     */
+    setOpen = (open, input) => {
         if (open === this.isOpen)
-            return;
+            return true;
+        const details = resolveOpenChangeDetails(input, { reason: 'imperative-action' });
+        if (!requestOpenChange(this.onOpenChange, open, details))
+            return false;
         this.isOpen = open;
-        this.onOpenChange?.(open);
+        return true;
     };
     onKeydown = (event) => {
         this.nav.onKeydown(event);

package/dist/components/Command/command.theme.js

@@ -1,4 +1,3 @@
-import { selectedSoft } from '../Theme/theme.recipes.js';
 import { setComponentTheme, useComponentTheme } from '../../utils/cva/index.js';
 import { cva } from '../../utils/cva/index.js';
 // A palette is sized by whatever hosts it — a `max-w-xl` dialog, an 18rem mention popover, an
@@ -117,8 +116,10 @@ const defaultCommandItem = cva({
         },
         highlighted: {
             // The keyboard cursor is a persistent selection, not a hover: it paints the shared soft
-            // selected recipe in the current role, like a sidebar row or a toggle button.
-            true: selectedSoft,
+            // selected fill in the current role, like a sidebar row or a toggle button. The row keeps
+            // its own ink: the neutral muted-readable ink is dimmer than an unhighlighted row in dark
+            // mode, which made the active row look disabled.
+            true: 'bg-selected-muted',
             false: ''
         }
     },