@multiplatform.one/frappe-ui 6.7.0 → 7.0.0

package/src/FrappeReportView.spec.tsx

@@ -2,14 +2,17 @@
 // through the house DataTable. These specs cover the pure payload
 // normalization (dict/string columns, dict/array rows incl. the server's
 // array-shaped total row), the fieldtype → DataTableColumn mapping
-// (DG-TBL-01 align-by-type), the filter → refetch flow (debounced runs,
+// (DG-TBL-01 align-by-type on the typed meta channel), row activation via
+// DataTable's first-class `onRowPress`/`rowLabel` (the replacement contract
+// for the deleted per-cell pressable layer: one pressable row unit, one
+// roving tab stop per LC-49, Enter AND Space per LC-50, honest row names
+// per DG-A11Y-06), the filter → refetch flow (debounced runs,
 // controlled/uncontrolled values, defaults seeding, refresh), and the honest
 // empty / error states.
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { getDefaultColumnAlign } from "@multiplatform.one/table";
 import { cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
 import i18next from "i18next";
-import type { ReactElement } from "react";
 import { initReactI18next } from "react-i18next";
 import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import {
@@ -20,6 +23,7 @@ import {
   normalizeReportRows,
   reportColumnToDataTableColumn,
   reportFieldtypeToTableField,
+  reportRowLabel,
   scrubFieldname,
   type FrappeReportColumn,
   type FrappeReportRunResponse,
@@ -261,20 +265,25 @@ describe("reportColumnToDataTableColumn", () => {
     expect(col.width).toBeUndefined();
   });
 
-  it("wraps cells in a pressable custom renderer when onRowPress is set", () => {
-    const onRowPress = vi.fn();
-    const rows = [{ size: 1 }, { size: 3.09 }];
-    const col = reportColumnToDataTableColumn(
-      { label: "Size (MB)", fieldname: "size", fieldtype: "Float" },
-      { onRowPress, rowsRef: { current: rows } },
-    );
-    // DG-TBL-01 alignment survives the custom escape hatch.
-    expect(col.field).toBe("custom");
-    expect(col.align).toBe("right");
-    const render = (col.fieldProps as { render: (v: unknown, r: unknown) => ReactElement }).render;
-    renderWithProviders(render(3.09, rows[1]));
-    fireEvent.click(screen.getByText("3.09"));
-    expect(onRowPress).toHaveBeenCalledWith(rows[1], 1);
+  it("pins DG-TBL-01 alignment on the typed meta channel (numerics right)", () => {
+    const alignFor = (fieldtype: string) =>
+      reportColumnToDataTableColumn({ label: "X", fieldname: "x", fieldtype }).meta?.align;
+    expect(alignFor("Int")).toBe("right");
+    expect(alignFor("Float")).toBe("right");
+    expect(alignFor("Currency")).toBe("right");
+    expect(alignFor("Check")).toBe("center");
+    expect(alignFor("Data")).toBe("left");
+  });
+});
+
+describe("reportRowLabel", () => {
+  it("names rows by name, then title, and stays empty otherwise", () => {
+    expect(reportRowLabel({ name: "SINV-0001", title: "Acme" })).toBe("SINV-0001");
+    expect(reportRowLabel({ title: "Acme Corp" })).toBe("Acme Corp");
+    expect(reportRowLabel({ name: 42 })).toBe("42");
+    // Empty defers to DataTable's fallbacks (first cell → "Row N").
+    expect(reportRowLabel({ table: "tabDocField" })).toBe("");
+    expect(reportRowLabel({ name: "" })).toBe("");
   });
 });
 
@@ -325,6 +334,27 @@ describe("FrappeReportView", () => {
     expect(await screen.findByText("Error running Broken Report")).toBeTruthy();
   });
 
+  it("permission chrome does not render a python traceback", async () => {
+    const err = Object.assign(
+      new Error(
+        '["Traceback (most recent call last):\\n  File "apps/frappe/frappe/app.py", line 120, in application',
+      ),
+      { status: 403 },
+    );
+    renderWithProviders(
+      <FrappeReportView
+        reportName="Database Storage Usage By Tables"
+        fixture={() => {
+          throw err;
+        }}
+      />,
+    );
+    expect(
+      await screen.findByText("You do not have permission to run Database Storage Usage By Tables"),
+    ).toBeTruthy();
+    expect(screen.queryByText(/Traceback/)).toBeNull();
+  });
+
   it("re-runs the report when a filter value changes (filter → refetch)", async () => {
     const loader = vi.fn(async ({ filters }: { filters: Record<string, unknown> }) => ({
       columns: storageReport.columns,
@@ -415,3 +445,97 @@ describe("FrappeReportView", () => {
     expect(await screen.findByText("Nothing to see here")).toBeTruthy();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Row activation — DataTable onRowPress (the replacement contract for the
+// deleted per-cell pressable layer)
+// ---------------------------------------------------------------------------
+
+const pressableReport: FrappeReportRunResponse = {
+  columns: [
+    { label: "Name", fieldname: "name", fieldtype: "Link", options: "ToDo", width: 140 },
+    { label: "Table", fieldname: "table", fieldtype: "Data", width: 200 },
+    { label: "Size (MB)", fieldname: "size", fieldtype: "Float" },
+  ],
+  result: [
+    { name: "ROW-0001", table: "tabDocField", size: 3.09 },
+    { name: "ROW-0002", table: "tabError Log", size: 0.89 },
+    { name: "ROW-0003", table: "tabSeries", size: 0.02 },
+  ],
+};
+
+function pressRows(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll('[data-row-press="true"]')) as HTMLElement[];
+}
+
+function renderPressableReport(extraProps: Record<string, unknown> = {}) {
+  const onRowPress = vi.fn();
+  const result = renderWithProviders(
+    <FrappeReportView
+      reportName="Pressable Report"
+      fixture={pressableReport}
+      onRowPress={onRowPress}
+      tableProps={{ layout: "table", enablePagination: false }}
+      {...extraProps}
+    />,
+  );
+  return { ...result, onRowPress };
+}
+
+describe("FrappeReportView onRowPress → DataTable onRowPress", () => {
+  it("activates on mouse click anywhere in the row and on Enter AND Space", async () => {
+    const { container, onRowPress } = renderPressableReport();
+    await screen.findByText("tabDocField");
+    const rows = pressRows(container);
+    expect(rows).toHaveLength(3);
+
+    // Mouse: any cell in the row is the row's press target (index keeps
+    // its full-row-set meaning).
+    fireEvent.click(screen.getByText("tabError Log"));
+    expect(onRowPress).toHaveBeenCalledTimes(1);
+    expect(onRowPress).toHaveBeenCalledWith(expect.objectContaining({ name: "ROW-0002" }), 1);
+
+    // Keyboard: Enter AND Space activate the focused row (LC-50).
+    rows[0].focus();
+    fireEvent.keyDown(rows[0], { key: "Enter" });
+    expect(onRowPress).toHaveBeenCalledTimes(2);
+    expect(onRowPress).toHaveBeenLastCalledWith(expect.objectContaining({ name: "ROW-0001" }), 0);
+    fireEvent.keyDown(rows[0], { key: " " });
+    expect(onRowPress).toHaveBeenCalledTimes(3);
+  });
+
+  it("exposes ONE roving tab stop, names rows honestly, and keeps cells pressable-free", async () => {
+    const { container } = renderPressableReport();
+    await screen.findByText("tabDocField");
+    const rows = pressRows(container);
+
+    // LC-49: exactly one tab stop across the row set; arrows rove it.
+    expect(rows.map((row) => row.getAttribute("tabindex"))).toEqual(["0", "-1", "-1"]);
+    rows[0].focus();
+    fireEvent.keyDown(rows[0], { key: "ArrowDown" });
+    expect(document.activeElement).toBe(rows[1]);
+
+    // DG-A11Y-06: rows named by report identity (the name column).
+    expect(rows.map((row) => row.getAttribute("aria-label"))).toEqual([
+      "ROW-0001",
+      "ROW-0002",
+      "ROW-0003",
+    ]);
+
+    // The per-cell pressable layer is GONE: no cell-level buttons or
+    // extra tab stops inside pressable rows.
+    for (const row of rows) {
+      expect(row.querySelectorAll('[role="button"]')).toHaveLength(0);
+      expect(row.querySelectorAll('[tabindex="0"]')).toHaveLength(0);
+    }
+  });
+
+  it("falls back to the first visible cell for rows without a name/title column", async () => {
+    const { container } = renderPressableReport({ fixture: storageReport });
+    await screen.findByText("tabDocField");
+    expect(pressRows(container).map((row) => row.getAttribute("aria-label"))).toEqual([
+      "tabDocField",
+      "tabError Log",
+    ]);
+  });
+});

package/src/FrappeReportView.stories.tsx

@@ -154,20 +154,26 @@ const storageReportFixture: FrappeReportRunResponse = {
   add_total_row: true,
 };
 
-export const Live = () => (
-  <FrappeStoryProvider>
+export const Live = () =>
+  frappeStoriesLive ? (
+    <FrappeStoryProvider>
+      <FrappeReportView
+        reportName="Database Storage Usage By Tables"
+        onRowPress={action("onRowPress")}
+      />
+    </FrappeStoryProvider>
+  ) : (
     <FrappeReportView
       reportName="Database Storage Usage By Tables"
-      fixture={frappeStoriesLive ? undefined : storageReportFixture}
+      fixture={storageReportFixture}
       onRowPress={action("onRowPress")}
     />
-  </FrappeStoryProvider>
-);
+  );
 Live.parameters = {
   docs: {
     description: {
       story:
-        "Runs the stock 'Database Storage Usage By Tables' Script Report against the real bench through the Storybook proxy (frappe.desk.query_report.run — verified live on a vanilla bench; System Manager report perms ride the proxy's Administrator token). When the bench is down the story renders a fixture payload mirroring the same column contract instead.",
+        "Runs the stock 'Database Storage Usage By Tables' Script Report against the real bench through the Storybook proxy. A session without Report permission (a plain Desk User) sees the permission EmptyState — 'You do not have permission to run …' plus the server's sentence — not a python traceback; same honesty as QueryReportScreen Live. System Manager / Administrator sees the table. When the bench is down the story renders a fixture payload mirroring the same column contract.",
     },
   },
 };

package/src/FrappeReportView.tsx

@@ -25,9 +25,13 @@
  * anything else falls back to Data.
  *
  * Column mapping targets read-only display: fieldtypes map to DataTable
- * `field` types so DG-TBL-01 align-by-type defaults apply automatically
- * (numerics right via `stepper`, Check centered via `checkbox`, text left)
- * and cells format through the forms `FieldDisplay` pipeline (`readOnly`).
+ * `field` types and cells format through the forms `FieldDisplay` pipeline
+ * (`readOnly`); the DG-TBL-01 align-by-type resolution (numerics right via
+ * `stepper`, Check centered via `checkbox`, text left) is pinned once per
+ * column on the typed `meta.align` channel. Row activation rides
+ * DataTable's first-class `onRowPress`/`rowLabel` contract — the whole row
+ * is ONE pressable unit (no per-cell pressable wrappers), named by the
+ * report row's `name`/`title` value when present.
  *
  * CSV/JSON export reuses `DataTableExport` from `@multiplatform.one/table`
  * (no new export machinery), capability-gated like FrappeReportBuilder (B12):
@@ -35,7 +39,7 @@
  */
 import { AsyncDebouncer, CallModule, HttpClient, type AuthConfig } from "@multiplatform.one/frappe";
 import { AsyncBoundary } from "@multiplatform.one/components";
-import { DatePicker, FieldDisplay, Spinner } from "@multiplatform.one/forms";
+import { DatePicker, Spinner } from "@multiplatform.one/forms";
 import {
   DataTable,
   DataTableExport,
@@ -44,11 +48,11 @@ import {
   type DataTableProps,
   type DataTableField,
 } from "@multiplatform.one/table";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { formatCalendarDate, useResolvedKnobs } from "@multiplatform.one/theme";
 import { ArrowClockwiseIcon } from "@phosphor-icons/react";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import { Button, Text, View, XStack, YStack, type YStackProps } from "tamagui";
+import { Button, Text, XStack, YStack, type YStackProps } from "tamagui";
 import { useFrappeConfig } from "./FrappeProvider";
 import { Check } from "./fields/Check";
 import { Data } from "./fields/Data";
@@ -269,62 +273,47 @@ export function reportFieldtypeToTableField(column: FrappeReportColumn): {
   }
 }
 
-export interface ReportColumnMapOptions {
-  /** Row press handler — cells wrap in a pressable surface when set. */
-  onRowPress?: (row: FrappeReportRow, index: number) => void;
-  /** Current rows (index lookup for onRowPress). Read at press time. */
-  rowsRef?: { current: FrappeReportRow[] };
-}
-
 /**
  * Map a normalized report column to a DataTableColumn.
  *
- * Without `onRowPress` the column carries a plain `field` (FieldDisplay via
- * the table's readOnly path; alignment fully automatic). With `onRowPress`
- * the cell renders through the `custom` escape hatch (pressable wrapper
- * around the same FieldDisplay) and the DG-TBL-01 alignment is preserved by
- * resolving it explicitly from the underlying field type.
+ * The column carries a plain `field` (FieldDisplay via the table's
+ * readOnly path) and pins its DG-TBL-01 alignment on the typed
+ * `meta.align` channel (numerics right, Check centered, text left) so the
+ * resolved alignment survives every downstream cell surface, custom
+ * renderers included (DataTable's aligned cell wrapper reads it).
  */
 export function reportColumnToDataTableColumn(
   column: FrappeReportColumn,
-  { onRowPress, rowsRef }: ReportColumnMapOptions = {},
 ): DataTableColumn<FrappeReportRow> {
   const { field, fieldProps } = reportFieldtypeToTableField(column);
   const width = column.width != null ? Number(column.width) : undefined;
-  const base: DataTableColumn<FrappeReportRow> = {
+  return {
     id: column.fieldname,
     accessorKey: column.fieldname,
     header: column.label,
     ...(width && Number.isFinite(width) ? { width } : {}),
     field,
     ...(fieldProps ? { fieldProps } : {}),
-  };
-  if (!onRowPress) return base;
-  return {
-    ...base,
-    // Explicit align: the custom field would otherwise default to left.
-    align: getDefaultColumnAlign({ field, fieldProps }),
-    field: "custom",
-    fieldProps: {
-      ...fieldProps,
-      render: (value: unknown, rowData: unknown) => (
-        <View
-          onPress={() => {
-            const rows = rowsRef?.current ?? [];
-            const row = rowData as FrappeReportRow;
-            onRowPress(row, rows.indexOf(row));
-          }}
-          cursor="pointer"
-          minWidth={0}
-          flexShrink={1}
-        >
-          <FieldDisplay field={field} value={value} fieldProps={fieldProps} />
-        </View>
-      ),
-    },
+    meta: { align: getDefaultColumnAlign({ id: column.fieldname, field, fieldProps }) },
   };
 }
 
+/**
+ * Accessible row identity for pressable report rows (DG-A11Y-06): report
+ * rows carry no doctype meta, so identity is the conventional report
+ * identity columns — the linked document `name`, else `title`. An empty
+ * result defers to DataTable's own fallbacks (first visible cell value →
+ * positional "Row N").
+ */
+export function reportRowLabel(row: FrappeReportRow): string {
+  for (const key of ["name", "title"] as const) {
+    const value = row[key];
+    if (typeof value === "string" && value) return value;
+    if (typeof value === "number") return String(value);
+  }
+  return "";
+}
+
 /**
  * Download capability gate for the built-in export path (B12 precedent from
  * FrappeReportBuilder): `downloadBlob` rides a DOM anchor + object URL and
@@ -565,13 +554,6 @@ export function useFrappeReport(
 // Filter bar
 // ---------------------------------------------------------------------------
 
-function toFrappeDate(date: Date): string {
-  const y = date.getFullYear();
-  const m = String(date.getMonth() + 1).padStart(2, "0");
-  const d = String(date.getDate()).padStart(2, "0");
-  return `${y}-${m}-${d}`;
-}
-
 interface ReportFilterFieldProps {
   def: FrappeReportFilterDef;
   value: unknown;
@@ -602,7 +584,7 @@ function ReportFilterField({ def, value, onChange }: ReportFilterFieldProps) {
           label={def.label}
           compact
           value={value == null ? null : String(value)}
-          onChange={(date) => onChange(date ? toFrappeDate(date) : "")}
+          onChange={(date) => onChange(date ? formatCalendarDate(date) : "")}
         />
       );
     case "Check":
@@ -648,7 +630,14 @@ export interface FrappeReportViewProps extends Omit<YStackProps, "children"> {
    * only the desk evaluates.
    */
   filterFields?: FrappeReportFilterDef[];
-  /** Row press handler (row, index). */
+  /**
+   * Callback when a row is activated (row, index into the full row set).
+   * Rides DataTable's first-class `onRowPress` contract: the whole row is
+   * ONE pressable unit (no per-cell pressable wrappers), the row set
+   * exposes a single roving tab stop (LC-49), Enter AND Space activate
+   * the focused row (LC-50), and presses on inner interactive controls
+   * never fire the row press.
+   */
   onRowPress?: (row: FrappeReportRow, index: number) => void;
   /** Fixture payload or loader — renders without any network. */
   fixture?: FrappeReportFixture;
@@ -758,15 +747,10 @@ export function FrappeReportView({
   }, [isControlled, reportName, filterDefs]);
 
   const rows = payload?.rows ?? [];
-  const rowsRef = useRef<FrappeReportRow[]>(rows);
-  rowsRef.current = rows;
 
   const columns = useMemo(
-    () =>
-      (payload?.columns ?? []).map((col) =>
-        reportColumnToDataTableColumn(col, onRowPress ? { onRowPress, rowsRef } : {}),
-      ),
-    [payload?.columns, onRowPress],
+    () => (payload?.columns ?? []).map((col) => reportColumnToDataTableColumn(col)),
+    [payload?.columns],
   );
 
   const exportColumns = useMemo(
@@ -881,7 +865,24 @@ export function FrappeReportView({
           {...boundaryState}
         />
       ) : (
-        <ReportDataTable data={rows} columns={columns} readOnly {...tableProps} />
+        <ReportDataTable
+          data={rows}
+          columns={columns}
+          readOnly
+          // onRowPress (the stable FrappeReportView prop) rides DataTable's
+          // first-class row activation: whole-row press target, roving tab
+          // stop (LC-49), Enter/Space activation (LC-50), inner interactive
+          // controls win. The forwarded index keeps its full-row-set
+          // meaning (DataTable reports page-local indexes). rowLabel names
+          // each pressable row by report identity. Both spread BEFORE
+          // {...tableProps} so an explicit consumer onRowPress/rowLabel
+          // still ejects (consumer-last house rule).
+          {...(onRowPress
+            ? { onRowPress: (row: FrappeReportRow) => onRowPress(row, rows.indexOf(row)) }
+            : {})}
+          rowLabel={reportRowLabel}
+          {...tableProps}
+        />
       )}
     </YStack>
   );

package/src/FrappeTable.keepRows.spec.tsx

@@ -0,0 +1,200 @@
+/**
+ * Keep-rows-and-reconcile (the read arm of the ONE optimistic pattern):
+ * changing the table's filters must NOT tear the list down and re-render
+ * from empty. The current rows stay mounted, the new filter applies
+ * locally to what is already on screen (optimistic narrowing), and the
+ * real query reconciles when data returns — no blanking, no skeleton
+ * flash, no scroll reset.
+ *
+ * The named reproducer was the backoffice list: every filter toggle
+ * remounted FrappeTable (list keyed on a filter generation), resetting
+ * `hasLoadedOnce` and flashing the AsyncBoundary skeleton for the full
+ * round-trip (~1.6s of blank list against the live bench). These specs pin
+ * the replacement contract at the FrappeTable layer: the `filters` prop
+ * adopts in place (content-keyed), held rows render while the swapped
+ * collection loads, and the loading boundary is reserved for the FIRST
+ * load only.
+ */
+
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import type { DataTableColumn } from "@multiplatform.one/table";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { FrappeProvider } from "./FrappeProvider";
+import { FrappeTable } from "./FrappeTable";
+
+beforeAll(async () => {
+  if (!i18next.isInitialized) {
+    await i18next.use(initReactI18next).init({
+      lng: "en",
+      interpolation: { escapeValue: false },
+      resources: { en: { translation: {} } },
+    });
+  }
+});
+
+afterEach(() => {
+  cleanup();
+});
+
+interface Customer {
+  name: string;
+  doctype: string;
+  customer_name: string;
+  status: string;
+}
+
+const customers: Customer[] = [
+  { name: "CUST-001", doctype: "Customer", customer_name: "Acme Corp", status: "Active" },
+  { name: "CUST-002", doctype: "Customer", customer_name: "Globex", status: "Active" },
+  { name: "CUST-003", doctype: "Customer", customer_name: "Initech", status: "Lead" },
+];
+
+const columns: DataTableColumn<Partial<Customer>>[] = [
+  { id: "name", accessorKey: "name", header: "ID" },
+  { id: "customer_name", accessorKey: "customer_name", header: "Customer Name" },
+  { id: "status", accessorKey: "status", header: "Status" },
+];
+
+const filterFields = [{ id: "status", label: "Status", type: "text" as const }];
+
+/**
+ * Fixture provider whose getList can be gated: while `gate` is set, list
+ * fetches wait on it — models the server round-trip a filter change causes,
+ * so the specs can assert what renders DURING the gap.
+ */
+class GatedFixtureProvider extends InMemoryFixtureProvider {
+  gate: Promise<void> | null = null;
+
+  override async getList<TDoc extends { name: string; doctype: string }>(
+    ...args: Parameters<InMemoryFixtureProvider["getList"]>
+  ) {
+    if (this.gate) await this.gate;
+    return super.getList(...args) as Promise<Partial<TDoc>[]>;
+  }
+}
+
+function renderTable(
+  fixtures: InMemoryFixtureProvider,
+  filters: Array<[keyof Customer & string, string, unknown]>,
+) {
+  return renderWithProviders(
+    <FrappeProvider baseURL="https://frappetable-keeprows.spec.test" fixtures={fixtures}>
+      <FrappeTable<Customer>
+        doctype="Customer"
+        columns={columns}
+        filterableFields={filterFields}
+        filters={filters}
+        layout="table"
+        enablePagination={false}
+      />
+    </FrappeProvider>,
+  );
+}
+
+function rerenderTable(
+  rerender: (ui: React.ReactElement) => void,
+  fixtures: InMemoryFixtureProvider,
+  filters: Array<[keyof Customer & string, string, unknown]>,
+) {
+  rerender(
+    <FrappeProvider baseURL="https://frappetable-keeprows.spec.test" fixtures={fixtures}>
+      <FrappeTable<Customer>
+        doctype="Customer"
+        columns={columns}
+        filterableFields={filterFields}
+        filters={filters}
+        layout="table"
+        enablePagination={false}
+      />
+    </FrappeProvider>,
+  );
+}
+
+describe("FrappeTable keep-rows-and-reconcile on filter change", () => {
+  it("keeps current rows rendered and locally narrows them while the new query is in flight, then reconciles", async () => {
+    const fixtures = new GatedFixtureProvider({ Customer: customers });
+    const { rerender } = renderTable(fixtures, []);
+    await screen.findByText("Acme Corp");
+    expect(screen.getByText("Initech")).toBeTruthy();
+
+    // Gate the round-trip the filter change will cause.
+    let release: () => void = () => {};
+    fixtures.gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    rerenderTable(rerender, fixtures, [["status", "=", "Active"]]);
+
+    // DURING the gap: the matching rows never left the screen, the filter
+    // already applied to what was cached locally, and no loading boundary
+    // replaced the table.
+    await waitFor(() => expect(screen.queryByText("Initech")).toBeNull());
+    expect(screen.getByText("Acme Corp")).toBeTruthy();
+    expect(screen.getByText("Globex")).toBeTruthy();
+    expect(screen.queryByText(/No Customer records found/i)).toBeNull();
+
+    // Reconcile: the server (fixture) result replaces the held rows.
+    release();
+    fixtures.gate = null;
+    await waitFor(() => {
+      expect(screen.getByText("Acme Corp")).toBeTruthy();
+      expect(screen.getByText("Globex")).toBeTruthy();
+      expect(screen.queryByText("Initech")).toBeNull();
+    });
+  });
+
+  it("a filter that matches no current rows keeps the last-good rows mounted (no empty boundary)", async () => {
+    const fixtures = new GatedFixtureProvider({ Customer: customers });
+    const { rerender } = renderTable(fixtures, []);
+    await screen.findByText("Acme Corp");
+
+    let release: () => void = () => {};
+    fixtures.gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    rerenderTable(rerender, fixtures, [["status", "=", "Closed"]]);
+
+    // DURING the gap: local apply would empty the page — previous rows stay
+    // as placeholderData. The empty AsyncBoundary must not replace the table.
+    expect(screen.getByText("Acme Corp")).toBeTruthy();
+    expect(screen.getByText("Initech")).toBeTruthy();
+    expect(screen.queryByText(/No Customer records found/i)).toBeNull();
+
+    release();
+    fixtures.gate = null;
+    await waitFor(() => {
+      expect(screen.queryByText("Acme Corp")).toBeNull();
+      expect(screen.getByText(/No Customer records found/i)).toBeTruthy();
+    });
+  });
+
+  it("clearing the filter keeps the narrowed rows rendered until the wider set reconciles in", async () => {
+    const fixtures = new GatedFixtureProvider({ Customer: customers });
+    const { rerender } = renderTable(fixtures, [["status", "=", "Active"]]);
+    await screen.findByText("Acme Corp");
+    expect(screen.queryByText("Initech")).toBeNull();
+
+    let release: () => void = () => {};
+    fixtures.gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    rerenderTable(rerender, fixtures, []);
+
+    // DURING the gap: last-good rows stay (no filter to narrow with).
+    expect(screen.getByText("Acme Corp")).toBeTruthy();
+    expect(screen.getByText("Globex")).toBeTruthy();
+    expect(screen.queryByText(/No Customer records found/i)).toBeNull();
+
+    release();
+    fixtures.gate = null;
+    // Reconcile: the wider set (including Initech) arrives.
+    await screen.findByText("Initech");
+    expect(screen.getByText("Acme Corp")).toBeTruthy();
+  });
+});