Merge pull request #8931 from backstage/rugvip/entityrr

catalog-react: deprecate catalogRouteRef and deduplicate entityRouteRef

plugins/bazaar/src/components/HomePageBazaarInfoCard/HomePageBazaarInfoCard.tsx

@@ -44,10 +44,7 @@ import { Member, BazaarProject } from '../../types';
 import { bazaarApiRef } from '../../api';
 import { Alert } from '@material-ui/lab';
 import useAsyncFn from 'react-use/lib/useAsyncFn';
-import {
-  catalogApiRef,
-  catalogRouteRef,
-} from '@backstage/plugin-catalog-react';
+import { catalogApiRef, entityRouteRef } from '@backstage/plugin-catalog-react';
 
 import {
   parseEntityName,
@@ -85,7 +82,7 @@ export const HomePageBazaarInfoCard = ({
   initEntity,
 }: Props) => {
   const classes = useStyles();
-  const catalogLink = useRouteRef(catalogRouteRef);
+  const entityLink = useRouteRef(entityRouteRef);
   const bazaarApi = useApi(bazaarApiRef);
   const identity = useApi(identityApiRef);
   const catalogApi = useApi(catalogApiRef);
@@ -156,7 +153,7 @@ export const HomePageBazaarInfoCard = ({
       const { name, kind, namespace } = parseEntityName(
         bazaarProject.value.entityRef,
       );
-      return `${catalogLink()}/${namespace}/${kind}/${name}`;
+      return entityLink({ kind, namespace, name });
     }
     return '';
   };

plugins/catalog-react/api-report.md

@@ -102,7 +102,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)
@@ -592,7 +592,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;
@@ -610,7 +610,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;
@@ -813,7 +813,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

plugins/org/api-report.md

@@ -7,6 +7,7 @@
 
 import { BackstagePlugin } from '@backstage/core-plugin-api';
 import { Entity } from '@backstage/catalog-model';
+import { ExternalRouteRef } from '@backstage/core-plugin-api';
 import { GroupEntity } from '@backstage/catalog-model';
 import { InfoCardVariants } from '@backstage/core-components';
 import { UserEntity } from '@backstage/catalog-model';
@@ -74,7 +75,12 @@ export const MembersListCard: (_props: {
 // Warning: (ae-missing-release-tag) "orgPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
-const orgPlugin: BackstagePlugin<{}, {}>;
+const orgPlugin: BackstagePlugin<
+  {},
+  {
+    catalogIndex: ExternalRouteRef<undefined, false>;
+  }
+>;
 export { orgPlugin };
 export { orgPlugin as plugin };
 

plugins/org/src/components/Cards/OwnershipCard/OwnershipCard.stories.tsx

@@ -19,7 +19,6 @@ import { ApiProvider } from '@backstage/core-app-api';
 import {
   CatalogApi,
   catalogApiRef,
-  catalogRouteRef,
   EntityProvider,
 } from '@backstage/plugin-catalog-react';
 import { TestApiRegistry, wrapInTestApp } from '@backstage/test-utils';
@@ -31,6 +30,7 @@ import {
 } from '@backstage/theme';
 import { Grid, ThemeProvider } from '@material-ui/core';
 import React from 'react';
+import { catalogIndexRouteRef } from '../../../routes';
 import { OwnershipCard } from './OwnershipCard';
 
 export default {
@@ -100,7 +100,7 @@ export const Default = () =>
       </EntityProvider>
     </ApiProvider>,
     {
-      mountedRoutes: { '/catalog': catalogRouteRef },
+      mountedRoutes: { '/catalog': catalogIndexRouteRef },
     },
   );
 
@@ -134,6 +134,6 @@ export const Themed = () =>
       </ApiProvider>
     </ThemeProvider>,
     {
-      mountedRoutes: { '/catalog': catalogRouteRef },
+      mountedRoutes: { '/catalog': catalogIndexRouteRef },
     },
   );

plugins/org/src/components/Cards/OwnershipCard/OwnershipCard.test.tsx

@@ -23,11 +23,11 @@ import {
   CatalogApi,
   catalogApiRef,
   EntityProvider,
-  catalogRouteRef,
 } from '@backstage/plugin-catalog-react';
 import { renderInTestApp, TestApiProvider } from '@backstage/test-utils';
 import { queryByText } from '@testing-library/react';
 import React from 'react';
+import { catalogIndexRouteRef } from '../../../routes';
 import { OwnershipCard } from './OwnershipCard';
 
 const items = [
@@ -159,7 +159,7 @@ describe('OwnershipCard', () => {
       </TestApiProvider>,
       {
         mountedRoutes: {
-          '/create': catalogRouteRef,
+          '/create': catalogIndexRouteRef,
         },
       },
     );
@@ -205,7 +205,7 @@ describe('OwnershipCard', () => {
       </TestApiProvider>,
       {
         mountedRoutes: {
-          '/create': catalogRouteRef,
+          '/create': catalogIndexRouteRef,
         },
       },
     );
@@ -236,7 +236,7 @@ describe('OwnershipCard', () => {
       </TestApiProvider>,
       {
         mountedRoutes: {
-          '/create': catalogRouteRef,
+          '/create': catalogIndexRouteRef,
         },
       },
     );
@@ -282,7 +282,7 @@ describe('OwnershipCard', () => {
       </TestApiProvider>,
       {
         mountedRoutes: {
-          '/create': catalogRouteRef,
+          '/create': catalogIndexRouteRef,
         },
       },
     );

plugins/org/src/components/Cards/OwnershipCard/OwnershipCard.tsx

@@ -25,7 +25,6 @@ import {
 import { useApi, useRouteRef } from '@backstage/core-plugin-api';
 import {
   catalogApiRef,
-  catalogRouteRef,
   formatEntityRefTitle,
   isOwnerOf,
   useEntity,
@@ -42,6 +41,7 @@ import qs from 'qs';
 import React from 'react';
 import pluralize from 'pluralize';
 import useAsync from 'react-use/lib/useAsync';
+import { catalogIndexRouteRef } from '../../../routes';
 
 type EntityTypeProps = {
   kind: string;
@@ -138,7 +138,7 @@ export const OwnershipCard = ({
 }) => {
   const { entity } = useEntity();
   const catalogApi = useApi(catalogApiRef);
-  const catalogLink = useRouteRef(catalogRouteRef);
+  const catalogLink = useRouteRef(catalogIndexRouteRef);
 
   const {
     loading,

plugins/org/src/plugin.ts

@@ -17,9 +17,13 @@ import {
   createComponentExtension,
   createPlugin,
 } from '@backstage/core-plugin-api';
+import { catalogIndexRouteRef } from './routes';
 
 export const orgPlugin = createPlugin({
   id: 'org',
+  externalRoutes: {
+    catalogIndex: catalogIndexRouteRef,
+  },
 });
 
 export const EntityGroupProfileCard = orgPlugin.provide(

plugins/org/src/routes.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createExternalRouteRef } from '@backstage/core-plugin-api';
+
+export const catalogIndexRouteRef = createExternalRouteRef({
+  id: 'catalog-index',
+});