@multiplatform.one/frappe-ui 7.22.0 → 7.23.0

package/src/FrappeForm.tsx

@@ -21,13 +21,7 @@ import { SchemaForm, type FieldOverride } from "./schemaForm";
 import type { HeadingLevel } from "./fields/Heading";
 import { FormSidebar, type SidebarSection, type SidebarMetadataEntry } from "./FormSidebar";
 import { eq } from "@tanstack/db";
-import {
-  ArrowLeftIcon,
-  FloppyDiskIcon,
-  PencilSimpleIcon,
-  TrashIcon,
-  XIcon,
-} from "@phosphor-icons/react";
+import { ArrowLeftIcon } from "@phosphor-icons/react";
 import type React from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { TFunction } from "i18next";
@@ -43,7 +37,19 @@ 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 {
+  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 { FrappeRowsReader, type FrappeRowsSnapshot } from "./FrappeRowsReader";
@@ -132,9 +138,18 @@ export interface FrappeFormProps<TDoc extends { name: string; doctype: string }>
   onSave?: (doc: Partial<TDoc>) => void;
   onCancel?: () => void;
   onDelete?: (doc: Partial<TDoc>) => void;
+  /**
+   * Opens the amended draft of a cancelled document (desk Amend). The draft
+   * carries `amended_from` and is also handed to the doctype's next
+   * create-mode FrappeForm, so navigating to one is enough. Absent, a
+   * cancelled document offers no Amend.
+   */
+  onAmend?: (draft: 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.
+   * Edit (this callback) instead of Save and Cancel, beside Delete and the
+   * document's Submit, Cancel or Amend. A document with nothing left to
+   * edit (cancelled, or submitted without allow_on_submit fields) shows no Edit.
    */
   onEdit?: () => void;
   /**
@@ -142,8 +157,9 @@ export interface FrappeFormProps<TDoc extends { name: string; doctype: string }>
    * 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.
+   * and after a save, cancel, edit or delete moves to the matching page;
+   * Amend opens the amended draft on `route/new`. Callbacks given alongside
+   * it replace those moves.
    */
   route?: string;
   showToolbar?: boolean;
@@ -386,6 +402,7 @@ function FrappeFormRoute<TDoc extends { name: string; doctype: string }>({
   onCancel,
   onDelete,
   onEdit,
+  onAmend,
   ...props
 }: Omit<FrappeFormProps<TDoc>, "route"> & { route: string }) {
   const router = useFrappeRouter();
@@ -419,6 +436,7 @@ function FrappeFormRoute<TDoc extends { name: string; doctype: string }>({
       }
       onCancel={onCancel ?? (() => go(name ? { mode: "view", name } : { mode: "list" }))}
       onDelete={onDelete ?? (() => go({ mode: "list" }))}
+      onAmend={onAmend ?? (() => go({ mode: "create" }))}
     />
   );
 }
@@ -440,6 +458,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
   onSave,
   onCancel,
   onDelete,
+  onAmend,
   onEdit,
   showToolbar = true,
   showSidebar = true,
@@ -477,6 +496,9 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
   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;
@@ -516,12 +538,18 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
     error: metaError,
   } = useDocTypeMeta(frappeConfig, doctype);
 
+  const isSubmittable = !!meta?.is_submittable;
   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,
+  );
   // 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);
@@ -649,6 +677,7 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
   // Reset per-document state when the target document changes.
   useEffect(() => {
     everLoadedRef.current = false;
+    if (name) createDraftRef.current = undefined;
     setWasDeleted(false);
     setConflictFields([]);
     setDocError(null);
@@ -746,7 +775,10 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
       // the server (doc_deleted event, CDC tombstone, or 404 eviction).
       setWasDeleted(true);
     } else if (!name) {
-      setLocalDoc({ doctype } as Partial<TDoc>);
+      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]);
 
@@ -930,6 +962,46 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
     }
   };
 
+  // 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 = () =>
+    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 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>);
+  };
+
   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);
@@ -1043,15 +1115,35 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
   const effectiveDisabled = disabled || wasDeleted;
   const readOnlyView = Boolean(onEdit) || readsWithoutMeta;
   const fieldsDisabled = effectiveDisabled || readOnlyView || !canWriteRecord;
-  const showDelete = Boolean(name && onDelete && !wasDeleted && rights.delete);
-  const showEdit = Boolean(onEdit && rights.write);
-  const showSave = !onEdit && canWriteRecord;
-  const showCancel = !onEdit && Boolean(onCancel);
-  const showNotSaved = hasUnsavedChanges && !onEdit;
+  const indicator = resolveDocIndicator({
+    docstatus,
+    isCreate,
+    isDirty: hasUnsavedChanges && !onEdit,
+    isSubmittable,
+  });
+  const docAction = resolveDocAction({
+    docstatus,
+    isCreate,
+    isDirty: hasUnsavedChanges,
+    isSubmittable,
+    perms: {
+      write: canWriteRecord,
+      submit: rights.submit,
+      cancel: rights.cancel,
+      amend: rights.amend,
+    },
+    isReadOnlyView: Boolean(onEdit),
+  });
+  const showDelete = Boolean(
+    name && onDelete && !wasDeleted && rights.delete && canDeleteDoc(docstatus),
+  );
+  const showEdit = Boolean(onEdit && rights.write && canEditDoc(docstatus, meta));
+  const showAmend = Boolean(onAmend && isAmendable(meta));
+  const showClose = !onEdit && Boolean(onCancel);
   const toolbarShown =
     showToolbar &&
     !readsWithoutMeta &&
-    (showDelete || showEdit || showSave || showCancel || showNotSaved);
+    Boolean(indicator || docAction || showDelete || showEdit || showClose);
   const shownTabs = formTabs ?? recordTabs;
   const imageFieldName = meta?.image_field;
   const sidebarImageUrl = imageFieldName
@@ -1227,73 +1319,21 @@ function FrappeFormBody<TDoc extends { name: string; doctype: string }>({
           )}
 
           {toolbarShown && (
-            <XStack
-              {...knobProps.gap}
-              justifyContent="flex-end"
-              alignItems="center"
-              paddingTop="$3"
-            >
-              {showNotSaved && (
-                <Text color="$orange11" marginInlineEnd="auto" {...knobProps.body}>
-                  {t("Not Saved")}
-                </Text>
-              )}
-
-              {showDelete && (
-                <Button
-                  outlined
-                  error
-                  icon={TrashIcon}
-                  loading={isSubmitting}
-                  disabled={effectiveDisabled}
-                  disabledReason={t("Form is read-only")}
-                  disabledReasonPlacement="inline"
-                  onPress={handleDelete}
-                >
-                  {t("Delete")}
-                </Button>
-              )}
-
-              {showEdit && (
-                <Button
-                  accent
-                  icon={PencilSimpleIcon}
-                  disabled={effectiveDisabled}
-                  disabledReason={t("Form is read-only")}
-                  disabledReasonPlacement="inline"
-                  onPress={onEdit}
-                >
-                  {t("Edit")}
-                </Button>
-              )}
-
-              {showCancel && (
-                <Button
-                  outlined
-                  icon={XIcon}
-                  disabled={disabled}
-                  disabledReason={t("Form is read-only")}
-                  disabledReasonPlacement="inline"
-                  onPress={handleCancel}
-                >
-                  {t("Cancel")}
-                </Button>
-              )}
-
-              {showSave && (
-                <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>
+            <FrappeFormActions
+              indicator={indicator}
+              action={docAction}
+              busy={isSubmitting}
+              disabled={effectiveDisabled}
+              onSave={handleSave}
+              onSubmit={handleSubmitDocument}
+              onCancelDocument={handleCancelDocument}
+              onAmend={showAmend ? handleAmend : undefined}
+              amendedAs={amendedAs}
+              onDelete={showDelete ? handleDelete : undefined}
+              onEdit={showEdit ? onEdit : undefined}
+              onClose={showClose ? handleCancel : undefined}
+              closeDisabled={disabled}
+            />
           )}
         </YStack>
       </XStack>

package/src/FrappeFormActions.tsx

@@ -0,0 +1,216 @@
+import { Chip, type ChipColor } from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  ArrowCounterClockwiseIcon,
+  CheckCircleIcon,
+  FloppyDiskIcon,
+  PencilSimpleIcon,
+  ProhibitIcon,
+  TrashIcon,
+  XIcon,
+} from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
+import { XStack } from "tamagui";
+import type { DocAction, DocStatusIndicator } from "./formEngine/docLifecycle";
+
+const indicatorColors: Record<DocStatusIndicator, ChipColor> = {
+  notSaved: "orange",
+  draft: "red",
+  submitted: "blue",
+  cancelled: "red",
+};
+
+export interface FrappeFormActionsProps {
+  /** Desk's state pill: Not Saved, Draft, Submitted or Cancelled. */
+  indicator?: DocStatusIndicator;
+  /** The one lifecycle action the document's state offers (resolveDocAction). */
+  action?: DocAction;
+  /** A save or a docstatus transition is in flight. */
+  busy: boolean;
+  /** The form is read-only: actions render, disabled with the reason. */
+  disabled: boolean;
+  onSave: () => void;
+  onSubmit: () => void;
+  /** Cancels the submitted document (docstatus 1 → 2). */
+  onCancelDocument: () => void;
+  /** Absent, a cancelled document offers no Amend: the host has nowhere to open the draft. */
+  onAmend?: () => void;
+  /** The live amendment of this cancelled document; Amend stays disabled while it exists. */
+  amendedAs?: string;
+  onDelete?: () => void;
+  /**
+   * Given, the form is a read-only view and this opens its editor. The
+   * caller leaves it out when the document has nothing left to edit.
+   */
+  onEdit?: () => void;
+  /** The host's leave action (discards unsaved edits first). */
+  onClose?: () => void;
+  closeDisabled?: boolean;
+}
+
+/**
+ * FrappeForm's action bar with desk's docstatus lifecycle: one primary
+ * action at a time (Save, Submit, Update or Amend), Cancel Document as the
+ * secondary destructive action on a submitted document, and the state pill.
+ * A read-only view trades Save and the leave button for Edit.
+ */
+export function FrappeFormActions({
+  indicator,
+  action,
+  busy,
+  disabled,
+  onSave,
+  onSubmit,
+  onCancelDocument,
+  onAmend,
+  amendedAs,
+  onDelete,
+  onEdit,
+  onClose,
+  closeDisabled,
+}: FrappeFormActionsProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const readOnlyReason = t("Form is read-only");
+
+  const indicatorLabels: Record<DocStatusIndicator, string> = {
+    notSaved: t("Not Saved"),
+    draft: t("Draft"),
+    submitted: t("Submitted"),
+    cancelled: t("Cancelled"),
+  };
+
+  return (
+    <XStack
+      {...knobProps.gap}
+      justifyContent="flex-end"
+      alignItems="center"
+      paddingTop="$3"
+      testID="frappe-form-actions"
+    >
+      {indicator && (
+        <XStack flex={1} alignItems="center" testID={`frappe-form-status-${indicator}`}>
+          <Chip size="$2" variant="subtle" color={indicatorColors[indicator]}>
+            {indicatorLabels[indicator]}
+          </Chip>
+        </XStack>
+      )}
+
+      {onDelete && (
+        <Button
+          outlined
+          error
+          icon={TrashIcon}
+          loading={busy}
+          disabled={disabled}
+          disabledReason={disabled ? readOnlyReason : undefined}
+          disabledReasonPlacement="inline"
+          onPress={onDelete}
+        >
+          {t("Delete")}
+        </Button>
+      )}
+
+      {onClose && (
+        <Button
+          outlined
+          icon={XIcon}
+          disabled={closeDisabled}
+          disabledReason={closeDisabled ? readOnlyReason : undefined}
+          disabledReasonPlacement="inline"
+          onPress={onClose}
+          testID="frappe-form-close"
+        >
+          {/* A submitted document's own Cancel sits beside this button. */}
+          {action === "cancel" ? t("Close") : t("Cancel")}
+        </Button>
+      )}
+
+      {action === "cancel" && (
+        <Button
+          outlined
+          error
+          actionRole="secondary"
+          icon={ProhibitIcon}
+          loading={busy}
+          disabled={disabled}
+          disabledReason={disabled ? readOnlyReason : undefined}
+          disabledReasonPlacement="inline"
+          onPress={onCancelDocument}
+          testID="frappe-form-cancel-document"
+        >
+          {t("Cancel Document")}
+        </Button>
+      )}
+
+      {onEdit && (
+        <Button
+          accent={action !== "submit"}
+          outlined={action === "submit"}
+          icon={PencilSimpleIcon}
+          disabled={disabled}
+          disabledReason={disabled ? readOnlyReason : undefined}
+          disabledReasonPlacement="inline"
+          onPress={onEdit}
+          testID="frappe-form-edit"
+        >
+          {t("Edit")}
+        </Button>
+      )}
+
+      {action === "amend" && onAmend && (
+        <Button
+          // Desk demotes Amend to a secondary action once the document is amended.
+          accent={!amendedAs}
+          outlined={Boolean(amendedAs)}
+          icon={ArrowCounterClockwiseIcon}
+          loading={busy}
+          disabled={disabled || Boolean(amendedAs)}
+          disabledReason={
+            amendedAs
+              ? t("Already amended as {{name}}", { name: amendedAs })
+              : disabled
+                ? readOnlyReason
+                : undefined
+          }
+          disabledReasonPlacement="inline"
+          onPress={onAmend}
+          testID="frappe-form-amend"
+        >
+          {t("Amend")}
+        </Button>
+      )}
+
+      {action === "submit" && (
+        <Button
+          accent
+          icon={CheckCircleIcon}
+          loading={busy}
+          disabled={disabled}
+          disabledReason={disabled ? readOnlyReason : undefined}
+          disabledReasonPlacement="inline"
+          onPress={onSubmit}
+          testID="frappe-form-submit"
+        >
+          {t("Submit")}
+        </Button>
+      )}
+
+      {(action === "save" || action === "update") && (
+        <Button
+          accent
+          icon={FloppyDiskIcon}
+          loading={busy}
+          disabled={disabled}
+          disabledReason={disabled ? readOnlyReason : undefined}
+          disabledReasonPlacement="inline"
+          onPress={onSave}
+          testID="frappe-form-save"
+        >
+          {busy ? t("Saving...") : action === "update" ? t("Update") : t("Save")}
+        </Button>
+      )}
+    </XStack>
+  );
+}