@multiplatform.one/frappe-ui 7.22.0 → 7.23.1

package/src/formEngine/docLifecycle.ts

@@ -0,0 +1,148 @@
+/**
+ * The docstatus lifecycle of a submittable doctype, with desk's rules
+ * (frappe/public/js/frappe/form/toolbar.js `get_action_status`,
+ * form.js `amend_doc`, model/create_new.js `copy_doc`):
+ *
+ *   docstatus 0  Draft      Save, or Submit once saved and clean
+ *   docstatus 1  Submitted  Update when an allow_on_submit field is dirty,
+ *                           else Cancel
+ *   docstatus 2  Cancelled  Amend into a new draft with amended_from
+ *
+ * The toolbar shows exactly one of those actions at a time, picked in
+ * desk's order: Submit, Save, Update, Cancel, Amend. A submitted document
+ * cannot be deleted. A read-only view (a record page) has no Save or
+ * Update: its Edit opens the editor, and Submit, Cancel and Amend stay.
+ */
+
+import { formatCalendarDate } from "@multiplatform.one/theme";
+import type { DocRights } from "./docPermissions";
+import type { DocFieldMeta, DoctypeMeta } from "./doctypeMeta";
+
+export type DocAction = "save" | "submit" | "update" | "cancel" | "amend";
+
+export type DocStatusIndicator = "notSaved" | "draft" | "submitted" | "cancelled";
+
+/**
+ * The session's level-0 rights the toolbar needs (desk `frm.perm[0]`), as
+ * docPermissions.ts resolves them. `write` is `create` on a new document.
+ */
+export type DocActionPerms = Pick<DocRights, "write" | "submit" | "cancel" | "amend">;
+
+export interface DocActionState {
+  docstatus: number;
+  isCreate: boolean;
+  isDirty: boolean;
+  isSubmittable: boolean;
+  perms: DocActionPerms;
+  /** The form is a read-only view whose Edit stands in for Save and Update. */
+  isReadOnlyView?: boolean;
+}
+
+/** The one lifecycle action desk offers for this state, if any. */
+export function resolveDocAction(state: DocActionState): DocAction | undefined {
+  const action = resolveDeskAction(state);
+  if (state.isReadOnlyView && (action === "save" || action === "update")) return undefined;
+  return action;
+}
+
+function resolveDeskAction(state: DocActionState): DocAction | undefined {
+  const { docstatus, isCreate, isDirty, isSubmittable, perms } = state;
+  if (docstatus === 0) {
+    if (isSubmittable && !isCreate && !isDirty && perms.submit) return "submit";
+    return perms.write ? "save" : undefined;
+  }
+  if (!isSubmittable) return undefined;
+  if (docstatus === 1) {
+    if (isDirty && perms.write && perms.submit) return "update";
+    return perms.cancel ? "cancel" : undefined;
+  }
+  if (docstatus === 2 && perms.amend) return "amend";
+  return undefined;
+}
+
+/** Desk hides Delete on a submitted document. */
+export function canDeleteDoc(docstatus: number): boolean {
+  return docstatus !== 1;
+}
+
+/**
+ * A saved document still has something to edit: any draft, a submitted one
+ * only through its allow_on_submit fields, a cancelled one nothing.
+ */
+export function canEditDoc(
+  docstatus: number,
+  meta: Pick<DoctypeMeta, "fields"> | undefined,
+): boolean {
+  if (docstatus === 0) return true;
+  if (docstatus === 1) return !!meta?.fields.some((field) => field.allow_on_submit);
+  return false;
+}
+
+/** Desk's title indicator for the document's state. */
+export function resolveDocIndicator(state: {
+  docstatus: number;
+  isCreate: boolean;
+  isDirty: boolean;
+  isSubmittable: boolean;
+}): DocStatusIndicator | undefined {
+  if (state.isCreate || state.isDirty) return "notSaved";
+  if (state.docstatus === 1) return "submitted";
+  if (state.docstatus === 2) return "cancelled";
+  return state.isSubmittable ? "draft" : undefined;
+}
+
+/** Desk refuses to amend a doctype that has no `amended_from` field. */
+export function isAmendable(meta: Pick<DoctypeMeta, "fields"> | undefined): boolean {
+  return !!meta?.fields.some((field) => field.fieldname === "amended_from");
+}
+
+const amendSkipped = new Set(["name", "amended_from", "amendment_date", "cancel_reason"]);
+const rowBookkeeping = new Set([
+  "name",
+  "parent",
+  "parentfield",
+  "parenttype",
+  "owner",
+  "creation",
+  "modified",
+  "modified_by",
+  "docstatus",
+]);
+const tableTypes = new Set(["Table", "Table MultiSelect"]);
+
+/**
+ * The new draft Amend opens (desk `copy_doc(doc, from_amend=1)`): every
+ * field value including `no_copy` ones, never a password, child rows
+ * stripped of their identity, `amended_from` pointing at the cancelled
+ * document and `amendment_date` set to today when the doctype has one.
+ */
+export function buildAmendValues(
+  fields: DocFieldMeta[],
+  doc: Record<string, unknown>,
+  cancelledName: string,
+): Record<string, unknown> {
+  const draft: Record<string, unknown> = {};
+  for (const field of fields) {
+    if (amendSkipped.has(field.fieldname) || field.fieldtype === "Password") continue;
+    const value = doc[field.fieldname];
+    if (value === undefined) continue;
+    if (tableTypes.has(field.fieldtype)) {
+      if (!Array.isArray(value)) continue;
+      draft[field.fieldname] = value.map((row) =>
+        Object.fromEntries(
+          Object.entries((row ?? {}) as Record<string, unknown>).filter(
+            ([key]) => !rowBookkeeping.has(key),
+          ),
+        ),
+      );
+      continue;
+    }
+    draft[field.fieldname] = value;
+  }
+  draft.amended_from = cancelledName;
+  draft.docstatus = 0;
+  if (fields.some((field) => field.fieldname === "amendment_date")) {
+    draft.amendment_date = formatCalendarDate(new Date());
+  }
+  return draft;
+}

package/src/formEngine/useAmendedAs.ts

@@ -0,0 +1,38 @@
+import { eq, useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import { useMemo } from "react";
+import type { FrappeConnection } from "./formActions";
+
+interface AmendmentRow {
+  name: string;
+  doctype: string;
+  amended_from?: string;
+  docstatus?: number;
+}
+
+/**
+ * The live amendment of a cancelled document: a document amended from
+ * `name` that is not itself cancelled (desk
+ * `frappe.client.is_document_amended`). Desk disables Amend while one
+ * exists. Pass no connection to skip the read.
+ */
+export function useAmendedAs(
+  connection: FrappeConnection | undefined,
+  doctype: string,
+  name: string | undefined,
+): string | undefined {
+  const collection = useFrappeCollection<AmendmentRow>(name ? connection : undefined, doctype, {
+    fields: ["name", "amended_from", "docstatus"],
+    filters: name ? { amended_from: name } : undefined,
+  });
+  const { data } = useLiveQuery(
+    (q) =>
+      collection && name
+        ? q.from({ _row: collection }).where(({ _row }) => eq(_row.amended_from, name))
+        : null,
+    [collection, name],
+  );
+  return useMemo(() => {
+    const rows = (Array.isArray(data) ? data : []) as AmendmentRow[];
+    return rows.find((row) => Number(row.docstatus ?? 0) < 2)?.name;
+  }, [data]);
+}

package/src/formEngine/useDocRights.ts

@@ -4,7 +4,7 @@ import type { DoctypeMeta } from "./doctypeMeta";
 import { useFrappeSession, type SessionConnection } from "./useSessionRoles";
 
 export interface DocRightsOptions {
-  /** Roles to resolve against instead of the session's. */
+  /** Roles to resolve against instead of the session's, on a fixtures connection too. */
   roles?: string[];
   /** The record's owner; omitted for the doctype's rights. */
   owner?: string;
@@ -33,8 +33,16 @@ export function useDocRights(
   const session = useFrappeSession(meta && !fixtures ? connection : undefined);
   const roles = rolesOverride ?? session.roles;
   const rights = useMemo(
-    () => sessionDocRights({ fixtures, meta, roles, user: session.user, owner, shares }),
-    [fixtures, meta, roles, session.user, owner, shares],
+    () =>
+      sessionDocRights({
+        fixtures: fixtures && !rolesOverride,
+        meta,
+        roles,
+        user: session.user,
+        owner,
+        shares,
+      }),
+    [fixtures, rolesOverride, meta, roles, session.user, owner, shares],
   );
   const pending = !fixtures && Boolean(meta) && !rolesOverride && session.state === "loading";
   return { rights, pending, user: session.user, roles };

package/src/formEngine/useFormEngine.ts

@@ -85,7 +85,7 @@ function isConflictError(err: unknown): boolean {
   return /TimestampMismatch|has been modified/i.test(e.message ?? "");
 }
 
-function extractServerError(err: unknown, fallback: string): string {
+export function extractServerError(err: unknown, fallback: string): string {
   const e = err as { _server_messages?: string; message?: string; exc_type?: string } | undefined;
   if (e?._server_messages) {
     try {

package/src/frappeViews.designLaw.spec.ts

@@ -96,4 +96,10 @@ describe("Frappe view adapters — design-law 100%", () => {
     expect(source).not.toMatch(/fontSize=\{display === "compressed" \? 12 : 14\}/);
     expect(source).toContain("formCommonColors");
   });
+
+  it("list indicator pills are catalog Chip, not 999-radius wells", () => {
+    const source = read("list/listColumns.tsx");
+    expect(source).toContain("<Chip");
+    expect(source).not.toMatch(/borderRadius=\{999\}/);
+  });
 });

package/src/index.ts

@@ -52,7 +52,6 @@ export {
 // ---------------------------------------------------------------------------
 
 export { FrappeTable, filterValueToFrappeTuple, type FrappeTableProps } from "./FrappeTable";
-export { docFieldsToFilterFields } from "./filterFields";
 export { FrappeForm, type FrappeConnectionRows, type FrappeFormProps } from "./FrappeForm";
 export {
   FrappeFormConnectionSection,
@@ -492,3 +491,50 @@ export type {
   SessionDocRightsInput,
 } from "./formEngine";
 export { connectionFields, connectionsFromMeta, type FrappeConnection } from "./frappeConnections";
+
+// ---------------------------------------------------------------------------
+// Desk List (MPO-15)
+// ---------------------------------------------------------------------------
+
+// The desk list's column derivation (title, in_list_view fields, activity)
+// and the one filterable-field vocabulary both list stacks read. Hoisted out
+// of @multiplatform.one/backoffice so FrappeTable can default its columns
+// and filter menu from them; backoffice re-exports these names from their
+// old paths.
+export {
+  buildListColumns,
+  type BuildListColumnsArgs,
+  type ListDoc,
+  type ListRow,
+} from "./list/listColumns";
+export { listDocumentColumnIds, listFieldsToFetch, listViewFields } from "./list/listFields";
+export {
+  formatDateCell,
+  formatTimeAgo,
+  parseFrappeDate,
+  parseTagsField,
+  parseUserListField,
+  stripHtmlPreview,
+} from "./list/listFormat";
+export { statusPillColors, type StatusPillColors } from "./list/statusColors";
+export {
+  defaultOperatorForKind,
+  DESK_OPERATOR_LABELS,
+  docFieldsToFilterFields,
+  draftToTuple,
+  fieldKind,
+  fieldLabelFor,
+  filterableFieldsFromMeta,
+  filterTupleLabel,
+  operatorsForKind,
+  quickFilterValue,
+  selectOptionsFromField,
+  setFieldFilter,
+  standardDocFilterFields,
+  standardFiltersFromMeta,
+  tupleToDraft,
+  type DeskOperator,
+  type FilterFieldDescriptor,
+  type FilterFieldKind,
+  type FilterRowDraft,
+} from "./filterFields";