@multiplatform.one/backoffice 6.4.2 → 6.6.0

package/src/form/DocFormScreen.tsx

@@ -0,0 +1,969 @@
+import React from "react";
+/**
+ * The document form page — desk form parity.
+ *
+ * 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)
+ *   Sidebar       assignments / attachments / tags / shares / likes / follow
+ *   Timeline      docinfo comments + versions + communications interleaved
+ *   Connections   linked-doctype tiles with live counts
+ *
+ * Data: meta via getdoctype (cached), doc via the live collection
+ * (realtime), docinfo via getdoc (refreshed after actions and on live
+ * `modified` changes).
+ */
+
+import {
+  AsyncSkeleton,
+  Button,
+  ConfirmDialog,
+  EmptyState,
+  ScrollView,
+  Tabs,
+  Text,
+  XStack,
+  YStack,
+  type TabsItem,
+} from "@multiplatform.one/components";
+import { Input } from "@multiplatform.one/forms";
+import { SchemaForm, useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useLayoutSizeClass, useResolvedKnobs } from "@multiplatform.one/theme";
+import { ListBulletsIcon } from "@phosphor-icons/react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  actionsForDoctype,
+  useBackofficeCapabilities,
+  useBackofficeConfig,
+  useBackofficeNavigator,
+  useBackofficePaths,
+  type BackofficeAction,
+} from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { invalidateDocinfo, useDocinfo } from "../shared/useDocinfo";
+import { useRecentVisit } from "../shared/useRecentVisit";
+import { useDoctypeMeta } from "../shared/useDoctypeMeta";
+import { useUserRoles } from "../shared/useUserRoles";
+import { setCreatePrefill } from "./createPrefill";
+import { normalizeDocPermissions } from "./docinfo";
+import { buildPermLevelMatrix } from "./fieldPermissions";
+import { createHttpClient, renameDoc, sendEmail } from "./formActions";
+import { EmailDialog, RenameDialog } 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";
+import { FormTimeline } from "./FormTimeline";
+import { FormToolbar, resolveIndicator, type FormToolbarMenuItem } from "./FormToolbar";
+import { htmlToText } from "./timeline-utils";
+import {
+  canOpenNewTab,
+  openInNewTab,
+  useBeforeUnloadGuard,
+  useNavigationDirtyGuard,
+  useSaveShortcut,
+} from "./platformHooks";
+import { useFormEngine } from "./useFormEngine";
+
+/** Host overrides for the form's ⋯ toolbar menu. */
+export interface DocFormActionOverrides {
+  /**
+   * Built-in menu item keys to remove ("reload" | "duplicate" | "rename" |
+   * "print" | "email" | "links" | "jump-list" | "new" | "delete").
+   */
+  hide?: readonly string[];
+  /** Extra host actions appended to the menu (after provider `actions.form`). */
+  extra?: readonly BackofficeAction[];
+}
+
+export interface DocFormScreenProps {
+  /** Proper-cased doctype name (e.g. "ToDo", "Sales Order") */
+  doctype: string;
+  /** Document name; the literal "new" renders create mode */
+  name: string;
+  /** Force the whole form read-only regardless of permissions. */
+  readOnly?: boolean;
+  /** Hide form sections/tabs by Section/Tab Break fieldname or label. */
+  hiddenSections?: readonly string[];
+  /** Hide individual fields by fieldname. */
+  hiddenFields?: readonly string[];
+  /** Create-mode field prefill (merged over meta defaults). */
+  defaults?: Record<string, unknown>;
+  /** After a successful save (create or update). `doc.name` is authoritative. */
+  onSaved?: (doc: Record<string, unknown> & { name: string }) => void;
+  /** After a successful delete. Replaces the default navigate-to-list. */
+  onDeleted?: () => void;
+  /** Hide built-in ⋯ menu items / append host actions. */
+  actionOverrides?: DocFormActionOverrides;
+}
+
+const CONNECTIONS_TAB = "__connections";
+
+export function DocFormScreen({
+  doctype,
+  name,
+  readOnly,
+  hiddenSections,
+  hiddenFields,
+  defaults,
+  onSaved,
+  onDeleted,
+  actionOverrides,
+}: DocFormScreenProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const capabilities = useBackofficeCapabilities();
+  const { actions, slots, emitEvent } = useBackofficeConfig();
+  // Canonical size-class mechanism (LC-28): `compact` = < 640 — the sidebar
+  // accordion stacks between the form body and the timeline.
+  const sizeClass = useLayoutSizeClass();
+  const config = useFrappeConfig();
+
+  const isCreate = name === "new";
+  const docName = isCreate ? undefined : name;
+
+  // Write-on-visit for the shared recents store (workspace "Continue where
+  // you left off" strip). Create mode and fixture mode (stories) skip.
+  useRecentVisit(
+    isCreate || config?.fixtures
+      ? undefined
+      : { label: `${doctype}: ${name}`, path: paths.form(doctype, name) },
+  );
+
+  // `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.
+  const defaultsKey = defaults ? JSON.stringify(defaults) : undefined;
+  useMemo(() => {
+    if (!isCreate || !defaultsKey) return;
+    const parsed = JSON.parse(defaultsKey) as Record<string, unknown>;
+    if (Object.keys(parsed).length > 0) setCreatePrefill(doctype, parsed);
+  }, [doctype, defaultsKey, isCreate]);
+
+  // Host event bus: a form was opened (edit mode; create emits on first save).
+  useEffect(() => {
+    if (!isCreate) emitEvent({ type: "doc-opened", doctype, name });
+  }, [isCreate, doctype, name, emitEvent]);
+
+  const connection = useMemo(
+    () =>
+      config?.baseURL
+        ? {
+            baseURL: config.baseURL,
+            socketPort: config.socketPort,
+            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
+  // read the same bundle.
+  const {
+    meta,
+    loading: isMetaLoading,
+    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]);
+
+  // Shared docinfo — one get_docinfo fetch shared with the header cluster,
+  // sidebar, and timeline panels; the screen reads the permission flags and
+  // passes the bundle down so cluster/sidebar mutations stay in sync.
+  const { docinfo, reload: reloadDocinfo } = useDocinfo(doctype, name);
+  const refreshDocinfo = useCallback(() => {
+    if (docName) invalidateDocinfo(doctype, docName);
+    reloadDocinfo();
+  }, [doctype, docName, reloadDocinfo]);
+
+  // 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;
+  const stampRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    stampRef.current = undefined;
+  }, [doctype, name]);
+  useEffect(() => {
+    if (!docName || !modifiedStamp) return;
+    if (stampRef.current === modifiedStamp) return;
+    const isFirstLoad = stampRef.current === undefined;
+    stampRef.current = modifiedStamp;
+    if (!isFirstLoad) {
+      invalidateDocinfo(doctype, docName);
+      reloadDocinfo();
+    }
+  }, [modifiedStamp, docName, doctype, reloadDocinfo]);
+
+  // -----------------------------------------------------------------------
+  // Permissions: per-doc flags from docinfo when usable, else the meta role
+  // matrix (union across roles — the session's role set is not exposed
+  // client-side; the desk itself relies on docinfo.permissions).
+  // -----------------------------------------------------------------------
+  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,
+      };
+    }
+    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, meta?.permissions]);
+
+  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 { roles } = useUserRoles();
+  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 [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);
+
+  // -----------------------------------------------------------------------
+  // Navigation with dirty guard
+  // -----------------------------------------------------------------------
+  const [pendingNav, setPendingNav] = useState<string | undefined>(undefined);
+  const navigate = useCallback(
+    (href: string) => {
+      if (engine.isDirty) {
+        setPendingNav(href);
+        return;
+      }
+      navigator.navigate(href);
+    },
+    [engine.isDirty, navigator],
+  );
+  useBeforeUnloadGuard(engine.isDirty);
+  // Covers back navigations that skip navigate(): browser back on web,
+  // back gesture/button on native (B7).
+  const backGuard = useNavigationDirtyGuard(engine.isDirty);
+
+  // -----------------------------------------------------------------------
+  // Actions
+  // -----------------------------------------------------------------------
+  const [confirmAction, setConfirmAction] = useState<"submit" | "cancel" | "delete" | undefined>(
+    undefined,
+  );
+  const [renameOpen, setRenameOpen] = useState(false);
+  const [emailOpen, setEmailOpen] = useState(false);
+
+  const [validationSummary, setValidationSummary] = useState<string | undefined>(undefined);
+
+  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 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);
+      setValidationSummary(
+        t("validationSummary", "Cannot save — {{count}} required field(s) are missing.", {
+          count: errorFields.length,
+        }),
+      );
+    } else {
+      setValidationSummary(undefined);
+    }
+    const savedName = await engine.save();
+    if (!savedName) return;
+    setValidationSummary(undefined);
+    invalidateDocinfo(doctype, savedName);
+    emitEvent({ type: "doc-saved", doctype, name: savedName, isNew: isCreate });
+    onSaved?.({ ...engine.doc, name: savedName });
+    if (isCreate) {
+      navigator.replace(paths.form(doctype, savedName));
+    } else {
+      reloadDocinfo();
+    }
+  }, [engine, formTabs, 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();
+  });
+
+  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]);
+
+  const handleDuplicate = useCallback(() => {
+    if (!meta) return;
+    setCreatePrefill(doctype, buildCopyValues(meta.fields, engine.doc));
+    navigator.navigate(paths.newDoc(doctype));
+  }, [meta, doctype, engine.doc, navigator, paths]);
+
+  const handleRename = useCallback(
+    async (newName: string) => {
+      if (!connection || !docName) return;
+      try {
+        const resolved = await renameDoc(createHttpClient(connection), doctype, docName, newName);
+        navigator.replace(paths.form(doctype, resolved));
+      } catch {
+        // rename_doc rejections (permissions / duplicates) leave the doc as-is.
+      }
+    },
+    [connection, docName, doctype, navigator, paths],
+  );
+
+  const titleFieldValue =
+    meta?.title_field && typeof engine.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)
+      : undefined;
+  const title = isCreate
+    ? t("newDocTitle", "New {{doctype}}", { doctype })
+    : titleFieldValue || name;
+
+  const menuItems = useMemo<FormToolbarMenuItem[]>(() => {
+    if (isCreate) return [];
+    const items: FormToolbarMenuItem[] = [
+      {
+        key: "reload",
+        label: t("menuReload", "Reload"),
+        icon: "reload",
+        onSelect: () => {
+          engine.reload();
+          setValidationSummary(undefined);
+          refetchMeta();
+          invalidateDocinfo(doctype, name);
+          reloadDocinfo();
+        },
+      },
+      {
+        key: "duplicate",
+        label: t("menuDuplicate", "Duplicate"),
+        icon: "duplicate",
+        onSelect: handleDuplicate,
+      },
+    ];
+    if (meta?.allow_rename && perms.write) {
+      items.push({
+        key: "rename",
+        label: t("menuRename", "Rename"),
+        icon: "rename",
+        onSelect: () => setRenameOpen(true),
+      });
+    }
+    if (capabilities.print.enabled && canOpenNewTab() && perms.print && connection) {
+      // Print opens the bench's printview in a new tab (web only; native
+      // and GNOME hide the entry — documented platform gap).
+      items.push({
+        key: "print",
+        label: t("menuPrint", "Print"),
+        icon: "print",
+        onSelect: () => {
+          const base = connection.baseURL.replace(/\/$/, "");
+          openInNewTab(
+            `${base}/printview?doctype=${encodeURIComponent(doctype)}&name=${encodeURIComponent(
+              name,
+            )}&format=Standard`,
+          );
+        },
+      });
+    }
+    if (capabilities.email.enabled && perms.email) {
+      items.push({
+        key: "email",
+        label: t("menuEmail", "Email"),
+        icon: "email",
+        onSelect: () => setEmailOpen(true),
+      });
+    }
+    if (showConnections) {
+      items.push({
+        key: "links",
+        label: t("menuLinks", "Links"),
+        icon: "links",
+        onSelect: () => setActiveTab(CONNECTIONS_TAB),
+      });
+    }
+    items.push({
+      key: "jump-list",
+      label: t("menuJumpToList", "Jump to {{doctype}} List", { doctype }),
+      icon: "list",
+      onSelect: () => navigate(paths.list(doctype)),
+    });
+    if (capabilities.newDoc.enabled && perms.create) {
+      items.push({
+        key: "new",
+        label: t("menuNew", "New {{doctype}}", { doctype }),
+        icon: "new",
+        onSelect: () => navigate(paths.newDoc(doctype)),
+      });
+    }
+    if (perms.delete) {
+      items.push({
+        key: "delete",
+        label: t("menuDelete", "Delete"),
+        icon: "delete",
+        destructive: true,
+        onSelect: () => setConfirmAction("delete"),
+      });
+    }
+    return items;
+  }, [
+    isCreate,
+    t,
+    engine,
+    refetchMeta,
+    reloadDocinfo,
+    handleDuplicate,
+    meta?.allow_rename,
+    perms,
+    connection,
+    doctype,
+    name,
+    showConnections,
+    navigate,
+    paths,
+    capabilities,
+  ]);
+
+  // Host action registry: provider-level `actions.form` plus per-screen
+  // `actionOverrides.extra` land on the ⋯ menu; `actionOverrides.hide`
+  // 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 injected: BackofficeAction[] = [
+      ...actionsForDoctype(actions.form, doctype),
+      ...actionsForDoctype(actionOverrides?.extra, doctype),
+    ];
+    for (const action of injected) {
+      items.push({
+        key: `host:${action.id}`,
+        label: action.label,
+        onSelect: () => action.onPress({ doctype, ...(docName ? { name: docName } : {}) }),
+      });
+    }
+    return items;
+  }, [menuItems, actions.form, actionOverrides, doctype, docName]);
+
+  // -----------------------------------------------------------------------
+  // Early states
+  // -----------------------------------------------------------------------
+  if (!config?.baseURL || !connection) {
+    return (
+      <YStack flex={1}>
+        <EmptyState
+          title={t("noFrappe", "Frappe is not configured")}
+          description={t(
+            "noFrappeHint",
+            "Pass a frappe connection to BackofficeProvider to point the backoffice at a bench.",
+          )}
+        />
+      </YStack>
+    );
+  }
+
+  if (isMetaLoading && !meta) {
+    return (
+      <YStack flex={1} {...knobProps.panelPadding} testID="doc-form-skeleton">
+        <AsyncSkeleton layout="generic" />
+      </YStack>
+    );
+  }
+
+  if (metaError && !meta) {
+    return (
+      <YStack flex={1}>
+        <EmptyState
+          title={t("metaError", "Could not load {{doctype}}", { doctype })}
+          description={metaError.message}
+        />
+      </YStack>
+    );
+  }
+
+  if (!isCreate && engine.notFound) {
+    return (
+      <YStack flex={1}>
+        <EmptyState
+          title={t("docNotFound", "{{doctype}} {{name}} not found", {
+            doctype,
+            name,
+          })}
+          description={t(
+            "docNotFoundHint",
+            "The document does not exist or you do not have permission to read it.",
+          )}
+          action={
+            <Button icon={ListBulletsIcon} onPress={() => navigator.navigate(paths.list(doctype))}>
+              {t("backToList", "Back to {{doctype}} list", { doctype })}
+            </Button>
+          }
+        />
+      </YStack>
+    );
+  }
+
+  if (!isCreate && engine.isLoading) {
+    return (
+      <YStack flex={1} {...knobProps.panelPadding} testID="doc-form-skeleton">
+        <AsyncSkeleton layout="generic" />
+      </YStack>
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // Toolbar state
+  // -----------------------------------------------------------------------
+  const indicator = resolveIndicator({
+    isCreate,
+    isDirty: engine.isDirty,
+    docstatus: engine.docstatus,
+    isSubmittable,
+    statusValue: typeof engine.doc.status === "string" ? engine.doc.status : undefined,
+    states: meta?.states,
+  });
+  const canSave =
+    !formReadOnly && (isCreate ? perms.create : perms.write && engine.docstatus === 0);
+  const canSubmit =
+    !isCreate &&
+    isSubmittable &&
+    engine.docstatus === 0 &&
+    !engine.isDirty &&
+    perms.submit &&
+    !engine.wasDeleted;
+  const canCancel =
+    !isCreate && isSubmittable && engine.docstatus === 1 && perms.cancel && !engine.wasDeleted;
+  const canAmend =
+    !isCreate && isSubmittable && engine.docstatus === 2 && perms.amend && !engine.wasDeleted;
+
+  const breadcrumbs = [
+    { label: t("home", "Home"), href: paths.home() },
+    { label: doctype, href: paths.list(doctype) },
+    { 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>
+            ),
+          },
+        ]
+      : []),
+  ];
+
+  // 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;
+
+  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>
+      )}
+    </YStack>
+  );
+
+  const timeline =
+    capabilities.timeline.enabled && !isCreate && docName ? (
+      <FormTimeline doctype={doctype} name={docName} />
+    ) : null;
+
+  const sidebar =
+    !isCreate && docName && meta ? (
+      <FormSidebarPanel
+        doctype={doctype}
+        name={docName}
+        meta={meta}
+        doc={engine.doc}
+        docinfo={docinfo}
+        currentUser={engine.currentUser}
+        onRefresh={refreshDocinfo}
+        stacked={sidebarStacked}
+      />
+    ) : null;
+
+  const toolbar = (
+    <FormToolbar
+      breadcrumbs={breadcrumbs}
+      onNavigate={navigate}
+      title={title}
+      indicator={indicator}
+      showIndicator={!!meta}
+      isSaving={engine.isSaving}
+      cluster={
+        !isCreate && docName ? (
+          <FormHeaderCluster
+            doctype={doctype}
+            name={docName}
+            docinfo={docinfo}
+            currentUser={engine.currentUser}
+            onRefresh={refreshDocinfo}
+          />
+        ) : undefined
+      }
+      canSave={canSave}
+      canSubmit={canSubmit}
+      canCancel={canCancel}
+      canAmend={canAmend}
+      onSave={() => void handleSave()}
+      onSubmit={() => setConfirmAction("submit")}
+      onCancel={() => setConfirmAction("cancel")}
+      onAmend={handleAmend}
+      menuItems={effectiveMenuItems}
+    />
+  );
+
+  return (
+    <YStack flex={1}>
+      {slots.renderFormHeader
+        ? slots.renderFormHeader({
+            doctype,
+            ...(docName ? { name: docName } : {}),
+            defaultContent: toolbar,
+          })
+        : toolbar}
+
+      {engine.wasDeleted && (
+        <XStack
+          role="alert"
+          {...knobProps.containerRadius}
+          {...knobProps.panelPadding}
+          marginHorizontal="$3"
+          backgroundColor="$red3"
+        >
+          <Text color="$red11" fontSize="$3">
+            {t("deletedBanner", "This document was deleted on the server. Fields are read-only.")}
+          </Text>
+        </XStack>
+      )}
+
+      {validationSummary && !engine.wasDeleted && (
+        <XStack
+          role="alert"
+          {...knobProps.containerRadius}
+          {...knobProps.panelPadding}
+          marginHorizontal="$3"
+          backgroundColor="$red3"
+          testID="doc-form-validation-summary"
+        >
+          <Text color="$red11" fontSize="$3">
+            {validationSummary}
+          </Text>
+        </XStack>
+      )}
+
+      {engine.conflict && !engine.wasDeleted && (
+        <XStack
+          role="status"
+          alignItems="center"
+          justifyContent="space-between"
+          {...knobProps.containerRadius}
+          {...knobProps.panelPadding}
+          marginHorizontal="$3"
+          backgroundColor="$orange3"
+          gap="$3"
+        >
+          <Text color="$orange11" fontSize="$3" flex={1}>
+            {t("conflictBanner", "This document changed on the server while you were editing.")}
+          </Text>
+          <Text
+            color="$orange11"
+            fontSize="$3"
+            fontWeight="700"
+            cursor="pointer"
+            role="button"
+            aria-label={t("reloadDoc", "Reload")}
+            onPress={engine.reload}
+          >
+            {t("reloadDoc", "Reload")}
+          </Text>
+        </XStack>
+      )}
+
+      <ScrollView flex={1}>
+        {sidebarStacked ? (
+          // Compact: form body → metadata accordion → timeline (the accordion
+          // must not hide below the activity feed's long scroll).
+          <YStack {...knobProps.panelPadding} {...knobProps.gapLg}>
+            {formBody}
+            {sidebar}
+            {timeline}
+          </YStack>
+        ) : (
+          // Wide: main column (body + timeline) with the compact metadata
+          // rail keeping its trailing position.
+          <XStack {...knobProps.panelPadding} {...knobProps.gapLg} alignItems="flex-start">
+            <YStack flex={1} minWidth={0} {...knobProps.gapLg}>
+              {formBody}
+              {timeline}
+            </YStack>
+            {sidebar}
+          </XStack>
+        )}
+      </ScrollView>
+
+      {/* Lifecycle confirms */}
+      <ConfirmDialog
+        open={confirmAction === "submit"}
+        onOpenChange={(open) => !open && setConfirmAction(undefined)}
+        title={t("submitConfirmTitle", "Submit {{doctype}}?", { doctype })}
+        body={t(
+          "submitConfirmBody",
+          "After submitting, the document becomes read-only and can only be cancelled or amended.",
+        )}
+        confirmLabel={t("submit", "Submit")}
+        warning
+        onConfirm={() => {
+          setConfirmAction(undefined);
+          void engine.submit().then((ok) => {
+            if (ok) reloadDocinfo();
+          });
+        }}
+      />
+      <ConfirmDialog
+        open={confirmAction === "cancel"}
+        onOpenChange={(open) => !open && setConfirmAction(undefined)}
+        title={t("cancelConfirmTitle", "Cancel {{doctype}}?", { doctype })}
+        body={t(
+          "cancelConfirmBody",
+          "Cancelling marks the document as void. You can amend it into a new draft afterwards.",
+        )}
+        confirmLabel={t("cancelAction", "Cancel")}
+        destructive
+        onConfirm={() => {
+          setConfirmAction(undefined);
+          void engine.cancel().then((ok) => {
+            if (ok) reloadDocinfo();
+          });
+        }}
+      />
+      <ConfirmDialog
+        open={confirmAction === "delete"}
+        onOpenChange={(open) => !open && setConfirmAction(undefined)}
+        title={t("deleteConfirmTitle", "Delete {{doctype}} {{name}}?", {
+          doctype,
+          name: title,
+        })}
+        body={t("deleteConfirmBody", "This action cannot be undone.")}
+        confirmLabel={t("menuDelete", "Delete")}
+        destructive
+        onConfirm={() => {
+          setConfirmAction(undefined);
+          void engine.remove().then((ok) => {
+            if (ok) {
+              invalidateDocinfo(doctype, name);
+              emitEvent({ type: "doc-deleted", doctype, name });
+              if (onDeleted) onDeleted();
+              else navigator.replace(paths.list(doctype));
+            }
+          });
+        }}
+      />
+
+      {/* Unsaved-changes nav guard (in-app navigate() + router-level back) */}
+      <ConfirmDialog
+        open={!!pendingNav || backGuard.blocked}
+        onOpenChange={(open) => {
+          if (open) return;
+          setPendingNav(undefined);
+          backGuard.reset();
+        }}
+        title={t("unsavedTitle", "Discard unsaved changes?")}
+        body={t(
+          "unsavedBody",
+          "You have unsaved changes that will be lost if you leave this page.",
+        )}
+        confirmLabel={t("leave", "Leave")}
+        warning
+        onConfirm={() => {
+          if (backGuard.blocked) {
+            backGuard.proceed();
+            return;
+          }
+          const target = pendingNav;
+          setPendingNav(undefined);
+          if (target) navigator.navigate(target);
+        }}
+      />
+
+      <RenameDialog
+        open={renameOpen}
+        onOpenChange={setRenameOpen}
+        currentName={name}
+        onRename={(newName) => {
+          setRenameOpen(false);
+          void handleRename(newName);
+        }}
+      />
+      <EmailDialog
+        open={emailOpen}
+        onOpenChange={setEmailOpen}
+        defaultSubject={`${doctype}: ${title}`}
+        onSend={(args) => {
+          setEmailOpen(false);
+          if (!docName) return;
+          void sendEmail(createHttpClient(connection), {
+            doctype,
+            name: docName,
+            ...args,
+          })
+            .catch(() => {
+              // Email failures surface in the refreshed timeline / bench logs.
+            })
+            .finally(reloadDocinfo);
+        }}
+      />
+    </YStack>
+  );
+}