@ethisyscore/plugin-ui 1.38.0 → 1.40.0

package/dist/useHostSidebarActions-DFZPen7T.d.cts

@@ -0,0 +1,152 @@
+import { Context } from 'react';
+import { HostSidebarActionsApiShape } from '@ethisyscore/components-react';
+
+/** Host-chrome / sidebar-actions contract version (semver). Host MAJOR must equal the SDK
+ *  MAJOR before any publish/subscribe; otherwise the plugin hook fails closed (WI 5188 batch 2). */
+declare const HOST_CHROME_CONTRACT_VERSION = "2.0.0";
+type HostSidebarActionSlot = "primary" | "overflow" | "sidebar-only";
+type HostSidebarActionVariant = "default" | "danger";
+/** Fields common to every action. */
+interface HostSidebarActionBase {
+    id: string;
+    label: string;
+    icon?: string;
+    slot?: HostSidebarActionSlot;
+    variant?: HostSidebarActionVariant;
+    disabled?: boolean;
+    active?: boolean;
+    /** Optional host-side double-gate: the mask is resolved against the surface extension groupCode. */
+    requiredPermission?: number;
+}
+/** Strictly serializable action the plugin publishes to the host sidebar — NO functions cross
+ *  the boundary. Discriminated union so `href` is REQUIRED at the type level for a navigate
+ *  action and FORBIDDEN for a dispatch action (spec-gate MEDIUM R1-M1 — a navigate with a
+ *  missing href fails typecheck at authoring time rather than being silently dropped by the host).
+ *  `kind:"dispatch"` is clicked back to the plugin by `id` via the action-emit subscription. */
+type HostSidebarActionDescriptor = (HostSidebarActionBase & {
+    kind: "dispatch";
+}) | (HostSidebarActionBase & {
+    kind: "navigate";
+    href: string;
+});
+/** A navigation leaf the plugin drives into the host detail sidebar. `href` is extension-relative;
+ *  the host canonicalises + confines it to `/extensions/<slug>/…` (host-owned, never trusted). */
+interface HostSidebarNavItem {
+    id: string;
+    label: string;
+    icon?: string;
+    href: string;
+}
+/** The single publish payload. `none` = contribute nothing (do NOT clobber the static manifest
+ *  actions); `actions` = batch-2 Quick Actions for a detail entity; `detail` = full detail-nav
+ *  REPLACEMENT (title + nav items + back-arrow + Quick Actions). `identityEpoch` is host-stamped
+ *  (plan D-1), so it is not part of this plugin-published shape. */
+type HostSidebarContribution = {
+    mode: "none";
+} | {
+    mode: "actions";
+    entityToken: string;
+    actions: HostSidebarActionDescriptor[];
+} | {
+    mode: "detail";
+    entityToken: string;
+    title: string;
+    navSectionLabel: string;
+    navItems: HostSidebarNavItem[];
+    backHref: string;
+    backLabel: string;
+    actions: HostSidebarActionDescriptor[];
+};
+interface HostSidebarActionsCapabilities {
+    readonly contractVersion: string;
+}
+/** Host-provided API, passed to a PlatformReact page as the `hostSidebar` prop and read via
+ *  the plugin-bundled context. Additive-only. */
+interface HostSidebarActionsApi {
+    /** Replace the surface's sidebar contribution. The host rejects a publish whose entityToken ≠
+     *  its current location-derived token, rejects duplicate action ids, and — for mode:"detail" —
+     *  rejects/atomically-drops an invalid or href-unsafe context (falls back to main nav). */
+    publish(contribution: HostSidebarContribution): void;
+    /** Revert to the static-manifest fallback (publication state = unpublished). */
+    clear(): void;
+    /** Subscribe to click dispatch for `kind:"dispatch"` actions. The host emits the clicked
+     *  action id. Returns an unsubscribe. The plugin bridge subscribes exactly once. */
+    subscribe(onAction: (actionId: string) => void): () => void;
+    readonly capabilities: HostSidebarActionsCapabilities;
+}
+/** Props the host injects into a page for the sidebar-actions seam (merged into PlatformReactPageProps).
+ *  Typed against the dependency-neutral `HostSidebarActionsApiShape` — the SAME type
+ *  `PlatformReactPageProps.hostSidebar` uses in `@ethisyscore/components-react` — so this
+ *  convenience alias never diverges from the canonical page-props declaration. The concrete
+ *  `HostSidebarActionsApi` is structurally assignable to the shape; the page bridge narrows to
+ *  it internally. */
+interface HostSidebarActionsPageProps {
+    hostSidebar?: HostSidebarActionsApiShape;
+}
+declare const HostSidebarActionsContext: Context<HostSidebarActionsApi | null>;
+interface HostChromeDiagnostic {
+    event: string;
+    pageId?: string;
+    detail?: unknown;
+}
+type DiagnosticSinkFn = (d: HostChromeDiagnostic) => void;
+declare function setHostChromeDiagnosticSink(sink: DiagnosticSinkFn): void;
+declare function reportHostChromeDiagnostic(d: HostChromeDiagnostic): void;
+/** Major-equality compatibility check; fail-closed on absent/unparseable input. */
+declare function isHostChromeCompatible(hostVersion: string | undefined): boolean;
+
+/** Authoring shape: a descriptor plus — ONLY for `kind:"dispatch"` — an inline handler.
+ *  A distributive union (not a blanket intersection over the whole descriptor union): `onSelect`
+ *  is permitted only on a dispatch action. A navigate action carries no handler (the host performs
+ *  the navigation from `href`), so supplying `onSelect` on a navigate action is a typecheck error
+ *  rather than a silently-ignored footgun. The hook strips `onSelect` before publishing (only
+ *  serializable descriptors cross to the host). */
+type HostSidebarAction = (Extract<HostSidebarActionDescriptor, {
+    kind: "dispatch";
+}> & {
+    onSelect?: () => void;
+}) | Extract<HostSidebarActionDescriptor, {
+    kind: "navigate";
+}>;
+/** Single source for the discriminant values used across the mode checks, `toContribution`, and
+ *  the content key — so the "none"/"actions"/"detail" strings live in one place. The union type
+ *  below intentionally keeps its literal members (they ARE the discriminant + drive IntelliSense);
+ *  `SIDEBAR_MODE.*` is `as const`, so it is type-identical to those literals. */
+declare const SIDEBAR_MODE: {
+    readonly none: "none";
+    readonly actions: "actions";
+    readonly detail: "detail";
+};
+/** Discriminated input to `useHostSidebarActions`. `mode:"none"` suppresses all plugin-side
+ *  contributions without clobbering the static manifest actions. `mode:"actions"` is the
+ *  batch-2 Quick Actions shape. `mode:"detail"` is the full detail-nav replacement with title,
+ *  navigation items, back-arrow, and Quick Actions. */
+type HostSidebarInput = {
+    mode: "none";
+} | {
+    mode: "actions";
+    entityToken: string;
+    actions: HostSidebarAction[];
+} | {
+    mode: "detail";
+    entityToken: string;
+    title: string;
+    navSectionLabel: string;
+    navItems: HostSidebarNavItem[];
+    backHref: string;
+    backLabel: string;
+    actions: HostSidebarAction[];
+};
+/**
+ * Publish contextual sidebar contributions from a PlatformReact page to the host sidebar, and
+ * receive click dispatch by id. Accepts a discriminated `HostSidebarInput`:
+ *  - `mode:"none"` — suppress all plugin contributions without clobbering the static manifest.
+ *  - `mode:"actions"` — batch-2 Quick Actions for a detail entity (entity token + action list).
+ *  - `mode:"detail"` — full detail-nav replacement (title, nav items, back-arrow, Quick Actions).
+ *
+ * Serializable descriptors only cross to the host; the inline `onSelect` handlers stay in a
+ * ref-map here and are always the latest closure. Fails closed (no publish/subscribe, no throw)
+ * when the host predates or is incompatible with the seam. */
+declare function useHostSidebarActions(input: HostSidebarInput): void;
+
+export { HOST_CHROME_CONTRACT_VERSION as H, SIDEBAR_MODE as S, type HostChromeDiagnostic as a, type HostSidebarAction as b, type HostSidebarActionDescriptor as c, type HostSidebarActionSlot as d, type HostSidebarActionVariant as e, type HostSidebarActionsApi as f, type HostSidebarActionsCapabilities as g, HostSidebarActionsContext as h, type HostSidebarActionsPageProps as i, type HostSidebarContribution as j, type HostSidebarInput as k, type HostSidebarNavItem as l, isHostChromeCompatible as m, reportHostChromeDiagnostic as r, setHostChromeDiagnosticSink as s, useHostSidebarActions as u };

package/dist/useHostSidebarActions-DFZPen7T.d.ts

@@ -0,0 +1,152 @@
+import { Context } from 'react';
+import { HostSidebarActionsApiShape } from '@ethisyscore/components-react';
+
+/** Host-chrome / sidebar-actions contract version (semver). Host MAJOR must equal the SDK
+ *  MAJOR before any publish/subscribe; otherwise the plugin hook fails closed (WI 5188 batch 2). */
+declare const HOST_CHROME_CONTRACT_VERSION = "2.0.0";
+type HostSidebarActionSlot = "primary" | "overflow" | "sidebar-only";
+type HostSidebarActionVariant = "default" | "danger";
+/** Fields common to every action. */
+interface HostSidebarActionBase {
+    id: string;
+    label: string;
+    icon?: string;
+    slot?: HostSidebarActionSlot;
+    variant?: HostSidebarActionVariant;
+    disabled?: boolean;
+    active?: boolean;
+    /** Optional host-side double-gate: the mask is resolved against the surface extension groupCode. */
+    requiredPermission?: number;
+}
+/** Strictly serializable action the plugin publishes to the host sidebar — NO functions cross
+ *  the boundary. Discriminated union so `href` is REQUIRED at the type level for a navigate
+ *  action and FORBIDDEN for a dispatch action (spec-gate MEDIUM R1-M1 — a navigate with a
+ *  missing href fails typecheck at authoring time rather than being silently dropped by the host).
+ *  `kind:"dispatch"` is clicked back to the plugin by `id` via the action-emit subscription. */
+type HostSidebarActionDescriptor = (HostSidebarActionBase & {
+    kind: "dispatch";
+}) | (HostSidebarActionBase & {
+    kind: "navigate";
+    href: string;
+});
+/** A navigation leaf the plugin drives into the host detail sidebar. `href` is extension-relative;
+ *  the host canonicalises + confines it to `/extensions/<slug>/…` (host-owned, never trusted). */
+interface HostSidebarNavItem {
+    id: string;
+    label: string;
+    icon?: string;
+    href: string;
+}
+/** The single publish payload. `none` = contribute nothing (do NOT clobber the static manifest
+ *  actions); `actions` = batch-2 Quick Actions for a detail entity; `detail` = full detail-nav
+ *  REPLACEMENT (title + nav items + back-arrow + Quick Actions). `identityEpoch` is host-stamped
+ *  (plan D-1), so it is not part of this plugin-published shape. */
+type HostSidebarContribution = {
+    mode: "none";
+} | {
+    mode: "actions";
+    entityToken: string;
+    actions: HostSidebarActionDescriptor[];
+} | {
+    mode: "detail";
+    entityToken: string;
+    title: string;
+    navSectionLabel: string;
+    navItems: HostSidebarNavItem[];
+    backHref: string;
+    backLabel: string;
+    actions: HostSidebarActionDescriptor[];
+};
+interface HostSidebarActionsCapabilities {
+    readonly contractVersion: string;
+}
+/** Host-provided API, passed to a PlatformReact page as the `hostSidebar` prop and read via
+ *  the plugin-bundled context. Additive-only. */
+interface HostSidebarActionsApi {
+    /** Replace the surface's sidebar contribution. The host rejects a publish whose entityToken ≠
+     *  its current location-derived token, rejects duplicate action ids, and — for mode:"detail" —
+     *  rejects/atomically-drops an invalid or href-unsafe context (falls back to main nav). */
+    publish(contribution: HostSidebarContribution): void;
+    /** Revert to the static-manifest fallback (publication state = unpublished). */
+    clear(): void;
+    /** Subscribe to click dispatch for `kind:"dispatch"` actions. The host emits the clicked
+     *  action id. Returns an unsubscribe. The plugin bridge subscribes exactly once. */
+    subscribe(onAction: (actionId: string) => void): () => void;
+    readonly capabilities: HostSidebarActionsCapabilities;
+}
+/** Props the host injects into a page for the sidebar-actions seam (merged into PlatformReactPageProps).
+ *  Typed against the dependency-neutral `HostSidebarActionsApiShape` — the SAME type
+ *  `PlatformReactPageProps.hostSidebar` uses in `@ethisyscore/components-react` — so this
+ *  convenience alias never diverges from the canonical page-props declaration. The concrete
+ *  `HostSidebarActionsApi` is structurally assignable to the shape; the page bridge narrows to
+ *  it internally. */
+interface HostSidebarActionsPageProps {
+    hostSidebar?: HostSidebarActionsApiShape;
+}
+declare const HostSidebarActionsContext: Context<HostSidebarActionsApi | null>;
+interface HostChromeDiagnostic {
+    event: string;
+    pageId?: string;
+    detail?: unknown;
+}
+type DiagnosticSinkFn = (d: HostChromeDiagnostic) => void;
+declare function setHostChromeDiagnosticSink(sink: DiagnosticSinkFn): void;
+declare function reportHostChromeDiagnostic(d: HostChromeDiagnostic): void;
+/** Major-equality compatibility check; fail-closed on absent/unparseable input. */
+declare function isHostChromeCompatible(hostVersion: string | undefined): boolean;
+
+/** Authoring shape: a descriptor plus — ONLY for `kind:"dispatch"` — an inline handler.
+ *  A distributive union (not a blanket intersection over the whole descriptor union): `onSelect`
+ *  is permitted only on a dispatch action. A navigate action carries no handler (the host performs
+ *  the navigation from `href`), so supplying `onSelect` on a navigate action is a typecheck error
+ *  rather than a silently-ignored footgun. The hook strips `onSelect` before publishing (only
+ *  serializable descriptors cross to the host). */
+type HostSidebarAction = (Extract<HostSidebarActionDescriptor, {
+    kind: "dispatch";
+}> & {
+    onSelect?: () => void;
+}) | Extract<HostSidebarActionDescriptor, {
+    kind: "navigate";
+}>;
+/** Single source for the discriminant values used across the mode checks, `toContribution`, and
+ *  the content key — so the "none"/"actions"/"detail" strings live in one place. The union type
+ *  below intentionally keeps its literal members (they ARE the discriminant + drive IntelliSense);
+ *  `SIDEBAR_MODE.*` is `as const`, so it is type-identical to those literals. */
+declare const SIDEBAR_MODE: {
+    readonly none: "none";
+    readonly actions: "actions";
+    readonly detail: "detail";
+};
+/** Discriminated input to `useHostSidebarActions`. `mode:"none"` suppresses all plugin-side
+ *  contributions without clobbering the static manifest actions. `mode:"actions"` is the
+ *  batch-2 Quick Actions shape. `mode:"detail"` is the full detail-nav replacement with title,
+ *  navigation items, back-arrow, and Quick Actions. */
+type HostSidebarInput = {
+    mode: "none";
+} | {
+    mode: "actions";
+    entityToken: string;
+    actions: HostSidebarAction[];
+} | {
+    mode: "detail";
+    entityToken: string;
+    title: string;
+    navSectionLabel: string;
+    navItems: HostSidebarNavItem[];
+    backHref: string;
+    backLabel: string;
+    actions: HostSidebarAction[];
+};
+/**
+ * Publish contextual sidebar contributions from a PlatformReact page to the host sidebar, and
+ * receive click dispatch by id. Accepts a discriminated `HostSidebarInput`:
+ *  - `mode:"none"` — suppress all plugin contributions without clobbering the static manifest.
+ *  - `mode:"actions"` — batch-2 Quick Actions for a detail entity (entity token + action list).
+ *  - `mode:"detail"` — full detail-nav replacement (title, nav items, back-arrow, Quick Actions).
+ *
+ * Serializable descriptors only cross to the host; the inline `onSelect` handlers stay in a
+ * ref-map here and are always the latest closure. Fails closed (no publish/subscribe, no throw)
+ * when the host predates or is incompatible with the seam. */
+declare function useHostSidebarActions(input: HostSidebarInput): void;
+
+export { HOST_CHROME_CONTRACT_VERSION as H, SIDEBAR_MODE as S, type HostChromeDiagnostic as a, type HostSidebarAction as b, type HostSidebarActionDescriptor as c, type HostSidebarActionSlot as d, type HostSidebarActionVariant as e, type HostSidebarActionsApi as f, type HostSidebarActionsCapabilities as g, HostSidebarActionsContext as h, type HostSidebarActionsPageProps as i, type HostSidebarContribution as j, type HostSidebarInput as k, type HostSidebarNavItem as l, isHostChromeCompatible as m, reportHostChromeDiagnostic as r, setHostChromeDiagnosticSink as s, useHostSidebarActions as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethisyscore/plugin-ui",
-  "version": "1.38.0",
+  "version": "1.40.0",
   "description": "Plugin-UI umbrella SDK: client bridge + a11y/l10n primitives + brokered-MCP client (WI 4858).",
   "type": "module",
   "main": "./dist/index.cjs",