@joewinke/jatui 0.25.0 → 0.26.0

package/CLAUDE.md

@@ -59,7 +59,7 @@ Then import:
 | `Badge` | Status/label badge | `variant`, `size`, `children` (snippet) |
 | `StatusBadge` | Status indicator with dot | `status: StatusValue`, `label` |
 | `Card` | Content card container | `title`, `children` (snippet) |
-| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number` |
+| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. **Escape is owned by the dialog element itself** (not the window handler) — Modal focuses the dialog on open, so `trapKeys`' stopPropagation would otherwise swallow Esc before the window listener sees it; a Modal opened inside a host Drawer closes before the drawer. The component ships its own open-state `.modal-box` opacity rule, so it renders under DaisyUI 5 with no host global override. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number`, `trapKeys?`, `closeOnEscape?` |
 | `ConfirmModal` | Yes/no confirmation dialog | `open` (bindable), `title`, `message`, `onConfirm`, `onCancel` |
 | `Drawer` | Slide-out side panel | `open` (bindable), `side`, `children` (snippet) |
 | `LoadingSpinner` | Spinner animation | `size`, `color` |
@@ -76,6 +76,14 @@ Then import:
 | `QuotaMeter` | "312 / 500 credits · resets in 4h 10m" bar — warning tint at `warnAt`, error at 100%. Presentational; the host owns the ledger. | `used`, `limit`, `resetsAt?`, `label?`, `unit?`, `warnAt?` (0.8), `size?` |
 | `VariantMatrixPicker` | Category/option chip grid for building a combinatorial variant matrix (harvested from vid-gen's FrameVariantGenerator, presets stripped — caller-supplied `categories`). Each category tab shows a live selection count and an additive/multiplicative badge: multiplicative selections cartesian-multiply the total, additive ones stack flat onto every combination. Live combination count in the footer; algebra exported separately as pure functions (`generateCombinations`, `countCombinations`, `variantCategoryMode`, `findVariantOption`, `generateVariantFilename`). | `categories: VariantCategory[]`, `selected` (bindable `VariantSelection`), `forceMode?`, `showCount?` (true), `countLabel?`, `onChange?`, `class?` |
 
+### Tables (subpath: `jatui/table`)
+
+Requires peer `@tanstack/table-core`. `import { DataTable, flexRender, columnResize } from 'jatui/table'`.
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `DataTable` | TanStack-backed table (generic over the row type): sorting, selection, client pagination, skeleton. Grid-mode hooks per jat `docs/design/datatable-virtualisation-group-rows.md` §3.3: `getRowId` (keys selection/expansion/api by id, renders `data-row-id`); controlled sort — `bind:sorting`, `initialSorting`, `manualSorting` (caller pre-sorts `data`), `onSortingChange(next, {field, shiftKey})`; `rowProps(row, item)` → `{class, attrs, onclick, oncontextmenu, ondragover, ondrop}` (`attrs` for `data-nav-id`, aria); `onRowClick(row, e)` (skips clicks on interactive children); `headerProps(columnId)`; `expandedRow` snippet `(row, {colspan})` — click/Enter toggles unless `isExpanded(row)` makes it controlled; `empty` snippet; `variant` `zebra`/`plain`/`unstyled` + `tableClass`; `bind:api` → `orderedRowIds()`, `scrollToRow(id)`. Sortable headers are keyboard-operable. | `data`, `columns`, `sortable`, `selectable`, `paginated`, `getRowId?`, `sorting?` (bindable), `rowProps?`, `onRowClick?`, `expandedRow?`, `empty?`, `variant?`, `api?` (bindable) |
+
 ### Media
 
 | Component | Purpose | Key Props |
@@ -244,7 +252,7 @@ const callbacks: AnnotationCallbacks = {
 <KeyboardShortcutsOverlay registry={shortcuts} />
 ```
 
-**Sidebar convention: `SIDEBAR_TOGGLE_KEY` = `mod+\`** (Ctrl+\ / ⌘\). Do NOT use Ctrl+B: Chrome reserves it (bookmarks bar). Also avoid Ctrl+T/W/N, which the browser keeps. The overlay owns `?`, so don't register it. Helpers: `formatShortcut(def | "mod+k", platform?)` → `⌘K` / `Ctrl+K`, `isTypingTarget(el)`, `parseShortcutCombo`, `detectShortcutPlatform`.
+**Sidebar convention: `SIDEBAR_TOGGLE_KEY` = `mod+\`** (Ctrl+\ / ⌘\). Do NOT use Ctrl+B: Chrome reserves it (bookmarks bar). Also avoid Ctrl+T/W/N, which the browser keeps. The overlay owns `?` by default, so don't register it — but if a host app already has its own global `?` handler registered first, the overlay respects `event.defaultPrevented` and stays out of the way (one overlay per keypress). Helpers: `formatShortcut(def | "mod+k", platform?)` → `⌘K` / `Ctrl+K`, `isTypingTarget(el)`, `parseShortcutCombo`, `detectShortcutPlatform`.
 
 ### Maps (Google Maps)
 

package/dist/components/KeyboardShortcutsOverlay.svelte

@@ -133,6 +133,11 @@
 	}
 
 	function onKeydown(e: KeyboardEvent) {
+		// Another listener already claimed this keypress (host app's own '?'
+		// handler, an open modal, …) — bail so one keypress can't toggle two
+		// overlays at once. Covers the '?' and Escape branches alike.
+		if (e.defaultPrevented) return;
+
 		if (e.ctrlKey || e.metaKey || e.altKey) return;
 
 		if (e.key === '?') {

package/dist/components/Modal.svelte

@@ -124,6 +124,21 @@
 	}
 
 	function handleKeyDown(event: KeyboardEvent) {
+		// Escape is owned HERE on the dialog element, not by <svelte:window>.
+		// Modal focuses the dialog (tabindex=-1) on open, so in the default state
+		// keydown dispatches from the dialog itself — and the trapKeys
+		// stopPropagation below (which under Svelte 5 delegated events also
+		// blocks every window listener) would swallow Escape before the window
+		// handler could act: Esc did nothing unless focus was in a text field.
+		// Handling it at element level also guarantees a Modal opened inside a
+		// host Drawer closes before the drawer does.
+		if (open && event.key === 'Escape' && closeOnEscape) {
+			event.preventDefault();
+			event.stopPropagation();
+			close();
+			return;
+		}
+
 		// Stop keydown events from bubbling to window while the modal is open.
 		// This prevents page-level keyboard navigation (listNav-style handlers
 		// on window) from reacting to arrow keys, j/k, vim chords, digit counts,
@@ -247,4 +262,21 @@
 		align-items: center;
 		justify-content: center;
 	}
+
+	/*
+	 * DaisyUI 5 puts .modal-box at opacity:0 (layer daisyui.l1.l2.l3) and only
+	 * restores it from `.modal[open] .modal-box { opacity: 1 }` in the outer
+	 * layer — a rule that assumes daisyUI's canonical markup where the box is a
+	 * direct grid child of the dialog. jatui nests the box inside
+	 * .modal-backdrop, and the restore rule loses the cascade: the panel stays
+	 * invisible unless the host adds a global override (the jat IDE had to in
+	 * app.css, jat-vte6e.17). Un-layered author styles beat @layer rules, so
+	 * declaring the open state here makes the component render correctly on
+	 * its own. Entrance motion stays owned by the in:fly transition on the box.
+	 */
+	:global(dialog.modal[open] .modal-box) {
+		opacity: 1;
+		translate: 0;
+		scale: 1;
+	}
 </style>

package/dist/components/table/DataTable.svelte

@@ -1,4 +1,5 @@
-<script lang="ts">
+<script lang="ts" generics="TData">
+	import { tick } from 'svelte';
 	import {
 		createTable,
 		getCoreRowModel,
@@ -9,12 +10,10 @@
 		type RowSelectionState,
 		type PaginationState,
 		type TableOptionsResolved,
+		type Row,
 	} from '@tanstack/table-core';
 	import { flexRender } from './flexRender.js';
-	import type { DataTableProps } from './types.js';
-
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	type AnyData = any;
+	import type { DataTableProps, DataTableRowProps, DataTableSortEvent, GroupedItem } from './types.js';
 
 	let {
 		data,
@@ -27,13 +26,36 @@
 		loadingRows = 5,
 		onSelectionChange,
 		class: className = '',
-	}: DataTableProps = $props();
+		getRowId,
+		sorting = $bindable(),
+		initialSorting,
+		manualSorting = false,
+		onSortingChange,
+		rowProps,
+		onRowClick,
+		headerProps,
+		expandedRow,
+		isExpanded,
+		empty,
+		variant = 'zebra',
+		tableClass = '',
+		api = $bindable(),
+	}: DataTableProps<TData> = $props();
 
 	// ── State ──────────────────────────────────────────────────────────────
-	let sorting = $state<SortingState>([]);
+	// `sorting` is bindable: bound, the caller owns it; unbound, it is local
+	// state seeded from `initialSorting`.
+	// svelte-ignore state_referenced_locally
+	if (sorting === undefined) sorting = initialSorting ?? [];
+	const sortState = $derived<SortingState>(sorting ?? []);
 	let rowSelection = $state<RowSelectionState>({});
 	// svelte-ignore state_referenced_locally
 	let pagination = $state<PaginationState>({ pageIndex: 0, pageSize });
+	/** Internally-owned expansion (only used when `isExpanded` is not supplied). */
+	let expandedIds = $state<Set<string>>(new Set());
+	/** The header click that triggered the sort change currently in flight. */
+	let pendingSortEvent: DataTableSortEvent | null = null;
+	let rootEl: HTMLDivElement | undefined = $state();
 
 	// Reset to the first page whenever the data set changes.
 	//
@@ -50,7 +72,7 @@
 		pagination = { pageIndex: 0, pageSize };
 	});
 
-	const checkboxCol: ColumnDef<AnyData, unknown> = {
+	const checkboxCol: ColumnDef<TData, unknown> = {
 		id: '__select',
 		header: () => null,
 		cell: () => null,
@@ -58,24 +80,26 @@
 		size: 40,
 	};
 
-	const allColumns = $derived<ColumnDef<AnyData, unknown>[]>(
-		selectable ? [checkboxCol, ...(columns as ColumnDef<AnyData, unknown>[])] : (columns as ColumnDef<AnyData, unknown>[])
-	);
+	const allColumns = $derived<ColumnDef<TData, unknown>[]>(selectable ? [checkboxCol, ...columns] : columns);
 
 	// ── Table instance ─────────────────────────────────────────────────────
 	const table = $derived.by(() => {
-		const opts: TableOptionsResolved<AnyData> = {
+		const opts: TableOptionsResolved<TData> = {
 			data,
 			columns: allColumns,
 			state: {
-				sorting,
+				sorting: sortState,
 				rowSelection,
 				...(paginated ? { pagination } : {}),
 			},
+			getRowId: getRowId ? (row: TData) => getRowId(row) : undefined,
 			enableRowSelection: selectable,
 			enableSorting: sortable,
+			manualSorting,
 			onSortingChange: (updater) => {
-				sorting = typeof updater === 'function' ? updater(sorting) : updater;
+				const next = typeof updater === 'function' ? updater(sortState) : updater;
+				sorting = next;
+				onSortingChange?.(next, pendingSortEvent ?? { field: next[0]?.id ?? '', shiftKey: false });
 			},
 			onRowSelectionChange: (updater) => {
 				rowSelection = typeof updater === 'function' ? updater(rowSelection) : updater;
@@ -87,7 +111,7 @@
 				: () => {},
 			onStateChange: () => {},
 			getCoreRowModel: getCoreRowModel(),
-			getSortedRowModel: sortable ? getSortedRowModel() : undefined,
+			getSortedRowModel: sortable && !manualSorting ? getSortedRowModel() : undefined,
 			getPaginationRowModel: paginated ? getPaginationRowModel() : undefined,
 			renderFallbackValue: '',
 		};
@@ -109,30 +133,128 @@
 	const canPrevPage = $derived(table.getCanPreviousPage());
 	const canNextPage = $derived(table.getCanNextPage());
 
+	const tableClasses = $derived(
+		[variant === 'unstyled' ? '' : variant === 'plain' ? 'table' : 'table table-zebra', 'w-full', tableClass]
+			.filter(Boolean)
+			.join(' ')
+	);
+
+	/** The table owns expansion: a row click / Enter / Space toggles the detail row. */
+	const internalExpand = $derived(!!expandedRow && !isExpanded);
+
 	$effect(() => {
 		if (!selectable || !onSelectionChange) return;
-		const selected = table.getSelectedRowModel().rows.map((r: AnyData) => r.original);
+		const selected = table.getSelectedRowModel().rows.map((r) => r.original);
 		onSelectionChange(selected);
 	});
 
+	// ── Imperative api ─────────────────────────────────────────────────────
+	api = {
+		orderedRowIds: () => table.getPrePaginationRowModel().rows.map((r) => r.id),
+		scrollToRow: async (id, align = 'auto') => {
+			if (paginated) {
+				const index = table.getPrePaginationRowModel().rows.findIndex((r) => r.id === id);
+				if (index < 0) return;
+				const pageIndex = Math.floor(index / pagination.pageSize);
+				if (pageIndex !== pagination.pageIndex) {
+					pagination = { ...pagination, pageIndex };
+					await tick();
+				}
+			}
+			const el = rootEl?.querySelector<HTMLElement>(`tr[data-row-id="${CSS.escape(id)}"]`);
+			el?.scrollIntoView({ block: align === 'auto' ? 'nearest' : align });
+		},
+	};
+
 	function sortDir(headerId: string): 'asc' | 'desc' | false {
-		const s = sorting.find((item) => item.id === headerId);
+		const s = sortState.find((item) => item.id === headerId);
 		return s ? (s.desc ? 'desc' : 'asc') : false;
 	}
 
-	function renderHeader(header: ReturnType<typeof table.getHeaderGroups>[0]['headers'][0]) {
+	type AnyHeader = ReturnType<typeof table.getHeaderGroups>[0]['headers'][0];
+
+	function toggleSort(header: AnyHeader, e: MouseEvent | KeyboardEvent) {
+		pendingSortEvent = { field: header.column.id, shiftKey: e.shiftKey };
+		try {
+			header.column.getToggleSortingHandler()?.(e);
+		} finally {
+			pendingSortEvent = null;
+		}
+	}
+
+	function onHeaderKeydown(header: AnyHeader, e: KeyboardEvent) {
+		if (e.key !== 'Enter' && e.key !== ' ') return;
+		e.preventDefault();
+		toggleSort(header, e);
+	}
+
+	function renderHeader(header: AnyHeader) {
 		return flexRender(header.column.columnDef.header, header.getContext());
 	}
 
-	function renderCell(cell: ReturnType<ReturnType<typeof table.getRowModel>['rows'][0]['getVisibleCells']>[0]) {
+	function renderCell(cell: ReturnType<Row<TData>['getVisibleCells']>[0]) {
 		return flexRender(cell.column.columnDef.cell, cell.getContext());
 	}
+
+	// ── Row helpers ────────────────────────────────────────────────────────
+	function rowItem(row: Row<TData>, index: number, count: number): GroupedItem<TData> {
+		const position = count === 1 ? 'only' : index === 0 ? 'first' : index === count - 1 ? 'last' : 'middle';
+		return { kind: 'row', row: row.original, id: row.id, depth: 0, groupPath: [], position };
+	}
+
+	function rowIsExpanded(row: Row<TData>): boolean {
+		if (!expandedRow) return false;
+		return isExpanded ? isExpanded(row.original) : expandedIds.has(row.id);
+	}
+
+	function toggleExpanded(id: string) {
+		const next = new Set(expandedIds);
+		if (next.has(id)) next.delete(id);
+		else next.add(id);
+		expandedIds = next;
+	}
+
+	/** Clicks on these inside a row belong to the control, not to the row. */
+	const INTERACTIVE = 'input, button, a, select, textarea, label, [contenteditable]:not([contenteditable="false"])';
+
+	function isInteractiveTarget(e: Event): boolean {
+		const target = e.target as Element | null;
+		const tr = e.currentTarget as Element;
+		const hit = target?.closest?.(INTERACTIVE);
+		return !!hit && hit !== tr && tr.contains(hit);
+	}
+
+	function onRowClickInternal(row: Row<TData>, rp: DataTableRowProps, e: MouseEvent) {
+		if (isInteractiveTarget(e)) return;
+		rp.onclick?.(e);
+		onRowClick?.(row.original, e);
+		if (internalExpand) toggleExpanded(row.id);
+	}
+
+	function onRowKeydown(row: Row<TData>, e: KeyboardEvent) {
+		if (!internalExpand || e.target !== e.currentTarget) return;
+		if (e.key !== 'Enter' && e.key !== ' ') return;
+		e.preventDefault();
+		toggleExpanded(row.id);
+	}
+
+	/** Normalise `rowProps().attrs`: booleans become `""`/omitted (aria-* stay "true"/"false"). */
+	function rowAttrs(rp: DataTableRowProps): Record<string, string | number | undefined> {
+		const out: Record<string, string | number | undefined> = {};
+		for (const [k, v] of Object.entries(rp.attrs ?? {})) {
+			if (typeof v === 'boolean') out[k] = k.startsWith('aria-') ? String(v) : v ? '' : undefined;
+			else out[k] = v;
+		}
+		return out;
+	}
+
+	const hasRowHandlers = $derived(!!rowProps || !!onRowClick || internalExpand);
 </script>
 
-<div class="datatable-root {className}">
+<div class="datatable-root {className}" bind:this={rootEl}>
 	{#if loading}
 		<div class="overflow-x-auto">
-			<table class="table table-zebra w-full">
+			<table class={tableClasses}>
 				<thead>
 					<tr>
 						{#each allColumns as _}
@@ -155,7 +277,7 @@
 		</div>
 	{:else}
 		<div class="overflow-x-auto">
-			<table class="table table-zebra w-full">
+			<table class={tableClasses}>
 				<thead>
 					{#each headerGroups as headerGroup}
 						<tr>
@@ -175,10 +297,15 @@
 									{@const isSortable = sortable && header.column.getCanSort()}
 									{@const dir = sortDir(header.column.id)}
 									{@const rendered = renderHeader(header)}
+									{@const hp = headerProps?.(header.column.id)}
 									<th
 										style:width={header.getSize() !== 150 ? `${header.getSize()}px` : undefined}
+										class={hp?.class}
 										class:dt-th-sortable={isSortable}
-										onclick={isSortable ? () => header.column.toggleSorting() : undefined}
+										tabindex={isSortable ? 0 : undefined}
+										onclick={isSortable ? (e) => toggleSort(header, e) : undefined}
+										onkeydown={isSortable ? (e) => onHeaderKeydown(header, e) : undefined}
+										oncontextmenu={hp?.oncontextmenu}
 										aria-sort={dir === 'asc' ? 'ascending' : dir === 'desc' ? 'descending' : undefined}
 									>
 										<span class="dt-th-label">
@@ -212,11 +339,33 @@
 				<tbody>
 					{#if rows.length === 0}
 						<tr>
-							<td colspan={allColumns.length} class="dt-empty">No data</td>
+							{#if empty}
+								<td colspan={allColumns.length} class="dt-empty-custom">{@render empty()}</td>
+							{:else}
+								<td colspan={allColumns.length} class="dt-empty">No data</td>
+							{/if}
 						</tr>
 					{:else}
-						{#each rows as row}
-							<tr class:dt-row-selected={row.getIsSelected()}>
+						{#each rows as row, ri (row.id)}
+							{@const rp = rowProps?.(row.original, rowItem(row, ri, rows.length)) ?? {}}
+							{@const attrs = rowAttrs(rp)}
+							{@const expanded = rowIsExpanded(row)}
+							<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+							<tr
+								{...attrs}
+								class={rp.class}
+								class:dt-row-selected={row.getIsSelected()}
+								class:dt-row-clickable={!!rp.onclick || !!onRowClick || internalExpand}
+								class:dt-row-expanded={expanded}
+								data-row-id={getRowId ? row.id : undefined}
+								aria-expanded={expandedRow ? expanded : undefined}
+								tabindex={internalExpand ? (attrs.tabindex ?? 0) : attrs.tabindex}
+								onclick={hasRowHandlers ? (e) => onRowClickInternal(row, rp, e) : undefined}
+								onkeydown={internalExpand ? (e) => onRowKeydown(row, e) : undefined}
+								oncontextmenu={rp.oncontextmenu}
+								ondragover={rp.ondragover}
+								ondrop={rp.ondrop}
+							>
 								{#each row.getVisibleCells() as cell}
 									{#if cell.column.id === '__select'}
 										<td class="dt-select-cell">
@@ -241,12 +390,16 @@
 									{/if}
 								{/each}
 							</tr>
+							{#if expanded && expandedRow}
+								<tr class="dt-expanded-detail" data-detail-for={getRowId ? row.id : undefined}>
+									<td colspan={allColumns.length}>{@render expandedRow(row.original, { colspan: allColumns.length })}</td>
+								</tr>
+							{/if}
 						{/each}
 					{/if}
 				</tbody>
 			</table>
 		</div>
-
 		{#if paginated && pageCount > 1}
 			<div class="dt-pagination">
 				<span class="dt-page-info">
@@ -327,6 +480,14 @@
 		background-color: color-mix(in oklch, var(--color-primary) 6%, transparent) !important;
 	}
 
+	.dt-row-clickable {
+		cursor: pointer;
+	}
+	.dt-row-clickable:focus-visible {
+		outline: 2px solid var(--color-primary);
+		outline-offset: -2px;
+	}
+
 	.dt-select-cell {
 		width: 2.5rem;
 		text-align: center;

package/dist/components/table/DataTable.svelte.d.ts

@@ -1,4 +1,25 @@
 import type { DataTableProps } from './types.js';
-declare const DataTable: import("svelte").Component<DataTableProps<any>, {}, "">;
-type DataTable = ReturnType<typeof DataTable>;
+declare function $$render<TData>(): {
+    props: DataTableProps<TData>;
+    exports: {};
+    bindings: "sorting" | "api";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TData> {
+    props(): ReturnType<typeof $$render<TData>>['props'];
+    events(): ReturnType<typeof $$render<TData>>['events'];
+    slots(): ReturnType<typeof $$render<TData>>['slots'];
+    bindings(): "sorting" | "api";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <TData>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const DataTable: $$IsomorphicComponent;
+type DataTable<TData> = InstanceType<typeof DataTable<TData>>;
 export default DataTable;

package/dist/components/table/index.d.ts

@@ -2,4 +2,4 @@ export { default as DataTable } from './DataTable.svelte';
 export { flexRender } from './flexRender';
 export { columnResize } from './columnResize';
 export type { ColumnResizeOptions } from './columnResize';
-export type { DataTableProps, SelectionEvent, ColumnDef, Row } from './types';
+export type { DataTableProps, DataTableApi, DataTableRowProps, DataTableHeaderProps, DataTableSortEvent, DataTableVariant, GroupedItem, SelectionEvent, ColumnDef, Row, SortingState } from './types';

package/dist/components/table/types.d.ts

@@ -1,5 +1,63 @@
-import type { ColumnDef, Row } from '@tanstack/table-core';
-export type { ColumnDef, Row };
+import type { Snippet } from 'svelte';
+import type { ColumnDef, Row, SortingState } from '@tanstack/table-core';
+export type { ColumnDef, Row, SortingState };
+/**
+ * One entry in the table's render list. Today DataTable renders flat rows, so
+ * every item is `kind: 'row'` with `depth: 0`; the `group` variant is the shape
+ * the grouped render list (`groupRows`, design doc
+ * jat/docs/design/datatable-virtualisation-group-rows.md §3.2) will produce, so
+ * `rowProps` callers written now keep working when grouping lands.
+ */
+export type GroupedItem<T = any> = {
+    kind: 'group';
+    key: string;
+    path: string[];
+    depth: number;
+    label: string;
+    rows: T[];
+    count: number;
+    collapsed: boolean;
+} | {
+    kind: 'row';
+    row: T;
+    id: string;
+    depth: number;
+    groupPath: string[];
+    position: 'first' | 'middle' | 'last' | 'only';
+};
+/** What `rowProps` may put on a body `<tr>`. */
+export interface DataTableRowProps {
+    class?: string;
+    /** Extra attributes (`data-*`, `aria-*`, `tabindex`…). `false` omits the attribute. */
+    attrs?: Record<string, string | number | boolean | undefined>;
+    onclick?: (e: MouseEvent) => void;
+    oncontextmenu?: (e: MouseEvent) => void;
+    ondragover?: (e: DragEvent) => void;
+    ondrop?: (e: DragEvent) => void;
+}
+/** What `headerProps` may put on a header `<th>`. */
+export interface DataTableHeaderProps {
+    class?: string;
+    oncontextmenu?: (e: MouseEvent) => void;
+}
+/** Context passed alongside a sorting change: which header, and whether it was a shift-click. */
+export interface DataTableSortEvent {
+    field: string;
+    shiftKey: boolean;
+}
+/** Imperative handle, exposed through `bind:api`. */
+export interface DataTableApi {
+    /** Scroll a row into view (jumping to its page first when paginated). */
+    scrollToRow(id: string, align?: 'auto' | 'start' | 'center'): void;
+    /** Row ids in render order across ALL pages — what keyboard nav should walk. */
+    orderedRowIds(): string[];
+}
+/**
+ * Table skin. `zebra` (default) = DaisyUI `table table-zebra`; `plain` drops the
+ * striping; `unstyled` drops the DaisyUI table classes entirely so the host's
+ * own CSS owns the look.
+ */
+export type DataTableVariant = 'zebra' | 'plain' | 'unstyled';
 export interface DataTableProps<TData = any> {
     /** Row data array */
     data: TData[];
@@ -19,8 +77,53 @@ export interface DataTableProps<TData = any> {
     loadingRows?: number;
     /** Emitted when the selection set changes */
     onSelectionChange?: (rows: TData[]) => void;
-    /** Additional table class */
+    /** Additional class on the root wrapper */
     class?: string;
+    /**
+     * Stable row identity (e.g. a task id). Keys selection, expansion and `api`
+     * by id instead of index, so a poll that reorders `data` keeps state on the
+     * right rows. Also renders `data-row-id` on each body `<tr>`.
+     */
+    getRowId?: (row: TData) => string;
+    /** Controlled sort state — `bind:sorting`. Unbound, the table owns it. */
+    sorting?: SortingState;
+    /** Starting sort state when `sorting` is not supplied (e.g. restored from localStorage). */
+    initialSorting?: SortingState;
+    /**
+     * true = DataTable does not sort; pass `data` already sorted and react to
+     * header clicks through `onSortingChange`. Headers still show the sort state.
+     */
+    manualSorting?: boolean;
+    /** Fires on every header-driven sort change — persist it here. */
+    onSortingChange?: (next: SortingState, ev: DataTableSortEvent) => void;
+    /** Per-row class / attributes / handlers for the body `<tr>`. */
+    rowProps?: (row: TData, item: GroupedItem<TData>) => DataTableRowProps;
+    /**
+     * Shorthand for `rowProps(...).onclick`. Not fired for clicks that land on an
+     * interactive child (input, button, link, select, textarea, label,
+     * contenteditable) — so the select checkbox and inline editors stay inert.
+     */
+    onRowClick?: (row: TData, e: MouseEvent) => void;
+    /** Per-column class / context-menu handler for the header `<th>`. */
+    headerProps?: (columnId: string) => DataTableHeaderProps;
+    /**
+     * Detail row rendered under an expanded row, in one full-width cell.
+     * Without `isExpanded`, the table owns expansion: a row click (or Enter /
+     * Space on the focused row) toggles it.
+     */
+    expandedRow?: Snippet<[TData, {
+        colspan: number;
+    }]>;
+    /** Controlled expansion — when given, the caller owns which rows are open. */
+    isExpanded?: (row: TData) => boolean;
+    /** Replaces the default "No data" cell when `data` is empty. */
+    empty?: Snippet;
+    /** `zebra` (default) | `plain` | `unstyled` — see DataTableVariant. */
+    variant?: DataTableVariant;
+    /** Extra class on the `<table>` element (e.g. `table-sm`). */
+    tableClass?: string;
+    /** Imperative handle — `bind:api`. */
+    api?: DataTableApi;
 }
 export interface SelectionEvent<TData> {
     rows: TData[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",