@multiplatform.one/frappe-ui 7.11.0 → 7.15.0

package/src/FrappeDashboard.tsx

@@ -1,8 +1,4 @@
-import {
-  useFrappeCollection,
-  useFrappeDoctypeEvents,
-  useLiveQuery,
-} from "@multiplatform.one/frappe";
+import { useFrappeDoctypeEvents } from "@multiplatform.one/frappe";
 import { Dashboard, type DashboardWidget } from "@multiplatform.one/components";
 import { Button, Spinner, formCommonColors } from "@multiplatform.one/forms";
 import { ArrowsClockwiseIcon } from "@phosphor-icons/react";
@@ -11,6 +7,7 @@ import { useTranslation } from "react-i18next";
 import { Text, XStack, YStack, type YStackProps, H3 } from "tamagui";
 import { formatTimeOfDay, useResolvedKnobs } from "@multiplatform.one/theme";
 import { useFrappeConfig } from "./FrappeProvider";
+import { useFrappeRows } from "./useFrappeRows";
 
 /**
  * Data source configuration for live data.
@@ -103,16 +100,15 @@ function LiveDashboardContent<TDoc extends { name: string; doctype: string }>({
   const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
 
-  const collection = useFrappeCollection<TDoc>(connectionConfig as any, dataSource.doctype, {
+  const {
+    rows: liveData,
+    isQueryLoading: isLiveLoading,
+    isError,
+  } = useFrappeRows<TDoc>(connectionConfig as any, dataSource.doctype, {
     fields: dataSource.fields,
     filters: dataSource.filters,
+    limit: null,
   });
-  const {
-    data: rawData,
-    isLoading: isLiveLoading,
-    isError,
-  } = useLiveQuery((q) => (collection ? q.from({ _list: collection }) : null), [collection]);
-  const liveData = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
 
   // Live staleness: a realtime change on the source doctype marks the view
   // stale until the collection reconciles (data identity changes) or a
@@ -240,10 +236,9 @@ function LiveDashboardContent<TDoc extends { name: string; doctype: string }>({
 /**
  * Thin Frappe wrapper around the generic Dashboard component.
  *
- * Fetches live data via `useFrappeCollection` / `useLiveQuery` if a
- * `dataSource` is configured, transforms it into widget data, and
- * passes everything to the generic `Dashboard` from
- * `@multiplatform.one/components`.
+ * Fetches live data via `useFrappeRows` if a `dataSource` is configured,
+ * transforms it into widget data, and passes everything to the generic
+ * `Dashboard` from `@multiplatform.one/components`.
  */
 export function FrappeDashboard<TDoc extends { name: string; doctype: string }>({
   baseURL,

package/src/FrappeForm.connections.spec.tsx

@@ -0,0 +1,280 @@
+// FrappeForm renders a doctype's connections (MPO-331): the doctypes that
+// link back to the record through a Link field, read from meta.links or
+// declared. A Pokemon shows its type, ability and move rows, which live in
+// three standalone junction doctypes, not child tables. The same form hosts
+// a detail page: render-prop mode hands those rows to `children`, and a
+// server-rendered document stands in until the live read answers.
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { renderWithProviders, TestProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { renderToString } from "react-dom/server";
+import { initReactI18next } from "react-i18next";
+import { Text } from "tamagui";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  rosterFixtureData,
+  rosterPokemonMeta,
+  type RosterPokemon,
+} from "../tests/fixtures/pokemonRoster";
+import type { FrappeConnection } from "./frappeConnections";
+import { FrappeForm, type FrappeConnectionRows, type FrappeFormProps } from "./FrappeForm";
+import { FrappeProvider } from "./FrappeProvider";
+
+const host = "https://form-connections.spec.test";
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const pokemonConnections: FrappeConnection[] = [
+  { doctype: "Pokemon Poke Type", fieldname: "pokemon", fields: ["poke_type", "slot"] },
+  { doctype: "Pokemon Poke Ability", fieldname: "pokemon", fields: ["poke_ability", "is_hidden"] },
+  {
+    doctype: "Pokemon Poke Move",
+    fieldname: "pokemon",
+    fields: ["poke_move", "level_learned_at", "move_learn_method"],
+  },
+];
+
+function corpus(meta: Record<string, unknown> = rosterPokemonMeta) {
+  return new InMemoryFixtureProvider({
+    DocType: [{ name: "Pokemon", ...meta, doctype: "DocType" }],
+    ...rosterFixtureData(),
+  });
+}
+
+function renderForm(
+  props: Partial<FrappeFormProps<RosterPokemon>>,
+  fixtures: InMemoryFixtureProvider = corpus(),
+) {
+  return renderWithProviders(
+    <FrappeProvider baseURL={host} fixtures={fixtures}>
+      <FrappeForm<RosterPokemon>
+        doctype="Pokemon"
+        showSidebar={false}
+        showTimeline={false}
+        {...props}
+      />
+    </FrappeProvider>,
+  );
+}
+
+function RowsProbe({ connections }: { connections: FrappeConnectionRows }) {
+  return (
+    <>
+      {Object.entries(connections).map(([doctype, rows]) => (
+        <Text key={doctype} testID={`rows-${doctype}`}>
+          {rows
+            .map((row) => String(row.poke_type ?? row.poke_ability ?? row.poke_move))
+            .sort()
+            .join(",")}
+        </Text>
+      ))}
+    </>
+  );
+}
+
+describe("FrappeForm connections, schema mode", () => {
+  it("shows the record's type, ability and move rows from meta.links on a Connections tab", async () => {
+    renderForm({ name: "bulbasaur" });
+    await waitFor(() => expect(screen.getByText("Connections")).toBeTruthy());
+    fireEvent.click(screen.getByText("Connections"));
+    await waitFor(() => expect(screen.getByText("grass")).toBeTruthy());
+    expect(screen.getByText("poison")).toBeTruthy();
+    expect(screen.getByText("overgrow")).toBeTruthy();
+    expect(screen.getByText("chlorophyll")).toBeTruthy();
+    expect(screen.getByText("tackle")).toBeTruthy();
+    expect(screen.getByText("vine-whip")).toBeTruthy();
+    expect(screen.queryByText("thunderbolt")).toBeNull();
+  });
+
+  it("uses declared connections where meta carries no links", async () => {
+    const { links: _links, ...metaWithoutLinks } = rosterPokemonMeta;
+    renderForm(
+      { name: "pikachu", connections: pokemonConnections.slice(2) },
+      corpus(metaWithoutLinks),
+    );
+    await waitFor(() => expect(screen.getByText("Connections")).toBeTruthy());
+    fireEvent.click(screen.getByText("Connections"));
+    await waitFor(() => expect(screen.getByText("thunderbolt")).toBeTruthy());
+    expect(screen.getByText("quick-attack")).toBeTruthy();
+    expect(screen.queryByText("static")).toBeNull();
+  });
+
+  it("names each connection with its row count", async () => {
+    renderForm({ name: "pikachu", connections: pokemonConnections });
+    await waitFor(() => expect(screen.getByText("Connections")).toBeTruthy());
+    fireEvent.click(screen.getByText("Connections"));
+    await waitFor(() => expect(screen.getByText("Pokemon Poke Move (3)")).toBeTruthy());
+    expect(screen.getByText("Pokemon Poke Type (1)")).toBeTruthy();
+  });
+
+  it("an unlinked record says so instead of showing an empty table", async () => {
+    renderForm({ name: "eevee", connections: pokemonConnections.slice(1, 2) });
+    await waitFor(() => expect(screen.getByText("Connections")).toBeTruthy());
+    fireEvent.click(screen.getByText("Connections"));
+    await waitFor(() => expect(screen.getByText("No Pokemon Poke Ability rows")).toBeTruthy());
+  });
+
+  it("a new record has no connections yet", async () => {
+    renderForm({});
+    await waitFor(() => expect(screen.getByText("Save")).toBeTruthy());
+    expect(screen.queryByText("Connections")).toBeNull();
+  });
+
+  it("showConnections={false} leaves the tab out", async () => {
+    renderForm({ name: "bulbasaur", showConnections: false });
+    await waitFor(() => expect(screen.getByText("Save")).toBeTruthy());
+    expect(screen.queryByText("Connections")).toBeNull();
+  });
+});
+
+describe("FrappeForm connections, render-prop mode", () => {
+  it("hands children the record's linked rows per doctype", async () => {
+    renderForm({
+      name: "bulbasaur",
+      connections: pokemonConnections,
+      showToolbar: false,
+      children: ({ connections }) => <RowsProbe connections={connections} />,
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("rows-Pokemon Poke Type").textContent).toBe("grass,poison"),
+    );
+    expect(screen.getByTestId("rows-Pokemon Poke Ability").textContent).toBe(
+      "chlorophyll,overgrow",
+    );
+    expect(screen.getByTestId("rows-Pokemon Poke Move").textContent).toBe("tackle,vine-whip");
+  });
+
+  it("reads connections from meta.links when none are declared", async () => {
+    renderForm({
+      name: "pikachu",
+      showToolbar: false,
+      children: ({ connections }) => <RowsProbe connections={connections} />,
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("rows-Pokemon Poke Type").textContent).toBe("electric"),
+    );
+  });
+});
+
+describe("FrappeForm hosting a detail page", () => {
+  const seed = {
+    name: "bulbasaur",
+    doctype: "Pokemon",
+    pokemon_name: "bulbasaur (server)",
+  } as Partial<RosterPokemon>;
+
+  const detail = ({ doc }: { doc: Partial<RosterPokemon> }) => (
+    <Text testID="detail-name">{doc.pokemon_name}</Text>
+  );
+
+  it("renders the server-rendered document on the server", () => {
+    const html = renderToString(
+      <TestProviders>
+        <FrappeProvider baseURL={host} fixtures={corpus()}>
+          <FrappeForm<RosterPokemon>
+            doctype="Pokemon"
+            name="bulbasaur"
+            initialDoc={seed}
+            showToolbar={false}
+            showSidebar={false}
+            showTimeline={false}
+            notFoundFallback={<Text>missing</Text>}
+          >
+            {detail}
+          </FrappeForm>
+        </FrappeProvider>
+      </TestProviders>,
+    );
+    expect(html).toContain("bulbasaur (server)");
+    expect(html).not.toContain("missing");
+    expect(html).not.toContain("frappe-form-skeleton");
+  });
+
+  it("shows the server document until the live read lands, then the live one", async () => {
+    const fixtures = corpus();
+    let release: () => void = () => undefined;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const getDoc = fixtures.getDoc.bind(fixtures);
+    vi.spyOn(fixtures, "getDoc").mockImplementation(async (...args) => {
+      await gate;
+      return getDoc(...args);
+    });
+    renderForm(
+      { name: "bulbasaur", initialDoc: seed, showToolbar: false, children: detail },
+      fixtures,
+    );
+    expect(screen.getByTestId("detail-name").textContent).toBe("bulbasaur (server)");
+    release();
+    await waitFor(() => expect(screen.getByTestId("detail-name").textContent).toBe("bulbasaur"));
+  });
+
+  it("ignores a server document for another name", async () => {
+    renderForm({
+      name: "pikachu",
+      initialDoc: seed,
+      showToolbar: false,
+      children: detail,
+    });
+    await waitFor(() => expect(screen.getByTestId("detail-name").textContent).toBe("pikachu"));
+  });
+
+  it("takes the page's own loading, not-found and error states", async () => {
+    const fixtures = corpus();
+    let release: () => void = () => undefined;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const getDoc = fixtures.getDoc.bind(fixtures);
+    vi.spyOn(fixtures, "getDoc").mockImplementation(async (...args) => {
+      await gate;
+      return getDoc(...args);
+    });
+    renderForm(
+      {
+        name: "missingno",
+        showToolbar: false,
+        children: detail,
+        loadingFallback: <Text>page skeleton</Text>,
+        notFoundFallback: <Text>no such pokemon</Text>,
+      },
+      fixtures,
+    );
+    expect(screen.getByText("page skeleton")).toBeTruthy();
+    release();
+    await waitFor(() => expect(screen.getByText("no such pokemon")).toBeTruthy());
+  });
+
+  it("a failed read is the error state, not not-found", async () => {
+    const fixtures = corpus();
+    vi.spyOn(fixtures, "getDoc").mockImplementation(async (doctype, ...rest) => {
+      if (doctype === "Pokemon") throw Object.assign(new Error("PermissionError"), { status: 403 });
+      return InMemoryFixtureProvider.prototype.getDoc.call(fixtures, doctype, ...rest);
+    });
+    renderForm(
+      {
+        name: "bulbasaur",
+        showToolbar: false,
+        children: detail,
+        notFoundFallback: <Text>no such pokemon</Text>,
+        errorFallback: <Text>could not load</Text>,
+      },
+      fixtures,
+    );
+    await waitFor(() => expect(screen.getByText("could not load")).toBeTruthy());
+    expect(screen.queryByText("no such pokemon")).toBeNull();
+  });
+});

package/src/FrappeForm.connections.stories.tsx

@@ -0,0 +1,93 @@
+import { Chip } from "@multiplatform.one/components";
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Text, XStack, YStack } from "tamagui";
+import {
+  rosterFixtureData,
+  rosterPokemonMeta,
+  type RosterPokemon,
+} from "../tests/fixtures/pokemonRoster";
+import type { FrappeConnection } from "./frappeConnections";
+import { FrappeForm, type FrappeConnectionRows } from "./FrappeForm";
+import { FrappeProvider } from "./FrappeProvider";
+
+export default {
+  title: "FrappeUI/FrappeForm Connections",
+  component: FrappeForm,
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "A record's connections: the doctypes linking back to it through a Link field (meta.links, or declared with `connections`). Schema mode lists them on a Connections tab; render-prop mode hands the rows to `children`, which is how a detail page renders them its own way. Pokemon's types, abilities and moves are standalone junction doctypes on the pokemon fixtures.",
+      },
+    },
+  },
+};
+
+const host = "https://form-connections.mock.test";
+
+const fixtures = () =>
+  new InMemoryFixtureProvider({
+    DocType: [{ ...rosterPokemonMeta, doctype: "DocType" }],
+    ...rosterFixtureData(),
+  });
+
+const pokemonConnections: FrappeConnection[] = [
+  { doctype: "Pokemon Poke Type", fieldname: "pokemon", fields: ["poke_type", "slot"] },
+  { doctype: "Pokemon Poke Ability", fieldname: "pokemon", fields: ["poke_ability", "is_hidden"] },
+  {
+    doctype: "Pokemon Poke Move",
+    fieldname: "pokemon",
+    fields: ["poke_move", "level_learned_at", "move_learn_method"],
+  },
+];
+
+export const ConnectionsTab = () => (
+  <FrappeProvider baseURL={host} fixtures={fixtures()}>
+    <FrappeForm<RosterPokemon> doctype="Pokemon" name="bulbasaur" showSidebar={false} />
+  </FrappeProvider>
+);
+
+function PokemonDetail({
+  doc,
+  connections,
+}: {
+  doc: Partial<RosterPokemon>;
+  connections: FrappeConnectionRows;
+}) {
+  const { knobProps } = useResolvedKnobs();
+  const types = connections["Pokemon Poke Type"] ?? [];
+  const moves = connections["Pokemon Poke Move"] ?? [];
+  return (
+    <YStack {...knobProps.gap}>
+      <Text {...knobProps.body} fontWeight="700" textTransform="capitalize">
+        {doc.pokemon_name}
+      </Text>
+      <XStack {...knobProps.gap}>
+        {types.map((row) => (
+          <Chip key={String(row.name)}>{String(row.poke_type)}</Chip>
+        ))}
+      </XStack>
+      <Text {...knobProps.label} color="$color10">
+        {moves.map((row) => String(row.poke_move)).join(" · ")}
+      </Text>
+    </YStack>
+  );
+}
+
+export const DetailPage = () => (
+  <FrappeProvider baseURL={host} fixtures={fixtures()}>
+    <FrappeForm<RosterPokemon>
+      doctype="Pokemon"
+      name="pikachu"
+      connections={pokemonConnections}
+      showToolbar={false}
+      showSidebar={false}
+      showTimeline={false}
+    >
+      {({ doc, connections }) => <PokemonDetail doc={doc} connections={connections} />}
+    </FrappeForm>
+  </FrappeProvider>
+);