@multiplatform.one/backoffice 6.4.3 → 6.6.0

package/src/form/formLayout.ts

@@ -0,0 +1,402 @@
+/**
+ * Desk form layout engine.
+ *
+ * Splits the flat DocType field list into desk tabs (Tab Break), sections
+ * (Section Break, collapsible honored), and columns (Column Break), and
+ * maps them to the generic `FormSchema` consumed by frappe-ui's SchemaForm.
+ *
+ * Dynamic behavior is computed HERE with the safe depends_on evaluator
+ * (dependsOn.ts) — the `depends_on` string is deliberately stripped from the
+ * FieldSchema handed to SchemaForm so its string-eval-based evaluator
+ * (which cannot run on Hermes/GJS) never engages:
+ *
+ *   - depends_on            → field omitted from the built schema
+ *   - mandatory_depends_on  → `required: true` on the built FieldSchema
+ *   - read_only_depends_on  → `readOnly: true` on the built FieldSchema
+ *   - permlevel             → hidden without level read, read-only without
+ *     level write (role matrix via fieldPermissions.ts; coarse read-only
+ *     fallback when roles are unavailable)
+ *   - set_only_once         → read-only on saved docs
+ *   - fetch_from            → read-only while the source link holds a value
+ *     (unless fetch_if_empty)
+ *   - docstatus > 0         → everything read-only except allow_on_submit
+ *     fields on a submitted (1) doc
+ *   - collapsible / collapsible_depends_on / missing-mandatory → per-section
+ *     computed collapse state (desk refresh_section_collapse)
+ *
+ * Sections whose Section Break has a false depends_on hide wholesale; a
+ * section with no visible fields is dropped so SchemaForm never renders an
+ * empty card.
+ */
+
+import type { FieldSchema, FormSchema, FormSection } from "@multiplatform.one/frappe-ui";
+import { evaluateDependsOn } from "./dependsOn";
+import { canReadLevel, canWriteLevel, type PermLevelMatrix } from "./fieldPermissions";
+import { isFetchLocked } from "./fetchFrom";
+import type { DocFieldMeta } from "../shared/useDoctypeMeta";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FormTab {
+  /** Stable key (fieldname of the Tab Break or "__details") */
+  key: string;
+  label: string;
+  schema: FormSchema;
+}
+
+interface LayoutColumn {
+  fields: DocFieldMeta[];
+}
+
+interface LayoutSection {
+  breakField?: DocFieldMeta;
+  columns: LayoutColumn[];
+}
+
+interface LayoutTab {
+  key: string;
+  label?: string;
+  sections: LayoutSection[];
+}
+
+// ---------------------------------------------------------------------------
+// Static structure (from meta, doc-independent)
+// ---------------------------------------------------------------------------
+
+function splitIntoTabs(fields: DocFieldMeta[]): LayoutTab[] {
+  const tabs: LayoutTab[] = [];
+  let currentTab: LayoutTab = { key: "__details", sections: [] };
+  let currentSection: LayoutSection = { columns: [{ fields: [] }] };
+  currentTab.sections.push(currentSection);
+  tabs.push(currentTab);
+
+  for (const field of fields) {
+    switch (field.fieldtype) {
+      case "Tab Break":
+        currentTab = { key: field.fieldname, label: field.label, sections: [] };
+        currentSection = { columns: [{ fields: [] }] };
+        currentTab.sections.push(currentSection);
+        tabs.push(currentTab);
+        break;
+      case "Section Break":
+        currentSection = { breakField: field, columns: [{ fields: [] }] };
+        currentTab.sections.push(currentSection);
+        break;
+      case "Column Break":
+        currentSection.columns.push({ fields: [] });
+        break;
+      default:
+        currentSection.columns[currentSection.columns.length - 1].fields.push(field);
+        break;
+    }
+  }
+  return tabs;
+}
+
+// ---------------------------------------------------------------------------
+// Doc-dependent resolution
+// ---------------------------------------------------------------------------
+
+export interface BuildTabsOptions {
+  fields: DocFieldMeta[];
+  doc: Record<string, unknown>;
+  /** docstatus of the loaded doc (0 draft / 1 submitted / 2 cancelled). */
+  docstatus: number;
+  /** Meta-level read_only or missing write permission. */
+  formReadOnly: boolean;
+  /** Create mode relaxes read_only_depends_on on unsaved values. */
+  isCreate: boolean;
+  /** Default label for the implicit first tab. */
+  detailsLabel: string;
+  /**
+   * Role-derived permlevel matrix (fieldPermissions.ts). Desk semantics:
+   * fields at a level without read HIDE; read without write → read-only.
+   * Undefined (fixtures / roles unavailable) → coarse fallback: any
+   * permlevel > 0 renders read-only, never hidden.
+   */
+  permLevels?: PermLevelMatrix;
+  /** Host-hidden fields (fieldnames) — dropped before layout resolution. */
+  hiddenFields?: readonly string[];
+  /**
+   * Host-hidden sections/tabs. Matches a Section Break's or Tab Break's
+   * fieldname OR label; the whole section (or tab) is dropped.
+   */
+  hiddenSections?: readonly string[];
+}
+
+function isFieldVisible(
+  field: DocFieldMeta,
+  doc: Record<string, unknown>,
+  permLevels?: PermLevelMatrix,
+): boolean {
+  if (field.hidden) return false;
+  // Desk hides fields whose permlevel the user cannot read (perm.js:209-215).
+  if (!canReadLevel(permLevels, field.permlevel ?? 0)) return false;
+  // Visibility fallback = true: an unparseable expression shows the field.
+  return evaluateDependsOn(field.depends_on, doc, true);
+}
+
+function toFieldSchema(
+  field: DocFieldMeta,
+  doc: Record<string, unknown>,
+  options: BuildTabsOptions,
+): FieldSchema {
+  const required =
+    !!field.reqd ||
+    (!!field.mandatory_depends_on && evaluateDependsOn(field.mandatory_depends_on, doc, false));
+
+  let readOnly =
+    !!field.read_only ||
+    (!!field.read_only_depends_on && evaluateDependsOn(field.read_only_depends_on, doc, false)) ||
+    !canWriteLevel(options.permLevels, field.permlevel ?? 0);
+  // set_only_once: editable only while the doc is unsaved (perm.js:261-263).
+  if (field.set_only_once && !options.isCreate) readOnly = true;
+  // fetch_from without fetch_if_empty locks the target while its source link
+  // holds a value (desk read_only_because_of_fetch_from).
+  if (!readOnly && isFetchLocked(field, doc)) readOnly = true;
+  if (options.docstatus === 1 && !field.allow_on_submit) readOnly = true;
+  if (options.docstatus === 2) readOnly = true;
+  if (options.formReadOnly) readOnly = true;
+
+  return {
+    type: field.fieldtype,
+    name: field.fieldname,
+    label: field.label,
+    options: field.options,
+    description: field.description,
+    required,
+    readOnly,
+    precision:
+      field.precision !== undefined && field.precision !== null && field.precision !== ""
+        ? Number(field.precision)
+        : undefined,
+    maxLength:
+      field.length !== undefined && field.length !== null && Number(field.length) > 0
+        ? Number(field.length)
+        : undefined,
+    // depends_on intentionally NOT forwarded — visibility resolved here.
+    fieldtype: field.fieldtype,
+    fieldname: field.fieldname,
+    in_list_view: field.in_list_view,
+    in_standard_filter: field.in_standard_filter,
+  };
+}
+
+/**
+ * Desk's refresh_section_collapse (layout.js:463-483): a collapsible section
+ * starts collapsed unless its `collapsible_depends_on` evaluates truthy, and
+ * a section with a missing mandatory value is forced open. Recomputed per
+ * doc change — SchemaForm treats it as the live default while manual toggles
+ * survive between recomputes.
+ */
+function resolveSectionCollapsed(
+  breakField: DocFieldMeta | undefined,
+  sectionFields: DocFieldMeta[],
+  doc: Record<string, unknown>,
+): boolean | undefined {
+  if (!breakField?.collapsible) return undefined;
+  let collapsed = true;
+  if (breakField.collapsible_depends_on) {
+    // Unparseable expression → expanded (never hide content silently).
+    collapsed = !evaluateDependsOn(breakField.collapsible_depends_on, doc, true);
+  }
+  if (collapsed && sectionHasMissingMandatory(sectionFields, doc)) collapsed = false;
+  return collapsed;
+}
+
+/** Desk section.has_missing_mandatory: `reqd && value == null` (section.js:146-156). */
+function sectionHasMissingMandatory(fields: DocFieldMeta[], doc: Record<string, unknown>): boolean {
+  return fields.some((field) => !!field.reqd && doc[field.fieldname] == null);
+}
+
+/**
+ * Build the desk tab list for the current doc state. Recomputed whenever
+ * the doc changes so depends_on chains re-resolve; the work is O(fields).
+ */
+export function buildFormTabs(options: BuildTabsOptions): FormTab[] {
+  const { fields, doc, detailsLabel, permLevels } = options;
+  const hiddenFieldSet = new Set(options.hiddenFields ?? []);
+  const hiddenSectionSet = new Set(options.hiddenSections ?? []);
+  const sectionHidden = (breakField: DocFieldMeta | undefined, label?: string): boolean => {
+    if (hiddenSectionSet.size === 0) return false;
+    if (breakField && hiddenSectionSet.has(breakField.fieldname)) return true;
+    const resolvedLabel = breakField?.label ?? label;
+    return !!resolvedLabel && hiddenSectionSet.has(resolvedLabel);
+  };
+  const layoutTabs = splitIntoTabs(fields);
+  const tabs: FormTab[] = [];
+
+  for (const layoutTab of layoutTabs) {
+    // Tab Break fields support depends_on + permlevel gating too (tab.js:38-43).
+    const tabBreak = fields.find(
+      (field) => field.fieldtype === "Tab Break" && field.fieldname === layoutTab.key,
+    );
+    if (tabBreak && !isFieldVisible(tabBreak, doc, permLevels)) continue;
+    // Host hiddenSections also match tabs (fieldname or label).
+    if (sectionHidden(tabBreak, layoutTab.label)) continue;
+
+    const sections: FormSection[] = [];
+    const flatFields: FieldSchema[] = [];
+
+    for (const section of layoutTab.sections) {
+      // Section Breaks are not permlevel-gated in desk (sections aren't
+      // controls; they only auto-hide when all their fields hide) — so the
+      // permlevel matrix is deliberately not passed here.
+      if (section.breakField && !isFieldVisible(section.breakField, doc)) continue;
+      if (sectionHidden(section.breakField)) continue;
+
+      const columns = section.columns
+        .map((column) => ({
+          fields: column.fields
+            .filter(
+              (field) =>
+                !hiddenFieldSet.has(field.fieldname) && isFieldVisible(field, doc, permLevels),
+            )
+            .map((field) => toFieldSchema(field, doc, options)),
+        }))
+        .filter((column) => column.fields.length > 0);
+      if (columns.length === 0) continue;
+
+      for (const column of columns) flatFields.push(...column.fields);
+      const sectionFields = section.columns.flatMap((column) => column.fields);
+      sections.push({
+        label: section.breakField?.label,
+        description: section.breakField?.description,
+        collapsible: !!section.breakField?.collapsible,
+        collapsed: resolveSectionCollapsed(section.breakField, sectionFields, doc),
+        hideBorder: !!section.breakField?.hide_border,
+        columns,
+      });
+    }
+
+    if (sections.length === 0) continue;
+    tabs.push({
+      key: layoutTab.key,
+      label: layoutTab.label || detailsLabel,
+      schema: { sections, fields: flatFields },
+    });
+  }
+
+  return tabs;
+}
+
+// ---------------------------------------------------------------------------
+// Create-mode defaults
+// ---------------------------------------------------------------------------
+
+const LAYOUT_TYPES = new Set(["Section Break", "Column Break", "Tab Break", "Fold"]);
+const NUMERIC_TYPES = new Set(["Int", "Float", "Currency", "Percent", "Check", "Rating"]);
+
+function todayISO(): string {
+  const now = new Date();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${now.getFullYear()}-${month}-${day}`;
+}
+
+function nowTime(): string {
+  const now = new Date();
+  const hours = String(now.getHours()).padStart(2, "0");
+  const minutes = String(now.getMinutes()).padStart(2, "0");
+  const seconds = String(now.getSeconds()).padStart(2, "0");
+  return `${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Seed a create-mode doc from meta field defaults — desk parity with
+ * create_new.js get_default_value / set_default_values:
+ *
+ * - `Today` → today's date; `now` → time (Time) / local datetime (else)
+ * - `__user` / `user` (Link/Data only, avoiding Select option collisions)
+ *   → session user
+ * - Select fields with no default seed their first option
+ *   (create_new.js:107-114)
+ * - `:fieldname` boot sysdefaults, `frappe.*`, `user_fullname` stay unset —
+ *   server-resolved on insert (documented gap)
+ */
+export function buildCreateDefaults(
+  fields: DocFieldMeta[],
+  currentUser?: string,
+): Record<string, unknown> {
+  const doc: Record<string, unknown> = {};
+  for (const field of fields) {
+    if (LAYOUT_TYPES.has(field.fieldtype)) continue;
+    const raw = field.default;
+    if (raw === undefined || raw === null || raw === "") {
+      // Desk seeds the first Select option when no default resolves.
+      if (
+        field.fieldtype === "Select" &&
+        typeof field.options === "string" &&
+        field.options &&
+        !["[Select]", "Loading..."].includes(field.options)
+      ) {
+        doc[field.fieldname] = field.options.split("\n")[0];
+      }
+      continue;
+    }
+    if (raw === "Today") {
+      doc[field.fieldname] = todayISO();
+      continue;
+    }
+    if (raw.toLowerCase() === "now") {
+      doc[field.fieldname] = field.fieldtype === "Time" ? nowTime() : `${todayISO()} ${nowTime()}`;
+      continue;
+    }
+    if (
+      raw === "__user" ||
+      (raw.toLowerCase() === "user" && (field.fieldtype === "Link" || field.fieldtype === "Data"))
+    ) {
+      if (currentUser) doc[field.fieldname] = currentUser;
+      continue;
+    }
+    if (raw === "user_fullname") continue; // session fullname not mirrored client-side
+    if (raw.startsWith(":") || raw.startsWith("frappe.")) continue; // server-resolved
+    doc[field.fieldname] = NUMERIC_TYPES.has(field.fieldtype) ? Number(raw) || 0 : raw;
+  }
+  return doc;
+}
+
+/**
+ * Copyable field values for Duplicate / Amend: strips standard bookkeeping
+ * fields, `no_copy` fields, layout breaks, and empty values.
+ */
+export function buildCopyValues(
+  fields: DocFieldMeta[],
+  doc: Record<string, unknown>,
+): Record<string, unknown> {
+  const copy: Record<string, unknown> = {};
+  for (const field of fields) {
+    if (LAYOUT_TYPES.has(field.fieldtype)) continue;
+    if (field.no_copy) continue;
+    if (field.fieldtype === "Attach" || field.fieldtype === "Attach Image") continue;
+    const value = doc[field.fieldname];
+    if (value === undefined || value === null || value === "") continue;
+    if (field.fieldtype === "Table" || field.fieldtype === "Table MultiSelect") {
+      if (Array.isArray(value)) {
+        copy[field.fieldname] = value.map((row) => {
+          const {
+            name: _name,
+            parent: _parent,
+            parentfield: _parentfield,
+            parenttype: _parenttype,
+            creation: _creation,
+            modified: _modified,
+            ...rest
+          } = (row ?? {}) as Record<string, unknown>;
+          return rest;
+        });
+      }
+      continue;
+    }
+    copy[field.fieldname] = value;
+  }
+  return copy;
+}
+
+/** True when the doctype names docs by user prompt (show a name input). */
+export function isPromptNamed(autoname?: string, namingRule?: string): boolean {
+  if (namingRule === 'By "Prompt"') return true;
+  return (autoname ?? "").toLowerCase() === "prompt";
+}

package/src/form/platformHooks.ts

@@ -0,0 +1,92 @@
+/**
+ * Web-guarded platform hooks for the form view. Every DOM access is behind
+ * a `typeof window/document` guard so native (Hermes) and GNOME (GJS, no
+ * DOM) builds never touch browser globals. External links ride the
+ * platform-split openUrl (web window.open / native Linking / GNOME Gio).
+ */
+
+import { openUrl } from "@multiplatform.one/platform";
+import { useEffect, useRef } from "react";
+import {
+  useBackofficeConfig,
+  type BackofficeNavigationBlocker,
+} from "../config/BackofficeProvider";
+
+/** Cmd/Ctrl+S → save (web only; native uses the toolbar button). */
+export function useSaveShortcut(enabled: boolean, onSave: () => void): void {
+  const saveRef = useRef(onSave);
+  saveRef.current = onSave;
+
+  useEffect(() => {
+    if (!enabled) return;
+    if (typeof document === "undefined" || typeof document.addEventListener !== "function") {
+      return;
+    }
+    const handler = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "s") {
+        event.preventDefault();
+        saveRef.current();
+      }
+    };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [enabled]);
+}
+
+const NOOP_BLOCKER: BackofficeNavigationBlocker = {
+  blocked: false,
+  proceed: () => {},
+  reset: () => {},
+};
+
+function useNoopNavigationBlocker(): BackofficeNavigationBlocker {
+  return NOOP_BLOCKER;
+}
+
+/**
+ * Router-level dirty guard for navigations that bypass the screen's
+ * `navigate()` wrapper: browser back/forward on web (history pop) and the
+ * native back gesture/button. The actual blocker is host-injected through
+ * `BackofficeProvider integrations.useNavigationBlocker` (the one-adapter
+ * ships `useOneNavigationBlocker`); without one, only the in-app
+ * navigate() guard applies. The injected hook must be referentially stable
+ * for the provider's lifetime (rules of hooks).
+ */
+export function useNavigationDirtyGuard(isDirty: boolean): BackofficeNavigationBlocker {
+  const { integrations } = useBackofficeConfig();
+  const useNavigationBlocker = integrations?.useNavigationBlocker ?? useNoopNavigationBlocker;
+  return useNavigationBlocker(isDirty);
+}
+
+/** beforeunload dirty guard (web only). */
+export function useBeforeUnloadGuard(isDirty: boolean): void {
+  useEffect(() => {
+    if (!isDirty) return;
+    if (typeof window === "undefined" || typeof window.addEventListener !== "function") {
+      return;
+    }
+    const handler = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      // Chrome requires returnValue to be set for the native prompt.
+      event.returnValue = "";
+    };
+    window.addEventListener("beforeunload", handler);
+    return () => window.removeEventListener("beforeunload", handler);
+  }, [isDirty]);
+}
+
+/**
+ * Open a URL externally: new browser tab on web, system browser via
+ * Linking on iOS/Android, desktop handler on GNOME (platform openUrl
+ * twins). NOTE: bench URLs (printview) open unauthenticated off-web —
+ * the system browser has no app session.
+ */
+export function openInNewTab(url: string): boolean {
+  openUrl(url, "_blank");
+  return true;
+}
+
+/** External-URL capability — platform openUrl has a twin on every target. */
+export function canOpenNewTab(): boolean {
+  return true;
+}

package/src/form/sidebar-attachments.tsx

@@ -0,0 +1,141 @@
+import React from "react";
+/**
+ * Desk-style compact attachment rows for the form sidebar: private files get
+ * a lock glyph, filenames open the file via the platform openUrl (new tab on
+ * web, system browser/viewer elsewhere), each row removes, and an upload
+ * affordance uses the web file picker (hidden on platforms without one;
+ * document-picker gap).
+ */
+
+import { Button, Text, XStack, YStack, useTheme } from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { LockSimpleIcon, PaperclipIcon, UploadSimpleIcon, XIcon } from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { canOpenUrl, canPickFile, openUrl, pickFile, toAbsoluteUrl } from "./sidebar-utils";
+
+export interface SidebarAttachmentItem {
+  /** File doc name (remove_attach fid). */
+  id: string;
+  fileName: string;
+  /** Raw file_url from docinfo (may be relative to the bench). */
+  fileUrl: string;
+  isPrivate?: boolean;
+}
+
+export interface SidebarAttachmentsProps {
+  items: SidebarAttachmentItem[];
+  /** Bench base URL used to absolutize relative file_urls. */
+  baseURL?: string;
+  /** meta.max_attachments (0/undefined = unlimited). */
+  maxAttachments?: number;
+  disabled?: boolean;
+  onUpload?: (file: File) => void;
+  onRemove?: (item: SidebarAttachmentItem) => void;
+}
+
+export function SidebarAttachments({
+  items,
+  baseURL,
+  maxAttachments,
+  disabled,
+  onUpload,
+  onRemove,
+}: SidebarAttachmentsProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  const theme = useTheme();
+  // Phosphor icons take a resolved color string, not a tamagui token —
+  // read the theme value so native/GTK get a real color (not a CSS var).
+  const iconColor = typeof theme.color11?.val === "string" ? theme.color11.val : undefined;
+  const sz = knobProps.sizeToken;
+  const fontSize = sz === "$3" ? "$1" : sz === "$5" ? "$4" : "$2";
+  const iconSize = sz === "$3" ? 12 : sz === "$5" ? 16 : 14;
+  const linkable = canOpenUrl();
+
+  const atLimit =
+    typeof maxAttachments === "number" && maxAttachments > 0 && items.length >= maxAttachments;
+  const showUpload = Boolean(onUpload) && canPickFile();
+
+  const handlePick = async () => {
+    const file = await pickFile();
+    if (file) onUpload?.(file);
+  };
+
+  return (
+    <YStack {...knobProps.gap}>
+      {items.length === 0 ? (
+        <Text fontSize="$1" color="$color11">
+          {t("noAttachments", "No attachments")}
+        </Text>
+      ) : (
+        <YStack gap="$1.5">
+          {items.map((item) => {
+            const url = toAbsoluteUrl(baseURL, item.fileUrl);
+            return (
+              <XStack key={item.id} gap="$2" alignItems="center">
+                {item.isPrivate ? (
+                  <LockSimpleIcon size={iconSize} color={iconColor} />
+                ) : (
+                  <PaperclipIcon size={iconSize} color={iconColor} />
+                )}
+                <Text
+                  flex={1}
+                  minWidth={0}
+                  fontSize={fontSize}
+                  color={linkable ? "$blue11" : "$color12"}
+                  numberOfLines={1}
+                  {...(linkable
+                    ? {
+                        cursor: "pointer",
+                        textDecorationLine: "underline",
+                        role: "link" as const,
+                        onPress: () => openUrl(url),
+                      }
+                    : {})}
+                >
+                  {item.fileName}
+                </Text>
+                {onRemove && (
+                  <Button
+                    size="$1"
+                    chromeless
+                    icon={XIcon}
+                    disabled={disabled}
+                    aria-label={t("removeAttachment", "Remove {{name}}", {
+                      name: item.fileName,
+                    })}
+                    onPress={() => onRemove(item)}
+                  />
+                )}
+              </XStack>
+            );
+          })}
+        </YStack>
+      )}
+
+      {showUpload && (
+        <XStack alignItems="center" gap="$2">
+          <Button
+            size="$2"
+            icon={UploadSimpleIcon}
+            disabled={disabled || atLimit}
+            {...(atLimit
+              ? {
+                  disabledReason: t("attachmentLimit", "Attachment limit reached"),
+                }
+              : {})}
+            onPress={() => void handlePick()}
+          >
+            {t("attachFile", "Attach File")}
+          </Button>
+          {typeof maxAttachments === "number" && maxAttachments > 0 && (
+            <Text fontSize="$1" color="$color11">
+              {items.length}/{maxAttachments}
+            </Text>
+          )}
+        </XStack>
+      )}
+    </YStack>
+  );
+}