@lostgradient/cinder 0.3.0 → 0.4.1

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

@@ -19,7 +19,9 @@
   import type { ContextMenuProps } from './context-menu.types.ts';
   import type { VirtualElement } from '@floating-ui/dom';
   import { createAnchoredOverlay } from '../../_internal/anchored-overlay.svelte.ts';
+  import { getLocaleContext } from '../../_internal/locale-context.ts';
   import { captureFocus } from '../../_internal/overlay.ts';
+  import { observeTextDirection, resolveTextDirection } from '../../_internal/text-direction.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { restoreFocusTo } from '../../utilities/focus.ts';
   import { createClickOutside } from '../../utilities/attachments.ts';
@@ -47,7 +49,9 @@
   let capturedFocus: HTMLElement | null = null;
   let requestedX = $state(0);
   let requestedY = $state(0);
+  let directionRevision = $state(0);
   let previouslyOpen = false;
+  const localeContext = getLocaleContext();
 
   function setOpen(nextOpen: boolean) {
     if (open === nextOpen) return;
@@ -103,12 +107,22 @@
   const virtualReference: VirtualElement | null = $derived(
     open ? makeVirtualReference(anchorPoint?.x ?? requestedX, anchorPoint?.y ?? requestedY) : null,
   );
+  const resolvedDirection = $derived.by(() => {
+    directionRevision;
+    return resolveTextDirection(triggerElement, localeContext?.direction);
+  });
+
+  $effect(() => {
+    return observeTextDirection(triggerElement, () => {
+      directionRevision += 1;
+    });
+  });
 
   const anchoredOverlay = createAnchoredOverlay({
     open: () => open,
     anchor: () => virtualReference,
     panel: () => menuElement,
-    placement: () => 'right-start',
+    placement: () => (resolvedDirection === 'rtl' ? 'left-start' : 'right-start'),
     offset: () => 0,
     widthMode: () => 'menu',
   });
@@ -133,6 +147,18 @@
     get supportsPopover() {
       return false;
     },
+    get anchorElement() {
+      return triggerElement;
+    },
+    get fallbackAnchorElement() {
+      return null;
+    },
+    get fallbackPositionStyle() {
+      return anchoredOverlay.positionStyle;
+    },
+    get fallbackPositionReady() {
+      return anchoredOverlay.positionReady;
+    },
     get initialFocus() {
       return 'first' as const;
     },
@@ -152,6 +178,9 @@
     get longPressDelay() {
       return longPressDelay;
     },
+    get direction() {
+      return resolvedDirection;
+    },
     openAt,
     close,
   });
@@ -161,17 +190,14 @@
     const x = anchorPoint?.x ?? requestedX;
     const y = anchorPoint?.y ?? requestedY;
     const menu = menuElement;
-    if (anchoredOverlay.positionStyle) {
-      menu.setAttribute('style', anchoredOverlay.positionStyle);
-    } else {
-      menu.removeAttribute('style');
-    }
-    menu.setAttribute('data-cinder-position-ready', String(anchoredOverlay.positionReady));
     menu.setAttribute('data-cinder-requested-x', String(x));
     menu.setAttribute('data-cinder-requested-y', String(y));
+    const ownsDirection = menu.dataset['cinderExplicitDirection'] !== 'true';
+    if (ownsDirection && resolvedDirection) {
+      menu.setAttribute('dir', resolvedDirection);
+    }
     return () => {
-      menu.removeAttribute('style');
-      menu.removeAttribute('data-cinder-position-ready');
+      if (ownsDirection) menu.removeAttribute('dir');
       menu.removeAttribute('data-cinder-requested-x');
       menu.removeAttribute('data-cinder-requested-y');
     };

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

@@ -17,7 +17,6 @@
 
 <script lang="ts">
   import type { ContextMenuTriggerProps } from './context-menu-trigger.types.ts';
-  import { onDestroy } from 'svelte';
   import { classNames } from '../../utilities/class-names.ts';
   import { getDropdownRegisterTrigger } from '../dropdown/dropdown.context.ts';
   import { getContextMenuContext } from '../context-menu/context-menu.context.ts';
@@ -51,12 +50,14 @@
     currentTarget: EventTarget & HTMLDivElement;
   };
 
-  $effect(() => {
-    registerTrigger(triggerElement);
+  function attachTrigger(node: HTMLDivElement) {
+    registerTrigger(node);
     return () => registerTrigger(null);
-  });
+  }
 
-  onDestroy(clearLongPress);
+  $effect(() => {
+    return () => clearLongPress();
+  });
 
   function clearLongPress() {
     clearTimeout(longPressTimer);
@@ -142,7 +143,8 @@
     event.preventDefault();
     const target = event.target instanceof HTMLElement ? event.target : triggerElement;
     const rect = target?.getBoundingClientRect() ?? triggerElement?.getBoundingClientRect();
-    context.openAt(rect?.left ?? 0, rect?.bottom ?? 0);
+    const x = context.direction === 'rtl' ? rect?.right : rect?.left;
+    context.openAt(x ?? 0, rect?.bottom ?? 0);
     callTriggerHandler(onkeydown, event);
   }
 
@@ -164,6 +166,7 @@
 
 <div
   bind:this={triggerElement}
+  {@attach attachTrigger}
   class={classNames('cinder-context-menu-trigger', className)}
   aria-haspopup="menu"
   oncontextmenu={handleContextmenu}

package/src/components/copy-button/copy-button.svelte

@@ -17,7 +17,6 @@
 
 <script lang="ts">
   import type { CopyButtonProps } from './copy-button.types.ts';
-  import { onDestroy } from 'svelte';
 
   import Check from 'lucide-svelte/icons/check';
   import Copy from 'lucide-svelte/icons/copy';
@@ -62,8 +61,10 @@
     }, confirmDuration);
   }
 
-  onDestroy(() => {
-    if (resetTimer) clearTimeout(resetTimer);
+  $effect(() => {
+    return () => {
+      if (resetTimer) clearTimeout(resetTimer);
+    };
   });
 </script>
 

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

@@ -33,7 +33,7 @@ ARIA data grid foundation for spreadsheet-like datasets with stable row identity
 ### Avoid When
 
 - You only need a semantic read-only table — use DataTable or the Table family instead.
-- You need sorting, virtualization, resize handles, drag-to-reorder controls, or editing today.
+- You need resize handles, drag-to-reorder controls, or editing today.
 
 ## Props
 
@@ -55,8 +55,8 @@ ARIA data grid foundation for spreadsheet-like datasets with stable row identity
 | `columns`                | `(opaque)`                                     | yes      | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                               |
 | `getRowAriaLabel`        | `(opaque)`                                     | no       | —       | Optional accessible row label for screen-reader row summaries. Not expressible in JSON Schema; see the component types for the signature.             |
 | `getRowId`               | `(opaque)`                                     | yes      | —       | Stable row identity used for ARIA ids and row-scoped state. Not expressible in JSON Schema; see the component types for the signature.                |
-| `onSelectionModelChange` | `(opaque)`                                     | no       | —       | Called when row selection changes through cell interaction. Not expressible in JSON Schema; see the component types for the signature.                |
-| `onSortModelChange`      | `(opaque)`                                     | no       | —       | Called after the user changes sort order and DataGrid updates `sortModel`. Not expressible in JSON Schema; see the component types for the signature. |
+| `onselectionmodelchange` | `(opaque)`                                     | no       | —       | Called when row selection changes through cell interaction. Not expressible in JSON Schema; see the component types for the signature.                |
+| `onsortmodelchange`      | `(opaque)`                                     | no       | —       | Called after the user changes sort order and DataGrid updates `sortModel`. Not expressible in JSON Schema; see the component types for the signature. |
 | `rowClass`               | `(opaque)`                                     | no       | —       | Additional class names for body rows. Not expressible in JSON Schema; see the component types for the signature.                                      |
 | `rows`                   | `(opaque)`                                     | yes      | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                              |
 | `sortModel`              | `(opaque)`                                     | no       | —       | Controls the row sort order used to render rows. Not expressible in JSON Schema; see the component types for the signature.                           |

package/src/components/data-grid/_internal/column-model.svelte.ts

@@ -13,6 +13,7 @@ export const DEFAULT_DATA_GRID_COLUMN_MIN_WIDTH = 60;
 
 export type DataGridValueColumn<TRow> = {
   key: string;
+  rowHeader?: boolean;
   sortable?: boolean;
   sortComparator?: DataGridSortComparator<TRow>;
   getValue?: (row: TRow) => unknown;
@@ -148,6 +149,7 @@ function resolveColumn<TRow>(
   };
   if (column.cell !== undefined) resolvedColumn.cell = column.cell;
   if (column.maxWidth !== undefined) resolvedColumn.maxWidth = column.maxWidth;
+  if (column.rowHeader !== undefined) resolvedColumn.rowHeader = column.rowHeader;
   if (column.sortable !== undefined) resolvedColumn.sortable = column.sortable;
   if (column.sortComparator !== undefined) resolvedColumn.sortComparator = column.sortComparator;
   if (column.getValue !== undefined) resolvedColumn.getValue = column.getValue;

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

@@ -9,6 +9,7 @@
     inline-size: 100%;
     max-inline-size: 100%;
     overflow: auto;
+    scrollbar-gutter: stable;
     border: 1px solid var(--cinder-border);
     border-radius: var(--cinder-radius-md);
     background: var(--cinder-surface);
@@ -18,11 +19,25 @@
     -webkit-overflow-scrolling: touch;
   }
 
+  .cinder-data-grid[data-cinder-virtualized-columns='true'] {
+    --_cinder-data-grid-overflow-shadow:
+      inset 1rem 0 1rem -1rem color-mix(in srgb, var(--cinder-text) 28%, transparent),
+      inset -1rem 0 1rem -1rem color-mix(in srgb, var(--cinder-text) 28%, transparent);
+  }
+
   .cinder-data-grid:focus-visible {
     outline: var(--cinder-ring-width) solid transparent;
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-data-grid:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(-1 * var(--cinder-ring-width));
+      box-shadow: none;
+    }
+  }
+
   .cinder-data-grid__header-row,
   .cinder-data-grid__row {
     display: grid;
@@ -33,6 +48,7 @@
 
   .cinder-data-grid__header-row {
     background: var(--cinder-surface-inset);
+    box-shadow: var(--_cinder-data-grid-overflow-shadow, none);
   }
 
   .cinder-data-grid[data-cinder-sticky-header] .cinder-data-grid__header-row {
@@ -43,6 +59,7 @@
 
   .cinder-data-grid__row {
     background: var(--cinder-surface);
+    box-shadow: var(--_cinder-data-grid-overflow-shadow, none);
     transition: background var(--cinder-duration-fast) var(--cinder-ease-standard);
   }
 
@@ -117,6 +134,14 @@
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-data-grid__sort-button:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 2px;
+      box-shadow: none;
+    }
+  }
+
   .cinder-data-grid__header-content {
     min-inline-size: 0;
     overflow: hidden;

package/src/components/data-grid/data-grid.svelte

@@ -84,9 +84,9 @@
     columnPinning,
     selectionMode = 'none',
     selectionModel = $bindable<DataGridSelectionModel | undefined>(undefined),
-    onSelectionModelChange,
+    onselectionmodelchange,
     sortModel = $bindable([]),
-    onSortModelChange,
+    onsortmodelchange,
     rowClass,
     getRowAriaLabel,
     class: className,
@@ -586,7 +586,7 @@
 
     const nextSortModel = getNextDataGridSortModel(activeSortModel, column.key, event.shiftKey);
     sortModel = nextSortModel;
-    onSortModelChange?.(nextSortModel);
+    onsortmodelchange?.(nextSortModel);
   }
 
   function getCellCoordinate(
@@ -644,7 +644,7 @@
 
   function setSelectionModel(nextSelectionModel: DataGridSelectionModel): void {
     selectionModel = nextSelectionModel;
-    onSelectionModelChange?.(nextSelectionModel);
+    onselectionmodelchange?.(nextSelectionModel);
   }
 
   function updateRowSelection(rowId: string, event: MouseEvent | KeyboardEvent): void {
@@ -981,7 +981,7 @@
         aria-rowindex={rowIndex + 2}
         aria-label={getResolvedRowAriaLabel(row, rowIndex)}
         aria-selected={selectedRowIds.has(rowId) ? 'true' : undefined}
-        data-cinder-selected={selectedRowIds.has(rowId) ? 'true' : undefined}
+        data-cinder-selected={selectedRowIds.has(rowId) ? '' : undefined}
         data-cinder-virtual-index={rowIndex}
         style={getRowStyle(renderedRow)}
       >
@@ -994,13 +994,13 @@
           <div
             id={cellId}
             class="cinder-data-grid__cell"
-            role="gridcell"
+            role={column.rowHeader ? 'rowheader' : 'gridcell'}
             aria-colindex={column.colIndex}
             aria-selected={isSelectedCell ? 'true' : undefined}
             tabindex="-1"
             data-cinder-pin={column.pin}
             data-cinder-active={activeCellId === cellId ? 'true' : undefined}
-            data-cinder-selected={isSelectedCell ? 'true' : undefined}
+            data-cinder-selected={isSelectedCell ? '' : undefined}
             data-cinder-anchor={isAnchorCell ? 'true' : undefined}
             data-cinder-row-id={rowId}
             data-cinder-row-dom-id={rowDomId}

package/src/components/data-grid/data-grid.types.ts

@@ -43,6 +43,12 @@ type DataGridBaseColumnDef<TRow> = {
   maxWidth?: number;
   /** Pin this column to the left or right edge of the horizontal scroller. */
   pin?: DataGridColumnPin;
+  /**
+   * Render body cells in this column as row headers (`role="rowheader"`).
+   * Use this for the column that uniquely identifies each row, such as the
+   * value returned by `getRowId`.
+   */
+  rowHeader?: boolean;
   /** Enables header-click sorting for this column. */
   sortable?: boolean;
 };
@@ -104,11 +110,11 @@ export type DataGridProps<TRow = Record<string, unknown>> = Omit<
   /** Controlled row-selection ids, keyed by `getRowId`. */
   selectionModel?: DataGridSelectionModel | undefined;
   /** Called when row selection changes through cell interaction. */
-  onSelectionModelChange?: (selectionModel: DataGridSelectionModel) => void;
+  onselectionmodelchange?: (selectionModel: DataGridSelectionModel) => void;
   /** Controls the row sort order used to render rows. */
   sortModel?: DataGridSortModel;
   /** Called after the user changes sort order and DataGrid updates `sortModel`. */
-  onSortModelChange?: (sortModel: DataGridSortModel) => void;
+  onsortmodelchange?: (sortModel: DataGridSortModel) => void;
   /** Additional class names merged onto the root grid. */
   class?: string;
   /** Additional class names for body rows. */

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

@@ -24,7 +24,7 @@ for tabular rows and columns use [`Table`](../table/README.md).
   ];
 </script>
 
-<DataList items={members} density="condensed">
+<DataList items={members} key={(member) => member.id} density="condensed">
   {#snippet children(member)}
     <StackedListItem>
       {#snippet title()}{member.name}{/snippet}
@@ -45,14 +45,14 @@ set its own `density` prop. The `empty` snippet renders inside a component-owned
 
 <!-- generated:props:start -->
 
-| Prop       | Type                             | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ---------- | -------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`                         | no       | —       | Additional class merged onto the `.cinder-data-list` root element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `density`  | `"comfortable"` \| `"condensed"` | no       | —       | List-level density inherited by StackedListItem rows that do not set their own `density` prop. Omit to let each row use its own default. A per-row `density` always overrides this list-level value. Note: when passing a variable that may be `undefined`, spread conditionally because `exactOptionalPropertyTypes` is enabled: `{...(density ? { density } : {})}`                                                                                                                                                                                                            |
-| `children` | `(opaque)`                       | yes      | —       | Row renderer. MUST render an `<li>` (the list root is a `<ul role="list">`). StackedListItem is the recommended row — it renders an `<li>` with leading/title/description/meta/trailing slots. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                        |
-| `empty`    | `(opaque)`                       | no       | —       | Rendered when `items` is empty. The component automatically wraps the snippet output in `<li class="cinder-data-list-empty">`. **Do NOT wrap in an `<li>` yourself** — the component provides the `<li>` wrapper automatically. Pass only inner content (e.g. a `<p>`, a `<div>`, or plain text). Contrast with `children`, which must render an `<li>`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                              |
-| `items`    | `(opaque)`                       | yes      | —       | The records to render. Each is passed to `children`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `key`      | `(opaque)`                       | no       | —       | Key extractor for efficient DOM updates. Svelte uses this to identify each row when the list is reordered, filtered, or updated — without it, rows are matched by index and the wrong row instances may receive updated props. Strongly recommended for any list that can change after initial render: `svelte <DataList {items} key={(m) => m.id}> ` Omit only for truly static, never-reordered lists (e.g. a fixed reference list). When omitted, Svelte falls back to index-based reconciliation. Not expressible in JSON Schema; see the component types for the signature. |
+| Prop       | Type                             | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------- | -------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`                         | no       | —       | Additional class merged onto the `.cinder-data-list` root element.                                                                                                                                                                                                                                                                                                                                                                  |
+| `density`  | `"comfortable"` \| `"condensed"` | no       | —       | List-level density inherited by StackedListItem rows that do not set their own `density` prop. Omit to let each row use its own default. A per-row `density` always overrides this list-level value. Note: when passing a variable that may be `undefined`, spread conditionally because `exactOptionalPropertyTypes` is enabled: `{...(density ? { density } : {})}`                                                               |
+| `children` | `(opaque)`                       | yes      | —       | Row renderer. MUST render an `<li>` (the list root is a `<ul role="list">`). StackedListItem is the recommended row — it renders an `<li>` with leading/title/description/meta/trailing slots. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                           |
+| `empty`    | `(opaque)`                       | no       | —       | Rendered when `items` is empty. The component automatically wraps the snippet output in `<li class="cinder-data-list-empty">`. **Do NOT wrap in an `<li>` yourself** — the component provides the `<li>` wrapper automatically. Pass only inner content (e.g. a `<p>`, a `<div>`, or plain text). Contrast with `children`, which must render an `<li>`. Not expressible in JSON Schema; see the component types for the signature. |
+| `items`    | `(opaque)`                       | yes      | —       | The records to render. Each is passed to `children`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                     |
+| `key`      | `(opaque)`                       | yes      | —       | Key extractor for stable DOM reconciliation. Svelte uses this to identify each row when the list is reordered, filtered, or updated. Without a key, rows are matched by index and the wrong row instances may receive updated props, causing O(n) churn and incorrect rendering. `svelte <DataList {items} key={(m) => m.id}> ` Not expressible in JSON Schema; see the component types for the signature.                          |
 
 <!-- generated:props:end -->
 

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

@@ -13,7 +13,7 @@
       "id": "empty",
       "title": "Empty state fallback",
       "description": "When items is empty, the empty snippet renders inside a component-owned `<li class=\"cinder-data-list-empty\">` — centered, muted padding, no inline styles required.",
-      "code": "<script lang=\"ts\">\n  import { DataList } from '@lostgradient/cinder/data-list';\n  import { StackedListItem } from '@lostgradient/cinder/stacked-list-item';\n\n  const members: { id: string; name: string }[] = [];\n</script>\n\n<DataList items={members}>\n  {#snippet children(member)}\n    <StackedListItem>\n      {#snippet title()}{member.name}{/snippet}\n    </StackedListItem>\n  {/snippet}\n  {#snippet empty()}\n    No team members yet.\n  {/snippet}\n</DataList>\n"
+      "code": "<script lang=\"ts\">\n  import { DataList } from '@lostgradient/cinder/data-list';\n  import { StackedListItem } from '@lostgradient/cinder/stacked-list-item';\n\n  const members: { id: string; name: string }[] = [];\n</script>\n\n<DataList items={members} key={(m) => m.id}>\n  {#snippet children(member)}\n    <StackedListItem>\n      {#snippet title()}{member.name}{/snippet}\n    </StackedListItem>\n  {/snippet}\n  {#snippet empty()}\n    No team members yet.\n  {/snippet}\n</DataList>\n"
     }
   ]
 }

package/src/components/data-list/data-list.svelte

@@ -49,15 +49,9 @@
 -->
 <ul {...rest} class={classNames('cinder-data-list', className)} role="list">
   {#if items.length > 0}
-    {#if key}
-      {#each items as entry (key(entry))}
-        {@render children(entry)}
-      {/each}
-    {:else}
-      {#each items as entry}
-        {@render children(entry)}
-      {/each}
-    {/if}
+    {#each items as entry (key(entry))}
+      {@render children(entry)}
+    {/each}
   {:else if empty}
     <li class="cinder-data-list-empty">
       {@render empty()}

package/src/components/data-list/data-list.types.ts

@@ -13,20 +13,16 @@ export type DataListProps<T> = Omit<
   /** The records to render. Each is passed to `children`. */
   items: T[];
   /**
-   * Key extractor for efficient DOM updates. Svelte uses this to identify each
-   * row when the list is reordered, filtered, or updated — without it, rows are
-   * matched by index and the wrong row instances may receive updated props.
-   *
-   * Strongly recommended for any list that can change after initial render:
+   * Key extractor for stable DOM reconciliation. Svelte uses this to identify
+   * each row when the list is reordered, filtered, or updated. Without a key,
+   * rows are matched by index and the wrong row instances may receive updated
+   * props, causing O(n) churn and incorrect rendering.
    *
    * ```svelte
    * <DataList {items} key={(m) => m.id}>
    * ```
-   *
-   * Omit only for truly static, never-reordered lists (e.g. a fixed reference
-   * list). When omitted, Svelte falls back to index-based reconciliation.
    */
-  key?: (item: T) => string | number;
+  key: (item: T) => string | number;
   /**
    * List-level density inherited by StackedListItem rows that do not set their
    * own `density` prop. Omit to let each row use its own default. A per-row

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

@@ -44,21 +44,27 @@ for this mode.
 
 <!-- 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'`.                                                                                                                                                                                                                                                                                                                                                                           |
-| `height`        | `string`                                         | no       | —       | CSS block-size for the virtualized native scroll container. Defaults to `"24rem"` when `virtualized` is true.                                                                                                                                                                                                                                                                                                                                              |
-| `overscan`      | `number`                                         | no       | —       | Extra body rows rendered before and after the visible virtualized window. Defaults to 5.                                                                                                                                                                                                                                                                                                                                                                   |
-| `rowHeight`     | `number`                                         | no       | —       | Fixed body row height in pixels for virtualized mode. This must match the actual rendered body row height, including density padding and any wrapping introduced by the table content. Defaults to 44.                                                                                                                                                                                                                                                     |
-| `scrollable`    | `boolean`                                        | no       | —       | When true, wraps the table in a `.cinder-table-scroll` container that enables horizontal overflow scrolling on small viewports.                                                                                                                                                                                                                                                                                                                            |
-| `stickToBottom` | `boolean`                                        | no       | —       | When true in virtualized mode, appending rows while scrolled to the bottom keeps the newest row pinned in view. Appending while scrolled up does not change the viewport.                                                                                                                                                                                                                                                                                  |
-| `stickyHeader`  | `boolean`                                        | no       | —       | When true, the header sticks to the top of the scrolling container.                                                                                                                                                                                                                                                                                                                                                                                        |
-| `virtualized`   | `boolean`                                        | no       | —       | When true, renders only the visible `<tbody>` row window plus spacer rows. Requires a fixed row height. This is intended for large, append-only tables such as live logs or event streams.                                                                                                                                                                                                                                                                 |
-| `columns`       | `(opaque)`                                       | yes      | —       | Column descriptors defining the headers and cell rendering for each column. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                     |
-| `rows`          | `(opaque)`                                       | yes      | —       | Row data. Each entry is read via `column.key` for each column. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                  |
-| `sort`          | `(opaque)`                                       | no       | —       | Bound sort state. When the user activates a sortable header cell, this prop is updated with the new `{ column, direction }`. The consumer is responsible for reordering `rows` in response — DataTable does not sort internally. Pass `undefined` initially when no column is sorted; the component will never write back `undefined` itself (sort always toggles to a column). Not expressible in JSON Schema; see the component types for the signature. |
+| 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'`.                                                                                                                                                                                                                                                                                                                                                                           |
+| `height`                 | `string`                                         | no       | —       | CSS block-size for the virtualized native scroll container. Defaults to `"24rem"` when `virtualized` is true.                                                                                                                                                                                                                                                                                                                                              |
+| `overscan`               | `number`                                         | no       | —       | Extra body rows rendered before and after the visible virtualized window. Defaults to 5.                                                                                                                                                                                                                                                                                                                                                                   |
+| `rowHeight`              | `number`                                         | no       | —       | Fixed body row height in pixels for virtualized mode. This must match the actual rendered body row height, including density padding and any wrapping introduced by the table content. Defaults to 44.                                                                                                                                                                                                                                                     |
+| `scrollable`             | `boolean`                                        | no       | —       | When true, wraps the table in a `.cinder-table-scroll` container that enables horizontal overflow scrolling on small viewports.                                                                                                                                                                                                                                                                                                                            |
+| `selectable`             | `"none"` \| `"single"` \| `"multiple"`           | no       | —       | Enables checkbox-based row selection. `"none"` renders no selection controls, `"single"` allows one selected row id, and `"multiple"` allows any number. Selection state is exposed through row checkbox controls; native table rows do not emit `aria-selected`. Defaults to `"none"`.                                                                                                                                                                    |
+| `selectAllLabel`         | `string`                                         | no       | —       | Accessible label for the multiple-selection header checkbox.                                                                                                                                                                                                                                                                                                                                                                                               |
+| `stickToBottom`          | `boolean`                                        | no       | —       | When true in virtualized mode, appending rows while scrolled to the bottom keeps the newest row pinned in view. Appending while scrolled up does not change the viewport.                                                                                                                                                                                                                                                                                  |
+| `stickyHeader`           | `boolean`                                        | no       | —       | When true, the header sticks to the top of the scrolling container.                                                                                                                                                                                                                                                                                                                                                                                        |
+| `virtualized`            | `boolean`                                        | no       | —       | When true, renders only the visible `<tbody>` row window plus spacer rows. Requires a fixed row height. This is intended for large, append-only tables such as live logs or event streams.                                                                                                                                                                                                                                                                 |
+| `columns`                | `(opaque)`                                       | yes      | —       | Column descriptors defining the headers and cell rendering for each column. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                     |
+| `getRowId`               | `(opaque)`                                       | no       | —       | Resolves the stable row id used for selection. Defaults to `row.id` when it is a string or number, otherwise the row's current positional index. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                |
+| `isRowSelectionDisabled` | `(opaque)`                                       | no       | —       | Returns true when a row should render a disabled selection checkbox. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                            |
+| `rows`                   | `(opaque)`                                       | yes      | —       | Row data. Each entry is read via `column.key` for each column. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                  |
+| `rowSelectionLabel`      | `(opaque)`                                       | no       | —       | Accessible label for an individual row selection checkbox. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                      |
+| `selectedRowIds`         | `(opaque)`                                       | no       | —       | Bound selected row ids. Arrays stay arrays on update; Sets stay Sets. When omitted, DataTable starts with an empty array. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                       |
+| `sort`                   | `(opaque)`                                       | no       | —       | Bound sort state. When the user activates a sortable header cell, this prop is updated with the new `{ column, direction }`. The consumer is responsible for reordering `rows` in response — DataTable does not sort internally. Pass `undefined` initially when no column is sorted; the component will never write back `undefined` itself (sort always toggles to a column). Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

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

@@ -6,6 +6,7 @@
  * 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';
+@import '../checkbox/checkbox.css';
 
 @layer cinder.components {
   /* ========================================
@@ -38,16 +39,48 @@
     contain: layout paint;
   }
 
+  .cinder-data-table[data-cinder-selectable] .cinder-table__cell--selection,
+  .cinder-data-table[data-cinder-selectable] .cinder-table__header-cell--selection {
+    width: 1px;
+    padding-inline: var(--cinder-space-3);
+    padding-block: var(--cinder-space-2);
+    text-align: center;
+    vertical-align: middle;
+  }
+
+  .cinder-data-table .cinder-table__cell--selection .cinder-checkbox-field,
+  .cinder-data-table .cinder-table__header-cell--selection .cinder-checkbox-field {
+    display: inline-block;
+  }
+
+  .cinder-data-table .cinder-table__cell--selection .cinder-checkbox-row,
+  .cinder-data-table .cinder-table__header-cell--selection .cinder-checkbox-row {
+    display: inline-flex;
+  }
+
   .cinder-data-table[data-cinder-virtualized] .cinder-table__row[data-cinder-virtual-row] {
     block-size: var(--_cinder-data-table-row-height, 44px);
   }
 
+  .cinder-data-table tbody .cinder-table__row:focus-within {
+    background: var(--cinder-surface-hover);
+  }
+
   .cinder-data-table[data-cinder-virtualized]
     .cinder-table__row[data-cinder-virtual-row]:focus-visible {
     outline: var(--cinder-ring-width) solid transparent;
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-data-table[data-cinder-virtualized]
+      .cinder-table__row[data-cinder-virtual-row]:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(-1 * var(--cinder-ring-width));
+      box-shadow: none;
+    }
+  }
+
   .cinder-data-table__virtual-spacer-cell {
     padding: 0;
     border: 0;