@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/sheet/README.md

@@ -2,12 +2,12 @@
 
 Bottom-anchored overlay panel optimised for mobile-style drawer interactions.
 
-## When to use
+## Choosing this component
 
 - Action sheets and option pickers on mobile or touch-first layouts where a bottom-up slide feels natural.
 - Quick-select panels (share, sort, filter) that need to feel native on small screens.
 
-## When not to use
+## Choosing something else
 
 - Desktop-first side panels — use [`Drawer`](../drawer/README.md) for left/right edge placement.
 - Full-attention blocking dialogs — use [`Modal`](../modal/README.md) when the user must act before continuing.
@@ -38,10 +38,10 @@ Bottom-anchored overlay panel optimised for mobile-style drawer interactions.
 | `open`           | `boolean`  | no       | —       | Whether the sheet is open. Bindable via `bind:open`.                                                                                                                                                                                                                                                                             |
 | `showDragHandle` | `boolean`  | no       | —       | When `true`, render a decorative drag handle above the header. Swipe-to-close gesture is a stretch goal not implemented in MVP — the handle is purely a visual affordance. Default `false`. Named `showDragHandle` (not `draggable`) to avoid colliding with the native HTML `draggable` attribute on the underlying `<dialog>`. |
 | `title`          | `string`   | yes      | —       | Accessible name for the sheet. Required for screen-reader labelling. Rendered as a visible `<h2>` in the default header. When a custom `header` snippet is provided without `ariaLabelledBy`, this text is rendered in a visually-hidden `<h2>` as the accessible name fallback.                                                 |
-| `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.                                                                                                                                                                                                       |
-| `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.                                                                                                                                                                                                       |
-| `header`         | `(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.                                                                                                                                                                                                                          |
+| `children`       | `(opaque)` | yes      | —       | Sheet body content. Required. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                         |
+| `footer`         | `(opaque)` | no       | —       | Optional footer (e.g. action buttons). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                |
+| `header`         | `(opaque)` | no       | —       | Custom header. Falls back to a default header that renders `title`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                   |
+| `triggerRef`     | `(opaque)` | no       | —       | Optional reference to the element that opened the sheet. When supplied, focus returns to this element on close. When omitted, focus restores to the element that held focus before the sheet opened. Not expressible in JSON Schema; see the component types for the signature.                                                  |
 
 <!-- generated:props:end -->
 

package/src/components/sheet/sheet.svelte

@@ -19,12 +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),
@@ -44,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(() => {
@@ -122,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"
@@ -240,12 +126,17 @@
       </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 && !dialogState.isClosing,
+          restoreFocus: false,
+          manageInitialFocus: false,
+        })}
       >
         {#if showDragHandle}
           <div class="cinder-sheet__drag-handle" aria-hidden="true">

package/src/components/shortcut-hint/README.md

@@ -25,13 +25,13 @@ Inline shortcut hint that renders a key combo via Kbd alongside an action label,
 
 <!-- generated:props:start -->
 
-| Prop           | Type                    | Required | Default   | Description                                                                                                                |
-| -------------- | ----------------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`                | no       | —         | Additional class names merged with `.cinder-shortcut-hint`.                                                                |
-| `keys`         | `string`[]              | yes      | —         | The key sequence to display.                                                                                               |
-| `keysLabel`    | `string`                | no       | —         | Accessible label for the key combo.                                                                                        |
-| `keysPosition` | `"before"` \| `"after"` | no       | `"after"` | Position of keys relative to children.                                                                                     |
-| `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. |
+| Prop           | Type                    | Required | Default   | Description                                                                                                           |
+| -------------- | ----------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`                | no       | —         | Additional class names merged with `.cinder-shortcut-hint`.                                                           |
+| `keys`         | `string`[]              | yes      | —         | The key sequence to display.                                                                                          |
+| `keysLabel`    | `string`                | no       | —         | Accessible label for the key combo.                                                                                   |
+| `keysPosition` | `"before"` \| `"after"` | no       | `"after"` | Position of keys relative to children.                                                                                |
+| `children`     | `(opaque)`              | no       | —         | The action label rendered beside the keys. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

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/README.md

@@ -28,11 +28,11 @@ The leaves remain importable individually for à-la-carte builds — see
 
 <!-- generated:props:start -->
 
-| Prop        | Type       | Required | Default | Description                                                                                                                |
-| ----------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `ariaLabel` | `string`   | yes      | —       | Accessible name for the <nav> landmark. Required, non-empty, distinct from other navs on the page.                         |
-| `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. |
-| `class`     | `(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                                                                                                                                            |
+| ----------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ariaLabel` | `string`   | yes      | —       | Accessible name for the <nav> landmark. Required, non-empty, distinct from other navs on the page.                                                     |
+| `children`  | `(opaque)` | yes      | —       | Must be <li> elements containing NavigationItem and/or SideNavigationGroup. Not expressible in JSON Schema; see the component types for the signature. |
+| `class`     | `(opaque)` | no       | —       | Additional CSS class merged with `.cinder-side-navigation`. Not expressible in JSON Schema; see the component types for the signature.                 |
 
 <!-- generated:props:end -->
 

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

@@ -12,8 +12,8 @@
     {
       "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"
+      "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 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/side-navigation-group/README.md

@@ -14,16 +14,16 @@ snippet. The flat `@lostgradient/cinder/side-navigation-group` subpath remains e
 
 <!-- generated:props:start -->
 
-| Prop       | Type       | Required | Default | Description                                                                                                                    |
-| ---------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `disabled` | `boolean`  | no       | —       | When true, the disclosure button is disabled. Default: false.                                                                  |
-| `expanded` | `boolean`  | no       | —       | Whether the group is expanded. Bindable. Default: true.                                                                        |
-| `id`       | `string`   | no       | —       | Optional stable id for the root <li>. Trigger uses `${id}-trigger`, panel uses `${id}-panel`. If omitted, generated via useId. |
-| `label`    | `string`   | yes      | —       | Visible section header label.                                                                                                  |
-| `badge`    | `(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       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.     |
-| `class`    | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                        |
-| `icon`     | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.     |
+| Prop       | Type       | Required | Default | Description                                                                                                                                                                  |
+| ---------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `disabled` | `boolean`  | no       | —       | When true, the disclosure button is disabled. Default: false.                                                                                                                |
+| `expanded` | `boolean`  | no       | —       | Whether the group is expanded. Bindable. Default: true.                                                                                                                      |
+| `id`       | `string`   | no       | —       | Optional stable id for the root <li>. Trigger uses `${id}-trigger`, panel uses `${id}-panel`. If omitted, generated via useId.                                               |
+| `label`    | `string`   | yes      | —       | Visible section header label.                                                                                                                                                |
+| `badge`    | `(opaque)` | no       | —       | Optional trailing badge rendered inside the header button after the label, before the chevron. Not expressible in JSON Schema; see the component types for the signature.    |
+| `children` | `(opaque)` | yes      | —       | Must be <li>-wrapped NavigationItems (or SideNavigationItems) rendered inside the disclosed <ul>. Not expressible in JSON Schema; see the component types for the signature. |
+| `class`    | `(opaque)` | no       | —       | Additional CSS class merged with `.cinder-side-navigation-group`. Not expressible in JSON Schema; see the component types for the signature.                                 |
+| `icon`     | `(opaque)` | no       | —       | Optional leading icon rendered inside the header button before the label. Not expressible in JSON Schema; see the component types for the signature.                         |
 
 <!-- generated:props:end -->
 

package/src/components/side-navigation-item/README.md

@@ -14,16 +14,16 @@ snippet. The flat `@lostgradient/cinder/side-navigation-item` subpath remains ex
 
 <!-- generated:props:start -->
 
-| Prop            | Type                                                                     | Required | Default | Description                                                                                                                                                                                                                                                                                                                                            |
-| --------------- | ------------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `active`        | `boolean`                                                                | no       | —       |                                                                                                                                                                                                                                                                                                                                                        |
-| `class`         | `string`                                                                 | no       | —       |                                                                                                                                                                                                                                                                                                                                                        |
-| `current`       | `"true"` \| `"page"` \| `"step"` \| `"location"` \| `"date"` \| `"time"` | no       | —       | The `aria-current` token emitted while `active` is true. Defaults to `'page'`, which is correct for navigation bars and breadcrumb-adjacent links. Use `'true'` (or another standard token such as `'step'` / `'location'`) for section/view switchers, where `'page'` would mislabel the current section as the current page in the browsing context. |
-| `disabled`      | `boolean`                                                                | no       | —       |                                                                                                                                                                                                                                                                                                                                                        |
-| `href`          | `string`                                                                 | no       | —       |                                                                                                                                                                                                                                                                                                                                                        |
-| `listItemClass` | `string`                                                                 | no       | —       | Class merged onto the outer <li>.                                                                                                                                                                                                                                                                                                                      |
-| `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.                                                                                                                                                                                                                             |
-| `onclick`       | `(opaque)`                                                               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                             |
+| Prop            | Type                                                                     | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `active`        | `boolean`                                                                | no       | —       | Marks this item as the currently active destination; emits `aria-current` and applies active visual styling.                                                                                                                                                                                                                                                   |
+| `class`         | `string`                                                                 | no       | —       | Additional class merged onto the `.cinder-navigation-item` root element.                                                                                                                                                                                                                                                                                       |
+| `current`       | `"true"` \| `"page"` \| `"step"` \| `"location"` \| `"date"` \| `"time"` | no       | —       | The `aria-current` token emitted while `active` is true. Defaults to `'page'`, which is correct for navigation bars and breadcrumb-adjacent links. Use `'true'` (or another standard token such as `'step'` / `'location'`) for section/view switchers, where `'page'` would mislabel the current section as the current page in the browsing context.         |
+| `disabled`      | `boolean`                                                                | no       | —       | Prevents interaction: removes the item from the tab order, blocks clicks, and applies disabled visual styling.                                                                                                                                                                                                                                                 |
+| `href`          | `string`                                                                 | no       | —       | Destination URL. Providing this prop renders the item as an `<a>` element instead of a `<button>`.                                                                                                                                                                                                                                                             |
+| `listItemClass` | `string`                                                                 | no       | —       | Class merged onto the outer <li>.                                                                                                                                                                                                                                                                                                                              |
+| `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.                                                                                                                                                                                                                                     |
+| `onclick`       | `(opaque)`                                                               | no       | —       | Optional click handler called for the rendered `<a>` element. Useful for intercepting plain left-clicks for SPA navigation while letting modified clicks (cmd/ctrl/shift/alt or middle-click) fall through to native browser behavior. Disabled-state preventDefault still applies. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

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,12 +22,12 @@ 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.                                                                |
-| `brand`      | `(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.                                                                                                                                                                                                                               |
-| `navigation` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                               |
+| `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.                               |
 
 <!-- generated:props:end -->
 

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"
     }
   ]
 }

package/src/components/sidebar/sidebar.svelte

@@ -31,7 +31,7 @@
   let {
     id: sidebarId,
     collapsed = $bindable(false),
-    ariaLabel = 'Sidebar',
+    label = 'Sidebar',
     class: className,
     brand: brandSnippet,
     navigation: navigationSnippet,
@@ -42,10 +42,10 @@
   }: SidebarRuntimeProps = $props();
 
   const validatedLabel = $derived.by(() => {
-    if (ariaLabel.trim() === '') {
-      throw new Error('Sidebar requires a non-empty ariaLabel.');
+    if (label.trim() === '') {
+      throw new Error('Sidebar requires a non-empty label.');
     }
-    return ariaLabel;
+    return label;
   });
 
   // The inner <nav> landmark gets a distinct accessible name so the outer

package/src/components/sidebar/sidebar.types.ts

@@ -20,7 +20,7 @@ export type SidebarProps = Omit<
    * by appending `' navigation'` so screen readers can distinguish the
    * outer complementary region from the inner navigation region.
    */
-  ariaLabel?: string;
+  label?: string;
   /** Additional CSS class merged with `.cinder-sidebar`. */
   class?: string;
   /** Optional branding region rendered above the navigation. */

package/src/components/skeleton/README.md

@@ -16,12 +16,12 @@ Animated placeholder shape that fills content areas while data is loading.
 
 <!-- generated:props:start -->
 
-| Prop     | Type     | Required | Default | Description |
-| -------- | -------- | -------- | ------- | ----------- |
-| `class`  | `string` | no       | —       |             |
-| `height` | `string` | no       | —       |             |
-| `radius` | `string` | no       | —       |             |
-| `width`  | `string` | no       | —       |             |
+| Prop     | Type     | Required | Default | Description                                                                                                    |
+| -------- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
+| `class`  | `string` | no       | —       | Additional class merged onto the `.cinder-skeleton` root element.                                              |
+| `height` | `string` | no       | —       | CSS height value applied as an inline style on the skeleton block (e.g. `'1rem'`, `'48px'`).                   |
+| `radius` | `string` | no       | —       | CSS border-radius value applied as an inline style, overriding the default pill shape (e.g. `'4px'`, `'50%'`). |
+| `width`  | `string` | no       | —       | CSS width value applied as an inline style on the skeleton block (e.g. `'200px'`, `'100%'`).                   |
 
 <!-- generated:props:end -->
 

package/src/components/skeleton/skeleton.types.ts

@@ -1,7 +1,11 @@
 /** Props for the Skeleton component. */
 export type SkeletonProps = {
+  /** CSS width value applied as an inline style on the skeleton block (e.g. `'200px'`, `'100%'`). */
   width?: string;
+  /** CSS height value applied as an inline style on the skeleton block (e.g. `'1rem'`, `'48px'`). */
   height?: string;
+  /** CSS border-radius value applied as an inline style, overriding the default pill shape (e.g. `'4px'`, `'50%'`). */
   radius?: string;
+  /** Additional class merged onto the `.cinder-skeleton` root element. */
   class?: string;
 };

package/src/components/skip-link/README.md

@@ -26,10 +26,11 @@ The default label is "Skip to main content"; pass children to override it. SkipL
 
 <!-- generated:props:start -->
 
-| Prop     | Type     | Required | Default | Description                                                          |
-| -------- | -------- | -------- | ------- | -------------------------------------------------------------------- |
-| `class`  | `string` | no       | —       | Additional classes merged onto the visually-hidden anchor.           |
-| `target` | `string` | yes      | —       | The `id` of the element to receive focus when the link is activated. |
+| Prop       | Type       | Required | Default | Description                                                                                                                                             |
+| ---------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`   | no       | —       | Additional classes merged onto the visually-hidden anchor.                                                                                              |
+| `target`   | `string`   | yes      | —       | The `id` of the element to receive focus when the link is activated.                                                                                    |
+| `children` | `(opaque)` | no       | —       | Optional override for the visible label. Defaults to "Skip to main content". Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/skip-link/skip-link.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic usage",
       "description": "Tab into this example to reveal the skip link, then press Enter to jump focus to the main content area.",
-      "code": "<script lang=\"ts\">\n  import { SkipLink } from '@lostgradient/cinder/skip-link';\n</script>\n\n<div\n  style=\"position: relative; min-height: 80px; border: 1px dashed var(--cinder-border); border-radius: 4px; padding: 1rem;\"\n>\n  <SkipLink target=\"skip-link-example-main\" />\n\n  <nav aria-label=\"Example navigation\">\n    <a href=\"#skip-link-example-main\" style=\"margin-right: 1rem;\">Home</a>\n    <a href=\"#skip-link-example-main\" style=\"margin-right: 1rem;\">About</a>\n    <a href=\"#skip-link-example-main\">Contact</a>\n  </nav>\n\n  <main id=\"skip-link-example-main\" style=\"margin-top: 1rem;\">\n    <p>Main content area. Focus lands here when the skip link is activated.</p>\n  </main>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { SkipLink } from '@lostgradient/cinder/skip-link';\n\n</script>\n\n<div\n  style=\"position: relative; min-height: 80px; border: 1px dashed var(--cinder-border); border-radius: 4px; padding: 1rem;\"\n>\n  <SkipLink target=\"main\" />\n\n  <nav aria-label=\"Example navigation\">\n    <a href=\"#main\" style=\"margin-right: 1rem;\">Home</a>\n    <a href=\"#main\" style=\"margin-right: 1rem;\">About</a>\n    <a href=\"#main\">Contact</a>\n  </nav>\n\n  <main id=\"main\" style=\"margin-top: 1rem;\">\n    <p>Main content area. Focus lands here when the skip link is activated.</p>\n  </main>\n</div>\n"
     }
   ]
 }