@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/color-swatch-picker/README.md

@@ -16,19 +16,19 @@ Presents a fixed palette of color swatches for constrained color selection.
 
 <!-- generated:props:start -->
 
-| Prop           | Type                                           | Required | Default | Description                                                                                                                                                                                                       |
-| -------------- | ---------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`                                       | no       | —       | Additional classes merged into the listbox `<ul>`.                                                                                                                                                                |
-| `defaultValue` | `string`                                       | no       | —       | Initial selected color for uncontrolled use. Ignored when `value` is set.                                                                                                                                         |
-| `disabled`     | `boolean`                                      | no       | —       | Disables the entire listbox. Keyboard activation and clicks are ignored.                                                                                                                                          |
-| `label`        | `string`                                       | yes      | —       | Accessible name for the listbox. Required — `role="listbox"` needs a label so screen readers can announce the control's purpose.                                                                                  |
-| `layout`       | `"grid"` \| `"stack"`                          | no       | —       | Layout direction. Default `'grid'`. Note: grid layout uses one-dimensional DOM-order navigation for both ArrowLeft/Right and ArrowUp/Down. True column-aware navigation is not implemented in v1 — see a11y memo. |
-| `shape`        | `"circle"` \| `"square"`                       | no       | —       | Visual shape of each swatch. Default `'circle'`.                                                                                                                                                                  |
-| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | no       | —       | Swatch dimension token. Default `'md'`.                                                                                                                                                                           |
-| `value`        | `string`                                       | no       | —       | Controlled selected color. When provided, the parent owns the state.                                                                                                                                              |
-| `colors`       | `(opaque)`                                     | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                           |
-| `indicator`    | `(opaque)`                                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                        |
-| `onchange`     | `(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                                                                                                                                                                                                                        |
+| -------------- | ---------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`                                       | no       | —       | Additional classes merged into the listbox `<ul>`.                                                                                                                                                                                 |
+| `defaultValue` | `string`                                       | no       | —       | Initial selected color for uncontrolled use. Ignored when `value` is set.                                                                                                                                                          |
+| `disabled`     | `boolean`                                      | no       | —       | Disables the entire listbox. Keyboard activation and clicks are ignored.                                                                                                                                                           |
+| `label`        | `string`                                       | yes      | —       | Accessible name for the listbox. Required — `role="listbox"` needs a label so screen readers can announce the control's purpose.                                                                                                   |
+| `layout`       | `"grid"` \| `"stack"`                          | no       | —       | Layout direction. Default `'grid'`. Note: grid layout uses one-dimensional DOM-order navigation for both ArrowLeft/Right and ArrowUp/Down. True column-aware navigation is not implemented in v1 — see a11y memo.                  |
+| `shape`        | `"circle"` \| `"square"`                       | no       | —       | Visual shape of each swatch. Default `'circle'`.                                                                                                                                                                                   |
+| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | no       | —       | Swatch dimension token. Default `'md'`.                                                                                                                                                                                            |
+| `value`        | `string`                                       | no       | —       | Controlled selected color. When provided, the parent owns the state.                                                                                                                                                               |
+| `colors`       | `(opaque)`                                     | yes      | —       | Palette to render. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                      |
+| `indicator`    | `(opaque)`                                     | no       | —       | Snippet that replaces the default check-icon indicator on the selected swatch. Receives the active swatch and the computed contrast color for the icon. Not expressible in JSON Schema; see the component types for the signature. |
+| `onchange`     | `(opaque)`                                     | no       | —       | Fired when the selected swatch changes. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                 |
 
 <!-- generated:props:end -->
 

package/src/components/combobox/README.md

@@ -28,9 +28,9 @@ Filterable dropdown that combines a text input with a selectable option list.
 | `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.                                                                                                               |
+| `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

@@ -25,6 +25,7 @@
     describeId,
     errorId as buildErrorId,
   } from '../../_internal/field-control.ts';
+  import { pushEscapeHandler } from '../../_internal/overlay.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import Popover from '../popover/popover.svelte';
 
@@ -75,6 +76,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,14 +94,57 @@
       // 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): 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(
     activeIndex >= 0 && activeIndex < filteredOptions.length
       ? `${id}-option-${activeIndex}`
@@ -124,12 +169,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,10 +212,14 @@
         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>
@@ -208,6 +265,7 @@
       role="listbox"
       focusManagement="preserve"
       wireTriggerAria={false}
+      closeOnEscape={false}
       widthMode="match-anchor"
       class="cinder-combobox__panel"
     >

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

@@ -16,17 +16,17 @@ 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                                                                                                                               |
+| --------------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `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)`             | 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-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"
     }
   ]
 }

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

@@ -41,11 +41,11 @@ Command items register with the palette by DOM node, so grouped results can use
 | `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       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                          |
-| `footer`      | `(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.                                                                                                                          |
-| `onclose`     | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                          |
-| `triggerRef`  | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                             |
+| `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.css

@@ -68,8 +68,30 @@
     gap: var(--cinder-space-3);
     min-block-size: 4.5rem;
     padding-inline: var(--cinder-space-5);
-    border-block-end: 1px solid var(--cinder-border);
+    /* Focus indication lives on this row, anchored to its visible bottom edge,
+       rather than a 3px box-shadow ring floating around the edgeless input. The
+       border is 2px AT REST so focusing only changes its COLOR — no width change,
+       so the option list below never shifts.
+
+       :focus-within (below) is correct here precisely because this row's ONLY
+       focusable child is the text <input> — there are no buttons in the search
+       row — and a text input always merits a visible focus indication regardless
+       of input modality (the UA's :focus-visible heuristic always matches a
+       focused text field). So :focus-within and :has(input:focus-visible) behave
+       identically for this row; :focus-within is the simpler, support-safe form. */
+    border-block-end: 2px solid var(--cinder-border);
     flex-shrink: 0;
+    transition: border-color var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  .cinder-command-palette__search:focus-within {
+    border-block-end-color: var(--cinder-ring-color);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-command-palette__search:focus-within {
+      border-block-end-color: Highlight;
+    }
   }
 
   .cinder-command-palette__search-icon {
@@ -87,20 +109,12 @@
     font-size: var(--cinder-text-base);
     line-height: var(--cinder-leading-normal);
     padding-block: var(--cinder-space-4);
+    /* No ring on the input itself — the search row's :focus-within bottom border
+       is the focus indicator (the input is edgeless, so a box ring reads as a
+       stray floating box). */
     outline: none;
   }
 
-  .cinder-command-palette__input:focus-visible {
-    outline: var(--cinder-ring-width) solid transparent;
-    box-shadow: var(--_cinder-focus-ring-shadow);
-  }
-
-  @media (forced-colors: active) {
-    .cinder-command-palette__input:focus-visible {
-      outline: var(--cinder-ring-width) solid ButtonText;
-    }
-  }
-
   .cinder-command-palette__input::placeholder {
     color: var(--cinder-text-muted);
   }

package/src/components/confirm-dialog/README.md

@@ -15,13 +15,13 @@ The key distinction between ConfirmDialog and AlertDialog is _who initiates_ the
 - ConfirmDialog is for user-initiated actions that need a safety gate ("You clicked Delete — are you sure?"). Escape is a safe exit; cancel is the default focus.
 - AlertDialog is for system-initiated or out-of-band urgency ("Your session expired", "This action affects others"). Escape is blocked; acknowledgement is mandatory.
 
-## When to use
+## Choosing this component
 
 - Asking the user to confirm before deleting, discarding, or publishing something that cannot easily be undone.
 - Any two-action flow where the only choices are "proceed" and "cancel" — ConfirmDialog saves you from composing Modal + two Buttons manually.
 - Destructive actions: set `destructive` to apply the danger variant to the confirm button.
 
-## When not to use
+## Choosing something else
 
 - When the dialog body needs rich content (lists, markup, multiple paragraphs) — compose [`Modal`](../modal/README.md) directly instead, since `aria-describedby` collapses to a single continuous string for screen readers.
 - When more than two actions are needed — use [`Modal`](../modal/README.md) with a custom `footer` snippet.
@@ -47,18 +47,18 @@ The key distinction between ConfirmDialog and AlertDialog is _who initiates_ the
 
 <!-- generated:props:start -->
 
-| Prop           | Type       | Required | Default | Description                                                                                                                                                                                                                                                                         |
-| -------------- | ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cancelLabel`  | `string`   | no       | —       | Cancel button label. Defaults to "Cancel".                                                                                                                                                                                                                                          |
-| `class`        | `string`   | no       | —       | Optional extra class on the underlying <Modal>. Destructured as `class: className` per repo convention.                                                                                                                                                                             |
-| `confirmLabel` | `string`   | yes      | —       | Confirm button label. Required — no default. Name the action being confirmed: - Destructive: "Delete", "Discard changes", "Remove from organization". - Non-destructive: "Save", "Continue", "Publish". Never use "OK" or "Confirm" in production — they don't describe the action. |
-| `description`  | `string`   | no       | —       | Optional body description — short, plain text only. Rendered as a single <p> and wired to aria-describedby. For rich content (markup, lists, multiple paragraphs), compose <Modal> + <Button> directly — screen readers announce aria-describedby targets as one continuous run.    |
-| `destructive`  | `boolean`  | no       | —       | When true, the confirm button uses variant="danger". The cancel button still receives default focus regardless — color is never the sole destructive signal.                                                                                                                        |
-| `open`         | `boolean`  | yes      | —       | Controls visibility. Bindable.                                                                                                                                                                                                                                                      |
-| `title`        | `string`   | yes      | —       | Modal title; passed through to <Modal>.                                                                                                                                                                                                                                             |
-| `oncancel`     | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                          |
-| `onconfirm`    | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                          |
-| `triggerRef`   | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                             |
+| Prop           | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                                             |
+| -------------- | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cancelLabel`  | `string`   | no       | —       | Cancel button label. Defaults to "Cancel".                                                                                                                                                                                                                                                                                              |
+| `class`        | `string`   | no       | —       | Optional extra class on the underlying <Modal>. Destructured as `class: className` per repo convention.                                                                                                                                                                                                                                 |
+| `confirmLabel` | `string`   | yes      | —       | Confirm button label. Required — no default. Name the action being confirmed: - Destructive: "Delete", "Discard changes", "Remove from organization". - Non-destructive: "Save", "Continue", "Publish". Never use "OK" or "Confirm" in production — they don't describe the action.                                                     |
+| `description`  | `string`   | no       | —       | Optional body description — short, plain text only. Rendered as a single <p> and wired to aria-describedby. For rich content (markup, lists, multiple paragraphs), compose <Modal> + <Button> directly — screen readers announce aria-describedby targets as one continuous run.                                                        |
+| `destructive`  | `boolean`  | no       | —       | When true, the confirm button uses variant="danger". The cancel button still receives default focus regardless — color is never the sole destructive signal.                                                                                                                                                                            |
+| `open`         | `boolean`  | yes      | —       | Controls visibility. Bindable.                                                                                                                                                                                                                                                                                                          |
+| `title`        | `string`   | yes      | —       | Modal title; passed through to <Modal>.                                                                                                                                                                                                                                                                                                 |
+| `oncancel`     | `(opaque)` | no       | —       | Fired when the user cancels via ANY dismissal affordance — cancel button, Escape, backdrop click, or the close-X button. Optional. Parent-driven `open = false` does NOT fire this callback. Callbacks are not awaited; thrown callbacks do not block close. Not expressible in JSON Schema; see the component types for the signature. |
+| `onconfirm`    | `(opaque)` | yes      | —       | Fired when the user activates the confirm button. Required. Component closes itself after. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                   |
+| `triggerRef`   | `(opaque)` | no       | —       | Forwarded to <Modal>; focus is restored here on close. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                       |
 
 <!-- generated:props:end -->
 

package/src/components/container/README.md

@@ -1,6 +1,6 @@
 # Container
 
-Centered, max-width-capped wrapper for the narrow-column reading pattern. Distinct from `PageLayout`, which scaffolds an app shell with header, breadcrumbs, and actions — Container composes no chrome, it just constrains and centers content.
+Centered, max-width-capped wrapper for the narrow-column reading pattern. Container composes no app shell chrome; it just constrains and centers content.
 
 ## Usage
 
@@ -19,19 +19,20 @@ Centered, max-width-capped wrapper for the narrow-column reading pattern. Distin
 
 The v1 inline gutter is a single non-responsive value (`--cinder-space-5`). Disable it with `padded={false}`, or override `.cinder-container` (or the `--cinder-content-width-*` tokens) per scope if you need different padding or widths.
 
-For an app shell with header and action regions, use [`PageLayout`](../page-layout/README.md) instead.
+For an app shell with header and action regions, write the shell directly from `Container`, `SectionHeading`, navigation, and action primitives.
 
 ## Props
 
 <!-- generated:props:start -->
 
-| Prop       | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required | Default | Description                                                                   |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------- |
-| `as`       | `"object"` \| `"a"` \| `"abbr"` \| `"address"` \| `"article"` \| `"aside"` \| `"audio"` \| `"b"` \| `"bdi"` \| `"bdo"` \| `"blockquote"` \| `"body"` \| `"button"` \| `"canvas"` \| `"caption"` \| `"cite"` \| `"code"` \| `"colgroup"` \| `"data"` \| `"datalist"` \| `"dd"` \| `"del"` \| `"details"` \| `"dfn"` \| `"dialog"` \| `"div"` \| `"dl"` \| `"dt"` \| `"em"` \| `"fieldset"` \| `"figcaption"` \| `"figure"` \| `"footer"` \| `"form"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"head"` \| `"header"` \| `"hgroup"` \| `"html"` \| `"i"` \| `"iframe"` \| `"ins"` \| `"kbd"` \| `"label"` \| `"legend"` \| `"li"` \| `"main"` \| `"map"` \| `"mark"` \| `"menu"` \| `"meter"` \| `"nav"` \| `"noscript"` \| `"ol"` \| `"optgroup"` \| `"option"` \| `"output"` \| `"p"` \| `"picture"` \| `"pre"` \| `"progress"` \| `"q"` \| `"rp"` \| `"rt"` \| `"ruby"` \| `"s"` \| `"samp"` \| `"script"` \| `"search"` \| `"section"` \| `"select"` \| `"slot"` \| `"small"` \| `"span"` \| `"strong"` \| `"style"` \| `"sub"` \| `"summary"` \| `"sup"` \| `"table"` \| `"tbody"` \| `"td"` \| `"template"` \| `"textarea"` \| `"tfoot"` \| `"th"` \| `"thead"` \| `"time"` \| `"title"` \| `"tr"` \| `"u"` \| `"ul"` \| `"var"` \| `"video"` | no       | `"div"` | Element tag to render.                                                        |
-| `centered` | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `true`  | Center the box with auto inline margins.                                      |
-| `class`    | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no       | —       | Additional classes merged onto the root element.                              |
-| `maxWidth` | `"prose"` \| `"narrow"` \| `"wide"` \| `"full"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | no       | —       | Named max-width token. Omitted falls back to the default content-width token. |
-| `padded`   | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `true`  | Apply the default inline gutter so content never touches the edges.           |
+| Prop       | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required | Default | Description                                                                                                                |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `as`       | `"object"` \| `"a"` \| `"abbr"` \| `"address"` \| `"article"` \| `"aside"` \| `"audio"` \| `"b"` \| `"bdi"` \| `"bdo"` \| `"blockquote"` \| `"body"` \| `"button"` \| `"canvas"` \| `"caption"` \| `"cite"` \| `"code"` \| `"colgroup"` \| `"data"` \| `"datalist"` \| `"dd"` \| `"del"` \| `"details"` \| `"dfn"` \| `"dialog"` \| `"div"` \| `"dl"` \| `"dt"` \| `"em"` \| `"fieldset"` \| `"figcaption"` \| `"figure"` \| `"footer"` \| `"form"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"head"` \| `"header"` \| `"hgroup"` \| `"html"` \| `"i"` \| `"iframe"` \| `"ins"` \| `"kbd"` \| `"label"` \| `"legend"` \| `"li"` \| `"main"` \| `"map"` \| `"mark"` \| `"menu"` \| `"meter"` \| `"nav"` \| `"noscript"` \| `"ol"` \| `"optgroup"` \| `"option"` \| `"output"` \| `"p"` \| `"picture"` \| `"pre"` \| `"progress"` \| `"q"` \| `"rp"` \| `"rt"` \| `"ruby"` \| `"s"` \| `"samp"` \| `"script"` \| `"search"` \| `"section"` \| `"select"` \| `"slot"` \| `"small"` \| `"span"` \| `"strong"` \| `"style"` \| `"sub"` \| `"summary"` \| `"sup"` \| `"table"` \| `"tbody"` \| `"td"` \| `"template"` \| `"textarea"` \| `"tfoot"` \| `"th"` \| `"thead"` \| `"time"` \| `"title"` \| `"tr"` \| `"u"` \| `"ul"` \| `"var"` \| `"video"` | no       | `"div"` | Element tag to render.                                                                                                     |
+| `centered` | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `true`  | Center the box with auto inline margins.                                                                                   |
+| `class`    | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no       | —       | Additional classes merged onto the root element.                                                                           |
+| `maxWidth` | `"prose"` \| `"narrow"` \| `"wide"` \| `"full"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | no       | —       | Named max-width token. Omitted falls back to the default content-width token.                                              |
+| `padded`   | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `true`  | Apply the default inline gutter so content never touches the edges.                                                        |
+| `children` | `(opaque)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | yes      | —       | Required content rendered inside the container. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

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

@@ -26,15 +26,15 @@ Right-click and long-press menu positioned at the user's pointer while reusing d
 
 <!-- generated:props:start -->
 
-| Prop             | Type                         | Required | Default | Description                                                                                                                |
-| ---------------- | ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `anchorPoint`    | { x: `number`; y: `number` } | no       | —       |                                                                                                                            |
-| `class`          | `string`                     | no       | —       |                                                                                                                            |
-| `disabled`       | `boolean`                    | no       | —       |                                                                                                                            |
-| `longPressDelay` | `number`                     | no       | —       |                                                                                                                            |
-| `open`           | `boolean`                    | no       | —       |                                                                                                                            |
-| `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. |
-| `onopenchange`   | `(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                                                                                                                          |
+| ---------------- | ---------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `anchorPoint`    | { x: `number`; y: `number` } | no       | —       | Explicit pointer coordinates at which to anchor the menu, overriding the position captured from the right-click or long-press event. |
+| `class`          | `string`                     | no       | —       | Additional class names merged with the component's root class.                                                                       |
+| `disabled`       | `boolean`                    | no       | —       | When true, disables context-menu activation on right-click and long-press within the trigger region. Default `false`.                |
+| `longPressDelay` | `number`                     | no       | —       | Duration in milliseconds a touch pointer must be held before the menu opens on mobile. Default `500`.                                |
+| `open`           | `boolean`                    | no       | —       | Controls the open state of the context menu; bindable for controlled usage.                                                          |
+| `children`       | `(opaque)`                   | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.           |
+| `onopenchange`   | `(opaque)`                   | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.           |
 
 <!-- generated:props:end -->
 

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

@@ -2,8 +2,10 @@ import { createContext } from 'svelte';
 
 export type ContextMenuContext = {
   get disabled(): boolean;
+  get isOpen(): boolean;
   get longPressDelay(): number;
   openAt: (x: number, y: number) => void;
+  close: () => void;
 };
 
 const [getContextMenuContextStrict, setContextMenuContext] = createContext<ContextMenuContext>();