From 5a85ef7f3f92142c9a589057dbd717c6659936c7 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:33:45 +0100 Subject: [PATCH] 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';