Merge pull request #20888 from backstage/rugvip/tree-api

frontend-*-api: add and implement AppTreeApi
2023-11-06 09:00:01 -06:00
parent 4d070b129f 733bd95746
commit cc8b12366a
16 changed files with 236 additions and 38 deletions
@@ -7,6 +7,7 @@

 import { AnyApiFactory } from '@backstage/core-plugin-api';
 import { AnyApiRef } from '@backstage/core-plugin-api';
+import { ApiRef } from '@backstage/core-plugin-api';
 import { AppTheme } from '@backstage/core-plugin-api';
 import { IconComponent } from '@backstage/core-plugin-api';
 import { JsonObject } from '@backstage/types';
@@ -55,6 +56,66 @@ export type AnyRoutes = {
  [name in string]: RouteRef;
 };

+// @public
+export interface AppNode {
+  readonly edges: AppNodeEdges;
+  readonly instance?: AppNodeInstance;
+  readonly spec: AppNodeSpec;
+}
+
+// @public
+export interface AppNodeEdges {
+  // (undocumented)
+  readonly attachedTo?: {
+    node: AppNode;
+    input: string;
+  };
+  // (undocumented)
+  readonly attachments: ReadonlyMap<string, AppNode[]>;
+}
+
+// @public
+export interface AppNodeInstance {
+  getData<T>(ref: ExtensionDataRef<T>): T | undefined;
+  getDataRefs(): Iterable<ExtensionDataRef<unknown>>;
+}
+
+// @public
+export interface AppNodeSpec {
+  // (undocumented)
+  readonly attachTo: {
+    id: string;
+    input: string;
+  };
+  // (undocumented)
+  readonly config?: unknown;
+  // (undocumented)
+  readonly disabled: boolean;
+  // (undocumented)
+  readonly extension: Extension<unknown>;
+  // (undocumented)
+  readonly id: string;
+  // (undocumented)
+  readonly source?: BackstagePlugin;
+}
+
+// @public
+export interface AppTree {
+  readonly nodes: ReadonlyMap<string, AppNode>;
+  readonly orphans: Iterable<AppNode>;
+  readonly root: AppNode;
+}
+
+// @public
+export interface AppTreeApi {
+  getTree(): {
+    tree: AppTree;
+  };
+}
+
+// @public
+export const appTreeApiRef: ApiRef<AppTreeApi>;
+
 // @public (undocumented)
 export interface BackstagePlugin<
  Routes extends AnyRoutes = AnyRoutes,
@@ -0,0 +1,114 @@
+/*
+ * Copyright 2023 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 { createApiRef } from '@backstage/core-plugin-api';
+import { BackstagePlugin, Extension, ExtensionDataRef } from '../../wiring';
+
+/**
+ * The specification for this {@link AppNode} in the {@link AppTree}.
+ *
+ * @public
+ * @remarks
+ *
+ * The specifications for a collection of app nodes is all the information needed
+ * to build the tree and instantiate the nodes.
+ */
+export interface AppNodeSpec {
+  readonly id: string;
+  readonly attachTo: { id: string; input: string };
+  readonly extension: Extension<unknown>;
+  readonly disabled: boolean;
+  readonly config?: unknown;
+  readonly source?: BackstagePlugin;
+}
+
+/**
+ * The connections from this {@link AppNode} to other nodes.
+ *
+ * @public
+ * @remarks
+ *
+ * The app node edges are resolved based on the app node specs, regardless of whether
+ * adjacent nodes are disabled or not. If no parent attachment is present or
+ */
+export interface AppNodeEdges {
+  readonly attachedTo?: { node: AppNode; input: string };
+  readonly attachments: ReadonlyMap<string, AppNode[]>;
+}
+
+/**
+ * The instance of this {@link AppNode} in the {@link AppTree}.
+ *
+ * @public
+ * @remarks
+ *
+ * The app node instance is created when the `factory` function of an extension is called.
+ * Instances will only be present for nodes in the app that are connected to the root
+ * node and not disabled
+ */
+export interface AppNodeInstance {
+  /** Returns a sequence of all extension data refs that were output by this instance */
+  getDataRefs(): Iterable<ExtensionDataRef<unknown>>;
+  /** Get the output data for a single extension data ref */
+  getData<T>(ref: ExtensionDataRef<T>): T | undefined;
+}
+
+/**
+ * A node in the {@link AppTree}.
+ *
+ * @public
+ */
+export interface AppNode {
+  /** The specification for how this node should be instantiated */
+  readonly spec: AppNodeSpec;
+  /** The edges from this node to other nodes in the app tree */
+  readonly edges: AppNodeEdges;
+  /** The instance of this node, if it was instantiated */
+  readonly instance?: AppNodeInstance;
+}
+
+/**
+ * The app tree containing all {@link AppNode}s of the app.
+ *
+ * @public
+ */
+export interface AppTree {
+  /** The root node of the app */
+  readonly root: AppNode;
+  /** A map of all nodes in the app by ID, including orphaned or disabled nodes */
+  readonly nodes: ReadonlyMap<string /* id */, AppNode>;
+  /** A sequence of all nodes with a parent that is not reachable from the app root node */
+  readonly orphans: Iterable<AppNode>;
+}
+
+/**
+ * The API for interacting with the {@link AppTree}.
+ *
+ * @public
+ */
+export interface AppTreeApi {
+  /**
+   * Get the {@link AppTree} for the app.
+   */
+  getTree(): { tree: AppTree };
+}
+
+/**
+ * The `ApiRef` of {@link AppTreeApi}.
+ *
+ * @public
+ */
+export const appTreeApiRef = createApiRef<AppTreeApi>({ id: 'core.app-tree' });
@@ -0,0 +1,25 @@
+/*
+ * Copyright 2023 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.
+ */
+
+export {
+  appTreeApiRef,
+  type AppNode,
+  type AppNodeEdges,
+  type AppNodeInstance,
+  type AppNodeSpec,
+  type AppTree,
+  type AppTreeApi,
+} from './AppTreeApi';
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2023 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.
+ */
+
+export * from './definitions';
@@ -20,6 +20,7 @@
 * @packageDocumentation
 */

+export * from './apis';
 export * from './components';
 export * from './extensions';
 export * from './routing';