@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/scroll-area/README.md

@@ -18,10 +18,10 @@ Bounded scrolling container that constrains overflowing content within a max hei
 
 | Prop        | Type                                                                                                               | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | ----------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ariaLabel` | `string`                                                                                                           | no       | —       | Accessible name for the scroll region. When provided on neutral containers, the container also gets `role="region"` so assistive technology treats it as a landmark. Semantic tags keep their native roles. Provide this when the scroll area represents a meaningful section (a chat transcript, a code panel) — omit it for purely decorative scrolling chrome. This is the single source of truth for the accessible name; pass it through this prop rather than the raw `aria-label` HTML attribute so the landmark role and label stay coupled. |
 | `as`        | `"article"` \| `"aside"` \| `"div"` \| `"li"` \| `"main"` \| `"nav"` \| `"ol"` \| `"pre"` \| `"section"` \| `"ul"` | no       | —       | Element tag to render. Defaults to `'div'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `class`     | `string`                                                                                                           | no       | —       | Additional classes merged onto the scroll viewport.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `direction` | `"vertical"` \| `"horizontal"` \| `"both"`                                                                         | no       | —       | Axis to allow scrolling on. Defaults to `'vertical'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `label`     | `string`                                                                                                           | no       | —       | Accessible name for the scroll region. When provided on neutral containers, the container also gets `role="region"` so assistive technology treats it as a landmark. Semantic tags keep their native roles. Provide this when the scroll area represents a meaningful section (a chat transcript, a code panel) — omit it for purely decorative scrolling chrome. This is the single source of truth for the accessible name; pass it through this prop rather than the raw `aria-label` HTML attribute so the landmark role and label stay coupled. |
 | `maxHeight` | `string`                                                                                                           | no       | —       | Maximum block size of the scroll viewport (any valid CSS length).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `maxWidth`  | `string`                                                                                                           | no       | —       | Maximum inline size of the scroll viewport (any valid CSS length).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `tabindex`  | `number`                                                                                                           | no       | —       | Override the default focus behavior. The component sets `tabindex="0"` by default so keyboard users can reach the viewport for arrow-key scrolling. Pass `tabindex={-1}` when the viewport should be programmatically focusable without entering the tab order.                                                                                                                                                                                                                                                                                      |

package/src/components/scroll-area/scroll-area.examples.json

@@ -13,19 +13,19 @@
       "id": "horizontal-code-snippet",
       "title": "Horizontal code snippet",
       "description": "Horizontal scrolling for a long single-line code sample, rendered as a <pre> via the `as` prop so the region role is preserved alongside the semantic tag.",
-      "code": "<script lang=\"ts\">\n  import { ScrollArea } from '@lostgradient/cinder/scroll-area';\n\n  const command =\n    '$ bun run --filter @cinder/components build && bun run --filter @cinder/components test --coverage --reporter=verbose --bail';\n</script>\n\n<ScrollArea as=\"pre\" direction=\"horizontal\" maxWidth=\"32rem\" ariaLabel=\"Example command\"\n  ><code>{command}</code></ScrollArea\n>\n"
+      "code": "<script lang=\"ts\">\n  import { ScrollArea } from '@lostgradient/cinder/scroll-area';\n\n  const command =\n    '$ bun run --filter @cinder/components build && bun run --filter @cinder/components test --coverage --reporter=verbose --bail';\n</script>\n\n<ScrollArea as=\"pre\" direction=\"horizontal\" maxWidth=\"32rem\" label=\"Example command\"\n  ><code>{command}</code></ScrollArea\n>\n"
     },
     {
       "id": "themed-scrollbar",
       "title": "Themed scrollbar tokens",
       "description": "Overrides --cinder-scrollbar-thumb and --cinder-scrollbar-thumb-hover on a wrapping surface so the native scrollbar picks up brand colors without replacing it.",
-      "code": "<script lang=\"ts\">\n  import { ScrollArea } from '@lostgradient/cinder/scroll-area';\n</script>\n\n<div\n  style=\"--cinder-scrollbar-thumb: oklch(62% 0.18 264 / 0.7); --cinder-scrollbar-thumb-hover: oklch(62% 0.18 264 / 0.95);\"\n>\n  <ScrollArea ariaLabel=\"Release notes\" maxHeight=\"14rem\">\n    <h3>0.42.0</h3>\n    <p>Adds scroll-area, themed via design tokens.</p>\n    <h3>0.41.0</h3>\n    <p>Combobox gains rich option rows with description and avatar.</p>\n    <h3>0.40.0</h3>\n    <p>Form-field contract lands on input, textarea, and select.</p>\n    <h3>0.39.0</h3>\n    <p>Changesets adopted; provenance-enabled publishing wired up.</p>\n    <h3>0.38.0</h3>\n    <p>Package exports unified under cinder/* with Shiki adapter.</p>\n  </ScrollArea>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { ScrollArea } from '@lostgradient/cinder/scroll-area';\n</script>\n\n<div\n  style=\"--cinder-scrollbar-thumb: oklch(62% 0.18 264 / 0.7); --cinder-scrollbar-thumb-hover: oklch(62% 0.18 264 / 0.95);\"\n>\n  <ScrollArea label=\"Release notes\" maxHeight=\"14rem\">\n    <h3>0.42.0</h3>\n    <p>Adds scroll-area, themed via design tokens.</p>\n    <h3>0.41.0</h3>\n    <p>Combobox gains rich option rows with description and avatar.</p>\n    <h3>0.40.0</h3>\n    <p>Form-field contract lands on input, textarea, and select.</p>\n    <h3>0.39.0</h3>\n    <p>Changesets adopted; provenance-enabled publishing wired up.</p>\n    <h3>0.38.0</h3>\n    <p>Package exports unified under cinder/* with Shiki adapter.</p>\n  </ScrollArea>\n</div>\n"
     },
     {
       "id": "vertical-chat-list",
       "title": "Vertical chat transcript",
       "description": "A vertical scroll region with a meaningful accessible name, so assistive technology treats it as a landmark via the derived role=\"region\".",
-      "code": "<script lang=\"ts\">\n  import { ScrollArea } from '@lostgradient/cinder/scroll-area';\n</script>\n\n<ScrollArea ariaLabel=\"Chat transcript\" maxHeight=\"16rem\">\n  <p>Avery: morning! ready to pair on the migration?</p>\n  <p>Jordan: yep — pulling the branch now.</p>\n  <p>Avery: heads up, the seed script changed.</p>\n  <p>Jordan: noticed. running it locally first.</p>\n  <p>Avery: thanks. ping me when you hit the auth step.</p>\n  <p>Jordan: will do. tests are green on my end.</p>\n  <p>Avery: nice. I'll start drafting the changelog.</p>\n  <p>Jordan: cool — should I cherry-pick the hotfix in?</p>\n  <p>Avery: yes please, then squash before review.</p>\n  <p>Jordan: pushed. take a look when you can.</p>\n</ScrollArea>\n"
+      "code": "<script lang=\"ts\">\n  import { ScrollArea } from '@lostgradient/cinder/scroll-area';\n</script>\n\n<ScrollArea label=\"Chat transcript\" maxHeight=\"16rem\">\n  <p>Avery: morning! ready to pair on the migration?</p>\n  <p>Jordan: yep — pulling the branch now.</p>\n  <p>Avery: heads up, the seed script changed.</p>\n  <p>Jordan: noticed. running it locally first.</p>\n  <p>Avery: thanks. ping me when you hit the auth step.</p>\n  <p>Jordan: will do. tests are green on my end.</p>\n  <p>Avery: nice. I'll start drafting the changelog.</p>\n  <p>Jordan: cool — should I cherry-pick the hotfix in?</p>\n  <p>Avery: yes please, then squash before review.</p>\n  <p>Jordan: pushed. take a look when you can.</p>\n</ScrollArea>\n"
     }
   ]
 }

package/src/components/scroll-area/scroll-area.svelte

@@ -31,7 +31,7 @@
     direction = 'vertical',
     maxHeight,
     maxWidth,
-    ariaLabel,
+    label,
     tabindex = 0,
     as = 'div',
     class: className,
@@ -40,13 +40,13 @@
   }: ScrollAreaProps = $props();
 
   const normalizedAriaLabel = $derived(
-    typeof ariaLabel === 'string' && ariaLabel.trim().length > 0 ? ariaLabel.trim() : undefined,
+    typeof label === 'string' && label.trim().length > 0 ? label.trim() : undefined,
   );
   // `aria-labelledby` reaches the element through `...rest`. Treat it the same as
-  // `ariaLabel` for landmark purposes: a neutral element (`div`/`pre`) with an
-  // accessible name — whether from `ariaLabel` or `aria-labelledby` — becomes a
+  // the `label` prop for landmark purposes: a neutral element (`div`/`pre`) with an
+  // accessible name — whether from `label` or `aria-labelledby` — becomes a
   // region landmark. Without this, `<ScrollArea as="div" aria-labelledby="…">`
-  // would be a named, focusable, but landmark-less container while the `ariaLabel`
+  // would be a named, focusable, but landmark-less container while the `label`
   // form would not — an asymmetry invisible to the consumer.
   const ariaLabelledby = $derived((rest as { 'aria-labelledby'?: string })['aria-labelledby']);
   const hasAccessibleName = $derived(

package/src/components/scroll-area/scroll-area.types.ts

@@ -40,7 +40,7 @@ export type ScrollAreaProps = Omit<
    * name; pass it through this prop rather than the raw `aria-label` HTML
    * attribute so the landmark role and label stay coupled.
    */
-  ariaLabel?: string;
+  label?: string;
   /**
    * Override the default focus behavior. The component sets `tabindex="0"`
    * by default so keyboard users can reach the viewport for arrow-key

package/src/components/secret-value-field/secret-value-field.svelte

@@ -2,7 +2,7 @@
   /**
    * @cinder
    * @category data-display
-   * @status beta
+   * @status stable
    * @purpose Displays a masked secret (API key, token, webhook secret) with copy action and optional reveal toggle.
    * @tag clipboard
    * @tag security
@@ -16,7 +16,7 @@
 </script>
 
 <script lang="ts">
-  import { onDestroy } from 'svelte';
+  import { onDestroy, untrack } from 'svelte';
 
   import type { SecretValueFieldProps } from './secret-value-field.types.ts';
   import { copyToClipboard } from '../../utilities/clipboard.ts';
@@ -39,10 +39,8 @@
 
   const fieldId = $props.id();
 
-  // initiallyRevealed overrides the hidden default so newly-created secrets are readable on first render.
-  // The seed const makes the initial-only capture explicit and silences state_referenced_locally.
-  const initiallyRevealedSeed = initiallyRevealed;
-  let revealed = $state(initiallyRevealedSeed);
+  let revealed = $state(untrack(() => initiallyRevealed));
+  let previousValue = $state(untrack(() => value));
 
   let copied = $state(false);
   let resetTimer: ReturnType<typeof setTimeout> | undefined;
@@ -67,6 +65,12 @@
     revealed = !revealed;
   }
 
+  $effect(() => {
+    if (value === previousValue) return;
+    previousValue = value;
+    revealed = initiallyRevealed;
+  });
+
   onDestroy(() => {
     if (resetTimer) clearTimeout(resetTimer);
   });

package/src/components/segmented-control/segmented-control.css

@@ -227,7 +227,7 @@
   /* ── Focus ──────────────────────────────────────────────────────────────── */
 
   .cinder-segmented-control-option:focus-visible {
-    outline: 2px solid transparent;
+    outline: var(--cinder-ring-width) solid transparent;
     box-shadow:
       0 0 0 var(--cinder-ring-offset) var(--cinder-ring-offset-color),
       0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-ring-color);
@@ -278,6 +278,19 @@
     z-index: 1;
   }
 
+  /* Forced-colors: selected/pressed segments also need outline fallback. Selection
+   * semantics apply (the segment represents a chosen option) → Highlight. */
+  @media (forced-colors: active) {
+    .cinder-segmented-control:not([data-cinder-variant='tablist'])
+      .cinder-segmented-control-option[data-cinder-selected]:focus-visible,
+    .cinder-segmented-control:not([data-cinder-variant='tablist'])
+      .cinder-segmented-control-option[data-cinder-pressed]:focus-visible {
+      outline: var(--cinder-ring-width) solid Highlight;
+      outline-offset: 1px;
+      box-shadow: none;
+    }
+  }
+
   /* ── Tablist variant (single mode only) ─────────────────────────────────────
  * See docs/decisions/segmented-control-tablist-variant.md. The tablist variant
  * carries tab semantics for externally owned panels, so it must read as a
@@ -350,6 +363,14 @@
       outline: var(--cinder-ring-width) solid Highlight;
       outline-offset: 1px;
     }
+
+    /* Forced-colors: selected+focused tab in tablist → selection semantics → Highlight. */
+    .cinder-segmented-control[data-cinder-selection-mode='single'][data-cinder-variant='tablist']
+      .cinder-segmented-control-option[data-cinder-selected]:focus-visible {
+      outline: var(--cinder-ring-width) solid Highlight;
+      outline-offset: 1px;
+      box-shadow: none;
+    }
   }
 
   /* Selected hover must not restore the filled pill — keep the selected tab's

package/src/components/segmented-control/segmented-control.examples.json

@@ -12,8 +12,8 @@
     {
       "id": "multiple",
       "title": "Multi-select segmented control",
-      "description": "Multiple options can be toggled independently. Bind a SvelteSet to track selection.",
-      "code": "<script lang=\"ts\">\n  import { SvelteSet } from 'svelte/reactivity';\n  import { Segment } from '@lostgradient/cinder/segment';\n  import { SegmentedControl } from '@lostgradient/cinder/segmented-control';\n\n  let formats = new SvelteSet<string>();\n\n  const selected = $derived([...formats].join(', ') || 'none');\n</script>\n\n<div style=\"display: grid; gap: 0.75rem; justify-items: start;\">\n  <SegmentedControl\n    id=\"playground-format\"\n    selectionMode=\"multiple\"\n    bind:value={formats}\n    label=\"Text formatting\"\n  >\n    <Segment value=\"bold\">Bold</Segment>\n    <Segment value=\"italic\">Italic</Segment>\n    <Segment value=\"underline\">Underline</Segment>\n    <Segment value=\"strikethrough\">Strike</Segment>\n  </SegmentedControl>\n  <p style=\"margin: 0; color: var(--cinder-text-muted);\">Active formats: {selected}</p>\n</div>\n"
+      "description": "Multiple options can be toggled independently. Pass a SvelteSet to track selection.",
+      "code": "<script lang=\"ts\">\n  import { SvelteSet } from 'svelte/reactivity';\n  import { Segment } from '@lostgradient/cinder/segment';\n  import { SegmentedControl } from '@lostgradient/cinder/segmented-control';\n\n  let formats = new SvelteSet<string>();\n\n  const selected = $derived([...formats].join(', ') || 'none');\n</script>\n\n<div style=\"display: grid; gap: 0.75rem; justify-items: start;\">\n  <SegmentedControl\n    id=\"playground-format\"\n    selectionMode=\"multiple\"\n    value={formats}\n    label=\"Text formatting\"\n  >\n    <Segment value=\"bold\">Bold</Segment>\n    <Segment value=\"italic\">Italic</Segment>\n    <Segment value=\"underline\">Underline</Segment>\n    <Segment value=\"strikethrough\">Strike</Segment>\n  </SegmentedControl>\n  <p style=\"margin: 0; color: var(--cinder-text-muted);\">Active formats: {selected}</p>\n</div>\n"
     },
     {
       "id": "sizing",

package/src/components/select/select.css

@@ -14,14 +14,21 @@
  * Label
  * ---------------------------------------- */
 
-  .cinder-select-field > label {
-    display: inline-block;
+  .cinder-select-field__label {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cinder-space-1);
     font-size: var(--cinder-text-xs);
     font-weight: var(--cinder-font-medium);
     line-height: 1;
     color: var(--cinder-text);
   }
 
+  .cinder-select-field__label[data-disabled] {
+    color: var(--cinder-text-disabled);
+    cursor: not-allowed;
+  }
+
   /* ----------------------------------------
  * Select control
  * ---------------------------------------- */

package/src/components/select/select.svelte

@@ -73,7 +73,12 @@
 
 <div class={classNames('cinder-select-field', className)}>
   {#if label}
-    <label for={id}>{label}</label>
+    <label for={id} class="cinder-select-field__label" data-disabled={field.disabled || undefined}>
+      {label}
+      {#if field.required}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
+    </label>
   {/if}
   <span class="cinder-select-field__control">
     {#if options.length === 0}

package/src/components/selection-popover/selection-popover.examples.json

@@ -25,7 +25,7 @@
       "id": "null-position",
       "title": "Null position clears the popover",
       "description": "Setting position to null hides the popover even while open is true — the consumer can clear an active selection without changing the open flag.",
-      "code": "<script lang=\"ts\">\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { Button } from '@lostgradient/cinder/button';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'null-position-selection-popover';\n\n  /**\n   * A fixed anchor used to demonstrate the null-clear behavior without requiring\n   * a real text selection in this example. The coordinates are viewport-relative,\n   * consistent with how a real selection anchor would be computed.\n   */\n  const demonstrationPosition: SelectionPopoverPosition = { x: 220, y: 220 };\n\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n\n  function showPopover(): void {\n    position = demonstrationPosition;\n    isOpen = true;\n  }\n\n  function clearPosition(): void {\n    position = null;\n    // open stays true — the component should hide because position is null.\n  }\n\n  function restorePosition(): void {\n    position = demonstrationPosition;\n  }\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    Demonstrates that setting <code>position</code> to <code>null</code> hides the popover even when\n    <code>open</code>\n    remains <code>true</code>. Click <em>Show popover</em> to open it, then use\n    <em>Clear position</em>\n    to set <code>position=null</code> while leaving\n    <code>open=true</code> — the popover disappears because the component has no anchor point to\n    position against. Use <em>Restore position</em> to bring it back without changing\n    <code>open</code>.\n  </p>\n\n  <div style=\"display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 0.75rem;\">\n    <Button label=\"Show popover\" onclick={showPopover} />\n    <Button label=\"Clear position (set null)\" onclick={clearPosition} disabled={!isOpen} />\n    <Button label=\"Restore position\" onclick={restorePosition} disabled={!isOpen} />\n  </div>\n\n  <p style=\"margin: 0; font-size: var(--cinder-text-sm); color: var(--cinder-text-muted);\">\n    Status: open={isOpen}, position={position ? `{x:${position.x},y:${position.y}}` : 'null'}\n  </p>\n</div>\n\n<SelectionPopover id={popoverId} open={isOpen} {position} />\n"
+      "code": "<script lang=\"ts\">\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { Button } from '@lostgradient/cinder/button';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'null-position-selection-popover';\n\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let anchorElement = $state<HTMLElement | null>(null);\n\n  function showPopover(): void {\n    if (!anchorElement) return;\n\n    const rect = anchorElement.getBoundingClientRect();\n    position = {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n      height: rect.height,\n    };\n    isOpen = true;\n  }\n\n  function clearPosition(): void {\n    position = null;\n    // open stays true — the component should hide because position is null.\n  }\n\n  function restorePosition(): void {\n    showPopover();\n  }\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    Demonstrates that setting <code>position</code> to <code>null</code> hides the popover even when\n    <code>open</code>\n    remains <code>true</code>. Click <em>Show popover</em> to open it, then use\n    <em>Clear position</em>\n    to set <code>position=null</code> while leaving\n    <code>open=true</code> — the popover disappears because the component has no anchor point to\n    position against. Use <em>Restore position</em> to bring it back without changing\n    <code>open</code>.\n  </p>\n\n  <div style=\"display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 0.75rem;\">\n    <span bind:this={anchorElement} style=\"display: inline-flex;\">\n      <Button label=\"Show popover\" onclick={showPopover} />\n    </span>\n    <Button label=\"Clear position (set null)\" onclick={clearPosition} disabled={!isOpen} />\n    <Button label=\"Restore position\" onclick={restorePosition} disabled={!isOpen} />\n  </div>\n\n  <p style=\"margin: 0; font-size: var(--cinder-text-sm); color: var(--cinder-text-muted);\">\n    Status: open={isOpen}, position={position ? `{x:${position.x},y:${position.y}}` : 'null'}\n  </p>\n</div>\n\n<SelectionPopover id={popoverId} open={isOpen} {position} />\n"
     },
     {
       "id": "toggled",

package/src/components/share-card/share-card.css

@@ -24,7 +24,7 @@
   }
 
   .cinder-share-card__title {
-    font-weight: 600;
+    font-weight: var(--cinder-font-semibold);
     font-size: var(--cinder-text-sm);
     margin: 0;
     color: var(--cinder-text);
@@ -76,10 +76,10 @@
     color: var(--cinder-text);
     cursor: pointer;
     font-size: var(--cinder-text-sm);
-    font-weight: 500;
+    font-weight: var(--cinder-font-medium);
     transition:
-      background-color 0.15s ease,
-      border-color 0.15s ease;
+      background-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      border-color var(--cinder-duration-fast) var(--cinder-ease-standard);
     white-space: nowrap;
   }
 
@@ -97,6 +97,17 @@
       0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-ring-color);
   }
 
+  @media (forced-colors: active) {
+    .cinder-share-card__action:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      /* 3px separates the outline from ButtonBorder (which renders in forced-colors
+         on all bordered controls and shares the ButtonText color family in HCM);
+         at 2px the ring and border can visually merge. */
+      outline-offset: 3px;
+      box-shadow: none;
+    }
+  }
+
   .cinder-share-card__action[data-cinder-copied] {
     color: var(--cinder-color-success-fg);
     border-color: var(--cinder-color-success-border);

package/src/components/share-card/share-card.svelte

@@ -16,8 +16,6 @@
 </script>
 
 <script lang="ts">
-  import { onDestroy } from 'svelte';
-
   import { classNames } from '../../utilities/class-names.ts';
   import { copyToClipboard } from '../../utilities/clipboard.ts';
   import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
@@ -161,9 +159,9 @@
   // the value actually looks like a URL, otherwise "Text to share".
   const valueRegionLabel = $derived(looksLikeUrl(value) ? 'Link to share' : 'Text to share');
 
-  onDestroy(() => {
+  $effect(() => {
     // clearTimer() clears BOTH resetTimer and announceTimer.
-    clearTimer();
+    return () => clearTimer();
   });
 
   // The action list: explicit `actions` verbatim, else the copy-link default.

package/src/components/sheet/sheet.svelte

@@ -19,13 +19,11 @@
   import type { SheetProps } from './sheet.types.ts';
   import { onDestroy, tick } from 'svelte';
 
-  import { captureFocus, lockBodyScroll, pushEscapeHandler } from '../../_internal/overlay.ts';
-  import { waitForTransitionCompletion } from '../../_internal/transition-completion.ts';
   import { overflowFade } from '../../utilities/attachments.ts';
   import { createFocusTrap } from '../focus-trap/index.ts';
   import { classNames } from '../../utilities/class-names.ts';
-  import { restoreFocusTo } from '../../utilities/focus.ts';
   import { useReducedMotion } from '../../utilities/use-reduced-motion.svelte.ts';
+  import { createSlidingDialogState } from '../_internal/create-sliding-dialog-state.svelte.ts';
 
   let {
     open = $bindable(false),
@@ -45,66 +43,33 @@
   let dialogElement: HTMLDialogElement | undefined = $state();
   let bodyElement: HTMLDivElement | undefined = $state();
   let panelElement: HTMLDivElement | undefined = $state();
-  let hydrated = $state(false);
-  let renderPanel = $state(open);
-  let isClosing = $state(false);
-  let closeGeneration = $state(0);
   let pendingOpenFocus = $state(false);
 
-  let capturedFocus: HTMLElement | null = null;
-  let releaseScrollLock: (() => void) | null = null;
-  let releaseEscape: (() => void) | null = null;
-  let cancelPendingClose: (() => void) | null = null;
-
   const reducedMotion = useReducedMotion();
   const bodyOverflowFade = overflowFade();
-
-  function acquireScrollLock(): void {
-    if (releaseScrollLock) return;
-    releaseScrollLock = lockBodyScroll();
-  }
-
-  function acquireEscapeMarker(): void {
-    if (releaseEscape) return;
-    // No-op handler: presence marker so stacked non-dialog overlays
-    // route ESC to themselves. Native <dialog> owns the actual ESC close.
-    releaseEscape = pushEscapeHandler(() => {});
-  }
+  const dialogState = createSlidingDialogState({
+    getOpen: () => open,
+    setOpen: (nextOpen) => {
+      open = nextOpen;
+    },
+    getDialogElement: () => dialogElement,
+    getPanelElement: () => panelElement,
+    getReducedMotion: () => reducedMotion.current,
+    getTriggerRef: () => triggerRef,
+    onOpen: () => {
+      pendingOpenFocus = true;
+    },
+    onClosed: () => {
+      pendingOpenFocus = false;
+    },
+  });
 
   $effect(() => {
-    hydrated = true;
+    dialogState.markHydrated();
   });
 
   $effect(() => {
-    if (!dialogElement) return;
-    if (open) {
-      if (isClosing) {
-        closeGeneration += 1;
-        cancelPendingClose?.();
-        cancelPendingClose = null;
-        isClosing = false;
-      }
-
-      if (!renderPanel) {
-        renderPanel = true;
-      }
-
-      if (!dialogElement.open) {
-        capturedFocus = captureFocus();
-        pendingOpenFocus = true;
-        dialogElement.showModal();
-        acquireScrollLock();
-        acquireEscapeMarker();
-      }
-      return;
-    }
-
-    if (dialogElement.open) {
-      beginClosing();
-    } else {
-      renderPanel = false;
-      pendingOpenFocus = false;
-    }
+    dialogState.syncOpenState();
   });
 
   $effect(() => {
@@ -123,109 +88,29 @@
     });
   });
 
-  function beginClosing(): void {
-    if (!dialogElement?.open || isClosing) return;
-    if (!panelElement) {
-      finishClosing(closeGeneration);
-      return;
-    }
-
-    isClosing = true;
-    const generation = ++closeGeneration;
-    cancelPendingClose?.();
-    cancelPendingClose = waitForTransitionCompletion({
-      element: panelElement,
-      reducedMotion: reducedMotion.current,
-      onComplete: () => finishClosing(generation),
-    });
-  }
-
-  function finishClosing(generation: number): void {
-    if (generation !== closeGeneration) return;
-    cancelPendingClose?.();
-    cancelPendingClose = null;
-    isClosing = false;
-    renderPanel = false;
-    pendingOpenFocus = false;
-    if (dialogElement?.open) {
-      dialogElement.close();
-    }
-  }
-
-  function handleClose() {
-    if (releaseScrollLock) {
-      releaseScrollLock();
-      releaseScrollLock = null;
-    }
-    if (releaseEscape) {
-      releaseEscape();
-      releaseEscape = null;
-    }
-    open = false;
-    const candidates: Array<HTMLElement | null> = [triggerRef, capturedFocus];
-    capturedFocus = null;
-    for (const candidate of candidates) {
-      if (restoreFocusTo(candidate)) break;
-    }
-  }
-
-  function requestClose(): void {
-    if (!open && (isClosing || !dialogElement?.open)) return;
-    open = false;
-    beginClosing();
-  }
-
-  function handleBackdropClick(event: MouseEvent) {
-    if (event.target === dialogElement) {
-      requestClose();
-    }
-  }
-
-  function handleNativeCancel(event: Event) {
-    event.preventDefault();
-    requestClose();
-  }
-
   onDestroy(() => {
-    cancelPendingClose?.();
-    cancelPendingClose = null;
-    const wasOpen = releaseScrollLock !== null || releaseEscape !== null;
-    if (releaseScrollLock) {
-      releaseScrollLock();
-      releaseScrollLock = null;
-    }
-    if (releaseEscape) {
-      releaseEscape();
-      releaseEscape = null;
-    }
-    if (wasOpen) {
-      const candidates: Array<HTMLElement | null> = [triggerRef, capturedFocus];
-      capturedFocus = null;
-      for (const candidate of candidates) {
-        if (restoreFocusTo(candidate)) break;
-      }
-    }
+    dialogState.destroy();
   });
 </script>
 
-{#if hydrated}
+{#if dialogState.hydrated}
   <dialog
     {...rest}
     bind:this={dialogElement}
     class={classNames('cinder-sheet', className)}
     aria-modal="true"
     aria-labelledby={ariaLabelledBy ?? titleId}
-    data-cinder-closing={isClosing ? '' : undefined}
-    onclose={handleClose}
-    oncancel={handleNativeCancel}
-    onclick={handleBackdropClick}
+    data-cinder-closing={dialogState.isClosing ? '' : undefined}
+    onclose={() => dialogState.handleClose()}
+    oncancel={(event) => dialogState.handleNativeCancel(event)}
+    onclick={(event) => dialogState.handleBackdropClick(event)}
   >
     {#snippet closeButton()}
       <button
         type="button"
         class="cinder-sheet__close"
         aria-label="Close sheet"
-        onclick={requestClose}
+        onclick={() => dialogState.requestClose()}
       >
         <svg
           class="cinder-sheet__close-icon"
@@ -241,14 +126,14 @@
       </button>
     {/snippet}
 
-    {#if renderPanel}
+    {#if dialogState.renderPanel}
       <div
         bind:this={panelElement}
         class="cinder-sheet__panel"
-        data-cinder-closing={isClosing ? '' : undefined}
-        inert={isClosing}
+        data-cinder-closing={dialogState.isClosing ? '' : undefined}
+        inert={dialogState.isClosing}
         {@attach createFocusTrap({
-          active: () => open && !isClosing,
+          active: () => open && !dialogState.isClosing,
           restoreFocus: false,
           manageInitialFocus: false,
         })}

package/src/components/shortcut-hint/shortcut-hint.svelte

@@ -47,7 +47,7 @@
   {/if}
 
   <span class="cinder-shortcut-hint__keys" aria-hidden="true">
-    {#each keys as key, index (key + index)}
+    {#each keys as key, index (index)}
       <Kbd label={key} size="sm" />
       {#if index < keys.length - 1}
         <span class="cinder-shortcut-hint__separator">+</span>

package/src/components/side-navigation/side-navigation.examples.json

@@ -13,7 +13,7 @@
       "id": "docs-sidebar",
       "title": "Docs sidebar",
       "description": "Documentation sidebar with grouped navigation sections. The active item receives aria-current=\"page\".",
-      "code": "<script lang=\"ts\" module>\n  export const title = 'Docs sidebar';\n  export const description =\n    'Documentation sidebar with grouped navigation sections. The active item receives aria-current=\"page\".' +\n    ' Composed inside Sidebar so the column collapses to a drawer below the ~767px viewport breakpoint —' +\n    ' resize your browser window to see the mobile drawer behavior.';\n</script>\n\n<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 28rem; border: 1px solid var(--cinder-border); border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed ariaLabel=\"Documentation\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder Docs</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Documentation sections\">\n          <SideNavigation.Group label=\"Getting Started\">\n            <SideNavigation.Item href=\"#introduction\" active>Introduction</SideNavigation.Item>\n            <SideNavigation.Item href=\"#installation\">Installation</SideNavigation.Item>\n            <SideNavigation.Item href=\"#quick-start\">Quick start</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"Components\">\n            <SideNavigation.Item href=\"#button\">Button</SideNavigation.Item>\n            <SideNavigation.Item href=\"#form-section\">FormSection</SideNavigation.Item>\n            <SideNavigation.Item href=\"#side-navigation\">SideNavigation</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"API Reference\">\n            <SideNavigation.Item href=\"#props\">Props</SideNavigation.Item>\n            <SideNavigation.Item href=\"#types\">Types</SideNavigation.Item>\n            <SideNavigation.Item href=\"#css-variables\">CSS variables</SideNavigation.Item>\n          </SideNavigation.Group>\n        </SideNavigation>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1.5rem;\">\n      <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n        Main content area. Resize the browser viewport below ~767px to see the navigation collapse\n        into a mobile drawer.\n      </p>\n    </main>\n  </div>\n</div>\n"
+      "code": "<script lang=\"ts\" module>\n  export const title = 'Docs sidebar';\n  export const description =\n    'Documentation sidebar with grouped navigation sections. The active item receives aria-current=\"page\".' +\n    ' Composed inside Sidebar so the column collapses to a drawer below the ~767px viewport breakpoint —' +\n    ' resize your browser window to see the mobile drawer behavior.';\n</script>\n\n<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 28rem; border: 1px solid var(--cinder-border); border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed label=\"Documentation\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder Docs</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Documentation sections\">\n          <SideNavigation.Group label=\"Getting Started\">\n            <SideNavigation.Item href=\"#introduction\" active>Introduction</SideNavigation.Item>\n            <SideNavigation.Item href=\"#installation\">Installation</SideNavigation.Item>\n            <SideNavigation.Item href=\"#quick-start\">Quick start</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"Components\">\n            <SideNavigation.Item href=\"#button\">Button</SideNavigation.Item>\n            <SideNavigation.Item href=\"#form-section\">FormSection</SideNavigation.Item>\n            <SideNavigation.Item href=\"#side-navigation\">SideNavigation</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"API Reference\">\n            <SideNavigation.Item href=\"#props\">Props</SideNavigation.Item>\n            <SideNavigation.Item href=\"#types\">Types</SideNavigation.Item>\n            <SideNavigation.Item href=\"#css-variables\">CSS variables</SideNavigation.Item>\n          </SideNavigation.Group>\n        </SideNavigation>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1.5rem;\">\n      <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n        Main content area. Resize the browser viewport below ~767px to see the navigation collapse\n        into a mobile drawer.\n      </p>\n    </main>\n  </div>\n</div>\n"
     }
   ]
 }

package/src/components/sidebar/README.md

@@ -9,7 +9,11 @@ Persistent side panel that houses navigation, filters, or supplementary page con
   import Sidebar from '@lostgradient/cinder/sidebar';
 </script>
 
-<Sidebar />
+<Sidebar label="App sidebar">
+  {#snippet navigation()}
+    <nav><!-- navigation items --></nav>
+  {/snippet}
+</Sidebar>
 ```
 
 ## Props
@@ -18,9 +22,9 @@ Persistent side panel that houses navigation, filters, or supplementary page con
 
 | Prop         | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                                                              |
 | ------------ | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ariaLabel`  | `string`   | no       | —       | Accessible name for the outer landmark and the mobile drawer. Required — defaults to `'Sidebar'` for convenience but must be unique per page. The inner `<nav>` landmark derives its own accessible name from this value by appending `' navigation'` so screen readers can distinguish the outer complementary region from the inner navigation region. |
 | `class`      | `string`   | no       | —       | Additional CSS class merged with `.cinder-sidebar`.                                                                                                                                                                                                                                                                                                      |
 | `collapsed`  | `boolean`  | no       | —       | Whether the sidebar is collapsed. Bindable via `bind:collapsed`. Default `false`. On desktop (>= md breakpoint) `collapsed=true` switches the sidebar to icon-only mode. Below the md breakpoint the sidebar renders inside a `<Drawer>` and `collapsed=true` means the drawer is closed.                                                                |
+| `label`      | `string`   | no       | —       | Accessible name for the outer landmark and the mobile drawer. Required — defaults to `'Sidebar'` for convenience but must be unique per page. The inner `<nav>` landmark derives its own accessible name from this value by appending `' navigation'` so screen readers can distinguish the outer complementary region from the inner navigation region. |
 | `brand`      | `(opaque)` | no       | —       | Optional branding region rendered above the navigation. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                       |
 | `footer`     | `(opaque)` | no       | —       | Optional footer region (e.g. user account, sign-out). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                         |
 | `navigation` | `(opaque)` | no       | —       | Navigation region. Typically a `<SideNavigation>` subtree. Optional — when omitted, no `<nav>` landmark is rendered (so the sidebar can serve as app chrome without a navigation list, and an empty `<nav>` isn't announced to screen readers). Not expressible in JSON Schema; see the component types for the signature.                               |

package/src/components/sidebar/sidebar.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic sidebar",
       "description": "Layout-level sidebar with brand, navigation, and footer regions. Collapse toggles icon-only mode on desktop and closes the drawer on mobile.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { SideNavigationGroup } from '@lostgradient/cinder/side-navigation-group';\n  import { SideNavigationItem } from '@lostgradient/cinder/side-navigation-item';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 24rem; border: 1px solid #e5e7eb; border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed ariaLabel=\"Workspace\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Workspace sections\">\n          {#snippet children()}\n            <SideNavigationItem href=\"#dashboard\">\n              {#snippet children()}Dashboard{/snippet}\n            </SideNavigationItem>\n            <SideNavigationItem href=\"#projects\" active>\n              {#snippet children()}Projects{/snippet}\n            </SideNavigationItem>\n            <SideNavigationGroup label=\"Settings\">\n              {#snippet children()}\n                <SideNavigationItem href=\"#general\">\n                  {#snippet children()}General{/snippet}\n                </SideNavigationItem>\n                <SideNavigationItem href=\"#billing\">\n                  {#snippet children()}Billing{/snippet}\n                </SideNavigationItem>\n              {/snippet}\n            </SideNavigationGroup>\n          {/snippet}\n        </SideNavigation>\n      {/snippet}\n\n      {#snippet footer()}\n        <NavigationItem variant=\"vertical\" href=\"#account\">\n          {#snippet children()}Account{/snippet}\n        </NavigationItem>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1rem;\">\n      <p>Main content area.</p>\n      <p>Resize the viewport below ~767px to see the mobile drawer behavior.</p>\n    </main>\n  </div>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { SideNavigationGroup } from '@lostgradient/cinder/side-navigation-group';\n  import { SideNavigationItem } from '@lostgradient/cinder/side-navigation-item';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 24rem; border: 1px solid #e5e7eb; border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed label=\"Workspace\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Workspace sections\">\n          {#snippet children()}\n            <SideNavigationItem href=\"#dashboard\">\n              {#snippet children()}Dashboard{/snippet}\n            </SideNavigationItem>\n            <SideNavigationItem href=\"#projects\" active>\n              {#snippet children()}Projects{/snippet}\n            </SideNavigationItem>\n            <SideNavigationGroup label=\"Settings\">\n              {#snippet children()}\n                <SideNavigationItem href=\"#general\">\n                  {#snippet children()}General{/snippet}\n                </SideNavigationItem>\n                <SideNavigationItem href=\"#billing\">\n                  {#snippet children()}Billing{/snippet}\n                </SideNavigationItem>\n              {/snippet}\n            </SideNavigationGroup>\n          {/snippet}\n        </SideNavigation>\n      {/snippet}\n\n      {#snippet footer()}\n        <NavigationItem variant=\"vertical\" href=\"#account\">\n          {#snippet children()}Account{/snippet}\n        </NavigationItem>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1rem;\">\n      <p>Main content area.</p>\n      <p>Resize the viewport below ~767px to see the mobile drawer behavior.</p>\n    </main>\n  </div>\n</div>\n"
     }
   ]
 }