@gcsa/console-react 0.1.0

package/src/GcsaDataTable.tsx

@@ -0,0 +1,779 @@
+import { Fragment, useEffect, useMemo, useRef, useState, type CSSProperties, type MouseEvent as ReactMouseEvent, type MutableRefObject, type PointerEvent as ReactPointerEvent, type ReactNode } from 'react';
+import {
+  flexRender,
+  getCoreRowModel,
+  getFilteredRowModel,
+  getExpandedRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type ColumnDef,
+  type ColumnFiltersState,
+  type ExpandedState,
+  type Row,
+  type SortingState
+} from '@tanstack/react-table';
+import type {
+  GcsaLegacyTableColumn,
+  GcsaPaginationAlign,
+  GcsaPaginationLayoutPart,
+  GcsaTableColumn,
+  GcsaTableColumnFixed,
+  GcsaTableColumnInfo
+} from '@gcsa/console-core';
+import {
+  GCSA_TABLE_DEFAULT_COLUMN_MIN_WIDTH,
+  GCSA_TABLE_EXPAND_COLUMN_WIDTH,
+  GCSA_TABLE_SELECTION_COLUMN_WIDTH,
+  formatGcsaLocaleMessage,
+  getGcsaTableFixedOffset,
+  getGcsaTableDefaultExpandedKeys,
+  getGcsaTableMinWidth,
+  getGcsaTableRowId,
+  getGcsaTableSortChange,
+  getGcsaTableSorting,
+  normalizeGcsaTableColumns
+} from '@gcsa/console-core';
+import { GcsaCheckbox } from './GcsaCheckbox';
+import { GcsaEmpty } from './GcsaEmpty';
+import { GcsaIcon } from './GcsaIcon';
+import { GcsaInput } from './GcsaInput';
+import { GcsaPagination } from './GcsaPagination';
+import { GcsaSelect } from './GcsaSelect';
+import { GcsaSpin } from './GcsaSpin';
+import { formatGcsaTableCellValue, resolveGcsaTableColumns } from './utils/gcsaTableColumns';
+import { useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+import { useGcsaComponentSize } from './hooks/useGcsaComponentSize';
+
+type TableMeta = {
+  width?: string;
+  minWidth?: string;
+  align?: 'left' | 'center' | 'right';
+  slotKey?: string;
+  fixed?: GcsaTableColumnFixed;
+  hidden?: boolean;
+  showOverflowTooltip?: boolean;
+  filter?: { type: 'text' | 'select'; placeholder?: string; options?: Array<{ label: string; value: string; disabled?: boolean }> };
+};
+
+function childColumns<T extends Record<string, unknown>>(column: ColumnDef<T, unknown>): ColumnDef<T, unknown>[] {
+  return 'columns' in column && Array.isArray(column.columns)
+    ? column.columns as ColumnDef<T, unknown>[]
+    : [];
+}
+
+function flattenColumns<T extends Record<string, unknown>>(columns: ColumnDef<T, unknown>[]): ColumnDef<T, unknown>[] {
+  return columns.flatMap(column => {
+    const children = childColumns(column);
+    return children.length ? flattenColumns(children) : [column];
+  });
+}
+
+function filterColumnTree<T extends Record<string, unknown>>(columns: ColumnDef<T, unknown>[], visibility: Record<string, boolean>): ColumnDef<T, unknown>[] {
+  return columns.flatMap(column => {
+    const meta = metaOf(column);
+    if (meta.hidden || visibility[column.id ?? ''] === false) return [];
+    const columnChildren = childColumns(column);
+    if (!columnChildren.length) return [column];
+    const children = filterColumnTree(columnChildren, visibility);
+    return children.length ? [{ ...column, columns: children }] : [];
+  });
+}
+
+function TableLoadingState({ label }: { label: string }) {
+  return (
+    <div className="gcsa-data-table__state gcsa-data-table__state--loading" role="status" aria-live="polite">
+      <div className="gcsa-data-table__loading-label">
+        <GcsaSpin spinning />
+        <span>{label}</span>
+      </div>
+    </div>
+  );
+}
+
+export type GcsaDataTableProps<T extends Record<string, unknown>> = {
+  data: T[];
+  columns?: Array<GcsaTableColumn<T> | ColumnDef<T, unknown>>;
+  legacyColumns?: GcsaLegacyTableColumn<T>[];
+  total?: number;
+  pageSize?: number;
+  pageSizeOptions?: number[];
+  showPageSize?: boolean;
+  showJumper?: boolean;
+  pageSizeLabel?: string;
+  jumperLabel?: string;
+  paginationLayout?: string | GcsaPaginationLayoutPart[];
+  paginationAlign?: GcsaPaginationAlign;
+  showTotal?: boolean;
+  page?: number;
+  pagination?: boolean;
+  showToolbar?: boolean;
+  /** 工具栏是否显示总条数 */
+  showCount?: boolean;
+  size?: 'sm' | 'md';
+  serverSide?: boolean;
+  sorting?: SortingState;
+  filters?: Record<string, string>;
+  defaultSorting?: SortingState;
+  defaultFilters?: Record<string, string>;
+  loading?: boolean;
+  error?: string;
+  retryLabel?: string;
+  selectable?: boolean | ((row: T, index: number) => boolean);
+  selectedRowKeys?: string[];
+  columnVisibility?: Record<string, boolean>;
+  resizable?: boolean;
+  columnWidths?: Record<string, number>;
+  treeData?: boolean;
+  childrenKey?: keyof T & string;
+  treeLazy?: boolean;
+  treeHasChildrenKey?: keyof T & string;
+  treeHasChildren?: (row: T, index: number) => boolean;
+  loadChildren?: (row: T, index: number) => Promise<T[]> | T[];
+  treeLoadingText?: string;
+  treeLoadErrorText?: string;
+  expandedRowKeys?: string[];
+  mobileMode?: 'scroll' | 'cards';
+  stripe?: boolean;
+  bordered?: boolean;
+  highlightCurrentRow?: boolean;
+  currentRowKey?: string;
+  rowClassName?: string | ((row: T, index: number) => string | undefined);
+  summary?: (rows: T[]) => Record<string, string | number | null | undefined>;
+  summaryLabel?: string;
+  apiRef?: MutableRefObject<GcsaDataTableApi<T> | null>;
+  rowKey?: keyof T & string | ((row: T, index: number) => string);
+  height?: string | number;
+  maxHeight?: string | number;
+  expandable?: boolean;
+  defaultExpandAll?: boolean;
+  fixedSelection?: boolean;
+  selectionColumnWidth?: number;
+  expandColumnWidth?: number;
+  renderExpandedRow?: (row: T, index: number) => ReactNode;
+  toolbar?: ReactNode;
+  onPageChange?: (page: number) => void;
+  onPageSizeChange?: (pageSize: number) => void;
+  onSortingChange?: (sorting: SortingState) => void;
+  /** Element-style sort event payload for migration from el-table. */
+  onSortChange?: (change: ReturnType<typeof getGcsaTableSortChange>) => void;
+  onFiltersChange?: (filters: Record<string, string>) => void;
+  onFilterChange?: (filters: Record<string, string>) => void;
+  onSelectionChange?: (rows: T[]) => void;
+  onSelect?: (rows: T[], row: T) => void;
+  onSelectAll?: (rows: T[]) => void;
+  onSelectedRowKeysChange?: (keys: string[]) => void;
+  onColumnVisibilityChange?: (visibility: Record<string, boolean>) => void;
+  onColumnWidthsChange?: (widths: Record<string, number>) => void;
+  onExpandedRowKeysChange?: (keys: string[]) => void;
+  onCurrentRowKeyChange?: (key: string | undefined) => void;
+  onRowClick?: (row: T, index: number, event: ReactMouseEvent<HTMLTableRowElement>) => void;
+  onRowDoubleClick?: (row: T, index: number, event: ReactMouseEvent<HTMLTableRowElement>) => void;
+  onCellClick?: (row: T, column: string, value: unknown, index: number, event: ReactMouseEvent<HTMLTableCellElement>) => void;
+  onCellDoubleClick?: (row: T, column: string, value: unknown, index: number, event: ReactMouseEvent<HTMLTableCellElement>) => void;
+  onHeaderClick?: (column: GcsaTableColumnInfo, event: ReactMouseEvent<HTMLTableCellElement>) => void;
+  onRowContextMenu?: (row: T, index: number, event: ReactMouseEvent<HTMLTableRowElement>) => void;
+  onCellContextMenu?: (row: T, column: string, value: unknown, index: number, event: ReactMouseEvent<HTMLTableCellElement>) => void;
+  onLegacyRowClick?: (row: T, column: GcsaTableColumnInfo, event: ReactMouseEvent<HTMLTableRowElement>) => void;
+  onLegacyCellClick?: (row: T, column: GcsaTableColumnInfo, cell: HTMLTableCellElement, event: ReactMouseEvent<HTMLTableCellElement>) => void;
+  onLegacyRowContextMenu?: (row: T, column: GcsaTableColumnInfo, event: ReactMouseEvent<HTMLTableRowElement>) => void;
+  onLegacyCellContextMenu?: (row: T, column: GcsaTableColumnInfo, cell: HTMLTableCellElement, event: ReactMouseEvent<HTMLTableCellElement>) => void;
+  onCurrentChange?: (current: T | undefined, previous: T | undefined) => void;
+  onExpandChange?: (row: T, expanded: boolean, expandedRows: T[]) => void;
+  columnSelector?: (columns: Array<{ id: string; title: string; visible: boolean }>, toggle: (id: string) => void) => ReactNode;
+  onRetry?: () => void;
+  onTreeLoadError?: (error: unknown, row: T, index: number) => void;
+};
+
+export type GcsaDataTableApi<T extends Record<string, unknown>> = {
+  clearSorting: () => void;
+  clearFilters: () => void;
+  clearSelection: () => void;
+  clearExpanded: () => void;
+  setRowSelected: (key: string, selected?: boolean) => void;
+  setRowExpanded: (key: string, expanded?: boolean) => Promise<void>;
+  clearSort: () => void;
+  clearFilter: (columnKeys?: string | string[]) => void;
+  sort: (prop: string, order: 'ascending' | 'descending' | null) => void;
+  toggleRowSelection: (row: T, selected?: boolean) => void;
+  toggleAllSelection: () => void;
+  toggleRowExpansion: (row: T, expanded?: boolean) => Promise<void>;
+  setCurrentRow: (row?: T) => void;
+  getSelectionRows: () => T[];
+  setScrollTop: (top: number) => void;
+  scrollTo: (options: ScrollToOptions | number, y?: number) => void;
+};
+
+function metaOf<T>(column: ColumnDef<T, unknown>): TableMeta {
+  return (column.meta ?? {}) as TableMeta;
+}
+
+function toColumnFilters(filters?: Record<string, string>): ColumnFiltersState {
+  return Object.entries(filters ?? {}).filter(([, value]) => value !== '').map(([id, value]) => ({ id, value }));
+}
+
+function filterRecord(filters: ColumnFiltersState) {
+  return Object.fromEntries(filters.map(filter => [filter.id, String(filter.value)]));
+}
+
+function fixedStyle<T extends Record<string, unknown>>(
+  columns: ColumnDef<T, unknown>[],
+  id: string,
+  meta: TableMeta,
+  widths: Record<string, number> = {},
+  controls: { expandable: boolean; selectable: boolean; fixedSelection: boolean; expandColumnWidth?: number; selectionColumnWidth?: number }
+): CSSProperties | undefined {
+  const override = widths[id];
+  const sizing = override
+    ? { width: `${override}px`, minWidth: `${override}px` }
+    : meta.width || meta.minWidth
+      ? { width: meta.width, minWidth: meta.minWidth ?? meta.width }
+      : { minWidth: `${GCSA_TABLE_DEFAULT_COLUMN_MIN_WIDTH}px` };
+  if (!meta.fixed) return Object.keys(sizing).length ? sizing : undefined;
+  const fixedDirection = meta.fixed === true ? 'left' : meta.fixed;
+  const offset = getGcsaTableFixedOffset(
+    columns.map(column => ({ id: column.id ?? '', ...metaOf(column) })),
+    id,
+    fixedDirection,
+    { ...controls, columnWidths: widths }
+  );
+  return { ...sizing, position: 'sticky', [fixedDirection]: offset } as CSSProperties;
+}
+
+function collectExpandedRows<T extends Record<string, unknown>>(
+  rows: T[],
+  expanded: ExpandedState,
+  getRowId: (row: T, index: number, parent?: Row<T>) => string,
+  treeData: boolean,
+  childrenKey: keyof T & string
+) {
+  const expandedKeys = expanded === true ? undefined : new Set(Object.keys(expanded).filter(key => expanded[key]));
+  const result: T[] = [];
+  const visit = (items: T[], parent?: Row<T>) => items.forEach((row, index) => {
+    const key = getRowId(row, index, parent);
+    if (!expandedKeys || expandedKeys.has(key)) result.push(row);
+    if (treeData) {
+      const children = (row as Record<string, unknown>)[childrenKey];
+      if (Array.isArray(children)) visit(children as T[], { id: key } as Row<T>);
+    }
+  });
+  visit(rows);
+  return result;
+}
+
+export function GcsaDataTable<T extends Record<string, unknown>>({
+  data,
+  columns,
+  legacyColumns,
+  total = data.length,
+  pageSize: pageSizeProp = 10,
+  pageSizeOptions = [10, 20, 50, 100],
+  showPageSize = false,
+  showJumper = false,
+  pageSizeLabel,
+  jumperLabel,
+  paginationLayout,
+  paginationAlign,
+  showTotal = true,
+  page = 1,
+  pagination = true,
+  showToolbar = true,
+  showCount = true,
+  size,
+  serverSide = false,
+  sorting: controlledSorting,
+  filters: controlledFilters,
+  defaultSorting = [],
+  defaultFilters = {},
+  loading = false,
+  error,
+  retryLabel,
+  selectable,
+  selectedRowKeys,
+  columnVisibility: controlledColumnVisibility,
+  resizable = false,
+  columnWidths: controlledColumnWidths,
+  treeData = false,
+  childrenKey = 'children' as keyof T & string,
+  treeLazy = false,
+  treeHasChildrenKey = 'hasChildren' as keyof T & string,
+  treeHasChildren,
+  loadChildren,
+  treeLoadingText,
+  treeLoadErrorText,
+  expandedRowKeys,
+  mobileMode = 'scroll',
+  stripe = false,
+  bordered = false,
+  highlightCurrentRow = false,
+  currentRowKey: controlledCurrentRowKey,
+  rowClassName,
+  summary,
+  summaryLabel,
+  apiRef,
+  rowKey,
+  expandable,
+  height,
+  maxHeight,
+  defaultExpandAll = false,
+  fixedSelection,
+  selectionColumnWidth,
+  expandColumnWidth,
+  renderExpandedRow,
+  toolbar,
+  onPageChange,
+  onPageSizeChange,
+  onSortingChange,
+  onSortChange,
+  onFiltersChange,
+  onFilterChange,
+  onSelectionChange,
+  onSelect,
+  onSelectAll,
+  onSelectedRowKeysChange,
+  onColumnVisibilityChange,
+  onColumnWidthsChange,
+  onExpandedRowKeysChange,
+  onCurrentRowKeyChange,
+  onRowClick,
+  onRowDoubleClick,
+  onCellClick,
+  onCellDoubleClick,
+  onHeaderClick,
+  onRowContextMenu,
+  onCellContextMenu,
+  onLegacyRowClick,
+  onLegacyCellClick,
+  onLegacyRowContextMenu,
+  onLegacyCellContextMenu,
+  onCurrentChange,
+  onExpandChange,
+  columnSelector,
+  onRetry,
+  onTreeLoadError
+}: GcsaDataTableProps<T>) {
+  const messages = useGcsaLocaleMessages();
+  const resolvedPageSizeLabel = pageSizeLabel ?? messages.paginationPageSize;
+  const resolvedJumperLabel = jumperLabel ?? messages.paginationJumper;
+  const resolvedRetryLabel = retryLabel ?? messages.retry;
+  const resolvedTreeLoadingText = treeLoadingText ?? messages.dataTableTreeLoading;
+  const resolvedTreeLoadErrorText = treeLoadErrorText ?? messages.dataTableTreeLoadError;
+  const resolvedSummaryLabel = summaryLabel ?? messages.dataTableSummary;
+  const resolvedSize = useGcsaComponentSize(size);
+  const getRowId = (row: T, index: number, parent?: Row<T>) => getGcsaTableRowId(row, index, rowKey, parent?.id);
+  const [pageSize, setPageSize] = useState(pageSizeProp);
+  const [sorting, setSorting] = useState<SortingState>(() => [...(controlledSorting ?? defaultSorting)]);
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>(() => toColumnFilters(controlledFilters ?? defaultFilters));
+  const [rowSelection, setRowSelection] = useState<Record<string, boolean>>(() => Object.fromEntries((selectedRowKeys ?? []).map(key => [key, true])));
+  const [columnVisibility, setColumnVisibility] = useState<Record<string, boolean>>(controlledColumnVisibility ?? {});
+  const [columnWidths, setColumnWidths] = useState<Record<string, number>>(controlledColumnWidths ?? {});
+  const [expandedKeys, setExpandedKeys] = useState<ExpandedState>(() => Object.fromEntries((expandedRowKeys ?? (defaultExpandAll ? getGcsaTableDefaultExpandedKeys(data, treeData, childrenKey, rowKey) : [])).map(key => [key, true])));
+  const [currentRowKey, setCurrentRowKey] = useState(controlledCurrentRowKey);
+  const [treeChildren, setTreeChildren] = useState<Record<string, T[]>>({});
+  const [treeLoadingKeys, setTreeLoadingKeys] = useState<Record<string, boolean>>({});
+  const [treeErrors, setTreeErrors] = useState<Record<string, unknown>>({});
+  const tableWrapRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    setPageSize(pageSizeProp);
+  }, [pageSizeProp]);
+  const treeObjectIds = useMemo(() => new WeakMap<object, string>(), []);
+  const treeObjectSequence = useRef(0);
+  const legacyMigration = useMemo(() => legacyColumns?.length
+    ? normalizeGcsaTableColumns(legacyColumns, { page, pageSize })
+    : undefined, [legacyColumns, page, pageSize]);
+  const effectiveSelectable = legacyMigration?.selectable ?? selectable ?? false;
+  const effectiveExpandable = legacyMigration?.expandable ?? expandable ?? false;
+  const effectiveFixedSelection = fixedSelection ?? legacyMigration?.fixedSelection ?? false;
+  const effectiveSelectionColumnWidth = selectionColumnWidth ?? legacyMigration?.selectionColumnWidth ?? GCSA_TABLE_SELECTION_COLUMN_WIDTH;
+  const effectiveExpandColumnWidth = expandColumnWidth ?? legacyMigration?.expandColumnWidth ?? GCSA_TABLE_EXPAND_COLUMN_WIDTH;
+  const allColumns = useMemo(() => resolveGcsaTableColumns(legacyMigration?.columns ?? columns ?? []), [legacyMigration, columns]);
+  const resolvedColumns = useMemo(() => filterColumnTree(allColumns, columnVisibility), [allColumns, columnVisibility]);
+  const leafColumns = useMemo(() => flattenColumns(resolvedColumns), [resolvedColumns]);
+  const columnOptions = useMemo(() => flattenColumns(allColumns).filter(column => !metaOf(column).hidden).map(column => ({ id: column.id ?? '', title: typeof column.header === 'string' ? column.header : column.id ?? '', visible: columnVisibility[column.id ?? ''] !== false })), [allColumns, columnVisibility]);
+  const treeNodeKey = (row: T, index: number) => {
+    const objectRow = row as object;
+    const existing = treeObjectIds.get(objectRow);
+    if (existing) return existing;
+    const key = rowKey ? getRowId(row, index) : `tree-${treeObjectSequence.current++}`;
+    treeObjectIds.set(objectRow, key);
+    return key;
+  };
+  const canExpandTreeRow = (row: T, index: number) => {
+    const key = treeNodeKey(row, index);
+    if (Object.prototype.hasOwnProperty.call(treeChildren, key)) return treeChildren[key].length > 0;
+    const children = (row as Record<string, unknown>)[childrenKey as string];
+    if (Array.isArray(children) && children.length) return true;
+    if (!treeLazy) return false;
+    return treeHasChildren ? treeHasChildren(row, index) : (row as Record<string, unknown>)[treeHasChildrenKey as string] === true;
+  };
+  const tableData = useMemo(() => {
+    if (!treeData || !Object.keys(treeChildren).length) return data;
+    const merge = (rows: T[]): T[] => rows.map((row, index) => {
+      const key = treeNodeKey(row, index);
+      const loaded = treeChildren[key];
+      const inline = (row as Record<string, unknown>)[childrenKey as string] as T[] | undefined;
+      const children = loaded ?? inline;
+      if (!children) return row;
+      const clone = { ...row, [childrenKey]: merge(children) } as T;
+      treeObjectIds.set(clone as object, key);
+      return clone;
+    });
+    return merge(data);
+  }, [data, treeChildren, treeData, childrenKey]);
+  const getSubRows = (row: T) => treeData ? (((row as Record<string, unknown>)[childrenKey as string] as T[] | undefined) ?? []) : undefined;
+  const table = useReactTable({
+    data: tableData,
+    columns: resolvedColumns,
+    state: { pagination: { pageIndex: page - 1, pageSize }, sorting, columnFilters, rowSelection, columnVisibility, expanded: expandedKeys },
+    getRowId,
+    getSubRows,
+    getRowCanExpand: row => treeData ? canExpandTreeRow(row.original, row.index) : false,
+    enableRowSelection: row => typeof effectiveSelectable === 'function' ? effectiveSelectable(row.original, row.index) : effectiveSelectable,
+    manualPagination: serverSide,
+    manualSorting: serverSide,
+    manualFiltering: serverSide,
+    pageCount: serverSide ? Math.ceil(total / pageSize) : undefined,
+    onPaginationChange: updater => { const next = typeof updater === 'function' ? updater({ pageIndex: page - 1, pageSize }) : updater; onPageChange?.(next.pageIndex + 1); },
+    onSortingChange: updater => { const next = typeof updater === 'function' ? updater(sorting) : updater; setSorting(next); onSortingChange?.(next); onSortChange?.(getGcsaTableSortChange(next)); },
+    onColumnFiltersChange: updater => { const next = typeof updater === 'function' ? updater(columnFilters) : updater; setColumnFilters(next); onFiltersChange?.(filterRecord(next)); },
+    onColumnVisibilityChange: updater => { const next = typeof updater === 'function' ? updater(columnVisibility) : updater; setColumnVisibility(next); onColumnVisibilityChange?.(next); },
+    onRowSelectionChange: updater => {
+      const next = typeof updater === 'function' ? updater(rowSelection) : updater;
+      setRowSelection(next);
+      onSelectedRowKeysChange?.(Object.keys(next).filter(key => next[key]));
+      onSelectionChange?.(selectedRowsForState(next));
+    },
+    onExpandedChange: updater => {
+      const next = typeof updater === 'function' ? updater(expandedKeys) : updater;
+      setExpandedKeys(next);
+      onExpandedRowKeysChange?.(next === true ? table.getRowModel().flatRows.map(row => row.id) : Object.keys(next).filter(key => next[key]));
+    },
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: serverSide ? undefined : getFilteredRowModel(),
+    getSortedRowModel: serverSide ? undefined : getSortedRowModel(),
+    getPaginationRowModel: serverSide ? undefined : getPaginationRowModel(),
+    getExpandedRowModel: treeData ? getExpandedRowModel() : undefined
+  });
+  useEffect(() => {
+    if (controlledSorting) setSorting([...controlledSorting]);
+  }, [controlledSorting]);
+  useEffect(() => {
+    if (defaultExpandAll && !expandedRowKeys) {
+      setExpandedKeys(Object.fromEntries(getGcsaTableDefaultExpandedKeys(data, treeData, childrenKey, rowKey).map(key => [key, true])));
+    }
+  }, [data, treeData, defaultExpandAll, expandedRowKeys, childrenKey, rowKey]);
+  useEffect(() => {
+    if (controlledFilters) setColumnFilters(toColumnFilters(controlledFilters));
+  }, [controlledFilters]);
+  useEffect(() => {
+    if (selectedRowKeys) setRowSelection(Object.fromEntries(selectedRowKeys.map(key => [key, true])));
+  }, [selectedRowKeys]);
+  useEffect(() => {
+    if (controlledColumnVisibility) setColumnVisibility(controlledColumnVisibility);
+  }, [controlledColumnVisibility]);
+  useEffect(() => {
+    if (controlledColumnWidths) setColumnWidths(controlledColumnWidths);
+  }, [controlledColumnWidths]);
+  useEffect(() => {
+    if (expandedRowKeys) setExpandedKeys(Object.fromEntries(expandedRowKeys.map(key => [key, true])));
+  }, [expandedRowKeys]);
+  useEffect(() => {
+    setCurrentRowKey(controlledCurrentRowKey);
+  }, [controlledCurrentRowKey]);
+  const selectedCount = table.getSelectedRowModel().rows.length;
+  const totalCountText = formatGcsaLocaleMessage(messages.dataTableTotal, { count: total });
+  const selectedCountText = formatGcsaLocaleMessage(messages.dataTableSelected, { count: selectedCount });
+  const selectableRows = table.getRowModel().rows.filter(row => row.getCanSelect());
+  const visibleColumnCount = leafColumns.length + (effectiveSelectable ? 1 : 0) + (effectiveExpandable || treeData ? 1 : 0);
+  const fixedControls = Boolean(effectiveSelectable && effectiveFixedSelection);
+  const fixedLayout = { expandable: effectiveExpandable || treeData, selectable: Boolean(effectiveSelectable), fixedSelection: effectiveFixedSelection, expandColumnWidth: effectiveExpandColumnWidth, selectionColumnWidth: effectiveSelectionColumnWidth };
+  const tableMinWidth = useMemo(
+    () => getGcsaTableMinWidth(
+      leafColumns.map(column => ({ id: column.id ?? '', ...metaOf(column) })),
+      {
+        expandable: effectiveExpandable || treeData,
+        selectable: Boolean(effectiveSelectable),
+        expandColumnWidth: effectiveExpandColumnWidth,
+        selectionColumnWidth: effectiveSelectionColumnWidth,
+        columnWidths
+      }
+    ),
+    [
+      columnWidths,
+      effectiveExpandColumnWidth,
+      effectiveExpandable,
+      effectiveSelectionColumnWidth,
+      effectiveSelectable,
+      leafColumns,
+      treeData
+    ]
+  );
+  const expandColumnStyle: CSSProperties = {
+    width: effectiveExpandColumnWidth,
+    minWidth: effectiveExpandColumnWidth,
+    maxWidth: effectiveExpandColumnWidth,
+    ...(fixedControls ? { position: 'sticky', left: 0 } : {})
+  };
+  const selectionColumnStyle: CSSProperties = {
+    width: effectiveSelectionColumnWidth,
+    minWidth: effectiveSelectionColumnWidth,
+    maxWidth: effectiveSelectionColumnWidth,
+    ...(fixedControls ? { position: 'sticky', left: effectiveExpandable || treeData ? effectiveExpandColumnWidth : 0 } : {})
+  };
+  const filterValue = (id: string) => String(columnFilters.find(filter => filter.id === id)?.value ?? '');
+  const updateFilter = (id: string, value: string) => {
+    const next = columnFilters.filter(filter => filter.id !== id);
+    if (value) next.push({ id, value });
+    setColumnFilters(next);
+    const filters = filterRecord(next);
+    onFiltersChange?.(filters);
+    onFilterChange?.(filters);
+  };
+  const rangeStart = total ? (page - 1) * pageSize + 1 : 0;
+  const rangeEnd = Math.min(page * pageSize, total);
+  const rangeText = formatGcsaLocaleMessage(messages.dataTableRange, {
+    start: rangeStart,
+    end: rangeEnd,
+    total
+  });
+  const toggleColumn = (id: string) => {
+    const visibleCount = leafColumns.length;
+    const next = { ...columnVisibility, [id]: columnVisibility[id] === false };
+    if (!next[id] && visibleCount <= 1) return;
+    setColumnVisibility(next);
+    onColumnVisibilityChange?.(next);
+  };
+  const startColumnResize = (event: ReactPointerEvent<HTMLSpanElement>, id: string) => {
+    const cell = event.currentTarget.parentElement;
+    const sourceColumn = leafColumns.find(column => column.id === id) as ColumnDef<T, unknown> | undefined;
+    const sourceMeta = sourceColumn ? metaOf(sourceColumn) : {};
+    const initialWidth = cell?.getBoundingClientRect().width ?? Number.parseFloat(String(sourceMeta.width ?? '0'));
+    const minWidth = Math.max(64, Number.parseFloat(String(sourceMeta.minWidth ?? sourceMeta.width ?? '64')) || 64);
+    const startX = event.clientX;
+    const move = (moveEvent: PointerEvent) => {
+      const next = Math.max(minWidth, Math.round(initialWidth + moveEvent.clientX - startX));
+      setColumnWidths(current => ({ ...current, [id]: next }));
+    };
+    const up = () => {
+      setColumnWidths(current => { onColumnWidthsChange?.(current); return current; });
+      document.removeEventListener('pointermove', move);
+      document.removeEventListener('pointerup', up);
+    };
+    document.addEventListener('pointermove', move);
+    document.addEventListener('pointerup', up, { once: true });
+  };
+
+  const tableRows = table.getRowModel().rows;
+  const expandedRowsFor = (expanded: ExpandedState) => collectExpandedRows(tableData, expanded, (row, index, parent) => getRowId(row, index, parent), treeData, childrenKey);
+  const summaryValues = summary?.(data);
+  const isRowExpanded = (rowIdValue: string) => expandedKeys === true ? true : expandedKeys[rowIdValue] === true;
+  const treeLoading = (row: Row<T>) => Boolean(treeLoadingKeys[treeNodeKey(row.original, row.index)]);
+  const treeError = (row: Row<T>) => Boolean(treeErrors[treeNodeKey(row.original, row.index)]);
+  const applyExpanded = (row: Row<T>, expanded: boolean) => {
+    const nextExpanded = { ...(expandedKeys === true ? {} : expandedKeys), [row.id]: expanded };
+    setExpandedKeys(nextExpanded);
+    onExpandedRowKeysChange?.(Object.keys(nextExpanded).filter(key => nextExpanded[key]));
+    onExpandChange?.(row.original, expanded, expandedRowsFor(nextExpanded));
+  };
+  const toggleExpanded = async (row: Row<T>) => {
+    if (treeData && treeLazy && !isRowExpanded(row.id)) {
+      const key = treeNodeKey(row.original, row.index);
+      if (!Object.prototype.hasOwnProperty.call(treeChildren, key) && loadChildren && canExpandTreeRow(row.original, row.index)) {
+        setTreeLoadingKeys(current => ({ ...current, [key]: true }));
+        setTreeErrors(current => { const next = { ...current }; delete next[key]; return next; });
+        try {
+          const children = await loadChildren(row.original, row.index);
+          setTreeChildren(current => ({ ...current, [key]: children ?? [] }));
+          if (children?.length) {
+            applyExpanded(row, true);
+          }
+        } catch (error) {
+          setTreeErrors(current => ({ ...current, [key]: error }));
+          onTreeLoadError?.(error, row.original, row.index);
+        } finally {
+          setTreeLoadingKeys(current => { const next = { ...current }; delete next[key]; return next; });
+        }
+      } else if (Object.prototype.hasOwnProperty.call(treeChildren, key)) {
+        applyExpanded(row, !isRowExpanded(row.id));
+      }
+      return;
+    }
+    if (treeData) {
+      applyExpanded(row, !isRowExpanded(row.id));
+    } else {
+      const expanded = !isRowExpanded(row.id);
+      applyExpanded(row, expanded);
+    }
+  };
+  const tableClassName = ['gcsa-table', resolvedSize === 'sm' ? 'gcsa-table--sm' : undefined, stripe ? 'gcsa-table--striped' : undefined, bordered ? 'gcsa-table--bordered' : undefined].filter(Boolean).join(' ');
+  const getRowClassName = (row: T, index: number) => typeof rowClassName === 'function' ? rowClassName(row, index) : rowClassName;
+  const getColumnInfo = (id: string): GcsaTableColumnInfo => {
+    const column = leafColumns.find(candidate => candidate.id === id);
+    const meta = column ? metaOf(column) : {};
+    return { id, prop: id, label: typeof column?.header === 'string' ? column.header : id, width: meta.width, minWidth: meta.minWidth, fixed: meta.fixed };
+  };
+  const selectCurrentRow = (row: T, index: number) => {
+    if (!highlightCurrentRow) return;
+    const key = getRowId(row, index);
+    setCurrentRowKey(key);
+    onCurrentRowKeyChange?.(key);
+  };
+  const emitSelection = (next: Record<string, boolean>) => {
+    setRowSelection(next);
+    const keys = Object.keys(next).filter(key => next[key]);
+    onSelectedRowKeysChange?.(keys);
+    onSelectionChange?.(selectedRowsForState(next));
+  };
+  const clearSorting = () => { setSorting([]); onSortingChange?.([]); onSortChange?.(getGcsaTableSortChange([])); };
+  const clearFilters = () => { setColumnFilters([]); onFiltersChange?.({}); onFilterChange?.({}); };
+  const clearFilter = (columnKeys?: string | string[]) => {
+    if (columnKeys === undefined) {
+      clearFilters();
+      return;
+    }
+    const keys = new Set(Array.isArray(columnKeys) ? columnKeys : [columnKeys]);
+    const next = columnFilters.filter(filter => !keys.has(filter.id));
+    setColumnFilters(next);
+    const filters = filterRecord(next);
+    onFiltersChange?.(filters);
+    onFilterChange?.(filters);
+  };
+  const sort = (prop: string, order: 'ascending' | 'descending' | null) => {
+    const next = getGcsaTableSorting(prop, order);
+    setSorting(next);
+    onSortingChange?.(next);
+    onSortChange?.(getGcsaTableSortChange(next));
+  };
+  const clearSelection = () => emitSelection({});
+  const clearExpanded = () => { setExpandedKeys({}); onExpandedRowKeysChange?.([]); };
+  const setRowSelected = (key: string, selected = true) => {
+    const row = table.getCoreRowModel().flatRows.find(candidate => candidate.id === key);
+    if (!row || !row.getCanSelect()) return;
+    emitSelection({ ...rowSelection, [key]: selected });
+  };
+  const toggleRowSelection = (row: T, selected?: boolean) => {
+    const tableRow = findTableRow(row);
+    if (!tableRow || !tableRow.getCanSelect()) return;
+    setRowSelected(tableRow.id, selected ?? !tableRow.getIsSelected());
+  };
+  const rowsForSelection = (selection: Record<string, boolean>) => table.getCoreRowModel().flatRows
+    .filter(row => selection[row.id] && row.getCanSelect())
+    .map(row => row.original);
+  const selectedRowsForState = rowsForSelection;
+  const toggleRowSelectionValue = (row: Row<T>, selected: boolean) => {
+    const next = { ...rowSelection, [row.id]: selected };
+    row.toggleSelected(selected);
+    onSelect?.(rowsForSelection(next), row.original);
+  };
+  const toggleAllSelection = (checked?: boolean) => {
+    const allSelected = selectableRows.length > 0 && selectableRows.every(row => row.getIsSelected());
+    const nextChecked = checked ?? !allSelected;
+    table.toggleAllPageRowsSelected(nextChecked);
+    const next = { ...rowSelection };
+    selectableRows.forEach(row => { next[row.id] = nextChecked; });
+    onSelectAll?.(rowsForSelection(next));
+  };
+  const setRowExpanded = async (key: string, expanded = true) => {
+    const row = table.getCoreRowModel().flatRows.find(candidate => candidate.id === key);
+    if (!row) return;
+    if (treeData) {
+      if (isRowExpanded(key) === expanded) return;
+      if (expanded) await toggleExpanded(row);
+      else applyExpanded(row, false);
+      return;
+    }
+    const next = { ...(expandedKeys === true ? {} : expandedKeys), [key]: expanded };
+    setExpandedKeys(next);
+    onExpandedRowKeysChange?.(Object.keys(next).filter(value => next[value]));
+  };
+  const toggleRowExpansion = async (row: T, expanded?: boolean) => {
+    const tableRow = findTableRow(row);
+    if (!tableRow) return;
+    await setRowExpanded(tableRow.id, expanded ?? !isRowExpanded(tableRow.id));
+  };
+  const setCurrentRow = (row?: T) => {
+    const tableRow = row ? findTableRow(row) : undefined;
+    setCurrentRowKey(tableRow?.id);
+    onCurrentRowKeyChange?.(tableRow?.id);
+  };
+  const findTableRow = (row: T) => {
+    const rows = table.getCoreRowModel().flatRows;
+    const byReference = rows.find(candidate => candidate.original === row);
+    if (byReference) return byReference;
+    if (rowKey) {
+      const key = getRowId(row, 0);
+      return rows.find(candidate => candidate.id === key);
+    }
+    return undefined;
+  };
+  const getSelectionRows = () => table.getCoreRowModel().flatRows.filter(row => row.getIsSelected()).map(row => row.original);
+  const setScrollTop = (top: number) => tableWrapRef.current?.scrollTo({ top });
+  const scrollTo = (options: ScrollToOptions | number, y?: number) => {
+    if (typeof options === 'number') tableWrapRef.current?.scrollTo(options, y ?? 0);
+    else tableWrapRef.current?.scrollTo(options);
+  };
+  if (apiRef) {
+    apiRef.current = {
+      clearSorting,
+      clearFilters,
+      clearSelection,
+      clearExpanded,
+      setRowSelected,
+      setRowExpanded,
+      clearSort: clearSorting,
+      clearFilter,
+      sort,
+      toggleRowSelection,
+      toggleAllSelection,
+      toggleRowExpansion,
+      setCurrentRow,
+      getSelectionRows,
+      setScrollTop,
+      scrollTo
+    };
+  }
+  return <div className={`gcsa-data-table${mobileMode === 'cards' ? ' gcsa-data-table--cards' : ''}`}>
+    {showToolbar && (toolbar || columnSelector) ? <div className="gcsa-data-table__toolbar"><div className="gcsa-data-table__toolbar-meta">{showCount && !loading ? <span className="gcsa-data-table__count">{totalCountText}</span> : null}{selectedCount ? <span className="gcsa-data-table__selected">{selectedCountText}</span> : null}</div><div className="gcsa-data-table__toolbar-actions">{toolbar}{columnSelector ? <div className="gcsa-data-table__columns-control">{columnSelector(columnOptions, toggleColumn)}</div> : null}</div></div> : null}
+    <div ref={tableWrapRef} className="gcsa-table-wrap gcsa-ui-surface" style={{ height: height === undefined ? undefined : typeof height === 'number' ? `${height}px` : height, maxHeight: maxHeight === undefined ? undefined : typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight }}>
+      {loading ? <TableLoadingState label={messages.dataTableLoading} /> : null}
+      {error ? <div className="gcsa-data-table__state gcsa-data-table__state--error" role="alert"><span>{error}</span><button type="button" className="gcsa-btn gcsa-btn--sm gcsa-btn--secondary" onClick={onRetry}>{resolvedRetryLabel}</button></div> : null}
+      {!loading && !error ? <table className={tableClassName} style={{ minWidth: tableMinWidth }}>
+        <thead className="gcsa-table__head">
+          {table.getHeaderGroups().map((headerGroup, groupIndex) => <tr key={headerGroup.id}>
+            {groupIndex === 0 && (effectiveExpandable || treeData) ? <th className="gcsa-table__col-expand" style={expandColumnStyle} rowSpan={table.getHeaderGroups().length} /> : null}
+            {groupIndex === 0 && effectiveSelectable ? <th className="gcsa-table__col-check" style={selectionColumnStyle} rowSpan={table.getHeaderGroups().length}><GcsaCheckbox checked={selectableRows.length > 0 && selectableRows.every(row => row.getIsSelected())} disabled={!selectableRows.length} label="" ariaLabel={messages.dataTableSelectAll} onCheckedChange={checked => toggleAllSelection(checked)} /></th> : null}
+            {headerGroup.headers.map(header => {
+              const meta = metaOf(header.column.columnDef);
+              const isLeaf = !header.column.columns.length;
+              return <th key={header.id} colSpan={header.colSpan} rowSpan={header.rowSpan > 1 ? header.rowSpan : undefined} style={fixedStyle(leafColumns, header.column.id, meta, columnWidths, fixedLayout)} className={meta.align === 'center' ? 'gcsa-table__align-center' : meta.align === 'right' ? 'gcsa-table__align-right' : undefined} onClick={event => onHeaderClick?.(getColumnInfo(header.column.id), event)}>
+                {header.isPlaceholder ? null : isLeaf && header.column.getCanSort() ? <button type="button" className={`gcsa-table__sort${header.column.getIsSorted() ? ' gcsa-table__sort--active' : ''}`} onClick={header.column.getToggleSortingHandler()}><span className="gcsa-table__sort-label">{flexRender(header.column.columnDef.header, header.getContext())}</span><span className="gcsa-table__sort-icon" aria-hidden="true"><GcsaIcon name="chevronUp" size="sm" /><GcsaIcon name="chevronDown" size="sm" /></span></button> : isLeaf ? <span className="gcsa-table__head-text">{flexRender(header.column.columnDef.header, header.getContext())}</span> : <span className="gcsa-table__head-text">{flexRender(header.column.columnDef.header, header.getContext())}</span>}
+                {isLeaf && meta.filter ? <div className="gcsa-table__filter">{meta.filter.type === 'text' ? <GcsaInput value={filterValue(header.column.id)} placeholder={meta.filter.placeholder ?? messages.dataTableFilter} onValueChange={value => updateFilter(header.column.id, value)} /> : <GcsaSelect value={filterValue(header.column.id)} options={meta.filter.options ?? []} placeholder={meta.filter.placeholder ?? messages.dataTableFilter} onValueChange={value => updateFilter(header.column.id, value)} />}</div> : null}
+                {resizable && isLeaf ? <span className="gcsa-table__resize-handle" role="separator" aria-label={messages.dataTableResizeColumn} onPointerDown={event => { event.stopPropagation(); event.preventDefault(); startColumnResize(event, header.column.id); }} /> : null}
+              </th>;
+            })}
+          </tr>)}
+        </thead>
+        <tbody className="gcsa-table__body">
+          {table.getRowModel().rows.map(row => { const rowExpanded = isRowExpanded(row.id); return <Fragment key={row.id}>
+            <tr key={row.id} className={`gcsa-table__row${row.index % 2 === 1 ? ' gcsa-table__row--striped' : ''}${getRowClassName(row.original, row.index) ? ` ${getRowClassName(row.original, row.index)}` : ''}`} data-selected={row.getIsSelected() || undefined} data-current={highlightCurrentRow && currentRowKey === getRowId(row.original, row.index) ? true : undefined} onClick={event => { const previous = highlightCurrentRow ? table.getCoreRowModel().flatRows.find(candidate => candidate.id === currentRowKey)?.original : undefined; selectCurrentRow(row.original, row.index); if (highlightCurrentRow) onCurrentChange?.(row.original, previous); onRowClick?.(row.original, row.index, event); onLegacyRowClick?.(row.original, getColumnInfo(row.getVisibleCells()[0]?.column.id ?? ''), event); }} onDoubleClick={event => onRowDoubleClick?.(row.original, row.index, event)} onContextMenu={event => { event.preventDefault(); onRowContextMenu?.(row.original, row.index, event); onLegacyRowContextMenu?.(row.original, getColumnInfo(row.getVisibleCells()[0]?.column.id ?? ''), event); }}>
+              {effectiveExpandable || treeData ? <td className="gcsa-table__col-expand" style={expandColumnStyle} onClick={event => event.stopPropagation()}>{(!treeData || row.getCanExpand()) ? <><button type="button" className="gcsa-table__expand gcsa-focus-ring" disabled={treeLoading(row)} aria-label={treeLoading(row) ? messages.dataTableLoadChildren : treeError(row) ? messages.dataTableRetryChildren : rowExpanded ? messages.dataTableCollapseRow : messages.dataTableExpandRow} aria-expanded={rowExpanded} onClick={() => toggleExpanded(row)}><GcsaIcon name="chevronDown" size="sm" className={rowExpanded ? 'gcsa-table__expand-icon--open' : undefined} /></button>{treeLoading(row) ? <span className="gcsa-table__tree-state" role="status">{resolvedTreeLoadingText}</span> : treeError(row) ? <button type="button" className="gcsa-table__tree-retry" onClick={() => toggleExpanded(row)}>{resolvedTreeLoadErrorText}</button> : null}</> : null}</td> : null}
+              {effectiveSelectable ? <td className="gcsa-table__col-check" onClick={event => event.stopPropagation()} style={selectionColumnStyle}><GcsaCheckbox checked={row.getIsSelected()} disabled={!row.getCanSelect()} label="" ariaLabel={messages.dataTableSelectRow} onCheckedChange={checked => toggleRowSelectionValue(row, checked)} /></td> : null}
+              {row.getVisibleCells().map((cell, cellIndex) => { const cellMeta = metaOf(cell.column.columnDef); const cellValue = cell.getValue(); return <td key={cell.id} data-label={typeof cell.column.columnDef.header === 'string' ? cell.column.columnDef.header : cell.column.id} title={cellMeta.showOverflowTooltip ? formatGcsaTableCellValue(cellValue) : undefined} className={`${cellMeta.align === 'center' ? 'gcsa-table__align-center' : cellMeta.align === 'right' ? 'gcsa-table__align-right' : ''}${cellMeta.showOverflowTooltip ? ' gcsa-table__cell--overflow' : ''}`} style={fixedStyle(leafColumns, cell.column.id, cellMeta, columnWidths, fixedLayout)} onClick={event => { event.stopPropagation(); selectCurrentRow(row.original, row.index); onCellClick?.(row.original, cell.column.id, cellValue, row.index, event); onLegacyCellClick?.(row.original, getColumnInfo(cell.column.id), event.currentTarget, event); }} onDoubleClick={event => { event.stopPropagation(); onCellDoubleClick?.(row.original, cell.column.id, cellValue, row.index, event); }} onContextMenu={event => { event.stopPropagation(); event.preventDefault(); onCellContextMenu?.(row.original, cell.column.id, cellValue, row.index, event); onLegacyCellContextMenu?.(row.original, getColumnInfo(cell.column.id), event.currentTarget, event); }}><div className="gcsa-table__cell" style={treeData && cellIndex === 0 ? { paddingInlineStart: `${row.depth * 18}px` } : undefined}>{cell.column.columnDef.cell ? flexRender(cell.column.columnDef.cell, cell.getContext()) : formatGcsaTableCellValue(cellValue)}</div></td>; })}
+            </tr>
+            {!treeData && rowExpanded && renderExpandedRow ? <tr key={`${row.id}-expanded`} className="gcsa-table__expanded-row"><td colSpan={visibleColumnCount}>{renderExpandedRow(row.original, row.index)}</td></tr> : null}
+          </Fragment>; })}
+        </tbody>
+        {summaryValues ? <tfoot className="gcsa-table__foot"><tr className="gcsa-table__summary-row">
+          {effectiveExpandable || treeData ? <th className="gcsa-table__col-expand" scope="row" style={expandColumnStyle} /> : null}
+          {effectiveSelectable ? <th className="gcsa-table__col-check" scope="row" style={selectionColumnStyle} /> : null}
+          {leafColumns.map((column, summaryIndex) => {
+            const columnMeta = metaOf(column);
+            return <td key={column.id} className={columnMeta.align === 'center' ? 'gcsa-table__align-center' : columnMeta.align === 'right' ? 'gcsa-table__align-right' : undefined} style={fixedStyle(leafColumns, column.id ?? '', columnMeta, columnWidths, fixedLayout)}>{summaryValues[column.id ?? ''] ?? (summaryIndex === 0 ? resolvedSummaryLabel : '')}</td>;
+          })}
+        </tr></tfoot> : null}
+      </table> : null}
+      {!loading && !error && tableRows.length === 0 ? <div className="gcsa-data-table__empty"><GcsaEmpty title={messages.dataTableEmpty} /></div> : null}
+    </div>
+    {pagination && total > 0 && !loading && !error ? <div className="gcsa-data-table__footer">{showTotal ? <div className="gcsa-data-table__footer-meta">{rangeText}</div> : null}<GcsaPagination page={page} total={total} pageSize={pageSize} pageSizeOptions={pageSizeOptions} showPageSize={showPageSize} showJumper={showJumper} pageSizeLabel={resolvedPageSizeLabel} jumperLabel={resolvedJumperLabel} layout={paginationLayout} align={paginationAlign} onPageChange={onPageChange} onPageSizeChange={next => { setPageSize(next); onPageSizeChange?.(next); }} /></div> : null}
+  </div>;
+}