Update api-report

Signed-off-by: Oliver Sand <oliver.sand@sda-se.com>

plugins/catalog-graph/api-report.md

@@ -0,0 +1,139 @@
+## API Report File for "@backstage/plugin-catalog-graph"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+/// <reference types="react" />
+
+import { BackstagePlugin } from '@backstage/core-plugin-api';
+import { DependencyGraphTypes } from '@backstage/core-components';
+import { EntityName } from '@backstage/catalog-model';
+import { ExternalRouteRef } from '@backstage/core-plugin-api';
+import { InfoCardVariants } from '@backstage/core-components';
+import { MouseEvent as MouseEvent_2 } from 'react';
+import { MouseEventHandler } from 'react';
+import { RouteRef } from '@backstage/core-plugin-api';
+
+// @public
+export const CatalogGraphPage: ({
+  relationPairs,
+  initialState,
+}: {
+  relationPairs?: RelationPairs | undefined;
+  initialState?:
+    | {
+        selectedRelations?: string[] | undefined;
+        selectedKinds?: string[] | undefined;
+        rootEntityRefs?: string[] | undefined;
+        maxDepth?: number | undefined;
+        unidirectional?: boolean | undefined;
+        mergeRelations?: boolean | undefined;
+        direction?: Direction | undefined;
+        showFilters?: boolean | undefined;
+      }
+    | undefined;
+}) => JSX.Element;
+
+// @public
+export const catalogGraphPlugin: BackstagePlugin<
+  {
+    catalogGraph: RouteRef<undefined>;
+  },
+  {
+    catalogEntity: ExternalRouteRef<
+      {
+        name: string;
+        kind: string;
+        namespace: string;
+      },
+      false
+    >;
+  }
+>;
+
+// @public
+export const catalogGraphRouteRef: RouteRef<undefined>;
+
+// @public
+export enum Direction {
+  BOTTOM_TOP = 'BT',
+  LEFT_RIGHT = 'LR',
+  RIGHT_LEFT = 'RL',
+  TOP_BOTTOM = 'TB',
+}
+
+// @public
+export const EntityCatalogGraphCard: ({
+  variant,
+  relationPairs,
+  maxDepth,
+  unidirectional,
+  mergeRelations,
+  kinds,
+  relations,
+  direction,
+  maxHeight,
+  title,
+}: {
+  variant?: InfoCardVariants | undefined;
+  relationPairs?: RelationPairs | undefined;
+  maxDepth?: number | undefined;
+  unidirectional?: boolean | undefined;
+  mergeRelations?: boolean | undefined;
+  kinds?: string[] | undefined;
+  relations?: string[] | undefined;
+  direction?: Direction | undefined;
+  maxHeight?: number | undefined;
+  title?: string | undefined;
+}) => JSX.Element;
+
+// @public
+export type EntityEdge = DependencyGraphTypes.DependencyEdge<{
+  relations: string[];
+  label: 'visible';
+}>;
+
+// @public
+export type EntityNode = DependencyGraphTypes.DependencyNode<{
+  name: string;
+  kind?: string;
+  title?: string;
+  namespace: string;
+  focused?: boolean;
+  color?: 'primary' | 'secondary' | 'default';
+  onClick?: MouseEventHandler<SVGGElement>;
+}>;
+
+// @public
+export const EntityRelationsGraph: ({
+  rootEntityNames,
+  maxDepth,
+  unidirectional,
+  mergeRelations,
+  kinds,
+  relations,
+  direction,
+  onNodeClick,
+  relationPairs,
+  className,
+}: {
+  rootEntityNames: EntityName | EntityName[];
+  maxDepth?: number | undefined;
+  unidirectional?: boolean | undefined;
+  mergeRelations?: boolean | undefined;
+  kinds?: string[] | undefined;
+  relations?: string[] | undefined;
+  direction?: Direction | undefined;
+  onNodeClick?:
+    | ((value: EntityNode, event: MouseEvent_2<SVGElement>) => void)
+    | undefined;
+  relationPairs?: RelationPairs | undefined;
+  className?: string | undefined;
+}) => JSX.Element;
+
+// @public
+export const RELATION_PAIRS: RelationPairs;
+
+// @public
+export type RelationPairs = [string, string][];
+```

plugins/catalog-graph/package.json

@@ -11,7 +11,7 @@
   },
   "scripts": {
     "build": "backstage-cli plugin:build",
-    "start": "backstage-cli plugin:serve --config ../../app-config.yaml",
+    "start": "backstage-cli plugin:serve",
     "lint": "backstage-cli lint",
     "test": "backstage-cli test",
     "diff": "backstage-cli plugin:diff",
@@ -46,7 +46,11 @@
     "@testing-library/jest-dom": "^5.10.1",
     "@testing-library/react": "^11.2.5",
     "@testing-library/user-event": "^13.1.8",
-    "@testing-library/react-hooks": "^3.4.2"
+    "@testing-library/react-hooks": "^3.4.2",
+    "@types/jest": "^26.0.7",
+    "@types/node": "^14.14.32",
+    "cross-fetch": "^3.0.6",
+    "msw": "^0.29.0"
   },
   "files": [
     "dist"

plugins/catalog-graph/src/components/CatalogGraphCard/CatalogGraphCard.tsx

@@ -47,19 +47,6 @@ const useStyles = makeStyles<Theme, { maxHeight: number | undefined }>({
   },
 });
 
-export type Props = {
-  variant?: InfoCardVariants;
-  relationPairs?: RelationPairs;
-  maxDepth?: number;
-  unidirectional?: boolean;
-  mergeRelations?: boolean;
-  kinds?: string[];
-  relations?: string[];
-  direction?: Direction;
-  maxHeight?: number;
-  title?: string;
-};
-
 export const CatalogGraphCard = ({
   variant = 'gridItem',
   relationPairs = RELATION_PAIRS,
@@ -71,7 +58,18 @@ export const CatalogGraphCard = ({
   direction = Direction.LEFT_RIGHT,
   maxHeight,
   title = 'Relations',
-}: Props) => {
+}: {
+  variant?: InfoCardVariants;
+  relationPairs?: RelationPairs;
+  maxDepth?: number;
+  unidirectional?: boolean;
+  mergeRelations?: boolean;
+  kinds?: string[];
+  relations?: string[];
+  direction?: Direction;
+  maxHeight?: number;
+  title?: string;
+}) => {
   const { entity } = useEntity();
   const entityName = getEntityName(entity);
   const catalogEntityRoute = useRouteRef(catalogEntityRouteRef);

plugins/catalog-graph/src/components/EntityRelationsGraph/EntityRelationsGraph.tsx

@@ -59,6 +59,11 @@ const useStyles = makeStyles(theme => ({
   },
 }));
 
+/**
+ * Core building block for custom entity relations diagrams.
+ *
+ * @public
+ */
 export const EntityRelationsGraph = ({
   rootEntityNames,
   maxDepth = Number.POSITIVE_INFINITY,

plugins/catalog-graph/src/components/EntityRelationsGraph/relations.ts

@@ -30,6 +30,12 @@ import {
   RELATION_PROVIDES_API,
 } from '@backstage/catalog-model';
 
+/**
+ * A pair of two relations that describe the opposite of each other. The first
+ * relation is considered as the primary relation.
+ *
+ * @public
+ */
 export type RelationPairs = [string, string][];
 
 // TODO: This file only contains the pairs for the build-in relations.
@@ -37,6 +43,12 @@ export type RelationPairs = [string, string][];
 //  the relations everywhere.
 //  Another option is to move this into @backstage/catalog-model
 
+/**
+ * A list of pairs of entity relations, used to define which relations are
+ * merged together and which the primary relation is.
+ *
+ * @public
+ */
 export const RELATION_PAIRS: RelationPairs = [
   [RELATION_OWNER_OF, RELATION_OWNED_BY],
   [RELATION_CONSUMES_API, RELATION_API_CONSUMED_BY],

plugins/catalog-graph/src/components/EntityRelationsGraph/types.ts

@@ -16,19 +16,57 @@
 import { DependencyGraphTypes } from '@backstage/core-components';
 import { MouseEventHandler } from 'react';
 
+/**
+ * Edge between two entities.
+ *
+ * @public
+ */
 export type EntityEdge = DependencyGraphTypes.DependencyEdge<{
+  /**
+   * Up to two relations that are connecting an entity.
+   */
   relations: string[];
+  /**
+   * Whether the entity is visible or not.
+   */
   // Not used, but has to be non empty to draw a label at all!
   label: 'visible';
 }>;
 
+/**
+ * Node representing an entity.
+ *
+ * @public
+ */
 export type EntityNode = DependencyGraphTypes.DependencyNode<{
+  /**
+   * Name of the entity.
+   */
   name: string;
+  /**
+   * Optional kind of the entity.
+   */
   kind?: string;
+  /**
+   * Optional title of the entity.
+   */
   title?: string;
+  /**
+   * Namespace of the entity.
+   */
   namespace: string;
+  /**
+   * Whether the entity is focused, optional, defaults to false. Focused
+   * entities are highlighted in the graph.
+   */
   focused?: boolean;
+  /**
+   * Optional color of the entity, defaults to 'default'.
+   */
   color?: 'primary' | 'secondary' | 'default';
+  /**
+   * Optional click handler.
+   */
   onClick?: MouseEventHandler<SVGGElement>;
 }>;
 
@@ -36,9 +74,26 @@ export type GraphEdge = DependencyGraphTypes.GraphEdge<EntityEdge>;
 
 export type GraphNode = DependencyGraphTypes.GraphNode<EntityNode>;
 
+/**
+ * Render direction of the graph.
+ *
+ * @public
+ */
 export enum Direction {
+  /**
+   * Top to bottom.
+   */
   TOP_BOTTOM = 'TB',
+  /**
+   * Bottom to top.
+   */
   BOTTOM_TOP = 'BT',
+  /**
+   * Left to right.
+   */
   LEFT_RIGHT = 'LR',
+  /**
+   * Right to left.
+   */
   RIGHT_LEFT = 'RL',
 }

plugins/catalog-graph/src/extensions.tsx

@@ -20,6 +20,11 @@ import {
 import { catalogGraphPlugin } from './plugin';
 import { catalogGraphRouteRef } from './routes';
 
+/**
+ * A card that displays the directly related entities to the current entity.
+ *
+ * @public
+ */
 export const EntityCatalogGraphCard = catalogGraphPlugin.provide(
   createComponentExtension({
     component: {
@@ -29,6 +34,12 @@ export const EntityCatalogGraphCard = catalogGraphPlugin.provide(
   }),
 );
 
+/**
+ * A standalone page that can be added to your application providing a viewer
+ * for your entities and their relations.
+ *
+ * @public
+ */
 export const CatalogGraphPage = catalogGraphPlugin.provide(
   createRoutableExtension({
     component: () =>

plugins/catalog-graph/src/index.ts

@@ -13,6 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+/**
+ * The catalog graph visualizes the relations between entities, like ownership,
+ * grouping or API relationships.
+ *
+ * @packageDocumentation
+ */
+
 export * from './components';
 export { CatalogGraphPage, EntityCatalogGraphCard } from './extensions';
 export { catalogGraphPlugin } from './plugin';

plugins/catalog-graph/src/plugin.ts

@@ -16,6 +16,10 @@
 import { createPlugin } from '@backstage/core-plugin-api';
 import { catalogEntityRouteRef, catalogGraphRouteRef } from './routes';
 
+/**
+ * Catalog Graph Plugin instance.
+ * @public
+ */
 export const catalogGraphPlugin = createPlugin({
   id: '@internal/catalog-graph',
   routes: {

plugins/catalog-graph/src/routes.ts

@@ -18,11 +18,22 @@ import {
   createRouteRef,
 } from '@backstage/core-plugin-api';
 
+/**
+ * Route pointing to the standalone catalog graph page.
+ *
+ * @public
+ */
 export const catalogGraphRouteRef = createRouteRef({
   path: '/catalog-graph',
   title: 'Catalog Graph',
 });
 
+/**
+ * Route pointing to the entity page.
+ * Used to navigate from the graph to an entity.
+ *
+ * @public
+ */
 export const catalogEntityRouteRef = createExternalRouteRef({
   id: 'catalog-entity',
   params: ['namespace', 'kind', 'name'],