catalog-react: route ref deprecations + deduplication and docs

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/hungry-buttons-fetch.md

@@ -0,0 +1,9 @@
+---
+'@backstage/plugin-catalog-react': patch
+---
+
+The `entityRouteRef` is now a well-known route that should be imported directly from `@backstage/plugin-catalog-react`. It is guaranteed to be globally unique across duplicate installations of the `@backstage/plugin-catalog-react`, starting at this version.
+
+Deprecated `entityRoute` in favor of `entityRouteRef`.
+
+Deprecated `rootRoute` and `catalogRouteRef`. If you want to refer to the catalog index page from a public plugin you now need to use an `ExternalRouteRef` instead. For private plugins it is possible to take the shortcut of referring directly to `catalogPlugin.routes.indexPage` instead.

plugins/catalog-react/api-report.md

@@ -101,7 +101,7 @@ export type CatalogReactUserListPickerClassKey =
 
 // Warning: (ae-missing-release-tag) "catalogRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const catalogRouteRef: RouteRef<undefined>;
 
 // Warning: (ae-missing-release-tag) "createDomainColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -591,7 +591,7 @@ export const EntityRefLinks: ({
 
 // Warning: (ae-missing-release-tag) "entityRoute" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const entityRoute: RouteRef<{
   name: string;
   kind: string;
@@ -609,7 +609,7 @@ export function entityRouteParams(entity: Entity): {
 
 // Warning: (ae-missing-release-tag) "entityRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export const entityRouteRef: RouteRef<{
   name: string;
   kind: string;
@@ -812,7 +812,7 @@ export function reduceEntityFilters(
 
 // Warning: (ae-missing-release-tag) "rootRoute" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const rootRoute: RouteRef<undefined>;
 
 // @public

plugins/catalog-react/src/routes.ts

@@ -16,20 +16,43 @@
 
 import { Entity, ENTITY_DEFAULT_NAMESPACE } from '@backstage/catalog-model';
 import { createRouteRef } from '@backstage/core-plugin-api';
+import { getOrCreateGlobalSingleton } from '@backstage/version-bridge';
 
 // TODO(Rugvip): Move these route refs back to the catalog plugin once we're all ported to using external routes
+/**
+ * @deprecated Use an `ExternalRouteRef` instead, which can point to `catalogPlugin.routes.catalogIndex`.
+ */
 export const rootRoute = createRouteRef({
   id: 'catalog',
 });
 
+/**
+ * @deprecated Use an `ExternalRouteRef` instead, which can point to `catalogPlugin.routes.catalogIndex`.
+ */
 export const catalogRouteRef = rootRoute;
 
-export const entityRoute = createRouteRef({
-  id: 'catalog:entity',
-  params: ['namespace', 'kind', 'name'],
-});
+/**
+ * A stable route ref that points to the catalog page for an individual entity.
+ *
+ * This `RouteRef` can be imported and used directly, and does not need to be referenced
+ * via an `ExternalRouteRef`.
+ *
+ * If you want to replace the `EntityPage` from `@backstage/catalog-plugin` in your app,
+ * you need to use the `entityRouteRef` as the mount point instead of your own.
+ */
+export const entityRouteRef = getOrCreateGlobalSingleton(
+  'catalog:entity-route-ref',
+  () =>
+    createRouteRef({
+      id: 'catalog:entity',
+      params: ['namespace', 'kind', 'name'],
+    }),
+);
 
-export const entityRouteRef = entityRoute;
+/**
+ * @deprecated use `entityRouteRef` instead.
+ */
+export const entityRoute = entityRouteRef;
 
 // Utility function to get suitable route params for entityRoute, given an
 // entity instance