@multiplatform.one/backoffice 6.4.3 → 6.6.0

package/src/report/savedReports.ts

@@ -0,0 +1,161 @@
+// 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 { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useFrappeApp } from "../shared/useFrappeApp";
+import {
+  toDeskReportSettings,
+  fromDeskReportSettings,
+  type ReportViewConfig,
+} from "./reportViewModel";
+
+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 };
+
+export function useSavedReports(doctype: string): UseSavedReportsResult {
+  const app = useFrappeApp();
+  const config = useFrappeConfig();
+  const fixtureMode = Boolean(config?.fixtures);
+  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 (!app || fixtureMode) return;
+    let cancelled = false;
+    setLoading(true);
+    app
+      .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;
+    };
+  }, [app, 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 && app) {
+        const res = await app
+          .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;
+      }
+    },
+    [app, 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 || !app) {
+        memoryConfigs.current.set(trimmed, viewConfig);
+        setReports((previous) => [
+          ...previous.filter((report) => report.name !== trimmed),
+          { name: trimmed, reportName: trimmed },
+        ]);
+        return trimmed;
+      }
+      const res = await app
+        .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;
+    },
+    [app, fixtureMode, doctype],
+  );
+
+  const remove = useCallback(
+    async (name: string): Promise<void> => {
+      if (fixtureMode || !app) {
+        memoryConfigs.current.delete(name);
+        setReports((previous) => previous.filter((report) => report.name !== name));
+        return;
+      }
+      await app.call().post("frappe.desk.reportview.delete_report", { name });
+      setGeneration((value) => value + 1);
+    },
+    [app, fixtureMode, doctype],
+  );
+
+  const refresh = useCallback(() => setGeneration((value) => value + 1), []);
+
+  return useMemo(
+    () => ({ reports, loading, load, save, remove, refresh }),
+    [reports, loading, load, save, remove, refresh],
+  );
+}

package/src/report/useQueryReport.ts

@@ -0,0 +1,302 @@
+// Data hook for frappe Query / Script Reports (the desk
+// /app/query-report/<name> surface): loads the Report doc (title,
+// ref_doctype, doc-level filters) and runs frappe.desk.query_report.run.
+// Wire-shape normalization (and the probed response documentation) lives in
+// reportShapes.ts; this file owns fetch/state.
+//
+//   GET /api/method/frappe.client.get {doctype:"Report", name}
+//   → {message: {report_name, ref_doctype, report_type, disabled,
+//      prepared_report, add_total_row, filters: [...], ...}}
+//
+// Doc-level filters (the Report `filters` child table) are the only filter
+// meta derivable via the API; standard reports declare filters in desk-side
+// JS files instead, so a failed run surfaces a hint rather than blocking.
+// `ignore_prepared_report` forces a synchronous run for prepared reports
+// (desk's background Prepared Report queue is out of scope here).
+import type { FrappeApp } from "@multiplatform.one/frappe";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useFrappeApp } from "../shared/useFrappeApp";
+import {
+  type QueryReportColumn,
+  type QueryReportFilterMeta,
+  type QueryReportFilters,
+  type QueryReportFixture,
+  type QueryReportMeta,
+  type QueryReportRow,
+  type QueryReportRunMessage,
+  humanizeFrappeError,
+  isEmptyFilterValue,
+  normalizeFilterMeta,
+  normalizeQueryReportColumns,
+  normalizeQueryReportRows,
+} from "./reportShapes";
+
+export {
+  normalizeQueryReportColumns,
+  normalizeQueryReportRows,
+  scrubFieldname,
+  stripHtml,
+} from "./reportShapes";
+export type {
+  QueryReportColumn,
+  QueryReportFilterMeta,
+  QueryReportFilters,
+  QueryReportFixture,
+  QueryReportMeta,
+  QueryReportRow,
+} from "./reportShapes";
+
+const RUN_METHOD = "frappe.desk.query_report.run";
+
+export interface UseQueryReportOptions {
+  fixture?: QueryReportFixture;
+  /** Filter values applied before the first run (report swaps re-apply them). */
+  initialFilters?: QueryReportFilters;
+}
+
+export interface UseQueryReportResult {
+  meta?: QueryReportMeta;
+  columns: QueryReportColumn[];
+  rows: QueryReportRow[];
+  /** True until the first meta+run cycle settles. */
+  loading: boolean;
+  /** True while a (re)run is in flight. */
+  running: boolean;
+  error?: Error;
+  /** The report's informational `message` payload (may embed HTML). */
+  serverMessage?: string;
+  /** Server-reported run time in seconds. */
+  executionTime?: number;
+  /** Doc-level filter meta (empty for reports with desk-JS filters). */
+  filterMeta: QueryReportFilterMeta[];
+  /** Mandatory doc-level filters currently unfilled — the run is skipped while non-empty. */
+  missingRequired: QueryReportFilterMeta[];
+  filters: QueryReportFilters;
+  setFilters: (next: QueryReportFilters) => void;
+  reload: () => void;
+}
+
+async function fetchReportMeta(app: FrappeApp, reportName: string): Promise<QueryReportMeta> {
+  const res = await app.call().get<{ message?: QueryReportMeta }>("frappe.client.get", {
+    doctype: "Report",
+    name: reportName,
+  });
+  const doc = res.payload?.message;
+  if (!doc) throw new Error(`Report "${reportName}" not found`);
+  return doc;
+}
+
+export function useQueryReport(
+  reportName: string,
+  options: UseQueryReportOptions = {},
+): UseQueryReportResult {
+  const { fixture } = options;
+  const app = useFrappeApp();
+
+  // Latest initialFilters without re-running effects on identity churn.
+  const initialFiltersRef = useRef(options.initialFilters);
+  initialFiltersRef.current = options.initialFilters;
+
+  const [meta, setMeta] = useState<QueryReportMeta | undefined>(undefined);
+  const [metaSettled, setMetaSettled] = useState(false);
+  const [filters, setFiltersState] = useState<QueryReportFilters>(() => ({
+    ...initialFiltersRef.current,
+  }));
+  const [columns, setColumns] = useState<QueryReportColumn[]>([]);
+  const [rows, setRows] = useState<QueryReportRow[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [running, setRunning] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [serverMessage, setServerMessage] = useState<string | undefined>(undefined);
+  const [executionTime, setExecutionTime] = useState<number | undefined>(undefined);
+  const [generation, setGeneration] = useState(0);
+  const seededFor = useRef<string | undefined>(undefined);
+
+  // The route component is reused across query-report navigations — a
+  // report swap resets filters and shows the loading state again.
+  const lastReport = useRef(reportName);
+  useEffect(() => {
+    if (lastReport.current === reportName) return;
+    lastReport.current = reportName;
+    setFiltersState({ ...initialFiltersRef.current });
+    setMeta(undefined);
+    setMetaSettled(false);
+    setColumns([]);
+    setRows([]);
+    setError(undefined);
+    setServerMessage(undefined);
+    setExecutionTime(undefined);
+    setLoading(true);
+  }, [reportName]);
+
+  // Report doc meta (title, ref_doctype, doc-level filters). Failure is
+  // non-fatal — the run below is still attempted.
+  useEffect(() => {
+    if (fixture) return;
+    if (!app) {
+      setMetaSettled(true);
+      return;
+    }
+    let cancelled = false;
+    setMetaSettled(false);
+    fetchReportMeta(app, reportName)
+      .then((doc) => {
+        if (cancelled) return;
+        setMeta(doc);
+        // Seed doc-level filter defaults once per report; user edits win.
+        if (seededFor.current !== reportName) {
+          seededFor.current = reportName;
+          const defaults: QueryReportFilters = {};
+          for (const filter of normalizeFilterMeta(doc.filters)) {
+            if (filter.default !== undefined && filter.default !== "")
+              defaults[filter.fieldname] = filter.default;
+          }
+          if (Object.keys(defaults).length > 0)
+            setFiltersState((previous) => ({ ...defaults, ...previous }));
+        }
+      })
+      .catch(() => {
+        // meta is a nicety (title/filters); the run reports real errors
+      })
+      .finally(() => {
+        if (!cancelled) setMetaSettled(true);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, fixture, reportName]);
+
+  const filterMeta = useMemo(
+    () => normalizeFilterMeta(fixture ? fixture.meta?.filters : meta?.filters),
+    [fixture, meta],
+  );
+
+  const missingRequired = useMemo(
+    () =>
+      filterMeta.filter(
+        (filter) =>
+          filter.mandatory === 1 && isEmptyFilterValue(filters[filter.fieldname] ?? filter.default),
+      ),
+    [filterMeta, filters],
+  );
+  const hasMissingRequired = missingRequired.length > 0;
+  const metaDisabled = (fixture ? fixture.meta?.disabled : meta?.disabled) === 1;
+
+  useEffect(() => {
+    if (fixture) return;
+    if (!metaSettled) return;
+    if (metaDisabled) {
+      setLoading(false);
+      return;
+    }
+    if (hasMissingRequired) {
+      setColumns([]);
+      setRows([]);
+      setError(undefined);
+      setLoading(false);
+      return;
+    }
+    if (!app) {
+      setError(new Error("No Frappe connection configured"));
+      setLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setRunning(true);
+    app
+      .call()
+      .post<{ message?: QueryReportRunMessage }>(RUN_METHOD, {
+        report_name: reportName,
+        filters,
+        ignore_prepared_report: 1,
+      })
+      .then((res) => {
+        if (cancelled) return;
+        const message = res.payload?.message;
+        const nextColumns = normalizeQueryReportColumns(message?.columns);
+        setColumns(nextColumns);
+        setRows(normalizeQueryReportRows(message?.result, nextColumns));
+        setServerMessage(typeof message?.message === "string" ? message.message : undefined);
+        setExecutionTime(
+          typeof message?.execution_time === "number" ? message.execution_time : undefined,
+        );
+        setError(undefined);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setColumns([]);
+        setRows([]);
+        setError(humanizeFrappeError(err));
+      })
+      .finally(() => {
+        if (cancelled) return;
+        setRunning(false);
+        setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    app,
+    fixture,
+    reportName,
+    filters,
+    generation,
+    metaSettled,
+    metaDisabled,
+    hasMissingRequired,
+  ]);
+
+  const setFilters = useCallback((next: QueryReportFilters) => {
+    setFiltersState(next);
+  }, []);
+
+  const reload = useCallback(() => {
+    setGeneration((previous) => previous + 1);
+  }, []);
+
+  // Fixture branch: static data, no RPCs (stories/tests).
+  const fixtureResult = useMemo(() => {
+    if (!fixture) return undefined;
+    const fixtureColumns = normalizeQueryReportColumns(fixture.columns);
+    return {
+      columns: fixtureColumns,
+      rows: normalizeQueryReportRows(fixture.rows, fixtureColumns),
+      meta: fixture.meta ? ({ name: reportName, ...fixture.meta } as QueryReportMeta) : undefined,
+    };
+  }, [fixture, reportName]);
+
+  if (fixtureResult) {
+    return {
+      meta: fixtureResult.meta,
+      columns: fixtureResult.columns,
+      rows: hasMissingRequired ? [] : fixtureResult.rows,
+      loading: false,
+      running: false,
+      error: undefined,
+      serverMessage: fixture?.message,
+      executionTime: undefined,
+      filterMeta,
+      missingRequired,
+      filters,
+      setFilters,
+      reload,
+    };
+  }
+
+  return {
+    meta,
+    columns,
+    rows,
+    loading,
+    running,
+    error,
+    serverMessage,
+    executionTime,
+    filterMeta,
+    missingRequired,
+    filters,
+    setFilters,
+    reload,
+  };
+}

package/src/shared/useSlugTarget.ts

@@ -15,6 +15,15 @@ import type { SlugTarget } from "./types";
 interface SlugIndex {
   workspaces: Map<string, string>;
   doctypes: Map<string, string>;
+  /**
+   * Proper-cased names of Single doctypes. Desk skips these via boot
+   * metadata (`frappe.boot.single_types`); we derive the same set from the
+   * one DocType list this index already fetches. Consumers use it to avoid
+   * operations that reject permanently on singles — `frappe.client.get_count`
+   * HTTP-500s for every Single (e.g. the stock Website workspace's
+   * "Website Settings" shortcut).
+   */
+  singles: Set<string>;
 }
 
 interface SlugIndexSource {
@@ -26,6 +35,11 @@ interface SlugIndexSource {
 /** Module-level cache: one fetch per (baseURL, fixture-mode) per session. */
 const slugIndexCache = new Map<string, Promise<SlugIndex>>();
 
+interface DoctypeIndexRow {
+  name?: string;
+  issingle?: 0 | 1;
+}
+
 function toSlugMap(names: readonly { name?: string }[]): Map<string, string> {
   const map = new Map<string, string>();
   for (const row of names) {
@@ -34,15 +48,24 @@ function toSlugMap(names: readonly { name?: string }[]): Map<string, string> {
   return map;
 }
 
+function toSinglesSet(rows: readonly DoctypeIndexRow[]): Set<string> {
+  const singles = new Set<string>();
+  for (const row of rows) {
+    if (row.name && row.issingle) singles.add(row.name);
+  }
+  return singles;
+}
+
 async function fetchSlugIndex(source: SlugIndexSource): Promise<SlugIndex> {
   if (source.fixtures) {
     const [workspaces, doctypes] = await Promise.all([
       source.fixtures.getList("Workspace", { fields: ["name"] }),
-      source.fixtures.getList("DocType", { fields: ["name"] }),
+      source.fixtures.getList("DocType", { fields: ["name", "issingle"] }),
     ]);
     return {
       workspaces: toSlugMap(workspaces as { name?: string }[]),
       doctypes: toSlugMap(doctypes as { name?: string }[]),
+      singles: toSinglesSet(doctypes as DoctypeIndexRow[]),
     };
   }
   const client = new HttpClient(source.baseURL, source.auth as AuthConfig | undefined);
@@ -51,15 +74,16 @@ async function fetchSlugIndex(source: SlugIndexSource): Promise<SlugIndex> {
       fields: '["name"]',
       limit_page_length: "0",
     }),
-    client.get<{ message?: { name: string }[] }>("/api/method/frappe.client.get_list", {
+    client.get<{ message?: DoctypeIndexRow[] }>("/api/method/frappe.client.get_list", {
       doctype: "DocType",
-      fields: '["name"]',
+      fields: '["name","issingle"]',
       limit_page_length: "0",
     }),
   ]);
   return {
     workspaces: toSlugMap(workspacesRes.payload?.data ?? []),
     doctypes: toSlugMap(doctypesRes.payload?.message ?? []),
+    singles: toSinglesSet(doctypesRes.payload?.message ?? []),
   };
 }
 
@@ -141,3 +165,44 @@ export function useSlugTarget(slug: string | undefined): SlugTarget {
     return { status: "loading" };
   }, [slug, index, failed]);
 }
+
+const EMPTY_SINGLES: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Proper-cased names of Single doctypes (desk boot's `single_types`
+ * equivalent), from the same once-per-session index the slug router uses —
+ * usually already resolved by the time any screen consults it.
+ *
+ * `undefined` while the index is loading; an EMPTY set once the fetch failed
+ * (degrade to pre-gate behavior rather than blocking consumers forever).
+ */
+export function useSingleDoctypes(): ReadonlySet<string> | undefined {
+  const config = useFrappeConfig();
+  const baseURL = config?.baseURL;
+  const fixtures = config?.fixtures;
+  const auth = config?.auth;
+
+  const [singles, setSingles] = useState<ReadonlySet<string> | undefined>(undefined);
+
+  useEffect(() => {
+    let cancelled = false;
+    if (!baseURL && !fixtures) {
+      setSingles(EMPTY_SINGLES);
+      return;
+    }
+    getSlugIndex({ baseURL: baseURL ?? "", auth, fixtures })
+      .then((result) => {
+        if (!cancelled) setSingles(result.singles);
+      })
+      .catch(() => {
+        if (!cancelled) setSingles(EMPTY_SINGLES);
+      });
+    return () => {
+      cancelled = true;
+    };
+    // `auth` is session-stable; the index cache is keyed by baseURL/fixtures.
+    // oxlint-disable-next-line exhaustive-deps
+  }, [baseURL, fixtures]);
+
+  return singles;
+}

package/src/shell/HomeRedirect.tsx

@@ -0,0 +1,63 @@
+/**
+ * Lands the user on their default workspace (desk parity): first private
+ * workspace, else the first public workspace by sequence order. Rendered by
+ * the backoffice home route ("{base}").
+ */
+import { EmptyState, Paragraph, Spinner, YStack } from "@multiplatform.one/components";
+import { useEffect } from "react";
+import { useTranslation } from "react-i18next";
+import { useBackofficeNavigator, useBackofficePaths } from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { useDefaultWorkspace } from "./useWorkspaces";
+
+export function HomeRedirect() {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const { workspace, isLoading } = useDefaultWorkspace();
+
+  useEffect(() => {
+    if (!workspace) return;
+    const target = paths.workspace(workspace);
+    // Host routers (one's included) can silently no-op a replace that fires
+    // before their navigation container mounts — routine on warm reloads
+    // where the cached workspace list resolves first, which stranded the
+    // home route on its spinner (audit R-2ii). Retry until the location
+    // actually moves off the path we started on; success normally unmounts
+    // this screen, which clears the interval either way.
+    const startPath = navigator.getLocation().path;
+    const attempt = () => {
+      if (navigator.getLocation().path !== startPath) return;
+      try {
+        navigator.replace(target);
+      } catch {
+        // navigation not ready yet — the interval retries
+      }
+    };
+    attempt();
+    const retry = setInterval(() => {
+      if (navigator.getLocation().path !== startPath) {
+        clearInterval(retry);
+        return;
+      }
+      attempt();
+    }, 250);
+    return () => clearInterval(retry);
+  }, [workspace, navigator, paths]);
+
+  if (!isLoading && !workspace) {
+    return (
+      <EmptyState
+        title={t("noWorkspacesTitle", "No workspaces")}
+        description={t("noWorkspacesDescription", "No workspaces are visible for this account.")}
+      />
+    );
+  }
+
+  return (
+    <YStack flex={1} alignItems="center" justifyContent="center" gap="$3">
+      <Spinner size="large" />
+      <Paragraph color="$color10">{t("loadingWorkspaces", "Loading workspaces…")}</Paragraph>
+    </YStack>
+  );
+}

package/src/shell/NotFoundScreen.tsx

@@ -0,0 +1,32 @@
+/**
+ * Unmatched-path surface (audit R-2i): any backoffice path that matches no
+ * route pattern (deep or malformed links). Same presentation as the
+ * SlugScreen unknown-slug state, plus a way back to the default workspace.
+ */
+import { Button, EmptyState } from "@multiplatform.one/components";
+import { useTranslation } from "react-i18next";
+import {
+  useBackofficeLocation,
+  useBackofficeNavigator,
+  useBackofficePaths,
+} from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+
+export function NotFoundScreen() {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const location = useBackofficeLocation();
+
+  return (
+    <EmptyState
+      title={t("notFound", "Not found")}
+      description={location.path || undefined}
+      action={
+        <Button onPress={() => navigator.replace(paths.home())}>
+          {t("notFoundGoHome", "Go to workspaces")}
+        </Button>
+      }
+    />
+  );
+}