@multiplatform.one/frappe-ui 7.23.2 → 7.24.0

package/src/FrappeListView.card.spec.tsx

@@ -0,0 +1,157 @@
+// FrappeListView's record card (MPO-411): a list whose doctype declares a
+// look draws each record as a card without a card slot of its own, the way
+// pokemon's roster drew its Pokedex card by hand.
+import fs from "node:fs";
+import path from "node:path";
+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 { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  createRosterFixtures,
+  rosterPokemonFields,
+  rosterPokemonMeta,
+  type RosterPokemon,
+} from "../tests/fixtures/pokemonRoster";
+import type { FrappeNavigation } from "./frappeNavigation";
+import { FrappeListView, type FrappeListViewProps } from "./FrappeListView";
+import { FrappeProvider } from "./FrappeProvider";
+import { favoritesStore } from "./list/favorites";
+
+const host = "https://listview-card.spec.test";
+const realFetch = globalThis.fetch;
+const favoritesKey = "card-spec-favorites";
+
+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();
+  favoritesStore(favoritesKey).setState(() => ({ names: [] }));
+});
+
+const look: FrappeListViewProps<RosterPokemon>["look"] = {
+  title: (doc) => (doc.pokemon_name ?? "").toUpperCase(),
+  code: (doc) => `#${String(doc.poke_id ?? 0).padStart(3, "0")}`,
+  subtitle: (doc) => doc.species,
+  images: (doc) => [`https://art.spec.test/${doc.poke_id}.png`, doc.sprite_front ?? ""],
+};
+
+function renderList(navigate = vi.fn()) {
+  const navigation: FrappeNavigation = {
+    usePathname: () => "/pokemon",
+    useNavigate: () => navigate,
+  };
+  return renderWithProviders(
+    <FrappeProvider baseURL={host} fixtures={createRosterFixtures()} navigation={navigation}>
+      <FrappeListView<RosterPokemon>
+        doctype="Pokemon"
+        route="/pokemon"
+        fields={rosterPokemonFields}
+        defaultViewMode="grid"
+        look={look}
+        favorites={favoritesKey}
+        facets={[
+          {
+            param: "type",
+            doctype: "Pokemon Poke Type",
+            field: "poke_type",
+            orderBy: "slot",
+            label: "Type",
+            options: ["grass", "poison", "fire", "water", "electric", "ghost", "normal"],
+            optionLabel: (value) => `type:${value}`,
+            tint: (value) => (value === "grass" ? "grass" : "purple"),
+          },
+        ]}
+      />
+    </FrappeProvider>,
+  );
+}
+
+describe("FrappeListView draws a record card from the doctype's look", () => {
+  it("offers the card grid and names each card by the doctype and the record", async () => {
+    renderList();
+    const card = await screen.findByTestId("pokemon-card-bulbasaur", {}, { timeout: 5000 });
+    expect(card.textContent).toContain("BULBASAUR");
+    expect(card.textContent).toContain("#001");
+    expect(card.textContent).toContain("Seed Pokémon");
+    expect(screen.getAllByTestId(/^pokemon-card-/)).toHaveLength(6);
+  });
+
+  it("draws the look's first image and the facet's values as badges in slot order", async () => {
+    renderList();
+    const card = await screen.findByTestId("pokemon-card-bulbasaur", {}, { timeout: 5000 });
+    expect(card.querySelector("img")?.getAttribute("src")).toBe("https://art.spec.test/1.png");
+    await waitFor(() => {
+      const text = card.textContent ?? "";
+      expect(text).toContain("type:grass");
+      expect(text.indexOf("type:grass")).toBeLessThan(text.indexOf("type:poison"));
+    });
+  });
+
+  it("links the card to the record under the list's route", async () => {
+    renderList();
+    const card = await screen.findByTestId("pokemon-card-bulbasaur", {}, { timeout: 5000 });
+    expect(card.querySelector("a")?.getAttribute("href")).toBe("/pokemon/bulbasaur");
+  });
+
+  it("keeps the heart a button beside the link that toggles the favorite and opens nothing", async () => {
+    const navigate = vi.fn();
+    renderList(navigate);
+    const heart = await screen.findByTestId("pokemon-favorite-bulbasaur", {}, { timeout: 5000 });
+    expect(heart.tagName).toBe("BUTTON");
+    expect(heart.getAttribute("type")).toBe("button");
+    expect(heart.closest("a")).toBeNull();
+    expect(heart.getAttribute("aria-pressed")).toBe("false");
+    expect(heart.getAttribute("aria-label")).toBe("Add BULBASAUR to favorites");
+    fireEvent.click(heart);
+    await waitFor(() => expect(favoritesStore(favoritesKey).state.names).toEqual(["bulbasaur"]));
+    await waitFor(() =>
+      expect(screen.getByTestId("pokemon-favorite-bulbasaur").getAttribute("aria-pressed")).toBe(
+        "true",
+      ),
+    );
+    expect(navigate).not.toHaveBeenCalled();
+  });
+});
+
+describe("RecordCard's native twin", () => {
+  const source = fs.readFileSync(path.resolve(__dirname, "list/RecordCard.native.tsx"), "utf8");
+
+  it("presses the card itself, since a native Anchor loses the tap to the Card", () => {
+    expect(source).not.toContain("<Anchor");
+    expect(source).toMatch(/onPress=\{\(\) => onPress\?\.\(\)\}/);
+  });
+
+  it("stops the heart's press from reaching the card", () => {
+    const handler = source.slice(
+      source.indexOf("const handleToggleFavorite"),
+      source.indexOf("return ("),
+    );
+    expect(handler).toContain("stopPropagation");
+  });
+});

package/src/FrappeListView.controls.spec.tsx

@@ -0,0 +1,225 @@
+// FrappeListView's list controls (MPO-411): sorts, a facet on a connection
+// doctype, a range, favorites, a search mapping and the URL state that a
+// list page (pokemon's roster) used to hand-wire around the view.
+import { Order } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { act, 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,
+  rosterPokemonFields,
+  rosterPokemonMeta,
+  type RosterPokemon,
+} from "../tests/fixtures/pokemonRoster";
+import type { FrappeNavigation } from "./frappeNavigation";
+import { FrappeListView, type FrappeListCard, type FrappeListViewProps } from "./FrappeListView";
+import { FrappeProvider } from "./FrappeProvider";
+import { favoritesStore } from "./list/favorites";
+
+const host = "https://listview-controls.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 cards = new Map<string, FrappeListCard | undefined>();
+
+const card = (pokemon: Partial<RosterPokemon>, _index: number, context?: FrappeListCard) => {
+  cards.set(pokemon.name ?? "", context);
+  return <Text testID={`card-${pokemon.name}`}>{pokemon.pokemon_name}</Text>;
+};
+
+const controls: Partial<FrappeListViewProps<RosterPokemon>> = {
+  sorts: [
+    { value: "number", label: "Number", orderBy: [{ field: "poke_id", order: Order.Asc }] },
+    { value: "xp", label: "XP", orderBy: [{ field: "base_experience", order: Order.Desc }] },
+  ],
+  searchFilter: (query) =>
+    /^\d+$/.test(query)
+      ? [["poke_id", "=", Number(query)]]
+      : [["pokemon_name", "like", `%${query}%`]],
+  facets: [
+    {
+      param: "type",
+      doctype: "Pokemon Poke Type",
+      field: "poke_type",
+      orderBy: "slot",
+      label: "Type",
+      allLabel: "All types",
+      options: ["grass", "poison", "fire", "water", "electric", "ghost", "normal"],
+    },
+  ],
+  ranges: [{ param: "xp", field: "base_experience", label: "Min XP" }],
+  favorites: "controls-spec-favorites",
+  urlState: true,
+};
+
+function navigationAt(
+  params: Record<string, string | undefined>,
+  setParams = vi.fn(),
+  navigate = vi.fn(),
+): FrappeNavigation {
+  return {
+    usePathname: () => "/pokemon",
+    useNavigate: () => navigate,
+    useSearchParams: () => params,
+    useSetSearchParams: () => setParams,
+  };
+}
+
+function renderList(
+  params: Record<string, string | undefined> = {},
+  props: Partial<FrappeListViewProps<RosterPokemon>> = {},
+  navigation = navigationAt(params),
+) {
+  cards.clear();
+  return renderWithProviders(
+    <FrappeProvider baseURL={host} fixtures={createRosterFixtures()} navigation={navigation}>
+      <FrappeListView<RosterPokemon>
+        doctype="Pokemon"
+        fields={rosterPokemonFields}
+        defaultViewMode="grid"
+        renderCard={card}
+        {...controls}
+        {...props}
+      />
+    </FrappeProvider>,
+  );
+}
+
+function shownCards(): string[] {
+  return screen.queryAllByTestId(/^card-/).map((node) => node.textContent ?? "");
+}
+
+async function expectCards(names: string[]): Promise<void> {
+  await waitFor(() => expect(shownCards()).toEqual(names), { timeout: 5000 });
+}
+
+describe("FrappeListView controls read their state from the URL", () => {
+  it("orders by the sort the URL names", async () => {
+    renderList({ sort: "xp" });
+    await expectCards(["gengar", "pikachu", "eevee", "bulbasaur", "squirtle", "charmander"]);
+  });
+
+  it("narrows to a facet value through its connection doctype", async () => {
+    renderList({ type: "poison" });
+    await expectCards(["bulbasaur", "gengar"]);
+  });
+
+  it("narrows by a range minimum and by the search mapping", async () => {
+    renderList({ xp: "100" });
+    await expectCards(["pikachu", "gengar"]);
+    cleanup();
+    renderList({ q: "25" });
+    await expectCards(["pikachu"]);
+  });
+
+  it("narrows to the favorites", async () => {
+    favoritesStore("controls-spec-favorites").setState(() => ({ names: ["eevee", "squirtle"] }));
+    renderList({ fav: "1" });
+    await expectCards(["squirtle", "eevee"]);
+    favoritesStore("controls-spec-favorites").setState(() => ({ names: [] }));
+  });
+});
+
+describe("FrappeListView controls write their state back", () => {
+  it("a facet chip narrows the rows and lands in the URL after the commit", async () => {
+    const setParams = vi.fn();
+    renderList({}, {}, navigationAt({}, setParams));
+    await waitFor(() => expect(shownCards().length).toBe(6), { timeout: 5000 });
+    fireEvent.click(await screen.findByTestId("pokemon-type-fire"));
+    await expectCards(["charmander"]);
+    expect(setParams).toHaveBeenCalledWith({ type: "fire" });
+  });
+
+  it("Clear filters drops every narrowing control from the list and the URL", async () => {
+    const setParams = vi.fn();
+    renderList({ type: "fire", xp: "10" }, {}, navigationAt({ type: "fire", xp: "10" }, setParams));
+    await expectCards(["charmander"]);
+    fireEvent.click(screen.getByTestId("pokemon-clear"));
+    await waitFor(() => expect(shownCards().length).toBe(6), { timeout: 5000 });
+    expect(setParams).toHaveBeenLastCalledWith({
+      q: undefined,
+      fav: undefined,
+      type: undefined,
+      xp: undefined,
+    });
+  });
+});
+
+describe("FrappeListView controls hand each card its context", () => {
+  it("gives a card its facet values in slot order, its href and its favorite", async () => {
+    favoritesStore("controls-spec-favorites").setState(() => ({ names: [] }));
+    renderList({}, { route: "/pokemon" });
+    await waitFor(() => expect(cards.get("bulbasaur")?.facets.type).toEqual(["grass", "poison"]));
+    const bulbasaur = cards.get("bulbasaur") as FrappeListCard;
+    expect(bulbasaur.href).toBe("/pokemon/bulbasaur");
+    expect(bulbasaur.favorite?.active).toBe(false);
+    act(() => bulbasaur.favorite?.toggle());
+    await waitFor(() => expect(cards.get("bulbasaur")?.favorite?.active).toBe(true));
+    expect(favoritesStore("controls-spec-favorites").state.names).toEqual(["bulbasaur"]);
+    favoritesStore("controls-spec-favorites").setState(() => ({ names: [] }));
+  });
+
+  it("counts each facet value's records on its chip", async () => {
+    renderList();
+    await waitFor(() =>
+      expect(screen.getByTestId("pokemon-type-poison").textContent).toContain("2"),
+    );
+    expect(screen.getByTestId("pokemon-type-all").textContent).toContain("6");
+  });
+});
+
+describe("FrappeListView routed page with its toolbar off", () => {
+  it("titles the page, counts the records and puts the actions in the header", async () => {
+    const navigate = vi.fn();
+    renderList(
+      {},
+      {
+        route: "/pokemon",
+        showToolbar: false,
+        title: "Roster",
+        subtitle: (count) => `${count} in the roster`,
+        actions: [{ label: "Insights", href: "/pokemon/insights", testID: "insights" }],
+      },
+      navigationAt({}, vi.fn(), navigate),
+    );
+    expect(await screen.findByText("Roster")).toBeTruthy();
+    expect(await screen.findByText("6 in the roster")).toBeTruthy();
+    fireEvent.click(screen.getByTestId("insights"));
+    expect(navigate).toHaveBeenCalledWith("/pokemon/insights");
+    expect(screen.getByText("Skip to results")).toBeTruthy();
+    fireEvent.click(await screen.findByText("Add Pokemon"));
+    expect(navigate).toHaveBeenCalledWith("/pokemon/new");
+  });
+});

package/src/FrappeListView.seed.spec.tsx

@@ -194,6 +194,36 @@ describe("FrappeListView SSR seed", () => {
     expect(listReads[0].searchParams.get("order_by")).toBe("poke_id asc");
   });
 
+  it("seeds from the route's loader, read through the host's navigation", async () => {
+    stubBench();
+    const rows = await serverPage();
+    stubBench({ hold: true });
+    const loader = async () => ({ rows });
+    const useLoader = vi.fn((given: unknown) => (given === loader ? { rows } : undefined));
+    renderWithProviders(
+      <FrappeProvider
+        baseURL={bench}
+        realtime={false}
+        navigation={{ usePathname: () => "/pokemon", useNavigate: () => () => {}, useLoader }}
+      >
+        <FrappeListView<Pokemon>
+          doctype="Pokemon"
+          fields={fields}
+          orderBy={orderBy}
+          viewMode="grid"
+          renderCard={(pokemon) => <Text>{pokemon.pokemon_name}</Text>}
+          showToolbar={false}
+          showSearch={false}
+          pageSize={50}
+          limit={100}
+          loader={loader}
+        />
+      </FrappeProvider>,
+    );
+    expect(renderedNames()).toHaveLength(rosterSize);
+    expect(useLoader).toHaveBeenCalledWith(loader);
+  });
+
   it("lists the live rows in the order it read them, not by name", async () => {
     stubBench({ reversedNames: true });
     renderWithProviders(listView({ limit: 100 }));