@multiplatform.one/backoffice 6.4.0 → 6.4.1

package/dist/jsx/workspace/useWorkspaceDoc.native.js

@@ -0,0 +1,120 @@
+"use strict";
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, {
+    get: all[name],
+    enumerable: true
+  });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
+  value: true
+}), mod);
+var useWorkspaceDoc_exports = {};
+__export(useWorkspaceDoc_exports, {
+  useFrappeDoc: () => useFrappeDoc,
+  useWorkspaceDoc: () => useWorkspaceDoc
+});
+module.exports = __toCommonJS(useWorkspaceDoc_exports);
+var import_frappe = require("@multiplatform.one/frappe");
+var import_frappe_ui = require("@multiplatform.one/frappe-ui");
+var import_react = require("react");
+function _instanceof(left, right) {
+  "@swc/helpers - instanceof";
+
+  if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+    return !!right[Symbol.hasInstance](left);
+  } else {
+    return left instanceof right;
+  }
+}
+var dbCache = /* @__PURE__ */new Map();
+function getDb(config) {
+  var _ref, _ref1;
+  var _config_auth, _config_auth1;
+  var key = `${config.baseURL}:${(_ref = (_config_auth = config.auth) === null || _config_auth === void 0 ? void 0 : _config_auth.token) !== null && _ref !== void 0 ? _ref : ""}:${(_ref1 = (_config_auth1 = config.auth) === null || _config_auth1 === void 0 ? void 0 : _config_auth1.type) !== null && _ref1 !== void 0 ? _ref1 : ""}`;
+  var db = dbCache.get(key);
+  if (!db) {
+    var authConfig = config.auth ? {
+      useToken: config.auth.useToken,
+      token: config.auth.token,
+      type: config.auth.type
+    } : void 0;
+    db = new import_frappe.DbModule(new import_frappe.HttpClient(config.baseURL, authConfig));
+    dbCache.set(key, db);
+  }
+  return db;
+}
+function useFrappeDoc(doctype, name) {
+  var config = (0, import_frappe_ui.useFrappeConfig)();
+  var [doc, setDoc] = (0, import_react.useState)(void 0);
+  var [isLoading, setIsLoading] = (0, import_react.useState)(!!name);
+  var [error, setError] = (0, import_react.useState)(void 0);
+  var fetchSeq = (0, import_react.useRef)(0);
+  var configRef = (0, import_react.useRef)(config);
+  configRef.current = config;
+  var runFetch = (0, import_react.useCallback)(async function (docName) {
+    var conn = configRef.current;
+    var seq = ++fetchSeq.current;
+    setIsLoading(true);
+    setError(void 0);
+    try {
+      var result;
+      if (conn === null || conn === void 0 ? void 0 : conn.fixtures) {
+        var fixtureDoc = await conn.fixtures.getDoc(doctype, docName);
+        if (!fixtureDoc) throw new Error(`${doctype} ${docName} not found`);
+        result = fixtureDoc;
+      } else if (conn === null || conn === void 0 ? void 0 : conn.baseURL) {
+        result = await getDb(conn).getDoc(doctype, docName);
+      } else {
+        throw new Error("useFrappeDoc requires a FrappeProvider with baseURL or fixtures");
+      }
+      if (seq !== fetchSeq.current) return;
+      setDoc(result);
+    } catch (err) {
+      if (seq !== fetchSeq.current) return;
+      setDoc(void 0);
+      setError(_instanceof(err, Error) ? err : new Error(String(err)));
+    } finally {
+      if (seq === fetchSeq.current) setIsLoading(false);
+    }
+  },
+  // doctype is stable per hook usage; config flows through configRef.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  [doctype]);
+  (0, import_react.useEffect)(function () {
+    if (!name) {
+      setDoc(void 0);
+      setIsLoading(false);
+      return;
+    }
+    void runFetch(name);
+  }, [name, runFetch, config === null || config === void 0 ? void 0 : config.baseURL, config === null || config === void 0 ? void 0 : config.fixtures]);
+  var refresh = (0, import_react.useCallback)(function () {
+    if (name) void runFetch(name);
+  }, [name, runFetch]);
+  var isPermissionError = (error === null || error === void 0 ? void 0 : error.status) === 403;
+  return {
+    doc,
+    isLoading,
+    error,
+    isPermissionError,
+    refresh
+  };
+}
+function useWorkspaceDoc(workspace) {
+  return useFrappeDoc("Workspace", workspace);
+}
+//# sourceMappingURL=useWorkspaceDoc.native.js.map

package/dist/jsx/workspace/useWorkspaceDoc.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["__defProp","Object","defineProperty","__getOwnPropDesc","getOwnPropertyDescriptor","__getOwnPropNames","getOwnPropertyNames","__hasOwnProp","prototype","hasOwnProperty","__export","target","all","name","get","enumerable","__copyProps","to","from","except","desc","key","call","__toCommonJS","mod","value","useWorkspaceDoc_exports","useFrappeDoc","useWorkspaceDoc","module","exports","import_frappe","require","import_frappe_ui","import_react","_instanceof","left","right","Symbol","hasInstance","dbCache","Map","getDb","config","_ref","_ref1","_config_auth","_config_auth1","baseURL","auth","token","type","db","authConfig","useToken","DbModule","HttpClient","set","doctype","useFrappeConfig","doc","setDoc","useState","isLoading","setIsLoading","error","setError","fetchSeq","useRef","configRef","current","runFetch","useCallback","docName","conn","seq","result","fixtures","fixtureDoc","getDoc","Error"],"sources":["../../../src/workspace/useWorkspaceDoc.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/backoffice",
-  "version": "6.4.0",
+  "version": "6.4.1",
   "description": "Embeddable Frappe desk recreation (backoffice) for the multiplatform.one stack",
   "keywords": [
     "backoffice",
@@ -72,15 +72,15 @@
   "dependencies": {
     "@phosphor-icons/react": "^2.1.10",
     "tamagui": "2.0.0-rc.41",
-    "@multiplatform.one/forms": "6.4.0",
-    "@multiplatform.one/frappe": "6.4.0",
-    "@multiplatform.one/frappe-ui": "6.4.0",
-    "@multiplatform.one/i18n": "6.4.0",
-    "@multiplatform.one/store": "6.4.0",
-    "@multiplatform.one/components": "6.4.0",
-    "@multiplatform.one/theme": "6.4.0",
-    "@multiplatform.one/platform": "6.4.0",
-    "@multiplatform.one/table": "6.4.0"
+    "@multiplatform.one/components": "6.4.1",
+    "@multiplatform.one/i18n": "6.4.1",
+    "@multiplatform.one/frappe-ui": "6.4.1",
+    "@multiplatform.one/forms": "6.4.1",
+    "@multiplatform.one/platform": "6.4.1",
+    "@multiplatform.one/store": "6.4.1",
+    "@multiplatform.one/frappe": "6.4.1",
+    "@multiplatform.one/theme": "6.4.1",
+    "@multiplatform.one/table": "6.4.1"
   },
   "devDependencies": {
     "@tamagui/build": "2.0.0-rc.41",
@@ -95,8 +95,8 @@
     "react-dom": "19.2.5",
     "react-i18next": "^16.6.6",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "6.4.0",
-    "@multiplatform.one/test-utils": "6.4.0"
+    "@multiplatform.one/test-utils": "6.4.1",
+    "@multiplatform.one/config": "6.4.1"
   },
   "peerDependencies": {
     "i18next": "^25.0.0",

package/src/chrome/CommandPalette.tsx

@@ -73,7 +73,6 @@ export function CommandPalette({ open, onOpenChange }: CommandPaletteProps) {
   const model = useCommandPaletteModel({ query, debouncedQuery, open });
   const { items } = model;
 
-  const rootRef = useRef<unknown>(null);
   const itemNodesRef = useRef<Array<unknown>>([]);
 
   // ── D-22 FOCUS-RETURN: render-phase capture on the opening render (before
@@ -109,15 +108,32 @@ export function CommandPalette({ open, onOpenChange }: CommandPaletteProps) {
     if (target?.isConnected) target.focus();
   }, [open]);
 
-  // Focus the palette input on open (fallback behind the Dialog focus scope;
-  // the sheet has no scope of its own on web).
+  // Focus the palette input on open. The Dialog focus scope re-targets the
+  // SearchInput's group frame (its first tabbable) DURING the mount
+  // animation — after any one-shot focus — so assert the input for the
+  // whole settle window, re-claiming every frame it gets stolen (D-23: the
+  // input is the palette's single tab stop). The panel is found by testid:
+  // Dialog.Content mounts in a portal and does not deliver a host-element
+  // ref, and the palette is a chrome singleton. The sheet has no scope of
+  // its own on web and settles on the first pass.
   useEffect(() => {
     if (!open || !isWeb || typeof document === "undefined") return;
-    const timer = setTimeout(() => {
-      const root = rootRef.current as HTMLElement | null;
-      root?.querySelector("input")?.focus();
-    }, 0);
-    return () => clearTimeout(timer);
+    let cancelled = false;
+    let raf = 0;
+    const deadline = Date.now() + 1000;
+    const claim = () => {
+      if (cancelled) return;
+      const input = document.querySelector<HTMLInputElement>(
+        '[data-testid="backoffice-command-palette"] input',
+      );
+      if (input && document.activeElement !== input) input.focus();
+      if (Date.now() < deadline) raf = requestAnimationFrame(claim);
+    };
+    raf = requestAnimationFrame(claim);
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(raf);
+    };
   }, [open]);
 
   // Keep the highlight on a real row as results stream in/out.
@@ -132,9 +148,18 @@ export function CommandPalette({ open, onOpenChange }: CommandPaletteProps) {
     node?.scrollIntoView?.({ block: "nearest" });
   }, [highlight]);
 
+  // One commit per open (LC-21 COMMIT class): Enter can reach both the
+  // keydown handler and the input's onSubmitEditing on web — the second
+  // call must not navigate again.
+  const activatedRef = useRef(false);
+  useEffect(() => {
+    if (open) activatedRef.current = false;
+  }, [open]);
+
   const activate = useCallback(
     (item: CommandPaletteItem | undefined) => {
-      if (!item) return;
+      if (!item || activatedRef.current) return;
+      activatedRef.current = true;
       navigator.navigate(item.path);
       addToRecent({ label: item.label, path: item.path });
       close();
@@ -240,11 +265,7 @@ export function CommandPalette({ open, onOpenChange }: CommandPaletteProps) {
         snapPoint={92}
         scrollable
         header={
-          <YStack
-            ref={rootRef as never}
-            paddingBottom="$2"
-            data-testid="backoffice-command-palette"
-          >
+          <YStack paddingBottom="$2" data-testid="backoffice-command-palette">
             {searchInput}
           </YStack>
         }
@@ -277,7 +298,6 @@ export function CommandPalette({ open, onOpenChange }: CommandPaletteProps) {
         />
         <DialogContent
           key="content"
-          ref={rootRef as never}
           width={PANEL_WIDTH}
           maxWidth="92%"
           // SP-EDGE: the container owns only its border — the input band,

package/src/i18n/en.ts

@@ -61,6 +61,27 @@ export const en = {
     exitToSite: "← multiplatform.one",
     logOut: "Log Out",
   },
+  // Flat surface keys (the migrated screens keep their original flat key
+  // vocabulary from the features tree — `screens.backoffice.X` → `X`).
+  loading: "Loading",
+  workspaceCardEmpty: "No links in this section",
+  workspaceShortcutUnavailable: "Not available",
+  workspaceQuickListViewAll: "View All",
+  workspaceNumberCardError: "Couldn't load number card",
+  workspaceNumberCardUnsupported: "This card type is only available in desk",
+  workspaceChartFixture: "Chart data is only available on a live bench",
+  workspaceChartError: "Couldn't load chart {{title}}",
+  workspaceBrowseAll: "Browse all",
+  workspaceBrowseAllCount_one: "{{count}} link",
+  workspaceBrowseAllCount_other: "{{count}} links",
+  workspaceFilterLinks: "Filter links...",
+  workspaceFilterNoMatch: 'No links match "{{query}}"',
+  workspaceRecents: "Continue where you left off",
+  workspacePermissionError: "You do not have permission to view {{workspace}}",
+  workspaceError: "Couldn't load workspace {{workspace}}",
+  workspaceEmpty: "This workspace is empty",
+  workspaceEmptyDescription: "No blocks have been added to {{workspace}} yet",
+  workspaceShortcuts: "Shortcuts",
   help: {
     label: "Help",
     documentation: "Documentation",

package/src/index.ts

@@ -148,3 +148,72 @@ export type { BackofficeShortcutHandlers } from "./chrome/shortcuts";
 
 // Shared
 export { useFrappeApp } from "./shared/useFrappeApp";
+export type { FrappeFilter, FrappeFilters, SlugTarget } from "./shared/types";
+export { useDoctypeMeta } from "./shared/useDoctypeMeta";
+export type {
+  DocFieldMeta,
+  DocLinkMeta,
+  DocPermissionRule,
+  DoctypeMeta,
+  DoctypeMetaBundle,
+} from "./shared/useDoctypeMeta";
+export { invalidateDocinfo, useDocinfo } from "./shared/useDocinfo";
+export type { DocInfo, DocInfoComment } from "./shared/useDocinfo";
+export { useSlugTarget } from "./shared/useSlugTarget";
+export { useUserRoles } from "./shared/useUserRoles";
+export { useRecentVisit } from "./shared/useRecentVisit";
+export type { RecentVisit } from "./shared/useRecentVisit";
+export { useSessionUserId } from "./shared/useSessionUserId";
+
+// Workspace surface
+export type {
+  FrappeFilterTuple,
+  WorkspaceBlock,
+  WorkspaceBlockType,
+  WorkspaceChartRow,
+  WorkspaceLinkGroup,
+  WorkspaceLinkRow,
+  WorkspaceNumberCardRow,
+  WorkspaceDoc as WorkspacePageDoc,
+  WorkspaceQuickListRow,
+  WorkspaceShortcutRow,
+} from "./workspace/types";
+export {
+  composeWorkspaceBlocks,
+  findLinkGroup,
+  findShortcut,
+  groupLinks,
+  headerLevel,
+  parseFrappeFilters,
+  parseWorkspaceContent,
+  stripHtml,
+} from "./workspace/parseContent";
+export type { WorkspaceComposition } from "./workspace/parseContent";
+export { useFrappeDoc, useWorkspaceDoc } from "./workspace/useWorkspaceDoc";
+export type { UseFrappeDocResult } from "./workspace/useWorkspaceDoc";
+export { useDashboardChartData } from "./workspace/useDashboardChart";
+export type {
+  DashboardChartDoc,
+  DashboardChartSeries,
+  UseDashboardChartDataResult,
+} from "./workspace/useDashboardChart";
+export { WorkspaceGrid } from "./workspace/WorkspaceGrid";
+export type { WorkspaceGridItem, WorkspaceGridProps } from "./workspace/WorkspaceGrid";
+export { WorkspaceLinkCard, resolveLinkTarget } from "./workspace/WorkspaceLinkCard";
+export type { WorkspaceLinkCardProps } from "./workspace/WorkspaceLinkCard";
+export { WorkspaceShortcut, resolveShortcutTarget } from "./workspace/WorkspaceShortcut";
+export type { WorkspaceShortcutProps } from "./workspace/WorkspaceShortcut";
+export { WorkspaceQuickList } from "./workspace/WorkspaceQuickList";
+export type { WorkspaceQuickListProps } from "./workspace/WorkspaceQuickList";
+export { WorkspaceNumberCard } from "./workspace/WorkspaceNumberCard";
+export type { NumberCardDoc, WorkspaceNumberCardProps } from "./workspace/WorkspaceNumberCard";
+export { WorkspaceChartBlock } from "./workspace/WorkspaceChartBlock";
+export type { WorkspaceChartBlockProps } from "./workspace/WorkspaceChartBlock";
+export { WorkspaceLinkDirectory, filterLinkGroup } from "./workspace/WorkspaceLinkDirectory";
+export type {
+  WorkspaceLinkDirectoryItem,
+  WorkspaceLinkDirectoryProps,
+} from "./workspace/WorkspaceLinkDirectory";
+export { WorkspaceRecents } from "./workspace/WorkspaceRecents";
+export { WorkspaceScreen } from "./workspace/WorkspaceScreen";
+export type { WorkspaceBlockKind, WorkspaceScreenProps } from "./workspace/WorkspaceScreen";

package/src/shared/types.ts

@@ -0,0 +1,14 @@
+/** Shared backoffice types — contracts between the backoffice surfaces. */
+
+/** Result of resolving a URL slug to a navigable target. */
+export type SlugTarget =
+  | { status: "loading" }
+  | { status: "resolved"; kind: "workspace"; workspace: string }
+  | { status: "resolved"; kind: "doctype"; doctype: string }
+  | { status: "not-found"; slug: string };
+
+/** A frappe filter tuple: [fieldname, operator, value]. */
+export type FrappeFilter = [string, string, unknown];
+
+/** Filters exchanged between the list surface components. */
+export type FrappeFilters = FrappeFilter[];

package/src/shared/useDocinfo.ts

@@ -0,0 +1,163 @@
+// Shared contract — consumed by the form sidebar, timeline, and connections
+// surfaces; keep signatures stable.
+// Shape verified against the live bench: get_docinfo → { docinfo: {...} }
+// with keys: user_info, comments, shared, assignment_logs, attachment_logs,
+// info_logs, like_logs, workflow_logs, attachments, communications,
+// automated_messages, versions, assignments, permissions, views,
+// additional_timeline_content, milestones, is_document_followed, tags,
+// document_email.
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useFrappeApp } from "./useFrappeApp";
+
+export interface DocInfoComment {
+  name: string;
+  comment_type?: string;
+  content?: string;
+  owner?: string;
+  creation?: string;
+  [key: string]: unknown;
+}
+
+export interface DocInfo {
+  doctype?: string;
+  name?: string;
+  user_info?: Record<
+    string,
+    { fullname?: string; image?: string; name?: string } & Record<string, unknown>
+  >;
+  comments?: DocInfoComment[];
+  communications?: Array<Record<string, unknown>>;
+  automated_messages?: Array<Record<string, unknown>>;
+  versions?: Array<Record<string, unknown>>;
+  assignments?: Array<
+    { name?: string; owner?: string; description?: string } & Record<string, unknown>
+  >;
+  assignment_logs?: Array<Record<string, unknown>>;
+  attachments?: Array<
+    { name?: string; file_name?: string; file_url?: string; is_private?: 0 | 1 } & Record<
+      string,
+      unknown
+    >
+  >;
+  attachment_logs?: Array<Record<string, unknown>>;
+  info_logs?: Array<Record<string, unknown>>;
+  like_logs?: Array<Record<string, unknown>>;
+  workflow_logs?: Array<Record<string, unknown>>;
+  shared?: Array<Record<string, unknown>>;
+  permissions?: Record<string, unknown>;
+  views?: Array<Record<string, unknown>>;
+  additional_timeline_content?: Array<Record<string, unknown>>;
+  milestones?: Array<Record<string, unknown>>;
+  is_document_followed?: number;
+  /** JSON string of tag list, e.g. "[]" or comma string — parse defensively */
+  tags?: string;
+  document_email?: unknown;
+  [key: string]: unknown;
+}
+
+interface CacheEntry {
+  promise: Promise<DocInfo>;
+  value?: DocInfo;
+  listeners: Set<() => void>;
+}
+
+const docinfoCache = new Map<string, CacheEntry>();
+
+function cacheKey(doctype: string, name: string) {
+  return `${doctype}\u0000${name}`;
+}
+
+/**
+ * Shared, deduped fetch of frappe's docinfo for a document. Multiple panels
+ * (sidebar, timeline, connections) share one fetch; `reload()` from any of
+ * them refreshes all subscribers.
+ */
+export function useDocinfo(
+  doctype?: string,
+  name?: string,
+): { docinfo?: DocInfo; loading: boolean; error?: Error; reload: () => void } {
+  const app = useFrappeApp();
+  const [docinfo, setDocinfo] = useState<DocInfo | undefined>(undefined);
+  const [loading, setLoading] = useState<boolean>(Boolean(doctype && name));
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [generation, setGeneration] = useState(0);
+
+  const isNewDoc = !name || name === "new";
+
+  useEffect(() => {
+    if (!app || !doctype || !name || isNewDoc) {
+      setDocinfo(undefined);
+      setLoading(false);
+      return;
+    }
+    let cancelled = false;
+    const key = cacheKey(doctype, name);
+    let entry = docinfoCache.get(key);
+    if (!entry) {
+      const listeners = new Set<() => void>();
+      const promise = app
+        .call()
+        .get<{ docinfo?: DocInfo; message?: { docinfo?: DocInfo } }>(
+          "frappe.desk.form.load.get_docinfo",
+          { doctype, name },
+        )
+        .then((res) => {
+          const info = res.payload?.docinfo ?? res.payload?.message?.docinfo;
+          if (!info) throw new Error(`No docinfo returned for ${doctype}/${name}`);
+          return info;
+        });
+      entry = { promise, listeners };
+      docinfoCache.set(key, entry);
+      promise
+        .then((value) => {
+          const current = docinfoCache.get(key);
+          if (current && current === entry) {
+            current.value = value;
+            for (const listener of current.listeners) listener();
+          }
+        })
+        .catch(() => {
+          if (docinfoCache.get(key) === entry) docinfoCache.delete(key);
+        });
+    }
+    const currentEntry = entry;
+    const sync = () => {
+      if (!cancelled && currentEntry.value) {
+        setDocinfo(currentEntry.value);
+        setLoading(false);
+      }
+    };
+    currentEntry.listeners.add(sync);
+    setLoading(!currentEntry.value);
+    setError(undefined);
+    if (currentEntry.value) setDocinfo(currentEntry.value);
+    currentEntry.promise.catch((err: Error) => {
+      if (!cancelled) {
+        setError(err);
+        setLoading(false);
+      }
+    });
+    return () => {
+      cancelled = true;
+      currentEntry.listeners.delete(sync);
+    };
+  }, [app, doctype, name, isNewDoc, generation]);
+
+  const reload = useCallback(() => {
+    if (doctype && name) {
+      const key = cacheKey(doctype, name);
+      const entry = docinfoCache.get(key);
+      docinfoCache.delete(key);
+      // wake every subscriber so they re-run the effect and share the refetch
+      if (entry) for (const listener of entry.listeners) listener();
+    }
+    setGeneration((g) => g + 1);
+  }, [doctype, name]);
+
+  return useMemo(() => ({ docinfo, loading, error, reload }), [docinfo, loading, error, reload]);
+}
+
+/** Invalidate the docinfo cache for a document (after mutations). */
+export function invalidateDocinfo(doctype: string, name: string) {
+  docinfoCache.delete(cacheKey(doctype, name));
+}