@lostgradient/cinder 0.2.0 → 0.3.0

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

@@ -17,7 +17,6 @@
 
 <script lang="ts">
   import { onDestroy } from 'svelte';
-  import { BROWSER } from 'esm-env';
 
   import { classNames } from '../../utilities/class-names.ts';
   import { copyToClipboard } from '../../utilities/clipboard.ts';
@@ -43,9 +42,22 @@
   let resetTimer: ReturnType<typeof setTimeout> | undefined;
   let announcement = $state('');
 
-  // Detect native share support. Only available in a browser with a secure origin.
+  // Hydration gate. The native-share button depends on `navigator.share`, which
+  // only exists in the browser — but gating it on a plain browser check would
+  // make the client's first render add a button the server never emitted,
+  // producing a hydration mismatch. `$effect` runs only on the client, AFTER
+  // hydration, so the server render and the initial client render both omit the
+  // button; it appears on the next tick once `hydrated` flips. Matches the
+  // toast-region / drawer hydration-gate convention.
+  let hydrated = $state(false);
+  $effect(() => {
+    hydrated = true;
+  });
+
+  // Detect native share support. Gated on `hydrated` (not a bare browser flag)
+  // so it is always `false` during SSR and the initial hydration render.
   const canNativeShare = $derived(
-    BROWSER && typeof navigator !== 'undefined' && typeof navigator.share === 'function',
+    hydrated && typeof navigator !== 'undefined' && typeof navigator.share === 'function',
   );
 
   let announceTimer: ReturnType<typeof setTimeout> | undefined;
@@ -154,30 +166,21 @@
     clearTimer();
   });
 
-  // Build the default actions when no explicit actions are provided. The default
-  // surface always offers copy (the universal fallback); the native-share button
-  // is added only where `navigator.share` exists, so there is no redundant
-  // "Share" button that merely re-copies on unsupported platforms. A consumer who
-  // wants a share button that copies-when-unavailable can pass an explicit action
-  // with `useNativeShare: true` — `handleNativeShare` falls back to copy for it.
-  const resolvedActions = $derived.by((): ShareCardAction[] => {
-    if (actions) return actions;
-    const defaultActions: ShareCardAction[] = [
-      {
-        key: 'copy-link',
-        label: copyLinkLabel,
-        copyValue: value,
-      },
-    ];
-    if (canNativeShare) {
-      defaultActions.push({
-        key: 'native-share',
-        label: shareLabel,
-        useNativeShare: true,
-      });
-    }
-    return defaultActions;
-  });
+  // The action list: explicit `actions` verbatim, else the copy-link default.
+  // The default native-share button is NOT in this array — it is rendered by a
+  // standalone `{#if !actions && canNativeShare}` in the template. `canNativeShare`
+  // only flips true after hydration (it is gated on the `hydrated` $effect), and
+  // when the native-share action was instead appended to this reactive array
+  // post-hydration, the keyed `{#each}` did not render it. The standalone `{#if}`
+  // (matching the drawer/sheet hydration convention) renders reliably on the flip.
+  const defaultActions: ShareCardAction[] = $derived([
+    {
+      key: 'copy-link',
+      label: copyLinkLabel,
+      copyValue: value,
+    },
+  ]);
+  const resolvedActions = $derived(actions ?? defaultActions);
 </script>
 
 <div {...rest} class={classNames('cinder-share-card', customClassName)}>
@@ -206,125 +209,140 @@
   <div class="cinder-share-card__actions" role="group" aria-label="Share actions">
     {#each resolvedActions as action (action.key)}
       {#if action.key === 'native-share' || action.useNativeShare}
-        <!-- When native share is unavailable or fails, `handleNativeShare` falls
-             back to a clipboard copy keyed `share-fallback`. Reflect that copied
-             state on the share button so the visual matches the live-region
-             announcement instead of silently staying on the Share label. -->
-        {@const shareCopied = copiedKey === 'share-fallback'}
-        <button
-          type="button"
-          class="cinder-share-card__action"
-          data-cinder-action={action.key}
-          data-cinder-copied={shareCopied ? '' : undefined}
-          onclick={() => {
-            // Honour a consumer onClick (analytics/side-effects) on the native
-            // share action too, then run the share. `void` marks the floating
-            // promise as intentional (the handler is synchronous).
-            action.onClick?.();
-            void handleNativeShare();
-          }}
-          aria-label={shareCopied ? copiedLabel : action.label}
-        >
-          {#if shareCopied}
-            <!-- Copied state icon (after a fallback copy) -->
-            <span class="cinder-share-card__action-icon" aria-hidden="true">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                class="cinder-share-card__icon"
-              >
-                <polyline points="20,6 9,17 4,12" />
-              </svg>
-            </span>
-            {copiedLabel}
-          {:else}
-            <!-- Share icon -->
-            <span class="cinder-share-card__action-icon" aria-hidden="true">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                class="cinder-share-card__icon"
-              >
-                <circle cx="18" cy="5" r="3" />
-                <circle cx="6" cy="12" r="3" />
-                <circle cx="18" cy="19" r="3" />
-                <line x1="8.59" y1="13.51" x2="15.42" y2="17.49" />
-                <line x1="15.41" y1="6.51" x2="8.59" y2="10.49" />
-              </svg>
-            </span>
-            {action.label}
-          {/if}
-        </button>
+        {@render shareButton(action)}
       {:else}
-        <button
-          type="button"
-          class="cinder-share-card__action"
-          data-cinder-action={action.key}
-          data-cinder-copied={copiedKey === action.key ? '' : undefined}
-          onclick={() => {
-            // onClick is a side-effect callback (e.g. analytics), NOT an
-            // override — run it AND still perform the copy when copyValue is
-            // present, matching the native-share button's behaviour. An empty
-            // string is a legitimate copyValue, so test for `undefined`, not
-            // truthiness. `void` marks the floating promise as intentional.
-            action.onClick?.();
-            if (action.copyValue !== undefined) {
-              void handleCopy(action.key, action.copyValue);
-            }
-          }}
-          aria-label={copiedKey === action.key ? copiedLabel : action.label}
-        >
-          {#if copiedKey === action.key}
-            <!-- Copied state icon -->
-            <span class="cinder-share-card__action-icon" aria-hidden="true">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                class="cinder-share-card__icon"
-              >
-                <polyline points="20,6 9,17 4,12" />
-              </svg>
-            </span>
-            {copiedLabel}
-          {:else}
-            <!-- Copy icon -->
-            <span class="cinder-share-card__action-icon" aria-hidden="true">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                class="cinder-share-card__icon"
-              >
-                <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
-                <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
-              </svg>
-            </span>
-            {action.label}
-          {/if}
-        </button>
+        {@render copyButton(action)}
       {/if}
     {/each}
+    <!-- The default native-share button is gated by a standalone `{#if}` rather
+         than pushed into `resolvedActions`, so it reconciles correctly when
+         `canNativeShare` flips from false to true after hydration. Only rendered
+         in the default surface (no explicit `actions`); a consumer-supplied
+         native-share action goes through the `{#each}` above. -->
+    {#if !actions && canNativeShare}
+      {@render shareButton({ key: 'native-share', label: shareLabel, useNativeShare: true })}
+    {/if}
   </div>
 </div>
 
+<!-- Native-share button. Reflects the `share-fallback` copied state so that when
+     `handleNativeShare` falls back to a clipboard copy (native share unavailable
+     or failed) the visual matches the live-region announcement instead of staying
+     on the Share label. -->
+{#snippet shareButton(action: ShareCardAction)}
+  {@const shareCopied = copiedKey === 'share-fallback'}
+  <button
+    type="button"
+    class="cinder-share-card__action"
+    data-cinder-action={action.key}
+    data-cinder-copied={shareCopied ? '' : undefined}
+    onclick={() => {
+      // Honour a consumer onClick (analytics/side-effects) on the native share
+      // action too, then run the share. `void` marks the floating promise as
+      // intentional (the handler is synchronous).
+      action.onClick?.();
+      void handleNativeShare();
+    }}
+    aria-label={shareCopied ? copiedLabel : action.label}
+  >
+    {#if shareCopied}
+      <!-- Copied state icon (after a fallback copy) -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <polyline points="20,6 9,17 4,12" />
+        </svg>
+      </span>
+      {copiedLabel}
+    {:else}
+      <!-- Share icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <circle cx="18" cy="5" r="3" />
+          <circle cx="6" cy="12" r="3" />
+          <circle cx="18" cy="19" r="3" />
+          <line x1="8.59" y1="13.51" x2="15.42" y2="17.49" />
+          <line x1="15.41" y1="6.51" x2="8.59" y2="10.49" />
+        </svg>
+      </span>
+      {action.label}
+    {/if}
+  </button>
+{/snippet}
+
+<!-- Copy button. `onClick` is a side-effect callback (e.g. analytics), NOT an
+     override — it runs AND the copy still fires when `copyValue` is present. An
+     empty string is a legitimate copyValue, so test for `undefined`, not
+     truthiness. -->
+{#snippet copyButton(action: ShareCardAction)}
+  <button
+    type="button"
+    class="cinder-share-card__action"
+    data-cinder-action={action.key}
+    data-cinder-copied={copiedKey === action.key ? '' : undefined}
+    onclick={() => {
+      action.onClick?.();
+      if (action.copyValue !== undefined) {
+        void handleCopy(action.key, action.copyValue);
+      }
+    }}
+    aria-label={copiedKey === action.key ? copiedLabel : action.label}
+  >
+    {#if copiedKey === action.key}
+      <!-- Copied state icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <polyline points="20,6 9,17 4,12" />
+        </svg>
+      </span>
+      {copiedLabel}
+    {:else}
+      <!-- Copy icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+          <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+        </svg>
+      </span>
+      {action.label}
+    {/if}
+  </button>
+{/snippet}
+
 <!-- Announce copy/share outcomes to assistive technology. -->
 <VisuallyHiddenLiveRegion message={announcement} />

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

@@ -22,6 +22,7 @@
   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';
@@ -246,6 +247,11 @@
         class="cinder-sheet__panel"
         data-cinder-closing={isClosing ? '' : undefined}
         inert={isClosing}
+        {@attach createFocusTrap({
+          active: () => open && !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/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 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"
     }
   ]
 }

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

@@ -21,9 +21,9 @@ Persistent side panel that houses navigation, filters, or supplementary page con
 | `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.                                                                                                                                                                                                                               |
+| `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/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"
     }
   ]
 }