@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/command-menu/command-menu.svelte

@@ -29,12 +29,8 @@
 
   import { createAnchoredOverlay } from '../../_internal/anchored-overlay.svelte.ts';
   import { classNames } from '../../utilities/class-names.ts';
-  import { inDocumentOrder } from '../../utilities/document-order.ts';
-  import {
-    setCommandListContext,
-    type CommandItemRegistrationInput,
-    type CommandListContext,
-  } from '../_internal/command-list-context.ts';
+  import { setCommandListContext } from '../_internal/command-list-context.ts';
+  import { createCommandListState } from '../_internal/create-command-list-state.svelte.ts';
   import { createPortalAttachment } from '../portal/index.ts';
 
   const listboxId = $props.id();
@@ -55,7 +51,6 @@
     class: className,
   }: CommandMenuProps = $props();
 
-  type RegistrationRecord = CommandItemRegistrationInput & { id: string; node: HTMLElement };
   const portalAttachment = createPortalAttachment({
     target: () => document.body,
     inheritAttributes: true,
@@ -64,19 +59,11 @@
 
   let mounted = $state(false);
   let listElement: HTMLElement | undefined = $state();
-  let registrations = $state<RegistrationRecord[]>([]);
-  let activeItemId = $state<string | null>(null);
-  let itemCounter = 0;
-  let registrationsReady = $state(false);
-  let readyCycle = 0;
+  const commandList = createCommandListState(listboxId);
 
-  const enabledIds = $derived.by(() => {
-    return inDocumentOrder(registrations)
-      .filter((registration) => !registration.getDisabled())
-      .map((registration) => registration.id);
-  });
-
-  const showEmpty = $derived(mounted && open && registrationsReady && registrations.length === 0);
+  const showEmpty = $derived(
+    mounted && open && commandList.registrationsReady && commandList.registrations.length === 0,
+  );
   const caretAnchor = $derived.by<VirtualElement | null>(() => {
     const anchorElement = anchor;
     const currentCaretIndex = caretIndex;
@@ -104,76 +91,34 @@
   });
 
   $effect(() => {
-    const ids = enabledIds;
     if (!open) {
-      activeItemId = null;
+      commandList.resetActiveItem();
       return;
     }
-    if (activeItemId !== null && ids.includes(activeItemId)) return;
-    activeItemId = ids[0] ?? null;
   });
 
   $effect(() => {
     void query;
-    registrationsReady = false;
-    const cycle = ++readyCycle;
-    queueMicrotask(() => {
-      if (cycle === readyCycle) registrationsReady = true;
-    });
+    commandList.refreshRegistrationsReady();
   });
 
   $effect(() => {
-    onstatechange?.({ listboxId, activeItemId: open ? activeItemId : null });
+    onstatechange?.({ listboxId, activeItemId: open ? commandList.activeItemId : null });
   });
 
   $effect(() => {
-    if (activeItemId === null) return;
-    document.getElementById(activeItemId)?.scrollIntoView({ block: 'nearest' });
+    commandList.scrollActiveItemIntoView();
   });
 
   function activateItemById(id: string) {
-    const record = registrations.find((registration) => registration.id === id);
-    if (!record || record.getDisabled()) return;
-    // Fire the per-item `onselect` callback first (matching command-palette's
-    // shared-context contract), then the menu-level `onselect` prop. Without the
-    // first call, an item's own onselect is silently dropped on activation.
-    record.getOnselect()();
+    const record = commandList.activateItemById(id);
+    if (!record) return;
+    // The command list activates the item callback first; the menu-level
+    // `onselect` prop then receives the committed value and query.
     onselect?.({ value: record.getValue(), query });
   }
 
-  const context: CommandListContext = {
-    get listboxId() {
-      return listboxId;
-    },
-    get activeItemId() {
-      return activeItemId;
-    },
-    register(input: CommandItemRegistrationInput, node: HTMLElement) {
-      const id = `${listboxId}-item-${++itemCounter}`;
-      registrations = [
-        ...registrations,
-        {
-          id,
-          node,
-          getValue: input.getValue,
-          getOnselect: input.getOnselect,
-          getDisabled: input.getDisabled,
-        },
-      ];
-      return {
-        id,
-        unregister: () => {
-          registrations = registrations.filter((registration) => registration.id !== id);
-        },
-      };
-    },
-    setActiveById(id: string) {
-      activeItemId = id;
-    },
-    activateItemById,
-  };
-
-  setCommandListContext(context);
+  setCommandListContext(commandList.createContext(activateItemById));
 
   function dismiss() {
     if (!open) return;
@@ -183,38 +128,12 @@
 
   function handleKeydown(event: KeyboardEvent) {
     if (!open) return;
-    if (event.isComposing || event.keyCode === 229) return;
-    const ids = enabledIds;
-
-    if (event.key === 'ArrowDown') {
-      if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
-      event.preventDefault();
-      if (ids.length === 0) return;
-      const index = activeItemId === null ? -1 : ids.indexOf(activeItemId);
-      activeItemId = ids[(index + 1) % ids.length] ?? null;
-    } else if (event.key === 'ArrowUp') {
-      if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
-      event.preventDefault();
-      if (ids.length === 0) return;
-      const index = activeItemId === null ? 0 : ids.indexOf(activeItemId);
-      activeItemId = ids[index <= 0 ? ids.length - 1 : index - 1] ?? null;
-    } else if (event.key === 'Home') {
-      if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
-      event.preventDefault();
-      activeItemId = ids[0] ?? null;
-    } else if (event.key === 'End') {
-      if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
-      event.preventDefault();
-      activeItemId = ids[ids.length - 1] ?? null;
-    } else if (event.key === 'Enter' && activeItemId !== null) {
-      event.preventDefault();
-      event.stopPropagation();
-      activateItemById(activeItemId);
-    } else if (event.key === 'Escape') {
-      event.preventDefault();
-      event.stopPropagation();
-      dismiss();
-    }
+    commandList.handleKeydown({
+      event,
+      onEnter: activateItemById,
+      onEscape: dismiss,
+      ignoreModifiedNavigation: true,
+    });
   }
 
   function handleDocumentPointerdown(event: PointerEvent) {

package/src/components/command-palette/README.md

@@ -34,18 +34,18 @@ Command items register with the palette by DOM node, so grouped results can use
 
 <!-- generated:props:start -->
 
-| Prop          | Type       | Required | Default | Description                                                                                                                                                                                                                                         |
-| ------------- | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`   | no       | —       | Class merged onto the palette panel.                                                                                                                                                                                                                |
-| `label`       | `string`   | no       | —       | Accessible name for the dialog, wired via `aria-label`.                                                                                                                                                                                             |
-| `open`        | `boolean`  | yes      | —       | Bindable open state. The component mutates `open = false` on Escape, backdrop click, or any explicit close path, then fires `onclose`.                                                                                                              |
-| `placeholder` | `string`   | no       | —       | Placeholder rendered inside the search input.                                                                                                                                                                                                       |
-| `query`       | `string`   | no       | —       | Bindable search query. Mutated by the input's oninput handler. Exposed to the items snippet so consumers can filter. Note: query is NOT reset on close — consumers who want a fresh query on each open should reset it in their `onclose` callback. |
-| `empty`       | `(opaque)` | no       | —       | Rendered when zero items are registered after filtering. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                 |
-| `footer`      | `(opaque)` | no       | —       | Optional footer, e.g. for keybinding hints. Not part of the listbox. Not expressible in JSON Schema; see the component types for the signature.                                                                                                     |
-| `items`       | `(opaque)` | yes      | —       | Receives the current query so consumers can filter. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                      |
-| `onclose`     | `(opaque)` | no       | —       | Fired after any close path routed through the palette close lifecycle. Not expressible in JSON Schema; see the component types for the signature.                                                                                                   |
-| `triggerRef`  | `(opaque)` | no       | —       | Element to restore focus to on close. Falls back to `captureFocus()`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                    |
+| Prop          | Type       | Required | Default | Description                                                                                                                                                                |
+| ------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`   | no       | —       | Class merged onto the palette panel.                                                                                                                                       |
+| `label`       | `string`   | no       | —       | Accessible name for the dialog, wired via `aria-label`.                                                                                                                    |
+| `open`        | `boolean`  | yes      | —       | Bindable open state. The component mutates `open = false` on Escape, backdrop click, or any explicit close path, then fires `onclose`.                                     |
+| `placeholder` | `string`   | no       | —       | Placeholder rendered inside the search input.                                                                                                                              |
+| `query`       | `string`   | no       | —       | Bindable search query. Mutated by the input's oninput handler. Exposed to the items snippet so consumers can filter. Reset to an empty string each time the palette opens. |
+| `empty`       | `(opaque)` | no       | —       | Rendered when zero items are registered after filtering. Not expressible in JSON Schema; see the component types for the signature.                                        |
+| `footer`      | `(opaque)` | no       | —       | Optional footer, e.g. for keybinding hints. Not part of the listbox. Not expressible in JSON Schema; see the component types for the signature.                            |
+| `items`       | `(opaque)` | yes      | —       | Receives the current query so consumers can filter. Not expressible in JSON Schema; see the component types for the signature.                                             |
+| `onclose`     | `(opaque)` | no       | —       | Fired after any close path routed through the palette close lifecycle. Not expressible in JSON Schema; see the component types for the signature.                          |
+| `triggerRef`  | `(opaque)` | no       | —       | Element to restore focus to on close. Falls back to `captureFocus()`. Not expressible in JSON Schema; see the component types for the signature.                           |
 
 <!-- generated:props:end -->
 

package/src/components/command-palette/command-palette.examples.json

@@ -7,19 +7,19 @@
       "id": "basic",
       "title": "Basic command palette",
       "description": "A minimal palette with three items opened by a button.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { CommandItem } from '@lostgradient/cinder/command-item';\n  import { CommandPalette } from '@lostgradient/cinder/command-palette';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let lastSelected = $state('');\n\n  const commands = [\n    { value: 'new-file', label: 'New file' },\n    { value: 'open-settings', label: 'Open settings' },\n    { value: 'sign-out', label: 'Sign out' },\n  ];\n\n  function select(label: string) {\n    lastSelected = label;\n    open = false;\n  }\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;\">\n  <Button\n    label=\"Open palette\"\n    onclick={(event) => {\n      triggerRef = event.currentTarget as HTMLElement;\n      open = true;\n    }}\n  />\n\n  {#if lastSelected}\n    <p style=\"font-size: 0.875rem; color: var(--cinder-text-muted);\">\n      Selected: <strong>{lastSelected}</strong>\n    </p>\n  {/if}\n</div>\n\n<CommandPalette bind:open label=\"Basic palette\" {triggerRef}>\n  {#snippet items({ query })}\n    {@const filteredCommands = commands.filter((command) =>\n      command.label.toLowerCase().includes(query.toLowerCase()),\n    )}\n    {#each filteredCommands as command (command.value)}\n      <CommandItem value={command.value} onselect={() => select(command.label)}>\n        {command.label}\n      </CommandItem>\n    {/each}\n  {/snippet}\n\n  {#snippet empty()}\n    No commands found.\n  {/snippet}\n</CommandPalette>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { CommandItem } from '@lostgradient/cinder/command-item';\n  import { CommandPalette } from '@lostgradient/cinder/command-palette';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let lastSelected = $state('');\n\n  const commands = [\n    { value: 'new-file', label: 'New file' },\n    { value: 'open-settings', label: 'Open settings' },\n    { value: 'sign-out', label: 'Sign out' },\n  ];\n\n  function select(label: string) {\n    lastSelected = label;\n    open = false;\n  }\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;\">\n  <Button\n    label=\"Open palette\"\n    onclick={(event) => {\n      triggerRef = event.currentTarget as HTMLElement;\n      open = true;\n    }}\n  />\n\n  {#if lastSelected}\n    <p style=\"font-size: 0.875rem; color: var(--cinder-text-muted);\">\n      Selected: <strong>{lastSelected}</strong>\n    </p>\n  {/if}\n</div>\n\n<CommandPalette bind:open label=\"Basic palette\" {triggerRef}>\n  {#snippet items({ query })}\n    {@const filteredCommands = commands.filter((command) =>\n      command.label.toLowerCase().includes(query.toLowerCase()),\n    )}\n    {#each filteredCommands as command (command.value)}\n      <CommandItem\n        value={command.value}\n        accessibleLabel={command.label}\n        onselect={() => select(command.label)}\n      >\n        {command.label}\n      </CommandItem>\n    {/each}\n  {/snippet}\n\n  {#snippet empty()}\n    No commands found.\n  {/snippet}\n</CommandPalette>\n"
     },
     {
       "id": "grouped",
       "title": "Grouped command palette",
       "description": "Command items grouped with named listbox sections.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { CommandItem } from '@lostgradient/cinder/command-item';\n  import { CommandPalette } from '@lostgradient/cinder/command-palette';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let lastSelected = $state('');\n\n  const recentItems = [\n    { id: 'roadmap', label: 'Roadmap' },\n    { id: 'release-notes', label: 'Release notes' },\n  ];\n\n  const actions = [\n    { id: 'new-project', label: 'New project', description: 'Create a workspace project.' },\n    { id: 'invite-teammate', label: 'Invite teammate', description: 'Add a collaborator.' },\n    { id: 'open-settings', label: 'Open settings', description: 'Manage preferences.' },\n  ];\n\n  function select(label: string) {\n    lastSelected = label;\n    open = false;\n  }\n\n  function matchesQuery(label: string, query: string): boolean {\n    return label.toLowerCase().includes(query.toLowerCase());\n  }\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;\">\n  <Button\n    label=\"Open palette\"\n    onclick={(event) => {\n      triggerRef = event.currentTarget as HTMLElement;\n      open = true;\n    }}\n  />\n\n  {#if lastSelected}\n    <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n      Selected: <strong>{lastSelected}</strong>\n    </p>\n  {/if}\n</div>\n\n<CommandPalette bind:open label=\"Grouped command palette\" {triggerRef}>\n  {#snippet items({ query })}\n    {@const filteredRecentItems = recentItems.filter((item) => matchesQuery(item.label, query))}\n    {@const filteredActions = actions.filter((action) => matchesQuery(action.label, query))}\n\n    {#if filteredRecentItems.length > 0}\n      <li role=\"presentation\" class=\"cinder-command-group\">\n        <span class=\"cinder-command-group__label\">Recent files</span>\n        <ul role=\"group\" aria-label=\"Recent files\">\n          {#each filteredRecentItems as item (item.id)}\n            <CommandItem value={item.id} onselect={() => select(item.label)}>\n              {item.label}\n            </CommandItem>\n          {/each}\n        </ul>\n      </li>\n    {/if}\n\n    {#if filteredActions.length > 0}\n      <li role=\"presentation\" class=\"cinder-command-group\">\n        <span class=\"cinder-command-group__label\">Actions</span>\n        <ul role=\"group\" aria-label=\"Actions\">\n          {#each filteredActions as action (action.id)}\n            <CommandItem\n              value={action.id}\n              description={action.description}\n              onselect={() => select(action.label)}\n            >\n              {action.label}\n            </CommandItem>\n          {/each}\n        </ul>\n      </li>\n    {/if}\n  {/snippet}\n\n  {#snippet empty()}\n    No commands found.\n  {/snippet}\n</CommandPalette>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { CommandItem } from '@lostgradient/cinder/command-item';\n  import { CommandPalette } from '@lostgradient/cinder/command-palette';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let lastSelected = $state('');\n\n  const recentItems = [\n    { id: 'roadmap', label: 'Roadmap' },\n    { id: 'release-notes', label: 'Release notes' },\n  ];\n\n  const actions = [\n    { id: 'new-project', label: 'New project', description: 'Create a workspace project.' },\n    { id: 'invite-teammate', label: 'Invite teammate', description: 'Add a collaborator.' },\n    { id: 'open-settings', label: 'Open settings', description: 'Manage preferences.' },\n  ];\n\n  function select(label: string) {\n    lastSelected = label;\n    open = false;\n  }\n\n  function matchesQuery(label: string, query: string): boolean {\n    return label.toLowerCase().includes(query.toLowerCase());\n  }\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;\">\n  <Button\n    label=\"Open palette\"\n    onclick={(event) => {\n      triggerRef = event.currentTarget as HTMLElement;\n      open = true;\n    }}\n  />\n\n  {#if lastSelected}\n    <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n      Selected: <strong>{lastSelected}</strong>\n    </p>\n  {/if}\n</div>\n\n<CommandPalette bind:open label=\"Grouped command palette\" {triggerRef}>\n  {#snippet items({ query })}\n    {@const filteredRecentItems = recentItems.filter((item) => matchesQuery(item.label, query))}\n    {@const filteredActions = actions.filter((action) => matchesQuery(action.label, query))}\n\n    {#if filteredRecentItems.length > 0}\n      <li role=\"presentation\" class=\"cinder-command-group\">\n        <span id=\"recent-files-heading\" class=\"cinder-command-group__label\">Recent files</span>\n        <ul role=\"group\" aria-labelledby=\"recent-files-heading\">\n          {#each filteredRecentItems as item (item.id)}\n            <CommandItem\n              value={item.id}\n              accessibleLabel={item.label}\n              onselect={() => select(item.label)}\n            >\n              {item.label}\n            </CommandItem>\n          {/each}\n        </ul>\n      </li>\n    {/if}\n\n    {#if filteredActions.length > 0}\n      <li role=\"presentation\" class=\"cinder-command-group\">\n        <span id=\"actions-heading\" class=\"cinder-command-group__label\">Actions</span>\n        <ul role=\"group\" aria-labelledby=\"actions-heading\">\n          {#each filteredActions as action (action.id)}\n            <CommandItem\n              value={action.id}\n              description={action.description}\n              accessibleLabel={action.label}\n              onselect={() => select(action.label)}\n            >\n              {action.label}\n            </CommandItem>\n          {/each}\n        </ul>\n      </li>\n    {/if}\n  {/snippet}\n\n  {#snippet empty()}\n    No commands found.\n  {/snippet}\n</CommandPalette>\n"
     },
     {
       "id": "search-recent-actions",
       "title": "Search, recent, and keyed actions",
       "description": "Cmd+K opens the palette. Three sections: filtered search results, recent items, and keyed actions separated by visual group headers.",
-      "code": "<script lang=\"ts\">\n  import { CommandItem } from '@lostgradient/cinder/command-item';\n  import { CommandPalette } from '@lostgradient/cinder/command-palette';\n  // ── State ──────────────────────────────────────────────────────────────\n  let open = $state(false);\n  let query = $state('');\n  let lastSelected = $state('');\n  let triggerRef: HTMLElement | null = $state(null);\n\n  // ── Data ──────────────────────────────────────────────────────────────\n  const allPages = [\n    { id: 'dashboard', label: 'Dashboard', description: 'View product and team metrics.' },\n    { id: 'settings', label: 'Settings', description: 'Manage workspace preferences.' },\n    { id: 'billing', label: 'Billing', description: 'Review invoices and payment methods.' },\n    { id: 'team', label: 'Team members', description: 'Invite or remove collaborators.' },\n    { id: 'api-keys', label: 'API keys', description: 'Create and rotate access tokens.' },\n    { id: 'integrations', label: 'Integrations', description: 'Connect external services.' },\n  ];\n\n  const recentItems = [\n    { id: 'recent-dashboard', label: 'Dashboard' },\n    { id: 'recent-billing', label: 'Billing' },\n  ];\n\n  const actions = [\n    {\n      id: 'action-new-project',\n      label: 'New project',\n      description: 'Create a blank project for a new body of work.',\n      icon: '+',\n      kbd: '⌘N',\n    },\n    {\n      id: 'action-invite',\n      label: 'Invite teammate',\n      description: 'Send an invitation to join this workspace.',\n      icon: '@',\n      kbd: '⌘I',\n    },\n    {\n      id: 'action-sign-out',\n      label: 'Sign out',\n      description: 'End this browser session.',\n      icon: '↪',\n      kbd: '',\n    },\n  ];\n\n  // ── Filtering ──────────────────────────────────────────────────────────\n  const filteredPages = $derived(\n    query ? allPages.filter((p) => p.label.toLowerCase().includes(query.toLowerCase())) : [],\n  );\n\n  const filteredActions = $derived(\n    query ? actions.filter((a) => a.label.toLowerCase().includes(query.toLowerCase())) : actions,\n  );\n\n  function select(label: string) {\n    lastSelected = label;\n    open = false;\n  }\n\n  // ── Cmd+K / Ctrl+K listener ────────────────────────────────────────────\n  function handleGlobalKeydown(event: KeyboardEvent) {\n    if ((event.metaKey || event.ctrlKey) && event.key === 'k') {\n      event.preventDefault();\n      open = true;\n    }\n  }\n</script>\n\n<svelte:window onkeydown={handleGlobalKeydown} />\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;\">\n  <button\n    bind:this={triggerRef}\n    type=\"button\"\n    onclick={() => (open = true)}\n    style=\"\n      display: inline-flex;\n      align-items: center;\n      gap: 0.5rem;\n      padding: 0.5rem 0.75rem;\n      border: 1px solid var(--cinder-border);\n      border-radius: var(--cinder-radius-md);\n      background: var(--cinder-surface);\n      color: var(--cinder-text-muted);\n      font-size: 0.875rem;\n      cursor: pointer;\n    \"\n  >\n    Search…\n    <kbd style=\"font-size: 0.75rem; opacity: 0.7;\">⌘K</kbd>\n  </button>\n\n  {#if lastSelected}\n    <p style=\"font-size: 0.875rem; color: var(--cinder-text-muted);\">\n      Selected: <strong>{lastSelected}</strong>\n    </p>\n  {/if}\n</div>\n\n<CommandPalette bind:open bind:query label=\"Command palette\" {triggerRef}>\n  {#snippet items({ query: paletteQuery })}\n    {@const headerBase =\n      'font-size: 0.6875rem; font-weight: 600; letter-spacing: 0.05em; text-transform: uppercase; color: var(--cinder-text-muted); pointer-events: none;'}\n    {@const headerFirst = 'padding: 0.625rem 1.25rem 0.375rem;'}\n    {@const headerWithDivider =\n      'padding: 0.625rem 1.25rem 0.375rem 1.25rem; padding-block-start: 0.625rem; margin-block-start: 0.25rem; border-block-start: 1px solid var(--cinder-border);'}\n    {@const showPages = filteredPages.length > 0}\n    {@const showRecent = !paletteQuery}\n    {@const showActions = filteredActions.length > 0}\n    <!--\n      Search results section — only shown while typing.\n      `paletteQuery` comes from the snippet parameter and mirrors CommandPalette's query.\n      using the snippet parameter keeps the pattern explicit for consumers.\n    -->\n    {#if showPages}\n      <li role=\"none\" style=\"{headerBase} {headerFirst}\">Pages</li>\n      {#each filteredPages as page (page.id)}\n        <CommandItem\n          value={page.id}\n          description={page.description}\n          onselect={() => select(page.label)}\n        >\n          {page.label}\n        </CommandItem>\n      {/each}\n    {/if}\n\n    <!--\n      Recent section — shown only when query is empty.\n      Uses `role=\"none\"` for the group label (purely visual; children remain in the AT).\n    -->\n    {#if showRecent}\n      <li role=\"none\" style=\"{headerBase} {showPages ? headerWithDivider : headerFirst}\">Recent</li>\n      {#each recentItems as item (item.id)}\n        <CommandItem value={item.id} onselect={() => select(item.label)}>\n          {item.label}\n        </CommandItem>\n      {/each}\n    {/if}\n\n    <!--\n      Actions section — always visible (filtered when typing).\n    -->\n    {#if showActions}\n      <li\n        role=\"none\"\n        style=\"{headerBase} {showPages || showRecent ? headerWithDivider : headerFirst}\"\n      >\n        Actions\n      </li>\n      {#each filteredActions as action (action.id)}\n        <CommandItem\n          value={action.id}\n          description={action.description}\n          onselect={() => select(action.label)}\n        >\n          {#snippet leading()}\n            <span style=\"font-size: 0.875rem; font-weight: 700; line-height: 1;\">{action.icon}</span\n            >\n          {/snippet}\n          {action.label}\n          {#snippet trailing()}\n            {#if action.kbd}\n              <kbd>{action.kbd}</kbd>\n            {/if}\n          {/snippet}\n        </CommandItem>\n      {/each}\n    {/if}\n  {/snippet}\n\n  {#snippet empty()}\n    No results for \"<strong>{query}</strong>\".\n  {/snippet}\n\n  {#snippet footer()}\n    <span>\n      <kbd>↑↓</kbd> navigate &nbsp; <kbd>↵</kbd> select &nbsp; <kbd>Esc</kbd> close\n    </span>\n  {/snippet}\n</CommandPalette>\n"
+      "code": "<script lang=\"ts\">\n  import { CommandItem } from '@lostgradient/cinder/command-item';\n  import { CommandPalette } from '@lostgradient/cinder/command-palette';\n  // ── State ──────────────────────────────────────────────────────────────\n  let open = $state(false);\n  let query = $state('');\n  let lastSelected = $state('');\n  let triggerRef: HTMLElement | null = $state(null);\n\n  // ── Data ──────────────────────────────────────────────────────────────\n  const allPages = [\n    { id: 'dashboard', label: 'Dashboard', description: 'View product and team metrics.' },\n    { id: 'settings', label: 'Settings', description: 'Manage workspace preferences.' },\n    { id: 'billing', label: 'Billing', description: 'Review invoices and payment methods.' },\n    { id: 'team', label: 'Team members', description: 'Invite or remove collaborators.' },\n    { id: 'api-keys', label: 'API keys', description: 'Create and rotate access tokens.' },\n    { id: 'integrations', label: 'Integrations', description: 'Connect external services.' },\n  ];\n\n  const recentItems = [\n    { id: 'recent-dashboard', label: 'Dashboard' },\n    { id: 'recent-billing', label: 'Billing' },\n  ];\n\n  const actions = [\n    {\n      id: 'action-new-project',\n      label: 'New project',\n      description: 'Create a blank project for a new body of work.',\n      icon: '+',\n      kbd: '⌘N',\n    },\n    {\n      id: 'action-invite',\n      label: 'Invite teammate',\n      description: 'Send an invitation to join this workspace.',\n      icon: '@',\n      kbd: '⌘I',\n    },\n    {\n      id: 'action-sign-out',\n      label: 'Sign out',\n      description: 'End this browser session.',\n      icon: '↪',\n      kbd: '',\n    },\n  ];\n\n  // ── Filtering ──────────────────────────────────────────────────────────\n  const filteredPages = $derived(\n    query ? allPages.filter((p) => p.label.toLowerCase().includes(query.toLowerCase())) : [],\n  );\n\n  const filteredActions = $derived(\n    query ? actions.filter((a) => a.label.toLowerCase().includes(query.toLowerCase())) : actions,\n  );\n\n  function select(label: string) {\n    lastSelected = label;\n    open = false;\n  }\n\n  // ── Cmd+K / Ctrl+K listener ────────────────────────────────────────────\n  function handleGlobalKeydown(event: KeyboardEvent) {\n    if ((event.metaKey || event.ctrlKey) && event.key === 'k') {\n      event.preventDefault();\n      open = true;\n    }\n  }\n</script>\n\n<svelte:window onkeydown={handleGlobalKeydown} />\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;\">\n  <button\n    bind:this={triggerRef}\n    type=\"button\"\n    onclick={() => (open = true)}\n    style=\"\n      display: inline-flex;\n      align-items: center;\n      gap: 0.5rem;\n      padding: 0.5rem 0.75rem;\n      border: 1px solid var(--cinder-border);\n      border-radius: var(--cinder-radius-md);\n      background: var(--cinder-surface);\n      color: var(--cinder-text-muted);\n      font-size: 0.875rem;\n      cursor: pointer;\n    \"\n  >\n    Search…\n    <kbd style=\"font-size: 0.75rem; opacity: 0.7;\">⌘K</kbd>\n  </button>\n\n  {#if lastSelected}\n    <p style=\"font-size: 0.875rem; color: var(--cinder-text-muted);\">\n      Selected: <strong>{lastSelected}</strong>\n    </p>\n  {/if}\n</div>\n\n<CommandPalette bind:open bind:query label=\"Command palette\" {triggerRef}>\n  {#snippet items({ query: paletteQuery })}\n    {@const headerBase =\n      'font-size: 0.6875rem; font-weight: 600; letter-spacing: 0.05em; text-transform: uppercase; color: var(--cinder-text-muted); pointer-events: none;'}\n    {@const headerFirst = 'padding: 0.625rem 1.25rem 0.375rem;'}\n    {@const headerWithDivider =\n      'padding: 0.625rem 1.25rem 0.375rem 1.25rem; padding-block-start: 0.625rem; margin-block-start: 0.25rem; border-block-start: 1px solid var(--cinder-border);'}\n    {@const showPages = filteredPages.length > 0}\n    {@const showRecent = !paletteQuery}\n    {@const showActions = filteredActions.length > 0}\n    <!--\n      Search results section — only shown while typing.\n      `paletteQuery` comes from the snippet parameter and mirrors CommandPalette's query.\n      using the snippet parameter keeps the pattern explicit for consumers.\n    -->\n    {#if showPages}\n      <li role=\"none\" style=\"{headerBase} {headerFirst}\">Pages</li>\n      {#each filteredPages as page (page.id)}\n        <CommandItem\n          value={page.id}\n          description={page.description}\n          accessibleLabel={page.label}\n          onselect={() => select(page.label)}\n        >\n          {page.label}\n        </CommandItem>\n      {/each}\n    {/if}\n\n    <!--\n      Recent section — shown only when query is empty.\n      Uses `role=\"none\"` for the group label (purely visual; children remain in the AT).\n    -->\n    {#if showRecent}\n      <li role=\"none\" style=\"{headerBase} {showPages ? headerWithDivider : headerFirst}\">Recent</li>\n      {#each recentItems as item (item.id)}\n        <CommandItem\n          value={item.id}\n          accessibleLabel={item.label}\n          onselect={() => select(item.label)}\n        >\n          {item.label}\n        </CommandItem>\n      {/each}\n    {/if}\n\n    <!--\n      Actions section — always visible (filtered when typing).\n    -->\n    {#if showActions}\n      <li\n        role=\"none\"\n        style=\"{headerBase} {showPages || showRecent ? headerWithDivider : headerFirst}\"\n      >\n        Actions\n      </li>\n      {#each filteredActions as action (action.id)}\n        <CommandItem\n          value={action.id}\n          description={action.description}\n          accessibleLabel={action.label}\n          keyboardShortcut={action.kbd === '⌘N'\n            ? 'Meta+N'\n            : action.kbd === '⌘I'\n              ? 'Meta+I'\n              : undefined}\n          onselect={() => select(action.label)}\n        >\n          {#snippet leading()}\n            <span style=\"font-size: 0.875rem; font-weight: 700; line-height: 1;\">{action.icon}</span\n            >\n          {/snippet}\n          {action.label}\n          {#snippet trailing()}\n            {#if action.kbd}\n              <kbd>{action.kbd}</kbd>\n            {/if}\n          {/snippet}\n        </CommandItem>\n      {/each}\n    {/if}\n  {/snippet}\n\n  {#snippet empty()}\n    No results for \"<strong>{query}</strong>\".\n  {/snippet}\n\n  {#snippet footer()}\n    <span>\n      <kbd>↑↓</kbd> navigate &nbsp; <kbd>↵</kbd> select &nbsp; <kbd>Esc</kbd> close\n    </span>\n  {/snippet}\n</CommandPalette>\n"
     }
   ]
 }

package/src/components/command-palette/command-palette.svelte

@@ -21,13 +21,9 @@
 
   import { captureFocus, pushEscapeHandler } from '../../_internal/overlay.ts';
   import { classNames } from '../../utilities/class-names.ts';
-  import { inDocumentOrder } from '../../utilities/document-order.ts';
   import { restoreFocusTo } from '../../utilities/focus.ts';
-  import {
-    setCommandListContext,
-    type CommandItemRegistrationInput,
-    type CommandListContext,
-  } from '../_internal/command-list-context.ts';
+  import { setCommandListContext } from '../_internal/command-list-context.ts';
+  import { createCommandListState } from '../_internal/create-command-list-state.svelte.ts';
 
   let {
     open = $bindable(false),
@@ -62,58 +58,12 @@
   // ── Focus capture ─────────────────────────────────────────────────────────
   let capturedFocus: HTMLElement | null = null;
 
-  // ── Item registration ─────────────────────────────────────────────────────
-  type RegistrationRecord = CommandItemRegistrationInput & { id: string; node: HTMLElement };
-  let registrations = $state<RegistrationRecord[]>([]);
-
-  // Stable incrementing counter for item ids within this palette instance.
-  let itemCounter = 0;
-
-  // ── Active item (virtual focus) ───────────────────────────────────────────
-  // `intendedActiveId` is the user's last navigation/hover intent. The resolved
-  // `activeItemId` clamps that intent to the currently-enabled set, so it is a
-  // pure function of intent + enabledIds rather than a value repaired one tick
-  // late inside an $effect. Keyboard/hover handlers write intent; everything
-  // downstream reads the resolved derived.
-  let intendedActiveId = $state<string | null>(null);
-
-  // Ordered list of non-disabled item ids. Derived so arrow-key navigation
-  // always walks the current set, including after prop changes (e.g. toggling
-  // disabled on a mounted item).
-  const enabledIds = $derived.by(() => {
-    return inDocumentOrder(registrations)
-      .filter((r) => !r.getDisabled())
-      .map((r) => r.id);
-  });
-
-  // Resolved active id: preserve the user's intent if it's still in the enabled
-  // set, otherwise fall back to the first enabled item (or null). This collapses
-  // the previous read-then-write $effect into a single synchronous derivation.
-  const activeItemId = $derived(
-    intendedActiveId !== null && enabledIds.includes(intendedActiveId)
-      ? intendedActiveId
-      : (enabledIds[0] ?? null),
-  );
-
-  // ── Empty-state flash prevention ─────────────────────────────────────────
-  // `registrationsReady` prevents the empty snippet from flashing on initial
-  // open or when a query change causes a full key-swap of items. It is set
-  // true after one microtask (giving children's $effect registrations time to
-  // settle), and reset on every query change.
-  //
-  // A cycle counter guards against stale microtasks: if the query changes
-  // twice in quick succession, only the most recent microtask sets ready=true.
-  let registrationsReady = $state(false);
-  let readyCycle = 0;
+  const commandList = createCommandListState(listboxId);
 
   $effect(() => {
     // Track query so this re-runs on every query change.
     void query;
-    registrationsReady = false;
-    const cycle = ++readyCycle;
-    queueMicrotask(() => {
-      if (cycle === readyCycle) registrationsReady = true;
-    });
+    commandList.refreshRegistrationsReady();
   });
 
   // ── Escape stack ──────────────────────────────────────────────────────────
@@ -155,6 +105,8 @@
   $effect(() => {
     if (!dialogElement) return;
     if (open && !dialogElement.open) {
+      query = '';
+      commandList.resetActiveItem();
       capturedFocus = captureFocus();
       dialogElement.showModal();
       inputElement?.focus();
@@ -193,40 +145,11 @@
 
   // ── Keyboard routing ──────────────────────────────────────────────────────
   function handleKeydown(event: KeyboardEvent) {
-    const ids = enabledIds;
-
-    if (event.key === 'ArrowDown') {
-      event.preventDefault();
-      if (ids.length === 0) return;
-      if (activeItemId === null) {
-        const firstId = ids[0];
-        if (firstId !== undefined) intendedActiveId = firstId;
-      } else {
-        const index = ids.indexOf(activeItemId);
-        const nextId = ids[(index + 1) % ids.length];
-        if (nextId !== undefined) intendedActiveId = nextId;
-      }
-    } else if (event.key === 'ArrowUp') {
-      event.preventDefault();
-      if (ids.length === 0) return;
-      if (activeItemId === null) {
-        const lastId = ids[ids.length - 1];
-        if (lastId !== undefined) intendedActiveId = lastId;
-      } else {
-        const index = ids.indexOf(activeItemId);
-        const previousId = ids[index <= 0 ? ids.length - 1 : index - 1];
-        if (previousId !== undefined) intendedActiveId = previousId;
-      }
-    } else if (event.key === 'Home') {
-      event.preventDefault();
-      intendedActiveId = ids[0] ?? null;
-    } else if (event.key === 'End') {
-      event.preventDefault();
-      intendedActiveId = ids[ids.length - 1] ?? null;
-    } else if (event.key === 'Enter') {
-      event.preventDefault();
-      if (activeItemId !== null) context.activateItemById(activeItemId);
-    }
+    commandList.handleKeydown({
+      event,
+      onEnter: (id) => commandList.activateItemById(id),
+      preventDefaultOnEmptyEnter: true,
+    });
   }
 
   function handleInput(event: Event) {
@@ -235,55 +158,15 @@
   }
 
   $effect(() => {
-    if (activeItemId === null) return;
-    // Use the node captured at registration time rather than
-    // document.getElementById, which assumes globally-unique ids and breaks in
-    // shadow DOM, iframes, or multi-instance scenarios.
-    const record = registrations.find((r) => r.id === activeItemId);
-    record?.node.scrollIntoView({ block: 'nearest' });
+    commandList.scrollActiveItemIntoView();
   });
 
   // ── Context ───────────────────────────────────────────────────────────────
-  const context: CommandListContext = {
-    get listboxId() {
-      return listboxId;
-    },
-    get activeItemId() {
-      return activeItemId;
-    },
-    register(input: CommandItemRegistrationInput, node: HTMLElement) {
-      const id = `${listboxId}-item-${++itemCounter}`;
-      // Mutate in place: $state wraps the array in a deep reactive proxy that
-      // tracks push/splice, so we avoid allocating a fresh array per register.
-      registrations.push({
-        id,
-        node,
-        getValue: input.getValue,
-        getOnselect: input.getOnselect,
-        getDisabled: input.getDisabled,
-      });
-      return {
-        id,
-        unregister: () => {
-          const index = registrations.findIndex((r) => r.id === id);
-          if (index !== -1) registrations.splice(index, 1);
-        },
-      };
-    },
-    setActiveById(id: string) {
-      intendedActiveId = id;
-    },
-    activateItemById(id: string) {
-      const record = registrations.find((r) => r.id === id);
-      if (record && !record.getDisabled()) {
-        record.getOnselect()();
-      }
-    },
-  };
-
-  setCommandListContext(context);
+  setCommandListContext(commandList.createContext());
 
-  const showEmpty = $derived(mounted && registrationsReady && registrations.length === 0);
+  const showEmpty = $derived(
+    mounted && commandList.registrationsReady && commandList.registrations.length === 0,
+  );
 </script>
 
 {#if mounted || open}
@@ -327,7 +210,7 @@
             aria-autocomplete="list"
             aria-expanded="true"
             aria-controls={listboxId}
-            aria-activedescendant={activeItemId ?? undefined}
+            aria-activedescendant={commandList.activeItemId ?? undefined}
             oninput={handleInput}
             onkeydown={handleKeydown}
           />

package/src/components/command-palette/command-palette.types.ts

@@ -12,8 +12,7 @@ export type CommandPaletteProps = {
   /**
    * Bindable search query. Mutated by the input's oninput handler.
    * Exposed to the items snippet so consumers can filter.
-   * Note: query is NOT reset on close — consumers who want a fresh query on
-   * each open should reset it in their `onclose` callback.
+   * Reset to an empty string each time the palette opens.
    */
   query?: string;
   /** Fired after any close path routed through the palette close lifecycle. */

package/src/components/context-menu/context-menu.context.ts

@@ -1,9 +1,11 @@
 import { createContext } from 'svelte';
+import type { TextDirection } from '../../_internal/locale-context.ts';
 
 export type ContextMenuContext = {
   get disabled(): boolean;
   get isOpen(): boolean;
   get longPressDelay(): number;
+  get direction(): TextDirection | undefined;
   openAt: (x: number, y: number) => void;
   close: () => void;
 };

package/src/components/context-menu/context-menu.svelte

@@ -19,7 +19,9 @@
   import type { ContextMenuProps } from './context-menu.types.ts';
   import type { VirtualElement } from '@floating-ui/dom';
   import { createAnchoredOverlay } from '../../_internal/anchored-overlay.svelte.ts';
+  import { getLocaleContext } from '../../_internal/locale-context.ts';
   import { captureFocus } from '../../_internal/overlay.ts';
+  import { observeTextDirection, resolveTextDirection } from '../../_internal/text-direction.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { restoreFocusTo } from '../../utilities/focus.ts';
   import { createClickOutside } from '../../utilities/attachments.ts';
@@ -47,7 +49,9 @@
   let capturedFocus: HTMLElement | null = null;
   let requestedX = $state(0);
   let requestedY = $state(0);
+  let directionRevision = $state(0);
   let previouslyOpen = false;
+  const localeContext = getLocaleContext();
 
   function setOpen(nextOpen: boolean) {
     if (open === nextOpen) return;
@@ -103,12 +107,22 @@
   const virtualReference: VirtualElement | null = $derived(
     open ? makeVirtualReference(anchorPoint?.x ?? requestedX, anchorPoint?.y ?? requestedY) : null,
   );
+  const resolvedDirection = $derived.by(() => {
+    directionRevision;
+    return resolveTextDirection(triggerElement, localeContext?.direction);
+  });
+
+  $effect(() => {
+    return observeTextDirection(triggerElement, () => {
+      directionRevision += 1;
+    });
+  });
 
   const anchoredOverlay = createAnchoredOverlay({
     open: () => open,
     anchor: () => virtualReference,
     panel: () => menuElement,
-    placement: () => 'right-start',
+    placement: () => (resolvedDirection === 'rtl' ? 'left-start' : 'right-start'),
     offset: () => 0,
     widthMode: () => 'menu',
   });
@@ -133,6 +147,18 @@
     get supportsPopover() {
       return false;
     },
+    get anchorElement() {
+      return triggerElement;
+    },
+    get fallbackAnchorElement() {
+      return null;
+    },
+    get fallbackPositionStyle() {
+      return anchoredOverlay.positionStyle;
+    },
+    get fallbackPositionReady() {
+      return anchoredOverlay.positionReady;
+    },
     get initialFocus() {
       return 'first' as const;
     },
@@ -152,6 +178,9 @@
     get longPressDelay() {
       return longPressDelay;
     },
+    get direction() {
+      return resolvedDirection;
+    },
     openAt,
     close,
   });
@@ -161,17 +190,14 @@
     const x = anchorPoint?.x ?? requestedX;
     const y = anchorPoint?.y ?? requestedY;
     const menu = menuElement;
-    if (anchoredOverlay.positionStyle) {
-      menu.setAttribute('style', anchoredOverlay.positionStyle);
-    } else {
-      menu.removeAttribute('style');
-    }
-    menu.setAttribute('data-cinder-position-ready', String(anchoredOverlay.positionReady));
     menu.setAttribute('data-cinder-requested-x', String(x));
     menu.setAttribute('data-cinder-requested-y', String(y));
+    const ownsDirection = menu.dataset['cinderExplicitDirection'] !== 'true';
+    if (ownsDirection && resolvedDirection) {
+      menu.setAttribute('dir', resolvedDirection);
+    }
     return () => {
-      menu.removeAttribute('style');
-      menu.removeAttribute('data-cinder-position-ready');
+      if (ownsDirection) menu.removeAttribute('dir');
       menu.removeAttribute('data-cinder-requested-x');
       menu.removeAttribute('data-cinder-requested-y');
     };