@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/masonry/masonry.css

@@ -0,0 +1,12 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  .cinder-masonry {
+    column-count: var(--cinder-masonry-columns, 3);
+    column-gap: var(--cinder-masonry-gap, var(--cinder-space-4));
+  }
+
+  .cinder-masonry > * {
+    break-inside: avoid;
+    margin-block-end: var(--cinder-masonry-gap, var(--cinder-space-4));
+  }
+}

package/src/components/masonry/masonry.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "masonry",
+  "import": "@lostgradient/cinder/masonry",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Variable-height cards",
+      "description": "CSS columns pack uneven cards into a masonry-style waterfall while keeping DOM order intact.",
+      "code": "<script lang=\"ts\">\n  import { Card } from '@lostgradient/cinder/card';\n  import { Masonry } from '@lostgradient/cinder/masonry';\n</script>\n\n<Masonry columns=\"3\" gap=\"var(--cinder-space-4)\" aria-label=\"Editorial cards\">\n  <Card>Short note.</Card>\n  <Card>\n    Longer content with enough copy to create a taller card. CSS columns balance the available\n    vertical space without JavaScript measurement.\n  </Card>\n  <Card>Medium content with a couple of lines.</Card>\n  <Card>Another taller item that demonstrates variable height placement across columns.</Card>\n</Masonry>\n"
+    }
+  ]
+}

package/src/components/masonry/masonry.svelte

@@ -0,0 +1,39 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category layout
+   * @status beta
+   * @purpose Pure CSS waterfall layout that packs variable-height children into balanced columns.
+   * @tag layout
+   * @tag masonry
+   * @useWhen Displaying cards, images, or panels with uneven heights where CSS column order is acceptable.
+   * @avoidWhen Items have equal heights - use grid-list instead. | grid-list
+   * @avoidWhen Left-to-right row reading order matters - use grid instead. | grid
+   * @related grid, grid-list
+   */
+  export type { MasonryProps } from './masonry.types.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import type { MasonryProps } from './masonry.types.ts';
+
+  let {
+    columns,
+    gap,
+    as = 'div',
+    class: customClassName,
+    children,
+    ...rest
+  }: MasonryProps = $props();
+</script>
+
+<svelte:element
+  this={as}
+  {...rest}
+  class={classNames('cinder-masonry', customClassName)}
+  style:--cinder-masonry-columns={columns}
+  style:--cinder-masonry-gap={gap}
+>
+  {@render children?.()}
+</svelte:element>

package/src/components/masonry/masonry.types.ts

@@ -0,0 +1,16 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Props for the Masonry component. */
+export type MasonryProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** CSS column count value. */
+  columns?: string;
+  /** Gap between columns and between direct children. */
+  gap?: string;
+  /** Rendered HTML tag. */
+  as?: string;
+  /** Custom class merged with `.cinder-masonry`. */
+  class?: string;
+  /** Masonry contents. */
+  children: Snippet;
+};

package/src/components/matrix-chart/README.md

@@ -26,21 +26,23 @@ Categorical × categorical heatmap for dense analytics, confusion matrices, and
 
 <!-- generated:props:start -->
 
-| Prop                  | Type                                                | Required | Default | Description |
-| --------------------- | --------------------------------------------------- | -------- | ------- | ----------- |
-| `class`               | `string`                                            | no       | —       |             |
-| `colorScale`          | `"sequential"` \| `"diverging"`                     | no       | —       |             |
-| `data`                | `object`[]                                          | yes      | —       |             |
-| `dataTableCaption`    | `string`                                            | no       | —       |             |
-| `dataTableVisibility` | `"screen-reader-only"` \| `"visible"` \| `"hidden"` | no       | —       |             |
-| `description`         | `string`                                            | no       | —       |             |
-| `height`              | `number`                                            | no       | —       |             |
-| `label`               | `string`                                            | yes      | —       |             |
-| `loading`             | `boolean`                                           | no       | —       |             |
-| `showCellLabels`      | `boolean`                                           | no       | —       |             |
-| `valueField`          | `string`                                            | yes      | —       |             |
-| `xField`              | `string`                                            | yes      | —       |             |
-| `yField`              | `string`                                            | yes      | —       |             |
+| Prop                  | Type                                                | Required | Default | Description                                                                                                             |
+| --------------------- | --------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `class`               | `string`                                            | no       | —       | Custom class applied to the root element.                                                                               |
+| `colorScale`          | `"sequential"` \| `"diverging"`                     | no       | —       | Color interpolation scale. Default `sequential`.                                                                        |
+| `data`                | `object`[]                                          | yes      | —       | Rows of data. Each row must include the keys named by the `xField`, `yField`, and `valueField` props.                   |
+| `dataTableCaption`    | `string`                                            | no       | —       | Custom data table caption; falls back to `label`.                                                                       |
+| `dataTableVisibility` | `"screen-reader-only"` \| `"visible"` \| `"hidden"` | no       | —       | Controls data table visibility. Default `screen-reader-only`.                                                           |
+| `description`         | `string`                                            | no       | —       | Optional description rendered below the label.                                                                          |
+| `height`              | `number`                                            | no       | —       | Pixel height of the chart viewport. Default `280`.                                                                      |
+| `label`               | `string`                                            | yes      | —       | Accessible label for the chart. Required for screen readers.                                                            |
+| `loading`             | `boolean`                                           | no       | —       | Whether the chart is in a loading state. Default `false`.                                                               |
+| `showCellLabels`      | `boolean`                                           | no       | —       | Show cell value labels. Default `true`.                                                                                 |
+| `valueField`          | `string`                                            | yes      | —       | Key on each datum used for the numeric cell value.                                                                      |
+| `xField`              | `string`                                            | yes      | —       | Key on each datum used for the x-axis (columns).                                                                        |
+| `yField`              | `string`                                            | yes      | —       | Key on each datum used for the y-axis (rows).                                                                           |
+| `empty`               | `(opaque)`                                          | no       | —       | Snippet rendered when the chart has no data. Not expressible in JSON Schema; see the component types for the signature. |
+| `loadingContent`      | `(opaque)`                                          | no       | —       | Snippet rendered while the chart is loading. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/matrix-chart/matrix-chart.css

@@ -28,6 +28,10 @@
     stroke-width: 1.5;
   }
 
+  .cinder-matrix-chart__cell[data-cinder-active] {
+    filter: brightness(1.15);
+  }
+
   .cinder-matrix-chart__cell-label {
     font-size: var(--cinder-text-xs);
     pointer-events: none;

package/src/components/matrix-chart/matrix-chart.svelte

@@ -200,6 +200,15 @@
 
   const hasDataTable = $derived(dataTableVisibility !== 'hidden');
 
+  // Pointer hover tracking: the key of the cell under the pointer, or null.
+  // Each cell rect sets this on pointerenter; the plot group clears it on leave.
+  // Hovering a cell also surfaces its native <title> (the value-on-hover tooltip).
+  let hoveredCellKey = $state<string | null>(null);
+
+  function handlePlotPointerLeave(): void {
+    hoveredCellKey = null;
+  }
+
   // Table rows for the data table fallback: xLabel × yLabel grid. Reuses the
   // nested lookup (O(1) per cell) instead of scanning the flattened cells array.
   const tableRows = $derived.by(() => {
@@ -252,7 +261,14 @@
            heatmap cells/labels would draw under the loading or empty overlay
            (data may be present while loading, so isEmpty alone is not enough). -->
       {#if !loading && !isEmpty}
-        <g transform={`translate(${marginLeft}, ${marginTop})`}>
+        <!-- Clearing on plot-level leave (not per-cell) avoids a stale highlight
+             flickering at the sub-pixel seams between cells, whose dimensions are
+             fractional (plotWidth / xLabels.length). -->
+        <g
+          role="presentation"
+          transform={`translate(${marginLeft}, ${marginTop})`}
+          onpointerleave={handlePlotPointerLeave}
+        >
           <!-- X-axis labels (column headers) -->
           {#each xLabels as xLabel, index (xLabel)}
             <text
@@ -286,6 +302,8 @@
                 aria-hidden="true"
                 data-cinder-x={cell.xLabel}
                 data-cinder-y={cell.yLabel}
+                data-cinder-active={hoveredCellKey === cell.key ? '' : undefined}
+                onpointerenter={() => (hoveredCellKey = cell.key)}
               >
                 <title
                   >{cell.xLabel} × {cell.yLabel}: {cell.value !== null

package/src/components/matrix-chart/matrix-chart.types.ts

@@ -11,7 +11,7 @@ export type MatrixChartProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
   label: string;
   /** Optional description rendered below the label. */
   description?: string;
-  /** Rows of data. Each row must contain xField, yField, and valueField. */
+  /** Rows of data. Each row must include the keys named by the `xField`, `yField`, and `valueField` props. */
   data: MatrixChartDatum[];
   /** Key on each datum used for the x-axis (columns). */
   xField: string;
@@ -40,17 +40,30 @@ export type MatrixChartProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
 };
 
 export type MatrixChartSchemaProps = {
+  /** Accessible label for the chart. Required for screen readers. */
   label: string;
+  /** Optional description rendered below the label. */
   description?: string;
+  /** Rows of data. Each row must include the keys named by the `xField`, `yField`, and `valueField` props. */
   data: Record<string, string | number | null>[];
+  /** Key on each datum used for the x-axis (columns). */
   xField: string;
+  /** Key on each datum used for the y-axis (rows). */
   yField: string;
+  /** Key on each datum used for the numeric cell value. */
   valueField: string;
+  /** Color interpolation scale. Default `sequential`. */
   colorScale?: MatrixColorScale;
+  /** Show cell value labels. Default `true`. */
   showCellLabels?: boolean;
+  /** Pixel height of the chart viewport. Default `280`. */
   height?: number;
+  /** Whether the chart is in a loading state. Default `false`. */
   loading?: boolean;
+  /** Custom data table caption; falls back to `label`. */
   dataTableCaption?: string;
+  /** Controls data table visibility. Default `screen-reader-only`. */
   dataTableVisibility?: ChartDataTableVisibility;
+  /** Custom class applied to the root element. */
   class?: string;
 };

package/src/components/media-controls/README.md

@@ -26,20 +26,20 @@ Accessible playback controls for play, pause, and replay actions with optional p
 
 <!-- generated:props:start -->
 
-| Prop            | Type                        | Required | Default     | Description                                                                                                                |
-| --------------- | --------------------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`         | `string`                    | no       | —           | Additional class names merged with `.cinder-media-controls`.                                                               |
-| `disabled`      | `boolean`                   | no       | `false`     | Disable all controls.                                                                                                      |
-| `layout`        | `"compact"` \| `"expanded"` | no       | `"compact"` | Layout mode.                                                                                                               |
-| `loading`       | `boolean`                   | no       | `false`     | Show loading state while media is buffering.                                                                               |
-| `playing`       | `boolean`                   | no       | `false`     | Whether playback is active.                                                                                                |
-| `progress`      | `number`                    | no       | —           | Progress value between 0 and 1. Omit to hide the progress bar.                                                             |
-| `progressLabel` | `string`                    | no       | —           | Accessible label for the progress bar.                                                                                     |
-| `replay`        | `boolean`                   | no       | `false`     | Show a replay action when the track has ended.                                                                             |
-| `unavailable`   | `boolean`                   | no       | `false`     | Controls are unavailable.                                                                                                  |
-| `onPause`       | `(opaque)`                  | no       | —           | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onPlay`        | `(opaque)`                  | no       | —           | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onReplay`      | `(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-media-controls`.                                                           |
+| `disabled`      | `boolean`                   | no       | `false`     | Disable all controls.                                                                                                  |
+| `layout`        | `"compact"` \| `"expanded"` | no       | `"compact"` | Layout mode.                                                                                                           |
+| `loading`       | `boolean`                   | no       | `false`     | Show loading state while media is buffering.                                                                           |
+| `playing`       | `boolean`                   | no       | `false`     | Whether playback is active.                                                                                            |
+| `progress`      | `number`                    | no       | —           | Progress value between 0 and 1. Omit to hide the progress bar.                                                         |
+| `progressLabel` | `string`                    | no       | —           | Accessible label for the progress bar.                                                                                 |
+| `replay`        | `boolean`                   | no       | `false`     | Show a replay action when the track has ended.                                                                         |
+| `unavailable`   | `boolean`                   | no       | `false`     | Controls are unavailable.                                                                                              |
+| `onPause`       | `(opaque)`                  | no       | —           | Called when the pause action is triggered. Not expressible in JSON Schema; see the component types for the signature.  |
+| `onPlay`        | `(opaque)`                  | no       | —           | Called when the play action is triggered. Not expressible in JSON Schema; see the component types for the signature.   |
+| `onReplay`      | `(opaque)`                  | no       | —           | Called when the replay action is triggered. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

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

@@ -26,13 +26,13 @@ Command menubar for application chrome such as File, Edit, and View menus.
 
 <!-- generated:props:start -->
 
-| Prop         | Type       | Required | Default | Description                                                                                             |
-| ------------ | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- |
-| `class`      | `string`   | no       | —       |                                                                                                         |
-| `id`         | `string`   | no       | —       |                                                                                                         |
-| `label`      | `string`   | no       | —       |                                                                                                         |
-| `labelledBy` | `string`   | no       | —       |                                                                                                         |
-| `menus`      | `(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                                                                                                          |
+| ------------ | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
+| `class`      | `string`   | no       | —       | Additional class names merged with the component's root class.                                                       |
+| `id`         | `string`   | no       | —       | HTML id applied to the menubar root element. Auto-generated when omitted.                                            |
+| `label`      | `string`   | no       | —       | Accessible label for the menubar, applied as aria-label. Ignored when labelledBy is set. Default `Application menu`. |
+| `labelledBy` | `string`   | no       | —       | ID of an existing element whose text labels the menubar, applied as aria-labelledby. Takes precedence over label.    |
+| `menus`      | `(opaque)` | yes      | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.              |
 
 <!-- generated:props:end -->
 

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

@@ -281,6 +281,15 @@
       return;
     }
 
+    // Only consume Escape when a menu or submenu is actually open. On a closed
+    // menubar item, swallowing Escape (preventDefault + a no-op closeAll) would
+    // block an enclosing overlay or page-level Escape handler from ever running.
+    if (event.key === 'Escape' && (openMenuIndex !== null || openSubmenuKey !== null)) {
+      event.preventDefault();
+      closeAll();
+      return;
+    }
+
     if (event.key === 'ArrowUp') {
       event.preventDefault();
       openMenu(index, 'last');

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

@@ -61,9 +61,13 @@ export type MenuBarProps = Omit<HTMLAttributes<HTMLDivElement>, OwnedMenuBarRoot
 };
 
 export interface MenuBarSchemaProps {
+  /** HTML id applied to the menubar root element. Auto-generated when omitted. */
   id?: string;
   menus: readonly MenuBarMenu[];
+  /** Accessible label for the menubar, applied as aria-label. Ignored when labelledBy is set. Default `Application menu`. */
   label?: string;
+  /** ID of an existing element whose text labels the menubar, applied as aria-labelledby. Takes precedence over label. */
   labelledBy?: string;
+  /** Additional class names merged with the component's root class. */
   class?: string;
 }

package/src/components/message/README.md

@@ -16,14 +16,14 @@ Chat-style bubble that renders a role label, optional timestamp, and arbitrary b
 
 <!-- generated:props:start -->
 
-| Prop        | Type                                    | Required | Default | Description                                                                                                                |
-| ----------- | --------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`     | `string`                                | no       | —       | Additional class names merged with `.cinder-message`.                                                                      |
-| `datetime`  | `string`                                | no       | —       | The machine-readable date/time value placed on the `<time datetime>` attribute.                                            |
-| `name`      | `string`                                | no       | —       | Optional speaker name override (defaults derived from role).                                                               |
-| `role`      | `"user"` \| `"assistant"` \| `"system"` | yes      | —       | Role of the speaker — drives visual treatment.                                                                             |
-| `timestamp` | `string`                                | no       | —       | Human-readable display text rendered inside the `<time>` element. Falls back to `datetime` when omitted.                   |
-| `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-message`.                                                    |
+| `datetime`  | `string`                                | no       | —       | The machine-readable date/time value placed on the `<time datetime>` attribute.                          |
+| `name`      | `string`                                | no       | —       | Optional speaker name override (defaults derived from role).                                             |
+| `role`      | `"user"` \| `"assistant"` \| `"system"` | yes      | —       | Role of the speaker — drives visual treatment.                                                           |
+| `timestamp` | `string`                                | no       | —       | Human-readable display text rendered inside the `<time>` element. Falls back to `datetime` when omitted. |
+| `children`  | `(opaque)`                              | yes      | —       | Message body content. Not expressible in JSON Schema; see the component types for the signature.         |
 
 <!-- generated:props:end -->
 

package/src/components/modal/README.md

@@ -2,13 +2,13 @@
 
 Generic modal shell for rich content, forms, and structured workflows. Use the more specialised components when the content fits their narrower contract.
 
-## When to use
+## Choosing this component
 
 - Presenting rich or structured content (forms, multi-step wizards, detail views) inside a blocking overlay.
 - Collecting structured input — especially when multiple fields or widgets are involved.
 - Displaying content that requires user interaction before the page can continue, but where the interaction is more than a simple yes/no.
 
-## When not to use
+## Choosing something else
 
 - Two-action confirm/cancel prompts — use [`ConfirmDialog`](../confirm-dialog/README.md) instead. It handles autofocus on the cancel button, `aria-describedby`, and the destructive-variant button automatically.
 - Urgent blocking acknowledgements that must not be dismissed by Escape or backdrop click — use [`AlertDialog`](../alert-dialog/README.md) instead.
@@ -60,20 +60,20 @@ If the content fits the plain-text `description` constraint, prefer `AlertDialog
 
 <!-- generated:props:start -->
 
-| Prop                     | Type                          | Required | Default | Description                                                                                                                |
-| ------------------------ | ----------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`                  | `string`                      | no       | —       |                                                                                                                            |
-| `describedById`          | `string`                      | no       | —       | When set, applied as aria-describedby on the underlying <dialog>. Pass a short, plain description ID only.                 |
-| `dismissOnBackdropClick` | `boolean`                     | no       | —       |                                                                                                                            |
-| `dismissOnEscape`        | `boolean`                     | no       | —       |                                                                                                                            |
-| `open`                   | `boolean`                     | yes      | —       |                                                                                                                            |
-| `role`                   | `"dialog"` \| `"alertdialog"` | no       | —       |                                                                                                                            |
-| `showCloseButton`        | `boolean`                     | no       | —       |                                                                                                                            |
-| `title`                  | `string`                      | yes      | —       |                                                                                                                            |
-| `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. |
-| `ondismiss`              | `(opaque)`                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `triggerRef`             | `(opaque)`                    | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop                     | Type                          | Required | Default | Description                                                                                                                                                                                                                                                                                                         |
+| ------------------------ | ----------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`                  | `string`                      | no       | —       | Additional class names merged with the component's root class.                                                                                                                                                                                                                                                      |
+| `describedById`          | `string`                      | no       | —       | When set, applied as aria-describedby on the underlying <dialog>. Pass a short, plain description ID only.                                                                                                                                                                                                          |
+| `dismissOnBackdropClick` | `boolean`                     | no       | —       | When true, clicking the backdrop outside the modal panel dismisses it. Default `true`.                                                                                                                                                                                                                              |
+| `dismissOnEscape`        | `boolean`                     | no       | —       | When true, pressing Escape dismisses the modal. Default `true`.                                                                                                                                                                                                                                                     |
+| `open`                   | `boolean`                     | yes      | —       | Controls whether the modal is open; bindable for controlled usage.                                                                                                                                                                                                                                                  |
+| `role`                   | `"dialog"` \| `"alertdialog"` | no       | —       | ARIA role applied to the underlying dialog element. Default `dialog`.                                                                                                                                                                                                                                               |
+| `showCloseButton`        | `boolean`                     | no       | —       | When true, renders the close button in the upper corner of the modal panel. Default `true`.                                                                                                                                                                                                                         |
+| `title`                  | `string`                      | yes      | —       | Text rendered as the modal's visible heading and used as its accessible label.                                                                                                                                                                                                                                      |
+| `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.                                                                                                                                                                                          |
+| `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.                                                                                                                                                                                          |
+| `ondismiss`              | `(opaque)`                    | no       | —       | Fired on user-initiated dismissal. Includes: Escape key (native dialog 'cancel' event), backdrop click, and the close-X button. EXCLUDES: parent-driven open = false. Callbacks are not awaited and thrown callbacks do not block close. Not expressible in JSON Schema; see the component types for the signature. |
+| `triggerRef`             | `(opaque)`                    | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                             |
 
 <!-- generated:props:end -->
 

package/src/components/modal/modal.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic modal",
       "description": "A modal used as a generic content shell — in this case an invite form with structured fields.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { Input } from '@lostgradient/cinder/input';\n  import { Modal } from '@lostgradient/cinder/modal';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let email = $state('');\n  let name = $state('');\n\n  function handleSend() {\n    open = false;\n  }\n</script>\n\n<Button\n  label=\"Invite teammate\"\n  onclick={(event) => {\n    triggerRef = event.currentTarget;\n    open = true;\n  }}\n/>\n\n<Modal bind:open title=\"Invite teammate\" {triggerRef}>\n  <div style=\"display: grid; gap: 1rem;\">\n    <Input id=\"invite-name\" label=\"Full name\" placeholder=\"Alex Kim\" bind:value={name} autofocus />\n    <Input\n      id=\"invite-email\"\n      label=\"Email address\"\n      type=\"email\"\n      placeholder=\"alex@example.com\"\n      bind:value={email}\n    />\n  </div>\n\n  {#snippet footer()}\n    <div style=\"display: flex; gap: 0.5rem; justify-content: flex-end;\">\n      <Button variant=\"secondary\" label=\"Cancel\" onclick={() => (open = false)} />\n      <Button variant=\"primary\" label=\"Send invite\" onclick={handleSend} />\n    </div>\n  {/snippet}\n</Modal>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { Input } from '@lostgradient/cinder/input';\n  import { Modal } from '@lostgradient/cinder/modal';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let email = $state('');\n  let name = $state('');\n\n  function handleSend() {\n    open = false;\n  }\n</script>\n\n<Button\n  label=\"Invite teammate\"\n  onclick={(event) => {\n    triggerRef = event.currentTarget;\n    open = true;\n  }}\n/>\n\n<Modal bind:open title=\"Invite teammate\" {triggerRef}>\n  <div style=\"display: grid; gap: 1rem;\">\n    <Input id=\"name\" label=\"Full name\" placeholder=\"Alex Kim\" bind:value={name} autofocus />\n    <Input\n      id=\"email\"\n      label=\"Email address\"\n      type=\"email\"\n      placeholder=\"alex@example.com\"\n      bind:value={email}\n    />\n  </div>\n\n  {#snippet footer()}\n    <div style=\"display: flex; gap: 0.5rem; justify-content: flex-end;\">\n      <Button variant=\"secondary\" label=\"Cancel\" onclick={() => (open = false)} />\n      <Button variant=\"primary\" label=\"Send invite\" onclick={handleSend} />\n    </div>\n  {/snippet}\n</Modal>\n"
     },
     {
       "id": "overflowing",

package/src/components/modal/modal.svelte

@@ -25,6 +25,7 @@
   import { overflowFade } from '../../utilities/attachments.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { restoreFocusTo } from '../../utilities/focus.ts';
+  import { createFocusTrap } from '../focus-trap/index.ts';
 
   const titleId = $props.id();
 
@@ -202,7 +203,24 @@
     oncancel={handleNativeCancel}
   >
     {#if open}
-      <div class="cinder-modal__panel">
+      <!--
+        The native <dialog> opened with showModal() already traps focus in
+        supporting browsers. The shared focus-trap is a defence-in-depth fallback
+        that keeps Tab / Shift+Tab cycling inside the panel; it carefully filters
+        hidden/inert/disabled/`tabindex="-1"` elements. Modal owns its own initial
+        focus (the body container, below) and focus restoration (returnFocus), so
+        the trap runs with `manageInitialFocus: false` and `restoreFocus: false` —
+        without the former the trap would yank focus off the body onto the close
+        button on the next microtask.
+      -->
+      <div
+        class="cinder-modal__panel"
+        {@attach createFocusTrap({
+          active: () => open,
+          restoreFocus: false,
+          manageInitialFocus: false,
+        })}
+      >
         <div class="cinder-modal__header">
           <h2 id={titleId} class="cinder-modal__title">{title}</h2>
         </div>

package/src/components/modal/modal.types.ts

@@ -1,11 +1,17 @@
 import type { Snippet } from 'svelte';
 
 type ModalSharedProps = {
+  /** Controls whether the modal is open; bindable for controlled usage. */
   open: boolean;
+  /** Text rendered as the modal's visible heading and used as its accessible label. */
   title: string;
+  /** When true, clicking the backdrop outside the modal panel dismisses it. Default `true`. */
   dismissOnBackdropClick?: boolean;
+  /** When true, pressing Escape dismisses the modal. Default `true`. */
   dismissOnEscape?: boolean;
+  /** When true, renders the close button in the upper corner of the modal panel. Default `true`. */
   showCloseButton?: boolean;
+  /** Additional class names merged with the component's root class. */
   class?: string;
   children: Snippet;
   footer?: Snippet;
@@ -19,12 +25,14 @@ type ModalSharedProps = {
 };
 
 type DialogModalProps = ModalSharedProps & {
+  /** ARIA role applied to the underlying dialog element. Default `dialog`. */
   role?: 'dialog';
   /** When set, applied as aria-describedby on the underlying <dialog>. Pass a short, plain description ID only. */
   describedById?: string;
 };
 
 type AlertDialogModalProps = ModalSharedProps & {
+  /** ARIA role applied to the underlying dialog element. Use `alertdialog` for urgent prompts that cannot be dismissed without an explicit action. */
   role: 'alertdialog';
   /** Required for alertdialog so assistive technology receives the urgent condition and required action. */
   describedById: string;

package/src/components/navigation-bar/README.md

@@ -1,30 +1,60 @@
 # NavigationBar
 
-Top-level horizontal navigation bar for primary site or app destinations.
+Top-level navigation bar for primary site or app destinations. Use
+`placement="top"` for header navigation and `placement="bottom"` for a mobile
+tab-bar composition.
 
 ## Usage
 
 ```svelte
 <script lang="ts">
-  import NavigationBar from '@lostgradient/cinder/navigation-bar';
+  import { NavigationBar } from '@lostgradient/cinder/navigation-bar';
+  import { NavigationItem } from '@lostgradient/cinder/navigation-item';
 </script>
 
-<NavigationBar />
+<NavigationBar>
+  {#snippet items({ variant })}
+    <NavigationItem {variant} href="/home" active>Home</NavigationItem>
+    <NavigationItem {variant} href="/settings">Settings</NavigationItem>
+  {/snippet}
+</NavigationBar>
+```
+
+Bottom placement keeps the same link semantics and leaves viewport pinning to
+the app shell:
+
+```svelte
+<div style="position: sticky; bottom: 0;">
+  <NavigationBar placement="bottom" showLabels="active">
+    {#snippet items({ variant })}
+      <NavigationItem {variant} href="/home" active>
+        <span aria-hidden="true">⌂</span>
+        <span data-cinder-navigation-label>Home</span>
+      </NavigationItem>
+      <NavigationItem {variant} href="/settings">
+        <span aria-hidden="true">⚙</span>
+        <span data-cinder-navigation-label>Settings</span>
+      </NavigationItem>
+    {/snippet}
+  </NavigationBar>
+</div>
 ```
 
 ## Props
 
 <!-- generated:props:start -->
 
-| Prop             | Type       | Required | Default | Description                                                                                                                |
-| ---------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`          | `string`   | no       | —       | Custom class merged onto the root `<nav>` element.                                                                         |
-| `mobileMenuOpen` | `boolean`  | no       | —       | Two-way bindable open state of the mobile menu.                                                                            |
-| `navAriaLabel`   | `string`   | no       | —       | Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'.               |
-| `actions`        | `(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       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `items`          | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `menuToggle`     | `(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       | —          | Custom class merged onto the root `<nav>` element.                                                                                                                                                                                                                                                  |
+| `mobileMenuOpen` | `boolean`                             | no       | —          | Two-way bindable open state of the mobile menu.                                                                                                                                                                                                                                                     |
+| `navAriaLabel`   | `string`                              | no       | —          | Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'.                                                                                                                                                                                        |
+| `placement`      | `"top"` \| `"bottom"`                 | no       | `"top"`    | Visual placement mode. `bottom` renders a mobile tab-bar composition, but still does not fix or stick itself to the viewport.                                                                                                                                                                       |
+| `showLabels`     | `"always"` \| `"active"` \| `"never"` | no       | `"always"` | Label visibility for mobile bottom-tab compositions. Hidden labels remain in the accessibility tree when wrapped in `[data-cinder-navigation-label]`.                                                                                                                                               |
+| `actions`        | `(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       | —          | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                          |
+| `items`          | `(opaque)`                            | yes      | —          | Receives a context object with the current variant. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                      |
+| `menuToggle`     | `(opaque)`                            | no       | —          | Snippet receiving toggle button attributes. Consumer renders the actual <button> and should mark decorative glyphs or icons inside it as aria-hidden so the button name comes from text or aria-label, not the ornament. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/navigation-bar/index.ts

@@ -4,6 +4,8 @@ import NavigationBar from './navigation-bar.svelte';
 export default NavigationBar;
 export type {
   NavigationBarItemsContext,
+  NavigationBarLabelVisibility,
+  NavigationBarPlacement,
   NavigationBarProps,
   NavigationBarToggleAttributes,
   NavigationVariant,