@lostgradient/cinder 0.2.0 → 0.3.0

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

@@ -0,0 +1,118 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type DataGridDensity = 'compact' | 'comfortable' | 'spacious';
+export type DataGridColumnPin = 'left' | 'right';
+export type DataGridSelectionMode = 'none' | 'single' | 'multiple';
+export type DataGridSortDirection = 'ascending' | 'descending';
+
+export type DataGridSortModelItem = {
+  key: string;
+  direction: DataGridSortDirection;
+};
+
+export type DataGridSortModel = readonly DataGridSortModelItem[];
+
+export type DataGridSortComparator<TRow, TValue = unknown> = {
+  bivarianceHack(leftValue: TValue, rightValue: TValue, leftRow: TRow, rightRow: TRow): number;
+}['bivarianceHack'];
+
+export type DataGridCellContext<TRow, TValue = unknown> = {
+  row: TRow;
+  value: TValue;
+  editing: boolean;
+};
+
+type DataGridBaseColumnDef<TRow> = {
+  /**
+   * Stable column identity used for ARIA cell ids and column state.
+   */
+  key: string;
+  /** Header content rendered in the columnheader cell. */
+  header: string | Snippet;
+  /**
+   * Custom body cell renderer. The `editing` flag is currently always false
+   * because DataGrid renders read-only cells.
+   */
+  cell?: Snippet<[DataGridCellContext<TRow>]>;
+  /** Initial pixel width. Defaults to 150. */
+  width?: number;
+  /** Minimum pixel width used by sizing resolution. Defaults to 60. */
+  minWidth?: number;
+  /** Maximum pixel width used by sizing resolution. */
+  maxWidth?: number;
+  /** Pin this column to the left or right edge of the horizontal scroller. */
+  pin?: DataGridColumnPin;
+  /** Enables header-click sorting for this column. */
+  sortable?: boolean;
+};
+
+type DataGridSortableColumnDef<TRow, TValue> = DataGridBaseColumnDef<TRow> & {
+  /** Custom comparator for this column. Receives cell values and their source rows. */
+  sortComparator?: DataGridSortComparator<TRow, TValue>;
+};
+
+export type DataGridColumnDef<TRow = Record<string, unknown>> =
+  | {
+      [TKey in Extract<keyof TRow, string>]: DataGridSortableColumnDef<TRow, TRow[TKey]> & {
+        key: TKey;
+        /** Reads a value from the row. Defaults to object-key access by `column.key`. */
+        getValue?: (row: TRow) => TRow[TKey];
+      };
+    }[Extract<keyof TRow, string>]
+  | (DataGridSortableColumnDef<TRow, unknown> & {
+      key: string;
+      /** Required for computed columns whose key is not a row property. */
+      getValue: (row: TRow) => unknown;
+    });
+
+export type DataGridColumnSizing = Record<string, number>;
+
+export type DataGridColumnPinning = {
+  left?: readonly string[];
+  right?: readonly string[];
+};
+
+export type DataGridSelectionModel = readonly string[];
+
+export type DataGridProps<TRow = Record<string, unknown>> = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'role'
+> & {
+  rows: readonly TRow[];
+  columns: readonly DataGridColumnDef<TRow>[];
+  /** Stable row identity used for ARIA ids and row-scoped state. */
+  getRowId: (row: TRow) => string;
+  /** Controls body row padding density. Defaults to `'comfortable'`. */
+  density?: DataGridDensity;
+  /** Keeps the column header row pinned to the top edge while scrolling. Defaults to `true`. */
+  stickyHeader?: boolean;
+  /** Enables fixed-height row virtualization. */
+  virtualizeRows?: boolean;
+  /** Enables LTR horizontal virtualization for unpinned columns. Pinned columns stay rendered. */
+  virtualizeColumns?: boolean;
+  /** Fixed body-row pixel height used by row virtualization. Defaults to 44 when omitted or invalid. */
+  rowHeight?: number;
+  /** Applies a supplied column order. */
+  columnOrder?: readonly string[];
+  /** Overrides resolved column widths by column key. */
+  columnSizing?: DataGridColumnSizing;
+  /** Pins supplied column keys to the left or right edge. */
+  columnPinning?: DataGridColumnPinning;
+  /** Controls row-selection behavior. Cell focus and range selection remain available. */
+  selectionMode?: DataGridSelectionMode;
+  /** Controlled row-selection ids, keyed by `getRowId`. */
+  selectionModel?: DataGridSelectionModel | undefined;
+  /** Called when row selection changes through cell interaction. */
+  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;
+  /** Additional class names merged onto the root grid. */
+  class?: string;
+  /** Additional class names for body rows. */
+  rowClass?: string | ((row: TRow, rowIndex: number) => string | undefined);
+  /** Optional accessible row label for screen-reader row summaries. */
+  getRowAriaLabel?: (row: TRow, rowIndex: number) => string | undefined;
+};

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

@@ -0,0 +1,16 @@
+import './data-grid.css';
+import DataGrid from './data-grid.svelte';
+
+export default DataGrid;
+export type {
+  DataGridCellContext,
+  DataGridColumnDef,
+  DataGridColumnPin,
+  DataGridColumnPinning,
+  DataGridColumnSizing,
+  DataGridDensity,
+  DataGridProps,
+  DataGridSelectionMode,
+  DataGridSelectionModel,
+} from './data-grid.types.ts';
+export { DataGrid };

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

@@ -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       | —       |                                                                                                                                                                                                                                                                                                                                                                       |
-| `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)`                       | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                            |
-| `empty`    | `(opaque)`                       | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                            |
-| `items`    | `(opaque)`                       | no       | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                              |
-| `key`      | `(opaque)`                       | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                            |
+| Prop       | Type                             | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ---------- | -------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`                         | no       | —       | Additional class 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. |
 
 <!-- generated:props:end -->
 

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

@@ -37,6 +37,7 @@ export type DataListProps<T> = Omit<
    * `{...(density ? { density } : {})}`
    */
   density?: StackedListItemDensity;
+  /** Additional class merged onto the `.cinder-data-list` root element. */
   class?: string;
   /**
    * Row renderer. MUST render an `<li>` (the list root is a `<ul role="list">`).

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

@@ -23,6 +23,13 @@ Data-driven accessible table that renders rows and columns into a real `<table>`
 
 ## Guidance
 
+Set `virtualized` with a fixed `rowHeight` when the table is rendering thousands
+of same-height append-only rows. The virtualized path keeps the `<table>`,
+`<thead>`, and `<tbody>` semantics intact, sets `aria-rowcount` to the full
+logical row count, and annotates mounted body rows with full-table
+`aria-rowindex` values. Variable or measured body row heights are out of scope
+for this mode.
+
 ### Use When
 
 - Rendering a roster, cohort, or assignment view from row/column data with real table semantics.
@@ -37,16 +44,21 @@ Data-driven accessible table that renders rows and columns into a real `<table>`
 
 <!-- generated:props:start -->
 
-| Prop           | Type                                             | Required | Default | Description                                                                                                                                                                                                            |
-| -------------- | ------------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `caption`      | `string`                                         | no       | —       | Visual caption rendered as a `<caption>` element above the table.                                                                                                                                                      |
-| `class`        | `string`                                         | no       | —       | Additional class names merged onto DataTable's root wrapper element (the `<div class="cinder-data-table">` that contains the table). To style the `<table>` itself, target `.cinder-data-table table` from this class. |
-| `density`      | `"comfortable"` \| `"condensed"` \| `"spacious"` | no       | —       | Vertical padding density for header and body cells. Defaults to `'comfortable'`.                                                                                                                                       |
-| `scrollable`   | `boolean`                                        | no       | —       | When true, wraps the table in a `.cinder-table-scroll` container that enables horizontal overflow scrolling on small viewports.                                                                                        |
-| `stickyHeader` | `boolean`                                        | no       | —       | When true, the header sticks to the top of the scrolling container.                                                                                                                                                    |
-| `columns`      | `(opaque)`                                       | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                |
-| `rows`         | `(opaque)`                                       | no       | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                               |
-| `sort`         | `(opaque)`                                       | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                |
+| 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. |
 
 <!-- generated:props:end -->
 
@@ -54,8 +66,7 @@ Data-driven accessible table that renders rows and columns into a real `<table>`
 
 <!-- generated:variables:start -->
 
-This component does not declare any local CSS variables.
-
+- `--cinder-data-table-height`
 <!-- generated:variables:end -->
 
 ## Subcomponents

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

@@ -27,4 +27,29 @@
   .cinder-data-table.cinder-table-scroll {
     display: block;
   }
+
+  .cinder-data-table[data-cinder-virtualized] {
+    --cinder-data-table-height: 24rem;
+
+    block-size: var(--cinder-data-table-height, 24rem);
+    overflow: auto;
+    overscroll-behavior: contain;
+    -webkit-overflow-scrolling: touch;
+    contain: layout paint;
+  }
+
+  .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[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);
+  }
+
+  .cinder-data-table__virtual-spacer-cell {
+    padding: 0;
+    border: 0;
+  }
 }

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

@@ -14,6 +14,12 @@
       "title": "Sortable data table",
       "description": "Multiple sortable columns with a scrollable wrapper. Sort state is bound and rows are reordered via $derived.",
       "code": "<script lang=\"ts\">\n  import { DataTable } from '@lostgradient/cinder/data-table';\n  import type { TableSort } from '@lostgradient/cinder/table';\n\n  type Contributor = {\n    name: string;\n    role: string;\n    commits: number;\n    reviews: number;\n  };\n\n  const contributors: Contributor[] = [\n    { name: 'Ada Lovelace', role: 'Mathematician', commits: 142, reviews: 34 },\n    { name: 'Grace Hopper', role: 'Computer Scientist', commits: 98, reviews: 41 },\n    { name: 'Alan Turing', role: 'Cryptanalyst', commits: 76, reviews: 28 },\n    { name: 'Margaret Hamilton', role: 'Software Engineer', commits: 304, reviews: 87 },\n    { name: 'Linus Torvalds', role: 'Systems Engineer', commits: 512, reviews: 19 },\n    { name: 'Dennis Ritchie', role: 'Language Designer', commits: 231, reviews: 55 },\n  ];\n\n  const columns = [\n    { key: 'name' as const, label: 'Name', sortable: true, rowHeader: true },\n    { key: 'role' as const, label: 'Role', sortable: true },\n    { key: 'commits' as const, label: 'Commits', sortable: true, align: 'end' as const },\n    { key: 'reviews' as const, label: 'Reviews', sortable: true, align: 'end' as const },\n  ];\n\n  let sort: TableSort | undefined = $state();\n\n  const sortedContributors = $derived.by(() => {\n    if (!sort) return contributors;\n    return [...contributors].sort((a, b) => {\n      const key = sort!.column as keyof Contributor;\n      const aValue = a[key];\n      const bValue = b[key];\n      const comparison =\n        typeof aValue === 'number' && typeof bValue === 'number'\n          ? aValue - bValue\n          : String(aValue).localeCompare(String(bValue));\n      return sort!.direction === 'ascending' ? comparison : -comparison;\n    });\n  });\n</script>\n\n<DataTable caption=\"Top contributors\" {columns} rows={sortedContributors} bind:sort scrollable />\n"
+    },
+    {
+      "id": "virtualized",
+      "title": "Virtualized data table",
+      "description": "A semantic table that windows 10,000 fixed-height body rows while preserving full row counts and row indexes.",
+      "code": "<script lang=\"ts\">\n  import { DataTable } from '@lostgradient/cinder/data-table';\n\n  type LogRow = {\n    event: string;\n    source: string;\n    severity: 'Info' | 'Warn' | 'Error';\n    message: string;\n  };\n\n  const severities: LogRow['severity'][] = ['Info', 'Warn', 'Error'];\n  const rows: LogRow[] = Array.from({ length: 10_000 }, (_, index) => ({\n    event: `evt-${index.toString().padStart(5, '0')}`,\n    source: `worker-${index % 16}`,\n    severity: severities[index % severities.length] ?? 'Info',\n    message: `Handled append-only log row ${index.toLocaleString('en-US')}`,\n  }));\n\n  const columns = [\n    { key: 'event' as const, label: 'Event', rowHeader: true },\n    { key: 'source' as const, label: 'Source' },\n    { key: 'severity' as const, label: 'Severity' },\n    { key: 'message' as const, label: 'Message' },\n  ];\n</script>\n\n<DataTable\n  caption=\"Workflow log tail\"\n  {columns}\n  {rows}\n  virtualized\n  density=\"condensed\"\n  rowHeight={36}\n  height=\"360px\"\n  overscan={4}\n  scrollable\n/>\n"
     }
   ]
 }