@multiplatform.one/table 7.8.0 → 7.11.0

package/src/components/DataTable/DataTableMobileCards.tsx

@@ -5,14 +5,18 @@
  * resolved layout is "cards" (below the `$sm` breakpoint with
  * layout="auto", or forced via layout="cards").
  *
- * Card anatomy (knobs system): `surface` + `cardSurface` fragments own
- * the card frame; the first visible column renders as the card title in
- * the header row (with selection checkbox / row number / delete), and
- * the remaining visible columns render as label/value rows. Column
- * visibility and order from table state apply unchanged — cells come
- * from `row.getVisibleCells()`. Values render through the same cell
- * renderers as the grid, inside `TableCellContext` so fields stay
- * chromeless (useIsInTableCell).
+ * Card anatomy: the first visible column is the card title in the header
+ * row (with selection checkbox / row number / delete). The remaining
+ * visible columns are NOT a stack of label/value rows any more — see
+ * `classifyCardField`. Column visibility and order from table state apply
+ * unchanged — cells come from `row.getVisibleCells()`. Values render
+ * through the same cell renderers as the grid, inside `TableCellContext`
+ * so fields stay chromeless (useIsInTableCell).
+ *
+ * The card is FLAT: no border, no elevation. A card list is drawn inside
+ * a panel that already has its own frame, and an outlined, shadowed card
+ * inside it reads as a box inside a box. The `cardSurface` fill and the
+ * gap between cards are what separate one row from the next.
  */
 
 import { TrashIcon } from "@phosphor-icons/react";
@@ -21,10 +25,10 @@ import { Button, Checkbox } from "@multiplatform.one/forms";
 import { hairline, useResolvedKnobs } from "@multiplatform.one/theme";
 import type React from "react";
 import { useCallback } from "react";
-import { Text, View, XStack } from "tamagui";
+import { Text, View, VisuallyHidden, XStack } from "tamagui";
 import { useTranslation } from "react-i18next";
 import { TableCellContext } from "@multiplatform.one/table-primitives";
-import type { DataTableColumn } from "../../types";
+import type { DataTableColumn, DataTableField } from "../../types";
 import { withInterp } from "../../utils/withInterp";
 import { rowIntentProps } from "./dataTableChrome";
 
@@ -34,13 +38,74 @@ import { rowIntentProps } from "./dataTableChrome";
  * header is a render function or a bare glyph (the liked heart) — without
  * it a card field row would print the raw column id (`_liked_by`).
  */
-function getColumnLabel(cell: any): string {
+export function getColumnLabel(cell: any): string {
   const columnDef = cell.column.columnDef as DataTableColumn;
   const metaLabel = columnDef.meta?.label;
   if (typeof metaLabel === "string" && metaLabel) return metaLabel;
   return typeof columnDef.header === "string" ? columnDef.header : columnDef.id || cell.column.id;
 }
 
+/** Fields that draw their own control, which names itself and needs a target. */
+const selfNamingFields = new Set<DataTableField>([
+  "checkbox",
+  "switch",
+  "rating",
+  "progress",
+  "image",
+  "signature",
+  "fileupload",
+  "colorpicker",
+  "barcode",
+  "geolocation",
+]);
+
+/** Column ids whose value is a state badge. A badge names itself. */
+const indicatorIds = new Set(["status", "priority", "workflow_state", "state"]);
+
+const dateLike = /^\d{4}-\d{2}-\d{2}([T ]|$)|^\d{1,2}\/\d{1,2}\/\d{2,4}$/;
+const numberLike = /^[+\-−]?[\d,\s]*\d(\.\d+)?%?$/;
+
+export type CardFieldKind = "skip" | "control" | "bare" | "figure";
+
+/**
+ * Whether a card field prints the column's name, and where it goes.
+ *
+ * A card is not the grid with its header repeated down the page. In the
+ * grid the header is written ONCE for a whole column of values; on a card
+ * it is written once per value, so a 12-column table prints 12 labels per
+ * record. That is what a label costs here, and most labels do not earn it.
+ *
+ *   skip     the raw value is absent. A field with nothing in it is not a
+ *            fact — "Rejected —" spends a row saying nothing.
+ *   control  a button, a switch, a rating. The control names itself and
+ *            needs its own tap target, so it keeps a row and takes no label.
+ *   bare     a string that is neither a number nor a date. "DIVIDEND
+ *            CREDIT" and "Income:Dividends" say what they are; "Payee" and
+ *            "Account" in front of them are the header printed twice. The
+ *            name is kept for assistive tech via VisuallyHidden, which
+ *            costs no layout.
+ *   figure   a number, a date, a boolean. "1,204" alone cannot be read, so
+ *            these DO keep their label — inline beside the figure, not in a
+ *            40%-wide column of its own.
+ */
+export function classifyCardField(cell: any): CardFieldKind {
+  const def = cell.column.columnDef as DataTableColumn;
+  const id = String(cell.column.id ?? "");
+  const role = def.meta?.role;
+  if (role === "hidden" || role === "skip") return "skip";
+  if (role === "actions" || id.startsWith("_") || (def.field && selfNamingFields.has(def.field))) {
+    return "control";
+  }
+  const raw = typeof cell.getValue === "function" ? cell.getValue() : undefined;
+  if (raw == null || (typeof raw === "string" && raw.trim() === "")) return "skip";
+  if (role === "indicator" || indicatorIds.has(id)) return "bare";
+  if (typeof raw === "string") {
+    const value = raw.trim();
+    return numberLike.test(value) || dateLike.test(value) ? "figure" : "bare";
+  }
+  return "figure";
+}
+
 export interface DataTableMobileCardsProps<TData> {
   tableRows: any[];
   enableRowSelection?: boolean;
@@ -98,6 +163,15 @@ export function DataTableMobileCards<TData extends Record<string, any>>({
   const { knobProps } = useResolvedKnobs({ component: "DataTable", compact });
   const tableZebraOn = knobProps.tableZebra === "on";
 
+  const renderCell = useCallback(
+    (cell: any, index: number, rowData: TData) => (
+      <TableCellContext.Provider value={{ inTableCell: true, isHeader: false }}>
+        {renderCellContent(cell, index, rowData)}
+      </TableCellContext.Provider>
+    ),
+    [renderCellContent],
+  );
+
   const renderMobileCard = useCallback(
     (row: any, index: number) => {
       const rowData = row.original as TData;
@@ -105,14 +179,22 @@ export function DataTableMobileCards<TData extends Record<string, any>>({
       const [titleCell, ...detailCells] = visibleCells;
       const showDelete = showDeleteRow && !readOnly;
 
+      const bare: any[] = [];
+      const figures: any[] = [];
+      const controls: any[] = [];
+      for (const cell of detailCells) {
+        const kind = classifyCardField(cell);
+        if (kind === "bare") bare.push(cell);
+        else if (kind === "figure") figures.push(cell);
+        else if (kind === "control") controls.push(cell);
+      }
+      const hasBody = bare.length > 0 || figures.length > 0 || controls.length > 0;
+
       return (
         <View
           key={`${row.id}-${index}`}
           testID="data-table-card"
-          {...knobProps.surface}
           {...knobProps.cardSurface}
-          elevation={knobProps.elevation}
-          borderColor="$color6"
           {...(tableZebraOn && index % 2 === 1 ? { backgroundColor: "$color2" } : {})}
           {...({
             "data-table-zebra": tableZebraOn ? (index % 2 === 0 ? "even" : "odd") : "off",
@@ -124,7 +206,7 @@ export function DataTableMobileCards<TData extends Record<string, any>>({
           <XStack
             alignItems="center"
             gap="$2"
-            {...(detailCells.length > 0
+            {...(hasBody
               ? {
                   paddingBottom: "$2",
                   marginBottom: "$2",
@@ -156,11 +238,10 @@ export function DataTableMobileCards<TData extends Record<string, any>>({
                 flex={1}
                 minWidth={0}
                 aria-label={getColumnLabel(titleCell)}
+                accessibilityLabel={getColumnLabel(titleCell)}
                 {...({ "data-card-slot": "title" } as any)}
               >
-                <TableCellContext.Provider value={{ inTableCell: true, isHeader: false }}>
-                  {renderCellContent(titleCell, index, rowData)}
-                </TableCellContext.Provider>
+                {renderCell(titleCell, index, rowData)}
               </View>
             ) : (
               <View flex={1} />
@@ -185,29 +266,71 @@ export function DataTableMobileCards<TData extends Record<string, any>>({
             )}
           </XStack>
 
-          {/* Field rows: remaining visible columns as label/value pairs */}
-          {detailCells.map((cell: any) => (
-            <View
-              key={cell.id}
-              flexDirection="row"
+          {/* Self-naming values, wrapped into one flow. No printed labels:
+              the name goes to assistive tech only, at no layout cost. */}
+          {bare.length > 0 ? (
+            <XStack
+              flexWrap="wrap"
               alignItems="center"
-              paddingVertical="$1.5"
               gap="$2"
+              {...({ "data-card-slot": "meta" } as any)}
             >
-              <Text
-                fontSize={knobProps.sizeToken}
-                color="$color10"
-                fontWeight="500"
-                width="40%"
-                flexShrink={0}
-              >
-                {getColumnLabel(cell)}
-              </Text>
-              <View flex={1} minWidth={0}>
-                <TableCellContext.Provider value={{ inTableCell: true, isHeader: false }}>
-                  {renderCellContent(cell, index, rowData)}
-                </TableCellContext.Provider>
-              </View>
+              {bare.map((cell: any, i: number) => (
+                <XStack key={cell.id} alignItems="center" gap="$2" flexShrink={1} minWidth={0}>
+                  <VisuallyHidden>{`${getColumnLabel(cell)}: `}</VisuallyHidden>
+                  <View flexShrink={1} minWidth={0}>
+                    {renderCell(cell, index, rowData)}
+                  </View>
+                  {/* The separator TRAILS its value, so a line that wraps
+                      starts with content instead of a stray dot. */}
+                  {i < bare.length - 1 ? (
+                    <Text
+                      fontSize={knobProps.sizeToken}
+                      color="$color8"
+                      aria-hidden
+                      accessibilityElementsHidden
+                      importantForAccessibility="no-hide-descendants"
+                    >
+                      ·
+                    </Text>
+                  ) : null}
+                </XStack>
+              ))}
+            </XStack>
+          ) : null}
+
+          {/* Figures keep their name, inline beside the value. */}
+          {figures.length > 0 ? (
+            <XStack
+              flexWrap="wrap"
+              alignItems="center"
+              gap="$3"
+              paddingTop={bare.length > 0 ? "$1.5" : 0}
+              {...({ "data-card-slot": "figure" } as any)}
+            >
+              {figures.map((cell: any) => (
+                <XStack key={cell.id} alignItems="center" gap="$1.5" flexShrink={1} minWidth={0}>
+                  <Text fontSize={knobProps.sizeToken} color="$color10" fontWeight="500">
+                    {getColumnLabel(cell)}
+                  </Text>
+                  <View flexShrink={1} minWidth={0}>
+                    {renderCell(cell, index, rowData)}
+                  </View>
+                </XStack>
+              ))}
+            </XStack>
+          ) : null}
+
+          {/* Controls keep a row of their own — they are tap targets. */}
+          {controls.map((cell: any) => (
+            <View
+              key={cell.id}
+              paddingTop="$2"
+              minWidth={0}
+              {...({ "data-card-slot": "control" } as any)}
+            >
+              <VisuallyHidden>{`${getColumnLabel(cell)}: `}</VisuallyHidden>
+              {renderCell(cell, index, rowData)}
             </View>
           ))}
         </View>
@@ -221,7 +344,7 @@ export function DataTableMobileCards<TData extends Record<string, any>>({
       disabled,
       dataLength,
       minRows,
-      renderCellContent,
+      renderCell,
       onDeleteRow,
       compact,
       knobProps,

package/src/components/DataTable/DataTableRoot.tsx

@@ -43,7 +43,7 @@ import type {
 } from "../../types";
 import { DataTableColumnPinning } from "../DataTableColumnPinning";
 import { DataTablePagination } from "../DataTablePagination";
-import { DataTableToolbar } from "../DataTableToolbar";
+import { DataTableCardToolbar, DataTableToolbar } from "../DataTableToolbar";
 import { DataTableBulkActions } from "../DataTableBulkActions";
 import { DataTableCell } from "../DataTableCell";
 import { ColumnHeaderFilter } from "../ColumnHeaderFilter";
@@ -56,7 +56,7 @@ import type {
   DataTableStateContextValue,
   FilterEditTarget,
 } from "./DataTableStateContext";
-import { DataTableCardControls } from "./DataTableCardControls";
+import { DataTableCardControls, DataTableCardSortControl } from "./DataTableCardControls";
 import { DataTableMobileCards } from "./DataTableMobileCards";
 import { DataTableDocumentList } from "./DataTableDocumentList";
 import { DataTableVirtualized } from "./DataTableVirtualized";
@@ -334,6 +334,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
           flexBasis: "auto" as const,
         };
       }
+      if (columnLayout === "equal" && !enableColumnResizing) return {};
       // Scroll layout needs one concrete width per column (from the column
       // def, TanStack default otherwise) so independent flex rows stay
       // aligned while the table grows past its container.
@@ -461,13 +462,13 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
       // flexBasis auto, not the `flex: 0` shorthand: RN expands `flex: 0` to
       // basis 0, which overrides per-column widths and crushes every cell to
       // the minWidth floor (contents then overflow and get clipped).
-      return { flexGrow: 0, flexShrink: 0, flexBasis: "auto" as const, minWidth: 80 };
+      return { flexGrow: 0, flexShrink: 0, flexBasis: "auto" as const, minWidth: 0 };
     }
     // Same flexBasis trap as the scroll branch above: `flex: 0` expands to
     // basis 0 and the per-column width from getColSizeProps loses, crushing
     // every resizable cell to the min-width floor (content then overlaps).
     if (enableColumnResizing) {
-      return { flexGrow: 0, flexShrink: 0, flexBasis: "auto" as const };
+      return { flexGrow: 0, flexShrink: 0, flexBasis: "auto" as const, minWidth: 0 };
     }
     return { flex: 1, flexShrink: 1, flexGrow: 1, flexBasis: 0, minWidth: 0 };
   }, [isFlexLayout, columnLayout, enableColumnResizing]);
@@ -1124,6 +1125,12 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
     [table, state, actions, computed, selectAllScope, filterUi],
   );
 
+  const hasCardSort =
+    showCards &&
+    enableSorting &&
+    table.getVisibleLeafColumns().some((column) => column.getCanSort());
+  const defaultCardToolbar = showCards && !renderToolbar;
+  const ToolbarComponent = defaultCardToolbar ? DataTableCardToolbar : DataTableToolbar;
   const renderToolbarComponent = () => {
     const activeFilterCount = table.getState().columnFilters?.length || 0;
 
@@ -1143,10 +1150,20 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
     }
 
     return (
-      <DataTableToolbar
+      <ToolbarComponent
         globalFilter={state.globalFilter || ""}
         onGlobalFilterChange={actions.setGlobalFilter}
         onClearFilters={actions.clearFilters}
+        customActions={
+          defaultCardToolbar && hasCardSort ? (
+            <DataTableCardSortControl
+              table={table}
+              compact={isCompact}
+              disabled={disabled}
+              contained
+            />
+          ) : undefined
+        }
         activeFilterCount={activeFilterCount}
         onSaveView={actions.saveView}
         onLoadView={actions.loadView}
@@ -1192,7 +1209,8 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
       newValue: any,
     ) => Promise<void>,
   ) => {
-    const hasToolbar = enableGlobalSearch || enableFiltering || enableViews;
+    const hasToolbar =
+      enableGlobalSearch || enableFiltering || enableViews || (defaultCardToolbar && hasCardSort);
     const scrollContainerRef = useRef<HTMLDivElement>(null);
 
     // DF-12 / Axiom 6 HONEST STATE — a height-constrained body clips rows
@@ -1347,14 +1365,16 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
               <>
                 {/* Header affordances (sort / per-column filter) live in the
                     grid headers; the card list restores them here. */}
-                <DataTableCardControls
-                  table={table}
-                  enableSorting={enableSorting}
-                  enableFiltering={enableFiltering}
-                  availableColumns={cardFilterColumns}
-                  compact={isCompact}
-                  disabled={disabled}
-                />
+                {!defaultCardToolbar && (
+                  <DataTableCardControls
+                    table={table}
+                    enableSorting={enableSorting}
+                    enableFiltering={enableFiltering}
+                    availableColumns={cardFilterColumns}
+                    compact={isCompact}
+                    disabled={disabled}
+                  />
+                )}
                 <DataTableMobileCards
                   tableRows={displayRows}
                   enableRowSelection={enableRowSelection}
@@ -2085,7 +2105,31 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                     <Table.Foot>
                       {footerGroups.map((footerGroup: any) => (
                         <Table.Row key={footerGroup.id}>
+                          {enableRowSelection && (
+                            <Table.Cell
+                              cellWidth={selectionColWidth}
+                              cellHeight={cellHeight as any}
+                              cellLocation="first"
+                            />
+                          )}
+                          {showRowNumbers && (
+                            <Table.Cell
+                              cellWidth={chrome.rowNumberCol}
+                              cellHeight={cellHeight as any}
+                              cellLocation={enableRowSelection ? "middle" : "first"}
+                            />
+                          )}
+                          {enableRowExpansion && (
+                            <Table.Cell
+                              cellWidth={chrome.expandCol}
+                              cellHeight={cellHeight as any}
+                              cellLocation={
+                                enableRowSelection || showRowNumbers ? "middle" : "first"
+                              }
+                            />
+                          )}
                           {footerGroup.headers.map((header: any) => {
+                            const stickyStyle = getStickyStyle(header.column.id);
                             const columnAlign = resolveColumnAlign({
                               ...(header.column.columnDef as DataTableColumn),
                               id: header.column.id,
@@ -2093,6 +2137,23 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                             return (
                               <Table.Cell
                                 key={header.id}
+                                {...cellFlexProps}
+                                {...getColSizeProps(header.column)}
+                                {...(isWeb && stickyStyle
+                                  ? {
+                                      style: {
+                                        position: "sticky",
+                                        ...("insetInlineStart" in stickyStyle && {
+                                          insetInlineStart: stickyStyle.insetInlineStart,
+                                        }),
+                                        ...("insetInlineEnd" in stickyStyle && {
+                                          insetInlineEnd: stickyStyle.insetInlineEnd,
+                                        }),
+                                        zIndex: 2,
+                                        backgroundColor: "var(--color2)",
+                                      } as React.CSSProperties,
+                                    }
+                                  : {})}
                                 justifyContent={alignToFlex(columnAlign)}
                                 data-align={columnAlign}
                               >
@@ -2115,6 +2176,13 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                               </Table.Cell>
                             );
                           })}
+                          {showDeleteRow && !readOnly && (
+                            <Table.Cell
+                              cellWidth={chrome.deleteCol}
+                              cellHeight={cellHeight as any}
+                              cellLocation="last"
+                            />
+                          )}
                         </Table.Row>
                       ))}
                     </Table.Foot>

package/src/components/DataTable/cardLayout.spec.tsx

@@ -7,7 +7,7 @@
  * breakpoint switch are exercised without resizing a window.
  *
  * Covers: breakpoint/override switching, card anatomy (title slot +
- * label/value rows), column visibility, sorting order, global search,
+ * classified fields), column visibility, sorting order, global search,
  * column filters, the card sort/filter controls, the SimpleTable layout
  * override, and the Table primitives card layout.
  */
@@ -127,7 +127,7 @@ describe("DataTable card layout", () => {
   });
 
   describe("card anatomy", () => {
-    it("renders the first visible column as the card title and the rest as label/value rows", () => {
+    it("renders the first visible column as the card title and classifies the rest", () => {
       const { container } = renderWithProviders(
         <DataTable data={sampleData} columns={columns} onStateChange={vi.fn()} />,
       );
@@ -140,15 +140,21 @@ describe("DataTable card layout", () => {
       expect(title!.textContent).toContain("John");
       expect(within(firstCard).queryByText("First Name")).toBeNull();
 
-      // Remaining visible columns render as label/value rows.
-      expect(within(firstCard).getByText("Last Name")).toBeDefined();
+      // A self-naming string goes bare. Its column name still reaches
+      // assistive tech, through a hidden node that costs no layout.
+      expect(within(firstCard).queryByText("Last Name")).toBeNull();
+      expect(within(firstCard).queryByText("Email")).toBeNull();
+      expect(firstCard.textContent).toContain("Last Name:");
+      expect(firstCard.textContent).toContain("Email:");
+
+      // A figure cannot be read without its name, so that one prints.
       expect(within(firstCard).getByText("Age")).toBeDefined();
-      expect(within(firstCard).getByText("Email")).toBeDefined();
+
       expect(firstCard.textContent).toContain("Doe");
       expect(firstCard.textContent).toContain("28");
     });
 
-    it("labels field rows from meta.label when the header is a render function", () => {
+    it("names a control from meta.label when the header is a render function", () => {
       const glyphColumns: DataTableColumn<Person>[] = [
         { id: "firstName", accessorKey: "firstName", header: "First Name" },
         {
@@ -162,7 +168,9 @@ describe("DataTable card layout", () => {
         <DataTable data={sampleData} columns={glyphColumns} onStateChange={vi.fn()} />,
       );
       const [firstCard] = getCards(container);
-      expect(within(firstCard).getByText("Liked")).toBeDefined();
+      // A leading underscore marks a control: its own row, no printed label.
+      expect(within(firstCard).queryByText("Liked")).toBeNull();
+      expect(firstCard.textContent).toContain("Liked:");
       expect(firstCard.textContent).not.toContain("_liked_by");
     });
 
@@ -180,9 +188,11 @@ describe("DataTable card layout", () => {
         <DataTable data={sampleData} columns={mixedColumns} onStateChange={vi.fn()} />,
       );
       const [firstCard] = getCards(container);
+      // A figure prints its name, a bare string hides it. meta.label wins
+      // either way, and the id fallback stays honest.
       expect(within(firstCard).getByText("Age (years)")).toBeDefined();
       expect(within(firstCard).queryByText("♥")).toBeNull();
-      expect(within(firstCard).getByText("email_addr")).toBeDefined();
+      expect(firstCard.textContent).toContain("email_addr:");
     });
 
     it("respects column visibility (hidden columns stay hidden in cards)", () => {
@@ -196,6 +206,7 @@ describe("DataTable card layout", () => {
       );
       const [firstCard] = getCards(container);
       expect(within(firstCard).queryByText("Email")).toBeNull();
+      expect(firstCard.textContent).not.toContain("Email:");
       expect(firstCard.textContent).not.toContain("john@example.com");
     });
   });
@@ -272,11 +283,12 @@ describe("DataTable card layout", () => {
       expect(titles).toEqual(["John"]);
     });
 
-    it("renders the filter chrome (Add Filter) in card layout", () => {
-      const { getByText } = renderWithProviders(
+    it("renders the canonical Filter in card layout", () => {
+      const { getByRole, queryByText } = renderWithProviders(
         <DataTable data={sampleData} columns={columns} onStateChange={vi.fn()} />,
       );
-      expect(getByText("Add Filter")).toBeDefined();
+      expect(getByRole("button", { name: "Filter" })).toBeDefined();
+      expect(queryByText("Add Filter")).toBeNull();
     });
 
     it("hides sort/filter chrome when sorting and filtering are disabled", () => {