@multiplatform.one/frappe 7.11.0 → 7.16.0

package/src/doctype.ts

@@ -5,95 +5,160 @@
  * documents, and searching across DocTypes for navigation (Awesomebar).
  */
 
+import { getCookie } from "@multiplatform.one/platform";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { HttpClient } from "./core/http";
-import type { AuthConfig } from "./core/types";
+import { FrappeError, type AuthConfig } from "./core/types";
 import type { FrappeConnectionConfig } from "./pacer";
 
 // ---------------------------------------------------------------------------
 // Type Definitions
 // ---------------------------------------------------------------------------
 
-/** All Frappe field type strings */
-export type FrappeFieldType =
-  | "Autocomplete"
-  | "Attach"
-  | "Attach Image"
-  | "Barcode"
-  | "Button"
-  | "Check"
-  | "Code"
-  | "Color"
-  | "Column Break"
-  | "Currency"
-  | "Data"
-  | "Date"
-  | "Datetime"
-  | "Duration"
-  | "Dynamic Link"
-  | "Float"
-  | "Geolocation"
-  | "HTML"
-  | "HTML Editor"
-  | "Heading"
-  | "Icon"
-  | "Image"
-  | "Int"
-  | "JSON"
-  | "Link"
-  | "Long Text"
-  | "Markdown Editor"
-  | "Password"
-  | "Percent"
-  | "Phone"
-  | "Rating"
-  | "Read Only"
-  | "Section Break"
-  | "Select"
-  | "Signature"
-  | "Small Text"
-  | "Tab Break"
-  | "Table"
-  | "Table MultiSelect"
-  | "Text"
-  | "Text Editor"
-  | "Time";
-
-/** Normalized DocType field descriptor */
+/**
+ * Every fieldtype a Frappe bench serves: the options of `DocField.fieldtype`.
+ */
+export const stockFieldTypes = [
+  "Autocomplete",
+  "Attach",
+  "Attach Image",
+  "Barcode",
+  "Button",
+  "Check",
+  "Code",
+  "Color",
+  "Column Break",
+  "Currency",
+  "Data",
+  "Date",
+  "Datetime",
+  "Duration",
+  "Dynamic Link",
+  "Float",
+  "Fold",
+  "Geolocation",
+  "HTML",
+  "HTML Editor",
+  "Heading",
+  "Icon",
+  "Image",
+  "Int",
+  "JSON",
+  "Link",
+  "Long Text",
+  "Markdown Editor",
+  "Password",
+  "Percent",
+  "Phone",
+  "Rating",
+  "Read Only",
+  "Section Break",
+  "Select",
+  "Signature",
+  "Small Text",
+  "Tab Break",
+  "Table",
+  "Table MultiSelect",
+  "Text",
+  "Text Editor",
+  "Time",
+] as const;
+
+/**
+ * Fieldtypes no bench serves. frappe-ui's field registry renders them for
+ * hand-written meta, so they belong to the union: the registry must never
+ * accept a fieldtype the meta model forbids (MPO-15).
+ */
+export const customFieldTypes = [
+  "Date Range",
+  "Mention",
+  "OTP",
+  "Progress",
+  "Radio",
+  "Slider",
+  "Switch",
+  "Toggle Group",
+] as const;
+
+/** Every fieldtype a `DocTypeField` may carry, and all `registerField` accepts. */
+export const frappeFieldTypes = [...stockFieldTypes, ...customFieldTypes] as const;
+
+export type FrappeFieldType = (typeof frappeFieldTypes)[number];
+
+/**
+ * One DocField row as `frappe.desk.form.load.getdoctype` sends it. This is
+ * the only field model: the desk form engine, the list surfaces and
+ * `useDocTypeMeta` all read it. Flags stay the server's `0 | 1`, and the
+ * index signature carries the keys no surface reads yet.
+ */
 export interface DocTypeField {
   fieldname: string;
   fieldtype: FrappeFieldType;
   label?: string;
   /** Link target DocType, Select options, or Table child DocType */
   options?: string;
-  reqd?: boolean;
-  unique?: boolean;
-  default?: string;
+  reqd?: 0 | 1;
+  unique?: 0 | 1;
+  hidden?: 0 | 1;
+  read_only?: 0 | 1;
+  bold?: 0 | 1;
+  in_list_view?: 0 | 1;
+  in_standard_filter?: 0 | 1;
+  in_global_search?: 0 | 1;
+  allow_in_quick_entry?: 0 | 1;
+  allow_on_submit?: 0 | 1;
+  no_copy?: 0 | 1;
+  set_only_once?: 0 | 1;
+  report_hide?: 0 | 1;
+  /** For Section Break fields: whether the section is collapsible */
+  collapsible?: 0 | 1;
+  collapsible_depends_on?: string;
   /** Conditional visibility expression (e.g. `eval:doc.status=="Active"`) */
   depends_on?: string;
-  read_only?: boolean;
-  hidden?: boolean;
-  in_list_view?: boolean;
-  in_standard_filter?: boolean;
-  description?: string;
+  mandatory_depends_on?: string;
+  read_only_depends_on?: string;
+  fetch_from?: string;
+  fetch_if_empty?: 0 | 1;
+  permlevel?: number;
   length?: number;
-  precision?: number;
+  precision?: string | number;
+  default?: string;
+  description?: string;
   /** For Link fields: comma-separated search fields */
   search_fields?: string;
-  /** For Section Break fields: whether the section is collapsible */
-  collapsible?: boolean;
+  idx?: number;
+  [key: string]: unknown;
 }
 
-/** DocType permission entry */
+/** Role permission row from the DocType meta. */
 export interface DocTypePermission {
-  role: string;
-  read?: boolean;
-  write?: boolean;
-  create?: boolean;
-  delete?: boolean;
-  submit?: boolean;
-  cancel?: boolean;
-  amend?: boolean;
+  role?: string;
+  permlevel?: number;
+  read?: 0 | 1;
+  write?: 0 | 1;
+  create?: 0 | 1;
+  delete?: 0 | 1;
+  submit?: 0 | 1;
+  cancel?: 0 | 1;
+  amend?: 0 | 1;
+  print?: 0 | 1;
+  email?: 0 | 1;
+  share?: 0 | 1;
+  if_owner?: 0 | 1;
+  [key: string]: unknown;
+}
+
+/** DocType Link child row (Connections tab). Probed: `group` arrives null when unset. */
+export interface DocTypeLink {
+  name?: string;
+  link_doctype: string;
+  link_fieldname: string;
+  group?: string | null;
+  hidden?: 0 | 1;
+  is_child_table?: 0 | 1;
+  parent_doctype?: string;
+  table_fieldname?: string;
+  [key: string]: unknown;
 }
 
 /** A column in a form section, containing an ordered list of fields */
@@ -110,20 +175,48 @@ export interface FormSection {
   columns: FormColumn[];
 }
 
-/** Normalized DocType metadata */
+/** DocType meta as `frappe.desk.form.load.getdoctype` sends it (loose: the server is the source of truth). */
 export interface DocTypeMeta {
+  doctype?: string;
   name: string;
-  module: string;
+  module?: string;
+  issingle?: 0 | 1;
+  istable?: 0 | 1;
+  is_submittable?: 0 | 1;
+  is_tree?: 0 | 1;
+  /** Desk treeview_settings asset (`{doctype}_tree.js`) — gates Tree. */
+  __tree_js?: string;
+  /** Desk calendar_settings asset (`{doctype}_calendar.js`) — gates Calendar. */
+  __calendar_js?: string;
+  is_virtual?: 0 | 1;
+  editable_grid?: 0 | 1;
+  track_changes?: 0 | 1;
+  quick_entry?: 0 | 1;
+  autoname?: string;
+  naming_rule?: string;
+  allow_rename?: 0 | 1;
+  allow_copy?: 0 | 1;
+  read_only?: 0 | 1;
+  in_create?: 0 | 1;
+  hide_toolbar?: 0 | 1;
+  max_attachments?: number;
   title_field?: string;
   image_field?: string;
-  is_tree?: boolean;
-  sort_field: string;
-  sort_order: string;
-  /** Flat list of all fields (ordered by field_order or position) */
+  search_fields?: string;
+  sort_field?: string;
+  sort_order?: string;
+  icon?: string;
+  document_type?: string;
+  /** May arrive as a JSON string or an already-parsed array. */
+  field_order?: string[] | string;
+  /** Flat list of all fields (`useDocTypeMeta` orders them by `field_order`) */
   fields: DocTypeField[];
-  /** Parsed layout tree from Section Break / Column Break / Tab Break fields */
-  sections: FormSection[];
-  permissions: DocTypePermission[];
+  permissions?: DocTypePermission[];
+  links?: DocTypeLink[];
+  states?: Array<{ title?: string; color?: string } & Record<string, unknown>>;
+  /** Layout tree parsed from the break fields. `useDocTypeMeta` fills it; a raw getdoctype doc has none. */
+  sections?: FormSection[];
+  [key: string]: unknown;
 }
 
 /** A search result for a Link field */
@@ -191,54 +284,6 @@ interface DocTypeListItem {
   title?: string;
 }
 
-// ---------------------------------------------------------------------------
-// Raw API response types (internal)
-// ---------------------------------------------------------------------------
-
-interface RawDocTypeResponse {
-  name: string;
-  module: string;
-  title_field?: string;
-  image_field?: string;
-  is_tree?: number;
-  sort_field?: string;
-  sort_order?: string;
-  field_order?: string[] | string;
-  fields: RawFieldResponse[];
-  permissions?: RawPermissionResponse[];
-}
-
-interface RawFieldResponse {
-  fieldname: string;
-  fieldtype: string;
-  label?: string;
-  options?: string;
-  reqd?: number;
-  unique?: number;
-  default?: string;
-  depends_on?: string;
-  read_only?: number;
-  hidden?: number;
-  in_list_view?: number;
-  in_standard_filter?: number;
-  description?: string;
-  length?: number;
-  precision?: number;
-  search_fields?: string;
-  collapsible?: number;
-}
-
-interface RawPermissionResponse {
-  role: string;
-  read?: number;
-  write?: number;
-  create?: number;
-  delete?: number;
-  submit?: number;
-  cancel?: number;
-  amend?: number;
-}
-
 // ---------------------------------------------------------------------------
 // Utility: parseDependsOn
 // ---------------------------------------------------------------------------
@@ -328,7 +373,7 @@ export function parseFormLayout(fields: DocTypeField[]): FormSection[] {
       case "Section Break":
         currentSection = {
           label: field.label,
-          collapsible: field.collapsible,
+          collapsible: !!field.collapsible,
           columns: [{ fields: [] }],
         };
         sections.push(currentSection);
@@ -384,39 +429,18 @@ function createHttpClient(config: FrappeConnectionConfig): HttpClient | undefine
   return new HttpClient(config.baseURL, authConfig);
 }
 
-function parseRawField(raw: RawFieldResponse): DocTypeField {
-  return {
-    fieldname: raw.fieldname,
-    fieldtype: raw.fieldtype as FrappeFieldType,
-    label: raw.label,
-    options: raw.options,
-    reqd: !!raw.reqd,
-    unique: !!raw.unique,
-    default: raw.default,
-    depends_on: raw.depends_on,
-    read_only: !!raw.read_only,
-    hidden: !!raw.hidden,
-    in_list_view: !!raw.in_list_view,
-    in_standard_filter: !!raw.in_standard_filter,
-    description: raw.description,
-    length: raw.length,
-    precision: raw.precision,
-    search_fields: raw.search_fields,
-    collapsible: !!raw.collapsible,
-  };
-}
-
-function parseRawPermission(raw: RawPermissionResponse): DocTypePermission {
-  return {
-    role: raw.role,
-    read: !!raw.read,
-    write: !!raw.write,
-    create: !!raw.create,
-    delete: !!raw.delete,
-    submit: !!raw.submit,
-    cancel: !!raw.cancel,
-    amend: !!raw.amend,
-  };
+/**
+ * True when requests on this connection reach Frappe as Guest: it names a
+ * token source, the source resolves empty (signed out), and no Frappe desk
+ * session cookie names a user. A cookie-only connection names no token
+ * source, so it is never judged here.
+ */
+async function connectsAsGuest(auth: FrappeConnectionConfig["auth"]): Promise<boolean> {
+  if (!auth?.useToken || !auth.token) return false;
+  const token = typeof auth.token === "function" ? await auth.token() : auth.token;
+  if (token) return false;
+  const user = getCookie("user_id");
+  return !user || user === "Guest";
 }
 
 function orderFields(fields: DocTypeField[], fieldOrder: string[]): DocTypeField[] {
@@ -442,8 +466,8 @@ function orderFields(fields: DocTypeField[], fieldOrder: string[]): DocTypeField
   return ordered;
 }
 
-function parseRawDocTypeMeta(raw: RawDocTypeResponse): DocTypeMeta {
-  const fields = raw.fields.map(parseRawField);
+function parseRawDocTypeMeta(raw: DocTypeMeta): DocTypeMeta {
+  const fields = raw.fields.map((field) => ({ ...field }));
 
   // field_order may be a JSON string or an already-parsed array
   let fieldOrder: string[] | undefined;
@@ -458,20 +482,14 @@ function parseRawDocTypeMeta(raw: RawDocTypeResponse): DocTypeMeta {
   }
 
   const orderedFields = fieldOrder ? orderFields(fields, fieldOrder) : fields;
-  const permissions = (raw.permissions ?? []).map(parseRawPermission);
-  const sections = parseFormLayout(orderedFields);
 
   return {
-    name: raw.name,
-    module: raw.module,
-    title_field: raw.title_field,
-    image_field: raw.image_field,
-    is_tree: !!raw.is_tree,
+    ...raw,
     sort_field: raw.sort_field || "modified",
     sort_order: raw.sort_order || "DESC",
     fields: orderedFields,
-    sections,
-    permissions,
+    permissions: raw.permissions ?? [],
+    sections: parseFormLayout(orderedFields),
   };
 }
 
@@ -533,6 +551,10 @@ function useHttpClientRef(
  * where the RPC is not registered. When `config.fixtures` carries a "DocType"
  * entry for the doctype it is used instead and no request is made.
  *
+ * Neither route is open to Guest. A signed-out connection (its token source
+ * resolves empty and no desk session cookie names a user) gets a 403
+ * `FrappeError` without a request, so callers keep their Guest fallbacks.
+ *
  * Responses are cached per-session in memory keyed by `{baseURL}:{doctype}`.
  * The `refetch` function clears the cache entry and forces a fresh fetch.
  *
@@ -545,7 +567,7 @@ function useHttpClientRef(
  * function PokemonForm() {
  *   const { meta, isLoading } = useDocTypeMeta(config, "Pokemon");
  *   if (isLoading) return <Spinner />;
- *   return meta?.sections.map(section => (
+ *   return meta?.sections?.map(section => (
  *     <FormSection key={section.label} section={section} />
  *   ));
  * }
@@ -613,7 +635,7 @@ export function useDocTypeMeta(
         // backoffice meta loader uses. Providers that stub only documents fall
         // through to the network below.
         const fromFixtures = config.fixtures
-          ? ((await config.fixtures.getDoc("DocType", doctype)) as RawDocTypeResponse | null)
+          ? ((await config.fixtures.getDoc("DocType", doctype)) as DocTypeMeta | null)
           : null;
         if (cancelled) return;
 
@@ -628,13 +650,20 @@ export function useDocTypeMeta(
             );
           }
 
+          // Both routes below are closed to Guest, so a signed-out reader
+          // gets the 403 without the request (MPO-322).
+          if (await connectsAsGuest(config.auth)) {
+            if (cancelled) return;
+            throw new FrappeError(`Sign in to load the ${doctype} schema`, 403);
+          }
+
           // `getdoctype` is the whitelisted RPC the Desk itself loads form
           // metadata with, and every logged-in user may call it. Reading
           // `/api/resource/DocType/<name>` instead asks for the DocType
           // *document*, which only System Manager holds read permission on, so
           // ordinary users got a 403 PermissionError — and Frappe's
           // developer-mode traceback rendered into the UI instead of a form.
-          const response = await http.get<{ docs?: RawDocTypeResponse[] }>(
+          const response = await http.get<{ docs?: DocTypeMeta[] }>(
             "/api/method/frappe.desk.form.load.getdoctype",
             { doctype },
           );
@@ -650,7 +679,7 @@ export function useDocTypeMeta(
             // above unregistered, so it answers with no `docs`. The document
             // route still serves meta there, and such a site's API clients are
             // typically System Managers, who may read it.
-            const rest = await http.get<{ data?: RawDocTypeResponse }>(
+            const rest = await http.get<{ data?: DocTypeMeta }>(
               `/api/resource/DocType/${encodeURIComponent(doctype)}`,
             );
 

package/src/fixtures.ts

@@ -234,6 +234,7 @@ export class InMemoryFixtureProvider implements FixtureProvider {
     doc: TDoc,
     fields: readonly string[],
   ): Partial<TDoc> {
+    if (fields.includes("*")) return { ...doc };
     const projected: any = {};
     for (const field of fields) {
       if (field in doc) {

package/src/frappeReact.hydration.spec.tsx

@@ -0,0 +1,164 @@
+import { act, Suspense } from "react";
+import { createRoot, hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { expect, it, vi } from "vitest";
+
+const runtime = vi.hoisted(() => ({ client: false }));
+const { mockSubscribe, mockUnsubscribe, mockGetDocsForSubscription, storeListeners, docStore } =
+  vi.hoisted(() => {
+    const listeners = new Set<() => void>();
+    const docs = new Map<string, Array<{ name: string; doctype: string; title: string }>>();
+    let subscriptionCounter = 0;
+    return {
+      storeListeners: listeners,
+      docStore: docs,
+      mockSubscribe: vi.fn(async (query: { doctype: string }) => {
+        const subscriptionId = `sub-${++subscriptionCounter}`;
+        docs.set(subscriptionId, [
+          { name: "ws-1", doctype: query.doctype, title: "Workspace One" },
+          { name: "ws-2", doctype: query.doctype, title: "Workspace Two" },
+        ]);
+        return { subscriptionId, rows: docs.get(subscriptionId), checkpoint: "t0" };
+      }),
+      mockUnsubscribe: vi.fn((subscriptionId: string) => {
+        docs.delete(subscriptionId);
+      }),
+      mockGetDocsForSubscription: vi.fn((subscriptionId: string) => {
+        return docs.get(subscriptionId) ?? [];
+      }),
+    };
+  });
+
+vi.mock("./sync", () => ({
+  SyncModule: class {
+    subscribe = mockSubscribe;
+    unsubscribe = mockUnsubscribe;
+    getDocsForSubscription = mockGetDocsForSubscription;
+    subscribeStore = (listener: () => void) => {
+      storeListeners.add(listener);
+      return () => storeListeners.delete(listener);
+    };
+    mutate = vi.fn();
+  },
+}));
+vi.mock("./realtime", () => ({ RealtimeModule: class {} }));
+vi.mock("./core/http", () => ({ HttpClient: class {} }));
+vi.mock("./db", () => ({ DbModule: class {} }));
+vi.mock("./util", () => ({ isBrowser: () => runtime.client }));
+vi.mock("./fixtureDb", () => ({ FixtureDbModule: class {} }));
+
+import { useFrappeCollection } from "./frappeReact";
+import { useLiveQuery } from "./useLiveQuery";
+
+type Doc = { name: string; doctype: string; title: string };
+
+it.each([false, true])(
+  "hydrates a cached collection after an earlier reader (delayed=%s)",
+  async (delayed) => {
+    const config = { baseURL: `https://neutral-${delayed}.invalid`, realtime: false };
+    const collections = new Set<NonNullable<ReturnType<typeof useFrappeCollection<Doc>>>>();
+    let release: () => void = () => {};
+    let wait = false;
+    const pending = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    function Reader({ late = false, enabled = true }: { late?: boolean; enabled?: boolean }) {
+      if (late && wait) throw pending;
+      const collection = useFrappeCollection<Doc>(enabled ? config : undefined, "Workspace");
+      if (collection) collections.add(collection);
+      const result = useLiveQuery(
+        (q) => (collection ? q.from({ item: collection }) : null),
+        [collection],
+      );
+      return (
+        <div data-result={late ? "late" : "early"}>
+          {!enabled
+            ? "Disabled"
+            : !collection || result.isLoading
+              ? "Loading"
+              : result.data?.map((row) => row.title).join(",")}
+        </div>
+      );
+    }
+    const view = (
+      <Suspense fallback={<span>Boundary pending</span>}>
+        <Reader late />
+      </Suspense>
+    );
+    runtime.client = false;
+    const host = document.createElement("div");
+    host.innerHTML = renderToString(view);
+    expect(host.textContent).toBe("Loading");
+    const serverNode = host.querySelector("[data-result]");
+    document.body.append(host);
+    const earlyHost = document.createElement("div");
+    document.body.append(earlyHost);
+    runtime.client = true;
+    const errors = vi.fn();
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    let early: Root | undefined;
+    let late: Root | undefined;
+    try {
+      await act(async () => {
+        early = createRoot(earlyHost);
+        early.render(<Reader />);
+      });
+      await vi.waitFor(() => expect(earlyHost.textContent).toContain("Workspace One"));
+      const warm = [...collections][0];
+      expect(warm.status).toBe("ready");
+      wait = delayed;
+      await act(async () => {
+        late = hydrateRoot(host, view, { onRecoverableError: errors });
+      });
+      if (delayed) {
+        expect(host.querySelector("[data-result]")).toBe(serverNode);
+        expect(host.textContent).toBe("Loading");
+        await act(async () => {
+          wait = false;
+          release();
+        });
+      }
+      await vi.waitFor(() => expect(host.textContent).toContain("Workspace One"));
+      expect(errors.mock.calls.map(([e]) => String(e))).toEqual([]);
+      expect(
+        consoleError.mock.calls.filter((args) => /hydration|did not match/i.test(args.join(" "))),
+      ).toEqual([]);
+      expect(host.querySelector("[data-result]")).toBe(serverNode);
+      expect(collections.size).toBe(1);
+      await act(async () => {
+        for (const docs of docStore.values())
+          docs.push({ name: "ws-3", doctype: "Workspace", title: "Workspace Three" });
+        for (const listener of storeListeners) listener();
+      });
+      await vi.waitFor(() => expect(host.textContent).toContain("Workspace Three"));
+      await act(async () => late!.render(<Reader enabled={false} />));
+      expect(host.textContent).toBe("Disabled");
+      // A fresh boundary must use its own SSR snapshot after the shared cache
+      // and an earlier boundary have both committed updates.
+      await act(async () => late!.unmount());
+      runtime.client = false;
+      host.innerHTML = renderToString(view);
+      expect(host.textContent).toBe("Loading");
+      const freshServerNode = host.querySelector("[data-result]");
+      runtime.client = true;
+      await act(async () => {
+        late = hydrateRoot(host, view, { onRecoverableError: errors });
+      });
+      await vi.waitFor(() => expect(host.textContent).toContain("Workspace Three"));
+      expect(host.querySelector("[data-result]")).toBe(freshServerNode);
+      expect(errors).not.toHaveBeenCalled();
+    } finally {
+      await act(async () => {
+        early?.unmount();
+        late?.unmount();
+      });
+      host.remove();
+      earlyHost.remove();
+      consoleError.mockRestore();
+    }
+    await vi.waitFor(
+      () => expect([...collections].every((c) => c.subscriberCount === 0)).toBe(true),
+      { timeout: 10000 },
+    );
+  },
+);