@multiplatform.one/table 6.0.0

package/src/components/DataTable/DataTableRoot.tsx

@@ -0,0 +1,1339 @@
+/**
+ * DataTableRoot - core table rendering component.
+ *
+ * Renders the table structure: headers, body rows, cells, footer.
+ * Handles form mode vs standalone mode, toolbar, pagination, mobile
+ * cards, virtualization, and keyboard navigation.
+ *
+ * This component calls useDataTable internally and provides state
+ * via both DataTableContext (styled) and DataTableStateContext (regular).
+ */
+
+import {
+  CaretDownIcon,
+  CaretRightIcon,
+  CaretUpDownIcon,
+  PlusIcon,
+  TrashIcon,
+} from "@phosphor-icons/react";
+import { Button, Field, useFormField, zIndex } from "@multiplatform.one/forms";
+import { flexRender } from "@tanstack/react-table";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import React, { useRef, useMemo, useCallback } from "react";
+import { Tooltip } from "@multiplatform.one/components";
+import { Spinner, Text, View, isWeb, useMedia } from "tamagui";
+import { useTranslation } from "react-i18next";
+import { useDataTable } from "../../hooks/useDataTable";
+import { useDragScroll } from "../../hooks/useDragScroll";
+import { useDataTableKeyboard } from "../../hooks/useDataTableKeyboard";
+import type { DataTableColumn, DataTableField, DataTableProps } from "../../types";
+import { DataTableColumnPinning } from "../DataTableColumnPinning";
+import { DataTablePagination } from "../DataTablePagination";
+import { DataTableToolbar } from "../DataTableToolbar";
+import { DataTableCell } from "../DataTableCell";
+import { ColumnHeaderFilter } from "../ColumnHeaderFilter";
+import { Table } from "@multiplatform.one/table-primitives";
+import { DataTableContext } from "./DataTableContext";
+import { DataTableStateContext } from "./DataTableStateContext";
+import type { DataTableStateContextValue } from "./DataTableStateContext";
+import { DataTableMobileCards } from "./DataTableMobileCards";
+import { DataTableVirtualized } from "./DataTableVirtualized";
+
+/** Returns the field type for a column, defaulting to "input" */
+function getColumnField(column: DataTableColumn): DataTableField {
+  return column.field ?? "input";
+}
+
+/** Returns true if the field type should be right-aligned (numeric fields) */
+function isNumericField(field: DataTableField): boolean {
+  switch (field) {
+    case "stepper":
+    case "slider":
+    case "progress":
+    case "rating":
+    case "duration":
+      return true;
+    default:
+      return false;
+  }
+}
+
+/** Maps field type to filter-compatible types */
+function mapFieldToFilterType(
+  field?: DataTableField,
+): "text" | "number" | "date" | "boolean" | "select" {
+  switch (field) {
+    case "stepper":
+    case "slider":
+    case "progress":
+    case "rating":
+    case "duration":
+      return "number";
+    case "datepicker":
+    case "datetimepicker":
+    case "timepicker":
+    case "daterangepicker":
+    case "multidatepicker":
+      return "date";
+    case "checkbox":
+    case "switch":
+      return "boolean";
+    case "select":
+    case "combobox":
+    case "radiogroup":
+    case "togglegroup":
+      return "select";
+    default:
+      return "text";
+  }
+}
+
+const rowHeightPx = 40;
+
+export interface DataTableRootProps<
+  TData extends Record<string, any> = Record<string, any>,
+> extends DataTableProps<TData> {
+  /** Compound sub-components rendered as children */
+  children?: React.ReactNode;
+  /** Structural modifier: compact layout */
+  compact?: boolean;
+  /** Structural modifier: disabled state */
+  disabled?: boolean;
+}
+
+export function DataTableRoot<TData extends Record<string, any> = Record<string, any>>({
+  data,
+  columns,
+  initialState,
+  onStateChange,
+  syncWithUrl = false,
+  urlDebounceMs = 500,
+  urlStrategy,
+  manualFiltering = false,
+  manualPagination = false,
+  manualSorting = false,
+  enableFiltering = true,
+  enableSorting = true,
+  enablePagination = true,
+  enableColumnVisibility = true,
+  enableColumnOrdering = false,
+  enableColumnResizing = false,
+  enableGlobalSearch = true,
+  enableViews = false,
+  columnLayout = "equal",
+  enableVirtualization = false,
+  virtualizationHeight,
+  virtualizationOverscan = 5,
+  enableRowExpansion = false,
+  renderSubComponent,
+  getSubRows,
+  enableColumnPinning = false,
+  maxPinnedColumns = 3,
+  enableGrouping = false,
+  enableKeyboardNavigation = false,
+  readOnly = false,
+  onCellChange,
+  name,
+  form: formProp,
+  showRowNumbers = false,
+  showAddRow = false,
+  showDeleteRow = false,
+  minRows = 0,
+  maxRows,
+  defaultRow,
+  onDataChange,
+  rowCount,
+  pageCount,
+  renderToolbar,
+  renderPagination,
+  renderFilters: _renderFilters,
+  className,
+  size,
+  compact = false,
+  disabled: _disabled = false,
+  children,
+  "aria-label": ariaLabel,
+  "aria-describedby": ariaDescribedBy,
+  ...props
+}: DataTableRootProps<TData>) {
+  const { t } = useTranslation();
+  const { sm } = useMedia();
+  const { knobProps } = useResolvedKnobs({ intent: undefined, component: "DataTable", compact });
+  const { resolvedForm } = useFormField({ form: formProp });
+
+  const isFormMode = Boolean(name && resolvedForm);
+
+  const { table, state, actions, computed } = useDataTable({
+    data,
+    columns,
+    initialState,
+    onStateChange,
+    syncWithUrl,
+    urlDebounceMs,
+    urlStrategy,
+    manualFiltering,
+    manualPagination,
+    manualSorting,
+    enableFiltering,
+    enableSorting,
+    enablePagination,
+    enableColumnVisibility,
+    enableColumnOrdering,
+    enableColumnResizing,
+    columnLayout,
+    enableGlobalSearch,
+    enableViews,
+    enableVirtualization,
+    virtualizationHeight,
+    virtualizationOverscan,
+    enableRowExpansion,
+    getSubRows,
+    renderSubComponent,
+    enableColumnPinning,
+    maxPinnedColumns,
+    enableGrouping,
+    enableKeyboardNavigation,
+    rowCount,
+    pageCount,
+  });
+
+  const resolvedSize: "sm" | "md" | "lg" =
+    size ?? (knobProps.sizeToken === "$3" ? "sm" : knobProps.sizeToken === "$5" ? "lg" : "md");
+
+  const cellHeight = resolvedSize === "sm" ? "$3" : resolvedSize === "lg" ? "$5" : "$4";
+
+  const headerGroups = table.getHeaderGroups();
+  const tableRows = table.getRowModel().rows;
+  const footerGroups = table.getFooterGroups();
+
+  const hasFooter = footerGroups.some((group: any) =>
+    group.headers.some((header: any) => header.column.columnDef.footer != null),
+  );
+
+  const allRowsLength =
+    tableRows.length + headerGroups.length + (hasFooter ? footerGroups.length : 0);
+  const rowCounter = useRef(-1);
+  rowCounter.current = -1;
+
+  const getColSizeProps = useCallback(
+    (col: {
+      getSize: () => number;
+      columnDef: { size?: number; minSize?: number; maxSize?: number };
+    }) => {
+      const hasExplicitSize = col.columnDef.size != null;
+      if (hasExplicitSize || enableColumnResizing) {
+        return { width: col.getSize() };
+      }
+      return {};
+    },
+    [enableColumnResizing],
+  );
+
+  // HTML5 column drag-and-drop (web only). Reorder swaps the dragged column
+  // and the drop-target column in `table.getState().columnOrder`. Native gets
+  // no DnD UI for now — apps can call `table.setColumnOrder(...)` directly.
+  const dnd = useMemo(() => {
+    if (!enableColumnOrdering || !isWeb) return null;
+    return {
+      onDragStart: (e: React.DragEvent<HTMLElement>, columnId: string) => {
+        e.dataTransfer?.setData("application/x-table-column-id", columnId);
+        if (e.dataTransfer) e.dataTransfer.effectAllowed = "move";
+      },
+      onDragOver: (e: React.DragEvent<HTMLElement>) => {
+        e.preventDefault();
+        if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+      },
+      onDrop: (e: React.DragEvent<HTMLElement>, targetColumnId: string) => {
+        e.preventDefault();
+        const sourceId = e.dataTransfer?.getData("application/x-table-column-id");
+        if (!sourceId || sourceId === targetColumnId) return;
+        const order = table.getAllLeafColumns().map((c) => c.id);
+        const currentOrder = table.getState().columnOrder.length
+          ? [...table.getState().columnOrder]
+          : order;
+        const fromIdx = currentOrder.indexOf(sourceId);
+        const toIdx = currentOrder.indexOf(targetColumnId);
+        if (fromIdx < 0 || toIdx < 0) return;
+        const next = [...currentOrder];
+        next.splice(fromIdx, 1);
+        next.splice(toIdx, 0, sourceId);
+        table.setColumnOrder(next);
+      },
+    };
+  }, [enableColumnOrdering, table]);
+
+  const bodyScrollRef = useRef<HTMLDivElement>(null);
+  const isVirtualized =
+    enableVirtualization &&
+    virtualizationHeight != null &&
+    virtualizationHeight > 0 &&
+    typeof window !== "undefined";
+
+  const virtualizer = useVirtualizer({
+    count: tableRows.length,
+    getScrollElement: () => bodyScrollRef.current,
+    estimateSize: () => rowHeightPx,
+    overscan: virtualizationOverscan,
+    enabled: isVirtualized,
+  });
+
+  const virtualItems = isVirtualized ? virtualizer.getVirtualItems() : [];
+  const totalSize = isVirtualized ? virtualizer.getTotalSize() : 0;
+
+  const isFlexLayout = columnLayout !== "auto";
+  const displayMode = isFlexLayout ? ("flex" as const) : ("table" as const);
+
+  const cellFlexProps = useMemo(() => {
+    if (!isFlexLayout) return {};
+    if (columnLayout === "scroll") return { flex: 0, flexShrink: 0, flexGrow: 0, minWidth: 80 };
+    if (enableColumnResizing) return { flex: 0, flexShrink: 0, flexGrow: 0 };
+    return { flex: 1, flexShrink: 1, flexGrow: 1, flexBasis: 0, minWidth: 0 };
+  }, [isFlexLayout, columnLayout, enableColumnResizing]);
+
+  const pinning = useMemo(
+    () =>
+      enableColumnPinning
+        ? DataTableColumnPinning({
+            table,
+            maxPinnedColumns,
+            allowPinning: true,
+          })
+        : null,
+    [enableColumnPinning, table, maxPinnedColumns],
+  );
+
+  const keyboardNav = useDataTableKeyboard({
+    table,
+    enabled: enableKeyboardNavigation,
+    viewportHeight: virtualizationHeight ?? 400,
+    onScrollToRow: isVirtualized
+      ? (idx) => virtualizer.scrollToIndex(idx, { align: "auto" })
+      : undefined,
+    onRowActivate: enableRowExpansion
+      ? (row) => {
+          if (row.getCanExpand()) row.toggleExpanded();
+        }
+      : undefined,
+  });
+
+  const handleCellChange = useCallback(
+    async (rowIndex: number, columnId: string, newValue: any) => {
+      if (readOnly) return;
+      const previousValue = data[rowIndex]?.[columnId];
+      if (onCellChange) {
+        const result = await onCellChange(rowIndex, columnId, newValue, previousValue);
+        if (result === false) return;
+      }
+      if (!isFormMode && onDataChange) {
+        const newData = [...data];
+        newData[rowIndex] = { ...newData[rowIndex], [columnId]: newValue };
+        onDataChange(newData);
+      }
+    },
+    [readOnly, data, onCellChange, isFormMode, onDataChange],
+  );
+
+  const handleAddRow = useCallback(() => {
+    if (readOnly || (maxRows && data.length >= maxRows)) return;
+    const newRow = { ...defaultRow, idx: data.length + 1 } as unknown as TData;
+    if (!isFormMode && onDataChange) {
+      onDataChange([...data, newRow]);
+    }
+  }, [readOnly, maxRows, data, defaultRow, isFormMode, onDataChange]);
+
+  const handleDeleteRow = useCallback(
+    (rowIndex: number) => {
+      if (readOnly || data.length <= minRows) return;
+      if (!isFormMode && onDataChange) {
+        onDataChange(data.filter((_, idx) => idx !== rowIndex));
+      }
+    },
+    [readOnly, minRows, data, isFormMode, onDataChange],
+  );
+
+  const isCompact = resolvedSize === "sm" || compact;
+  const renderCellContent = useCallback(
+    (cell: any, rowIndex: number, rowData: TData) => {
+      const columnDef = cell.column.columnDef as DataTableColumn;
+      const columnId = cell.column.id;
+      const value = cell.getValue();
+
+      if (columnDef.cell && !columnDef.field) {
+        return flexRender(columnDef.cell, cell.getContext());
+      }
+
+      const columnField = getColumnField(columnDef);
+      const dateRangeLinkedColumn = columnDef.fieldProps?.dateRangeLinkedColumn;
+      let linkedValue: any;
+      let onLinkedChange: ((value: any) => void) | undefined;
+
+      if (dateRangeLinkedColumn && rowData) {
+        linkedValue = rowData[dateRangeLinkedColumn];
+        onLinkedChange = (newValue: any) => {
+          handleCellChange(rowIndex, dateRangeLinkedColumn, newValue);
+        };
+      }
+
+      return (
+        <DataTableCell
+          value={value}
+          field={columnField}
+          fieldProps={columnDef.fieldProps}
+          onChange={(newValue) => handleCellChange(rowIndex, columnId, newValue)}
+          readOnly={readOnly}
+          columnId={columnId}
+          rowIndex={rowIndex}
+          rowData={rowData}
+          size={knobProps.sizeToken}
+          compact={isCompact}
+          linkedValue={linkedValue}
+          onLinkedChange={onLinkedChange}
+        />
+      );
+    },
+    [handleCellChange, readOnly, knobProps.sizeToken, isCompact],
+  );
+
+  const isSSR = typeof window === "undefined";
+
+  const extraColumnsBefore = (showRowNumbers ? 1 : 0) + (enableRowExpansion ? 1 : 0);
+  const extraColumnsAfter = showDeleteRow && !readOnly ? 1 : 0;
+
+  const getStickyStyle = useCallback(
+    (columnId: string) => {
+      if (!enableColumnPinning || !pinning) return undefined;
+      const colPinning = table.getState().columnPinning || {
+        left: [] as string[],
+        right: [] as string[],
+      };
+      const leftPinned = colPinning.left || [];
+      const rightPinned = colPinning.right || [];
+      const leftIdx = leftPinned.indexOf(columnId);
+      const rightIdx = rightPinned.indexOf(columnId);
+
+      if (leftIdx >= 0) {
+        let leftOffset = 0;
+        for (let i = 0; i < leftIdx; i++) {
+          const col = table.getColumn(leftPinned[i]);
+          if (col) leftOffset += col.getSize();
+        }
+        if (enableRowExpansion) leftOffset += 32;
+        if (showRowNumbers) leftOffset += 50;
+        return {
+          position: "sticky" as const,
+          left: leftOffset,
+          zIndex: 2,
+          backgroundColor: "$color2",
+        };
+      }
+
+      if (rightIdx >= 0) {
+        let rightOffset = 0;
+        for (let i = rightIdx + 1; i < rightPinned.length; i++) {
+          const col = table.getColumn(rightPinned[i]);
+          if (col) rightOffset += col.getSize();
+        }
+        if (showDeleteRow && !readOnly) rightOffset += 60;
+        return {
+          position: "sticky" as const,
+          right: rightOffset,
+          zIndex: 2,
+          backgroundColor: "$color2",
+        };
+      }
+
+      return undefined;
+    },
+    [
+      enableColumnPinning,
+      pinning,
+      table,
+      enableRowExpansion,
+      showRowNumbers,
+      showDeleteRow,
+      readOnly,
+    ],
+  );
+
+  const renderRowContent = useCallback(
+    (row: any, rowIndex: number, _isLastRow: boolean) => {
+      const rowData = row.original as TData;
+
+      return (
+        <>
+          {showRowNumbers && (
+            <Table.Cell cellWidth={50} cellHeight={cellHeight as any} cellLocation="first">
+              <Text fontSize={knobProps.sizeToken} color="$color10">
+                {rowIndex + 1}
+              </Text>
+            </Table.Cell>
+          )}
+
+          {enableRowExpansion && (
+            <Table.Cell
+              cellWidth={32 + row.depth * 20}
+              cellHeight={cellHeight as any}
+              cellLocation={showRowNumbers ? "middle" : "first"}
+              paddingLeft={0}
+              paddingRight={0}
+            >
+              <View flexDirection="row" alignItems="center" height="100%">
+                {row.depth > 0 && (
+                  <View
+                    flexDirection="row"
+                    alignItems="center"
+                    height="100%"
+                    width={row.depth * 20}
+                  >
+                    {Array.from({ length: row.depth }).map((_, i) => (
+                      <View
+                        key={i}
+                        width={20}
+                        height="100%"
+                        alignItems="center"
+                        justifyContent="center"
+                      >
+                        <View
+                          position="absolute"
+                          width={1}
+                          height="100%"
+                          backgroundColor="$color6"
+                          left={10}
+                        />
+                        {i === row.depth - 1 && (
+                          <View
+                            position="absolute"
+                            height={1}
+                            width={10}
+                            backgroundColor="$color6"
+                            left={10}
+                          />
+                        )}
+                      </View>
+                    ))}
+                  </View>
+                )}
+                {row.getCanExpand() ? (
+                  <View
+                    onPress={() => row.toggleExpanded()}
+                    cursor="pointer"
+                    padding="$1"
+                    aria-expanded={row.getIsExpanded()}
+                    aria-label={row.getIsExpanded() ? "Collapse row" : "Expand row"}
+                    hoverStyle={{ backgroundColor: "$color4" }}
+                    borderRadius="$2"
+                  >
+                    <CaretRightIcon
+                      size={14}
+                      style={{
+                        transform: row.getIsExpanded() ? "rotate(90deg)" : "none",
+                        transition: "transform 0.15s ease",
+                      }}
+                    />
+                  </View>
+                ) : (
+                  <View width={22} />
+                )}
+              </View>
+            </Table.Cell>
+          )}
+
+          {row.getVisibleCells().map((cell: any, cellIndex: number) => {
+            const isFirstDataCell = cellIndex === 0 && !showRowNumbers && !enableRowExpansion;
+            const isLastDataCell = cellIndex === row.getVisibleCells().length - 1 && !showDeleteRow;
+            const cellLocation = isFirstDataCell ? "first" : isLastDataCell ? "last" : "middle";
+            const stickyStyle = getStickyStyle(cell.column.id);
+
+            return (
+              <Table.Cell
+                key={cell.id}
+                {...cellFlexProps}
+                {...getColSizeProps(cell.column)}
+                cellHeight={cellHeight as any}
+                cellLocation={cellLocation}
+                {...(isWeb && stickyStyle
+                  ? {
+                      style: {
+                        position: "sticky",
+                        ...("left" in stickyStyle && { left: stickyStyle.left }),
+                        ...("right" in stickyStyle && { right: stickyStyle.right }),
+                        zIndex: 2,
+                        backgroundColor: "var(--color2)",
+                      } as React.CSSProperties,
+                    }
+                  : {})}
+              >
+                {renderCellContent(cell, rowIndex, rowData)}
+              </Table.Cell>
+            );
+          })}
+
+          {showDeleteRow && !readOnly && (
+            <Table.Cell
+              cellWidth={60}
+              cellHeight={cellHeight as any}
+              cellLocation="last"
+              justifyContent="center"
+            >
+              <Button
+                chromeless
+                circular
+                icon={TrashIcon}
+                disabled={data.length <= minRows}
+                onPress={() => handleDeleteRow(rowIndex)}
+                aria-label={t("Delete row")}
+              />
+            </Table.Cell>
+          )}
+        </>
+      );
+    },
+    [
+      showRowNumbers,
+      enableRowExpansion,
+      showDeleteRow,
+      readOnly,
+      cellHeight,
+      knobProps.sizeToken,
+      cellFlexProps,
+      getColSizeProps,
+      getStickyStyle,
+      renderCellContent,
+      handleDeleteRow,
+      data.length,
+      minRows,
+      t,
+    ],
+  );
+
+  // Build the state context value
+  const stateContextValue = useMemo<DataTableStateContextValue<TData>>(
+    () => ({ table, state, actions, computed }),
+    [table, state, actions, computed],
+  );
+
+  const renderToolbarComponent = () => {
+    const activeFilterCount = table.getState().columnFilters?.length || 0;
+
+    if (renderToolbar) {
+      return renderToolbar({
+        globalFilter: state.globalFilter || "",
+        onGlobalFilterChange: actions.setGlobalFilter,
+        onClearFilters: actions.clearFilters,
+        onSaveView: actions.saveView,
+        onLoadView: actions.loadView,
+        views: state.views,
+        activeViewId: state.activeViewId,
+        size: knobProps.sizeToken,
+        compact: isCompact,
+      });
+    }
+
+    return (
+      <DataTableToolbar
+        globalFilter={state.globalFilter || ""}
+        onGlobalFilterChange={actions.setGlobalFilter}
+        onClearFilters={actions.clearFilters}
+        activeFilterCount={activeFilterCount}
+        onSaveView={actions.saveView}
+        onLoadView={actions.loadView}
+        views={state.views}
+        activeViewId={state.activeViewId}
+        enableViews={enableViews}
+        enableGlobalSearch={enableGlobalSearch}
+        enableFiltering={enableFiltering}
+        size={knobProps.sizeToken}
+        compact={isCompact}
+      />
+    );
+  };
+
+  const renderPaginationComponent = () => {
+    if (renderPagination) {
+      return renderPagination({
+        pagination: state.pagination,
+        onPaginationChange: actions.setPagination,
+        pageSizeOptions: [10, 20, 50, 100],
+      });
+    }
+
+    return (
+      <DataTablePagination
+        pagination={state.pagination}
+        onPaginationChange={actions.setPagination}
+        pageSizeOptions={[10, 20, 50, 100]}
+        compact
+      />
+    );
+  };
+
+  const renderInner = (
+    tableData: TData[],
+    effectiveHandleAddRow: () => void,
+    effectiveHandleDeleteRow: (idx: number) => void,
+    _effectiveHandleCellChange: (
+      rowIndex: number,
+      columnId: string,
+      newValue: any,
+    ) => Promise<void>,
+  ) => {
+    const hasToolbar = enableGlobalSearch || enableFiltering || enableViews;
+    const scrollContainerRef = useRef<HTMLDivElement>(null);
+
+    // Enable drag-to-scroll when in scroll layout mode
+    useDragScroll(scrollContainerRef, columnLayout === "scroll" && isWeb && !isSSR);
+
+    return (
+      <DataTableContext.Provider size={resolvedSize} compact={isCompact}>
+        <DataTableStateContext.Provider value={stateContextValue}>
+          <View
+            flexDirection="column"
+            gap={0}
+            width="100%"
+            flex={1}
+            minHeight={0}
+            {...(isWeb && className ? { className } : {})}
+            aria-label={ariaLabel || "Data table"}
+            aria-describedby={ariaDescribedBy}
+            aria-live="polite"
+            aria-atomic="false"
+            {...props}
+          >
+            {/* Toolbar */}
+            {hasToolbar && renderToolbarComponent()}
+
+            {/* Compound sub-components (children) */}
+            {children}
+
+            {/* Mobile Card View */}
+            {sm === false ? (
+              <DataTableMobileCards
+                tableRows={tableRows}
+                showRowNumbers={showRowNumbers}
+                showDeleteRow={showDeleteRow}
+                readOnly={readOnly}
+                dataLength={tableData.length}
+                minRows={minRows}
+                hasActiveFilters={computed.hasActiveFilters}
+                renderCellContent={renderCellContent}
+                onDeleteRow={effectiveHandleDeleteRow}
+              />
+            ) : (
+              /* Table View */
+              <View
+                ref={(node: any) => {
+                  if (enableKeyboardNavigation && !isSSR && keyboardNav.containerRef) {
+                    (keyboardNav.containerRef as any).current = node;
+                  }
+                  if (scrollContainerRef) {
+                    (scrollContainerRef as any).current = node;
+                  }
+                }}
+                flexDirection="column"
+                width="100%"
+                flex={1}
+                minHeight={0}
+                aria-label={`${ariaLabel || "Data table"} content`}
+                tabIndex={enableKeyboardNavigation && !isSSR ? 0 : undefined}
+                onKeyDown={
+                  enableKeyboardNavigation && !isSSR ? keyboardNav.handleKeyDown : undefined
+                }
+                onPress={
+                  enableKeyboardNavigation && !isSSR ? keyboardNav.handleContainerClick : undefined
+                }
+                onBlur={
+                  enableKeyboardNavigation && !isSSR ? keyboardNav.handleContainerBlur : undefined
+                }
+              >
+                <Table
+                  displayMode={displayMode}
+                  alignCells={{ x: "start", y: "center" }}
+                  alignHeaderCells={{ x: "start", y: "center" }}
+                  cellHeight={cellHeight}
+                  borderTopLeftRadius={hasToolbar ? 0 : knobProps.borderRadius.borderRadius}
+                  borderTopRightRadius={hasToolbar ? 0 : knobProps.borderRadius.borderRadius}
+                  borderBottomLeftRadius={knobProps.borderRadius.borderRadius}
+                  borderBottomRightRadius={knobProps.borderRadius.borderRadius}
+                  marginBottom={0}
+                  aria-label={ariaLabel || "Data table"}
+                  aria-rowcount={computed.totalPages * state.pagination.pageSize}
+                  aria-colcount={
+                    table.getVisibleLeafColumns().length + extraColumnsBefore + extraColumnsAfter
+                  }
+                  width="100%"
+                  {...(columnLayout === "scroll" && isWeb
+                    ? {
+                        overflowX: "auto" as any,
+                        style: { minWidth: "max-content", width: "max-content" },
+                      }
+                    : {})}
+                >
+                  {/* Table Header */}
+                  <Table.Head zIndex="$1" aria-label="Table headers">
+                    {headerGroups.map((headerGroup: any) => {
+                      rowCounter.current++;
+                      return (
+                        <Table.Row
+                          key={headerGroup.id}
+                          {...({
+                            background: true,
+                            backgroundColor: "$color2",
+                            rowLocation:
+                              rowCounter.current === 0
+                                ? "first"
+                                : rowCounter.current === allRowsLength - 1
+                                  ? "last"
+                                  : "middle",
+                            borderTopRightRadius: hasToolbar
+                              ? "$0"
+                              : knobProps.borderRadius.borderRadius,
+                            borderTopLeftRadius: hasToolbar
+                              ? "$0"
+                              : knobProps.borderRadius.borderRadius,
+                            borderBottomLeftRadius: "$0",
+                            borderBottomRightRadius: "$0",
+                            "aria-rowindex": rowCounter.current,
+                          } as any)}
+                        >
+                          {showRowNumbers && (
+                            <Table.HeaderCell
+                              cellWidth={50}
+                              cellHeight={cellHeight as any}
+                              cellLocation="first"
+                            >
+                              <Text fontSize="$4" fontWeight="600">
+                                #
+                              </Text>
+                            </Table.HeaderCell>
+                          )}
+
+                          {enableRowExpansion && (
+                            <Table.HeaderCell
+                              cellWidth={32}
+                              cellHeight={cellHeight as any}
+                              cellLocation={showRowNumbers ? "middle" : "first"}
+                            >
+                              <View width={14} />
+                            </Table.HeaderCell>
+                          )}
+
+                          {headerGroup.headers.map((header: any, headerIndex: number) => {
+                            const isSortableHeader = header.column.getCanSort();
+                            const sortDirection = header.column.getIsSorted();
+                            const canResize = enableColumnResizing && header.column.getCanResize();
+                            const resizeHandler = canResize ? header.getResizeHandler() : undefined;
+                            const colSize = header.getSize();
+                            const colMinSize = header.column.columnDef.minSize ?? 0;
+                            const colMaxSize =
+                              header.column.columnDef.maxSize ?? Number.MAX_SAFE_INTEGER;
+                            const stickyStyle = getStickyStyle(header.column.id);
+                            const columnField = getColumnField(
+                              header.column.columnDef as DataTableColumn,
+                            );
+                            const isNumeric = isNumericField(columnField);
+
+                            const isFirstHeaderCell =
+                              headerIndex === 0 && !showRowNumbers && !enableRowExpansion;
+                            const isLastHeaderCell =
+                              headerIndex === headerGroup.headers.length - 1 &&
+                              !(showDeleteRow && !readOnly);
+                            const headerCellLocation = isFirstHeaderCell
+                              ? "first"
+                              : isLastHeaderCell
+                                ? "last"
+                                : "middle";
+
+                            return (
+                              <Table.HeaderCell
+                                key={header.id}
+                                id={`${header.column.id}-header`}
+                                onPress={
+                                  isSortableHeader
+                                    ? header.column.getToggleSortingHandler()
+                                    : undefined
+                                }
+                                cursor={isSortableHeader ? "pointer" : "default"}
+                                position="relative"
+                                cellLocation={headerCellLocation}
+                                aria-sort={
+                                  isSortableHeader
+                                    ? sortDirection === "asc"
+                                      ? "ascending"
+                                      : sortDirection === "desc"
+                                        ? "descending"
+                                        : "none"
+                                    : undefined
+                                }
+                                {...(dnd
+                                  ? ({
+                                      draggable: true,
+                                      onDragStart: (e: React.DragEvent<HTMLElement>) =>
+                                        dnd.onDragStart(e, header.column.id),
+                                      onDragOver: dnd.onDragOver,
+                                      onDrop: (e: React.DragEvent<HTMLElement>) =>
+                                        dnd.onDrop(e, header.column.id),
+                                    } as any)
+                                  : {})}
+                                {...cellFlexProps}
+                                {...getColSizeProps(header.column)}
+                                {...(isWeb && stickyStyle
+                                  ? {
+                                      style: {
+                                        position: "sticky",
+                                        ...("left" in stickyStyle && { left: stickyStyle.left }),
+                                        ...("right" in stickyStyle && {
+                                          right: (stickyStyle as any).right,
+                                        }),
+                                        zIndex: 2,
+                                        backgroundColor: "var(--color2)",
+                                      } as React.CSSProperties,
+                                    }
+                                  : {})}
+                              >
+                                <View
+                                  flexDirection="row"
+                                  gap="$2"
+                                  alignItems="center"
+                                  justifyContent={isNumeric ? "flex-end" : "space-between"}
+                                  flex={1}
+                                >
+                                  <View
+                                    flexDirection="row"
+                                    gap="$2"
+                                    alignItems="center"
+                                    flex={isNumeric ? undefined : 1}
+                                    justifyContent={isNumeric ? "flex-end" : undefined}
+                                  >
+                                    <Text fontSize="$4" userSelect="none">
+                                      {header.isPlaceholder
+                                        ? null
+                                        : flexRender(
+                                            header.column.columnDef.header,
+                                            header.getContext(),
+                                          )}
+                                    </Text>
+                                    {isSortableHeader && (
+                                      <Tooltip
+                                        content={
+                                          sortDirection === "asc"
+                                            ? t("Sorted ascending (click to sort descending)")
+                                            : sortDirection === "desc"
+                                              ? t("Sorted descending (click to clear)")
+                                              : t("Click to sort (Shift+click for multi-sort)")
+                                        }
+                                      >
+                                        <View aria-hidden={true} role="presentation">
+                                          {sortDirection === "asc" && (
+                                            <CaretDownIcon
+                                              size={14}
+                                              color={
+                                                sortDirection ? "var(--color10)" : "var(--color8)"
+                                              }
+                                            />
+                                          )}
+                                          {sortDirection === "desc" && (
+                                            <CaretDownIcon
+                                              size={14}
+                                              color={
+                                                sortDirection ? "var(--color10)" : "var(--color8)"
+                                              }
+                                              style={{ transform: "rotate(180deg)" }}
+                                            />
+                                          )}
+                                          {sortDirection === false && (
+                                            <CaretUpDownIcon size={14} color="var(--color8)" />
+                                          )}
+                                        </View>
+                                      </Tooltip>
+                                    )}
+                                  </View>
+                                  <View flexDirection="row" gap="$1" alignItems="center">
+                                    {enableFiltering && header.column.getCanFilter() && (
+                                      <ColumnHeaderFilter
+                                        columnId={header.column.id}
+                                        columnLabel={
+                                          typeof header.column.columnDef.header === "string"
+                                            ? header.column.columnDef.header
+                                            : header.column.id
+                                        }
+                                        columnType={mapFieldToFilterType(
+                                          getColumnField(
+                                            header.column.columnDef as DataTableColumn,
+                                          ),
+                                        )}
+                                        filterValue={header.column.getFilterValue()}
+                                        onFilterChange={(value) =>
+                                          header.column.setFilterValue(value)
+                                        }
+                                        isFiltered={header.column.getIsFiltered()}
+                                        options={
+                                          (header.column.columnDef as any).fieldProps?.options
+                                        }
+                                      />
+                                    )}
+                                    {pinning && enableColumnPinning && (
+                                      <>
+                                        <pinning.PinButton
+                                          columnId={header.column.id}
+                                          position="left"
+                                        />
+                                        <pinning.PinButton
+                                          columnId={header.column.id}
+                                          position="right"
+                                        />
+                                      </>
+                                    )}
+                                  </View>
+                                </View>
+                                {canResize && resizeHandler && (
+                                  <View
+                                    position="absolute"
+                                    right={-4}
+                                    top={0}
+                                    height={2000}
+                                    width={8}
+                                    cursor="col-resize"
+                                    onMouseDown={resizeHandler as any}
+                                    onTouchStart={resizeHandler as any}
+                                    role="separator"
+                                    aria-valuenow={colSize}
+                                    aria-valuemin={colMinSize}
+                                    aria-valuemax={colMaxSize}
+                                    aria-label={`Resize ${header.column.columnDef.header || header.column.id} column`}
+                                    style={{ touchAction: "none" }}
+                                    zIndex={10}
+                                  />
+                                )}
+                              </Table.HeaderCell>
+                            );
+                          })}
+
+                          {showDeleteRow && !readOnly && (
+                            <Table.HeaderCell
+                              cellWidth={60}
+                              cellHeight={cellHeight as any}
+                              cellLocation="last"
+                            />
+                          )}
+                        </Table.Row>
+                      );
+                    })}
+                  </Table.Head>
+
+                  {/* Table Body */}
+                  <Table.Body aria-label="Table data">
+                    {tableRows.length === 0 ? (
+                      <Table.Row>
+                        <Table.Cell>
+                          <View
+                            padding="$8"
+                            alignItems="center"
+                            justifyContent="center"
+                            aria-live="polite"
+                          >
+                            <Text color="$color10" fontSize="$4">
+                              {computed.hasActiveFilters
+                                ? t("No results found")
+                                : t("No data available")}
+                            </Text>
+                          </View>
+                        </Table.Cell>
+                      </Table.Row>
+                    ) : isVirtualized ? (
+                      <Table.Row>
+                        <Table.Cell
+                          padding={0}
+                          style={{ display: "block", overflow: "hidden" } as any}
+                          {...({
+                            colSpan:
+                              table.getVisibleLeafColumns().length +
+                              extraColumnsBefore +
+                              extraColumnsAfter,
+                          } as any)}
+                        >
+                          <DataTableVirtualized
+                            virtualItems={virtualItems}
+                            totalSize={totalSize}
+                            bodyScrollRef={bodyScrollRef}
+                            virtualizationHeight={virtualizationHeight}
+                            tableRows={tableRows}
+                            headerGroups={headerGroups}
+                            showRowNumbers={showRowNumbers}
+                            enableRowExpansion={enableRowExpansion}
+                            showDeleteRow={showDeleteRow}
+                            readOnly={readOnly}
+                            enableKeyboardNavigation={enableKeyboardNavigation}
+                            keyboardNav={keyboardNav}
+                            getColSizeProps={getColSizeProps}
+                            renderRowContent={renderRowContent}
+                            extraColumnsBefore={extraColumnsBefore}
+                            extraColumnsAfter={extraColumnsAfter}
+                            table={table}
+                          />
+                        </Table.Cell>
+                      </Table.Row>
+                    ) : (
+                      <>
+                        {tableRows.map((row: any, index: number) => {
+                          rowCounter.current++;
+                          const isLastRow = index === tableRows.length - 1;
+
+                          // Grouped row: render a single header cell spanning all columns
+                          // with expand toggle, group label, and item count.
+                          if (enableGrouping && row.getIsGrouped?.()) {
+                            const colSpan =
+                              table.getVisibleLeafColumns().length +
+                              extraColumnsBefore +
+                              extraColumnsAfter;
+                            const indent = (row.depth ?? 0) * 16;
+                            return (
+                              <Table.Row
+                                key={row.id}
+                                backgroundColor="$color3"
+                                flexShrink={0}
+                                aria-rowindex={rowCounter.current}
+                              >
+                                <Table.Cell {...({ colSpan } as any)}>
+                                  <View
+                                    flexDirection="row"
+                                    alignItems="center"
+                                    gap="$2"
+                                    paddingLeft={indent}
+                                    cursor="pointer"
+                                    onPress={() => row.toggleExpanded()}
+                                  >
+                                    <Text fontFamily="$mono" fontSize="$3">
+                                      {row.getIsExpanded() ? "▼" : "▶"}
+                                    </Text>
+                                    <Text fontWeight="600">{String(row.groupingValue ?? "—")}</Text>
+                                    <Text color="$placeholderColor" fontSize="$2">
+                                      ({row.subRows?.length ?? 0})
+                                    </Text>
+                                  </View>
+                                </Table.Cell>
+                              </Table.Row>
+                            );
+                          }
+
+                          const mainRow = (
+                            <Table.Row
+                              backgroundColor={
+                                enableKeyboardNavigation &&
+                                keyboardNav.isNavigating &&
+                                index === keyboardNav.focusedRowIndex
+                                  ? "$color4"
+                                  : index % 2 === 0
+                                    ? "$color1"
+                                    : "$color2"
+                              }
+                              {...({ animation: "quick" } as any)}
+                              hoverStyle={{ backgroundColor: "$color3" }}
+                              flexShrink={0}
+                              rowLocation={
+                                rowCounter.current === 0
+                                  ? "first"
+                                  : rowCounter.current === allRowsLength - 1
+                                    ? "last"
+                                    : "middle"
+                              }
+                              key={`${row.id}-${index}`}
+                              aria-rowindex={rowCounter.current}
+                              aria-label={`Row ${index + 1}`}
+                              tabIndex={-1}
+                            >
+                              {renderRowContent(row, index, isLastRow)}
+                            </Table.Row>
+                          );
+
+                          const subRow =
+                            enableRowExpansion &&
+                            renderSubComponent &&
+                            row.getIsExpanded() &&
+                            !row.subRows?.length ? (
+                              <Table.Row key={`${row.id}-sub`} backgroundColor="$color2">
+                                <Table.Cell
+                                  {...({
+                                    colSpan:
+                                      table.getVisibleLeafColumns().length +
+                                      extraColumnsBefore +
+                                      extraColumnsAfter,
+                                  } as any)}
+                                >
+                                  {renderSubComponent(row)}
+                                </Table.Cell>
+                              </Table.Row>
+                            ) : null;
+
+                          return (
+                            <React.Fragment key={row.id}>
+                              {mainRow}
+                              {subRow}
+                            </React.Fragment>
+                          );
+                        })}
+                        {/* Filler row — fills remaining space with background */}
+                        {isFlexLayout && (
+                          <Table.Row
+                            key="filler-row"
+                            aria-hidden={true}
+                            backgroundColor="$color1"
+                            flex={1}
+                            flexShrink={1}
+                            flexGrow={1}
+                            flexBasis={0}
+                            minHeight={0}
+                          >
+                            {showRowNumbers && (
+                              <Table.Cell
+                                cellWidth={50}
+                                cellLocation="first"
+                                padding={0}
+                                minHeight={0}
+                              />
+                            )}
+                            {enableRowExpansion && (
+                              <Table.Cell
+                                cellWidth={32}
+                                cellLocation={showRowNumbers ? "middle" : "first"}
+                                padding={0}
+                                minHeight={0}
+                              />
+                            )}
+                            {headerGroups[0]?.headers.map((header: any, headerIndex: number) => {
+                              const isFirstDataCell =
+                                headerIndex === 0 && !showRowNumbers && !enableRowExpansion;
+                              const isLastDataCell =
+                                headerIndex === headerGroups[0].headers.length - 1 &&
+                                !(showDeleteRow && !readOnly);
+                              const cellLoc = isFirstDataCell
+                                ? "first"
+                                : isLastDataCell
+                                  ? "last"
+                                  : "middle";
+                              return (
+                                <Table.Cell
+                                  key={header.id}
+                                  {...cellFlexProps}
+                                  {...getColSizeProps(header.column)}
+                                  cellLocation={cellLoc}
+                                  padding={0}
+                                  minHeight={0}
+                                />
+                              );
+                            })}
+                            {showDeleteRow && !readOnly && (
+                              <Table.Cell
+                                cellWidth={60}
+                                cellLocation="last"
+                                padding={0}
+                                minHeight={0}
+                              />
+                            )}
+                          </Table.Row>
+                        )}
+                      </>
+                    )}
+                  </Table.Body>
+
+                  {/* Table Footer */}
+                  {hasFooter && (
+                    <Table.Foot>
+                      {footerGroups.map((footerGroup: any) => (
+                        <Table.Row key={footerGroup.id}>
+                          {footerGroup.headers.map((header: any) => (
+                            <Table.Cell key={header.id}>
+                              {header.isPlaceholder
+                                ? null
+                                : flexRender(header.column.columnDef.footer, header.getContext())}
+                            </Table.Cell>
+                          ))}
+                        </Table.Row>
+                      ))}
+                    </Table.Foot>
+                  )}
+                </Table>
+              </View>
+            )}
+
+            {/* Add Row Button */}
+            {showAddRow && !readOnly && (
+              <View>
+                <Button
+                  icon={PlusIcon}
+                  disabled={maxRows !== undefined && tableData.length >= maxRows}
+                  onPress={effectiveHandleAddRow}
+                  aria-label={t("Add Row")}
+                >
+                  {t("Add Row")}
+                </Button>
+              </View>
+            )}
+
+            {/* Pagination */}
+            {enablePagination && <View paddingTop="$3">{renderPaginationComponent()}</View>}
+
+            {/* Loading State */}
+            {state.isLoading && (
+              <View
+                position="absolute"
+                top={0}
+                left={0}
+                right={0}
+                bottom={0}
+                alignItems="center"
+                justifyContent="center"
+                zIndex={zIndex.loading}
+                aria-busy={true}
+                aria-live="assertive"
+                aria-label="Loading table data"
+                role="status"
+              >
+                <Spinner size="large" color="$color10" />
+              </View>
+            )}
+          </View>
+        </DataTableStateContext.Provider>
+      </DataTableContext.Provider>
+    );
+  };
+
+  // Form mode wrapper
+  if (isFormMode) {
+    return (
+      <Field form={resolvedForm} name={name!} mode="array">
+        {(field) => {
+          const formData = (field.state.value as TData[]) ?? [];
+          const setFormData = (next: TData[]) => field.handleChange(next as any);
+
+          return renderInner(
+            formData,
+            () => {
+              if (readOnly || (maxRows && formData.length >= maxRows)) return;
+              const newRow = { ...defaultRow, idx: formData.length + 1 } as unknown as TData;
+              setFormData([...formData, newRow]);
+            },
+            (idx: number) => {
+              if (readOnly || formData.length <= minRows) return;
+              setFormData(formData.filter((_, i) => i !== idx));
+            },
+            async (rowIndex: number, columnId: string, newValue: any) => {
+              if (readOnly) return;
+              const previousValue = formData[rowIndex]?.[columnId];
+              if (onCellChange) {
+                const result = await onCellChange(rowIndex, columnId, newValue, previousValue);
+                if (result === false) return;
+              }
+              const newData = [...formData];
+              newData[rowIndex] = { ...newData[rowIndex], [columnId]: newValue };
+              setFormData(newData);
+            },
+          );
+        }}
+      </Field>
+    );
+  }
+
+  // Standalone mode
+  return renderInner(data, handleAddRow, handleDeleteRow, handleCellChange);
+}