@joewinke/jatui 0.25.0 → 0.27.0

package/dist/components/table/DataTable.svelte

@@ -1,4 +1,5 @@
-<script lang="ts">
+<script lang="ts" generics="TData">
+	import { tick, untrack } from 'svelte';
 	import {
 		createTable,
 		getCoreRowModel,
@@ -9,12 +10,18 @@
 		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 { groupRows, groupPathKey, type GroupedGroupItem, type GroupedRowItem, type GroupLevel } from './groupRows.js';
+	import type {
+		DataTableProps,
+		DataTableRowProps,
+		DataTableSortEvent,
+		DataTableRenderItem,
+		DataTableRowWindow,
+		GroupedItem,
+	} from './types.js';
 
 	let {
 		data,
@@ -27,13 +34,51 @@
 		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(),
+		groupBy,
+		collapsed = $bindable(),
+		onCollapsedChange,
+		groupLabel,
+		groupHeader,
+		stickyGroupHeaders = false,
+		stickyHeader = false,
+		maxHeight,
+		virtual,
+		pinnedRowIds,
+		ariaGrid = false,
+		ariaLabel,
+	}: 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 ?? [];
+	// Same contract for the collapsed-group set.
+	// svelte-ignore state_referenced_locally
+	if (collapsed === undefined) collapsed = new Set();
+	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 +95,7 @@
 		pagination = { pageIndex: 0, pageSize };
 	});
 
-	const checkboxCol: ColumnDef<AnyData, unknown> = {
+	const checkboxCol: ColumnDef<TData, unknown> = {
 		id: '__select',
 		header: () => null,
 		cell: () => null,
@@ -58,24 +103,37 @@
 		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> = {
+	// Created ONCE; every reactive change is pushed in with `setOptions` (R6).
+	// It used to be rebuilt in a `$derived.by` on every sort / selection / data
+	// change, which threw away TanStack's memoised row models and handed the
+	// template brand-new Row objects, so every row re-rendered on every poll.
+	//
+	// Row-model factories are created once too: TanStack caches the model a
+	// factory builds on first use, so a fresh factory per update would be ignored.
+	const coreRowModel = getCoreRowModel<TData>();
+	const sortedRowModel = getSortedRowModel<TData>();
+	const paginationRowModel = getPaginationRowModel<TData>();
+
+	function buildOptions(): TableOptionsResolved<TData> {
+		return {
 			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;
@@ -86,53 +144,351 @@
 					}
 				: () => {},
 			onStateChange: () => {},
-			getCoreRowModel: getCoreRowModel(),
-			getSortedRowModel: sortable ? getSortedRowModel() : undefined,
-			getPaginationRowModel: paginated ? getPaginationRowModel() : undefined,
+			getCoreRowModel: coreRowModel,
+			getSortedRowModel: sortable && !manualSorting ? sortedRowModel : undefined,
+			getPaginationRowModel: paginated ? paginationRowModel : undefined,
 			renderFallbackValue: '',
 		};
-		const instance = createTable(opts);
-		// createTable takes a fully-resolved state — unlike the framework adapters it does
-		// not fill in defaults, so feature state we never touch (columnPinning, columnVisibility,
-		// …) lands undefined and getHeaderGroups() dies reading columnPinning.left. Merge the
-		// instance defaults under our reactive slices, the same way the TanStack adapters do.
-		instance.setOptions((prev) => ({
+	}
+
+	const table = createTable(untrack(buildOptions));
+	/** The row-model mode the cached `_get*RowModel`s were built for. */
+	let modelMode = '';
+
+	/**
+	 * Pushes the current props/state into the one instance. Its value is a fresh
+	 * token per change: everything that reads the table goes through `t()` (or
+	 * reads this), so it re-runs exactly when the table's inputs moved.
+	 */
+	const tableRev = $derived.by(() => {
+		const opts = buildOptions();
+		const mode = `${sortable && !manualSorting}|${paginated}`;
+		if (mode !== modelMode) {
+			// TanStack caches the sorted / paginated model on first use and never
+			// re-reads the option, so a flag flip must drop the cache.
+			table._getSortedRowModel = undefined;
+			table._getPaginationRowModel = undefined;
+			modelMode = mode;
+		}
+		// createTable takes a fully-resolved state — unlike the framework adapters it
+		// does not fill in defaults, so feature state we never touch (columnPinning,
+		// columnVisibility, …) would land undefined and getHeaderGroups() dies reading
+		// columnPinning.left. Merge the instance defaults under our reactive slices.
+		table.setOptions((prev) => ({
 			...prev,
-			state: { ...instance.initialState, ...opts.state },
+			...opts,
+			state: { ...table.initialState, ...opts.state },
 		}));
-		return instance;
+		return {};
 	});
 
-	const headerGroups = $derived(table.getHeaderGroups());
-	const rows = $derived(table.getRowModel().rows);
-	const pageCount = $derived(table.getPageCount());
-	const canPrevPage = $derived(table.getCanPreviousPage());
-	const canNextPage = $derived(table.getCanNextPage());
+	/** The table, read through `tableRev` so the caller re-runs when it changes. */
+	function t() {
+		void tableRev;
+		return table;
+	}
+
+	const headerGroups = $derived(t().getHeaderGroups());
+	const rows = $derived(t().getRowModel().rows);
+	const pageCount = $derived(t().getPageCount());
+	const canPrevPage = $derived(t().getCanPreviousPage());
+	const canNextPage = $derived(t().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 = t().getSelectedRowModel().rows.map((r) => r.original);
 		onSelectionChange(selected);
 	});
 
+	// ── Render list ────────────────────────────────────────────────────────
+	// Everything the body draws, in order: group headers, data rows and the
+	// detail row under each expanded row. One entry = one `<tr>`, which is what
+	// the row window counts and measures.
+	const GROUP_KEY = '\u0000group:';
+	const DETAIL_KEY = '\u0000detail:';
+
+	type Entry =
+		| { kind: 'group'; key: string; item: GroupedGroupItem<TData>; pathKey: string }
+		| { kind: 'row'; key: string; item: GroupedRowItem<TData>; row: Row<TData> }
+		| { kind: 'detail'; key: string; row: Row<TData> };
+
+	const grouped = $derived(!!groupBy && groupBy.length > 0);
+
+	const entries = $derived.by<Entry[]>(() => {
+		const list = rows;
+		const out: Entry[] = [];
+		const pushRow = (row: Row<TData>, item: GroupedRowItem<TData>) => {
+			out.push({ kind: 'row', key: row.id, item, row });
+			if (rowIsExpanded(row)) out.push({ kind: 'detail', key: DETAIL_KEY + row.id, row });
+		};
+
+		if (!grouped) {
+			const n = list.length;
+			list.forEach((row, i) => {
+				const position = n === 1 ? 'only' : i === 0 ? 'first' : i === n - 1 ? 'last' : 'middle';
+				pushRow(row, { kind: 'row', row: row.original, id: row.id, depth: 0, groupPath: [], position });
+			});
+			return out;
+		}
+
+		// Group the TanStack rows themselves (not their originals) so duplicate
+		// originals stay distinct, then hand callers originals in the items.
+		const levels: GroupLevel<Row<TData>>[] = groupBy!.map((level) => ({
+			key: (r) => level.key(r.original),
+			compare: level.compare,
+			showHeader: level.showHeader
+				? (k, rs) => level.showHeader!(k, rs.map((r) => r.original))
+				: undefined,
+		}));
+		const items = groupRows(list, levels, {
+			getRowId: (r) => r.id,
+			collapsed: collapsed ?? new Set(),
+			label: groupLabel,
+		});
+		for (const it of items) {
+			if (it.kind === 'group') {
+				const pathKey = groupPathKey(it.path);
+				out.push({
+					kind: 'group',
+					key: GROUP_KEY + pathKey,
+					pathKey,
+					item: { ...it, rows: it.rows.map((r) => r.original) },
+				});
+			} else {
+				pushRow(it.row, { ...it, row: it.row.original });
+			}
+		}
+		return out;
+	});
+
+	/** Group-header indices per depth, outermost first — the window's sticky levels. */
+	const stickyLevels = $derived.by<number[][]>(() => {
+		const levels: number[][] = [];
+		entries.forEach((e, i) => {
+			if (e.kind !== 'group') return;
+			(levels[e.item.depth] ??= []).push(i);
+		});
+		for (let d = 0; d < levels.length; d++) levels[d] ??= [];
+		return levels;
+	});
+
+	// ── Windowing (grid mode) ──────────────────────────────────────────────
+	function renderItem(e: Entry): DataTableRenderItem<TData> {
+		if (e.kind === 'detail') return { kind: 'detail', row: e.row.original, id: e.row.id };
+		return e.item as GroupedItem<TData>;
+	}
+
+	function estimate(e: Entry | undefined): number {
+		if (!e) return 40;
+		const est = virtual?.estimateRowSize;
+		if (typeof est === 'function') return est(renderItem(e));
+		if (e.kind === 'group') return 36;
+		if (e.kind === 'detail') return 120;
+		return typeof est === 'number' ? est : 40;
+	}
+
+	// Read once: the window must be created during component init.
+	const virtualAtMount = untrack(() => virtual);
+	const win: DataTableRowWindow | null = virtualAtMount
+		? virtualAtMount.createRowWindow({
+				count: () => entries.length,
+				getKey: (i) => entries[i]?.key ?? String(i),
+				estimateSize: (i) => estimate(entries[i]),
+				overscan: virtualAtMount.overscan,
+				get threshold() {
+					return virtual?.threshold ?? 0;
+				},
+				scrollRoot: virtualAtMount.scrollRoot ?? 'auto',
+				scrollPaddingStart: virtualAtMount.scrollPaddingStart,
+				pinned: () => {
+					const keys: string[] = [];
+					for (const id of pinnedRowIds ?? []) keys.push(id, DETAIL_KEY + id);
+					return keys;
+				},
+				stickyIndices: () => (stickyGroupHeaders ? stickyLevels : []),
+			})
+		: null;
+
+	const noopAction = (_node: HTMLElement, _key?: string) => ({ update() {}, destroy() {} });
+	const measureAction = win ? win.measure : noopAction;
+	const anchorAction = win ? win.anchor : noopAction;
+
+	type Slot = { entry: Entry; index: number; spacers: number[] };
+
+	/**
+	 * Spacer rows that stand in for `skipped` undrawn entries totalling `height`
+	 * px. The COUNT keeps `nth-child` parity with the unwindowed table, so zebra
+	 * striping does not flip as the slice scrolls: an odd gap gets one spacer, an
+	 * even one gets two.
+	 */
+	function spacersFor(skipped: number, height: number): number[] {
+		if (skipped <= 0) return height > 0 ? [height, 0] : [];
+		return skipped % 2 === 1 ? [height] : [height, 0];
+	}
+
+	const slots = $derived.by<Slot[]>(() => {
+		if (!win) return entries.map((entry, index) => ({ entry, index, spacers: [] }));
+		const out: Slot[] = [];
+		let prev = -1;
+		for (const it of win.items) {
+			const entry = entries[it.index];
+			// The window can trail the entry list by one flush; skip strays.
+			if (!entry || entry.key !== it.key) continue;
+			const height = prev < 0 ? win.paddingTop : it.gapBefore;
+			out.push({ entry, index: it.index, spacers: spacersFor(it.index - prev - 1, height) });
+			prev = it.index;
+		}
+		return out;
+	});
+
+	// ── ARIA ───────────────────────────────────────────────────────────────
+	const ariaRows = $derived(ariaGrid || !!win);
+	const tableRole = $derived(ariaGrid ? (grouped ? 'treegrid' : 'grid') : undefined);
+	/** 1-based row index, counting the header rows. */
+	function ariaRowIndex(index: number): number | undefined {
+		return ariaRows ? index + 1 + headerGroups.length : undefined;
+	}
+
+	// ── Imperative api ─────────────────────────────────────────────────────
+	api = {
+		orderedRowIds: () =>
+			grouped && !paginated
+				? entries.filter((e) => e.kind === 'row').map((e) => e.key)
+				: t().getPrePaginationRowModel().rows.map((r) => r.id),
+		scrollToRow: async (id, align = 'auto') => {
+			if (paginated) {
+				const index = t().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();
+				}
+			}
+			if (win) {
+				win.scrollToKey(id, { align });
+				return;
+			}
+			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 isSelected(row: Row<TData>): boolean {
+		void tableRev;
+		return row.getIsSelected();
+	}
+
+	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;
+	}
+
+	function toggleGroup(pathKey: string) {
+		const next = new Set(collapsed ?? []);
+		if (next.has(pathKey)) next.delete(pathKey);
+		else next.add(pathKey);
+		collapsed = next;
+		onCollapsedChange?.(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);
+
+	// ── Scroll container ───────────────────────────────────────────────────
+	// The default wrapper scrolls horizontally, which also makes it the sticky
+	// containing block — a sticky header would stick to a box that never scrolls
+	// vertically. With sticky on and no `maxHeight`, clip instead (no scroll
+	// container); with `maxHeight`, the wrapper becomes the real scroller.
+	const sticky = $derived(stickyHeader || stickyGroupHeaders);
+	const scrollerClass = $derived(maxHeight ? 'dt-scroller' : sticky ? 'dt-clip' : 'overflow-x-auto');
+	let theadHeight = $state(0);
 </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 _}
@@ -154,19 +510,30 @@
 			</table>
 		</div>
 	{:else}
-		<div class="overflow-x-auto">
-			<table class="table table-zebra w-full">
-				<thead>
-					{#each headerGroups as headerGroup}
-						<tr>
+		<div
+			class={scrollerClass}
+			style:max-height={maxHeight}
+			style:--dt-thead-h={sticky ? `${stickyHeader ? theadHeight : 0}px` : undefined}
+		>
+			<table
+				class={tableClasses}
+				class:dt-sticky-head={stickyHeader}
+				role={tableRole}
+				aria-label={ariaLabel}
+				aria-multiselectable={ariaGrid && selectable ? 'true' : undefined}
+				aria-rowcount={ariaRows ? entries.length + headerGroups.length : undefined}
+			>
+				<thead bind:offsetHeight={theadHeight}>
+					{#each headerGroups as headerGroup, hi}
+						<tr aria-rowindex={ariaRows ? hi + 1 : undefined}>
 							{#each headerGroup.headers as header}
 								{#if header.column.id === '__select'}
 									<th class="dt-select-cell">
 										<input
 											type="checkbox"
 											class="checkbox checkbox-sm"
-											checked={table.getIsAllRowsSelected()}
-											indeterminate={table.getIsSomeRowsSelected()}
+											checked={t().getIsAllRowsSelected()}
+											indeterminate={t().getIsSomeRowsSelected()}
 											aria-label="Select all rows"
 											onchange={() => table.toggleAllRowsSelected()}
 										/>
@@ -175,10 +542,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">
@@ -209,44 +581,127 @@
 					{/each}
 				</thead>
 
-				<tbody>
+				<tbody use:anchorAction>
 					{#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 row.getVisibleCells() as cell}
-									{#if cell.column.id === '__select'}
-										<td class="dt-select-cell">
-											<input
-												type="checkbox"
-												class="checkbox checkbox-sm"
-												checked={row.getIsSelected()}
-												disabled={!row.getCanSelect()}
-												aria-label="Select row"
-												onchange={() => row.toggleSelected()}
-											/>
-										</td>
+						{#each slots as slot (slot.entry.key)}
+							{#each slot.spacers as h}
+								<tr class="dt-spacer" aria-hidden="true" style:height="{h}px"></tr>
+							{/each}
+							{@const entry = slot.entry}
+							{#if entry.kind === 'group'}
+								{@const g = entry.item}
+								{@const pathKey = entry.pathKey}
+								<tr
+									class="dt-group-row"
+									class:dt-group-sticky={stickyGroupHeaders}
+									data-group-key={pathKey}
+									data-group-depth={g.depth}
+									style:--dt-group-depth={g.depth}
+									aria-rowindex={ariaRowIndex(slot.index)}
+									aria-level={ariaGrid ? g.depth + 1 : undefined}
+									aria-expanded={ariaGrid ? !g.collapsed : undefined}
+									use:measureAction={entry.key}
+								>
+									{#if groupHeader}
+										{@render groupHeader(g, {
+											toggle: () => toggleGroup(pathKey),
+											colspan: allColumns.length,
+											collapsed: g.collapsed,
+										})}
 									{:else}
-										{@const rendered = renderCell(cell)}
-										<td>
-											{#if rendered.type === 'snippet'}
-												{@render rendered.snippet(rendered.props)}
-											{:else}
-												{rendered.value}
-											{/if}
-										</td>
+										<th colspan={allColumns.length} scope="rowgroup" class="dt-group-cell">
+											<button
+												type="button"
+												class="dt-group-toggle"
+												aria-expanded={!g.collapsed}
+												onclick={() => toggleGroup(pathKey)}
+											>
+												<svg class="dt-group-chevron" class:dt-group-chevron-open={!g.collapsed} width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+													<path d="M4.5 2.5L8 6L4.5 9.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+												</svg>
+												<span class="dt-group-label">{g.label}</span>
+												<span class="dt-group-count">{g.count}</span>
+											</button>
+										</th>
 									{/if}
-								{/each}
-							</tr>
+								</tr>
+							{:else if entry.kind === 'row'}
+								{@const row = entry.row}
+								{@const rp = rowProps?.(row.original, entry.item) ?? {}}
+								{@const attrs = rowAttrs(rp)}
+								{@const expanded = rowIsExpanded(row)}
+								{@const selected = isSelected(row)}
+								<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+								<tr
+									{...attrs}
+									class={rp.class}
+									class:dt-row-selected={selected}
+									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}
+									aria-selected={ariaGrid && selectable ? selected : undefined}
+									aria-level={ariaGrid && grouped ? entry.item.depth + 1 : undefined}
+									aria-rowindex={ariaRowIndex(slot.index)}
+									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}
+									use:measureAction={entry.key}
+								>
+									{#each row.getVisibleCells() as cell}
+										{#if cell.column.id === '__select'}
+											<td class="dt-select-cell">
+												<input
+													type="checkbox"
+													class="checkbox checkbox-sm"
+													checked={selected}
+													disabled={!row.getCanSelect()}
+													aria-label="Select row"
+													onchange={() => row.toggleSelected()}
+												/>
+											</td>
+										{:else}
+											{@const rendered = renderCell(cell)}
+											<td>
+												{#if rendered.type === 'snippet'}
+													{@render rendered.snippet(rendered.props)}
+												{:else}
+													{rendered.value}
+												{/if}
+											</td>
+										{/if}
+									{/each}
+								</tr>
+							{:else if expandedRow}
+								{@const row = entry.row}
+								<tr
+									class="dt-expanded-detail"
+									data-detail-for={getRowId ? row.id : undefined}
+									aria-rowindex={ariaRowIndex(slot.index)}
+									use:measureAction={entry.key}
+								>
+									<td colspan={allColumns.length}>{@render expandedRow(row.original, { colspan: allColumns.length })}</td>
+								</tr>
+							{/if}
 						{/each}
+						{#if win && win.paddingBottom > 0}
+							<tr class="dt-spacer" aria-hidden="true" style:height="{win.paddingBottom}px"></tr>
+						{/if}
 					{/if}
 				</tbody>
 			</table>
 		</div>
-
 		{#if paginated && pageCount > 1}
 			<div class="dt-pagination">
 				<span class="dt-page-info">
@@ -327,6 +782,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;
@@ -381,4 +844,76 @@
 	@media (prefers-reduced-motion: reduce) {
 		.skel-cell { animation: none; }
 	}
+
+	/* ── Grid mode ─────────────────────────────────────────────────────── */
+	.dt-scroller {
+		overflow: auto;
+	}
+	/* Sticky without maxHeight: no scroll container, so sticky cells stick to
+	   the page's scroller. Horizontal overflow is clipped instead of scrolled. */
+	.dt-clip {
+		overflow-x: clip;
+	}
+
+	.dt-sticky-head thead th {
+		position: sticky;
+		top: 0;
+		z-index: 3;
+		background-color: var(--color-base-100);
+	}
+
+	.dt-spacer {
+		border: 0;
+		background: transparent !important;
+	}
+
+	.dt-group-sticky > :global(th),
+	.dt-group-sticky > :global(td) {
+		position: sticky;
+		top: calc(var(--dt-thead-h, 0px) + var(--dt-group-depth, 0) * var(--dt-group-row-h, 2.25rem));
+		z-index: 2;
+	}
+
+	.dt-group-cell {
+		text-align: left;
+		padding-left: calc(var(--jatui-space-base, 8px) + var(--dt-group-depth, 0) * var(--dt-group-indent, 1rem));
+		background-color: var(--color-base-200);
+		font-weight: 600;
+	}
+
+	.dt-group-toggle {
+		display: inline-flex;
+		align-items: center;
+		gap: var(--jatui-space-sm, 4px);
+		padding: 0;
+		border: 0;
+		background: none;
+		color: inherit;
+		font: inherit;
+		cursor: pointer;
+		border-radius: var(--jatui-radius-selector, 0.375rem);
+	}
+	.dt-group-toggle:focus-visible {
+		outline: 2px solid var(--color-primary);
+		outline-offset: 2px;
+	}
+
+	.dt-group-chevron {
+		flex-shrink: 0;
+		color: color-mix(in oklch, var(--color-base-content) 55%, transparent);
+		transition: transform var(--motion-fast, 150ms) var(--motion-glide, ease-out);
+	}
+	.dt-group-chevron-open {
+		transform: rotate(90deg);
+	}
+
+	.dt-group-count {
+		font-weight: 400;
+		font-size: 0.75rem;
+		color: color-mix(in oklch, var(--color-base-content) 50%, transparent);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.dt-group-chevron { transition: none; }
+	}
 </style>