feat(frontend-plugin-api): add titleRouteRef to PageBlueprint

Add `titleRouteRef` to `PageLayoutProps` so the plugin header title
links back to the plugin root. `PageBlueprint` resolves it from
`plugin.routes.root` with fallback to `params.routeRef`.

- PageLayout swap resolves the title link via a conditional child
  component that calls `useRouteRef` only when a route ref exists
- Header actions get stable React keys via `cloneElement`

Signed-off-by: Johan Persson <johanopersson@gmail.com>

packages/frontend-plugin-api/report.api.md

@@ -1924,6 +1924,8 @@ export interface PageLayoutProps {
   tabs?: PageLayoutTab[];
   // (undocumented)
   title?: string;
+  // (undocumented)
+  titleLink?: string;
 }
 
 // @public

packages/frontend-plugin-api/src/blueprints/PageBlueprint.tsx

@@ -25,7 +25,24 @@ import {
 } from '../wiring';
 import { ExtensionBoundary, PageLayout, PageLayoutTab } from '../components';
 import { useApi } from '../apis/system';
+import { routeResolutionApiRef } from '../apis/definitions/RouteResolutionApi';
 import { pluginHeaderActionsApiRef } from '../apis/definitions/PluginHeaderActionsApi';
+import { RouteResolutionApi } from '../apis/definitions/RouteResolutionApi';
+
+function resolveTitleLink(
+  routeResolutionApi: RouteResolutionApi,
+  routeRef: RouteRef | undefined,
+): string | undefined {
+  if (!routeRef) {
+    return undefined;
+  }
+  try {
+    return routeResolutionApi.resolve(routeRef)?.();
+  } catch {
+    // Route ref may require params not available in the current context
+    return undefined;
+  }
+}
 
 /**
  * Creates extensions that are routable React page components.
@@ -78,11 +95,15 @@ export const PageBlueprint = createExtensionBlueprint({
     const resolvedTitle =
       title ?? node.spec.plugin.title ?? node.spec.plugin.pluginId;
     const resolvedIcon = icon ?? node.spec.plugin.icon;
+    const titleRouteRef =
+      (node.spec.plugin.routes as { root?: RouteRef }).root ?? params.routeRef;
 
     yield coreExtensionData.routePath(config.path ?? params.path);
     if (params.loader) {
       const loader = params.loader;
       const PageContent = () => {
+        const routeResolutionApi = useApi(routeResolutionApiRef);
+        const titleLink = resolveTitleLink(routeResolutionApi, titleRouteRef);
         const headerActionsApi = useApi(pluginHeaderActionsApiRef);
         const headerActions = headerActionsApi.getPluginHeaderActions(pluginId);
 
@@ -91,6 +112,7 @@ export const PageBlueprint = createExtensionBlueprint({
             title={resolvedTitle}
             icon={resolvedIcon}
             noHeader={noHeader}
+            titleLink={titleLink}
             headerActions={headerActions}
           >
             {ExtensionBoundary.lazy(node, loader)}
@@ -114,6 +136,8 @@ export const PageBlueprint = createExtensionBlueprint({
 
       const PageContent = () => {
         const firstPagePath = inputs.pages[0]?.get(coreExtensionData.routePath);
+        const routeResolutionApi = useApi(routeResolutionApiRef);
+        const titleLink = resolveTitleLink(routeResolutionApi, titleRouteRef);
 
         const headerActionsApi = useApi(pluginHeaderActionsApiRef);
         const headerActions = headerActionsApi.getPluginHeaderActions(pluginId);
@@ -123,6 +147,7 @@ export const PageBlueprint = createExtensionBlueprint({
             title={resolvedTitle}
             icon={resolvedIcon}
             tabs={tabs}
+            titleLink={titleLink}
             headerActions={headerActions}
           >
             <Routes>
@@ -147,12 +172,15 @@ export const PageBlueprint = createExtensionBlueprint({
       yield coreExtensionData.reactElement(<PageContent />);
     } else {
       const PageContent = () => {
+        const routeResolutionApi = useApi(routeResolutionApiRef);
+        const titleLink = resolveTitleLink(routeResolutionApi, titleRouteRef);
         const headerActionsApi = useApi(pluginHeaderActionsApiRef);
         const headerActions = headerActionsApi.getPluginHeaderActions(pluginId);
         return (
           <PageLayout
             title={resolvedTitle}
             icon={resolvedIcon}
+            titleLink={titleLink}
             headerActions={headerActions}
           />
         );

packages/frontend-plugin-api/src/components/PageLayout.tsx

@@ -43,6 +43,7 @@ export interface PageLayoutProps {
   title?: string;
   icon?: IconElement;
   noHeader?: boolean;
+  titleLink?: string;
   headerActions?: Array<JSX.Element | null>;
   tabs?: PageLayoutTab[];
   children?: ReactNode;