@multiplatform.one/frappe-ui 7.11.0 → 7.15.0

package/src/FrappeForm.tsx

@@ -1,4 +1,5 @@
 import {
+  getFrappeSyncModule,
   useFrappeCollection,
   useFrappeDoctypeEvents,
   useLiveQuery,
@@ -7,32 +8,54 @@ import {
   type DocTypeField,
   type FormSection,
 } from "@multiplatform.one/frappe";
-import { AsyncSkeleton } from "@multiplatform.one/components";
 import {
-  SchemaForm,
-  type FormSchema,
-  type FormSection as GenericFormSection,
-  type FormColumn as GenericFormColumn,
-  type FieldOverride,
-} from "./schemaForm";
+  AsyncBoundary,
+  AsyncSkeleton,
+  DetailPageLayout,
+  PageHeader,
+  Tabs,
+  type TabsItem,
+} from "@multiplatform.one/components";
+import { SchemaForm, type FieldOverride } from "./schemaForm";
 import type { HeadingLevel } from "./fields/Heading";
-import type { FieldSchema } from "./fieldRegistry";
 import { FormSidebar, type SidebarSection, type SidebarMetadataEntry } from "./FormSidebar";
 import { eq } from "@tanstack/db";
-import { FloppyDiskIcon, TrashIcon, XIcon } from "@phosphor-icons/react";
+import {
+  ArrowLeftIcon,
+  FloppyDiskIcon,
+  PencilSimpleIcon,
+  TrashIcon,
+  XIcon,
+} from "@phosphor-icons/react";
 import type React from "react";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { TFunction } from "i18next";
 import { useTranslation } from "react-i18next";
-import { Button, formCommonColors } from "@multiplatform.one/forms";
+import { Button, Input, formCommonColors } from "@multiplatform.one/forms";
 import { Text, XStack, YStack } from "tamagui";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 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 { useSessionRoles } from "./formEngine/useSessionRoles";
+import { connectionFields, connectionsFromMeta, type FrappeConnection } from "./frappeConnections";
+import { FrappeFormConnections } from "./FrappeFormConnections";
+import { FrappeRowsReader, type FrappeRowsSnapshot } from "./FrappeRowsReader";
+import {
+  frappeRouteHref,
+  frappeRouteTarget,
+  useFrappeRouter,
+  type FrappeRouteTarget,
+} from "./frappeNavigation";
+import type { FieldSchema } from "./fieldRegistry";
 
-const LAYOUT_FIELDTYPES = new Set(["Section Break", "Column Break", "Tab Break"]);
+/** 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;
@@ -57,7 +80,32 @@ export interface FrappeFormProps<TDoc extends { name: string; doctype: string }>
     meta?: DocTypeMeta;
     /** True when the form is read-only (disabled prop, or doc deleted on the server). */
     disabled: boolean;
+    /** The record's linked rows per connection doctype (edit mode), live. */
+    connections: FrappeConnectionRows;
+    /** A connection's rows are still being read. */
+    connectionsLoading: boolean;
   }) => React.ReactNode;
+  /**
+   * Doctypes linking back to this one (the desk's Connections). Defaults to
+   * meta.links; declare them where the reader cannot load meta (Guest).
+   * Schema mode shows them on a Connections tab; render-prop mode hands the
+   * rows to `children`.
+   */
+  connections?: readonly FrappeConnection[];
+  /** False leaves the Connections tab out of schema mode. */
+  showConnections?: boolean;
+  /**
+   * The document a route loader rendered on the server (`loadDoc`), shown
+   * until the live read lands so the server page and the hydrated page match.
+   * Ignored unless its name is `name`.
+   */
+  initialDoc?: Partial<TDoc>;
+  /** Replaces the skeleton while the document loads. */
+  loadingFallback?: React.ReactNode;
+  /** Replaces the not-found message for a name that does not resolve. */
+  notFoundFallback?: React.ReactNode;
+  /** Replaces the error state when the document cannot be read. */
+  errorFallback?: React.ReactNode;
   /** Per-field overrides for schema-driven mode (when children not provided). */
   overrides?: Record<string, FieldOverride>;
   /** Fields to hide in schema-driven mode. */
@@ -72,9 +120,31 @@ export interface FrappeFormProps<TDoc extends { name: string; doctype: string }>
    * names are ignored. Cheaper than replacing `sections`.
    */
   order?: string[];
+  /**
+   * Session roles for permlevel resolution. Omitted: the form asks the site
+   * for them when the doctype has fields above permlevel 0, and a fixtures
+   * connection takes the conservative rule (permlevel > 0 is read-only,
+   * never hidden).
+   */
+  roles?: string[];
+  /** Called after a save; a created document carries the name the server gave it. */
   onSave?: (doc: Partial<TDoc>) => void;
   onCancel?: () => void;
   onDelete?: (doc: Partial<TDoc>) => void;
+  /**
+   * Given, the form is a read-only view of the record: its toolbar offers
+   * Edit (this callback) and Delete instead of Save and Cancel.
+   */
+  onEdit?: () => void;
+  /**
+   * The path the doctype's pages live under (`/moves`). Given, the form is
+   * the doctype's record page: it reads the record from the path through
+   * the FrappeProvider's navigation (`route/new` creates, `route/<name>`
+   * views, `route/<name>/edit` edits), carries the detail page template,
+   * and after a save, cancel, edit or delete moves to the matching page.
+   * Callbacks given alongside it replace those moves.
+   */
+  route?: string;
   showToolbar?: boolean;
   showSidebar?: boolean;
   showTimeline?: boolean;
@@ -87,56 +157,76 @@ export interface FrappeFormProps<TDoc extends { name: string; doctype: string }>
 }
 
 // ---------------------------------------------------------------------------
-// Frappe DocTypeMeta → Generic FormSchema mapper
+// Layout source for the form engine
 // ---------------------------------------------------------------------------
 
 /**
- * Maps a Frappe `DocTypeField` to a generic `FieldSchema`.
+ * 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 mapFieldToGenericSchema(field: DocTypeField): FieldSchema {
-  return {
-    type: field.fieldtype,
-    name: field.fieldname,
-    label: field.label,
-    options: field.options,
-    required: !!field.reqd,
-    hidden: !!field.hidden,
-    readOnly: !!field.read_only,
-    precision: field.precision,
-    depends_on: field.depends_on,
-    // Pass through additional Frappe-specific metadata
-    fieldtype: field.fieldtype,
-    fieldname: field.fieldname,
-    in_list_view: field.in_list_view,
-    in_standard_filter: field.in_standard_filter,
-  };
+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",
+]);
+
 /**
- * Maps Frappe `DocTypeMeta` (with optional section overrides) to a
- * generic `FormSchema` consumable by `SchemaForm` from
- * `@multiplatform.one/forms`.
+ * 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.
  */
-function mapMetaToFormSchema(meta: DocTypeMeta, sectionOverrides?: FormSection[]): FormSchema {
-  const sections = sectionOverrides ?? meta.sections;
-
-  const genericSections: GenericFormSection[] = sections.map((section) => ({
-    label: section.label,
-    collapsible: section.collapsible,
-    columns: section.columns.map(
-      (col): GenericFormColumn => ({
-        fields: col.fields.map(mapFieldToGenericSchema),
-      }),
-    ),
-  }));
-
-  // Flat list of all fields for depends_on pre-compilation
-  const allFields = meta.fields.map(mapFieldToGenericSchema);
+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,
+    }));
+}
 
-  return {
-    sections: genericSections,
-    fields: allFields,
-  };
+function hasRestrictedPermLevel(meta: DocTypeMeta | undefined): boolean {
+  return !!meta?.fields.some((field) => Number(field.permlevel ?? 0) > 0);
 }
 
 // ---------------------------------------------------------------------------
@@ -268,13 +358,75 @@ export function mapDocToSidebarMetadata(
 // ---------------------------------------------------------------------------
 
 /**
- * Thin Frappe wrapper around the generic SchemaForm component.
+ * The form for a Frappe doctype, resolved from meta by the desk form engine.
  *
- * Fetches Frappe doctype metadata and document data, maps the metadata
- * to a generic `FormSchema`, and passes it to `SchemaForm` from
- * `@multiplatform.one/forms`.
+ * Fetches doctype metadata and the document, lays the fields out through
+ * `buildFormTabs` (tabs, sections, `depends_on`, `mandatory_depends_on`,
+ * `read_only_depends_on`, `collapsible_depends_on`, permlevel,
+ * `set_only_once`, `fetch_from` and docstatus), and renders each tab with
+ * `SchemaForm`. With a `route` it is the doctype's record page.
  */
-export function FrappeForm<TDoc extends { name: string; doctype: string }>({
+export function FrappeForm<TDoc extends { name: string; doctype: string }>(
+  props: FrappeFormProps<TDoc>,
+) {
+  const { route, ...formProps } = props;
+  if (route === undefined) return <FrappeFormBody<TDoc> {...formProps} />;
+  return <FrappeFormRoute<TDoc> {...formProps} route={route} />;
+}
+
+type FrappeFormBodyProps<TDoc extends { name: string; doctype: string }> = Omit<
+  FrappeFormProps<TDoc>,
+  "route"
+> & {
+  /** Routed page: the detail template, with a back action to the list. */
+  routePage?: { onBack: () => void };
+};
+
+function FrappeFormRoute<TDoc extends { name: string; doctype: string }>({
+  route,
+  name: nameProp,
+  onSave,
+  onCancel,
+  onDelete,
+  onEdit,
+  ...props
+}: Omit<FrappeFormProps<TDoc>, "route"> & { route: string }) {
+  const router = useFrappeRouter();
+  const fromPath = router ? frappeRouteTarget(route, router.pathname) : undefined;
+  const target: FrappeRouteTarget = nameProp
+    ? { mode: fromPath?.mode === "view" ? "view" : "edit", name: nameProp }
+    : fromPath?.mode === "view" || fromPath?.mode === "edit"
+      ? fromPath
+      : { mode: "create" };
+  const go = (next: FrappeRouteTarget) => router?.navigate(frappeRouteHref(route, next));
+  const name = target.mode === "view" || target.mode === "edit" ? target.name : undefined;
+
+  return (
+    <FrappeFormBody<TDoc>
+      {...props}
+      // A new target is a new page: no state carries over from the last one.
+      key={`${target.mode}:${name ?? ""}`}
+      name={name}
+      routePage={{ onBack: () => go({ mode: "list" }) }}
+      onEdit={
+        target.mode === "view"
+          ? (onEdit ?? (() => go({ mode: "edit", name: target.name })))
+          : undefined
+      }
+      onSave={
+        onSave ??
+        ((doc) => {
+          const saved = doc.name ?? name;
+          go(saved ? { mode: "view", name: saved } : { mode: "list" });
+        })
+      }
+      onCancel={onCancel ?? (() => go(name ? { mode: "view", name } : { mode: "list" }))}
+      onDelete={onDelete ?? (() => go({ mode: "list" }))}
+    />
+  );
+}
+
+function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
   baseURL,
   auth,
   syncOptions,
@@ -287,27 +439,42 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
   readOnlyFields,
   sections,
   order,
+  roles,
   onSave,
   onCancel,
   onDelete,
+  onEdit,
   showToolbar = true,
   showSidebar = true,
   showTimeline = true,
   disabled = false,
   sectionHeadingLevel,
-}: FrappeFormProps<TDoc>) {
+  connections,
+  showConnections = true,
+  initialDoc,
+  loadingFallback,
+  notFoundFallback,
+  errorFallback,
+  routePage,
+}: FrappeFormBodyProps<TDoc>) {
   const config = useFrappeConfig();
   const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
-  const [localDoc, setLocalDoc] = useState<Partial<TDoc>>({});
+  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>(undefined);
+  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;
@@ -352,17 +519,58 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
     error: metaError,
   } = useDocTypeMeta(frappeConfig, doctype);
 
-  // Map Frappe meta to generic FormSchema
-  const formSchema = useMemo(() => {
+  const sessionRoles = useSessionRoles(
+    !roles && hasRestrictedPermLevel(meta) ? frappeConfig : undefined,
+  );
+  const effectiveRoles = roles ?? sessionRoles;
+  const permLevels = useMemo(
+    () => buildPermLevelMatrix(meta?.permissions, effectiveRoles),
+    [meta?.permissions, effectiveRoles],
+  );
+
+  const isCreate = !name;
+  const docstatus = Number((baselineDoc as Record<string, unknown> | undefined)?.docstatus ?? 0);
+  const layoutFields = useMemo(() => {
     if (!meta) return undefined;
-    return mapMetaToFormSchema(meta, sections);
+    return sections ? sectionsToLayoutFields(sections) : meta.fields;
   }, [meta, sections]);
+  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]);
+  // 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>);
+    return [
+      {
+        key: "__details",
+        label: t("Details"),
+        schema: { sections: [{ columns: [{ fields: recordFields }] }], fields: recordFields },
+      },
+    ];
+  }, [readsWithoutMeta, baselineDoc, t]);
+  const promptNamed = isCreate && !!meta && isPromptNamed(meta.autoname, meta.naming_rule);
+  const fetchMap = useMemo(() => (meta ? buildFetchMap(meta.fields) : undefined), [meta]);
 
-  const hideFieldSet = useMemo(() => new Set(hideFields ?? []), [hideFields]);
-
+  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) => {
@@ -440,9 +648,53 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
     everLoadedRef.current = false;
     setWasDeleted(false);
     setConflictFields([]);
-    setBaselineDoc(undefined);
+    setDocError(null);
+    const seed = seedRef.current;
+    setBaselineDoc(seed);
+    if (seed) setLocalDoc(seed);
   }, [doctype, name]);
 
+  const effectiveConnections = useMemo(
+    () => connections ?? connectionsFromMeta(meta),
+    [connections, meta],
+  );
+  const readsConnections = Boolean(children) && Boolean(name) && effectiveConnections.length > 0;
+  const [connectionSnapshots, setConnectionSnapshots] = useState<
+    Record<string, FrappeRowsSnapshot<Record<string, unknown> & { name: string; doctype: string }>>
+  >({});
+  useEffect(() => {
+    setConnectionSnapshots({});
+  }, [doctype, name]);
+  const connectionReads = useMemo(
+    () =>
+      readsConnections && name
+        ? effectiveConnections.map((link) => ({
+            link,
+            options: {
+              fields: connectionFields(link),
+              filters: [[link.fieldname, "=", name]] as Array<[string, string, unknown]>,
+              limit: link.limit ?? 0,
+            },
+            onChange: (
+              snapshot: FrappeRowsSnapshot<
+                Record<string, unknown> & { name: string; doctype: string }
+              >,
+            ) => setConnectionSnapshots((prev) => ({ ...prev, [link.doctype]: snapshot })),
+          }))
+        : [],
+    [readsConnections, effectiveConnections, name],
+  );
+  const connectionRows = useMemo(() => {
+    const rows: FrappeConnectionRows = {};
+    for (const { link } of connectionReads) {
+      rows[link.doctype] = connectionSnapshots[link.doctype]?.rows ?? [];
+    }
+    return rows;
+  }, [connectionReads, connectionSnapshots]);
+  const connectionsLoading = connectionReads.some(
+    ({ 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.
@@ -508,6 +760,38 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
   }, [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,
@@ -518,20 +802,27 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
       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 (!meta) return {};
+    if (!formTabs) return {};
     const validationErrors: Record<string, string> = {};
     const doc = localDoc as Record<string, unknown>;
-    for (const field of meta.fields) {
-      if (!field.reqd) continue;
-      if (field.hidden || LAYOUT_FIELDTYPES.has(field.fieldtype)) continue;
-      if (hideFieldSet.has(field.fieldname)) continue;
-      if (isEmptyFieldValue(doc[field.fieldname])) {
-        validationErrors[field.fieldname] = t("{{label}} is required", {
-          label: field.label || field.fieldname,
-        });
+    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;
@@ -567,15 +858,15 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
         setConflictFields([]);
       } else {
         if (!collection) return;
-        const docToInsert = {
-          ...localDoc,
-          doctype,
-          name:
-            ((localDoc as Record<string, unknown>).name as string | undefined) ??
-            `new-${Date.now()}`,
-        } as TDoc;
+        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) {
@@ -634,17 +925,46 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
     }
   };
 
+  const titleField = meta?.title_field;
+  const titleValue = titleField ? (localDoc as Record<string, unknown>)[titleField] : undefined;
+  const pageTitle = isCreate ? t("New {{doctype}}", { doctype }) : String(titleValue || name);
+  const frame = (content: React.ReactNode, aside?: React.ReactNode) =>
+    routePage ? (
+      // flexBasis auto: see DeskFormPage (react-native-web's min-height:0
+      // reset would cap the scroll page at viewport height).
+      <DetailPageLayout
+        flexBasis="auto"
+        toolbarLeading={
+          <Button
+            size="$3"
+            chromeless
+            icon={ArrowLeftIcon}
+            onPress={routePage.onBack}
+            aria-label={t("Back to {{doctype}} list", { doctype })}
+          >
+            {doctype}
+          </Button>
+        }
+        header={<PageHeader title={pageTitle} divider={false} />}
+        aside={aside}
+      >
+        {content}
+      </DetailPageLayout>
+    ) : (
+      content
+    );
+
   // Schema-driven mode needs meta; render-prop mode can proceed without it.
   if (!children && isMetaLoading && !meta) {
-    return (
+    return frame(
       <YStack {...knobProps.panelPadding} testID="frappe-form-skeleton">
         <AsyncSkeleton layout="generic" />
-      </YStack>
+      </YStack>,
     );
   }
 
-  if (!children && metaError && !meta) {
-    return (
+  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 })}
@@ -652,22 +972,40 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
         <Text color={formCommonColors.muted} {...knobProps.body}>
           {metaError.message}
         </Text>
-      </YStack>
+      </YStack>,
+    );
+  }
+
+  // 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 (errorFallback !== undefined) return frame(errorFallback);
+    return frame(
+      <AsyncBoundary
+        {...knobProps.panelPadding}
+        error={docError}
+        errorTitle={t("Failed to load {{doctype}}", { doctype })}
+      />,
     );
   }
 
-  if (name && liveDoc?.isLoading && !wasDeleted) {
-    return (
+  if (name && isDocReading && !showsSeed && !wasDeleted) {
+    if (loadingFallback !== undefined) return frame(loadingFallback);
+    return frame(
       <YStack {...knobProps.panelPadding} testID="frappe-form-skeleton">
         <AsyncSkeleton layout="generic" />
-      </YStack>
+      </YStack>,
     );
   }
 
   // Never-loaded miss (bad name, or read denied) — distinct from the
   // deleted-while-open state below, which keeps the form mounted.
-  if (name && !liveDoc?.isLoading && !liveDoc?.data && !wasDeleted) {
-    return (
+  if (name && !isDocReading && !liveDoc?.data && !wasDeleted) {
+    if (notFoundFallback !== undefined) return frame(notFoundFallback);
+    return frame(
       <YStack {...knobProps.panelPadding} alignItems="center" {...knobProps.gap}>
         <Text color={formCommonColors.error} {...knobProps.body}>
           {t("{{doctype}} not found", { doctype })}
@@ -675,11 +1013,14 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
         <Text color={formCommonColors.muted} {...knobProps.body}>
           {t("Document {{name}} does not exist or could not be loaded.", { name })}
         </Text>
-      </YStack>
+      </YStack>,
     );
   }
 
   const effectiveDisabled = disabled || wasDeleted;
+  const readOnlyView = Boolean(onEdit) || readsWithoutMeta;
+  const fieldsDisabled = effectiveDisabled || readOnlyView;
+  const shownTabs = formTabs ?? recordTabs;
   const imageFieldName = meta?.image_field;
   const sidebarImageUrl = imageFieldName
     ? resolveFileUrl((localDoc as Record<string, unknown>)[imageFieldName], finalBaseURL)
@@ -691,13 +1032,73 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
     })
     .join(", ");
 
-  return (
+  const formTabItems: TabsItem[] = (shownTabs ?? []).map((tab) => ({
+    value: tab.key,
+    label: tab.label,
+    content: (
+      <SchemaForm
+        schema={tab.schema}
+        doc={localDoc as Record<string, any>}
+        setValue={(field, value) => setValue(field as keyof TDoc, value)}
+        errors={errors}
+        disabled={fieldsDisabled}
+        overrides={overrides}
+        readOnlyFields={readOnlyFields}
+        sectionHeadingLevel={sectionHeadingLevel}
+        order={order}
+      />
+    ),
+  }));
+  const tabItems: TabsItem[] =
+    showConnections && name && effectiveConnections.length > 0
+      ? [
+          ...formTabItems,
+          {
+            value: "__connections",
+            label: t("Connections"),
+            content: (
+              <FrappeFormConnections
+                connection={frappeConfig}
+                connections={effectiveConnections}
+                name={name}
+              />
+            ),
+          },
+        ]
+      : formTabItems;
+  const effectiveTab =
+    activeTab && tabItems.some((tab) => tab.value === activeTab) ? activeTab : tabItems[0]?.value;
+  const localName = (localDoc as Record<string, unknown>).name;
+  const sidebar =
+    showSidebar && name && meta ? (
+      <FormSidebar
+        imageUrl={sidebarImageUrl}
+        sections={buildSidebarSections(
+          localDoc as Record<string, any>,
+          shareRows,
+          t,
+          assignmentRows,
+        )}
+        metadata={mapDocToSidebarMetadata(localDoc as Record<string, any>, t)}
+      />
+    ) : undefined;
+
+  return frame(
     // flexBasis auto (not the flex:1 shorthand's 0%): inside scroll-flow page
     // scaffolds (LC-29 templates) the parent is auto-height, and a 0% basis
     // 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}
+        />
+      ))}
 
       {wasDeleted && (
         <XStack
@@ -742,19 +1143,9 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
       {/* flexBasis auto — see the root stack note (zero-height collapse in
           auto-height scroll flows would paint the Timeline over the form). */}
       <XStack flexGrow={1} flexShrink={1} flexBasis="auto" {...knobProps.gapLg}>
-        {/* Sidebar (edit mode only) — assignments/shares/image are live */}
-        {showSidebar && name && meta && (
-          <FormSidebar
-            imageUrl={sidebarImageUrl}
-            sections={buildSidebarSections(
-              localDoc as Record<string, any>,
-              shareRows,
-              t,
-              assignmentRows,
-            )}
-            metadata={mapDocToSidebarMetadata(localDoc as Record<string, any>, t)}
-          />
-        )}
+        {/* Sidebar (edit mode only) — assignments/shares/image are live.
+            A routed page carries it in the template's aside instead. */}
+        {routePage ? null : sidebar}
 
         {/* Form body */}
         <YStack flex={1} {...knobProps.gapLg}>
@@ -766,22 +1157,28 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
               isSubmitting,
               errors,
               meta,
-              disabled: effectiveDisabled,
+              disabled: fieldsDisabled,
+              connections: connectionRows,
+              connectionsLoading,
             })
-          ) : formSchema ? (
-            // Schema-driven mode using generic SchemaForm from @multiplatform.one/forms
-            <SchemaForm
-              schema={formSchema}
-              doc={localDoc as Record<string, any>}
-              setValue={(field, value) => setValue(field as keyof TDoc, value)}
-              errors={errors}
-              disabled={effectiveDisabled}
-              overrides={overrides}
-              hideFields={hideFields}
-              readOnlyFields={readOnlyFields}
-              sectionHeadingLevel={sectionHeadingLevel}
-              order={order}
-            />
+          ) : shownTabs ? (
+            <YStack {...knobProps.gapLg}>
+              {promptNamed && (
+                <Input
+                  label={t("Name")}
+                  value={typeof localName === "string" ? localName : ""}
+                  onChangeText={(value) => setValue("name" as keyof TDoc, value)}
+                  placeholder={t("New document name")}
+                  error={errors.name}
+                  disabled={effectiveDisabled}
+                />
+              )}
+              {tabItems.length > 1 ? (
+                <Tabs items={tabItems} value={effectiveTab} onChange={setActiveTab} lazyMount />
+              ) : (
+                (tabItems[0]?.content ?? null)
+              )}
+            </YStack>
           ) : (
             // Metadata unavailable (should be covered by metaError branch above)
             <YStack {...knobProps.panelPadding} alignItems="center">
@@ -797,14 +1194,14 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
             </Text>
           )}
 
-          {showToolbar && (
+          {showToolbar && !readsWithoutMeta && (
             <XStack
               {...knobProps.gap}
               justifyContent="flex-end"
               alignItems="center"
               paddingTop="$3"
             >
-              {hasUnsavedChanges && (
+              {hasUnsavedChanges && !onEdit && (
                 <Text color="$orange11" marginInlineEnd="auto" {...knobProps.body}>
                   {t("Not Saved")}
                 </Text>
@@ -825,37 +1222,55 @@ export function FrappeForm<TDoc extends { name: string; doctype: string }>({
                 </Button>
               )}
 
-              {onCancel && (
+              {onEdit ? (
                 <Button
-                  outlined
-                  icon={XIcon}
-                  disabled={isSubmitting || disabled}
+                  accent
+                  icon={PencilSimpleIcon}
+                  disabled={effectiveDisabled}
                   disabledReason={t("Form is read-only")}
                   disabledReasonPlacement="inline"
-                  onPress={handleCancel}
+                  onPress={onEdit}
                 >
-                  {t("Cancel")}
+                  {t("Edit")}
                 </Button>
-              )}
+              ) : (
+                <>
+                  {onCancel && (
+                    <Button
+                      outlined
+                      icon={XIcon}
+                      disabled={disabled}
+                      disabledReason={t("Form is read-only")}
+                      disabledReasonPlacement="inline"
+                      onPress={handleCancel}
+                    >
+                      {t("Cancel")}
+                    </Button>
+                  )}
 
-              <Button
-                accent
-                icon={FloppyDiskIcon}
-                loading={isSubmitting}
-                disabled={effectiveDisabled}
-                disabledReason={t("Form is read-only")}
-                disabledReasonPlacement="inline"
-                onPress={handleSave}
-              >
-                {isSubmitting ? t("Saving...") : t("Save")}
-              </Button>
+                  <Button
+                    accent
+                    icon={FloppyDiskIcon}
+                    loading={isSubmitting}
+                    disabled={effectiveDisabled}
+                    disabledReason={t("Form is read-only")}
+                    disabledReasonPlacement="inline"
+                    onPress={handleSave}
+                  >
+                    {isSubmitting ? t("Saving...") : t("Save")}
+                  </Button>
+                </>
+              )}
             </XStack>
           )}
         </YStack>
       </XStack>
 
       {/* Timeline (edit mode only) — live Comment/Version via useFrappeCollection */}
-      {showTimeline && name && <Timeline doctype={doctype} docname={name} label={t("Activity")} />}
-    </YStack>
+      {showTimeline && name && !readsWithoutMeta && (
+        <Timeline doctype={doctype} docname={name} label={t("Activity")} />
+      )}
+    </YStack>,
+    routePage ? sidebar : undefined,
   );
 }