@multiplatform.one/frappe-ui 7.10.0 → 7.15.0

package/src/frappeConnections.ts

@@ -0,0 +1,50 @@
+import type { DocTypeMeta } from "@multiplatform.one/frappe";
+
+/**
+ * A doctype whose rows point at one record of another doctype through a Link
+ * field: the desk's Connections, one DocType Link row (`link_doctype` +
+ * `link_fieldname`). Pokemon's types, abilities and moves are three of them,
+ * each a standalone doctype with a `pokemon` Link, not a child table.
+ */
+export interface FrappeConnection {
+  /** The linked doctype (DocType Link `link_doctype`). */
+  doctype: string;
+  /** Its Link field naming the record (DocType Link `link_fieldname`). */
+  fieldname: string;
+  /** Columns to read from the linked rows; the link field is always read. */
+  fields?: readonly string[];
+  /** Section heading; defaults to the linked doctype. */
+  label?: string;
+  /** DocType Link `group`, for desk parity. */
+  group?: string;
+  /** Row ceiling per record; 0 (the default) reads every linked row. */
+  limit?: number;
+}
+
+/**
+ * `meta.links` as connections. Hidden rows and links that resolve through a
+ * child table (`is_child_table`) are left out: neither names the record by a
+ * Link field on the linked doctype itself.
+ */
+export function connectionsFromMeta(
+  meta: Pick<DocTypeMeta, "links"> | null | undefined,
+): FrappeConnection[] {
+  return (meta?.links ?? [])
+    .filter(
+      (link) => !link.hidden && !link.is_child_table && link.link_doctype && link.link_fieldname,
+    )
+    .map((link) => ({
+      doctype: link.link_doctype,
+      fieldname: link.link_fieldname,
+      ...(link.group ? { group: link.group } : {}),
+    }));
+}
+
+/**
+ * The fields a connection read asks for: `name`, the link field, then its
+ * own; every field (`*`) when it names none, as a meta.links row does.
+ */
+export function connectionFields(connection: FrappeConnection): string[] {
+  if (!connection.fields?.length) return ["*"];
+  return Array.from(new Set(["name", connection.fieldname, ...connection.fields]));
+}

package/src/frappeNavigation.tsx

@@ -0,0 +1,112 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+/**
+ * The host router as frappe-ui sees it. frappe-ui imports no router: the
+ * host app hands this to `FrappeProvider` once (`@multiplatform.one/core`
+ * does it from One's router), and a routed `FrappeListView` or `FrappeForm`
+ * (`route` prop) reads its record from the path and moves with it.
+ *
+ * Both members are hooks, called where the routed view renders, so they see
+ * that page's route. A host keeps the same navigation for the life of the
+ * tree.
+ */
+export interface FrappeNavigation {
+  /** The pathname of the route the caller renders in. */
+  usePathname(): string;
+  /** A function that pushes an href onto the history. */
+  useNavigate(): (href: string) => void;
+}
+
+/** A routed view's handle on the host router. */
+export interface FrappeRouter {
+  pathname: string;
+  navigate(href: string): void;
+}
+
+const FrappeNavigationContext = createContext<FrappeNavigation | undefined>(undefined);
+
+export function FrappeNavigationProvider({
+  navigation,
+  children,
+}: {
+  navigation: FrappeNavigation | undefined;
+  children: ReactNode;
+}) {
+  const inherited = useContext(FrappeNavigationContext);
+  return (
+    <FrappeNavigationContext.Provider value={navigation ?? inherited}>
+      {children}
+    </FrappeNavigationContext.Provider>
+  );
+}
+
+export function useFrappeNavigation(): FrappeNavigation | undefined {
+  return useContext(FrappeNavigationContext);
+}
+
+/** The host router for a routed view, or undefined when the host gave none. */
+export function useFrappeRouter(): FrappeRouter | undefined {
+  const navigation = useFrappeNavigation();
+  if (!navigation) return undefined;
+  // oxlint-disable-next-line rules-of-hooks -- one navigation per tree
+  const pathname = navigation.usePathname();
+  // oxlint-disable-next-line rules-of-hooks -- one navigation per tree
+  const navigate = navigation.useNavigate();
+  return { pathname, navigate };
+}
+
+/**
+ * What a path under a doctype's route names, desk style: the list
+ * (`/route`), a new record (`/route/new`), a record (`/route/<name>`) or its
+ * edit form (`/route/<name>/edit`).
+ */
+export type FrappeRouteTarget =
+  | { mode: "list" }
+  | { mode: "create" }
+  | { mode: "view"; name: string }
+  | { mode: "edit"; name: string };
+
+function trimPath(path: string): string {
+  const bare = path.split(/[?#]/)[0] ?? "";
+  return bare.length > 1 ? bare.replace(/\/+$/, "") : bare;
+}
+
+function decodeSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+export function frappeRouteTarget(route: string, pathname: string): FrappeRouteTarget | undefined {
+  const base = trimPath(route);
+  const path = trimPath(pathname);
+  if (path === base) return { mode: "list" };
+  if (!path.startsWith(`${base}/`)) return undefined;
+  const segments = path.slice(base.length + 1).split("/");
+  const [first, second] = segments;
+  if (!first) return undefined;
+  if (segments.length === 1) {
+    return first === "new" ? { mode: "create" } : { mode: "view", name: decodeSegment(first) };
+  }
+  if (segments.length === 2 && second === "edit") {
+    return { mode: "edit", name: decodeSegment(first) };
+  }
+  return undefined;
+}
+
+/** The href of a doctype route's list, new record, record or record edit form. */
+export function frappeRouteHref(route: string, target: FrappeRouteTarget): string {
+  const base = trimPath(route);
+  switch (target.mode) {
+    case "list":
+      return base;
+    case "create":
+      return `${base}/new`;
+    case "view":
+      return `${base}/${encodeURIComponent(target.name)}`;
+    case "edit":
+      return `${base}/${encodeURIComponent(target.name)}/edit`;
+  }
+}

package/src/frappeRoutes.spec.tsx

@@ -0,0 +1,335 @@
+// A doctype's list, record, edit and new pages from a declaration alone
+// (MPO-333): `<FrappeListView doctype route>` and `<FrappeForm doctype
+// route>` read the record from the host router's path, draw the page, and
+// move between the pages on row press, Add, Edit, Save, Cancel and Delete.
+// The bench below is a stock one: getdoctype for meta, /api/resource for
+// reads, the live app's create_doc / update_doc / delete_doc for writes, and
+// a hash name the server picks on create. Poke Move is the doctype.
+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 { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { FrappeForm } from "./FrappeForm";
+import { FrappeListView } from "./FrappeListView";
+import { frappeRouteHref, frappeRouteTarget, type FrappeNavigation } from "./frappeNavigation";
+import { FrappeProvider } from "./FrappeProvider";
+
+const doctype = "Poke Move";
+const route = "/moves";
+
+const pokeMoveMeta = {
+  name: doctype,
+  doctype: "DocType",
+  title_field: "move_name",
+  fields: [
+    { fieldname: "move_name", fieldtype: "Data", label: "Move Name", reqd: 1 },
+    { fieldname: "power", fieldtype: "Int", label: "Power" },
+    { fieldname: "pp", fieldtype: "Int", label: "PP" },
+    {
+      fieldname: "damage_class",
+      fieldtype: "Select",
+      label: "Damage Class",
+      options: "\nphysical\nspecial\nstatus",
+    },
+  ],
+  permissions: [
+    { role: "System Manager", read: 1, write: 1, create: 1, delete: 1 },
+    { role: "Guest", read: 1 },
+  ],
+};
+
+interface Move {
+  name: string;
+  doctype: string;
+  move_name?: string;
+  power?: number;
+  pp?: number;
+  damage_class?: string;
+}
+
+interface Write {
+  method: string;
+  body: Record<string, unknown>;
+}
+
+let run = 0;
+let bench = "";
+let moves = new Map<string, Move>();
+let writes: Write[] = [];
+let guest = false;
+let confirmDelete = vi.fn(() => true);
+
+function json(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function matchesNameFilter(row: Move, filters: string | null): boolean {
+  if (!filters) return true;
+  const parsed = JSON.parse(filters) as unknown;
+  const clauses = Array.isArray(parsed)
+    ? (parsed as Array<[string, string, unknown]>)
+    : Object.entries(parsed as Record<string, unknown>).map(([key, value]) => [key, "=", value]);
+  return clauses.every(([field, operator, value]) =>
+    field === "name" && operator === "=" ? row.name === value : true,
+  );
+}
+
+function stubBench() {
+  vi.stubGlobal("fetch", async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(String(input instanceof Request ? input.url : input));
+    const method = url.pathname.replace(/^\/api\/method\//, "");
+    if (method === "frappe.desk.form.load.getdoctype") {
+      if (guest) return json({ exc_type: "PermissionError" }, 403);
+      return json({ docs: [pokeMoveMeta] });
+    }
+    const resource = `/api/resource/${encodeURIComponent(doctype)}`;
+    if (url.pathname === resource) {
+      const rows = [...moves.values()].filter((row) =>
+        matchesNameFilter(row, url.searchParams.get("filters")),
+      );
+      return json({ data: rows });
+    }
+    if (url.pathname.startsWith(`${resource}/`)) {
+      const row = moves.get(decodeURIComponent(url.pathname.slice(resource.length + 1)));
+      return row ? json({ data: row }) : json({ exc_type: "DoesNotExistError" }, 404);
+    }
+    if (/^live\.live\.api\.(create|update|delete)_doc$/.test(method)) {
+      const body = JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+      writes.push({ method, body });
+      if (method === "live.live.api.create_doc") {
+        const created = {
+          ...(body as unknown as Move),
+          name: `move-${moves.size + 1}-hash`,
+          doctype,
+        };
+        moves.set(created.name, created);
+        return json({ message: created });
+      }
+      if (method === "live.live.api.update_doc") {
+        const name = String(body.name);
+        const updated = { ...moves.get(name), ...(body.data as object) } as Move;
+        moves.set(name, updated);
+        return json({ message: updated });
+      }
+      if (method === "live.live.api.delete_doc") {
+        moves.delete(String(body.name));
+        return json({ message: "ok" });
+      }
+    }
+    return json({ data: [], message: [] });
+  });
+}
+
+function stubNavigation(pathname: string) {
+  const pushed: string[] = [];
+  const navigation: FrappeNavigation = {
+    usePathname: () => pathname,
+    useNavigate: () => (href) => pushed.push(href),
+  };
+  return { navigation, pushed };
+}
+
+function renderAt(pathname: string, page: "list" | "form") {
+  const { navigation, pushed } = stubNavigation(pathname);
+  const view = renderWithProviders(
+    <FrappeProvider baseURL={bench} realtime={false} navigation={navigation}>
+      {page === "list" ? (
+        <FrappeListView<Move> doctype={doctype} route={route} />
+      ) : (
+        <FrappeForm<Move> doctype={doctype} route={route} />
+      )}
+    </FrappeProvider>,
+  );
+  return { ...view, pushed };
+}
+
+function button(container: HTMLElement, label: string): HTMLElement {
+  const found = Array.from(container.querySelectorAll('[role="button"], button')).find(
+    (node) => node.textContent?.trim() === label || node.getAttribute("aria-label") === label,
+  );
+  if (!found) throw new Error(`no ${label} button`);
+  return found as HTMLElement;
+}
+
+function input(container: HTMLElement, label: string): HTMLInputElement {
+  const field = screen.getByLabelText(label, { exact: false });
+  if (field instanceof HTMLInputElement) return field;
+  const nested = field.querySelector("input") ?? container.querySelector(`input[name="${label}"]`);
+  if (!nested) throw new Error(`no ${label} input`);
+  return nested as HTMLInputElement;
+}
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+beforeEach(() => {
+  run += 1;
+  bench = `http://routes-${run}.spec.test`;
+  guest = false;
+  writes = [];
+  moves = new Map([
+    ["a1b2c3", { name: "a1b2c3", doctype, move_name: "tackle", power: 40, pp: 35 }],
+    ["d4e5f6", { name: "d4e5f6", doctype, move_name: "vine-whip", power: 45, pp: 25 }],
+  ]);
+  stubBench();
+  confirmDelete = vi.fn(() => true);
+  vi.stubGlobal("confirm", confirmDelete);
+  window.confirm = confirmDelete;
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("frappeRouteTarget", () => {
+  it("reads the list, a new record, a record and its edit form off the path", () => {
+    expect(frappeRouteTarget(route, "/moves")).toEqual({ mode: "list" });
+    expect(frappeRouteTarget(route, "/moves/")).toEqual({ mode: "list" });
+    expect(frappeRouteTarget(route, "/moves/new")).toEqual({ mode: "create" });
+    expect(frappeRouteTarget(route, "/moves/a1b2c3")).toEqual({ mode: "view", name: "a1b2c3" });
+    expect(frappeRouteTarget(route, "/moves/Hyper%20Beam/edit")).toEqual({
+      mode: "edit",
+      name: "Hyper Beam",
+    });
+    expect(frappeRouteTarget(route, "/pokemon/bulbasaur")).toBeUndefined();
+    expect(frappeRouteTarget(route, "/moves/a/b/c")).toBeUndefined();
+  });
+
+  it("writes the href for each page, the record name escaped", () => {
+    expect(frappeRouteHref(route, { mode: "list" })).toBe("/moves");
+    expect(frappeRouteHref(route, { mode: "create" })).toBe("/moves/new");
+    expect(frappeRouteHref(route, { mode: "view", name: "Hyper Beam" })).toBe(
+      "/moves/Hyper%20Beam",
+    );
+    expect(frappeRouteHref(`${route}/`, { mode: "edit", name: "a1b2c3" })).toBe(
+      "/moves/a1b2c3/edit",
+    );
+  });
+});
+
+describe("FrappeListView with a route", () => {
+  it("is the doctype's list page: its rows, a row opens the record, Add opens a new one", async () => {
+    const { container, pushed } = renderAt("/moves", "list");
+    await waitFor(() => expect(screen.getByText("tackle")).toBeTruthy());
+    expect(screen.getByText("vine-whip")).toBeTruthy();
+    expect(screen.getByRole("heading", { name: doctype })).toBeTruthy();
+
+    fireEvent.click(screen.getByText("tackle"));
+    expect(pushed).toEqual(["/moves/a1b2c3"]);
+
+    await waitFor(() => expect(button(container, `Add ${doctype}`)).toBeTruthy());
+    fireEvent.click(button(container, `Add ${doctype}`));
+    expect(pushed).toEqual(["/moves/a1b2c3", "/moves/new"]);
+  });
+
+  it("offers no Add to a reader who cannot load the doctype's meta", async () => {
+    guest = true;
+    const { container } = renderAt("/moves", "list");
+    await waitFor(() => expect(screen.getByText("tackle")).toBeTruthy());
+    expect(() => button(container, `Add ${doctype}`)).toThrow();
+  });
+});
+
+describe("FrappeForm with a route", () => {
+  it("shows the record read-only on its page, with Edit and Delete", async () => {
+    const { container, pushed } = renderAt("/moves/a1b2c3", "form");
+    await waitFor(() => expect(input(container, "Move Name").value).toBe("tackle"));
+    expect(screen.getByRole("heading", { name: "tackle" })).toBeTruthy();
+    expect(input(container, "Move Name").disabled || input(container, "Move Name").readOnly).toBe(
+      true,
+    );
+    expect(() => button(container, "Save")).toThrow();
+
+    fireEvent.click(button(container, "Edit"));
+    expect(pushed).toEqual(["/moves/a1b2c3/edit"]);
+
+    fireEvent.click(button(container, `Back to ${doctype} list`));
+    expect(pushed).toEqual(["/moves/a1b2c3/edit", "/moves"]);
+  });
+
+  it("edits the record through update_doc and returns to it", async () => {
+    const { container, pushed } = renderAt("/moves/a1b2c3/edit", "form");
+    await waitFor(() => expect(input(container, "Move Name").value).toBe("tackle"));
+    fireEvent.change(input(container, "Power"), { target: { value: "50" } });
+    fireEvent.click(button(container, "Save"));
+
+    await waitFor(() => expect(pushed).toEqual(["/moves/a1b2c3"]));
+    expect(writes).toEqual([
+      {
+        method: "live.live.api.update_doc",
+        body: { doctype, name: "a1b2c3", data: { power: 50 } },
+      },
+    ]);
+    expect(moves.get("a1b2c3")?.power).toBe(50);
+  });
+
+  it("cancels an edit back to the record", async () => {
+    const { container, pushed } = renderAt("/moves/a1b2c3/edit", "form");
+    await waitFor(() => expect(input(container, "Move Name").value).toBe("tackle"));
+    fireEvent.click(button(container, "Cancel"));
+    expect(pushed).toEqual(["/moves/a1b2c3"]);
+    expect(writes).toEqual([]);
+  });
+
+  it("creates through create_doc and opens the record under the name the server gave it", async () => {
+    const { container, pushed } = renderAt("/moves/new", "form");
+    await waitFor(() => expect(input(container, "Move Name")).toBeTruthy());
+    expect(screen.getByRole("heading", { name: `New ${doctype}` })).toBeTruthy();
+    fireEvent.change(input(container, "Move Name"), { target: { value: "hyper-beam" } });
+    fireEvent.change(input(container, "Power"), { target: { value: "150" } });
+    fireEvent.click(button(container, "Save"));
+
+    await waitFor(() => expect(pushed).toEqual(["/moves/move-3-hash"]));
+    expect(writes).toHaveLength(1);
+    expect(writes[0]?.method).toBe("live.live.api.create_doc");
+    expect(writes[0]?.body).toMatchObject({ doctype, move_name: "hyper-beam", power: 150 });
+    expect(moves.get("move-3-hash")?.move_name).toBe("hyper-beam");
+  });
+
+  it("deletes through delete_doc and returns to the list", async () => {
+    const { container, pushed } = renderAt("/moves/d4e5f6", "form");
+    await waitFor(() => expect(input(container, "Move Name").value).toBe("vine-whip"));
+    fireEvent.click(button(container, "Delete"));
+
+    await waitFor(() => expect(pushed).toEqual(["/moves"]));
+    expect(confirmDelete).toHaveBeenCalledTimes(1);
+    expect(writes).toEqual([
+      { method: "live.live.api.delete_doc", body: { doctype, name: "d4e5f6" } },
+    ]);
+    expect(moves.has("d4e5f6")).toBe(false);
+  });
+
+  it("shows a reader without meta the record's own fields, read-only and with no actions", async () => {
+    guest = true;
+    const { container } = renderAt("/moves/a1b2c3", "form");
+    await waitFor(() => expect(input(container, "Move Name").value).toBe("tackle"));
+    expect(input(container, "Power").value).toBe("40");
+    expect(screen.queryByText(`Failed to load ${doctype} form`)).toBeNull();
+    expect(() => button(container, "Edit")).toThrow();
+    expect(() => button(container, "Delete")).toThrow();
+  });
+
+  it("draws no field for the collection's own $ keys on a reader's record", async () => {
+    guest = true;
+    const { container } = renderAt("/moves/a1b2c3", "form");
+    await waitFor(() => expect(input(container, "Move Name").value).toBe("tackle"));
+    const labels = Array.from(container.querySelectorAll("label"), (node) =>
+      node.textContent?.trim(),
+    );
+    expect(labels.filter((label) => label?.startsWith("$"))).toEqual([]);
+    for (const key of ["$origin", "$key", "$collectionId"]) {
+      expect(screen.queryByText(key)).toBeNull();
+    }
+  });
+});

package/src/index.ts

@@ -24,6 +24,16 @@ export {
   type FrappeConfig,
   type FrappeProviderProps,
 } from "./FrappeProvider";
+export {
+  FrappeNavigationProvider,
+  frappeRouteHref,
+  frappeRouteTarget,
+  useFrappeNavigation,
+  useFrappeRouter,
+  type FrappeNavigation,
+  type FrappeRouter,
+  type FrappeRouteTarget,
+} from "./frappeNavigation";
 export {
   FrappeReconnectIndicator,
   type FrappeReconnectIndicatorProps,
@@ -43,7 +53,13 @@ export {
 
 export { FrappeTable, filterValueToFrappeTuple, type FrappeTableProps } from "./FrappeTable";
 export { docFieldsToFilterFields } from "./filterFields";
-export { FrappeForm, type FrappeFormProps } from "./FrappeForm";
+export { FrappeForm, type FrappeConnectionRows, type FrappeFormProps } from "./FrappeForm";
+export {
+  FrappeFormConnectionSection,
+  FrappeFormConnections,
+  type FrappeFormConnectionSectionProps,
+  type FrappeFormConnectionsProps,
+} from "./FrappeFormConnections";
 export {
   FormSidebar,
   type FormSidebarProps,
@@ -53,6 +69,13 @@ export {
 } from "./FormSidebar";
 export { FrappeList, type FrappeListProps } from "./FrappeList";
 export { FrappeListView, type FrappeListViewProps, type ListViewMode } from "./FrappeListView";
+export {
+  useConnectionFilters,
+  type ConnectionFiltersResult,
+  type FrappeDoctypeFilter,
+  type FrappeFieldFilter,
+  type FrappeFilters,
+} from "./useConnectionFilters";
 
 export {
   FrappeKanban,
@@ -206,6 +229,8 @@ export {
   getFieldComponent,
   initDefaultRegistry,
   childFieldsToColumns,
+  childFieldsToDetailColumns,
+  childCellHidden,
   fieldtypeToTableField,
 } from "./fieldRegistry";
 export { FieldOverridesProvider, useFieldResolver } from "./fieldOverrides";
@@ -437,6 +462,7 @@ export {
   setCreatePrefill,
   takeCreatePrefill,
   useFormEngine,
+  useSessionRoles,
 } from "./formEngine";
 export type {
   BuildTabsOptions,
@@ -451,3 +477,4 @@ export type {
   LevelPerm,
   PermLevelMatrix,
 } from "./formEngine";
+export { connectionFields, connectionsFromMeta, type FrappeConnection } from "./frappeConnections";

package/src/schemaForm/index.tsx

@@ -254,6 +254,7 @@ export function SchemaForm({
       multiple: field.multiple,
       commit: field.commit,
       control: field.control,
+      ...(field.type === "Table" ? { parentDoc: doc } : null),
     };
 
     // Check overrides