@multiplatform.one/table 6.7.0 → 7.1.0

package/src/components/DataTable/DataTableRoot.tsx

@@ -17,7 +17,7 @@ import {
   PlusIcon,
   TrashIcon,
 } from "@phosphor-icons/react";
-import { Button, Checkbox, Field, Spinner, useFormField, zIndex } from "@multiplatform.one/forms";
+import { Button, Checkbox, Field, useFormField } from "@multiplatform.one/forms";
 import { flexRender } from "@tanstack/react-table";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { ensureFocusVisibleRing, useResolvedKnobs } from "@multiplatform.one/theme";
@@ -58,7 +58,9 @@ import type {
 } from "./DataTableStateContext";
 import { DataTableCardControls } from "./DataTableCardControls";
 import { DataTableMobileCards } from "./DataTableMobileCards";
+import { DataTableDocumentList } from "./DataTableDocumentList";
 import { DataTableVirtualized } from "./DataTableVirtualized";
+import { tableCellKeyboardProps, tableRowStateProps } from "./rowStateChrome";
 import { alignToFlex, getDefaultColumnAlign } from "../../utils/columnAlign";
 import { mapFieldToFilterType } from "../../utils/filterFields";
 import { INFINITE_TRIGGER_ROWS } from "../../utils/paginationDefaults";
@@ -103,8 +105,11 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
   data,
   columns,
   initialState,
+  controlledState,
   onStateChange,
   onRetry,
+  isLoading: isLoadingProp,
+  isFetching: isFetchingProp,
   syncWithUrl = false,
   urlDebounceMs = 500,
   urlStrategy,
@@ -169,7 +174,8 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
   const { sm } = useMedia();
   // Resolved responsive layout: cards below `$sm` (W11 compact class) unless
   // pinned via the `layout` prop. Same table state drives both layouts.
-  const showCards = layout === "cards" || (layout === "auto" && sm === false);
+  const showList = layout === "list";
+  const showCards = !showList && (layout === "cards" || (layout === "auto" && sm === false));
   const { knobProps, disabledState } = useResolvedKnobs({
     intent: undefined,
     component: "DataTable",
@@ -194,6 +200,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
     data,
     columns,
     initialState,
+    controlledState,
     onStateChange,
     syncWithUrl,
     urlDebounceMs,
@@ -226,6 +233,8 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
     enableRowSelection,
     rowCount,
     pageCount,
+    isLoading: isLoadingProp,
+    isFetching: isFetchingProp,
   });
 
   const resolvedBulkActions = (bulkActions ?? []) as BulkAction<TData>[];
@@ -260,6 +269,23 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
   // already just the accumulated rows, so the slice is a no-op there.
   const infinite = computed.infinite;
   const tableRows = infinite ? rowModelRows.slice(0, infinite.visibleRowCount) : rowModelRows;
+  const heldRowsRef = useRef(tableRows);
+  if (tableRows.length > 0) {
+    heldRowsRef.current = tableRows;
+  }
+  const queryInFlight = Boolean(
+    state.isFetching ||
+    state.isPlaceholderData ||
+    infinite?.isAppending ||
+    state.isLoading ||
+    infinite?.isInitialLoading,
+  );
+  const displayRows =
+    tableRows.length > 0
+      ? tableRows
+      : queryInFlight && heldRowsRef.current.length > 0
+        ? heldRowsRef.current
+        : tableRows;
   const footerGroups = table.getFooterGroups();
 
   const hasFooter = footerGroups.some((group: any) =>
@@ -267,7 +293,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
   );
 
   const allRowsLength =
-    tableRows.length + headerGroups.length + (hasFooter ? footerGroups.length : 0);
+    displayRows.length + headerGroups.length + (hasFooter ? footerGroups.length : 0);
   const rowCounter = useRef(-1);
   rowCounter.current = -1;
 
@@ -349,7 +375,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
   // appended pages grow geometry instead of collapsing it.
   const hasInfiniteTail = Boolean(infinite && !infinite.exhausted && tableRows.length > 0);
   const virtualizer = useVirtualizer({
-    count: tableRows.length + (hasInfiniteTail ? 1 : 0),
+    count: displayRows.length + (hasInfiniteTail ? 1 : 0),
     getScrollElement: () => bodyScrollRef.current,
     estimateSize: () => rowHeightPx,
     overscan: virtualizationOverscan,
@@ -475,6 +501,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
         }
       : undefined,
   });
+  const [focusedColIndex, setFocusedColIndex] = useState(0);
 
   const isSSR = typeof window === "undefined";
 
@@ -484,7 +511,8 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
   // LC-49 roving anchor: the row set exposes exactly one tab stop — the
   // focused row while focus is inside the set, else the first row.
   const [rowPressAnchor, setRowPressAnchor] = useState(0);
-  const effectiveRowPressAnchor = Math.min(rowPressAnchor, Math.max(tableRows.length - 1, 0));
+  const [rowPressHasFocus, setRowPressHasFocus] = useState(false);
+  const effectiveRowPressAnchor = Math.min(rowPressAnchor, Math.max(displayRows.length - 1, 0));
 
   // Row identity for accessible names (DG-A11Y-06): consumer accessor →
   // first visible column's cell value → undefined (caller picks its own
@@ -573,15 +601,21 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
               tabIndex: rowIndex === effectiveRowPressAnchor ? 0 : -1,
               focusVisibleStyle: ensureFocusVisibleRing({ outlineOffset: -2 }),
               "data-row-press": "true",
+              "data-row-keyboard-focus":
+                rowIndex === effectiveRowPressAnchor && rowPressHasFocus ? "true" : "false",
               onFocus: (e: React.FocusEvent) => {
                 // Only a focused ROW moves the anchor; focus on an inner
                 // control (own tab stop) leaves the roving state alone.
-                if (e.target === e.currentTarget) setRowPressAnchor(rowIndex);
+                if (e.target === e.currentTarget) {
+                  setRowPressAnchor(rowIndex);
+                  setRowPressHasFocus(true);
+                }
               },
               onBlur: (e: React.FocusEvent) => {
                 const next = e.relatedTarget;
                 if (!(next instanceof Element) || !next.closest('[data-row-press="true"]')) {
                   setRowPressAnchor(0);
+                  setRowPressHasFocus(false);
                 }
               },
               onKeyDown: (e: React.KeyboardEvent) => {
@@ -626,7 +660,14 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
           : {}),
       };
     },
-    [rowPressActive, deriveRowLabel, activateRowPress, effectiveRowPressAnchor, isSSR],
+    [
+      rowPressActive,
+      deriveRowLabel,
+      activateRowPress,
+      effectiveRowPressAnchor,
+      isSSR,
+      rowPressHasFocus,
+    ],
   );
 
   const handleCellChange = useCallback(
@@ -736,6 +777,25 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
   const extraColumnsBefore =
     (enableRowSelection ? 1 : 0) + (showRowNumbers ? 1 : 0) + (enableRowExpansion ? 1 : 0);
   const extraColumnsAfter = showDeleteRow && !readOnly ? 1 : 0;
+  const excelCellNav = enableKeyboardNavigation && !rowPressActive && !disabled;
+  const gridColCount = Math.max(
+    table.getVisibleLeafColumns().length + extraColumnsBefore + extraColumnsAfter,
+    1,
+  );
+  const handleGridKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (!enableKeyboardNavigation || disabled) return;
+      if (excelCellNav) {
+        if (event.key === "ArrowRight") {
+          setFocusedColIndex((i) => Math.min(i + 1, gridColCount - 1));
+        } else if (event.key === "ArrowLeft") {
+          setFocusedColIndex((i) => Math.max(i - 1, 0));
+        }
+      }
+      keyboardNav.handleKeyDown(event);
+    },
+    [disabled, enableKeyboardNavigation, excelCellNav, gridColCount, keyboardNav],
+  );
 
   const getStickyStyle = useCallback(
     (columnId: string) => {
@@ -806,12 +866,21 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
     (row: any, rowIndex: number, _isLastRow: boolean, cellElement?: "div") => {
       const rowData = row.original as TData;
       const cellRenderProps = cellElement ? ({ render: cellElement } as any) : {};
+      let cellSlot = 0;
+      const cellNavProps = () => {
+        const slot = cellSlot++;
+        if (!excelCellNav || !keyboardNav.isNavigating) return {};
+        return tableCellKeyboardProps(
+          rowIndex === keyboardNav.focusedRowIndex && slot === focusedColIndex,
+        );
+      };
 
       return (
         <>
           {enableRowSelection && (
             <Table.Cell
               {...cellRenderProps}
+              {...cellNavProps()}
               cellWidth={SELECTION_COL_WIDTH}
               cellHeight={cellHeight as any}
               cellLocation="first"
@@ -838,6 +907,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
           {showRowNumbers && (
             <Table.Cell
               {...cellRenderProps}
+              {...cellNavProps()}
               cellWidth={50}
               cellHeight={cellHeight as any}
               cellLocation={enableRowSelection ? "middle" : "first"}
@@ -851,6 +921,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
           {enableRowExpansion && (
             <Table.Cell
               {...cellRenderProps}
+              {...cellNavProps()}
               cellWidth={32 + row.depth * 20}
               cellHeight={cellHeight as any}
               cellLocation={enableRowSelection || showRowNumbers ? "middle" : "first"}
@@ -945,6 +1016,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
               <Table.Cell
                 key={cell.id}
                 {...cellRenderProps}
+                {...cellNavProps()}
                 {...cellFlexProps}
                 {...getColSizeProps(cell.column)}
                 cellHeight={cellHeight as any}
@@ -976,6 +1048,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
           {showDeleteRow && !readOnly && (
             <Table.Cell
               {...cellRenderProps}
+              {...cellNavProps()}
               cellWidth={60}
               cellHeight={cellHeight as any}
               cellLocation="last"
@@ -1018,6 +1091,10 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
       ExpandCaretIcon,
       expandedCaretRotation,
       clipBodyCells,
+      excelCellNav,
+      keyboardNav.isNavigating,
+      keyboardNav.focusedRowIndex,
+      focusedColIndex,
     ],
   );
 
@@ -1048,6 +1125,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
         activeViewId: state.activeViewId,
         size: knobProps.sizeToken,
         compact: isCompact,
+        isFetching: Boolean(state.isFetching),
       });
     }
 
@@ -1066,6 +1144,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
         enableFiltering={enableFiltering}
         size={knobProps.sizeToken}
         compact={isCompact}
+        isFetching={Boolean(state.isFetching)}
       />
     );
   };
@@ -1124,7 +1203,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
         el.removeEventListener("scroll", update);
         ro?.disconnect();
       };
-    }, [tableRows.length, showCards]);
+    }, [displayRows.length, showCards]);
 
     // Enable drag-to-scroll in the horizontal-overflow modes (scroll layout
     // and column pinning share the content-View scrollport).
@@ -1141,8 +1220,10 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
 
     // W9 / DG-ST-01,02,04 / DG-TBL-06 — first-class async states.
     // Error wins over empty chrome; initial load uses a table-shaped skeleton.
-    // Selection API untouched.
+    // A refetch (isFetching / placeholderData) MUST keep the body mounted —
+    // skeleton only when there are no rows to hold (first load).
     const resolvedAriaLabel = ariaLabel || t("Data table");
+    const isRefetching = queryInFlight;
     if (state.error) {
       return (
         <AsyncBoundary
@@ -1155,7 +1236,12 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
         />
       );
     }
-    if ((state.isLoading || infinite?.isInitialLoading) && tableRows.length === 0) {
+    if (
+      (state.isLoading || infinite?.isInitialLoading) &&
+      displayRows.length === 0 &&
+      !state.isFetching &&
+      !state.isPlaceholderData
+    ) {
       return <AsyncBoundary loading layout="table" aria-label={resolvedAriaLabel} />;
     }
 
@@ -1180,6 +1266,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
             aria-describedby={ariaDescribedBy}
             aria-live="polite"
             aria-atomic="false"
+            aria-busy={isRefetching || undefined}
             // UX-011 / Axiom 6 HONEST STATE: the advertised `disabled` prop
             // makes the whole assembly inert and says so. `inert` (React 19)
             // blocks pointer, keyboard, and AT for every control inside —
@@ -1231,7 +1318,19 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
             {children}
 
             {/* Card List View (layout="cards" or auto below $sm) */}
-            {showCards ? (
+            {showList ? (
+              <DataTableDocumentList
+                tableRows={displayRows}
+                enableRowSelection={enableRowSelection}
+                disabled={disabled}
+                hasActiveFilters={computed.hasActiveFilters}
+                renderCellContent={renderCellContent}
+                compact={isCompact}
+                selectRowLabel={deriveSelectRowLabel}
+                queryInFlight={queryInFlight}
+                {...(rowPressActive ? { getRowPressProps } : {})}
+              />
+            ) : showCards ? (
               <>
                 {/* Header affordances (sort / per-column filter) live in the
                     grid headers; the card list restores them here. */}
@@ -1244,7 +1343,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                   disabled={disabled}
                 />
                 <DataTableMobileCards
-                  tableRows={tableRows}
+                  tableRows={displayRows}
                   enableRowSelection={enableRowSelection}
                   showRowNumbers={showRowNumbers}
                   showDeleteRow={showDeleteRow}
@@ -1260,6 +1359,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                   onToggleSelectAll={toggleSelectAll}
                   compact={isCompact}
                   selectRowLabel={deriveSelectRowLabel}
+                  queryInFlight={queryInFlight}
                   {...(rowPressActive ? { getRowPressProps } : {})}
                 />
               </>
@@ -1295,9 +1395,8 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                   label: resolvedAriaLabel,
                 })}
                 tabIndex={enableKeyboardNavigation && !isSSR ? 0 : undefined}
-                onKeyDown={
-                  enableKeyboardNavigation && !isSSR ? keyboardNav.handleKeyDown : undefined
-                }
+                {...({ "data-table-grid": "true" } as any)}
+                onKeyDown={enableKeyboardNavigation && !isSSR ? handleGridKeyDown : undefined}
                 onPress={
                   enableKeyboardNavigation && !isSSR ? keyboardNav.handleContainerClick : undefined
                 }
@@ -1678,18 +1777,20 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                       tableBodyRef.current = node ?? null;
                     }}
                   >
-                    {tableRows.length === 0 ? (
+                    {displayRows.length === 0 ? (
                       <Table.Row>
                         <Table.Cell>
-                          <EmptyState
-                            compact
-                            aria-live="polite"
-                            title={
-                              computed.hasActiveFilters
-                                ? t("No results found")
-                                : t("No data available")
-                            }
-                          />
+                          {isRefetching ? null : (
+                            <EmptyState
+                              compact
+                              aria-live="polite"
+                              title={
+                                computed.hasActiveFilters
+                                  ? t("No results found")
+                                  : t("No data available")
+                              }
+                            />
+                          )}
                         </Table.Cell>
                       </Table.Row>
                     ) : isVirtualized ? (
@@ -1724,7 +1825,7 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                             totalSize={totalSize}
                             bodyScrollRef={bodyScrollRef}
                             virtualizationHeight={virtualizationHeight}
-                            tableRows={tableRows}
+                            tableRows={displayRows}
                             headerGroups={headerGroups}
                             showRowNumbers={showRowNumbers}
                             enableRowExpansion={enableRowExpansion}
@@ -1744,9 +1845,9 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                       </Table.Row>
                     ) : (
                       <>
-                        {tableRows.map((row: any, index: number) => {
+                        {displayRows.map((row: any, index: number) => {
                           rowCounter.current++;
-                          const isLastRow = index === tableRows.length - 1;
+                          const isLastRow = index === displayRows.length - 1;
 
                           // Grouped row: render a single header cell spanning all columns
                           // with expand toggle, group label, and item count.
@@ -1800,17 +1901,13 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
 
                           const mainRow = (
                             <Table.Row
-                              backgroundColor={
-                                enableKeyboardNavigation &&
-                                keyboardNav.isNavigating &&
-                                index === keyboardNav.focusedRowIndex
-                                  ? "$color4"
-                                  : tableZebraOn && index % 2 === 1
-                                    ? "$color2"
-                                    : "$color1"
-                              }
+                              {...(tableRowStateProps({
+                                selected: Boolean(enableRowSelection && row.getIsSelected?.()),
+                                keyboardFocused: false,
+                                zebraOn: tableZebraOn,
+                                index,
+                              }) as any)}
                               {...({ animation: "quick" } as any)}
-                              hoverStyle={{ backgroundColor: "$color3" }}
                               flexShrink={0}
                               rowLocation={
                                 rowCounter.current === 0
@@ -2125,26 +2222,6 @@ export function DataTableRoot<TData extends Record<string, any> = Record<string,
                 </Text>
               </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={t("Loading table data")}
-                role="status"
-              >
-                <Spinner size="large" color="$color10" />
-              </View>
-            )}
           </View>
         </DataTableStateContext.Provider>
       </DataTableContext.Provider>

package/src/components/DataTable/DataTableVirtualized.tsx

@@ -7,7 +7,7 @@
  * column border extension.
  */
 
-import type React from "react";
+import { tableRowStateProps } from "./rowStateChrome";
 import { Skeleton } from "@multiplatform.one/components";
 import { Text, View } from "tamagui";
 
@@ -61,7 +61,7 @@ export function DataTableVirtualized({
   enableRowExpansion,
   showDeleteRow,
   readOnly,
-  enableKeyboardNavigation,
+  enableKeyboardNavigation: _enableKeyboardNavigation,
   keyboardNav,
   getColSizeProps,
   renderRowContent,
@@ -184,15 +184,12 @@ export function DataTableVirtualized({
                 minHeight: rowHeightPx,
               }}
               flexDirection="row"
-              backgroundColor={
-                enableKeyboardNavigation &&
-                keyboardNav.isNavigating &&
-                virtualRow.index === keyboardNav.focusedRowIndex
-                  ? "$color4"
-                  : virtualRow.index % 2 === 0
-                    ? "$color1"
-                    : "$color2"
-              }
+              {...(tableRowStateProps({
+                selected: Boolean(row.getIsSelected?.()),
+                keyboardFocused: false,
+                zebraOn: true,
+                index: virtualRow.index,
+              }) as any)}
               role="row"
               aria-rowindex={virtualRow.index + 1}
               {...(getRowPressProps ? (getRowPressProps(row, virtualRow.index) as any) : {})}

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

@@ -72,6 +72,58 @@ describe("DataTable card layout", () => {
       expect(container.querySelector('[data-testid="data-table-cards"]')).not.toBeNull();
       expect(container.querySelector(".is_Table")).toBeNull();
     });
+
+    it("layout=list renders document rows, not the grid or cards", () => {
+      const { container } = renderWithProviders(
+        <DataTable data={sampleData} columns={columns} layout="list" onStateChange={vi.fn()} />,
+      );
+      expect(container.querySelector('[data-testid="data-table-list"]')).not.toBeNull();
+      expect(container.querySelectorAll('[data-testid="data-table-list-row"]').length).toBe(
+        sampleData.length,
+      );
+      expect(container.querySelector('[data-testid="data-table-cards"]')).toBeNull();
+      expect(container.querySelector(".is_Table")).toBeNull();
+      expect(container.querySelector('[aria-label="Table headers"]')).toBeNull();
+    });
+
+    it("list title slot uses the title-role column, not a leading _liked_by glyph", () => {
+      const listColumns: DataTableColumn<Person>[] = [
+        { id: "_liked_by", accessorKey: "id", header: "♥", meta: { label: "Liked" } },
+        { accessorKey: "firstName", header: "First Name", meta: { role: "title" } },
+        { accessorKey: "lastName", header: "Last Name" },
+        { accessorKey: "email", header: "Email" },
+      ];
+      const { container } = renderWithProviders(
+        <DataTable data={sampleData} columns={listColumns} layout="list" onStateChange={vi.fn()} />,
+      );
+      const titleSlots = container.querySelectorAll('[data-list-slot="title"]');
+      expect(titleSlots.length).toBe(sampleData.length);
+      expect(titleSlots[0]?.textContent).toBe("John");
+      const metaSlots = container.querySelectorAll('[data-list-slot="meta"]');
+      expect(Array.from(metaSlots).some((slot) => slot.textContent === "Doe")).toBe(true);
+    });
+
+    it("list rows are a nowrap flex list, not a column grid or labeled cards", () => {
+      const listColumns: DataTableColumn<Person>[] = [
+        { accessorKey: "firstName", header: "Name", meta: { role: "title" } },
+        { accessorKey: "lastName", header: "Last Name" },
+        { accessorKey: "email", header: "Email" },
+        { accessorKey: "age", header: "Age", meta: { role: "indicator" } },
+      ];
+      const { container, queryByText } = renderWithProviders(
+        <DataTable data={sampleData} columns={listColumns} layout="list" onStateChange={vi.fn()} />,
+      );
+      const list = container.querySelector('[data-testid="data-table-list"]') as HTMLElement;
+      const row = container.querySelector('[data-testid="data-table-list-row"]') as HTMLElement;
+      expect(list.getAttribute("data-list-layout")).toBe("list");
+      expect(row.getAttribute("data-list-wrap")).toBe("nowrap");
+      expect(getComputedStyle(list).display).not.toBe("grid");
+      expect(getComputedStyle(row).flexWrap).toBe("nowrap");
+      expect(container.querySelector('[data-list-slot="indicator"]')?.textContent).toBe("28");
+      // A list is not a form: column headers do not reprint as labels.
+      expect(queryByText("Last Name")).toBeNull();
+      expect(queryByText("Email")).toBeNull();
+    });
   });
 
   describe("card anatomy", () => {
@@ -96,6 +148,43 @@ describe("DataTable card layout", () => {
       expect(firstCard.textContent).toContain("28");
     });
 
+    it("labels field rows from meta.label when the header is a render function", () => {
+      const glyphColumns: DataTableColumn<Person>[] = [
+        { id: "firstName", accessorKey: "firstName", header: "First Name" },
+        {
+          id: "_liked_by",
+          accessorKey: "lastName",
+          header: () => <span aria-label="Liked">♥</span>,
+          meta: { label: "Liked" },
+        },
+      ];
+      const { container } = renderWithProviders(
+        <DataTable data={sampleData} columns={glyphColumns} onStateChange={vi.fn()} />,
+      );
+      const [firstCard] = getCards(container);
+      expect(within(firstCard).getByText("Liked")).toBeDefined();
+      expect(firstCard.textContent).not.toContain("_liked_by");
+    });
+
+    it("meta.label wins over a string header; a bare function header falls back to the id", () => {
+      const mixedColumns: DataTableColumn<Person>[] = [
+        { id: "firstName", accessorKey: "firstName", header: "First Name" },
+        // Explicit channel beats the display string — a glyph header ("♥")
+        // is exactly what meta.label exists to replace in card labels.
+        { id: "age", accessorKey: "age", header: "♥", meta: { label: "Age (years)" } },
+        // No meta.label + non-string header: the raw id still prints — the
+        // fallback stays honest instead of inventing a label.
+        { id: "email_addr", accessorKey: "email", header: () => <span>Email</span> },
+      ];
+      const { container } = renderWithProviders(
+        <DataTable data={sampleData} columns={mixedColumns} onStateChange={vi.fn()} />,
+      );
+      const [firstCard] = getCards(container);
+      expect(within(firstCard).getByText("Age (years)")).toBeDefined();
+      expect(within(firstCard).queryByText("♥")).toBeNull();
+      expect(within(firstCard).getByText("email_addr")).toBeDefined();
+    });
+
     it("respects column visibility (hidden columns stay hidden in cards)", () => {
       const { container } = renderWithProviders(
         <DataTable

package/src/components/DataTable/documentListSlots.ts

@@ -0,0 +1,57 @@
+/**
+ * Document-list slot taxonomy (Polaris Index / Frappe list, not a grid).
+ *
+ * A list row is subject-led: title + stacked muted meta, then a trailing
+ * indicator cluster and actions. Remaining columns never lay out as equal
+ * grid tracks — that is the table layout.
+ */
+
+import type { DataTableColumn, DataTableField } from "../../types";
+
+export type DocumentListSlot = "title" | "indicator" | "meta" | "actions" | "skip";
+
+const INDICATOR_FIELDS = new Set<DataTableField>([
+  "select",
+  "combobox",
+  "togglegroup",
+  "radiogroup",
+]);
+
+const INDICATOR_IDS = new Set(["status", "priority", "workflow_state", "state"]);
+
+export function classifyDocumentListSlot(cell: {
+  column: { id: string; columnDef: unknown };
+}): DocumentListSlot {
+  const id = String(cell.column.id ?? "");
+  const def = cell.column.columnDef as DataTableColumn;
+  const role = def.meta?.role;
+  if (role === "title") return "title";
+  if (role === "indicator") return "indicator";
+  if (role === "actions") return "actions";
+  if (role === "hidden" || role === "skip") return "skip";
+  if (id.startsWith("_")) return "actions";
+  if (INDICATOR_IDS.has(id) || (def.field != null && INDICATOR_FIELDS.has(def.field))) {
+    return "indicator";
+  }
+  return "meta";
+}
+
+export function partitionDocumentListCells<
+  TCell extends { id: string; column: { id: string; columnDef: unknown } },
+>(
+  visibleCells: TCell[],
+  titleCell: TCell | undefined,
+): { indicators: TCell[]; metas: TCell[]; actions: TCell[] } {
+  const rest = visibleCells.filter((cell) => cell.id !== titleCell?.id);
+  const indicators: TCell[] = [];
+  const metas: TCell[] = [];
+  const actions: TCell[] = [];
+  for (const cell of rest) {
+    const slot = classifyDocumentListSlot(cell);
+    if (slot === "indicator") indicators.push(cell);
+    else if (slot === "actions") actions.push(cell);
+    else if (slot === "skip" || slot === "title") continue;
+    else metas.push(cell);
+  }
+  return { indicators, metas, actions };
+}