@lostgradient/cinder 0.8.0 → 0.11.0

package/src/components/chat-composer-popover/chat-composer-popover.css

@@ -0,0 +1,7 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+/* ChatComposerPopover renders CommandMenu and CommandItem internally. Pull in
+ * the command menu family so the wrapper is styled through its own styles path. */
+@import '../command-menu/command-menu.css';
+
+@layer cinder.components {
+}

package/src/components/chat-composer-popover/chat-composer-popover.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "chat-composer-popover",
+  "import": "@lostgradient/cinder/chat-composer-popover",
+  "examples": [
+    {
+      "id": "slash-commands",
+      "title": "Slash commands in ChatInput",
+      "description": "Wires ChatComposerPopover to ChatInput with consumer-owned command definitions.",
+      "code": "<script lang=\"ts\">\n  import ChatComposerPopover, {\n    type ChatComposerPopoverSelection,\n  } from '@lostgradient/cinder/chat-composer-popover';\n  import { ChatInput } from '@lostgradient/cinder/chat';\n\n  type SlashCommand = {\n    value: string;\n    label: string;\n    description: string;\n    insert: string;\n    keywords?: string[];\n  };\n\n  const commands: SlashCommand[] = [\n    {\n      value: 'help',\n      label: 'Help',\n      description: 'Show available assistant commands',\n      insert: '/help ',\n      keywords: ['docs', 'support'],\n    },\n    {\n      value: 'new',\n      label: 'New conversation',\n      description: 'Start a fresh thread',\n      insert: '/new ',\n      keywords: ['reset', 'fresh'],\n    },\n    {\n      value: 'tools',\n      label: 'Tools',\n      description: 'Open tool controls',\n      insert: '/tools ',\n      keywords: ['integrations', 'actions'],\n    },\n    {\n      value: 'stop',\n      label: 'Stop',\n      description: 'Stop the current response',\n      insert: '/stop',\n      keywords: ['cancel', 'halt'],\n    },\n  ];\n\n  let value = $state('');\n  let selectedCommand = $state('None');\n\n  function handleSelect(selection: ChatComposerPopoverSelection<SlashCommand>) {\n    value = `${value.slice(0, selection.range.start)}${selection.item.insert}${value.slice(\n      selection.range.end,\n    )}`;\n    selectedCommand = selection.item.label;\n  }\n</script>\n\n<ChatComposerPopover id=\"slash-command\" bind:value items={commands} onselect={handleSelect}>\n  {#snippet composer(composerProps)}\n    <ChatInput\n      id=\"chat\"\n      bind:value\n      allowAttachments={false}\n      placeholder=\"Type / for commands\"\n      composerRole={composerProps.composerRole}\n      composerAriaExpanded={composerProps.composerAriaExpanded}\n      composerAriaControls={composerProps.composerAriaControls}\n      composerAriaActiveDescendant={composerProps.composerAriaActiveDescendant}\n      composerAriaAutocomplete={composerProps.composerAriaAutocomplete}\n      oncomposerinput={composerProps.oncomposerinput}\n      oncomposerkeydown={composerProps.oncomposerkeydown}\n      oncomposerselectionchange={composerProps.oncomposerselectionchange}\n      oncomposerblur={composerProps.oncomposerblur}\n    />\n  {/snippet}\n</ChatComposerPopover>\n\n<p>Selected: {selectedCommand}</p>\n"
+    }
+  ]
+}

package/src/components/chat-composer-popover/chat-composer-popover.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier used for the listbox and item ids."
+    },
+    "value": {
+      "type": "string",
+      "description": "Current composer value. Bind this to the same value as ChatInput."
+    },
+    "triggers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Trigger characters that open the popover. Default `['/', '@']`."
+    },
+    "label": {
+      "type": "string",
+      "description": "Accessible listbox label. Default `'Composer suggestions'`."
+    },
+    "placement": {
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "top-start",
+        "top-end",
+        "bottom-start",
+        "bottom-end"
+      ],
+      "description": "Caret-relative placement. Default `'bottom-start'`."
+    },
+    "offset": {
+      "type": "number",
+      "description": "Distance in px between the caret and popover. Default `6`."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["id"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "composer",
+        "reason": "function-or-snippet",
+        "required": true,
+        "description": "Render the ChatInput or compatible composer with the provided overlay props."
+      },
+      {
+        "name": "detectTrigger",
+        "reason": "function-or-snippet",
+        "description": "Override trigger detection."
+      },
+      {
+        "name": "empty",
+        "reason": "function-or-snippet",
+        "description": "Optional empty state rendered when filtering produces no matching rows."
+      },
+      {
+        "name": "filter",
+        "reason": "function-or-snippet",
+        "description": "Override filtering."
+      },
+      {
+        "name": "item",
+        "reason": "function-or-snippet",
+        "description": "Optional custom row contents. Defaults to the item label and description."
+      },
+      {
+        "name": "items",
+        "reason": "generic-type-parameter",
+        "required": true,
+        "description": "Consumer-owned command or mention definitions."
+      },
+      {
+        "name": "ondismiss",
+        "reason": "function-or-snippet",
+        "description": "Invoked when Escape, trigger loss, or outside pointerdown dismisses the popover."
+      },
+      {
+        "name": "onselect",
+        "reason": "function-or-snippet",
+        "description": "Invoked when an enabled item is selected by keyboard or pointer."
+      }
+    ]
+  }
+}

package/src/components/chat-composer-popover/chat-composer-popover.schema.ts

@@ -0,0 +1,95 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier used for the listbox and item ids.',
+    },
+    value: {
+      type: 'string',
+      description: 'Current composer value. Bind this to the same value as ChatInput.',
+    },
+    triggers: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+      description: "Trigger characters that open the popover. Default `['/', '@']`.",
+    },
+    label: {
+      type: 'string',
+      description: "Accessible listbox label. Default `'Composer suggestions'`.",
+    },
+    placement: {
+      enum: [
+        'top',
+        'bottom',
+        'left',
+        'right',
+        'top-start',
+        'top-end',
+        'bottom-start',
+        'bottom-end',
+      ],
+      description: "Caret-relative placement. Default `'bottom-start'`.",
+    },
+    offset: {
+      type: 'number',
+      description: 'Distance in px between the caret and popover. Default `6`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['id'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'composer',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Render the ChatInput or compatible composer with the provided overlay props.',
+      },
+      {
+        name: 'detectTrigger',
+        reason: 'function-or-snippet',
+        description: 'Override trigger detection.',
+      },
+      {
+        name: 'empty',
+        reason: 'function-or-snippet',
+        description: 'Optional empty state rendered when filtering produces no matching rows.',
+      },
+      {
+        name: 'filter',
+        reason: 'function-or-snippet',
+        description: 'Override filtering.',
+      },
+      {
+        name: 'item',
+        reason: 'function-or-snippet',
+        description: 'Optional custom row contents. Defaults to the item label and description.',
+      },
+      {
+        name: 'items',
+        reason: 'generic-type-parameter',
+        required: true,
+        description: 'Consumer-owned command or mention definitions.',
+      },
+      {
+        name: 'ondismiss',
+        reason: 'function-or-snippet',
+        description:
+          'Invoked when Escape, trigger loss, or outside pointerdown dismisses the popover.',
+      },
+      {
+        name: 'onselect',
+        reason: 'function-or-snippet',
+        description: 'Invoked when an enabled item is selected by keyboard or pointer.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/chat-composer-popover/chat-composer-popover.svelte

@@ -0,0 +1,234 @@
+<script lang="ts" module>
+export { filterFuzzySubsequence, fuzzySubsequenceScore, } from './chat-composer-popover-filter.ts';
+</script>
+
+<script lang="ts" generics="TItem extends ChatComposerPopoverItem">
+import CommandItem from '../command-item/command-item.svelte';
+import CommandMenu from '../command-menu/command-menu.svelte';
+import { onDestroy } from 'svelte';
+import { detectTrigger as detectCommandTrigger } from '../command-menu/command-menu-trigger.ts';
+import { filterFuzzySubsequence } from './chat-composer-popover-filter.ts';
+let { id, value = $bindable(''), items, triggers = ['/', '@'], label = 'Composer suggestions', placement = 'bottom-start', offset = 6, composer, item, empty, detectTrigger, filter = filterFuzzySubsequence, onselect, ondismiss, } = $props();
+let open = $state(false);
+let anchor = $state(null);
+let caretIndex = $state(0);
+const listboxId = $derived(`${id}-listbox`);
+let activeItemId = $state(null);
+let activeMatch = $state(null);
+let composerSyncTimer = null;
+let lastSyncedValue = $state(value);
+let suppressNextValueSync = false;
+const emptyContent = $derived(empty);
+const query = $derived(activeMatch?.query ?? '');
+const trigger = $derived(activeMatch?.trigger ?? triggers[0] ?? '/');
+const filteredItems = $derived.by(() => {
+    if (!activeMatch)
+        return [];
+    return [...filter(items, activeMatch.query, activeMatch.trigger)];
+});
+const composerProps = $derived({
+    composerRole: 'combobox',
+    composerAriaExpanded: open,
+    composerAriaControls: open ? listboxId : undefined,
+    composerAriaActiveDescendant: open ? (activeItemId ?? undefined) : undefined,
+    composerAriaAutocomplete: 'list',
+    oncomposerinput: handleComposerInput,
+    oncomposerkeydown: handleComposerKeydown,
+    oncomposerselectionchange: handleComposerSelectionChange,
+    oncomposerblur: handleComposerBlur,
+});
+function getComposerElement(event) {
+    const target = event.currentTarget ?? event.target;
+    if (target instanceof HTMLTextAreaElement || target instanceof HTMLInputElement) {
+        return target;
+    }
+    return null;
+}
+function findTriggerMatch(text, selectionStart, selectionEnd) {
+    if (detectTrigger)
+        return detectTrigger(text, selectionStart, selectionEnd);
+    for (const triggerChar of triggers) {
+        const match = detectCommandTrigger({ text, selectionStart, selectionEnd, triggerChar });
+        if (match) {
+            return { ...match, trigger: triggerChar };
+        }
+    }
+    return null;
+}
+function updateFromComposer(composerElement, nextValue) {
+    if (composerElement)
+        anchor = composerElement;
+    const selectionStart = composerElement?.selectionStart ?? nextValue.length;
+    const selectionEnd = composerElement?.selectionEnd ?? selectionStart;
+    lastSyncedValue = nextValue;
+    value = nextValue;
+    caretIndex = selectionEnd;
+    activeMatch = findTriggerMatch(nextValue, selectionStart, selectionEnd);
+    const wasOpen = open;
+    open = activeMatch !== null && anchor !== null;
+    if (!open) {
+        activeItemId = null;
+        if (wasOpen)
+            ondismiss?.();
+    }
+}
+function dismiss({ restoreFocus = true } = {}) {
+    if (!open && !activeMatch && !activeItemId)
+        return;
+    clearComposerSyncTimer();
+    open = false;
+    activeItemId = null;
+    activeMatch = null;
+    if (restoreFocus)
+        anchor?.focus();
+    ondismiss?.();
+}
+function handleComposerInput(nextValue, event) {
+    suppressNextValueSync = false;
+    updateFromComposer(event ? getComposerElement(event) : anchor, nextValue);
+}
+function handleComposerSelectionChange(event) {
+    suppressNextValueSync = false;
+    const composerElement = getComposerElement(event);
+    if (!composerElement)
+        return;
+    syncComposerSelectionAfterNativeNavigation(composerElement);
+}
+function handleComposerBlur(event) {
+    if (event.currentTarget === anchor) {
+        dismiss({ restoreFocus: false });
+    }
+}
+function syncComposerSelectionAfterNativeNavigation(composerElement) {
+    clearComposerSyncTimer();
+    composerSyncTimer = setTimeout(() => {
+        composerSyncTimer = null;
+        updateFromComposer(composerElement, composerElement.value);
+    }, 0);
+}
+function clearComposerSyncTimer() {
+    if (composerSyncTimer === null)
+        return;
+    clearTimeout(composerSyncTimer);
+    composerSyncTimer = null;
+}
+function handleComposerKeydown(event) {
+    const composerElement = event.currentTarget instanceof HTMLTextAreaElement ||
+        event.currentTarget instanceof HTMLInputElement
+        ? event.currentTarget
+        : null;
+    if (composerElement) {
+        anchor = composerElement;
+        caretIndex = composerElement.selectionEnd ?? value.length;
+    }
+    if (!open || event.isComposing || event.keyCode === 229)
+        return;
+    if (event.key === 'Escape') {
+        event.preventDefault();
+        event.stopPropagation();
+        dismiss();
+        return;
+    }
+    const isNavigationKey = event.key === 'ArrowDown' ||
+        event.key === 'ArrowUp' ||
+        event.key === 'ArrowLeft' ||
+        event.key === 'ArrowRight' ||
+        event.key === 'Home' ||
+        event.key === 'End';
+    const isMenuNavigationKey = event.key === 'ArrowDown' ||
+        event.key === 'ArrowUp' ||
+        event.key === 'Home' ||
+        event.key === 'End';
+    const isModifiedNavigation = isNavigationKey && (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey);
+    if ((isMenuNavigationKey && !isModifiedNavigation) || (event.key === 'Enter' && activeItemId)) {
+        event.preventDefault();
+    }
+    if (composerElement && isNavigationKey && (isModifiedNavigation || !isMenuNavigationKey)) {
+        syncComposerSelectionAfterNativeNavigation(composerElement);
+    }
+}
+onDestroy(() => {
+    clearComposerSyncTimer();
+});
+$effect(() => {
+    if (value === lastSyncedValue)
+        return;
+    if (suppressNextValueSync) {
+        suppressNextValueSync = false;
+        lastSyncedValue = value;
+        return;
+    }
+    updateFromComposer(anchor, value);
+});
+function handleStateChange(state) {
+    activeItemId = state.activeItemId;
+}
+function handleSelect(selection) {
+    const selectedItem = filteredItems.find((candidate) => candidate.value === selection.value);
+    if (!selectedItem || !activeMatch)
+        return;
+    const detail = {
+        item: selectedItem,
+        value: selection.value,
+        query: activeMatch.query,
+        trigger: activeMatch.trigger,
+        range: {
+            start: activeMatch.start,
+            end: activeMatch.end,
+        },
+    };
+    open = false;
+    activeItemId = null;
+    activeMatch = null;
+    anchor?.focus();
+    suppressNextValueSync = true;
+    queueMicrotask(() => {
+        suppressNextValueSync = false;
+    });
+    onselect?.(detail);
+}
+</script>
+
+{@render composer(composerProps)}
+
+<CommandMenu
+  bind:open
+  {anchor}
+  {caretIndex}
+  {query}
+  {placement}
+  {offset}
+  {label}
+  {listboxId}
+  onselect={handleSelect}
+  ondismiss={() => dismiss({ restoreFocus: false })}
+  onstatechange={handleStateChange}
+>
+  {#snippet items()}
+    {#each filteredItems as command (command.value)}
+      <CommandItem
+        value={command.value}
+        disabled={command.disabled === true}
+        description={item ? '' : (command.description ?? '')}
+        accessibleLabel={command.description
+          ? `${command.label}, ${command.description}`
+          : command.label}
+        selectionMode="parent"
+      >
+        {#if item}
+          {@render item({ item: command, query, trigger })}
+        {:else}
+          {command.label}
+        {/if}
+      </CommandItem>
+    {/each}
+  {/snippet}
+
+  {#snippet empty()}
+    {#if emptyContent}
+      {@render emptyContent()}
+    {:else}
+      No suggestions
+    {/if}
+  {/snippet}
+</CommandMenu>

package/src/components/chat-composer-popover/chat-composer-popover.types.ts

@@ -0,0 +1,88 @@
+import type { Snippet } from 'svelte';
+
+import type { PopoverPlacement } from '../popover/popover.types.ts';
+
+export type ChatComposerPopoverItem = {
+  /** Stable submitted value surfaced through onselect. */
+  value: string;
+  /** Default visible and accessible label for the command row. */
+  label: string;
+  /** Optional secondary text for the command row. */
+  description?: string | undefined;
+  /** Optional fuzzy-search aliases. */
+  keywords?: readonly string[] | undefined;
+  /** Whether this row is skipped by keyboard navigation and activation. */
+  disabled?: boolean | undefined;
+};
+
+export type ChatComposerPopoverTriggerMatch = {
+  active: true;
+  trigger: string;
+  query: string;
+  start: number;
+  end: number;
+};
+
+export type ChatComposerPopoverSelection<TItem extends ChatComposerPopoverItem> = {
+  item: TItem;
+  value: string;
+  query: string;
+  trigger: string;
+  range: {
+    start: number;
+    end: number;
+  };
+};
+
+export type ChatComposerPopoverComposerProps = {
+  composerRole: 'combobox';
+  composerAriaExpanded: boolean;
+  composerAriaControls: string | undefined;
+  composerAriaActiveDescendant: string | undefined;
+  composerAriaAutocomplete: 'list';
+  oncomposerinput: (value: string, event?: Event) => void;
+  oncomposerkeydown: (event: KeyboardEvent) => void;
+  oncomposerselectionchange: (event: Event) => void;
+  oncomposerblur: (event: FocusEvent) => void;
+};
+
+export type ChatComposerPopoverItemSnippetContext<TItem extends ChatComposerPopoverItem> = {
+  item: TItem;
+  query: string;
+  trigger: string;
+};
+
+export type ChatComposerPopoverProps<TItem extends ChatComposerPopoverItem> = {
+  /** Unique identifier used for the listbox and item ids. */
+  id: string;
+  /** Current composer value. Bind this to the same value as ChatInput. */
+  value?: string;
+  /** Consumer-owned command or mention definitions. */
+  items: readonly TItem[];
+  /** Trigger characters that open the popover. Default `['/', '@']`. */
+  triggers?: readonly string[];
+  /** Accessible listbox label. Default `'Composer suggestions'`. */
+  label?: string;
+  /** Caret-relative placement. Default `'bottom-start'`. */
+  placement?: PopoverPlacement;
+  /** Distance in px between the caret and popover. Default `6`. */
+  offset?: number;
+  /** Render the ChatInput or compatible composer with the provided overlay props. */
+  composer: Snippet<[ChatComposerPopoverComposerProps]>;
+  /** Optional custom row contents. Defaults to the item label and description. */
+  item?: Snippet<[ChatComposerPopoverItemSnippetContext<TItem>]>;
+  /** Optional empty state rendered when filtering produces no matching rows. */
+  empty?: Snippet;
+  /** Override trigger detection. */
+  detectTrigger?: (
+    value: string,
+    selectionStart: number,
+    selectionEnd: number,
+  ) => ChatComposerPopoverTriggerMatch | null;
+  /** Override filtering. */
+  filter?: (items: readonly TItem[], query: string, trigger: string) => readonly TItem[];
+  /** Invoked when an enabled item is selected by keyboard or pointer. */
+  onselect?: (selection: ChatComposerPopoverSelection<TItem>) => void;
+  /** Invoked when Escape, trigger loss, or outside pointerdown dismisses the popover. */
+  ondismiss?: () => void;
+};

package/src/components/chat-composer-popover/chat-composer-popover.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/chat-composer-popover/chat-composer-popover.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/chat-composer-popover/index.ts

@@ -0,0 +1,19 @@
+import './chat-composer-popover.css';
+import ChatComposerPopover from './chat-composer-popover.svelte';
+
+export default ChatComposerPopover;
+export {
+  filterFuzzySubsequence,
+  fuzzySubsequenceScore,
+  type FuzzyFilterItem,
+  type FuzzyFilterResult,
+} from './chat-composer-popover-filter.ts';
+export type {
+  ChatComposerPopoverComposerProps,
+  ChatComposerPopoverItem,
+  ChatComposerPopoverItemSnippetContext,
+  ChatComposerPopoverProps,
+  ChatComposerPopoverSelection,
+  ChatComposerPopoverTriggerMatch,
+} from './chat-composer-popover.types.ts';
+export { ChatComposerPopover };

package/src/components/code-block/code-block.schema.json

@@ -18,6 +18,10 @@
       "type": "boolean",
       "description": "When true, render a copy button in the header."
     },
+    "showLanguageLabel": {
+      "type": "boolean",
+      "description": "Whether to render the language label in the header. Default `true`.\nPass `false` to keep `language`-driven highlighting without the visible\nheader chip; with `copyable` also unset, no header renders at all."
+    },
     "class": {
       "type": "string",
       "description": "Additional class names merged with `.cinder-code-block`."

package/src/components/code-block/code-block.schema.ts

@@ -22,6 +22,11 @@ const schema = {
       type: 'boolean',
       description: 'When true, render a copy button in the header.',
     },
+    showLanguageLabel: {
+      type: 'boolean',
+      description:
+        'Whether to render the language label in the header. Default `true`.\nPass `false` to keep `language`-driven highlighting without the visible\nheader chip; with `copyable` also unset, no header renders at all.',
+    },
     class: {
       type: 'string',
       description: 'Additional class names merged with `.cinder-code-block`.',

package/src/components/code-block/code-block.svelte

@@ -7,7 +7,7 @@ import { loadDefaultHighlighter } from './code-block-default-highlighter.ts';
 import { classNames } from '../../utilities/class-names.ts';
 import { devWarn } from '../../utilities/dev-warn.ts';
 import CopyButton from '../copy-button/copy-button.svelte';
-let { code, language, highlight, highlighter, copyable = false, class: className, } = $props();
+let { code, language, highlight, highlighter, copyable = false, showLanguageLabel = true, class: className, } = $props();
 let highlighted = $state(null);
 // Two-phase render contract: the server (and the first client paint) emits
 // the plain `<pre><code>` fallback because `$effect` never runs during SSR.
@@ -70,9 +70,9 @@ $effect(() => {
 </script>
 
 <div class={classNames('cinder-code-block', className)}>
-  {#if language || copyable}
+  {#if (language && showLanguageLabel) || copyable}
     <header class="cinder-code-block__header">
-      {#if language}
+      {#if language && showLanguageLabel}
         <span class="cinder-code-block__language">{language}</span>
       {/if}
       {#if copyable}

package/src/components/code-block/code-block.types.ts

@@ -49,6 +49,12 @@ export type CodeBlockProps = {
   highlighter?: Highlighter;
   /** When true, render a copy button in the header. */
   copyable?: boolean;
+  /**
+   * Whether to render the language label in the header. Default `true`.
+   * Pass `false` to keep `language`-driven highlighting without the visible
+   * header chip; with `copyable` also unset, no header renders at all.
+   */
+  showLanguageLabel?: boolean;
   /** Additional class names merged with `.cinder-code-block`. */
   class?: string;
 };

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

@@ -15,8 +15,9 @@ const commandList = getCommandListContext();
 // CommandMenu items can opt into parent-owned activation. Read untracked
 // because this is a one-time discard, not a reactive dependency.
 void untrack(() => selectionMode);
-// Stable id assigned by the palette on registration.
-let itemId = $state(null);
+// Live id assigned by the parent command list on registration.
+let registrationHandle = $state(null);
+const itemId = $derived(registrationHandle?.id ?? null);
 // Register with the palette at attach time, unregister on detach. Using an
 // attachment (rather than onMount) means the DOM node is available at
 // registration, so the palette can sort items by document order for
@@ -26,15 +27,15 @@ const registerWithPalette = (node) => {
     // call mutates the palette's $state registrations list, which feeds derived
     // values the attachment indirectly depends on — producing an update cycle.
     return untrack(() => {
-        const { id, unregister } = commandList.register({
+        const registeredItem = commandList.register({
             getValue: () => value,
             getOnselect: () => onselect,
             getDisabled: () => disabled,
         }, node);
-        itemId = id;
+        registrationHandle = registeredItem;
         return () => {
-            unregister();
-            itemId = null;
+            registeredItem.unregister();
+            registrationHandle = null;
         };
     });
 };

package/src/components/command-menu/command-menu.schema.json

@@ -2,6 +2,10 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
+    "listboxId": {
+      "type": "string",
+      "description": "Stable listbox id. Defaults to a generated component id."
+    },
     "open": {
       "type": "boolean",
       "description": "Open state. Bindable. Default `false`."

package/src/components/command-menu/command-menu.schema.ts

@@ -4,6 +4,10 @@ const schema = {
   $schema: 'https://json-schema.org/draft/2020-12/schema',
   type: 'object',
   properties: {
+    listboxId: {
+      type: 'string',
+      description: 'Stable listbox id. Defaults to a generated component id.',
+    },
     open: {
       type: 'boolean',
       description: 'Open state. Bindable. Default `false`.',