@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/color-swatch-picker/color-swatch-picker.svelte

@@ -15,7 +15,7 @@
 </script>
 
 <script lang="ts">
-  import type { ColorSwatchPickerProps } from './color-swatch-picker.types.ts';
+  import type { ColorSwatch, ColorSwatchPickerProps } from './color-swatch-picker.types.ts';
   import { tick, untrack } from 'svelte';
 
   import { classNames } from '../../utilities/class-names.ts';
@@ -43,6 +43,31 @@
   let internalValue = $state(untrack(() => defaultValue) ?? '');
   const selected = $derived(value ?? internalValue);
 
+  // Deduplicate swatches by color (first occurrence wins) so the keyed {#each}
+  // never receives duplicate keys and Svelte cannot throw each_key_duplicate.
+  // A dev warning is emitted when duplicates are found so the data author can fix
+  // their input, but the component continues to render the deduplicated list.
+  const renderableColors = $derived.by(() => {
+    const seen = new Set<string>();
+    const result: ColorSwatch[] = [];
+    let hasDuplicates = false;
+    for (const swatch of colors) {
+      if (seen.has(swatch.color)) {
+        hasDuplicates = true;
+      } else {
+        seen.add(swatch.color);
+        result.push(swatch);
+      }
+    }
+    if (hasDuplicates) {
+      devWarn(
+        '[ColorSwatchPicker] Duplicate color values detected in palette. ' +
+          'Only the first matching swatch will be shown as selected. Duplicates were removed.',
+      );
+    }
+    return result;
+  });
+
   // Track focus index driven by user interaction. null = derive from selection.
   let userFocusIndex = $state<number | null>(null);
 
@@ -53,25 +78,25 @@
   });
 
   const effectiveFocusIndex = $derived.by(() => {
-    if (colors.length === 0) return -1;
+    if (renderableColors.length === 0) return -1;
 
     // 1. User-driven focus if it points to a valid, non-item-disabled option.
     if (
       userFocusIndex !== null &&
-      userFocusIndex < colors.length &&
-      !colors[userFocusIndex]?.disabled
+      userFocusIndex < renderableColors.length &&
+      !renderableColors[userFocusIndex]?.disabled
     ) {
       return userFocusIndex;
     }
 
     // 2. Currently selected swatch if it exists and is not item-disabled.
-    const selectedIndex = colors.findIndex((s) => s.color === selected);
-    if (selectedIndex !== -1 && !colors[selectedIndex]?.disabled) {
+    const selectedIndex = renderableColors.findIndex((s) => s.color === selected);
+    if (selectedIndex !== -1 && !renderableColors[selectedIndex]?.disabled) {
       return selectedIndex;
     }
 
     // 3. First non-item-disabled option.
-    const firstEnabled = colors.findIndex((s) => !s.disabled);
+    const firstEnabled = renderableColors.findIndex((s) => !s.disabled);
     if (firstEnabled !== -1) return firstEnabled;
 
     // 4. First option in DOM order (ensures the control always has a tab stop).
@@ -82,19 +107,19 @@
   let liRefs: (HTMLLIElement | null)[] = $state([]);
 
   // Index of the first swatch (by DOM order) matching `selected` — for aria-selected.
-  const selectedIndex = $derived(colors.findIndex((s) => s.color === selected));
+  const selectedIndex = $derived(renderableColors.findIndex((s) => s.color === selected));
 
   function isItemDisabledForRoving(index: number): boolean {
-    return colors[index]?.disabled === true;
+    return renderableColors[index]?.disabled === true;
   }
 
   function isInteractive(index: number): boolean {
-    return !disabled && !colors[index]?.disabled;
+    return !disabled && !renderableColors[index]?.disabled;
   }
 
   function selectSwatch(index: number): void {
     if (!isInteractive(index)) return;
-    const swatch = colors[index];
+    const swatch = renderableColors[index];
     if (!swatch) return;
     internalValue = swatch.color;
     onchange?.(swatch.color);
@@ -112,7 +137,7 @@
       return;
     }
 
-    const newIndex = handleRovingKeydown(event, effectiveFocusIndex, colors.length, {
+    const newIndex = handleRovingKeydown(event, effectiveFocusIndex, renderableColors.length, {
       vertical: true,
       horizontal: layout === 'grid',
       isDisabled: isItemDisabledForRoving,
@@ -133,17 +158,6 @@
     userFocusIndex = index;
     selectSwatch(index);
   }
-
-  // Warn in dev mode when duplicate colors appear in the palette.
-  $effect(() => {
-    const colorValues = colors.map((c) => c.color);
-    if (new Set(colorValues).size !== colorValues.length) {
-      devWarn(
-        '[ColorSwatchPicker] Duplicate color values detected in palette. ' +
-          'Only the first matching swatch will be shown as selected.',
-      );
-    }
-  });
 </script>
 
 <ul
@@ -157,7 +171,7 @@
   data-cinder-layout={layout}
   onkeydown={handleKeydown}
 >
-  {#each colors as swatch, index (swatch.color + index)}
+  {#each renderableColors as swatch, index (swatch.color)}
     {@const isSelected = index === selectedIndex}
     {@const isDisabled = swatch.disabled === true}
     {@const contrastColor = pickContrastColor(swatch.color)}

package/src/components/combobox/README.md

@@ -21,16 +21,17 @@ Filterable dropdown that combines a text input with a selectable option list.
 | `aria-describedby`  | `string`   | no       | —       | External element id(s) to compose into `aria-describedby`. Composed after the component-generated description and error ids, matching the field-control contract in Select. Useful for tooltip ids, counter ids, or any external hint. |
 | `class`             | `string`   | no       | —       | Additional class names merged with `.cinder-combobox`.                                                                                                                                                                                 |
 | `description`       | `string`   | no       | —       | Helper text displayed below the input; wired via aria-describedby.                                                                                                                                                                     |
-| `disabled`          | `boolean`  | no       | —       | Disables the combobox.                                                                                                                                                                                                                 |
+| `disabled`          | `boolean`  | no       | —       | Disables the combobox. Inherited from a wrapping FormField when unset.                                                                                                                                                                 |
 | `error`             | `string`   | no       | —       | Validation error message; sets aria-invalid="true".                                                                                                                                                                                    |
 | `id`                | `string`   | yes      | —       | Unique identifier — required for label association and ARIA wiring.                                                                                                                                                                    |
 | `inputValue`        | `string`   | no       | —       | Free-text input value (the text the user has typed). Bindable.                                                                                                                                                                         |
 | `label`             | `string`   | no       | —       | Visible label rendered in a `<label>` associated via `for`.                                                                                                                                                                            |
 | `maxVisibleOptions` | `number`   | no       | —       | Hard cap on visible filtered options. Default 200.                                                                                                                                                                                     |
 | `placeholder`       | `string`   | no       | —       | Placeholder when no value is selected.                                                                                                                                                                                                 |
-| `filter`            | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                             |
-| `options`           | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                |
-| `value`             | `(opaque)` | no       | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                               |
+| `required`          | `boolean`  | no       | —       | Marks the field required: renders the required marker on the label and sets `aria-required` on the input. Inherited from a wrapping FormField when unset.                                                                              |
+| `filter`            | `(opaque)` | no       | —       | Custom synchronous filter. Receives an option and the current input value; returns true to keep. Defaults to case-insensitive substring match on label. Not expressible in JSON Schema; see the component types for the signature.     |
+| `options`           | `(opaque)` | yes      | —       | Full set of options to filter. The sole inference source for T. Not expressible in JSON Schema; see the component types for the signature.                                                                                             |
+| `value`             | `(opaque)` | no       | —       | Currently selected value. Bindable. `''` when nothing is selected. Not expressible in JSON Schema; see the component types for the signature.                                                                                          |
 
 <!-- generated:props:end -->
 

package/src/components/combobox/combobox.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic combobox",
       "description": "Type to filter; the list is filtered with a case-insensitive substring match.",
-      "code": "<script lang=\"ts\">\n  import { Combobox } from '@lostgradient/cinder/combobox';\n  const fruits = [\n    { value: 'apple', label: 'Apple' },\n    { value: 'apricot', label: 'Apricot' },\n    { value: 'banana', label: 'Banana' },\n    { value: 'blackberry', label: 'Blackberry' },\n    { value: 'cherry', label: 'Cherry' },\n    { value: 'grape', label: 'Grape' },\n    { value: 'mango', label: 'Mango' },\n    { value: 'peach', label: 'Peach' },\n    { value: 'pineapple', label: 'Pineapple' },\n    { value: 'raspberry', label: 'Raspberry' },\n  ];\n\n  let selected = $state('');\n</script>\n\n<Combobox\n  id=\"combobox-fruit\"\n  label=\"Favorite fruit\"\n  placeholder=\"Start typing…\"\n  options={fruits}\n  bind:value={selected}\n/>\n"
+      "code": "<script lang=\"ts\">\n  import { Combobox } from '@lostgradient/cinder/combobox';\n\n  const fruits = [\n    { value: 'apple', label: 'Apple' },\n    { value: 'apricot', label: 'Apricot' },\n    { value: 'banana', label: 'Banana' },\n    { value: 'blackberry', label: 'Blackberry' },\n    { value: 'cherry', label: 'Cherry' },\n    { value: 'grape', label: 'Grape' },\n    { value: 'mango', label: 'Mango' },\n    { value: 'peach', label: 'Peach' },\n    { value: 'pineapple', label: 'Pineapple' },\n    { value: 'raspberry', label: 'Raspberry' },\n  ];\n\n  let selected = $state('');\n</script>\n\n<Combobox\n  id=\"fruit\"\n  label=\"Favorite fruit\"\n  placeholder=\"Start typing…\"\n  options={fruits}\n  bind:value={selected}\n/>\n"
     },
     {
       "id": "disabled",

package/src/components/combobox/combobox.svelte

@@ -19,12 +19,9 @@
   import type { ComboboxOption, ComboboxProps } from './combobox.types.ts';
   import { untrack } from 'svelte';
 
-  import {
-    ariaInvalid,
-    composeDescribedBy,
-    describeId,
-    errorId as buildErrorId,
-  } from '../../_internal/field-control.ts';
+  import { resolveFieldControl } from '../../_internal/field-control.ts';
+  import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+  import { pushEscapeHandler } from '../../_internal/overlay.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import Popover from '../popover/popover.svelte';
 
@@ -38,17 +35,38 @@
     filter,
     description,
     error,
-    disabled = false,
+    disabled,
+    required,
     maxVisibleOptions = 200,
     class: className,
     'aria-describedby': consumerDescribedBy,
   }: ComboboxProps<T> = $props();
 
+  const context = getFormFieldContext();
+  const field = $derived(
+    resolveFieldControl({
+      id,
+      generatedId: id,
+      context,
+      hasDescription: !!description,
+      hasError: !!error,
+      localIdNamespace: 'combobox',
+      consumerDescribedBy,
+      required,
+      disabled,
+    }),
+  );
+  const resolvedDisabled = $derived(field.disabled);
+  const resolvedRequired = $derived(field.required);
+  const describedBy = $derived(field.describedBy);
+
   const listboxId = $derived(`${id}-listbox`);
-  const descriptionId = $derived(describeId(id, !!description));
-  // errId only included in aria-describedby when error is active.
-  const errId = $derived(buildErrorId(id, !!error));
-  const describedBy = $derived(composeDescribedBy(descriptionId, errId, consumerDescribedBy));
+  const descriptionId = $derived(field.ownDescriptionId);
+  // Stable id for the always-in-DOM error live region when no error is active.
+  // Mirrors Select: avoids colliding with a wrapping FormField's error id.
+  const stableLocalErrorId = $derived(
+    context?.errorId === `${field.id}-error` ? `${field.id}-combobox-error` : `${field.id}-error`,
+  );
 
   const defaultFilter = (option: ComboboxOption<T>, query: string): boolean => {
     if (!query) return true;
@@ -75,6 +93,7 @@
   let activeIndex = $state(-1);
   let inputElement = $state<HTMLInputElement | null>(null);
   let listboxElement = $state<HTMLElement | null>(null);
+  let committedLabel = $state('');
 
   // Reset active index whenever the filtered set changes so we don't point
   // at a stale option.
@@ -92,12 +111,55 @@
       // Clearing the value (deselect/reset) must also clear the visible text;
       // otherwise the input keeps showing the previously selected option's label.
       if (untrack(() => inputValue)) inputValue = '';
+      committedLabel = '';
       return;
     }
     const matched = options.find((option) => option.value === value);
-    if (matched && untrack(() => inputValue) !== matched.label) {
-      inputValue = matched.label;
+    if (matched) {
+      // `committedLabel` tracks the committed `value`'s label and must stay in
+      // sync whenever a match exists — even when `inputValue` already shows that
+      // label. Gating it behind the `inputValue !== matched.label` check left
+      // `committedLabel` stale (''), so a later Escape restored to empty text.
+      committedLabel = matched.label;
+      if (untrack(() => inputValue) !== matched.label) {
+        inputValue = matched.label;
+      }
+    }
+  });
+
+  // Escape ownership.
+  //
+  // The combobox is the single Escape owner for the whole time it is open. The
+  // option Popover is told `closeOnEscape={false}`, so it never registers its
+  // own escape-stack handler — otherwise, while options are visible, the
+  // Popover's handler would sit on top of the shared LIFO stack and shadow this
+  // one. With the Popover opting out, this combobox's handler is the top-most
+  // Escape consumer for the entire open session, including the empty-filter gap
+  // (`open && filteredOptions.length === 0`) where the Popover is unmounted.
+  //
+  // That matters most when the combobox is nested inside a Modal/Sheet: the
+  // shared escape stack's window listener is capture-phase and invokes ONLY its
+  // top handler, so this combobox consumes Escape and `preventDefault()`s it
+  // before the parent overlay ever sees the key — Escape dismisses just the
+  // combobox, never the enclosing overlay.
+  function handleEscape(event: KeyboardEvent | undefined = undefined): void {
+    const wasOpen = open;
+    open = false;
+    // Restore the committed label whenever the live text drifted from it.
+    if (inputValue !== committedLabel) {
+      inputValue = committedLabel;
+      if (inputElement) inputElement.value = committedLabel;
     }
+    // Swallow the key if the combobox actually consumed this Escape (it was
+    // open) so the same keystroke doesn't also dismiss an enclosing overlay or
+    // trigger a page-level default.
+    if (wasOpen) event?.preventDefault();
+  }
+
+  $effect(() => {
+    if (!open) return;
+    const releaseEscape = pushEscapeHandler(handleEscape);
+    return releaseEscape;
   });
 
   const activeOptionId = $derived(
@@ -114,7 +176,7 @@
   }
 
   function handleFocus() {
-    if (!disabled) open = true;
+    if (!resolvedDisabled) open = true;
   }
 
   function handleBlur(event: FocusEvent) {
@@ -124,12 +186,20 @@
     const next = event.relatedTarget as Node | null;
     if (next && listboxElement?.contains(next)) return;
     open = false;
+    // Restore the committed label if the live text drifted from it. Leaving the
+    // field on a stale edit (without selecting an option) would desync the
+    // visible text from the unchanged `value` — the same mismatch Escape fixes.
+    if (inputValue !== committedLabel) {
+      inputValue = committedLabel;
+      if (inputElement) inputElement.value = committedLabel;
+    }
   }
 
   function selectOption(option: ComboboxOption<T>) {
     if (option.disabled) return;
     value = option.value;
     inputValue = option.label;
+    committedLabel = option.label;
     open = false;
   }
 
@@ -159,18 +229,25 @@
         selectOption(option);
       }
     } else if (event.key === 'Escape') {
-      if (open) {
-        event.preventDefault();
-        open = false;
-      }
+      // Fallback path. In a real browser the capture-phase escape-stack listener
+      // (installed by the $effect's pushEscapeHandler) runs first and has
+      // already closed + restored + preventDefault'd; `defaultPrevented` is true
+      // here and we bail. This branch only does real work when the stack
+      // listener never ran — SSR/no-window environments where `window` is
+      // absent so `pushEscapeHandler` installed nothing.
+      if (event.defaultPrevented) return;
+      handleEscape(event);
     }
   }
 </script>
 
 <div class={classNames('cinder-combobox', className)}>
   {#if label}
-    <label for={id} class="cinder-combobox__label" data-disabled={disabled || undefined}>
+    <label for={id} class="cinder-combobox__label" data-disabled={resolvedDisabled || undefined}>
       {label}
+      {#if resolvedRequired}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
     </label>
   {/if}
 
@@ -184,14 +261,15 @@
       autocomplete="off"
       autocorrect="off"
       spellcheck="false"
-      {disabled}
+      disabled={resolvedDisabled}
       {placeholder}
       value={inputValue}
       aria-autocomplete="list"
       aria-expanded={open}
       aria-controls={listboxId}
       aria-activedescendant={activeOptionId}
-      aria-invalid={ariaInvalid(!!error)}
+      aria-invalid={field.ariaInvalid}
+      aria-required={resolvedRequired || undefined}
       aria-describedby={describedBy}
       oninput={handleInput}
       onfocus={handleFocus}
@@ -208,6 +286,7 @@
       role="listbox"
       focusManagement="preserve"
       wireTriggerAria={false}
+      closeOnEscape={false}
       widthMode="match-anchor"
       class="cinder-combobox__panel"
     >
@@ -267,7 +346,7 @@
 
   <!-- Always in DOM for the same reason — live region must pre-exist before text is injected. -->
   <p
-    id="{id}-error"
+    id={field.ownErrorId ?? stableLocalErrorId}
     class="cinder-combobox__error"
     aria-live="polite"
     data-cinder-error={!!error || undefined}

package/src/components/combobox/combobox.types.ts

@@ -56,8 +56,14 @@ export type ComboboxProps<T extends string = string> = {
   description?: string;
   /** Validation error message; sets aria-invalid="true". */
   error?: string;
-  /** Disables the combobox. */
+  /** Disables the combobox. Inherited from a wrapping FormField when unset. */
   disabled?: boolean;
+  /**
+   * Marks the field required: renders the required marker on the label and
+   * sets `aria-required` on the input. Inherited from a wrapping FormField
+   * when unset.
+   */
+  required?: boolean;
   /** Hard cap on visible filtered options. Default 200. */
   maxVisibleOptions?: number;
   /**

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

@@ -16,17 +16,19 @@ Individual selectable row within a command palette or dropdown command list.
 
 <!-- generated:props:start -->
 
-| Prop            | Type                   | Required | Default | Description                                                                                                                |
-| --------------- | ---------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`         | `string`               | no       | —       | Class merged with `.cinder-command-item`.                                                                                  |
-| `description`   | `string`               | no       | —       | Optional secondary text shown below the main label.                                                                        |
-| `disabled`      | `boolean`              | no       | —       | When true, the item is skipped by arrow keys and cannot be activated.                                                      |
-| `selectionMode` | `"item"` \| `"parent"` | no       | —       | The item owns activation. This is the default CommandPalette mode.                                                         |
-| `value`         | `string`               | yes      | —       | Submitted value; surfaced through the registration record.                                                                 |
-| `children`      | `(opaque)`             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `leading`       | `(opaque)`             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onselect`      | `(opaque)`             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `trailing`      | `(opaque)`             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop               | Type                   | Required | Default | Description                                                                                                                               |
+| ------------------ | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `accessibleLabel`  | `string`               | no       | —       | Accessible name for the option when the rendered row contains secondary text or rich content.                                             |
+| `class`            | `string`               | no       | —       | Class merged with `.cinder-command-item`.                                                                                                 |
+| `description`      | `string`               | no       | —       | Optional secondary text shown below the main label.                                                                                       |
+| `disabled`         | `boolean`              | no       | —       | When true, the item is skipped by arrow keys and cannot be activated.                                                                     |
+| `keyboardShortcut` | `string`               | no       | —       | Keyboard shortcut exposed through `aria-keyshortcuts`, e.g. `Meta+N`.                                                                     |
+| `selectionMode`    | `"item"` \| `"parent"` | no       | —       | The item owns activation. This is the default CommandPalette mode.                                                                        |
+| `value`            | `string`               | yes      | —       | Submitted value; surfaced through the registration record.                                                                                |
+| `children`         | `(opaque)`             | yes      | —       | Main label content. Not expressible in JSON Schema; see the component types for the signature.                                            |
+| `leading`          | `(opaque)`             | no       | —       | Leading content (icon, avatar). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature.     |
+| `onselect`         | `(opaque)`             | no       | —       | Invoked when the item is activated inside CommandPalette. Not expressible in JSON Schema; see the component types for the signature.      |
+| `trailing`         | `(opaque)`             | no       | —       | Trailing content (kbd hint, badge). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

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

@@ -29,6 +29,16 @@
   .cinder-command-item[data-cinder-active] {
     background: var(--cinder-accent);
     color: var(--cinder-accent-contrast);
+    /* Keyboard-cursor ring for WCAG 1.4.11 (non-text contrast, ≥3:1). The ring
+       sits ON the accent fill, so it must contrast against --cinder-accent — NOT
+       against a neutral surface. --cinder-ring-color is engineered for ~4.5:1
+       against near-white surfaces and collapses to ~1.1–1.3:1 on the accent fill
+       (invisible), which is why the shared _floating-surface.css ring works there
+       (it sits on a neutral hover surface) but cannot be reused here verbatim.
+       --cinder-accent-contrast is the only token already proven to clear AA on the
+       accent fill (it is the text color on this fill; check-token-contrast.test.ts
+       gates it), giving ~6.5:1 (light) / ~7.8:1 (dark) for the ring. */
+    box-shadow: inset 0 0 0 1px var(--cinder-accent-contrast);
   }
 
   @media (forced-colors: active) {

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

@@ -36,6 +36,8 @@
     selectionMode = 'item',
     disabled = false,
     description,
+    accessibleLabel,
+    keyboardShortcut,
     leading,
     trailing,
     children,
@@ -77,6 +79,13 @@
   };
 
   const isActive = $derived(itemId !== null && commandList.activeItemId === itemId);
+  const normalizedAccessibleLabel = $derived(normalizeOptionalAttribute(accessibleLabel));
+  const normalizedKeyboardShortcut = $derived(normalizeOptionalAttribute(keyboardShortcut));
+
+  function normalizeOptionalAttribute(value: string | undefined): string | undefined {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+  }
 
   function handlePointerEnter() {
     if (!disabled && itemId !== null) {
@@ -104,6 +113,8 @@
   class={classNames('cinder-command-item', className)}
   aria-selected={isActive}
   aria-disabled={disabled || undefined}
+  aria-label={normalizedAccessibleLabel}
+  aria-keyshortcuts={normalizedKeyboardShortcut}
   data-cinder-active={isActive ? '' : undefined}
   data-cinder-disabled={disabled || undefined}
   onpointerenter={handlePointerEnter}

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

@@ -7,6 +7,10 @@ type CommandItemBaseProps = {
   disabled?: boolean;
   /** Optional secondary text shown below the main label. */
   description?: string;
+  /** Accessible name for the option when the rendered row contains secondary text or rich content. */
+  accessibleLabel?: string | undefined;
+  /** Keyboard shortcut exposed through `aria-keyshortcuts`, e.g. `Meta+N`. */
+  keyboardShortcut?: string | undefined;
   /** Leading content (icon, avatar). Rendered with aria-hidden. */
   leading?: Snippet;
   /** Trailing content (kbd hint, badge). Rendered with aria-hidden. */

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

@@ -26,21 +26,21 @@ Inline caret-anchored slash-command list for textareas and single-line text inpu
 
 <!-- generated:props:start -->
 
-| Prop            | Type                                                                                                                 | Required | Default | Description                                                                                                                |
-| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `caretIndex`    | `number`                                                                                                             | yes      | —       | Caret offset within the anchor value.                                                                                      |
-| `class`         | `string`                                                                                                             | no       | —       | Class merged with `.cinder-command-menu`.                                                                                  |
-| `label`         | `string`                                                                                                             | no       | —       | Accessible listbox label. Default `'Commands'`.                                                                            |
-| `offset`        | `number`                                                                                                             | no       | —       | Distance in px between the caret and menu. Default `6`.                                                                    |
-| `open`          | `boolean`                                                                                                            | no       | —       | Open state. Bindable. Default `false`.                                                                                     |
-| `placement`     | `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"top-start"` \| `"top-end"` \| `"bottom-start"` \| `"bottom-end"` | no       | —       | Caret-relative placement. Default `'bottom-start'`.                                                                        |
-| `query`         | `string`                                                                                                             | no       | —       | Query text after the trigger character. Bindable. Default `''`.                                                            |
-| `anchor`        | `(opaque)`                                                                                                           | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `empty`         | `(opaque)`                                                                                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `items`         | `(opaque)`                                                                                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `ondismiss`     | `(opaque)`                                                                                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onselect`      | `(opaque)`                                                                                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onstatechange` | `(opaque)`                                                                                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop            | Type                                                                                                                 | Required | Default | Description                                                                                                                               |
+| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `caretIndex`    | `number`                                                                                                             | yes      | —       | Caret offset within the anchor value.                                                                                                     |
+| `class`         | `string`                                                                                                             | no       | —       | Class merged with `.cinder-command-menu`.                                                                                                 |
+| `label`         | `string`                                                                                                             | no       | —       | Accessible listbox label. Default `'Commands'`.                                                                                           |
+| `offset`        | `number`                                                                                                             | no       | —       | Distance in px between the caret and menu. Default `6`.                                                                                   |
+| `open`          | `boolean`                                                                                                            | no       | —       | Open state. Bindable. Default `false`.                                                                                                    |
+| `placement`     | `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"top-start"` \| `"top-end"` \| `"bottom-start"` \| `"bottom-end"` | no       | —       | Caret-relative placement. Default `'bottom-start'`.                                                                                       |
+| `query`         | `string`                                                                                                             | no       | —       | Query text after the trigger character. Bindable. Default `''`.                                                                           |
+| `anchor`        | `(opaque)`                                                                                                           | yes      | —       | Text field used as the caret-position anchor. Not expressible in JSON Schema; see the component types for the signature.                  |
+| `empty`         | `(opaque)`                                                                                                           | no       | —       | Optional empty state rendered after item registration settles. Not expressible in JSON Schema; see the component types for the signature. |
+| `items`         | `(opaque)`                                                                                                           | yes      | —       | Render command items for the current query. Not expressible in JSON Schema; see the component types for the signature.                    |
+| `ondismiss`     | `(opaque)`                                                                                                           | no       | —       | Invoked when Escape or outside pointerdown dismisses the menu. Not expressible in JSON Schema; see the component types for the signature. |
+| `onselect`      | `(opaque)`                                                                                                           | no       | —       | Invoked when an enabled command is activated. Not expressible in JSON Schema; see the component types for the signature.                  |
+| `onstatechange` | `(opaque)`                                                                                                           | no       | —       | One-way state output for host-owned field ARIA. Not expressible in JSON Schema; see the component types for the signature.                |
 
 <!-- generated:props:end -->
 

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

@@ -7,7 +7,7 @@
       "id": "slash-in-textarea",
       "title": "Slash commands in a textarea",
       "description": "A caret-anchored command menu controlled by a textarea host.",
-      "code": "<script lang=\"ts\">\n  import { CommandItem } from '@lostgradient/cinder/command-item';\n  import { CommandMenu, detectTrigger } from '@lostgradient/cinder/command-menu';\n  import { Textarea } from '@lostgradient/cinder/textarea';\n\n  type Command = {\n    value: string;\n    label: string;\n    description: string;\n  };\n\n  const commands: Command[] = [\n    { value: 'summary', label: 'Summary', description: 'Insert a summary block.' },\n    { value: 'decision', label: 'Decision', description: 'Insert a decision marker.' },\n    { value: 'follow-up', label: 'Follow-up', description: 'Insert a follow-up item.' },\n    { value: 'code', label: 'Code', description: 'Insert a fenced code block.' },\n  ];\n\n  let value = $state('Type / to open commands.\\n');\n  let open = $state(false);\n  let query = $state('');\n  let caretIndex = $state(0);\n  let triggerRange = $state<{ start: number; end: number } | null>(null);\n  let anchor: HTMLTextAreaElement | null = $state(null);\n  let listboxId = $state<string | undefined>();\n  let activeItemId = $state<string | undefined>();\n\n  const filteredCommands = $derived(\n    commands.filter((command) => command.label.toLowerCase().includes(query.toLowerCase())),\n  );\n\n  function syncTrigger(field: HTMLTextAreaElement) {\n    anchor = field;\n    const match = detectTrigger({\n      text: field.value,\n      selectionStart: field.selectionStart,\n      selectionEnd: field.selectionEnd,\n    });\n\n    if (!match) {\n      open = false;\n      query = '';\n      triggerRange = null;\n      activeItemId = undefined;\n      return;\n    }\n\n    open = true;\n    query = match.query;\n    caretIndex = match.end;\n    triggerRange = { start: match.start, end: match.end };\n  }\n\n  function selectCommand(commandValue: string) {\n    const command = commands.find((item) => item.value === commandValue);\n    if (!command || !anchor || !triggerRange) return;\n\n    const replacement = command.value === 'code' ? '```ts\\n\\n```' : `[${command.label}]`;\n    value = `${value.slice(0, triggerRange.start)}${replacement}${value.slice(triggerRange.end)}`;\n    const nextCaretIndex = triggerRange.start + replacement.length;\n    open = false;\n    query = '';\n    triggerRange = null;\n\n    queueMicrotask(() => {\n      anchor?.focus();\n      anchor?.setSelectionRange(nextCaretIndex, nextCaretIndex);\n      caretIndex = nextCaretIndex;\n    });\n  }\n</script>\n\n<div style=\"display: grid; gap: var(--cinder-space-3); max-inline-size: 42rem;\">\n  <Textarea\n    id=\"command-menu-textarea\"\n    label=\"Notes\"\n    rows={8}\n    bind:value\n    aria-controls={open ? listboxId : undefined}\n    aria-activedescendant={open ? activeItemId : undefined}\n    aria-autocomplete=\"list\"\n    onfocus={(event) => syncTrigger(event.currentTarget as HTMLTextAreaElement)}\n    oninput={(event) => syncTrigger(event.currentTarget as HTMLTextAreaElement)}\n    onclick={(event) => syncTrigger(event.currentTarget as HTMLTextAreaElement)}\n    onkeyup={(event) => syncTrigger(event.currentTarget as HTMLTextAreaElement)}\n  />\n\n  <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n    Last query: {query || 'none'}\n  </p>\n</div>\n\n<CommandMenu\n  bind:open\n  bind:query\n  {anchor}\n  {caretIndex}\n  label=\"Slash commands\"\n  onselect={(selection) => selectCommand(selection.value)}\n  ondismiss={() => {\n    open = false;\n    query = '';\n    triggerRange = null;\n  }}\n  onstatechange={(state) => {\n    listboxId = state.listboxId;\n    activeItemId = state.activeItemId ?? undefined;\n  }}\n>\n  {#snippet items()}\n    {#each filteredCommands as command (command.value)}\n      <CommandItem value={command.value} description={command.description} selectionMode=\"parent\">\n        {command.label}\n      </CommandItem>\n    {/each}\n  {/snippet}\n\n  {#snippet empty()}\n    No commands match \"{query}\".\n  {/snippet}\n</CommandMenu>\n"
+      "code": "<script lang=\"ts\">\n  import { CommandItem } from '@lostgradient/cinder/command-item';\n  import { CommandMenu, detectTrigger } from '@lostgradient/cinder/command-menu';\n  import { Textarea } from '@lostgradient/cinder/textarea';\n\n  type Command = {\n    value: string;\n    label: string;\n    description: string;\n  };\n\n  const commands: Command[] = [\n    { value: 'summary', label: 'Summary', description: 'Insert a summary block.' },\n    { value: 'decision', label: 'Decision', description: 'Insert a decision marker.' },\n    { value: 'follow-up', label: 'Follow-up', description: 'Insert a follow-up item.' },\n    { value: 'code', label: 'Code', description: 'Insert a fenced code block.' },\n  ];\n\n  let value = $state('Type / to open commands.\\n');\n  let open = $state(false);\n  let query = $state('');\n  let caretIndex = $state(0);\n  let triggerRange = $state<{ start: number; end: number } | null>(null);\n  let anchor: HTMLTextAreaElement | null = $state(null);\n  let listboxId = $state<string | undefined>();\n  let activeItemId = $state<string | undefined>();\n\n  const filteredCommands = $derived(\n    commands.filter((command) => command.label.toLowerCase().includes(query.toLowerCase())),\n  );\n\n  function syncTrigger(field: HTMLTextAreaElement) {\n    anchor = field;\n    const match = detectTrigger({\n      text: field.value,\n      selectionStart: field.selectionStart,\n      selectionEnd: field.selectionEnd,\n    });\n\n    if (!match) {\n      open = false;\n      query = '';\n      triggerRange = null;\n      activeItemId = undefined;\n      return;\n    }\n\n    open = true;\n    query = match.query;\n    caretIndex = match.end;\n    triggerRange = { start: match.start, end: match.end };\n  }\n\n  function selectCommand(commandValue: string) {\n    const command = commands.find((item) => item.value === commandValue);\n    if (!command || !anchor || !triggerRange) return;\n\n    const replacement = command.value === 'code' ? '```ts\\n\\n```' : `[${command.label}]`;\n    value = `${value.slice(0, triggerRange.start)}${replacement}${value.slice(triggerRange.end)}`;\n    const nextCaretIndex = triggerRange.start + replacement.length;\n    open = false;\n    query = '';\n    triggerRange = null;\n\n    queueMicrotask(() => {\n      anchor?.focus();\n      anchor?.setSelectionRange(nextCaretIndex, nextCaretIndex);\n      caretIndex = nextCaretIndex;\n    });\n  }\n</script>\n\n<div style=\"display: grid; gap: var(--cinder-space-3); max-inline-size: 42rem;\">\n  <Textarea\n    id=\"field\"\n    label=\"Notes\"\n    rows={8}\n    bind:value\n    aria-controls={open ? listboxId : undefined}\n    aria-activedescendant={open ? activeItemId : undefined}\n    aria-autocomplete=\"list\"\n    onfocus={(event) => syncTrigger(event.currentTarget as HTMLTextAreaElement)}\n    oninput={(event) => syncTrigger(event.currentTarget as HTMLTextAreaElement)}\n    onclick={(event) => syncTrigger(event.currentTarget as HTMLTextAreaElement)}\n    onkeyup={(event) => syncTrigger(event.currentTarget as HTMLTextAreaElement)}\n  />\n\n  <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n    Last query: {query || 'none'}\n  </p>\n</div>\n\n<CommandMenu\n  bind:open\n  bind:query\n  {anchor}\n  {caretIndex}\n  label=\"Slash commands\"\n  onselect={(selection) => selectCommand(selection.value)}\n  ondismiss={() => {\n    open = false;\n    query = '';\n    triggerRange = null;\n  }}\n  onstatechange={(state) => {\n    listboxId = state.listboxId;\n    activeItemId = state.activeItemId ?? undefined;\n  }}\n>\n  {#snippet items()}\n    {#each filteredCommands as command (command.value)}\n      <CommandItem value={command.value} description={command.description} selectionMode=\"parent\">\n        {command.label}\n      </CommandItem>\n    {/each}\n  {/snippet}\n\n  {#snippet empty()}\n    No commands match \"{query}\".\n  {/snippet}\n</CommandMenu>\n"
     }
   ]
 }