@multiplatform.one/backoffice 7.6.3 → 7.7.1

package/src/desk/DeskSurface.stories.tsx

@@ -0,0 +1,297 @@
+// OWNER: backoffice screens workstream (MPO-189).
+// DeskSurface stories: the target→surface switch. One arm per DeskTarget
+// kind, so the whole dispatch table is visible in one place, plus the
+// override registry (per-kind and per-doctype).
+//
+// Everything rides fixtures: doctype meta through the fixture provider's
+// "DocType" collection (shared/useDoctypeMeta's fixture branch), rows and
+// Workspace docs through the same InMemoryFixtureProvider. Query reports
+// are the one surface with no fixture branch — they run three desk RPCs —
+// so a fetch mock scoped to this story's mock host answers those and keeps
+// every arm off the network.
+import { Text, YStack } from "@multiplatform.one/components";
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import type { ReactNode } from "react";
+import { BackofficeProvider } from "../config/BackofficeProvider";
+import { createMemoryNavigator } from "../navigation/navigator";
+import { DeskSurface, DeskSurfaceLoading, type DeskSurfaceProps } from "./DeskSurface";
+import type { DeskTarget } from "./target";
+
+const meta = {
+  title: "Screens/Backoffice/DeskSurface",
+  component: DeskSurface,
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "The desk's target→surface switch: a resolved DeskTarget in, one wired screen out (home redirect, workspace page, list, alternate view, create form, document form, query report, not-found). It is pure dispatch — no fetch, no filter construction, no visual values — and the override registry lets a host replace a whole surface per kind, or per doctype under a kind.",
+      },
+    },
+  },
+};
+export default meta;
+
+const MOCK_HOST = "https://backoffice-desk-surface.mock.test";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const TASK_DOCTYPE = "QaDeskTask";
+
+/** Getdoctype-shaped meta doc for the fixture "DocType" collection. */
+const taskMeta = {
+  name: TASK_DOCTYPE,
+  doctype: "DocType",
+  module: "QA",
+  title_field: "subject",
+  fields: [
+    { fieldname: "subject", fieldtype: "Data", label: "Subject", in_list_view: 1, reqd: 1 },
+    {
+      fieldname: "status",
+      fieldtype: "Select",
+      label: "Status",
+      options: "Open\nWorking\nDone",
+      in_list_view: 1,
+    },
+    {
+      fieldname: "priority",
+      fieldtype: "Select",
+      label: "Priority",
+      options: "High\nMedium\nLow",
+      in_list_view: 1,
+    },
+    { fieldname: "owner_name", fieldtype: "Data", label: "Owner", in_list_view: 1 },
+  ],
+  permissions: [{ role: "All", read: 1, write: 1, create: 1 }],
+};
+
+const statuses = ["Open", "Working", "Done"];
+const priorities = ["High", "Medium", "Low"];
+const owners = ["ana", "bo", "cyrus", "dee"];
+
+const firstTaskName = "QDT-0001";
+
+const taskDocs = Array.from({ length: 12 }, (_, i) => ({
+  name: `QDT-${String(i + 1).padStart(4, "0")}`,
+  doctype: TASK_DOCTYPE,
+  subject: `Task ${i + 1}: ${["triage inbox", "ship release", "write docs", "fix flaky test"][i % 4]}`,
+  status: statuses[i % statuses.length],
+  priority: priorities[i % priorities.length],
+  owner_name: owners[i % owners.length],
+}));
+
+const workspaceDocs = [
+  {
+    name: "Tools",
+    doctype: "Workspace",
+    label: "Tools",
+    title: "Tools",
+    icon: "tool",
+    module: "Automation",
+    parent_page: "",
+    public: 1,
+    for_user: "",
+    sequence_id: 1,
+    is_hidden: 0,
+    content: JSON.stringify([
+      {
+        id: "h1",
+        type: "header",
+        data: { text: '<span class="h4"><b>Your Shortcuts</b></span>', col: 12 },
+      },
+      { id: "s1", type: "shortcut", data: { shortcut_name: "Tasks", col: 3 } },
+      {
+        id: "p1",
+        type: "paragraph",
+        data: { text: "Everything on this page comes from fixtures.<br>", col: 12 },
+      },
+    ]),
+    shortcuts: [{ name: "sc1", type: "DocType", link_to: TASK_DOCTYPE, label: "Tasks" }],
+    links: [],
+    charts: [],
+    number_cards: [],
+    quick_lists: [],
+  },
+];
+
+const makeFixtures = () =>
+  new InMemoryFixtureProvider({
+    DocType: [taskMeta],
+    Workspace: workspaceDocs,
+    "Notification Log": [],
+    [TASK_DOCTYPE]: taskDocs,
+  });
+
+// ---------------------------------------------------------------------------
+// Query-report RPCs. useQueryReport has no fixture branch (it calls
+// frappe.client.get, query_report.get_script and query_report.run), so the
+// `report` arm needs these three answered. Scoped to MOCK_HOST, installed
+// once; stories only run on web. Same precedent as DeskShell.stories.
+// ---------------------------------------------------------------------------
+
+const reportColumns = [
+  { label: "Task", fieldname: "task", fieldtype: "Data", width: "140" },
+  { label: "Status", fieldname: "status", fieldtype: "Data", width: "110" },
+  { label: "Owner", fieldname: "owner_name", fieldtype: "Data", width: "120" },
+  { label: "Age (days)", fieldname: "age", fieldtype: "Int", width: "100" },
+];
+
+const reportRows = taskDocs.map((doc, i) => ({
+  task: doc.name,
+  status: doc.status,
+  owner_name: doc.owner_name,
+  age: (i * 3) % 41,
+}));
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+(() => {
+  if (typeof window === "undefined") return;
+  const w = window as unknown as Record<string, unknown>;
+  if (w.__deskSurfaceMockFetch) return;
+  w.__deskSurfaceMockFetch = true;
+  const realFetch = window.fetch.bind(window);
+  window.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const urlStr =
+      typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    if (!urlStr.startsWith(MOCK_HOST)) return realFetch(input as RequestInfo, init);
+    const { pathname } = new URL(urlStr);
+    if (pathname.endsWith("frappe.desk.query_report.run")) {
+      return jsonResponse({ message: { columns: reportColumns, result: reportRows } });
+    }
+    if (pathname.endsWith("frappe.desk.query_report.get_script")) {
+      return jsonResponse({ message: { script: null } });
+    }
+    if (pathname.endsWith("frappe.client.get")) {
+      return jsonResponse({
+        message: { name: "Open Tasks", report_name: "Open Tasks", ref_doctype: TASK_DOCTYPE },
+      });
+    }
+    // No session against the inert mock host: get_logged_user must answer
+    // null, not a truthy docname (BackofficeShell.stories precedent).
+    if (pathname.endsWith("frappe.auth.get_logged_user")) return jsonResponse({ message: null });
+    return jsonResponse({ data: [], message: [] });
+  };
+})();
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+function Surface({ target, children }: { target?: DeskTarget; children?: ReactNode }) {
+  return (
+    <BackofficeProvider
+      frappe={{ baseURL: MOCK_HOST, fixtures: makeFixtures() }}
+      navigation={createMemoryNavigator("/backoffice")}
+    >
+      <YStack flex={1} height={560} minHeight={0}>
+        {children ?? (target ? <DeskSurface target={target} /> : null)}
+      </YStack>
+    </BackofficeProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// One arm per DeskTarget kind
+// ---------------------------------------------------------------------------
+
+/** kind "list" — the doctype list surface, the desk's most-visited screen. */
+export const List = () => <Surface target={{ kind: "list", doctype: TASK_DOCTYPE }} />;
+List.storyName = "Main";
+
+/** kind "home" — the home redirect, resolving the default workspace. */
+export const Home = () => <Surface target={{ kind: "home" }} />;
+
+/** kind "workspace" — a workspace page rendered from its fixture doc. */
+export const Workspace = () => <Surface target={{ kind: "workspace", workspace: "Tools" }} />;
+
+/** kind "view" — an alternate view; the switch hands off to DoctypeViewScreen. */
+export const AlternateView = () => (
+  <Surface target={{ kind: "view", doctype: TASK_DOCTYPE, view: "kanban" }} />
+);
+
+/** kind "new" — create mode; `defaults` route through the ONE prefill stash. */
+export const NewDocument = () => (
+  <Surface
+    target={{
+      kind: "new",
+      doctype: TASK_DOCTYPE,
+      defaults: { status: "Working", priority: "High" },
+    }}
+  />
+);
+
+/** kind "form" — an existing document. */
+export const Form = () => (
+  <Surface target={{ kind: "form", doctype: TASK_DOCTYPE, name: firstTaskName }} />
+);
+
+/** kind "report" — a Query/Script Report, served by the scoped RPC mock. */
+export const Report = () => <Surface target={{ kind: "report", reportName: "Open Tasks" }} />;
+
+/** kind "not-found" — a dead address. */
+export const NotFound = () => <Surface target={{ kind: "not-found", slug: "no-such-doctype" }} />;
+
+/** The resolving state: an ambiguous slug still in flight against the index. */
+export const Loading = () => (
+  <Surface>
+    <DeskSurfaceLoading />
+  </Surface>
+);
+
+// ---------------------------------------------------------------------------
+// Override registry
+// ---------------------------------------------------------------------------
+
+function TargetCard({ target }: DeskSurfaceProps) {
+  return (
+    <YStack
+      flex={1}
+      padding="$4"
+      gap="$2"
+      borderWidth={1}
+      borderColor="$borderColor"
+      borderRadius="$3"
+      backgroundColor="$color2"
+    >
+      <Text>{`host surface for kind "${target.kind}"`}</Text>
+      <Text>{JSON.stringify(target)}</Text>
+    </YStack>
+  );
+}
+
+/**
+ * Per-kind override: the host replaces the whole list surface. The override
+ * receives the target and the readOnly flag — thin enough to wrap the
+ * built-in rather than reimplement it.
+ */
+export const OverrideByKind = () => (
+  <Surface>
+    <DeskSurface
+      target={{ kind: "list", doctype: TASK_DOCTYPE }}
+      overrides={{ list: TargetCard }}
+    />
+  </Surface>
+);
+
+/**
+ * Per-doctype override beats per-kind, and a miss falls through to the
+ * built-in: the same registry keyed by doctype under one kind.
+ */
+export const OverrideByDoctype = () => (
+  <Surface>
+    <DeskSurface
+      target={{ kind: "list", doctype: TASK_DOCTYPE }}
+      overrides={{ list: { [TASK_DOCTYPE]: TargetCard } }}
+    />
+  </Surface>
+);

package/src/desk/DeskSurface.tsx

@@ -110,10 +110,14 @@ export function DeskSurface({
         <NewDocSurface doctype={target.doctype} defaults={target.defaults} readOnly={readOnly} />
       );
     case "form":
-      // MPO-15: DocFormScreen is the strong form today. When the form-engine
-      // seam collapses (formLayout + useFormEngine hoisted into frappe-ui,
-      // gap GL-3), the exported FrappeForm becomes this branch's renderer —
-      // swap here, nowhere else.
+      // MPO-15: DocFormScreen is the strong form today. The engine itself
+      // (formLayout + useFormEngine) now lives in frappe-ui, but FrappeForm
+      // still builds its schema from the LOSSY normalized meta
+      // (frappe/src/doctype.ts parseRawField drops permlevel, fetch_from,
+      // set_only_once and the *_depends_on keys), so it cannot render those
+      // semantics yet. When that meta model collapses (gap GL-3), the
+      // exported FrappeForm becomes this branch's renderer — swap here,
+      // nowhere else.
       return <DocFormScreen doctype={target.doctype} name={target.name} readOnly={readOnly} />;
     case "report":
       return <QueryReportScreen reportName={target.reportName} />;

package/src/form/createPrefill.ts

@@ -1,28 +1,8 @@
 /**
- * One-shot create-mode prefill hand-off.
- *
- * Two producers, one mechanism:
- * - Duplicate and Amend navigate to `newDocPath(doctype)` and stash the
- *   copied values here (in-memory only — a refresh honestly falls back to
- *   a blank form; no URL-size limits for large docs).
- * - NewDocRouteScreen stashes parsed `?d=` URL defaults (kanban column "+",
- *   calendar day click, connections "+") before rendering the form — those
- *   survive refresh because the URL re-stashes them.
- *
- * The create-mode form (useFormEngine seeding) consumes and clears the
- * stash on mount, merging it over meta defaults. Last stash per doctype
- * wins, so a `?d=` navigation cannot double-apply with a stale
- * Duplicate/Amend hand-off.
+ * Create-mode prefill handoff — moved to
+ * `@multiplatform.one/frappe-ui/src/formEngine/createPrefill` (MPO-15).
+ * Re-exported here so existing imports keep resolving (the GNOME shim
+ * deep-imports this path).
  */
 
-const prefills = new Map<string, Record<string, unknown>>();
-
-export function setCreatePrefill(doctype: string, values: Record<string, unknown>): void {
-  prefills.set(doctype, values);
-}
-
-export function takeCreatePrefill(doctype: string): Record<string, unknown> | undefined {
-  const values = prefills.get(doctype);
-  if (values) prefills.delete(doctype);
-  return values;
-}
+export { setCreatePrefill, takeCreatePrefill } from "@multiplatform.one/frappe-ui";

package/src/form/dirtyTracking.ts

@@ -1,64 +1,7 @@
 /**
- * Dirty tracking for the desk form engine (R-1 false "Not Saved" fix).
- *
- * The engine diffs the locally edited doc against the last server baseline.
- * A strict `!==` diff falsely armed Save on untouched documents whenever a
- * field's *representation* of a value differed from the wire format (mount
- * emitters have been fixed at the field level — forms contract: initialization
- * must not emit change events — but the engine stays defensive).
+ * Dirty-field diffing — moved to
+ * `@multiplatform.one/frappe-ui/src/formEngine/dirtyTracking` (MPO-15).
+ * Re-exported here so existing imports keep resolving.
  */
 
-export function isEmptyValue(value: unknown): boolean {
-  if (value === undefined || value === null) return true;
-  if (typeof value === "string" && value.trim() === "") return true;
-  if (Array.isArray(value) && value.length === 0) return true;
-  return false;
-}
-
-/**
- * Init-aware value equality. Two representation classes are folded:
- *
- * - empty: null / undefined / "" / [] are one empty state (a field
- *   normalizing null → "" is not an edit)
- * - boolean: Check wires 0/1 but a control may emit true/false
- *
- * Everything else stays strict equality — deliberately shallow and honest
- * (no deep equality): desk parity means an edit reverted to a value that is
- * merely *equivalent* (not identical) may still read dirty, while reverting
- * to the exact original value reads clean.
- */
-export function isSameValue(a: unknown, b: unknown): boolean {
-  if (a === b) return true;
-  if (isEmptyValue(a) && isEmptyValue(b)) return true;
-  if (typeof a === "boolean" || typeof b === "boolean") {
-    const an = a === true ? 1 : a === false ? 0 : a;
-    const bn = b === true ? 1 : b === false ? 0 : b;
-    return an === bn;
-  }
-  return false;
-}
-
-/**
- * Names of fields whose local value differs from the baseline.
- *
- * - Edit mode (baseline defined): normalization-insensitive diff via
- *   `isSameValue` — an untouched doc reads pristine even if a field
- *   re-represented its value during initialization.
- * - Create mode (no baseline): any non-empty value counts, defaults included —
- *   desk parity, a new doc shows "Not Saved".
- *
- * `doctype` / `name` are bookkeeping, never dirty.
- */
-export function computeDirtyFields(
-  localDoc: Record<string, unknown>,
-  baseline: Record<string, unknown> | undefined,
-): string[] {
-  const dirty: string[] = [];
-  for (const key of Object.keys(localDoc)) {
-    if (key === "doctype" || key === "name") continue;
-    if (baseline ? !isSameValue(localDoc[key], baseline[key]) : !isEmptyValue(localDoc[key])) {
-      dirty.push(key);
-    }
-  }
-  return dirty;
-}
+export { computeDirtyFields, isEmptyValue, isSameValue } from "@multiplatform.one/frappe-ui";

package/src/form/fetchFrom.ts

@@ -1,111 +1,8 @@
 /**
- * fetch_from client-side preview — desk parity with
- * frappe/public/js/frappe/form/script_manager.js (`setup_add_fetch`) and
- * controls/link.js (`validate_link_and_fetch`):
- *
- * - A field participates when `fetch_from` is "<link_field>.<source_field>"
- *   AND (its fieldtype is in the scalar set desk registers, or it is
- *   read_only / is_virtual).
- * - When the link field changes to a value, desk calls
- *   `frappe.client.validate_link` with the source columns and writes the
- *   returned values onto the targets; clearing the link clears the targets.
- * - `fetch_if_empty` targets keep a non-empty existing value (server
- *   semantics; desk leaves such fields editable — see
- *   `read_only_because_of_fetch_from`, base_input.js:56-66).
- *
- * The server remains authoritative: this is a preview so the user sees the
- * fetched values before save.
+ * `fetch_from` map + lock helpers — moved to
+ * `@multiplatform.one/frappe-ui/src/formEngine/fetchFrom` (MPO-15).
+ * Re-exported here so existing imports keep resolving.
  */
 
-import type { DocFieldMeta } from "../shared/useDoctypeMeta";
-
-/** Fieldtypes desk registers for client-side fetch (script_manager.js:196-215). */
-const FETCHABLE_FIELDTYPES = new Set([
-  "Data",
-  "Read Only",
-  "Text",
-  "Small Text",
-  "Currency",
-  "Check",
-  "Text Editor",
-  "Attach Image",
-  "Code",
-  "Link",
-  "Float",
-  "Int",
-  "Date",
-  "Datetime",
-  "Select",
-  "Duration",
-  "Time",
-]);
-
-export interface FetchRule {
-  /** Field to populate. */
-  target: string;
-  /** Column on the linked doc to read. */
-  source: string;
-  /** Only fill when the target is currently empty; never lock the field. */
-  fetchIfEmpty: boolean;
-}
-
-/** Map of link fieldname → fetch rules hanging off that link. */
-export type FetchMap = Map<string, FetchRule[]>;
-
-export function buildFetchMap(fields: DocFieldMeta[]): FetchMap {
-  const map: FetchMap = new Map();
-  for (const field of fields) {
-    const fetchFrom = typeof field.fetch_from === "string" ? field.fetch_from : "";
-    if (!fetchFrom || !fetchFrom.includes(".")) continue;
-    const eligible =
-      FETCHABLE_FIELDTYPES.has(field.fieldtype) ||
-      !!field.read_only ||
-      !!(field as { is_virtual?: 0 | 1 }).is_virtual;
-    if (!eligible) continue;
-    const [linkField, ...rest] = fetchFrom.split(".");
-    const source = rest.join(".");
-    if (!linkField || !source) continue;
-    const rules = map.get(linkField) ?? [];
-    rules.push({
-      target: field.fieldname,
-      source,
-      fetchIfEmpty: !!field.fetch_if_empty,
-    });
-    map.set(linkField, rules);
-  }
-  return map;
-}
-
-function isEmpty(value: unknown): boolean {
-  return value === undefined || value === null || value === "";
-}
-
-/**
- * Values to patch onto the doc after the linked doc's columns arrive.
- * `fetched` is empty when the link was cleared — desk then blanks the
- * targets; `fetch_if_empty` targets holding a value are left alone in both
- * directions (they belong to the user until the server reconciles).
- */
-export function applyFetchedValues(
-  rules: FetchRule[],
-  fetched: Record<string, unknown>,
-  currentDoc: Record<string, unknown>,
-): Record<string, unknown> {
-  const patch: Record<string, unknown> = {};
-  for (const rule of rules) {
-    if (rule.fetchIfEmpty && !isEmpty(currentDoc[rule.target])) continue;
-    patch[rule.target] = fetched[rule.source] ?? "";
-  }
-  return patch;
-}
-
-/**
- * Desk's `read_only_because_of_fetch_from`: a fetch target without
- * `fetch_if_empty` renders read-only while its source link holds a value.
- */
-export function isFetchLocked(field: DocFieldMeta, doc: Record<string, unknown>): boolean {
-  const fetchFrom = typeof field.fetch_from === "string" ? field.fetch_from : "";
-  if (!fetchFrom || !fetchFrom.includes(".") || field.fetch_if_empty) return false;
-  const linkField = fetchFrom.split(".")[0];
-  return !isEmpty(doc[linkField]);
-}
+export { applyFetchedValues, buildFetchMap, isFetchLocked } from "@multiplatform.one/frappe-ui";
+export type { FetchMap, FetchRule } from "@multiplatform.one/frappe-ui";

package/src/form/fieldPermissions.ts

@@ -1,68 +1,10 @@
 /**
- * Field-level permission matrix — desk parity with
- * frappe/public/js/frappe/model/perm.js (`get_role_permissions` +
- * `get_field_display_status`):
- *
- *   perm[level] = OR of meta.permissions rows whose role the session user
- *   holds. A field at permlevel L then resolves to:
- *     - no read at L  → hidden   ("None")
- *     - read, no write → read-only ("Read")
- *     - write          → editable ("Write", subject to the other rules)
- *
- * Levels that appear on fields but have no granting rows resolve to
- * {read: false} — desk hides those fields (gap-filled `{}` in perm.js:153).
- * When the caller has no role list (fixtures, roles RPC unavailable) the
- * matrix is undefined and formLayout falls back to the conservative
- * "permlevel > 0 → read-only" rule (never hides, never unlocks).
+ * Permlevel matrix helpers — moved to
+ * `@multiplatform.one/frappe-ui/src/formEngine/fieldPermissions` (MPO-15),
+ * because formLayout consumes them and formLayout now lives there.
+ * Re-exported here so existing imports keep resolving (the GNOME shim
+ * deep-imports this path).
  */
 
-import type { DocPermissionRule } from "../shared/useDoctypeMeta";
-
-export interface LevelPerm {
-  read: boolean;
-  write: boolean;
-}
-
-/** Sparse array indexed by permlevel; missing entries mean "no rights". */
-export type PermLevelMatrix = LevelPerm[];
-
-export function buildPermLevelMatrix(
-  permissions: DocPermissionRule[] | undefined,
-  userRoles: string[] | undefined,
-): PermLevelMatrix | undefined {
-  if (!userRoles || !permissions || permissions.length === 0) return undefined;
-  const roles = new Set(userRoles);
-  const matrix: PermLevelMatrix = [];
-  for (const rule of permissions) {
-    if (!rule.role || !roles.has(rule.role)) continue;
-    const level = Number(rule.permlevel ?? 0) || 0;
-    const current = (matrix[level] ??= { read: false, write: false });
-    // if_owner rows are unioned in like desk's get_role_permissions — the
-    // owner check itself is enforced server-side (and via docinfo at level 0).
-    if (rule.read) current.read = true;
-    if (rule.write) current.write = true;
-  }
-  return matrix;
-}
-
-/**
- * Read access at a permlevel. Level 0 is implied by having the doc at all
- * (docinfo/doc-level perms govern it — including share/if_owner grants the
- * role matrix can't see), so only higher levels consult the matrix.
- */
-export function canReadLevel(matrix: PermLevelMatrix | undefined, permlevel: number): boolean {
-  if (!permlevel) return true;
-  if (!matrix) return true; // caller falls back to the coarse read-only rule
-  return !!matrix[permlevel]?.read;
-}
-
-/**
- * Write access at a permlevel. Level 0 defers to the doc-level write flag
- * (formReadOnly); higher levels require a granting role row — without a
- * matrix the coarse fallback keeps them read-only (desk-safe direction).
- */
-export function canWriteLevel(matrix: PermLevelMatrix | undefined, permlevel: number): boolean {
-  if (!permlevel) return true;
-  if (!matrix) return false;
-  return !!matrix[permlevel]?.write;
-}
+export { buildPermLevelMatrix, canReadLevel, canWriteLevel } from "@multiplatform.one/frappe-ui";
+export type { LevelPerm, PermLevelMatrix } from "@multiplatform.one/frappe-ui";