@multiplatform.one/backoffice 6.3.0

package/src/navigation/paths.ts

@@ -0,0 +1,146 @@
+/**
+ * Backoffice route paths.
+ *
+ * Route map (relative to the mount `basePath`, default "/backoffice"):
+ *   {base}                          → home (default workspace)
+ *   {base}/[slug]                   → workspace page OR doctype list (runtime-resolved)
+ *   {base}/[slug]/view/[view]       → alternate doctype views (report, kanban, …)
+ *   {base}/[slug]/new               → new document (optional `?d=` JSON prefill)
+ *   {base}/[slug]/[name]            → document form page
+ *
+ * Slugs follow frappe's router slugs: lowercase, spaces → dashes
+ * ("Sales Order" → "sales-order").
+ *
+ * Surfaces inside the package MUST build paths through
+ * `useBackofficeConfig().paths` (basePath-aware). The default-bound helpers
+ * at the bottom exist for host apps mounted at the canonical "/backoffice"
+ * prefix — their template-literal return types match one-router's generated
+ * typed-route unions so they can be passed straight to router.push and
+ * <Link href>.
+ */
+
+export const BACKOFFICE_BASE = "/backoffice";
+
+export type BackofficeSubPath = `${typeof BACKOFFICE_BASE}/${string}`;
+export type BackofficePath = typeof BACKOFFICE_BASE | BackofficeSubPath;
+
+export const BACKOFFICE_VIEWS = [
+  "list",
+  "report",
+  "kanban",
+  "calendar",
+  "tree",
+  "image",
+  "dashboard",
+] as const;
+
+export type BackofficeView = (typeof BACKOFFICE_VIEWS)[number];
+
+export function isBackofficeView(value: string): value is BackofficeView {
+  return (BACKOFFICE_VIEWS as readonly string[]).includes(value);
+}
+
+/** frappe.router.slug: "Sales Order" → "sales-order" */
+export function toSlug(name: string): string {
+  return name.toLowerCase().replace(/ /g, "-");
+}
+
+/** Best-effort display name from a slug: "sales-order" → "Sales Order" */
+export function slugToDisplayName(slug: string): string {
+  return slug.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Parse the `?d=` new-doc defaults query (urlencoded JSON object). The
+ * router usually decodes the param already, so the raw value is tried first.
+ * Malformed or non-object input degrades to no defaults.
+ */
+export function parseDocDefaults(raw: string | undefined): Record<string, unknown> | undefined {
+  if (!raw) return undefined;
+  const candidates = [raw];
+  try {
+    const decoded = decodeURIComponent(raw);
+    if (decoded !== raw) candidates.push(decoded);
+  } catch {
+    // raw is not percent-encoded — the direct candidate covers it
+  }
+  for (const candidate of candidates) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // not JSON in this shape — try the next candidate
+    }
+  }
+  return undefined;
+}
+
+/** Path builders bound to a mount prefix. */
+export interface BackofficePaths {
+  /** The mount prefix these builders are bound to (no trailing slash). */
+  base: string;
+  home(): string;
+  workspace(workspaceName: string): string;
+  list(doctype: string): string;
+  view(doctype: string, view: BackofficeView): string;
+  /**
+   * New-document route. Optional `defaults` become the create form's initial
+   * field values, carried as `?d=<urlencoded JSON object>` — desk parity for
+   * creating from context (kanban column "+", calendar day click, …).
+   */
+  newDoc(doctype: string, defaults?: Record<string, unknown>): string;
+  form(doctype: string, name: string): string;
+}
+
+export function createBackofficePaths(basePath: string = BACKOFFICE_BASE): BackofficePaths {
+  const base = basePath.replace(/\/+$/, "") || "/";
+  const prefix = base === "/" ? "" : base;
+  return {
+    base,
+    home: () => base,
+    workspace: (workspaceName) => `${prefix}/${toSlug(workspaceName)}`,
+    list: (doctype) => `${prefix}/${toSlug(doctype)}`,
+    view: (doctype, view) =>
+      view === "list"
+        ? `${prefix}/${toSlug(doctype)}`
+        : `${prefix}/${toSlug(doctype)}/view/${view}`,
+    newDoc: (doctype, defaults) => {
+      const path = `${prefix}/${toSlug(doctype)}/new`;
+      if (!defaults || Object.keys(defaults).length === 0) return path;
+      return `${path}?d=${encodeURIComponent(JSON.stringify(defaults))}`;
+    },
+    form: (doctype, name) => `${prefix}/${toSlug(doctype)}/${encodeURIComponent(name)}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Default-bound helpers ("/backoffice" prefix — one-router typed-route compat)
+// ---------------------------------------------------------------------------
+
+const defaultPaths = createBackofficePaths(BACKOFFICE_BASE);
+
+export function homePath(): BackofficePath {
+  return defaultPaths.home() as BackofficePath;
+}
+
+export function workspacePath(workspaceName: string): BackofficeSubPath {
+  return defaultPaths.workspace(workspaceName) as BackofficeSubPath;
+}
+
+export function listPath(doctype: string): BackofficeSubPath {
+  return defaultPaths.list(doctype) as BackofficeSubPath;
+}
+
+export function viewPath(doctype: string, view: BackofficeView): BackofficeSubPath {
+  return defaultPaths.view(doctype, view) as BackofficeSubPath;
+}
+
+export function newDocPath(doctype: string, defaults?: Record<string, unknown>): BackofficeSubPath {
+  return defaultPaths.newDoc(doctype, defaults) as BackofficeSubPath;
+}
+
+export function formPath(doctype: string, name: string): BackofficeSubPath {
+  return defaultPaths.form(doctype, name) as BackofficeSubPath;
+}

package/src/oneAdapter/index.tsx

@@ -0,0 +1,61 @@
+/**
+ * One-router adapter — subpath export `@multiplatform.one/backoffice/one-adapter`.
+ *
+ * Lives on its own export path so the MAIN entry stays router-free: `one` is
+ * an optional peer, only resolved by hosts that import this adapter (same
+ * pattern as `@multiplatform.one/router`'s `./seam` subpath).
+ *
+ * Usage (a One app's backoffice layout):
+ *
+ *   const navigation = useOneNavigator();
+ *   return (
+ *     <BackofficeProvider frappe={{ baseURL }} navigation={navigation}>
+ *       <BackofficeShell><Slot /></BackofficeShell>
+ *     </BackofficeProvider>
+ *   );
+ */
+import { useLocalSearchParams, usePathname, useRouter } from "one";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import {
+  ControlledNavigator,
+  type BackofficeNavigator,
+  type BackofficeParams,
+} from "../navigation/navigator";
+
+// SSR-safe layout effect: One renders routes server-side, where
+// useLayoutEffect warns; the location mirror runs post-render either way.
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * A {@link BackofficeNavigator} backed by One's router. Referentially stable
+ * across renders; the current pathname + search params are mirrored into the
+ * navigator's subscribable location after every route change.
+ */
+export function useOneNavigator(): BackofficeNavigator {
+  const router = useRouter();
+  const pathname = usePathname();
+  const params = useLocalSearchParams() as BackofficeParams;
+
+  // One's router object is referentially stable, but route through a ref so
+  // even a host swapping router implementations stays wired.
+  const routerRef = useRef(router);
+  routerRef.current = router;
+
+  const [navigator] = useState(
+    () =>
+      new ControlledNavigator(
+        {
+          navigate: (path) => routerRef.current.push(path as never),
+          replace: (path) => routerRef.current.replace(path as never),
+          back: () => routerRef.current.back(),
+        },
+        { path: pathname, params },
+      ),
+  );
+
+  useIsomorphicLayoutEffect(() => {
+    navigator.setLocation({ path: pathname, params });
+  }, [navigator, pathname, params]);
+
+  return navigator;
+}

package/src/shared/useFrappeApp.ts

@@ -0,0 +1,39 @@
+import { FrappeApp, type AuthConfig } from "@multiplatform.one/frappe";
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useMemo } from "react";
+
+const appCache = new Map<string, FrappeApp>();
+
+/**
+ * Memoized FrappeApp built from the ambient FrappeProvider config (mounted
+ * by BackofficeProvider). Use `app.call()` for desk RPCs, `app.db()` for
+ * CRUD, `app.file()` for uploads. Prefer Frappe* components /
+ * useFrappeCollection where possible — reach for this only when no component
+ * covers the API. Returns undefined outside a provider.
+ */
+export function useFrappeApp(): FrappeApp | undefined {
+  const config = useFrappeConfig();
+  const baseURL = config?.baseURL;
+  // Without socketPort the realtime module dials `${baseURL}/socket.io`
+  // (:8000 in dev) instead of frappe's socketio server (:9000), producing a
+  // CORS-failed handshake on every mount.
+  const socketPort = config?.socketPort;
+  const useToken = config?.auth?.useToken;
+  const token = config?.auth?.token;
+  const type = config?.auth?.type;
+  return useMemo(() => {
+    if (!baseURL) return undefined;
+    const key = `${baseURL}|${socketPort ?? ""}|${useToken ? "t" : ""}|${token ?? ""}|${type ?? ""}`;
+    let app = appCache.get(key);
+    if (!app) {
+      app = new FrappeApp(baseURL, {
+        useToken,
+        token,
+        type: (type === "Bearer" ? "Bearer" : type ? "token" : undefined) as AuthConfig["type"],
+        realtimeOptions: socketPort ? { socketPort } : undefined,
+      });
+      appCache.set(key, app);
+    }
+    return app;
+  }, [baseURL, socketPort, useToken, token, type]);
+}

package/src/shell/BackofficeShell.tsx

@@ -0,0 +1,222 @@
+/**
+ * Backoffice desk chrome: top navbar (app title → home, centered awesomebar,
+ * notifications / help / user menus) and the left workspace sidebar around
+ * the routed content.
+ *
+ * Router-free by design — navigation and the active path come from the
+ * BackofficeProvider's navigator (explicit `activePath`/`onNavigate` props
+ * override it for stories/tests). Capability flags from the provider gate
+ * every piece of chrome; `renderShellHeader`/`renderSidebarFooter` slots
+ * replace/extend the built-ins. Narrow viewports collapse the sidebar into
+ * an overlay drawer (same breakpoint as frappe-ui's DeskShell:
+ * DESK_NARROW_BREAKPOINT === theme NARROW_BREAKPOINT).
+ */
+import { Button, SizableText, XStack, YStack, isWeb } from "@multiplatform.one/components";
+import { useLayoutSizeClass, useResolvedKnobs } from "@multiplatform.one/theme";
+import { ListIcon, XIcon } from "@phosphor-icons/react";
+import type React from "react";
+import { useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  BackofficeAwesomebar,
+  type BackofficeAwesomebarHandle,
+} from "../chrome/BackofficeAwesomebar";
+import { HelpMenu } from "../chrome/HelpMenu";
+import { NotificationsButton } from "../chrome/NotificationsButton";
+import { useBackofficeShortcuts } from "../chrome/shortcuts";
+import { UserMenu } from "../chrome/UserMenu";
+import {
+  useBackofficeCapabilities,
+  useBackofficeLocation,
+  useBackofficeNavigator,
+  useBackofficePaths,
+  useBackofficeSlots,
+} from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { WorkspaceSidebar } from "./WorkspaceSidebar";
+
+export interface BackofficeShellProps {
+  children: React.ReactNode;
+  /** Current path for the sidebar active state (default: navigator location). */
+  activePath?: string;
+  /** Navigation handler (default: navigator push). */
+  onNavigate?: (path: string) => void;
+}
+
+/**
+ * Cross-platform narrow-viewport detection: theme `compact` size class =
+ * width < NARROW_BREAKPOINT (640) — matchMedia on web, window dimensions on
+ * native, so phones get the drawer instead of a permanent desktop rail.
+ */
+function useIsNarrow(): boolean {
+  return useLayoutSizeClass() === "compact";
+}
+
+export function BackofficeShell({ children, activePath, onNavigate }: BackofficeShellProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  const capabilities = useBackofficeCapabilities();
+  const slots = useBackofficeSlots();
+  const navigator = useBackofficeNavigator();
+  const location = useBackofficeLocation();
+  const paths = useBackofficePaths();
+  const isNarrow = useIsNarrow();
+  const [drawerOpen, setDrawerOpen] = useState(false);
+
+  const resolvedActivePath = activePath ?? location.path;
+  const navigate = onNavigate ?? navigator.navigate;
+
+  const sidebarEnabled = capabilities.sidebar.enabled;
+
+  // Global desk shortcuts (Mod+K / Mod+G → awesomebar). One document
+  // listener for the whole chrome; SSR/native-safe, skips editable targets.
+  const awesomebarRef = useRef<BackofficeAwesomebarHandle>(null);
+  useBackofficeShortcuts({
+    onFocusSearch: capabilities.awesomebar.enabled
+      ? () => awesomebarRef.current?.focus()
+      : undefined,
+  });
+
+  // Leaving the narrow range always closes the drawer.
+  useEffect(() => {
+    if (!isNarrow) setDrawerOpen(false);
+  }, [isNarrow]);
+
+  // Escape dismisses the drawer (web-only keyboard listener).
+  useEffect(() => {
+    if (!isWeb || typeof document === "undefined" || !drawerOpen) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setDrawerOpen(false);
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [drawerOpen]);
+
+  const handleNavigate = (path: string) => {
+    if (isNarrow) setDrawerOpen(false);
+    navigate(path);
+  };
+
+  const surfaceBorderWidth = knobProps.surface.borderWidth;
+
+  const sidebarContent = (
+    <>
+      <WorkspaceSidebar activePath={resolvedActivePath} onNavigate={handleNavigate} />
+      {slots.renderSidebarFooter?.()}
+    </>
+  );
+
+  const headerContent = (
+    <>
+      {isNarrow && sidebarEnabled && (
+        <Button
+          chromeless
+          circular
+          size="$3"
+          icon={drawerOpen ? XIcon : ListIcon}
+          aria-label={t("shell.toggleSidebar", "Toggle sidebar")}
+          aria-expanded={drawerOpen}
+          onPress={() => setDrawerOpen((open) => !open)}
+          data-testid="backoffice-sidebar-toggle"
+        />
+      )}
+      <Button
+        chromeless
+        size="$3"
+        paddingHorizontal="$2"
+        onPress={() => handleNavigate(paths.home())}
+        aria-label={t("shell.home", "Home")}
+        data-testid="backoffice-home"
+      >
+        <SizableText size="$5" fontWeight="700">
+          {t("shell.title", "Backoffice")}
+        </SizableText>
+      </Button>
+
+      {/* Centered awesomebar (the flex spacer keeps the right chrome pinned
+          when the awesomebar capability is off) */}
+      <XStack flex={1} minWidth={0} justifyContent="center">
+        {capabilities.awesomebar.enabled && (
+          <XStack flex={1} maxWidth={560} minWidth={0}>
+            <BackofficeAwesomebar focusRef={awesomebarRef} />
+          </XStack>
+        )}
+      </XStack>
+
+      {/* Right chrome */}
+      <XStack alignItems="center" gap="$1" flexShrink={0}>
+        {capabilities.notifications.enabled && <NotificationsButton />}
+        {capabilities.help.enabled && <HelpMenu />}
+        {capabilities.userMenu.enabled && <UserMenu />}
+      </XStack>
+    </>
+  );
+
+  return (
+    <YStack flex={1} height="100%" width="100%" overflow="hidden" data-testid="backoffice-shell">
+      {/* Top navbar */}
+      <XStack
+        role="banner"
+        {...knobProps.surface}
+        // Surface knobs paint a full box border; keep only the bottom edge
+        // (DeskShell precedent, SB-M-1708).
+        borderWidth={0}
+        borderBottomWidth={surfaceBorderWidth}
+        borderBottomColor={knobProps.surface.borderColor}
+        alignItems="center"
+        paddingHorizontal="$3"
+        paddingVertical="$2"
+        gap="$2"
+        flexShrink={0}
+      >
+        {slots.renderShellHeader
+          ? slots.renderShellHeader({ defaultContent: headerContent })
+          : headerContent}
+      </XStack>
+
+      <XStack flex={1} minWidth={0} position="relative" overflow="hidden">
+        {/* Desktop rail — in flow */}
+        {sidebarEnabled && !isNarrow && (
+          <YStack role="navigation" flexShrink={0} data-testid="backoffice-sidebar-rail">
+            {sidebarContent}
+          </YStack>
+        )}
+
+        {/* Narrow drawer + scrim */}
+        {sidebarEnabled && isNarrow && drawerOpen && (
+          <>
+            <YStack
+              position="absolute"
+              top={0}
+              left={0}
+              right={0}
+              bottom={0}
+              backgroundColor="$shadowColor"
+              opacity={0.5}
+              zIndex={10}
+              onPress={() => setDrawerOpen(false)}
+              data-testid="backoffice-sidebar-scrim"
+            />
+            <YStack
+              role="navigation"
+              position="absolute"
+              top={0}
+              left={0}
+              bottom={0}
+              zIndex={11}
+              backgroundColor="$background"
+              data-testid="backoffice-sidebar-drawer"
+            >
+              {sidebarContent}
+            </YStack>
+          </>
+        )}
+
+        {/* Routed content — pages own their own headers/breadcrumbs */}
+        <YStack role="main" flex={1} minWidth={0}>
+          {children}
+        </YStack>
+      </XStack>
+    </YStack>
+  );
+}

package/src/shell/WorkspaceSidebar.tsx

@@ -0,0 +1,119 @@
+/**
+ * Left workspace navigation for the backoffice shell (desk parity).
+ *
+ * Private workspaces (for_user = session user) on top, public workspaces
+ * below ordered by sequence_id, children nested via parent_page (rendered
+ * indented under their parent). Data is live via useWorkspaces; paths come
+ * from the BackofficeProvider (basePath-aware).
+ */
+import {
+  Sidebar,
+  Spinner,
+  XStack,
+  YStack,
+  type SidebarItem,
+  type SidebarSection,
+} from "@multiplatform.one/components";
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { useBackofficePaths } from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import type { BackofficePaths } from "../navigation/paths";
+import { useWorkspaces, type WorkspaceDoc } from "./useWorkspaces";
+import { workspaceIcon } from "./workspaceIcons";
+
+export const WORKSPACE_SIDEBAR_WIDTH = 250;
+
+export interface WorkspaceSidebarProps {
+  /** Current path, used to highlight the active workspace. */
+  activePath?: string;
+  /** Called with the target path when a workspace is selected. */
+  onNavigate?: (path: string) => void;
+}
+
+function workspaceItem(
+  workspace: WorkspaceDoc,
+  depth: number,
+  paths: BackofficePaths,
+  activePath: string | undefined,
+  onNavigate: ((path: string) => void) | undefined,
+): SidebarItem {
+  const path = paths.workspace(workspace.name);
+  const IconComponent = workspaceIcon(workspace.icon);
+  const icon = (
+    // Depth-based inset carried by the icon slot — the Sidebar row API has
+    // no nesting support, so children indent icon+label via this wrapper.
+    <XStack paddingLeft={depth > 0 ? depth * 16 : 0}>
+      <IconComponent size={16} />
+    </XStack>
+  );
+  return {
+    label: workspace.title || workspace.name,
+    value: path,
+    icon,
+    active: activePath === path,
+    onPress: onNavigate ? () => onNavigate(path) : undefined,
+  };
+}
+
+/** Flatten a workspace tree into indented sidebar items (children follow parents). */
+function flattenTree(
+  roots: WorkspaceDoc[],
+  childrenByParent: Map<string, WorkspaceDoc[]>,
+  paths: BackofficePaths,
+  activePath: string | undefined,
+  onNavigate: ((path: string) => void) | undefined,
+  depth = 0,
+): SidebarItem[] {
+  const items: SidebarItem[] = [];
+  for (const workspace of roots) {
+    items.push(workspaceItem(workspace, depth, paths, activePath, onNavigate));
+    const children = childrenByParent.get(workspace.name);
+    if (children?.length) {
+      items.push(
+        ...flattenTree(children, childrenByParent, paths, activePath, onNavigate, depth + 1),
+      );
+    }
+  }
+  return items;
+}
+
+export function WorkspaceSidebar({ activePath, onNavigate }: WorkspaceSidebarProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const paths = useBackofficePaths();
+  const { privateWorkspaces, publicRoots, childrenByParent, isLoading } = useWorkspaces();
+
+  const sections = useMemo<SidebarSection[]>(() => {
+    const result: SidebarSection[] = [];
+    if (privateWorkspaces.length > 0) {
+      result.push({
+        title: t("sidebar.private", "Private"),
+        items: privateWorkspaces.map((workspace) =>
+          workspaceItem(workspace, 0, paths, activePath, onNavigate),
+        ),
+      });
+    }
+    if (publicRoots.length > 0) {
+      result.push({
+        title: t("sidebar.public", "Public"),
+        items: flattenTree(publicRoots, childrenByParent, paths, activePath, onNavigate),
+      });
+    }
+    return result;
+  }, [privateWorkspaces, publicRoots, childrenByParent, paths, activePath, onNavigate, t]);
+
+  if (isLoading && sections.length === 0) {
+    return (
+      <YStack
+        width={WORKSPACE_SIDEBAR_WIDTH}
+        alignItems="center"
+        paddingTop="$6"
+        aria-label={t("sidebar.loading", "Loading workspaces")}
+      >
+        <Spinner size="small" />
+      </YStack>
+    );
+  }
+
+  return <Sidebar sections={sections} width={WORKSPACE_SIDEBAR_WIDTH} />;
+}