@ethisyscore/plugin-ui 1.44.0 → 1.46.0

package/dist/pageHeaderTypes-PWZpiwp6.d.cts

@@ -0,0 +1,198 @@
+import { ReactNode } from 'react';
+
+/**
+ * `@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;
+    /**
+     * Optional subtitle (e.g. the entity name) shown under the title. Read by
+     * `usePageHeader` so a wrapper-rendered header (see
+     * {@link PageHeaderProviderProps.useDetailContext}) can surface it without the
+     * page spreading its own `headerProps`.
+     */
+    subtitle?: ReactNode;
+    actions?: HeaderAction[];
+}
+/**
+ * One action or nav node in a plugin's DETAIL CONTEXT — the rich, shared shape a
+ * plugin's `*DetailContext` hook returns (promoted from the monolith's
+ * `SidebarDetailContextNavItem`). One such context drives BOTH surfaces of a
+ * detail page: the page header (via {@link useDetailHeaderActions}) and the host
+ * left-sidebar Quick-actions panel (via `toHostSidebarInput` +
+ * `useHostSidebarActions`). A plugin can pass its own `SidebarDetailContext*`
+ * value here without changing imports — it assigns structurally.
+ */
+interface PluginDetailContextItem {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Navigates when clicked (plugin-surface-relative or absolute plugin path). */
+    href?: string;
+    /** Dispatches via the sidebar-action channel to a page's `useSidebarActions` handler. */
+    actionId?: string;
+    /** Explicit click handler (used when there is no `href`/`actionId`). */
+    onClick?: () => void;
+    /** `"danger"` renders the destructive style. */
+    variant?: "default" | "danger";
+    /** Header placement — see {@link ActionSlot}. */
+    slot?: ActionSlot;
+    disabled?: boolean;
+    /** Nested items (e.g. a Lifecycle / Share dropdown). */
+    children?: PluginDetailContextItem[];
+}
+/**
+ * A plugin detail page's context: title, sub-page nav, back link and the action
+ * set. Promoted from the monolith's `SidebarDetailContext`; the SDK reads only the
+ * fields both surfaces need, so a plugin's richer value assigns to it structurally.
+ */
+interface PluginDetailContext {
+    title: string;
+    subtitle?: ReactNode;
+    /** Sidebar section heading for the nav items (defaults to "Sections"). */
+    navSectionLabel?: string;
+    /** Sub-page navigation items (each needs an `href`). */
+    navItems: PluginDetailContextItem[];
+    /** The Edit/Delete/Add action set surfaced in the header and sidebar. */
+    actions?: PluginDetailContextItem[];
+    /** Back-link target (plugin-surface path). */
+    backHref?: string;
+    backLabel?: string;
+}
+/** 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[];
+}
+
+export type { ActionDescriptor as A, Breadcrumb as B, HeaderMenuItem as H, PageHeaderDerivedProps as P, RouteMeta as R, PluginDetailContextItem as a, HeaderDetailContext as b, PageHeaderState as c, ActionSlot as d, HeaderAction as e, HeaderActionVariant as f, PluginDetailContext as g, RouteMetaEntry as h };

package/dist/pageHeaderTypes-PWZpiwp6.d.ts

@@ -0,0 +1,198 @@
+import { ReactNode } from 'react';
+
+/**
+ * `@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;
+    /**
+     * Optional subtitle (e.g. the entity name) shown under the title. Read by
+     * `usePageHeader` so a wrapper-rendered header (see
+     * {@link PageHeaderProviderProps.useDetailContext}) can surface it without the
+     * page spreading its own `headerProps`.
+     */
+    subtitle?: ReactNode;
+    actions?: HeaderAction[];
+}
+/**
+ * One action or nav node in a plugin's DETAIL CONTEXT — the rich, shared shape a
+ * plugin's `*DetailContext` hook returns (promoted from the monolith's
+ * `SidebarDetailContextNavItem`). One such context drives BOTH surfaces of a
+ * detail page: the page header (via {@link useDetailHeaderActions}) and the host
+ * left-sidebar Quick-actions panel (via `toHostSidebarInput` +
+ * `useHostSidebarActions`). A plugin can pass its own `SidebarDetailContext*`
+ * value here without changing imports — it assigns structurally.
+ */
+interface PluginDetailContextItem {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Navigates when clicked (plugin-surface-relative or absolute plugin path). */
+    href?: string;
+    /** Dispatches via the sidebar-action channel to a page's `useSidebarActions` handler. */
+    actionId?: string;
+    /** Explicit click handler (used when there is no `href`/`actionId`). */
+    onClick?: () => void;
+    /** `"danger"` renders the destructive style. */
+    variant?: "default" | "danger";
+    /** Header placement — see {@link ActionSlot}. */
+    slot?: ActionSlot;
+    disabled?: boolean;
+    /** Nested items (e.g. a Lifecycle / Share dropdown). */
+    children?: PluginDetailContextItem[];
+}
+/**
+ * A plugin detail page's context: title, sub-page nav, back link and the action
+ * set. Promoted from the monolith's `SidebarDetailContext`; the SDK reads only the
+ * fields both surfaces need, so a plugin's richer value assigns to it structurally.
+ */
+interface PluginDetailContext {
+    title: string;
+    subtitle?: ReactNode;
+    /** Sidebar section heading for the nav items (defaults to "Sections"). */
+    navSectionLabel?: string;
+    /** Sub-page navigation items (each needs an `href`). */
+    navItems: PluginDetailContextItem[];
+    /** The Edit/Delete/Add action set surfaced in the header and sidebar. */
+    actions?: PluginDetailContextItem[];
+    /** Back-link target (plugin-surface path). */
+    backHref?: string;
+    backLabel?: string;
+}
+/** 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[];
+}
+
+export type { ActionDescriptor as A, Breadcrumb as B, HeaderMenuItem as H, PageHeaderDerivedProps as P, RouteMeta as R, PluginDetailContextItem as a, HeaderDetailContext as b, PageHeaderState as c, ActionSlot as d, HeaderAction as e, HeaderActionVariant as f, PluginDetailContext as g, RouteMetaEntry as h };

package/dist/platform-react/index.cjs

@@ -648,6 +648,71 @@ function useHostSidebarActions(input) {
   }, [compatible, key]);
 }
 
+// src/platform-react/toHostSidebarInput.ts
+function toHostSidebarInput(context, opts) {
+  if (!context || !opts.entityToken) {
+    return { mode: "none" };
+  }
+  const navItems = context.navItems.map((n) => ({ id: n.id, label: n.label, icon: n.icon, href: slugRelative(n.href, opts.basePath) })).filter((n) => isConfinable(n.href));
+  const mappedBack = slugRelative(context.backHref, opts.basePath);
+  const backHref = isConfinable(mappedBack) ? mappedBack : opts.backHrefFallback ?? "";
+  return {
+    mode: "detail",
+    entityToken: opts.entityToken,
+    title: context.title,
+    navSectionLabel: context.navSectionLabel ?? "Sections",
+    navItems,
+    backHref,
+    backLabel: context.backLabel ?? "Back",
+    actions: toHostActions(context.actions ?? [], opts)
+  };
+}
+function slugRelative(href, basePath) {
+  if (!href) return "";
+  const base = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+  if (href === base) return "";
+  const prefix = `${base}/`;
+  return href.startsWith(prefix) ? href.slice(prefix.length) : href;
+}
+function isConfinable(slugRelativeHref) {
+  return slugRelativeHref.length > 0 && !slugRelativeHref.startsWith("/") && !/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(slugRelativeHref) && !slugRelativeHref.includes("#");
+}
+function flattenLeaves(items) {
+  const out = [];
+  for (const item of items) {
+    if (item.children?.length) out.push(...flattenLeaves(item.children));
+    else out.push(item);
+  }
+  return out;
+}
+function toHostActions(actions, opts) {
+  const out = [];
+  for (const item of flattenLeaves(actions)) {
+    const mapped = toHostAction(item, opts);
+    if (mapped) out.push(mapped);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return out.filter((a) => seen.has(a.id) ? false : (seen.add(a.id), true));
+}
+function toHostAction(item, opts) {
+  const slot = item.slot === "primary" ? "primary" : item.slot === "sidebar-only" ? "sidebar-only" : "overflow";
+  const variant = item.variant === "danger" ? "danger" : void 0;
+  const shared = { id: item.id, label: item.label, icon: item.icon, slot, variant, disabled: item.disabled };
+  if (item.href) {
+    const href = slugRelative(item.href, opts.basePath);
+    if (!isConfinable(href)) return null;
+    return { ...shared, kind: "navigate", href };
+  }
+  if (item.actionId) {
+    const actionId = item.actionId;
+    return { ...shared, kind: "dispatch", onSelect: () => opts.onDispatch(actionId) };
+  }
+  if (item.onClick) {
+    return { ...shared, kind: "dispatch", onSelect: item.onClick };
+  }
+  return null;
+}
+
 exports.BaseMcpService = BaseMcpService;
 exports.DEFAULT_MAX_UPLOAD_BYTES = DEFAULT_MAX_UPLOAD_BYTES;
 exports.EHX_PLUGIN_ROOT_CLASS = EHX_PLUGIN_ROOT_CLASS;
@@ -676,6 +741,7 @@ exports.reportHostChromeDiagnostic = reportHostChromeDiagnostic;
 exports.resolveSurfaceBase = resolveSurfaceBase;
 exports.setHostChromeDiagnosticSink = setHostChromeDiagnosticSink;
 exports.surfacePathFor = surfacePathFor;
+exports.toHostSidebarInput = toHostSidebarInput;
 exports.useAuthenticatedQueries = useAuthenticatedQueries;
 exports.useAuthenticatedQuery = useAuthenticatedQuery;
 exports.useHostSidebarActions = useHostSidebarActions;