@multiplatform.one/frappe-ui 7.28.0 → 7.29.0

package/src/FrappeForm.tsx

@@ -1,11 +1,7 @@
 import {
-  getFrappeSyncModule,
   useFrappeCollection,
-  useFrappeDoctypeEvents,
   useLiveQuery,
-  useDocTypeMeta,
   type DocTypeMeta,
-  type DocTypeField,
   type FormSection,
 } from "@multiplatform.one/frappe";
 import {
@@ -17,13 +13,12 @@ import {
   Tabs,
   type TabsItem,
 } from "@multiplatform.one/components";
-import { SchemaForm, type FieldOverride } from "./schemaForm";
+import { SchemaForm, type FieldOverride, type SchemaFormProps } from "./schemaForm";
 import type { HeadingLevel } from "./fields/Heading";
 import { FormSidebar, type SidebarSection, type SidebarMetadataEntry } from "./FormSidebar";
-import { eq } from "@tanstack/db";
 import { ArrowLeftIcon } from "@phosphor-icons/react";
 import type React from "react";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import type { TFunction } from "i18next";
 import { useTranslation } from "react-i18next";
 import { Button, Input, formCommonColors } from "@multiplatform.one/forms";
@@ -33,27 +28,21 @@ import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeReconnectIndicator } from "./FrappeReconnectIndicator";
 import { Timeline } from "./components/timeline";
 import { dialog } from "@multiplatform.one/desktop";
-import { applyFetchedValues, buildFetchMap } from "./formEngine/fetchFrom";
-import { buildPermLevelMatrix } from "./formEngine/fieldPermissions";
-import { createHttpClient, validateLink } from "./formEngine/formActions";
-import { buildFormTabs, isPromptNamed, type FormTab } from "./formEngine/formLayout";
-import { setCreatePrefill, takeCreatePrefill } from "./formEngine/createPrefill";
+import type { FormTab } from "./formEngine/formLayout";
 import {
-  buildAmendValues,
   canDeleteDoc,
   canEditDoc,
   isAmendable,
   resolveDocAction,
   resolveDocIndicator,
 } from "./formEngine/docLifecycle";
-import { useAmendedAs } from "./formEngine/useAmendedAs";
-import { useDocRights } from "./formEngine/useDocRights";
-import { extractServerError } from "./formEngine/useFormEngine";
 import { FrappeFormActions } from "./FrappeFormActions";
 import { connectionFields, connectionsFromMeta, type FrappeConnection } from "./frappeConnections";
 import { FrappeFormConnections } from "./FrappeFormConnections";
 import { FrappeNotConfigured } from "./FrappeNotConfigured";
 import { FrappeRowsReader, type FrappeRowsSnapshot } from "./FrappeRowsReader";
+import { isPermissionError } from "./liveErrors";
+import { fieldsFromRecord } from "./recordShape";
 import {
   frappeRouteHref,
   frappeRouteTarget,
@@ -61,17 +50,11 @@ import {
   type FrappeRouteTarget,
 } from "./frappeNavigation";
 import type { FieldSchema } from "./fieldRegistry";
+import { useFrappeForm, type FrappeFormController } from "./useFrappeForm";
 
 /** Linked rows per connection doctype, as the render prop receives them. */
 export type FrappeConnectionRows = Record<string, Array<Record<string, unknown>>>;
 
-function isEmptyFieldValue(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;
-}
-
 export interface FrappeFormProps<TDoc extends { name: string; doctype: string }> {
   baseURL?: string;
   auth?: { useToken?: boolean; token?: string; type?: string };
@@ -172,75 +155,36 @@ export interface FrappeFormProps<TDoc extends { name: string; doctype: string }>
    * via SchemaForm — sections sit one step below the page h1.
    */
   sectionHeadingLevel?: HeadingLevel;
+  /**
+   * The form's state, owned by the caller (`useFrappeForm`). Given, the form
+   * renders from it instead of holding its own, so a page can build its
+   * chrome on the same controller: turn the form's toolbar, sidebar,
+   * timeline and banners off and render them from `form` instead.
+   */
+  form?: FrappeFormController<TDoc>;
+  /** Section or Tab Breaks to hide, by fieldname or label. */
+  hideSections?: string[];
+  /** False leaves the deleted and changed-elsewhere banners to the host. */
+  showBanners?: boolean;
+  /** Host tabs after the form's own (and its Connections tab). */
+  extraTabs?: TabsItem[];
+  /** Wraps each rendered field, e.g. in an error boundary. */
+  renderFieldWrapper?: SchemaFormProps["renderFieldWrapper"];
+  /** Wraps each laid-out tab's body. */
+  renderTab?: (tab: FormTab, content: React.ReactNode) => React.ReactNode;
 }
 
-// ---------------------------------------------------------------------------
-// Layout source for the form engine
-// ---------------------------------------------------------------------------
-
-/**
- * A `sections` override re-expressed as the flat break-delimited field list
- * the form engine lays out, so an overridden layout resolves every field
- * exactly like the meta one.
- */
-function sectionsToLayoutFields(sections: FormSection[]): DocTypeField[] {
-  const fields: DocTypeField[] = [];
-  sections.forEach((section, sectionIndex) => {
-    fields.push({
-      fieldname: `__section_${sectionIndex}`,
-      fieldtype: section.tab ? "Tab Break" : "Section Break",
-      label: section.label,
-      collapsible: section.collapsible ? 1 : 0,
-    });
-    section.columns.forEach((column, columnIndex) => {
-      if (columnIndex > 0) {
-        fields.push({
-          fieldname: `__column_${sectionIndex}_${columnIndex}`,
-          fieldtype: "Column Break",
-        });
-      }
-      fields.push(...column.fields);
-    });
-  });
-  return fields;
-}
-
-// Document bookkeeping, never shown as a field of the record.
-const documentBookkeeping = new Set([
-  "name",
-  "owner",
-  "creation",
-  "modified",
-  "modified_by",
-  "docstatus",
-  "idx",
-  "doctype",
-  "_user_tags",
-  "_comments",
-  "_assign",
-  "_liked_by",
-  "_seen",
-]);
-
 /**
- * A record's own scalar fields as read-only schema fields, for a reader without
- * meta. `$`-keys are the collection's virtual props ($origin, $key,
- * $collectionId), which the row carries but the record does not.
+ * A record's own fields as read-only schema fields, for a reader without meta
+ * (LC-96).
  */
-function fieldsFromDocument(doc: Record<string, unknown>): FieldSchema[] {
-  return Object.entries(doc)
-    .filter(
-      ([key, value]) =>
-        !key.startsWith("$") &&
-        !documentBookkeeping.has(key) &&
-        (value === null || typeof value === "string" || typeof value === "number"),
-    )
-    .map(([key, value]) => ({
-      name: key,
-      label: key.replace(/_/g, " ").replace(/(^|\s)\S/g, (c) => c.toUpperCase()),
-      type: typeof value === "number" ? (Number.isInteger(value) ? "Int" : "Float") : "Data",
-      readOnly: true,
-    }));
+function schemaFieldsFromRecord(doc: Record<string, unknown>): FieldSchema[] {
+  return fieldsFromRecord(doc).map((field) => ({
+    name: field.fieldname,
+    label: field.label,
+    type: field.fieldtype,
+    readOnly: true,
+  }));
 }
 
 // ---------------------------------------------------------------------------
@@ -447,20 +391,46 @@ function FrappeFormRoute<TDoc extends { name: string; doctype: string }>({
   );
 }
 
-function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
-  baseURL,
-  auth,
-  syncOptions,
+function FrappeFormBody<TDoc extends { name: string; doctype: string }>(
+  props: FrappeFormBodyProps<TDoc>,
+) {
+  if (props.form) return <FrappeFormView<TDoc> {...props} form={props.form} />;
+  return <FrappeFormOwned<TDoc> {...props} />;
+}
+
+function FrappeFormOwned<TDoc extends { name: string; doctype: string }>(
+  props: FrappeFormBodyProps<TDoc>,
+) {
+  const config = useFrappeConfig();
+  if (!(props.baseURL ?? config?.baseURL)) {
+    throw new Error("FrappeForm requires baseURL prop or FrappeProvider with baseURL");
+  }
+  const form = useFrappeForm<TDoc>({
+    doctype: props.doctype,
+    name: props.name,
+    baseURL: props.baseURL,
+    auth: props.auth,
+    syncOptions: props.syncOptions,
+    fields: props.fields,
+    sections: props.sections,
+    hideFields: props.hideFields,
+    hideSections: props.hideSections,
+    roles: props.roles,
+    readShares: props.showSidebar ?? true,
+    disabled: props.disabled,
+    initialDoc: props.initialDoc,
+  });
+  return <FrappeFormView<TDoc> {...props} form={form} />;
+}
+
+function FrappeFormView<TDoc extends { name: string; doctype: string }>({
+  form,
   doctype,
   name,
-  fields,
   children,
   overrides,
-  hideFields,
   readOnlyFields,
-  sections,
   order,
-  roles,
   onSave,
   onCancel,
   onDelete,
@@ -469,99 +439,53 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
   showToolbar = true,
   showSidebar = true,
   showTimeline = true,
+  showBanners = true,
   disabled = false,
   sectionHeadingLevel,
   connections,
   showConnections = true,
-  initialDoc,
+  extraTabs,
+  renderFieldWrapper,
+  renderTab,
   loadingFallback,
   notFoundFallback,
   errorFallback,
   routePage,
-}: FrappeFormBodyProps<TDoc>) {
-  const config = useFrappeConfig();
+}: FrappeFormBodyProps<TDoc> & { form: FrappeFormController<TDoc> }) {
   const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
-  const seedDoc =
-    name && initialDoc && (initialDoc as { name?: string }).name === name ? initialDoc : undefined;
-  const seedRef = useRef(seedDoc);
-  seedRef.current = seedDoc;
-  const [localDoc, setLocalDoc] = useState<Partial<TDoc>>(() => seedDoc ?? {});
-  /** Last authoritative server snapshot applied to the form (dirty = localDoc ≠ baseline). */
-  const [baselineDoc, setBaselineDoc] = useState<Partial<TDoc> | undefined>(() => seedDoc);
-  const [docError, setDocError] = useState<Error | null>(null);
-  /** Fields the user edited that ALSO changed on the server since baseline. */
-  const [conflictFields, setConflictFields] = useState<string[]>([]);
-  /** The open document was deleted on the server (doc_deleted / tombstone / eviction). */
-  const [wasDeleted, setWasDeleted] = useState(false);
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  const [errors, setErrors] = useState<Record<string, string>>({});
-  const [activeTab, setActiveTab] = useState<string | undefined>(undefined);
-  const everLoadedRef = useRef(false);
-  const localDocRef = useRef(localDoc);
-  localDocRef.current = localDoc;
-  const baselineRef = useRef(baselineDoc);
-  baselineRef.current = baselineDoc;
-  // Taken once per create session: effects re-run (StrictMode) must not
-  // lose a draft the one-shot stash already handed over.
-  const createDraftRef = useRef<{ doctype: string; values?: Record<string, unknown> }>(undefined);
-
-  const finalBaseURL = baseURL ?? config?.baseURL;
-  const finalAuth = auth ?? config?.auth;
-  const finalSyncOptions = syncOptions ?? config?.syncOptions;
-
-  if (!finalBaseURL) {
-    throw new Error("FrappeForm requires baseURL prop or FrappeProvider with baseURL");
-  }
-
-  const frappeConfig = useMemo(
-    () => ({
-      baseURL: finalBaseURL,
-      socketPort: config?.socketPort,
-      siteName: config?.siteName,
-      socketBaseURL: config?.socketBaseURL,
-      auth: finalAuth,
-      syncOptions: finalSyncOptions,
-      realtime: config?.realtime,
-      fixtures: config?.fixtures,
-    }),
-    [
-      finalBaseURL,
-      config?.socketPort,
-      config?.siteName,
-      config?.socketBaseURL,
-      config?.realtime,
-      finalAuth,
-      finalSyncOptions,
-      config?.fixtures,
-    ],
-  );
-
-  // Fetch DocType metadata
   const {
     meta,
-    isLoading: isMetaLoading,
-    error: metaError,
-  } = useDocTypeMeta(frappeConfig, doctype);
-
-  const isSubmittable = !!meta?.is_submittable;
+    metaLoading: isMetaLoading,
+    metaError,
+    doc: localDoc,
+    baseline: baselineDoc,
+    setValue,
+    errors,
+    isSubmitting,
+    docstatus,
+    isSubmittable,
+    rights,
+    rightsPending,
+    canWrite: canWriteRecord,
+    wasDeleted,
+    conflictFields,
+    docError,
+    tabs: formTabs,
+    promptNamed,
+    activeTab,
+    setActiveTab,
+    amendedAs,
+  } = form;
+  const frappeConfig = form.connection;
   const isCreate = !name;
-  const docstatus = Number((baselineDoc as Record<string, unknown> | undefined)?.docstatus ?? 0);
-  const layoutFields = useMemo(() => {
-    if (!meta) return undefined;
-    return sections ? sectionsToLayoutFields(sections) : meta.fields;
-  }, [meta, sections]);
-  const amendedAs = useAmendedAs(
-    isSubmittable && docstatus === 2 ? frappeConfig : undefined,
-    doctype,
-    name,
-  );
+  const hasUnsavedChanges = form.isDirty;
   // Meta is permission-gated (Guest gets 403) while the record may still be
   // readable: the form then lays the record's own fields out, read-only.
   const readsWithoutMeta = !children && !meta && Boolean(metaError) && Boolean(name);
   const recordTabs = useMemo((): FormTab[] | undefined => {
     if (!readsWithoutMeta || !baselineDoc) return undefined;
-    const recordFields = fieldsFromDocument(baselineDoc as Record<string, unknown>);
+    const recordFields = schemaFieldsFromRecord(baselineDoc as Record<string, unknown>);
     return [
       {
         key: "__details",
@@ -570,89 +494,6 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
       },
     ];
   }, [readsWithoutMeta, baselineDoc, t]);
-  const promptNamed = isCreate && !!meta && isPromptNamed(meta.autoname, meta.naming_rule);
-  const fetchMap = useMemo(() => (meta ? buildFetchMap(meta.fields) : undefined), [meta]);
-
-  const handleDocSyncError = useCallback((err: unknown) => {
-    setDocError(err instanceof Error ? err : new Error(String(err)));
-  }, []);
-  const docCollection = useFrappeCollection<TDoc>(name ? frappeConfig : undefined, doctype, {
-    fields,
-    filters: name ? { name } : undefined,
-    onSyncError: handleDocSyncError,
-  });
-  const { data: rawDocData, isLoading: isDocLoading } = useLiveQuery(
-    (q) => {
-      if (!docCollection || !name) return null;
-      return q.from({ _doc: docCollection }).where(({ _doc }) => {
-        if (!_doc) return eq(name, name);
-        return eq(_doc.name, name);
-      });
-    },
-    [docCollection, name],
-  );
-  const liveDoc = useMemo(() => {
-    const arr = Array.isArray(rawDocData) ? rawDocData : rawDocData ? [rawDocData] : [];
-    const doc = (arr[0] ?? null) as TDoc | null;
-    return doc
-      ? { data: doc, isLoading: isDocLoading }
-      : name
-        ? { data: null, isLoading: isDocLoading }
-        : null;
-  }, [rawDocData, isDocLoading, name]);
-
-  // Create-mode collection (insert path). Edit-mode saves/deletes go through
-  // docCollection above — the name-filtered subscription that owns the doc —
-  // so edit mode never subscribes to the whole doctype.
-  const collection = useFrappeCollection<TDoc>(name ? undefined : frappeConfig, doctype, {
-    fields,
-  });
-
-  // Live "Shared With" rows for the sidebar (edit mode only).
-  const shareCollection = useFrappeCollection<DocShareRow>(
-    showSidebar && name ? frappeConfig : undefined,
-    "DocShare",
-    {
-      fields: ["name", "user", "everyone", "read", "write", "share"],
-      filters: { share_doctype: doctype, share_name: name },
-    },
-  );
-  const { data: rawShareRows } = useLiveQuery(
-    (q) => (shareCollection ? q.from({ _share: shareCollection }) : null),
-    [shareCollection],
-  );
-  const shareRows = useMemo(
-    () => (shareCollection ? ((rawShareRows as DocShareRow[] | undefined) ?? []) : undefined),
-    [shareCollection, rawShareRows],
-  );
-
-  const owner = (baselineDoc as Record<string, unknown> | undefined)?.owner;
-  const {
-    rights,
-    pending: rightsPending,
-    roles: effectiveRoles,
-  } = useDocRights(frappeConfig, meta, {
-    roles,
-    owner: typeof owner === "string" ? owner : undefined,
-    shares: shareRows,
-  });
-  const permLevels = useMemo(
-    () => buildPermLevelMatrix(meta?.permissions, effectiveRoles),
-    [meta?.permissions, effectiveRoles],
-  );
-  const formTabs = useMemo(() => {
-    if (!layoutFields) return undefined;
-    return buildFormTabs({
-      fields: layoutFields,
-      doc: { ...(localDoc as Record<string, unknown>), __islocal: isCreate ? 1 : 0 },
-      docstatus,
-      formReadOnly: !!meta?.read_only,
-      isCreate,
-      detailsLabel: t("Details"),
-      permLevels,
-      hiddenFields: hideFields,
-    });
-  }, [layoutFields, localDoc, docstatus, meta?.read_only, isCreate, permLevels, hideFields, t]);
 
   // Live "Assigned To" rows: the open assignment ToDos referencing this doc.
   // The doc's own `_assign` mirror is written silently (update_modified=False,
@@ -661,7 +502,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
   // source of truth. Fixture mode keeps the `_assign` fallback (no fixture
   // data exists for referencing ToDos), signalled by assignmentRows=undefined.
   const assignmentCollection = useFrappeCollection<AssignmentTodoRow>(
-    showSidebar && name && !frappeConfig.fixtures ? frappeConfig : undefined,
+    showSidebar && name && frappeConfig && !frappeConfig.fixtures ? frappeConfig : undefined,
     "ToDo",
     {
       fields: ["name", "allocated_to", "status", "reference_type", "reference_name"],
@@ -680,18 +521,6 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
     [assignmentCollection, rawAssignmentRows],
   );
 
-  // Reset per-document state when the target document changes.
-  useEffect(() => {
-    everLoadedRef.current = false;
-    if (name) createDraftRef.current = undefined;
-    setWasDeleted(false);
-    setConflictFields([]);
-    setDocError(null);
-    const seed = seedRef.current;
-    setBaselineDoc(seed);
-    if (seed) setLocalDoc(seed);
-  }, [doctype, name]);
-
   const effectiveConnections = useMemo(
     () => connections ?? connectionsFromMeta(meta),
     [connections, meta],
@@ -733,279 +562,44 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
     ({ link }) => connectionSnapshots[link.doctype]?.isLoading ?? true,
   );
 
-  // Immediate honest deleted state: the live app emits doc_deleted for the
-  // open doc's doctype room; tombstone backfill / cache eviction below is the
-  // durable fallback for deletions that happen while disconnected.
-  useFrappeDoctypeEvents(
-    name ? frappeConfig : undefined,
-    doctype,
-    (event) => {
-      if (event.type !== "doc_deleted") return;
-      const payload = event.payload as { name?: string } | undefined;
-      if (payload?.name === name) setWasDeleted(true);
-    },
-    Boolean(name),
-  );
-
-  // Field-level in-place sync: apply external updates to clean fields,
-  // preserve the user's dirty edits, and flag true conflicts (both sides
-  // changed the same field to different values) instead of clobbering.
-  useEffect(() => {
-    const incoming = liveDoc?.data as Record<string, unknown> | undefined;
-    if (incoming) {
-      everLoadedRef.current = true;
-      setWasDeleted(false);
-      const baseline = baselineRef.current as Record<string, unknown> | undefined;
-      if (!baseline) {
-        setBaselineDoc(incoming as Partial<TDoc>);
-        setLocalDoc(incoming as Partial<TDoc>);
-        return;
-      }
-      const local = localDocRef.current as Record<string, unknown>;
-      const merged: Record<string, unknown> = { ...incoming };
-      const newConflicts: string[] = [];
-      for (const key of Object.keys(local)) {
-        const localValue = local[key];
-        if (localValue === baseline[key]) continue; // clean field → take server value
-        merged[key] = localValue; // dirty field → preserve the user's edit
-        const remote = incoming[key];
-        if (remote !== baseline[key] && remote !== localValue) newConflicts.push(key);
-      }
-      setBaselineDoc(incoming as Partial<TDoc>);
-      setLocalDoc(merged as Partial<TDoc>);
-      if (newConflicts.length > 0) {
-        setConflictFields((prev) => Array.from(new Set([...prev, ...newConflicts])));
-      }
-    } else if (name && everLoadedRef.current && !liveDoc?.isLoading) {
-      // The doc was live and is now gone from the subscription: deleted on
-      // the server (doc_deleted event, CDC tombstone, or 404 eviction).
-      setWasDeleted(true);
-    } else if (!name) {
-      if (createDraftRef.current?.doctype !== doctype) {
-        createDraftRef.current = { doctype, values: takeCreatePrefill(doctype) };
-      }
-      setLocalDoc({ ...createDraftRef.current.values, doctype } as Partial<TDoc>);
-    }
-  }, [liveDoc?.data, liveDoc?.isLoading, doctype, name]);
-
-  // Dirty fields = fields where the local value diverges from the baseline.
-  const dirtyFieldNames = useMemo(() => {
-    const local = localDoc as Record<string, unknown>;
-    const base = baselineDoc as Record<string, unknown> | undefined;
-    const dirty: string[] = [];
-    for (const key of Object.keys(local)) {
-      if (key === "doctype" || key === "name") continue;
-      if (base ? local[key] !== base[key] : local[key] !== undefined) dirty.push(key);
-    }
-    return dirty;
-  }, [localDoc, baselineDoc]);
-  const hasUnsavedChanges = dirtyFieldNames.length > 0;
-
-  // fetch_from preview: a changed Link pulls its dependent columns off the
-  // linked doc (validate_link on a bench, the fixture corpus otherwise) and
-  // patches the targets; clearing the link blanks them.
-  const runFetchFrom = (field: string, value: unknown) => {
-    const rules = fetchMap?.get(field);
-    if (!rules || rules.length === 0) return;
-    const applyPatch = (fetched: Record<string, unknown>) => {
-      setLocalDoc((prev) => {
-        const current = prev as Record<string, unknown>;
-        if (current[field] !== value) return prev;
-        const patch = applyFetchedValues(rules, fetched, current);
-        return Object.keys(patch).length > 0 ? ({ ...current, ...patch } as Partial<TDoc>) : prev;
-      });
-    };
-    if (isEmptyFieldValue(value)) {
-      applyPatch({});
-      return;
-    }
-    const linkField = meta?.fields.find((metaField) => metaField.fieldname === field);
-    const targetDoctype = typeof linkField?.options === "string" ? linkField.options : "";
-    if (!targetDoctype) return;
-    const sources = Array.from(new Set(rules.map((rule) => rule.source)));
-    const fixtures = frappeConfig.fixtures;
-    const fetched = fixtures
-      ? fixtures
-          .getDoc(targetDoctype, String(value), sources)
-          .then((doc) => (doc ?? {}) as Record<string, unknown>)
-      : validateLink(createHttpClient(frappeConfig), targetDoctype, String(value), sources);
-    // An unknown link leaves the targets as they are; the server re-validates on save.
-    fetched.then(applyPatch).catch(() => undefined);
-  };
-
-  const setValue = (field: keyof TDoc, value: unknown) => {
-    setLocalDoc((prev) => ({
-      ...prev,
-      [field]: value,
-    }));
-    setErrors((prev) => {
-      const newErrors = { ...prev };
-      delete newErrors[String(field)];
-      return newErrors;
-    });
-    runFetchFrom(String(field), value);
-  };
-
-  // Required = what the engine resolved: reqd or a truthy
-  // mandatory_depends_on, on fields that are actually laid out (depends_on,
-  // permlevel and host-hidden fields never reach the tabs).
-  const validateRequiredFields = (): Record<string, string> => {
-    if (!formTabs) return {};
-    const validationErrors: Record<string, string> = {};
-    const doc = localDoc as Record<string, unknown>;
-    if (promptNamed && isEmptyFieldValue(doc.name)) {
-      validationErrors.name = t("Name is required");
-    }
-    for (const tab of formTabs) {
-      for (const field of tab.schema.fields) {
-        if (!field.required) continue;
-        if (isEmptyFieldValue(doc[field.name])) {
-          validationErrors[field.name] = t("{{label}} is required", {
-            label: field.label || field.name,
-          });
-        }
-      }
-    }
-    return validationErrors;
-  };
-
-  const canWriteRecord = isCreate ? rights.create : rights.write;
-
   const handleSave = async () => {
-    if (wasDeleted || !canWriteRecord) return;
-
-    const requiredErrors = validateRequiredFields();
-    if (Object.keys(requiredErrors).length > 0) {
-      setErrors(requiredErrors);
-      return;
-    }
-
-    setIsSubmitting(true);
-    setErrors({});
-
-    try {
-      if (name) {
-        if (!docCollection) return;
-        // Write only the dirty fields through the optimistic mutation path —
-        // clean fields stay untouched so concurrent server edits survive.
-        const changedFields = dirtyFieldNames;
-        if (changedFields.length > 0) {
-          const local = localDoc as Record<string, unknown>;
-          const tx = docCollection.update(name, (draft) => {
-            for (const key of changedFields) {
-              (draft as Record<string, unknown>)[key] = local[key];
-            }
-          });
-          await tx.isPersisted.promise;
-        }
-        setConflictFields([]);
-      } else {
-        if (!collection) return;
-        const temporaryName =
-          ((localDoc as Record<string, unknown>).name as string | undefined) ?? `new-${Date.now()}`;
-        const docToInsert = { ...localDoc, doctype, name: temporaryName } as TDoc;
-        const tx = collection.insert(docToInsert);
-        await tx.isPersisted.promise;
-        const createdName =
-          getFrappeSyncModule(frappeConfig)?.createdName(temporaryName) ?? temporaryName;
-        onSave?.({ ...localDoc, name: createdName } as Partial<TDoc>);
-        return;
-      }
-      onSave?.(localDoc as Partial<TDoc>);
-    } catch (err: unknown) {
-      const e = err as { exc_type?: string; _server_messages?: string; message?: string };
-      if (e?.exc_type === "ValidationError") {
-        const validationErrors: Record<string, string> = {};
-        if (e._server_messages) {
-          try {
-            const messages = JSON.parse(e._server_messages) as string[];
-            for (const msg of messages) {
-              const parsed =
-                typeof msg === "string" ? (JSON.parse(msg) as { message?: string }) : msg;
-              if (parsed.message) {
-                validationErrors.general = parsed.message;
-              }
-            }
-          } catch {
-            validationErrors.general = t("Validation error occurred");
-          }
-        }
-        setErrors(validationErrors);
-      } else {
-        setErrors({ general: e?.message || t("Failed to save document") });
-      }
-    } finally {
-      setIsSubmitting(false);
-    }
+    const saved = await form.save();
+    if (!saved) return;
+    onSave?.((isCreate ? { ...localDoc, name: saved } : localDoc) as Partial<TDoc>);
   };
 
   const handleCancel = () => {
-    if (baselineDoc) {
-      setLocalDoc(baselineDoc);
-    } else if (liveDoc?.data) {
-      setLocalDoc(liveDoc.data as Partial<TDoc>);
-    } else {
-      setLocalDoc({ doctype } as Partial<TDoc>);
-    }
-    setConflictFields([]);
-    setErrors({});
+    form.reset();
     onCancel?.();
   };
 
   const handleDelete = async () => {
-    if (!docCollection || !name || wasDeleted || !rights.delete) return;
+    if (!name || wasDeleted || !rights.delete) return;
     if (!(await dialog.confirm(t("Delete this {{doctype}}?", { doctype })))) return;
-    setIsSubmitting(true);
-    setErrors({});
-    try {
-      const tx = docCollection.delete(name);
-      await tx.isPersisted.promise;
-      onDelete?.(localDoc as Partial<TDoc>);
-    } catch (err) {
-      setErrors({ general: (err as Error)?.message || t("Failed to delete") });
-    } finally {
-      setIsSubmitting(false);
-    }
+    if (await form.remove()) onDelete?.(localDoc as Partial<TDoc>);
   };
 
-  // Submit and Cancel write docstatus through the collection that owns the
-  // doc: the server's save runs the transition (0 → 1 submits, 1 → 2
-  // cancels) under the same OCC as any other edit.
-  const transitionDocstatus = async (to: 1 | 2, question: string, failure: string) => {
-    if (!docCollection || !name || wasDeleted || !rights[to === 1 ? "submit" : "cancel"]) return;
-    if (to === 1) {
-      const requiredErrors = validateRequiredFields();
-      if (Object.keys(requiredErrors).length > 0) {
-        setErrors(requiredErrors);
-        return;
-      }
-    }
-    if (!(await dialog.confirm(question))) return;
-    setIsSubmitting(true);
-    setErrors({});
-    try {
-      const tx = docCollection.update(name, (draft) => {
-        (draft as Record<string, unknown>).docstatus = to;
-      });
-      await tx.isPersisted.promise;
-    } catch (err) {
-      setErrors({ general: extractServerError(err, failure) });
-    } finally {
-      setIsSubmitting(false);
+  const handleSubmitDocument = async () => {
+    if (!name || wasDeleted || !rights.submit) return;
+    const requiredErrors = form.validate();
+    if (Object.keys(requiredErrors).length > 0) {
+      form.setErrors(requiredErrors);
+      return;
     }
+    if (!(await dialog.confirm(t("Permanently Submit {{name}}?", { name })))) return;
+    await form.submitDocument();
   };
 
-  const handleSubmitDocument = () =>
-    transitionDocstatus(1, t("Permanently Submit {{name}}?", { name }), t("Failed to submit"));
-
-  const handleCancelDocument = () =>
-    transitionDocstatus(2, t("Permanently Cancel {{name}}?", { name }), t("Failed to cancel"));
+  const handleCancelDocument = async () => {
+    if (!name || wasDeleted || !rights.cancel) return;
+    if (!(await dialog.confirm(t("Permanently Cancel {{name}}?", { name })))) return;
+    await form.cancelDocument();
+  };
 
   const handleAmend = () => {
-    if (!meta || !name || !onAmend || !rights.amend) return;
-    const draft = buildAmendValues(meta.fields, localDoc as Record<string, unknown>, name);
-    setCreatePrefill(doctype, draft);
-    onAmend(draft as Partial<TDoc>);
+    if (!onAmend) return;
+    const draft = form.amend();
+    if (draft) onAmend(draft);
   };
 
   const titleField = meta?.title_field;
@@ -1066,24 +660,33 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
 
   if (!children && metaError && !meta && !name) {
     return frame(
-      <YStack {...knobProps.panelPadding} alignItems="center" {...knobProps.gap}>
-        <Text color={formCommonColors.error} {...knobProps.body}>
-          {t("Failed to load {{doctype}} form", { doctype })}
-        </Text>
-        <Text color={formCommonColors.muted} {...knobProps.body}>
-          {metaError.message}
-        </Text>
-      </YStack>,
+      isPermissionError(metaError) ? (
+        <EmptyState
+          testID="frappe-form-not-permitted"
+          title={t("You can't create {{doctype}}", { doctype })}
+          description={metaError.message}
+        />
+      ) : (
+        <AsyncBoundary
+          {...knobProps.panelPadding}
+          error={metaError}
+          errorTitle={t("Failed to load {{doctype}} form", { doctype })}
+        />
+      ),
     );
   }
 
-  // No collection yet (server render, hydration pass) reads as loading: the
-  // document is not known to be missing until the live read answers.
-  const isDocReading = Boolean(name) && (!docCollection || Boolean(liveDoc?.isLoading));
-  const showsSeed = Boolean(seedDoc) && isDocReading;
-
-  if (name && docError && !liveDoc?.data && !wasDeleted) {
+  if (name && form.status === "error" && docError) {
     if (errorFallback !== undefined) return frame(errorFallback);
+    if (isPermissionError(docError)) {
+      return frame(
+        <EmptyState
+          testID="frappe-form-not-permitted"
+          title={t("You can't open {{doctype}} {{name}}", { doctype, name })}
+          description={t("Your session can't read this {{doctype}}.", { doctype })}
+        />,
+      );
+    }
     return frame(
       <AsyncBoundary
         {...knobProps.panelPadding}
@@ -1093,7 +696,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
     );
   }
 
-  if (name && isDocReading && !showsSeed && !wasDeleted) {
+  if (name && form.status === "loading") {
     if (loadingFallback !== undefined) return frame(loadingFallback);
     return frame(
       <YStack {...knobProps.panelPadding} testID="frappe-form-skeleton">
@@ -1104,7 +707,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
 
   // Never-loaded miss (bad name, or read denied) — distinct from the
   // deleted-while-open state below, which keeps the form mounted.
-  if (name && !isDocReading && !liveDoc?.data && !wasDeleted) {
+  if (name && form.status === "notFound") {
     if (notFoundFallback !== undefined) return frame(notFoundFallback);
     return frame(
       <YStack {...knobProps.panelPadding} alignItems="center" {...knobProps.gap}>
@@ -1153,7 +756,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
   const shownTabs = formTabs ?? recordTabs;
   const imageFieldName = meta?.image_field;
   const sidebarImageUrl = imageFieldName
-    ? resolveFileUrl((localDoc as Record<string, unknown>)[imageFieldName], finalBaseURL)
+    ? resolveFileUrl((localDoc as Record<string, unknown>)[imageFieldName], frappeConfig?.baseURL)
     : undefined;
   const conflictLabels = conflictFields
     .map((fieldname) => {
@@ -1162,10 +765,8 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
     })
     .join(", ");
 
-  const formTabItems: TabsItem[] = (shownTabs ?? []).map((tab) => ({
-    value: tab.key,
-    label: tab.label,
-    content: (
+  const formTabItems: TabsItem[] = (shownTabs ?? []).map((tab) => {
+    const content = (
       <SchemaForm
         schema={tab.schema}
         doc={localDoc as Record<string, any>}
@@ -1176,13 +777,19 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
         readOnlyFields={readOnlyFields}
         sectionHeadingLevel={sectionHeadingLevel}
         order={order}
+        renderFieldWrapper={renderFieldWrapper}
       />
-    ),
-  }));
-  const tabItems: TabsItem[] =
-    showConnections && name && effectiveConnections.length > 0
+    );
+    return {
+      value: tab.key,
+      label: tab.label,
+      content: renderTab ? renderTab(tab, content) : content,
+    };
+  });
+  const tabItems: TabsItem[] = [
+    ...formTabItems,
+    ...(showConnections && name && frappeConfig && effectiveConnections.length > 0
       ? [
-          ...formTabItems,
           {
             value: "__connections",
             label: t("Connections"),
@@ -1195,7 +802,9 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
             ),
           },
         ]
-      : formTabItems;
+      : []),
+    ...(extraTabs ?? []),
+  ];
   const effectiveTab =
     activeTab && tabItems.some((tab) => tab.value === activeTab) ? activeTab : tabItems[0]?.value;
   const localName = (localDoc as Record<string, unknown>).name;
@@ -1205,7 +814,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
         imageUrl={sidebarImageUrl}
         sections={buildSidebarSections(
           localDoc as Record<string, any>,
-          shareRows,
+          form.shareRows as DocShareRow[] | undefined,
           t,
           assignmentRows,
         )}
@@ -1219,18 +828,20 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
     // collapses this stack to zero height on web — content then paints over
     // whatever follows. Bounded parents still fill (grow 1) exactly as before.
     <YStack {...knobProps.gapLg} flexGrow={1} flexShrink={1} flexBasis="auto">
-      <FrappeReconnectIndicator config={frappeConfig} />
-      {connectionReads.map((read) => (
-        <FrappeRowsReader
-          key={read.link.doctype}
-          connection={frappeConfig}
-          doctype={read.link.doctype}
-          options={read.options as never}
-          onChange={read.onChange}
-        />
-      ))}
+      {frappeConfig ? <FrappeReconnectIndicator config={frappeConfig} /> : null}
+      {frappeConfig
+        ? connectionReads.map((read) => (
+            <FrappeRowsReader
+              key={read.link.doctype}
+              connection={frappeConfig}
+              doctype={read.link.doctype}
+              options={read.options as never}
+              onChange={read.onChange}
+            />
+          ))
+        : null}
 
-      {wasDeleted && (
+      {showBanners && wasDeleted && (
         <XStack
           role="alert"
           alignItems="center"
@@ -1252,7 +863,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
         </XStack>
       )}
 
-      {!wasDeleted && conflictFields.length > 0 && (
+      {showBanners && !wasDeleted && conflictFields.length > 0 && (
         <XStack
           role="status"
           alignItems="center"
@@ -1319,7 +930,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
           )}
 
           {errors.general && (
-            <Text color={formCommonColors.error} {...knobProps.body}>
+            <Text color={formCommonColors.error} {...knobProps.body} role="alert">
               {errors.general}
             </Text>
           )}