@multiplatform.one/frappe-ui 7.10.0 → 7.15.0

package/src/FrappeFormConnections.tsx

@@ -0,0 +1,148 @@
+import { AsyncBoundary, PageSection } from "@multiplatform.one/components";
+import { DataTable, type DataTableColumn } from "@multiplatform.one/table";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { YStack } from "tamagui";
+import { connectionFields, type FrappeConnection } from "./frappeConnections";
+import { isPermissionError } from "./liveErrors";
+import { useFrappeRows, type FrappeRowsConnection } from "./useFrappeRows";
+
+type ConnectionRow = Record<string, unknown> & { name: string; doctype: string };
+
+const bookkeepingKeys = new Set([
+  "name",
+  "doctype",
+  "owner",
+  "creation",
+  "modified",
+  "modified_by",
+  "docstatus",
+  "idx",
+  "parent",
+  "parentfield",
+  "parenttype",
+  "_user_tags",
+  "_comments",
+  "_assign",
+  "_liked_by",
+  "_seen",
+]);
+
+/** "poke_type" -> "Poke Type". */
+function fieldLabel(key: string): string {
+  return key.replace(/_/g, " ").replace(/(^|\s)\S/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Columns for one connection's rows: its declared fields, else what the rows
+ * carry. The link field is left out; every row holds the same record.
+ */
+function connectionColumns(
+  link: FrappeConnection,
+  rows: readonly ConnectionRow[],
+): DataTableColumn<ConnectionRow>[] {
+  const declared = (link.fields ?? []).filter((field) => field !== "name");
+  const keys = (
+    declared.length > 0
+      ? declared
+      : Object.keys(rows[0] ?? {}).filter((key) => !bookkeepingKeys.has(key))
+  ).filter((key) => key !== link.fieldname);
+  return (keys.length > 0 ? keys : ["name"]).map((key) => ({
+    id: key,
+    accessorKey: key,
+    header: fieldLabel(key),
+  }));
+}
+
+export interface FrappeFormConnectionSectionProps {
+  connection: FrappeRowsConnection | undefined;
+  link: FrappeConnection;
+  /** The record whose linked rows to read. */
+  name: string;
+}
+
+/** One connection of a record: its linked rows, live, with honest states. */
+export function FrappeFormConnectionSection({
+  connection,
+  link,
+  name,
+}: FrappeFormConnectionSectionProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const options = useMemo(
+    () => ({
+      fields: connectionFields(link),
+      filters: [[link.fieldname, "=", name]] as Array<[string, string, unknown]>,
+      limit: link.limit ?? 0,
+    }),
+    [link, name],
+  );
+  const { rows, isLoading, error } = useFrappeRows<ConnectionRow>(
+    connection,
+    link.doctype,
+    options as never,
+  );
+  const columns = useMemo(() => connectionColumns(link, rows), [link, rows]);
+  const title = t(link.label ?? link.doctype);
+  return (
+    <PageSection
+      title={isLoading || error ? title : `${title} (${rows.length})`}
+      divider={false}
+      testID={`frappe-form-connection-${link.doctype.toLowerCase().replace(/\s+/g, "-")}`}
+    >
+      <YStack {...knobProps.gap}>
+        <AsyncBoundary
+          layout="table"
+          compact
+          loading={isLoading}
+          error={error}
+          errorTitle={
+            error && isPermissionError(error)
+              ? t("You do not have permission to view {{doctype}}", { doctype: link.doctype })
+              : t("Error loading {{doctype}}", { doctype: link.doctype })
+          }
+          empty={rows.length === 0}
+          emptyTitle={t("No {{doctype}} rows", { doctype: link.doctype })}
+        >
+          <DataTable<ConnectionRow>
+            data={rows}
+            columns={columns}
+            enableFiltering={false}
+            enableGlobalSearch={false}
+            enablePagination={false}
+            enableColumnVisibility={false}
+            enableViews={false}
+          />
+        </AsyncBoundary>
+      </YStack>
+    </PageSection>
+  );
+}
+
+export interface FrappeFormConnectionsProps {
+  connection: FrappeRowsConnection | undefined;
+  connections: readonly FrappeConnection[];
+  name: string;
+}
+
+/** The desk's Connections for one record: a section per linked doctype. */
+export function FrappeFormConnections({
+  connection,
+  connections,
+  name,
+}: FrappeFormConnectionsProps) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack {...knobProps.gapLg} testID="frappe-form-connections">
+      {connections.map((link) => (
+        <FrappeFormConnectionSection
+          key={`${link.doctype}:${link.fieldname}`}
+          connection={connection}
+          link={link}
+          name={name}
+        />
+      ))}
+    </YStack>
+  );
+}

package/src/FrappeGuestMeta.spec.tsx

@@ -0,0 +1,143 @@
+// A signed-out visitor reads Guest-readable rows, but getdoctype and the
+// DocType document are closed to Guest (MPO-322): pokemon's list and detail
+// each logged a 403 for meta they render without. The bench below answers
+// meta only to the signed-in bearer token, like the live tenant.
+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 { Text } from "tamagui";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { FrappeForm } from "./FrappeForm";
+import { FrappeListView } from "./FrappeListView";
+import { FrappeProvider } from "./FrappeProvider";
+
+interface Pokemon {
+  name: string;
+  doctype: string;
+  pokemon_name: string;
+  poke_id: number;
+}
+
+const fields = ["name", "pokemon_name", "poke_id"] as const;
+const roster = [
+  { name: "bulbasaur", pokemon_name: "Bulbasaur", poke_id: 1 },
+  { name: "ivysaur", pokemon_name: "Ivysaur", poke_id: 2 },
+];
+const pokemonMeta = {
+  name: "Pokemon",
+  title_field: "pokemon_name",
+  fields: [{ fieldname: "pokemon_name", fieldtype: "Data", label: "Pokemon Name" }],
+  permissions: [{ role: "Guest", read: 1 }],
+};
+
+const signedOut = { useToken: true, type: "Bearer", token: async () => "" };
+const signedIn = { useToken: true, type: "Bearer", token: async () => "jwt" };
+
+let run = 0;
+let bench = "";
+let metaReads: string[] = [];
+
+function json(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function stubBench() {
+  metaReads = [];
+  vi.stubGlobal("fetch", async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(String(input instanceof Request ? input.url : input));
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : {}));
+    if (
+      url.pathname === "/api/method/frappe.desk.form.load.getdoctype" ||
+      url.pathname.startsWith("/api/resource/DocType/")
+    ) {
+      metaReads.push(url.pathname);
+      return headers.get("authorization") === "Bearer jwt"
+        ? json({ docs: [pokemonMeta] })
+        : json({ exc_type: "PermissionError" }, 403);
+    }
+    if (url.pathname === "/api/resource/Pokemon") return json({ data: roster });
+    if (url.pathname === "/api/resource/Pokemon/bulbasaur") {
+      return json({ data: { ...roster[0], doctype: "Pokemon" } });
+    }
+    return json({ data: [] });
+  });
+}
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+beforeEach(() => {
+  run += 1;
+  bench = `http://guest-meta-${run}.spec.test`;
+  stubBench();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+function settle() {
+  return new Promise((resolve) => setTimeout(resolve, 50));
+}
+
+function cardGrid(auth: typeof signedOut) {
+  return (
+    <FrappeProvider baseURL={bench} realtime={false} auth={auth}>
+      <FrappeListView<Pokemon>
+        doctype="Pokemon"
+        fields={fields}
+        viewMode="grid"
+        renderCard={(pokemon) => <Text>{pokemon.pokemon_name}</Text>}
+        showToolbar={false}
+        showSearch={false}
+      />
+    </FrappeProvider>
+  );
+}
+
+describe("DocType meta for a signed-out visitor", () => {
+  it("the card grid renders its rows without asking for meta", async () => {
+    renderWithProviders(cardGrid(signedOut));
+    await waitFor(() => expect(screen.getByText("Ivysaur")).toBeTruthy());
+    await settle();
+    expect(metaReads).toEqual([]);
+  });
+
+  it("a render-prop form renders its doc without asking for meta", async () => {
+    renderWithProviders(
+      <FrappeProvider baseURL={bench} realtime={false} auth={signedOut}>
+        <FrappeForm<Pokemon>
+          doctype="Pokemon"
+          name="bulbasaur"
+          connections={[]}
+          showToolbar={false}
+          showSidebar={false}
+          showTimeline={false}
+        >
+          {({ doc }) => <Text>{`read ${doc.pokemon_name ?? ""}`}</Text>}
+        </FrappeForm>
+      </FrappeProvider>,
+    );
+    await waitFor(() => expect(screen.getByText("read Bulbasaur")).toBeTruthy());
+    await settle();
+    expect(metaReads).toEqual([]);
+  });
+
+  it("a signed-in reader still loads meta", async () => {
+    renderWithProviders(cardGrid(signedIn));
+    await waitFor(() => expect(screen.getByText("Ivysaur")).toBeTruthy());
+    await waitFor(() =>
+      expect(metaReads).toContain("/api/method/frappe.desk.form.load.getdoctype"),
+    );
+  });
+});

package/src/FrappeImageView.tsx

@@ -1,4 +1,4 @@
-import { useDocTypeMeta, useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import { useDocTypeMeta } from "@multiplatform.one/frappe";
 import { AsyncSkeleton, Card, ImageGrid } from "@multiplatform.one/components";
 import { ImageSquareIcon } from "@phosphor-icons/react";
 import React, { useMemo } from "react";
@@ -9,6 +9,7 @@ import { isServer } from "@multiplatform.one/platform";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeReconnectIndicator } from "./FrappeReconnectIndicator";
+import { useFrappeRows } from "./useFrappeRows";
 
 /**
  * True when this module is evaluated during web server rendering.
@@ -66,9 +67,8 @@ export interface FrappeImageViewProps<TDoc extends { name: string; doctype: stri
 /**
  * Thin Frappe wrapper around the generic ImageGrid component.
  *
- * Fetches data via `useFrappeCollection` / `useLiveQuery`, resolves image
- * URLs, and passes items to the generic `ImageGrid` from
- * `@multiplatform.one/components`.
+ * Fetches data via `useFrappeRows`, resolves image URLs, and passes items
+ * to the generic `ImageGrid` from `@multiplatform.one/components`.
  *
  * **SSR**: `useLiveQuery` (via `useSyncExternalStore`) lacks a
  * `getServerSnapshot` so it can't run on the server. If the consumer
@@ -150,7 +150,7 @@ export function FrappeImageView<TDoc extends { name: string; doctype: string }>(
 
 /**
  * Inner client-only implementation that calls the hooks requiring a
- * browser environment (useFrappeCollection, useLiveQuery).
+ * browser environment (useFrappeRows).
  */
 function FrappeImageViewClient<TDoc extends { name: string; doctype: string }>({
   doctype,
@@ -180,7 +180,7 @@ function FrappeImageViewClient<TDoc extends { name: string; doctype: string }>({
     throw new Error("FrappeImageView requires baseURL prop or FrappeProvider with baseURL");
   }
 
-  // Memoize so downstream hooks (useDocTypeMeta / useFrappeCollection) receive
+  // Memoize so downstream hooks (useDocTypeMeta / useFrappeRows) receive
   // a stable config reference across renders instead of a fresh object each
   // time (which would otherwise retrigger their effects every render).
   const appConfig = useMemo(
@@ -240,15 +240,11 @@ function FrappeImageViewClient<TDoc extends { name: string; doctype: string }>({
     return searchFilter as unknown as typeof filters;
   }, [filters, searchText, effectiveTitleField]);
 
-  const collection = useFrappeCollection<TDoc>(appConfig, doctype, {
+  const { rows: items, isQueryLoading: isDataLoading } = useFrappeRows<TDoc>(appConfig, doctype, {
     fields: effectiveFields,
     filters: effectiveFilters,
+    limit: null,
   });
-  const { data: rawData, isLoading: isDataLoading } = useLiveQuery(
-    (q) => (collection ? q.from({ _list: collection }) : null),
-    [collection],
-  );
-  const items = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
 
   // Only block rendering on DocType-meta loading when we actually need it
   // (i.e. the caller didn't pass explicit image/title fields). The meta

package/src/FrappeList.tsx

@@ -1,13 +1,19 @@
-import { AsyncBoundary, List, type ListProps } from "@multiplatform.one/components";
+import {
+  AsyncBoundary,
+  ImageGrid,
+  List,
+  type ImageGridProps,
+  type ListProps,
+} from "@multiplatform.one/components";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import type React from "react";
-import { useMemo } from "react";
+import { useCallback, useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { YStack } from "tamagui";
 import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeReconnectIndicator } from "./FrappeReconnectIndicator";
 import { isPermissionError } from "./liveErrors";
-import { useFrappePagination } from "./useFrappePagination";
+import { useFrappePagination, type UseFrappePaginationOptions } from "./useFrappePagination";
 
 export interface FrappeListProps<TDoc extends { name: string; doctype: string }> extends Omit<
   ListProps<Partial<TDoc>>,
@@ -21,8 +27,25 @@ export interface FrappeListProps<TDoc extends { name: string; doctype: string }>
   doctype: string;
   fields?: readonly (keyof TDoc & string)[];
   filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, any]>;
+  /** Rows the subscription reads; omitted, the bench's page length (20) applies. */
+  limit?: number;
+  orderBy?: UseFrappePaginationOptions<TDoc>["orderBy"];
+  /** Server-rendered rows for this same query, shown until the first sync lands. */
+  initialRows?: readonly Partial<TDoc>[];
   /** Page size for progressive loading (default 20). */
   pageSize?: number;
+  /**
+   * `grid` lays the rows out as cards through the catalog ImageGrid;
+   * `renderItem` then draws one card. Loading, error and empty stay the
+   * same states in both layouts.
+   */
+  layout?: "list" | "grid";
+  /** Grid layout: column count, tile rung and media aspect of the cards. */
+  gridProps?: Pick<ImageGridProps<Partial<TDoc>>, "columns" | "tileSize" | "mediaAspect">;
+  /** Replaces the default empty message when the doctype has no rows to show. */
+  emptyState?: React.ReactNode;
+  /** Error-state retry, e.g. a remount that starts one fresh sync. */
+  onRetry?: () => void;
 }
 
 /**
@@ -39,8 +62,15 @@ export function FrappeList<TDoc extends { name: string; doctype: string }>({
   doctype,
   fields,
   filters,
+  limit,
+  orderBy,
+  initialRows,
   pageSize,
   renderItem,
+  layout = "list",
+  gridProps,
+  emptyState,
+  onRetry,
   ...listProps
 }: FrappeListProps<TDoc>) {
   const config = useFrappeConfig();
@@ -85,7 +115,16 @@ export function FrappeList<TDoc extends { name: string; doctype: string }>({
   const { items, isLoading, onLoadMore, hasMore, error } = useFrappePagination<TDoc>(
     connectionConfig,
     doctype,
-    { fields, filters, pageSize },
+    { fields, filters, pageSize, limit, orderBy, initialRows: initialRows as readonly TDoc[] },
+  );
+
+  const itemIndex = useMemo(
+    () => new Map<Partial<TDoc>, number>(items.map((item, index) => [item, index])),
+    [items],
+  );
+  const renderCard = useCallback(
+    (item: Partial<TDoc>) => renderItem(item, itemIndex.get(item) ?? 0),
+    [renderItem, itemIndex],
   );
 
   // Honest error state: a permission/network failure must not masquerade
@@ -93,8 +132,9 @@ export function FrappeList<TDoc extends { name: string; doctype: string }>({
   if (error) {
     return (
       <AsyncBoundary
-        layout="list"
+        layout={layout === "grid" ? "generic" : "list"}
         error={error}
+        onRetry={onRetry}
         errorTitle={
           isPermissionError(error)
             ? t("You do not have permission to view {{doctype}}", { doctype })
@@ -105,7 +145,7 @@ export function FrappeList<TDoc extends { name: string; doctype: string }>({
   }
 
   return (
-    <YStack {...knobProps.gap} flex={1}>
+    <YStack {...knobProps.gap} flex={layout === "grid" ? undefined : 1}>
       <FrappeReconnectIndicator config={connectionConfig} />
       {/*
         No chrome fragment rides this passthrough (LC-55 FRAGMENT-LICENSE):
@@ -114,15 +154,31 @@ export function FrappeList<TDoc extends { name: string; doctype: string }>({
         clip. Rows and the error/empty panels own their own chrome; the error
         branch above renders a bare AsyncBoundary, so both paths now match.
       */}
-      <List
-        items={items}
-        isLoading={isLoading}
-        renderItem={renderItem}
-        onLoadMore={onLoadMore}
-        hasMore={hasMore}
-        emptyMessage={t("No {{doctype}} records found", { doctype })}
-        {...listProps}
-      />
+      {!isLoading && items.length === 0 && emptyState ? (
+        emptyState
+      ) : layout === "grid" ? (
+        <ImageGrid
+          items={items}
+          isLoading={isLoading}
+          renderItem={renderCard}
+          onItemClick={listProps.onItemClick}
+          onLoadMore={onLoadMore}
+          hasMore={hasMore}
+          emptyMessage={listProps.emptyMessage ?? t("No {{doctype}} records found", { doctype })}
+          testID={listProps.testID}
+          {...gridProps}
+        />
+      ) : (
+        <List
+          items={items}
+          isLoading={isLoading}
+          renderItem={renderItem}
+          onLoadMore={onLoadMore}
+          hasMore={hasMore}
+          emptyMessage={t("No {{doctype}} records found", { doctype })}
+          {...listProps}
+        />
+      )}
     </YStack>
   );
 }

package/src/FrappeListView.cards.spec.tsx

@@ -0,0 +1,175 @@
+// FrappeListView's card slot (MPO-331): a doctype with a picture keeps its
+// card without leaving the component. `renderCard` draws each row into the
+// catalog ImageGrid; loading, empty and error stay the view's own states.
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { Text } from "tamagui";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  createRosterFixtures,
+  rosterPokemon,
+  rosterPokemonFields,
+  rosterPokemonMeta,
+  type RosterPokemon,
+} from "../tests/fixtures/pokemonRoster";
+import { FrappeListView, type FrappeListViewProps } from "./FrappeListView";
+import { FrappeProvider } from "./FrappeProvider";
+
+const host = "https://listview-cards.spec.test";
+const realFetch = globalThis.fetch;
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    if (url.startsWith(host)) {
+      const body = /\/api\/resource\/DocType\//.test(url)
+        ? { data: rosterPokemonMeta }
+        : { data: [] };
+      return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    return realFetch(input as RequestInfo, init);
+  }) as typeof fetch;
+});
+
+afterAll(() => {
+  globalThis.fetch = realFetch;
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const card = (pokemon: Partial<RosterPokemon>, index: number) => (
+  <Text testID={`card-${pokemon.name}`}>{`${index}:${pokemon.pokemon_name}`}</Text>
+);
+
+function renderCards(
+  fixtures: InMemoryFixtureProvider,
+  props: Partial<FrappeListViewProps<RosterPokemon>> = {},
+) {
+  return renderWithProviders(
+    <FrappeProvider baseURL={host} fixtures={fixtures}>
+      <FrappeListView<RosterPokemon>
+        doctype="Pokemon"
+        fields={rosterPokemonFields}
+        viewMode="grid"
+        renderCard={card}
+        {...props}
+      />
+    </FrappeProvider>,
+  );
+}
+
+describe("FrappeListView card slot", () => {
+  it("draws every row through renderCard in the grid", async () => {
+    renderCards(createRosterFixtures());
+    for (const pokemon of rosterPokemon) {
+      await waitFor(() => expect(screen.getByTestId(`card-${pokemon.name}`)).toBeTruthy());
+    }
+    expect(screen.getByTestId("card-bulbasaur").textContent).toMatch(/^\d+:bulbasaur$/);
+  });
+
+  it("hands the slot each row's position in the page", async () => {
+    renderCards(createRosterFixtures());
+    await waitFor(() => expect(screen.getByTestId("card-eevee")).toBeTruthy());
+    const positions = rosterPokemon.map((pokemon) =>
+      Number(screen.getByTestId(`card-${pokemon.name}`).textContent?.split(":")[0]),
+    );
+    expect([...positions].sort((a, b) => a - b)).toEqual(rosterPokemon.map((_, i) => i));
+  });
+
+  it("offers the card grid in the view switcher only when a slot is given", async () => {
+    const { unmount } = renderCards(createRosterFixtures(), { viewMode: undefined });
+    await waitFor(() => expect(screen.getByText("Cards")).toBeTruthy());
+    unmount();
+    renderWithProviders(
+      <FrappeProvider baseURL={host} fixtures={createRosterFixtures()}>
+        <FrappeListView<RosterPokemon> doctype="Pokemon" fields={rosterPokemonFields} />
+      </FrappeProvider>,
+    );
+    await waitFor(() => expect(screen.getByText("Table")).toBeTruthy());
+    expect(screen.queryByText("Cards")).toBeNull();
+  });
+
+  it("a grid asked for without a slot falls back to the list", async () => {
+    renderWithProviders(
+      <FrappeProvider baseURL={host} fixtures={createRosterFixtures()}>
+        <FrappeListView<RosterPokemon>
+          doctype="Pokemon"
+          fields={rosterPokemonFields}
+          viewMode="grid"
+          displayFields={[{ key: "pokemon_name" }]}
+        />
+      </FrappeProvider>,
+    );
+    await waitFor(() => expect(screen.getByText("pikachu")).toBeTruthy());
+    expect(screen.queryByTestId("card-pikachu")).toBeNull();
+  });
+
+  it("switching views reports the mode and leaves a controlled view where it is", async () => {
+    const onViewModeChange = vi.fn();
+    renderCards(createRosterFixtures(), { onViewModeChange });
+    await waitFor(() => expect(screen.getByTestId("card-pikachu")).toBeTruthy());
+    fireEvent.click(screen.getByText("Table"));
+    expect(onViewModeChange).toHaveBeenCalledWith("table");
+    expect(screen.getByTestId("card-pikachu")).toBeTruthy();
+  });
+});
+
+describe("FrappeListView card grid states", () => {
+  it("renders the grid's skeleton while the first page loads", async () => {
+    const fixtures = createRosterFixtures();
+    let release: () => void = () => undefined;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const getList = fixtures.getList.bind(fixtures);
+    vi.spyOn(fixtures, "getList").mockImplementation(async (...args) => {
+      await gate;
+      return getList(...args);
+    });
+    renderCards(fixtures);
+    await waitFor(() =>
+      expect(
+        document.querySelector('[data-testid="image-grid-skeleton"], [aria-busy="true"]'),
+      ).toBeTruthy(),
+    );
+    expect(screen.queryByTestId("card-pikachu")).toBeNull();
+    release();
+    await waitFor(() => expect(screen.getByTestId("card-pikachu")).toBeTruthy());
+  });
+
+  it("an empty doctype shows the empty message, not a blank grid", async () => {
+    renderCards(createRosterFixtures({ Pokemon: [] }));
+    await waitFor(() => expect(screen.getByText("No Pokemon records found")).toBeTruthy());
+  });
+
+  it("an empty doctype shows the screen's own empty state when one is given", async () => {
+    renderCards(createRosterFixtures({ Pokemon: [] }), {
+      emptyState: <Text testID="roster-empty">Catch your first Pokemon</Text>,
+    });
+    await waitFor(() => expect(screen.getByTestId("roster-empty")).toBeTruthy());
+    expect(screen.queryByText("No Pokemon records found")).toBeNull();
+  });
+
+  it("a failed read is an error with a retry, never an empty grid", async () => {
+    const fixtures = createRosterFixtures();
+    vi.spyOn(fixtures, "getList").mockRejectedValue(new Error("Failed to fetch"));
+    renderCards(fixtures, { emptyState: <Text testID="roster-empty">empty</Text> });
+    await waitFor(() => expect(screen.getByText("Error loading Pokemon")).toBeTruthy());
+    expect(screen.queryByTestId("roster-empty")).toBeNull();
+    expect(screen.getByRole("button", { name: /retry/i })).toBeTruthy();
+  });
+});