From 542b83963197d39c10d5ffffc213ee217022be30 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:28:41 +0100 Subject: [PATCH 01/22] change naming of DocsResultListItem -> TechDocsSearchResultListItem to follow pattern Signed-off-by: Emma Indal --- .../app/src/components/search/SearchPage.tsx | 4 +- .../app/src/components/search/SearchPage.tsx | 4 +- .../components/DocsResultListItem/index.ts | 17 --------- .../TechDocsSearchResultListItem.test.tsx} | 15 +++++--- .../TechDocsSearchResultListItem.tsx} | 37 +++++++++++++++---- 5 files changed, 43 insertions(+), 34 deletions(-) delete mode 100644 plugins/techdocs/src/components/DocsResultListItem/index.ts rename plugins/techdocs/src/{components/DocsResultListItem/DocsResultListItem.test.tsx => search/components/TechDocsSearchResultListItem.test.tsx} (84%) rename plugins/techdocs/src/{components/DocsResultListItem/DocsResultListItem.tsx => search/components/TechDocsSearchResultListItem.tsx} (78%) diff --git a/packages/app/src/components/search/SearchPage.tsx b/packages/app/src/components/search/SearchPage.tsx index fe759c9799..65da72d91c 100644 --- a/packages/app/src/components/search/SearchPage.tsx +++ b/packages/app/src/components/search/SearchPage.tsx @@ -38,7 +38,7 @@ import { SearchType, useSearch, } from '@backstage/plugin-search'; -import { DocsResultListItem } from '@backstage/plugin-techdocs'; +import { TechDocsSearchResultListItem } from '@backstage/plugin-techdocs'; import { Grid, List, makeStyles, Paper, Theme } from '@material-ui/core'; import React, { useContext } from 'react'; @@ -143,7 +143,7 @@ const SearchPage = () => { ); case 'techdocs': return ( - diff --git a/packages/create-app/templates/default-app/packages/app/src/components/search/SearchPage.tsx b/packages/create-app/templates/default-app/packages/app/src/components/search/SearchPage.tsx index 469a230ecd..cd4603ecd3 100644 --- a/packages/create-app/templates/default-app/packages/app/src/components/search/SearchPage.tsx +++ b/packages/create-app/templates/default-app/packages/app/src/components/search/SearchPage.tsx @@ -6,7 +6,7 @@ import { catalogApiRef, CATALOG_FILTER_EXISTS, } from '@backstage/plugin-catalog-react'; -import { DocsResultListItem } from '@backstage/plugin-techdocs'; +import { TechDocsSearchResultListItem } from '@backstage/plugin-techdocs'; import { SearchBar, @@ -123,7 +123,7 @@ const SearchPage = () => { ); case 'techdocs': return ( - diff --git a/plugins/techdocs/src/components/DocsResultListItem/index.ts b/plugins/techdocs/src/components/DocsResultListItem/index.ts deleted file mode 100644 index 4e1e511ea1..0000000000 --- a/plugins/techdocs/src/components/DocsResultListItem/index.ts +++ /dev/null @@ -1,17 +0,0 @@ -/* - * Copyright 2021 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 { DocsResultListItem } from './DocsResultListItem'; diff --git a/plugins/techdocs/src/components/DocsResultListItem/DocsResultListItem.test.tsx b/plugins/techdocs/src/search/components/TechDocsSearchResultListItem.test.tsx similarity index 84% rename from plugins/techdocs/src/components/DocsResultListItem/DocsResultListItem.test.tsx rename to plugins/techdocs/src/search/components/TechDocsSearchResultListItem.test.tsx index 807914c5ad..7ebdd6c340 100644 --- a/plugins/techdocs/src/components/DocsResultListItem/DocsResultListItem.test.tsx +++ b/plugins/techdocs/src/search/components/TechDocsSearchResultListItem.test.tsx @@ -16,7 +16,7 @@ import React from 'react'; import { render } from '@testing-library/react'; -import { DocsResultListItem } from './DocsResultListItem'; +import { TechDocsSearchResultListItem } from './TechDocsSearchResultListItem'; // Using canvas to render text.. jest.mock('react-text-truncate', () => { @@ -44,9 +44,11 @@ const validResultWithTitle = { lifecycle: 'production', }; -describe('DocsResultListItem test', () => { +describe('TechDocsSearchResultListItem test', () => { it('should render search doc passed in', async () => { - const { findByText } = render(); + const { findByText } = render( + , + ); expect( await findByText('Documentation | Backstage docs'), @@ -60,7 +62,10 @@ describe('DocsResultListItem test', () => { it('should use title if defined', async () => { const { findByText } = render( - , + , ); expect(await findByText('Count Dookumentation')).toBeInTheDocument(); @@ -73,7 +78,7 @@ describe('DocsResultListItem test', () => { it('should use entity title if defined', async () => { const { findByText } = render( - , + , ); expect( diff --git a/plugins/techdocs/src/components/DocsResultListItem/DocsResultListItem.tsx b/plugins/techdocs/src/search/components/TechDocsSearchResultListItem.tsx similarity index 78% rename from plugins/techdocs/src/components/DocsResultListItem/DocsResultListItem.tsx rename to plugins/techdocs/src/search/components/TechDocsSearchResultListItem.tsx index 03cf011c32..152fa2e3d3 100644 --- a/plugins/techdocs/src/components/DocsResultListItem/DocsResultListItem.tsx +++ b/plugins/techdocs/src/search/components/TechDocsSearchResultListItem.tsx @@ -29,19 +29,34 @@ const useStyles = makeStyles({ }, }); -export const DocsResultListItem = ({ - result, - lineClamp = 5, - asListItem = true, - asLink = true, - title, -}: { +/** + * Props for {@link TechDocsSearchResultListItem}. + * + * @public + */ +export type TechDocsSearchResultListItemProps = { result: any; lineClamp?: number; asListItem?: boolean; asLink?: boolean; title?: string; -}) => { +}; + +/** + * Component which renders documentation and related metadata. + * + * @public + */ +export const TechDocsSearchResultListItem = ( + props: TechDocsSearchResultListItemProps, +) => { + const { + result, + lineClamp = 5, + asListItem = true, + asLink = true, + title, + } = props; const classes = useStyles(); const TextItem = () => ( ); }; + +/** + * @public + * @deprecated use {@link TechDocsSearchResultListItem} instead + */ +export const DocsResultListItem = TechDocsSearchResultListItem; From 505adf271ab49f08467560a3d13c7df0824bae75 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:30:41 +0100 Subject: [PATCH 02/22] move TechDocsSearch into search components Signed-off-by: Emma Indal --- .../components/TechDocsSearch.test.tsx | 2 +- .../components/TechDocsSearch.tsx | 22 +++++++++++++------ 2 files changed, 16 insertions(+), 8 deletions(-) rename plugins/techdocs/src/{reader => search}/components/TechDocsSearch.test.tsx (99%) rename plugins/techdocs/src/{reader => search}/components/TechDocsSearch.tsx (92%) diff --git a/plugins/techdocs/src/reader/components/TechDocsSearch.test.tsx b/plugins/techdocs/src/search/components/TechDocsSearch.test.tsx similarity index 99% rename from plugins/techdocs/src/reader/components/TechDocsSearch.test.tsx rename to plugins/techdocs/src/search/components/TechDocsSearch.test.tsx index b4233734aa..06d5ac6aac 100644 --- a/plugins/techdocs/src/reader/components/TechDocsSearch.test.tsx +++ b/plugins/techdocs/src/search/components/TechDocsSearch.test.tsx @@ -48,7 +48,7 @@ const singleResult = Promise.resolve({ ], }); -describe('', () => { +describe('', () => { it('should render techdocs search bar', async () => { const query = () => emptyResults; const querySpy = jest.fn(query); diff --git a/plugins/techdocs/src/reader/components/TechDocsSearch.tsx b/plugins/techdocs/src/search/components/TechDocsSearch.tsx similarity index 92% rename from plugins/techdocs/src/reader/components/TechDocsSearch.tsx rename to plugins/techdocs/src/search/components/TechDocsSearch.tsx index 6c0be16f4f..74e2ac554e 100644 --- a/plugins/techdocs/src/reader/components/TechDocsSearch.tsx +++ b/plugins/techdocs/src/search/components/TechDocsSearch.tsx @@ -28,7 +28,7 @@ import Autocomplete from '@material-ui/lab/Autocomplete'; import React, { ChangeEvent, useEffect, useState } from 'react'; import { useNavigate } from 'react-router'; import useDebounce from 'react-use/lib/useDebounce'; -import { DocsResultListItem } from '../../components/DocsResultListItem'; +import { TechDocsSearchResultListItem } from '../../search'; const useStyles = makeStyles({ root: { @@ -36,7 +36,12 @@ const useStyles = makeStyles({ }, }); -type TechDocsSearchProps = { +/** + * Props for {@link TechDocsSearch} + * + * @public + */ +export type TechDocsSearchProps = { entityId: EntityName; debounceTime?: number; }; @@ -55,10 +60,8 @@ type TechDocsSearchResult = { document: TechDocsDoc; }; -const TechDocsSearchBar = ({ - entityId, - debounceTime = 150, -}: TechDocsSearchProps) => { +const TechDocsSearchBar = (props: TechDocsSearchProps) => { + const { entityId, debounceTime = 150 } = props; const [open, setOpen] = useState(false); const navigate = useNavigate(); const { @@ -138,7 +141,7 @@ const TechDocsSearchBar = ({ value={null} options={options} renderOption={({ document }) => ( - { const initialState = { term: '', From 5a85ef7f3f92142c9a589057dbd717c6659936c7 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:33:45 +0100 Subject: [PATCH 03/22] improve project structure for home Table + Grid components Signed-off-by: Emma Indal --- .../{ => Grids}/DocsCardGrid.test.tsx | 2 +- .../components/{ => Grids}/DocsCardGrid.tsx | 15 ++++++----- .../{ => Grids}/EntityListDocsGrid.tsx | 8 +++++- .../src/home/components/Grids/index.ts | 18 +++++++++++++ .../{ => Tables}/DocsTable.test.tsx | 2 +- .../components/{ => Tables}/DocsTable.tsx | 27 ++++++++++++------- .../{ => Tables}/EntityListDocsTable.tsx | 20 ++++++++++---- .../home/components/{ => Tables}/actions.tsx | 12 +++++++++ .../home/components/{ => Tables}/columns.tsx | 15 +++++++++++ .../src/home/components/Tables/index.ts | 19 +++++++++++++ .../src/home/components/{ => Tables}/types.ts | 5 ++++ plugins/techdocs/src/home/index.ts | 17 ++++++++++++ 12 files changed, 136 insertions(+), 24 deletions(-) rename plugins/techdocs/src/home/components/{ => Grids}/DocsCardGrid.test.tsx (98%) rename plugins/techdocs/src/home/components/{ => Grids}/DocsCardGrid.tsx (91%) rename plugins/techdocs/src/home/components/{ => Grids}/EntityListDocsGrid.tsx (92%) create mode 100644 plugins/techdocs/src/home/components/Grids/index.ts rename plugins/techdocs/src/home/components/{ => Tables}/DocsTable.test.tsx (99%) rename plugins/techdocs/src/home/components/{ => Tables}/DocsTable.tsx (90%) rename plugins/techdocs/src/home/components/{ => Tables}/EntityListDocsTable.tsx (87%) rename plugins/techdocs/src/home/components/{ => Tables}/actions.tsx (88%) rename plugins/techdocs/src/home/components/{ => Tables}/columns.tsx (85%) create mode 100644 plugins/techdocs/src/home/components/Tables/index.ts rename plugins/techdocs/src/home/components/{ => Tables}/types.ts (90%) create mode 100644 plugins/techdocs/src/home/index.ts diff --git a/plugins/techdocs/src/home/components/DocsCardGrid.test.tsx b/plugins/techdocs/src/home/components/Grids/DocsCardGrid.test.tsx similarity index 98% rename from plugins/techdocs/src/home/components/DocsCardGrid.test.tsx rename to plugins/techdocs/src/home/components/Grids/DocsCardGrid.test.tsx index e52636a54a..311f83544a 100644 --- a/plugins/techdocs/src/home/components/DocsCardGrid.test.tsx +++ b/plugins/techdocs/src/home/components/Grids/DocsCardGrid.test.tsx @@ -18,7 +18,7 @@ import { configApiRef } from '@backstage/core-plugin-api'; import { wrapInTestApp } from '@backstage/test-utils'; import { render } from '@testing-library/react'; import React from 'react'; -import { rootDocsRouteRef } from '../../routes'; +import { rootDocsRouteRef } from '../../../routes'; import { DocsCardGrid } from './DocsCardGrid'; // Hacky way to mock a specific boolean config value. diff --git a/plugins/techdocs/src/home/components/DocsCardGrid.tsx b/plugins/techdocs/src/home/components/Grids/DocsCardGrid.tsx similarity index 91% rename from plugins/techdocs/src/home/components/DocsCardGrid.tsx rename to plugins/techdocs/src/home/components/Grids/DocsCardGrid.tsx index 1aef793bd2..6ec500e199 100644 --- a/plugins/techdocs/src/home/components/DocsCardGrid.tsx +++ b/plugins/techdocs/src/home/components/Grids/DocsCardGrid.tsx @@ -14,20 +14,23 @@ * limitations under the License. */ -import React from 'react'; - +import { rootDocsRouteRef } from '../../../routes'; +import { toLowerMaybe } from '../../../helpers'; import { Entity } from '@backstage/catalog-model'; import { useApi, useRouteRef, configApiRef } from '@backstage/core-plugin-api'; -import { Card, CardActions, CardContent, CardMedia } from '@material-ui/core'; -import { rootDocsRouteRef } from '../../routes'; - import { Button, ItemCardGrid, ItemCardHeader, } from '@backstage/core-components'; -import { toLowerMaybe } from '../../helpers'; +import { Card, CardActions, CardContent, CardMedia } from '@material-ui/core'; +import React from 'react'; +/** + * Component which accepts a list of entities and renders a item card for each entity + * + * @public + */ export const DocsCardGrid = ({ entities, }: { diff --git a/plugins/techdocs/src/home/components/EntityListDocsGrid.tsx b/plugins/techdocs/src/home/components/Grids/EntityListDocsGrid.tsx similarity index 92% rename from plugins/techdocs/src/home/components/EntityListDocsGrid.tsx rename to plugins/techdocs/src/home/components/Grids/EntityListDocsGrid.tsx index 11fb71961c..348104f5cc 100644 --- a/plugins/techdocs/src/home/components/EntityListDocsGrid.tsx +++ b/plugins/techdocs/src/home/components/Grids/EntityListDocsGrid.tsx @@ -13,6 +13,8 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + +import { DocsCardGrid } from './DocsCardGrid'; import { CodeSnippet, Progress, @@ -20,8 +22,12 @@ import { } from '@backstage/core-components'; import { useEntityList } from '@backstage/plugin-catalog-react'; import React from 'react'; -import { DocsCardGrid } from './DocsCardGrid'; +/** + * Component responsible to get entities from entity list context and pass down to DocsCardGrid + * + * @public + */ export const EntityListDocsGrid = () => { const { loading, error, entities } = useEntityList(); diff --git a/plugins/techdocs/src/home/components/Grids/index.ts b/plugins/techdocs/src/home/components/Grids/index.ts new file mode 100644 index 0000000000..c28b5a0723 --- /dev/null +++ b/plugins/techdocs/src/home/components/Grids/index.ts @@ -0,0 +1,18 @@ +/* + * Copyright 2022 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 './EntityListDocsGrid'; +export * from './DocsCardGrid'; diff --git a/plugins/techdocs/src/home/components/DocsTable.test.tsx b/plugins/techdocs/src/home/components/Tables/DocsTable.test.tsx similarity index 99% rename from plugins/techdocs/src/home/components/DocsTable.test.tsx rename to plugins/techdocs/src/home/components/Tables/DocsTable.test.tsx index 9586cfb2ef..730354f253 100644 --- a/plugins/techdocs/src/home/components/DocsTable.test.tsx +++ b/plugins/techdocs/src/home/components/Tables/DocsTable.test.tsx @@ -18,7 +18,7 @@ import { render } from '@testing-library/react'; import { wrapInTestApp } from '@backstage/test-utils'; import { configApiRef } from '@backstage/core-plugin-api'; import { DocsTable } from './DocsTable'; -import { rootDocsRouteRef } from '../../routes'; +import { rootDocsRouteRef } from '../../../routes'; import { entityRouteRef } from '@backstage/plugin-catalog-react'; // Hacky way to mock a specific boolean config value. diff --git a/plugins/techdocs/src/home/components/DocsTable.tsx b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx similarity index 90% rename from plugins/techdocs/src/home/components/DocsTable.tsx rename to plugins/techdocs/src/home/components/Tables/DocsTable.tsx index a00d608b0f..cbc8ddc0b9 100644 --- a/plugins/techdocs/src/home/components/DocsTable.tsx +++ b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx @@ -23,7 +23,7 @@ import { formatEntityRefTitle, getEntityRelations, } from '@backstage/plugin-catalog-react'; -import { rootDocsRouteRef } from '../../routes'; +import { rootDocsRouteRef } from '../../../routes'; import { Button, EmptyState, @@ -33,22 +33,29 @@ import { } from '@backstage/core-components'; import * as actionFactories from './actions'; import * as columnFactories from './columns'; +import { toLowerMaybe } from '../../../helpers'; import { DocsTableRow } from './types'; -import { toLowerMaybe } from '../../helpers'; -export const DocsTable = ({ - entities, - title, - loading, - columns, - actions, -}: { +/** + * Props for {@link DocsTable}. + * + * @public + */ +export type DocsTableProps = { entities: Entity[] | undefined; title?: string | undefined; loading?: boolean | undefined; columns?: TableColumn[]; actions?: TableProps['actions']; -}) => { +}; + +/** + * Component which renders a table documents + * + * @public + */ +export const DocsTable = (props: DocsTableProps) => { + const { entities, title, loading, columns, actions } = props; const [, copyToClipboard] = useCopyToClipboard(); const getRouteToReaderPageFor = useRouteRef(rootDocsRouteRef); const config = useApi(configApiRef); diff --git a/plugins/techdocs/src/home/components/EntityListDocsTable.tsx b/plugins/techdocs/src/home/components/Tables/EntityListDocsTable.tsx similarity index 87% rename from plugins/techdocs/src/home/components/EntityListDocsTable.tsx rename to plugins/techdocs/src/home/components/Tables/EntityListDocsTable.tsx index fa99622885..a963d53428 100644 --- a/plugins/techdocs/src/home/components/EntityListDocsTable.tsx +++ b/plugins/techdocs/src/home/components/Tables/EntityListDocsTable.tsx @@ -32,13 +32,23 @@ import * as actionFactories from './actions'; import * as columnFactories from './columns'; import { DocsTableRow } from './types'; -export const EntityListDocsTable = ({ - columns, - actions, -}: { +/** + * Props for {@link EntityListDocsTable}. + * + * @public + */ +export type EntityListDocsTableProps = { columns?: TableColumn[]; actions?: TableProps['actions']; -}) => { +}; + +/** + * Component which renders a table with entities from catalog. + * + * @public + */ +export const EntityListDocsTable = (props: EntityListDocsTableProps) => { + const { columns, actions } = props; const { loading, error, entities, filters } = useEntityList(); const { isStarredEntity, toggleStarredEntity } = useStarredEntities(); const [, copyToClipboard] = useCopyToClipboard(); diff --git a/plugins/techdocs/src/home/components/actions.tsx b/plugins/techdocs/src/home/components/Tables/actions.tsx similarity index 88% rename from plugins/techdocs/src/home/components/actions.tsx rename to plugins/techdocs/src/home/components/Tables/actions.tsx index eb09c1d429..4e86fb1b89 100644 --- a/plugins/techdocs/src/home/components/actions.tsx +++ b/plugins/techdocs/src/home/components/Tables/actions.tsx @@ -22,6 +22,12 @@ import { } from '@backstage/plugin-catalog-react'; import { DocsTableRow } from './types'; +/** + * Utility function for creating a copy docs url action for {@link DocsTable}. + * + * @internal + */ + export function createCopyDocsUrlAction(copyToClipboard: Function) { return (row: DocsTableRow) => { return { @@ -33,6 +39,12 @@ export function createCopyDocsUrlAction(copyToClipboard: Function) { }; } +/** + * Utility function for creating a star entity action for {@link DocsTable}. + * + * @internal + */ + export function createStarEntityAction( isStarredEntity: Function, toggleStarredEntity: Function, diff --git a/plugins/techdocs/src/home/components/columns.tsx b/plugins/techdocs/src/home/components/Tables/columns.tsx similarity index 85% rename from plugins/techdocs/src/home/components/columns.tsx rename to plugins/techdocs/src/home/components/Tables/columns.tsx index d29f44da75..6f41ccb1d6 100644 --- a/plugins/techdocs/src/home/components/columns.tsx +++ b/plugins/techdocs/src/home/components/Tables/columns.tsx @@ -24,6 +24,11 @@ function customTitle(entity: Entity): string { return entity.metadata.title || entity.metadata.name; } +/** + * Utility function for creating a name column for {@link DocsTable}. + * + * @internal + */ export function createNameColumn(): TableColumn { return { title: 'Document', @@ -38,6 +43,11 @@ export function createNameColumn(): TableColumn { }; } +/** + * Utility function for creating an owner column for {@link DocsTable}. + * + * @internal + */ export function createOwnerColumn(): TableColumn { return { title: 'Owner', @@ -51,6 +61,11 @@ export function createOwnerColumn(): TableColumn { }; } +/** + * Utility function for creating an spec type column for {@link DocsTable}. + * + * @internal + */ export function createTypeColumn(): TableColumn { return { title: 'Type', diff --git a/plugins/techdocs/src/home/components/Tables/index.ts b/plugins/techdocs/src/home/components/Tables/index.ts new file mode 100644 index 0000000000..2db7f0ae89 --- /dev/null +++ b/plugins/techdocs/src/home/components/Tables/index.ts @@ -0,0 +1,19 @@ +/* + * Copyright 2022 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 './EntityListDocsTable'; +export * from './DocsTable'; +export * from './types'; diff --git a/plugins/techdocs/src/home/components/types.ts b/plugins/techdocs/src/home/components/Tables/types.ts similarity index 90% rename from plugins/techdocs/src/home/components/types.ts rename to plugins/techdocs/src/home/components/Tables/types.ts index 6fd29f1716..c076d4c12d 100644 --- a/plugins/techdocs/src/home/components/types.ts +++ b/plugins/techdocs/src/home/components/Tables/types.ts @@ -16,6 +16,11 @@ import { Entity, EntityName } from '@backstage/catalog-model'; +/** + * Generic representing the metadata structure for a docs table row. + * + * @public + */ export type DocsTableRow = { entity: Entity; resolved: { diff --git a/plugins/techdocs/src/home/index.ts b/plugins/techdocs/src/home/index.ts new file mode 100644 index 0000000000..1be7f65c25 --- /dev/null +++ b/plugins/techdocs/src/home/index.ts @@ -0,0 +1,17 @@ +/* + * Copyright 2022 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 './components'; From fc9e6643292604808a5701cfb369de0f3ac1f36f Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:35:05 +0100 Subject: [PATCH 04/22] improve naming of techdocs reader page component, to avoid exporting two with same name Signed-off-by: Emma Indal --- ...e.test.tsx => TechDocsReaderPage.test.tsx} | 10 ++--- ...echDocsPage.tsx => TechDocsReaderPage.tsx} | 37 +++++++++++++++++-- 2 files changed, 38 insertions(+), 9 deletions(-) rename plugins/techdocs/src/reader/components/{TechDocsPage.test.tsx => TechDocsReaderPage.test.tsx} (96%) rename plugins/techdocs/src/reader/components/{TechDocsPage.tsx => TechDocsReaderPage.tsx} (75%) diff --git a/plugins/techdocs/src/reader/components/TechDocsPage.test.tsx b/plugins/techdocs/src/reader/components/TechDocsReaderPage.test.tsx similarity index 96% rename from plugins/techdocs/src/reader/components/TechDocsPage.test.tsx rename to plugins/techdocs/src/reader/components/TechDocsReaderPage.test.tsx index b297466a62..76bf195489 100644 --- a/plugins/techdocs/src/reader/components/TechDocsPage.test.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsReaderPage.test.tsx @@ -14,7 +14,7 @@ * limitations under the License. */ import React from 'react'; -import { TechDocsPage } from './TechDocsPage'; +import { TechDocsReaderPage } from './TechDocsReaderPage'; import { render, act } from '@testing-library/react'; import { ConfigReader } from '@backstage/config'; import { @@ -51,7 +51,7 @@ const { useParams }: { useParams: jest.Mock } = jest.requireMock('react-router-dom'); global.scroll = jest.fn(); -describe('', () => { +describe('', () => { it('should render techdocs page', async () => { useParams.mockReturnValue({ entityRef: 'Component::backstage', @@ -101,7 +101,7 @@ describe('', () => { const rendered = render( wrapInTestApp( - + , ), ); @@ -158,7 +158,7 @@ describe('', () => { const rendered = render( wrapInTestApp( - + {({ techdocsMetadataValue }) => (
', () => { subtitle={techdocsMetadataValue?.site_name} /> )} - + , ), ); diff --git a/plugins/techdocs/src/reader/components/TechDocsPage.tsx b/plugins/techdocs/src/reader/components/TechDocsReaderPage.tsx similarity index 75% rename from plugins/techdocs/src/reader/components/TechDocsPage.tsx rename to plugins/techdocs/src/reader/components/TechDocsReaderPage.tsx index d96bed6b60..eea6b94d3d 100644 --- a/plugins/techdocs/src/reader/components/TechDocsPage.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsReaderPage.tsx @@ -25,7 +25,12 @@ import { EntityName } from '@backstage/catalog-model'; import { useApi, useApp } from '@backstage/core-plugin-api'; import { Page } from '@backstage/core-components'; -export type TechDocsPageRenderFunction = ({ +/** + * Helper function that gives the children of {@link TechDocsReaderPage} acccess to techdocs and entity metadata + * + * @public + */ +export type TechDocsReaderPageRenderFunction = ({ techdocsMetadataValue, entityMetadataValue, entityRef, @@ -36,11 +41,22 @@ export type TechDocsPageRenderFunction = ({ onReady: () => void; }) => JSX.Element; -export type TechDocsPageProps = { - children?: TechDocsPageRenderFunction | React.ReactNode; +/** + * Props for {@link TechDocsReaderPage} + * + * @public + */ +export type TechDocsReaderPageProps = { + children?: TechDocsReaderPageRenderFunction | React.ReactNode; }; -export const TechDocsPage = ({ children }: TechDocsPageProps) => { +/** + * Component responsible for composing a TechDocs reader page experience + * + * @public + */ +export const TechDocsReaderPage = (props: TechDocsReaderPageProps) => { + const { children } = props; const { NotFoundErrorPage } = useApp().getComponents(); const outlet = useOutlet(); @@ -83,3 +99,16 @@ export const TechDocsPage = ({ children }: TechDocsPageProps) => { ); }; + +/** + * @public + * @deprecated use {@link TechDocsReaderPage} instead + */ +export const TechDocsPage = TechDocsReaderPage; + +/** + * @public + * @deprecated use {@link TechDocsReaderPageRenderFunction} instead + */ + +export type TechDocsPageRenderFunction = TechDocsReaderPageRenderFunction; From 2fb1d5e622c7632e82a2d07701d2b681dbce52ce Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:36:09 +0100 Subject: [PATCH 05/22] TechDocs reader page header to follow new naming pattern Signed-off-by: Emma Indal --- ....tsx => TechDocsReaderPageHeader.test.tsx} | 10 +++---- ...eader.tsx => TechDocsReaderPageHeader.tsx} | 29 +++++++++++++++++-- 2 files changed, 31 insertions(+), 8 deletions(-) rename plugins/techdocs/src/reader/components/{TechDocsPageHeader.test.tsx => TechDocsReaderPageHeader.test.tsx} (93%) rename plugins/techdocs/src/reader/components/{TechDocsPageHeader.tsx => TechDocsReaderPageHeader.tsx} (83%) diff --git a/plugins/techdocs/src/reader/components/TechDocsPageHeader.test.tsx b/plugins/techdocs/src/reader/components/TechDocsReaderPageHeader.test.tsx similarity index 93% rename from plugins/techdocs/src/reader/components/TechDocsPageHeader.test.tsx rename to plugins/techdocs/src/reader/components/TechDocsReaderPageHeader.test.tsx index 4fa43bfed5..9245bb66c5 100644 --- a/plugins/techdocs/src/reader/components/TechDocsPageHeader.test.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsReaderPageHeader.test.tsx @@ -14,17 +14,17 @@ * limitations under the License. */ import React from 'react'; -import { TechDocsPageHeader } from './TechDocsPageHeader'; +import { TechDocsReaderPageHeader } from './TechDocsReaderPageHeader'; import { act } from '@testing-library/react'; import { renderInTestApp } from '@backstage/test-utils'; import { entityRouteRef } from '@backstage/plugin-catalog-react'; import { rootRouteRef } from '../../routes'; -describe('', () => { +describe('', () => { it('should render a techdocs page header', async () => { await act(async () => { const rendered = await renderInTestApp( - ', () => { it('should render a techdocs page header even if metadata is missing', async () => { await act(async () => { const rendered = await renderInTestApp( - ', () => { it('should render a link back to the component page', async () => { await act(async () => { const rendered = await renderInTestApp( - ; -export const TechDocsPageHeader = ({ +/** + * Component responsible for rendering a Header with metadata on TechDocs reader page. + * + * @public + */ +export const TechDocsReaderPageHeader = ({ entityRef, entityMetadata, techDocsMetadata, children, -}: TechDocsPageHeaderProps) => { +}: TechDocsReaderPageHeaderProps) => { const { name } = entityRef; const { site_name: siteName, site_description: siteDescription } = @@ -114,3 +124,16 @@ export const TechDocsPageHeader = ({
); }; + +/** + * @public + * @deprecated use {@link TechDocsReaderPageHeader} instead + */ +export const TechDocsPageHeader = TechDocsReaderPageHeader; + +/** + * @public + * @deprecated use {@link TechDocsReaderPageHeader} instead + */ + +export type TechDocsPageHeaderProps = TechDocsReaderPageHeaderProps; From 0eb8b4ef49c2326203b38338824def77b2b9d7fe Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:36:50 +0100 Subject: [PATCH 06/22] rename index file Signed-off-by: Emma Indal --- plugins/techdocs/src/reader/{index.tsx => index.ts} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename plugins/techdocs/src/reader/{index.tsx => index.ts} (100%) diff --git a/plugins/techdocs/src/reader/index.tsx b/plugins/techdocs/src/reader/index.ts similarity index 100% rename from plugins/techdocs/src/reader/index.tsx rename to plugins/techdocs/src/reader/index.ts From 88a1205329e0ffba9ca4e6bb7d2781c641390e38 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:37:26 +0100 Subject: [PATCH 07/22] export search components Signed-off-by: Emma Indal --- .../techdocs/src/search/components/index.ts | 18 ++++++++++++++++++ plugins/techdocs/src/search/index.ts | 17 +++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 plugins/techdocs/src/search/components/index.ts create mode 100644 plugins/techdocs/src/search/index.ts diff --git a/plugins/techdocs/src/search/components/index.ts b/plugins/techdocs/src/search/components/index.ts new file mode 100644 index 0000000000..1f7615b4ff --- /dev/null +++ b/plugins/techdocs/src/search/components/index.ts @@ -0,0 +1,18 @@ +/* + * Copyright 2021 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 './TechDocsSearchResultListItem'; +export * from './TechDocsSearch'; diff --git a/plugins/techdocs/src/search/index.ts b/plugins/techdocs/src/search/index.ts new file mode 100644 index 0000000000..6f9ea2a52d --- /dev/null +++ b/plugins/techdocs/src/search/index.ts @@ -0,0 +1,17 @@ +/* + * Copyright 2020 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 './components'; From 071c1c1de0a7118482357a36a5966a7b537593ed Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:41:04 +0100 Subject: [PATCH 08/22] api report clean ups Signed-off-by: Emma Indal --- plugins/techdocs/api-report.md | 367 ++++++++---------- plugins/techdocs/src/Router.tsx | 21 +- .../home/components/DefaultTechDocsHome.tsx | 3 +- .../home/components/LegacyTechDocsHome.tsx | 3 + .../home/components/TechDocsCustomHome.tsx | 24 +- .../home/components/TechDocsPageWrapper.tsx | 15 +- .../src/home/components/TechDocsPicker.tsx | 5 + plugins/techdocs/src/plugin.ts | 72 ++-- .../reader/components/LegacyTechDocsPage.tsx | 7 +- .../techdocs/src/reader/components/Reader.tsx | 41 +- plugins/techdocs/src/types.ts | 10 + 11 files changed, 311 insertions(+), 257 deletions(-) diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index 7d554a293c..3b953556c4 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -22,50 +22,7 @@ import { TableColumn } from '@backstage/core-components'; import { TableProps } from '@backstage/core-components'; import { UserListFilterKind } from '@backstage/plugin-catalog-react'; -// Warning: (ae-missing-release-tag) "createCopyDocsUrlAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createCopyDocsUrlAction(copyToClipboard: Function): ( - row: DocsTableRow, -) => { - icon: () => JSX.Element; - tooltip: string; - onClick: () => any; -}; - -// Warning: (ae-missing-release-tag) "createNameColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createNameColumn(): TableColumn; - -// Warning: (ae-missing-release-tag) "createOwnerColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createOwnerColumn(): TableColumn; - -// Warning: (ae-missing-release-tag) "createStarEntityAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createStarEntityAction( - isStarredEntity: Function, - toggleStarredEntity: Function, -): ({ entity }: DocsTableRow) => { - cellStyle: { - paddingLeft: string; - }; - icon: () => JSX.Element; - tooltip: string; - onClick: () => any; -}; - -// Warning: (ae-missing-release-tag) "createTypeColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createTypeColumn(): TableColumn; - -// Warning: (ae-missing-release-tag) "DefaultTechDocsHome" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const DefaultTechDocsHome: ({ initialFilter, columns, @@ -73,49 +30,6 @@ export const DefaultTechDocsHome: ({ }: { initialFilter?: UserListFilterKind | undefined; columns?: TableColumn[] | undefined; - actions?: TableProps['actions']; -}) => JSX.Element; - -// Warning: (ae-missing-release-tag) "DocsCardGrid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const DocsCardGrid: ({ - entities, -}: { - entities: Entity[] | undefined; -}) => JSX.Element | null; - -// Warning: (ae-missing-release-tag) "DocsResultListItem" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const DocsResultListItem: ({ - result, - lineClamp, - asListItem, - asLink, - title, -}: { - result: any; - lineClamp?: number | undefined; - asListItem?: boolean | undefined; - asLink?: boolean | undefined; - title?: string | undefined; -}) => JSX.Element; - -// Warning: (ae-missing-release-tag) "DocsTable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const DocsTable: ({ - entities, - title, - loading, - columns, - actions, -}: { - entities: Entity[] | undefined; - title?: string | undefined; - loading?: boolean | undefined; - columns?: TableColumn[] | undefined; actions?: | ( | Action @@ -126,11 +40,33 @@ export const DocsTable: ({ | ((rowData: DocsTableRow) => Action) )[] | undefined; +}) => JSX.Element; + +// @public +export const DocsCardGrid: ({ + entities, +}: { + entities: Entity[] | undefined; }) => JSX.Element | null; -// Warning: (ae-missing-release-tag) "DocsTableRow" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public @deprecated (undocumented) +export const DocsResultListItem: ( + props: TechDocsSearchResultListItemProps, +) => JSX.Element; + +// @public +export const DocsTable: (props: DocsTableProps) => JSX.Element | null; + +// @public +export type DocsTableProps = { + entities: Entity[] | undefined; + title?: string | undefined; + loading?: boolean | undefined; + columns?: TableColumn[]; + actions?: TableProps['actions']; +}; + +// @public export type DocsTableRow = { entity: Entity; resolved: { @@ -140,74 +76,80 @@ export type DocsTableRow = { }; }; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "EmbeddedDocsRouter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const EmbeddedDocsRouter: (_props: Props_2) => JSX.Element; +// @public +export const EmbeddedDocsRouter: () => JSX.Element; -// Warning: (ae-missing-release-tag) "EntityListDocsGrid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const EntityListDocsGrid: () => JSX.Element; -// Warning: (ae-missing-release-tag) "EntityListDocsTable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const EntityListDocsTable: { - ({ - columns, - actions, - }: { - columns?: TableColumn[] | undefined; - actions?: TableProps['actions']; - }): JSX.Element; + (props: EntityListDocsTableProps): JSX.Element; columns: typeof columnFactories; actions: typeof actionFactories; }; -// Warning: (ae-missing-release-tag) "EntityTechdocsContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const EntityTechdocsContent: (_props: {}) => JSX.Element; +// @public +export type EntityListDocsTableProps = { + columns?: TableColumn[]; + actions?: TableProps['actions']; +}; -// Warning: (ae-missing-release-tag) "isTechDocsAvailable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export const EntityTechdocsContent: () => JSX.Element; + +// @public export const isTechDocsAvailable: (entity: Entity) => boolean; -// Warning: (ae-missing-release-tag) "PanelType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export interface PanelConfig { + // (undocumented) + description: string; + // (undocumented) + filterPredicate: ((entity: Entity) => boolean) | string; + // (undocumented) + panelCSS?: CSSProperties; + // (undocumented) + panelType: PanelType; + // (undocumented) + title: string; +} + +// @public export type PanelType = 'DocsCardGrid' | 'DocsTable'; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "Reader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const Reader: ({ - entityRef, - onReady, - withSearch, -}: Props_3) => JSX.Element; +// @public +export const Reader: (props: ReaderProps) => JSX.Element; -// Warning: (ae-missing-release-tag) "Router" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type ReaderProps = { + entityRef: EntityName; + withSearch?: boolean; + onReady?: () => void; +}; + +// @public export const Router: () => JSX.Element; // @public export type SyncResult = 'cached' | 'updated'; +// @public +export interface TabConfig { + // (undocumented) + label: string; + // (undocumented) + panels: PanelConfig[]; +} + +// @public +export type TabsConfig = TabConfig[]; + // @public export interface TechDocsApi { getApiOrigin(): Promise; - // Warning: (ae-forgotten-export) The symbol "TechDocsEntityMetadata" needs to be exported by the entry point index.d.ts - // // (undocumented) getEntityMetadata(entityId: EntityName): Promise; - // Warning: (ae-forgotten-export) The symbol "TechDocsMetadata" needs to be exported by the entry point index.d.ts - // // (undocumented) getTechDocsMetadata(entityId: EntityName): Promise; } @@ -232,84 +174,61 @@ export class TechDocsClient implements TechDocsApi { getTechDocsMetadata(entityId: EntityName): Promise; } -// Warning: (ae-missing-release-tag) "TechDocsCustomHome" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const TechDocsCustomHome: ({ tabsConfig, }: { tabsConfig: TabsConfig; }) => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsIndexPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type TechDocsEntityMetadata = Entity & { + locationMetadata?: LocationSpec; +}; + +// @public export const TechDocsIndexPage: () => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const TechDocsPage: ({ children }: TechDocsPageProps) => JSX.Element; +// @public +export type TechDocsMetadata = { + site_name: string; + site_description: string; +}; -// Warning: (ae-missing-release-tag) "TechdocsPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public @deprecated (undocumented) +export const TechDocsPage: (props: TechDocsReaderPageProps) => JSX.Element; + +// @public export const TechdocsPage: () => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsPageHeader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public @deprecated (undocumented) export const TechDocsPageHeader: ({ entityRef, entityMetadata, techDocsMetadata, children, -}: TechDocsPageHeaderProps) => JSX.Element; +}: TechDocsReaderPageHeaderProps) => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsPageHeaderProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export type TechDocsPageHeaderProps = PropsWithChildren<{ - entityRef: EntityName; - entityMetadata?: TechDocsEntityMetadata; - techDocsMetadata?: TechDocsMetadata; -}>; +// @public @deprecated (undocumented) +export type TechDocsPageHeaderProps = TechDocsReaderPageHeaderProps; -// Warning: (ae-missing-release-tag) "TechDocsPageProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export type TechDocsPageProps = { - children?: TechDocsPageRenderFunction | React_2.ReactNode; +// @public @deprecated (undocumented) +export type TechDocsPageRenderFunction = TechDocsReaderPageRenderFunction; + +// @public +export const TechDocsPageWrapper: ( + props: TechDocsPageWrapperProps, +) => JSX.Element; + +// @public +export type TechDocsPageWrapperProps = { + children?: React_2.ReactNode; }; -// Warning: (ae-missing-release-tag) "TechDocsPageRenderFunction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export type TechDocsPageRenderFunction = ({ - techdocsMetadataValue, - entityMetadataValue, - entityRef, -}: { - techdocsMetadataValue?: TechDocsMetadata | undefined; - entityMetadataValue?: TechDocsEntityMetadata | undefined; - entityRef: EntityName; - onReady: () => void; -}) => JSX.Element; - -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "TechDocsPageWrapper" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const TechDocsPageWrapper: ({ children }: Props) => JSX.Element; - -// Warning: (ae-missing-release-tag) "TechDocsPicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const TechDocsPicker: () => null; -// Warning: (ae-missing-release-tag) "techdocsPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public const techdocsPlugin: BackstagePlugin< { root: RouteRef; @@ -325,12 +244,65 @@ const techdocsPlugin: BackstagePlugin< export { techdocsPlugin as plugin }; export { techdocsPlugin }; -// Warning: (ae-missing-release-tag) "TechDocsReaderPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const TechDocsReaderPage: ({ +// @public +export const TechDocsReaderPage: ( + props: TechDocsReaderPageProps, +) => JSX.Element; + +// @public +export const TechDocsReaderPageHeader: ({ + entityRef, + entityMetadata, + techDocsMetadata, children, -}: TechDocsPageProps) => JSX.Element; +}: TechDocsReaderPageHeaderProps) => JSX.Element; + +// @public +export type TechDocsReaderPageHeaderProps = PropsWithChildren<{ + entityRef: EntityName; + entityMetadata?: TechDocsEntityMetadata; + techDocsMetadata?: TechDocsMetadata; +}>; + +// @public +export type TechDocsReaderPageProps = { + children?: TechDocsReaderPageRenderFunction | React_2.ReactNode; +}; + +// @public +export type TechDocsReaderPageRenderFunction = ({ + techdocsMetadataValue, + entityMetadataValue, + entityRef, +}: { + techdocsMetadataValue?: TechDocsMetadata | undefined; + entityMetadataValue?: TechDocsEntityMetadata | undefined; + entityRef: EntityName; + onReady: () => void; +}) => JSX.Element; + +// @public +export const TechDocsSearch: (props: TechDocsSearchProps) => JSX.Element; + +// @public +export type TechDocsSearchProps = { + entityId: EntityName; + debounceTime?: number; +}; + +// @public +export const TechDocsSearchResultListItem: ( + props: TechDocsSearchResultListItemProps, +) => JSX.Element; + +// @public +export type TechDocsSearchResultListItemProps = { + result: any; + lineClamp?: number; + asListItem?: boolean; + asLink?: boolean; + title?: string; +}; // @public export interface TechDocsStorageApi { @@ -392,7 +364,6 @@ export class TechDocsStorageClient implements TechDocsStorageApi { // Warnings were encountered during analysis: // -// src/home/components/EntityListDocsTable.d.ts:11:5 - (ae-forgotten-export) The symbol "columnFactories" needs to be exported by the entry point index.d.ts -// src/home/components/EntityListDocsTable.d.ts:12:5 - (ae-forgotten-export) The symbol "actionFactories" needs to be exported by the entry point index.d.ts -// src/plugin.d.ts:27:5 - (ae-forgotten-export) The symbol "TabsConfig" needs to be exported by the entry point index.d.ts +// src/home/components/Tables/EntityListDocsTable.d.ts:22:5 - (ae-forgotten-export) The symbol "columnFactories" needs to be exported by the entry point index.d.ts +// src/home/components/Tables/EntityListDocsTable.d.ts:23:5 - (ae-forgotten-export) The symbol "actionFactories" needs to be exported by the entry point index.d.ts ``` diff --git a/plugins/techdocs/src/Router.tsx b/plugins/techdocs/src/Router.tsx index 0ba69c021f..3a49f6edf9 100644 --- a/plugins/techdocs/src/Router.tsx +++ b/plugins/techdocs/src/Router.tsx @@ -19,15 +19,25 @@ import { Entity } from '@backstage/catalog-model'; import { useEntity } from '@backstage/plugin-catalog-react'; import { Route, Routes } from 'react-router-dom'; import { TechDocsIndexPage } from './home/components/TechDocsIndexPage'; -import { TechDocsPage as TechDocsReaderPage } from './reader/components/TechDocsPage'; +import { TechDocsReaderPage } from './reader/components/TechDocsReaderPage'; import { EntityPageDocs } from './EntityPageDocs'; import { MissingAnnotationEmptyState } from '@backstage/core-components'; const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref'; +/** + * Helper that takes in entity and returns true/false if TechDocs is available for the entity + * + * @public + */ export const isTechDocsAvailable = (entity: Entity) => Boolean(entity?.metadata?.annotations?.[TECHDOCS_ANNOTATION]); +/** + * Responsible for registering routes for TechDocs, TechDocs Homepage and separate TechDocs page + * + * @public + */ export const Router = () => { return ( @@ -40,9 +50,12 @@ export const Router = () => { ); }; -type Props = {}; - -export const EmbeddedDocsRouter = (_props: Props) => { +/** + * Responsible for registering route to view docs on Entity page + * + * @public + */ +export const EmbeddedDocsRouter = () => { const { entity } = useEntity(); const projectId = entity.metadata.annotations?.[TECHDOCS_ANNOTATION]; diff --git a/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx b/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx index ff4bf63724..af9fbb093d 100644 --- a/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx +++ b/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx @@ -34,10 +34,9 @@ import { UserListFilterKind, UserListPicker, } from '@backstage/plugin-catalog-react'; -import { EntityListDocsTable } from './EntityListDocsTable'; import { TechDocsPageWrapper } from './TechDocsPageWrapper'; import { TechDocsPicker } from './TechDocsPicker'; -import { DocsTableRow } from './types'; +import { DocsTableRow, EntityListDocsTable } from './Tables'; export const DefaultTechDocsHome = ({ initialFilter = 'all', diff --git a/plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx b/plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx index 34ea416026..536c2c80c8 100644 --- a/plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx +++ b/plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx @@ -17,6 +17,9 @@ import React from 'react'; import { PanelType, TechDocsCustomHome } from './TechDocsCustomHome'; +/** + * @deprecated Use {@link TechDocsCustomHome} instead. + */ export const LegacyTechDocsHome = () => { const tabsConfig = [ { diff --git a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx index 54c622fdf3..24555e01ae 100644 --- a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx +++ b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx @@ -30,8 +30,8 @@ import { parseEntityRef, UserEntity, } from '@backstage/catalog-model'; -import { DocsTable } from './DocsTable'; -import { DocsCardGrid } from './DocsCardGrid'; +import { DocsTable } from './Tables'; +import { DocsCardGrid } from './Grids'; import { TechDocsPageWrapper } from './TechDocsPageWrapper'; import { @@ -51,8 +51,18 @@ const panels = { DocsCardGrid: DocsCardGrid, }; +/** + * Available panel types + * + * @public + */ export type PanelType = 'DocsCardGrid' | 'DocsTable'; +/** + * Type representing a TechDocsCustomHome panel. + * + * @public + */ export interface PanelConfig { title: string; description: string; @@ -61,11 +71,21 @@ export interface PanelConfig { filterPredicate: ((entity: Entity) => boolean) | string; } +/** + * Type representing a TechDocsCustomHome tab. + * + * @public + */ export interface TabConfig { label: string; panels: PanelConfig[]; } +/** + * Type representing a list of TechDocsCustomHome tabs. + * + * @public + */ export type TabsConfig = TabConfig[]; const CustomPanel = ({ diff --git a/plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx b/plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx index 453cfc22cc..52511bda19 100644 --- a/plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx +++ b/plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx @@ -19,11 +19,22 @@ import React from 'react'; import { PageWithHeader } from '@backstage/core-components'; import { useApi, configApiRef } from '@backstage/core-plugin-api'; -type Props = { +/** + * Props for {@link TechDocsPageWrapper} + * + * @public + */ +export type TechDocsPageWrapperProps = { children?: React.ReactNode; }; -export const TechDocsPageWrapper = ({ children }: Props) => { +/** + * Component wrapping a techdocs page with Page and Header components + * + * @public + */ +export const TechDocsPageWrapper = (props: TechDocsPageWrapperProps) => { + const { children } = props; const configApi = useApi(configApiRef); const generatedSubtitle = `Documentation available in ${ configApi.getOptionalString('organization.name') ?? 'Backstage' diff --git a/plugins/techdocs/src/home/components/TechDocsPicker.tsx b/plugins/techdocs/src/home/components/TechDocsPicker.tsx index ce79b9a4e9..32c7b800eb 100644 --- a/plugins/techdocs/src/home/components/TechDocsPicker.tsx +++ b/plugins/techdocs/src/home/components/TechDocsPicker.tsx @@ -34,6 +34,11 @@ type CustomFilters = DefaultEntityFilters & { techdocs?: TechDocsFilter; }; +/** + * Component responsible for updating TechDocs filters + * + * @public + */ export const TechDocsPicker = () => { const { updateFilters } = useEntityList(); diff --git a/plugins/techdocs/src/plugin.ts b/plugins/techdocs/src/plugin.ts index a37ad61f80..50360c4902 100644 --- a/plugins/techdocs/src/plugin.ts +++ b/plugins/techdocs/src/plugin.ts @@ -32,6 +32,11 @@ import { identityApiRef, } from '@backstage/core-plugin-api'; +/** + * The Backstage plugin that renders technical documentation for your components + * + * @public + */ export const techdocsPlugin = createPlugin({ id: 'techdocs', apis: [ @@ -73,6 +78,11 @@ export const techdocsPlugin = createPlugin({ }, }); +/** + * Routable extension used to render docs + * + * @public + */ export const TechdocsPage = techdocsPlugin.provide( createRoutableExtension({ name: 'TechdocsPage', @@ -81,6 +91,11 @@ export const TechdocsPage = techdocsPlugin.provide( }), ); +/** + * Routable extension used to render docs on Entity page + * + * @public + */ export const EntityTechdocsContent = techdocsPlugin.provide( createRoutableExtension({ name: 'EntityTechdocsContent', @@ -89,28 +104,11 @@ export const EntityTechdocsContent = techdocsPlugin.provide( }), ); -// takes a list of entities and renders documentation cards -export const DocsCardGrid = techdocsPlugin.provide( - createComponentExtension({ - name: 'DocsCardGrid', - component: { - lazy: () => - import('./home/components/DocsCardGrid').then(m => m.DocsCardGrid), - }, - }), -); - -// takes a list of entities and renders table listing documentation -export const DocsTable = techdocsPlugin.provide( - createComponentExtension({ - name: 'DocsTable', - component: { - lazy: () => import('./home/components/DocsTable').then(m => m.DocsTable), - }, - }), -); - -// takes a custom tabs config object and renders a documentation landing page +/** + * Component which takes a custom tabs config object and renders a documentation landing page. + * + * @public + */ export const TechDocsCustomHome = techdocsPlugin.provide( createRoutableExtension({ name: 'TechDocsCustomHome', @@ -122,6 +120,27 @@ export const TechDocsCustomHome = techdocsPlugin.provide( }), ); +/** + * Component which renders a default documentation landing page. + * + * @public + */ +export const DefaultTechDocsHome = techdocsPlugin.provide( + createRoutableExtension({ + name: 'DefaultTechDocsHome', + component: () => + import('./home/components/DefaultTechDocsHome').then( + m => m.DefaultTechDocsHome, + ), + mountPoint: rootRouteRef, + }), +); + +/** + * Responsible for rendering the provided router element + * + * @public + */ export const TechDocsIndexPage = techdocsPlugin.provide( createRoutableExtension({ name: 'TechDocsIndexPage', @@ -132,12 +151,3 @@ export const TechDocsIndexPage = techdocsPlugin.provide( mountPoint: rootRouteRef, }), ); - -export const TechDocsReaderPage = techdocsPlugin.provide( - createRoutableExtension({ - name: 'TechDocsReaderPage', - component: () => - import('./reader/components/TechDocsPage').then(m => m.TechDocsPage), - mountPoint: rootDocsRouteRef, - }), -); diff --git a/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx b/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx index f3384e21b3..c305dd1698 100644 --- a/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx +++ b/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx @@ -22,8 +22,11 @@ import { TechDocsNotFound } from './TechDocsNotFound'; import { useApi } from '@backstage/core-plugin-api'; import { Page, Content } from '@backstage/core-components'; import { Reader } from './Reader'; -import { TechDocsPageHeader } from './TechDocsPageHeader'; +import { TechDocsReaderPageHeader } from './TechDocsReaderPageHeader'; +/** + * @deprecated Use {@link TechDocsPage} instead. + */ export const LegacyTechDocsPage = () => { const [documentReady, setDocumentReady] = useState(false); const { namespace, kind, name } = useParams(); @@ -53,7 +56,7 @@ export const LegacyTechDocsPage = () => { return ( - void; @@ -823,7 +828,7 @@ const TheReader = ({ entityRef, onReady = () => {}, withSearch = true, -}: Props) => { +}: ReaderProps) => { const classes = useStyles(); const dom = useTechDocsReaderDom(entityRef); const shadowDomRef = useRef(null); @@ -860,16 +865,20 @@ const TheReader = ({ ); }; -export const Reader = ({ - entityRef, - onReady = () => {}, - withSearch = true, -}: Props) => ( - - - -); +/** + * Component responsible for rendering TechDocs documentation + * + * @public + */ +export const Reader = (props: ReaderProps) => { + const { entityRef, onReady = () => {}, withSearch = true } = props; + return ( + + + + ); +}; diff --git a/plugins/techdocs/src/types.ts b/plugins/techdocs/src/types.ts index fbe6f4b870..ee6b88756c 100644 --- a/plugins/techdocs/src/types.ts +++ b/plugins/techdocs/src/types.ts @@ -16,11 +16,21 @@ import { Entity } from '@backstage/catalog-model'; +/** + * Metadata for TechDocs page + * + * @public + */ export type TechDocsMetadata = { site_name: string; site_description: string; }; +/** + * Metadata for TechDocs Entity + * + * @public + */ export type TechDocsEntityMetadata = Entity & { locationMetadata?: { type: string; target: string }; }; From 98e974a994c6f2b071392fd8ab6ae47923c5f6da Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:42:11 +0100 Subject: [PATCH 09/22] export/import fixups Signed-off-by: Emma Indal --- plugins/techdocs/src/home/components/index.ts | 17 +++++++++---- plugins/techdocs/src/index.ts | 24 ++++++------------- plugins/techdocs/src/plugin.ts | 1 - .../techdocs/src/reader/components/index.ts | 5 ++-- 4 files changed, 21 insertions(+), 26 deletions(-) diff --git a/plugins/techdocs/src/home/components/index.ts b/plugins/techdocs/src/home/components/index.ts index d9d627cf8d..be8029687b 100644 --- a/plugins/techdocs/src/home/components/index.ts +++ b/plugins/techdocs/src/home/components/index.ts @@ -14,10 +14,17 @@ * limitations under the License. */ +export * from './Grids'; +export * from './Tables'; export { DefaultTechDocsHome } from './DefaultTechDocsHome'; -export { EntityListDocsGrid } from './EntityListDocsGrid'; -export { EntityListDocsTable } from './EntityListDocsTable'; -export type { PanelType } from './TechDocsCustomHome'; -export { TechDocsPageWrapper } from './TechDocsPageWrapper'; +export type { + PanelType, + PanelConfig, + TabConfig, + TabsConfig, +} from './TechDocsCustomHome'; +export { + TechDocsPageWrapper, + type TechDocsPageWrapperProps, +} from './TechDocsPageWrapper'; export { TechDocsPicker } from './TechDocsPicker'; -export type { DocsTableRow } from './types'; diff --git a/plugins/techdocs/src/index.ts b/plugins/techdocs/src/index.ts index a6a95e9264..400874ada7 100644 --- a/plugins/techdocs/src/index.ts +++ b/plugins/techdocs/src/index.ts @@ -20,29 +20,19 @@ * @packageDocumentation */ +export * from './types'; export * from './api'; -export { techdocsApiRef, techdocsStorageApiRef } from './api'; -export type { TechDocsApi, TechDocsStorageApi } from './api'; -export { TechDocsClient, TechDocsStorageClient } from './client'; -export * from './components/DocsResultListItem'; +export * from './client'; +export * from './reader'; +export * from './search'; +export * from './home'; export { - DefaultTechDocsHome, - EntityListDocsGrid, - EntityListDocsTable, - TechDocsPageWrapper, - TechDocsPicker, -} from './home/components'; -export type { DocsTableRow, PanelType } from './home/components'; -export { - DocsCardGrid, - DocsTable, EntityTechdocsContent, + DefaultTechDocsHome, TechDocsCustomHome, TechDocsIndexPage, TechdocsPage, techdocsPlugin as plugin, techdocsPlugin, - TechDocsReaderPage, } from './plugin'; -export * from './reader'; -export { EmbeddedDocsRouter, isTechDocsAvailable, Router } from './Router'; +export * from './Router'; diff --git a/plugins/techdocs/src/plugin.ts b/plugins/techdocs/src/plugin.ts index 50360c4902..35960c7cbb 100644 --- a/plugins/techdocs/src/plugin.ts +++ b/plugins/techdocs/src/plugin.ts @@ -24,7 +24,6 @@ import { import { configApiRef, createApiFactory, - createComponentExtension, createPlugin, createRoutableExtension, discoveryApiRef, diff --git a/plugins/techdocs/src/reader/components/index.ts b/plugins/techdocs/src/reader/components/index.ts index 99a0a7a3bc..861f8e7bdb 100644 --- a/plugins/techdocs/src/reader/components/index.ts +++ b/plugins/techdocs/src/reader/components/index.ts @@ -15,8 +15,8 @@ */ export * from './Reader'; -export * from './TechDocsPage'; -export * from './TechDocsPageHeader'; +export * from './TechDocsReaderPage'; +export * from './TechDocsReaderPageHeader'; export * from './TechDocsStateIndicator'; /** @@ -31,4 +31,3 @@ export * from './TechDocsStateIndicator'; * todo: Make public or stop exporting (ctrl+f "altReaderExperiments") * @internal */ -export { TechDocsSearch } from './TechDocsSearch'; From da29cb2998bb4f07721345e98b3ed2913bf65975 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Wed, 23 Feb 2022 09:47:13 +0100 Subject: [PATCH 10/22] Update LegacyTechDocsPage.tsx Signed-off-by: Emma Indal --- plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx b/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx index c305dd1698..4bfda57ace 100644 --- a/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx +++ b/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx @@ -25,7 +25,7 @@ import { Reader } from './Reader'; import { TechDocsReaderPageHeader } from './TechDocsReaderPageHeader'; /** - * @deprecated Use {@link TechDocsPage} instead. + * @deprecated Use {@link TechDocsReaderPage} instead. */ export const LegacyTechDocsPage = () => { const [documentReady, setDocumentReady] = useState(false); From ee3d6c6f108125a0ca783cccb189e6521bd9db25 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Wed, 23 Feb 2022 09:49:56 +0100 Subject: [PATCH 11/22] add changesets Signed-off-by: Emma Indal --- .changeset/fast-paws-arrive.md | 22 ++++++++++++++++++++++ .changeset/tiny-lobsters-exercise.md | 15 +++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 .changeset/fast-paws-arrive.md create mode 100644 .changeset/tiny-lobsters-exercise.md diff --git a/.changeset/fast-paws-arrive.md b/.changeset/fast-paws-arrive.md new file mode 100644 index 0000000000..fc4b531711 --- /dev/null +++ b/.changeset/fast-paws-arrive.md @@ -0,0 +1,22 @@ +--- +'@backstage/create-app': patch +--- + +Update the template to reflect the renaming of `DocsResultListItem` to `TechDocsSearchResultListItem` from `@backstage/plugin-techdocs`. + +To apply this change to an existing app, make the following change to `packages/app/src/components/search/SearchPage.tsx`: + +```diff +-import { DocsResultListItem } from '@backstage/plugin-techdocs'; ++import { TechDocsSearchResultListItem } from '@backstage/plugin-techdocs'; +``` + +```diff + case 'techdocs': + return ( +- +``` diff --git a/.changeset/tiny-lobsters-exercise.md b/.changeset/tiny-lobsters-exercise.md new file mode 100644 index 0000000000..f50ff9a236 --- /dev/null +++ b/.changeset/tiny-lobsters-exercise.md @@ -0,0 +1,15 @@ +--- +'@backstage/plugin-techdocs': patch +--- + +- Renamed `DocsResultListItem` to `TechDocsSearchResultListItem`, leaving the old name in place as a deprecations. + +- Renamed `TechDocsPage` to `TechDocsReaderPage`, leaving the old name in place as a deprecations. + +- Renamed `TechDocsPageRenderFunction` to `TechDocsPageRenderFunction`, leaving the old name in place as a deprecations. + +- Renamed `TechDocsPageHeader` to `TechDocsReaderPageHeader`, leaving the old name in place as a deprecations. + +- `LegacyTechDocsHome` marked as deprecated and will be deleted in next release, use `TechDocsCustomHome` instead. + +- `LegacyTechDocsPage` marked as deprecated and will be deleted in next release, use `TechDocsReaderPage` instead. From e1a3d0df92f663f235e5d8dba13ad4d43ee723b3 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Wed, 23 Feb 2022 11:13:24 +0100 Subject: [PATCH 12/22] fixups Signed-off-by: Emma Indal --- plugins/techdocs/src/home/components/index.ts | 9 +++------ .../techdocs/src/search/components/TechDocsSearch.tsx | 2 +- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/plugins/techdocs/src/home/components/index.ts b/plugins/techdocs/src/home/components/index.ts index be8029687b..a6ecc2be39 100644 --- a/plugins/techdocs/src/home/components/index.ts +++ b/plugins/techdocs/src/home/components/index.ts @@ -16,15 +16,12 @@ export * from './Grids'; export * from './Tables'; -export { DefaultTechDocsHome } from './DefaultTechDocsHome'; +export * from './DefaultTechDocsHome'; export type { PanelType, PanelConfig, TabConfig, TabsConfig, } from './TechDocsCustomHome'; -export { - TechDocsPageWrapper, - type TechDocsPageWrapperProps, -} from './TechDocsPageWrapper'; -export { TechDocsPicker } from './TechDocsPicker'; +export * from './TechDocsPageWrapper'; +export * from './TechDocsPicker'; diff --git a/plugins/techdocs/src/search/components/TechDocsSearch.tsx b/plugins/techdocs/src/search/components/TechDocsSearch.tsx index 74e2ac554e..c817fb3217 100644 --- a/plugins/techdocs/src/search/components/TechDocsSearch.tsx +++ b/plugins/techdocs/src/search/components/TechDocsSearch.tsx @@ -28,7 +28,7 @@ import Autocomplete from '@material-ui/lab/Autocomplete'; import React, { ChangeEvent, useEffect, useState } from 'react'; import { useNavigate } from 'react-router'; import useDebounce from 'react-use/lib/useDebounce'; -import { TechDocsSearchResultListItem } from '../../search'; +import { TechDocsSearchResultListItem } from './TechDocsSearchResultListItem'; const useStyles = makeStyles({ root: { From ce2dcca3d1d685b9a83f5eb62c893fb583de32d1 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Wed, 23 Feb 2022 13:29:59 +0100 Subject: [PATCH 13/22] do not plublicly export factories directly, but through tables Signed-off-by: Emma Indal --- plugins/techdocs/api-report.md | 30 +++++-- .../src/home/components/Tables/DocsTable.tsx | 4 +- .../components/Tables/EntityListDocsTable.tsx | 4 +- .../src/home/components/Tables/actions.tsx | 58 ++++++------- .../src/home/components/Tables/columns.tsx | 82 +++++++++---------- 5 files changed, 90 insertions(+), 88 deletions(-) diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index 3b953556c4..558c6397a3 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -85,8 +85,29 @@ export const EntityListDocsGrid: () => JSX.Element; // @public export const EntityListDocsTable: { (props: EntityListDocsTableProps): JSX.Element; - columns: typeof columnFactories; - actions: typeof actionFactories; + columns: { + createNameColumn(): TableColumn; + createOwnerColumn(): TableColumn; + createTypeColumn(): TableColumn; + }; + actions: { + createCopyDocsUrlAction(copyToClipboard: Function): (row: DocsTableRow) => { + icon: () => JSX.Element; + tooltip: string; + onClick: () => any; + }; + createStarEntityAction( + isStarredEntity: Function, + toggleStarredEntity: Function, + ): ({ entity }: DocsTableRow) => { + cellStyle: { + paddingLeft: string; + }; + icon: () => JSX.Element; + tooltip: string; + onClick: () => any; + }; + }; }; // @public @@ -361,9 +382,4 @@ export class TechDocsStorageClient implements TechDocsStorageApi { logHandler?: (line: string) => void, ): Promise; } - -// Warnings were encountered during analysis: -// -// src/home/components/Tables/EntityListDocsTable.d.ts:22:5 - (ae-forgotten-export) The symbol "columnFactories" needs to be exported by the entry point index.d.ts -// src/home/components/Tables/EntityListDocsTable.d.ts:23:5 - (ae-forgotten-export) The symbol "actionFactories" needs to be exported by the entry point index.d.ts ``` diff --git a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx index cbc8ddc0b9..323cdab96a 100644 --- a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx +++ b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx @@ -31,8 +31,8 @@ import { TableColumn, TableProps, } from '@backstage/core-components'; -import * as actionFactories from './actions'; -import * as columnFactories from './columns'; +import { actionFactories } from './actions'; +import { columnFactories } from './columns'; import { toLowerMaybe } from '../../../helpers'; import { DocsTableRow } from './types'; diff --git a/plugins/techdocs/src/home/components/Tables/EntityListDocsTable.tsx b/plugins/techdocs/src/home/components/Tables/EntityListDocsTable.tsx index a963d53428..d47ddb13c4 100644 --- a/plugins/techdocs/src/home/components/Tables/EntityListDocsTable.tsx +++ b/plugins/techdocs/src/home/components/Tables/EntityListDocsTable.tsx @@ -28,8 +28,8 @@ import { useStarredEntities, } from '@backstage/plugin-catalog-react'; import { DocsTable } from './DocsTable'; -import * as actionFactories from './actions'; -import * as columnFactories from './columns'; +import { actionFactories } from './actions'; +import { columnFactories } from './columns'; import { DocsTableRow } from './types'; /** diff --git a/plugins/techdocs/src/home/components/Tables/actions.tsx b/plugins/techdocs/src/home/components/Tables/actions.tsx index 4e86fb1b89..d0dbb8bf47 100644 --- a/plugins/techdocs/src/home/components/Tables/actions.tsx +++ b/plugins/techdocs/src/home/components/Tables/actions.tsx @@ -23,39 +23,33 @@ import { import { DocsTableRow } from './types'; /** - * Utility function for creating a copy docs url action for {@link DocsTable}. + * Not directly exported, but through DocsTable.actions and EntityListDocsTable.actions * - * @internal + * @public */ - -export function createCopyDocsUrlAction(copyToClipboard: Function) { - return (row: DocsTableRow) => { - return { - icon: () => , - tooltip: 'Click to copy documentation link to clipboard', - onClick: () => - copyToClipboard(`${window.location.origin}${row.resolved.docsUrl}`), +export const actionFactories = { + createCopyDocsUrlAction(copyToClipboard: Function) { + return (row: DocsTableRow) => { + return { + icon: () => , + tooltip: 'Click to copy documentation link to clipboard', + onClick: () => + copyToClipboard(`${window.location.origin}${row.resolved.docsUrl}`), + }; }; - }; -} - -/** - * Utility function for creating a star entity action for {@link DocsTable}. - * - * @internal - */ - -export function createStarEntityAction( - isStarredEntity: Function, - toggleStarredEntity: Function, -) { - return ({ entity }: DocsTableRow) => { - const isStarred = isStarredEntity(entity); - return { - cellStyle: { paddingLeft: '1em' }, - icon: () => favoriteEntityIcon(isStarred), - tooltip: favoriteEntityTooltip(isStarred), - onClick: () => toggleStarredEntity(entity), + }, + createStarEntityAction( + isStarredEntity: Function, + toggleStarredEntity: Function, + ) { + return ({ entity }: DocsTableRow) => { + const isStarred = isStarredEntity(entity); + return { + cellStyle: { paddingLeft: '1em' }, + icon: () => favoriteEntityIcon(isStarred), + tooltip: favoriteEntityTooltip(isStarred), + onClick: () => toggleStarredEntity(entity), + }; }; - }; -} + }, +}; diff --git a/plugins/techdocs/src/home/components/Tables/columns.tsx b/plugins/techdocs/src/home/components/Tables/columns.tsx index 6f41ccb1d6..774cfc5e8a 100644 --- a/plugins/techdocs/src/home/components/Tables/columns.tsx +++ b/plugins/techdocs/src/home/components/Tables/columns.tsx @@ -25,50 +25,42 @@ function customTitle(entity: Entity): string { } /** - * Utility function for creating a name column for {@link DocsTable}. + * Not directly exported, but through DocsTable.columns and EntityListDocsTable.columns * - * @internal + * @public */ -export function createNameColumn(): TableColumn { - return { - title: 'Document', - field: 'entity.metadata.name', - highlight: true, - render: (row: DocsTableRow) => ( - {customTitle(row.entity)}} - subvalue={row.entity.metadata.description} - /> - ), - }; -} - -/** - * Utility function for creating an owner column for {@link DocsTable}. - * - * @internal - */ -export function createOwnerColumn(): TableColumn { - return { - title: 'Owner', - field: 'resolved.ownedByRelationsTitle', - render: ({ resolved }) => ( - - ), - }; -} - -/** - * Utility function for creating an spec type column for {@link DocsTable}. - * - * @internal - */ -export function createTypeColumn(): TableColumn { - return { - title: 'Type', - field: 'entity.spec.type', - }; -} +export const columnFactories = { + createNameColumn(): TableColumn { + return { + title: 'Document', + field: 'entity.metadata.name', + highlight: true, + render: (row: DocsTableRow) => ( + {customTitle(row.entity)} + } + subvalue={row.entity.metadata.description} + /> + ), + }; + }, + createOwnerColumn(): TableColumn { + return { + title: 'Owner', + field: 'resolved.ownedByRelationsTitle', + render: ({ resolved }) => ( + + ), + }; + }, + createTypeColumn(): TableColumn { + return { + title: 'Type', + field: 'entity.spec.type', + }; + }, +}; From 2bd91261a6677ed05513d6ac9f10785e36f563c8 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Wed, 23 Feb 2022 15:38:13 +0100 Subject: [PATCH 14/22] unpack props inside fn Signed-off-by: Emma Indal --- plugins/techdocs/api-report.md | 67 ++++++++----------- .../home/components/DefaultTechDocsHome.tsx | 16 +++-- .../home/components/Grids/DocsCardGrid.tsx | 16 +++-- .../home/components/TechDocsCustomHome.tsx | 14 ++-- plugins/techdocs/src/home/components/index.ts | 1 + .../components/TechDocsReaderPageHeader.tsx | 10 ++- 6 files changed, 64 insertions(+), 60 deletions(-) diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index 558c6397a3..31f8ee9a6d 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -5,7 +5,6 @@ ```ts /// -import { Action } from '@material-table/core'; import { ApiRef } from '@backstage/core-plugin-api'; import { BackstagePlugin } from '@backstage/core-plugin-api'; import { Config } from '@backstage/config'; @@ -23,31 +22,24 @@ import { TableProps } from '@backstage/core-components'; import { UserListFilterKind } from '@backstage/plugin-catalog-react'; // @public -export const DefaultTechDocsHome: ({ - initialFilter, - columns, - actions, -}: { - initialFilter?: UserListFilterKind | undefined; - columns?: TableColumn[] | undefined; - actions?: - | ( - | Action - | { - action: (rowData: DocsTableRow) => Action; - position: string; - } - | ((rowData: DocsTableRow) => Action) - )[] - | undefined; -}) => JSX.Element; +export const DefaultTechDocsHome: ( + props: DefaultTechDocsHomeProps, +) => JSX.Element; // @public -export const DocsCardGrid: ({ - entities, -}: { +export type DefaultTechDocsHomeProps = { + initialFilter?: UserListFilterKind; + columns?: TableColumn[]; + actions?: TableProps['actions']; +}; + +// @public +export const DocsCardGrid: (props: DocsCardGridProps) => JSX.Element | null; + +// @public +export type DocsCardGridProps = { entities: Entity[] | undefined; -}) => JSX.Element | null; +}; // @public @deprecated (undocumented) export const DocsResultListItem: ( @@ -196,11 +188,14 @@ export class TechDocsClient implements TechDocsApi { } // @public -export const TechDocsCustomHome: ({ - tabsConfig, -}: { +export const TechDocsCustomHome: ( + props: TechDocsCustomHomeProps, +) => JSX.Element; + +// @public +export type TechDocsCustomHomeProps = { tabsConfig: TabsConfig; -}) => JSX.Element; +}; // @public export type TechDocsEntityMetadata = Entity & { @@ -223,12 +218,9 @@ export const TechDocsPage: (props: TechDocsReaderPageProps) => JSX.Element; export const TechdocsPage: () => JSX.Element; // @public @deprecated (undocumented) -export const TechDocsPageHeader: ({ - entityRef, - entityMetadata, - techDocsMetadata, - children, -}: TechDocsReaderPageHeaderProps) => JSX.Element; +export const TechDocsPageHeader: ( + props: TechDocsReaderPageHeaderProps, +) => JSX.Element; // @public @deprecated (undocumented) export type TechDocsPageHeaderProps = TechDocsReaderPageHeaderProps; @@ -271,12 +263,9 @@ export const TechDocsReaderPage: ( ) => JSX.Element; // @public -export const TechDocsReaderPageHeader: ({ - entityRef, - entityMetadata, - techDocsMetadata, - children, -}: TechDocsReaderPageHeaderProps) => JSX.Element; +export const TechDocsReaderPageHeader: ( + props: TechDocsReaderPageHeaderProps, +) => JSX.Element; // @public export type TechDocsReaderPageHeaderProps = PropsWithChildren<{ diff --git a/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx b/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx index af9fbb093d..750b1d89bc 100644 --- a/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx +++ b/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx @@ -38,15 +38,19 @@ import { TechDocsPageWrapper } from './TechDocsPageWrapper'; import { TechDocsPicker } from './TechDocsPicker'; import { DocsTableRow, EntityListDocsTable } from './Tables'; -export const DefaultTechDocsHome = ({ - initialFilter = 'all', - columns, - actions, -}: { +/** + * Props for {@link DefaultTechDocsHome} + * + * @public + */ +export type DefaultTechDocsHomeProps = { initialFilter?: UserListFilterKind; columns?: TableColumn[]; actions?: TableProps['actions']; -}) => { +}; + +export const DefaultTechDocsHome = (props: DefaultTechDocsHomeProps) => { + const { initialFilter = 'all', columns, actions } = props; return ( diff --git a/plugins/techdocs/src/home/components/Grids/DocsCardGrid.tsx b/plugins/techdocs/src/home/components/Grids/DocsCardGrid.tsx index 6ec500e199..6f1d9fbe61 100644 --- a/plugins/techdocs/src/home/components/Grids/DocsCardGrid.tsx +++ b/plugins/techdocs/src/home/components/Grids/DocsCardGrid.tsx @@ -26,16 +26,22 @@ import { import { Card, CardActions, CardContent, CardMedia } from '@material-ui/core'; import React from 'react'; +/** + * Props for {@link DocsCardGrid} + * + * @public + */ +export type DocsCardGridProps = { + entities: Entity[] | undefined; +}; + /** * Component which accepts a list of entities and renders a item card for each entity * * @public */ -export const DocsCardGrid = ({ - entities, -}: { - entities: Entity[] | undefined; -}) => { +export const DocsCardGrid = (props: DocsCardGridProps) => { + const { entities } = props; const getRouteToReaderPageFor = useRouteRef(rootDocsRouteRef); const config = useApi(configApiRef); if (!entities) return null; diff --git a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx index 24555e01ae..c8149f1ff2 100644 --- a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx +++ b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx @@ -138,11 +138,17 @@ const CustomPanel = ({ ); }; -export const TechDocsCustomHome = ({ - tabsConfig, -}: { +/** + * Props for {@link TechDocsCustomHome} + * + * @public + */ +export type TechDocsCustomHomeProps = { tabsConfig: TabsConfig; -}) => { +}; + +export const TechDocsCustomHome = (props: TechDocsCustomHomeProps) => { + const { tabsConfig } = props; const [selectedTab, setSelectedTab] = useState(0); const catalogApi: CatalogApi = useApi(catalogApiRef); diff --git a/plugins/techdocs/src/home/components/index.ts b/plugins/techdocs/src/home/components/index.ts index a6ecc2be39..d21f992cef 100644 --- a/plugins/techdocs/src/home/components/index.ts +++ b/plugins/techdocs/src/home/components/index.ts @@ -22,6 +22,7 @@ export type { PanelConfig, TabConfig, TabsConfig, + TechDocsCustomHomeProps, } from './TechDocsCustomHome'; export * from './TechDocsPageWrapper'; export * from './TechDocsPicker'; diff --git a/plugins/techdocs/src/reader/components/TechDocsReaderPageHeader.tsx b/plugins/techdocs/src/reader/components/TechDocsReaderPageHeader.tsx index b260205156..928833efed 100644 --- a/plugins/techdocs/src/reader/components/TechDocsReaderPageHeader.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsReaderPageHeader.tsx @@ -45,12 +45,10 @@ export type TechDocsReaderPageHeaderProps = PropsWithChildren<{ * * @public */ -export const TechDocsReaderPageHeader = ({ - entityRef, - entityMetadata, - techDocsMetadata, - children, -}: TechDocsReaderPageHeaderProps) => { +export const TechDocsReaderPageHeader = ( + props: TechDocsReaderPageHeaderProps, +) => { + const { entityRef, entityMetadata, techDocsMetadata, children } = props; const { name } = entityRef; const { site_name: siteName, site_description: siteDescription } = From 231d0dc8dfcdafdc5f102cf16084be0a9da5e626 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 25 Feb 2022 12:08:55 +0100 Subject: [PATCH 15/22] update changeset Signed-off-by: Emma Indal --- .changeset/tiny-lobsters-exercise.md | 16 +++++++++- plugins/techdocs/api-report.md | 32 +++++++++++++++++-- .../src/home/components/Tables/DocsTable.tsx | 3 ++ 3 files changed, 48 insertions(+), 3 deletions(-) diff --git a/.changeset/tiny-lobsters-exercise.md b/.changeset/tiny-lobsters-exercise.md index f50ff9a236..78cc753bab 100644 --- a/.changeset/tiny-lobsters-exercise.md +++ b/.changeset/tiny-lobsters-exercise.md @@ -1,7 +1,21 @@ --- -'@backstage/plugin-techdocs': patch +'@backstage/plugin-techdocs': minor --- +**BREAKING:** +Table column utilities `createNameColumn`, `createOwnerColumn`, `createTypeColumn` as well as actions utilities `createCopyDocsUrlAction` and `createStarEntityAction` are no longer directly exported. Instead accessible through DocsTable and EntityListDocsTable. + +Use as following: + +```tsx +DocsTable.columns.createNameColumn(); +DocsTable.columns.createOwnerColumn(); +DocsTable.columns.createTypeColumn(); + +DocsTable.actions.createCopyDocsUrlAction(); +DocsTable.actions.createStarEntityAction(); +``` + - Renamed `DocsResultListItem` to `TechDocsSearchResultListItem`, leaving the old name in place as a deprecations. - Renamed `TechDocsPage` to `TechDocsReaderPage`, leaving the old name in place as a deprecations. diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index 31f8ee9a6d..917c1d5d85 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -47,7 +47,32 @@ export const DocsResultListItem: ( ) => JSX.Element; // @public -export const DocsTable: (props: DocsTableProps) => JSX.Element | null; +export const DocsTable: { + (props: DocsTableProps): JSX.Element | null; + columns: { + createNameColumn(): TableColumn; + createOwnerColumn(): TableColumn; + createTypeColumn(): TableColumn; + }; + actions: { + createCopyDocsUrlAction(copyToClipboard: Function): (row: DocsTableRow) => { + icon: () => JSX.Element; + tooltip: string; + onClick: () => any; + }; + createStarEntityAction( + isStarredEntity: Function, + toggleStarredEntity: Function, + ): ({ entity }: DocsTableRow) => { + cellStyle: { + paddingLeft: string; + }; + icon: () => JSX.Element; + tooltip: string; + onClick: () => any; + }; + }; +}; // @public export type DocsTableProps = { @@ -199,7 +224,10 @@ export type TechDocsCustomHomeProps = { // @public export type TechDocsEntityMetadata = Entity & { - locationMetadata?: LocationSpec; + locationMetadata?: { + type: string; + target: string; + }; }; // @public diff --git a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx index 323cdab96a..b875ba4e98 100644 --- a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx +++ b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx @@ -131,3 +131,6 @@ export const DocsTable = (props: DocsTableProps) => { ); }; + +DocsTable.columns = columnFactories; +DocsTable.actions = actionFactories; From d0f60325905339ff0901caa49707d3f86234a4c6 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 25 Feb 2022 13:47:26 +0100 Subject: [PATCH 16/22] add techdocs to list of packages with no warnings in api extractor script Signed-off-by: Emma Indal --- scripts/api-extractor.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index 482b011ffb..e73dd9a09f 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -239,6 +239,7 @@ const NO_WARNING_PACKAGES = [ 'plugins/tech-insights-backend-module-jsonfc', 'plugins/tech-insights-common', 'plugins/tech-insights-node', + 'plugins/techdocs', 'plugins/todo', 'plugins/todo-backend', ]; From d0c90c4f649fece59052a406eccf0710d016d000 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 25 Feb 2022 14:21:11 +0100 Subject: [PATCH 17/22] replace all TechDocsPage -> TechDocsReaderPage and TechDocsPageHeader -> TechDocsReaderPageHeader except in docs Signed-off-by: Emma Indal --- packages/app/src/components/techdocs/TechDocsPage.tsx | 10 +++++----- .../src/reader/components/TechDocsReaderPage.test.tsx | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/app/src/components/techdocs/TechDocsPage.tsx b/packages/app/src/components/techdocs/TechDocsPage.tsx index be11e30e61..4f49cf38e8 100644 --- a/packages/app/src/components/techdocs/TechDocsPage.tsx +++ b/packages/app/src/components/techdocs/TechDocsPage.tsx @@ -16,18 +16,18 @@ import { Content } from '@backstage/core-components'; import { - TechDocsPageHeader, - TechDocsPage, + TechDocsReaderPageHeader, + TechDocsReaderPage, Reader, } from '@backstage/plugin-techdocs'; import React from 'react'; const DefaultTechDocsPage = () => { return ( - + {({ techdocsMetadataValue, entityMetadataValue, entityRef, onReady }) => ( <> - { )} - + ); }; diff --git a/plugins/techdocs/src/reader/components/TechDocsReaderPage.test.tsx b/plugins/techdocs/src/reader/components/TechDocsReaderPage.test.tsx index 76bf195489..55637806a3 100644 --- a/plugins/techdocs/src/reader/components/TechDocsReaderPage.test.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsReaderPage.test.tsx @@ -40,10 +40,10 @@ jest.mock('react-router-dom', () => { }; }); -jest.mock('./TechDocsPageHeader', () => { +jest.mock('./TechDocsReaderPageHeader', () => { return { __esModule: true, - TechDocsPageHeader: () =>
, + TechDocsReaderPageHeader: () =>
, }; }); From 8049538eb1093b1318524bedd7cdbd8e0a5a19e9 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 25 Feb 2022 14:23:49 +0100 Subject: [PATCH 18/22] TechDocsIndexPage to fall back to DefaultTechDocsHome as LegacyTechDocsHome is deprecated Signed-off-by: Emma Indal --- packages/app/src/App.tsx | 4 +--- .../templates/default-app/packages/app/src/App.tsx | 5 +---- plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx | 5 +++++ plugins/techdocs/src/home/components/TechDocsIndexPage.tsx | 4 ++-- plugins/techdocs/src/index.ts | 1 - 5 files changed, 9 insertions(+), 10 deletions(-) diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx index 345915189a..f6d47c82f8 100644 --- a/packages/app/src/App.tsx +++ b/packages/app/src/App.tsx @@ -169,9 +169,7 @@ const routes = ( /> } /> - }> - - + } /> } diff --git a/packages/create-app/templates/default-app/packages/app/src/App.tsx b/packages/create-app/templates/default-app/packages/app/src/App.tsx index 9b6518620d..6f00993273 100644 --- a/packages/create-app/templates/default-app/packages/app/src/App.tsx +++ b/packages/create-app/templates/default-app/packages/app/src/App.tsx @@ -15,7 +15,6 @@ import { orgPlugin } from '@backstage/plugin-org'; import { SearchPage } from '@backstage/plugin-search'; import { TechRadarPage } from '@backstage/plugin-tech-radar'; import { - DefaultTechDocsHome, TechDocsIndexPage, techdocsPlugin, TechDocsReaderPage, @@ -65,9 +64,7 @@ const routes = ( > {entityPage} - }> - - + } /> } diff --git a/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx b/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx index 750b1d89bc..4dcff501ed 100644 --- a/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx +++ b/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx @@ -49,6 +49,11 @@ export type DefaultTechDocsHomeProps = { actions?: TableProps['actions']; }; +/** + * Component which renders a default documentation landing page. + * + * @public + */ export const DefaultTechDocsHome = (props: DefaultTechDocsHomeProps) => { const { initialFilter = 'all', columns, actions } = props; return ( diff --git a/plugins/techdocs/src/home/components/TechDocsIndexPage.tsx b/plugins/techdocs/src/home/components/TechDocsIndexPage.tsx index ff694d3570..4467baf2a1 100644 --- a/plugins/techdocs/src/home/components/TechDocsIndexPage.tsx +++ b/plugins/techdocs/src/home/components/TechDocsIndexPage.tsx @@ -16,10 +16,10 @@ import React from 'react'; import { useOutlet } from 'react-router'; -import { LegacyTechDocsHome } from './LegacyTechDocsHome'; +import { DefaultTechDocsHome } from './DefaultTechDocsHome'; export const TechDocsIndexPage = () => { const outlet = useOutlet(); - return outlet || ; + return outlet || ; }; diff --git a/plugins/techdocs/src/index.ts b/plugins/techdocs/src/index.ts index 400874ada7..e43d7400ee 100644 --- a/plugins/techdocs/src/index.ts +++ b/plugins/techdocs/src/index.ts @@ -28,7 +28,6 @@ export * from './search'; export * from './home'; export { EntityTechdocsContent, - DefaultTechDocsHome, TechDocsCustomHome, TechDocsIndexPage, TechdocsPage, From 69a5d47ff82773e7cf99a79a4a840c13536d9e2c Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 25 Feb 2022 14:24:51 +0100 Subject: [PATCH 19/22] export TechDocsReaderPage as routable extension, do not export DefaultTechDocsHome as routable extension Signed-off-by: Emma Indal --- plugins/techdocs/src/index.ts | 1 + plugins/techdocs/src/plugin.ts | 32 +++++++++---------- .../reader/components/TechDocsReaderPage.tsx | 5 --- .../techdocs/src/reader/components/index.ts | 7 +++- 4 files changed, 23 insertions(+), 22 deletions(-) diff --git a/plugins/techdocs/src/index.ts b/plugins/techdocs/src/index.ts index e43d7400ee..c31f8b7370 100644 --- a/plugins/techdocs/src/index.ts +++ b/plugins/techdocs/src/index.ts @@ -31,6 +31,7 @@ export { TechDocsCustomHome, TechDocsIndexPage, TechdocsPage, + TechDocsReaderPage, techdocsPlugin as plugin, techdocsPlugin, } from './plugin'; diff --git a/plugins/techdocs/src/plugin.ts b/plugins/techdocs/src/plugin.ts index 35960c7cbb..2e3967cb6d 100644 --- a/plugins/techdocs/src/plugin.ts +++ b/plugins/techdocs/src/plugin.ts @@ -119,22 +119,6 @@ export const TechDocsCustomHome = techdocsPlugin.provide( }), ); -/** - * Component which renders a default documentation landing page. - * - * @public - */ -export const DefaultTechDocsHome = techdocsPlugin.provide( - createRoutableExtension({ - name: 'DefaultTechDocsHome', - component: () => - import('./home/components/DefaultTechDocsHome').then( - m => m.DefaultTechDocsHome, - ), - mountPoint: rootRouteRef, - }), -); - /** * Responsible for rendering the provided router element * @@ -150,3 +134,19 @@ export const TechDocsIndexPage = techdocsPlugin.provide( mountPoint: rootRouteRef, }), ); + +/** + * Component responsible for composing a TechDocs reader page experience + * + * @public + */ +export const TechDocsReaderPage = techdocsPlugin.provide( + createRoutableExtension({ + name: 'TechDocsReaderPage', + component: () => + import('./reader/components/TechDocsReaderPage').then( + m => m.TechDocsReaderPage, + ), + mountPoint: rootDocsRouteRef, + }), +); diff --git a/plugins/techdocs/src/reader/components/TechDocsReaderPage.tsx b/plugins/techdocs/src/reader/components/TechDocsReaderPage.tsx index eea6b94d3d..d03ea2ef61 100644 --- a/plugins/techdocs/src/reader/components/TechDocsReaderPage.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsReaderPage.tsx @@ -50,11 +50,6 @@ export type TechDocsReaderPageProps = { children?: TechDocsReaderPageRenderFunction | React.ReactNode; }; -/** - * Component responsible for composing a TechDocs reader page experience - * - * @public - */ export const TechDocsReaderPage = (props: TechDocsReaderPageProps) => { const { children } = props; const { NotFoundErrorPage } = useApp().getComponents(); diff --git a/plugins/techdocs/src/reader/components/index.ts b/plugins/techdocs/src/reader/components/index.ts index 861f8e7bdb..3124a92f93 100644 --- a/plugins/techdocs/src/reader/components/index.ts +++ b/plugins/techdocs/src/reader/components/index.ts @@ -15,7 +15,12 @@ */ export * from './Reader'; -export * from './TechDocsReaderPage'; +export type { + TechDocsReaderPageProps, + TechDocsPageRenderFunction, + TechDocsReaderPageRenderFunction, +} from './TechDocsReaderPage'; +export { TechDocsPage } from './TechDocsReaderPage'; export * from './TechDocsReaderPageHeader'; export * from './TechDocsStateIndicator'; From 0492fdf964598e4b909a1e2e1f3dd4fd6d35f902 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 25 Feb 2022 14:33:01 +0100 Subject: [PATCH 20/22] update create-app changeset Signed-off-by: Emma Indal --- .changeset/fast-paws-arrive.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.changeset/fast-paws-arrive.md b/.changeset/fast-paws-arrive.md index fc4b531711..9c5f4f444f 100644 --- a/.changeset/fast-paws-arrive.md +++ b/.changeset/fast-paws-arrive.md @@ -20,3 +20,12 @@ To apply this change to an existing app, make the following change to `packages/ result={document} /> ``` + +The `TechDocsIndexPage` now uses `DefaultTechDocsHome` as fall back if no children is provided as `LegacyTechDocsHome` is marked as deprecated. If you do not use a custom techdocs homepage, you can therefore update your app to the following: + +```diff +- }> +- +- ++ } /> +``` From b6d7475a6ceef2b8a1087ead0fcd26fc94206330 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 25 Feb 2022 14:34:24 +0100 Subject: [PATCH 21/22] delete unused import Signed-off-by: Emma Indal --- packages/app/src/App.tsx | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx index f6d47c82f8..374d637b2e 100644 --- a/packages/app/src/App.tsx +++ b/packages/app/src/App.tsx @@ -65,7 +65,6 @@ import { import { SearchPage } from '@backstage/plugin-search'; import { TechRadarPage } from '@backstage/plugin-tech-radar'; import { - DefaultTechDocsHome, TechDocsIndexPage, techdocsPlugin, TechDocsReaderPage, From 2f96848ee9921cf4f3d3dd92e95f06c01d968578 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Fri, 25 Feb 2022 14:52:29 +0100 Subject: [PATCH 22/22] update tests for TechDocsIndexPage Signed-off-by: Emma Indal --- .../src/home/components/TechDocsIndexPage.test.tsx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/techdocs/src/home/components/TechDocsIndexPage.test.tsx b/plugins/techdocs/src/home/components/TechDocsIndexPage.test.tsx index fbeca7cfd4..1d018eec70 100644 --- a/plugins/techdocs/src/home/components/TechDocsIndexPage.test.tsx +++ b/plugins/techdocs/src/home/components/TechDocsIndexPage.test.tsx @@ -24,8 +24,8 @@ jest.mock('react-router', () => ({ useOutlet: jest.fn().mockReturnValue('Route Children'), })); -jest.mock('./LegacyTechDocsHome', () => ({ - LegacyTechDocsHome: jest.fn().mockReturnValue('LegacyTechDocsHomeMock'), +jest.mock('./DefaultTechDocsHome', () => ({ + DefaultTechDocsHome: jest.fn().mockReturnValue('DefaultTechDocsHomeMock'), })); describe('TechDocsIndexPage', () => { @@ -35,10 +35,10 @@ describe('TechDocsIndexPage', () => { expect(getByText('Route Children')).toBeInTheDocument(); }); - it('renders legacy TechDocs home when no router children are provided', async () => { + it('renders DefaultTechDocsHome when no router children are provided', async () => { (useOutlet as jest.Mock).mockReturnValueOnce(null); const { getByText } = await renderInTestApp(); - expect(getByText('LegacyTechDocsHomeMock')).toBeInTheDocument(); + expect(getByText('DefaultTechDocsHomeMock')).toBeInTheDocument(); }); });