From a285d8c00098197d5dbe57a9c2c3312eaebfda53 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 12 Oct 2023 18:52:06 +0200
Subject: [PATCH] API report updates and frontend-*-api fixes

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../app-next-example-plugin/api-report.md     |   4 +-
 packages/frontend-app-api/api-report.md       |  17 ++-
 packages/frontend-app-api/src/index.ts        |   1 +
 packages/frontend-plugin-api/api-report.md    | 140 +++++++++++++++++-
 .../src/routing/SubRouteRef.ts                |  19 +--
 .../src/wiring/createPlugin.ts                |   4 +-
 .../frontend-plugin-api/src/wiring/index.ts   |   2 +
 plugins/adr/alpha-api-report.md               |   4 +-
 plugins/catalog/alpha-api-report.md           |   4 +-
 plugins/explore/alpha-api-report.md           |   4 +-
 plugins/graphiql/alpha-api-report.md          |  11 +-
 plugins/search/alpha-api-report.md            |  11 +-
 plugins/tech-radar/alpha-api-report.md        |  11 +-
 plugins/techdocs/alpha-api-report.md          |   4 +-
 plugins/user-settings/alpha-api-report.md     |  15 +-
 15 files changed, 203 insertions(+), 48 deletions(-)

diff --git a/packages/app-next-example-plugin/api-report.md b/packages/app-next-example-plugin/api-report.md
index 83449a102f..979abac30a 100644
--- a/packages/app-next-example-plugin/api-report.md
+++ b/packages/app-next-example-plugin/api-report.md
@@ -3,8 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
+import { AnyRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { default as React_2 } from 'react';
 
diff --git a/packages/frontend-app-api/api-report.md b/packages/frontend-app-api/api-report.md
index 74c34be5f4..11c9ac03c5 100644
--- a/packages/frontend-app-api/api-report.md
+++ b/packages/frontend-app-api/api-report.md
@@ -3,13 +3,28 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AppRouteBinder } from '@backstage/core-app-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { Config } from '@backstage/config';
 import { ConfigApi } from '@backstage/core-plugin-api';
 import { ExtensionDataRef } from '@backstage/frontend-plugin-api';
 import { ExtensionOverrides } from '@backstage/frontend-plugin-api';
+import { ExternalRouteRef } from '@backstage/frontend-plugin-api';
 import { JSX as JSX_2 } from 'react';
+import { RouteRef } from '@backstage/frontend-plugin-api';
+import { SubRouteRef } from '@backstage/frontend-plugin-api';
+
+// @public
+export type AppRouteBinder = <
+  TExternalRoutes extends {
+    [name: string]: ExternalRouteRef;
+  },
+>(
+  externalRoutes: TExternalRoutes,
+  targetRoutes: PartialKeys<
+    TargetRouteMap<TExternalRoutes>,
+    KeysWithType<TExternalRoutes, ExternalRouteRef<any, true>>
+  >,
+) => void;
 
 // @public (undocumented)
 export function createApp(options: {
diff --git a/packages/frontend-app-api/src/index.ts b/packages/frontend-app-api/src/index.ts
index f2dfa0f029..ad82b4ceef 100644
--- a/packages/frontend-app-api/src/index.ts
+++ b/packages/frontend-app-api/src/index.ts
@@ -21,3 +21,4 @@
  */
 
 export * from './wiring';
+export * from './routing';
diff --git a/packages/frontend-plugin-api/api-report.md b/packages/frontend-plugin-api/api-report.md
index 071b617851..7753b1744e 100644
--- a/packages/frontend-plugin-api/api-report.md
+++ b/packages/frontend-plugin-api/api-report.md
@@ -7,15 +7,12 @@
 
 import { AnyApiFactory } from '@backstage/core-plugin-api';
 import { AnyApiRef } from '@backstage/core-plugin-api';
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
 import { AppTheme } from '@backstage/core-plugin-api';
 import { IconComponent } from '@backstage/core-plugin-api';
 import { JsonObject } from '@backstage/types';
 import { JSX as JSX_2 } from 'react';
 import { default as React_2 } from 'react';
 import { ReactNode } from 'react';
-import { RouteRef } from '@backstage/core-plugin-api';
 import { z } from 'zod';
 import { ZodSchema } from 'zod';
 import { ZodTypeDef } from 'zod';
@@ -41,6 +38,23 @@ export type AnyExtensionInputMap = {
   >;
 };
 
+// @public (undocumented)
+export type AnyExternalRoutes = {
+  [name in string]: ExternalRouteRef;
+};
+
+// @public
+export type AnyRouteParams =
+  | {
+      [param in string]: string;
+    }
+  | undefined;
+
+// @public (undocumented)
+export type AnyRoutes = {
+  [name in string]: RouteRef;
+};
+
 // @public (undocumented)
 export interface BackstagePlugin<
   Routes extends AnyRoutes = AnyRoutes,
@@ -79,7 +93,7 @@ export const coreExtensionData: {
   reactElement: ConfigurableExtensionDataRef<JSX_2.Element, {}>;
   routePath: ConfigurableExtensionDataRef<string, {}>;
   apiFactory: ConfigurableExtensionDataRef<AnyApiFactory, {}>;
-  routeRef: ConfigurableExtensionDataRef<RouteRef, {}>;
+  routeRef: ConfigurableExtensionDataRef<RouteRef<AnyRouteParams>, {}>;
   navTarget: ConfigurableExtensionDataRef<NavTarget, {}>;
   theme: ConfigurableExtensionDataRef<AppTheme, {}>;
 };
@@ -173,10 +187,35 @@ export function createExtensionOverrides(
   options: ExtensionOverridesOptions,
 ): ExtensionOverrides;
 
+// @public
+export function createExternalRouteRef<
+  TParams extends
+    | {
+        [param in TParamKeys]: string;
+      }
+    | undefined = undefined,
+  TOptional extends boolean = false,
+  TParamKeys extends string = string,
+>(options?: {
+  readonly params?: string extends TParamKeys
+    ? (keyof TParams)[]
+    : TParamKeys[];
+  optional?: TOptional;
+}): ExternalRouteRef<
+  keyof TParams extends never
+    ? undefined
+    : string extends TParamKeys
+    ? TParams
+    : {
+        [param in TParamKeys]: string;
+      },
+  TOptional
+>;
+
 // @public
 export function createNavItemExtension(options: {
   id: string;
-  routeRef: RouteRef;
+  routeRef: RouteRef<undefined>;
   title: string;
   icon: IconComponent;
 }): Extension<{
@@ -215,17 +254,46 @@ export function createPageExtension<
 
 // @public (undocumented)
 export function createPlugin<
-  Routes extends AnyRoutes = AnyRoutes,
-  ExternalRoutes extends AnyExternalRoutes = AnyExternalRoutes,
+  Routes extends AnyRoutes,
+  ExternalRoutes extends AnyExternalRoutes,
 >(
   options: PluginOptions<Routes, ExternalRoutes>,
 ): BackstagePlugin<Routes, ExternalRoutes>;
 
+// @public
+export function createRouteRef<
+  TParams extends
+    | {
+        [param in TParamKeys]: string;
+      }
+    | undefined = undefined,
+  TParamKeys extends string = string,
+>(config?: {
+  readonly params: string extends TParamKeys ? (keyof TParams)[] : TParamKeys[];
+}): RouteRef<
+  keyof TParams extends never
+    ? undefined
+    : string extends TParamKeys
+    ? TParams
+    : {
+        [param in TParamKeys]: string;
+      }
+>;
+
 // @public (undocumented)
 export function createSchemaFromZod<TOutput, TInput>(
   schemaCreator: (zImpl: typeof z) => ZodSchema<TOutput, ZodTypeDef, TInput>,
 ): PortableSchema<TOutput>;
 
+// @public
+export function createSubRouteRef<
+  Path extends string,
+  ParentParams extends AnyRouteParams = never,
+>(config: {
+  path: Path;
+  parent: RouteRef<ParentParams>;
+}): MakeSubRouteRef<PathParams<Path>, ParentParams>;
+
 // @public (undocumented)
 export function createThemeExtension(theme: AppTheme): Extension<never>;
 
@@ -344,11 +412,24 @@ export interface ExtensionOverridesOptions {
   extensions: Extension<unknown>[];
 }
 
+// @public
+export interface ExternalRouteRef<
+  TParams extends AnyRouteParams = AnyRouteParams,
+  TOptional extends boolean = boolean,
+> {
+  // (undocumented)
+  readonly $$type: '@backstage/ExternalRouteRef';
+  // (undocumented)
+  readonly optional: TOptional;
+  // (undocumented)
+  readonly T: TParams;
+}
+
 // @public (undocumented)
 export type NavTarget = {
   title: string;
   icon: IconComponent;
-  routeRef: RouteRef<{}>;
+  routeRef: RouteRef<undefined>;
 };
 
 // @public (undocumented)
@@ -371,4 +452,47 @@ export type PortableSchema<TOutput> = {
   parse: (input: unknown) => TOutput;
   schema: JsonObject;
 };
+
+// @public
+export type RouteFunc<TParams extends AnyRouteParams> = (
+  ...[params]: TParams extends undefined
+    ? readonly []
+    : readonly [params: TParams]
+) => string;
+
+// @public
+export interface RouteRef<TParams extends AnyRouteParams = AnyRouteParams> {
+  // (undocumented)
+  readonly $$type: '@backstage/RouteRef';
+  // (undocumented)
+  readonly T: TParams;
+}
+
+// @public
+export interface SubRouteRef<TParams extends AnyRouteParams = AnyRouteParams> {
+  // (undocumented)
+  readonly $$type: '@backstage/SubRouteRef';
+  // (undocumented)
+  readonly path: string;
+  // (undocumented)
+  readonly T: TParams;
+}
+
+// @public
+export function useRouteRef<
+  TOptional extends boolean,
+  TParams extends AnyRouteParams,
+>(
+  routeRef: ExternalRouteRef<TParams, TOptional>,
+): TParams extends true ? RouteFunc<TParams> | undefined : RouteFunc<TParams>;
+
+// @public
+export function useRouteRef<TParams extends AnyRouteParams>(
+  routeRef: RouteRef<TParams> | SubRouteRef<TParams>,
+): RouteFunc<TParams>;
+
+// @public
+export function useRouteRefParams<Params extends AnyRouteParams>(
+  _routeRef: RouteRef<Params> | SubRouteRef<Params>,
+): Params;
 ```
diff --git a/packages/frontend-plugin-api/src/routing/SubRouteRef.ts b/packages/frontend-plugin-api/src/routing/SubRouteRef.ts
index b71ceb6a95..5c093afa7a 100644
--- a/packages/frontend-plugin-api/src/routing/SubRouteRef.ts
+++ b/packages/frontend-plugin-api/src/routing/SubRouteRef.ts
@@ -105,30 +105,27 @@ export class SubRouteRefImpl<TParams extends AnyRouteParams>
  * Used in {@link PathParams} type declaration.
  * @ignore
  */
-export type ParamPart<S extends string> = S extends `:${infer Param}`
-  ? Param
-  : never;
+type ParamPart<S extends string> = S extends `:${infer Param}` ? Param : never;
 
 /**
  * Used in {@link PathParams} type declaration.
  * @ignore
  */
-export type ParamNames<S extends string> =
-  S extends `${infer Part}/${infer Rest}`
-    ? ParamPart<Part> | ParamNames<Rest>
-    : ParamPart<S>;
+type ParamNames<S extends string> = S extends `${infer Part}/${infer Rest}`
+  ? ParamPart<Part> | ParamNames<Rest>
+  : ParamPart<S>;
 /**
  * This utility type helps us infer a Param object type from a string path
  * For example, `/foo/:bar/:baz` inferred to `{ bar: string, baz: string }`
  * @ignore
  */
-export type PathParams<S extends string> = { [name in ParamNames<S>]: string };
+type PathParams<S extends string> = { [name in ParamNames<S>]: string };
 
 /**
  * Merges a param object type with an optional params type into a params object.
  * @ignore
  */
-export type MergeParams<
+type MergeParams<
   P1 extends { [param in string]: string },
   P2 extends AnyRouteParams,
 > = (P1[keyof P1] extends never ? {} : P1) & (P2 extends undefined ? {} : P2);
@@ -137,7 +134,7 @@ export type MergeParams<
  * Convert empty params to undefined.
  * @ignore
  */
-export type TrimEmptyParams<Params extends { [param in string]: string }> =
+type TrimEmptyParams<Params extends { [param in string]: string }> =
   keyof Params extends never ? undefined : Params;
 
 /**
@@ -146,7 +143,7 @@ export type TrimEmptyParams<Params extends { [param in string]: string }> =
  *
  * @ignore
  */
-export type MakeSubRouteRef<
+type MakeSubRouteRef<
   Params extends { [param in string]: string },
   ParentParams extends AnyRouteParams,
 > = keyof Params & keyof ParentParams extends never
diff --git a/packages/frontend-plugin-api/src/wiring/createPlugin.ts b/packages/frontend-plugin-api/src/wiring/createPlugin.ts
index 782e5134ec..cf18de2b5d 100644
--- a/packages/frontend-plugin-api/src/wiring/createPlugin.ts
+++ b/packages/frontend-plugin-api/src/wiring/createPlugin.ts
@@ -17,10 +17,10 @@
 import { Extension } from './createExtension';
 import { ExternalRouteRef, RouteRef } from '../routing';
 
-/** @internal */
+/** @public */
 export type AnyRoutes = { [name in string]: RouteRef };
 
-/** @internal */
+/** @public */
 export type AnyExternalRoutes = { [name in string]: ExternalRouteRef };
 
 /** @public */
diff --git a/packages/frontend-plugin-api/src/wiring/index.ts b/packages/frontend-plugin-api/src/wiring/index.ts
index 4e4104de97..ec685d6c81 100644
--- a/packages/frontend-plugin-api/src/wiring/index.ts
+++ b/packages/frontend-plugin-api/src/wiring/index.ts
@@ -37,6 +37,8 @@ export {
   createPlugin,
   type BackstagePlugin,
   type PluginOptions,
+  type AnyRoutes,
+  type AnyExternalRoutes,
 } from './createPlugin';
 export {
   createExtensionOverrides,
diff --git a/plugins/adr/alpha-api-report.md b/plugins/adr/alpha-api-report.md
index 6dd1c8043f..379b7e2ada 100644
--- a/plugins/adr/alpha-api-report.md
+++ b/plugins/adr/alpha-api-report.md
@@ -3,8 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
+import { AnyRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { Extension } from '@backstage/frontend-plugin-api';
 import { TranslationRef } from '@backstage/core-plugin-api/alpha';
diff --git a/plugins/catalog/alpha-api-report.md b/plugins/catalog/alpha-api-report.md
index 4582a13a5d..0ae94b81ae 100644
--- a/plugins/catalog/alpha-api-report.md
+++ b/plugins/catalog/alpha-api-report.md
@@ -3,8 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
+import { AnyRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { Extension } from '@backstage/frontend-plugin-api';
 
diff --git a/plugins/explore/alpha-api-report.md b/plugins/explore/alpha-api-report.md
index 308cbac733..b4de3ef3db 100644
--- a/plugins/explore/alpha-api-report.md
+++ b/plugins/explore/alpha-api-report.md
@@ -3,8 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
+import { AnyRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { Extension } from '@backstage/frontend-plugin-api';
 
diff --git a/plugins/graphiql/alpha-api-report.md b/plugins/graphiql/alpha-api-report.md
index 6c0ea02988..eca4a81c33 100644
--- a/plugins/graphiql/alpha-api-report.md
+++ b/plugins/graphiql/alpha-api-report.md
@@ -3,12 +3,12 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { Extension } from '@backstage/frontend-plugin-api';
 import { GraphQLEndpoint } from '@backstage/plugin-graphiql';
 import { PortableSchema } from '@backstage/frontend-plugin-api';
+import { RouteRef } from '@backstage/frontend-plugin-api';
 
 // @alpha (undocumented)
 export function createEndpointExtension<TConfig extends {}>(options: {
@@ -21,7 +21,12 @@ export function createEndpointExtension<TConfig extends {}>(options: {
 }): Extension<TConfig>;
 
 // @alpha (undocumented)
-const _default: BackstagePlugin<AnyRoutes, AnyExternalRoutes>;
+const _default: BackstagePlugin<
+  {
+    root: RouteRef<undefined>;
+  },
+  AnyExternalRoutes
+>;
 export default _default;
 
 // @alpha (undocumented)
diff --git a/plugins/search/alpha-api-report.md b/plugins/search/alpha-api-report.md
index 58c963b1d6..cc4b68f86e 100644
--- a/plugins/search/alpha-api-report.md
+++ b/plugins/search/alpha-api-report.md
@@ -3,13 +3,18 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { Extension } from '@backstage/frontend-plugin-api';
+import { RouteRef } from '@backstage/frontend-plugin-api';
 
 // @alpha (undocumented)
-const _default: BackstagePlugin<AnyRoutes, AnyExternalRoutes>;
+const _default: BackstagePlugin<
+  {
+    root: RouteRef<undefined>;
+  },
+  AnyExternalRoutes
+>;
 export default _default;
 
 // @alpha (undocumented)
diff --git a/plugins/tech-radar/alpha-api-report.md b/plugins/tech-radar/alpha-api-report.md
index 9245acfaf2..24846a1106 100644
--- a/plugins/tech-radar/alpha-api-report.md
+++ b/plugins/tech-radar/alpha-api-report.md
@@ -3,13 +3,18 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { Extension } from '@backstage/frontend-plugin-api';
+import { RouteRef } from '@backstage/frontend-plugin-api';
 
 // @alpha (undocumented)
-const _default: BackstagePlugin<AnyRoutes, AnyExternalRoutes>;
+const _default: BackstagePlugin<
+  {
+    root: RouteRef<undefined>;
+  },
+  AnyExternalRoutes
+>;
 export default _default;
 
 // @alpha (undocumented)
diff --git a/plugins/techdocs/alpha-api-report.md b/plugins/techdocs/alpha-api-report.md
index 0bf8c25b33..5fd1374114 100644
--- a/plugins/techdocs/alpha-api-report.md
+++ b/plugins/techdocs/alpha-api-report.md
@@ -3,8 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
+import { AnyRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
 import { Extension } from '@backstage/frontend-plugin-api';
 
diff --git a/plugins/user-settings/alpha-api-report.md b/plugins/user-settings/alpha-api-report.md
index 8a3e109e5b..4ad22fa984 100644
--- a/plugins/user-settings/alpha-api-report.md
+++ b/plugins/user-settings/alpha-api-report.md
@@ -3,19 +3,20 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyExternalRoutes } from '@backstage/core-plugin-api';
-import { AnyRoutes } from '@backstage/core-plugin-api';
+import { AnyExternalRoutes } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin } from '@backstage/frontend-plugin-api';
-import { RouteRef } from '@backstage/core-plugin-api';
+import { RouteRef } from '@backstage/frontend-plugin-api';
 import { TranslationRef } from '@backstage/core-plugin-api/alpha';
 
 // @alpha (undocumented)
-const _default: BackstagePlugin<AnyRoutes, AnyExternalRoutes>;
+const _default: BackstagePlugin<
+  {
+    root: RouteRef<undefined>;
+  },
+  AnyExternalRoutes
+>;
 export default _default;
 
-// @alpha (undocumented)
-export const userSettingsRouteRef: RouteRef<undefined>;
-
 // @alpha (undocumented)
 export const userSettingsTranslationRef: TranslationRef<
   'user-settings',