@multiplatform.one/backoffice 6.4.0 → 6.4.2

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

package/src/shared/useSlugTarget.ts

@@ -0,0 +1,143 @@
+// Contract: resolve a {basePath}/[slug] segment to a workspace or doctype.
+// Every backoffice route relies on this hook; keep the signature stable.
+import { HttpClient, type AuthConfig, type FixtureProvider } from "@multiplatform.one/frappe";
+import { useFrappeConfig, type FrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useEffect, useMemo, useState } from "react";
+import { slugToDisplayName, toSlug } from "../navigation/paths";
+import type { SlugTarget } from "./types";
+
+/**
+ * Slug → proper-cased-name indexes, fetched once per session.
+ *
+ * Workspaces win over doctypes on collision (desk parity: `/app/tools` is the
+ * Tools workspace even though a "Tools" doctype could exist).
+ */
+interface SlugIndex {
+  workspaces: Map<string, string>;
+  doctypes: Map<string, string>;
+}
+
+interface SlugIndexSource {
+  baseURL: string;
+  auth?: FrappeConfig["auth"];
+  fixtures?: FixtureProvider;
+}
+
+/** Module-level cache: one fetch per (baseURL, fixture-mode) per session. */
+const slugIndexCache = new Map<string, Promise<SlugIndex>>();
+
+function toSlugMap(names: readonly { name?: string }[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const row of names) {
+    if (row.name) map.set(toSlug(row.name), row.name);
+  }
+  return map;
+}
+
+async function fetchSlugIndex(source: SlugIndexSource): Promise<SlugIndex> {
+  if (source.fixtures) {
+    const [workspaces, doctypes] = await Promise.all([
+      source.fixtures.getList("Workspace", { fields: ["name"] }),
+      source.fixtures.getList("DocType", { fields: ["name"] }),
+    ]);
+    return {
+      workspaces: toSlugMap(workspaces as { name?: string }[]),
+      doctypes: toSlugMap(doctypes as { name?: string }[]),
+    };
+  }
+  const client = new HttpClient(source.baseURL, source.auth as AuthConfig | undefined);
+  const [workspacesRes, doctypesRes] = await Promise.all([
+    client.get<{ data?: { name: string }[] }>("/api/resource/Workspace", {
+      fields: '["name"]',
+      limit_page_length: "0",
+    }),
+    client.get<{ message?: { name: string }[] }>("/api/method/frappe.client.get_list", {
+      doctype: "DocType",
+      fields: '["name"]',
+      limit_page_length: "0",
+    }),
+  ]);
+  return {
+    workspaces: toSlugMap(workspacesRes.payload?.data ?? []),
+    doctypes: toSlugMap(doctypesRes.payload?.message ?? []),
+  };
+}
+
+function getSlugIndex(source: SlugIndexSource): Promise<SlugIndex> {
+  const key = `${source.baseURL}:${source.fixtures ? "fixtures" : "live"}`;
+  let promise = slugIndexCache.get(key);
+  if (!promise) {
+    promise = fetchSlugIndex(source);
+    // Failed fetches are evicted so a later mount can retry.
+    promise.catch(() => {
+      if (slugIndexCache.get(key) === promise) slugIndexCache.delete(key);
+    });
+    slugIndexCache.set(key, promise);
+  }
+  return promise;
+}
+
+/**
+ * Resolve a URL slug ("sales-order") to its target:
+ * - a Workspace whose slugged name matches → workspace page (workspaces win)
+ * - otherwise a DocType whose slugged name matches → doctype list
+ * - otherwise not-found
+ *
+ * The Workspace + DocType name indexes are fetched once per session (module
+ * cache) via the frappe client, honoring FrappeProvider fixtures in stories
+ * and tests. Connection comes exclusively from the ambient FrappeProvider
+ * (mounted by BackofficeProvider); without one the hook degrades the same
+ * way a failed fetch does. SSR-safe: the fetch runs in an effect, so the
+ * server render (and first client paint) reports `loading`. If the fetch
+ * fails the hook degrades gracefully by treating the slug as a title-cased
+ * doctype.
+ */
+export function useSlugTarget(slug: string | undefined): SlugTarget {
+  const config = useFrappeConfig();
+  const baseURL = config?.baseURL;
+  const fixtures = config?.fixtures;
+  const auth = config?.auth;
+
+  const [index, setIndex] = useState<SlugIndex | undefined>(undefined);
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    // No provider config → no bench to ask; degrade like a failed fetch.
+    if (!baseURL && !fixtures) {
+      setFailed(true);
+      return;
+    }
+    setFailed(false);
+    getSlugIndex({ baseURL: baseURL ?? "", auth, fixtures })
+      .then((result) => {
+        if (!cancelled) setIndex(result);
+      })
+      .catch(() => {
+        if (!cancelled) setFailed(true);
+      });
+    return () => {
+      cancelled = true;
+    };
+    // `auth` is intentionally not a dependency: the cache is keyed by
+    // baseURL/fixtures and provider auth is stable for the session.
+    // oxlint-disable-next-line exhaustive-deps
+  }, [baseURL, fixtures]);
+
+  return useMemo<SlugTarget>(() => {
+    if (!slug) return { status: "loading" };
+    if (index) {
+      const workspace = index.workspaces.get(slug);
+      if (workspace) return { status: "resolved", kind: "workspace", workspace };
+      const doctype = index.doctypes.get(slug);
+      if (doctype) return { status: "resolved", kind: "doctype", doctype };
+      return { status: "not-found", slug };
+    }
+    if (failed) {
+      // Degrade gracefully: guess a title-cased doctype so deep links still
+      // land somewhere useful when the metadata fetch is unavailable.
+      return { status: "resolved", kind: "doctype", doctype: slugToDisplayName(slug) };
+    }
+    return { status: "loading" };
+  }, [slug, index, failed]);
+}

package/src/shared/useUserRoles.ts

@@ -0,0 +1,66 @@
+/**
+ * Session user's role list — the client-side half of desk's
+ * `frappe.user_roles` (bootinfo). Fetched once per session via the
+ * whitelisted `frappe.core.doctype.user.user.get_roles` RPC (probed:
+ * `?uid=<user>` → `{"message": ["Role", ...]}`), keyed off
+ * `frappe.auth.get_logged_user`.
+ *
+ * `roles` stays undefined while loading, in fixture mode, or when the RPC
+ * fails — consumers (permlevel matrix) fall back to the conservative
+ * "permlevel > 0 → read-only" rule in that case.
+ */
+
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useEffect, useState } from "react";
+import { useFrappeApp } from "./useFrappeApp";
+
+const rolesCache = new Map<string, Promise<string[]>>();
+
+export function useUserRoles(): { roles?: string[] } {
+  const app = useFrappeApp();
+  const config = useFrappeConfig();
+  const fixtures = config?.fixtures;
+  const baseURL = config?.baseURL;
+  const [roles, setRoles] = useState<string[] | undefined>(undefined);
+
+  useEffect(() => {
+    // Fixture mode has no session — permlevel falls back to the coarse rule.
+    if (!app || fixtures || !baseURL) {
+      setRoles(undefined);
+      return;
+    }
+    let cancelled = false;
+    let promise = rolesCache.get(baseURL);
+    if (!promise) {
+      promise = app
+        .call()
+        .get<{ message?: string }>("frappe.auth.get_logged_user")
+        .then((res) => {
+          const user = res.payload?.message;
+          if (!user) throw new Error("No session user");
+          return app.call().get<{ message?: string[] }>("frappe.core.doctype.user.user.get_roles", {
+            uid: user,
+          });
+        })
+        .then((res) => {
+          const list = res.payload?.message;
+          if (!Array.isArray(list)) throw new Error("No roles returned");
+          return list;
+        });
+      rolesCache.set(baseURL, promise);
+      promise.catch(() => rolesCache.delete(baseURL));
+    }
+    promise
+      .then((list) => {
+        if (!cancelled) setRoles(list);
+      })
+      .catch(() => {
+        if (!cancelled) setRoles(undefined);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, fixtures, baseURL]);
+
+  return { roles };
+}

package/src/workspace/WorkspaceChartBlock.tsx

@@ -0,0 +1,115 @@
+/**
+ * Workspace chart block — renders a Dashboard Chart by name using the desk
+ * chart RPC for real series data, drawn with the catalog ChartCard.
+ *
+ * Mappings (frappe → catalog): Line→line, Bar→bar, Pie/Donut/Percentage→pie.
+ * Heatmap has no catalog equivalent and falls back to bar (documented gap).
+ * Only the first dataset is drawn — the catalog chart is single-series
+ * (documented gap). In fixture mode (stories) the RPC is unavailable, so
+ * the block renders an informational card instead.
+ */
+import { AsyncBoundary, Card, SizableText, Skeleton, YStack } from "@multiplatform.one/components";
+import { ChartCard, type ChartConfig, type ChartType } from "@multiplatform.one/frappe-ui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import type { WorkspaceChartRow } from "./types";
+import { useDashboardChartData, type DashboardChartDoc } from "./useDashboardChart";
+import { useFrappeDoc } from "./useWorkspaceDoc";
+
+function toChartType(frappeType: string | undefined): ChartType {
+  switch (frappeType) {
+    case "Line":
+      return "line";
+    case "Pie":
+    case "Donut":
+    case "Percentage":
+      return "pie";
+    default:
+      // "Bar", "Heatmap" (no catalog heatmap yet), unknown → bar.
+      return "bar";
+  }
+}
+
+export interface WorkspaceChartBlockProps {
+  row: WorkspaceChartRow;
+}
+
+export function WorkspaceChartBlock({ row }: WorkspaceChartBlockProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  const title = row.label || row.chart_name;
+
+  const {
+    doc: chartDoc,
+    isLoading: docLoading,
+    error: docError,
+  } = useFrappeDoc<DashboardChartDoc>("Dashboard Chart", row.chart_name);
+  const {
+    series,
+    isLoading: dataLoading,
+    error: dataError,
+    unsupported,
+  } = useDashboardChartData(row.chart_name);
+
+  const config = useMemo<ChartConfig | undefined>(() => {
+    if (!series) return undefined;
+    const dataset = series.datasets?.[0];
+    if (!dataset) return undefined;
+    return {
+      id: `workspace-chart-${row.name}`,
+      title,
+      type: toChartType(chartDoc?.type),
+      data: series.labels.map((label, index) => ({
+        label,
+        value: dataset.values[index] ?? 0,
+      })),
+      height: 220,
+    };
+  }, [series, chartDoc?.type, row.name, title]);
+
+  if (unsupported) {
+    return (
+      <Card flexGrow={1}>
+        <YStack {...knobProps.panelPadding} {...knobProps.gap}>
+          <SizableText size="$4" fontWeight="700">
+            {title}
+          </SizableText>
+          <SizableText size="$2" color="$color10">
+            {t(
+              "workspaceChartFixture",
+              "Chart data is only available on a live bench",
+            )}
+          </SizableText>
+        </YStack>
+      </Card>
+    );
+  }
+
+  if (docLoading || dataLoading) {
+    return (
+      <Card flexGrow={1} aria-busy aria-label={t("loading", "Loading")}>
+        <YStack {...knobProps.panelPadding} {...knobProps.gap}>
+          <Skeleton width="40%" height={16} />
+          <Skeleton variant="rounded" width="100%" height={220} />
+        </YStack>
+      </Card>
+    );
+  }
+
+  const error = docError ?? dataError;
+  if (error || !config) {
+    return (
+      <AsyncBoundary
+        compact
+        error={error ?? true}
+        errorTitle={t("workspaceChartError", "Couldn't load chart {{title}}", {
+          title,
+        })}
+      />
+    );
+  }
+
+  return <ChartCard config={config} flexGrow={1} />;
+}