diff --git a/plugins/tech-radar/api-report.md b/plugins/tech-radar/api-report.md index 452b241937..0961a3d7b6 100644 --- a/plugins/tech-radar/api-report.md +++ b/plugins/tech-radar/api-report.md @@ -9,138 +9,114 @@ import { ApiRef } from '@backstage/core-plugin-api'; import { BackstagePlugin } from '@backstage/core-plugin-api'; import { RouteRef } from '@backstage/core-plugin-api'; +// Warning: (ae-missing-release-tag) "MovedState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public +export enum MovedState { + Down = -1, + NoChange = 0, + Up = 1, +} + // Warning: (ae-missing-release-tag) "RadarEntry" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public export interface RadarEntry { - // (undocumented) description?: string; - // (undocumented) id: string; - // (undocumented) key: string; - // (undocumented) quadrant: string; - // (undocumented) timeline: Array; - // (undocumented) title: string; - // (undocumented) url: string; } // Warning: (ae-missing-release-tag) "RadarEntrySnapshot" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public export interface RadarEntrySnapshot { - // (undocumented) date: Date; - // (undocumented) description?: string; - // Warning: (ae-forgotten-export) The symbol "MovedState" needs to be exported by the entry point index.d.ts - // - // (undocumented) moved?: MovedState; - // (undocumented) ringId: string; } // Warning: (ae-missing-release-tag) "RadarQuadrant" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public export interface RadarQuadrant { - // (undocumented) id: string; - // (undocumented) name: string; } // Warning: (ae-missing-release-tag) "RadarRing" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public export interface RadarRing { - // (undocumented) color: string; - // (undocumented) id: string; - // (undocumented) name: string; } // Warning: (ae-missing-release-tag) "RadarPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) -export const Router: { - ({ title, subtitle, pageTitle, ...props }: TechRadarPageProps): JSX.Element; - defaultProps: { - title: string; - subtitle: string; - pageTitle: string; - }; -}; +// @public +export function Router(props: TechRadarPageProps): JSX.Element; // Warning: (ae-missing-release-tag) "TechRadarApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public export interface TechRadarApi { load: (id: string | undefined) => Promise; } // Warning: (ae-missing-release-tag) "techRadarApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public export const techRadarApiRef: ApiRef; // Warning: (ae-missing-release-tag) "RadarComponent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) -export const TechRadarComponent: ( - props: TechRadarComponentProps, -) => JSX.Element; +// @public +export function TechRadarComponent(props: TechRadarComponentProps): JSX.Element; // Warning: (ae-missing-release-tag) "TechRadarComponentProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public export interface TechRadarComponentProps { - // (undocumented) height: number; - // (undocumented) id?: string; - // (undocumented) searchText?: string; - // (undocumented) svgProps?: object; - // (undocumented) width: number; } // Warning: (ae-missing-release-tag) "TechRadarLoaderResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public export interface TechRadarLoaderResponse { - // (undocumented) entries: RadarEntry[]; - // (undocumented) quadrants: RadarQuadrant[]; - // (undocumented) rings: RadarRing[]; } // Warning: (ae-missing-release-tag) "TechRadarPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) -export const TechRadarPage: { - ({ title, subtitle, pageTitle, ...props }: TechRadarPageProps): JSX.Element; - defaultProps: { - title: string; - subtitle: string; - pageTitle: string; - }; +// @public +export const TechRadarPage: Router; + +// Warning: (ae-missing-release-tag) "TechRadarPageProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public +export type TechRadarPageProps = TechRadarComponentProps & { + title?: string; + subtitle?: string; + pageTitle?: string; }; // Warning: (ae-missing-release-tag) "techRadarPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public const techRadarPlugin: BackstagePlugin< { root: RouteRef; @@ -149,8 +125,4 @@ const techRadarPlugin: BackstagePlugin< >; export { techRadarPlugin as plugin }; export { techRadarPlugin }; - -// Warnings were encountered during analysis: -// -// src/components/RadarPage.d.ts:9:5 - (ae-forgotten-export) The symbol "TechRadarPageProps" needs to be exported by the entry point index.d.ts ``` diff --git a/plugins/tech-radar/src/api.ts b/plugins/tech-radar/src/api.ts index 2497834e22..82a476ddc4 100644 --- a/plugins/tech-radar/src/api.ts +++ b/plugins/tech-radar/src/api.ts @@ -13,15 +13,26 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +import { ApiRef, createApiRef } from '@backstage/core-plugin-api'; -import { MovedState } from './utils/types'; -import { createApiRef } from '@backstage/core-plugin-api'; - -export const techRadarApiRef = createApiRef({ - id: 'plugin.techradar.service', - description: 'Used to populate data in the TechRadar plugin', -}); +/** + * {@link @backstage/core-plugin-api#ApiRef} for the {@link TechRadarApi} + */ +export const techRadarApiRef: ApiRef = createApiRef( + { + id: 'plugin.techradar.service', + description: 'Used to populate data in the TechRadar plugin', + }, +); +/** + * Tech Radar API responsible for loading data for the plugin + * + * @remarks + * + * This should be implemented by user, as {@link https://github.com/backstage/backstage/blob/master/plugins/tech-radar/src/sample.ts | default} + * serves only some static data for example purposes + */ export interface TechRadarApi { /** * Loads the TechRadar response data to pass through to the TechRadar component. @@ -34,41 +45,139 @@ export interface TechRadarApi { * Types related to the Radar's visualization. */ +/** + * Tech Radar Ring which indicates stage of {@link RadarEntry} + */ export interface RadarRing { + /** + * ID of the Ring + */ id: string; + /** + * Display name of the Ring + */ name: string; + /** + * Color used for entries in particular Ring + * + * @remarks + * + * Supports any value parseable by {@link https://www.npmjs.com/package/color-string | color-string} + */ color: string; } +/** + * Tech Radar Quadrant which represent area/topic of {@link RadarEntry} + */ export interface RadarQuadrant { + /** + * ID of the Quadrant + */ id: string; + /** + * Display name of the Quadrant + */ name: string; } +/** + * Single Entry in Tech Radar + */ export interface RadarEntry { - key: string; // react key + /** + * React key to use for this Entry + */ + key: string; + /** + * ID of this Radar Entry + */ id: string; + /** + * ID of {@link RadarQuadrant} this Entry belongs to + */ quadrant: string; + /** + * Display name of the Entry + */ title: string; + /** + * User-clickable URL when rendered in Radar + * + * @remarks + * + * You can use `#` if you don't want to provide any other url + */ url: string; + /** + * History of the Entry moving through {@link RadarRing} + */ timeline: Array; + /** + * Description of the Entry + */ description?: string; } +/** + * State of {@link RadarEntry} at given point in time + */ export interface RadarEntrySnapshot { + /** + * Point in time when change happened + */ date: Date; + /** + * ID of {@link RadarRing} + */ ringId: string; + /** + * Description of change + */ description?: string; + /** + * Indicates trend compared to previous snapshot + */ moved?: MovedState; } +/** + * Indicates how {@link RadarEntry} moved though {@link RadarRing} on {@link RadarEntry.timeline} + */ +export enum MovedState { + /** + * Moved down + */ + Down = -1, + /** + * Didn't move + */ + NoChange = 0, + /** + * Move up + */ + Up = 1, +} + /* * Types related to data collection for the Radar. */ +/** + * Response from {@link TechRadarApi} + */ export interface TechRadarLoaderResponse { + /** + * Quadrant of Tech Radar. Should be 4 + */ quadrants: RadarQuadrant[]; + /** + * Rings of Tech Radar + */ rings: RadarRing[]; + /** + * Entries visualised in Tech Radar + */ entries: RadarEntry[]; } @@ -76,10 +185,50 @@ export interface TechRadarLoaderResponse { * Set up the Radar as a Backstage component. */ +/** + * Properties of {@link TechRadarComponent} + */ export interface TechRadarComponentProps { + /** + * ID of this Tech Radar + * + * @remarks + * + * Used when there are multiple Tech Radars and passed to {@link TechRadarApi.load} + */ id?: string; + /** + * Width of Tech Radar + */ width: number; + /** + * Height of Tech Radar + */ height: number; + /** + * Custom React props to the `` element created for Tech Radar + */ svgProps?: object; + /** + * Text to filter {@link RadarEntry} inside Tech Radar + */ searchText?: string; } + +/** + * Properties for {@link TechRadarPage} + */ +export type TechRadarPageProps = TechRadarComponentProps & { + /** + * Title + */ + title?: string; + /** + * Subtitle + */ + subtitle?: string; + /** + * Page Title + */ + pageTitle?: string; +}; diff --git a/plugins/tech-radar/src/components/RadarComponent.tsx b/plugins/tech-radar/src/components/RadarComponent.tsx index 9abb200792..0a001a6f42 100644 --- a/plugins/tech-radar/src/components/RadarComponent.tsx +++ b/plugins/tech-radar/src/components/RadarComponent.tsx @@ -64,7 +64,14 @@ function matchFilter(filter?: string): (entry: RadarEntry) => boolean { }; } -const RadarComponent = (props: TechRadarComponentProps): JSX.Element => { +/** + * Main React component of Tech Radar + * + * @remarks + * + * For advanced use cases. Typically, you want to use {@link TechRadarPage} + */ +function RadarComponent(props: TechRadarComponentProps) { const { loading, error, value: data } = useTechRadarLoader(props.id); const mapToEntries = ( @@ -106,6 +113,6 @@ const RadarComponent = (props: TechRadarComponentProps): JSX.Element => { )} ); -}; +} export default RadarComponent; diff --git a/plugins/tech-radar/src/components/RadarPage.tsx b/plugins/tech-radar/src/components/RadarPage.tsx index 8ae7d17fd0..a19b04d0ab 100644 --- a/plugins/tech-radar/src/components/RadarPage.tsx +++ b/plugins/tech-radar/src/components/RadarPage.tsx @@ -23,7 +23,7 @@ import { } from '@backstage/core-components'; import { Grid, Input, makeStyles } from '@material-ui/core'; import React from 'react'; -import { TechRadarComponentProps } from '../api'; +import { TechRadarPageProps } from '../api'; import RadarComponent from '../components/RadarComponent'; const useStyles = makeStyles(() => ({ @@ -32,18 +32,16 @@ const useStyles = makeStyles(() => ({ }, })); -export type TechRadarPageProps = TechRadarComponentProps & { - title?: string; - subtitle?: string; - pageTitle?: string; -}; - -export const RadarPage = ({ - title, - subtitle, - pageTitle, - ...props -}: TechRadarPageProps): JSX.Element => { +/** + * Main Page of Tech Radar + */ +export function RadarPage(props: TechRadarPageProps) { + const { + title = 'Tech Radar', + subtitle = 'Pick the recommended technologies for your projects', + pageTitle = 'Company Radar', + ...componentProps + } = props; const classes = useStyles(); const [searchText, setSearchText] = React.useState(''); @@ -66,16 +64,10 @@ export const RadarPage = ({ - + ); -}; - -RadarPage.defaultProps = { - title: 'Tech Radar', - subtitle: 'Pick the recommended technologies for your projects', - pageTitle: 'Company Radar', -}; +} diff --git a/plugins/tech-radar/src/index.ts b/plugins/tech-radar/src/index.ts index a2bbb95c2b..a2c9cc01a9 100644 --- a/plugins/tech-radar/src/index.ts +++ b/plugins/tech-radar/src/index.ts @@ -26,6 +26,9 @@ export { TechRadarPage, } from './plugin'; +/** + * @deprecated Use plugin extensions instead + */ export { RadarPage as Router } from './components/RadarPage'; /** diff --git a/plugins/tech-radar/src/plugin.ts b/plugins/tech-radar/src/plugin.ts index de8a82df3f..321cfcf72c 100644 --- a/plugins/tech-radar/src/plugin.ts +++ b/plugins/tech-radar/src/plugin.ts @@ -28,6 +28,9 @@ const rootRouteRef = createRouteRef({ title: 'Tech Radar', }); +/** + * Tech Radar plugin instance + */ export const techRadarPlugin = createPlugin({ id: 'tech-radar', routes: { @@ -36,6 +39,13 @@ export const techRadarPlugin = createPlugin({ apis: [createApiFactory(techRadarApiRef, new SampleTechRadarApi())], }); +/** + * Main Tech Radar Page + * + * @remarks + * + * Uses {@link TechRadarPageProps} as props + */ export const TechRadarPage = techRadarPlugin.provide( createRoutableExtension({ component: () => import('./components/RadarPage').then(m => m.RadarPage), diff --git a/plugins/tech-radar/src/utils/types.ts b/plugins/tech-radar/src/utils/types.ts index ff5ef05f93..8689b17678 100644 --- a/plugins/tech-radar/src/utils/types.ts +++ b/plugins/tech-radar/src/utils/types.ts @@ -13,6 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +import { MovedState } from '../api'; // Parameters for a ring; its index in an array determines how close to the center this ring is. export type Ring = { @@ -45,12 +46,6 @@ export type Segment = { random: Function; }; -export enum MovedState { - Down = -1, - NoChange = 0, - Up = 1, -} - export type Entry = { id: string; index?: number;