@lostgradient/cinder 0.1.1 → 0.3.0

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

@@ -0,0 +1,61 @@
+# CommandMenu
+
+Inline caret-anchored slash-command list for textareas and single-line text inputs.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { CommandMenu } from '@lostgradient/cinder/command-menu';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Showing a contextual command list at the caret while a user types in a textarea or input.
+- Building slash-command insertion flows where the host owns text replacement.
+
+### Avoid When
+
+- Exposing a global app launcher — use command-palette instead.
+- Selecting from a static form option list — use combobox instead.
+
+## Props
+
+<!-- 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)`                                                                                                           | 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 -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents: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/confirm-dialog/confirm-dialog.examples.json

@@ -8,6 +8,12 @@
       "title": "Confirm dialog",
       "description": "A destructive action gated behind an explicit confirm and cancel prompt.",
       "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { ConfirmDialog } from '@lostgradient/cinder/confirm-dialog';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let lastAction = $state('');\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;\">\n  <Button\n    label=\"Delete item\"\n    variant=\"danger\"\n    onclick={(event) => {\n      triggerRef = event.currentTarget as HTMLElement;\n      open = true;\n    }}\n  />\n\n  {#if lastAction}\n    <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n      Last action: <strong>{lastAction}</strong>\n    </p>\n  {/if}\n</div>\n\n<ConfirmDialog\n  bind:open\n  {triggerRef}\n  title=\"Delete item?\"\n  description=\"This permanently removes the item. This action cannot be undone.\"\n  destructive\n  confirmLabel=\"Delete\"\n  onconfirm={() => (lastAction = 'confirmed')}\n  oncancel={() => (lastAction = 'cancelled')}\n/>\n"
+    },
+    {
+      "id": "delete-account",
+      "title": "Delete account",
+      "description": "A destructive ConfirmDialog for permanent account and data deletion. Default focus lands on Cancel to guard against accidental confirmation.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { ConfirmDialog } from '@lostgradient/cinder/confirm-dialog';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let lastAction = $state('');\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;\">\n  <Button\n    label=\"Delete account\"\n    variant=\"danger\"\n    onclick={(event) => {\n      triggerRef = event.currentTarget as HTMLElement;\n      open = true;\n    }}\n  />\n\n  {#if lastAction}\n    <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n      Last action: <strong>{lastAction}</strong>\n    </p>\n  {/if}\n</div>\n\n<ConfirmDialog\n  bind:open\n  {triggerRef}\n  title=\"Delete your account?\"\n  description=\"This will permanently delete your account and all associated data. This action cannot be undone.\"\n  destructive\n  confirmLabel=\"Delete account\"\n  onconfirm={() => (lastAction = 'account deleted')}\n  oncancel={() => (lastAction = 'cancelled')}\n/>\n"
     }
   ]
 }

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

@@ -0,0 +1,55 @@
+# ContextMenu
+
+Right-click and long-press menu positioned at the user's pointer while reusing dropdown menu parts.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ContextMenu } from '@lostgradient/cinder/context-menu';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Providing contextual actions for a canvas, list row, file, or selected item.
+- Opening a menu from a pointer location instead of a visible dropdown trigger.
+
+### Avoid When
+
+- The menu should open from a button — use dropdown.
+- Showing arbitrary rich content rather than menu actions — use popover.
+
+## Props
+
+<!-- generated:props:start -->
+
+| 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 -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents: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>();

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

@@ -146,10 +146,14 @@
     get disabled() {
       return disabled;
     },
+    get isOpen() {
+      return open;
+    },
     get longPressDelay() {
       return longPressDelay;
     },
     openAt,
+    close,
   });
 
   $effect(() => {

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

@@ -9,11 +9,16 @@ export type ContextMenuAnchorPoint = {
 };
 
 export type ContextMenuProps = {
+  /** Controls the open state of the context menu; bindable for controlled usage. */
   open?: boolean;
   onopenchange?: (open: boolean) => void;
+  /** Explicit pointer coordinates at which to anchor the menu, overriding the position captured from the right-click or long-press event. */
   anchorPoint?: ContextMenuAnchorPoint | undefined;
+  /** When true, disables context-menu activation on right-click and long-press within the trigger region. Default `false`. */
   disabled?: boolean;
+  /** Duration in milliseconds a touch pointer must be held before the menu opens on mobile. Default `500`. */
   longPressDelay?: number;
   children: Snippet;
+  /** Additional class names merged with the component's root class. */
   class?: string;
 };

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

@@ -0,0 +1,50 @@
+# ContextMenuTrigger
+
+Compose-only trigger region that opens a context-menu on right-click or touch long-press.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ContextMenuTrigger } from '@lostgradient/cinder/context-menu-trigger';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Wrapping the region that should own contextual actions inside ContextMenu.
+- Pairing pointer-positioned menu behavior with dropdown menu items.
+
+### Avoid When
+
+- Used outside context-menu — it requires the ContextMenu provider.
+- Opening a normal click menu from a visible button — use dropdown-trigger.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop       | Type       | Required | Default | Description                                                                                                                |
+| ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`   | no       | —       | Additional class names merged with the component's root class.                                                             |
+| `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. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

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

@@ -45,7 +45,7 @@
   let startX = 0;
   let startY = 0;
   let suppressClick = false;
-  let suppressNextContextmenuUntil = 0;
+  let suppressNextContextmenu = false;
 
   type TriggerEvent<EventType extends Event> = EventType & {
     currentTarget: EventTarget & HTMLDivElement;
@@ -75,7 +75,7 @@
       callTriggerHandler(oncontextmenu, event);
       return;
     }
-    if (Date.now() < suppressNextContextmenuUntil) {
+    if (suppressNextContextmenu) {
       event.preventDefault();
       callTriggerHandler(oncontextmenu, event);
       return;
@@ -91,14 +91,16 @@
       return;
     }
     if (event.pointerType !== 'touch') {
+      suppressNextContextmenu = false;
       callTriggerHandler(onpointerdown, event);
       return;
     }
+    suppressNextContextmenu = false;
     startX = event.clientX;
     startY = event.clientY;
     clearLongPress();
     longPressTimer = setTimeout(() => {
-      suppressNextContextmenuUntil = Date.now() + 700;
+      suppressNextContextmenu = true;
       suppressClick = true;
       context.openAt(startX, startY);
     }, context.longPressDelay);
@@ -127,6 +129,12 @@
       callTriggerHandler(onkeydown, event);
       return;
     }
+    if (event.key === 'Escape' && context.isOpen) {
+      event.preventDefault();
+      context.close();
+      callTriggerHandler(onkeydown, event);
+      return;
+    }
     if (event.key !== 'ContextMenu' && !(event.shiftKey && event.key === 'F10')) {
       callTriggerHandler(onkeydown, event);
       return;

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

@@ -2,6 +2,7 @@ import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 
 export type ContextMenuTriggerProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Additional class names merged with the component's root class. */
   class?: string;
   children: Snippet;
 };

package/src/components/copy-button/README.md

@@ -24,8 +24,8 @@ Button that copies a given text value to the clipboard with visual feedback.
 | `iconOnly`        | `boolean`  | no       | —       | Render the button with only an icon and a visually hidden label. When true, defaults to a Copy icon (idle) and a Check icon (copied).                                                                                                                                                |
 | `label`           | `string`   | no       | —       | Accessible label for the idle state. Defaults to "Copy to clipboard".                                                                                                                                                                                                                |
 | `value`           | `string`   | yes      | —       | Text to copy to the clipboard.                                                                                                                                                                                                                                                       |
-| `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.                                                                                                                                                           |
-| `confirmation`    | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                           |
+| `children`        | `(opaque)` | no       | —       | Default content (idle state). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                             |
+| `confirmation`    | `(opaque)` | no       | —       | Content rendered while in the "copied" state. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                             |
 
 <!-- generated:props:end -->