@multiplatform.one/backoffice 6.3.0 → 6.4.1

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));
+}

package/src/shared/useDoctypeMeta.ts

@@ -0,0 +1,243 @@
+// Shared contract — consumed by the list, form, views, and quick-entry
+// surfaces; keep signatures stable.
+// This is the ONE meta loader for backoffice surfaces (form/deskMeta.ts and
+// views/viewMeta.ts loaders were consolidated here): getdoctype RPC on live
+// benches, the FrappeProvider fixture branch for stories/tests, one
+// module-wide cache either way.
+import type { FixtureProvider } from "@multiplatform.one/frappe";
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useFrappeApp } from "./useFrappeApp";
+
+/** A single DocField row from a DocType meta (loose — server is source of truth). */
+export interface DocFieldMeta {
+  fieldname: string;
+  label?: string;
+  fieldtype: string;
+  options?: string;
+  reqd?: 0 | 1;
+  hidden?: 0 | 1;
+  read_only?: 0 | 1;
+  bold?: 0 | 1;
+  in_list_view?: 0 | 1;
+  in_standard_filter?: 0 | 1;
+  in_global_search?: 0 | 1;
+  allow_in_quick_entry?: 0 | 1;
+  allow_on_submit?: 0 | 1;
+  no_copy?: 0 | 1;
+  collapsible?: 0 | 1;
+  collapsible_depends_on?: string;
+  depends_on?: string;
+  mandatory_depends_on?: string;
+  read_only_depends_on?: string;
+  fetch_from?: string;
+  permlevel?: number;
+  length?: number;
+  default?: string;
+  description?: string;
+  precision?: string | number;
+  idx?: number;
+  [key: string]: unknown;
+}
+
+/** DocType Link child row (Connections tab). Probed: `group` arrives null when unset. */
+export interface DocLinkMeta {
+  name?: string;
+  link_doctype: string;
+  link_fieldname: string;
+  group?: string | null;
+  hidden?: 0 | 1;
+  is_child_table?: 0 | 1;
+  parent_doctype?: string;
+  table_fieldname?: string;
+  [key: string]: unknown;
+}
+
+/** Role permission row from the DocType meta. */
+export interface DocPermissionRule {
+  role?: string;
+  permlevel?: number;
+  read?: 0 | 1;
+  write?: 0 | 1;
+  create?: 0 | 1;
+  delete?: 0 | 1;
+  submit?: 0 | 1;
+  cancel?: 0 | 1;
+  amend?: 0 | 1;
+  print?: 0 | 1;
+  email?: 0 | 1;
+  share?: 0 | 1;
+  if_owner?: 0 | 1;
+  [key: string]: unknown;
+}
+
+/** DocType meta as returned by frappe.desk.form.load.getdoctype (loose). */
+export interface DoctypeMeta {
+  doctype?: string;
+  name: string;
+  module?: string;
+  issingle?: 0 | 1;
+  istable?: 0 | 1;
+  is_submittable?: 0 | 1;
+  is_tree?: 0 | 1;
+  is_virtual?: 0 | 1;
+  editable_grid?: 0 | 1;
+  track_changes?: 0 | 1;
+  quick_entry?: 0 | 1;
+  autoname?: string;
+  naming_rule?: string;
+  allow_rename?: 0 | 1;
+  allow_copy?: 0 | 1;
+  read_only?: 0 | 1;
+  in_create?: 0 | 1;
+  hide_toolbar?: 0 | 1;
+  max_attachments?: number;
+  title_field?: string;
+  image_field?: string;
+  search_fields?: string;
+  sort_field?: string;
+  sort_order?: string;
+  icon?: string;
+  document_type?: string;
+  fields: DocFieldMeta[];
+  permissions?: DocPermissionRule[];
+  links?: DocLinkMeta[];
+  states?: Array<{ title?: string; color?: string } & Record<string, unknown>>;
+  [key: string]: unknown;
+}
+
+export interface DoctypeMetaBundle {
+  /** Parent doctype meta (docs[0]) */
+  meta: DoctypeMeta;
+  /** Child table doctype metas keyed by doctype name (docs[1..]) */
+  childMetas: Record<string, DoctypeMeta>;
+  /** Parsed user_settings (list view settings etc.), when present */
+  userSettings?: Record<string, unknown>;
+}
+
+interface GetDoctypeResponse {
+  docs?: DoctypeMeta[];
+  user_settings?: string | Record<string, unknown>;
+}
+
+const metaCache = new Map<string, Promise<DoctypeMetaBundle>>();
+
+function parseUserSettings(raw: GetDoctypeResponse["user_settings"]) {
+  if (!raw) return undefined;
+  if (typeof raw !== "string") return raw;
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Fixture path (stories / tests): the raw getdoctype-shaped meta doc lives in
+ * the fixture provider's "DocType" collection under the doctype's name
+ * (fields / links / permissions arrays inline).
+ */
+async function loadBundleFromFixtures(
+  fixtures: FixtureProvider,
+  doctype: string,
+): Promise<DoctypeMetaBundle> {
+  const doc = await fixtures.getDoc("DocType", doctype);
+  if (!doc) throw new Error(`No fixture meta for DocType "${doctype}"`);
+  const raw = doc as Record<string, unknown>;
+  const meta = { ...raw, fields: (raw.fields as DocFieldMeta[] | undefined) ?? [] } as DoctypeMeta;
+  return { meta, childMetas: {} };
+}
+
+/**
+ * Load (and cache, module-wide) the meta bundle for a doctype via
+ * `frappe.desk.form.load.getdoctype` — or, when the ambient FrappeProvider
+ * carries a fixture provider, from its "DocType" collection. All backoffice
+ * surfaces share this cache, so meta is fetched once per doctype per session.
+ */
+export function useDoctypeMeta(doctype?: string): {
+  bundle?: DoctypeMetaBundle;
+  meta?: DoctypeMeta;
+  loading: boolean;
+  error?: Error;
+  reload: () => void;
+} {
+  const app = useFrappeApp();
+  const config = useFrappeConfig();
+  const fixtures = config?.fixtures;
+  const [bundle, setBundle] = useState<DoctypeMetaBundle | undefined>(undefined);
+  const [loading, setLoading] = useState<boolean>(Boolean(doctype));
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [generation, setGeneration] = useState(0);
+
+  // Fixture and live providers must not share cache entries (storybook mounts
+  // both kinds in one session); baseURL keeps multi-bench setups apart.
+  const cacheKey = doctype
+    ? `${config?.baseURL ?? ""}\u0000${fixtures ? "fixtures" : "live"}\u0000${doctype}`
+    : undefined;
+
+  useEffect(() => {
+    if ((!app && !fixtures) || !doctype || !cacheKey) {
+      setBundle(undefined);
+      setLoading(Boolean(doctype));
+      return;
+    }
+    let cancelled = false;
+    let promise = metaCache.get(cacheKey);
+    if (!promise) {
+      if (fixtures) {
+        promise = loadBundleFromFixtures(fixtures, doctype);
+      } else if (app) {
+        promise = app
+          .call()
+          .get<GetDoctypeResponse>("frappe.desk.form.load.getdoctype", {
+            doctype,
+            with_parent: 1,
+          })
+          .then((res) => {
+            const docs = res.payload?.docs ?? [];
+            const meta = docs.find((d) => d.name === doctype) ?? docs[0];
+            if (!meta) throw new Error(`No meta returned for ${doctype}`);
+            const childMetas: Record<string, DoctypeMeta> = {};
+            for (const doc of docs) {
+              if (doc !== meta) childMetas[doc.name] = doc;
+            }
+            return {
+              meta,
+              childMetas,
+              userSettings: parseUserSettings(res.payload?.user_settings),
+            };
+          });
+      } else {
+        return;
+      }
+      metaCache.set(cacheKey, promise);
+      promise.catch(() => metaCache.delete(cacheKey));
+    }
+    setLoading(true);
+    setError(undefined);
+    promise
+      .then((value) => {
+        if (cancelled) return;
+        setBundle(value);
+        setLoading(false);
+      })
+      .catch((err: Error) => {
+        if (cancelled) return;
+        setError(err);
+        setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, fixtures, doctype, cacheKey, generation]);
+
+  const reload = useCallback(() => {
+    if (cacheKey) metaCache.delete(cacheKey);
+    setGeneration((g) => g + 1);
+  }, [cacheKey]);
+
+  return useMemo(
+    () => ({ bundle, meta: bundle?.meta, loading, error, reload }),
+    [bundle, loading, error, reload],
+  );
+}

package/src/shared/useRecentVisit.ts

@@ -0,0 +1,33 @@
+/**
+ * Write side of the shared desk recents store ("frappe-desk-recent") for
+ * plain navigation. The awesomebar/command palette already writes recents
+ * when it navigates, but sidebar/list navigation never did — so the
+ * workspace "Continue where you left off" strip stayed empty for anyone who
+ * doesn't use the palette. Screens call this on mount (and whenever the
+ * visited path changes) so every doctype-list and document visit lands in
+ * the same store the palette, sidebar recents, and the workspace strip read.
+ *
+ * Label vocabulary follows the existing writers: doctype lists use the bare
+ * doctype (command-palette navigation items), documents use
+ * "{doctype}: {name}" (frappe-ui DeskFormPage precedent).
+ */
+import { addToRecent } from "@multiplatform.one/frappe-ui";
+import { useEffect } from "react";
+
+export interface RecentVisit {
+  label: string;
+  path: string;
+}
+
+/**
+ * Record a visit in the shared recents store. Pass `undefined` to skip
+ * (create mode, fixture/story mode). Dedup/cap is owned by `addToRecent`.
+ */
+export function useRecentVisit(visit: RecentVisit | undefined): void {
+  const label = visit?.label;
+  const path = visit?.path;
+  useEffect(() => {
+    if (!label || !path) return;
+    addToRecent({ label, path });
+  }, [label, path]);
+}

package/src/shared/useSessionUserId.ts

@@ -0,0 +1,42 @@
+// Session user id (for liked-hearts + "assigned to me"), cached per app.
+// (The shell's useSessionUser in shell/useWorkspaces.ts is the HttpClient
+// variant used by the sidebar; this one rides the FrappeApp auth module.)
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useEffect, useState } from "react";
+import { useFrappeApp } from "./useFrappeApp";
+
+const userCache = new Map<string, Promise<string>>();
+
+/**
+ * The logged-in user's id (`frappe.auth.get_logged_user`), or undefined
+ * while loading / in fixture mode (no session exists against fixtures).
+ */
+export function useSessionUserId(): string | undefined {
+  const config = useFrappeConfig();
+  const app = useFrappeApp();
+  const fixtureMode = Boolean(config?.fixtures);
+  const [user, setUser] = useState<string | undefined>(undefined);
+
+  useEffect(() => {
+    if (!app || fixtureMode || !config?.baseURL) return;
+    let cancelled = false;
+    let promise = userCache.get(config.baseURL);
+    if (!promise) {
+      promise = app.auth().getLoggedInUser();
+      userCache.set(config.baseURL, promise);
+      promise.catch(() => userCache.delete(config.baseURL));
+    }
+    promise
+      .then((value) => {
+        if (!cancelled && value) setUser(value);
+      })
+      .catch(() => {
+        // No session — hearts render unfilled, "me" facets hidden.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, fixtureMode, config?.baseURL]);
+
+  return user;
+}