From ae717aa54c7681fb67fe1b861272d0036c78f2b6 Mon Sep 17 00:00:00 2001 From: Chris Suich Date: Mon, 28 Apr 2025 12:42:35 -0400 Subject: [PATCH] move helpers to techdocs-react Signed-off-by: Chris Suich --- .changeset/smooth-eels-think.md | 1 + plugins/catalog/package.json | 2 +- .../src/components/AboutCard/AboutCard.tsx | 2 +- plugins/techdocs-react/package.json | 1 + plugins/techdocs-react/src/helpers.ts | 67 ++++++++++++++++++- plugins/techdocs-react/src/index.ts | 7 +- plugins/techdocs/src/EntityPageDocs.tsx | 2 +- plugins/techdocs/src/helpers.ts | 65 ------------------ plugins/techdocs/src/index.ts | 3 - yarn.lock | 3 +- 10 files changed, 79 insertions(+), 74 deletions(-) diff --git a/.changeset/smooth-eels-think.md b/.changeset/smooth-eels-think.md index 33e711045c..ddae6dc151 100644 --- a/.changeset/smooth-eels-think.md +++ b/.changeset/smooth-eels-think.md @@ -1,5 +1,6 @@ --- '@backstage/plugin-techdocs': minor +'@backstage/plugin-techdocs-react': minor '@backstage/plugin-catalog': minor '@backstage/plugin-techdocs-common': patch --- diff --git a/plugins/catalog/package.json b/plugins/catalog/package.json index d9124f0077..2f8ea66134 100644 --- a/plugins/catalog/package.json +++ b/plugins/catalog/package.json @@ -72,7 +72,7 @@ "@backstage/plugin-scaffolder-common": "workspace:^", "@backstage/plugin-search-common": "workspace:^", "@backstage/plugin-search-react": "workspace:^", - "@backstage/plugin-techdocs": "workspace:^", + "@backstage/plugin-techdocs-react": "workspace:^", "@backstage/types": "workspace:^", "@backstage/version-bridge": "workspace:^", "@material-ui/core": "^4.12.2", diff --git a/plugins/catalog/src/components/AboutCard/AboutCard.tsx b/plugins/catalog/src/components/AboutCard/AboutCard.tsx index 4d8421932b..46bc239ffa 100644 --- a/plugins/catalog/src/components/AboutCard/AboutCard.tsx +++ b/plugins/catalog/src/components/AboutCard/AboutCard.tsx @@ -64,7 +64,7 @@ import { taskCreatePermission } from '@backstage/plugin-scaffolder-common/alpha' import { usePermission } from '@backstage/plugin-permission-react'; import { catalogTranslationRef } from '../../alpha/translation'; import { useTranslationRef } from '@backstage/core-plugin-api/alpha'; -import { buildTechDocsURL } from '@backstage/plugin-techdocs'; +import { buildTechDocsURL } from '@backstage/plugin-techdocs-react'; const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref'; diff --git a/plugins/techdocs-react/package.json b/plugins/techdocs-react/package.json index f6dc740ee7..6c7166f997 100644 --- a/plugins/techdocs-react/package.json +++ b/plugins/techdocs-react/package.json @@ -63,6 +63,7 @@ "@backstage/core-components": "workspace:^", "@backstage/core-plugin-api": "workspace:^", "@backstage/frontend-plugin-api": "workspace:^", + "@backstage/plugin-techdocs-common": "workspace:^", "@backstage/version-bridge": "workspace:^", "@material-ui/core": "^4.12.2", "@material-ui/styles": "^4.11.0", diff --git a/plugins/techdocs-react/src/helpers.ts b/plugins/techdocs-react/src/helpers.ts index 3f10fff2ba..8e3a6b5e7d 100644 --- a/plugins/techdocs-react/src/helpers.ts +++ b/plugins/techdocs-react/src/helpers.ts @@ -15,7 +15,23 @@ */ import { Config } from '@backstage/config'; -import { CompoundEntityRef } from '@backstage/catalog-model'; +import { + CompoundEntityRef, + DEFAULT_NAMESPACE, + Entity, + parseEntityRef, +} from '@backstage/catalog-model'; +import { + TECHDOCS_EXTERNAL_ANNOTATION, + TECHDOCS_EXTERNAL_PATH_ANNOTATION, +} from '@backstage/plugin-techdocs-common'; +import { RouteFunc } from '@backstage/core-plugin-api'; + +export type TechDocsRouteFunc = RouteFunc<{ + namespace: string; + kind: string; + name: string; +}>; /** * Lower-case entity triplets by default, but allow override. @@ -35,3 +51,52 @@ export function toLowercaseEntityRefMaybe( return entityRef; } + +export function getEntityRootTechDocsPath(entity: Entity): string { + let path = entity.metadata.annotations?.[TECHDOCS_EXTERNAL_PATH_ANNOTATION]; + if (!path) { + return ''; + } + if (!path.startsWith('/')) { + path = `/${path}`; + } + return path; +} + +export const buildTechDocsURL = ( + entity: Entity, + routeFunc: TechDocsRouteFunc | undefined, +) => { + if (!routeFunc) { + return undefined; + } + + let namespace = entity.metadata.namespace || DEFAULT_NAMESPACE; + let kind = entity.kind; + let name = entity.metadata.name; + + 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 { + // not a fan of this but we don't care if the parseEntityRef fails + } + } + + const url = routeFunc({ + namespace, + kind, + name, + }); + + // Add on the external entity path to the url if one exists. This allows deep linking into another + // entities TechDocs. + const path = getEntityRootTechDocsPath(entity); + + return `${url}${path}`; +}; diff --git a/plugins/techdocs-react/src/index.ts b/plugins/techdocs-react/src/index.ts index 5cbab1a326..6b0e228a27 100644 --- a/plugins/techdocs-react/src/index.ts +++ b/plugins/techdocs-react/src/index.ts @@ -52,4 +52,9 @@ export { useShadowRootElements, useShadowRootSelection, } from './hooks'; -export { toLowercaseEntityRefMaybe } from './helpers'; +export { + toLowercaseEntityRefMaybe, + getEntityRootTechDocsPath, + buildTechDocsURL, +} from './helpers'; +export type { TechDocsRouteFunc } from './helpers'; diff --git a/plugins/techdocs/src/EntityPageDocs.tsx b/plugins/techdocs/src/EntityPageDocs.tsx index a88ec8275d..14dcb00d29 100644 --- a/plugins/techdocs/src/EntityPageDocs.tsx +++ b/plugins/techdocs/src/EntityPageDocs.tsx @@ -20,12 +20,12 @@ import { parseEntityRef, } from '@backstage/catalog-model'; import { TECHDOCS_EXTERNAL_ANNOTATION } from '@backstage/plugin-techdocs-common'; +import { getEntityRootTechDocsPath } from '@backstage/plugin-techdocs-react'; import { TechDocsReaderPage } from './plugin'; import { TechDocsReaderPageContent } from './reader/components/TechDocsReaderPageContent'; import { TechDocsReaderPageSubheader } from './reader/components/TechDocsReaderPageSubheader'; import { useEntityPageTechDocsRedirect } from './search/hooks/useTechDocsLocation'; -import { getEntityRootTechDocsPath } from './helpers'; type EntityPageDocsProps = { entity: Entity; diff --git a/plugins/techdocs/src/helpers.ts b/plugins/techdocs/src/helpers.ts index 4b525445d7..7ff4dec6e7 100644 --- a/plugins/techdocs/src/helpers.ts +++ b/plugins/techdocs/src/helpers.ts @@ -14,23 +14,7 @@ * limitations under the License. */ -import { - DEFAULT_NAMESPACE, - Entity, - parseEntityRef, -} from '@backstage/catalog-model'; import { Config } from '@backstage/config'; -import { - TECHDOCS_EXTERNAL_ANNOTATION, - TECHDOCS_EXTERNAL_PATH_ANNOTATION, -} from '@backstage/plugin-techdocs-common'; -import { RouteFunc } from '@backstage/core-plugin-api'; - -export type TechDocsRouteFunc = RouteFunc<{ - namespace: string; - kind: string; - name: string; -}>; // Lower-case entity triplets by default, but allow override. export function toLowerMaybe(str: string, config: Config) { @@ -40,52 +24,3 @@ export function toLowerMaybe(str: string, config: Config) { ? str : str.toLocaleLowerCase('en-US'); } - -export function getEntityRootTechDocsPath(entity: Entity): string { - let path = entity.metadata.annotations?.[TECHDOCS_EXTERNAL_PATH_ANNOTATION]; - if (!path) { - return ''; - } - if (!path.startsWith('/')) { - path = `/${path}`; - } - return path; -} - -export const buildTechDocsURL = ( - entity: Entity, - routeFunc: TechDocsRouteFunc | undefined, -) => { - if (!routeFunc) { - return undefined; - } - - let namespace = entity.metadata.namespace || DEFAULT_NAMESPACE; - let kind = entity.kind; - let name = entity.metadata.name; - - 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 { - // not a fan of this but we don't care if the parseEntityRef fails - } - } - - const url = routeFunc({ - namespace, - kind, - name, - }); - - // Add on the external entity path to the url if one exists. This allows deep linking into another - // entities TechDocs. - const path = getEntityRootTechDocsPath(entity); - - return `${url}${path}`; -}; diff --git a/plugins/techdocs/src/index.ts b/plugins/techdocs/src/index.ts index e7cefa6437..713efc17c6 100644 --- a/plugins/techdocs/src/index.ts +++ b/plugins/techdocs/src/index.ts @@ -46,7 +46,6 @@ export { LegacyEmbeddedDocsRouter as EmbeddedDocsRouter, Router, } from './Router'; -export { buildTechDocsURL, getEntityRootTechDocsPath } from './helpers'; export type { TechDocsSearchResultListItemProps } from './search/components/TechDocsSearchResultListItem'; @@ -70,5 +69,3 @@ export type { }; export * from './overridableComponents'; - -export type { TechDocsRouteFunc } from './helpers'; diff --git a/yarn.lock b/yarn.lock index 7e61c3ca48..c54f62e4b6 100644 --- a/yarn.lock +++ b/yarn.lock @@ -6355,7 +6355,7 @@ __metadata: "@backstage/plugin-scaffolder-common": "workspace:^" "@backstage/plugin-search-common": "workspace:^" "@backstage/plugin-search-react": "workspace:^" - "@backstage/plugin-techdocs": "workspace:^" + "@backstage/plugin-techdocs-react": "workspace:^" "@backstage/test-utils": "workspace:^" "@backstage/types": "workspace:^" "@backstage/version-bridge": "workspace:^" @@ -8504,6 +8504,7 @@ __metadata: "@backstage/core-components": "workspace:^" "@backstage/core-plugin-api": "workspace:^" "@backstage/frontend-plugin-api": "workspace:^" + "@backstage/plugin-techdocs-common": "workspace:^" "@backstage/test-utils": "workspace:^" "@backstage/theme": "workspace:^" "@backstage/version-bridge": "workspace:^"