@multiplatform.one/backoffice 6.3.0

package/src/config/BackofficeProvider.spec.tsx

@@ -0,0 +1,126 @@
+import React from "react";
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { createMemoryNavigator } from "../navigation/navigator";
+import { BackofficeShell } from "../shell/BackofficeShell";
+import { BackofficeProvider, type BackofficeProviderProps } from "./BackofficeProvider";
+
+const MOCK_HOST = "https://backoffice-package.mock.test";
+
+const makeFixtures = () =>
+  new InMemoryFixtureProvider({
+    Workspace: [
+      {
+        name: "Tools",
+        doctype: "Workspace",
+        title: "Tools",
+        icon: "tool",
+        parent_page: "",
+        public: 1,
+        for_user: "",
+        sequence_id: 1,
+        module: "Automation",
+        is_hidden: 0,
+      },
+    ],
+    DocType: [{ name: "ToDo", doctype: "DocType" }],
+    "Notification Log": [],
+  });
+
+function renderShell(props: Partial<BackofficeProviderProps> = {}) {
+  const navigation = props.navigation ?? createMemoryNavigator("/backoffice");
+  return {
+    navigation,
+    ...renderWithProviders(
+      <BackofficeProvider
+        frappe={{ baseURL: MOCK_HOST, fixtures: makeFixtures() }}
+        navigation={navigation}
+        {...props}
+      >
+        <BackofficeShell>
+          <div>page body</div>
+        </BackofficeShell>
+      </BackofficeProvider>,
+    ),
+  };
+}
+
+describe("BackofficeProvider capability flags", () => {
+  it("renders the full chrome by default", () => {
+    const { container } = renderShell();
+
+    expect(screen.getByTestId("backoffice-shell")).toBeTruthy();
+    expect(screen.getByTestId("backoffice-awesomebar")).toBeTruthy();
+    expect(screen.getByTestId("backoffice-notifications-button")).toBeTruthy();
+    expect(screen.getByTestId("backoffice-help-trigger")).toBeTruthy();
+    expect(container.querySelector('[aria-label="User menu"]')).toBeTruthy();
+    expect(screen.getByTestId("backoffice-sidebar-rail")).toBeTruthy();
+    expect(screen.getByText("page body")).toBeTruthy();
+  });
+
+  it("boolean flags gate each piece of chrome", () => {
+    const { container } = renderShell({
+      capabilities: {
+        awesomebar: false,
+        notifications: false,
+        userMenu: false,
+        help: false,
+        sidebar: false,
+      },
+    });
+
+    expect(screen.queryByTestId("backoffice-awesomebar")).toBeNull();
+    expect(screen.queryByTestId("backoffice-notifications-button")).toBeNull();
+    expect(screen.queryByTestId("backoffice-help-trigger")).toBeNull();
+    expect(container.querySelector('[aria-label="User menu"]')).toBeNull();
+    expect(screen.queryByTestId("backoffice-sidebar-rail")).toBeNull();
+    // Content always renders — flags remove chrome, not the page.
+    expect(screen.getByText("page body")).toBeTruthy();
+  });
+
+  it("object flags resolve enabled + per-feature config", () => {
+    renderShell({
+      capabilities: { notifications: { enabled: false }, awesomebar: { enabled: true } },
+    });
+
+    expect(screen.queryByTestId("backoffice-notifications-button")).toBeNull();
+    expect(screen.getByTestId("backoffice-awesomebar")).toBeTruthy();
+  });
+
+  it("renders host slots (sidebar footer)", () => {
+    renderShell({
+      slots: { renderSidebarFooter: () => <div data-testid="host-sidebar-footer">custom</div> },
+    });
+
+    expect(screen.getByTestId("host-sidebar-footer")).toBeTruthy();
+  });
+});
+
+describe("BackofficeProvider navigation", () => {
+  it("shell home button navigates through the adapter and emits an event", () => {
+    const onEvent = vi.fn();
+    const { navigation } = renderShell({ onEvent });
+
+    fireEvent.click(screen.getByTestId("backoffice-home"));
+
+    expect(navigation.getLocation().path).toBe("/backoffice");
+    expect(onEvent).toHaveBeenCalledWith({
+      type: "navigate",
+      path: "/backoffice",
+      mode: "push",
+    });
+  });
+
+  it("basePath rebinds every path the chrome navigates to", () => {
+    const onEvent = vi.fn();
+    const navigation = createMemoryNavigator("/admin");
+    renderShell({ navigation, basePath: "/admin", onEvent });
+
+    fireEvent.click(screen.getByTestId("backoffice-home"));
+
+    expect(onEvent).toHaveBeenCalledWith({ type: "navigate", path: "/admin", mode: "push" });
+    expect(navigation.getLocation().path).toBe("/admin");
+  });
+});

package/src/config/BackofficeProvider.tsx

@@ -0,0 +1,315 @@
+/**
+ * BackofficeProvider — the single configuration surface for embedding the
+ * backoffice in a host app.
+ *
+ * It composes @multiplatform.one/frappe-ui's FrappeProvider internally (the
+ * `frappe` prop), publishes the navigation seam + capability flags + slots +
+ * event bus through BackofficeConfigContext (consumed by every backoffice
+ * surface), registers the package's "backoffice" i18n namespace, and applies
+ * host field-registry overrides.
+ *
+ * Surfaces render without a provider too (stories/tests): the context
+ * default is a fully-enabled config with an inert navigator.
+ */
+import {
+  FrappeProvider,
+  registerField,
+  type FieldRenderProps,
+  type FrappeProviderProps,
+} from "@multiplatform.one/frappe-ui";
+import type { i18n as I18nInstance } from "i18next";
+import type { ComponentType, ReactNode } from "react";
+import React, { createContext, useContext, useMemo, useRef, useState } from "react";
+import { useSyncExternalStore } from "react";
+import { registerBackofficeTranslations } from "../i18n";
+import {
+  createNoopNavigator,
+  type BackofficeLocation,
+  type BackofficeNavigator,
+} from "../navigation/navigator";
+import { BACKOFFICE_BASE, createBackofficePaths, type BackofficePaths } from "../navigation/paths";
+import {
+  isDoctypeAllowed,
+  resolveCapabilities,
+  type BackofficeCapabilities,
+  type BackofficeDoctypeScope,
+  type ResolvedBackofficeCapabilities,
+} from "./capabilities";
+import type { BackofficeEvent, BackofficeEventHandler } from "./events";
+import type { BackofficeSlots } from "./slots";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Frappe connection config — fed into frappe-ui's FrappeProvider. */
+export interface BackofficeFrappeConfig {
+  /** Base URL of the Frappe server, e.g. "https://mysite.frappe.cloud". */
+  baseURL: string;
+  /** Override port for the Socket.IO realtime connection (e.g. 9000 in dev). */
+  socketPort?: number;
+  /** Authentication configuration (token auth for cross-origin/native hosts). */
+  auth?: FrappeProviderProps["auth"];
+  /** Sync options for the live data engine (persistKey, cdcInterval, …). */
+  syncOptions?: FrappeProviderProps["syncOptions"];
+  /** Extra Socket.IO client options for the realtime connection. */
+  socketOptions?: FrappeProviderProps["socketOptions"];
+  /** Fixture provider (stories/tests — no network). */
+  fixtures?: FrappeProviderProps["fixtures"];
+}
+
+/** Host color-scheme adapter (drives the user menu's "Toggle Theme"). */
+export interface BackofficeAppearance {
+  /** Current scheme value. */
+  scheme: "light" | "dark" | "system" | (string & {});
+  /** Set the scheme. */
+  setScheme: (scheme: "light" | "dark" | "system") => void;
+}
+
+/** Host-injected custom action (form toolbars, list toolbars). */
+export interface BackofficeActionContext {
+  doctype: string;
+  /** Document name (form actions; undefined for unsaved docs). */
+  name?: string;
+  /** Selected row names (list bulk actions). */
+  selection?: readonly string[];
+}
+
+export interface BackofficeAction {
+  id: string;
+  label: string;
+  onPress: (context: BackofficeActionContext) => void;
+}
+
+export interface BackofficeActions {
+  /** Extra actions on the document form toolbar. */
+  form?: readonly BackofficeAction[];
+  /** Extra actions on the list toolbar / bulk-actions bar. */
+  list?: readonly BackofficeAction[];
+}
+
+export interface BackofficeProviderProps {
+  children: ReactNode;
+  /** Frappe connection — feeds FrappeProvider internally. */
+  frappe: BackofficeFrappeConfig;
+  /**
+   * Navigation adapter. Use `useOneNavigator()` from
+   * `@multiplatform.one/backoffice/one-adapter` in One apps,
+   * `createMemoryNavigator()` in tests/stories, or bridge your own router
+   * with `ControlledNavigator`.
+   */
+  navigation: BackofficeNavigator;
+  /** URL prefix the backoffice is mounted under. Default "/backoffice". */
+  basePath?: string;
+  /** Feature visibility/behavior flags. Everything defaults ON. */
+  capabilities?: BackofficeCapabilities;
+  /** Restrict which doctypes are reachable (awesomebar, lists, links). */
+  doctypes?: BackofficeDoctypeScope;
+  /**
+   * Field-renderer overrides merged into frappe-ui's field registry
+   * (fieldtype → component), e.g. `{ Rating: MyRating }`.
+   */
+  fields?: Record<string, ComponentType<FieldRenderProps>>;
+  /** Host-injected custom actions (form/list toolbars). */
+  actions?: BackofficeActions;
+  /** Render-prop slots replacing built-in chrome. */
+  slots?: BackofficeSlots;
+  /** Color-scheme adapter for the user menu's "Toggle Theme". */
+  appearance?: BackofficeAppearance;
+  /** Event bus — every notable backoffice action lands here. */
+  onEvent?: BackofficeEventHandler;
+  /**
+   * i18next instance to register the "backoffice" namespace on (defaults to
+   * the global singleton).
+   */
+  i18nInstance?: I18nInstance;
+}
+
+/** Resolved config every backoffice surface consumes. */
+export interface BackofficeConfig {
+  frappe?: BackofficeFrappeConfig;
+  navigation: BackofficeNavigator;
+  basePath: string;
+  paths: BackofficePaths;
+  capabilities: ResolvedBackofficeCapabilities;
+  doctypes?: BackofficeDoctypeScope;
+  actions: BackofficeActions;
+  slots: BackofficeSlots;
+  appearance?: BackofficeAppearance;
+  /** Emit an event to the host's `onEvent` bus (no-op when unset). */
+  emitEvent: (event: BackofficeEvent) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONFIG: BackofficeConfig = {
+  navigation: createNoopNavigator(BACKOFFICE_BASE),
+  basePath: BACKOFFICE_BASE,
+  paths: createBackofficePaths(BACKOFFICE_BASE),
+  capabilities: resolveCapabilities(),
+  actions: {},
+  slots: {},
+  emitEvent: () => {},
+};
+
+const BackofficeConfigContext = createContext<BackofficeConfig>(DEFAULT_CONFIG);
+
+/**
+ * The resolved backoffice config. Outside a BackofficeProvider this returns
+ * a fully-enabled default config with an inert navigator, so surfaces stay
+ * mountable in isolation (stories, tests).
+ */
+export function useBackofficeConfig(): BackofficeConfig {
+  return useContext(BackofficeConfigContext);
+}
+
+export function useBackofficeCapabilities(): ResolvedBackofficeCapabilities {
+  return useBackofficeConfig().capabilities;
+}
+
+export function useBackofficeNavigator(): BackofficeNavigator {
+  return useBackofficeConfig().navigation;
+}
+
+export function useBackofficePaths(): BackofficePaths {
+  return useBackofficeConfig().paths;
+}
+
+export function useBackofficeSlots(): BackofficeSlots {
+  return useBackofficeConfig().slots;
+}
+
+/** Current location from the navigation adapter (subscription-backed). */
+export function useBackofficeLocation(): BackofficeLocation {
+  const navigator = useBackofficeNavigator();
+  return useSyncExternalStore(navigator.subscribe, navigator.getLocation, navigator.getLocation);
+}
+
+/** Is `doctype` reachable under the provider's doctype scope? */
+export function useIsDoctypeAllowed(): (doctype: string) => boolean {
+  const { doctypes } = useBackofficeConfig();
+  return useMemo(() => (doctype: string) => isDoctypeAllowed(doctypes, doctype), [doctypes]);
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export function BackofficeProvider({
+  children,
+  frappe,
+  navigation,
+  basePath = BACKOFFICE_BASE,
+  capabilities,
+  doctypes,
+  fields,
+  actions,
+  slots,
+  appearance,
+  onEvent,
+  i18nInstance,
+}: BackofficeProviderProps) {
+  // Register the "backoffice" i18n namespace BEFORE children first render,
+  // so useTranslation("backoffice") is ready on the first pass (idempotent).
+  useState(() => {
+    registerBackofficeTranslations(i18nInstance);
+    return true;
+  });
+
+  // Host field-registry overrides — applied during render (frappe-ui's
+  // registry is module-global) so first-pass field rendering sees them.
+  const appliedFields = useRef<Record<string, ComponentType<FieldRenderProps>>>({});
+  if (fields) {
+    for (const [fieldtype, component] of Object.entries(fields)) {
+      if (appliedFields.current[fieldtype] !== component) {
+        registerField(fieldtype, component);
+        appliedFields.current[fieldtype] = component;
+      }
+    }
+  }
+
+  // Keep the handler on a ref so the wrapped navigator's identity survives
+  // inline `onEvent` props.
+  const onEventRef = useRef<BackofficeEventHandler | undefined>(onEvent);
+  onEventRef.current = onEvent;
+
+  const emitEvent = useMemo(
+    () => (event: BackofficeEvent) => {
+      onEventRef.current?.(event);
+    },
+    [],
+  );
+
+  // Wrap the host navigator so every navigation the backoffice performs
+  // lands on the event bus.
+  const wrappedNavigation = useMemo<BackofficeNavigator>(
+    () => ({
+      navigate: (path) => {
+        emitEvent({ type: "navigate", path, mode: "push" });
+        navigation.navigate(path);
+      },
+      replace: (path) => {
+        emitEvent({ type: "navigate", path, mode: "replace" });
+        navigation.replace(path);
+      },
+      back: () => {
+        emitEvent({
+          type: "navigate",
+          path: navigation.getLocation().path,
+          mode: "back",
+        });
+        navigation.back();
+      },
+      getLocation: () => navigation.getLocation(),
+      subscribe: (listener) => navigation.subscribe(listener),
+    }),
+    [navigation, emitEvent],
+  );
+
+  const paths = useMemo(() => createBackofficePaths(basePath), [basePath]);
+  const resolvedCapabilities = useMemo(() => resolveCapabilities(capabilities), [capabilities]);
+
+  const config = useMemo<BackofficeConfig>(
+    () => ({
+      frappe,
+      navigation: wrappedNavigation,
+      basePath,
+      paths,
+      capabilities: resolvedCapabilities,
+      doctypes,
+      actions: actions ?? {},
+      slots: slots ?? {},
+      appearance,
+      emitEvent,
+    }),
+    [
+      frappe,
+      wrappedNavigation,
+      basePath,
+      paths,
+      resolvedCapabilities,
+      doctypes,
+      actions,
+      slots,
+      appearance,
+      emitEvent,
+    ],
+  );
+
+  return (
+    <BackofficeConfigContext.Provider value={config}>
+      <FrappeProvider
+        baseURL={frappe.baseURL}
+        socketPort={frappe.socketPort}
+        auth={frappe.auth}
+        syncOptions={frappe.syncOptions}
+        socketOptions={frappe.socketOptions}
+        fixtures={frappe.fixtures}
+      >
+        {children}
+      </FrappeProvider>
+    </BackofficeConfigContext.Provider>
+  );
+}

package/src/config/capabilities.ts

@@ -0,0 +1,172 @@
+/**
+ * Backoffice capability flags — the host's on/off (and per-feature config)
+ * switches for what the embedded backoffice displays and allows.
+ *
+ * Every flag accepts either a boolean or a config object; everything
+ * defaults ON so `<BackofficeProvider>` with no `capabilities` prop renders
+ * the full desk. Resolution happens once in the provider; surfaces read the
+ * resolved shape via `useBackofficeCapabilities()`.
+ */
+
+import { BACKOFFICE_VIEWS, type BackofficeView } from "../navigation/paths";
+
+/** Boolean shorthand or per-feature config object. */
+export type CapabilityInput<Config extends object = { enabled?: boolean }> =
+  | boolean
+  | (Config & { enabled?: boolean })
+  | undefined;
+
+export interface BackofficeCapabilities {
+  /** Global search / command bar in the shell navbar. */
+  awesomebar?: CapabilityInput;
+  /** Notification bell + panel in the shell navbar. */
+  notifications?: CapabilityInput;
+  /** Avatar menu (profile, theme toggle, logout) in the shell navbar. */
+  userMenu?: CapabilityInput<{
+    /** Show the "Toggle Theme" item (needs an `appearance` adapter too). */
+    themeToggle?: boolean;
+    /** Show the "Log Out" item. */
+    logout?: boolean;
+    /**
+     * "Exit to site" escape hatch back into the host app (web only).
+     * `path` is host-app absolute (default "/"); `label` overrides the
+     * translated default.
+     */
+    exitToSite?: boolean | { enabled?: boolean; path?: string; label?: string };
+  }>;
+  /** Help menu (docs links, shortcuts + about dialogs) in the shell navbar. */
+  help?: CapabilityInput;
+  /** Workspace sidebar (desktop rail + narrow drawer). */
+  sidebar?: CapabilityInput;
+  /** Quick-entry dialogs (compact create forms). */
+  quickEntry?: CapabilityInput;
+  /** List views. `allow` restricts which views are reachable. */
+  views?: CapabilityInput<{ allow?: readonly BackofficeView[] }>;
+  /** "New <doctype>" affordances (list header, awesomebar new-commands, …). */
+  newDoc?: CapabilityInput;
+  /** List bulk-action bar (multi-select edit/assign/tag/delete). */
+  bulkActions?: CapabilityInput;
+  /** Form sidebar attachments section. */
+  attachments?: CapabilityInput;
+  /** Form activity timeline (comments, versions, communications). */
+  timeline?: CapabilityInput;
+  /** Assignment (ToDo) surfaces on forms and lists. */
+  assignments?: CapabilityInput;
+  /** Tag surfaces on forms and lists. */
+  tags?: CapabilityInput;
+  /** Document share surfaces. */
+  shares?: CapabilityInput;
+  /** Print affordances. */
+  print?: CapabilityInput;
+  /** Email / communication affordances. */
+  email?: CapabilityInput;
+}
+
+export interface ResolvedCapability {
+  enabled: boolean;
+}
+
+export interface ResolvedExitToSite {
+  enabled: boolean;
+  path: string;
+  label?: string;
+}
+
+export interface ResolvedBackofficeCapabilities {
+  awesomebar: ResolvedCapability;
+  notifications: ResolvedCapability;
+  userMenu: ResolvedCapability & {
+    themeToggle: boolean;
+    logout: boolean;
+    exitToSite: ResolvedExitToSite;
+  };
+  help: ResolvedCapability;
+  sidebar: ResolvedCapability;
+  quickEntry: ResolvedCapability;
+  views: ResolvedCapability & { allow: readonly BackofficeView[] };
+  newDoc: ResolvedCapability;
+  bulkActions: ResolvedCapability;
+  attachments: ResolvedCapability;
+  timeline: ResolvedCapability;
+  assignments: ResolvedCapability;
+  tags: ResolvedCapability;
+  shares: ResolvedCapability;
+  print: ResolvedCapability;
+  email: ResolvedCapability;
+}
+
+function resolveFlag<Resolved extends { enabled: boolean }>(
+  input: boolean | (Partial<Resolved> & { enabled?: boolean }) | undefined,
+  defaults: Resolved,
+): Resolved {
+  if (input === undefined) return defaults;
+  if (typeof input === "boolean") return { ...defaults, enabled: input };
+  // Undefined config values must not clobber defaults (exactOptionalPropertyTypes).
+  const merged: Record<string, unknown> = { ...defaults };
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) merged[key] = value;
+  }
+  merged.enabled = input.enabled ?? true;
+  return merged as Resolved;
+}
+
+function resolveExitToSite(
+  input: boolean | { enabled?: boolean; path?: string; label?: string } | undefined,
+): ResolvedExitToSite {
+  if (input === undefined) return { enabled: true, path: "/" };
+  if (typeof input === "boolean") return { enabled: input, path: "/" };
+  const resolved: ResolvedExitToSite = { enabled: input.enabled ?? true, path: input.path ?? "/" };
+  if (input.label !== undefined) resolved.label = input.label;
+  return resolved;
+}
+
+export function resolveCapabilities(
+  input: BackofficeCapabilities = {},
+): ResolvedBackofficeCapabilities {
+  const userMenuInput = typeof input.userMenu === "object" ? input.userMenu : undefined;
+  return {
+    awesomebar: resolveFlag<ResolvedCapability>(input.awesomebar, { enabled: true }),
+    notifications: resolveFlag<ResolvedCapability>(input.notifications, { enabled: true }),
+    userMenu: {
+      enabled:
+        typeof input.userMenu === "boolean" ? input.userMenu : (userMenuInput?.enabled ?? true),
+      themeToggle: userMenuInput?.themeToggle ?? true,
+      logout: userMenuInput?.logout ?? true,
+      exitToSite: resolveExitToSite(userMenuInput?.exitToSite),
+    },
+    help: resolveFlag<ResolvedCapability>(input.help, { enabled: true }),
+    sidebar: resolveFlag<ResolvedCapability>(input.sidebar, { enabled: true }),
+    quickEntry: resolveFlag<ResolvedCapability>(input.quickEntry, { enabled: true }),
+    views: resolveFlag<ResolvedBackofficeCapabilities["views"]>(input.views, {
+      enabled: true,
+      allow: BACKOFFICE_VIEWS,
+    }),
+    newDoc: resolveFlag<ResolvedCapability>(input.newDoc, { enabled: true }),
+    bulkActions: resolveFlag<ResolvedCapability>(input.bulkActions, { enabled: true }),
+    attachments: resolveFlag<ResolvedCapability>(input.attachments, { enabled: true }),
+    timeline: resolveFlag<ResolvedCapability>(input.timeline, { enabled: true }),
+    assignments: resolveFlag<ResolvedCapability>(input.assignments, { enabled: true }),
+    tags: resolveFlag<ResolvedCapability>(input.tags, { enabled: true }),
+    shares: resolveFlag<ResolvedCapability>(input.shares, { enabled: true }),
+    print: resolveFlag<ResolvedCapability>(input.print, { enabled: true }),
+    email: resolveFlag<ResolvedCapability>(input.email, { enabled: true }),
+  };
+}
+
+/** Doctype reachability scope (allow wins over deny being absent; deny always wins). */
+export interface BackofficeDoctypeScope {
+  /** When set, only these doctypes are reachable. */
+  allow?: readonly string[];
+  /** Always-unreachable doctypes (applied after `allow`). */
+  deny?: readonly string[];
+}
+
+export function isDoctypeAllowed(
+  scope: BackofficeDoctypeScope | undefined,
+  doctype: string,
+): boolean {
+  if (!scope) return true;
+  if (scope.deny?.includes(doctype)) return false;
+  if (scope.allow && !scope.allow.includes(doctype)) return false;
+  return true;
+}

package/src/config/events.ts

@@ -0,0 +1,19 @@
+/**
+ * Host event bus — `onEvent` on the provider receives every notable thing
+ * the embedded backoffice does, so host apps can sync their own chrome,
+ * analytics, or state.
+ */
+
+export type BackofficeEvent =
+  /** Any navigation performed through the backoffice navigator. */
+  | { type: "navigate"; path: string; mode: "push" | "replace" | "back" }
+  /** A document form was opened. */
+  | { type: "doc-opened"; doctype: string; name: string }
+  /** A document was saved (`isNew` for first inserts). */
+  | { type: "doc-saved"; doctype: string; name: string; isNew?: boolean }
+  /** A document was deleted. */
+  | { type: "doc-deleted"; doctype: string; name: string }
+  /** A surface caught an operational error worth surfacing to the host. */
+  | { type: "error"; error: unknown; context?: string };
+
+export type BackofficeEventHandler = (event: BackofficeEvent) => void;

package/src/config/slots.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+
+/**
+ * Host render-prop slots — the highest-leverage replacement points. Slots
+ * are provider-level (they apply everywhere the surface renders); when a
+ * slot is undefined the built-in rendering is used.
+ */
+export interface BackofficeSlots {
+  /**
+   * Replace the shell navbar CONTENT (inside the styled banner bar).
+   * `defaultContent` is the built-in navbar row (home button, awesomebar,
+   * bell/help/user chrome) so hosts can wrap instead of rebuild.
+   */
+  renderShellHeader?: (context: { defaultContent: ReactNode }) => ReactNode;
+  /** Rendered at the bottom of the workspace sidebar (rail and drawer). */
+  renderSidebarFooter?: () => ReactNode;
+  /** Replace the list screen's empty state. (Consumed by the list surface.) */
+  renderListEmpty?: (context: { doctype: string }) => ReactNode;
+  /**
+   * Replace the document form header row. (Consumed by the form surface.)
+   * `name` is undefined for new (unsaved) documents.
+   */
+  renderFormHeader?: (context: {
+    doctype: string;
+    name?: string;
+    defaultContent: ReactNode;
+  }) => ReactNode;
+}