@multiplatform.one/table 7.8.0 → 7.11.0

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

@@ -0,0 +1,238 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, screen, waitFor, within } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { DataTableColumn, FilterableField } from "../../types";
+import { DataTableCardToolbar, DataTableToolbar } from "../DataTableToolbar";
+import { DataTableCardSortControl } from "./DataTableCardControls";
+import { useDataTableState } from "./DataTableStateContext";
+import { DataTable } from "./index";
+
+const filings = [
+  { id: "a", form: "Alpha", entity: "personal", year: 2023 },
+  { id: "b", form: "Beta", entity: "business", year: 2024 },
+  { id: "c", form: "Gamma", entity: "personal", year: 2023 },
+];
+const columns: DataTableColumn<(typeof filings)[number]>[] = [
+  { accessorKey: "form", header: "Form" },
+  { accessorKey: "entity", header: "Entity" },
+];
+const filterableFields: FilterableField[] = [{ id: "year", label: "Year", type: "number" }];
+
+function Cards(props: Record<string, any>) {
+  return (
+    <DataTable
+      data={filings}
+      columns={columns}
+      filterableFields={filterableFields}
+      layout="cards"
+      enableGlobalSearch={false}
+      onStateChange={vi.fn()}
+      {...props}
+    />
+  );
+}
+
+function cardTitles(container: HTMLElement) {
+  return [...container.querySelectorAll('[data-card-slot="title"]')].map((el) => el.textContent);
+}
+
+function AllCardActionsToolbar(props: Record<string, any>) {
+  const { table } = useDataTableState()!;
+  return (
+    <DataTableCardToolbar
+      {...props}
+      enableExport
+      enableViews
+      isFetching
+      customActions={<DataTableCardSortControl table={table} contained />}
+    />
+  );
+}
+
+describe("default card toolbar", () => {
+  it("owns Filter and Sort in one primary row with no duplicate controls", () => {
+    const { container } = renderWithProviders(<Cards />);
+    const toolbar = screen.getByRole("toolbar", { name: "Table toolbar" });
+    expect(screen.getAllByRole("toolbar")).toHaveLength(1);
+    const primary = container.querySelector<HTMLElement>("[data-table-card-primary]")!;
+    expect(toolbar.contains(primary)).toBe(true);
+    expect(primary.contains(screen.getByRole("button", { name: "Filter" }))).toBe(true);
+    expect(primary.contains(screen.getByLabelText("Sort rows"))).toBe(true);
+    expect(screen.queryByText("Add Filter")).toBeNull();
+  });
+
+  it("keeps search and secondary view/fetching controls outside the primary pair", () => {
+    const { container } = renderWithProviders(<Cards enableGlobalSearch enableViews isFetching />);
+    const primary = container.querySelector<HTMLElement>("[data-table-card-primary]")!;
+    const secondary = container.querySelector<HTMLElement>("[data-table-card-secondary]")!;
+    expect(primary).not.toBeNull();
+    expect(secondary).not.toBeNull();
+    expect(primary.contains(screen.getByLabelText("Search table data"))).toBe(false);
+    expect(secondary.contains(screen.getByLabelText("Save view"))).toBe(true);
+    expect(secondary.querySelector("[data-table-fetching]")).not.toBeNull();
+    expect(primary.contains(secondary)).toBe(false);
+  });
+
+  it("keeps a sort-only toolbar when search, filtering and views are all off", () => {
+    renderWithProviders(<Cards enableFiltering={false} enableViews={false} />);
+    const toolbar = screen.getByRole("toolbar", { name: "Table toolbar" });
+    expect(within(toolbar).getByLabelText("Sort rows")).toBeTruthy();
+    expect(screen.queryByRole("button", { name: "Filter" })).toBeNull();
+  });
+
+  it("does not create an empty toolbar for unsortable columns", () => {
+    renderWithProviders(
+      <Cards
+        enableFiltering={false}
+        columns={columns.map((column) => ({ ...column, enableSorting: false }))}
+      />,
+    );
+    expect(screen.queryByRole("toolbar")).toBeNull();
+  });
+
+  it("exposes the full active sorting identity without replacing the button label recipe", () => {
+    const longHeader = "Form with a deliberately long distinguishing classification suffix";
+    renderWithProviders(
+      <Cards
+        columns={[{ accessorKey: "form", header: longHeader }]}
+        initialState={{ sorting: [{ id: "form", desc: true }] }}
+      />,
+    );
+    const trigger = screen.getByLabelText("Sort rows");
+    expect(trigger.getAttribute("aria-description")).toBe(`${longHeader} ↓`);
+    expect(trigger.textContent).toContain(`${longHeader} ↓`);
+  });
+
+  it("retains hidden Year filtering, chip edit and removal in readOnly cards", async () => {
+    const { container } = renderWithProviders(<Cards readOnly />);
+    expect(screen.queryByText("Add Filter")).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "Filter" }));
+    fireEvent.click(await screen.findByRole("option", { name: "Year" }));
+    fireEvent.change(await screen.findByPlaceholderText("Enter value..."), {
+      target: { value: "2023" },
+    });
+    await waitFor(() => expect(cardTitles(container)).toEqual(["Alpha", "Gamma"]));
+    fireEvent.keyDown(document, { key: "Escape" });
+    await waitFor(() => expect(screen.queryByPlaceholderText("Enter value...")).toBeNull());
+    fireEvent.click(await screen.findByRole("button", { name: /Edit filter.*Year/ }));
+    const value = await screen.findByPlaceholderText("Enter value...");
+    expect((value as HTMLInputElement).value).toBe("2023");
+    fireEvent.change(value, { target: { value: "2024" } });
+    await waitFor(() => expect(cardTitles(container)).toEqual(["Beta"]));
+    fireEvent.keyDown(document, { key: "Escape" });
+    await waitFor(() => expect(screen.queryByPlaceholderText("Enter value...")).toBeNull());
+    fireEvent.click(screen.getByRole("button", { name: "Remove" }));
+    await waitFor(() => expect(cardTitles(container)).toEqual(["Alpha", "Beta", "Gamma"]));
+  });
+
+  it("keeps the custom-toolbar fallback and clears its active filter", async () => {
+    const { container } = renderWithProviders(
+      <Cards
+        renderToolbar={() => <div>Custom actions</div>}
+        initialState={{
+          filters: [{ id: "f", columnId: "form", value: { operator: "contains", value: "Alpha" } }],
+        }}
+      />,
+    );
+    expect(screen.getByText("Custom actions")).toBeTruthy();
+    const fallback = screen.getByRole("toolbar", { name: "Card list controls" });
+    expect(within(fallback).getByRole("button", { name: /Add Filter/ })).toBeTruthy();
+    expect(cardTitles(container)).toEqual(["Alpha"]);
+    fireEvent.click(within(fallback).getByRole("button", { name: "Clear" }));
+    await waitFor(() => expect(cardTitles(container)).toEqual(["Alpha", "Beta", "Gamma"]));
+    fireEvent.click(within(fallback).getByRole("button", { name: "Add Filter" }));
+    expect(await screen.findByText("Select column")).toBeTruthy();
+  });
+
+  it("leaves an explicitly supplied canonical custom toolbar intact", () => {
+    renderWithProviders(<Cards renderToolbar={(props: any) => <DataTableToolbar {...props} />} />);
+    expect(screen.getByRole("button", { name: "Filter" })).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Add Filter" })).toBeTruthy();
+    expect(screen.getByRole("toolbar", { name: "Card list controls" })).toBeTruthy();
+  });
+
+  it("partitions actual export, long saved view, save and fetching from Filter and Sort", () => {
+    const name = "Saved view with a deliberately long distinguishing classification suffix";
+    const { container } = renderWithProviders(
+      <Cards
+        enableGlobalSearch
+        initialState={{
+          activeViewId: "long",
+          views: [
+            {
+              id: "long",
+              name,
+              columns: {},
+              filters: [],
+              sorting: [],
+              pagination: { pageIndex: 0, pageSize: 10 },
+            },
+          ],
+        }}
+        renderToolbar={(props: any) => <AllCardActionsToolbar {...props} />}
+      />,
+    );
+    const primary = container.querySelector<HTMLElement>("[data-table-card-primary]")!;
+    const secondary = container.querySelector<HTMLElement>("[data-table-card-secondary]")!;
+    expect(within(primary).getByLabelText("Sort rows")).toBeTruthy();
+    expect(within(primary).getByRole("button", { name: "Filter" })).toBeTruthy();
+    expect(within(secondary).getByRole("button", { name: /Export as CSV/ })).toBeTruthy();
+    expect(within(secondary).getByLabelText("Saved views").textContent).toContain(name);
+    expect(within(secondary).getByLabelText("Save view")).toBeTruthy();
+    expect(secondary.querySelector("[data-table-fetching]")).not.toBeNull();
+    expect(within(primary).queryByLabelText("Saved views")).toBeNull();
+    const sort = primary.querySelector("[data-table-card-sort]")!;
+    expect(sort.contains(within(primary).getByLabelText("Sort rows"))).toBe(true);
+  });
+
+  it("retains hidden filters and sort order when cards change to grid and back", () => {
+    const initialState = {
+      filters: [{ id: "year", columnId: "year", value: { operator: "is", value: "2023" } }],
+      sorting: [{ id: "form", desc: true }],
+    };
+    const { container, rerender } = renderWithProviders(<Cards initialState={initialState} />);
+    expect(cardTitles(container)).toEqual(["Gamma", "Alpha"]);
+    rerender(<Cards initialState={initialState} layout="table" />);
+    expect(cardTitles(container)).toEqual([]);
+    expect(screen.queryByLabelText("Sort rows")).toBeNull();
+    expect(screen.getByText("Gamma")).toBeTruthy();
+    expect(screen.queryByText("Beta")).toBeNull();
+    rerender(<Cards initialState={initialState} />);
+    expect(cardTitles(container)).toEqual(["Gamma", "Alpha"]);
+    expect(screen.getByLabelText("Sort rows").getAttribute("aria-description")).toBe("Form ↓");
+    expect(screen.getAllByRole("button", { name: "Filter" })).toHaveLength(1);
+    expect(screen.queryByPlaceholderText("Enter value...")).toBeNull();
+  });
+
+  it("clears hidden and visible advanced filters together without clearing plain column filters", async () => {
+    const { container } = renderWithProviders(
+      <Cards
+        initialState={{
+          filters: [
+            { id: "year", columnId: "year", value: { operator: "is", value: "2023" } },
+            { id: "form", columnId: "form", value: { operator: "contains", value: "Alpha" } },
+          ],
+          columnFilters: [{ id: "entity", value: "personal" }],
+        }}
+      />,
+    );
+    expect(cardTitles(container)).toEqual(["Alpha"]);
+    fireEvent.click(screen.getByRole("button", { name: "Clear all" }));
+    await waitFor(() => expect(cardTitles(container)).toEqual(["Alpha", "Gamma"]));
+    expect(screen.queryByRole("button", { name: /Edit filter/ })).toBeNull();
+  });
+
+  it("leaves the public standalone toolbar in its original layout", () => {
+    const { container } = renderWithProviders(
+      <DataTableToolbar
+        enableGlobalSearch
+        enableViews
+        customActions={<button type="button">Custom action</button>}
+      />,
+    );
+    expect(container.querySelector<HTMLElement>("[data-table-card-primary]")).toBeNull();
+    expect(container.querySelector<HTMLElement>("[data-table-card-secondary]")).toBeNull();
+    expect(screen.getByLabelText("Search table data")).toBeTruthy();
+    expect(screen.getByText("Custom action")).toBeTruthy();
+  });
+});

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

@@ -204,8 +204,11 @@ describe("chrome interplay: Search × injected filters × enableFiltering", () =
     expect(screen.getByLabelText("Search table data")).toBeInTheDocument();
   });
 
-  it("enableFiltering=false suppresses the card layout's Add Filter control too", () => {
+  it("enableFiltering=false suppresses the card layout's filter control too", () => {
     // auto layout renders cards below sm (the test env default).
+    // MPO-300: the default card path owns the canonical all-field Filter in
+    // the toolbar; the lower Card list controls toolbar and its Add Filter
+    // builder only mount behind a custom toolbar now.
     const control = renderWithProviders(
       <DataTable
         data={rows}
@@ -214,10 +217,8 @@ describe("chrome interplay: Search × injected filters × enableFiltering", () =
         initialState={{ filters: injectedReadyFilter }}
       />,
     );
-    // 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();
+    expect(screen.getByRole("button", { name: "Filter" })).toBeInTheDocument();
+    expect(screen.queryByText("Add Filter")).not.toBeInTheDocument();
     control.unmount();
 
     renderWithProviders(
@@ -228,6 +229,7 @@ describe("chrome interplay: Search × injected filters × enableFiltering", () =
         initialState={{ filters: injectedReadyFilter }}
       />,
     );
+    expect(screen.queryByRole("button", { name: "Filter" })).not.toBeInTheDocument();
     expect(screen.queryByText("Add Filter")).not.toBeInTheDocument();
     // Injected filters still scope the card list.
     expect(screen.getByText("Alpha")).toBeInTheDocument();

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

@@ -11,12 +11,34 @@
  * render. The combination warns instead, naming `columnLayout` as the reason.
  */
 
+import { fireEvent, waitFor } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { DataTableColumn } from "../../types";
 import { __resetTableDevWarnSeen, warnColumnWidthIgnored } from "../../shared/devWarn";
 import { DataTable } from "./index";
 
+vi.mock("@tanstack/react-virtual", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@tanstack/react-virtual")>();
+  return {
+    ...actual,
+    useVirtualizer: (options: Parameters<typeof actual.useVirtualizer>[0]) =>
+      actual.useVirtualizer({
+        ...options,
+        initialRect: { width: 800, height: 240 },
+        observeElementRect: (_instance, callback) => {
+          callback({ width: 800, height: 240 });
+          return () => {};
+        },
+        observeElementOffset: (_instance, callback) => {
+          callback(0, false);
+          return () => {};
+        },
+        scrollToFn: () => {},
+      }),
+  };
+});
+
 type Pokemon = { id: number; name: string; xp: number };
 
 const sampleData: Pokemon[] = [
@@ -193,3 +215,170 @@ describe("DataTable columnLayout=equal with per-column widths", () => {
     expect(widthWarnings()).toHaveLength(0);
   });
 });
+
+function hasSizingStyle(element: HTMLElement, property: string, value: string, token: string) {
+  return (
+    element.style.getPropertyValue(property) === value || String(element.className).includes(token)
+  );
+}
+
+function expectCellWidth(element: HTMLElement | null, width: number) {
+  expect(element).not.toBeNull();
+  expect(hasSizingStyle(element!, "width", `${width}px`, `_w-${width}px`)).toBe(true);
+}
+
+describe("DataTable declared column sizes", () => {
+  beforeEach(startCapture);
+  afterEach(stopCapture);
+
+  it.each(["alias", "canonical"])(
+    "applies %s widths to scroll headers, body and footer below the old floor",
+    (spelling) => {
+      const sizingColumns = plainColumns.map((column, index) => ({
+        ...column,
+        [spelling === "alias" ? "width" : "size"]: index === 0 ? 320 : 48,
+        footer: index === 0 ? "Totals" : "126",
+      }));
+      const { container } = renderTable(sizingColumns, "scroll");
+      expectCellWidth(container.querySelector("#name-header"), 320);
+      expectCellWidth(container.querySelector("#xp-header"), 48);
+      const cells = container.querySelectorAll('[aria-label="Table data"] [role="cell"]');
+      expect(cells.length).toBeGreaterThanOrEqual(4);
+      expectCellWidth(cells[0] as HTMLElement, 320);
+      expectCellWidth(cells[1] as HTMLElement, 48);
+      expect(hasSizingStyle(cells[1] as HTMLElement, "min-width", "0px", "_miw-0px")).toBe(true);
+      const footer = container.querySelectorAll('tfoot [role="cell"]');
+      expect(footer).toHaveLength(2);
+      expectCellWidth(footer[0] as HTMLElement, 320);
+      expectCellWidth(footer[1] as HTMLElement, 48);
+      expect(widthWarnings()).toHaveLength(0);
+    },
+  );
+
+  it("gives unpinned equal cells the same flex policy for canonical and alias declarations", () => {
+    const canonical = plainColumns.map((column, index) => ({
+      ...column,
+      size: index === 0 ? 320 : 80,
+    }));
+    const withSizes = renderTable(canonical);
+    const sizeMarkup = stripGeneratedIds(withSizes.container.innerHTML);
+    withSizes.unmount();
+    const withoutSizes = renderTable(plainColumns);
+    expect(stripGeneratedIds(withoutSizes.container.innerHTML)).toBe(sizeMarkup);
+  });
+
+  it("lets resizing use aliases in equal mode while preserving the fixed flex basis", () => {
+    const { container } = renderWithProviders(
+      <DataTable
+        data={sampleData}
+        columns={widthColumns}
+        columnLayout="equal"
+        layout="table"
+        enableColumnResizing
+        enablePagination={false}
+        readOnly
+      />,
+    );
+    const header = container.querySelector("#name-header") as HTMLElement;
+    expectCellWidth(header, 320);
+    expect(hasSizingStyle(header, "flex-basis", "auto", "_fb-auto")).toBe(true);
+    expect(hasSizingStyle(header, "flex-grow", "0", "_fg-0")).toBe(true);
+    expect(widthWarnings()).toHaveLength(0);
+  });
+
+  it("does not inflate a 48px resizable equal-layout cell with the primitive width floor", () => {
+    const { container } = renderWithProviders(
+      <DataTable
+        data={sampleData}
+        columns={[{ accessorKey: "xp", header: "XP", width: 48 }]}
+        columnLayout="equal"
+        layout="table"
+        enableColumnResizing
+        enablePagination={false}
+        readOnly
+      />,
+    );
+    const header = container.querySelector("#xp-header") as HTMLElement;
+    expectCellWidth(header, 48);
+    expect(hasSizingStyle(header, "min-width", "0px", "_miw-0px")).toBe(true);
+  });
+
+  it("passes size inputs to auto layout without changing its table algorithm", () => {
+    const { container } = renderTable(widthColumns, "auto");
+    expectCellWidth(container.querySelector("#name-header"), 320);
+    expect((container.querySelector('[role="table"]') as HTMLElement).style.tableLayout).toBe(
+      "fixed",
+    );
+  });
+
+  it("resizes an aliased column through the real header handle within its bounds", () => {
+    const columns = widthColumns.map((column) => ({ ...column, minWidth: 50, maxWidth: 350 }));
+    const { container, getByRole } = renderWithProviders(
+      <DataTable
+        data={sampleData}
+        columns={columns}
+        columnLayout="scroll"
+        layout="table"
+        enableColumnResizing
+        enablePagination={false}
+        readOnly
+      />,
+    );
+    const handle = getByRole("separator", { name: "Resize Name column" });
+    expect(handle.getAttribute("aria-valuenow")).toBe("320");
+    fireEvent.mouseDown(handle, { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 120 });
+    fireEvent.mouseUp(document, { clientX: 120 });
+    expectCellWidth(container.querySelector("#name-header"), 340);
+    fireEvent.mouseDown(handle, { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 300 });
+    fireEvent.mouseUp(document, { clientX: 300 });
+    expectCellWidth(container.querySelector("#name-header"), 350);
+    expect(handle.getAttribute("aria-valuenow")).toBe("350");
+    const cell = container.querySelector<HTMLElement>('[aria-label="Table data"] [role="cell"]');
+    expectCellWidth(cell, 350);
+  });
+
+  it("exposes the normalized size to the view-options display on mount", async () => {
+    const { getByText } = renderWithProviders(
+      <DataTable
+        data={sampleData}
+        columns={widthColumns}
+        columnLayout="scroll"
+        layout="table"
+        enableColumnResizing
+        enablePagination={false}
+        readOnly
+      >
+        <DataTable.ViewOptions showColumnResizing showColumnVisibility={false} />
+      </DataTable>,
+    );
+    await waitFor(() => expect(getByText("320px")).toBeDefined());
+    expect(getByText("80px")).toBeDefined();
+  });
+
+  it("uses the real virtual row renderer with the same declared widths", async () => {
+    const { container } = renderWithProviders(
+      <DataTable
+        data={sampleData}
+        columns={widthColumns}
+        columnLayout="scroll"
+        layout="table"
+        enableVirtualization
+        virtualizationHeight={240}
+        enablePagination={false}
+        readOnly
+      />,
+    );
+    await waitFor(() => {
+      const virtualBody = container.querySelector('tbody[role="presentation"] [role="rowgroup"]');
+      expect(virtualBody).not.toBeNull();
+      expect(virtualBody!.querySelectorAll('[role="row"]')).toHaveLength(2);
+      const cells = virtualBody!.querySelectorAll('[role="cell"]');
+      expect(cells.length).toBeGreaterThanOrEqual(4);
+      expectCellWidth(cells[0] as HTMLElement, 320);
+      expectCellWidth(cells[1] as HTMLElement, 80);
+    });
+    expectCellWidth(container.querySelector("#name-header"), 320);
+  });
+});

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

@@ -42,7 +42,7 @@ function renderCards(props: Record<string, any> = {}) {
 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" });
+    const toolbar = screen.getByRole("toolbar", { name: "Table toolbar" });
     expect(toolbar).toBeTruthy();
     expect(screen.getByLabelText("Sort rows")).toBeTruthy();
   });
@@ -61,7 +61,8 @@ describe("DataTableCardControls", () => {
   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();
+    expect(screen.getByRole("button", { name: "Filter" })).toBeTruthy();
+    expect(screen.queryByText("Add Filter")).toBeNull();
   });
 
   it("with no sort applied the trigger reads the neutral label", () => {

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

@@ -8,10 +8,14 @@
  * delete cluster beside the title, the delete floor at `minRows`, and the two
  * distinct empty-state copies (no data vs no results) — plus the rule that an
  * in-flight refetch paints NO empty state over a momentarily blank body.
+ *
+ * It also pins `classifyCardField`, which decides whether a field prints its
+ * column name at all. In the grid a header is written once for a whole
+ * column; on a card it would be written once per value.
  */
 
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { fireEvent, screen, waitFor, within } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import type { DataTableColumn, TableFilter } from "../../types";
 import { DataTable } from "./index";
@@ -52,7 +56,7 @@ describe("DataTableMobileCards", () => {
     expect(cards(container).length).toBe(people.length);
   });
 
-  it("the first visible column is the card title, the rest are label/value rows", () => {
+  it("the first visible column is the card title, the rest are classified fields", () => {
     const { container } = renderCards();
     const first = cards(container)[0];
     expect(first.querySelector('[data-card-slot="title"]')?.textContent).toBe("John");
@@ -69,6 +73,50 @@ describe("DataTableMobileCards", () => {
     expect(first.textContent).not.toContain("Last Name");
   });
 
+  it("a self-naming string goes bare, into one wrapped flow with its name hidden", () => {
+    const { container } = renderCards();
+    const first = cards(container)[0];
+    const meta = first.querySelector('[data-card-slot="meta"]');
+    expect(meta).not.toBeNull();
+    expect(meta!.textContent).toContain("Doe");
+    expect(within(first).queryByText("Last Name")).toBeNull();
+    expect(first.textContent).toContain("Last Name:");
+  });
+
+  it("a figure keeps its column name, inline beside the value", () => {
+    const { container } = renderCards();
+    const first = cards(container)[0];
+    const figure = first.querySelector('[data-card-slot="figure"]');
+    expect(figure).not.toBeNull();
+    expect(figure!.textContent).toContain("28");
+    expect(within(first).getByText("Age")).toBeDefined();
+  });
+
+  it("a field with no value spends no row at all", () => {
+    const { container } = renderCards({
+      data: [{ id: 1, firstName: "John", lastName: "", age: 28 }],
+    });
+    const first = cards(container)[0];
+    expect(first.querySelector('[data-card-slot="meta"]')).toBeNull();
+    expect(first.textContent).not.toContain("Last Name");
+  });
+
+  it("a control keeps a row of its own and prints no label", () => {
+    // Explicit id on BOTH columns: DataTable seeds columnOrder from
+    // `col.id || ""`, so an id-less accessor column beside an id'd one would
+    // put `_actions` first and make the control the card title instead.
+    const { container } = renderCards({
+      columns: [
+        { id: "firstName", accessorKey: "firstName", header: "First Name" },
+        { id: "_actions", accessorKey: "lastName", header: "Actions", meta: { role: "actions" } },
+      ],
+    });
+    const first = cards(container)[0];
+    expect(first.querySelector('[data-card-slot="control"]')).not.toBeNull();
+    expect(within(first).queryByText("Actions")).toBeNull();
+    expect(first.textContent).toContain("Actions:");
+  });
+
   it("selection adds a select-all bar above the stack and a checkbox per card", () => {
     const { container } = renderCards({ enableRowSelection: true });
     expect(screen.getByLabelText("Select all rows")).toBeTruthy();