@happyvertical/smrt-ui 0.42.3 → 0.42.5

package/dist/components/data/DataTable.svelte

@@ -11,15 +11,38 @@
  * - Material 3 styling with theme token support
  */
 
-import type { Snippet } from 'svelte';
+import { type Snippet, tick } from 'svelte';
 import { M } from '../../i18n/strings.js';
 import Trans from '../../i18n/Trans.svelte';
 import { useI18n } from '../../i18n/use-i18n.js';
 import Pagination from '../ui/Pagination.svelte';
+import {
+  compareDataTableRowIds,
+  createDataTableController,
+  type DataTableCommand,
+  type DataTableController,
+  type DataTableFilter,
+  type DataTableModes,
+  type DataTableRowId,
+  type DataTableSnapshot,
+  type DataTableViewState,
+  type DataTableViewStateInput,
+  dataTableRowIdKey,
+} from './DataTableController.js';
+import { resolveDataTableRows } from './DataTableIdentity.js';
+import {
+  type DataTableResolvedColumn,
+  resolveDataTableLayout,
+} from './DataTableLayout.js';
+import {
+  maximumDataTableVirtualScrollTop,
+  resolveDataTableVirtualWindow,
+  scrollTopForDataTableRow,
+} from './DataTableVirtualization.js';
 import type {
   DataTableColumn,
   DataTableProps,
-  SortDirection,
+  DataTableStructuralRow,
   SortState,
 } from './types.js';
 import { defaultSort, getNestedValue } from './types.js';
@@ -37,10 +60,12 @@ let {
   data = [],
   columns = [],
   rowKey,
+  agentAddressable = false,
   selectable = false,
   selected = $bindable(new Set<string | number>()),
   onSelectionChange,
   onRowClick,
+  rowLabel,
   sortable = false,
   sort = $bindable({ columnId: null, direction: null }),
   onSortChange,
@@ -49,6 +74,7 @@ let {
   page = $bindable(1),
   pageSize,
   manualPagination = false,
+  virtualization,
   totalRows,
   onPageChange,
   expanded = $bindable(new Set<string | number>()),
@@ -57,8 +83,14 @@ let {
   expandedContent,
   toolbar,
   footer,
+  structuralRows = [],
   visibleColumnIds,
   loading = false,
+  refreshing = false,
+  stale = false,
+  partialResults = false,
+  error = null,
+  onRetry,
   empty,
   rowClass,
   size = 'md',
@@ -68,85 +100,283 @@ let {
   caption,
   dense = false,
   cell,
+  controller,
+  state: controlledState,
+  initialState,
+  onStateChange,
+  modes,
 }: ExtendedProps<T> = $props();
 
-// Get row key value
-function getRowKey(row: T, index: number): string | number {
-  if (!rowKey) return index;
-  if (typeof rowKey === 'function') return rowKey(row);
-  return row[rowKey] as string | number;
+const dataTableId = $props.id();
+
+function legacyModes(): DataTableModes {
+  return {
+    filtering: modes?.filtering ?? 'local',
+    sorting: modes?.sorting ?? (manualSorting ? 'manual' : 'local'),
+    pagination: modes?.pagination ?? (manualPagination ? 'manual' : 'local'),
+  };
 }
 
-function getDisplayRowKey(row: T, index: number): string | number {
-  return getRowKey(row, displayIndexOffset + index);
+function legacyViewState(): Partial<DataTableViewState> {
+  const next: Partial<DataTableViewState> = {
+    sorting:
+      sort.columnId && sort.direction
+        ? [{ columnId: sort.columnId, direction: sort.direction }]
+        : [],
+    page,
+    pageSize: pageSize ?? null,
+    selectedRowIds: [...selected],
+    expandedRowIds: [...expanded],
+  };
+  if (visibleColumnIds) {
+    next.columnVisibility = columns.map((column) => ({
+      columnId: column.id,
+      visible: visibleColumnIds.has(column.id),
+    }));
+  }
+  return next;
 }
 
-// Handle sort click
-function handleSort(column: DataTableColumn<T>) {
-  if (!sortable || !column.sortable) return;
+function mergedLegacyState(): Omit<DataTableViewState, 'selection'> {
+  const { selection: _selection, ...current } = localController.getState();
+  return { ...current, ...legacyViewState() };
+}
 
-  const newSort: SortState = {
-    columnId: column.id,
-    direction:
-      sort.columnId === column.id
-        ? sort.direction === 'asc'
-          ? 'desc'
-          : sort.direction === 'desc'
-            ? null
-            : 'asc'
-        : 'asc',
-  };
+const localController = createDataTableController({
+  modes: legacyModes(),
+  onStateChange: (next, command) => onStateChange?.(next, command),
+});
+
+let controllerSnapshot = $state<DataTableSnapshot>(localController.snapshot());
+let measuredColumnWidths = $state<Record<string, number>>({});
+let publishedLegacySignature: string | undefined;
+let localControllerInitialized = false;
+let hasHorizontalOverflow = $state(false);
+let canScrollLeft = $state(false);
+let canScrollRight = $state(false);
+
+function activeController(): DataTableController {
+  return controller ?? localController;
+}
+
+function legacySignature(): string {
+  const legacy = legacyViewState();
+  return JSON.stringify({
+    sorting: legacy.sorting,
+    page: legacy.page,
+    pageSize: legacy.pageSize,
+    columnVisibility: legacy.columnVisibility,
+    selectedRowIds: [...(legacy.selectedRowIds ?? [])].sort(),
+    expandedRowIds: [...(legacy.expandedRowIds ?? [])].sort(),
+  });
+}
+
+function legacySort(next: DataTableViewState): SortState {
+  const rule = next.sorting[0];
+  return rule
+    ? { columnId: rule.columnId, direction: rule.direction }
+    : { columnId: null, direction: null };
+}
+
+function publishLegacyState(
+  next: DataTableViewState,
+  command: DataTableCommand,
+  previous: DataTableViewState,
+) {
+  const nextSort = legacySort(next);
+  const previousSort = legacySort(previous);
+  sort = nextSort;
+  page = next.page;
+  selected = new Set(next.selectedRowIds);
+  expanded = new Set(next.expandedRowIds);
+  publishedLegacySignature = legacySignature();
+
+  if (
+    nextSort.columnId !== previousSort.columnId ||
+    nextSort.direction !== previousSort.direction
+  ) {
+    onSortChange?.(nextSort);
+  }
+  if (
+    JSON.stringify(next.selectedRowIds) !==
+    JSON.stringify(previous.selectedRowIds)
+  ) {
+    onSelectionChange?.(new Set(next.selectedRowIds));
+  }
+  if (
+    JSON.stringify(next.expandedRowIds) !==
+    JSON.stringify(previous.expandedRowIds)
+  ) {
+    onExpandedChange?.(new Set(next.expandedRowIds));
+  }
+  if (next.page !== previous.page) onPageChange?.(next.page);
+  void command;
+}
+
+$effect(() => {
+  if (controller) return;
+
+  localController.setControlled(controlledState !== undefined);
+  localController.setModes(legacyModes());
+  const columnIds = columns.map((column) => column.id);
+  const hiddenColumnIds = columns
+    .filter(
+      (column) =>
+        column.hidden ||
+        (visibleColumnIds !== undefined && !visibleColumnIds.has(column.id)),
+    )
+    .map((column) => column.id);
+
+  if (!localControllerInitialized) {
+    localControllerInitialized = true;
+    const nextState: DataTableViewStateInput = controlledState ?? {
+      ...mergedLegacyState(),
+      ...initialState,
+    };
+    localController.replaceState(nextState);
+    localController.setColumnIds(columnIds, hiddenColumnIds);
+    return;
+  }
+
+  localController.setColumnIds(columnIds, hiddenColumnIds);
+
+  if (controlledState !== undefined) {
+    localController.replaceState(controlledState);
+    return;
+  }
 
-  if (newSort.direction === null) {
-    newSort.columnId = null;
+  const signature = legacySignature();
+  if (signature === publishedLegacySignature) {
+    publishedLegacySignature = undefined;
+    return;
   }
+  localController.replaceState(mergedLegacyState());
+});
+
+$effect(() => {
+  const current = activeController();
+  current.setColumnIds(
+    columns.map((column) => column.id),
+    columns
+      .filter(
+        (column) =>
+          column.hidden ||
+          (visibleColumnIds !== undefined && !visibleColumnIds.has(column.id)),
+      )
+      .map((column) => column.id),
+  );
+  controllerSnapshot = current.snapshot();
+  return current.subscribe((transition) => {
+    controllerSnapshot = transition.next;
+    if (
+      current === localController &&
+      controlledState === undefined &&
+      transition.command
+    ) {
+      publishLegacyState(
+        transition.next.state,
+        transition.command,
+        transition.previous.state,
+      );
+    }
+  });
+});
+
+const tableState = $derived(controllerSnapshot.state);
+const tableModes = $derived(controllerSnapshot.modes);
+const constrainedLayoutState = $derived.by(() => ({
+  ...tableState,
+  columnWidths: tableState.columnWidths.map((entry) => {
+    const column = columns.find((candidate) => candidate.id === entry.columnId);
+    return column
+      ? { ...entry, width: clampedColumnWidth(column, entry.width) }
+      : entry;
+  }),
+}));
+const requiresStableRowIdentity = $derived(
+  selectable ||
+    Boolean(expandedContent) ||
+    agentAddressable ||
+    tableModes.filtering === 'manual' ||
+    tableModes.sorting === 'manual' ||
+    tableModes.pagination === 'manual' ||
+    Boolean(virtualization),
+);
+const sourceRows = $derived.by(() =>
+  resolveDataTableRows(data, rowKey, {
+    requireStableIdentity: requiresStableRowIdentity,
+  }),
+);
 
-  sort = newSort;
-  onSortChange?.(newSort);
+function dispatch(command: DataTableCommand) {
+  activeController().dispatch(command);
 }
 
-// Handle row selection
-function handleRowSelect(key: string | number, event: Event) {
-  event.stopPropagation();
-  const newSelected = new Set(selected);
+function handleSort(column: DataTableColumn<T>, event: MouseEvent) {
+  if (!sortable || !column.sortable) return;
+  dispatch({
+    type: 'toggleSorting',
+    columnId: column.id,
+    multi: event.shiftKey,
+  });
+}
 
-  if (newSelected.has(key)) {
-    newSelected.delete(key);
-  } else {
-    newSelected.add(key);
+function usesAutomaticSortButton(column: DataTableColumn<T>): boolean {
+  return (
+    sortable && column.sortable === true && column.headerSortMode !== 'manual'
+  );
+}
+
+function sortActionLabel(column: DataTableColumn<T>): string {
+  const columnSort = tableState.sorting.find(
+    (sort) => sort.columnId === column.id,
+  );
+  if (!columnSort) {
+    return t(M['ui.data_table.sort_ascending'], { column: column.label });
   }
+  if (columnSort.direction === 'asc') {
+    return t(M['ui.data_table.sort_descending'], { column: column.label });
+  }
+  return t(M['ui.data_table.clear_sort'], { column: column.label });
+}
 
-  selected = newSelected;
-  onSelectionChange?.(newSelected);
+function handleRowSelect(key: DataTableRowId, event: Event) {
+  event.stopPropagation();
+  dispatch({ type: 'toggleRowSelection', rowId: key });
 }
 
-// Handle select all
 function handleSelectAll() {
+  if (tableState.selection.scope === 'allMatching') {
+    dispatch({
+      type: 'setSelection',
+      selection: { scope: 'explicit', rowIds: [] },
+    });
+    return;
+  }
+  const selectedIds = new Set(tableState.selectedRowIds);
+  const visibleIds = displayRows.map(({ rowId }) => rowId);
+  if (tableState.selection.scope === 'page') {
+    dispatch({
+      type: 'setPageSelection',
+      rowIds: allSelected ? [] : visibleIds,
+    });
+    return;
+  }
   if (allSelected) {
-    const visibleKeys = new Set(
-      displayData.map((row, i) => getDisplayRowKey(row, i)),
-    );
-    selected = new Set([...selected].filter((key) => !visibleKeys.has(key)));
+    for (const key of visibleIds) selectedIds.delete(key);
   } else {
-    selected = new Set([
-      ...selected,
-      ...displayData.map((row, i) => getDisplayRowKey(row, i)),
-    ]);
+    for (const key of visibleIds) selectedIds.add(key);
   }
-  onSelectionChange?.(selected);
+  dispatch({ type: 'setSelectedRows', rowIds: [...selectedIds] });
 }
 
-function handleExpanded(key: string | number, event: Event) {
+function handleExpanded(key: DataTableRowId, event: Event) {
   event.stopPropagation();
-  const next = new Set(expanded);
-  next.has(key) ? next.delete(key) : next.add(key);
-  expanded = next;
-  onExpandedChange?.(next);
+  dispatch({ type: 'toggleRowExpansion', rowId: key });
 }
 
 function handlePageChange(next: number) {
-  page = Math.min(Math.max(1, next), totalPages);
-  onPageChange?.(page);
+  dispatch({ type: 'setPage', page: next });
 }
 
 // Handle row click
@@ -154,6 +384,100 @@ function handleRowClick(row: T, index: number) {
   onRowClick?.(row, index);
 }
 
+function getRowLabel(row: T, index: number): string {
+  return (
+    rowLabel?.(row, index) ??
+    t(M['ui.data_table.row_number'], {
+      number: virtualRowOffset + index + 1,
+    })
+  );
+}
+
+function expansionContentId(key: DataTableRowId): string {
+  return `${dataTableId}-expanded-${encodeURIComponent(dataTableRowIdKey(key))}`;
+}
+
+function isNestedInteractiveTarget(target: EventTarget | null): boolean {
+  return (
+    target instanceof Element &&
+    target.closest(
+      'a, button, input, select, textarea, label, summary, [contenteditable="true"], [role="button"], [role="link"], [role="menuitem"], [role="checkbox"], [role="switch"]',
+    ) !== null
+  );
+}
+
+function handleRowActivation(event: MouseEvent, row: T, index: number) {
+  if (isNestedInteractiveTarget(event.target)) return;
+  handleRowClick(row, index);
+}
+
+function handleRowKeydown(event: KeyboardEvent, row: T, index: number) {
+  if (
+    !onRowClick ||
+    isNestedInteractiveTarget(event.target) ||
+    (event.key !== 'Enter' && event.key !== ' ')
+  ) {
+    return;
+  }
+  event.preventDefault();
+  handleRowClick(row, index);
+}
+
+function updateOverflowState() {
+  const container = tableContainer;
+  if (!container) return;
+
+  const maxScrollLeft = Math.max(
+    0,
+    container.scrollWidth - container.clientWidth,
+  );
+  hasHorizontalOverflow = maxScrollLeft > 1;
+  canScrollLeft = hasHorizontalOverflow && container.scrollLeft > 1;
+  canScrollRight =
+    hasHorizontalOverflow && container.scrollLeft < maxScrollLeft - 1;
+}
+
+function handleOverflowKeydown(event: KeyboardEvent) {
+  const container = tableContainer;
+  if (!container || !hasHorizontalOverflow || event.target !== container) {
+    return;
+  }
+
+  const maxScrollLeft = Math.max(
+    0,
+    container.scrollWidth - container.clientWidth,
+  );
+  const scrollStep = Math.max(Math.floor(container.clientWidth * 0.8), 40);
+  let nextScrollLeft: number | undefined;
+
+  switch (event.key) {
+    case 'ArrowLeft':
+      nextScrollLeft = container.scrollLeft - scrollStep;
+      break;
+    case 'ArrowRight':
+      nextScrollLeft = container.scrollLeft + scrollStep;
+      break;
+    case 'Home':
+      nextScrollLeft = 0;
+      break;
+    case 'End':
+      nextScrollLeft = maxScrollLeft;
+      break;
+  }
+
+  if (nextScrollLeft === undefined) return;
+
+  const clampedScrollLeft = Math.max(
+    0,
+    Math.min(maxScrollLeft, nextScrollLeft),
+  );
+  if (clampedScrollLeft === container.scrollLeft) return;
+
+  event.preventDefault();
+  container.scrollLeft = clampedScrollLeft;
+  updateOverflowState();
+}
+
 // Action to set indeterminate state (can't be set via HTML attribute)
 function setIndeterminate(node: HTMLInputElement, value: boolean) {
   node.indeterminate = value;
@@ -164,160 +488,774 @@ function setIndeterminate(node: HTMLInputElement, value: boolean) {
   };
 }
 
-// Get visible columns
-const visibleColumns = $derived(
-  columns.filter(
-    (col) => !col.hidden && (!visibleColumnIds || visibleColumnIds.has(col.id)),
-  ),
+const dataTableLayout = $derived(
+  resolveDataTableLayout(columns, constrainedLayoutState, measuredColumnWidths),
+);
+const visibleColumns = $derived(dataTableLayout.columns);
+const dataBodyStructuralRows = $derived(
+  structuralRows.filter((row) => row.kind !== 'footer'),
 );
+const footerStructuralRows = $derived(
+  structuralRows.filter((row) => row.kind === 'footer'),
+);
+const structuralRowCount = $derived(
+  dataBodyStructuralRows.length +
+    footerStructuralRows.length +
+    (footer ? 1 : 0),
+);
+const headerRowCount = $derived(dataTableLayout.headerRows.length);
 
-const filteredData = $derived(filterFn ? data.filter(filterFn) : data);
+function sameFilterValue(value: unknown, expected: unknown): boolean {
+  return Object.is(value, expected);
+}
 
-// Sort data
-const sortedData = $derived.by(() => {
-  if (manualSorting || !sort.columnId || !sort.direction) return filteredData;
+function textValue(value: unknown): string {
+  return String(value ?? '').toLowerCase();
+}
 
-  const column = columns.find((c) => c.id === sort.columnId);
-  if (!column) return filteredData;
+function compareFilterValues(left: unknown, right: unknown): number {
+  const leftValue = left instanceof Date ? left.getTime() : left;
+  const rightValue = right instanceof Date ? right.getTime() : right;
+  if (typeof leftValue === 'number' && typeof rightValue === 'number')
+    return leftValue - rightValue;
+  const a = String(leftValue ?? '');
+  const b = String(rightValue ?? '');
+  return a < b ? -1 : a > b ? 1 : 0;
+}
 
-  const accessor = column.accessor ?? column.id;
-  const direction = sort.direction;
+function matchesFilter(
+  row: T,
+  column: DataTableColumn<T>,
+  filter: DataTableFilter,
+): boolean {
+  if (column.filterable === false) return true;
+  const value = getCellValue(row, column);
+  if (column.filterFn) return column.filterFn(row, value, filter);
+  const expected = filter.value;
+  const valueText = textValue(value);
+  const expectedText = textValue(expected);
+  switch (filter.operator) {
+    case 'equals':
+      return sameFilterValue(value, expected);
+    case 'notEquals':
+      return !sameFilterValue(value, expected);
+    case 'contains':
+      return valueText.includes(expectedText);
+    case 'notContains':
+      return !valueText.includes(expectedText);
+    case 'startsWith':
+      return valueText.startsWith(expectedText);
+    case 'endsWith':
+      return valueText.endsWith(expectedText);
+    case 'in':
+      return (
+        Array.isArray(expected) &&
+        expected.some((entry) => sameFilterValue(value, entry))
+      );
+    case 'notIn':
+      return (
+        Array.isArray(expected) &&
+        !expected.some((entry) => sameFilterValue(value, entry))
+      );
+    case 'gt':
+      return compareFilterValues(value, expected) > 0;
+    case 'gte':
+      return compareFilterValues(value, expected) >= 0;
+    case 'lt':
+      return compareFilterValues(value, expected) < 0;
+    case 'lte':
+      return compareFilterValues(value, expected) <= 0;
+    case 'isNull':
+      return value == null;
+    case 'isNotNull':
+      return value != null;
+  }
+}
 
-  return [...filteredData].sort((a, b) => {
-    if (column.sortFn) {
-      return column.sortFn(a, b, direction);
+const filteredRows = $derived.by(() => {
+  if (tableModes.filtering === 'manual') return sourceRows;
+  const search = tableState.search.toLowerCase();
+  return sourceRows.filter(({ row, sourceIndex }) => {
+    if (filterFn && !filterFn(row, sourceIndex)) return false;
+    if (
+      search &&
+      !columns.some(
+        (column) =>
+          column.searchable !== false &&
+          textValue(getCellValue(row, column)).includes(search),
+      )
+    ) {
+      return false;
     }
-    return defaultSort(a, b, String(accessor), direction);
+    return tableState.filters.every((filter) => {
+      const column = columns.find(
+        (candidate) => candidate.id === filter.columnId,
+      );
+      return Boolean(column && matchesFilter(row, column, filter));
+    });
   });
 });
 
-const totalRowCount = $derived(totalRows ?? sortedData.length);
+const sortedRows = $derived.by(() => {
+  if (tableModes.sorting === 'manual' || tableState.sorting.length === 0)
+    return filteredRows;
+  return filteredRows.slice().sort((left, right) => {
+    for (const rule of tableState.sorting) {
+      const column = columns.find(
+        (candidate) => candidate.id === rule.columnId,
+      );
+      if (!column) continue;
+      const result = column.sortFn
+        ? column.sortFn(left.row, right.row, rule.direction)
+        : defaultSort(
+            left.row,
+            right.row,
+            String(column.accessor ?? column.id),
+            rule.direction,
+          );
+      if (result !== 0) return result;
+    }
+    return rowKey
+      ? compareDataTableRowIds(left.rowId, right.rowId)
+      : left.sourceIndex - right.sourceIndex;
+  });
+});
+
+const totalRowCount = $derived(
+  tableModes.pagination === 'manual' ? totalRows : sortedRows.length,
+);
 const totalPages = $derived(
-  pageSize ? Math.max(1, Math.ceil(totalRowCount / pageSize)) : 1,
+  tableState.pageSize
+    ? totalRowCount === undefined
+      ? null
+      : Math.max(1, Math.ceil(totalRowCount / tableState.pageSize))
+    : 1,
+);
+const displayRows = $derived.by(() => {
+  if (!tableState.pageSize || tableModes.pagination === 'manual')
+    return sortedRows;
+  const start = (tableState.page - 1) * tableState.pageSize;
+  return sortedRows.slice(start, start + tableState.pageSize);
+});
+
+let tableContainer: HTMLDivElement | undefined = $state();
+let tableCaption: HTMLTableCaptionElement | undefined = $state();
+let tableHead: HTMLTableSectionElement | undefined = $state();
+let tableBody: HTMLTableSectionElement | undefined = $state();
+let tableStructuralBody: HTMLTableSectionElement | undefined = $state();
+let tableFooter: HTMLTableSectionElement | undefined = $state();
+let virtualScrollTop = $state(0);
+let virtualStructuralHeight = $state(0);
+let virtualCaptionHeight = $state(0);
+let virtualFooterHeight = $state(0);
+
+const virtualizedBody = $derived(Boolean(virtualization) && !expandedContent);
+
+const virtualizationWindow = $derived.by(() =>
+  resolveDataTableVirtualWindow({
+    options: virtualization,
+    rowCount: displayRows.length,
+    scrollTop: virtualization?.scrollTop ?? virtualScrollTop,
+    hasVariableRowHeight: Boolean(expandedContent),
+    headerRowCount,
+    summaryRowCount: structuralRowCount,
+  }),
+);
+const renderedRows = $derived.by(() =>
+  displayRows.slice(
+    virtualizationWindow.startIndex,
+    virtualizationWindow.endIndex,
+  ),
+);
+const virtualRowCount = $derived(totalRowCount ?? displayRows.length);
+const virtualRowOffset = $derived(
+  tableModes.pagination === 'manual' && tableState.pageSize
+    ? (tableState.page - 1) * tableState.pageSize
+    : 0,
 );
-const displayData = $derived.by(() => {
-  if (!pageSize || manualPagination) return sortedData;
-  const start = (page - 1) * pageSize;
-  return sortedData.slice(start, start + pageSize);
+const virtualContainerHeight = $derived(
+  virtualizedBody && virtualization
+    ? virtualization.viewportHeight + virtualStructuralHeight
+    : undefined,
+);
+
+function clampVirtualScrollTop(nextScrollTop: number): number {
+  if (!virtualization) return 0;
+  const maximum = Math.max(
+    0,
+    maximumDataTableVirtualScrollTop(
+      displayRows.length,
+      virtualization,
+      virtualFooterHeight,
+    ),
+  );
+  return Math.min(Math.max(0, nextScrollTop), maximum);
+}
+
+function setVirtualScrollTop(nextScrollTop: number, notify = false) {
+  if (!virtualization || !tableContainer || !virtualizedBody) return;
+  const clampedScrollTop = clampVirtualScrollTop(nextScrollTop);
+  tableContainer.scrollTop = clampedScrollTop;
+  virtualScrollTop = clampedScrollTop;
+  if (notify) virtualization.onScrollTopChange?.(clampedScrollTop);
+}
+
+function handleTableScroll(event: Event) {
+  if (!virtualizationWindow.enabled) return;
+  const nextScrollTop = (event.currentTarget as HTMLDivElement).scrollTop;
+  const clampedScrollTop = clampVirtualScrollTop(nextScrollTop);
+  virtualScrollTop = clampedScrollTop;
+  virtualization?.onScrollTopChange?.(clampedScrollTop);
+}
+
+function handleVirtualizationKeydown(event: KeyboardEvent) {
+  if (!virtualizationWindow.enabled || !virtualization || !tableContainer)
+    return;
+  const pageStep = Math.max(
+    virtualization.rowHeight,
+    virtualization.viewportHeight - virtualization.rowHeight,
+  );
+  const currentScrollTop = tableContainer.scrollTop;
+  const nextScrollTop =
+    event.key === 'ArrowDown'
+      ? currentScrollTop + virtualization.rowHeight
+      : event.key === 'ArrowUp'
+        ? currentScrollTop - virtualization.rowHeight
+        : event.key === 'PageDown'
+          ? currentScrollTop + pageStep
+          : event.key === 'PageUp'
+            ? currentScrollTop - pageStep
+            : event.key === 'Home'
+              ? 0
+              : event.key === 'End'
+                ? Number.POSITIVE_INFINITY
+                : undefined;
+  if (nextScrollTop === undefined) return;
+  event.preventDefault();
+  setVirtualScrollTop(nextScrollTop, true);
+}
+
+function handleRowFocus(rowId: DataTableRowId) {
+  virtualization?.onFocusedRowIdChange?.(rowId);
+}
+
+$effect(() => {
+  if (!virtualizedBody || !tableContainer) return;
+  const controlledScrollTop = virtualization?.scrollTop;
+  if (controlledScrollTop !== undefined) {
+    setVirtualScrollTop(controlledScrollTop);
+  }
+});
+
+$effect(() => {
+  if (!virtualizedBody || !virtualization || !tableContainer) return;
+  const focusRowId = virtualization.focusedRowId;
+  const focusIndex =
+    focusRowId == null
+      ? -1
+      : displayRows.findIndex(({ rowId }) => rowId === focusRowId);
+  if (focusIndex < 0 || focusRowId == null) return;
+  const nextScrollTop = scrollTopForDataTableRow(
+    focusIndex,
+    displayRows.length,
+    virtualization,
+    tableContainer.scrollTop,
+  );
+  setVirtualScrollTop(nextScrollTop, virtualization.scrollTop !== undefined);
+  const focusContainer = tableContainer;
+  void tick().then(() => {
+    const focusedRow = Array.from(
+      focusContainer.querySelectorAll<HTMLTableRowElement>('tr[data-row-id]'),
+    ).find((row) => row.dataset.rowId === dataTableRowIdKey(focusRowId));
+    focusedRow?.focus({ preventScroll: true });
+  });
 });
-const displayIndexOffset = $derived(pageSize ? (page - 1) * pageSize : 0);
 
 $effect(() => {
-  if (page > totalPages) handlePageChange(totalPages);
+  if (!virtualizedBody || !tableBody) {
+    virtualStructuralHeight = 0;
+    virtualCaptionHeight = 0;
+    virtualFooterHeight = 0;
+    return;
+  }
+
+  const body = tableBody;
+  const captionElement = tableCaption;
+  const head = tableHead;
+  const structuralBody = tableStructuralBody;
+  const footerElement = tableFooter;
+  const measureStructure = () => {
+    virtualStructuralHeight = body.offsetTop;
+    virtualCaptionHeight = captionElement?.offsetHeight ?? 0;
+    virtualFooterHeight =
+      (structuralBody?.offsetHeight ?? 0) + (footerElement?.offsetHeight ?? 0);
+  };
+  measureStructure();
+  if (typeof ResizeObserver === 'undefined') return;
+
+  const observer = new ResizeObserver(measureStructure);
+  if (captionElement) observer.observe(captionElement);
+  if (head) observer.observe(head);
+  if (structuralBody) observer.observe(structuralBody);
+  if (footerElement) observer.observe(footerElement);
+  return () => observer.disconnect();
+});
+
+$effect(() => {
+  const total = totalRows;
+  if (total === undefined) return;
+  if (tableModes.pagination !== 'manual') {
+    throw new TypeError(
+      'DataTable totalRows is only valid when pagination mode is manual',
+    );
+  }
+  if (!Number.isFinite(total) || !Number.isInteger(total) || total < 0) {
+    throw new TypeError(
+      'DataTable totalRows must be a non-negative integer when supplied',
+    );
+  }
 });
 
-// Selection state
+$effect(() => {
+  void tableState.page;
+  void tableState.pageSize;
+  activeController().clampPage(totalRowCount);
+});
+
+const selectedIds = $derived(new Set(tableState.selectedRowIds));
+const expandedIds = $derived(new Set(tableState.expandedRowIds));
+const currentSort = $derived(legacySort(tableState));
+
 const allSelected = $derived(
-  displayData.length > 0 &&
-    displayData.every((row, i) => selected.has(getDisplayRowKey(row, i))),
+  tableState.selection.scope === 'allMatching' ||
+    (displayRows.length > 0 &&
+      displayRows.every(({ rowId }) => selectedIds.has(rowId))),
 );
 const someSelected = $derived(
-  displayData.some((row, i) => selected.has(getDisplayRowKey(row, i))) &&
+  tableState.selection.scope !== 'allMatching' &&
+    displayRows.some(({ rowId }) => selectedIds.has(rowId)) &&
     !allSelected,
 );
 
+const errorMessage = $derived.by(() => {
+  if (error == null) return undefined;
+  const message = typeof error === 'string' ? error : error.message;
+  return message.trim() || t(M['ui.data_table.load_error']);
+});
+const hasRenderedRows = $derived(displayRows.length > 0);
+const isInitialLoading = $derived(
+  (loading || refreshing) && !hasRenderedRows && !errorMessage,
+);
+const isRefreshing = $derived(
+  (loading || refreshing) && hasRenderedRows && !errorMessage,
+);
+const isBusy = $derived((loading || refreshing) && !errorMessage);
+
 const columnCount = $derived(
   visibleColumns.length + (selectable ? 1 : 0) + (expandedContent ? 1 : 0),
 );
+const overflowRegionLabel = $derived(
+  caption
+    ? t(M['ui.data_table.overflow_region'], { caption })
+    : t(M['ui.data_table.default_overflow_region']),
+);
 
-// Get cell value
 function getCellValue(row: T, column: DataTableColumn<T>): unknown {
   const accessor = column.accessor ?? column.id;
   return getNestedValue(row, String(accessor));
 }
 
-// Size classes
+function widthForColumn(
+  column: DataTableResolvedColumn<T>,
+): string | undefined {
+  return column.width === undefined ? column.column.width : `${column.width}px`;
+}
+
+function observeColumnWidth(node: HTMLElement, initialColumnId: string) {
+  let columnId = initialColumnId;
+  const recordWidth = () => {
+    const width = Math.ceil(node.getBoundingClientRect().width);
+    if (width <= 0 || measuredColumnWidths[columnId] === width) return;
+    measuredColumnWidths = { ...measuredColumnWidths, [columnId]: width };
+  };
+  recordWidth();
+  if (typeof ResizeObserver === 'undefined') return;
+  const observer = new ResizeObserver(recordWidth);
+  observer.observe(node);
+  return {
+    update(nextColumnId: string) {
+      columnId = nextColumnId;
+      recordWidth();
+    },
+    destroy() {
+      observer.disconnect();
+    },
+  };
+}
+
+function numberFromCssPixels(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const match = /^(\d+(?:\.\d+)?)(px|rem)$/.exec(value.trim());
+  if (!match) return undefined;
+  const number = Number(match[1]);
+  if (match[2] === 'px') return number;
+  const rootFontSize =
+    typeof document === 'undefined'
+      ? undefined
+      : /^\d+(?:\.\d+)?px$/.exec(
+          getComputedStyle(document.documentElement).fontSize.trim(),
+        );
+  return number * (rootFontSize ? Number(rootFontSize[0].slice(0, -2)) : 16);
+}
+
+function minimumWidth(column: DataTableColumn<T>): number {
+  return numberFromCssPixels(column.minWidth) ?? 40;
+}
+
+function maximumWidth(column: DataTableColumn<T>): number | undefined {
+  return numberFromCssPixels(column.maxWidth);
+}
+
+function clampedColumnWidth(column: DataTableColumn<T>, width: number): number {
+  const maximum = maximumWidth(column);
+  return Math.min(
+    Math.max(minimumWidth(column), Math.round(width)),
+    maximum ?? Infinity,
+  );
+}
+
+function currentColumnWidth(
+  resolved: DataTableResolvedColumn<T>,
+  target?: EventTarget | null,
+): number {
+  const measuredWidth = measuredColumnWidths[resolved.column.id];
+  if (measuredWidth !== undefined && measuredWidth > 0) return measuredWidth;
+  if (resolved.width !== undefined) return resolved.width;
+  const staticWidth = numberFromCssPixels(resolved.column.width);
+  if (staticWidth !== undefined) return staticWidth;
+  const header = target instanceof Element ? target.closest('th') : undefined;
+  return header?.getBoundingClientRect().width ?? 160;
+}
+
+function setColumnWidth(column: DataTableColumn<T>, width: number) {
+  dispatch({
+    type: 'setColumnWidth',
+    columnId: column.id,
+    width: clampedColumnWidth(column, width),
+  });
+}
+
+function handleResizeKeydown(
+  event: KeyboardEvent,
+  resolved: DataTableResolvedColumn<T>,
+) {
+  const step = event.shiftKey ? 32 : 8;
+  const current = currentColumnWidth(resolved, event.currentTarget);
+  const maximum = maximumWidth(resolved.column);
+  const next =
+    event.key === 'ArrowLeft'
+      ? current - step
+      : event.key === 'ArrowRight'
+        ? current + step
+        : event.key === 'Home'
+          ? minimumWidth(resolved.column)
+          : event.key === 'End' && maximum !== undefined
+            ? maximum
+            : undefined;
+  if (next === undefined) return;
+  event.preventDefault();
+  setColumnWidth(resolved.column, next);
+}
+
+function handleResizePointerDown(
+  event: PointerEvent,
+  resolved: DataTableResolvedColumn<T>,
+) {
+  if (event.button !== 0) return;
+  event.preventDefault();
+  event.stopPropagation();
+  const handle = event.currentTarget as HTMLElement;
+  const startX = event.clientX;
+  const startWidth = currentColumnWidth(resolved, handle);
+  handle.setPointerCapture?.(event.pointerId);
+  const update = (nextEvent: PointerEvent) =>
+    setColumnWidth(resolved.column, startWidth + nextEvent.clientX - startX);
+  const finish = () => {
+    handle.removeEventListener('pointermove', update);
+    handle.removeEventListener('pointerup', finish);
+    handle.removeEventListener('pointercancel', finish);
+  };
+  handle.addEventListener('pointermove', update);
+  handle.addEventListener('pointerup', finish, { once: true });
+  handle.addEventListener('pointercancel', finish, { once: true });
+}
+
+function structuralLabelColumnId(
+  row: DataTableStructuralRow<T>,
+): string | undefined {
+  if (
+    row.labelColumnId &&
+    visibleColumns.some((column) => column.column.id === row.labelColumnId)
+  ) {
+    return row.labelColumnId;
+  }
+  return visibleColumns[0]?.column.id;
+}
+
+function structuralRowLabel(row: DataTableStructuralRow<T>): string {
+  const kind =
+    row.kind === 'summary'
+      ? t(M['ui.data_table.summary'])
+      : row.kind === 'subtotal'
+        ? t(M['ui.data_table.subtotal'])
+        : row.kind === 'aggregate'
+          ? t(M['ui.data_table.aggregate'])
+          : t(M['ui.data_table.footer_row']);
+  return t(M['ui.data_table.structural_row'], { kind, label: row.label });
+}
+
+function structuralCellValue(
+  row: DataTableStructuralRow<T>,
+  column: DataTableColumn<T>,
+): unknown {
+  return (
+    row.values?.[column.id] ??
+    (column.id === structuralLabelColumnId(row) ? row.label : '')
+  );
+}
+
 const sizeClasses = {
   sm: 'data-table--sm',
   md: 'data-table--md',
   lg: 'data-table--lg',
 };
+
+$effect(() => {
+  const container = tableContainer;
+  void columnCount;
+  void displayRows.length;
+  if (!container) return;
+
+  const resizeObserver =
+    typeof ResizeObserver === 'undefined'
+      ? undefined
+      : new ResizeObserver(updateOverflowState);
+  resizeObserver?.observe(container);
+  const table = container.querySelector('table');
+  if (table) resizeObserver?.observe(table);
+  window.addEventListener('resize', updateOverflowState);
+  updateOverflowState();
+
+  return () => {
+    resizeObserver?.disconnect();
+    window.removeEventListener('resize', updateOverflowState);
+  };
+});
 </script>
 
 {#if toolbar}<div class="data-table-toolbar">{@render toolbar()}</div>{/if}
-<div class="data-table-container" class:data-table-container--sticky={stickyHeader}>
+<!-- svelte-ignore a11y_no_noninteractive_tabindex: the region provides horizontal or virtual keyboard scrolling. -->
+<div
+  bind:this={tableContainer}
+  class="data-table-container"
+  class:data-table-container--sticky={stickyHeader || virtualizedBody}
+  class:data-table-container--overflowing={hasHorizontalOverflow}
+  class:data-table-container--virtualized={virtualizationWindow.enabled}
+  style:height={virtualContainerHeight === undefined ? undefined : `${virtualContainerHeight}px`}
+  tabindex={virtualizationWindow.enabled || hasHorizontalOverflow ? 0 : undefined}
+  role={virtualizationWindow.enabled || hasHorizontalOverflow ? 'region' : undefined}
+  aria-label={virtualizationWindow.enabled
+    ? caption
+      ? t(M['ui.data_table.virtual_region'], { caption })
+      : t(M['ui.data_table.default_virtual_region'])
+    : hasHorizontalOverflow
+      ? overflowRegionLabel
+      : undefined}
+  onscroll={(event) => {
+    updateOverflowState();
+    handleTableScroll(event);
+  }}
+  onkeydown={(event) => {
+    handleVirtualizationKeydown(event);
+    if (!event.defaultPrevented) handleOverflowKeydown(event);
+  }}
+>
   <table
     class="data-table {sizeClasses[size]}"
     class:data-table--striped={striped}
+    class:data-table--virtualized={virtualizationWindow.enabled}
     class:data-table--hoverable={hoverable}
     class:data-table--dense={dense}
-    class:data-table--loading={loading}
+    class:data-table--loading={isInitialLoading}
+    aria-busy={isBusy}
+    aria-rowcount={virtualizationWindow.enabled
+      ? virtualRowCount + headerRowCount + structuralRowCount
+      : undefined}
+    style={`--data-table-caption-height: ${virtualCaptionHeight}px`}
   >
     {#if caption}
-      <caption class="data-table__caption">{caption}</caption>
+      <caption bind:this={tableCaption} class="data-table__caption">{caption}</caption>
     {/if}
 
-    <thead class="data-table__head">
-      <tr class="data-table__row data-table__row--header">
-        {#if expandedContent}<th class="data-table__cell data-table__cell--expand" scope="col"><span class="sr-only">Expand</span></th>{/if}
-        {#if selectable}
-          <th class="data-table__cell data-table__cell--checkbox" scope="col">
-            <input
-              type="checkbox"
-              checked={allSelected}
-              use:setIndeterminate={someSelected}
-              onchange={handleSelectAll}
-              aria-label={t(M['ui.data_table.select_all'])}
-              class="data-table__checkbox"
-            />
-          </th>
-        {/if}
+    <thead bind:this={tableHead} class="data-table__head">
+      {#each dataTableLayout.headerRows as headerRow, headerIndex (headerIndex)}
+        <tr class="data-table__row data-table__row--header">
+          {#if headerIndex === 0 && expandedContent}
+            <th class="data-table__cell data-table__cell--expand" scope="col" rowspan={headerRowCount}>
+              <span class="sr-only"><Trans key={M['ui.data_table.expand']} /></span>
+            </th>
+          {/if}
+          {#if headerIndex === 0 && selectable}
+            <th class="data-table__cell data-table__cell--checkbox" scope="col" rowspan={headerRowCount}>
+              <input
+                type="checkbox"
+                checked={allSelected}
+                use:setIndeterminate={someSelected}
+                onchange={handleSelectAll}
+                aria-label={t(M['ui.data_table.select_current_page'])}
+                class="data-table__checkbox"
+              />
+            </th>
+          {/if}
 
-        {#each visibleColumns as column (column.id)}
-          <th
-            class="data-table__cell data-table__cell--header"
-            class:data-table__cell--sortable={sortable && column.sortable}
-            class:data-table__cell--sorted={sort.columnId === column.id}
-            style:width={column.width}
-            style:min-width={column.minWidth}
-            style:max-width={column.maxWidth}
-            style:text-align={column.align}
-            scope="col"
-            aria-sort={sort.columnId === column.id
-              ? sort.direction === 'asc'
-                ? 'ascending'
-                : 'descending'
-              : undefined}
-          >
-            {#if column.header}
-              {@render column.header({ column })}
-            {:else if sortable && column.sortable}
-              <button
-                type="button"
-                class="data-table__sort-button"
-                onclick={() => handleSort(column)}
+          {#each headerRow as headerCell, cellIndex (`${headerIndex}:${cellIndex}`)}
+            {#if headerCell.kind === 'group'}
+              <th
+                class="data-table__cell data-table__cell--header data-table__cell--header-group"
+                class:data-table__cell--pinned-start={headerCell.pin === 'start'}
+                class:data-table__cell--pinned-end={headerCell.pin === 'end'}
+                scope="colgroup"
+                colspan={headerCell.colspan}
+                rowspan={headerCell.rowspan}
+                style:left={headerCell.pin === 'start' ? headerCell.stickyOffset : undefined}
+                style:right={headerCell.pin === 'end' ? headerCell.stickyOffset : undefined}
               >
-                <span>{column.label}</span>
-                <span class="data-table__sort-icon" aria-hidden="true">
-                  {#if sort.columnId === column.id}
-                    {sort.direction === 'asc' ? '↑' : '↓'}
+                {headerCell.label}
+              </th>
+            {:else}
+              {@const resolvedColumn = headerCell.column}
+              {@const column = resolvedColumn.column}
+              <th
+                class="data-table__cell data-table__cell--header"
+                class:data-table__cell--sortable={usesAutomaticSortButton(column)}
+                class:data-table__cell--sorted={currentSort.columnId === column.id}
+                class:data-table__cell--pinned-start={resolvedColumn.pin === 'start'}
+                class:data-table__cell--pinned-end={resolvedColumn.pin === 'end'}
+                data-column-id={column.id}
+                data-column-role={column.role}
+                data-responsive-priority={column.responsive?.priority}
+                data-keep-visible={column.responsive?.keepVisible ? 'true' : undefined}
+                use:observeColumnWidth={column.id}
+                style:width={widthForColumn(resolvedColumn)}
+                style:min-width={column.minWidth}
+                style:max-width={column.maxWidth}
+                style:left={resolvedColumn.pin === 'start' ? resolvedColumn.stickyOffset : undefined}
+                style:right={resolvedColumn.pin === 'end' ? resolvedColumn.stickyOffset : undefined}
+                style:text-align={column.align}
+                scope="col"
+                rowspan={headerCell.rowspan}
+                aria-label={column.resizable && !column.header
+                  ? column.label
+                  : undefined}
+                aria-sort={currentSort.columnId === column.id
+                  ? currentSort.direction === 'asc'
+                    ? 'ascending'
+                    : 'descending'
+                  : undefined}
+              >
+                {#if usesAutomaticSortButton(column)}
+                  {#if column.header}
+                    <div class="data-table__header-content">
+                      {@render column.header({ column })}
+                      <button
+                        type="button"
+                        class="data-table__sort-button"
+                        onclick={(event) => handleSort(column, event)}
+                        aria-label={sortActionLabel(column)}
+                      >
+                        <span class="data-table__sort-icon" aria-hidden="true">
+                          {#if currentSort.columnId === column.id}
+                            {currentSort.direction === 'asc' ? '↑' : '↓'}
+                          {:else}
+                            ↕
+                          {/if}
+                        </span>
+                      </button>
+                    </div>
                   {:else}
-                    ↕
+                    <button
+                      type="button"
+                      class="data-table__sort-button"
+                      onclick={(event) => handleSort(column, event)}
+                      aria-label={sortActionLabel(column)}
+                    >
+                      <span>{column.label}</span>
+                      <span class="data-table__sort-icon" aria-hidden="true">
+                        {#if currentSort.columnId === column.id}
+                          {currentSort.direction === 'asc' ? '↑' : '↓'}
+                        {:else}
+                          ↕
+                        {/if}
+                      </span>
+                    </button>
                   {/if}
-                </span>
-              </button>
-            {:else}
-              {column.label}
+                {:else if column.header}
+                  {@render column.header({ column })}
+                {:else}
+                  {column.label}
+                {/if}
+                {#if column.resizable}
+                  <!-- svelte-ignore a11y_no_noninteractive_element_interactions: a focusable ARIA separator is the resize control. -->
+                  <span
+                    class="data-table__resize-handle"
+                    role="separator"
+                    aria-orientation="vertical"
+                    aria-label={t(M['ui.data_table.resize_column'], { column: column.label })}
+                    aria-valuemin={minimumWidth(column)}
+                    aria-valuemax={maximumWidth(column)}
+                    aria-valuenow={Math.round(currentColumnWidth(resolvedColumn))}
+                    tabindex="0"
+                    onpointerdown={(event) => handleResizePointerDown(event, resolvedColumn)}
+                    onkeydown={(event) => handleResizeKeydown(event, resolvedColumn)}
+                  ></span>
+                {/if}
+              </th>
             {/if}
-          </th>
-        {/each}
-      </tr>
+          {/each}
+        </tr>
+      {/each}
     </thead>
 
-    <tbody class="data-table__body">
-      {#if loading}
+    <tbody bind:this={tableBody} class="data-table__body">
+      {#if errorMessage && !hasRenderedRows}
+        <tr class="data-table__row data-table__row--error">
+          <td
+            class="data-table__cell data-table__cell--error"
+            colspan={columnCount}
+          >
+            <div class="data-table__error-state" role="alert">
+              <span>{errorMessage}</span>
+              {#if onRetry}
+                <button type="button" class="data-table__retry-button" onclick={onRetry}>
+                  {t(M['ui.data_table.retry'])}
+                </button>
+              {/if}
+            </div>
+          </td>
+        </tr>
+      {:else if isInitialLoading}
         <tr class="data-table__row data-table__row--loading">
           <td
             class="data-table__cell data-table__cell--loading"
             colspan={columnCount}
           >
-            <div class="data-table__loading-indicator">
+            <div class="data-table__loading-indicator" role="status" aria-live="polite">
               <span class="data-table__spinner"></span>
               <span><Trans key={M['ui.data_table.loading']} /></span>
             </div>
           </td>
         </tr>
-      {:else if displayData.length === 0}
+      {:else if displayRows.length === 0}
         <tr class="data-table__row data-table__row--empty">
           <td
             class="data-table__cell data-table__cell--empty"
@@ -333,27 +1271,37 @@ const sizeClasses = {
           </td>
         </tr>
       {:else}
-        {#each displayData as row, index (getDisplayRowKey(row, index))}
-          {@const key = getDisplayRowKey(row, index)}
-          {@const isSelected = selected.has(key)}
-          {@const isExpanded = expanded.has(key)}
-          {@const rowCanExpand = canExpand?.(row, index) ?? true}
+        {#if virtualizationWindow.topSpacerHeight > 0}
+          <tr class="data-table__virtual-spacer" aria-hidden="true">
+            <td colspan={columnCount} style:height={`${virtualizationWindow.topSpacerHeight}px`}></td>
+          </tr>
+        {/if}
+        {#each renderedRows as entry, index (entry.rowId)}
+          {@const row = entry.row}
+          {@const key = entry.rowId}
+          {@const displayIndex = virtualizationWindow.startIndex + index}
+          {@const isSelected = tableState.selection.scope === 'allMatching' || selectedIds.has(key)}
+          {@const isExpanded = expandedIds.has(key)}
+          {@const rowCanExpand = canExpand?.(row, displayIndex) ?? true}
           <tr
-            class="data-table__row {rowClass?.(row, index) ?? ''}"
+            class="data-table__row {rowClass?.(row, displayIndex) ?? ''}"
             class:data-table__row--selected={isSelected}
-            onclick={() => handleRowClick(row, index)}
-            role={onRowClick ? 'button' : undefined}
-            tabindex={onRowClick ? 0 : undefined}
-            onkeydown={(e) => {
-              if (onRowClick && (e.key === 'Enter' || e.key === ' ')) {
-                e.preventDefault();
-                handleRowClick(row, index);
-              }
-            }}
+            class:data-table__row--striped={
+              virtualizationWindow.enabled && striped && displayIndex % 2 === 1
+            }
+            class:data-table__row--interactive={Boolean(onRowClick)}
+            data-row-id={dataTableRowIdKey(key)}
+            aria-rowindex={virtualizationWindow.enabled
+              ? virtualRowOffset + displayIndex + headerRowCount + 1
+              : undefined}
+            onclick={(event) => handleRowActivation(event, row, displayIndex)}
+            tabindex={onRowClick || virtualizationWindow.enabled ? 0 : undefined}
+            onfocusin={() => handleRowFocus(key)}
+            onkeydown={(event) => handleRowKeydown(event, row, displayIndex)}
           >
             {#if expandedContent}
               <td class="data-table__cell data-table__cell--expand">
-                {#if rowCanExpand}<button type="button" class="data-table__expand-button" aria-label={isExpanded ? 'Collapse row' : 'Expand row'} aria-expanded={isExpanded} onclick={(event) => handleExpanded(key, event)}>{isExpanded ? '−' : '+'}</button>{/if}
+                {#if rowCanExpand}<button type="button" class="data-table__expand-button" aria-label={isExpanded ? t(M['ui.data_table.collapse_row'], { row: getRowLabel(row, displayIndex) }) : t(M['ui.data_table.expand_row'], { row: getRowLabel(row, displayIndex) })} aria-expanded={isExpanded} aria-controls={expansionContentId(key)} onclick={(event) => handleExpanded(key, event)}>{isExpanded ? '−' : '+'}</button>{/if}
               </td>
             {/if}
             {#if selectable}
@@ -361,23 +1309,36 @@ const sizeClasses = {
                 <input
                   type="checkbox"
                   checked={isSelected}
+                  disabled={tableState.selection.scope === 'allMatching'}
                   onchange={(e) => handleRowSelect(key, e)}
-                  aria-label={t(M['ui.data_table.select_row'])}
+                  aria-label={isSelected ? t(M['ui.data_table.deselect_row'], { row: getRowLabel(row, displayIndex) }) : t(M['ui.data_table.select_row'], { row: getRowLabel(row, displayIndex) })}
                   class="data-table__checkbox"
                 />
               </td>
             {/if}
 
-            {#each visibleColumns as column (column.id)}
+            {#each visibleColumns as resolvedColumn (resolvedColumn.column.id)}
+              {@const column = resolvedColumn.column}
               {@const value = getCellValue(row, column)}
               <td
                 class="data-table__cell {column.className ?? ''}"
+                class:data-table__cell--pinned-start={resolvedColumn.pin === 'start'}
+                class:data-table__cell--pinned-end={resolvedColumn.pin === 'end'}
+                data-column-id={column.id}
+                data-column-role={column.role}
+                data-responsive-priority={column.responsive?.priority}
+                data-keep-visible={column.responsive?.keepVisible ? 'true' : undefined}
+                style:width={widthForColumn(resolvedColumn)}
+                style:min-width={column.minWidth}
+                style:max-width={column.maxWidth}
+                style:left={resolvedColumn.pin === 'start' ? resolvedColumn.stickyOffset : undefined}
+                style:right={resolvedColumn.pin === 'end' ? resolvedColumn.stickyOffset : undefined}
                 style:text-align={column.align}
               >
                 {#if cell}
-                  {@render cell({ column, row, value, index })}
+                  {@render cell({ column, row, value, index: displayIndex })}
                 {:else if column.cell}
-                  {@render column.cell({ row, value, index })}
+                  {@render column.cell({ row, value, index: displayIndex })}
                 {:else}
                   {value ?? ''}
                 {/if}
@@ -385,26 +1346,206 @@ const sizeClasses = {
             {/each}
           </tr>
           {#if expandedContent && isExpanded}
-            <tr class="data-table__row data-table__row--expanded">
-              <td class="data-table__cell data-table__cell--expanded" colspan={columnCount}>{@render expandedContent({ row, index })}</td>
+            <tr id={expansionContentId(key)} class="data-table__row data-table__row--expanded">
+              <td class="data-table__cell data-table__cell--expanded" colspan={columnCount}>{@render expandedContent({ row, index: displayIndex })}</td>
             </tr>
           {/if}
         {/each}
+        {#if virtualizationWindow.bottomSpacerHeight > 0}
+          <tr class="data-table__virtual-spacer" aria-hidden="true">
+            <td colspan={columnCount} style:height={`${virtualizationWindow.bottomSpacerHeight}px`}></td>
+          </tr>
+        {/if}
       {/if}
     </tbody>
-    {#if footer}
-      <tfoot><tr><td class="data-table__cell data-table__footer" colspan={columnCount}>{@render footer({ rows: displayData })}</td></tr></tfoot>
+    {#if dataBodyStructuralRows.length > 0}
+      <tbody
+        bind:this={tableStructuralBody}
+        class="data-table__body data-table__body--structural"
+      >
+        {#each dataBodyStructuralRows as structuralRow, structuralIndex (structuralRow.id)}
+          {@const labelColumnId = structuralLabelColumnId(structuralRow)}
+          <tr
+            class="data-table__row data-table__row--structural"
+            data-row-kind={structuralRow.kind}
+            aria-label={structuralRowLabel(structuralRow)}
+            aria-rowindex={virtualizationWindow.enabled
+              ? virtualRowOffset + displayRows.length + headerRowCount + structuralIndex + 1
+              : undefined}
+          >
+            {#if expandedContent}<td class="data-table__cell data-table__cell--expand"></td>{/if}
+            {#if selectable}<td class="data-table__cell data-table__cell--checkbox"></td>{/if}
+            {#each visibleColumns as resolvedColumn (resolvedColumn.column.id)}
+              {@const column = resolvedColumn.column}
+              {@const value = structuralCellValue(structuralRow, column)}
+              {#if column.id === labelColumnId}
+                <th
+                  class="data-table__cell data-table__cell--structural-label {column.className ?? ''}"
+                  class:data-table__cell--pinned-start={resolvedColumn.pin === 'start'}
+                  class:data-table__cell--pinned-end={resolvedColumn.pin === 'end'}
+                  scope="row"
+                  data-column-id={column.id}
+                  style:width={widthForColumn(resolvedColumn)}
+                  style:min-width={column.minWidth}
+                  style:max-width={column.maxWidth}
+                  style:left={resolvedColumn.pin === 'start' ? resolvedColumn.stickyOffset : undefined}
+                  style:right={resolvedColumn.pin === 'end' ? resolvedColumn.stickyOffset : undefined}
+                  style:text-align={column.align}
+                >
+                  <span class="sr-only">{structuralRowLabel(structuralRow)}: </span>
+                  {#if structuralRow.cell}
+                    {@render structuralRow.cell({ row: structuralRow, column, value })}
+                  {:else}
+                    {value ?? ''}
+                  {/if}
+                </th>
+              {:else}
+                <td
+                  class="data-table__cell {column.className ?? ''}"
+                  class:data-table__cell--pinned-start={resolvedColumn.pin === 'start'}
+                  class:data-table__cell--pinned-end={resolvedColumn.pin === 'end'}
+                  data-column-id={column.id}
+                  style:width={widthForColumn(resolvedColumn)}
+                  style:min-width={column.minWidth}
+                  style:max-width={column.maxWidth}
+                  style:left={resolvedColumn.pin === 'start' ? resolvedColumn.stickyOffset : undefined}
+                  style:right={resolvedColumn.pin === 'end' ? resolvedColumn.stickyOffset : undefined}
+                  style:text-align={column.align}
+                >
+                  {#if structuralRow.cell}
+                    {@render structuralRow.cell({ row: structuralRow, column, value })}
+                  {:else}
+                    {value ?? ''}
+                  {/if}
+                </td>
+              {/if}
+            {/each}
+          </tr>
+        {/each}
+      </tbody>
+    {/if}
+    {#if footer || footerStructuralRows.length > 0}
+      <tfoot bind:this={tableFooter}>
+        {#each footerStructuralRows as structuralRow, structuralIndex (structuralRow.id)}
+          {@const labelColumnId = structuralLabelColumnId(structuralRow)}
+          <tr
+            class="data-table__row data-table__row--structural data-table__row--footer"
+            data-row-kind={structuralRow.kind}
+            aria-label={structuralRowLabel(structuralRow)}
+            aria-rowindex={virtualizationWindow.enabled
+              ? virtualRowCount + headerRowCount + dataBodyStructuralRows.length + structuralIndex + 1
+              : undefined}
+          >
+            {#if expandedContent}<td class="data-table__cell data-table__cell--expand"></td>{/if}
+            {#if selectable}<td class="data-table__cell data-table__cell--checkbox"></td>{/if}
+            {#each visibleColumns as resolvedColumn (resolvedColumn.column.id)}
+              {@const column = resolvedColumn.column}
+              {@const value = structuralCellValue(structuralRow, column)}
+              {#if column.id === labelColumnId}
+                <th
+                  class="data-table__cell data-table__cell--structural-label {column.className ?? ''}"
+                  class:data-table__cell--pinned-start={resolvedColumn.pin === 'start'}
+                  class:data-table__cell--pinned-end={resolvedColumn.pin === 'end'}
+                  scope="row"
+                  data-column-id={column.id}
+                  style:width={widthForColumn(resolvedColumn)}
+                  style:min-width={column.minWidth}
+                  style:max-width={column.maxWidth}
+                  style:left={resolvedColumn.pin === 'start' ? resolvedColumn.stickyOffset : undefined}
+                  style:right={resolvedColumn.pin === 'end' ? resolvedColumn.stickyOffset : undefined}
+                  style:text-align={column.align}
+                >
+                  <span class="sr-only">{structuralRowLabel(structuralRow)}: </span>
+                  {#if structuralRow.cell}
+                    {@render structuralRow.cell({ row: structuralRow, column, value })}
+                  {:else}
+                    {value ?? ''}
+                  {/if}
+                </th>
+              {:else}
+                <td
+                  class="data-table__cell {column.className ?? ''}"
+                  class:data-table__cell--pinned-start={resolvedColumn.pin === 'start'}
+                  class:data-table__cell--pinned-end={resolvedColumn.pin === 'end'}
+                  data-column-id={column.id}
+                  style:width={widthForColumn(resolvedColumn)}
+                  style:min-width={column.minWidth}
+                  style:max-width={column.maxWidth}
+                  style:left={resolvedColumn.pin === 'start' ? resolvedColumn.stickyOffset : undefined}
+                  style:right={resolvedColumn.pin === 'end' ? resolvedColumn.stickyOffset : undefined}
+                  style:text-align={column.align}
+                >
+                  {#if structuralRow.cell}
+                    {@render structuralRow.cell({ row: structuralRow, column, value })}
+                  {:else}
+                    {value ?? ''}
+                  {/if}
+                </td>
+              {/if}
+            {/each}
+          </tr>
+        {/each}
+        {#if footer}
+          <tr aria-rowindex={virtualizationWindow.enabled
+            ? virtualRowCount + headerRowCount + structuralRowCount
+            : undefined}>
+            <td class="data-table__cell data-table__footer" colspan={columnCount}>
+              {@render footer({ rows: displayRows.map(({ row }) => row) })}
+            </td>
+          </tr>
+        {/if}
+      </tfoot>
     {/if}
   </table>
+  {#if errorMessage && hasRenderedRows}
+    <div class="data-table__async-status data-table__async-status--error" role="alert">
+      <span>{errorMessage}</span>
+      {#if onRetry}
+        <button type="button" class="data-table__retry-button" onclick={onRetry}>
+          {t(M['ui.data_table.retry'])}
+        </button>
+      {/if}
+    </div>
+  {:else if isRefreshing || stale || partialResults}
+    <div class="data-table__async-status" role="status" aria-live="polite" aria-atomic="true">
+      {#if isRefreshing}<span>{t(M['ui.data_table.refreshing'])}</span>{/if}
+      {#if stale}<span>{t(M['ui.data_table.stale'])}</span>{/if}
+      {#if partialResults}<span>{t(M['ui.data_table.partial_results'])}</span>{/if}
+    </div>
+  {/if}
 </div>
-{#if pageSize && totalPages > 1}<Pagination currentPage={page} {totalPages} onPageChange={handlePageChange} aria-label="Table pages" />{/if}
+{#if hasHorizontalOverflow}
+  <div class="data-table__overflow-cue" aria-hidden="true">
+    {#if canScrollLeft}<span>← {t(M['ui.data_table.more_columns'])}</span>{/if}
+    {#if canScrollRight}<span>{t(M['ui.data_table.more_columns'])} →</span>{/if}
+  </div>
+{/if}
+{#if tableState.pageSize && totalPages && totalPages > 1}<Pagination currentPage={tableState.page} {totalPages} onPageChange={handlePageChange} aria-label={t(M['ui.data_table.pagination'])} />{/if}
 
 <style>
   .data-table-container {
+    position: relative;
     width: 100%;
     overflow-x: auto;
   }
 
+  .data-table-container--overflowing:focus-visible {
+    outline: 2px solid var(--smrt-color-primary, #3b82f6);
+    outline-offset: 2px;
+  }
+
+  .data-table__overflow-cue {
+    display: flex;
+    justify-content: space-between;
+    padding: var(--smrt-spacing-2, 0.5rem) var(--smrt-spacing-3, 0.75rem);
+    border-top: 1px solid var(--smrt-color-outline-variant, #e5e7eb);
+    background: var(--smrt-color-surface-container-low, #f9fafb);
+    color: var(--smrt-color-on-surface-variant, #6b7280);
+    font-size: var(--smrt-typography-label-small-size, 0.75rem);
+    font-weight: var(--smrt-typography-weight-medium, 500);
+    pointer-events: none;
+  }
+
   .data-table-toolbar { margin-bottom: var(--smrt-spacing-2); }
 
   .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
@@ -414,6 +1555,23 @@ const sizeClasses = {
     overflow-y: auto;
   }
 
+  .data-table-container--virtualized {
+    overflow: auto;
+  }
+
+  /* Keep structural context fixed so scrollTop is measured from data row zero. */
+  .data-table-container--virtualized .data-table__caption {
+    position: sticky;
+    top: 0;
+    z-index: 2;
+  }
+
+  .data-table-container--sticky.data-table-container--virtualized .data-table__head {
+    position: sticky;
+    top: var(--data-table-caption-height, 0px);
+    z-index: 1;
+  }
+
   .data-table {
     width: 100%;
     border-collapse: collapse;
@@ -448,6 +1606,7 @@ const sizeClasses = {
   }
 
   .data-table__cell--header {
+    position: relative;
     padding: var(--smrt-spacing-3, 0.75rem) var(--smrt-spacing-4, 1rem);
     font-weight: var(--smrt-typography-weight-semibold, 600);
     text-align: left;
@@ -473,6 +1632,45 @@ const sizeClasses = {
     cursor: pointer;
   }
 
+  .data-table__header-content {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--smrt-spacing-1, 0.25rem);
+  }
+
+  .data-table__cell--header-group {
+    color: var(--smrt-color-on-surface-variant, #6b7280);
+    font: var(--smrt-typography-label-medium-font);
+    letter-spacing: 0.02em;
+  }
+
+  .data-table__resize-handle {
+    position: absolute;
+    top: 0;
+    right: -0.35rem;
+    z-index: 3;
+    display: block;
+    width: 0.7rem;
+    height: 100%;
+    cursor: col-resize;
+    touch-action: none;
+  }
+
+  .data-table__resize-handle::after {
+    position: absolute;
+    top: 20%;
+    right: 0.3rem;
+    width: 1px;
+    height: 60%;
+    background: var(--smrt-color-outline, #9ca3af);
+    content: '';
+  }
+
+  .data-table__resize-handle:focus-visible {
+    outline: 2px solid var(--smrt-color-primary, #3b82f6);
+    outline-offset: -2px;
+  }
+
   .data-table__sort-button:hover {
     color: var(--smrt-color-primary, #3b82f6);
   }
@@ -497,6 +1695,11 @@ const sizeClasses = {
     transition: background-color var(--smrt-duration-fast, 150ms) var(--smrt-easing-standard, ease);
   }
 
+  .data-table__virtual-spacer td {
+    padding: 0;
+    border: 0;
+  }
+
   .data-table--hoverable .data-table__row:hover:not(.data-table__row--loading):not(.data-table__row--empty) {
     background: var(--smrt-color-surface-container-low, #f9fafb);
   }
@@ -505,15 +1708,21 @@ const sizeClasses = {
     background: var(--smrt-color-primary-container, #dbeafe) !important;
   }
 
-  .data-table--striped .data-table__row:nth-child(even) {
+  .data-table--striped:not(.data-table--virtualized) .data-table__row:nth-child(even),
+  .data-table__row--striped {
     background: var(--smrt-color-surface-container-lowest, #fafafa);
   }
 
-  .data-table__row[role='button'] {
+  .data-table__row--interactive {
     cursor: pointer;
   }
 
-  .data-table__row[role='button']:focus-visible {
+  .data-table__row--interactive:focus-visible {
+    outline: 2px solid var(--smrt-color-primary, #3b82f6);
+    outline-offset: -2px;
+  }
+
+  .data-table-container--virtualized .data-table__row:focus-visible {
     outline: 2px solid var(--smrt-color-primary, #3b82f6);
     outline-offset: -2px;
   }
@@ -523,6 +1732,24 @@ const sizeClasses = {
     vertical-align: middle;
   }
 
+  .data-table__cell--pinned-start,
+  .data-table__cell--pinned-end {
+    position: sticky;
+    z-index: 1;
+    background: var(--smrt-color-surface, #ffffff);
+  }
+
+  .data-table__cell--header.data-table__cell--pinned-start,
+  .data-table__cell--header.data-table__cell--pinned-end {
+    z-index: 3;
+    background: var(--smrt-color-surface-container, #f3f4f6);
+  }
+
+  .data-table__row--selected .data-table__cell--pinned-start,
+  .data-table__row--selected .data-table__cell--pinned-end {
+    background: var(--smrt-color-primary-container, #dbeafe);
+  }
+
   .data-table__cell--checkbox {
     width: 48px;
     text-align: center;
@@ -533,6 +1760,9 @@ const sizeClasses = {
   .data-table__expand-button:focus-visible { outline: 2px solid var(--smrt-color-primary); outline-offset: 2px; }
   .data-table__cell--expanded { padding: var(--smrt-spacing-4); background: var(--smrt-color-surface-container-low); }
   .data-table__footer { border-top: 2px solid var(--smrt-color-outline-variant); font-weight: var(--smrt-typography-weight-medium); }
+  .data-table__row--structural { background: var(--smrt-color-surface-container-low, #f9fafb); }
+  .data-table__row--footer { border-top: 2px solid var(--smrt-color-outline-variant); }
+  .data-table__cell--structural-label { font-weight: var(--smrt-typography-weight-semibold, 600); }
 
   .data-table__checkbox {
     width: 18px;
@@ -543,7 +1773,8 @@ const sizeClasses = {
 
   /* Loading */
   .data-table__cell--loading,
-  .data-table__cell--empty {
+  .data-table__cell--empty,
+  .data-table__cell--error {
     padding: var(--smrt-spacing-8, 2rem);
     text-align: center;
   }
@@ -575,6 +1806,42 @@ const sizeClasses = {
     color: var(--smrt-color-on-surface-variant, #6b7280);
   }
 
+  .data-table__error-state,
+  .data-table__async-status {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-wrap: wrap;
+    gap: var(--smrt-spacing-3, 0.75rem);
+    color: var(--smrt-color-on-surface-variant, #6b7280);
+  }
+
+  .data-table__error-state,
+  .data-table__async-status--error {
+    color: var(--smrt-color-error, #b3261e);
+  }
+
+  .data-table__async-status {
+    padding: var(--smrt-spacing-3, 0.75rem);
+    border-top: 1px solid var(--smrt-color-outline-variant, #e5e7eb);
+    font: var(--smrt-typography-body-small-font);
+  }
+
+  .data-table__retry-button {
+    border: 1px solid currentColor;
+    border-radius: var(--smrt-radius-small, 0.25rem);
+    background: transparent;
+    color: inherit;
+    cursor: pointer;
+    font: inherit;
+    padding: var(--smrt-spacing-1, 0.25rem) var(--smrt-spacing-3, 0.75rem);
+  }
+
+  .data-table__retry-button:focus-visible {
+    outline: 2px solid var(--smrt-color-primary, #3b82f6);
+    outline-offset: 2px;
+  }
+
   /* Size variants */
   .data-table--sm .data-table__cell {
     padding: var(--smrt-spacing-2, 0.5rem) var(--smrt-spacing-3, 0.75rem);
@@ -604,6 +1871,11 @@ const sizeClasses = {
   /* Loading overlay */
   .data-table--loading {
     opacity: 0.7;
-    pointer-events: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .data-table__spinner {
+      animation: none;
+    }
   }
 </style>