@multiplatform.one/table 7.6.3 → 7.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/table",
-  "version": "7.6.3",
+  "version": "7.7.1",
   "description": "Advanced table components with filtering, pagination, sorting, and URL state management",
   "keywords": [
     "cross-platform",
@@ -80,18 +80,17 @@
     "@tanstack/react-table": "^8.21.3",
     "@tanstack/table-core": "^8.21.3",
     "tamagui": "2.7.6",
-    "@multiplatform.one/forms": "7.6.3",
-    "@multiplatform.one/components": "7.6.3",
-    "@multiplatform.one/platform": "7.6.3",
-    "@multiplatform.one/rich-text": "7.6.3",
-    "@multiplatform.one/router": "7.6.3",
-    "@multiplatform.one/table-primitives": "7.6.3",
-    "@multiplatform.one/theme": "7.6.3"
+    "@multiplatform.one/components": "7.7.1",
+    "@multiplatform.one/forms": "7.7.1",
+    "@multiplatform.one/platform": "7.7.1",
+    "@multiplatform.one/rich-text": "7.7.1",
+    "@multiplatform.one/router": "7.7.1",
+    "@multiplatform.one/table-primitives": "7.7.1",
+    "@multiplatform.one/theme": "7.7.1"
   },
   "devDependencies": {
     "@tamagui/build": "2.7.6",
     "@testing-library/react": "^16.3.2",
-    "@types/react": "~19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "@vitest/coverage-v8": "^4.1.5",
@@ -99,10 +98,10 @@
     "react": "19.2.5",
     "react-dom": "19.2.5",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "7.6.3",
-    "@multiplatform.one/router": "7.6.3",
-    "@multiplatform.one/storybook": "7.6.3",
-    "@multiplatform.one/test-utils": "7.6.3"
+    "@multiplatform.one/config": "7.7.1",
+    "@multiplatform.one/router": "7.7.1",
+    "@multiplatform.one/storybook": "7.7.1",
+    "@multiplatform.one/test-utils": "7.7.1"
   },
   "peerDependencies": {
     "i18next": "^25.0.0",

package/src/components/ChildTable/ChildTable.stories.tsx

@@ -30,7 +30,10 @@ const columns: DataTableColumn<LineItem>[] = [
   { accessorKey: "qty", header: "Qty", field: "stepper", fieldProps: { min: 0 } },
 ];
 
-const meta: Meta<typeof ChildTable> = {
+// Instantiation expression: `Meta<typeof ChildTable>` resolves ChildTable's
+// TRow to its default (DataTableData), so `args.columns` typed as
+// DataTableColumn<DataTableData>[] and rejected the LineItem columns below.
+const meta: Meta<typeof ChildTable<LineItem>> = {
   title: "Table/ChildTable",
   component: ChildTable,
   parameters: {

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

@@ -328,10 +328,11 @@ describe("DataTable", () => {
       expect(screen.getByText("John")).toBeDefined();
       expect(screen.getByText("Jane")).toBeDefined();
 
-      // The forms SearchInput default placeholder is bidi-isolated (LC-58,
-      // FSI…PDI) — match the isolated form, same as the DataTablePagination
-      // range-label assertions.
-      await user.type(screen.getByPlaceholderText("\u2068Search...\u2069"), "Charlie");
+      // DataTableToolbar passes an explicit `placeholder={t("Search")}`, so
+      // the forms SearchInput default (bidi-isolated "Search…") never reaches
+      // this input. Query the stable aria-label instead of a literal
+      // placeholder string.
+      await user.type(screen.getByLabelText("Search table data"), "Charlie");
 
       await waitFor(() => {
         expect(screen.queryByText("John")).toBeNull();
@@ -656,7 +657,10 @@ describe("DataTable", () => {
       );
 
       expect(screen.queryByLabelText("Select all rows")).toBeNull();
-      expect(screen.queryByLabelText(/^Select row/)).toBeNull();
+      // Anchored on the row-name template, not the bare "Select row" prefix:
+      // DataTablePagination's page-size control is labelled "Select rows per
+      // page", which /^Select row/ also matches.
+      expect(screen.queryByLabelText(/^Select row \S/)).toBeNull();
       expect(screen.queryByText(/selected/)).toBeNull();
     });
 
@@ -673,8 +677,10 @@ describe("DataTable", () => {
 
       expect(screen.getByLabelText("Select all rows")).toBeDefined();
       // Row identity is templated into the name (DG-A11Y-06); without an
-      // initialized i18n instance the raw key renders, so match the prefix.
-      expect(screen.getAllByLabelText(/^Select row/).length).toBe(sampleData.length);
+      // initialized i18n instance the raw key renders, so match the prefix —
+      // but require a following token so the pagination page-size control
+      // ("Select rows per page") is not counted as a sixth row.
+      expect(screen.getAllByLabelText(/^Select row \S/).length).toBe(sampleData.length);
     });
 
     it("auto-shows selection toolbar with count and clear after selecting a row", async () => {

package/src/components/DataTable/DataTableCardControls.stories.tsx

@@ -0,0 +1,116 @@
+/**
+ * DataTableCardControls — the sort + filter row above the card list.
+ *
+ * The grid puts sorting and per-column filtering in the column headers. The
+ * card layout has no headers, so this toolbar restores both: a sort menu that
+ * cycles none → asc → desc per sortable column (the same cycle as a header
+ * click) and the compact DataTableFilters chrome. Both drive the same table
+ * state as the grid — there is no parallel state.
+ *
+ * It only exists in `layout="cards"`, which is why these stories pin the
+ * layout instead of relying on the viewport.
+ */
+
+import type { Meta } from "@storybook/react-native-web-vite";
+import { Paragraph, YStack } from "tamagui";
+import type { DataTableColumn } from "../../types";
+import { DataTable } from "./index";
+
+const meta: Meta = {
+  title: "Table/DataTableCardControls",
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "Sort menu plus filter chrome above the card list, standing in for the grid's " +
+          "column headers. Renders only in the cards layout, and only when sorting or " +
+          "filtering is enabled.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+interface Person {
+  id: number;
+  firstName: string;
+  lastName: string;
+  age: number;
+  email: string;
+}
+
+const people: Person[] = [
+  { id: 1, firstName: "John", lastName: "Doe", age: 28, email: "john@example.com" },
+  { id: 2, firstName: "Jane", lastName: "Smith", age: 32, email: "jane@example.com" },
+  { id: 3, firstName: "Bob", lastName: "Johnson", age: 45, email: "bob@example.com" },
+  { id: 4, firstName: "Alice", lastName: "Williams", age: 22, email: "alice@example.com" },
+];
+
+const columns: DataTableColumn<Person>[] = [
+  { accessorKey: "firstName", header: "First Name" },
+  { accessorKey: "lastName", header: "Last Name" },
+  { accessorKey: "age", header: "Age" },
+  { accessorKey: "email", header: "Email" },
+];
+
+function CardTable(props: Record<string, any>) {
+  return (
+    <YStack padding="$4" width="100%" maxWidth={520}>
+      <DataTable
+        data={people}
+        columns={columns}
+        layout="cards"
+        aria-label="People as cards"
+        {...props}
+      />
+    </YStack>
+  );
+}
+
+/** Both affordances: Sort menu on the left, Add Filter chrome beside it. */
+export const Default = {
+  name: "Main",
+  render: () => <CardTable enableSorting enableFiltering />,
+};
+
+/** Sorting only — no filter chrome in the row. */
+export const SortOnly = {
+  render: () => <CardTable enableSorting enableFiltering={false} />,
+};
+
+/** Filtering only — no Sort menu in the row. */
+export const FilterOnly = {
+  render: () => <CardTable enableSorting={false} enableFiltering />,
+};
+
+/**
+ * With a sort already applied the button reads the column and direction
+ * (`Age ↑`) instead of the bare "Sort", so the card list is never sorted
+ * invisibly.
+ */
+export const ActiveSort = {
+  render: () => (
+    <CardTable
+      enableSorting
+      enableFiltering
+      initialState={{ sorting: [{ id: "age", desc: false }] }}
+    />
+  ),
+};
+
+/** UX-011: the whole table disabled renders the controls inert and LC-40 visible. */
+export const Disabled = {
+  render: () => <CardTable enableSorting enableFiltering disabled />,
+};
+
+/** Neither enabled: the toolbar is absent, not an empty bar taking vertical space. */
+export const NoControls = {
+  render: () => (
+    <YStack padding="$4" gap="$2" width="100%" maxWidth={520}>
+      <Paragraph size="$2">Sorting and filtering off — no control row above the cards.</Paragraph>
+      <CardTable enableSorting={false} enableFiltering={false} />
+    </YStack>
+  ),
+};

package/src/components/DataTable/DataTableDocumentList.stories.tsx

@@ -0,0 +1,132 @@
+/**
+ * DataTableDocumentList — subject-led document rows for `layout="list"`.
+ *
+ * This is the desk List view, not a grid and not cards. Each document gets one
+ * horizontal row: checkbox, then a title with its meta stacked underneath in
+ * muted text, then a trailing indicator cluster, then actions. No column
+ * headers, no key-value labels, no card frame, and no wrapping into a column
+ * grid (Polaris Index / Frappe list).
+ *
+ * Slots are assigned by column, not by position: `meta.role` of `title`,
+ * `indicator`, `actions` or `hidden` decides, and status-shaped ids
+ * (status, priority, workflow_state, state) and option-group fields fall into
+ * the indicator cluster on their own.
+ */
+
+import type { Meta } from "@storybook/react-native-web-vite";
+import { YStack } from "tamagui";
+import type { DataTableColumn } from "../../types";
+import { DataTable } from "./index";
+
+const meta: Meta = {
+  title: "Table/DataTableDocumentList",
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "One row per document: title plus stacked muted meta, a trailing indicator cluster, " +
+          "then actions. Stacked-group radius rounds the first and last rows only.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+interface Task {
+  id: number;
+  title: string;
+  owner: string;
+  due: string;
+  status: string;
+}
+
+const tasks: Task[] = [
+  {
+    id: 1,
+    title: "Ship the card layout",
+    owner: "Ada Lovelace",
+    due: "2026-09-08",
+    status: "Open",
+  },
+  {
+    id: 2,
+    title: "Rewire the filter chips",
+    owner: "Grace Hopper",
+    due: "2026-09-10",
+    status: "In progress",
+  },
+  {
+    id: 3,
+    title: "Retire the legacy grid",
+    owner: "Alan Turing",
+    due: "2026-09-15",
+    status: "Blocked",
+  },
+  {
+    id: 4,
+    title: "Document the slot taxonomy",
+    owner: "Katherine Johnson",
+    due: "2026-09-20",
+    status: "Open",
+  },
+];
+
+/** Roles are explicit: title leads, status is the trailing indicator. */
+const columns: DataTableColumn<Task>[] = [
+  { accessorKey: "title", header: "Title", meta: { role: "title" } },
+  { accessorKey: "owner", header: "Owner" },
+  { accessorKey: "due", header: "Due" },
+  { accessorKey: "status", header: "Status", meta: { role: "indicator" } },
+];
+
+function ListTable(props: Record<string, any>) {
+  return (
+    <YStack padding="$4" width="100%" maxWidth={720}>
+      <DataTable
+        data={tasks}
+        columns={columns}
+        layout="list"
+        aria-label="Tasks as a document list"
+        {...props}
+      />
+    </YStack>
+  );
+}
+
+/** Title leads, owner and due stack beneath it, status rides the right edge. */
+export const Default = {
+  name: "Main",
+  render: () => <ListTable />,
+};
+
+/** Selection puts a checkbox at the head of every row. */
+export const Selection = {
+  render: () => <ListTable enableRowSelection />,
+};
+
+/**
+ * No `meta.role` anywhere: the first non-action column becomes the title and
+ * `status` still lands in the indicator cluster on its id alone.
+ */
+export const InferredSlots = {
+  render: () => (
+    <ListTable
+      columns={[
+        { accessorKey: "title", header: "Title" },
+        { accessorKey: "owner", header: "Owner" },
+        { accessorKey: "status", header: "Status" },
+      ]}
+    />
+  ),
+};
+
+/** No rows and no filters: the list paints "No data available", not blank. */
+export const Empty = {
+  render: () => (
+    <YStack padding="$4" width="100%" maxWidth={720}>
+      <DataTable data={[]} columns={columns} layout="list" aria-label="Empty document list" />
+    </YStack>
+  ),
+};

package/src/components/DataTable/DataTableMobileCards.stories.tsx

@@ -0,0 +1,124 @@
+/**
+ * DataTableMobileCards — the stacked card body for `layout="cards"`.
+ *
+ * Below `$sm` (or forced) a DataTable stops being a grid: each row becomes a
+ * card whose first visible column is the title and whose remaining columns
+ * become label/value rows. Column visibility, order, sorting and filtering all
+ * come from the same table state as the grid — the cells run through the same
+ * renderers inside `TableCellContext`, so fields stay chromeless.
+ *
+ * Selection, row numbers and delete live in the card header beside the title.
+ */
+
+import type { Meta } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+import { YStack } from "tamagui";
+import type { DataTableColumn } from "../../types";
+import { DataTable } from "./index";
+
+const meta: Meta = {
+  title: "Table/DataTableMobileCards",
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "One card per row: title in the header, remaining columns as label/value rows. " +
+          "Select-all sits above the stack; per-row select, row number and delete sit in the card header.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+interface Person {
+  id: number;
+  firstName: string;
+  lastName: string;
+  age: number;
+  email: string;
+}
+
+const people: Person[] = [
+  { id: 1, firstName: "John", lastName: "Doe", age: 28, email: "john@example.com" },
+  { id: 2, firstName: "Jane", lastName: "Smith", age: 32, email: "jane@example.com" },
+  { id: 3, firstName: "Bob", lastName: "Johnson", age: 45, email: "bob@example.com" },
+  { id: 4, firstName: "Alice", lastName: "Williams", age: 22, email: "alice@example.com" },
+];
+
+const columns: DataTableColumn<Person>[] = [
+  { accessorKey: "firstName", header: "First Name" },
+  { accessorKey: "lastName", header: "Last Name" },
+  { accessorKey: "age", header: "Age" },
+  { accessorKey: "email", header: "Email" },
+];
+
+function CardTable(props: Record<string, any>) {
+  return (
+    <YStack padding="$4" width="100%" maxWidth={480}>
+      <DataTable
+        data={people}
+        columns={columns}
+        layout="cards"
+        aria-label="People as cards"
+        {...props}
+      />
+    </YStack>
+  );
+}
+
+/** Card anatomy: title header, then one label/value row per remaining column. */
+export const Default = {
+  name: "Main",
+  render: () => <CardTable />,
+};
+
+/** Select-all above the stack, a checkbox in every card header. */
+export const Selection = {
+  render: () => <CardTable enableRowSelection />,
+};
+
+function DeletableCards() {
+  const [rows, setRows] = useState(people);
+  return (
+    <YStack padding="$4" width="100%" maxWidth={480}>
+      <DataTable
+        data={rows}
+        columns={columns}
+        layout="cards"
+        showRowNumbers
+        showDeleteRow
+        minRows={1}
+        onDataChange={(next: Person[]) => setRows(next)}
+        aria-label="People as deletable cards"
+      />
+    </YStack>
+  );
+}
+
+/**
+ * Row numbers and the delete affordance share the card header with the title.
+ * The parent owns `data` — the card asks via onDataChange, it does not splice.
+ */
+export const RowChrome = {
+  render: () => <DeletableCards />,
+};
+
+/** A single visible column: the header carries the title and there are no field rows. */
+export const TitleOnly = {
+  render: () => (
+    <CardTable
+      columns={[{ accessorKey: "firstName", header: "First Name" } as DataTableColumn<Person>]}
+    />
+  ),
+};
+
+/** No rows and no filters: the empty state reads "No data available". */
+export const Empty = {
+  render: () => (
+    <YStack padding="$4" width="100%" maxWidth={480}>
+      <DataTable data={[]} columns={columns} layout="cards" aria-label="Empty card list" />
+    </YStack>
+  ),
+};

package/src/components/DataTable/DataTableVirtualized.stories.tsx

@@ -0,0 +1,69 @@
+/**
+ * DataTableVirtualized is an internal body renderer. The public surface is
+ * DataTable with enableVirtualization — mounting the helper bare crashed
+ * playground SSR on virtualItems.map. This catalog row is that mode, not
+ * the helper's prop dump.
+ */
+
+import type { Meta } from "@storybook/react-native-web-vite";
+import { YStack } from "tamagui";
+import type { DataTableColumn } from "../../types";
+import { DataTable } from "./index";
+
+const meta: Meta = {
+  title: "Table/DataTableVirtualized",
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "Virtual-scroll body for large row sets. Enable it on DataTable; do not mount " +
+          "DataTableVirtualized as a standalone component.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+interface Employee {
+  id: number;
+  name: string;
+  email: string;
+  department: string;
+  salary: number;
+}
+
+const departments = ["Engineering", "Marketing", "Sales", "Design", "Support"];
+
+const rows: Employee[] = Array.from({ length: 200 }, (_, i) => ({
+  id: i + 1,
+  name: `Employee ${i + 1}`,
+  email: `emp${i + 1}@example.com`,
+  department: departments[i % departments.length],
+  salary: 50000 + (i % 80) * 1000,
+}));
+
+const columns: DataTableColumn<Employee>[] = [
+  { accessorKey: "id", header: "ID" },
+  { accessorKey: "name", header: "Name" },
+  { accessorKey: "email", header: "Email" },
+  { accessorKey: "department", header: "Department" },
+  { accessorKey: "salary", header: "Salary" },
+];
+
+export const Default = {
+  name: "Main",
+  render: () => (
+    <YStack padding="$4" height={360}>
+      <DataTable
+        data={rows}
+        columns={columns}
+        enableVirtualization
+        virtualizationHeight={320}
+        enableGlobalSearch
+        aria-label="Virtualized employees"
+      />
+    </YStack>
+  ),
+};

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

@@ -214,7 +214,10 @@ describe("chrome interplay: Search × injected filters × enableFiltering", () =
         initialState={{ filters: injectedReadyFilter }}
       />,
     );
-    expect(screen.getByText("Add Filter")).toBeInTheDocument();
+    // The control renders its active-filter count in the label text
+    // ("Add Filter (1)"), so an exact getByText no longer matches. The
+    // aria-label is the stable handle, as the sibling arms above use.
+    expect(screen.getByLabelText("Add Filter")).toBeInTheDocument();
     control.unmount();
 
     renderWithProviders(

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

@@ -0,0 +1,99 @@
+/**
+ * DataTableCardControls specs — the control row's OWN contract.
+ *
+ * cardLayout.spec.tsx already drives the sort menu through the card list and
+ * proves the cycle reorders cards. What nothing pinned is the row itself: that
+ * it is a labelled toolbar, that it disappears entirely when neither affordance
+ * is enabled (rather than rendering an empty bar), that each affordance can be
+ * turned off independently, and that the trigger reports the ACTIVE sort so a
+ * card list is never sorted invisibly.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { DataTableColumn } from "../../types";
+import { DataTable } from "./index";
+
+type Person = {
+  id: number;
+  firstName: string;
+  age: number;
+  email: string;
+};
+
+const people: Person[] = [
+  { id: 1, firstName: "John", age: 28, email: "john@example.com" },
+  { id: 2, firstName: "Jane", age: 32, email: "jane@example.com" },
+  { id: 3, firstName: "Bob", age: 45, email: "bob@example.com" },
+];
+
+const columns: DataTableColumn<Person>[] = [
+  { accessorKey: "firstName", header: "First Name" },
+  { accessorKey: "age", header: "Age" },
+];
+
+function renderCards(props: Record<string, any> = {}) {
+  return renderWithProviders(
+    <DataTable data={people} columns={columns} layout="cards" onStateChange={vi.fn()} {...props} />,
+  );
+}
+
+describe("DataTableCardControls", () => {
+  it("is a labelled toolbar above the card list", () => {
+    renderCards({ enableSorting: true, enableFiltering: true });
+    const toolbar = screen.getByRole("toolbar", { name: "Card list controls" });
+    expect(toolbar).toBeTruthy();
+    expect(screen.getByLabelText("Sort rows")).toBeTruthy();
+  });
+
+  it("renders no toolbar at all when neither sorting nor filtering is enabled", () => {
+    renderCards({ enableSorting: false, enableFiltering: false });
+    expect(screen.queryByRole("toolbar", { name: "Card list controls" })).toBeNull();
+  });
+
+  it("sorting only: the sort menu is there, the filter chrome is not", () => {
+    renderCards({ enableSorting: true, enableFiltering: false });
+    expect(screen.getByLabelText("Sort rows")).toBeTruthy();
+    expect(screen.queryByText("Add Filter")).toBeNull();
+  });
+
+  it("filtering only: the filter chrome is there, the sort menu is not", () => {
+    renderCards({ enableSorting: false, enableFiltering: true });
+    expect(screen.queryByLabelText("Sort rows")).toBeNull();
+    expect(screen.getByText("Add Filter")).toBeTruthy();
+  });
+
+  it("with no sort applied the trigger reads the neutral label", () => {
+    renderCards({ enableSorting: true });
+    expect(screen.getByLabelText("Sort rows").textContent).toContain("Sort");
+    expect(screen.getByLabelText("Sort rows").textContent).not.toContain("Age");
+  });
+
+  it("an active ascending sort is named on the trigger, arrow and all", () => {
+    renderCards({ enableSorting: true, initialState: { sorting: [{ id: "age", desc: false }] } });
+    expect(screen.getByLabelText("Sort rows").textContent).toContain("Age ↑");
+  });
+
+  it("an active descending sort flips the arrow on the trigger", () => {
+    renderCards({ enableSorting: true, initialState: { sorting: [{ id: "age", desc: true }] } });
+    expect(screen.getByLabelText("Sort rows").textContent).toContain("Age ↓");
+  });
+
+  it("picking a column from the menu updates the trigger label", async () => {
+    renderCards({ enableSorting: true });
+    fireEvent.click(screen.getByLabelText("Sort rows"));
+    fireEvent.click(await screen.findByLabelText("Sort by Age"));
+    await waitFor(() => {
+      expect(screen.getByLabelText("Sort rows").textContent).toContain("Age ↑");
+    });
+  });
+
+  it("offers one menu entry per sortable column and no more", async () => {
+    renderCards({ enableSorting: true });
+    fireEvent.click(screen.getByLabelText("Sort rows"));
+    expect(await screen.findByLabelText("Sort by First Name")).toBeTruthy();
+    expect(screen.getByLabelText("Sort by Age")).toBeTruthy();
+    expect(screen.queryByLabelText("Sort by Email")).toBeNull();
+  });
+});