@multiplatform.one/backoffice 6.4.2 → 6.6.0

package/src/form/FormToolbar.tsx

@@ -0,0 +1,458 @@
+/**
+ * Desk-capability form toolbar: breadcrumbs → title + status indicator pill +
+ * header cluster slot (MOD-07 — assignees/like/follow readout) → primary
+ * actions (Save / Submit / Cancel / Amend per the docstatus lifecycle),
+ * standalone Refresh, and the ⋯ menu. Presentational — every action is a
+ * callback from DocFormScreen (which owns confirms, dialogs, and RPCs).
+ *
+ * Emphasis budget (LC-05): the current lifecycle primary (Save or Submit)
+ * is THE single accent-solid action; everything else stays neutral, and
+ * Cancel carries the error intent outlined (destructive, not primary).
+ *
+ * Indicator parity follows desk's `frappe.get_indicator` order:
+ * unsaved → meta.states row (by status value) → docstatus defaults →
+ * status-field value with a guessed color → Draft (submittable) → no pill.
+ *
+ * Compact viewports (< 640, `useLayoutSizeClass`) collapse secondary
+ * lifecycle actions and the standalone Refresh into the ⋯ menu; one primary
+ * button stays visible.
+ */
+
+import {
+  Breadcrumbs,
+  Chip,
+  DropdownMenu,
+  Text,
+  XStack,
+  YStack,
+  type BreadcrumbItem,
+  type ChipColor,
+  type DropdownMenuEntry,
+} from "@multiplatform.one/components";
+import { useLayoutSizeClass, useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  ArrowCounterClockwiseIcon,
+  CheckCircleIcon,
+  CopyIcon,
+  DotsThreeIcon,
+  EnvelopeIcon,
+  FloppyDiskIcon,
+  LinkIcon,
+  ListBulletsIcon,
+  PencilSimpleIcon,
+  PlusIcon,
+  PrinterIcon,
+  ProhibitIcon,
+  TrashIcon,
+} from "@phosphor-icons/react";
+import type { ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { Button } from "@multiplatform.one/forms";
+
+// ---------------------------------------------------------------------------
+// Status indicator
+// ---------------------------------------------------------------------------
+
+export type DocIndicator =
+  | "notSaved"
+  | "draft"
+  | "submitted"
+  | "cancelled"
+  | "new"
+  /** Clean, saved, non-submittable, no status → desk shows no pill. */
+  | "saved";
+
+/** A resolved data-driven indicator (status value + chip color). */
+export interface DocStatusIndicator {
+  label: string;
+  color: ChipColor;
+}
+
+export type DocIndicatorSpec = DocIndicator | DocStatusIndicator;
+
+/** Desk indicator colors mapped to theme chip colors (no hex literals). */
+const INDICATOR_COLORS: Record<Exclude<DocIndicator, "saved">, ChipColor> = {
+  notSaved: "orange",
+  draft: "red",
+  submitted: "blue",
+  cancelled: "red",
+  new: "orange",
+};
+
+/** Map a frappe indicator color name (DocType States rows) → ChipColor. */
+export function frappeColorToChipColor(color?: string): ChipColor {
+  switch (
+    (color ?? "")
+      .trim()
+      .toLowerCase()
+      .replace(/[\s_-]+/g, "")
+  ) {
+    case "red":
+      return "red";
+    case "green":
+      return "green";
+    case "blue":
+    case "lightblue":
+    case "cyan":
+      return "blue";
+    case "orange":
+      return "orange";
+    case "yellow":
+      return "yellow";
+    case "purple":
+    case "pink":
+      return "purple";
+    default:
+      return "gray";
+  }
+}
+
+/**
+ * Heuristic status → color mapping mirroring desk's `guess_colour` for
+ * status values with no `meta.states` row (e.g. ToDo "Open").
+ */
+function guessStatusColor(status: string): ChipColor {
+  const value = status.toLowerCase();
+  const has = (...words: string[]) => words.some((word) => value.includes(word));
+  if (has("cancel", "inactive", "archiv", "low")) return "gray";
+  if (
+    has(
+      "success",
+      "complet",
+      "closed",
+      "approv",
+      "confirm",
+      "paid",
+      "receiv",
+      "active",
+      "enabled",
+      "done",
+      "finish",
+      "resolv",
+    )
+  ) {
+    return "green";
+  }
+  if (has("error", "fail", "reject", "lost", "overdue", "urgent", "high", "disabled", "expire")) {
+    return "red";
+  }
+  if (
+    has(
+      "open",
+      "pending",
+      "progress",
+      "working",
+      "review",
+      "draft",
+      "unpaid",
+      "medium",
+      "wait",
+      "queue",
+      "hold",
+    )
+  ) {
+    return "orange";
+  }
+  return "gray";
+}
+
+export function resolveIndicator(args: {
+  isCreate: boolean;
+  isDirty: boolean;
+  docstatus: number;
+  isSubmittable: boolean;
+  /** Doc's status-field (or workflow state field) value, when present. */
+  statusValue?: string;
+  /** `meta.states` rows — data-driven color mapping that wins over guesses. */
+  states?: Array<{ title?: string; color?: string } & Record<string, unknown>>;
+}): DocIndicatorSpec {
+  if (args.isCreate) return "new";
+  if (args.isDirty) return "notSaved";
+  if (args.statusValue) {
+    const state = args.states?.find((row) => row.title === args.statusValue);
+    if (state) return { label: args.statusValue, color: frappeColorToChipColor(state.color) };
+  }
+  if (args.docstatus === 1) return "submitted";
+  if (args.docstatus === 2) return "cancelled";
+  if (args.statusValue) {
+    return { label: args.statusValue, color: guessStatusColor(args.statusValue) };
+  }
+  return args.isSubmittable ? "draft" : "saved";
+}
+
+// ---------------------------------------------------------------------------
+// Toolbar
+// ---------------------------------------------------------------------------
+
+export interface FormToolbarMenuItem {
+  key: string;
+  label: string;
+  icon?:
+    | "reload"
+    | "duplicate"
+    | "rename"
+    | "delete"
+    | "print"
+    | "email"
+    | "links"
+    | "new"
+    | "list";
+  destructive?: boolean;
+  disabled?: boolean;
+  disabledReason?: string;
+  onSelect: () => void;
+}
+
+export interface FormToolbarProps {
+  breadcrumbs: BreadcrumbItem[];
+  onNavigate: (href: string) => void;
+  title: string;
+  indicator: DocIndicatorSpec;
+  /** Hide the status chip entirely (e.g. meta still loading). */
+  showIndicator?: boolean;
+  isSaving: boolean;
+  /**
+   * MOD-07 header cluster (assignee avatars / like / follow) rendered right
+   * after the status chip. The toolbar stays presentational — the cluster
+   * owns its own data + mutations.
+   */
+  cluster?: ReactNode;
+  /** Primary action visibilities per permissions + lifecycle. */
+  canSave: boolean;
+  canSubmit: boolean;
+  canCancel: boolean;
+  canAmend: boolean;
+  onSave: () => void;
+  onSubmit: () => void;
+  onCancel: () => void;
+  onAmend: () => void;
+  menuItems: FormToolbarMenuItem[];
+  /**
+   * Standalone Refresh button (desk parity). Falls back to the `reload`
+   * menu item's action so existing consumers get the button for free.
+   */
+  onReload?: () => void;
+}
+
+const MENU_ICONS = {
+  reload: ArrowCounterClockwiseIcon,
+  duplicate: CopyIcon,
+  rename: PencilSimpleIcon,
+  delete: TrashIcon,
+  print: PrinterIcon,
+  email: EnvelopeIcon,
+  links: LinkIcon,
+  new: PlusIcon,
+  list: ListBulletsIcon,
+} as const;
+
+type LifecycleAction = "save" | "submit" | "cancel" | "amend";
+
+export function FormToolbar({
+  breadcrumbs,
+  onNavigate,
+  title,
+  indicator,
+  showIndicator = true,
+  isSaving,
+  cluster,
+  canSave,
+  canSubmit,
+  canCancel,
+  canAmend,
+  onSave,
+  onSubmit,
+  onCancel,
+  onAmend,
+  menuItems,
+  onReload,
+}: FormToolbarProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  const isNarrow = useLayoutSizeClass() === "compact";
+
+  const indicatorLabels: Record<Exclude<DocIndicator, "saved">, string> = {
+    notSaved: t("notSaved", "Not Saved"),
+    draft: t("draft", "Draft"),
+    submitted: t("submitted", "Submitted"),
+    cancelled: t("cancelled", "Cancelled"),
+    new: t("notSaved", "Not Saved"),
+  };
+
+  const chip =
+    typeof indicator === "string"
+      ? indicator === "saved"
+        ? undefined
+        : { label: indicatorLabels[indicator], color: INDICATOR_COLORS[indicator] }
+      : indicator;
+
+  // Desk primary-action lifecycle: dirty/new → Save; saved submittable
+  // draft → Submit; docstatus 1 → Cancel; docstatus 2 → Amend.
+  const isDirtyish =
+    typeof indicator === "string" && (indicator === "notSaved" || indicator === "new");
+  const actionLabels: Record<LifecycleAction, string> = {
+    save: isSaving ? t("saving", "Saving…") : t("save", "Save"),
+    submit: t("submit", "Submit"),
+    cancel: t("cancelAction", "Cancel"),
+    amend: t("amend", "Amend"),
+  };
+  const actionHandlers: Record<LifecycleAction, () => void> = {
+    save: onSave,
+    submit: onSubmit,
+    cancel: onCancel,
+    amend: onAmend,
+  };
+  // Ordered by primacy: the first visible action is THE primary on narrow.
+  const visibleActions: LifecycleAction[] = [
+    ...(canSave && (isDirtyish || !canSubmit) ? (["save"] as const) : []),
+    ...(canSubmit && !isDirtyish ? (["submit"] as const) : []),
+    ...(canCancel ? (["cancel"] as const) : []),
+    ...(canAmend ? (["amend"] as const) : []),
+  ];
+  const buttonActions = isNarrow ? visibleActions.slice(0, 1) : visibleActions;
+  const collapsedActions = isNarrow ? visibleActions.slice(1) : [];
+
+  const reload = onReload ?? menuItems.find((item) => item.key === "reload")?.onSelect;
+
+  const actionEntryIcons: Record<LifecycleAction, typeof CheckCircleIcon> = {
+    save: FloppyDiskIcon,
+    submit: CheckCircleIcon,
+    cancel: ProhibitIcon,
+    amend: CopyIcon,
+  };
+  const entries: DropdownMenuEntry[] = [
+    // Narrow viewports: secondary lifecycle actions fold into the menu.
+    ...collapsedActions.map((action) => {
+      const Icon = actionEntryIcons[action];
+      return {
+        key: `__action-${action}`,
+        label: actionLabels[action],
+        icon: <Icon size={16} />,
+        destructive: action === "cancel",
+        disabled: isSaving,
+        ...(isSaving ? { disabledReason: t("saving", "Saving…") } : {}),
+        onSelect: actionHandlers[action],
+      };
+    }),
+    ...(collapsedActions.length > 0 && menuItems.length > 0 ? [{ separator: true as const }] : []),
+    ...menuItems.map((item) => ({
+      key: item.key,
+      label: item.label,
+      icon: item.icon
+        ? (() => {
+            const Icon = MENU_ICONS[item.icon];
+            return <Icon size={16} />;
+          })()
+        : undefined,
+      destructive: item.destructive,
+      disabled: item.disabled,
+      disabledReason: item.disabledReason,
+      onSelect: item.onSelect,
+    })),
+  ];
+
+  return (
+    <YStack {...knobProps.gap} {...knobProps.panelPadding} paddingBottom={0} testID="form-toolbar">
+      <Breadcrumbs items={breadcrumbs} onNavigate={onNavigate} />
+      <XStack alignItems="center" flexWrap="wrap" {...knobProps.gap}>
+        <XStack alignItems="center" gap="$3" flex={1} minWidth={0}>
+          <Text
+            role="heading"
+            aria-level={1}
+            fontSize="$7"
+            fontWeight="700"
+            color="$color12"
+            numberOfLines={1}
+            flexShrink={1}
+          >
+            {title}
+          </Text>
+          {showIndicator && chip && (
+            <Chip size="$2" variant="subtle" color={chip.color}>
+              {chip.label}
+            </Chip>
+          )}
+          {cluster}
+        </XStack>
+
+        <XStack alignItems="center" gap="$2" flexShrink={0}>
+          {reload && !isNarrow && (
+            <Button
+              size={knobProps.sizeToken}
+              outlined
+              icon={<ArrowCounterClockwiseIcon size={16} />}
+              aria-label={t("reloadDoc", "Reload")}
+              onPress={reload}
+              testID="form-toolbar-reload"
+            />
+          )}
+          {entries.length > 0 && (
+            <DropdownMenu items={entries} placement="bottom-end">
+              <Button
+                size={knobProps.sizeToken}
+                outlined
+                icon={<DotsThreeIcon size={18} weight="bold" />}
+                aria-label={t("menu", "Menu")}
+                testID="form-toolbar-menu"
+              />
+            </DropdownMenu>
+          )}
+          {buttonActions.includes("cancel") && (
+            <Button
+              size={knobProps.sizeToken}
+              error
+              outlined
+              actionRole="secondary"
+              icon={<ProhibitIcon size={16} />}
+              loading={isSaving}
+              onPress={onCancel}
+              testID="form-toolbar-cancel"
+            >
+              {actionLabels.cancel}
+            </Button>
+          )}
+          {buttonActions.includes("amend") && (
+            <Button
+              size={knobProps.sizeToken}
+              outlined
+              icon={<CopyIcon size={16} />}
+              loading={isSaving}
+              onPress={onAmend}
+              testID="form-toolbar-amend"
+            >
+              {actionLabels.amend}
+            </Button>
+          )}
+          {/* LC-05 / R-3: the lifecycle primary (Submit or Save — mutually
+              exclusive per the visibleActions gate) is the single
+              accent-solid action on the screen. */}
+          {buttonActions.includes("submit") && (
+            <Button
+              size={knobProps.sizeToken}
+              accent
+              icon={<CheckCircleIcon size={16} />}
+              loading={isSaving}
+              onPress={onSubmit}
+              testID="form-toolbar-submit"
+            >
+              {actionLabels.submit}
+            </Button>
+          )}
+          {buttonActions.includes("save") && (
+            <Button
+              size={knobProps.sizeToken}
+              accent
+              icon={<FloppyDiskIcon size={16} />}
+              loading={isSaving}
+              onPress={onSave}
+              testID="form-toolbar-save"
+            >
+              {actionLabels.save}
+            </Button>
+          )}
+        </XStack>
+      </XStack>
+    </YStack>
+  );
+}

package/src/form/connections-data.tsx

@@ -0,0 +1,219 @@
+// Data layer for the desk "Connections" tab: groups meta.links the way
+// frappe's meta.get_dashboard_data() does, and loads per-doctype counts via
+// frappe.desk.notifications.get_open_count with a per-link
+// frappe.client.get_count fallback.
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { BackofficePaths } from "../navigation/paths";
+import type { FrappeFilters } from "../shared/types";
+import type { DoctypeMeta } from "../shared/useDoctypeMeta";
+import { useFrappeApp } from "../shared/useFrappeApp";
+
+/** One connections row derived from a visible `meta.links` entry. */
+export interface ConnectionLink {
+  /**
+   * Doctype the row represents. For child-table ("internal") links desk uses
+   * the child's parent doctype (`parent_doctype`), not `link_doctype`.
+   */
+  targetDoctype: string;
+  /** Fieldname on the target doctype that points back at this document. */
+  linkFieldname: string;
+  /**
+   * Internal link: the connection lives in THIS doc's child rows, so counts
+   * and navigation come from the `names` returned by get_open_count.
+   */
+  isChildTable: boolean;
+}
+
+/** A titled group of connection rows (a desk `transactions` group). */
+export interface ConnectionGroup {
+  /** Raw group label from the link row; undefined → caller shows "Reference". */
+  label?: string;
+  links: ConnectionLink[];
+}
+
+/**
+ * Group visible meta.links rows by `group` label, preserving first-seen order
+ * and deduping doctypes within a group — mirrors
+ * frappe.model.meta.Meta.add_doctype_links (hidden rows skipped, internal
+ * links keyed by parent_doctype).
+ */
+export function groupConnectionLinks(meta?: DoctypeMeta): ConnectionGroup[] {
+  const groups: ConnectionGroup[] = [];
+  for (const row of meta?.links ?? []) {
+    if (!row || row.hidden) continue;
+    const isChildTable = Boolean(row.is_child_table);
+    const parentDoctype = typeof row.parent_doctype === "string" ? row.parent_doctype : "";
+    const targetDoctype = (isChildTable && parentDoctype) || row.link_doctype;
+    if (!targetDoctype) continue;
+    const label = row.group || undefined;
+    let group = groups.find((g) => (g.label ?? "") === (label ?? ""));
+    if (!group) {
+      group = { label, links: [] };
+      groups.push(group);
+    }
+    if (group.links.some((link) => link.targetDoctype === targetDoctype)) continue;
+    group.links.push({ targetDoctype, linkFieldname: row.link_fieldname, isChildTable });
+  }
+  return groups;
+}
+
+/** Count data for one linked doctype ("?" = server-side count timeout). */
+export interface ConnectionCount {
+  count?: number | string;
+  openCount?: number | string;
+  /** Linked docnames for internal links (drives the `name in (...)` filter). */
+  names?: string[];
+}
+
+interface OpenCountEntry {
+  doctype?: string;
+  count?: number | string;
+  open_count?: number | string;
+  names?: string[];
+}
+
+interface OpenCountPayload {
+  message?: {
+    /** Degrades to [] while the bench migrates/installs. */
+    count?:
+      | { external_links_found?: OpenCountEntry[]; internal_links_found?: OpenCountEntry[] }
+      | unknown[];
+  };
+}
+
+export interface ConnectionCounts {
+  /** Keyed by ConnectionLink.targetDoctype. */
+  counts: Record<string, ConnectionCount>;
+  loading: boolean;
+}
+
+/**
+ * Load linked-document counts for a doc in one
+ * `frappe.desk.notifications.get_open_count` call. When that endpoint fails
+ * (permissions, older bench) falls back to one `frappe.client.get_count` per
+ * external link; internal links need the doc's child rows server-side, so
+ * they stay uncounted in fallback mode.
+ */
+export function useConnectionCounts(
+  doctype: string,
+  name: string,
+  links: ConnectionLink[],
+): ConnectionCounts {
+  const app = useFrappeApp();
+  const [state, setState] = useState<ConnectionCounts>({ counts: {}, loading: links.length > 0 });
+  // Refetch keys off the link signature (not array identity) so callers don't
+  // have to memoize the links array.
+  const linksKey = useMemo(
+    () =>
+      links
+        .map(
+          (link) =>
+            `${link.targetDoctype}\u0000${link.linkFieldname}\u0000${link.isChildTable ? 1 : 0}`,
+        )
+        .join("\n"),
+    [links],
+  );
+  const linksRef = useRef(links);
+  linksRef.current = links;
+
+  useEffect(() => {
+    const currentLinks = linksRef.current;
+    if (!app || !doctype || !name || currentLinks.length === 0) {
+      setState({ counts: {}, loading: false });
+      return;
+    }
+    let cancelled = false;
+    setState({ counts: {}, loading: true });
+    app
+      .call()
+      .get<OpenCountPayload>("frappe.desk.notifications.get_open_count", { doctype, name })
+      .then((res) => {
+        if (cancelled) return;
+        const counts: Record<string, ConnectionCount> = {};
+        const raw = res.payload?.message?.count;
+        if (raw && !Array.isArray(raw)) {
+          for (const entry of raw.external_links_found ?? []) {
+            if (!entry?.doctype) continue;
+            counts[entry.doctype] = { count: entry.count, openCount: entry.open_count };
+          }
+          for (const entry of raw.internal_links_found ?? []) {
+            if (!entry?.doctype) continue;
+            counts[entry.doctype] = {
+              count: entry.count,
+              openCount: entry.open_count,
+              names: entry.names,
+            };
+          }
+        }
+        setState({ counts, loading: false });
+      })
+      .catch(() => {
+        if (cancelled) return;
+        const external = currentLinks.filter((link) => !link.isChildTable);
+        Promise.all(
+          external.map((link) =>
+            app
+              .call()
+              .get<{ message?: number }>("frappe.client.get_count", {
+                doctype: link.targetDoctype,
+                filters: { [link.linkFieldname]: name },
+              })
+              .then((res) => [link.targetDoctype, res.payload?.message] as const)
+              .catch(() => [link.targetDoctype, undefined] as const),
+          ),
+        ).then((pairs) => {
+          if (cancelled) return;
+          const counts: Record<string, ConnectionCount> = {};
+          for (const [target, count] of pairs) {
+            if (typeof count === "number") counts[target] = { count };
+          }
+          setState({ counts, loading: false });
+        });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, doctype, name, linksKey]);
+
+  return state;
+}
+
+/**
+ * Badge text for a count value. Mirrors desk: zero hides the badge, the
+ * server caps count scans at 100 rows so 100 renders as "99+", and a
+ * server-side count timeout arrives as the literal string "?".
+ */
+export function formatConnectionCount(value: number | string | undefined): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string") return value || undefined;
+  if (value <= 0) return undefined;
+  return value >= 100 ? "99+" : String(value);
+}
+
+/**
+ * Filters the target list opens with (the list surface parses `?f=`).
+ * External links filter by the back-reference field; internal links match
+ * desk and filter by the child-row names collected by get_open_count.
+ */
+export function connectionListFilters(
+  link: ConnectionLink,
+  docname: string,
+  names?: string[],
+): FrappeFilters {
+  if (link.isChildTable) return [["name", "in", names ?? []]];
+  return [[link.linkFieldname, "=", docname]];
+}
+
+/**
+ * Href for a connection row: filtered list of the target doctype. Takes the
+ * provider's basePath-aware `paths` (from `useBackofficePaths()`).
+ */
+export function connectionListHref(
+  paths: BackofficePaths,
+  link: ConnectionLink,
+  docname: string,
+  names?: string[],
+): string {
+  const filters = connectionListFilters(link, docname, names);
+  return `${paths.list(link.targetDoctype)}?f=${encodeURIComponent(JSON.stringify(filters))}`;
+}

package/src/form/createPrefill.ts

@@ -0,0 +1,28 @@
+/**
+ * One-shot create-mode prefill hand-off.
+ *
+ * Two producers, one mechanism:
+ * - Duplicate and Amend navigate to `newDocPath(doctype)` and stash the
+ *   copied values here (in-memory only — a refresh honestly falls back to
+ *   a blank form; no URL-size limits for large docs).
+ * - NewDocRouteScreen stashes parsed `?d=` URL defaults (kanban column "+",
+ *   calendar day click, connections "+") before rendering the form — those
+ *   survive refresh because the URL re-stashes them.
+ *
+ * The create-mode form (useFormEngine seeding) consumes and clears the
+ * stash on mount, merging it over meta defaults. Last stash per doctype
+ * wins, so a `?d=` navigation cannot double-apply with a stale
+ * Duplicate/Amend hand-off.
+ */
+
+const prefills = new Map<string, Record<string, unknown>>();
+
+export function setCreatePrefill(doctype: string, values: Record<string, unknown>): void {
+  prefills.set(doctype, values);
+}
+
+export function takeCreatePrefill(doctype: string): Record<string, unknown> | undefined {
+  const values = prefills.get(doctype);
+  if (values) prefills.delete(doctype);
+  return values;
+}