@multiplatform.one/backoffice 6.3.0

package/src/i18n/en.ts

@@ -0,0 +1,83 @@
+/**
+ * Bundled English resources for the "backoffice" i18n namespace.
+ *
+ * Keys mirror the surface structure (shell/sidebar/awesomebar/notifications/
+ * userMenu/help). Host apps override by registering their own bundle:
+ *
+ *   i18next.addResourceBundle("en", "backoffice", { shell: { title: "Admin" } }, true, true);
+ */
+export const en = {
+  shell: {
+    title: "Backoffice",
+    home: "Home",
+    toggleSidebar: "Toggle sidebar",
+  },
+  sidebar: {
+    private: "Private",
+    public: "Public",
+    loading: "Loading workspaces",
+  },
+  awesomebar: {
+    triggerLabel: "Search",
+    placeholder: "Search or type a command…",
+    label: "Search or type a command",
+    results: "Search results",
+    recents: "Recents",
+    actions: "Actions",
+    navigation: "Navigation",
+    documents: "Documents",
+    listCommand: "{{doctype}} List",
+    newCommand: "New {{doctype}}",
+    reportCommand: "{{doctype}} Report",
+    kanbanCommand: "{{doctype}} Kanban",
+    workspaceBadge: "Workspace",
+    doctypeBadge: "DocType",
+    searching: "Searching…",
+    noResults: "No results for “{{query}}”",
+    empty: "Type to search…",
+    hintNavigate: "navigate",
+    hintOpen: "open",
+    hintClose: "close",
+  },
+  notifications: {
+    title: "Notifications",
+    untitled: "Notification",
+    markAllRead: "Mark all as read",
+    settingsUnavailable: "Notification settings (not available yet)",
+    emptyTitle: "No new notifications",
+    emptyDescription: "Mentions, assignments, and shares will show up here.",
+  },
+  userMenu: {
+    label: "User menu",
+    sessionUnavailable: "Session not loaded",
+    myProfile: "My Profile",
+    mySettings: "My Settings",
+    sessionDefaults: "Session Defaults",
+    sessionDefaultsGap: "Not implemented yet",
+    reload: "Reload",
+    toggleTheme: "Toggle Theme",
+    themeUnavailable: "Theme switching is unavailable on this platform",
+    viewWebsite: "View Website",
+    exitToSite: "← multiplatform.one",
+    logOut: "Log Out",
+  },
+  help: {
+    label: "Help",
+    documentation: "Documentation",
+    userForum: "User Forum",
+    reportIssue: "Report an Issue",
+    keyboardShortcuts: "Keyboard Shortcuts",
+    about: "About",
+    aboutTitle: "About",
+    aboutTagline:
+      "Backoffice is the multiplatform.one recreation of the Frappe Desk — one codebase across web, mobile, and desktop.",
+    installedApps: "Installed Apps",
+    versionsUnavailable: "Version information is unavailable.",
+    close: "Close",
+    shortcutsTitle: "Keyboard Shortcuts",
+    shortcutsIntro: "Shortcuts available across the backoffice (web).",
+    shortcutFocusSearch: "Open the command palette",
+    shortcutSaveForm: "Save the open document",
+    shortcutCloseOverlays: "Close dialogs and menus",
+  },
+} as const;

package/src/i18n/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Backoffice i18n — the package ships its own translations under the
+ * "backoffice" namespace (English bundled; more languages can join the
+ * BUNDLED_RESOURCES map) and registers them into the ambient i18next
+ * instance, following @multiplatform.one/i18n conventions:
+ *
+ *   - registration is additive: `addResourceBundle(lng, ns, …, deep=true,
+ *     overwrite=false)`, so anything the HOST already registered for the
+ *     namespace wins, and a Frappe i18n backend (partialBundledLanguages)
+ *     can still supplement over the bundle.
+ *   - every t() call in the package also carries an inline English default,
+ *     so a missing bundle degrades to English instead of raw keys.
+ *
+ * When no i18next instance was initialized at all (a host app that does not
+ * use i18n), the provider initializes a minimal English-only instance so
+ * react-i18next binds a working `t`.
+ */
+import i18next, { type i18n as I18nInstance } from "i18next";
+import { initReactI18next } from "react-i18next";
+import { en } from "./en";
+
+export const BACKOFFICE_I18N_NAMESPACE = "backoffice";
+
+const BUNDLED_RESOURCES: Record<string, object> = { en };
+
+const registeredInstances = new WeakSet<I18nInstance>();
+
+function addBundles(instance: I18nInstance): void {
+  for (const [lng, resources] of Object.entries(BUNDLED_RESOURCES)) {
+    // deep merge, never overwrite — host-registered keys take precedence.
+    instance.addResourceBundle(lng, BACKOFFICE_I18N_NAMESPACE, resources, true, false);
+  }
+  // Satisfy backends that lazy-load namespaces (react-i18next readiness).
+  void instance.loadNamespaces(BACKOFFICE_I18N_NAMESPACE).catch(() => {});
+}
+
+/**
+ * Idempotently register the bundled backoffice translations on `instance`
+ * (the global i18next singleton by default). Safe to call before the host
+ * initializes i18next — registration is deferred to the `initialized` event.
+ * Called automatically by BackofficeProvider.
+ */
+export function registerBackofficeTranslations(instance: I18nInstance = i18next): void {
+  if (registeredInstances.has(instance)) return;
+  registeredInstances.add(instance);
+
+  if (instance.isInitialized) {
+    addBundles(instance);
+    return;
+  }
+
+  instance.on("initialized", () => addBundles(instance));
+
+  // No host i18n at all: bring up a minimal instance so t() works. Guarded
+  // against a host init that is merely in flight.
+  const initializing = (instance as { isInitializing?: boolean }).isInitializing;
+  if (!initializing && !instance.isInitialized) {
+    void instance.use(initReactI18next).init({
+      lng: "en",
+      fallbackLng: "en",
+      defaultNS: BACKOFFICE_I18N_NAMESPACE,
+      ns: [BACKOFFICE_I18N_NAMESPACE],
+      resources: {},
+      interpolation: { escapeValue: false },
+      returnNull: false,
+      returnEmptyString: false,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,150 @@
+/**
+ * @multiplatform.one/backoffice — embeddable Frappe desk recreation.
+ *
+ * Mount BackofficeProvider (frappe connection + navigation adapter +
+ * capability flags) around the surfaces you want; BackofficeShell is the
+ * full desk chrome. See README.md for the embedding story.
+ *
+ * The one-router adapter lives on the `./one-adapter` subpath so this entry
+ * stays router-free.
+ */
+
+// Provider + config
+export {
+  BackofficeProvider,
+  useBackofficeCapabilities,
+  useBackofficeConfig,
+  useBackofficeLocation,
+  useBackofficeNavigator,
+  useBackofficePaths,
+  useBackofficeSlots,
+  useIsDoctypeAllowed,
+} from "./config/BackofficeProvider";
+export type {
+  BackofficeAction,
+  BackofficeActionContext,
+  BackofficeActions,
+  BackofficeAppearance,
+  BackofficeConfig,
+  BackofficeFrappeConfig,
+  BackofficeProviderProps,
+} from "./config/BackofficeProvider";
+export { isDoctypeAllowed, resolveCapabilities } from "./config/capabilities";
+export type {
+  BackofficeCapabilities,
+  BackofficeDoctypeScope,
+  CapabilityInput,
+  ResolvedBackofficeCapabilities,
+  ResolvedCapability,
+  ResolvedExitToSite,
+} from "./config/capabilities";
+export type { BackofficeEvent, BackofficeEventHandler } from "./config/events";
+export type { BackofficeSlots } from "./config/slots";
+
+// Navigation seam
+export {
+  ControlledNavigator,
+  MemoryNavigator,
+  createMemoryNavigator,
+  createNoopNavigator,
+  parseBackofficeHref,
+} from "./navigation/navigator";
+export type {
+  BackofficeLocation,
+  BackofficeNavigator,
+  BackofficeParams,
+  ControlledNavigatorHandlers,
+} from "./navigation/navigator";
+export {
+  BACKOFFICE_BASE,
+  BACKOFFICE_VIEWS,
+  createBackofficePaths,
+  formPath,
+  homePath,
+  isBackofficeView,
+  listPath,
+  newDocPath,
+  parseDocDefaults,
+  slugToDisplayName,
+  toSlug,
+  viewPath,
+  workspacePath,
+} from "./navigation/paths";
+export type {
+  BackofficePath,
+  BackofficePaths,
+  BackofficeSubPath,
+  BackofficeView,
+} from "./navigation/paths";
+
+// i18n
+export { BACKOFFICE_I18N_NAMESPACE, registerBackofficeTranslations } from "./i18n";
+
+// Shell
+export { BackofficeShell } from "./shell/BackofficeShell";
+export type { BackofficeShellProps } from "./shell/BackofficeShell";
+export { WORKSPACE_SIDEBAR_WIDTH, WorkspaceSidebar } from "./shell/WorkspaceSidebar";
+export type { WorkspaceSidebarProps } from "./shell/WorkspaceSidebar";
+export { useDefaultWorkspace, useSessionUser, useWorkspaces } from "./shell/useWorkspaces";
+export type { WorkspaceDoc, WorkspacesResult } from "./shell/useWorkspaces";
+export { workspaceIcon } from "./shell/workspaceIcons";
+
+// Chrome
+export { BackofficeAwesomebar } from "./chrome/BackofficeAwesomebar";
+export type {
+  BackofficeAwesomebarHandle,
+  BackofficeAwesomebarProps,
+} from "./chrome/BackofficeAwesomebar";
+export { CommandPalette } from "./chrome/CommandPalette";
+export type { CommandPaletteProps } from "./chrome/CommandPalette";
+export { useCommandPaletteModel } from "./chrome/command-palette-model";
+export type {
+  CommandPaletteItem,
+  CommandPaletteModel,
+  CommandPaletteSection,
+  CommandPaletteSectionId,
+  UseCommandPaletteModelOptions,
+} from "./chrome/command-palette-model";
+export {
+  rankNameMatches,
+  readRecentItems,
+  toContentSnippet,
+  useAwesomebarCatalog,
+  useGlobalSearch,
+} from "./chrome/awesomebar-data";
+export type {
+  AwesomebarCatalog,
+  AwesomebarCatalogState,
+  AwesomebarWorkspace,
+  GlobalSearchHit,
+  GlobalSearchState,
+  RecentItem,
+} from "./chrome/awesomebar-data";
+export { NotificationsButton } from "./chrome/NotificationsButton";
+export { NotificationsPanel } from "./chrome/notifications-panel";
+export type { NotificationsPanelProps } from "./chrome/notifications-panel";
+export { useNotifications } from "./chrome/notifications-data";
+export type {
+  NotificationItem,
+  NotificationLogDoc,
+  UseNotificationsResult,
+} from "./chrome/notifications-data";
+export { parseFrappeTimestamp, stripHtmlToText } from "./chrome/notifications-utils";
+export { HelpMenu } from "./chrome/HelpMenu";
+export { HelpAboutDialog } from "./chrome/help-about-dialog";
+export type { FrappeAppVersion, HelpAboutDialogProps } from "./chrome/help-about-dialog";
+export { HelpShortcutsDialog } from "./chrome/help-shortcuts-dialog";
+export type { HelpShortcutsDialogProps } from "./chrome/help-shortcuts-dialog";
+export { UserMenu } from "./chrome/UserMenu";
+export type { UserMenuProps } from "./chrome/UserMenu";
+export {
+  clearSessionUserCache,
+  resolveUserImageUrl,
+  useSessionUserInfo,
+} from "./chrome/user-session";
+export type { SessionUserInfo } from "./chrome/user-session";
+export { useBackofficeShortcuts } from "./chrome/shortcuts";
+export type { BackofficeShortcutHandlers } from "./chrome/shortcuts";
+
+// Shared
+export { useFrappeApp } from "./shared/useFrappeApp";

package/src/navigation/navigator.spec.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from "vitest";
+import { ControlledNavigator, createMemoryNavigator, parseBackofficeHref } from "./navigator";
+
+describe("parseBackofficeHref", () => {
+  it("splits path and query params", () => {
+    const location = parseBackofficeHref("/backoffice/todo?f=abc&x=1");
+    expect(location.path).toBe("/backoffice/todo");
+    expect(location.params).toEqual({ f: "abc", x: "1" });
+  });
+
+  it("collects repeated keys into arrays", () => {
+    const location = parseBackofficeHref("/backoffice?tag=a&tag=b");
+    expect(location.params).toEqual({ tag: ["a", "b"] });
+  });
+
+  it("decodes percent-encoded params", () => {
+    const location = parseBackofficeHref(
+      "/backoffice/sales-order?d=%7B%22status%22%3A%22Open%22%7D",
+    );
+    expect(location.params.d).toBe('{"status":"Open"}');
+  });
+});
+
+describe("MemoryNavigator (navigator contract)", () => {
+  it("starts on the initial path", () => {
+    const navigator = createMemoryNavigator("/backoffice");
+    expect(navigator.getLocation()).toEqual({ path: "/backoffice", params: {} });
+  });
+
+  it("navigate pushes entries and notifies subscribers", () => {
+    const navigator = createMemoryNavigator("/backoffice");
+    const listener = vi.fn();
+    navigator.subscribe(listener);
+
+    navigator.navigate("/backoffice/todo?f=x");
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(navigator.getLocation()).toEqual({ path: "/backoffice/todo", params: { f: "x" } });
+    expect(navigator.entries).toHaveLength(2);
+  });
+
+  it("replace swaps the top entry without growing the stack", () => {
+    const navigator = createMemoryNavigator("/backoffice");
+    navigator.navigate("/backoffice/todo");
+    navigator.replace("/backoffice/note");
+
+    expect(navigator.entries).toHaveLength(2);
+    expect(navigator.getLocation().path).toBe("/backoffice/note");
+  });
+
+  it("back pops to the previous entry and is a no-op at the root", () => {
+    const navigator = createMemoryNavigator("/backoffice");
+    navigator.navigate("/backoffice/todo");
+    navigator.back();
+    expect(navigator.getLocation().path).toBe("/backoffice");
+
+    navigator.back();
+    expect(navigator.getLocation().path).toBe("/backoffice");
+  });
+
+  it("getLocation identity is stable until the location changes", () => {
+    const navigator = createMemoryNavigator("/backoffice");
+    const first = navigator.getLocation();
+    expect(navigator.getLocation()).toBe(first);
+    navigator.navigate("/backoffice/todo");
+    expect(navigator.getLocation()).not.toBe(first);
+  });
+
+  it("unsubscribe stops notifications", () => {
+    const navigator = createMemoryNavigator("/backoffice");
+    const listener = vi.fn();
+    const unsubscribe = navigator.subscribe(listener);
+    unsubscribe();
+    navigator.navigate("/backoffice/todo");
+    expect(listener).not.toHaveBeenCalled();
+  });
+});
+
+describe("ControlledNavigator (bridge contract)", () => {
+  it("forwards navigation to the host handlers", () => {
+    const handlers = { navigate: vi.fn(), replace: vi.fn(), back: vi.fn() };
+    const navigator = new ControlledNavigator(handlers, { path: "/backoffice", params: {} });
+
+    navigator.navigate("/backoffice/todo");
+    navigator.replace("/backoffice/note");
+    navigator.back();
+
+    expect(handlers.navigate).toHaveBeenCalledWith("/backoffice/todo");
+    expect(handlers.replace).toHaveBeenCalledWith("/backoffice/note");
+    expect(handlers.back).toHaveBeenCalledTimes(1);
+  });
+
+  it("mirrors host location through setLocation and notifies", () => {
+    const navigator = new ControlledNavigator(
+      { navigate: () => {}, replace: () => {}, back: () => {} },
+      { path: "/backoffice", params: {} },
+    );
+    const listener = vi.fn();
+    navigator.subscribe(listener);
+
+    navigator.setLocation({ path: "/backoffice/todo", params: { f: "x" } });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(navigator.getLocation().path).toBe("/backoffice/todo");
+  });
+});

package/src/navigation/navigator.ts

@@ -0,0 +1,209 @@
+/**
+ * Backoffice navigation seam.
+ *
+ * The backoffice never imports a router. Every surface navigates through a
+ * host-supplied {@link BackofficeNavigator} — a deliberately minimal contract
+ * (push/replace/back + a subscribable location) that any routing runtime can
+ * satisfy in a few lines:
+ *
+ *   - One router      → `useOneNavigator()` from
+ *                       `@multiplatform.one/backoffice/one-adapter`
+ *   - tests/storybook → {@link createMemoryNavigator}
+ *   - custom hosts    → {@link ControlledNavigator} (bridge callbacks in,
+ *                       mirror location back with `setLocation`)
+ *
+ * This is intentionally lighter than the stack-navigation seam in
+ * `@multiplatform.one/router/seam`: that module OWNS a navigation stack
+ * (route manifest + host stack adapter) for targets with no router at all,
+ * while this contract EMBEDS into whatever router the host app already runs.
+ * A seam-backed host can still implement this interface over its
+ * StackNavigator (push/replace/back map 1:1, location from `useNavState`).
+ */
+
+export type BackofficeParams = Record<string, string | string[] | undefined>;
+
+export interface BackofficeLocation {
+  /** Current pathname (no query string), e.g. `"/backoffice/todo"`. */
+  path: string;
+  /** Dynamic route segments merged with query params (One router semantics). */
+  params: BackofficeParams;
+}
+
+export interface BackofficeNavigator {
+  /** Push a new history entry. */
+  navigate(path: string): void;
+  /** Replace the current history entry. */
+  replace(path: string): void;
+  /** Go back one entry. */
+  back(): void;
+  /** Snapshot of the current location (stable identity until it changes). */
+  getLocation(): BackofficeLocation;
+  /** Subscribe to location changes. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+}
+
+/**
+ * Minimal query parser (repeated keys become arrays). Deliberately not
+ * URLSearchParams so this module has zero polyfill-order dependency — same
+ * trade the router seam makes for GJS entries.
+ */
+function parseQuery(query: string | undefined): BackofficeParams {
+  const params: BackofficeParams = {};
+  if (!query) return params;
+  for (const pair of query.split("&")) {
+    if (!pair) continue;
+    const eq = pair.indexOf("=");
+    const rawKey = eq === -1 ? pair : pair.slice(0, eq);
+    const rawValue = eq === -1 ? "" : pair.slice(eq + 1);
+    let key = rawKey;
+    let value = rawValue;
+    try {
+      key = decodeURIComponent(rawKey);
+      value = decodeURIComponent(rawValue);
+    } catch {
+      // malformed escape — keep the raw pair
+    }
+    const prev = params[key];
+    if (prev === undefined) params[key] = value;
+    else if (Array.isArray(prev)) prev.push(value);
+    else params[key] = [prev, value];
+  }
+  return params;
+}
+
+/** Split an href into a {@link BackofficeLocation} (query → params). */
+export function parseBackofficeHref(href: string): BackofficeLocation {
+  const queryIndex = href.indexOf("?");
+  const path = queryIndex === -1 ? href : href.slice(0, queryIndex);
+  const query = queryIndex === -1 ? undefined : href.slice(queryIndex + 1);
+  return { path: path || "/", params: parseQuery(query) };
+}
+
+type Listener = () => void;
+
+abstract class SubscribableNavigator implements BackofficeNavigator {
+  protected listeners = new Set<Listener>();
+  protected location: BackofficeLocation;
+
+  constructor(initialLocation: BackofficeLocation) {
+    this.location = initialLocation;
+  }
+
+  abstract navigate(path: string): void;
+  abstract replace(path: string): void;
+  abstract back(): void;
+
+  getLocation = (): BackofficeLocation => this.location;
+
+  subscribe = (listener: Listener): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  protected setLocationInternal(next: BackofficeLocation): void {
+    if (next.path === this.location.path && next.params === this.location.params) return;
+    this.location = next;
+    for (const listener of this.listeners) listener();
+  }
+}
+
+/**
+ * In-memory navigator — a self-contained history stack for tests, stories,
+ * and hosts with no routing runtime (e.g. a modal embedding of a single
+ * backoffice surface).
+ */
+export class MemoryNavigator extends SubscribableNavigator {
+  private stack: BackofficeLocation[];
+
+  constructor(initialPath = "/backoffice") {
+    const initial = parseBackofficeHref(initialPath);
+    super(initial);
+    this.stack = [initial];
+  }
+
+  /** History entries, oldest first (test introspection). */
+  get entries(): readonly BackofficeLocation[] {
+    return this.stack;
+  }
+
+  navigate = (path: string): void => {
+    const next = parseBackofficeHref(path);
+    this.stack.push(next);
+    this.setLocationInternal(next);
+  };
+
+  replace = (path: string): void => {
+    const next = parseBackofficeHref(path);
+    this.stack[this.stack.length - 1] = next;
+    this.setLocationInternal(next);
+  };
+
+  back = (): void => {
+    if (this.stack.length <= 1) return;
+    this.stack.pop();
+    const top = this.stack[this.stack.length - 1];
+    if (top) this.setLocationInternal(top);
+  };
+}
+
+export function createMemoryNavigator(initialPath = "/backoffice"): MemoryNavigator {
+  return new MemoryNavigator(initialPath);
+}
+
+export interface ControlledNavigatorHandlers {
+  navigate(path: string): void;
+  replace(path: string): void;
+  back(): void;
+}
+
+/**
+ * Bridge navigator for adapters over an external router: navigation calls
+ * forward to the host handlers, and the host mirrors its location back via
+ * {@link ControlledNavigator.setLocation}. The one-adapter is ~20 lines over
+ * this class; a react-router or seam adapter looks the same.
+ */
+export class ControlledNavigator extends SubscribableNavigator {
+  private handlers: ControlledNavigatorHandlers;
+
+  constructor(handlers: ControlledNavigatorHandlers, initialLocation?: BackofficeLocation) {
+    super(initialLocation ?? { path: "/", params: {} });
+    this.handlers = handlers;
+  }
+
+  /** Swap the forwarding callbacks (adapters keep them fresh per render). */
+  setHandlers(handlers: ControlledNavigatorHandlers): void {
+    this.handlers = handlers;
+  }
+
+  /** Mirror the host router's current location into the navigator. */
+  setLocation(next: BackofficeLocation): void {
+    this.setLocationInternal(next);
+  }
+
+  navigate = (path: string): void => {
+    this.handlers.navigate(path);
+  };
+
+  replace = (path: string): void => {
+    this.handlers.replace(path);
+  };
+
+  back = (): void => {
+    this.handlers.back();
+  };
+}
+
+/**
+ * Inert navigator — the default-context fallback so package surfaces render
+ * (and stories mount) without a BackofficeProvider. Navigation is a no-op.
+ */
+export function createNoopNavigator(initialPath = "/backoffice"): BackofficeNavigator {
+  const location = parseBackofficeHref(initialPath);
+  return {
+    navigate: () => {},
+    replace: () => {},
+    back: () => {},
+    getLocation: () => location,
+    subscribe: () => () => {},
+  };
+}