@backstage/plugin-techdocs-react 1.2.17 → 1.3.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @backstage/plugin-techdocs-react
 
+## 1.3.0-next.0
+
+### Minor Changes
+
+- ec7b35d: Introduced `backstage.io/techdocs-entity-path` annotation which allows deep linking into another entities TechDocs in conjunction with `backstage.io/techdocs-entity`.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/frontend-plugin-api@0.10.3-next.0
+  - @backstage/plugin-techdocs-common@0.1.1-next.0
+
 ## 1.2.17
 
 ### Patch Changes

package/dist/helpers.esm.js

@@ -1,3 +1,6 @@
+import { getCompoundEntityRef, parseEntityRef } from '@backstage/catalog-model';
+import { TECHDOCS_EXTERNAL_PATH_ANNOTATION, TECHDOCS_EXTERNAL_ANNOTATION } from '@backstage/plugin-techdocs-common';
+
 function toLowercaseEntityRefMaybe(entityRef, config) {
   if (config.getOptionalBoolean("techdocs.legacyUseCaseSensitiveTripletPaths"))
     return entityRef;
@@ -6,6 +9,40 @@ function toLowercaseEntityRefMaybe(entityRef, config) {
   entityRef.namespace = entityRef.namespace.toLocaleLowerCase();
   return entityRef;
 }
+function getEntityRootTechDocsPath(entity) {
+  let path = entity.metadata.annotations?.[TECHDOCS_EXTERNAL_PATH_ANNOTATION];
+  if (!path) {
+    return "";
+  }
+  if (!path.startsWith("/")) {
+    path = `/${path}`;
+  }
+  return path;
+}
+const buildTechDocsURL = (entity, routeFunc) => {
+  if (!routeFunc) {
+    return void 0;
+  }
+  let { namespace, kind, name } = getCompoundEntityRef(entity);
+  if (entity.metadata.annotations?.[TECHDOCS_EXTERNAL_ANNOTATION]) {
+    try {
+      const techdocsRef = parseEntityRef(
+        entity.metadata.annotations?.[TECHDOCS_EXTERNAL_ANNOTATION]
+      );
+      namespace = techdocsRef.namespace;
+      kind = techdocsRef.kind;
+      name = techdocsRef.name;
+    } catch {
+    }
+  }
+  const url = routeFunc({
+    namespace,
+    kind,
+    name
+  });
+  const path = getEntityRootTechDocsPath(entity);
+  return `${url}${path}`;
+};
 
-export { toLowercaseEntityRefMaybe };
+export { buildTechDocsURL, getEntityRootTechDocsPath, toLowercaseEntityRefMaybe };
 //# sourceMappingURL=helpers.esm.js.map

package/dist/helpers.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.esm.js","sources":["../src/helpers.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport { CompoundEntityRef } from '@backstage/catalog-model';\n\n/**\n * Lower-case entity triplets by default, but allow override.\n *\n * @public\n */\nexport function toLowercaseEntityRefMaybe(\n  entityRef: CompoundEntityRef,\n  config: Config,\n): CompoundEntityRef {\n  if (config.getOptionalBoolean('techdocs.legacyUseCaseSensitiveTripletPaths'))\n    return entityRef;\n\n  entityRef.kind = entityRef.kind.toLocaleLowerCase();\n  entityRef.name = entityRef.name.toLocaleLowerCase();\n  entityRef.namespace = entityRef.namespace.toLocaleLowerCase();\n\n  return entityRef;\n}\n"],"names":[],"mappings":"AAwBgB,SAAA,yBAAA,CACd,WACA,MACmB,EAAA;AACnB,EAAI,IAAA,MAAA,CAAO,mBAAmB,6CAA6C,CAAA;AACzE,IAAO,OAAA,SAAA;AAET,EAAU,SAAA,CAAA,IAAA,GAAO,SAAU,CAAA,IAAA,CAAK,iBAAkB,EAAA;AAClD,EAAU,SAAA,CAAA,IAAA,GAAO,SAAU,CAAA,IAAA,CAAK,iBAAkB,EAAA;AAClD,EAAU,SAAA,CAAA,SAAA,GAAY,SAAU,CAAA,SAAA,CAAU,iBAAkB,EAAA;AAE5D,EAAO,OAAA,SAAA;AACT;;;;"}
+{"version":3,"file":"helpers.esm.js","sources":["../src/helpers.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport {\n  CompoundEntityRef,\n  Entity,\n  getCompoundEntityRef,\n  parseEntityRef,\n} from '@backstage/catalog-model';\nimport {\n  TECHDOCS_EXTERNAL_ANNOTATION,\n  TECHDOCS_EXTERNAL_PATH_ANNOTATION,\n} from '@backstage/plugin-techdocs-common';\nimport { RouteFunc } from '@backstage/core-plugin-api';\n\n/**\n * Lower-case entity triplets by default, but allow override.\n *\n * @public\n */\nexport function toLowercaseEntityRefMaybe(\n  entityRef: CompoundEntityRef,\n  config: Config,\n): CompoundEntityRef {\n  if (config.getOptionalBoolean('techdocs.legacyUseCaseSensitiveTripletPaths'))\n    return entityRef;\n\n  entityRef.kind = entityRef.kind.toLocaleLowerCase();\n  entityRef.name = entityRef.name.toLocaleLowerCase();\n  entityRef.namespace = entityRef.namespace.toLocaleLowerCase();\n\n  return entityRef;\n}\n\n/**\n * Get the entity path annotation from the given entity and ensure it starts with a slash.\n *\n * @public\n */\nexport function getEntityRootTechDocsPath(entity: Entity): string {\n  let path = entity.metadata.annotations?.[TECHDOCS_EXTERNAL_PATH_ANNOTATION];\n  if (!path) {\n    return '';\n  }\n  if (!path.startsWith('/')) {\n    path = `/${path}`;\n  }\n  return path;\n}\n\n/**\n * Build the TechDocs URL for the given entity. This helper should be used anywhere there\n * is a link to an entities TechDocs.\n *\n * @public\n */\nexport const buildTechDocsURL = (\n  entity: Entity,\n  routeFunc:\n    | RouteFunc<{\n        namespace: string;\n        kind: string;\n        name: string;\n      }>\n    | undefined,\n) => {\n  if (!routeFunc) {\n    return undefined;\n  }\n\n  let { namespace, kind, name } = getCompoundEntityRef(entity);\n\n  if (entity.metadata.annotations?.[TECHDOCS_EXTERNAL_ANNOTATION]) {\n    try {\n      const techdocsRef = parseEntityRef(\n        entity.metadata.annotations?.[TECHDOCS_EXTERNAL_ANNOTATION],\n      );\n      namespace = techdocsRef.namespace;\n      kind = techdocsRef.kind;\n      name = techdocsRef.name;\n    } catch {\n      // not a fan of this but we don't care if the parseEntityRef fails\n    }\n  }\n\n  const url = routeFunc({\n    namespace,\n    kind,\n    name,\n  });\n\n  // Add on the external entity path to the url if one exists. This allows deep linking into another\n  // entities TechDocs.\n  const path = getEntityRootTechDocsPath(entity);\n\n  return `${url}${path}`;\n};\n"],"names":[],"mappings":";;;AAkCgB,SAAA,yBAAA,CACd,WACA,MACmB,EAAA;AACnB,EAAI,IAAA,MAAA,CAAO,mBAAmB,6CAA6C,CAAA;AACzE,IAAO,OAAA,SAAA;AAET,EAAU,SAAA,CAAA,IAAA,GAAO,SAAU,CAAA,IAAA,CAAK,iBAAkB,EAAA;AAClD,EAAU,SAAA,CAAA,IAAA,GAAO,SAAU,CAAA,IAAA,CAAK,iBAAkB,EAAA;AAClD,EAAU,SAAA,CAAA,SAAA,GAAY,SAAU,CAAA,SAAA,CAAU,iBAAkB,EAAA;AAE5D,EAAO,OAAA,SAAA;AACT;AAOO,SAAS,0BAA0B,MAAwB,EAAA;AAChE,EAAA,IAAI,IAAO,GAAA,MAAA,CAAO,QAAS,CAAA,WAAA,GAAc,iCAAiC,CAAA;AAC1E,EAAA,IAAI,CAAC,IAAM,EAAA;AACT,IAAO,OAAA,EAAA;AAAA;AAET,EAAA,IAAI,CAAC,IAAA,CAAK,UAAW,CAAA,GAAG,CAAG,EAAA;AACzB,IAAA,IAAA,GAAO,IAAI,IAAI,CAAA,CAAA;AAAA;AAEjB,EAAO,OAAA,IAAA;AACT;AAQa,MAAA,gBAAA,GAAmB,CAC9B,MAAA,EACA,SAOG,KAAA;AACH,EAAA,IAAI,CAAC,SAAW,EAAA;AACd,IAAO,OAAA,KAAA,CAAA;AAAA;AAGT,EAAA,IAAI,EAAE,SAAW,EAAA,IAAA,EAAM,IAAK,EAAA,GAAI,qBAAqB,MAAM,CAAA;AAE3D,EAAA,IAAI,MAAO,CAAA,QAAA,CAAS,WAAc,GAAA,4BAA4B,CAAG,EAAA;AAC/D,IAAI,IAAA;AACF,MAAA,MAAM,WAAc,GAAA,cAAA;AAAA,QAClB,MAAA,CAAO,QAAS,CAAA,WAAA,GAAc,4BAA4B;AAAA,OAC5D;AACA,MAAA,SAAA,GAAY,WAAY,CAAA,SAAA;AACxB,MAAA,IAAA,GAAO,WAAY,CAAA,IAAA;AACnB,MAAA,IAAA,GAAO,WAAY,CAAA,IAAA;AAAA,KACb,CAAA,MAAA;AAAA;AAER;AAGF,EAAA,MAAM,MAAM,SAAU,CAAA;AAAA,IACpB,SAAA;AAAA,IACA,IAAA;AAAA,IACA;AAAA,GACD,CAAA;AAID,EAAM,MAAA,IAAA,GAAO,0BAA0B,MAAM,CAAA;AAE7C,EAAO,OAAA,CAAA,EAAG,GAAG,CAAA,EAAG,IAAI,CAAA,CAAA;AACtB;;;;"}

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as react from 'react';
 import { ComponentType, PropsWithChildren, Dispatch, SetStateAction, ReactNode } from 'react';
 import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
-import { Extension } from '@backstage/core-plugin-api';
+import { Extension, RouteFunc } from '@backstage/core-plugin-api';
 import { T as TechDocsAddonOptions, a as TechDocsAddonLocations, b as TechDocsMetadata, c as TechDocsEntityMetadata } from './types/types.d-BooYUMWM.js';
-import { CompoundEntityRef } from '@backstage/catalog-model';
+import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { AsyncState } from 'react-use/esm/useAsync';
 import { Config } from '@backstage/config';
@@ -268,5 +268,22 @@ declare const useShadowRootSelection: (waitMillis?: number) => Selection | null;
  * @public
  */
 declare function toLowercaseEntityRefMaybe(entityRef: CompoundEntityRef, config: Config): CompoundEntityRef;
+/**
+ * Get the entity path annotation from the given entity and ensure it starts with a slash.
+ *
+ * @public
+ */
+declare function getEntityRootTechDocsPath(entity: Entity): string;
+/**
+ * Build the TechDocs URL for the given entity. This helper should be used anywhere there
+ * is a link to an entities TechDocs.
+ *
+ * @public
+ */
+declare const buildTechDocsURL: (entity: Entity, routeFunc: RouteFunc<{
+    namespace: string;
+    kind: string;
+    name: string;
+}> | undefined) => string | undefined;
 
-export { SHADOW_DOM_STYLE_LOAD_EVENT, type SyncResult, TECHDOCS_ADDONS_KEY, TECHDOCS_ADDONS_WRAPPER_KEY, TechDocsAddonLocations, TechDocsAddonOptions, TechDocsAddons, type TechDocsApi, TechDocsEntityMetadata, TechDocsMetadata, TechDocsReaderPageProvider, type TechDocsReaderPageProviderProps, type TechDocsReaderPageProviderRenderFunction, type TechDocsReaderPageValue, TechDocsShadowDom, type TechDocsShadowDomProps, type TechDocsStorageApi, createTechDocsAddonExtension, techdocsApiRef, techdocsStorageApiRef, toLowercaseEntityRefMaybe, useShadowDomStylesLoading, useShadowRoot, useShadowRootElements, useShadowRootSelection, useTechDocsAddons, useTechDocsReaderPage };
+export { SHADOW_DOM_STYLE_LOAD_EVENT, type SyncResult, TECHDOCS_ADDONS_KEY, TECHDOCS_ADDONS_WRAPPER_KEY, TechDocsAddonLocations, TechDocsAddonOptions, TechDocsAddons, type TechDocsApi, TechDocsEntityMetadata, TechDocsMetadata, TechDocsReaderPageProvider, type TechDocsReaderPageProviderProps, type TechDocsReaderPageProviderRenderFunction, type TechDocsReaderPageValue, TechDocsShadowDom, type TechDocsShadowDomProps, type TechDocsStorageApi, buildTechDocsURL, createTechDocsAddonExtension, getEntityRootTechDocsPath, techdocsApiRef, techdocsStorageApiRef, toLowercaseEntityRefMaybe, useShadowDomStylesLoading, useShadowRoot, useShadowRootElements, useShadowRootSelection, useTechDocsAddons, useTechDocsReaderPage };

package/dist/index.esm.js

@@ -4,5 +4,5 @@ export { TechDocsReaderPageProvider, useTechDocsReaderPage } from './context.esm
 export { TechDocsAddonLocations } from './types.esm.js';
 export { SHADOW_DOM_STYLE_LOAD_EVENT, TechDocsShadowDom, useShadowDomStylesLoading } from './component.esm.js';
 export { useShadowRoot, useShadowRootElements, useShadowRootSelection } from './hooks.esm.js';
-export { toLowercaseEntityRefMaybe } from './helpers.esm.js';
+export { buildTechDocsURL, getEntityRootTechDocsPath, toLowercaseEntityRefMaybe } from './helpers.esm.js';
 //# sourceMappingURL=index.esm.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-react",
-  "version": "1.2.17",
+  "version": "1.3.0-next.0",
   "description": "Shared frontend utilities for TechDocs and Addons",
   "backstage": {
     "role": "web-library",
@@ -66,12 +66,13 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/catalog-model": "^1.7.4",
-    "@backstage/config": "^1.3.2",
-    "@backstage/core-components": "^0.17.2",
-    "@backstage/core-plugin-api": "^1.10.7",
-    "@backstage/frontend-plugin-api": "^0.10.2",
-    "@backstage/version-bridge": "^1.0.11",
+    "@backstage/catalog-model": "1.7.4",
+    "@backstage/config": "1.3.2",
+    "@backstage/core-components": "0.17.2",
+    "@backstage/core-plugin-api": "1.10.7",
+    "@backstage/frontend-plugin-api": "0.10.3-next.0",
+    "@backstage/plugin-techdocs-common": "0.1.1-next.0",
+    "@backstage/version-bridge": "1.0.11",
     "@material-ui/core": "^4.12.2",
     "@material-ui/styles": "^4.11.0",
     "jss": "~10.10.0",
@@ -80,9 +81,9 @@
     "react-use": "^17.2.4"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.32.1",
-    "@backstage/test-utils": "^1.7.8",
-    "@backstage/theme": "^0.6.6",
+    "@backstage/cli": "0.32.1",
+    "@backstage/test-utils": "1.7.8",
+    "@backstage/theme": "0.6.6",
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.0.0",
     "@types/react": "^18.0.0",