@multiplatform.one/table 6.1.0 → 6.3.0

package/src/components/DataTable/index.native.tsx

@@ -7,20 +7,24 @@
 
 import {
   CaretDownIcon,
+  CaretLeftIcon,
   CaretRightIcon,
   CaretUpDownIcon,
   PlusIcon,
   TrashIcon,
 } from "@phosphor-icons/react";
 import { FlashList, type FlashListRef } from "@shopify/flash-list";
+import { AsyncBoundary, EmptyState, useDirection } from "@multiplatform.one/components";
 import { Button, Field, useFormField, zIndex } from "@multiplatform.one/forms";
 import { flexRender } from "@tanstack/react-table";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { hairline, useResolvedKnobs } from "@multiplatform.one/theme";
 import React, { useRef, useMemo, useCallback } from "react";
 import { ScrollView, Spinner, Text, View, useMedia, withStaticProperties } from "tamagui";
 import { useTranslation } from "react-i18next";
 import { useDataTable } from "../../hooks/useDataTable";
 import type { DataTableColumn, DataTableField } from "../../types";
+import { DEFAULT_PAGE_SIZE_OPTIONS } from "../../utils/paginationDefaults";
+import { withInterp } from "../../utils/withInterp";
 import { DataTableColumnPinning } from "../DataTableColumnPinning";
 import { DataTablePagination } from "../DataTablePagination";
 import { DataTableToolbar } from "../DataTableToolbar";
@@ -42,6 +46,32 @@ export { DataTableStateContext, useDataTableState } from "./DataTableStateContex
 export type { DataTableStateContextValue } from "./DataTableStateContext";
 export type { DataTableRootProps } from "./DataTableRoot";
 
+/**
+ * Renders a tanstack cell definition natively. RN drops raw string/number
+ * children inside a View ("Text strings must be rendered within a <Text>
+ * component"), and both tanstack's default cell and common custom cells
+ * (`cell: (info) => info.getValue()`) return primitives — on native those
+ * cells rendered blank. flexRender defers the call into an element, hiding
+ * the primitive from the caller, so this wrapper calls the renderer in its
+ * own render (hooks stay legal — same stability as flexRender's element)
+ * and wraps primitive output in <Text>.
+ */
+function NativeCellContent({
+  cellDef,
+  ctx,
+  fontSize,
+}: {
+  cellDef: unknown;
+  ctx: unknown;
+  fontSize?: any;
+}) {
+  const rendered = typeof cellDef === "function" ? cellDef(ctx) : cellDef;
+  if (typeof rendered === "string" || typeof rendered === "number") {
+    return <Text {...(fontSize ? { fontSize } : {})}>{String(rendered)}</Text>;
+  }
+  return rendered ?? null;
+}
+
 /** Maps field type to filter-compatible types */
 function mapFieldToFilterType(
   field?: DataTableField,
@@ -79,6 +109,7 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
   columns,
   initialState,
   onStateChange,
+  onRetry,
   syncWithUrl = false,
   urlDebounceMs = 500,
   urlStrategy,
@@ -88,11 +119,13 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
   enableFiltering = true,
   enableSorting = true,
   enablePagination = true,
+  pageSizeOptions,
   enableColumnVisibility = true,
   enableColumnOrdering = false,
   enableColumnResizing = false,
   enableGlobalSearch = true,
   enableViews = false,
+  layout = "auto",
   enableVirtualization = false,
   virtualizationHeight,
   virtualizationOverscan = 5,
@@ -120,6 +153,7 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
   className: _className,
   size,
   compact = false,
+  disabled = false,
   children,
   "aria-label": ariaLabel,
   "aria-describedby": ariaDescribedBy,
@@ -127,7 +161,20 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
 }: DataTableRootProps<TData>) {
   const { t } = useTranslation();
   const { sm } = useMedia();
-  const { knobProps } = useResolvedKnobs({ intent: undefined, component: "DataTable", compact });
+  // Native keeps its certified card pattern; the `layout` prop only pins a
+  // mode ("table" forces the grid, "cards" forces cards, default auto = !sm).
+  const showCards = layout === "cards" || (layout === "auto" && !sm);
+  const { knobProps, disabledState } = useResolvedKnobs({
+    intent: undefined,
+    component: "DataTable",
+    compact,
+  });
+  // Collapsed expand-caret points toward inline-end, so it mirrors in RTL via
+  // glyph swap (useDirection, Axiom 15); rotation sign flips so expanded
+  // still points down.
+  const isRTL = useDirection() === "rtl";
+  const ExpandCaretIcon = isRTL ? CaretLeftIcon : CaretRightIcon;
+  const expandedCaretRotation = isRTL ? "rotate(-90deg)" : "rotate(90deg)";
   const { resolvedForm } = useFormField({ form: formProp });
 
   const isFormMode = Boolean(name && resolvedForm);
@@ -209,21 +256,28 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
   const isVirtualized =
     enableVirtualization && virtualizationHeight != null && virtualizationHeight > 0;
 
-  const pinning = useMemo(
-    () =>
-      enableColumnPinning
-        ? DataTableColumnPinning({ table, maxPinnedColumns, allowPinning: true })
-        : null,
-    [enableColumnPinning, table, maxPinnedColumns],
-  );
+  // DataTableColumnPinning is a hook-style helper (it calls useState/useMemo/
+  // useCallback internally), so it must run unconditionally at the top level —
+  // the previous useMemo wrapper made its hooks conditional (crash class the
+  // web variant already fixed).
+  const pinningHelpers = DataTableColumnPinning({
+    table,
+    maxPinnedColumns,
+    allowPinning: true,
+    disabled,
+  });
+  const pinning = enableColumnPinning ? pinningHelpers : null;
 
   const extraColumnsBefore = (showRowNumbers ? 1 : 0) + (enableRowExpansion ? 1 : 0);
   const extraColumnsAfter = showDeleteRow && !readOnly ? 1 : 0;
 
   const handleCellChange = useCallback(
     async (rowIndex: number, columnId: string, newValue: any) => {
-      if (readOnly) return;
+      if (readOnly || disabled) return;
       const previousValue = data[rowIndex]?.[columnId];
+      // Bail on no-op commits so a field that re-emits the same primitive value
+      // (e.g. OTP sync effects) cannot force a new data array every render.
+      if (Object.is(previousValue, newValue)) return;
       if (onCellChange) {
         const result = await onCellChange(rowIndex, columnId, newValue, previousValue);
         if (result === false) return;
@@ -234,25 +288,25 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
         onDataChange(newData);
       }
     },
-    [readOnly, data, onCellChange, isFormMode, onDataChange],
+    [readOnly, disabled, data, onCellChange, isFormMode, onDataChange],
   );
 
   const handleAddRow = useCallback(() => {
-    if (readOnly || (maxRows && data.length >= maxRows)) return;
+    if (readOnly || disabled || (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]);
+  }, [readOnly, disabled, maxRows, data, defaultRow, isFormMode, onDataChange]);
 
   const handleDeleteRow = useCallback(
     (rowIndex: number) => {
-      if (readOnly || data.length <= minRows) return;
+      if (readOnly || disabled || data.length <= minRows) return;
       if (!isFormMode && onDataChange) {
         onDataChange(data.filter((_, idx) => idx !== rowIndex));
       }
     },
-    [readOnly, minRows, data, isFormMode, onDataChange],
+    [readOnly, disabled, minRows, data, isFormMode, onDataChange],
   );
 
   const isCompact = resolvedSize === "sm" || compact;
@@ -263,7 +317,18 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
       const value = cell.getValue();
 
       if (columnDef.cell && !columnDef.field) {
-        return flexRender(columnDef.cell, cell.getContext());
+        // TanStack injects a default cell renderer that returns the raw value,
+        // and story/consumer columns commonly do `cell: (info) => info.getValue()`;
+        // raw strings/numbers outside <Text> are dropped on native. flexRender
+        // hides function-cell primitives inside an element, so NativeCellContent
+        // calls the renderer itself and wraps primitive output.
+        return (
+          <NativeCellContent
+            cellDef={columnDef.cell}
+            ctx={cell.getContext()}
+            fontSize={knobProps.sizeToken}
+          />
+        );
       }
 
       return (
@@ -273,13 +338,15 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
           fieldProps={columnDef.fieldProps}
           onChange={(newValue) => handleCellChange(rowIndex, columnId, newValue)}
           readOnly={readOnly}
+          disabled={disabled}
           columnId={columnId}
+          columnLabel={typeof columnDef.header === "string" ? columnDef.header : undefined}
           rowIndex={rowIndex}
           rowData={rowData}
         />
       );
     },
-    [handleCellChange, readOnly],
+    [handleCellChange, readOnly, disabled, knobProps.sizeToken],
   );
 
   const renderRowContent = useCallback(
@@ -302,15 +369,27 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
             >
               {row.getCanExpand() ? (
                 <View
-                  onPress={() => row.toggleExpanded()}
-                  cursor="pointer"
+                  onPress={() => {
+                    if (disabled) return;
+                    row.toggleExpanded();
+                  }}
+                  cursor={disabled ? "not-allowed" : "pointer"}
+                  aria-disabled={disabled || undefined}
                   padding="$1"
                   aria-expanded={row.getIsExpanded()}
-                  aria-label={row.getIsExpanded() ? "Collapse row" : "Expand row"}
+                  aria-label={
+                    row.getIsExpanded()
+                      ? withInterp(t("Collapse row {{row}}", { row: rowIndex + 1 }), {
+                          row: rowIndex + 1,
+                        })
+                      : withInterp(t("Expand row {{row}}", { row: rowIndex + 1 }), {
+                          row: rowIndex + 1,
+                        })
+                  }
                 >
-                  <CaretRightIcon
+                  <ExpandCaretIcon
                     size={14}
-                    style={{ transform: row.getIsExpanded() ? "rotate(90deg)" : "none" }}
+                    style={{ transform: row.getIsExpanded() ? expandedCaretRotation : "none" }}
                   />
                 </View>
               ) : (
@@ -345,9 +424,11 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                 chromeless
                 circular
                 icon={TrashIcon}
-                disabled={data.length <= minRows}
+                disabled={disabled || data.length <= minRows}
                 onPress={() => handleDeleteRow(rowIndex)}
-                aria-label={t("Delete row")}
+                aria-label={withInterp(t("Delete row {{row}}", { row: rowIndex + 1 }), {
+                  row: rowIndex + 1,
+                })}
               />
             </Table.Cell>
           )}
@@ -359,6 +440,7 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
       enableRowExpansion,
       showDeleteRow,
       readOnly,
+      disabled,
       cellHeight,
       knobProps.sizeToken,
       getColSizeProps,
@@ -367,22 +449,29 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
       data.length,
       minRows,
       t,
+      ExpandCaretIcon,
+      expandedCaretRotation,
     ],
   );
 
+  const tableZebraOn = knobProps.tableZebra === "on";
+
   const renderRow = useCallback(
     (row: (typeof tableRows)[0], index: number) => (
       <Table.Row
-        backgroundColor={index % 2 === 0 ? "$color1" : "$color2"}
+        backgroundColor={tableZebraOn && index % 2 === 1 ? "$color2" : "$color1"}
         rowLocation="middle"
         key={`${row.id}-${index}`}
         aria-rowindex={index + 1}
-        aria-label={`Row ${index + 1}`}
+        aria-label={withInterp(t("Row {{row}}", { row: index + 1 }), { row: index + 1 })}
+        {...({
+          "data-table-zebra": tableZebraOn ? (index % 2 === 0 ? "even" : "odd") : "off",
+        } as any)}
       >
         {renderRowContent(row, index)}
       </Table.Row>
     ),
-    [renderRowContent],
+    [renderRowContent, tableZebraOn, t],
   );
 
   const renderMobileCard = useCallback(
@@ -404,7 +493,7 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
               flexDirection="row"
               justifyContent="space-between"
               paddingBottom="$2"
-              borderBottomWidth={1}
+              {...hairline.bottom}
               borderBottomColor="$borderColor"
               marginBottom="$2"
             >
@@ -417,9 +506,11 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                   circular
                   size="$2"
                   icon={TrashIcon}
-                  disabled={tableRows.length <= minRows}
+                  disabled={disabled || tableRows.length <= minRows}
                   onPress={() => onDelete?.(index)}
-                  aria-label={t("Delete row")}
+                  aria-label={withInterp(t("Delete row {{row}}", { row: index + 1 }), {
+                    row: index + 1,
+                  })}
                 />
               )}
             </View>
@@ -452,16 +543,27 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                 circular
                 size="$2"
                 icon={TrashIcon}
-                disabled={tableRows.length <= minRows}
+                disabled={disabled || tableRows.length <= minRows}
                 onPress={() => onDelete?.(index)}
-                aria-label={t("Delete row")}
+                aria-label={withInterp(t("Delete row {{row}}", { row: index + 1 }), {
+                  row: index + 1,
+                })}
               />
             </View>
           )}
         </View>
       );
     },
-    [showRowNumbers, showDeleteRow, readOnly, tableRows.length, minRows, renderCellContent, t],
+    [
+      showRowNumbers,
+      showDeleteRow,
+      readOnly,
+      disabled,
+      tableRows.length,
+      minRows,
+      renderCellContent,
+      t,
+    ],
   );
 
   const renderToolbarComponent = () => {
@@ -493,18 +595,19 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
   };
 
   const renderPaginationComponent = () => {
+    const resolvedPageSizeOptions = pageSizeOptions ?? [...DEFAULT_PAGE_SIZE_OPTIONS];
     if (renderPagination) {
       return renderPagination({
         pagination: state.pagination,
         onPaginationChange: actions.setPagination,
-        pageSizeOptions: [10, 20, 50, 100],
+        pageSizeOptions: resolvedPageSizeOptions,
       });
     }
     return (
       <DataTablePagination
         pagination={state.pagination}
         onPaginationChange={actions.setPagination}
-        pageSizeOptions={[10, 20, 50, 100]}
+        pageSizeOptions={resolvedPageSizeOptions}
         showInfo={!sm}
       />
     );
@@ -518,15 +621,32 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
   const renderTableInner = useCallback(
     (tableData: TData[], setTableData?: (d: TData[]) => void) => {
       const effectiveHandleAddRow = () => {
-        if (readOnly || (maxRows && tableData.length >= maxRows)) return;
+        if (readOnly || disabled || (maxRows && tableData.length >= maxRows)) return;
         const newRow = { ...defaultRow, idx: tableData.length + 1 } as unknown as TData;
         setTableData?.([...tableData, newRow]);
       };
       const effectiveHandleDeleteRow = (rowIndex: number) => {
-        if (readOnly || tableData.length <= minRows) return;
+        if (readOnly || disabled || tableData.length <= minRows) return;
         setTableData?.(tableData.filter((_, idx) => idx !== rowIndex));
       };
 
+      // W9 / DG-ST-01,02,04 — error wins over empty; initial load uses table skeleton.
+      if (state.error) {
+        return (
+          <AsyncBoundary
+            error={state.error}
+            onRetry={onRetry}
+            layout="table"
+            errorTitle={t("Couldn't load table")}
+            compact
+            aria-label={ariaLabel || "Data table"}
+          />
+        );
+      }
+      if (state.isLoading && tableRows.length === 0) {
+        return <AsyncBoundary loading layout="table" aria-label={ariaLabel || "Data table"} />;
+      }
+
       return (
         <DataTableContext.Provider size={resolvedSize} compact={isCompact}>
           <DataTableStateContext.Provider value={stateContextValue}>
@@ -538,9 +658,25 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
               aria-live="polite"
               aria-atomic="false"
               {...knobProps.borderRadius}
+              // UX-011 / Axiom 6 HONEST STATE: `disabled` makes the whole
+              // assembly inert (pointerEvents none blocks every touch) and
+              // says so (aria-disabled). LC-40 assembly fragment carries the
+              // dimWhole visual; keepLabel washes per-control chrome (cells,
+              // buttons receive their own `disabled`).
+              aria-disabled={disabled || undefined}
+              {...(disabled
+                ? {
+                    ...disabledState.assemblyKnobProps,
+                    pointerEvents: "none" as const,
+                  }
+                : {})}
               {...props}
             >
-              {(enableGlobalSearch || enableFiltering || enableViews) && renderToolbarComponent()}
+              {(enableGlobalSearch || enableFiltering || enableViews) && (
+                <View width="100%" {...(disabled ? disabledState.chromeKnobProps : {})}>
+                  {renderToolbarComponent()}
+                </View>
+              )}
               {children}
               {renderFilters?.({
                 filters: state.filters || [],
@@ -555,21 +691,18 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                 })),
               })}
 
-              {!sm ? (
+              {showCards ? (
                 <View flexDirection="column" gap="$2">
                   {tableRows.length === 0 ? (
-                    <View
-                      padding="$8"
-                      alignItems="center"
-                      justifyContent="center"
+                    <EmptyState
+                      compact
                       backgroundColor="$color1"
                       borderRadius="$4"
                       aria-live="polite"
-                    >
-                      <Text color="$color10" fontSize="$4">
-                        {computed.hasActiveFilters ? t("No results found") : t("No data available")}
-                      </Text>
-                    </View>
+                      title={
+                        computed.hasActiveFilters ? t("No results found") : t("No data available")
+                      }
+                    />
                   ) : (
                     tableRows.map((row, index) =>
                       renderMobileCard(
@@ -579,7 +712,11 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                       ),
                     )
                   )}
-                  {enablePagination && renderPaginationComponent()}
+                  {enablePagination && (
+                    <View width="100%" {...(disabled ? disabledState.chromeKnobProps : {})}>
+                      {renderPaginationComponent()}
+                    </View>
+                  )}
                 </View>
               ) : (
                 <ScrollView horizontal maxWidth="100%">
@@ -638,11 +775,17 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                                   key={header.id}
                                   id={`${header.column.id}-header`}
                                   onPress={
-                                    isSortableHeader
+                                    isSortableHeader && !disabled
                                       ? header.column.getToggleSortingHandler()
                                       : undefined
                                   }
-                                  cursor={isSortableHeader ? "pointer" : "default"}
+                                  cursor={
+                                    disabled
+                                      ? "not-allowed"
+                                      : isSortableHeader
+                                        ? "pointer"
+                                        : "default"
+                                  }
                                   position="relative"
                                   aria-sort={
                                     isSortableHeader
@@ -688,14 +831,9 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                                     )}
                                     {pinning && (
                                       <View flexDirection="row" gap="$1">
-                                        <pinning.PinButton
-                                          columnId={header.column.id}
-                                          position="left"
-                                        />
-                                        <pinning.PinButton
-                                          columnId={header.column.id}
-                                          position="right"
-                                        />
+                                        {/* One compact cycle control (left →
+                                            right → unpin) mirrors web. */}
+                                        <pinning.PinButton columnId={header.column.id} />
                                       </View>
                                     )}
                                   </View>
@@ -717,18 +855,15 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                         {tableRows.length === 0 ? (
                           <Table.Row>
                             <Table.Cell>
-                              <View
-                                padding="$8"
-                                alignItems="center"
-                                justifyContent="center"
+                              <EmptyState
+                                compact
                                 aria-live="polite"
-                              >
-                                <Text color="$color10" fontSize="$4">
-                                  {computed.hasActiveFilters
+                                title={
+                                  computed.hasActiveFilters
                                     ? t("No results found")
-                                    : t("No data available")}
-                                </Text>
-                              </View>
+                                    : t("No data available")
+                                }
+                              />
                             </Table.Cell>
                           </Table.Row>
                         ) : isVirtualized ? (
@@ -778,12 +913,12 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                             <Table.Row key={footerGroup.id}>
                               {footerGroup.headers.map((header) => (
                                 <Table.Cell key={header.id}>
-                                  {header.isPlaceholder
-                                    ? null
-                                    : flexRender(
-                                        header.column.columnDef.footer,
-                                        header.getContext(),
-                                      )}
+                                  {header.isPlaceholder ? null : (
+                                    <NativeCellContent
+                                      cellDef={header.column.columnDef.footer}
+                                      ctx={header.getContext()}
+                                    />
+                                  )}
                                 </Table.Cell>
                               ))}
                             </Table.Row>
@@ -799,7 +934,7 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                 <View>
                   <Button
                     icon={PlusIcon}
-                    disabled={maxRows !== undefined && tableData.length >= maxRows}
+                    disabled={disabled || (maxRows !== undefined && tableData.length >= maxRows)}
                     onPress={isFormMode ? effectiveHandleAddRow : handleAddRow}
                     aria-label={t("Add Row")}
                   >
@@ -808,7 +943,11 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
                 </View>
               )}
 
-              {sm && enablePagination && renderPaginationComponent()}
+              {!showCards && enablePagination && (
+                <View width="100%" {...(disabled ? disabledState.chromeKnobProps : {})}>
+                  {renderPaginationComponent()}
+                </View>
+              )}
 
               {state.isLoading && (
                 <View
@@ -872,6 +1011,7 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
       renderSubComponent,
       footerGroups,
       sm,
+      showCards,
       renderPaginationComponent,
       showAddRow,
       maxRows,
@@ -880,6 +1020,8 @@ function DataTableRoot<TData extends Record<string, any> = Record<string, any>>(
       handleDeleteRow,
       minRows,
       defaultRow,
+      disabled,
+      disabledState,
       t,
     ],
   );
@@ -904,6 +1046,7 @@ export const DataTable = withStaticProperties(DataTableRoot, {
   Filters: DataTableFilters,
   Pagination: DataTablePagination,
   BulkActions: DataTableBulkActions,
+  SelectionToolbar: DataTableBulkActions,
   Export: DataTableExport,
   Search: DataTableSearch,
   ViewOptions: DataTableViewOptions,

package/src/components/DataTable/index.tsx

@@ -35,6 +35,8 @@ export const DataTable = withStaticProperties(DataTableRoot, {
   Filters: DataTableFilters,
   Pagination: DataTablePagination,
   BulkActions: DataTableBulkActions,
+  /** Alias for BulkActions — auto-shown by DataTableRoot when enableRowSelection is on. */
+  SelectionToolbar: DataTableBulkActions,
   Export: DataTableExport,
   Search: DataTableSearch,
   ViewOptions: DataTableViewOptions,