@ethisyscore/plugin-ui 1.23.0 → 1.25.0

package/dist/components/layout/index.d.cts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
 
 /**
  * Static Tailwind basis classes for {@link FillGridItem}.
@@ -45,4 +46,292 @@ interface FillGridItemProps {
 }
 declare function FillGridItem({ span, className, children }: FillGridItemProps): react.JSX.Element;
 
-export { type FillGap, FillGrid, FillGridItem, type FillSpan, type Twelfths };
+/**
+ * `@ethisyscore/plugin-ui/components/layout` — page-header contracts.
+ *
+ * Promoted from the monolith's `src/components/layout/types.ts` +
+ * `src/hooks/menu/menuConfig.ts` so every plugin shares ONE header layer instead
+ * of copying `PageHeader` + `usePageHeader` + these types per plugin. The shapes
+ * are the subset the header machinery actually reads — decoupled from the
+ * monolith's shell-only `SubMenuProps`/`MenuActionConfig`, which drag in RBAC,
+ * notification, and layout state a plugin never has.
+ */
+/**
+ * Header-placement hint for an action.
+ *
+ * - "primary"      surfaces as the page-header primary CTA.
+ * - "secondary"    surfaces as the page-header secondary dropdown (at most one per page).
+ * - "overflow"     surfaces in the page-header ⋯ More menu.
+ * - "sidebar-only" not header-visible (default).
+ */
+type ActionSlot = "primary" | "secondary" | "overflow" | "sidebar-only";
+/**
+ * Visual variant of a header action. `"danger"` renders the destructive style;
+ * `"primary"`/`"secondary"` are sidebar-pill hints.
+ */
+type HeaderActionVariant = "primary" | "secondary" | "danger";
+/**
+ * Header-facing descriptor of an action. Built by `usePageHeader` from a menu
+ * item / detail context; consumed by `PageHeader`.
+ */
+interface ActionDescriptor {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Anchor href. Mutually exclusive with `onClick`. */
+    href?: string;
+    /** Imperative click handler. Mutually exclusive with `href`. */
+    onClick?: () => void;
+    /** Render with danger style (Delete / Cancel). */
+    danger?: boolean;
+    /** Secondary-slot dropdown children (Lifecycle ▾ etc.). */
+    children?: ActionDescriptor[];
+    /** Optional disabled state (e.g. Lifecycle option not legal in current state). */
+    disabled?: boolean;
+    /** Optional tooltip / aria-label for icon-only buttons. */
+    description?: ReactNode;
+}
+/**
+ * A raw header source action, as authored in a plugin's menu config or supplied
+ * by a detail context. The union superset of the monolith's `MenuActionConfig`
+ * and `SidebarDetailContextNavItem` — only the fields the header reads.
+ */
+interface HeaderAction {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Navigates when clicked. Mutually exclusive with `actionId`/`onClick`. */
+    href?: string;
+    /** Dispatches via the sidebar-action channel instead of navigating. */
+    actionId?: string;
+    /** Explicit click handler (detail-context actions can carry one directly). */
+    onClick?: () => void;
+    /** Visual variant — see {@link HeaderActionVariant}. */
+    variant?: HeaderActionVariant;
+    /** Page-header placement. Defaults to `"sidebar-only"` (not header-visible). */
+    slot?: ActionSlot;
+    disabled?: boolean;
+    /** Secondary-slot dropdown children. */
+    children?: HeaderAction[];
+}
+/**
+ * A menu item the `PageHeaderProvider` matches against the current route. When
+ * the active route is this item's `href`, its `actions` feed the header. Plugins
+ * author these as a faithful slice of the monolith's `menuConfig.ts`.
+ */
+interface HeaderMenuItem {
+    id: string;
+    label: string;
+    href?: string;
+    group?: string;
+    actions?: HeaderAction[];
+    children?: HeaderMenuItem[];
+}
+/**
+ * Detail-page header context — the actions/title a detail or edit page surfaces
+ * without a menu item of its own. A page hook publishes this (or, more commonly,
+ * spreads its own `headerProps`); parity with the monolith's `detailContext`.
+ */
+interface HeaderDetailContext {
+    title?: string;
+    actions?: HeaderAction[];
+}
+/** One node in the header breadcrumb trail (`Home / Finance / <page>`). */
+interface Breadcrumb {
+    label: string;
+    /** Navigates when clicked; omit for the current (leaf) crumb. */
+    href?: string;
+}
+/**
+ * Breadcrumb metadata for one route — a faithful shift of the monolith's
+ * `routeMeta.ts` entry: a full path `pattern` (`:`-segments are params) with a
+ * `label` and the `parent` route's `pattern`. `buildBreadcrumbs` matches the
+ * current path against the patterns (most-specific wins), walks the `parent`
+ * chain, prepends Home, and resolves each ancestor's pattern with the captured
+ * params — identical to the monolith's breadcrumb builder.
+ *
+ * `pageId` is the one plugin-only addition (the monolith has no page-bundle ids):
+ * it links a pattern to its platform-react page so the manifest generator can emit
+ * the page's `route`. The SDK breadcrumb builder ignores it.
+ */
+interface RouteMetaEntry {
+    /** Full path pattern, e.g. `/extensions/finance/invoices/:id/edit`. */
+    pattern: string;
+    label: string;
+    /** Parent route's `pattern`; omit for a top-level route. */
+    parent?: string;
+    /** Platform-react page id this pattern maps to (plugin manifest link; SDK ignores). */
+    pageId?: string;
+}
+/** The migrated `routeMeta` slice — a flat array, same shape as the monolith. */
+type RouteMeta = RouteMetaEntry[];
+/**
+ * What `PageHeaderContext` publishes — the subset of the monolith's `SubMenuProps`
+ * that `usePageHeader` reads. `null` when no provider is mounted (a page rendered
+ * standalone, e.g. a test) → the hook derives empty header props.
+ */
+interface PageHeaderState {
+    activeMenuItem?: HeaderMenuItem | null;
+    detailContext?: HeaderDetailContext | null;
+    title?: string;
+    subtitle?: ReactNode;
+    /** Root breadcrumb trail (e.g. `Home / Finance`); `PageHeader` appends the title. */
+    breadcrumbs?: Breadcrumb[];
+}
+/** The prop bundle `usePageHeader` returns, ready to spread onto `<PageHeader>`. */
+interface PageHeaderDerivedProps {
+    title: string;
+    subtitle?: ReactNode;
+    primaryAction?: ActionDescriptor;
+    secondaryAction?: ActionDescriptor;
+    overflowActions?: ActionDescriptor[];
+    /** Root breadcrumb trail; `PageHeader` appends the current `title` as the leaf. */
+    breadcrumbs?: Breadcrumb[];
+}
+
+/**
+ * `@ethisyscore/plugin-ui/components/layout` — the page-header, promoted from the
+ * monolith so plugins share one component instead of copying it. In a plugin this
+ * IS the page header: the host suppresses its own chrome for platform-react
+ * surfaces, so this renders the breadcrumb trail, the title, and the CTAs.
+ *
+ * `breadcrumbs` is the ROOT trail (e.g. `Home / Finance`); the current `title` is
+ * appended as the non-link leaf crumb. MUI primitives come from the sibling
+ * `../ui` barrel (host externals, never bundled); `Link` is react-router's so
+ * links keep middle-click / open-in-new-tab / a11y.
+ */
+interface PageHeaderProps {
+    title: string;
+    subtitle?: ReactNode;
+    primaryAction?: ActionDescriptor;
+    secondaryAction?: ActionDescriptor;
+    overflowActions?: ActionDescriptor[];
+    /** Root breadcrumb trail; the `title` is appended as the current-page leaf. */
+    breadcrumbs?: Breadcrumb[];
+}
+declare function PageHeader({ title, subtitle, primaryAction, secondaryAction, overflowActions, breadcrumbs, }: PageHeaderProps): react.JSX.Element;
+
+/**
+ * Derives `<PageHeader>` props from the active menu item or detail context —
+ * promoted verbatim from the monolith's `usePageHeader`, reading the plugin's
+ * `PageHeaderContext` instead of the shell's `SubMenuPropsContext`.
+ *
+ * Outside a mounted `PageHeaderProvider` (or in a test rendering a page
+ * standalone) the context is `null` and the hook derives empty header props —
+ * same shape, no work. Page hooks spread the result and may override
+ * title/subtitle/actions.
+ */
+declare function usePageHeader(): PageHeaderDerivedProps;
+
+/**
+ * Builds the `Home / … / <page>` breadcrumb trail — a faithful port of the
+ * monolith's `buildBreadcrumbs`. Matches the current path against the `routeMeta`
+ * patterns (most-specific wins), walks the `parent` chain, prepends Home, and maps
+ * each ancestor to its resolved-pattern href (the current page gets no href). The
+ * app/module crumb (e.g. "Finance") is just the top-level `routeMeta` entry — no
+ * separate config, exactly like the monolith's `/finance` root entry.
+ */
+declare function buildBreadcrumbs(pathname: string, routeMeta: RouteMeta): Breadcrumb[];
+
+interface PageHeaderProviderProps {
+    /**
+     * The plugin's menu-item config — a faithful slice of the monolith's
+     * `menuConfig.ts`. The provider matches the active route against each item's
+     * `href` (pre-order, so a parent list item wins over its own overview child)
+     * and publishes the match so `usePageHeader` can surface its `actions`.
+     */
+    config: HeaderMenuItem[];
+    /**
+     * The plugin's breadcrumb metadata — a faithful slice of the monolith's
+     * `routeMeta.ts` (`{ pattern, label, parent }[]`, re-rooted). The provider derives
+     * the full `Home / … / <Page>` trail per route via `buildBreadcrumbs`, exactly like
+     * the monolith. The app/module crumb (e.g. "Finance") is just its top-level entry.
+     * Omit for no breadcrumbs.
+     */
+    routeMeta?: RouteMeta;
+    /** Optional detail-context override for detail/edit routes with no menu item. */
+    detailContext?: HeaderDetailContext | null;
+    children: ReactNode;
+}
+/**
+ * Plugin analogue of the monolith shell's `SubMenuPropsContext` provider: mounted
+ * once at the plugin's router root, it resolves the active menu item from the
+ * current route (feeding `usePageHeader`'s title + CTAs) and derives the breadcrumb
+ * trail from `routeMeta`. Also mounts the `SidebarActionProvider` so `actionId`
+ * header CTAs can dispatch to page-registered handlers.
+ *
+ * In a plugin this feeds the in-body `PageHeader` that migrated pages render —
+ * which IS the surface header (the host suppresses its own chrome for
+ * platform-react surfaces).
+ */
+declare function PageHeaderProvider({ config, routeMeta, detailContext, children, }: PageHeaderProviderProps): react.JSX.Element;
+/**
+ * Ready-made page wrapper for the PlatformReact page-definer's `wrapPage` option:
+ * `withPageHeader(config, routeMeta, app)` returns
+ * `(page) => <PageHeaderProvider …>{page}</>`.
+ *
+ * Kept here — the same module as `PageHeaderProvider` and `usePageHeader` — on
+ * purpose: the provider and the hook must resolve to ONE `PageHeaderContext`
+ * instance, which only holds when both come from this `components/layout` entry.
+ * (A bundler inlines a separate context copy into each entry, so wrapping from the
+ * `platform-react` entry would give the provider a different context than the
+ * hook — the header would render empty.) A plugin passes
+ * `wrapPage: withPageHeader(<feature>MenuConfig, <feature>RouteMeta)`
+ * to `createPluginPageDefiner`.
+ */
+declare function withPageHeader(config: HeaderMenuItem[], routeMeta?: RouteMeta): (page: ReactElement) => ReactElement;
+
+/**
+ * Carries the active menu item / detail context so `usePageHeader` can derive
+ * header props. The plugin analogue of the monolith shell's
+ * `SubMenuPropsContext`: mounted once by `PageHeaderProvider`, read per page.
+ *
+ * `null` when no provider is mounted (a page rendered standalone, e.g. a test) —
+ * consumers treat `null` as "no header context" and derive empty props.
+ */
+declare const PageHeaderContext: react.Context<PageHeaderState | null>;
+/** Returns the provider-published header state, or `null` when none is mounted. */
+declare function usePageHeaderContext(): PageHeaderState | null;
+
+/**
+ * Sidebar-action dispatch channel — promoted from the monolith's
+ * `SidebarActionContext`. Header buttons carrying an `actionId` (rather than an
+ * `href`) dispatch through here; a page registers a handler via
+ * `useSidebarAction` to open its own dialog. This is what makes `actionId` CTAs
+ * ("New Supplier Invoice", "New Cost Code", …) fire when clicked.
+ */
+type ActionHandler = (actionId: string) => void;
+interface SidebarActionContextValue {
+    /** Dispatch an action to all registered page handlers. */
+    triggerAction: (actionId: string) => void;
+    /** Register a handler that receives sidebar actions. Returns an unregister function. */
+    registerHandler: (handler: ActionHandler) => () => void;
+    /** Set of actionIds whose owning UI surface (e.g. a dialog) is currently open. */
+    activeActions: ReadonlySet<string>;
+    /** Reports whether the owning UI surface for `actionId` is currently open. */
+    setActionActive: (actionId: string, isActive: boolean) => void;
+}
+declare const SidebarActionContext: react.Context<SidebarActionContextValue>;
+declare function SidebarActionProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/** Used by the header to dispatch actions to pages. */
+declare function useTriggerSidebarAction(): (actionId: string) => void;
+/** Used by pages to register a handler for sidebar actions. Auto-cleans up on unmount. */
+declare function useSidebarAction(handler: ActionHandler): void;
+/**
+ * Registers a map of sidebar-action handlers keyed by action id, dispatching the
+ * matching entry when an action fires (unknown ids are ignored). The handler map
+ * may change every render — a ref keeps the dispatcher stable so the registration
+ * doesn't churn.
+ */
+declare function useSidebarActions(handlers: Record<string, (() => void) | undefined>): void;
+/** Reads the set of dispatch-action ids whose owning UI surface is currently open. */
+declare function useActiveSidebarActions(): ReadonlySet<string>;
+/**
+ * Reports to the channel whether the owning UI surface for `actionId` is open.
+ * Pages call this from a hook scope, mirroring their dialog/drawer open state.
+ */
+declare function useReportSidebarActionActive(actionId: string, isActive: boolean): void;
+
+export { type ActionDescriptor, type ActionHandler, type ActionSlot, type Breadcrumb, type FillGap, FillGrid, FillGridItem, type FillSpan, type HeaderAction, type HeaderActionVariant, type HeaderDetailContext, type HeaderMenuItem, PageHeader, PageHeaderContext, type PageHeaderDerivedProps, type PageHeaderProps, PageHeaderProvider, type PageHeaderProviderProps, type PageHeaderState, type RouteMeta, type RouteMetaEntry, SidebarActionContext, type SidebarActionContextValue, SidebarActionProvider, type Twelfths, buildBreadcrumbs, useActiveSidebarActions, usePageHeader, usePageHeaderContext, useReportSidebarActionActive, useSidebarAction, useSidebarActions, useTriggerSidebarAction, withPageHeader };

package/dist/components/layout/index.d.ts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
 
 /**
  * Static Tailwind basis classes for {@link FillGridItem}.
@@ -45,4 +46,292 @@ interface FillGridItemProps {
 }
 declare function FillGridItem({ span, className, children }: FillGridItemProps): react.JSX.Element;
 
-export { type FillGap, FillGrid, FillGridItem, type FillSpan, type Twelfths };
+/**
+ * `@ethisyscore/plugin-ui/components/layout` — page-header contracts.
+ *
+ * Promoted from the monolith's `src/components/layout/types.ts` +
+ * `src/hooks/menu/menuConfig.ts` so every plugin shares ONE header layer instead
+ * of copying `PageHeader` + `usePageHeader` + these types per plugin. The shapes
+ * are the subset the header machinery actually reads — decoupled from the
+ * monolith's shell-only `SubMenuProps`/`MenuActionConfig`, which drag in RBAC,
+ * notification, and layout state a plugin never has.
+ */
+/**
+ * Header-placement hint for an action.
+ *
+ * - "primary"      surfaces as the page-header primary CTA.
+ * - "secondary"    surfaces as the page-header secondary dropdown (at most one per page).
+ * - "overflow"     surfaces in the page-header ⋯ More menu.
+ * - "sidebar-only" not header-visible (default).
+ */
+type ActionSlot = "primary" | "secondary" | "overflow" | "sidebar-only";
+/**
+ * Visual variant of a header action. `"danger"` renders the destructive style;
+ * `"primary"`/`"secondary"` are sidebar-pill hints.
+ */
+type HeaderActionVariant = "primary" | "secondary" | "danger";
+/**
+ * Header-facing descriptor of an action. Built by `usePageHeader` from a menu
+ * item / detail context; consumed by `PageHeader`.
+ */
+interface ActionDescriptor {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Anchor href. Mutually exclusive with `onClick`. */
+    href?: string;
+    /** Imperative click handler. Mutually exclusive with `href`. */
+    onClick?: () => void;
+    /** Render with danger style (Delete / Cancel). */
+    danger?: boolean;
+    /** Secondary-slot dropdown children (Lifecycle ▾ etc.). */
+    children?: ActionDescriptor[];
+    /** Optional disabled state (e.g. Lifecycle option not legal in current state). */
+    disabled?: boolean;
+    /** Optional tooltip / aria-label for icon-only buttons. */
+    description?: ReactNode;
+}
+/**
+ * A raw header source action, as authored in a plugin's menu config or supplied
+ * by a detail context. The union superset of the monolith's `MenuActionConfig`
+ * and `SidebarDetailContextNavItem` — only the fields the header reads.
+ */
+interface HeaderAction {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Navigates when clicked. Mutually exclusive with `actionId`/`onClick`. */
+    href?: string;
+    /** Dispatches via the sidebar-action channel instead of navigating. */
+    actionId?: string;
+    /** Explicit click handler (detail-context actions can carry one directly). */
+    onClick?: () => void;
+    /** Visual variant — see {@link HeaderActionVariant}. */
+    variant?: HeaderActionVariant;
+    /** Page-header placement. Defaults to `"sidebar-only"` (not header-visible). */
+    slot?: ActionSlot;
+    disabled?: boolean;
+    /** Secondary-slot dropdown children. */
+    children?: HeaderAction[];
+}
+/**
+ * A menu item the `PageHeaderProvider` matches against the current route. When
+ * the active route is this item's `href`, its `actions` feed the header. Plugins
+ * author these as a faithful slice of the monolith's `menuConfig.ts`.
+ */
+interface HeaderMenuItem {
+    id: string;
+    label: string;
+    href?: string;
+    group?: string;
+    actions?: HeaderAction[];
+    children?: HeaderMenuItem[];
+}
+/**
+ * Detail-page header context — the actions/title a detail or edit page surfaces
+ * without a menu item of its own. A page hook publishes this (or, more commonly,
+ * spreads its own `headerProps`); parity with the monolith's `detailContext`.
+ */
+interface HeaderDetailContext {
+    title?: string;
+    actions?: HeaderAction[];
+}
+/** One node in the header breadcrumb trail (`Home / Finance / <page>`). */
+interface Breadcrumb {
+    label: string;
+    /** Navigates when clicked; omit for the current (leaf) crumb. */
+    href?: string;
+}
+/**
+ * Breadcrumb metadata for one route — a faithful shift of the monolith's
+ * `routeMeta.ts` entry: a full path `pattern` (`:`-segments are params) with a
+ * `label` and the `parent` route's `pattern`. `buildBreadcrumbs` matches the
+ * current path against the patterns (most-specific wins), walks the `parent`
+ * chain, prepends Home, and resolves each ancestor's pattern with the captured
+ * params — identical to the monolith's breadcrumb builder.
+ *
+ * `pageId` is the one plugin-only addition (the monolith has no page-bundle ids):
+ * it links a pattern to its platform-react page so the manifest generator can emit
+ * the page's `route`. The SDK breadcrumb builder ignores it.
+ */
+interface RouteMetaEntry {
+    /** Full path pattern, e.g. `/extensions/finance/invoices/:id/edit`. */
+    pattern: string;
+    label: string;
+    /** Parent route's `pattern`; omit for a top-level route. */
+    parent?: string;
+    /** Platform-react page id this pattern maps to (plugin manifest link; SDK ignores). */
+    pageId?: string;
+}
+/** The migrated `routeMeta` slice — a flat array, same shape as the monolith. */
+type RouteMeta = RouteMetaEntry[];
+/**
+ * What `PageHeaderContext` publishes — the subset of the monolith's `SubMenuProps`
+ * that `usePageHeader` reads. `null` when no provider is mounted (a page rendered
+ * standalone, e.g. a test) → the hook derives empty header props.
+ */
+interface PageHeaderState {
+    activeMenuItem?: HeaderMenuItem | null;
+    detailContext?: HeaderDetailContext | null;
+    title?: string;
+    subtitle?: ReactNode;
+    /** Root breadcrumb trail (e.g. `Home / Finance`); `PageHeader` appends the title. */
+    breadcrumbs?: Breadcrumb[];
+}
+/** The prop bundle `usePageHeader` returns, ready to spread onto `<PageHeader>`. */
+interface PageHeaderDerivedProps {
+    title: string;
+    subtitle?: ReactNode;
+    primaryAction?: ActionDescriptor;
+    secondaryAction?: ActionDescriptor;
+    overflowActions?: ActionDescriptor[];
+    /** Root breadcrumb trail; `PageHeader` appends the current `title` as the leaf. */
+    breadcrumbs?: Breadcrumb[];
+}
+
+/**
+ * `@ethisyscore/plugin-ui/components/layout` — the page-header, promoted from the
+ * monolith so plugins share one component instead of copying it. In a plugin this
+ * IS the page header: the host suppresses its own chrome for platform-react
+ * surfaces, so this renders the breadcrumb trail, the title, and the CTAs.
+ *
+ * `breadcrumbs` is the ROOT trail (e.g. `Home / Finance`); the current `title` is
+ * appended as the non-link leaf crumb. MUI primitives come from the sibling
+ * `../ui` barrel (host externals, never bundled); `Link` is react-router's so
+ * links keep middle-click / open-in-new-tab / a11y.
+ */
+interface PageHeaderProps {
+    title: string;
+    subtitle?: ReactNode;
+    primaryAction?: ActionDescriptor;
+    secondaryAction?: ActionDescriptor;
+    overflowActions?: ActionDescriptor[];
+    /** Root breadcrumb trail; the `title` is appended as the current-page leaf. */
+    breadcrumbs?: Breadcrumb[];
+}
+declare function PageHeader({ title, subtitle, primaryAction, secondaryAction, overflowActions, breadcrumbs, }: PageHeaderProps): react.JSX.Element;
+
+/**
+ * Derives `<PageHeader>` props from the active menu item or detail context —
+ * promoted verbatim from the monolith's `usePageHeader`, reading the plugin's
+ * `PageHeaderContext` instead of the shell's `SubMenuPropsContext`.
+ *
+ * Outside a mounted `PageHeaderProvider` (or in a test rendering a page
+ * standalone) the context is `null` and the hook derives empty header props —
+ * same shape, no work. Page hooks spread the result and may override
+ * title/subtitle/actions.
+ */
+declare function usePageHeader(): PageHeaderDerivedProps;
+
+/**
+ * Builds the `Home / … / <page>` breadcrumb trail — a faithful port of the
+ * monolith's `buildBreadcrumbs`. Matches the current path against the `routeMeta`
+ * patterns (most-specific wins), walks the `parent` chain, prepends Home, and maps
+ * each ancestor to its resolved-pattern href (the current page gets no href). The
+ * app/module crumb (e.g. "Finance") is just the top-level `routeMeta` entry — no
+ * separate config, exactly like the monolith's `/finance` root entry.
+ */
+declare function buildBreadcrumbs(pathname: string, routeMeta: RouteMeta): Breadcrumb[];
+
+interface PageHeaderProviderProps {
+    /**
+     * The plugin's menu-item config — a faithful slice of the monolith's
+     * `menuConfig.ts`. The provider matches the active route against each item's
+     * `href` (pre-order, so a parent list item wins over its own overview child)
+     * and publishes the match so `usePageHeader` can surface its `actions`.
+     */
+    config: HeaderMenuItem[];
+    /**
+     * The plugin's breadcrumb metadata — a faithful slice of the monolith's
+     * `routeMeta.ts` (`{ pattern, label, parent }[]`, re-rooted). The provider derives
+     * the full `Home / … / <Page>` trail per route via `buildBreadcrumbs`, exactly like
+     * the monolith. The app/module crumb (e.g. "Finance") is just its top-level entry.
+     * Omit for no breadcrumbs.
+     */
+    routeMeta?: RouteMeta;
+    /** Optional detail-context override for detail/edit routes with no menu item. */
+    detailContext?: HeaderDetailContext | null;
+    children: ReactNode;
+}
+/**
+ * Plugin analogue of the monolith shell's `SubMenuPropsContext` provider: mounted
+ * once at the plugin's router root, it resolves the active menu item from the
+ * current route (feeding `usePageHeader`'s title + CTAs) and derives the breadcrumb
+ * trail from `routeMeta`. Also mounts the `SidebarActionProvider` so `actionId`
+ * header CTAs can dispatch to page-registered handlers.
+ *
+ * In a plugin this feeds the in-body `PageHeader` that migrated pages render —
+ * which IS the surface header (the host suppresses its own chrome for
+ * platform-react surfaces).
+ */
+declare function PageHeaderProvider({ config, routeMeta, detailContext, children, }: PageHeaderProviderProps): react.JSX.Element;
+/**
+ * Ready-made page wrapper for the PlatformReact page-definer's `wrapPage` option:
+ * `withPageHeader(config, routeMeta, app)` returns
+ * `(page) => <PageHeaderProvider …>{page}</>`.
+ *
+ * Kept here — the same module as `PageHeaderProvider` and `usePageHeader` — on
+ * purpose: the provider and the hook must resolve to ONE `PageHeaderContext`
+ * instance, which only holds when both come from this `components/layout` entry.
+ * (A bundler inlines a separate context copy into each entry, so wrapping from the
+ * `platform-react` entry would give the provider a different context than the
+ * hook — the header would render empty.) A plugin passes
+ * `wrapPage: withPageHeader(<feature>MenuConfig, <feature>RouteMeta)`
+ * to `createPluginPageDefiner`.
+ */
+declare function withPageHeader(config: HeaderMenuItem[], routeMeta?: RouteMeta): (page: ReactElement) => ReactElement;
+
+/**
+ * Carries the active menu item / detail context so `usePageHeader` can derive
+ * header props. The plugin analogue of the monolith shell's
+ * `SubMenuPropsContext`: mounted once by `PageHeaderProvider`, read per page.
+ *
+ * `null` when no provider is mounted (a page rendered standalone, e.g. a test) —
+ * consumers treat `null` as "no header context" and derive empty props.
+ */
+declare const PageHeaderContext: react.Context<PageHeaderState | null>;
+/** Returns the provider-published header state, or `null` when none is mounted. */
+declare function usePageHeaderContext(): PageHeaderState | null;
+
+/**
+ * Sidebar-action dispatch channel — promoted from the monolith's
+ * `SidebarActionContext`. Header buttons carrying an `actionId` (rather than an
+ * `href`) dispatch through here; a page registers a handler via
+ * `useSidebarAction` to open its own dialog. This is what makes `actionId` CTAs
+ * ("New Supplier Invoice", "New Cost Code", …) fire when clicked.
+ */
+type ActionHandler = (actionId: string) => void;
+interface SidebarActionContextValue {
+    /** Dispatch an action to all registered page handlers. */
+    triggerAction: (actionId: string) => void;
+    /** Register a handler that receives sidebar actions. Returns an unregister function. */
+    registerHandler: (handler: ActionHandler) => () => void;
+    /** Set of actionIds whose owning UI surface (e.g. a dialog) is currently open. */
+    activeActions: ReadonlySet<string>;
+    /** Reports whether the owning UI surface for `actionId` is currently open. */
+    setActionActive: (actionId: string, isActive: boolean) => void;
+}
+declare const SidebarActionContext: react.Context<SidebarActionContextValue>;
+declare function SidebarActionProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/** Used by the header to dispatch actions to pages. */
+declare function useTriggerSidebarAction(): (actionId: string) => void;
+/** Used by pages to register a handler for sidebar actions. Auto-cleans up on unmount. */
+declare function useSidebarAction(handler: ActionHandler): void;
+/**
+ * Registers a map of sidebar-action handlers keyed by action id, dispatching the
+ * matching entry when an action fires (unknown ids are ignored). The handler map
+ * may change every render — a ref keeps the dispatcher stable so the registration
+ * doesn't churn.
+ */
+declare function useSidebarActions(handlers: Record<string, (() => void) | undefined>): void;
+/** Reads the set of dispatch-action ids whose owning UI surface is currently open. */
+declare function useActiveSidebarActions(): ReadonlySet<string>;
+/**
+ * Reports to the channel whether the owning UI surface for `actionId` is open.
+ * Pages call this from a hook scope, mirroring their dialog/drawer open state.
+ */
+declare function useReportSidebarActionActive(actionId: string, isActive: boolean): void;
+
+export { type ActionDescriptor, type ActionHandler, type ActionSlot, type Breadcrumb, type FillGap, FillGrid, FillGridItem, type FillSpan, type HeaderAction, type HeaderActionVariant, type HeaderDetailContext, type HeaderMenuItem, PageHeader, PageHeaderContext, type PageHeaderDerivedProps, type PageHeaderProps, PageHeaderProvider, type PageHeaderProviderProps, type PageHeaderState, type RouteMeta, type RouteMetaEntry, SidebarActionContext, type SidebarActionContextValue, SidebarActionProvider, type Twelfths, buildBreadcrumbs, useActiveSidebarActions, usePageHeader, usePageHeaderContext, useReportSidebarActionActive, useSidebarAction, useSidebarActions, useTriggerSidebarAction, withPageHeader };