From 4d27f6ae69a7c98effc00e6aa621c5f8970fc3dd Mon Sep 17 00:00:00 2001
From: Camila Belo <camilaibs@gmail.com>
Date: Thu, 1 Feb 2024 09:55:51 +0100
Subject: [PATCH] docs: start drafting the card documentation

Signed-off-by: Camila Belo <camilaibs@gmail.com>
---
 plugins/catalog-graph/EXPERIMENTAL.md | 224 ++++++++++++++++++++++++++
 plugins/catalog-graph/README.md       |   3 +
 plugins/catalog-graph/src/alpha.tsx   |  28 ++--
 3 files changed, 246 insertions(+), 9 deletions(-)
 create mode 100644 plugins/catalog-graph/EXPERIMENTAL.md

diff --git a/plugins/catalog-graph/EXPERIMENTAL.md b/plugins/catalog-graph/EXPERIMENTAL.md
new file mode 100644
index 0000000000..5870b30e4b
--- /dev/null
+++ b/plugins/catalog-graph/EXPERIMENTAL.md
@@ -0,0 +1,224 @@
+# catalog-graph
+
+> **Disclaimer:**
+> This documentation is made for those using the experimental new Frontend system.
+> If you are not using the new Backstage frontend system, please go [here](./README.md).
+
+Welcome to the catalog graph plugin! The catalog graph visualizes the relations
+between entities, like ownership, grouping or API relationships.
+
+The plugin comes with these features:
+
+- Catalog entity relations graph card:
+  A card that displays the directly related entities to the current entity.
+  This card is for use on the entity page.
+  The card can be customized, for example filtering for specific relations.
+  <video src='https://user-images.githubusercontent.com/648527/133401912-aaedc36a-b70b-437e-8e5f-2a14b21962f0.mov'  width=640>
+
+- Catalog entity relations graph page:
+  A standalone page that can be added to your application providing a viewer for your entities and their relations.
+  The viewer can be used to navigate through the entities and filter for specific relations.
+  You can access it from the `EntityCatalogGraphCard`.
+  <video src='https://user-images.githubusercontent.com/648527/133403059-6584e469-23ab-41d2-a9e6-fd691a4e2737.mov' width=640>
+
+- `EntityRelationsGraph`:
+  A react component that can be used to build own customized entity relation graphs.
+
+## Installation
+
+This plugin installation requires the following steps:
+
+> [!Note]
+> This plugin only works if you're also using the [catalog](https://backstage.io/docs/features/software-catalog/) plugin, so make sure you've got it installed;
+
+1. Add the `@backstage/catalog-graph` dependency to your app `package.json` file and install it;
+2. In your application's configuration file, enable the catalog entity relations graphic card extension so that the card begins to be presented on the catalog entity page:
+
+```yaml
+app:
+  extensions:
+    - entity-card:catalog-graph/entity-relations
+```
+
+3. Then start the app, navigate to an entity's page and see the Relations graph there;
+4. By clicking on the 'View Graph' card action, you will be redirected to the catalog entity relations page.
+
+## Routes
+
+The Catalog Graph plugin exposes routes that can be used to configure route bindings.
+
+| Key             | Type           | Description                                |
+| --------------- | -------------- | ------------------------------------------ |
+| `catalogGraph`  | Regular route  | Reference to the Catalog graph page route  |
+| `catalogEntity` | External route | Reference to the Catalog entity page route |
+
+With this, you can optionally associate the entity relations graph page to a different route other than the Catalog plugin's default entity page (for more information about route binding, see [this](https://backstage.io/docs/frontend-system/architecture/routes#binding-external-route-references) documentation).
+
+```yaml
+# example binding the catalog graph entity page
+app:
+  routes:
+    bindings:
+      # defaults to catalog.catalogEntity
+      catalog-graph.catalogEntity: <some-plugin-id>.<some-external-route-key>
+```
+
+You can also point an external route from another plug-in to the Catalog chart page:
+
+```yaml
+app:
+  routes:
+    bindings:
+      <some-plugin-id>.<some-external-route-key>: catalog-graph.catalogEntity
+```
+
+## Extensions
+
+This plugin extensions are configurable through the `app-config.yaml` file and its implementation is also replaceable.
+
+### Catalog Entity Relations Graph Card
+
+A [Entity Card](https://backstage.io/docs/frontend-system/building-plugins/extension-types#entitycard---reference) extension renders the relation graph for a Catalog entity on the Catalog entity page. This extension has an action that redirects users to the Catalog entity's relations graph [page](#catalog-entity-relations-graph-page).
+
+| kind        | namespace     | name             | id                                           |
+| ----------- | ------------- | ---------------- | -------------------------------------------- |
+| entity-card | catalog-graph | entity-relations | `entity-card:catalog-graph/entity-relations` |
+
+#### Output
+
+A React component defined by the [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata/) type.
+
+#### Inputs
+
+There are no inputs available for this extension.
+
+#### Config
+
+The card configurations should be defined under the `app.extensions.entity-card:catalog-graph/entity-relations.config` key:
+
+```yaml
+# example configuring the card title
+app:
+  extensions:
+    # this is the extension id and it follows the naming pattern bellow:
+    # <extension-kind>/<plugin-namespace>:<extension-name>
+    - entity-card:catalog-graph/entity-relations:
+        config:
+          # defaults to "Relations"
+          title: 'Entities Relations Graph'
+```
+
+See below the complete list of available configs:
+
+| Key               | Description                                                                                                                                        | Type                                                                                                        | Optional | Default value                                                                                                               |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `filter`          | A query to filter when to show the card based on the entity metadata, for more details [see](./https://github.com/backstage/backstage/pull/21480). | `string`                                                                                                    | yes      | -                                                                                                                           |
+| `title`           | The card title text.                                                                                                                               | `string`                                                                                                    | yes      | `'Relations'`                                                                                                               |
+| `variant`         | The card layout variants.                                                                                                                          | `flex` \| `fullHeight` \| `gridItem`                                                                        | yes      | `'gridItem'`                                                                                                                |
+| `height`          | The card height fixed size.                                                                                                                        | `number`                                                                                                    | yes      | -                                                                                                                           |
+| `rootEntityNames` | A single our multiple compound root entity ref objects.                                                                                            | `{ kind: string, namespace: string, name: string }` \| `{ kind: string, namespace: string, name: string}[]` | yes      | Defaults to the entity available in the entity page context                                                                 |
+| `kinds`           | List of "kinds" used to filter which entities to show on the graph.                                                                                | `string[]`                                                                                                  | yes      | Show all entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format#apiversion-and-kind-required) |
+| `relations`       | List of "relations" used to filter which entities to show on the graph.                                                                            | `string[]`                                                                                                  | yes      | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations)             |
+| `maxDepth`        | Amount of relationship levels.                                                                                                                     | `number`                                                                                                    | yes      | `1`                                                                                                                         |
+| `unidirectional`  | Shows only unidirectional relations.                                                                                                               | `boolean`                                                                                                   | yes      | `true`                                                                                                                      |
+| `mergeRelations`  | Enable merging entity relation pairs.                                                                                                              | `boolean`                                                                                                   | yes      | `true`                                                                                                                      |
+| `direction`       | Render direction of the graph.                                                                                                                     | `TB` \| `BT` \| `LR` \| `RL`                                                                                | yes      | `'LR'`                                                                                                                      |
+| `relationPairs`   | A list of pairs of entity relations, used to define which relations are merged together and which the primary relation is.                         | `string[]`                                                                                                  | yes      | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations)             |
+| `zoom`            | Controls zoom behavior of graph.                                                                                                                   | `enabled` \| `disabled` \| `enable-on-click`                                                                | yes      | `'enabled'`                                                                                                                 |
+| `curve`           | A factory name for curve generators addressing both lines and areas.                                                                               | `curveStepBefore` \| `curveMonotoneX`                                                                       | yes      | `'enable-on-click' `                                                                                                        |
+
+#### How to override the card extension
+
+There is more than one option on where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides) to learn more about the recommendations.
+
+> [!Warning]
+> To maintain the same level of configuration, you should define the same or an extended configuration schema.
+
+```tsx
+import { createExtensionOverrides } from '@backstage/backstage-plugin-api';
+import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha';
+
+createExtensionOverrides(
+  extensions: [
+    createEntityCardExtension({
+      // This namespace is necessary so the system knows that this extension will replace the default 'entity-relations' card extension that is provided by the 'catalog-graph' plugin
+      namespace: 'catalog-graph',
+      name: 'entity-relations',
+      loader: () => import('./components').then(m => <m.MyEntityRelationsCard />)
+    })
+  ]
+);
+```
+
+### Catalog Entity Relations Graph Page
+
+This page displays a more detailed relation graph for a Catalog entity. It contains a few filters that you can use to narrow down what's displayed.
+
+| kind | namespace     | name | id                   |
+| ---- | ------------- | ---- | -------------------- |
+| page | catalog-graph | -    | `page:catalog-graph` |
+
+#### Output
+
+A React component defined by the [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata/) type.
+
+#### Inputs
+
+There are no inputs available for this extension.
+
+#### Config
+
+The page configurations should be defined under the `app.extensions.page:catalog-graph.config` key:
+
+```yaml
+# example configuring the page path
+app:
+  extensions:
+    # this is the extension id and it follows the naming pattern bellow:
+    # <extension-kind>/<plugin-namespace>:<extension-name>
+    - page:catalog-graph:
+        config:
+          # defaults to "/catalog-graph"
+          path: '/entity-graph'
+```
+
+See below the complete list of available configs:
+
+| Key               | Description                                                                                                                | Type                                                                                                                                                                                                                                                | Optional | Default value                                                                                                               |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `path`            | The page route path.                                                                                                       | `string`                                                                                                                                                                                                                                            | true     | '/catalog-graph'                                                                                                            |
+| `initialState`    | The page initial state.                                                                                                    | `{ selectedRelations?: string[],selectedKinds?: string[],rootEntityRefs?: string[],maxDepth?: number,unidirectional?: boolean,mergeRelations?: boolean,direction?: Direction,showFilters?: boolean,curve?: 'curveStepBefore' \| 'curveMonotoneX' }` | true     | {}                                                                                                                          |
+| `rootEntityNames` | A single our multiple compound root entity ref objects.                                                                    | `{ kind: string, namespace: string, name: string }` \| `{ kind: string, namespace: string, name: string}[]`                                                                                                                                         | yes      | Defaults to the entity available in the entity page context                                                                 |
+| `kinds`           | List of "kinds" used to filter which entities to show on the graph.                                                        | `string[]`                                                                                                                                                                                                                                          | yes      | Show all entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format#apiversion-and-kind-required) |
+| `relations`       | List of "relations" used to filter which entities to show on the graph.                                                    | `string[]`                                                                                                                                                                                                                                          | yes      | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations)             |
+| `maxDepth`        | Amount of relationship levels.                                                                                             | `number`                                                                                                                                                                                                                                            | yes      | `1`                                                                                                                         |
+| `unidirectional`  | Shows only unidirectional relations.                                                                                       | `boolean`                                                                                                                                                                                                                                           | yes      | `true`                                                                                                                      |
+| `mergeRelations`  | Enable merging entity relation pairs.                                                                                      | `boolean`                                                                                                                                                                                                                                           | yes      | `true`                                                                                                                      |
+| `direction`       | Render direction of the graph.                                                                                             | `TB` \| `BT` \| `LR` \| `RL`                                                                                                                                                                                                                        | yes      | `'LR'`                                                                                                                      |
+| `relationPairs`   | A list of pairs of entity relations, used to define which relations are merged together and which the primary relation is. | `string[]`                                                                                                                                                                                                                                          | yes      | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations)             |
+| `zoom`            | Controls zoom behavior of graph.                                                                                           | `enabled` \| `disabled` \| `enable-on-click`                                                                                                                                                                                                        | yes      | `'enabled'`                                                                                                                 |
+| `curve`           | A factory name for curve generators addressing both lines and areas.                                                       | `curveStepBefore` \| `curveMonotoneX`                                                                                                                                                                                                               | yes      | `'enable-on-click' `                                                                                                        |
+
+## How to override the page extension
+
+There is more than one option on where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides) to learn more about the recommendations.
+
+> [!Warning]
+> To maintain the same level of configuration, you should define the same or an extended configuration schema. Also remember to use the same default path so that applications that use the default path still point to the same page and the same route reference to avoid side effects on external plugins that expect this page to be associated with the default route reference.
+
+```tsx
+import { createExtensionOverrides, createPageExtension } from '@backstage/backstage-plugin-api';
+
+createExtensionOverrides(
+  extensions: [
+    createPageExtension({
+      // Ommiting name since it is an index page
+      // This namespace is necessary so the system knows that this extension will replace the default 'entity-relations' card extension that is provided by the 'catalog-graph' plugin
+      namespace: 'catalog-graph',
+      defaultPath: '/catalog-graph',
+      routeRef: convertLegacyRouteRef(catalogGraphRouteRef),
+      loader: () => import('./components').then(m => <m.MyEntityRelationsPage />)
+    })
+  ]
+);
+```
diff --git a/plugins/catalog-graph/README.md b/plugins/catalog-graph/README.md
index 1b972082d5..820ed1bdca 100644
--- a/plugins/catalog-graph/README.md
+++ b/plugins/catalog-graph/README.md
@@ -1,5 +1,8 @@
 # catalog-graph
 
+> Disclaimer:
+> If you are looking for documentation on the experimental new frontend system support, please go [here](./EXPERIMENTAL.md).
+
 Welcome to the catalog graph plugin! The catalog graph visualizes the relations
 between entities, like ownership, grouping or API relationships.
 
diff --git a/plugins/catalog-graph/src/alpha.tsx b/plugins/catalog-graph/src/alpha.tsx
index 6d0c9d2403..4f92b16b8b 100644
--- a/plugins/catalog-graph/src/alpha.tsx
+++ b/plugins/catalog-graph/src/alpha.tsx
@@ -26,7 +26,7 @@ import {
 } from '@backstage/core-compat-api';
 import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha';
 import { catalogGraphRouteRef, catalogEntityRouteRef } from './routes';
-import { Direction } from './components';
+import { ALL_RELATION_PAIRS, Direction } from './components';
 
 type Zod = Parameters<Parameters<typeof createSchemaFromZod>[0]>[0];
 
@@ -42,18 +42,25 @@ function getEntityGraphRelationsConfigSchema(z: Zod) {
   // Mapping EntityRelationsGraphProps to config
   // TODO: Define how className and render functions will be configured
   return z.object({
-    rootEntityRef: getCompoundEntityRefConfigSchema(z)
+    rootEntityNames: getCompoundEntityRefConfigSchema(z)
       .or(z.array(getCompoundEntityRefConfigSchema(z)))
       .optional(),
     kinds: z.array(z.string()).optional(),
     relations: z.array(z.string()).optional(),
-    maxDepth: z.number().optional(),
+    maxDepth: z.number().default(1),
     unidirectional: z.boolean().optional(),
     mergeRelations: z.boolean().optional(),
-    direction: z.nativeEnum(Direction).optional(),
-    relationPairs: z.array(z.tuple([z.string(), z.string()])).optional(),
-    zoom: z.enum(['enabled', 'disabled', 'enable-on-click']).optional(),
-    curve: z.enum(['curveStepBefore', 'curveMonotoneX']).optional(),
+    direction: z.nativeEnum(Direction).default(Direction.LEFT_RIGHT),
+    relationPairs: z
+      .array(z.tuple([z.string(), z.string()]))
+      .optional()
+      .default(ALL_RELATION_PAIRS),
+    zoom: z
+      .enum(['enabled', 'disabled', 'enable-on-click'])
+      .default('enable-on-click'),
+    curve: z
+      .enum(['curveStepBefore', 'curveMonotoneX'])
+      .default('curveMonotoneX'),
   });
 }
 
@@ -64,9 +71,12 @@ const CatalogGraphEntityCard = createEntityCardExtension({
       .object({
         // Filter is a config required to all entity cards
         filter: z.string().optional(),
-        title: z.string().optional(),
+        title: z.string().optional().default('Relations'),
         height: z.number().optional(),
-        variant: z.enum(['flex', 'fullHeight', 'gridItem']).optional(),
+        variant: z
+          .enum(['flex', 'fullHeight', 'gridItem'])
+          .optional()
+          .default('gridItem'),
       })
       .merge(getEntityGraphRelationsConfigSchema(z)),
   ),