Merge pull request #3844 from backstage/mob/dev-utils

dev-utils: add addPage for use with composability API + EntityGridItem to easily create different card test cases

.changeset/loud-days-breathe.md

@@ -0,0 +1,5 @@
+---
+'@backstage/dev-utils': patch
+---
+
+Add new `addPage` method for use with extensions, as well as an `EntityGridItem` to easily create different test cases for entity overview cards.

packages/dev-utils/package.json

@@ -30,6 +30,8 @@
   },
   "dependencies": {
     "@backstage/core": "^0.4.0",
+    "@backstage/catalog-model": "^0.6.0",
+    "@backstage/plugin-catalog": "^0.2.8",
     "@backstage/test-utils": "^0.1.5",
     "@backstage/theme": "^0.2.2",
     "@material-ui/core": "^4.11.0",

packages/dev-utils/src/components/EntityGridItem/EntityGridItem.tsx

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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 React from 'react';
+import { Grid, GridProps, makeStyles } from '@material-ui/core';
+import { Entity } from '@backstage/catalog-model';
+import { EntityProvider } from '@backstage/plugin-catalog';
+import { BackstageTheme } from '@backstage/theme';
+
+const useStyles = makeStyles<BackstageTheme, { entity: Entity }>(theme => ({
+  root: ({ entity }) => ({
+    position: 'relative',
+
+    '&::before': {
+      content: `"${entity.metadata.name}"`,
+      top: -theme.typography.fontSize + 4,
+      display: 'block',
+      position: 'absolute',
+      color: theme.palette.textSubtle,
+    },
+  }),
+}));
+
+export const EntityGridItem = ({
+  entity,
+  classes,
+  ...rest
+}: Omit<GridProps, 'item' | 'container'> & { entity: Entity }): JSX.Element => {
+  const itemClasses = useStyles({ entity });
+
+  return (
+    <EntityProvider entity={entity}>
+      <Grid classes={{ root: itemClasses.root, ...classes }} {...rest} item />
+    </EntityProvider>
+  );
+};

packages/dev-utils/src/components/EntityGridItem/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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.
+ */
+
+export { EntityGridItem } from './EntityGridItem';

packages/dev-utils/src/components/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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.
+ */
+
+export * from './EntityGridItem';

packages/dev-utils/src/devApp/render.tsx

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { hot } from 'react-hot-loader/root';
+import { hot } from 'react-hot-loader';
 import React, { ComponentType, ReactNode } from 'react';
 import ReactDOM from 'react-dom';
 import BookmarkIcon from '@material-ui/icons/Bookmark';
@@ -29,9 +29,25 @@ import {
   AlertDisplay,
   OAuthRequestDialog,
   AnyApiFactory,
+  IconComponent,
+  BackstageRoutes,
+  attachComponentData,
 } from '@backstage/core';
 import SentimentDissatisfiedIcon from '@material-ui/icons/SentimentDissatisfied';
-import { Routes } from 'react-router';
+import { Outlet } from 'react-router';
+
+const GatheringRoute: (props: {
+  path: string;
+  children: JSX.Element;
+}) => JSX.Element = () => <Outlet />;
+
+attachComponentData(GatheringRoute, 'core.gatherMountPoints', true);
+
+type RegisterPageOptions = {
+  element: JSX.Element;
+  title?: string;
+  icon?: IconComponent;
+};
 
 // TODO(rugvip): export proper plugin type from core that isn't the plugin class
 type BackstagePlugin = ReturnType<typeof createPlugin>;
@@ -44,6 +60,8 @@ class DevAppBuilder {
   private readonly plugins = new Array<BackstagePlugin>();
   private readonly apis = new Array<AnyApiFactory>();
   private readonly rootChildren = new Array<ReactNode>();
+  private readonly routes = new Array<JSX.Element>();
+  private readonly sidebarItems = new Array<JSX.Element>();
 
   /**
    * Register one or more plugins to render in the dev app
@@ -75,6 +93,21 @@ class DevAppBuilder {
     return this;
   }
 
+  addPage({ element, title, icon }: RegisterPageOptions): DevAppBuilder {
+    const path = `/page-${this.routes.length + 1}`;
+    this.sidebarItems.push(
+      <SidebarItem
+        key={path}
+        to={path}
+        text={title ?? path}
+        icon={icon ?? BookmarkIcon}
+      />,
+    );
+    this.routes.push(
+      <GatheringRoute key={path} path={path} children={element} />,
+    );
+    return this;
+  }
   /**
    * Build a DevApp component using the resources registered so far
    */
@@ -100,7 +133,10 @@ class DevAppBuilder {
           <AppRouter>
             <SidebarPage>
               {sidebar}
-              <Routes>{deprecatedAppRoutes}</Routes>
+              <BackstageRoutes>
+                {this.routes}
+                {deprecatedAppRoutes}
+              </BackstageRoutes>
             </SidebarPage>
           </AppRouter>
         </AppProvider>
@@ -114,7 +150,12 @@ class DevAppBuilder {
    * Build and render directory to #root element, with react hot loading.
    */
   render(): void {
-    const DevApp = hot(this.build());
+    const hotModule =
+      require.cache['./dev/index.tsx'] ??
+      require.cache['./dev/index.ts'] ??
+      module;
+
+    const DevApp = hot(hotModule)(this.build());
 
     const paths = this.findPluginPaths(this.plugins);
 
@@ -166,6 +207,7 @@ class DevAppBuilder {
     return (
       <Sidebar>
         <SidebarSpacer />
+        {this.sidebarItems}
         {sidebarItems}
       </Sidebar>
     );
@@ -199,7 +241,7 @@ class DevAppBuilder {
 // this to provide their own plugin dev wrappers.
 
 /**
- * Creates a dev app for rendering one or more plugins and exposing the touchpoints of the plugin.
+ * Creates a dev app for rendering one or more plugins and exposing the touch points of the plugin.
  */
 export function createDevApp() {
   return new DevAppBuilder();

packages/dev-utils/src/index.ts

@@ -13,4 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+export * from './components';
 export * from './devApp';