@lostgradient/cinder 0.2.0 → 0.3.0

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

@@ -146,10 +146,14 @@
     get disabled() {
       return disabled;
     },
+    get isOpen() {
+      return open;
+    },
     get longPressDelay() {
       return longPressDelay;
     },
     openAt,
+    close,
   });
 
   $effect(() => {

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

@@ -9,11 +9,16 @@ export type ContextMenuAnchorPoint = {
 };
 
 export type ContextMenuProps = {
+  /** Controls the open state of the context menu; bindable for controlled usage. */
   open?: boolean;
   onopenchange?: (open: boolean) => void;
+  /** Explicit pointer coordinates at which to anchor the menu, overriding the position captured from the right-click or long-press event. */
   anchorPoint?: ContextMenuAnchorPoint | undefined;
+  /** When true, disables context-menu activation on right-click and long-press within the trigger region. Default `false`. */
   disabled?: boolean;
+  /** Duration in milliseconds a touch pointer must be held before the menu opens on mobile. Default `500`. */
   longPressDelay?: number;
   children: Snippet;
+  /** Additional class names merged with the component's root class. */
   class?: string;
 };

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

@@ -28,8 +28,8 @@ Compose-only trigger region that opens a context-menu on right-click or touch lo
 
 | 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. |
+| `class`    | `string`   | no       | —       | Additional class names merged with the component's root class.                                                             |
+| `children` | `(opaque)` | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 
 <!-- generated:props:end -->
 

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

@@ -129,6 +129,12 @@
       callTriggerHandler(onkeydown, event);
       return;
     }
+    if (event.key === 'Escape' && context.isOpen) {
+      event.preventDefault();
+      context.close();
+      callTriggerHandler(onkeydown, event);
+      return;
+    }
     if (event.key !== 'ContextMenu' && !(event.shiftKey && event.key === 'F10')) {
       callTriggerHandler(onkeydown, event);
       return;

package/src/components/context-menu-trigger/context-menu-trigger.types.ts

@@ -2,6 +2,7 @@ import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 
 export type ContextMenuTriggerProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Additional class names merged with the component's root class. */
   class?: string;
   children: Snippet;
 };

package/src/components/copy-button/README.md

@@ -24,8 +24,8 @@ Button that copies a given text value to the clipboard with visual feedback.
 | `iconOnly`        | `boolean`  | no       | —       | Render the button with only an icon and a visually hidden label. When true, defaults to a Copy icon (idle) and a Check icon (copied).                                                                                                                                                |
 | `label`           | `string`   | no       | —       | Accessible label for the idle state. Defaults to "Copy to clipboard".                                                                                                                                                                                                                |
 | `value`           | `string`   | yes      | —       | Text to copy to the clipboard.                                                                                                                                                                                                                                                       |
-| `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.                                                                                                                                                           |
-| `confirmation`    | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                           |
+| `children`        | `(opaque)` | no       | —       | Default content (idle state). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                             |
+| `confirmation`    | `(opaque)` | no       | —       | Content rendered while in the "copied" state. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                             |
 
 <!-- generated:props:end -->
 

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

@@ -0,0 +1,80 @@
+# DataGrid
+
+ARIA data grid foundation for spreadsheet-like datasets with stable row identity, explicit column widths, keyboard navigation, row selection, cell/range selection, and pinned-column metadata.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { DataGrid } from '@lostgradient/cinder/data-grid';
+
+  const columns = [
+    { key: 'id', header: 'Order', width: 120, pin: 'left' },
+    { key: 'customer', header: 'Customer', width: 220 },
+    { key: 'status', header: 'Status', width: 140 },
+  ];
+
+  const rows = [
+    { id: 'ORD-1001', customer: 'Ada Lovelace', status: 'Packed' },
+    { id: 'ORD-1002', customer: 'Grace Hopper', status: 'Shipped' },
+  ];
+</script>
+
+<DataGrid {columns} {rows} getRowId={(row) => row.id} aria-label="Orders" />
+```
+
+## Guidance
+
+### Use When
+
+- Rendering an interactive tabular surface that needs grid semantics instead of native table semantics.
+- You need built-in row selection, cell focus, range selection, and copy behavior before adding virtualization or editing.
+
+### 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.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop                     | Type                                           | Required | Default | Description                                                                                                                                           |
+| ------------------------ | ---------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`                  | `string`                                       | no       | —       | Additional class names merged onto the root grid.                                                                                                     |
+| `columnOrder`            | `string`[]                                     | no       | —       | Applies a supplied column order.                                                                                                                      |
+| `columnSizing`           | `object`                                       | no       | —       | Overrides resolved column widths by column key.                                                                                                       |
+| `density`                | `"compact"` \| `"comfortable"` \| `"spacious"` | no       | —       | Controls body row padding density. Defaults to `'comfortable'`.                                                                                       |
+| `rowHeight`              | `number`                                       | no       | —       | Fixed body-row pixel height used by row virtualization. Defaults to 44 when omitted or invalid.                                                       |
+| `selectionMode`          | `"none"` \| `"single"` \| `"multiple"`         | no       | —       | Controls row-selection behavior. Cell focus and range selection remain available.                                                                     |
+| `selectionModel`         | `string`[]                                     | no       | —       | Controlled row-selection ids, keyed by `getRowId`.                                                                                                    |
+| `stickyHeader`           | `boolean`                                      | no       | —       | Keeps the column header row pinned to the top edge while scrolling. Defaults to `true`.                                                               |
+| `virtualizeColumns`      | `boolean`                                      | no       | —       | Enables LTR horizontal virtualization for unpinned columns. Pinned columns stay rendered.                                                             |
+| `virtualizeRows`         | `boolean`                                      | no       | —       | Enables fixed-height row virtualization.                                                                                                              |
+| `columnPinning`          | `(opaque)`                                     | no       | —       | Pins supplied column keys to the left or right edge. Not expressible in JSON Schema; see the component types for the signature.                       |
+| `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. |
+| `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.                           |
+
+<!-- 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-grid/_internal/column-model.svelte.ts

@@ -0,0 +1,218 @@
+import type { Snippet } from 'svelte';
+import type {
+  DataGridCellContext,
+  DataGridColumnDef,
+  DataGridColumnPin,
+  DataGridColumnPinning,
+  DataGridColumnSizing,
+  DataGridSortComparator,
+} from '../data-grid.types.ts';
+
+export const DEFAULT_DATA_GRID_COLUMN_WIDTH = 150;
+export const DEFAULT_DATA_GRID_COLUMN_MIN_WIDTH = 60;
+
+export type DataGridValueColumn<TRow> = {
+  key: string;
+  sortable?: boolean;
+  sortComparator?: DataGridSortComparator<TRow>;
+  getValue?: (row: TRow) => unknown;
+};
+
+export type ResolvedDataGridColumn<TRow> = DataGridValueColumn<TRow> & {
+  header: string | Snippet;
+  cell?: Snippet<[DataGridCellContext<TRow>]>;
+  width: number;
+  minWidth: number;
+  maxWidth?: number;
+  colIndex: number;
+  renderIndex: number;
+  pin?: DataGridColumnPin;
+  pinOffset: number;
+};
+
+type DataGridColumnModelOptions<TRow> = {
+  columns: () => readonly DataGridColumnDef<TRow>[];
+  columnOrder: () => readonly string[] | undefined;
+  columnSizing: () => DataGridColumnSizing | undefined;
+  columnPinning: () => DataGridColumnPinning | undefined;
+};
+
+export class DataGridColumnModel<TRow> {
+  readonly columns: () => readonly DataGridColumnDef<TRow>[];
+  readonly columnOrder: () => readonly string[] | undefined;
+  readonly columnSizing: () => DataGridColumnSizing | undefined;
+  readonly columnPinning: () => DataGridColumnPinning | undefined;
+
+  constructor(options: DataGridColumnModelOptions<TRow>) {
+    this.columns = options.columns;
+    this.columnOrder = options.columnOrder;
+    this.columnSizing = options.columnSizing;
+    this.columnPinning = options.columnPinning;
+  }
+
+  readonly orderedColumns = $derived.by(() =>
+    orderColumns(this.columns(), this.columnOrder()).map((column, index) =>
+      resolveColumn(column, index, this.columnSizing(), this.columnPinning()),
+    ),
+  );
+
+  readonly leftPinnedColumns = $derived.by(() =>
+    withPinOffsets(
+      this.orderedColumns.filter((column) => column.pin === 'left'),
+      'left',
+    ),
+  );
+
+  readonly rightPinnedColumns = $derived.by(() =>
+    withPinOffsets(
+      this.orderedColumns.filter((column) => column.pin === 'right'),
+      'right',
+    ),
+  );
+
+  readonly leftPinnedWidth = $derived(totalColumnWidth(this.leftPinnedColumns));
+
+  readonly rightPinnedWidth = $derived(totalColumnWidth(this.rightPinnedColumns));
+
+  readonly unpinnedColumns = $derived.by(() =>
+    this.orderedColumns.filter((column) => column.pin === undefined),
+  );
+
+  readonly renderColumns = $derived.by(() => {
+    return withRenderColIndexes([
+      ...this.leftPinnedColumns,
+      ...this.unpinnedColumns,
+      ...this.rightPinnedColumns,
+    ]);
+  });
+}
+
+function orderColumns<TRow>(
+  columns: readonly DataGridColumnDef<TRow>[],
+  columnOrder: readonly string[] | undefined,
+): readonly DataGridColumnDef<TRow>[] {
+  assertUniqueColumnKeys(columns);
+  if (!columnOrder || columnOrder.length === 0) return columns;
+
+  const byKey = new Map(columns.map((column) => [column.key, column]));
+  const ordered = columnOrder.flatMap((key) => {
+    const column = byKey.get(key);
+    if (!column) return [];
+    byKey.delete(key);
+    return [column];
+  });
+
+  return [...ordered, ...byKey.values()];
+}
+
+function assertUniqueColumnKeys<TRow>(columns: readonly DataGridColumnDef<TRow>[]): void {
+  const seenColumnKeys = new Set<string>();
+  for (const column of columns) {
+    if (seenColumnKeys.has(column.key)) {
+      throw new Error(
+        `[cinder-data-grid] DataGrid column keys must be unique. Duplicate column key: ${JSON.stringify(column.key)}.`,
+      );
+    }
+    seenColumnKeys.add(column.key);
+  }
+}
+
+function resolveColumn<TRow>(
+  column: DataGridColumnDef<TRow>,
+  index: number,
+  columnSizing: DataGridColumnSizing | undefined,
+  columnPinning: DataGridColumnPinning | undefined,
+): ResolvedDataGridColumn<TRow> {
+  const minWidth = Math.max(
+    0,
+    finiteNumberOrFallback(column.minWidth, DEFAULT_DATA_GRID_COLUMN_MIN_WIDTH),
+  );
+  const baseWidth = finiteNumberOrFallback(
+    columnSizing?.[column.key] ?? column.width,
+    DEFAULT_DATA_GRID_COLUMN_WIDTH,
+  );
+  const maxWidth = Math.max(
+    minWidth,
+    finiteNumberOrFallback(column.maxWidth, Number.POSITIVE_INFINITY),
+  );
+  const pin = resolveColumnPin(column, columnPinning);
+
+  const resolvedColumn: ResolvedDataGridColumn<TRow> = {
+    key: column.key,
+    header: column.header,
+    minWidth,
+    width: Math.min(Math.max(baseWidth, minWidth), maxWidth),
+    colIndex: index + 1,
+    renderIndex: index + 1,
+    pinOffset: 0,
+  };
+  if (column.cell !== undefined) resolvedColumn.cell = column.cell;
+  if (column.maxWidth !== undefined) resolvedColumn.maxWidth = column.maxWidth;
+  if (column.sortable !== undefined) resolvedColumn.sortable = column.sortable;
+  if (column.sortComparator !== undefined) resolvedColumn.sortComparator = column.sortComparator;
+  if (column.getValue !== undefined) resolvedColumn.getValue = column.getValue;
+
+  if (pin !== undefined) return { ...resolvedColumn, pin };
+
+  const { pin: _pin, ...unpinnedColumn } = resolvedColumn;
+  return unpinnedColumn;
+}
+
+function finiteNumberOrFallback(value: number | undefined, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function resolveColumnPin<TRow>(
+  column: DataGridColumnDef<TRow>,
+  columnPinning: DataGridColumnPinning | undefined,
+): DataGridColumnPin | undefined {
+  if (columnPinning?.left?.includes(column.key)) return 'left';
+  if (columnPinning?.right?.includes(column.key)) return 'right';
+  return column.pin;
+}
+
+function withPinOffsets<TRow>(
+  columns: readonly ResolvedDataGridColumn<TRow>[],
+  pin: DataGridColumnPin,
+): ResolvedDataGridColumn<TRow>[] {
+  if (pin === 'left') {
+    let offset = 0;
+    return columns.map((column) => {
+      const nextColumn = { ...column, pinOffset: offset };
+      offset += column.width;
+      return nextColumn;
+    });
+  }
+
+  let offset = 0;
+  const columnsWithOffsets: ResolvedDataGridColumn<TRow>[] = [];
+  for (let index = columns.length - 1; index >= 0; index -= 1) {
+    const column = columns[index];
+    if (!column) continue;
+    columnsWithOffsets.unshift({ ...column, pinOffset: offset });
+    offset += column.width;
+  }
+  return columnsWithOffsets;
+}
+
+function withRenderColIndexes<TRow>(
+  columns: readonly ResolvedDataGridColumn<TRow>[],
+): ResolvedDataGridColumn<TRow>[] {
+  return columns.map((column, index) => ({ ...column, renderIndex: index + 1 }));
+}
+
+function totalColumnWidth<TRow>(columns: readonly ResolvedDataGridColumn<TRow>[]): number {
+  return columns.reduce((totalWidth, column) => totalWidth + column.width, 0);
+}
+
+export function getDataGridColumnValue<TRow>(
+  row: TRow,
+  column: DataGridValueColumn<TRow>,
+): unknown {
+  if (column.getValue) return column.getValue(row);
+  if (row !== null && typeof row === 'object' && Object.hasOwn(row, column.key)) {
+    const value: unknown = Reflect.get(row, column.key);
+    return value;
+  }
+  return undefined;
+}

package/src/components/data-grid/_internal/geometry.ts

@@ -0,0 +1,87 @@
+export type DataGridCellCoordinate = {
+  rowId: string;
+  columnKey: string;
+};
+
+export type DataGridCellRange = {
+  anchor: DataGridCellCoordinate;
+  focus: DataGridCellCoordinate;
+  rowIds: readonly string[];
+  columnKeys: readonly string[];
+  startRowIndex: number;
+  endRowIndex: number;
+  startColumnIndex: number;
+  endColumnIndex: number;
+};
+
+export function getCellCoordinateKey(cell: DataGridCellCoordinate): string {
+  return `${cell.rowId}\u0000${cell.columnKey}`;
+}
+
+export function computeCellRange(
+  anchor: DataGridCellCoordinate,
+  focus: DataGridCellCoordinate,
+  rowIds: readonly string[],
+  columnKeys: readonly string[],
+): DataGridCellRange | undefined {
+  const anchorRowIndex = rowIds.indexOf(anchor.rowId);
+  const focusRowIndex = rowIds.indexOf(focus.rowId);
+  const anchorColumnIndex = columnKeys.indexOf(anchor.columnKey);
+  const focusColumnIndex = columnKeys.indexOf(focus.columnKey);
+
+  if (anchorRowIndex < 0 || focusRowIndex < 0 || anchorColumnIndex < 0 || focusColumnIndex < 0) {
+    return undefined;
+  }
+
+  const startRowIndex = Math.min(anchorRowIndex, focusRowIndex);
+  const endRowIndex = Math.max(anchorRowIndex, focusRowIndex);
+  const startColumnIndex = Math.min(anchorColumnIndex, focusColumnIndex);
+  const endColumnIndex = Math.max(anchorColumnIndex, focusColumnIndex);
+
+  return {
+    anchor,
+    focus,
+    rowIds: rowIds.slice(startRowIndex, endRowIndex + 1),
+    columnKeys: columnKeys.slice(startColumnIndex, endColumnIndex + 1),
+    startRowIndex,
+    endRowIndex,
+    startColumnIndex,
+    endColumnIndex,
+  };
+}
+
+export function isCellInRange(
+  cell: DataGridCellCoordinate,
+  range: DataGridCellRange | undefined,
+): boolean {
+  if (!range) return false;
+  return range.rowIds.includes(cell.rowId) && range.columnKeys.includes(cell.columnKey);
+}
+
+export function getCellsInRange(range: DataGridCellRange | undefined): DataGridCellCoordinate[] {
+  if (!range) return [];
+  return range.rowIds.flatMap((rowId) =>
+    range.columnKeys.map((columnKey) => ({
+      rowId,
+      columnKey,
+    })),
+  );
+}
+
+export function clampCellCoordinate(
+  cell: DataGridCellCoordinate,
+  rowIds: readonly string[],
+  columnKeys: readonly string[],
+): DataGridCellCoordinate | undefined {
+  if (rowIds.length === 0 || columnKeys.length === 0) return undefined;
+
+  const rowIndex = rowIds.indexOf(cell.rowId);
+  const columnIndex = columnKeys.indexOf(cell.columnKey);
+  if (rowIndex < 0 || columnIndex < 0) return undefined;
+
+  return {
+    rowId: rowIds[Math.min(Math.max(rowIndex, 0), rowIds.length - 1)] ?? rowIds[0]!,
+    columnKey:
+      columnKeys[Math.min(Math.max(columnIndex, 0), columnKeys.length - 1)] ?? columnKeys[0]!,
+  };
+}

package/src/components/data-grid/_internal/keyboard-model.ts

@@ -0,0 +1,131 @@
+export type DataGridKeyboardAction =
+  | {
+      type: 'move-cell';
+      rowIndex: number;
+      columnIndex: number;
+      extend: boolean;
+    }
+  | {
+      type: 'copy-selection';
+    }
+  | {
+      type: 'select-all';
+    }
+  | {
+      type: 'collapse-selection';
+    }
+  | {
+      type: 'select-active-cell';
+    };
+
+export type DataGridKeyboardContext = {
+  activeRowIndex: number;
+  activeColumnIndex: number;
+  rowCount: number;
+  columnCount: number;
+  pageSize?: number;
+};
+
+export function dataGridKeyToAction(
+  event: KeyboardEvent,
+  context: DataGridKeyboardContext,
+): DataGridKeyboardAction | undefined {
+  const { activeRowIndex, activeColumnIndex, rowCount, columnCount, pageSize = 10 } = context;
+  if (rowCount === 0 || columnCount === 0) return undefined;
+
+  const extend = event.shiftKey;
+  const isCommand = event.ctrlKey || event.metaKey;
+
+  if (isCommand && event.key.toLowerCase() === 'a') return { type: 'select-all' };
+  if (isCommand && event.key.toLowerCase() === 'c') return { type: 'copy-selection' };
+  if (event.key === 'Escape') return { type: 'collapse-selection' };
+  if (event.key === 'Enter' || event.key === ' ') return { type: 'select-active-cell' };
+
+  if (event.key === 'ArrowRight') {
+    return {
+      type: 'move-cell',
+      rowIndex: activeRowIndex,
+      columnIndex: activeColumnIndex + 1,
+      extend,
+    };
+  }
+
+  if (event.key === 'ArrowLeft') {
+    return {
+      type: 'move-cell',
+      rowIndex: activeRowIndex,
+      columnIndex: activeColumnIndex - 1,
+      extend,
+    };
+  }
+
+  if (event.key === 'ArrowDown') {
+    return {
+      type: 'move-cell',
+      rowIndex: activeRowIndex + 1,
+      columnIndex: activeColumnIndex,
+      extend,
+    };
+  }
+
+  if (event.key === 'ArrowUp') {
+    return {
+      type: 'move-cell',
+      rowIndex: activeRowIndex - 1,
+      columnIndex: activeColumnIndex,
+      extend,
+    };
+  }
+
+  if (event.key === 'Home') {
+    return {
+      type: 'move-cell',
+      rowIndex: isCommand ? 0 : activeRowIndex,
+      columnIndex: 0,
+      extend,
+    };
+  }
+
+  if (event.key === 'End') {
+    return {
+      type: 'move-cell',
+      rowIndex: isCommand ? rowCount - 1 : activeRowIndex,
+      columnIndex: columnCount - 1,
+      extend,
+    };
+  }
+
+  if (event.key === 'PageDown') {
+    return {
+      type: 'move-cell',
+      rowIndex: activeRowIndex + pageSize,
+      columnIndex: activeColumnIndex,
+      extend,
+    };
+  }
+
+  if (event.key === 'PageUp') {
+    return {
+      type: 'move-cell',
+      rowIndex: activeRowIndex - pageSize,
+      columnIndex: activeColumnIndex,
+      extend,
+    };
+  }
+
+  if (event.key === 'Tab') {
+    const direction = event.shiftKey ? -1 : 1;
+    const nextCellIndex = activeRowIndex * columnCount + activeColumnIndex + direction;
+    const lastCellIndex = rowCount * columnCount - 1;
+    if (nextCellIndex < 0 || nextCellIndex > lastCellIndex) return undefined;
+
+    return {
+      type: 'move-cell',
+      rowIndex: Math.floor(nextCellIndex / columnCount),
+      columnIndex: nextCellIndex % columnCount,
+      extend: false,
+    };
+  }
+
+  return undefined;
+}