@multiplatform.one/frappe-ui 7.23.1 → 7.24.0

package/src/FrappeNotConfigured.tsx

@@ -0,0 +1,29 @@
+import { EmptyState, ListPageLayout, PageHeader } from "@multiplatform.one/components";
+import { useTranslation } from "react-i18next";
+
+export interface FrappeNotConfiguredProps {
+  doctype: string;
+  /** A routed page keeps the page template, the doctype as its title. */
+  page?: boolean;
+}
+
+/**
+ * What a doctype's list or form shows when neither a bench URL nor a fixture
+ * corpus is configured (a host built with Frappe off), in place of the view.
+ */
+export function FrappeNotConfigured({ doctype, page = false }: FrappeNotConfiguredProps) {
+  const { t } = useTranslation();
+  const state = (
+    <EmptyState
+      testID="frappe-not-configured"
+      title={t("Frappe is not configured")}
+      description={t("{{doctype}} can't load without a Frappe bench URL.", { doctype })}
+    />
+  );
+  if (!page) return state;
+  return (
+    <ListPageLayout scroll={false} header={<PageHeader title={doctype} divider={false} />}>
+      {state}
+    </ListPageLayout>
+  );
+}

package/src/FrappeRecordView.spec.tsx

@@ -0,0 +1,276 @@
+// FrappeRecordView (MPO-411): a doctype's record page declared from its look,
+// facet, metrics and tabs, the way pokemon's detail page drew itself by hand.
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { ArrowSquareOutIcon } from "@phosphor-icons/react";
+import { cleanup, fireEvent, screen, waitFor, within } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { Order } from "@multiplatform.one/frappe";
+import {
+  createRosterFixtures,
+  rosterPokemon,
+  rosterPokemonFields,
+  rosterPokemonMeta,
+  type RosterPokemon,
+} from "../tests/fixtures/pokemonRoster";
+import type { FrappeNavigation } from "./frappeNavigation";
+import { FrappeProvider } from "./FrappeProvider";
+import { FrappeRecordView, type FrappeRecordViewProps } from "./FrappeRecordView";
+import { favoritesStore } from "./list/favorites";
+
+const host = "https://record-view.spec.test";
+const realFetch = globalThis.fetch;
+const favoritesKey = "record-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 pokemon = rosterPokemon.map((doc) =>
+  doc.name === "pikachu"
+    ? {
+        ...doc,
+        owner: "ash@example.com",
+        creation: "2026-08-01 10:00:00",
+        modified_by: "misty@example.com",
+        stats: [
+          { stat_name: "speed", base_stat: 90 },
+          { stat_name: "hp", base_stat: 35 },
+        ],
+      }
+    : { ...doc },
+);
+
+const declaration: Partial<FrappeRecordViewProps<RosterPokemon>> = {
+  listTitle: "Roster",
+  fields: rosterPokemonFields,
+  orderBy: [{ field: "poke_id", order: Order.Asc }],
+  connections: [
+    { doctype: "Pokemon Poke Type", fieldname: "pokemon", fields: ["poke_type", "slot"] },
+    {
+      doctype: "Pokemon Poke Ability",
+      fieldname: "pokemon",
+      fields: ["poke_ability", "is_hidden", "slot"],
+    },
+    {
+      doctype: "Pokemon Poke Move",
+      fieldname: "pokemon",
+      fields: ["poke_move", "level_learned_at", "move_learn_method"],
+    },
+  ],
+  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`],
+  },
+  facet: {
+    param: "type",
+    doctype: "Pokemon Poke Type",
+    field: "poke_type",
+    orderBy: "slot",
+    options: [],
+    label: "Type",
+    optionLabel: (value) => `type:${value}`,
+    tint: (value) => (value === "grass" ? "grass" : "purple"),
+  },
+  metrics: [{ field: "base_experience", label: "Base XP", max: 608 }],
+  summary: (doc) => ({ text: `${doc.pokemon_name}, the ${doc.species}.`, cite: "The dex" }),
+  favorites: favoritesKey,
+  actions: [
+    {
+      label: "Open in backoffice",
+      icon: ArrowSquareOutIcon,
+      href: (doc) => `/backoffice/pokemon/${doc.name}`,
+      testID: "hop",
+    },
+  ],
+  tabs: [
+    {
+      value: "overview",
+      label: "Overview",
+      sections: [
+        {
+          kind: "rows",
+          doctype: "Pokemon Poke Ability",
+          field: "poke_ability",
+          title: "Abilities",
+          orderBy: ["slot"],
+          flag: { field: "is_hidden", label: "Hidden" },
+        },
+        {
+          kind: "bars",
+          id: "stats",
+          table: "stats",
+          label: "stat_name",
+          value: "base_stat",
+          max: 255,
+          order: ["hp", "speed"],
+          title: "Stats",
+          totalLabel: "Stat total",
+        },
+      ],
+    },
+    {
+      value: "moves",
+      label: "Moves",
+      count: "Pokemon Poke Move",
+      sections: [
+        {
+          kind: "rows",
+          doctype: "Pokemon Poke Move",
+          field: "poke_move",
+          orderBy: ["move_learn_method", "level_learned_at", "poke_move"],
+          detail: { field: "level_learned_at", label: (level) => `Lv ${level}` },
+          groupBy: { field: "move_learn_method", label: (method) => method.toUpperCase() },
+        },
+      ],
+    },
+  ],
+};
+
+function renderRecord(name: string, navigate = vi.fn()) {
+  const navigation: FrappeNavigation = {
+    usePathname: () => `/pokemon/${name}`,
+    useNavigate: () => navigate,
+  };
+  return renderWithProviders(
+    <FrappeProvider
+      baseURL={host}
+      fixtures={createRosterFixtures({ Pokemon: pokemon })}
+      navigation={navigation}
+    >
+      <FrappeRecordView<RosterPokemon> doctype="Pokemon" route="/pokemon" {...declaration} />
+    </FrappeProvider>,
+  );
+}
+
+async function identity(): Promise<HTMLElement> {
+  return screen.findByTestId("pokemon-hero-identity", {}, { timeout: 5000 });
+}
+
+describe("FrappeRecordView heads the record from its look and facet", () => {
+  it("names the record by code, title and subtitle under the list's breadcrumb", async () => {
+    renderRecord("bulbasaur");
+    const hero = await identity();
+    expect(hero.textContent).toContain("#001");
+    expect(hero.textContent).toContain("BULBASAUR");
+    expect(hero.textContent).toContain("Seed Pokémon");
+    expect(screen.getByText("Roster")).toBeTruthy();
+    expect(screen.getByText("#001 BULBASAUR")).toBeTruthy();
+  });
+
+  it("badges the facet's values in slot order and draws the first image", async () => {
+    renderRecord("bulbasaur");
+    const hero = await identity();
+    await waitFor(() => expect(hero.textContent).toContain("type:poison"));
+    const text = hero.textContent ?? "";
+    expect(text.indexOf("type:grass")).toBeLessThan(text.indexOf("type:poison"));
+    const art = screen.getByTestId("pokemon-hero-art");
+    expect(art.querySelector("img")?.getAttribute("src")).toBe("https://art.spec.test/1.png");
+  });
+
+  it("tiles each metric, a max adding a bar", async () => {
+    renderRecord("bulbasaur");
+    const hero = await identity();
+    expect(hero.textContent).toContain("Base XP");
+    expect(hero.textContent).toContain("64");
+    expect(within(hero).getByLabelText("Base XP")).toBeTruthy();
+  });
+});
+
+describe("FrappeRecordView tabs the record's rows", () => {
+  it("opens with the summary, the linked rows in order with their flags, and the audit trail", async () => {
+    renderRecord("pikachu");
+    await identity();
+    expect(await screen.findByText("pikachu, the Mouse Pokémon.")).toBeTruthy();
+    await waitFor(() => expect(screen.getByText("lightning rod")).toBeTruthy());
+    expect(screen.getAllByText("Hidden")).toHaveLength(1);
+    expect(screen.getByText("Record history")).toBeTruthy();
+  });
+
+  it("draws a child table as bars on a fixed scale with their total", async () => {
+    renderRecord("pikachu");
+    await identity();
+    expect(await screen.findByTestId("pokemon-stats-chart")).toBeTruthy();
+    expect(screen.getByText("Stat total")).toBeTruthy();
+    expect(screen.getByText("125")).toBeTruthy();
+  });
+
+  it("badges a tab with its rows' count and groups them, detailed", async () => {
+    renderRecord("pikachu");
+    await identity();
+    const movesTab = await waitFor(() => {
+      const tab = screen.getAllByRole("tab").find((node) => node.textContent?.includes("Moves"));
+      expect(tab?.textContent).toContain("3");
+      return tab as HTMLElement;
+    });
+    fireEvent.click(movesTab);
+    expect(await screen.findByText("LEVEL-UP")).toBeTruthy();
+    expect(screen.getByText("MACHINE")).toBeTruthy();
+    expect(screen.getByText("Lv 16")).toBeTruthy();
+  });
+});
+
+describe("FrappeRecordView's controls", () => {
+  it("opens the neighbors in the list's order and the edit form", async () => {
+    const navigate = vi.fn();
+    renderRecord("pikachu", navigate);
+    await identity();
+    fireEvent.click(await screen.findByTestId("pokemon-next", {}, { timeout: 5000 }));
+    expect(navigate).toHaveBeenCalledWith("/pokemon/gengar");
+    fireEvent.click(screen.getByTestId("pokemon-prev"));
+    expect(navigate).toHaveBeenCalledWith("/pokemon/squirtle");
+    fireEvent.click(screen.getByTestId("pokemon-detail-edit"));
+    expect(navigate).toHaveBeenCalledWith("/pokemon/pikachu/edit");
+  });
+
+  it("toggles the favorite from a real button and hops through a declared action", async () => {
+    const navigate = vi.fn();
+    renderRecord("pikachu", navigate);
+    const heart = await screen.findByTestId("pokemon-detail-favorite", {}, { timeout: 5000 });
+    expect(heart.tagName).toBe("BUTTON");
+    expect(heart.getAttribute("type")).toBe("button");
+    expect(heart.getAttribute("aria-pressed")).toBe("false");
+    fireEvent.click(heart);
+    await waitFor(() => expect(favoritesStore(favoritesKey).state.names).toEqual(["pikachu"]));
+    fireEvent.click(screen.getByTestId("hop"));
+    expect(navigate).toHaveBeenCalledWith("/backoffice/pokemon/pikachu");
+  });
+
+  it("names a missing record and offers the way back", async () => {
+    const navigate = vi.fn();
+    renderRecord("missingno", navigate);
+    expect(await screen.findByText("Pokemon not found", {}, { timeout: 5000 })).toBeTruthy();
+    fireEvent.click(screen.getByText("Back to Roster"));
+    expect(navigate).toHaveBeenCalledWith("/pokemon");
+  });
+});

package/src/FrappeRecordView.tsx

@@ -0,0 +1,231 @@
+import { EmptyState, Screen, ScreenToolbar, YStack } from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import type { Order } from "@multiplatform.one/frappe";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { ArrowLeftIcon } from "@phosphor-icons/react";
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import type { FrappeConnection } from "./frappeConnections";
+import { FrappeForm } from "./FrappeForm";
+import { frappeRouteTarget, useFrappeRouter, useRouteLoaderData } from "./frappeNavigation";
+import { FrappeNotConfigured } from "./FrappeNotConfigured";
+import { useFrappeConfig } from "./FrappeProvider";
+import { useDocRights } from "./formEngine/useDocRights";
+import { orderRows } from "./insights/insightsData";
+import type { FrappeInsightsMetric } from "./insights/insightsRecord";
+import type { FrappeListFacet } from "./list/listState";
+import type { FrappeRecordLook } from "./list/recordLook";
+import { RecordBreadcrumbBone, RecordSkeleton } from "./record/RecordHero";
+import { RecordPage, type FrappeRecordAction, type RecordPageProps } from "./record/RecordPage";
+import type { FrappeRecordTab } from "./record/recordSections";
+import { useFrappeConnection, useFrappeRows } from "./useFrappeRows";
+
+export type {
+  FrappeRecordBarsSection,
+  FrappeRecordRowsSection,
+  FrappeRecordSection,
+  FrappeRecordTab,
+} from "./record/recordSections";
+
+export type { FrappeRecordAction } from "./record/RecordPage";
+
+type Row = Record<string, unknown>;
+
+export interface FrappeRecordViewProps<TDoc extends { name: string; doctype: string }> {
+  doctype: string;
+  /** The doctype's list route: breadcrumb, Back, Edit and the neighbors hang off it. */
+  route: string;
+  /** Defaults to the record the route names. */
+  name?: string;
+  /** The list's title; defaults to the doctype. */
+  listTitle?: string;
+  /** The record a route loader rendered on the server. */
+  initialDoc?: Partial<TDoc>;
+  /** The route's loader (`frappeDocLoader`), read through the host's navigation. */
+  loader?: (...args: never[]) => Promise<{ doc: Partial<TDoc> | null }>;
+  /** The list's read, so the neighbors follow the list's order. */
+  fields?: readonly (keyof TDoc & string)[];
+  limit?: number;
+  orderBy?: Array<{ field: keyof TDoc & string; order: Order }>;
+  /** Declared connections; defaults to the meta's (a Guest cannot read meta). */
+  connections?: readonly FrappeConnection[];
+  look?: FrappeRecordLook<TDoc>;
+  titleField?: string;
+  /** Its values badge the hero and tint it. */
+  facet?: FrappeListFacet;
+  /** Numeric fields as fact tiles in the hero; `max` adds a bar. */
+  metrics?: readonly FrappeInsightsMetric[];
+  /** A quote opening the first tab. */
+  summary?: (doc: Partial<TDoc>) => { text: string; cite?: string } | undefined;
+  tabs?: readonly FrappeRecordTab[];
+  /** Star the record: true keys the stars by doctype, a string names the key. */
+  favorites?: boolean | string;
+  actions?: readonly FrappeRecordAction<TDoc>[];
+  /** False leaves the audit trail off the first tab. */
+  history?: boolean;
+  /** Prefix of the page's test ids; defaults to the doctype's slug. */
+  testID?: string;
+}
+
+const noTabs: readonly FrappeRecordTab[] = [];
+
+/**
+ * A doctype's record page, read first: the list's breadcrumb and Back, the
+ * favorite heart, the record's hops and Edit under the write right; a hero
+ * with the record's images, code, title, subtitle, facet badges and metric
+ * tiles, tinted by the facet; tabs of linked rows and child-table bars with
+ * the audit trail; and the records either side of it in the list's order.
+ * FrappeForm reads the record and its connections live; loading, not found
+ * and error keep the page's wayfinding.
+ */
+export function FrappeRecordView<TDoc extends { name: string; doctype: string }>({
+  doctype,
+  route,
+  name: nameProp,
+  listTitle,
+  initialDoc,
+  loader,
+  fields,
+  limit,
+  orderBy,
+  connections,
+  look,
+  titleField,
+  facet,
+  metrics = [],
+  summary,
+  tabs = noTabs,
+  favorites,
+  actions = [],
+  history = true,
+  testID,
+}: FrappeRecordViewProps<TDoc>) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const config = useFrappeConfig();
+  const connection = useFrappeConnection();
+  const router = useFrappeRouter();
+  const target = router ? frappeRouteTarget(route, router.pathname) : undefined;
+  const name = nameProp ?? (target?.mode === "view" ? target.name : "");
+  const slug = testID ?? doctype.toLowerCase().replace(/\s+/g, "-");
+  const loaded = useRouteLoaderData(loader) as { doc?: Partial<TDoc> | null } | undefined;
+  const listName = listTitle ?? doctype;
+  const navigate = (href: string) => router?.navigate(href);
+
+  const orderKey = JSON.stringify(orderBy ?? null);
+  const readOptions = useMemo(
+    () => ({ fields, limit, orderBy: JSON.parse(orderKey) }),
+    [fields, limit, orderKey],
+  );
+  const { rows: readRows } = useFrappeRows<TDoc>(connection, doctype, readOptions);
+  const listRows = useMemo(
+    () => orderRows(readRows as never[], JSON.parse(orderKey)) as Partial<TDoc>[],
+    [readRows, orderKey],
+  );
+
+  if (!config?.baseURL && !config?.fixtures) return <FrappeNotConfigured doctype={doctype} page />;
+
+  const backButton = (
+    <ScreenToolbar
+      leading={
+        <Button
+          outlined
+          minHeight={knobProps.sizeToken}
+          onPress={() => navigate(route)}
+          icon={<ArrowLeftIcon size={16} />}
+          testID={`${slug}-detail-back`}
+        >
+          {t("Back")}
+        </Button>
+      }
+    />
+  );
+
+  return (
+    <FrappeForm<TDoc>
+      doctype={doctype}
+      name={name}
+      initialDoc={initialDoc ?? loaded?.doc ?? undefined}
+      connections={connections}
+      showToolbar={false}
+      showSidebar={false}
+      showTimeline={false}
+      loadingFallback={
+        <Screen>
+          <YStack gap="$2">
+            <RecordBreadcrumbBone />
+            {backButton}
+          </YStack>
+          <RecordSkeleton testID={`${slug}-detail-skeleton`} />
+        </Screen>
+      }
+      notFoundFallback={
+        <Screen scroll={false}>
+          {backButton}
+          <EmptyState
+            title={t("{{doctype}} not found", { doctype })}
+            description={t("No {{doctype}} is named {{name}}.", { doctype, name })}
+            action={
+              <Button theme="accent" onPress={() => navigate(route)}>
+                {t("Back to {{title}}", { title: listName })}
+              </Button>
+            }
+          />
+        </Screen>
+      }
+      errorFallback={
+        <Screen scroll={false}>
+          {backButton}
+          <EmptyState
+            intent="error"
+            title={t("Couldn't load this {{doctype}}", { doctype })}
+            description={t("Check the connection and try again.")}
+          />
+        </Screen>
+      }
+    >
+      {({ doc, connections: linked, meta }) => (
+        <RecordWithRights
+          doc={doc}
+          meta={meta}
+          page={{
+            linked: linked as Record<string, Row[]>,
+            doctype,
+            route,
+            listName,
+            listRows,
+            look,
+            titleField: titleField ?? meta?.title_field,
+            facet,
+            metrics,
+            summary,
+            tabs,
+            favorites,
+            actions,
+            history,
+            slug,
+            baseURL: config?.baseURL,
+            navigate,
+          }}
+        />
+      )}
+    </FrappeForm>
+  );
+}
+
+function RecordWithRights<TDoc extends { name: string; doctype: string }>({
+  doc,
+  meta,
+  page,
+}: {
+  doc: Partial<TDoc>;
+  meta: Parameters<typeof useDocRights>[1];
+  page: Omit<RecordPageProps<TDoc>, "doc" | "canEdit">;
+}) {
+  const connection = useFrappeConnection();
+  const owner = (doc as Row).owner;
+  const { rights } = useDocRights(connection, meta, {
+    owner: typeof owner === "string" ? owner : undefined,
+  });
+  return <RecordPage<TDoc> {...page} doc={doc} canEdit={Boolean(rights.write)} />;
+}

package/src/FrappeReportBuilder.tsx

@@ -331,12 +331,11 @@ export function FrappeReportBuilder({
         {...knobProps.panelPadding}
         alignItems="center"
         justifyContent="center"
+        gap="$2"
         {...stackProps}
       >
         <Spinner size="large" />
-        <Text color="$color10" marginTop="$2">
-          {t("Loading {{doctype}} schema...", { doctype })}
-        </Text>
+        <Text color="$color10">{t("Loading {{doctype}} schema...", { doctype })}</Text>
       </YStack>
     );
   }
@@ -354,9 +353,9 @@ export function FrappeReportBuilder({
 
   if (isLoading) {
     return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...stackProps}>
+      <YStack {...knobProps.panelPadding} alignItems="center" gap="$1" {...stackProps}>
         <Spinner size="small" />
-        <Text color="$color10" fontSize="$2" marginTop="$1">
+        <Text color="$color10" fontSize="$2">
           {t("Loading data...")}
         </Text>
       </YStack>

package/src/FrappeReportView.tsx

@@ -349,7 +349,7 @@ export interface FrappeReportConnection {
 const callCache = new Map<string, CallModule>();
 
 function getCall(connection: FrappeReportConnection): CallModule {
-  const key = `${connection.baseURL}:${connection.auth?.token ?? ""}:${connection.auth?.type ?? ""}`;
+  const key = `${connection.baseURL}:${connection.auth?.useToken ? "t" : ""}:${connection.auth?.token ?? ""}:${connection.auth?.type ?? ""}`;
   let call = callCache.get(key);
   if (!call) {
     const authConfig: AuthConfig | undefined = connection.auth

package/src/FrappeTreeView.tsx

@@ -398,7 +398,7 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
             {valueField &&
               node.data &&
               (node.data as Record<string, unknown>)[valueField] != null && (
-                <Text color={formCommonColors.muted} {...knobProps.label} marginInlineStart="$2">
+                <Text color={formCommonColors.muted} {...knobProps.label} paddingInlineStart="$2">
                   {String((node.data as Record<string, unknown>)[valueField])}
                 </Text>
               )}

package/src/clientCache.auth.spec.tsx

@@ -0,0 +1,94 @@
+// Each hook here caches its REST client per connection. Two connections to
+// one bench that differ only in useToken must not share a client, or the
+// first one built decides whether the other sends its token (MPO-399,
+// MPO-406). The bench answers a tokenless call as Guest.
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useFrappeReport } from "./FrappeReportView";
+import { useFrappeAggregate } from "./useFrappeAggregate";
+import { useFrappeFacets } from "./useFrappeFacets";
+
+const token = "token key:secret";
+let sent: (string | null)[] = [];
+
+function reply(url: URL): unknown {
+  const method = url.pathname.replace(/^\/api\/method\//, "");
+  if (method === "frappe.client.get_count") return { message: 3 };
+  if (method === "frappe.desk.reportview.get_sidebar_stats") return { message: { stats: {} } };
+  if (method === "frappe.desk.query_report.run") return { message: { columns: [], result: [] } };
+  return { message: [] };
+}
+
+beforeEach(() => {
+  sent = [];
+  vi.stubGlobal("fetch", async (input: string | URL | Request, init?: RequestInit) => {
+    sent.push(new Headers(init?.headers).get("Authorization"));
+    return new Response(JSON.stringify(reply(new URL(String(input)))), {
+      headers: { "content-type": "application/json" },
+    });
+  });
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+function connection(baseURL: string, useToken: boolean) {
+  return { baseURL, realtime: false, auth: { useToken, token: "key:secret", type: "token" } };
+}
+
+async function authorizationPerConnection(
+  mount: (useToken: boolean) => () => boolean,
+): Promise<{ off: (string | null)[]; on: (string | null)[] }> {
+  const offSettled = mount(false);
+  await waitFor(() => expect(offSettled()).toBe(true));
+  const off = sent.splice(0);
+  const onSettled = mount(true);
+  await waitFor(() => expect(onSettled()).toBe(true));
+  return { off, on: sent.splice(0) };
+}
+
+describe("cached REST clients never drop a connection's token", () => {
+  it("useFrappeAggregate", async () => {
+    const { off, on } = await authorizationPerConnection((useToken) => {
+      const { result } = renderHook(() =>
+        useFrappeAggregate(connection("http://aggregate-auth.test", useToken), {
+          doctype: "ToDo",
+        }),
+      );
+      return () => !result.current.isLoading;
+    });
+    expect(off).toEqual([null]);
+    expect(on).toEqual([token]);
+  });
+
+  it("useFrappeFacets", async () => {
+    const { off, on } = await authorizationPerConnection((useToken) => {
+      const { result } = renderHook(() =>
+        useFrappeFacets("ToDo", [], {
+          connection: connection("http://facets-auth.test", useToken),
+        }),
+      );
+      return () =>
+        !result.current.assigned.isLoading &&
+        !result.current.owner.isLoading &&
+        !result.current.tags.isLoading;
+    });
+    expect(off.length).toBeGreaterThan(0);
+    expect(new Set(off)).toEqual(new Set([null]));
+    expect(on.length).toBe(off.length);
+    expect(new Set(on)).toEqual(new Set([token]));
+  });
+
+  it("useFrappeReport (FrappeReportView)", async () => {
+    const { off, on } = await authorizationPerConnection((useToken) => {
+      const { result } = renderHook(() =>
+        useFrappeReport(connection("http://report-auth.test", useToken), {
+          reportName: "ToDo Summary",
+          debounceMs: 0,
+        }),
+      );
+      return () => !result.current.isLoading;
+    });
+    expect(off).toEqual([null]);
+    expect(on).toEqual([token]);
+  });
+});

package/src/desk/DeskFormSidebar.stories.tsx

@@ -3,6 +3,8 @@ import { YStack } from "tamagui";
 import { FrappeProvider } from "../FrappeProvider";
 import { DeskFormSidebar } from "./DeskFormSidebar";
 
+// hex-escape: generated image fixtures are data, not paint
+
 export default {
   title: "FrappeUI/Desk/DeskFormSidebar",
   component: DeskFormSidebar,