@multiplatform.one/backoffice 7.28.0 → 7.29.0

package/src/form/DocFormScreen.tsx

@@ -1,12 +1,13 @@
 import React from "react";
 /**
- * The document form page — desk form parity.
+ * The document form page — desk form parity, as page chrome over FrappeForm.
  *
  * Composition:
  *   FormToolbar   breadcrumbs / title (title_field) / status chip /
  *                 Save → Submit → Cancel/Amend lifecycle / ⋯ menu
- *   FormBody      meta-driven tabs → SchemaForm sections/columns/fields
- *                 (safe depends_on engine in formLayout.ts)
+ *   FrappeForm    the fields: tabs, sections, columns and every rule that
+ *                 decides what renders, from the controller useFrappeForm
+ *                 returns (the same engine a bare <FrappeForm> runs)
  *   Sidebar       assignments / attachments / tags / shares / likes / follow
  *   Timeline      docinfo comments + versions + communications interleaved
  *   Connections   linked-doctype tiles with live counts
@@ -17,24 +18,27 @@ import React from "react";
  */
 
 import {
+  AsyncBoundary,
   AsyncSkeleton,
   Button,
   ConfirmDialog,
   EmptyState,
   ScrollView,
-  Tabs,
   Text,
   XStack,
   YStack,
   notify,
-  type TabsItem,
 } from "@multiplatform.one/components";
-import { Input } from "@multiplatform.one/forms";
 import {
-  SchemaForm,
-  sessionDocRights,
+  FrappeForm,
+  docinfoRights,
+  fixtureDocRights,
+  isPermissionError,
+  refusalReason,
   useFrappeConfig,
+  useFrappeForm,
   type DocShareGrant,
+  type FormTab,
 } from "@multiplatform.one/frappe-ui";
 import { useLayoutSizeClass, useResolvedKnobs } from "@multiplatform.one/theme";
 import { ListBulletsIcon } from "@phosphor-icons/react";
@@ -54,10 +58,8 @@ import { getListNavNeighbors, type ListNavNeighbors } from "../shared/listNavCon
 import { invalidateDocinfo, useDocinfo } from "../shared/useDocinfo";
 import { useRecentVisit } from "../shared/useRecentVisit";
 import { useDoctypeMeta } from "../shared/useDoctypeMeta";
-import { useUserRoles } from "../shared/useUserRoles";
+import { groupConnectionLinks } from "./connections-data";
 import { setCreatePrefill } from "./createPrefill";
-import { normalizeDocPermissions } from "./docinfo";
-import { buildPermLevelMatrix } from "./fieldPermissions";
 import { createHttpClient, renameDoc, sendEmail } from "./formActions";
 import {
   EmailDialog,
@@ -66,7 +68,6 @@ import {
   type JumpToFieldTarget,
 } from "./FormDialogs";
 import { FormErrorBoundary, wrapFieldWithErrorBoundary } from "./FormErrorBoundary";
-import { buildCopyValues, buildFormTabs, isPromptNamed } from "./formLayout";
 import { FormConnections } from "./FormConnections";
 import { FormHeaderCluster } from "./FormHeaderCluster";
 import { FormSidebarPanel } from "./FormSidebarPanel";
@@ -82,7 +83,6 @@ import {
   useNavigationDirtyGuard,
   useSaveShortcut,
 } from "./platformHooks";
-import { useFormEngine } from "./useFormEngine";
 
 /** Host overrides for the form's ⋯ toolbar menu. */
 export interface DocFormActionOverrides {
@@ -102,9 +102,9 @@ export interface DocFormScreenProps {
   name: string;
   /** Force the whole form read-only regardless of permissions. */
   readOnly?: boolean;
-  /** Hide form sections/tabs by Section/Tab Break fieldname or label. */
+  /** Hide form sections/tabs by Section/Tab Break name or label. */
   hiddenSections?: readonly string[];
-  /** Hide individual fields by fieldname. */
+  /** Hide individual fields by name. */
   hiddenFields?: readonly string[];
   /** Create-mode field prefill (merged over meta defaults). */
   defaults?: Record<string, unknown>;
@@ -118,6 +118,8 @@ export interface DocFormScreenProps {
 
 const CONNECTIONS_TAB = "__connections";
 
+type DeskDoc = Record<string, unknown> & { name: string; doctype: string };
+
 export function DocFormScreen({
   doctype,
   name,
@@ -153,8 +155,8 @@ export function DocFormScreen({
 
   // `defaults` prop rides the SAME one-shot stash Duplicate/Amend and the
   // `?d=` route param use (createPrefill) — stashed in a memo (not an
-  // effect) so the values land before useFormEngine's create-mode seeding
-  // runs, and keyed on content so re-renders don't re-stash consumed values.
+  // effect) so the values land before the form's create-mode seeding runs,
+  // and keyed on content so re-renders don't re-stash consumed values.
   const defaultsKey = defaults ? JSON.stringify(defaults) : undefined;
   useMemo(() => {
     if (!isCreate || !defaultsKey) return;
@@ -167,24 +169,8 @@ export function DocFormScreen({
     if (!isCreate) emitEvent({ type: "doc-opened", doctype, name });
   }, [isCreate, doctype, name, emitEvent]);
 
-  const connection = useMemo(
-    () =>
-      config?.baseURL
-        ? {
-            baseURL: config.baseURL,
-            socketPort: config.socketPort,
-            siteName: config.siteName,
-            socketBaseURL: config.socketBaseURL,
-            auth: config.auth,
-            syncOptions: config.syncOptions,
-            fixtures: config.fixtures,
-          }
-        : undefined,
-    [config],
-  );
-
   // One meta loader for the whole screen (shared getdoctype cache with the
-  // fixture branch for stories) — the engine, sidebar, and connections all
+  // fixture branch for stories) — the form, sidebar, and connections all
   // read the same bundle.
   const {
     meta,
@@ -192,11 +178,14 @@ export function DocFormScreen({
     error: metaError,
     reload: refetchMeta,
   } = useDoctypeMeta(doctype);
-  const engine = useFormEngine(connection, doctype, docName, meta, t);
-
-  useEffect(() => {
-    if (metaError && !meta) emitEvent({ type: "error", error: metaError, context: "form-meta" });
-  }, [metaError, meta, emitEvent]);
+  const metaSource = useMemo(
+    () => ({ meta, isLoading: isMetaLoading, error: metaError }),
+    [meta, isMetaLoading, metaError],
+  );
+  // Guest is refused getdoctype while it may still read the record (LC-96):
+  // FrappeForm then lays the record out read-only, and the page offers
+  // nothing that needs the meta or the docinfo Guest can't read either.
+  const metaRefused = !meta && metaError !== undefined && isPermissionError(metaError);
 
   // Shared docinfo — one get_docinfo fetch shared with the header cluster,
   // sidebar, and timeline panels; the screen reads the permission flags and
@@ -207,10 +196,42 @@ export function DocFormScreen({
     reloadDocinfo();
   }, [doctype, docName, reloadDocinfo]);
 
+  // Rights: the bench's per-record answer (docinfo) when it gave one, else the
+  // session's (the form resolves those). Fixture mode has no session and
+  // keeps what the doctype's rows grant.
+  const fixtureMode = Boolean(config?.fixtures);
+  const rights = useMemo(
+    () =>
+      docinfoRights(docinfo?.permissions as Record<string, unknown> | undefined) ??
+      (fixtureMode ? fixtureDocRights(meta) : undefined),
+    [docinfo?.permissions, fixtureMode, meta],
+  );
+
+  const form = useFrappeForm<DeskDoc>({
+    doctype,
+    name: docName,
+    meta: metaSource,
+    rights,
+    shares: docinfo?.shared as DocShareGrant[] | undefined,
+    readShares: false,
+    disabled: readOnly,
+    hideFields: hiddenFields,
+    hideSections: hiddenSections,
+  });
+  const connection = form.connection;
+  const currentUser = form.user ?? "";
+  const perms = form.rights;
+
+  useEffect(() => {
+    if (metaError && !meta && !metaRefused) {
+      emitEvent({ type: "error", error: metaError, context: "form-meta" });
+    }
+  }, [metaError, meta, metaRefused, emitEvent]);
+
   // Refresh docinfo whenever the live doc's `modified` stamp moves —
   // an external edit usually lands with new versions/comments too.
   const modifiedStamp =
-    typeof engine.baseline?.modified === "string" ? engine.baseline.modified : undefined;
+    typeof form.baseline?.modified === "string" ? form.baseline.modified : undefined;
   const stampRef = useRef<string | undefined>(undefined);
   useEffect(() => {
     stampRef.current = undefined;
@@ -226,133 +247,13 @@ export function DocFormScreen({
     }
   }, [modifiedStamp, docName, doctype, reloadDocinfo]);
 
-  // -----------------------------------------------------------------------
-  // Permissions: per-doc flags from docinfo when usable, else the session's
-  // roles against meta's DocPerm rows (sessionDocRights). Fixture mode has no
-  // session, so it keeps the union of every role's rows.
-  // -----------------------------------------------------------------------
-  const { roles, user: sessionUser } = useUserRoles();
-  const fixtureMode = Boolean(config?.fixtures);
-  const recordOwner =
-    !isCreate && typeof engine.baseline?.owner === "string" ? engine.baseline.owner : undefined;
-  const perms = useMemo(() => {
-    const docPerms = normalizeDocPermissions(
-      docinfo?.permissions as Record<string, number> | undefined,
-    );
-    if (docPerms) {
-      return {
-        write: !!docPerms.write,
-        create: !!docPerms.create,
-        delete: !!docPerms.delete,
-        submit: !!docPerms.submit,
-        cancel: !!docPerms.cancel,
-        amend: !!docPerms.amend,
-        email: !!docPerms.email,
-        print: !!docPerms.print,
-      };
-    }
-    if (!fixtureMode) {
-      const rights = sessionDocRights({
-        fixtures: false,
-        meta,
-        roles,
-        user: sessionUser,
-        owner: recordOwner,
-        shares: docinfo?.shared as DocShareGrant[] | undefined,
-      });
-      return {
-        write: rights.write,
-        create: rights.create,
-        delete: rights.delete,
-        submit: rights.submit,
-        cancel: rights.cancel,
-        amend: rights.amend,
-        email: rights.email,
-        print: rights.print,
-      };
-    }
-    const rules = meta?.permissions ?? [];
-    const anyRole = (key: keyof (typeof rules)[number]) =>
-      rules.some((rule) => !rule.permlevel && !!rule[key]);
-    return {
-      write: rules.length === 0 || anyRole("write"),
-      create: rules.length === 0 || anyRole("create"),
-      delete: anyRole("delete"),
-      submit: anyRole("submit"),
-      cancel: anyRole("cancel"),
-      amend: anyRole("amend"),
-      email: rules.length === 0 || anyRole("email"),
-      print: rules.length === 0 || anyRole("print"),
-    };
-  }, [docinfo?.permissions, docinfo?.shared, meta, fixtureMode, roles, sessionUser, recordOwner]);
+  const isSubmittable = form.isSubmittable;
+  const formReadOnly = form.readOnly;
+  const jumpTargets = form.fieldTargets;
 
-  const isSubmittable = !!meta?.is_submittable;
-  const formReadOnly =
-    !!readOnly ||
-    !!meta?.read_only ||
-    engine.wasDeleted ||
-    (!isCreate && !perms.write) ||
-    (isCreate && !perms.create);
-
-  // -----------------------------------------------------------------------
-  // Body tabs (meta + doc → SchemaForm schemas) + Connections
-  // -----------------------------------------------------------------------
-  // Permlevel matrix: session roles × meta.permissions (desk perm.js). Roles
-  // stay undefined in fixture mode → coarse permlevel>0 read-only fallback.
-  const permLevels = useMemo(
-    () => buildPermLevelMatrix(meta?.permissions, roles),
-    [meta?.permissions, roles],
-  );
-  const formTabs = useMemo(() => {
-    if (!meta) return [];
-    return buildFormTabs({
-      fields: meta.fields,
-      // depends_on evaluates against the doc plus desk's ambient context:
-      // __islocal (unsaved doc flag) and the session user behind
-      // `frappe.session.user` references.
-      doc: {
-        ...engine.doc,
-        __islocal: isCreate ? 1 : 0,
-        ...(engine.currentUser ? { __session_user: engine.currentUser } : {}),
-      },
-      docstatus: engine.docstatus,
-      formReadOnly,
-      isCreate,
-      detailsLabel: t("detailsTab", "Details"),
-      permLevels,
-      hiddenFields,
-      hiddenSections,
-    });
-  }, [
-    meta,
-    engine.doc,
-    engine.currentUser,
-    engine.docstatus,
-    formReadOnly,
-    isCreate,
-    permLevels,
-    hiddenFields,
-    hiddenSections,
-    t,
-  ]);
-
-  const jumpTargets = useMemo<JumpToFieldTarget[]>(
-    () =>
-      formTabs.flatMap((tab) =>
-        tab.schema.fields.map((field) => ({
-          name: field.name,
-          label: field.label || field.name,
-          tabKey: tab.key,
-          tabLabel: tab.label,
-        })),
-      ),
-    [formTabs],
-  );
-
-  const [activeTab, setActiveTab] = useState<string | undefined>(undefined);
-  // Hidden link rows never render (desk parity — connections-data skips them).
-  const showConnections =
-    !isCreate && !!connection && (meta?.links?.some((link) => !link.hidden) ?? false);
+  // Connections render what FormConnections groups (connections-data skips
+  // the link rows a doctype hides, desk parity).
+  const showConnections = !isCreate && !!connection && groupConnectionLinks(meta).length > 0;
 
   // -----------------------------------------------------------------------
   // Navigation with dirty guard
@@ -360,18 +261,18 @@ export function DocFormScreen({
   const [pendingNav, setPendingNav] = useState<string | undefined>(undefined);
   const navigate = useCallback(
     (href: string) => {
-      if (engine.isDirty) {
+      if (form.isDirty) {
         setPendingNav(href);
         return;
       }
       navigator.navigate(href);
     },
-    [engine.isDirty, navigator],
+    [form.isDirty, navigator],
   );
-  useBeforeUnloadGuard(engine.isDirty);
+  useBeforeUnloadGuard(form.isDirty);
   // Covers back navigations that skip navigate(): browser back on web,
   // back gesture/button on native (B7).
-  const backGuard = useNavigationDirtyGuard(engine.isDirty);
+  const backGuard = useNavigationDirtyGuard(form.isDirty);
 
   // -----------------------------------------------------------------------
   // Actions
@@ -389,13 +290,10 @@ export function DocFormScreen({
   const handleSave = useCallback(async () => {
     // Pre-check required fields so the failing tab is surfaced — inline
     // errors on an inactive tab would otherwise fail invisibly.
-    const validationErrors = engine.validate();
+    const validationErrors = form.validate();
     const errorFields = Object.keys(validationErrors);
     if (errorFields.length > 0) {
-      const owner = formTabs.find((tab) =>
-        tab.schema.fields.some((field) => errorFields.includes(field.name)),
-      );
-      if (owner) setActiveTab(owner.key);
+      errorFields.some((field) => form.revealField(field));
       setValidationSummary(
         t("validationSummary", {
           count: errorFields.length,
@@ -406,12 +304,12 @@ export function DocFormScreen({
     } else {
       setValidationSummary(undefined);
     }
-    const savedName = await engine.save();
+    const savedName = await form.save();
     if (!savedName) return;
     setValidationSummary(undefined);
     // Explicit save confirmation (desk's green "Saved" toast) — the
     // "Not Saved" badge clearing alone is too passive a success signal.
-    // Errors stay on the existing inline path (engine.errors.general).
+    // Errors stay on the form's inline path (errors.general).
     notify({
       severity: "success",
       scope: "page",
@@ -419,36 +317,29 @@ export function DocFormScreen({
     });
     invalidateDocinfo(doctype, savedName);
     emitEvent({ type: "doc-saved", doctype, name: savedName, isNew: isCreate });
-    onSaved?.({ ...engine.doc, name: savedName });
+    onSaved?.({ ...form.doc, name: savedName });
     if (isCreate) {
       navigator.replace(paths.form(doctype, savedName));
     } else {
       reloadDocinfo();
     }
-  }, [engine, formTabs, isCreate, navigator, paths, doctype, reloadDocinfo, t, emitEvent, onSaved]);
+  }, [form, isCreate, navigator, paths, doctype, reloadDocinfo, t, emitEvent, onSaved]);
 
   // Always swallow Cmd/Ctrl+S while the form is editable (desk parity —
   // the browser save dialog must never appear on a form page); saving
   // itself only fires when there is something to save.
   useSaveShortcut(!formReadOnly, () => {
-    if (engine.isDirty || isCreate) void handleSave();
+    if (form.isDirty || isCreate) void handleSave();
   });
   useJumpToFieldShortcut(jumpTargets.length > 0 && !jumpOpen, () => setJumpOpen(true));
 
   const handleAmend = useCallback(() => {
-    if (!meta || !docName) return;
-    setCreatePrefill(doctype, {
-      ...buildCopyValues(meta.fields, engine.doc),
-      amended_from: docName,
-    });
-    navigator.navigate(paths.newDoc(doctype));
-  }, [meta, docName, doctype, engine.doc, navigator, paths]);
+    if (form.amend()) navigator.navigate(paths.newDoc(doctype));
+  }, [form, doctype, navigator, paths]);
 
   const handleDuplicate = useCallback(() => {
-    if (!meta) return;
-    setCreatePrefill(doctype, buildCopyValues(meta.fields, engine.doc));
-    navigator.navigate(paths.newDoc(doctype));
-  }, [meta, doctype, engine.doc, navigator, paths]);
+    if (form.duplicate()) navigator.navigate(paths.newDoc(doctype));
+  }, [form, doctype, navigator, paths]);
 
   const handleRename = useCallback(
     async (newName: string) => {
@@ -468,7 +359,7 @@ export function DocFormScreen({
   // list order the user came from — DoctypeListScreen mirrors each resolved
   // page into the shared listNavContext store (sessionStorage-backed so a
   // reload keeps paging). No context / not in the last result (deep link,
-  // renamed doc) → no pager at all: hidden beats dead arrows (LC-40).
+  // renamed doc) → no pager at all: no arrows beat dead arrows (LC-40).
   // -----------------------------------------------------------------------
   const docPager = useMemo<ListNavNeighbors>(
     () => (docName ? getListNavNeighbors(doctype, docName) : { inList: false }),
@@ -488,11 +379,11 @@ export function DocFormScreen({
   );
 
   const titleFieldValue =
-    meta?.title_field && typeof engine.doc[meta.title_field] === "string"
+    meta?.title_field && typeof form.doc[meta.title_field] === "string"
       ? // Title fields can hold rich text (e.g. ToDo.description = "<p>…</p>");
         // strip to plain text so the breadcrumb + toolbar heading don't show
         // literal HTML tags.
-        htmlToText(engine.doc[meta.title_field] as string)
+        htmlToText(form.doc[meta.title_field] as string)
       : undefined;
   const title = isCreate
     ? t("newDocTitle", "New {{doctype}}", { doctype })
@@ -506,20 +397,22 @@ export function DocFormScreen({
         label: t("menuReload", "Reload"),
         icon: "reload",
         onSelect: () => {
-          engine.reload();
+          form.reset();
           setValidationSummary(undefined);
           refetchMeta();
           invalidateDocinfo(doctype, name);
           reloadDocinfo();
         },
       },
-      {
+    ];
+    if (!metaRefused) {
+      items.push({
         key: "duplicate",
         label: t("menuDuplicate", "Duplicate"),
         icon: "duplicate",
         onSelect: handleDuplicate,
-      },
-    ];
+      });
+    }
     if (meta?.allow_rename && perms.write) {
       items.push({
         key: "rename",
@@ -558,7 +451,7 @@ export function DocFormScreen({
         key: "links",
         label: t("menuLinks", "Links"),
         icon: "links",
-        onSelect: () => setActiveTab(CONNECTIONS_TAB),
+        onSelect: () => form.setActiveTab(CONNECTIONS_TAB),
       });
     }
     if (jumpTargets.length > 0) {
@@ -606,10 +499,11 @@ export function DocFormScreen({
   }, [
     isCreate,
     t,
-    engine,
+    form,
     refetchMeta,
     reloadDocinfo,
     handleDuplicate,
+    metaRefused,
     meta?.allow_rename,
     perms,
     connection,
@@ -627,8 +521,8 @@ export function DocFormScreen({
   // removes built-ins by key (a host can replace "print" by hiding it and
   // injecting its own).
   const effectiveMenuItems = useMemo<FormToolbarMenuItem[]>(() => {
-    const hidden = new Set(actionOverrides?.hide ?? []);
-    const items = menuItems.filter((item) => !hidden.has(item.key));
+    const hiddenKeys = new Set(actionOverrides?.hide ?? []);
+    const items = menuItems.filter((item) => !hiddenKeys.has(item.key));
     const injected: BackofficeAction[] = [
       ...actionsForDoctype(actions.form, doctype),
       ...actionsForDoctype(actionOverrides?.extra, doctype),
@@ -643,11 +537,14 @@ export function DocFormScreen({
     return items;
   }, [menuItems, actions.form, actionOverrides, doctype, docName]);
 
-  const handleJumpToField = useCallback((field: JumpToFieldTarget) => {
-    setJumpOpen(false);
-    setActiveTab(field.tabKey);
-    setPendingJump(field.name);
-  }, []);
+  const handleJumpToField = useCallback(
+    (field: JumpToFieldTarget) => {
+      setJumpOpen(false);
+      form.setActiveTab(field.tabKey);
+      setPendingJump(field.name);
+    },
+    [form],
+  );
 
   // Desk Jump-to-field: switch tab (lazyMount) then focus the LC-71 field shell.
   useEffect(() => {
@@ -704,18 +601,53 @@ export function DocFormScreen({
     );
   }
 
-  if (metaError && !meta) {
+  if (metaError && !meta && !metaRefused) {
+    return (
+      <YStack flex={1}>
+        <AsyncBoundary
+          error={metaError}
+          errorTitle={t("metaError", "Could not load {{doctype}}", { doctype })}
+          onRetry={refetchMeta}
+        />
+      </YStack>
+    );
+  }
+
+  if (!isCreate && form.status === "error" && form.docError && isPermissionError(form.docError)) {
     return (
       <YStack flex={1}>
         <EmptyState
-          title={t("metaError", "Could not load {{doctype}}", { doctype })}
-          description={metaError.message}
+          testID="frappe-form-not-permitted"
+          title={t("docNotPermitted", "You can't open {{doctype}} {{name}}", { doctype, name })}
+          description={refusalReason(form.docError)}
+          action={
+            <Button icon={ListBulletsIcon} onPress={() => navigator.navigate(paths.list(doctype))}>
+              {t("backToList", "Back to {{doctype}} list", { doctype })}
+            </Button>
+          }
         />
       </YStack>
     );
   }
 
-  if (!isCreate && engine.notFound) {
+  if (!isCreate && form.status === "error" && form.docError) {
+    return (
+      <YStack flex={1}>
+        <EmptyState
+          intent="error"
+          title={t("docLoadError", "Could not load {{doctype}} {{name}}", { doctype, name })}
+          description={form.docError.message}
+          action={
+            <Button icon={ListBulletsIcon} onPress={() => navigator.navigate(paths.list(doctype))}>
+              {t("backToList", "Back to {{doctype}} list", { doctype })}
+            </Button>
+          }
+        />
+      </YStack>
+    );
+  }
+
+  if (!isCreate && form.status === "notFound") {
     return (
       <YStack flex={1}>
         <EmptyState
@@ -737,7 +669,7 @@ export function DocFormScreen({
     );
   }
 
-  if (!isCreate && engine.isLoading) {
+  if (!isCreate && form.status === "loading") {
     return (
       <YStack flex={1} {...knobProps.panelPadding} testID="doc-form-skeleton">
         <AsyncSkeleton layout="generic" />
@@ -750,25 +682,24 @@ export function DocFormScreen({
   // -----------------------------------------------------------------------
   const indicator = resolveIndicator({
     isCreate,
-    isDirty: engine.isDirty,
-    docstatus: engine.docstatus,
+    isDirty: form.isDirty,
+    docstatus: form.docstatus,
     isSubmittable,
-    statusValue: typeof engine.doc.status === "string" ? engine.doc.status : undefined,
+    statusValue: typeof form.doc.status === "string" ? form.doc.status : undefined,
     states: meta?.states,
   });
-  const canSave =
-    !formReadOnly && (isCreate ? perms.create : perms.write && engine.docstatus === 0);
+  const canSave = !formReadOnly && (isCreate ? perms.create : perms.write && form.docstatus === 0);
   const canSubmit =
     !isCreate &&
     isSubmittable &&
-    engine.docstatus === 0 &&
-    !engine.isDirty &&
+    form.docstatus === 0 &&
+    !form.isDirty &&
     perms.submit &&
-    !engine.wasDeleted;
+    !form.wasDeleted;
   const canCancel =
-    !isCreate && isSubmittable && engine.docstatus === 1 && perms.cancel && !engine.wasDeleted;
+    !isCreate && isSubmittable && form.docstatus === 1 && perms.cancel && !form.wasDeleted;
   const canAmend =
-    !isCreate && isSubmittable && engine.docstatus === 2 && perms.amend && !engine.wasDeleted;
+    !isCreate && isSubmittable && form.docstatus === 2 && perms.amend && !form.wasDeleted;
 
   const breadcrumbs = [
     { label: t("home", "Home"), href: paths.home() },
@@ -776,91 +707,64 @@ export function DocFormScreen({
     { label: isCreate ? t("newCrumb", "New") : title },
   ];
 
-  const promptNamed = isCreate && isPromptNamed(meta?.autoname, meta?.naming_rule);
   // Compact (< 640): the sidebar accordion stacks between form body and
   // timeline (LC-29 — asides stack, never hide; metadata before history).
   const sidebarStacked = sizeClass === "compact";
 
-  const bodyTabs: TabsItem[] = [
-    ...formTabs.map((tab) => ({
-      value: tab.key,
-      label: tab.label,
-      content: (
-        <YStack {...knobProps.gapLg} paddingTop="$3">
-          {/* Containment at two granularities: each field renders behind its
-              own boundary (a broken field degrades to an inline error slot;
-              siblings stay editable), and the whole tab body behind another
-              (a SchemaForm-level crash costs one tab, not the route). */}
-          <FormErrorBoundary
-            errorTitle={t("formTabRenderError", "This form tab failed to render")}
-            testID={`form-tab-error-${tab.key}`}
-          >
-            <SchemaForm
-              schema={tab.schema}
-              doc={engine.doc}
-              setValue={engine.setValue}
-              errors={engine.errors}
-              disabled={formReadOnly || engine.isSaving}
-              sectionHeadingLevel={2}
-              renderFieldWrapper={wrapFieldWithErrorBoundary}
-            />
-          </FormErrorBoundary>
-        </YStack>
-      ),
-    })),
-    ...(showConnections
-      ? [
-          {
-            value: CONNECTIONS_TAB,
-            label: t("connectionsTab", "Connections"),
-            content: (
-              <YStack paddingTop="$3">
-                <FormConnections doctype={doctype} name={name} meta={meta} />
-              </YStack>
-            ),
-          },
-        ]
-      : []),
-  ];
+  const connectionsTab = showConnections
+    ? [
+        {
+          value: CONNECTIONS_TAB,
+          label: t("connectionsTab", "Connections"),
+          content: (
+            <YStack paddingTop="$3">
+              <FormConnections doctype={doctype} name={name} meta={meta} />
+            </YStack>
+          ),
+        },
+      ]
+    : [];
 
-  // Guard against a stale active tab (a Tab Break hidden by depends_on
-  // while active) — fall back to the first visible tab.
-  const effectiveTab =
-    activeTab && bodyTabs.some((tab) => tab.value === activeTab) ? activeTab : bodyTabs[0]?.value;
+  // Containment at two granularities: each field renders behind its own
+  // boundary (a broken field degrades to an inline error slot; siblings stay
+  // editable), and the whole tab body behind another (a crash in the form
+  // costs one tab, not the route).
+  const renderTab = (tab: FormTab, content: React.ReactNode) => (
+    <YStack {...knobProps.gapLg} paddingTop="$3">
+      <FormErrorBoundary
+        errorTitle={t("formTabRenderError", "This form tab failed to render")}
+        testID={`form-tab-error-${tab.key}`}
+      >
+        {content}
+      </FormErrorBoundary>
+    </YStack>
+  );
 
   const formBody = (
-    // No flex here: formBody now lives inside COLUMN containers (both
-    // branches below), where `flex={1}` means flex-basis:0 — the body would
-    // stop contributing height and the timeline/sidebar would paint over it.
-    <YStack minWidth={0} {...knobProps.gapLg}>
-      {promptNamed && (
-        <YStack {...knobProps.gap}>
-          <Input
-            label={t("namePrompt", "Name")}
-            value={typeof engine.doc.name === "string" ? engine.doc.name : ""}
-            onChangeText={(value) => engine.setValue("name", value)}
-            placeholder={t("namePromptPlaceholder", "New document name")}
-            error={engine.errors.name}
-          />
-        </YStack>
-      )}
-
-      {bodyTabs.length > 1 ? (
-        <Tabs items={bodyTabs} value={effectiveTab} onChange={setActiveTab} lazyMount />
-      ) : (
-        (bodyTabs[0]?.content ?? null)
-      )}
-
-      {engine.errors.general && (
-        <Text color="$red10" fontSize="$3" role="alert">
-          {engine.errors.general}
-        </Text>
-      )}
+    // No flex here: formBody lives inside COLUMN containers (both branches
+    // below), where `flex={1}` means flex-basis:0 — the body would stop
+    // contributing height and the timeline/sidebar would paint over it.
+    <YStack minWidth={0}>
+      <FrappeForm<DeskDoc>
+        form={form}
+        doctype={doctype}
+        name={docName}
+        disabled={readOnly}
+        showToolbar={false}
+        showSidebar={false}
+        showTimeline={false}
+        showConnections={false}
+        showBanners={false}
+        sectionHeadingLevel={2}
+        renderFieldWrapper={wrapFieldWithErrorBoundary}
+        renderTab={renderTab}
+        extraTabs={connectionsTab}
+      />
     </YStack>
   );
 
   const timeline =
-    capabilities.timeline.enabled && !isCreate && docName ? (
+    capabilities.timeline.enabled && !isCreate && docName && !metaRefused ? (
       // Composed mode: the screen's shared docinfo (and its refresh) feed
       // the timeline. Self-fetch mode subscribed the timeline to its OWN
       // cache entry, which the save path's invalidate+reload orphaned — the
@@ -871,7 +775,7 @@ export function DocFormScreen({
         name={docName}
         docInfo={docinfo}
         refreshDocInfo={refreshDocinfo}
-        currentUser={engine.currentUser}
+        currentUser={currentUser}
         connection={connection}
       />
     ) : null;
@@ -882,9 +786,9 @@ export function DocFormScreen({
         doctype={doctype}
         name={docName}
         meta={meta}
-        doc={engine.doc}
+        doc={form.doc}
         docinfo={docinfo}
-        currentUser={engine.currentUser}
+        currentUser={currentUser}
         onRefresh={refreshDocinfo}
         stacked={sidebarStacked}
       />
@@ -897,14 +801,14 @@ export function DocFormScreen({
       title={title}
       indicator={indicator}
       showIndicator={!!meta}
-      isSaving={engine.isSaving}
+      isSaving={form.isSubmitting}
       cluster={
-        !isCreate && docName ? (
+        !isCreate && docName && !metaRefused ? (
           <FormHeaderCluster
             doctype={doctype}
             name={docName}
             docinfo={docinfo}
-            currentUser={engine.currentUser}
+            currentUser={currentUser}
             onRefresh={refreshDocinfo}
           />
         ) : undefined
@@ -944,9 +848,9 @@ export function DocFormScreen({
           })
         : toolbar}
 
-      {(engine.wasDeleted || validationSummary || engine.conflict) && (
+      {(form.wasDeleted || validationSummary || form.conflict) && (
         <YStack paddingHorizontal="$3">
-          {engine.wasDeleted && (
+          {form.wasDeleted && (
             <XStack
               role="alert"
               {...knobProps.containerRadius}
@@ -962,7 +866,7 @@ export function DocFormScreen({
             </XStack>
           )}
 
-          {validationSummary && !engine.wasDeleted && (
+          {validationSummary && !form.wasDeleted && (
             <XStack
               role="alert"
               {...knobProps.containerRadius}
@@ -976,7 +880,7 @@ export function DocFormScreen({
             </XStack>
           )}
 
-          {engine.conflict && !engine.wasDeleted && (
+          {form.conflict && !form.wasDeleted && (
             <XStack
               role="status"
               alignItems="center"
@@ -989,12 +893,7 @@ export function DocFormScreen({
               <Text color="$orange11" fontSize="$3" flex={1}>
                 {t("conflictBanner", "This document changed on the server while you were editing.")}
               </Text>
-              <Button
-                size="$2"
-                outlined
-                aria-label={t("reloadDoc", "Reload")}
-                onPress={engine.reload}
-              >
+              <Button size="$2" outlined aria-label={t("reloadDoc", "Reload")} onPress={form.reset}>
                 {t("reloadDoc", "Reload")}
               </Button>
             </XStack>
@@ -1037,7 +936,7 @@ export function DocFormScreen({
         warning
         onConfirm={() => {
           setConfirmAction(undefined);
-          void engine.submit().then((ok) => {
+          void form.submitDocument().then((ok) => {
             if (ok) {
               notify({
                 severity: "success",
@@ -1061,7 +960,7 @@ export function DocFormScreen({
         destructive
         onConfirm={() => {
           setConfirmAction(undefined);
-          void engine.cancel().then((ok) => {
+          void form.cancelDocument().then((ok) => {
             if (ok) {
               notify({
                 severity: "success",
@@ -1085,7 +984,7 @@ export function DocFormScreen({
         destructive
         onConfirm={() => {
           setConfirmAction(undefined);
-          void engine.remove().then((ok) => {
+          void form.remove().then((ok) => {
             if (ok) {
               invalidateDocinfo(doctype, name);
               emitEvent({ type: "doc-deleted", doctype, name });