@multiplatform.one/frappe-ui 7.28.0 → 7.29.0

package/src/report/savedReports.ts

@@ -0,0 +1,172 @@
+// Saved reports — desk parity via the `Report` doctype (report_type
+// "Report Builder"): the same records desk's "Select Report" dropdown
+// lists. Save/Save As ride the whitelisted frappe.desk.reportview
+// save_report / delete_report methods (identical payload shape, so desk
+// opens reports saved here and vice versa). Fixture mode (stories / no
+// bench) keeps an in-memory list so the control stays demonstrable.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useFrappeConfig } from "../FrappeProvider";
+import {
+  toDeskReportSettings,
+  fromDeskReportSettings,
+  type ReportViewConfig,
+} from "./reportViewModel";
+import { reportCall, type FrappeReportConnection } from "./useFrappeReport";
+
+export interface SavedReportSummary {
+  /** Report document name (usually equals the report title). */
+  name: string;
+  reportName: string;
+  json?: string;
+}
+
+export interface UseSavedReportsResult {
+  reports: SavedReportSummary[];
+  loading: boolean;
+  /** Load a saved report's view config (fields/filters/sort/…). */
+  load: (name: string) => Promise<ReportViewConfig | undefined>;
+  /** Create or update a Report doc; returns the server-side name. */
+  save: (name: string, config: ReportViewConfig) => Promise<string>;
+  remove: (name: string) => Promise<void>;
+  refresh: () => void;
+}
+
+type ReportListRow = { name: string; report_name?: string; json?: string };
+
+/**
+ * Where saved reports are read and written. Omitted, the ambient
+ * FrappeProvider's connection; `fixtures` keeps them in memory.
+ */
+export interface SavedReportsConnection extends FrappeReportConnection {
+  fixtures?: unknown;
+}
+
+export function useSavedReports(
+  doctype: string,
+  connection?: SavedReportsConnection,
+): UseSavedReportsResult {
+  const config = useFrappeConfig();
+  const baseURL = connection ? connection.baseURL : config?.baseURL;
+  const auth = connection ? connection.auth : config?.auth;
+  const fixtureMode = Boolean(connection ? connection.fixtures : config?.fixtures);
+  const call = useMemo(
+    () => (baseURL ? reportCall({ baseURL, auth }) : undefined),
+    [baseURL, auth],
+  );
+  const [reports, setReports] = useState<SavedReportSummary[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [generation, setGeneration] = useState(0);
+  // Fixture-mode saves live here (stories/tests) — never reaches a bench.
+  const memoryConfigs = useRef(new Map<string, ReportViewConfig>());
+
+  useEffect(() => {
+    memoryConfigs.current = new Map();
+    setReports([]);
+  }, [doctype]);
+
+  useEffect(() => {
+    if (!call || fixtureMode) return;
+    let cancelled = false;
+    setLoading(true);
+    call
+      .get<{ message?: ReportListRow[] }>("frappe.client.get_list", {
+        doctype: "Report",
+        filters: JSON.stringify([
+          ["ref_doctype", "=", doctype],
+          ["report_type", "=", "Report Builder"],
+          ["disabled", "=", 0],
+        ]),
+        fields: JSON.stringify(["name", "report_name", "json"]),
+        limit_page_length: 0,
+        order_by: "report_name asc",
+      })
+      .then((res) => {
+        if (cancelled) return;
+        const rows = res.payload?.message ?? [];
+        setReports(
+          rows.map((row) => ({
+            name: row.name,
+            reportName: row.report_name || row.name,
+            json: row.json,
+          })),
+        );
+        setLoading(false);
+      })
+      .catch(() => {
+        // Report doctype may be unreadable for restricted roles — the
+        // selector then simply offers no saved reports.
+        if (cancelled) return;
+        setReports([]);
+        setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [call, fixtureMode, doctype, generation]);
+
+  const load = useCallback(
+    async (name: string): Promise<ReportViewConfig | undefined> => {
+      if (fixtureMode) return memoryConfigs.current.get(name);
+      const summary = reports.find((report) => report.name === name);
+      let json = summary?.json;
+      if (json === undefined && call) {
+        const res = await call.get<{ message?: { json?: string } }>("frappe.client.get_value", {
+          doctype: "Report",
+          filters: JSON.stringify({ name }),
+          fieldname: JSON.stringify(["json"]),
+        });
+        json = res.payload?.message?.json;
+      }
+      if (!json) return undefined;
+      try {
+        return fromDeskReportSettings(doctype, JSON.parse(json));
+      } catch {
+        return undefined;
+      }
+    },
+    [call, fixtureMode, reports, doctype],
+  );
+
+  const save = useCallback(
+    async (name: string, viewConfig: ReportViewConfig): Promise<string> => {
+      const trimmed = name.trim();
+      if (!trimmed) throw new Error("Report name is required");
+      if (fixtureMode || !call) {
+        memoryConfigs.current.set(trimmed, viewConfig);
+        setReports((previous) => [
+          ...previous.filter((report) => report.name !== trimmed),
+          { name: trimmed, reportName: trimmed },
+        ]);
+        return trimmed;
+      }
+      const res = await call.post<{ message?: string }>("frappe.desk.reportview.save_report", {
+        name: trimmed,
+        doctype,
+        report_settings: JSON.stringify(toDeskReportSettings(doctype, viewConfig)),
+      });
+      setGeneration((value) => value + 1);
+      return res.payload?.message ?? trimmed;
+    },
+    [call, fixtureMode, doctype],
+  );
+
+  const remove = useCallback(
+    async (name: string): Promise<void> => {
+      if (fixtureMode || !call) {
+        memoryConfigs.current.delete(name);
+        setReports((previous) => previous.filter((report) => report.name !== name));
+        return;
+      }
+      await call.post("frappe.desk.reportview.delete_report", { name });
+      setGeneration((value) => value + 1);
+    },
+    [call, fixtureMode],
+  );
+
+  const refresh = useCallback(() => setGeneration((value) => value + 1), []);
+
+  return useMemo(
+    () => ({ reports, loading, load, save, remove, refresh }),
+    [reports, loading, load, save, remove, refresh],
+  );
+}

package/src/report/seam.spec.ts

@@ -0,0 +1,216 @@
+/**
+ * MPO-15 (GL-28) — the report seam, from this side.
+ *
+ * Two report concepts, a named query/script report and a doctype's report
+ * view, used to carry four models: FrappeReportView and FrappeReportBuilder
+ * here, reportShapes and reportViewModel plus DoctypeReportView one tier up
+ * in `@multiplatform.one/backoffice`. One model per concept lives here now,
+ * and four things have to stay true for that to mean anything:
+ *
+ *  1. The package barrel hands every name out.
+ *  2. The report modules reach nothing above them: no backoffice import and
+ *     no bounce back through this package's own barrel.
+ *  3. Each model is declared once across both packages, and scrub is the
+ *     server's `frappe.scrub`.
+ *  4. The exported components render through the models: FrappeReportView
+ *     through the query-report model, FrappeReportBuilder through the
+ *     report-view model.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const reportDir = path.resolve(__dirname);
+const srcDir = path.resolve(__dirname, "..");
+const publicDir = path.resolve(srcDir, "../..");
+
+function sourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...sourceFiles(full));
+      continue;
+    }
+    if (!/\.(ts|tsx)$/.test(entry.name)) continue;
+    if (/\.(spec|stories)\./.test(entry.name)) continue;
+    out.push(full);
+  }
+  return out;
+}
+
+function read(rel: string): string {
+  return fs.readFileSync(path.resolve(srcDir, rel), "utf-8");
+}
+
+function declaredIn(pattern: RegExp): string[] {
+  return [...sourceFiles(srcDir), ...sourceFiles(path.resolve(publicDir, "backoffice/src"))]
+    .filter((file) => pattern.test(fs.readFileSync(file, "utf-8")))
+    .map((file) => path.relative(publicDir, file))
+    .sort();
+}
+
+const QUERY_REPORT_NAMES = [
+  "QueryReportColumn",
+  "QueryReportRow",
+  "QueryReportFilters",
+  "QueryReportFilterMeta",
+  "QueryReportMeta",
+  "QueryReportFixture",
+  "QueryReportRunMessage",
+  "ScriptFilterExtraction",
+  "buildRunFilters",
+  "compactFilterValues",
+  "compactQueryReportFilters",
+  "defaultFilterValues",
+  "extractScriptFilters",
+  "humanizeFrappeError",
+  "isEmptyFilterValue",
+  "normalizeFilterMeta",
+  "normalizeQueryReportColumns",
+  "normalizeQueryReportPayload",
+  "normalizeQueryReportRows",
+  "scrubFieldname",
+  "stripReportHtml",
+  "useFrappeReport",
+  "useQueryReport",
+  "UseQueryReportOptions",
+  "UseQueryReportResult",
+  "buildQueryReportColumns",
+  "buildQueryReportCsv",
+  "BuildQueryReportColumnsArgs",
+];
+
+const REPORT_VIEW_NAMES = [
+  "ReportColumnDef",
+  "ReportRow",
+  "ReportSortState",
+  "ReportViewConfig",
+  "DeskReportSettings",
+  "ReportGridRow",
+  "ReportTotalsCell",
+  "REPORT_NUMERIC_FIELDTYPES",
+  "REPORT_PAGE_SIZES",
+  "DEFAULT_REPORT_PAGE_SIZE",
+  "reportColumnsFromMeta",
+  "defaultReportFieldnames",
+  "resolveReportColumns",
+  "reportColumnFilterTuple",
+  "reportColumnFilterTuples",
+  "parseReportFiltersParam",
+  "parseDeskOrderBy",
+  "toDeskReportSettings",
+  "fromDeskReportSettings",
+  "orderReportRows",
+  "buildReportGridRows",
+  "computeReportTotals",
+  "buildReportCsv",
+  "ReportGrid",
+  "ReportGridProps",
+  "ReportViewToolbar",
+  "ReportViewToolbarProps",
+  "useSavedReports",
+  "SavedReportSummary",
+  "UseSavedReportsResult",
+  "dialogBodyMinWidth",
+  "overlayListMaxHeight",
+];
+
+describe("report seam (MPO-15, GL-28)", () => {
+  it("hands both report models out of the package barrel", () => {
+    const barrel = read("index.ts");
+    const start = barrel.indexOf("Report models (MPO-15");
+    expect(start, "the barrel must carry a report models block").toBeGreaterThan(-1);
+    const block = barrel.slice(start);
+    expect(block).toContain('from "./report/queryReport"');
+    expect(block).toContain('from "./report/reportViewModel"');
+    for (const name of [...QUERY_REPORT_NAMES, ...REPORT_VIEW_NAMES]) {
+      expect(block, `the barrel must re-export "${name}"`).toMatch(new RegExp(`\\b${name}\\b`));
+    }
+  });
+
+  it("keeps the report modules off backoffice and off their own barrel", () => {
+    const files = [
+      ...sourceFiles(reportDir),
+      path.resolve(srcDir, "FrappeReportView.tsx"),
+      path.resolve(srcDir, "FrappeReportBuilder.tsx"),
+    ];
+    for (const file of files) {
+      const source = fs.readFileSync(file, "utf-8");
+      expect(source, file).not.toMatch(/from ["']@multiplatform\.one\/backoffice/);
+      expect(source, file).not.toMatch(/from ["']@multiplatform\.one\/frappe-ui/);
+      expect(source, file).not.toMatch(/from ["']\.\.?\/index["']/);
+    }
+  });
+
+  it("scrubs a label the way the server's frappe.scrub does", async () => {
+    const modelPath = "./queryReport";
+    const { scrubFieldname } = (await import(/* @vite-ignore */ modelPath)) as {
+      scrubFieldname: (label: string) => string;
+    };
+    expect(scrubFieldname("Modified On")).toBe("modified_on");
+    expect(scrubFieldname("Multi-Word Label")).toBe("multi_word_label");
+    expect(scrubFieldname("Size (MB)")).toBe("size_(mb)");
+    expect(scrubFieldname("Assigned To/Owner")).toBe("assigned_to/owner");
+    expect(scrubFieldname("  Total (USD) ")).toBe("__total_(usd)_");
+  });
+
+  it("declares the query-report model once, across both packages", () => {
+    expect(declaredIn(/function scrubFieldname\b/)).toEqual([
+      "frappe-ui/src/report/queryReport.ts",
+    ]);
+    expect(declaredIn(/function normalizeQueryReportColumns\b/)).toEqual([
+      "frappe-ui/src/report/queryReport.ts",
+    ]);
+    expect(declaredIn(/function normalizeQueryReportRows\b/)).toEqual([
+      "frappe-ui/src/report/queryReport.ts",
+    ]);
+    expect(declaredIn(/function (?:compactFilterValues|compactQueryReportFilters)\b/)).toEqual([
+      "frappe-ui/src/report/queryReport.ts",
+    ]);
+    expect(declaredIn(/interface (?:QueryReportColumn|FrappeReportColumn)\b/)).toEqual([
+      "frappe-ui/src/report/queryReport.ts",
+    ]);
+  });
+
+  it("declares the report-view model once, across both packages", () => {
+    for (const name of [
+      "reportColumnsFromMeta",
+      "defaultReportFieldnames",
+      "columnFilterTuple",
+      "orderReportRows",
+      "buildReportCsv",
+      "parseReportFiltersParam",
+    ]) {
+      expect(declaredIn(new RegExp(`function ${name}\\b`)), name).toEqual([
+        "frappe-ui/src/report/reportViewModel.ts",
+      ]);
+    }
+    expect(declaredIn(/REPORT_NUMERIC_FIELDTYPES\s*=/)).toEqual([
+      "frappe-ui/src/report/reportViewModel.ts",
+    ]);
+  });
+
+  it("renders FrappeReportView through the query-report model", () => {
+    const view = read("FrappeReportView.tsx");
+    expect(view).toContain('from "./report/queryReport"');
+    expect(view).toContain('from "./report/useFrappeReport"');
+    expect(view).not.toMatch(
+      /export function (?:normalizeReport|compactFilterValues|scrubFieldname)/,
+    );
+    const useQueryReport = read("report/useQueryReport.ts");
+    expect(useQueryReport, "the desk hook runs through the same transport").toContain(
+      'from "./useFrappeReport"',
+    );
+  });
+
+  it("renders FrappeReportBuilder through the report-view model", () => {
+    const builder = read("FrappeReportBuilder.tsx");
+    expect(builder).toContain('from "./report/reportViewModel"');
+    for (const call of ["reportColumnsFromMeta(", "defaultReportFieldnames(", "orderReportRows("]) {
+      expect(builder, call).toContain(call);
+    }
+    expect(builder).toContain("<ReportGrid");
+    expect(builder).not.toMatch(/<ReportBuilder\b/);
+  });
+});

package/src/report/useFrappeReport.ts

@@ -0,0 +1,241 @@
+/**
+ * The query-report transport: one `frappe.desk.query_report.run` caller per
+ * connection, debounced filter changes, the Report's DB-defined filters via
+ * `get_script`. FrappeReportView runs on it directly and the desk's
+ * `useQueryReport` runs its reports through it, so both surfaces send the
+ * same request and read the same normalized payload (MPO-15, GL-28).
+ */
+import { AsyncDebouncer, CallModule, HttpClient, type AuthConfig } from "@multiplatform.one/frappe";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  compactFilterValues,
+  normalizeQueryReportPayload,
+  type QueryReportFilterInput,
+  type QueryReportFilters,
+  type QueryReportPayload,
+  type QueryReportRunMessage,
+} from "./queryReport";
+
+/** Fixture payload or loader — renders the report without any network. */
+export type FrappeReportFixture =
+  | QueryReportRunMessage
+  | ((args: {
+      reportName: string;
+      filters: QueryReportFilters;
+    }) => QueryReportRunMessage | Promise<QueryReportRunMessage>);
+
+export interface FrappeReportConnection {
+  baseURL: string;
+  auth?: {
+    useToken?: boolean;
+    token?: string | (() => string | Promise<string>);
+    type?: string;
+  };
+}
+
+// One whitelisted-method caller per connection — report views sharing a
+// bench share it (same pattern as useFrappeAggregate's DbModule cache).
+const callCache = new Map<string, CallModule>();
+
+/** The shared caller for a connection (report runs, Report doc reads, get_script). */
+export function reportCall(connection: FrappeReportConnection): CallModule {
+  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
+      ? {
+          useToken: connection.auth.useToken,
+          token: connection.auth.token,
+          type: connection.auth.type as AuthConfig["type"],
+        }
+      : undefined;
+    call = new CallModule(new HttpClient(connection.baseURL, authConfig));
+    callCache.set(key, call);
+  }
+  return call;
+}
+
+const DEFAULT_DEBOUNCE_MS = 400;
+
+export interface UseFrappeReportOptions {
+  reportName: string;
+  /** Current filter values (already compacted values are fine too). */
+  filters?: QueryReportFilters;
+  /** Fixture payload / loader — no network is touched when set. */
+  fixture?: FrappeReportFixture;
+  /**
+   * Fetch the report's DB-defined filter definitions (`get_script`).
+   * Off when the consumer supplies `filterFields` explicitly.
+   */
+  fetchFilterDefs?: boolean;
+  /** Bypass the prepared-report cache and execute the report now. */
+  ignorePreparedReport?: boolean;
+  /** Debounce for filter-change refetches in ms (default 400). */
+  debounceMs?: number;
+  enabled?: boolean;
+}
+
+export interface UseFrappeReportResult {
+  payload: QueryReportPayload | undefined;
+  /** DB-defined filter defs (`get_script`); undefined while unknown. */
+  scriptFilters: QueryReportFilterInput[] | undefined;
+  /** First run in flight — nothing to show yet. */
+  isLoading: boolean;
+  /** Any run in flight (filter-change / refresh refetches included). */
+  isFetching: boolean;
+  error: Error | undefined;
+  /** Immediate re-run (skips the debounce window). */
+  refresh: () => void;
+}
+
+/**
+ * Run a named server-side report (`frappe.desk.query_report.run`) with the
+ * given filters. Filter-value changes are debounced; report changes and
+ * explicit `refresh()` run immediately.
+ */
+export function useFrappeReport(
+  connection: FrappeReportConnection | undefined,
+  {
+    reportName,
+    filters,
+    fixture,
+    fetchFilterDefs = false,
+    ignorePreparedReport = false,
+    debounceMs = DEFAULT_DEBOUNCE_MS,
+    enabled = true,
+  }: UseFrappeReportOptions,
+): UseFrappeReportResult {
+  const isEnabled = enabled && !!reportName && (!!connection || !!fixture);
+
+  const [payload, setPayload] = useState<QueryReportPayload | undefined>(undefined);
+  const [scriptFilters, setScriptFilters] = useState<QueryReportFilterInput[] | undefined>(
+    undefined,
+  );
+  const [isLoading, setIsLoading] = useState(isEnabled);
+  const [isFetching, setIsFetching] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  const compactedFilters = useMemo(() => compactFilterValues(filters), [filters]);
+  const filtersKey = JSON.stringify(compactedFilters);
+  const runKey = JSON.stringify([
+    connection?.baseURL,
+    !!fixture,
+    reportName,
+    filtersKey,
+    ignorePreparedReport,
+  ]);
+
+  const fetchSeq = useRef(0);
+  const argsRef = useRef({ reportName, filters: compactedFilters, fixture, ignorePreparedReport });
+  argsRef.current = { reportName, filters: compactedFilters, fixture, ignorePreparedReport };
+  const connectionRef = useRef(connection);
+  connectionRef.current = connection;
+
+  const runFetch = useCallback(async () => {
+    const {
+      reportName: name,
+      filters: values,
+      fixture: fx,
+      ignorePreparedReport: skipPrepared,
+    } = argsRef.current;
+    const conn = connectionRef.current;
+    if (!name || (!conn && !fx)) return;
+    const seq = ++fetchSeq.current;
+    setIsFetching(true);
+    try {
+      let raw: QueryReportRunMessage | undefined;
+      if (fx) {
+        raw = typeof fx === "function" ? await fx({ reportName: name, filters: values }) : fx;
+      } else if (conn) {
+        const res = await reportCall(conn).post<{ message: QueryReportRunMessage }>(
+          "frappe.desk.query_report.run",
+          {
+            report_name: name,
+            filters: values,
+            ignore_prepared_report: skipPrepared ? 1 : 0,
+            // Desk parity: only let the server substitute saved custom
+            // filters when the caller sent no filter values at all.
+            are_default_filters: Object.keys(values).length ? 0 : 1,
+          },
+        );
+        raw = res.payload.message;
+      }
+      if (seq !== fetchSeq.current) return; // stale response — a newer run won
+      setPayload(normalizeQueryReportPayload(raw ?? {}));
+      setError(undefined);
+    } catch (err) {
+      if (seq !== fetchSeq.current) return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      if (seq === fetchSeq.current) {
+        setIsLoading(false);
+        setIsFetching(false);
+      }
+    }
+  }, []);
+
+  // Debouncer coalescing filter keystrokes into one refetch.
+  const debouncerRef = useRef<AsyncDebouncer<() => Promise<void>> | undefined>(undefined);
+  if (!debouncerRef.current) {
+    debouncerRef.current = new AsyncDebouncer(() => runFetch(), {
+      wait: debounceMs,
+    });
+  }
+  useEffect(() => {
+    debouncerRef.current?.setOptions({ wait: debounceMs });
+  }, [debounceMs]);
+  useEffect(() => () => debouncerRef.current?.cancel(), []);
+
+  // Report identity changes (and first mount) run immediately; filter-value
+  // changes ride the debouncer so per-keystroke Data filters cost one run.
+  // The run key guards actual query changes; captured args ride argsRef.
+  const lastRunKeyRef = useRef<string | undefined>(undefined);
+  const lastReportRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (!isEnabled || lastRunKeyRef.current === runKey) return;
+    lastRunKeyRef.current = runKey;
+    const reportChanged = lastReportRef.current !== argsRef.current.reportName;
+    lastReportRef.current = argsRef.current.reportName;
+    setError(undefined);
+    if (reportChanged) {
+      setIsLoading(true);
+      debouncerRef.current?.cancel();
+      void runFetch();
+    } else if (debounceMs <= 0) {
+      void runFetch();
+    } else {
+      void debouncerRef.current?.maybeExecute();
+    }
+  }, [isEnabled, runKey, debounceMs, runFetch]);
+
+  // DB-defined filter definitions (Report doc `filters` child table) via
+  // get_script — live mode only; fixtures carry defs on the payload itself.
+  useEffect(() => {
+    if (!isEnabled || !fetchFilterDefs || fixture || !connection) {
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      try {
+        const res = await reportCall(connection).get<{
+          message: { filters?: QueryReportFilterInput[] };
+        }>("frappe.desk.query_report.get_script", { report_name: reportName });
+        if (!cancelled) setScriptFilters(res.payload.message?.filters ?? []);
+      } catch {
+        // Filter defs are progressive enhancement — a failing get_script
+        // must not take the report down (run() surfaces real errors).
+        if (!cancelled) setScriptFilters([]);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [isEnabled, fetchFilterDefs, fixture, connection, reportName]);
+
+  const refresh = useCallback(() => {
+    debouncerRef.current?.cancel();
+    void runFetch();
+  }, [runFetch]);
+
+  return { payload, scriptFilters, isLoading, isFetching, error, refresh };
+}