@ethisyscore/plugin-ui 1.99.0 → 1.100.1

package/dist/{useHostSidebarActions-Bt2U-EuA.d.ts → activeNavHref-BkBjanre.d.cts}

@@ -1,11 +1,15 @@
+import { R as RouteMeta } from './pageHeaderTypes-PWZpiwp6.cjs';
 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).
  *  2.1.0 added the additive `kind:"group"` action variant (collapsible Lifecycle/Share); the
- *  major-equality gate keeps 2.0 and 2.1 mutually compatible (older hosts ignore group children). */
-declare const HOST_CHROME_CONTRACT_VERSION = "2.1.0";
+ *  major-equality gate keeps 2.0 and 2.1 mutually compatible (older hosts ignore group children).
+ *  2.2.0 added the additive, optional `activeNavHref` on every contribution mode; an older host
+ *  ignores the extra field (it builds its state field-by-field, never by spreading the
+ *  contribution), so a plugin declaring it against a 2.0/2.1 host is inert, not broken. */
+declare const HOST_CHROME_CONTRACT_VERSION = "2.2.0";
 type HostSidebarActionSlot = "primary" | "overflow" | "sidebar-only";
 type HostSidebarActionVariant = "default" | "danger";
 /** Fields common to every action. */
@@ -46,13 +50,13 @@ interface HostSidebarNavItem {
  *  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 = {
+type HostSidebarContribution = ({
     mode: "none";
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "actions";
     entityToken: string;
     actions: HostSidebarActionDescriptor[];
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "detail";
     entityToken: string;
     title: string;
@@ -61,7 +65,30 @@ type HostSidebarContribution = {
     backHref: string;
     backLabel: string;
     actions: HostSidebarActionDescriptor[];
-};
+} & HostSidebarActiveNav);
+/**
+ * The optional active-nav declaration carried by EVERY contribution mode (contract ≥2.2.0).
+ *
+ * `activeNavHref` is a slug-relative href — the SAME vocabulary as nav-item and navigate-action
+ * hrefs — naming the sidebar entry the plugin considers active for the current route. The host
+ * resolves it to its own nav-item id and highlights that entry; when it is absent, or names
+ * nothing the host is rendering, the host's URL election decides exactly as it always has.
+ *
+ * It exists because the host's election can only light an item whose href PREFIXES the current
+ * URL, so a sub-page whose URL does not nest under its section (`/extensions/projects/people/:id`
+ * belonging to "People" at `/extensions/projects/settings`) lights the module root instead. A
+ * plugin's information architecture is not always recoverable from its URL shape, so the plugin
+ * says so; {@link resolveActiveNavHref} derives it from the `routeMeta` parent chain the plugin
+ * already declares for breadcrumbs.
+ *
+ * It rides on `mode:"none"` too — deliberately. `"none"` is what a plugin publishes on an
+ * ordinary list route with no CTAs, and that is precisely the route shape whose highlight is most
+ * often wrong; a declaration there still contributes no actions and still does not clobber the
+ * static manifest.
+ */
+interface HostSidebarActiveNav {
+    activeNavHref?: string;
+}
 interface HostSidebarActionsCapabilities {
     readonly contractVersion: string;
 }
@@ -134,13 +161,13 @@ declare const SIDEBAR_MODE: {
  *  `entityToken` is REQUIRED here — this is the published shape existing consumers narrow
  *  against (`input.entityToken` is a `string` after a mode check), unchanged. To let the
  *  hook derive the token instead, OMIT the property via {@link HostSidebarDerivedInput}. */
-type HostSidebarInput = {
+type HostSidebarInput = ({
     mode: "none";
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "actions";
     entityToken: string;
     actions: HostSidebarAction[];
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "detail";
     entityToken: string;
     title: string;
@@ -149,7 +176,7 @@ type HostSidebarInput = {
     backHref: string;
     backLabel: string;
     actions: HostSidebarAction[];
-};
+} & HostSidebarActiveNav);
 /** Token-less authoring variants: the hook derives the host-mirrored entity token from the
  *  surface base + current location (`deriveHostEntityToken`) — correct by construction, since
  *  the host's token guard silently drops a mismatching publish. Prefer these unless you need
@@ -158,11 +185,11 @@ type HostSidebarInput = {
  *  (e.g. `entityToken: maybeToken` with an unresolved token) keeps the long-standing
  *  "unresolved token → contribute nothing" semantic and is treated as `mode:"none"`, NOT
  *  derived — only a truly ABSENT property derives. */
-type HostSidebarDerivedInput = {
+type HostSidebarDerivedInput = ({
     mode: "actions";
     entityToken?: undefined;
     actions: HostSidebarAction[];
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "detail";
     entityToken?: undefined;
     title: string;
@@ -171,7 +198,7 @@ type HostSidebarDerivedInput = {
     backHref: string;
     backLabel: string;
     actions: HostSidebarAction[];
-};
+} & HostSidebarActiveNav);
 /** What `useHostSidebarActions` accepts: the classic explicit-token shape or a derived-token variant. */
 type HostSidebarHookInput = HostSidebarInput | HostSidebarDerivedInput;
 /**
@@ -186,4 +213,58 @@ type HostSidebarHookInput = HostSidebarInput | HostSidebarDerivedInput;
  * when the host predates or is incompatible with the seam. */
 declare function useHostSidebarActions(input: HostSidebarHookInput): 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, type HostSidebarHookInput as n, type HostSidebarDerivedInput as o, reportHostChromeDiagnostic as r, setHostChromeDiagnosticSink as s, useHostSidebarActions as u };
+/**
+ * Options for {@link resolveActiveNavHref}.
+ */
+interface ResolveActiveNavHrefOptions {
+    /**
+     * The plugin's mount base (e.g. `/extensions/projects`), stripped to make the result
+     * slug-relative for the host confiner. Defaults to the `/extensions/<slug>` prefix of the
+     * pathname — the same default {@link menuConfigToHostSidebarInput} uses.
+     */
+    basePath?: string;
+}
+/**
+ * Derive the sidebar entry that owns the current route, as a slug-relative href for
+ * `activeNavHref` on a `useHostSidebarActions` input.
+ *
+ * The source of truth is the plugin's own `routeMeta` — the `{ pattern, label, parent }` chain it
+ * already declares for breadcrumbs. That chain IS the plugin's information architecture: it
+ * records that `/extensions/projects/people/:id` belongs under `/extensions/projects/settings`,
+ * which no amount of URL inspection can recover, because the two share no path. So this walks the
+ * matched route up its `parent` chain and returns the nearest CONCRETE (param-free) ancestor:
+ *
+ *   - `/extensions/projects/people/abc`  → `settings`  (via parent `/extensions/projects/settings`)
+ *   - `/extensions/tech/technologies/7/edit` → `technologies` (two parents up, past `…/:id`)
+ *   - `/extensions/projects/all`         → `all`       (the route is its own nav item)
+ *
+ * Returns `undefined` — meaning "no opinion, let the host's URL election decide" — when the path
+ * matches no route, when no ancestor is concrete, or when the answer is the plugin ROOT. The root
+ * is deliberately not declarable: its href prefixes every URL in the plugin, so the URL election
+ * already picks it whenever nothing deeper matches, and there is no case where declaring it
+ * changes an outcome.
+ *
+ * The result is a HINT. The host validates it against the nav items it is actually rendering and
+ * falls back to its URL election if it names nothing, so a stale or mistaken `routeMeta` entry
+ * degrades to today's behaviour rather than blanking the sidebar.
+ */
+declare function resolveActiveNavHref(pathname: string, routeMeta: RouteMeta, opts?: ResolveActiveNavHrefOptions): string | undefined;
+/**
+ * Attach an active-nav declaration to an existing `useHostSidebarActions` input.
+ *
+ * The input union is discriminated on `mode`, so a plugin cannot just spread the field on without
+ * re-narrowing; this does it once, correctly, for every mode — including `mode:"none"`, which is
+ * what the input builders return on an ordinary list route and is exactly where the declaration
+ * matters most. Passing `undefined` returns the input untouched, so the call site needs no branch.
+ *
+ * ```ts
+ * const input = withActiveNavHref(
+ *   menuConfigToHostSidebarInput(menuConfig, { pathname, onDispatch }),
+ *   resolveActiveNavHref(pathname, routeMeta),
+ * );
+ * useHostSidebarActions(input);
+ * ```
+ */
+declare function withActiveNavHref(input: HostSidebarHookInput, activeNavHref: string | undefined): HostSidebarHookInput;
+
+export { HOST_CHROME_CONTRACT_VERSION as H, type ResolveActiveNavHrefOptions as R, 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 HostSidebarActiveNav as j, type HostSidebarContribution as k, type HostSidebarInput as l, type HostSidebarNavItem as m, isHostChromeCompatible as n, resolveActiveNavHref as o, type HostSidebarHookInput as p, type HostSidebarDerivedInput as q, reportHostChromeDiagnostic as r, setHostChromeDiagnosticSink as s, useHostSidebarActions as u, withActiveNavHref as w };

package/dist/{useHostSidebarActions-Bt2U-EuA.d.cts → activeNavHref-cA3_ywRa.d.ts}

@@ -1,11 +1,15 @@
+import { R as RouteMeta } from './pageHeaderTypes-PWZpiwp6.js';
 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).
  *  2.1.0 added the additive `kind:"group"` action variant (collapsible Lifecycle/Share); the
- *  major-equality gate keeps 2.0 and 2.1 mutually compatible (older hosts ignore group children). */
-declare const HOST_CHROME_CONTRACT_VERSION = "2.1.0";
+ *  major-equality gate keeps 2.0 and 2.1 mutually compatible (older hosts ignore group children).
+ *  2.2.0 added the additive, optional `activeNavHref` on every contribution mode; an older host
+ *  ignores the extra field (it builds its state field-by-field, never by spreading the
+ *  contribution), so a plugin declaring it against a 2.0/2.1 host is inert, not broken. */
+declare const HOST_CHROME_CONTRACT_VERSION = "2.2.0";
 type HostSidebarActionSlot = "primary" | "overflow" | "sidebar-only";
 type HostSidebarActionVariant = "default" | "danger";
 /** Fields common to every action. */
@@ -46,13 +50,13 @@ interface HostSidebarNavItem {
  *  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 = {
+type HostSidebarContribution = ({
     mode: "none";
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "actions";
     entityToken: string;
     actions: HostSidebarActionDescriptor[];
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "detail";
     entityToken: string;
     title: string;
@@ -61,7 +65,30 @@ type HostSidebarContribution = {
     backHref: string;
     backLabel: string;
     actions: HostSidebarActionDescriptor[];
-};
+} & HostSidebarActiveNav);
+/**
+ * The optional active-nav declaration carried by EVERY contribution mode (contract ≥2.2.0).
+ *
+ * `activeNavHref` is a slug-relative href — the SAME vocabulary as nav-item and navigate-action
+ * hrefs — naming the sidebar entry the plugin considers active for the current route. The host
+ * resolves it to its own nav-item id and highlights that entry; when it is absent, or names
+ * nothing the host is rendering, the host's URL election decides exactly as it always has.
+ *
+ * It exists because the host's election can only light an item whose href PREFIXES the current
+ * URL, so a sub-page whose URL does not nest under its section (`/extensions/projects/people/:id`
+ * belonging to "People" at `/extensions/projects/settings`) lights the module root instead. A
+ * plugin's information architecture is not always recoverable from its URL shape, so the plugin
+ * says so; {@link resolveActiveNavHref} derives it from the `routeMeta` parent chain the plugin
+ * already declares for breadcrumbs.
+ *
+ * It rides on `mode:"none"` too — deliberately. `"none"` is what a plugin publishes on an
+ * ordinary list route with no CTAs, and that is precisely the route shape whose highlight is most
+ * often wrong; a declaration there still contributes no actions and still does not clobber the
+ * static manifest.
+ */
+interface HostSidebarActiveNav {
+    activeNavHref?: string;
+}
 interface HostSidebarActionsCapabilities {
     readonly contractVersion: string;
 }
@@ -134,13 +161,13 @@ declare const SIDEBAR_MODE: {
  *  `entityToken` is REQUIRED here — this is the published shape existing consumers narrow
  *  against (`input.entityToken` is a `string` after a mode check), unchanged. To let the
  *  hook derive the token instead, OMIT the property via {@link HostSidebarDerivedInput}. */
-type HostSidebarInput = {
+type HostSidebarInput = ({
     mode: "none";
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "actions";
     entityToken: string;
     actions: HostSidebarAction[];
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "detail";
     entityToken: string;
     title: string;
@@ -149,7 +176,7 @@ type HostSidebarInput = {
     backHref: string;
     backLabel: string;
     actions: HostSidebarAction[];
-};
+} & HostSidebarActiveNav);
 /** Token-less authoring variants: the hook derives the host-mirrored entity token from the
  *  surface base + current location (`deriveHostEntityToken`) — correct by construction, since
  *  the host's token guard silently drops a mismatching publish. Prefer these unless you need
@@ -158,11 +185,11 @@ type HostSidebarInput = {
  *  (e.g. `entityToken: maybeToken` with an unresolved token) keeps the long-standing
  *  "unresolved token → contribute nothing" semantic and is treated as `mode:"none"`, NOT
  *  derived — only a truly ABSENT property derives. */
-type HostSidebarDerivedInput = {
+type HostSidebarDerivedInput = ({
     mode: "actions";
     entityToken?: undefined;
     actions: HostSidebarAction[];
-} | {
+} & HostSidebarActiveNav) | ({
     mode: "detail";
     entityToken?: undefined;
     title: string;
@@ -171,7 +198,7 @@ type HostSidebarDerivedInput = {
     backHref: string;
     backLabel: string;
     actions: HostSidebarAction[];
-};
+} & HostSidebarActiveNav);
 /** What `useHostSidebarActions` accepts: the classic explicit-token shape or a derived-token variant. */
 type HostSidebarHookInput = HostSidebarInput | HostSidebarDerivedInput;
 /**
@@ -186,4 +213,58 @@ type HostSidebarHookInput = HostSidebarInput | HostSidebarDerivedInput;
  * when the host predates or is incompatible with the seam. */
 declare function useHostSidebarActions(input: HostSidebarHookInput): 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, type HostSidebarHookInput as n, type HostSidebarDerivedInput as o, reportHostChromeDiagnostic as r, setHostChromeDiagnosticSink as s, useHostSidebarActions as u };
+/**
+ * Options for {@link resolveActiveNavHref}.
+ */
+interface ResolveActiveNavHrefOptions {
+    /**
+     * The plugin's mount base (e.g. `/extensions/projects`), stripped to make the result
+     * slug-relative for the host confiner. Defaults to the `/extensions/<slug>` prefix of the
+     * pathname — the same default {@link menuConfigToHostSidebarInput} uses.
+     */
+    basePath?: string;
+}
+/**
+ * Derive the sidebar entry that owns the current route, as a slug-relative href for
+ * `activeNavHref` on a `useHostSidebarActions` input.
+ *
+ * The source of truth is the plugin's own `routeMeta` — the `{ pattern, label, parent }` chain it
+ * already declares for breadcrumbs. That chain IS the plugin's information architecture: it
+ * records that `/extensions/projects/people/:id` belongs under `/extensions/projects/settings`,
+ * which no amount of URL inspection can recover, because the two share no path. So this walks the
+ * matched route up its `parent` chain and returns the nearest CONCRETE (param-free) ancestor:
+ *
+ *   - `/extensions/projects/people/abc`  → `settings`  (via parent `/extensions/projects/settings`)
+ *   - `/extensions/tech/technologies/7/edit` → `technologies` (two parents up, past `…/:id`)
+ *   - `/extensions/projects/all`         → `all`       (the route is its own nav item)
+ *
+ * Returns `undefined` — meaning "no opinion, let the host's URL election decide" — when the path
+ * matches no route, when no ancestor is concrete, or when the answer is the plugin ROOT. The root
+ * is deliberately not declarable: its href prefixes every URL in the plugin, so the URL election
+ * already picks it whenever nothing deeper matches, and there is no case where declaring it
+ * changes an outcome.
+ *
+ * The result is a HINT. The host validates it against the nav items it is actually rendering and
+ * falls back to its URL election if it names nothing, so a stale or mistaken `routeMeta` entry
+ * degrades to today's behaviour rather than blanking the sidebar.
+ */
+declare function resolveActiveNavHref(pathname: string, routeMeta: RouteMeta, opts?: ResolveActiveNavHrefOptions): string | undefined;
+/**
+ * Attach an active-nav declaration to an existing `useHostSidebarActions` input.
+ *
+ * The input union is discriminated on `mode`, so a plugin cannot just spread the field on without
+ * re-narrowing; this does it once, correctly, for every mode — including `mode:"none"`, which is
+ * what the input builders return on an ordinary list route and is exactly where the declaration
+ * matters most. Passing `undefined` returns the input untouched, so the call site needs no branch.
+ *
+ * ```ts
+ * const input = withActiveNavHref(
+ *   menuConfigToHostSidebarInput(menuConfig, { pathname, onDispatch }),
+ *   resolveActiveNavHref(pathname, routeMeta),
+ * );
+ * useHostSidebarActions(input);
+ * ```
+ */
+declare function withActiveNavHref(input: HostSidebarHookInput, activeNavHref: string | undefined): HostSidebarHookInput;
+
+export { HOST_CHROME_CONTRACT_VERSION as H, type ResolveActiveNavHrefOptions as R, 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 HostSidebarActiveNav as j, type HostSidebarContribution as k, type HostSidebarInput as l, type HostSidebarNavItem as m, isHostChromeCompatible as n, resolveActiveNavHref as o, type HostSidebarHookInput as p, type HostSidebarDerivedInput as q, reportHostChromeDiagnostic as r, setHostChromeDiagnosticSink as s, useHostSidebarActions as u, withActiveNavHref as w };