diff --git a/packages/app-next/app-config.yaml b/packages/app-next/app-config.yaml index f43fe32faa..2007aaba58 100644 --- a/packages/app-next/app-config.yaml +++ b/packages/app-next/app-config.yaml @@ -16,7 +16,7 @@ app: config: filter: kind:component has:links - entity-card:linguist/languages - - entity-card:catalog-graph/entity-relations: + - entity-card:catalog-graph/relations: config: height: 300 # Entity page content diff --git a/plugins/catalog-graph/EXPERIMENTAL.md b/plugins/catalog-graph/README-alpha.md similarity index 65% rename from plugins/catalog-graph/EXPERIMENTAL.md rename to plugins/catalog-graph/README-alpha.md index 9af7dbea66..52c09c4b50 100644 --- a/plugins/catalog-graph/EXPERIMENTAL.md +++ b/plugins/catalog-graph/README-alpha.md @@ -2,7 +2,7 @@ > [!WARNING] > 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). +> If you are not using the new frontend system, please go [here](./README.md). The Catalog graph plugin helps you to visualize the relations between entities, like ownership, grouping or API relationships. It comes with these features: @@ -44,7 +44,7 @@ app: packages: all extensions: # This is required because the card is not enable by default once you install the plugin - - entity-card:catalog-graph/entity-relations + - entity-card:catalog-graph/relations ``` 3. Then start the app, navigate to an entity's page and see the Relations graph there; @@ -128,9 +128,9 @@ The Catalog graphics plugin provides extensions for each of its features, see be An [entity card](https://backstage.io/docs/frontend-system/building-plugins/extension-types#entitycard---reference) extension that renders the relation graph for an entity on the Catalog entity page and has an action that redirects users to the more advanced [relations graph page](#catalog-entity-relations-graph-page). -| kind | namespace | name | id | Default enabled | -| ----------- | ------------- | ---------------- | -------------------------------------------- | --------------- | -| entity-card | catalog-graph | entity-relations | `entity-card:catalog-graph/entity-relations` | No | +| kind | namespace | name | id | Default enabled | +| ----------- | ------------- | ---------------- | ------------------------------------- | --------------- | +| entity-card | catalog-graph | entity-relations | `entity-card:catalog-graph/relations` | No | ##### Output @@ -142,7 +142,7 @@ 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: +The card configurations should be defined under the `app.extensions.entity-card:catalog-graph/relations.config` key: ```yaml # app-config.yaml @@ -150,7 +150,7 @@ app: extensions: # this is the extension id and it follows the naming pattern bellow: # /: - - entity-card:catalog-graph/entity-relations: + - entity-card:catalog-graph/relations: config: # example configuring the card title # defaults to "Relations" @@ -159,22 +159,20 @@ app: See below the complete list of available configs: -| Key | Description | Type | Optional | Default value | -| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | -| `filter` | A [text-based query](<(https://github.com/backstage/backstage/pull/21480)>) used to filter whether the extension should be rendered or not. | `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` | Restricted list of entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) to display in the graph. | `string[]` | yes | - | -| `relations` | Restricted list of entity [relations](https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-relations) to display in the graph. | `string[]` | yes | - | -| `maxDepth` | A maximum number of levels of relations to display in the graph. | `number` | yes | `1` | -| `unidirectional` | Shows only relations that from the source to the target entity. | `boolean` | yes | `true` | -| `mergeRelations` | Merge the relations line into a single one. | `boolean` | yes | `true` | -| `direction` | Render direction of the graph. | `TB` \| `BT` \| `LR` \| `RL` | yes | `'LR'` | -| `relationPairs` | A list of [pairs of entity relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations), used to define which relations are merged together and which the primary relation is. | `[string[], 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' ` | +| Key | Description | Type | Optional | Default value | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | +| `filter` | A [text-based query](<(https://github.com/backstage/backstage/pull/21480)>) used to filter whether the extension should be rendered or not. | `string` | yes | - | +| `title` | The card title text. | `string` | yes | `'Relations'` | +| `height` | The card height fixed size. | `number` | yes | - | +| `kinds` | Restricted list of entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) to display in the graph. | `string[]` | yes | - | +| `relations` | Restricted list of entity [relations](https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-relations) to display in the graph. | `string[]` | yes | - | +| `maxDepth` | A maximum number of levels of relations to display in the graph. | `number` | yes | `1` | +| `unidirectional` | Shows only relations that are from the source to the target entity. | `boolean` | yes | `true` | +| `mergeRelations` | Merge the relations line into a single one. | `boolean` | yes | `true` | +| `direction` | Render direction of the graph. | `TB` \| `BT` \| `LR` \| `RL` | yes | `'LR'` | +| `relationPairs` | A list of [pairs of entity relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations), used to define which relations are merged together and which the primary relation is. | `[string[], 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' ` | ##### Disable @@ -187,7 +185,7 @@ app: # this is the extension id and it follows the naming pattern bellow: # /: # example disbaling the graph card extension - - entity-card:catalog-graph/entity-relations: false + - entity-card:catalog-graph/relations: false ``` ##### Override @@ -256,20 +254,19 @@ app: 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 filters 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` | Restricted list of entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) to display in the graph. | `string[]` | yes | - | -| `relations` | Restricted list of entity [relations](https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-relations) to display in the graph. | `string[]` | yes | - | -| `maxDepth` | A maximum number of levels of relations to display in the graph. | `number` | yes | `1` | -| `unidirectional` | Shows only relations that from the source to the target entity. | `boolean` | yes | `true` | -| `mergeRelations` | Merge the relations line into a single one. | `boolean` | yes | `true` | -| `direction` | Render direction of the graph. | `TB` \| `BT` \| `LR` \| `RL` | yes | `'LR'` | -| `relationPairs` | A list of [pairs of entity relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations), used to define which relations are merged together and which the primary relation is. | `[string[], 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' ` | +| Key | Description | Type | Optional | Default value | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | +| `path` | The page route path. | `string` | true | `'/catalog-graph' ` | +| `initialState` | These are the initial filter values, as opposed to configuration of the available filter values. | `{ selectedRelations?: string[],selectedKinds?: string[],rootEntityRefs?: string[],maxDepth?: number,unidirectional?: boolean,mergeRelations?: boolean,direction?: Direction,showFilters?: boolean,curve?: 'curveStepBefore' \| 'curveMonotoneX' }` | true | `{}` | +| `kinds` | Restricted list of entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) to display in the graph. | `string[]` | yes | - | +| `relations` | Restricted list of entity [relations](https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-relations) to display in the graph. | `string[]` | yes | - | +| `maxDepth` | A maximum number of levels of relations to display in the graph. | `number` | yes | `1` | +| `unidirectional` | Shows only relations that are from the source to the target entity. | `boolean` | yes | `true` | +| `mergeRelations` | Merge the relations line into a single one. | `boolean` | yes | `true` | +| `direction` | Render direction of the graph. | `TB` \| `BT` \| `LR` \| `RL` | yes | `'LR'` | +| `relationPairs` | A list of [pairs of entity relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations), used to define which relations are merged together and which the primary relation is. | `[string[], 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' ` | ##### Disable diff --git a/plugins/catalog-graph/README.md b/plugins/catalog-graph/README.md index 820ed1bdca..0862abbc96 100644 --- a/plugins/catalog-graph/README.md +++ b/plugins/catalog-graph/README.md @@ -1,7 +1,7 @@ # catalog-graph > Disclaimer: -> If you are looking for documentation on the experimental new frontend system support, please go [here](./EXPERIMENTAL.md). +> If you are looking for documentation on the experimental new frontend system support, please go [here](./README-alpha.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 4f92b16b8b..6d8429332e 100644 --- a/plugins/catalog-graph/src/alpha.tsx +++ b/plugins/catalog-graph/src/alpha.tsx @@ -26,57 +26,37 @@ import { } from '@backstage/core-compat-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; import { catalogGraphRouteRef, catalogEntityRouteRef } from './routes'; -import { ALL_RELATION_PAIRS, Direction } from './components'; +import { Direction } from './components'; -type Zod = Parameters[0]>[0]; - -function getCompoundEntityRefConfigSchema(z: Zod) { - return z.object({ - kind: z.string(), - namespace: z.string(), - name: z.string(), - }); -} - -function getEntityGraphRelationsConfigSchema(z: Zod) { +function getEntityGraphRelationsConfigSchema( + z: Parameters[0]>[0], +) { // Mapping EntityRelationsGraphProps to config - // TODO: Define how className and render functions will be configured + // The classname and render functions are configurable only via extension overrides return z.object({ - rootEntityNames: getCompoundEntityRefConfigSchema(z) - .or(z.array(getCompoundEntityRefConfigSchema(z))) - .optional(), kinds: z.array(z.string()).optional(), relations: z.array(z.string()).optional(), - maxDepth: z.number().default(1), + maxDepth: z.number().optional(), unidirectional: z.boolean().optional(), mergeRelations: z.boolean().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'), + 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(), }); } const CatalogGraphEntityCard = createEntityCardExtension({ - name: 'entity-relations', + name: 'relations', configSchema: createSchemaFromZod(z => z .object({ // Filter is a config required to all entity cards filter: z.string().optional(), - title: z.string().optional().default('Relations'), + title: z.string().optional(), height: z.number().optional(), - variant: z - .enum(['flex', 'fullHeight', 'gridItem']) - .optional() - .default('gridItem'), + // Skipping a "variant" config for now, defaulting to "gridItem" in the component + // For more details, see this comment: https://github.com/backstage/backstage/pull/22619#discussion_r1477333252 }) .merge(getEntityGraphRelationsConfigSchema(z)), ), @@ -93,7 +73,7 @@ const CatalogGraphPage = createPageExtension({ z.object({ // Path is a default config required to all pages path: z.string().default('/catalog-graph'), - // Mapping intialState prop to config + // Mapping intialState prop to config, these are the initial filter values, as opposed to configuration of the available filter values initialState: z .object({ selectedKinds: z.array(z.string()).optional(),