@multiplatform.one/backoffice 6.4.3 → 6.7.0

package/src/form/dependsOn.extra.spec.ts

@@ -0,0 +1,273 @@
+/**
+ * dependsOn — additional coverage on top of dependsOn.spec.ts (owned by the
+ * form workstream; new cases live here so the two files never collide).
+ * Focus: compileDependsOn API surface, nested doc paths, literals, strict
+ * operators, operator precedence, tokenizer edges, and fallback semantics.
+ */
+import { describe, expect, it } from "vitest";
+import { compileDependsOn, evaluateDependsOn } from "./dependsOn";
+
+describe("compileDependsOn", () => {
+  it("returns undefined for empty / blank expressions", () => {
+    expect(compileDependsOn(undefined)).toBeUndefined();
+    expect(compileDependsOn("")).toBeUndefined();
+    expect(compileDependsOn("   ")).toBeUndefined();
+  });
+
+  it("returns a reusable evaluator", () => {
+    const evaluator = compileDependsOn('eval:doc.status == "Open"');
+    expect(evaluator).toBeTypeOf("function");
+    expect(evaluator?.({ status: "Open" })).toBe(true);
+    expect(evaluator?.({ status: "Closed" })).toBe(false);
+  });
+
+  it("caches compiled evaluators per expression + fallback", () => {
+    const a = compileDependsOn("eval:doc.a && doc.b", true);
+    const b = compileDependsOn("eval:doc.a && doc.b", true);
+    expect(a).toBe(b);
+    // Different fallback → different cache entry (behavior may differ).
+    const c = compileDependsOn("eval:doc.a && doc.b", false);
+    expect(c).toBeTypeOf("function");
+  });
+});
+
+describe("nested doc paths", () => {
+  it("resolves doc.a.b chains", () => {
+    expect(
+      evaluateDependsOn('eval:doc.customer.status == "Active"', {
+        customer: { status: "Active" },
+      }),
+    ).toBe(true);
+    expect(
+      evaluateDependsOn('eval:doc.customer.status == "Active"', {
+        customer: { status: "Blocked" },
+      }),
+    ).toBe(false);
+  });
+
+  it("treats missing intermediate objects as undefined (falsy, no throw)", () => {
+    expect(evaluateDependsOn("eval:doc.customer.status", {})).toBe(false);
+    expect(evaluateDependsOn("eval:doc.customer.status", { customer: null })).toBe(false);
+  });
+});
+
+describe("literals", () => {
+  it("evaluates boolean literals", () => {
+    expect(evaluateDependsOn("eval:true", {})).toBe(true);
+    expect(evaluateDependsOn("eval:false", {})).toBe(false);
+  });
+
+  it("compares against null (nullish match, empty string is NOT null)", () => {
+    expect(evaluateDependsOn("eval:doc.parent == null", { parent: null })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.parent == null", {})).toBe(true);
+    expect(evaluateDependsOn("eval:doc.parent == null", { parent: "" })).toBe(false);
+    expect(evaluateDependsOn("eval:doc.parent != null", { parent: "PROJ-1" })).toBe(true);
+  });
+
+  it("handles negative and decimal number literals", () => {
+    expect(evaluateDependsOn("eval:doc.qty > -1", { qty: 0 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.rate >= 2.5", { rate: 2.5 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.rate >= 2.5", { rate: 2.49 })).toBe(false);
+  });
+
+  it("handles escaped quotes inside string literals", () => {
+    expect(evaluateDependsOn('eval:doc.note == "say \\"hi\\""', { note: 'say "hi"' })).toBe(true);
+  });
+});
+
+describe("strict equality", () => {
+  it("=== does not coerce across types", () => {
+    expect(evaluateDependsOn("eval:doc.qty === 1", { qty: 1 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.qty === 1", { qty: "1" })).toBe(false);
+  });
+
+  it("!== is the strict negation", () => {
+    expect(evaluateDependsOn("eval:doc.qty !== 1", { qty: "1" })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.qty !== 1", { qty: 1 })).toBe(false);
+  });
+});
+
+describe("comparison coercion", () => {
+  it("compares numeric strings numerically ('10' > '5')", () => {
+    expect(evaluateDependsOn("eval:doc.qty > doc.min", { qty: "10", min: "5" })).toBe(true);
+  });
+
+  it("returns false for non-numeric ordering comparisons", () => {
+    expect(evaluateDependsOn("eval:doc.status > 5", { status: "abc" })).toBe(false);
+    expect(evaluateDependsOn("eval:doc.status < 5", { status: "abc" })).toBe(false);
+  });
+});
+
+describe("operator precedence and grouping", () => {
+  it("binds && tighter than ||", () => {
+    // a || (b && c) — not (a || b) && c
+    expect(evaluateDependsOn("eval:doc.a || doc.b && doc.c", { a: 1, b: 1, c: 0 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.a || doc.b && doc.c", { a: 0, b: 1, c: 0 })).toBe(false);
+  });
+
+  it("parens override precedence", () => {
+    expect(evaluateDependsOn("eval:(doc.a || doc.b) && doc.c", { a: 1, b: 0, c: 0 })).toBe(false);
+    expect(evaluateDependsOn("eval:(doc.a || doc.b) && doc.c", { a: 1, b: 0, c: 1 })).toBe(true);
+  });
+
+  it("negates parenthesized groups and membership calls", () => {
+    expect(evaluateDependsOn("eval:!(doc.a && doc.b)", { a: 1, b: 0 })).toBe(true);
+    expect(evaluateDependsOn('eval:!in_list(["A","B"], doc.s)', { s: "C" })).toBe(true);
+    expect(evaluateDependsOn('eval:!["A","B"].includes(doc.s)', { s: "A" })).toBe(false);
+  });
+
+  it("tolerates extra whitespace", () => {
+    expect(evaluateDependsOn('eval:  doc.a   &&doc.status=="Open"', { a: 1, status: "Open" })).toBe(
+      true,
+    );
+  });
+});
+
+describe("membership coercion", () => {
+  it("matches numeric doc values against numeric array literals loosely", () => {
+    expect(evaluateDependsOn("eval:[1,2,3].includes(doc.idx)", { idx: "2" })).toBe(true);
+    expect(evaluateDependsOn("eval:[1,2,3].includes(doc.idx)", { idx: 4 })).toBe(false);
+  });
+});
+
+describe("frappe coercion helpers (cint/flt/cstr/cbool)", () => {
+  it("cint coerces check-ish values (real usage: User.change_password)", () => {
+    expect(
+      evaluateDependsOn("eval:doc.enabled && (!doc.__islocal || !cint(doc.send_welcome_email))", {
+        enabled: 1,
+        __islocal: 1,
+        send_welcome_email: "0",
+      }),
+    ).toBe(true);
+    expect(
+      evaluateDependsOn("eval:doc.enabled && (!doc.__islocal || !cint(doc.send_welcome_email))", {
+        enabled: 1,
+        __islocal: 1,
+        send_welcome_email: "1",
+      }),
+    ).toBe(false);
+  });
+
+  it("cint truncates and defaults to 0", () => {
+    expect(evaluateDependsOn("eval:cint(doc.qty) == 2", { qty: "2.9" })).toBe(true);
+    expect(evaluateDependsOn("eval:cint(doc.qty) == 0", {})).toBe(true);
+  });
+
+  it("flt parses decimals", () => {
+    expect(evaluateDependsOn("eval:flt(doc.rate) > 2.4", { rate: "2.5" })).toBe(true);
+    expect(evaluateDependsOn("eval:flt(doc.rate) > 2.4", { rate: "bad" })).toBe(false);
+  });
+
+  it("cstr stringifies nullish to empty", () => {
+    expect(evaluateDependsOn('eval:cstr(doc.note) == ""', {})).toBe(true);
+    expect(evaluateDependsOn('eval:cstr(doc.qty) == "3"', { qty: 3 })).toBe(true);
+  });
+});
+
+describe(".length on doc values", () => {
+  it("reads string length (real usage: User.bypass_restrict_ip_check…)", () => {
+    expect(
+      evaluateDependsOn("eval:doc.restrict_ip && doc.restrict_ip.length", {
+        restrict_ip: "10.0.0.1",
+      }),
+    ).toBe(true);
+    expect(
+      evaluateDependsOn("eval:doc.restrict_ip && doc.restrict_ip.length", { restrict_ip: "" }),
+    ).toBe(false);
+  });
+
+  it("reads array length", () => {
+    expect(evaluateDependsOn("eval:doc.items.length > 1", { items: [1, 2] })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.items.length > 1", { items: [] })).toBe(false);
+  });
+});
+
+describe("parent context (child tables)", () => {
+  it("resolves parent.fieldname when a parent doc is provided", () => {
+    expect(
+      evaluateDependsOn('eval:parent.status == "Open"', { qty: 1 }, true, { status: "Open" }),
+    ).toBe(true);
+    expect(
+      evaluateDependsOn('eval:parent.status == "Open"', { qty: 1 }, true, { status: "Closed" }),
+    ).toBe(false);
+  });
+
+  it("mixes doc and parent references", () => {
+    expect(
+      evaluateDependsOn("eval:doc.qty > 0 && parent.enabled", { qty: 2 }, false, { enabled: 1 }),
+    ).toBe(true);
+  });
+
+  it("falls back when parent is referenced but not in scope", () => {
+    expect(evaluateDependsOn("eval:parent.status", { qty: 1 }, true)).toBe(true);
+    expect(evaluateDependsOn("eval:parent.status", { qty: 1 }, false)).toBe(false);
+  });
+});
+
+describe("frappe.session.user", () => {
+  it("resolves from the injected __session_user key", () => {
+    expect(
+      evaluateDependsOn("eval:doc.owner == frappe.session.user", {
+        owner: "admin@example.com",
+        __session_user: "admin@example.com",
+      }),
+    ).toBe(true);
+    expect(
+      evaluateDependsOn("eval:doc.owner == frappe.session.user", {
+        owner: "someone@example.com",
+        __session_user: "admin@example.com",
+      }),
+    ).toBe(false);
+  });
+
+  it("falls back when the session user is not injected", () => {
+    expect(evaluateDependsOn("eval:doc.owner == frappe.session.user", { owner: "x" }, true)).toBe(
+      true,
+    );
+    expect(evaluateDependsOn("eval:doc.owner == frappe.session.user", { owner: "x" }, false)).toBe(
+      false,
+    );
+  });
+});
+
+describe("__islocal ambient flag", () => {
+  it("reads like any doc key (callers inject it)", () => {
+    expect(evaluateDependsOn("eval:doc.__islocal", { __islocal: 1 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.__islocal", { __islocal: 0 })).toBe(false);
+    expect(evaluateDependsOn("eval:!doc.__islocal", { __islocal: 0 })).toBe(true);
+  });
+});
+
+describe("bare-fieldname array truthiness", () => {
+  it("counts rows for array values (desk: array → !!length)", () => {
+    expect(evaluateDependsOn("items", { items: [{}] })).toBe(true);
+    expect(evaluateDependsOn("items", { items: [] })).toBe(false);
+  });
+});
+
+describe("fallback semantics on unparseable expressions", () => {
+  it("falls back on arithmetic (documented gap)", () => {
+    expect(evaluateDependsOn("eval:doc.qty + 1 > 2", { qty: 5 }, true)).toBe(true);
+    expect(evaluateDependsOn("eval:doc.qty + 1 > 2", { qty: 5 }, false)).toBe(false);
+  });
+
+  it("falls back on unterminated strings", () => {
+    expect(evaluateDependsOn('eval:doc.status == "Open', { status: "Open" }, true)).toBe(true);
+    expect(evaluateDependsOn('eval:doc.status == "Open', { status: "Open" }, false)).toBe(false);
+  });
+
+  it("falls back on trailing garbage after a valid expression", () => {
+    expect(evaluateDependsOn("eval:doc.a doc.b", { a: 1, b: 1 }, false)).toBe(false);
+  });
+
+  it("falls back on method calls outside the safe subset", () => {
+    expect(evaluateDependsOn('eval:doc.name.startsWith("SAL")', { name: "SAL-1" }, false)).toBe(
+      false,
+    );
+  });
+
+  it("falls back on empty eval: body", () => {
+    expect(evaluateDependsOn("eval:", {}, true)).toBe(true);
+    expect(evaluateDependsOn("eval:", {}, false)).toBe(false);
+  });
+});

package/src/form/dependsOn.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { evaluateDependsOn } from "./dependsOn";
+
+describe("evaluateDependsOn", () => {
+  it("returns true for empty expressions", () => {
+    expect(evaluateDependsOn(undefined, {})).toBe(true);
+    expect(evaluateDependsOn("", {})).toBe(true);
+  });
+
+  it("evaluates bare fieldname truthiness", () => {
+    expect(evaluateDependsOn("status", { status: "Open" })).toBe(true);
+    expect(evaluateDependsOn("status", { status: "" })).toBe(false);
+    expect(evaluateDependsOn("archived", { archived: 0 })).toBe(false);
+    expect(evaluateDependsOn("archived", { archived: 1 })).toBe(true);
+    expect(evaluateDependsOn("missing", {})).toBe(false);
+  });
+
+  it("evaluates eval: equality comparisons", () => {
+    expect(evaluateDependsOn('eval:doc.status == "Open"', { status: "Open" })).toBe(true);
+    expect(evaluateDependsOn('eval:doc.status == "Open"', { status: "Closed" })).toBe(false);
+    expect(evaluateDependsOn("eval:doc.status == 'Open'", { status: "Open" })).toBe(true);
+    expect(evaluateDependsOn('eval:doc.status != "Open"', { status: "Closed" })).toBe(true);
+    expect(evaluateDependsOn('eval:doc.status === "Open"', { status: "Open" })).toBe(true);
+  });
+
+  it("coerces loosely like frappe (numbers vs strings, check fields)", () => {
+    expect(evaluateDependsOn("eval:doc.qty == 1", { qty: "1" })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.enabled == 1", { enabled: 1 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.enabled != 1", { enabled: 0 })).toBe(true);
+  });
+
+  it("evaluates numeric comparisons", () => {
+    expect(evaluateDependsOn("eval:doc.qty > 5", { qty: 6 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.qty >= 5", { qty: 5 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.qty < 5", { qty: 6 })).toBe(false);
+    expect(evaluateDependsOn("eval:doc.qty <= 4", { qty: 4 })).toBe(true);
+  });
+
+  it("evaluates boolean composition and negation", () => {
+    expect(evaluateDependsOn("eval:doc.a && doc.b", { a: 1, b: 1 })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.a && doc.b", { a: 1, b: 0 })).toBe(false);
+    expect(evaluateDependsOn("eval:doc.a || doc.b", { a: 0, b: 1 })).toBe(true);
+    expect(evaluateDependsOn("eval:!doc.a", { a: 0 })).toBe(true);
+    expect(
+      evaluateDependsOn('eval:doc.a && (doc.b || doc.status == "X")', {
+        a: 1,
+        b: 0,
+        status: "X",
+      }),
+    ).toBe(true);
+  });
+
+  it("evaluates bare doc.field truthiness inside eval", () => {
+    expect(evaluateDependsOn("eval:doc.priority", { priority: "High" })).toBe(true);
+    expect(evaluateDependsOn("eval:doc.priority", { priority: "" })).toBe(false);
+  });
+
+  it("evaluates membership forms", () => {
+    expect(
+      evaluateDependsOn('eval:["Open","Closed"].includes(doc.status)', { status: "Open" }),
+    ).toBe(true);
+    expect(
+      evaluateDependsOn('eval:["Open","Closed"].includes(doc.status)', { status: "Other" }),
+    ).toBe(false);
+    expect(
+      evaluateDependsOn('eval:in_list(["Open","Closed"], doc.status)', { status: "Closed" }),
+    ).toBe(true);
+  });
+
+  it("falls back on unparseable expressions", () => {
+    expect(evaluateDependsOn("eval:frappe.session.user == doc.owner", {}, true)).toBe(true);
+    expect(evaluateDependsOn("eval:frappe.session.user == doc.owner", {}, false)).toBe(false);
+    expect(evaluateDependsOn("eval:cint(doc.qty) > 2", { qty: 5 }, true)).toBe(true);
+  });
+});

package/src/form/dependsOn.ts

@@ -0,0 +1,22 @@
+/**
+ * Safe evaluator for Frappe `depends_on` / `mandatory_depends_on` /
+ * `read_only_depends_on` expressions.
+ *
+ * The implementation lives in `@multiplatform.one/frappe-ui/src/dependsOn`
+ * so SchemaForm (which receives raw `depends_on` strings on the standalone
+ * FrappeForm path) shares the exact same Hermes/GJS/CSP-safe parser instead
+ * of a string-eval fork. This module re-exports it for the backoffice form
+ * engine; the specs next door exercise the shared source. Grammar coverage
+ * and fallback semantics are documented at the implementation.
+ */
+
+// Dedicated "./dependsOn" subpath (see frappe-ui package.json exports): keeps
+// the node-environment specs next door from dragging the full frappe-ui barrel
+// (FrappeTable → table dist → react-native) into a DOM-less run, while still
+// resolving under Vite/Storybook (the old extension-less "./src/*" path did not).
+export {
+  compileDependsOn,
+  evaluateDependsOn,
+  type DependsDoc,
+  type DependsEvaluator,
+} from "@multiplatform.one/frappe-ui/dependsOn";

package/src/form/dirtyTracking.spec.ts

@@ -0,0 +1,91 @@
+// R-1 false "Not Saved": engine-level dirty-tracking contract.
+// An untouched existing doc must read pristine, a real edit must read dirty,
+// create mode must read dirty from applied defaults (desk parity).
+import { describe, expect, it } from "vitest";
+import { computeDirtyFields, isSameValue } from "./dirtyTracking";
+
+describe("isSameValue (normalization-insensitive equality)", () => {
+  it("treats null / undefined / empty string / empty array as one empty state", () => {
+    expect(isSameValue(null, "")).toBe(true);
+    expect(isSameValue(undefined, "")).toBe(true);
+    expect(isSameValue(null, undefined)).toBe(true);
+    expect(isSameValue([], null)).toBe(true);
+    expect(isSameValue("  ", "")).toBe(true);
+  });
+
+  it("folds boolean and wire 0/1 representations", () => {
+    expect(isSameValue(false, 0)).toBe(true);
+    expect(isSameValue(true, 1)).toBe(true);
+    expect(isSameValue(0, false)).toBe(true);
+    expect(isSameValue(true, 0)).toBe(false);
+    expect(isSameValue(false, 1)).toBe(false);
+  });
+
+  it("does not conflate empty with falsy non-empty values", () => {
+    expect(isSameValue(0, "")).toBe(false);
+    expect(isSameValue(false, "")).toBe(false);
+    expect(isSameValue(0, null)).toBe(false);
+  });
+
+  it("stays strict for real values — no deep equality", () => {
+    expect(isSameValue("a", "a")).toBe(true);
+    expect(isSameValue("a", "b")).toBe(false);
+    // Distinct array/object identities read as different even when
+    // structurally equal (deliberate: no deep-equality time bombs).
+    expect(isSameValue([{ a: 1 }], [{ a: 1 }])).toBe(false);
+    // Representation changes of real content are edits (the field layer is
+    // responsible for not emitting them during initialization).
+    expect(isSameValue("plain", "<p>plain</p>")).toBe(false);
+  });
+});
+
+describe("computeDirtyFields", () => {
+  const baseline = {
+    doctype: "ToDo",
+    name: "abc",
+    description: "hello",
+    status: "Open",
+    color: null,
+    priority: "Medium",
+    date: "2026-08-12",
+    checked: 0,
+  };
+
+  it("existing doc mount: local === baseline snapshot reads pristine", () => {
+    expect(computeDirtyFields({ ...baseline }, baseline)).toEqual([]);
+  });
+
+  it("field re-representation during init does not dirty (null→'' and 0→false)", () => {
+    const local = { ...baseline, color: "", checked: false };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("a real edit reads dirty", () => {
+    const local = { ...baseline, description: "hello edited" };
+    expect(computeDirtyFields(local, baseline)).toEqual(["description"]);
+  });
+
+  it("revert to the exact baseline value reads clean again", () => {
+    // Documented behavior: value equality, not edit history — typing and
+    // deleting back to the original string is pristine. An equivalent-but-
+    // differently-represented value (e.g. tiptap-normalized HTML) would
+    // still read dirty, which matches desk.
+    const local = { ...baseline, description: "hello" };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("bookkeeping keys never dirty", () => {
+    const local = { ...baseline, name: "renamed", doctype: "Other" };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("new doc (no baseline) with applied create-defaults reads dirty — desk parity", () => {
+    const local = { doctype: "ToDo", status: "Open", priority: "Medium", description: "" };
+    expect(computeDirtyFields(local, undefined)).toEqual(["status", "priority"]);
+  });
+
+  it("new doc with only empty values reads pristine", () => {
+    const local = { doctype: "ToDo", description: "", color: null };
+    expect(computeDirtyFields(local, undefined)).toEqual([]);
+  });
+});

package/src/form/dirtyTracking.ts

@@ -0,0 +1,64 @@
+/**
+ * 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).
+ */
+
+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;
+}

package/src/form/docinfo.ts

@@ -0,0 +1,24 @@
+/**
+ * Docinfo permission normalization.
+ *
+ * The docinfo fetch itself lives in shared/useDocinfo (one deduped
+ * get_docinfo per document shared by the sidebar / timeline / form screen);
+ * the unused local `useDocInfo` getdoc loader was pruned by the integrator.
+ *
+ * NOTE: this bench returns `permissions: {"null": 0}` for token-auth users —
+ * an upstream quirk. `normalizeDocPermissions` treats a payload without a
+ * real `read` key as unusable and callers fall back to meta role rules.
+ */
+
+/**
+ * Returns per-doc permission flags when the payload is usable, else
+ * undefined (fall back to meta role rules). See module note on the
+ * `{"null": 0}` quirk.
+ */
+export function normalizeDocPermissions(
+  permissions: Record<string, number> | undefined,
+): Record<string, number> | undefined {
+  if (!permissions) return undefined;
+  if (!("read" in permissions)) return undefined;
+  return permissions;
+}

package/src/form/fetchFrom.spec.ts

@@ -0,0 +1,92 @@
+/**
+ * fetchFrom — fetch_from preview parity with desk script_manager.js
+ * setup_add_fetch + link.js validate_link_and_fetch.
+ */
+import { describe, expect, it } from "vitest";
+import type { DocFieldMeta } from "../shared/useDoctypeMeta";
+import { applyFetchedValues, buildFetchMap, isFetchLocked } from "./fetchFrom";
+
+function field(overrides: Partial<DocFieldMeta> & { fieldname: string }): DocFieldMeta {
+  return { fieldtype: "Data", ...overrides };
+}
+
+describe("buildFetchMap", () => {
+  it("registers scalar fieldtypes keyed by their link field", () => {
+    const map = buildFetchMap([
+      field({ fieldname: "customer", fieldtype: "Link", options: "Customer" }),
+      field({ fieldname: "customer_name", fetch_from: "customer.customer_name" }),
+      field({ fieldname: "territory", fieldtype: "Select", fetch_from: "customer.territory" }),
+    ]);
+    expect(map.get("customer")).toEqual([
+      { target: "customer_name", source: "customer_name", fetchIfEmpty: false },
+      { target: "territory", source: "territory", fetchIfEmpty: false },
+    ]);
+  });
+
+  it("skips fetch_from without a dot and non-registered fieldtypes", () => {
+    const map = buildFetchMap([
+      field({ fieldname: "bad", fetch_from: "customer" }),
+      field({ fieldname: "html", fieldtype: "HTML", fetch_from: "customer.blurb" }),
+    ]);
+    expect(map.size).toBe(0);
+  });
+
+  it("includes non-scalar fieldtypes when read_only (script_manager gate)", () => {
+    const map = buildFetchMap([
+      field({
+        fieldname: "blurb",
+        fieldtype: "HTML Editor",
+        fetch_from: "customer.blurb",
+        read_only: 1,
+      }),
+    ]);
+    expect(map.get("customer")).toHaveLength(1);
+  });
+
+  it("records fetch_if_empty", () => {
+    const map = buildFetchMap([
+      field({ fieldname: "note", fetch_from: "customer.note", fetch_if_empty: 1 }),
+    ]);
+    expect(map.get("customer")?.[0].fetchIfEmpty).toBe(true);
+  });
+});
+
+describe("applyFetchedValues", () => {
+  const rules = [
+    { target: "customer_name", source: "customer_name", fetchIfEmpty: false },
+    { target: "note", source: "note", fetchIfEmpty: true },
+  ];
+
+  it("writes fetched values onto targets", () => {
+    const patch = applyFetchedValues(rules, { customer_name: "Acme", note: "VIP" }, {});
+    expect(patch).toEqual({ customer_name: "Acme", note: "VIP" });
+  });
+
+  it("fetch_if_empty targets keep an existing value", () => {
+    const patch = applyFetchedValues(
+      rules,
+      { customer_name: "Acme", note: "VIP" },
+      { note: "user wrote this" },
+    );
+    expect(patch).toEqual({ customer_name: "Acme" });
+  });
+
+  it("clearing the link blanks plain targets but spares fetch_if_empty values", () => {
+    const patch = applyFetchedValues(rules, {}, { customer_name: "Acme", note: "mine" });
+    expect(patch).toEqual({ customer_name: "" });
+  });
+});
+
+describe("isFetchLocked", () => {
+  it("locks while the source link holds a value, unless fetch_if_empty", () => {
+    const target = field({ fieldname: "customer_name", fetch_from: "customer.customer_name" });
+    expect(isFetchLocked(target, { customer: "CUST-1" })).toBe(true);
+    expect(isFetchLocked(target, {})).toBe(false);
+    const softTarget = field({
+      fieldname: "note",
+      fetch_from: "customer.note",
+      fetch_if_empty: 1,
+    });
+    expect(isFetchLocked(softTarget, { customer: "CUST-1" })).toBe(false);
+  });
+});