@lostgradient/cinder 0.4.0 → 0.4.1

package/src/_internal/tree-registry.svelte.ts

@@ -1,6 +1,7 @@
 import { SvelteMap } from 'svelte/reactivity';
 
 import { inDocumentOrder } from '../utilities/document-order.ts';
+import { findTypeaheadMatch } from '../utilities/typeahead.ts';
 
 /** A single registered tree node. */
 export type TreeNodeRegistration = {
@@ -224,20 +225,17 @@ export class TreeRegistry {
     visibilityPredicate?: TreeVisibilityPredicate,
   ): string | undefined {
     const visible = this.getVisible(expandedIds, visibilityPredicate);
-    const lower = prefix.toLowerCase();
-    const startIndex = visible.indexOf(currentId);
-
-    // Search from item after current, then wrap around to the start.
-    // visible[index] is always defined: index = (startIndex + offset) % visible.length
-    // and we only enter this loop when visible.length > 0 (offset <= visible.length guard).
-    for (let offset = 1; offset <= visible.length; offset++) {
-      const index = (startIndex + offset) % visible.length;
-      const id = visible[index]!;
-      const node = this.#nodes.get(id);
-      if (node && node.label().toLowerCase().startsWith(lower)) {
-        return id;
-      }
-    }
-    return undefined;
+    return findTypeaheadMatch(
+      visible.map((id) => {
+        const node = this.#nodes.get(id);
+        return {
+          value: id,
+          label: node?.label() ?? '',
+          disabled: node?.disabled,
+        };
+      }),
+      prefix,
+      visible.indexOf(currentId),
+    );
   }
 }

package/src/components/_sortable-item.svelte

@@ -1,6 +1,6 @@
 <script lang="ts" module>
   import type { Snippet } from 'svelte';
-  import type { SortableItemContext } from '../utilities/sortable-controller.svelte.ts';
+  import type { SortableItemContext } from '../utilities/sortable-controller.types.ts';
 
   /** Internal props for SortableItem — not part of the public package API. */
   export type SortableItemProps<Item> = {

package/src/components/autocomplete/autocomplete.svelte

@@ -24,6 +24,7 @@
   import { devWarn } from '../../utilities/dev-warn.ts';
   import { resolveFieldControl } from '../../_internal/field-control.ts';
   import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+  import { pushEscapeHandler } from '../../_internal/overlay.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import Popover from '../popover/popover.svelte';
   import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
@@ -170,6 +171,17 @@
     suggestions = [];
   }
 
+  function handleEscape(event: KeyboardEvent | undefined = undefined): void {
+    const wasOpen = open;
+    closePopup();
+    if (wasOpen) event?.preventDefault();
+  }
+
+  $effect(() => {
+    if (!open) return;
+    return pushEscapeHandler(handleEscape);
+  });
+
   $effect(() => {
     const query = value;
     const source = suggestionSource;
@@ -381,8 +393,8 @@
     }
 
     if (event.key === 'Escape' && open) {
-      event.preventDefault();
-      closePopup();
+      if (event.defaultPrevented) return;
+      handleEscape(event);
       return;
     }
 
@@ -484,6 +496,7 @@
   role="listbox"
   focusManagement="preserve"
   wireTriggerAria={false}
+  closeOnEscape={false}
   widthMode="match-anchor"
   class="cinder-autocomplete__panel"
 >

package/src/components/combobox/README.md

@@ -27,6 +27,7 @@ Filterable dropdown that combines a text input with a selectable option list.
 | `inputValue`        | `string`   | no       | —       | Free-text input value (the text the user has typed). Bindable.                                                                                                                                                                         |
 | `label`             | `string`   | no       | —       | Visible label rendered in a `<label>` associated via `for`.                                                                                                                                                                            |
 | `maxVisibleOptions` | `number`   | no       | —       | Hard cap on visible filtered options. Default 200.                                                                                                                                                                                     |
+| `name`              | `string`   | no       | —       | Native form field name. Renders a hidden input carrying the selected value.                                                                                                                                                            |
 | `placeholder`       | `string`   | no       | —       | Placeholder when no value is selected.                                                                                                                                                                                                 |
 | `required`          | `boolean`  | no       | —       | Marks the field required: renders the required marker on the label and sets `aria-required` on the input. Inherited from a wrapping FormField when unset.                                                                              |
 | `filter`            | `(opaque)` | no       | —       | Custom synchronous filter. Receives an option and the current input value; returns true to keep. Defaults to case-insensitive substring match on label. Not expressible in JSON Schema; see the component types for the signature.     |

package/src/components/combobox/combobox.svelte

@@ -28,6 +28,7 @@
   let {
     id,
     value = $bindable(''),
+    name,
     inputValue = $bindable(''),
     options,
     label,
@@ -92,8 +93,12 @@
   let open = $state(false);
   let activeIndex = $state(-1);
   let inputElement = $state<HTMLInputElement | null>(null);
+  let hiddenInputElement = $state<HTMLInputElement | null>(null);
   let listboxElement = $state<HTMLElement | null>(null);
   let committedLabel = $state('');
+  let resetSyncTimeout: ReturnType<typeof setTimeout> | undefined;
+  const initialValue = untrack(() => value);
+  const initialInputValue = untrack(() => inputValue);
 
   // Reset active index whenever the filtered set changes so we don't point
   // at a stale option.
@@ -203,6 +208,45 @@
     open = false;
   }
 
+  function resetToInitialValue(event: Event): void {
+    if (resetSyncTimeout !== undefined) clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+      resetSyncTimeout = undefined;
+      if (event.defaultPrevented) return;
+      value = initialValue;
+      const matched = options.find((option) => option.value === initialValue);
+      const nextInputValue = matched?.label ?? initialInputValue;
+      inputValue = nextInputValue;
+      committedLabel = matched?.label ?? '';
+      open = false;
+      activeIndex = -1;
+      if (inputElement) inputElement.value = nextInputValue;
+      if (hiddenInputElement) hiddenInputElement.value = initialValue;
+    }, 0);
+  }
+
+  $effect(() => {
+    const input = hiddenInputElement;
+    if (input === null) return;
+    const form = input.form;
+    form?.addEventListener('reset', resetToInitialValue);
+    return () => {
+      form?.removeEventListener('reset', resetToInitialValue);
+      if (resetSyncTimeout !== undefined) {
+        clearTimeout(resetSyncTimeout);
+        resetSyncTimeout = undefined;
+      }
+    };
+  });
+
+  $effect(() => {
+    inputElement?.setCustomValidity(
+      (resolvedRequired && !value) || inputValue !== committedLabel
+        ? 'Please select an option.'
+        : '',
+    );
+  });
+
   function handleKeydown(event: KeyboardEvent) {
     if (event.key === 'ArrowDown') {
       event.preventDefault();
@@ -262,6 +306,7 @@
       autocorrect="off"
       spellcheck="false"
       disabled={resolvedDisabled}
+      required={resolvedRequired}
       {placeholder}
       value={inputValue}
       aria-autocomplete="list"
@@ -278,6 +323,16 @@
     />
   </div>
 
+  {#if name}
+    <input
+      bind:this={hiddenInputElement}
+      type="hidden"
+      {name}
+      {value}
+      disabled={resolvedDisabled}
+    />
+  {/if}
+
   {#if open && filteredOptions.length > 0}
     <Popover
       bind:open

package/src/components/combobox/combobox.types.ts

@@ -38,6 +38,8 @@ export type ComboboxProps<T extends string = string> = {
   id: string;
   /** Currently selected value. Bindable. `''` when nothing is selected. */
   value?: NoInfer<T> | '';
+  /** Native form field name. Renders a hidden input carrying the selected value. */
+  name?: string | undefined;
   /** Free-text input value (the text the user has typed). Bindable. */
   inputValue?: string;
   /** Full set of options to filter. The sole inference source for T. */

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,6 +39,25 @@
     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);
   }

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

@@ -9,15 +9,21 @@
    * @useWhen Rendering a structured dataset where columns and rows are known at runtime (e.g. API responses, config-driven dashboards).
    * @useWhen You want correct scope=col / scope=row semantics and aria-sort wiring without writing Table.Header / Table.Body manually.
    * @avoidWhen You need custom cell rendering, interactive cells, nested components, or column spanning — use the compositional Table family directly.
-   * @avoidWhen You need row selection — DataTable does not expose a selection prop; use Table with selectable instead.
+   * @avoidWhen You need fully custom cell or row composition — use Table directly.
    * @related table, table-header, table-body, table-row, table-cell, table-header-cell
    */
-  export type { DataTableColumn, DataTableProps, DataTableRow } from './data-table.types.ts';
+  export type {
+    DataTableColumn,
+    DataTableProps,
+    DataTableRow,
+    DataTableSelectionMode,
+  } from './data-table.types.ts';
 </script>
 
 <script lang="ts" generics="Row extends DataTableRow">
-  import { tick } from 'svelte';
+  import { tick, untrack } from 'svelte';
 
+  import Checkbox from '../checkbox/checkbox.svelte';
   import TableBody from '../table-body/table-body.svelte';
   import TableCell from '../table-cell/table-cell.svelte';
   import TableHeaderCell from '../table-header-cell/table-header-cell.svelte';
@@ -40,6 +46,12 @@
     rows,
     caption,
     sort = $bindable(),
+    selectable = 'none',
+    selectedRowIds = $bindable<string[] | Set<string>>([]),
+    getRowId,
+    isRowSelectionDisabled,
+    selectAllLabel = 'Select all rows',
+    rowSelectionLabel,
     stickyHeader = false,
     density = 'comfortable',
     scrollable = false,
@@ -62,6 +74,8 @@
   let previousRowCount = 0;
   let hasObservedRowCount = false;
   let shouldStickAfterAppend = false;
+  let resetSyncTimeout: ReturnType<typeof setTimeout> | undefined;
+  const initialSelectedRowIds = untrack(() => new Set(selectedRowIds));
 
   /**
    * The key of the row-header column. Explicitly set via `column.rowHeader === true`,
@@ -71,6 +85,25 @@
   const rowHeaderKey = $derived(
     (columns.find((column) => column.rowHeader === true) ?? columns[0])?.key,
   );
+  const selectionEnabled = $derived(selectable !== 'none');
+  const selectedRowIdSet = $derived(new Set(selectedRowIds));
+  const selectableRowIds = $derived(
+    rows
+      .map((row, index) => ({
+        id: resolveRowId(row, index),
+        disabled: isRowSelectionDisabled?.(row, index) ?? false,
+      }))
+      .filter((row) => !row.disabled)
+      .map((row) => row.id),
+  );
+  const allRowsSelected = $derived(
+    selectable === 'multiple' &&
+      selectableRowIds.length > 0 &&
+      selectableRowIds.every((id) => selectedRowIdSet.has(id)),
+  );
+  const someRowsSelected = $derived(
+    selectable === 'multiple' && selectableRowIds.some((id) => selectedRowIdSet.has(id)),
+  );
   const shouldVirtualizeRows = $derived(virtualized);
   const resolvedRowHeight = $derived(resolveVirtualItemHeight(rowHeight, 44));
   const resolvedOverscan = $derived(resolveVirtualOverscan(overscan));
@@ -113,6 +146,76 @@
     return undefined;
   }
 
+  function resolveRowId(row: Row, index: number): string {
+    if (getRowId) return getRowId(row, index);
+    const candidate = row['id'];
+    if (typeof candidate === 'string' || typeof candidate === 'number') return String(candidate);
+    return String(index);
+  }
+
+  function readableRowLabel(row: Row, index: number): string {
+    const customLabel = rowSelectionLabel?.(row, index)?.trim();
+    if (customLabel) return customLabel;
+    const rowHeaderValue = rowHeaderKey ? row[rowHeaderKey] : undefined;
+    if (typeof rowHeaderValue === 'string' || typeof rowHeaderValue === 'number') {
+      return `Select ${rowHeaderValue}`;
+    }
+    return `Select row ${index + 1}`;
+  }
+
+  function commitSelectedRowIds(nextSelectedRowIds: Set<string>): void {
+    selectedRowIds =
+      selectedRowIds instanceof Set ? new Set(nextSelectedRowIds) : Array.from(nextSelectedRowIds);
+  }
+
+  function setRowSelected(row: Row, index: number, nextSelected: boolean): void {
+    if (!selectionEnabled || isRowSelectionDisabled?.(row, index)) return;
+    const rowId = resolveRowId(row, index);
+    const nextSelectedRowIds = new Set(selectedRowIdSet);
+
+    if (selectable === 'single') {
+      commitSelectedRowIds(nextSelected ? new Set([rowId]) : new Set());
+      return;
+    }
+
+    if (nextSelected) nextSelectedRowIds.add(rowId);
+    else nextSelectedRowIds.delete(rowId);
+    commitSelectedRowIds(nextSelectedRowIds);
+  }
+
+  function setAllRowsSelected(nextSelected: boolean): void {
+    if (selectable !== 'multiple') return;
+    const nextSelectedRowIds = new Set(selectedRowIdSet);
+    for (const rowId of selectableRowIds) {
+      if (nextSelected) nextSelectedRowIds.add(rowId);
+      else nextSelectedRowIds.delete(rowId);
+    }
+    commitSelectedRowIds(nextSelectedRowIds);
+  }
+
+  function syncSelectionAfterFormReset(event: Event): void {
+    if (resetSyncTimeout !== undefined) clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+      resetSyncTimeout = undefined;
+      if (event.defaultPrevented) return;
+      commitSelectedRowIds(initialSelectedRowIds);
+    }, 0);
+  }
+
+  $effect(() => {
+    const form = wrapperElement?.closest('form');
+    if (!form || !selectionEnabled) return;
+
+    form.addEventListener('reset', syncSelectionAfterFormReset);
+    return () => {
+      form.removeEventListener('reset', syncSelectionAfterFormReset);
+      if (resetSyncTimeout !== undefined) {
+        clearTimeout(resetSyncTimeout);
+        resetSyncTimeout = undefined;
+      }
+    };
+  });
+
   $effect(() => {
     const element = wrapperElement;
     if (!element || !shouldVirtualizeRows) return;
@@ -294,6 +397,14 @@
   function handleRowKeydown(event: KeyboardEvent, index: number): void {
     if (!shouldVirtualizeRows) return;
 
+    if (event.key === ' ' && selectionEnabled) {
+      const row = rows[index];
+      if (!row || isRowSelectionDisabled?.(row, index)) return;
+      event.preventDefault();
+      setRowSelected(row, index, !selectedRowIdSet.has(resolveRowId(row, index)));
+      return;
+    }
+
     if (event.key === 'ArrowDown') {
       event.preventDefault();
       focusRow(index + 1);
@@ -326,6 +437,26 @@
   >
     <TableHeader>
       <TableRow>
+        {#if selectionEnabled}
+          <th
+            scope="col"
+            class="cinder-table__header-cell cinder-table__header-cell--selection"
+            aria-label={selectable === 'single' ? 'Row selection' : undefined}
+          >
+            {#if selectable === 'multiple'}
+              <Checkbox
+                checked={allRowsSelected}
+                indeterminate={someRowsSelected && !allRowsSelected}
+                aria-label={selectAllLabel}
+                class="cinder-table__selection-checkbox"
+                onchange={(event) => {
+                  const input = event.currentTarget as HTMLInputElement;
+                  setAllRowsSelected(input.checked);
+                }}
+              />
+            {/if}
+          </th>
+        {/if}
         {#each columns as column (column.key)}
           <TableHeaderCell
             {...column.sortable ? { column: column.key } : {}}
@@ -347,7 +478,7 @@
         <tr class="cinder-data-table__virtual-spacer" aria-hidden="true">
           <td
             class="cinder-data-table__virtual-spacer-cell"
-            colspan={columns.length}
+            colspan={columns.length + (selectionEnabled ? 1 : 0)}
             style:height={`${virtualWindow.leadingSize}px`}
           ></td>
         </tr>
@@ -365,6 +496,26 @@
               }
             : {}}
         >
+          {#if selectionEnabled}
+            {@const rowSelectionDisabled =
+              isRowSelectionDisabled?.(virtualRow.row, virtualRow.index) ?? false}
+            {@const rowId = resolveRowId(virtualRow.row, virtualRow.index)}
+            <td
+              class="cinder-table__cell cinder-table__cell--selection"
+              data-cinder-selection-disabled={rowSelectionDisabled || undefined}
+            >
+              <Checkbox
+                checked={selectedRowIdSet.has(rowId)}
+                disabled={rowSelectionDisabled}
+                aria-label={readableRowLabel(virtualRow.row, virtualRow.index)}
+                class="cinder-table__selection-checkbox"
+                onchange={(event) => {
+                  const input = event.currentTarget as HTMLInputElement;
+                  setRowSelected(virtualRow.row, virtualRow.index, input.checked);
+                }}
+              />
+            </td>
+          {/if}
           {#each columns as column (column.key)}
             <TableCell
               as={column.key === rowHeaderKey ? 'th' : 'td'}
@@ -379,7 +530,7 @@
         <tr class="cinder-data-table__virtual-spacer" aria-hidden="true">
           <td
             class="cinder-data-table__virtual-spacer-cell"
-            colspan={columns.length}
+            colspan={columns.length + (selectionEnabled ? 1 : 0)}
             style:height={`${virtualWindow.trailingSize}px`}
           ></td>
         </tr>
@@ -398,6 +549,7 @@
     className,
   )}
   data-cinder-virtualized={shouldVirtualizeRows ? 'true' : undefined}
+  data-cinder-selectable={selectionEnabled || undefined}
   style:--cinder-data-table-height={shouldVirtualizeRows ? height : undefined}
   style:--_cinder-data-table-row-height={shouldVirtualizeRows
     ? `${resolvedRowHeight}px`

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

@@ -44,6 +44,9 @@ export type DataTableColumn<Row extends DataTableRow = DataTableRow> = {
   rowHeader?: boolean;
 };
 
+/** Row-selection mode for DataTable. */
+export type DataTableSelectionMode = 'none' | 'single' | 'multiple';
+
 /**
  * Props for the DataTable component.
  *
@@ -73,6 +76,30 @@ export type DataTableProps<Row extends DataTableRow = DataTableRow> = Omit<
    * write back `undefined` itself (sort always toggles to a column).
    */
   sort?: TableSort | undefined;
+  /**
+   * 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"`.
+   */
+  selectable?: DataTableSelectionMode;
+  /**
+   * Bound selected row ids. Arrays stay arrays on update; Sets stay Sets.
+   * When omitted, DataTable starts with an empty array.
+   */
+  selectedRowIds?: string[] | Set<string>;
+  /**
+   * 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.
+   */
+  getRowId?: (row: Row, index: number) => string;
+  /** Returns true when a row should render a disabled selection checkbox. */
+  isRowSelectionDisabled?: (row: Row, index: number) => boolean;
+  /** Accessible label for the multiple-selection header checkbox. */
+  selectAllLabel?: string;
+  /** Accessible label for an individual row selection checkbox. */
+  rowSelectionLabel?: (row: Row, index: number) => string;
   /** When true, the header sticks to the top of the scrolling container. */
   stickyHeader?: boolean;
   /**

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

@@ -2,5 +2,10 @@ import './data-table.css';
 import DataTable from './data-table.svelte';
 
 export default DataTable;
-export type { DataTableColumn, DataTableProps, DataTableRow } from './data-table.types.ts';
+export type {
+  DataTableColumn,
+  DataTableProps,
+  DataTableRow,
+  DataTableSelectionMode,
+} from './data-table.types.ts';
 export { DataTable };