@happyvertical/smrt-ui 0.42.4 → 0.42.5

package/dist/components/data/DataTable.svelte

@@ -11,7 +11,7 @@
  * - 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';
@@ -27,9 +27,24 @@ import {
   type DataTableSnapshot,
   type DataTableViewState,
   type DataTableViewStateInput,
+  dataTableRowIdKey,
 } from './DataTableController.js';
 import { resolveDataTableRows } from './DataTableIdentity.js';
-import type { DataTableColumn, DataTableProps, SortState } from './types.js';
+import {
+  type DataTableResolvedColumn,
+  resolveDataTableLayout,
+} from './DataTableLayout.js';
+import {
+  maximumDataTableVirtualScrollTop,
+  resolveDataTableVirtualWindow,
+  scrollTopForDataTableRow,
+} from './DataTableVirtualization.js';
+import type {
+  DataTableColumn,
+  DataTableProps,
+  DataTableStructuralRow,
+  SortState,
+} from './types.js';
 import { defaultSort, getNestedValue } from './types.js';
 
 const { t } = useI18n();
@@ -50,6 +65,7 @@ let {
   selected = $bindable(new Set<string | number>()),
   onSelectionChange,
   onRowClick,
+  rowLabel,
   sortable = false,
   sort = $bindable({ columnId: null, direction: null }),
   onSortChange,
@@ -58,6 +74,7 @@ let {
   page = $bindable(1),
   pageSize,
   manualPagination = false,
+  virtualization,
   totalRows,
   onPageChange,
   expanded = $bindable(new Set<string | number>()),
@@ -66,8 +83,14 @@ let {
   expandedContent,
   toolbar,
   footer,
+  structuralRows = [],
   visibleColumnIds,
   loading = false,
+  refreshing = false,
+  stale = false,
+  partialResults = false,
+  error = null,
+  onRetry,
   empty,
   rowClass,
   size = 'md',
@@ -84,6 +107,8 @@ let {
   modes,
 }: ExtendedProps<T> = $props();
 
+const dataTableId = $props.id();
+
 function legacyModes(): DataTableModes {
   return {
     filtering: modes?.filtering ?? 'local',
@@ -93,21 +118,23 @@ function legacyModes(): DataTableModes {
 }
 
 function legacyViewState(): Partial<DataTableViewState> {
-  return {
+  const next: Partial<DataTableViewState> = {
     sorting:
       sort.columnId && sort.direction
         ? [{ columnId: sort.columnId, direction: sort.direction }]
         : [],
     page,
     pageSize: pageSize ?? null,
-    columnOrder: columns.map((column) => column.id),
-    columnVisibility: columns.map((column) => ({
-      columnId: column.id,
-      visible: !visibleColumnIds || visibleColumnIds.has(column.id),
-    })),
     selectedRowIds: [...selected],
     expandedRowIds: [...expanded],
   };
+  if (visibleColumnIds) {
+    next.columnVisibility = columns.map((column) => ({
+      columnId: column.id,
+      visible: visibleColumnIds.has(column.id),
+    }));
+  }
+  return next;
 }
 
 function mergedLegacyState(): Omit<DataTableViewState, 'selection'> {
@@ -121,8 +148,12 @@ const localController = createDataTableController({
 });
 
 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;
@@ -187,7 +218,14 @@ $effect(() => {
 
   localController.setControlled(controlledState !== undefined);
   localController.setModes(legacyModes());
-  localController.setColumnIds(columns.map((column) => column.id));
+  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;
@@ -196,9 +234,12 @@ $effect(() => {
       ...initialState,
     };
     localController.replaceState(nextState);
+    localController.setColumnIds(columnIds, hiddenColumnIds);
     return;
   }
 
+  localController.setColumnIds(columnIds, hiddenColumnIds);
+
   if (controlledState !== undefined) {
     localController.replaceState(controlledState);
     return;
@@ -214,7 +255,16 @@ $effect(() => {
 
 $effect(() => {
   const current = activeController();
-  current.setColumnIds(columns.map((column) => column.id));
+  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;
@@ -234,13 +284,23 @@ $effect(() => {
 
 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',
+    tableModes.pagination === 'manual' ||
+    Boolean(virtualization),
 );
 const sourceRows = $derived.by(() =>
   resolveDataTableRows(data, rowKey, {
@@ -261,6 +321,25 @@ function handleSort(column: DataTableColumn<T>, event: MouseEvent) {
   });
 }
 
+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 });
+}
+
 function handleRowSelect(key: DataTableRowId, event: Event) {
   event.stopPropagation();
   dispatch({ type: 'toggleRowSelection', rowId: key });
@@ -305,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;
@@ -315,23 +488,22 @@ function setIndeterminate(node: HTMLInputElement, value: boolean) {
   };
 }
 
-const visibleColumns = $derived.by(() => {
-  const configuredOrder = new Map(
-    tableState.columnOrder.map((id, index) => [id, index]),
-  );
-  const visibility = new Map(
-    tableState.columnVisibility.map((entry) => [entry.columnId, entry.visible]),
-  );
-  return columns
-    .filter((column) => !column.hidden && visibility.get(column.id) !== false)
-    .slice()
-    .sort((left, right) => {
-      const leftOrder = configuredOrder.get(left.id) ?? Number.MAX_SAFE_INTEGER;
-      const rightOrder =
-        configuredOrder.get(right.id) ?? Number.MAX_SAFE_INTEGER;
-      return leftOrder - rightOrder;
-    });
-});
+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);
 
 function sameFilterValue(value: unknown, expected: unknown): boolean {
   return Object.is(value, expected);
@@ -466,6 +638,169 @@ const displayRows = $derived.by(() => {
   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 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 });
+  });
+});
+
+$effect(() => {
+  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;
@@ -502,100 +837,419 @@ const someSelected = $derived(
     !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']),
+);
 
 function getCellValue(row: T, column: DataTableColumn<T>): unknown {
   const accessor = column.accessor ?? column.id;
   return getNestedValue(row, String(accessor));
 }
 
+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_current_page'])}
-              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={currentSort.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={currentSort.columnId === column.id
-              ? currentSort.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={(event) => handleSort(column, event)}
+          {#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}
+              >
+                {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}
               >
-                <span>{column.label}</span>
-                <span class="data-table__sort-icon" aria-hidden="true">
-                  {#if currentSort.columnId === column.id}
-                    {currentSort.direction === 'asc' ? '↑' : '↓'}
+                {#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>
@@ -617,28 +1271,37 @@ const sizeClasses = {
           </td>
         </tr>
       {:else}
-        {#each displayRows as entry, index (entry.rowId)}
+        {#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, index) ?? true}
+          {@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}
@@ -648,22 +1311,34 @@ const sizeClasses = {
                   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}
@@ -671,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: displayRows.map(({ row }) => row) })}</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 tableState.pageSize && totalPages && totalPages > 1}<Pagination currentPage={tableState.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; }
@@ -700,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;
@@ -734,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;
@@ -759,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);
   }
@@ -783,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);
   }
@@ -791,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;
   }
@@ -809,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;
@@ -819,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;
@@ -829,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;
   }
@@ -861,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);
@@ -890,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>