Add <EntityListDocsGrid> and extend <DocsCardGrid> to display the entity title

Signed-off-by: Oliver Sand <oliver.sand@sda-se.com>

.changeset/few-fishes-heal.md

@@ -0,0 +1,9 @@
+---
+'@backstage/plugin-techdocs': patch
+---
+
+Add `<EntityListDocsGrid>` as an alternative to `<EntityListDocsTable>` that
+shows a grid of card instead of table.
+
+Extend `<DocsCardGrid>` to display the entity title of the entity instead of the
+name if available.

plugins/techdocs/api-report.md

@@ -145,6 +145,11 @@ export type DocsTableRow = {
 // @public (undocumented)
 export const EmbeddedDocsRouter: (_props: Props_2) => 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)
+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)

plugins/techdocs/src/home/components/DocsCardGrid.test.tsx

@@ -14,12 +14,12 @@
  * limitations under the License.
  */
 
+import { configApiRef } from '@backstage/core-plugin-api';
 import { wrapInTestApp } from '@backstage/test-utils';
 import { render } from '@testing-library/react';
 import React from 'react';
-import { configApiRef } from '@backstage/core-plugin-api';
-import { DocsCardGrid } from './DocsCardGrid';
 import { rootDocsRouteRef } from '../../routes';
+import { DocsCardGrid } from './DocsCardGrid';
 
 // Hacky way to mock a specific boolean config value.
 const getOptionalBooleanMock = jest.fn().mockReturnValue(false);
@@ -126,4 +126,32 @@ describe('Entity Docs Card Grid', () => {
       '/techdocs/SomeNamespace/TestKind/testName',
     );
   });
+
+  it('should render entity title if available', async () => {
+    const { findByText } = render(
+      wrapInTestApp(
+        <DocsCardGrid
+          entities={[
+            {
+              apiVersion: 'version',
+              kind: 'TestKind',
+              metadata: {
+                name: 'testName',
+                title: 'TestTitle',
+              },
+              spec: {
+                owner: 'techdocs@example.com',
+              },
+            },
+          ]}
+        />,
+        {
+          mountedRoutes: {
+            '/docs/:namespace/:kind/:name/*': rootDocsRouteRef,
+          },
+        },
+      ),
+    );
+    expect(await findByText('TestTitle')).toBeInTheDocument();
+  });
 });

plugins/techdocs/src/home/components/DocsCardGrid.tsx

@@ -49,7 +49,9 @@ export const DocsCardGrid = ({
         : entities.map((entity, index: number) => (
             <Card key={index}>
               <CardMedia>
-                <ItemCardHeader title={entity.metadata.name} />
+                <ItemCardHeader
+                  title={entity.metadata.title ?? entity.metadata.name}
+                />
               </CardMedia>
               <CardContent>{entity.metadata.description}</CardContent>
               <CardActions>

plugins/techdocs/src/home/components/EntityListDocsGrid.tsx

@@ -0,0 +1,50 @@
+/*
+ * 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.
+ */
+import {
+  CodeSnippet,
+  Progress,
+  WarningPanel,
+} from '@backstage/core-components';
+import { useEntityListProvider } from '@backstage/plugin-catalog-react';
+import React from 'react';
+import { DocsCardGrid } from './DocsCardGrid';
+
+export const EntityListDocsGrid = () => {
+  const { loading, error, entities } = useEntityListProvider();
+
+  if (error) {
+    return (
+      <WarningPanel
+        severity="error"
+        title="Could not load available documentation."
+      >
+        <CodeSnippet language="text" text={error.toString()} />
+      </WarningPanel>
+    );
+  }
+
+  if (loading || !entities) {
+    return <Progress />;
+  }
+
+  entities.sort((a, b) =>
+    (a.metadata.title ?? a.metadata.name).localeCompare(
+      b.metadata.title ?? b.metadata.name,
+    ),
+  );
+
+  return <DocsCardGrid entities={entities} />;
+};

plugins/techdocs/src/home/components/index.ts

@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
-export { EntityListDocsTable } from './EntityListDocsTable';
 export { DefaultTechDocsHome } from './DefaultTechDocsHome';
+export { EntityListDocsGrid } from './EntityListDocsGrid';
+export { EntityListDocsTable } from './EntityListDocsTable';
+export type { PanelType } from './TechDocsCustomHome';
 export { TechDocsPageWrapper } from './TechDocsPageWrapper';
 export { TechDocsPicker } from './TechDocsPicker';
-export type { PanelType } from './TechDocsCustomHome';
 export type { DocsTableRow } from './types';

plugins/techdocs/src/index.ts

@@ -24,14 +24,15 @@ export * from './api';
 export { techdocsApiRef, techdocsStorageApiRef } from './api';
 export type { TechDocsApi, TechDocsStorageApi } from './api';
 export { TechDocsClient, TechDocsStorageClient } from './client';
-export type { DocsTableRow, PanelType } from './home/components';
+export * from './components/DocsResultListItem';
 export {
-  EntityListDocsTable,
   DefaultTechDocsHome,
+  EntityListDocsGrid,
+  EntityListDocsTable,
   TechDocsPageWrapper,
   TechDocsPicker,
 } from './home/components';
-export * from './components/DocsResultListItem';
+export type { DocsTableRow, PanelType } from './home/components';
 export {
   DocsCardGrid,
   DocsTable,
@@ -44,4 +45,4 @@ export {
   TechDocsReaderPage,
 } from './plugin';
 export * from './reader';
-export { EmbeddedDocsRouter, Router, isTechDocsAvailable } from './Router';
+export { EmbeddedDocsRouter, isTechDocsAvailable, Router } from './Router';