techdocs: add extensions for techdocs addons (#28644)

* techdocs: add extensions for techdocs addons Signed-off-by: Jackson Chen <jacksonc@spotify.com> * techdocs: add blueprint extension for techdocs addons Signed-off-by: Jackson Chen <jacksonc@spotify.com> * techdocs: move addons blueprint to alpha Signed-off-by: Jackson Chen <jacksonc@spotify.com> * techdocs: add addon extensions for new frontend system and add docs Signed-off-by: Jackson Chen <jacksonc@spotify.com> * techdocs: fix addon modules naming patterns Signed-off-by: Jackson Chen <jacksonc@spotify.com> * techdocs: update test utils with entity presentation api Signed-off-by: Jackson Chen <jacksonc@spotify.com> --------- Signed-off-by: Jackson Chen <jacksonc@spotify.com>
2025-02-21 16:39:45 -05:00
parent b8ef3783fb
commit b5a82087a7
20 changed files with 589 additions and 30 deletions
@@ -14,9 +14,7 @@
    ]
  },
  "publishConfig": {
-    "access": "public",
-    "main": "dist/index.esm.js",
-    "types": "dist/index.d.ts"
+    "access": "public"
  },
  "keywords": [
    "backstage",
@@ -30,8 +28,23 @@
  },
  "license": "Apache-2.0",
  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./alpha": "./src/alpha.ts",
+    "./package.json": "./package.json"
+  },
  "main": "src/index.ts",
  "types": "src/index.ts",
+  "typesVersions": {
+    "*": {
+      "alpha": [
+        "src/alpha.ts"
+      ],
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
  "files": [
    "dist"
  ],
@@ -49,6 +62,7 @@
    "@backstage/config": "workspace:^",
    "@backstage/core-components": "workspace:^",
    "@backstage/core-plugin-api": "workspace:^",
+    "@backstage/frontend-plugin-api": "workspace:^",
    "@backstage/version-bridge": "workspace:^",
    "@material-ui/core": "^4.12.2",
    "@material-ui/styles": "^4.11.0",
@@ -0,0 +1,63 @@
+## API Report File for "@backstage/plugin-techdocs-react"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { ComponentType } from 'react';
+import { ConfigurableExtensionDataRef } from '@backstage/frontend-plugin-api';
+import { ExtensionBlueprint } from '@backstage/frontend-plugin-api';
+
+// @alpha
+export const AddonBlueprint: ExtensionBlueprint<{
+  kind: 'addon';
+  name: undefined;
+  params: TechDocsAddonOptions;
+  output: ConfigurableExtensionDataRef<
+    TechDocsAddonOptions,
+    'techdocs.addon',
+    {}
+  >;
+  inputs: {};
+  config: {};
+  configInput: {};
+  dataRefs: {
+    addon: ConfigurableExtensionDataRef<
+      TechDocsAddonOptions,
+      'techdocs.addon',
+      {}
+    >;
+  };
+}>;
+
+// @alpha (undocumented)
+export const attachTechDocsAddonComponentData: <P>(
+  techDocsAddon: ComponentType<P>,
+  data: TechDocsAddonOptions,
+) => void;
+
+// @alpha (undocumented)
+export const techDocsAddonDataRef: ConfigurableExtensionDataRef<
+  TechDocsAddonOptions,
+  'techdocs.addon',
+  {}
+>;
+
+// @public
+export const TechDocsAddonLocations: Readonly<{
+  readonly Header: 'Header';
+  readonly Subheader: 'Subheader';
+  readonly Settings: 'Settings';
+  readonly PrimarySidebar: 'PrimarySidebar';
+  readonly SecondarySidebar: 'SecondarySidebar';
+  readonly Content: 'Content';
+}>;
+
+// @public
+export type TechDocsAddonOptions<TAddonProps = {}> = {
+  name: string;
+  location: keyof typeof TechDocsAddonLocations;
+  component: ComponentType<TAddonProps>;
+};
+
+// (No @packageDocumentation comment for this package)
+```
@@ -49,7 +49,7 @@ export const TechDocsAddons: React.ComponentType<

 attachComponentData(TechDocsAddons, TECHDOCS_ADDONS_WRAPPER_KEY, true);

-const getDataKeyByName = (name: string) => {
+export const getDataKeyByName = (name: string) => {
  return `${TECHDOCS_ADDONS_KEY}.${name.toLocaleLowerCase('en-US')}`;
 };

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2025 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 { TechDocsAddonOptions } from './types';
+import { attachComponentData } from '@backstage/core-plugin-api';
+import { ComponentType } from 'react';
+import { getDataKeyByName, TECHDOCS_ADDONS_KEY } from './addons';
+import {
+  createExtensionBlueprint,
+  createExtensionDataRef,
+} from '@backstage/frontend-plugin-api';
+
+/** @alpha */
+export type { TechDocsAddonOptions, TechDocsAddonLocations } from './types';
+
+/** @alpha */
+export const techDocsAddonDataRef =
+  createExtensionDataRef<TechDocsAddonOptions>().with({
+    id: 'techdocs.addon',
+  });
+
+/**
+ * Creates an extension to add addons to the TechDocs standalone reader and entity pages.
+ * @alpha
+ */
+export const AddonBlueprint = createExtensionBlueprint({
+  kind: 'addon',
+  attachTo: [
+    { id: 'page:techdocs/reader', input: 'addons' },
+    { id: 'entity-content:techdocs', input: 'addons' },
+  ],
+  output: [techDocsAddonDataRef],
+  factory: (params: TechDocsAddonOptions) => [techDocsAddonDataRef(params)],
+  dataRefs: {
+    addon: techDocsAddonDataRef,
+  },
+});
+
+/** @alpha */
+export const attachTechDocsAddonComponentData = <P>(
+  techDocsAddon: ComponentType<P>,
+  data: TechDocsAddonOptions,
+) => {
+  attachComponentData(techDocsAddon, TECHDOCS_ADDONS_KEY, data);
+  attachComponentData(techDocsAddon, getDataKeyByName(data.name), true);
+};