@multiplatform.one/frappe-ui 7.6.2 → 7.7.0

package/src/formEngine/formLayout.ts

@@ -0,0 +1,392 @@
+/**
+ * Desk form layout engine.
+ *
+ * Splits the flat DocType field list into desk tabs (Tab Break), sections
+ * (Section Break, collapsible honored), and columns (Column Break), and
+ * maps them to the generic `FormSchema` consumed by frappe-ui's SchemaForm.
+ *
+ * Dynamic behavior is computed HERE with the safe depends_on evaluator
+ * (dependsOn.ts) — the `depends_on` string is deliberately stripped from the
+ * FieldSchema handed to SchemaForm so its string-eval-based evaluator
+ * (which cannot run on Hermes/GJS) never engages:
+ *
+ *   - depends_on            → field omitted from the built schema
+ *   - mandatory_depends_on  → `required: true` on the built FieldSchema
+ *   - read_only_depends_on  → `readOnly: true` on the built FieldSchema
+ *   - permlevel             → hidden without level read, read-only without
+ *     level write (role matrix via fieldPermissions.ts; coarse read-only
+ *     fallback when roles are unavailable)
+ *   - set_only_once         → read-only on saved docs
+ *   - fetch_from            → read-only while the source link holds a value
+ *     (unless fetch_if_empty)
+ *   - docstatus > 0         → everything read-only except allow_on_submit
+ *     fields on a submitted (1) doc
+ *   - collapsible / collapsible_depends_on / missing-mandatory → per-section
+ *     computed collapse state (desk refresh_section_collapse)
+ *
+ * Sections whose Section Break has a false depends_on hide wholesale; a
+ * section with no visible fields is dropped so SchemaForm never renders an
+ * empty card.
+ */
+
+import { formatCalendarDate } from "@multiplatform.one/theme";
+import type { FieldSchema } from "../fieldRegistry";
+import type { FormSchema, FormSection } from "../schemaForm";
+import { evaluateDependsOn } from "../dependsOn";
+import { canReadLevel, canWriteLevel, type PermLevelMatrix } from "./fieldPermissions";
+import { isFetchLocked } from "./fetchFrom";
+import type { DocFieldMeta } from "./doctypeMeta";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FormTab {
+  /** Stable key (fieldname of the Tab Break or "__details") */
+  key: string;
+  label: string;
+  schema: FormSchema;
+}
+
+interface LayoutColumn {
+  fields: DocFieldMeta[];
+}
+
+interface LayoutSection {
+  breakField?: DocFieldMeta;
+  columns: LayoutColumn[];
+}
+
+interface LayoutTab {
+  key: string;
+  label?: string;
+  sections: LayoutSection[];
+}
+
+// ---------------------------------------------------------------------------
+// Static structure (from meta, doc-independent)
+// ---------------------------------------------------------------------------
+
+function splitIntoTabs(fields: DocFieldMeta[]): LayoutTab[] {
+  const tabs: LayoutTab[] = [];
+  let currentTab: LayoutTab = { key: "__details", sections: [] };
+  let currentSection: LayoutSection = { columns: [{ fields: [] }] };
+  currentTab.sections.push(currentSection);
+  tabs.push(currentTab);
+
+  for (const field of fields) {
+    switch (field.fieldtype) {
+      case "Tab Break":
+        currentTab = { key: field.fieldname, label: field.label, sections: [] };
+        currentSection = { columns: [{ fields: [] }] };
+        currentTab.sections.push(currentSection);
+        tabs.push(currentTab);
+        break;
+      case "Section Break":
+        currentSection = { breakField: field, columns: [{ fields: [] }] };
+        currentTab.sections.push(currentSection);
+        break;
+      case "Column Break":
+        currentSection.columns.push({ fields: [] });
+        break;
+      default:
+        currentSection.columns[currentSection.columns.length - 1].fields.push(field);
+        break;
+    }
+  }
+  return tabs;
+}
+
+// ---------------------------------------------------------------------------
+// Doc-dependent resolution
+// ---------------------------------------------------------------------------
+
+export interface BuildTabsOptions {
+  fields: DocFieldMeta[];
+  doc: Record<string, unknown>;
+  /** docstatus of the loaded doc (0 draft / 1 submitted / 2 cancelled). */
+  docstatus: number;
+  /** Meta-level read_only or missing write permission. */
+  formReadOnly: boolean;
+  /** Create mode relaxes read_only_depends_on on unsaved values. */
+  isCreate: boolean;
+  /** Default label for the implicit first tab. */
+  detailsLabel: string;
+  /**
+   * Role-derived permlevel matrix (fieldPermissions.ts). Desk semantics:
+   * fields at a level without read HIDE; read without write → read-only.
+   * Undefined (fixtures / roles unavailable) → coarse fallback: any
+   * permlevel > 0 renders read-only, never hidden.
+   */
+  permLevels?: PermLevelMatrix;
+  /** Host-hidden fields (fieldnames) — dropped before layout resolution. */
+  hiddenFields?: readonly string[];
+  /**
+   * Host-hidden sections/tabs. Matches a Section Break's or Tab Break's
+   * fieldname OR label; the whole section (or tab) is dropped.
+   */
+  hiddenSections?: readonly string[];
+}
+
+function isFieldVisible(
+  field: DocFieldMeta,
+  doc: Record<string, unknown>,
+  permLevels?: PermLevelMatrix,
+): boolean {
+  if (field.hidden) return false;
+  // Desk hides fields whose permlevel the user cannot read (perm.js:209-215).
+  if (!canReadLevel(permLevels, field.permlevel ?? 0)) return false;
+  // Visibility fallback = true: an unparseable expression shows the field.
+  return evaluateDependsOn(field.depends_on, doc, true);
+}
+
+function toFieldSchema(
+  field: DocFieldMeta,
+  doc: Record<string, unknown>,
+  options: BuildTabsOptions,
+): FieldSchema {
+  const required =
+    !!field.reqd ||
+    (!!field.mandatory_depends_on && evaluateDependsOn(field.mandatory_depends_on, doc, false));
+
+  let readOnly =
+    !!field.read_only ||
+    (!!field.read_only_depends_on && evaluateDependsOn(field.read_only_depends_on, doc, false)) ||
+    !canWriteLevel(options.permLevels, field.permlevel ?? 0);
+  // set_only_once: editable only while the doc is unsaved (perm.js:261-263).
+  if (field.set_only_once && !options.isCreate) readOnly = true;
+  // fetch_from without fetch_if_empty locks the target while its source link
+  // holds a value (desk read_only_because_of_fetch_from).
+  if (!readOnly && isFetchLocked(field, doc)) readOnly = true;
+  if (options.docstatus === 1 && !field.allow_on_submit) readOnly = true;
+  if (options.docstatus === 2) readOnly = true;
+  if (options.formReadOnly) readOnly = true;
+
+  return {
+    type: field.fieldtype,
+    name: field.fieldname,
+    label: field.label,
+    options: field.options,
+    description: field.description,
+    required,
+    readOnly,
+    precision:
+      field.precision !== undefined && field.precision !== null && field.precision !== ""
+        ? Number(field.precision)
+        : undefined,
+    maxLength:
+      field.length !== undefined && field.length !== null && Number(field.length) > 0
+        ? Number(field.length)
+        : undefined,
+    // depends_on intentionally NOT forwarded — visibility resolved here.
+    fieldtype: field.fieldtype,
+    fieldname: field.fieldname,
+    in_list_view: field.in_list_view,
+    in_standard_filter: field.in_standard_filter,
+  };
+}
+
+/**
+ * Desk's refresh_section_collapse (layout.js:463-483): a collapsible section
+ * starts collapsed unless its `collapsible_depends_on` evaluates truthy, and
+ * a section with a missing mandatory value is forced open. Recomputed per
+ * doc change — SchemaForm treats it as the live default while manual toggles
+ * survive between recomputes.
+ */
+function resolveSectionCollapsed(
+  breakField: DocFieldMeta | undefined,
+  sectionFields: DocFieldMeta[],
+  doc: Record<string, unknown>,
+): boolean | undefined {
+  if (!breakField?.collapsible) return undefined;
+  let collapsed = true;
+  if (breakField.collapsible_depends_on) {
+    // Unparseable expression → expanded (never hide content silently).
+    collapsed = !evaluateDependsOn(breakField.collapsible_depends_on, doc, true);
+  }
+  if (collapsed && sectionHasMissingMandatory(sectionFields, doc)) collapsed = false;
+  return collapsed;
+}
+
+/** Desk section.has_missing_mandatory: `reqd && value == null` (section.js:146-156). */
+function sectionHasMissingMandatory(fields: DocFieldMeta[], doc: Record<string, unknown>): boolean {
+  return fields.some((field) => !!field.reqd && doc[field.fieldname] == null);
+}
+
+/**
+ * Build the desk tab list for the current doc state. Recomputed whenever
+ * the doc changes so depends_on chains re-resolve; the work is O(fields).
+ */
+export function buildFormTabs(options: BuildTabsOptions): FormTab[] {
+  const { fields, doc, detailsLabel, permLevels } = options;
+  const hiddenFieldSet = new Set(options.hiddenFields ?? []);
+  const hiddenSectionSet = new Set(options.hiddenSections ?? []);
+  const sectionHidden = (breakField: DocFieldMeta | undefined, label?: string): boolean => {
+    if (hiddenSectionSet.size === 0) return false;
+    if (breakField && hiddenSectionSet.has(breakField.fieldname)) return true;
+    const resolvedLabel = breakField?.label ?? label;
+    return !!resolvedLabel && hiddenSectionSet.has(resolvedLabel);
+  };
+  const layoutTabs = splitIntoTabs(fields);
+  const tabs: FormTab[] = [];
+
+  for (const layoutTab of layoutTabs) {
+    // Tab Break fields support depends_on + permlevel gating too (tab.js:38-43).
+    const tabBreak = fields.find(
+      (field) => field.fieldtype === "Tab Break" && field.fieldname === layoutTab.key,
+    );
+    if (tabBreak && !isFieldVisible(tabBreak, doc, permLevels)) continue;
+    // Host hiddenSections also match tabs (fieldname or label).
+    if (sectionHidden(tabBreak, layoutTab.label)) continue;
+
+    const sections: FormSection[] = [];
+    const flatFields: FieldSchema[] = [];
+
+    for (const section of layoutTab.sections) {
+      // Section Breaks are not permlevel-gated in desk (sections aren't
+      // controls; they only auto-hide when all their fields hide) — so the
+      // permlevel matrix is deliberately not passed here.
+      if (section.breakField && !isFieldVisible(section.breakField, doc)) continue;
+      if (sectionHidden(section.breakField)) continue;
+
+      const columns = section.columns
+        .map((column) => ({
+          fields: column.fields
+            .filter(
+              (field) =>
+                !hiddenFieldSet.has(field.fieldname) && isFieldVisible(field, doc, permLevels),
+            )
+            .map((field) => toFieldSchema(field, doc, options)),
+        }))
+        .filter((column) => column.fields.length > 0);
+      if (columns.length === 0) continue;
+
+      for (const column of columns) flatFields.push(...column.fields);
+      const sectionFields = section.columns.flatMap((column) => column.fields);
+      sections.push({
+        label: section.breakField?.label,
+        description: section.breakField?.description,
+        collapsible: !!section.breakField?.collapsible,
+        collapsed: resolveSectionCollapsed(section.breakField, sectionFields, doc),
+        hideBorder: !!section.breakField?.hide_border,
+        columns,
+      });
+    }
+
+    if (sections.length === 0) continue;
+    tabs.push({
+      key: layoutTab.key,
+      label: layoutTab.label || detailsLabel,
+      schema: { sections, fields: flatFields },
+    });
+  }
+
+  return tabs;
+}
+
+// ---------------------------------------------------------------------------
+// Create-mode defaults
+// ---------------------------------------------------------------------------
+
+const LAYOUT_TYPES = new Set(["Section Break", "Column Break", "Tab Break", "Fold"]);
+const NUMERIC_TYPES = new Set(["Int", "Float", "Currency", "Percent", "Check", "Rating"]);
+
+const todayISO = () => formatCalendarDate(new Date());
+const nowTime = () => formatCalendarDate(new Date(), "time");
+
+/**
+ * Seed a create-mode doc from meta field defaults — desk parity with
+ * create_new.js get_default_value / set_default_values:
+ *
+ * - `Today` → today's date; `now` → time (Time) / local datetime (else)
+ * - `__user` / `user` (Link/Data only, avoiding Select option collisions)
+ *   → session user
+ * - Select fields with no default seed their first option
+ *   (create_new.js:107-114)
+ * - `:fieldname` boot sysdefaults, `frappe.*`, `user_fullname` stay unset —
+ *   server-resolved on insert (documented gap)
+ */
+export function buildCreateDefaults(
+  fields: DocFieldMeta[],
+  currentUser?: string,
+): Record<string, unknown> {
+  const doc: Record<string, unknown> = {};
+  for (const field of fields) {
+    if (LAYOUT_TYPES.has(field.fieldtype)) continue;
+    const raw = field.default;
+    if (raw === undefined || raw === null || raw === "") {
+      // Desk seeds the first Select option when no default resolves.
+      if (
+        field.fieldtype === "Select" &&
+        typeof field.options === "string" &&
+        field.options &&
+        !["[Select]", "Loading..."].includes(field.options)
+      ) {
+        doc[field.fieldname] = field.options.split("\n")[0];
+      }
+      continue;
+    }
+    if (raw === "Today") {
+      doc[field.fieldname] = todayISO();
+      continue;
+    }
+    if (raw.toLowerCase() === "now") {
+      doc[field.fieldname] = field.fieldtype === "Time" ? nowTime() : `${todayISO()} ${nowTime()}`;
+      continue;
+    }
+    if (
+      raw === "__user" ||
+      (raw.toLowerCase() === "user" && (field.fieldtype === "Link" || field.fieldtype === "Data"))
+    ) {
+      if (currentUser) doc[field.fieldname] = currentUser;
+      continue;
+    }
+    if (raw === "user_fullname") continue; // session fullname not mirrored client-side
+    if (raw.startsWith(":") || raw.startsWith("frappe.")) continue; // server-resolved
+    doc[field.fieldname] = NUMERIC_TYPES.has(field.fieldtype) ? Number(raw) || 0 : raw;
+  }
+  return doc;
+}
+
+/**
+ * Copyable field values for Duplicate / Amend: strips standard bookkeeping
+ * fields, `no_copy` fields, layout breaks, and empty values.
+ */
+export function buildCopyValues(
+  fields: DocFieldMeta[],
+  doc: Record<string, unknown>,
+): Record<string, unknown> {
+  const copy: Record<string, unknown> = {};
+  for (const field of fields) {
+    if (LAYOUT_TYPES.has(field.fieldtype)) continue;
+    if (field.no_copy) continue;
+    if (field.fieldtype === "Attach" || field.fieldtype === "Attach Image") continue;
+    const value = doc[field.fieldname];
+    if (value === undefined || value === null || value === "") continue;
+    if (field.fieldtype === "Table" || field.fieldtype === "Table MultiSelect") {
+      if (Array.isArray(value)) {
+        copy[field.fieldname] = value.map((row) => {
+          const {
+            name: _name,
+            parent: _parent,
+            parentfield: _parentfield,
+            parenttype: _parenttype,
+            creation: _creation,
+            modified: _modified,
+            ...rest
+          } = (row ?? {}) as Record<string, unknown>;
+          return rest;
+        });
+      }
+      continue;
+    }
+    copy[field.fieldname] = value;
+  }
+  return copy;
+}
+
+/** True when the doctype names docs by user prompt (show a name input). */
+export function isPromptNamed(autoname?: string, namingRule?: string): boolean {
+  if (namingRule === 'By "Prompt"') return true;
+  return (autoname ?? "").toLowerCase() === "prompt";
+}

package/src/formEngine/index.ts

@@ -0,0 +1,33 @@
+/**
+ * The desk form engine.
+ *
+ * Frappe's desk resolves a form from meta at render time: tabs and sections
+ * from the layout breaks, visibility and read-only from `depends_on` chains,
+ * `permlevel`, `set_only_once`, `fetch_from`, `docstatus`, and a
+ * save/submit/cancel/amend lifecycle on top. All of that used to live in
+ * `@multiplatform.one/backoffice`, so an app author who imported the
+ * EXPORTED `FrappeForm` got a strictly weaker form than the desk rendered
+ * for the same doctype (MPO-15).
+ *
+ * It lives here now. `@multiplatform.one/backoffice` re-exports every name
+ * from its previous paths, so existing imports — barrel and
+ * `@multiplatform.one/backoffice/src/form/*` deep — keep resolving.
+ */
+
+export type { DocFieldMeta, DocLinkMeta, DocPermissionRule, DoctypeMeta } from "./doctypeMeta";
+
+export { buildPermLevelMatrix, canReadLevel, canWriteLevel } from "./fieldPermissions";
+export type { LevelPerm, PermLevelMatrix } from "./fieldPermissions";
+
+export { applyFetchedValues, buildFetchMap, isFetchLocked } from "./fetchFrom";
+export type { FetchMap, FetchRule } from "./fetchFrom";
+
+export { computeDirtyFields, isEmptyValue, isSameValue } from "./dirtyTracking";
+
+export { setCreatePrefill, takeCreatePrefill } from "./createPrefill";
+
+export { buildCopyValues, buildCreateDefaults, buildFormTabs, isPromptNamed } from "./formLayout";
+export type { BuildTabsOptions, FormTab } from "./formLayout";
+
+export { useFormEngine } from "./useFormEngine";
+export type { FormEngine } from "./useFormEngine";

package/src/formEngine/seam.spec.ts

@@ -0,0 +1,148 @@
+/**
+ * MPO-15 — the form-engine seam, from this side.
+ *
+ * The desk form engine used to live in `@multiplatform.one/backoffice`, one
+ * tier ABOVE this package, so `FrappeForm` could not reach it: an app author
+ * who imported the EXPORTED component got a strictly weaker form than the
+ * desk renders for the same doctype. The engine lives here now.
+ *
+ * Three things have to stay true for that to mean anything, and each one has
+ * broken silently in this repo before:
+ *
+ *  1. The engine is REACHABLE from the package barrel — a hoist that lands
+ *     the files but leaves them unexported moves the problem, not the code.
+ *  2. Nothing under `public/frappe-ui/src` imports `@multiplatform.one/`
+ *     `backoffice`. A lower tier importing a higher one is the defect the
+ *     hoist exists to remove; re-introducing it here would be a cycle
+ *     (backoffice already depends on this package).
+ *  3. The engine modules do not reach back up through the barrel either —
+ *     `formLayout` takes its FieldSchema/FormSchema types from the sibling
+ *     modules directly, so importing the engine never drags SchemaForm,
+ *     FrappeTable and the whole table/native stack into a node-ish consumer.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import * as formEngine from "./index";
+
+const engineDir = path.resolve(__dirname);
+const srcDir = path.resolve(__dirname, "..");
+
+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;
+    out.push(full);
+  }
+  return out;
+}
+
+/** Every name the engine barrel publishes (values and types alike). */
+const ENGINE_VALUES = [
+  "applyFetchedValues",
+  "buildCopyValues",
+  "buildCreateDefaults",
+  "buildFetchMap",
+  "buildFormTabs",
+  "buildPermLevelMatrix",
+  "canReadLevel",
+  "canWriteLevel",
+  "computeDirtyFields",
+  "isEmptyValue",
+  "isFetchLocked",
+  "isPromptNamed",
+  "isSameValue",
+  "setCreatePrefill",
+  "takeCreatePrefill",
+  "useFormEngine",
+] as const;
+
+/** Types the engine barrel publishes alongside those values. */
+const ENGINE_TYPES = [
+  "BuildTabsOptions",
+  "DocFieldMeta",
+  "DocLinkMeta",
+  "DocPermissionRule",
+  "DoctypeMeta",
+  "FetchMap",
+  "FetchRule",
+  "FormEngine",
+  "FormTab",
+  "LevelPerm",
+  "PermLevelMatrix",
+] as const;
+
+describe("form-engine seam (MPO-15)", () => {
+  it("hands every engine value out of ./formEngine", () => {
+    for (const name of ENGINE_VALUES) {
+      expect(
+        (formEngine as Record<string, unknown>)[name],
+        `./formEngine must export "${name}"`,
+      ).toBeTypeOf("function");
+    }
+  });
+
+  it("re-exports the whole engine from the package barrel", () => {
+    // Source-level, not a runtime import of ../index: pulling the full barrel
+    // in here would drag FrappeTable -> the table/forms stacks into what is
+    // otherwise a node-ish spec, for no extra signal (tests/exports.spec.ts
+    // already exercises the barrel at runtime).
+    const barrel = fs.readFileSync(path.resolve(srcDir, "index.ts"), "utf-8");
+    const block = barrel.slice(barrel.indexOf("Desk Form Engine"));
+    expect(block, "the barrel must carry a form-engine block").toContain('from "./formEngine"');
+    for (const name of [...ENGINE_VALUES, ...ENGINE_TYPES]) {
+      expect(block, `the barrel must re-export "${name}"`).toContain(name);
+    }
+  });
+
+  it("keeps formActions off both barrels (deep-import only, colliding names)", () => {
+    // `addComment`, `addTag`, `getCount`, `sendEmail` and friends collide with
+    // the list and shell surfaces; the dedicated "./formActions" subpath
+    // export is how a consumer reaches them.
+    for (const name of ["addComment", "addTag", "getCount", "sendEmail", "renameDoc"]) {
+      expect((formEngine as Record<string, unknown>)[name], name).toBeUndefined();
+    }
+    const pkg = JSON.parse(fs.readFileSync(path.resolve(srcDir, "../package.json"), "utf-8")) as {
+      exports: Record<string, { source?: string }>;
+    };
+    expect(pkg.exports["./formActions"]?.source).toBe("./src/formEngine/formActions.ts");
+  });
+
+  it("never imports the package that sits above it", () => {
+    for (const file of sourceFiles(srcDir)) {
+      const source = fs.readFileSync(file, "utf-8");
+      expect(source, file).not.toMatch(/from ["']@multiplatform\.one\/backoffice/);
+    }
+  });
+
+  it("keeps the engine off its own package barrel (no import cycle)", () => {
+    for (const file of sourceFiles(engineDir)) {
+      if (file.includes(".spec.")) continue;
+      const source = fs.readFileSync(file, "utf-8");
+      expect(source, file).not.toMatch(/from ["']@multiplatform\.one\/frappe-ui/);
+      expect(source, file).not.toMatch(/from ["']\.\.\/index["']/);
+    }
+  });
+
+  it("keeps the meta shapes here, where the engine that consumes them lives", () => {
+    const meta = fs.readFileSync(path.resolve(engineDir, "doctypeMeta.ts"), "utf-8");
+    for (const name of ["DocFieldMeta", "DocLinkMeta", "DocPermissionRule", "DoctypeMeta"]) {
+      expect(meta, name).toContain(`export interface ${name}`);
+    }
+    // The shapes reach the engine by relative import, never through the barrel.
+    for (const file of [
+      "formLayout.ts",
+      "fetchFrom.ts",
+      "fieldPermissions.ts",
+      "useFormEngine.ts",
+    ]) {
+      const source = fs.readFileSync(path.resolve(engineDir, file), "utf-8");
+      expect(source, file).not.toMatch(/shared\/useDoctypeMeta/);
+    }
+  });
+});