@lostgradient/cinder 0.1.0 → 0.2.0

package/src/components/color-field/color-field.css

@@ -36,20 +36,17 @@
 
   .cinder-color-field__swatch[data-cinder-alpha]:not([data-cinder-empty]) {
     /* structural-pattern: transparency checkerboard so partially-transparent
-     * swatches stay visible — a fixed light/neutral grid signalling "see-through",
-     * not a themeable surface. Raw values declared once here with markers. */
-    --_cinder-color-field-checker-base: #fff; /* cinder-allow-raw-color: structural-pattern — checkerboard backing */
-    --_cinder-color-field-checker-tile: #ccc; /* cinder-allow-raw-color: structural-pattern — checkerboard tile */
-    background-color: var(--_cinder-color-field-checker-base);
+     * swatches stay visible while following the shared checker tokens. */
+    background-color: var(--cinder-color-checker-base);
     background-image:
       linear-gradient(
         var(--cinder-color-field-swatch, transparent),
         var(--cinder-color-field-swatch, transparent)
       ),
-      linear-gradient(45deg, var(--_cinder-color-field-checker-tile) 25%, transparent 25%),
-      linear-gradient(-45deg, var(--_cinder-color-field-checker-tile) 25%, transparent 25%),
-      linear-gradient(45deg, transparent 75%, var(--_cinder-color-field-checker-tile) 75%),
-      linear-gradient(-45deg, transparent 75%, var(--_cinder-color-field-checker-tile) 75%);
+      linear-gradient(45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--cinder-color-checker-tile) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--cinder-color-checker-tile) 75%);
     background-size:
       auto,
       6px 6px,

package/src/components/color-picker/color-picker.css

@@ -13,12 +13,21 @@
     width: 100%;
     max-width: 280px;
 
-    /* structural-pattern: the transparency checkerboard (shown behind alpha
-     * channels by the alpha slider and the preview chip) is a fixed light/neutral
-     * grid that signals "see-through", not a themeable surface. Declared once here
-     * and reused by both checkerboards below so the raw values have a single home. */
-    --_cinder-color-picker-checker-base: #fff; /* cinder-allow-raw-color: structural-pattern — checkerboard backing */
-    --_cinder-color-picker-checker-tile: #ccc; /* cinder-allow-raw-color: structural-pattern — checkerboard tile */
+    /* structural-pattern: the thumb sits over arbitrary picked colors, so the
+     * white ring and dark edge stay fixed; dark chrome gets one extra outer ring. */
+    --_cinder-color-picker-thumb-border: #fff; /* cinder-allow-raw-color: structural-pattern — thumb contrast ring over arbitrary picked color */
+    /* prettier-ignore */
+    --_cinder-color-picker-thumb-shadow-edge: rgba(0, 0, 0, 0.5); /* cinder-allow-raw-color: structural-pattern — thumb outline over arbitrary picked color */
+    --_cinder-color-picker-thumb-shadow-support-light: transparent;
+    /* prettier-ignore */
+    --_cinder-color-picker-thumb-shadow-support-dark: rgba(255, 255, 255, 0.65); /* cinder-allow-raw-color: structural-pattern — thumb outline over dark chrome */
+    --_cinder-color-picker-thumb-shadow-support: light-dark(
+      var(--_cinder-color-picker-thumb-shadow-support-light),
+      var(--_cinder-color-picker-thumb-shadow-support-dark)
+    );
+    --_cinder-color-picker-thumb-shadow:
+      0 0 0 1px var(--_cinder-color-picker-thumb-shadow-edge),
+      0 0 0 2px var(--_cinder-color-picker-thumb-shadow-support);
   }
 
   .cinder-color-picker[data-cinder-disabled] {
@@ -62,12 +71,11 @@
     width: 14px;
     height: 14px;
     /* structural-pattern: the draggable thumb sits over the user's chosen color,
-     * so its white ring + dark outline are fixed contrast devices (visible on any
-     * hue), not themeable chrome. */
-    border: 2px solid #fff; /* cinder-allow-raw-color: structural-pattern — thumb contrast ring over arbitrary picked color */
+     * so its white ring + contrast outline are hue-agnostic devices. */
+    border: 2px solid var(--_cinder-color-picker-thumb-border);
     border-radius: 50%;
     transform: translate(-50%, -50%);
-    box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.5); /* cinder-allow-raw-color: structural-pattern — thumb dark outline for contrast on light hues */
+    box-shadow: var(--_cinder-color-picker-thumb-shadow);
     pointer-events: none;
   }
 
@@ -92,13 +100,13 @@
   }
 
   .cinder-color-picker__alpha {
-    background-color: var(--_cinder-color-picker-checker-base);
+    background-color: var(--cinder-color-checker-base);
     background-image:
       linear-gradient(to right, transparent, var(--cinder-color-picker-base, currentColor)),
-      linear-gradient(45deg, var(--_cinder-color-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(-45deg, var(--_cinder-color-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(45deg, transparent 75%, var(--_cinder-color-picker-checker-tile) 75%),
-      linear-gradient(-45deg, transparent 75%, var(--_cinder-color-picker-checker-tile) 75%);
+      linear-gradient(45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--cinder-color-checker-tile) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--cinder-color-checker-tile) 75%);
     background-size:
       auto,
       8px 8px,
@@ -126,13 +134,12 @@
     width: 14px;
     height: 14px;
     /* structural-pattern: slider thumb sits over the hue rail / alpha
-     * checkerboard, so its white ring + dark outline are fixed contrast devices,
-     * not themeable chrome (same rationale as the gradient handle). */
-    border: 2px solid #fff; /* cinder-allow-raw-color: structural-pattern — slider thumb contrast ring */
+     * checkerboard, so its ring + outline follow the gradient handle. */
+    border: 2px solid var(--_cinder-color-picker-thumb-border);
     border-radius: 50%;
     background: transparent;
     transform: translate(-50%, -50%);
-    box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.5); /* cinder-allow-raw-color: structural-pattern — slider thumb dark outline */
+    box-shadow: var(--_cinder-color-picker-thumb-shadow);
     pointer-events: none;
   }
 
@@ -154,16 +161,16 @@
   }
 
   .cinder-color-picker__preview[data-cinder-alpha] {
-    background-color: var(--_cinder-color-picker-checker-base);
+    background-color: var(--cinder-color-checker-base);
     background-image:
       linear-gradient(
         var(--cinder-color-picker-preview, transparent),
         var(--cinder-color-picker-preview, transparent)
       ),
-      linear-gradient(45deg, var(--_cinder-color-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(-45deg, var(--_cinder-color-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(45deg, transparent 75%, var(--_cinder-color-picker-checker-tile) 75%),
-      linear-gradient(-45deg, transparent 75%, var(--_cinder-color-picker-checker-tile) 75%);
+      linear-gradient(45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--cinder-color-checker-tile) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--cinder-color-checker-tile) 75%);
     background-size:
       auto,
       8px 8px,

package/src/components/color-swatch-picker/color-swatch-picker.css

@@ -71,17 +71,14 @@
 
   .cinder-color-swatch-picker__swatch[data-cinder-alpha] {
     /* structural-pattern: transparency checkerboard beneath the color layer — a
-     * fixed light/neutral grid signalling "see-through", not a themeable surface.
-     * Raw values declared once here with markers. */
-    --_cinder-color-swatch-picker-checker-base: #fff; /* cinder-allow-raw-color: structural-pattern — checkerboard backing */
-    --_cinder-color-swatch-picker-checker-tile: #ccc; /* cinder-allow-raw-color: structural-pattern — checkerboard tile */
-    background-color: var(--_cinder-color-swatch-picker-checker-base);
+     * shared grid signalling "see-through" in both light and dark chrome. */
+    background-color: var(--cinder-color-checker-base);
     background-image:
       linear-gradient(var(--swatch-color), var(--swatch-color)),
-      linear-gradient(45deg, var(--_cinder-color-swatch-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(-45deg, var(--_cinder-color-swatch-picker-checker-tile) 25%, transparent 25%),
-      linear-gradient(45deg, transparent 75%, var(--_cinder-color-swatch-picker-checker-tile) 75%),
-      linear-gradient(-45deg, transparent 75%, var(--_cinder-color-swatch-picker-checker-tile) 75%);
+      linear-gradient(45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--cinder-color-checker-tile) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--cinder-color-checker-tile) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--cinder-color-checker-tile) 75%);
     background-size:
       auto,
       8px 8px,

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

@@ -0,0 +1,61 @@
+# CommandMenu
+
+Inline caret-anchored slash-command list for textareas and single-line text inputs.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { CommandMenu } from '@lostgradient/cinder/command-menu';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Showing a contextual command list at the caret while a user types in a textarea or input.
+- Building slash-command insertion flows where the host owns text replacement.
+
+### Avoid When
+
+- Exposing a global app launcher — use command-palette instead.
+- Selecting from a static form option list — use combobox instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop            | Type                                                                                                                 | Required | Default | Description                                                                                                                |
+| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `caretIndex`    | `number`                                                                                                             | yes      | —       | Caret offset within the anchor value.                                                                                      |
+| `class`         | `string`                                                                                                             | no       | —       | Class merged with `.cinder-command-menu`.                                                                                  |
+| `label`         | `string`                                                                                                             | no       | —       | Accessible listbox label. Default `'Commands'`.                                                                            |
+| `offset`        | `number`                                                                                                             | no       | —       | Distance in px between the caret and menu. Default `6`.                                                                    |
+| `open`          | `boolean`                                                                                                            | no       | —       | Open state. Bindable. Default `false`.                                                                                     |
+| `placement`     | `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"top-start"` \| `"top-end"` \| `"bottom-start"` \| `"bottom-end"` | no       | —       | Caret-relative placement. Default `'bottom-start'`.                                                                        |
+| `query`         | `string`                                                                                                             | no       | —       | Query text after the trigger character. Bindable. Default `''`.                                                            |
+| `anchor`        | `(opaque)`                                                                                                           | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| `empty`         | `(opaque)`                                                                                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `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. |
+| `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. |
+| `onselect`      | `(opaque)`                                                                                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `onstatechange` | `(opaque)`                                                                                                           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/confirm-dialog/confirm-dialog.examples.json

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

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

@@ -0,0 +1,55 @@
+# ContextMenu
+
+Right-click and long-press menu positioned at the user's pointer while reusing dropdown menu parts.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ContextMenu } from '@lostgradient/cinder/context-menu';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Providing contextual actions for a canvas, list row, file, or selected item.
+- Opening a menu from a pointer location instead of a visible dropdown trigger.
+
+### Avoid When
+
+- The menu should open from a button — use dropdown.
+- Showing arbitrary rich content rather than menu actions — use popover.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop             | Type                         | Required | Default | Description                                                                                                                |
+| ---------------- | ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `anchorPoint`    | { x: `number`; y: `number` } | no       | —       |                                                                                                                            |
+| `class`          | `string`                     | no       | —       |                                                                                                                            |
+| `disabled`       | `boolean`                    | no       | —       |                                                                                                                            |
+| `longPressDelay` | `number`                     | no       | —       |                                                                                                                            |
+| `open`           | `boolean`                    | no       | —       |                                                                                                                            |
+| `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. |
+| `onopenchange`   | `(opaque)`                   | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

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

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

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

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

package/src/components/data-table/README.md

@@ -0,0 +1,67 @@
+# DataTable
+
+Data-driven accessible table that renders rows and columns into a real `<table>` with `<caption>`, scoped column and row headers, optional sortable columns, and a horizontal-scroll responsive container.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { DataTable } from '@lostgradient/cinder/data-table';
+
+  const columns = [
+    { key: 'name', label: 'Name', rowHeader: true },
+    { key: 'score', label: 'Score', sortable: true, align: 'end' },
+  ];
+  const rows = [
+    { name: 'Ada', score: 98 },
+    { name: 'Grace', score: 95 },
+  ];
+</script>
+
+<DataTable {columns} {rows} caption="Class roster" />
+```
+
+## Guidance
+
+### Use When
+
+- Rendering a roster, cohort, or assignment view from row/column data with real table semantics.
+- Needing sortable columns with screen-reader-announced sort state out of the box.
+
+### Avoid When
+
+- Composing a bespoke table layout with custom cell markup — use the compositional Table family directly.
+- Visualizing dense numeric magnitude across two dimensions — use matrix-chart instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop           | Type                                             | Required | Default | Description                                                                                                                                                                                                            |
+| -------------- | ------------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `caption`      | `string`                                         | no       | —       | Visual caption rendered as a `<caption>` element above the table.                                                                                                                                                      |
+| `class`        | `string`                                         | no       | —       | Additional class names merged onto DataTable's root wrapper element (the `<div class="cinder-data-table">` that contains the table). To style the `<table>` itself, target `.cinder-data-table table` from this class. |
+| `density`      | `"comfortable"` \| `"condensed"` \| `"spacious"` | no       | —       | Vertical padding density for header and body cells. Defaults to `'comfortable'`.                                                                                                                                       |
+| `scrollable`   | `boolean`                                        | no       | —       | When true, wraps the table in a `.cinder-table-scroll` container that enables horizontal overflow scrolling on small viewports.                                                                                        |
+| `stickyHeader` | `boolean`                                        | no       | —       | When true, the header sticks to the top of the scrolling container.                                                                                                                                                    |
+| `columns`      | `(opaque)`                                       | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                |
+| `rows`         | `(opaque)`                                       | no       | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                               |
+| `sort`         | `(opaque)`                                       | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/data-table/data-table.css

@@ -0,0 +1,30 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+/* Compound-family aggregation: DataTable renders the whole Table family, so
+ * `cinder/data-table/styles` must pull in the Table CSS (which itself imports
+ * table-body / table-cell / table-header / table-header-cell / table-row and
+ * defines `.cinder-table-scroll`). Without this, the data-table subpath ships
+ * an unstyled table and the scroll override below has no base behaviour to
+ * extend. Sibling-leaf paths resolve identically in `src/` and `dist/`. */
+@import '../table/table.css';
+
+@layer cinder.components {
+  /* ========================================
+ * DATA TABLE
+ * Thin wrapper div that scopes the data-driven DataTable component.
+ * Visual treatment for the table itself lives in table.css.
+ * ======================================== */
+
+  /* The non-scrollable wrapper is a pure structural pass-through: `display:
+   * contents` lets the inner <table> participate directly in the parent layout
+   * with no extra box. */
+  .cinder-data-table {
+    display: contents;
+  }
+
+  /* When scrollable, the wrapper MUST generate a box so its `overflow-x: auto`
+   * (from .cinder-table-scroll) has something to scroll — `display: contents`
+   * would erase the box and silently disable horizontal scrolling. */
+  .cinder-data-table.cinder-table-scroll {
+    display: block;
+  }
+}

package/src/components/data-table/data-table.examples.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "data-table",
+  "import": "@lostgradient/cinder/data-table",
+  "examples": [
+    {
+      "id": "roster",
+      "title": "Class roster",
+      "description": "A class roster with a sortable grade column. The Name column is the row header (scope=\"row\"). Bind sort state and reorder rows in a $derived expression.",
+      "code": "<script lang=\"ts\">\n  import { DataTable } from '@lostgradient/cinder/data-table';\n  import type { TableSort } from '@lostgradient/cinder/table';\n\n  type Student = {\n    name: string;\n    subject: string;\n    grade: number;\n  };\n\n  const students: Student[] = [\n    { name: 'Ada Lovelace', subject: 'Mathematics', grade: 98 },\n    { name: 'Grace Hopper', subject: 'Computer Science', grade: 92 },\n    { name: 'Alan Turing', subject: 'Cryptography', grade: 95 },\n    { name: 'Margaret Hamilton', subject: 'Software Engineering', grade: 89 },\n  ];\n\n  const columns = [\n    { key: 'name' as const, label: 'Name', rowHeader: true },\n    { key: 'subject' as const, label: 'Subject' },\n    { key: 'grade' as const, label: 'Grade', sortable: true, align: 'end' as const },\n  ];\n\n  let sort: TableSort | undefined = $state();\n\n  const sortedStudents = $derived.by(() => {\n    if (!sort) return students;\n    return [...students].sort((a, b) => {\n      const key = sort!.column as keyof Student;\n      const aValue = a[key];\n      const bValue = b[key];\n      const comparison =\n        typeof aValue === 'number' && typeof bValue === 'number'\n          ? aValue - bValue\n          : String(aValue).localeCompare(String(bValue));\n      return sort!.direction === 'ascending' ? comparison : -comparison;\n    });\n  });\n</script>\n\n<DataTable caption=\"Spring semester roster\" {columns} rows={sortedStudents} bind:sort />\n"
+    },
+    {
+      "id": "sortable",
+      "title": "Sortable data table",
+      "description": "Multiple sortable columns with a scrollable wrapper. Sort state is bound and rows are reordered via $derived.",
+      "code": "<script lang=\"ts\">\n  import { DataTable } from '@lostgradient/cinder/data-table';\n  import type { TableSort } from '@lostgradient/cinder/table';\n\n  type Contributor = {\n    name: string;\n    role: string;\n    commits: number;\n    reviews: number;\n  };\n\n  const contributors: Contributor[] = [\n    { name: 'Ada Lovelace', role: 'Mathematician', commits: 142, reviews: 34 },\n    { name: 'Grace Hopper', role: 'Computer Scientist', commits: 98, reviews: 41 },\n    { name: 'Alan Turing', role: 'Cryptanalyst', commits: 76, reviews: 28 },\n    { name: 'Margaret Hamilton', role: 'Software Engineer', commits: 304, reviews: 87 },\n    { name: 'Linus Torvalds', role: 'Systems Engineer', commits: 512, reviews: 19 },\n    { name: 'Dennis Ritchie', role: 'Language Designer', commits: 231, reviews: 55 },\n  ];\n\n  const columns = [\n    { key: 'name' as const, label: 'Name', sortable: true, rowHeader: true },\n    { key: 'role' as const, label: 'Role', sortable: true },\n    { key: 'commits' as const, label: 'Commits', sortable: true, align: 'end' as const },\n    { key: 'reviews' as const, label: 'Reviews', sortable: true, align: 'end' as const },\n  ];\n\n  let sort: TableSort | undefined = $state();\n\n  const sortedContributors = $derived.by(() => {\n    if (!sort) return contributors;\n    return [...contributors].sort((a, b) => {\n      const key = sort!.column as keyof Contributor;\n      const aValue = a[key];\n      const bValue = b[key];\n      const comparison =\n        typeof aValue === 'number' && typeof bValue === 'number'\n          ? aValue - bValue\n          : String(aValue).localeCompare(String(bValue));\n      return sort!.direction === 'ascending' ? comparison : -comparison;\n    });\n  });\n</script>\n\n<DataTable caption=\"Top contributors\" {columns} rows={sortedContributors} bind:sort scrollable />\n"
+    }
+  ]
+}

package/src/components/data-table/data-table.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "caption": {
+      "type": "string",
+      "description": "Visual caption rendered as a `<caption>` element above the table."
+    },
+    "stickyHeader": {
+      "type": "boolean",
+      "description": "When true, the header sticks to the top of the scrolling container."
+    },
+    "density": {
+      "enum": ["comfortable", "condensed", "spacious"],
+      "description": "Vertical padding density for header and body cells.\nDefaults to `'comfortable'`."
+    },
+    "scrollable": {
+      "type": "boolean",
+      "description": "When true, wraps the table in a `.cinder-table-scroll` container that\nenables horizontal overflow scrolling on small viewports."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional class names merged onto DataTable's root wrapper element (the\n`<div class=\"cinder-data-table\">` that contains the table). To style the\n`<table>` itself, target `.cinder-data-table table` from this class."
+    }
+  },
+  "additionalProperties": false,
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "columns",
+        "reason": "unknown-shape"
+      },
+      {
+        "name": "rows",
+        "reason": "generic-type-parameter"
+      },
+      {
+        "name": "sort",
+        "reason": "unknown-shape"
+      }
+    ]
+  }
+}

package/src/components/data-table/data-table.schema.ts

@@ -0,0 +1,50 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    caption: {
+      type: 'string',
+      description: 'Visual caption rendered as a `<caption>` element above the table.',
+    },
+    stickyHeader: {
+      type: 'boolean',
+      description: 'When true, the header sticks to the top of the scrolling container.',
+    },
+    density: {
+      enum: ['comfortable', 'condensed', 'spacious'],
+      description:
+        "Vertical padding density for header and body cells.\nDefaults to `'comfortable'`.",
+    },
+    scrollable: {
+      type: 'boolean',
+      description:
+        'When true, wraps the table in a `.cinder-table-scroll` container that\nenables horizontal overflow scrolling on small viewports.',
+    },
+    class: {
+      type: 'string',
+      description:
+        'Additional class names merged onto DataTable\'s root wrapper element (the\n`<div class="cinder-data-table">` that contains the table). To style the\n`<table>` itself, target `.cinder-data-table table` from this class.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'columns',
+        reason: 'unknown-shape',
+      },
+      {
+        name: 'rows',
+        reason: 'generic-type-parameter',
+      },
+      {
+        name: 'sort',
+        reason: 'unknown-shape',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;