change naming from widget to panel

Signed-off-by: Chongyang Adrian, Ke <ftt.adrian.ke@grabtaxi.com>

docs/features/techdocs/how-to-guides.md

@@ -92,7 +92,7 @@ In your main App.tsx:
 ```tsx
 import {
   TechDocsCustomHome,
-  WidgetType,
+  PanelType,
   TechDocsReaderPage,
 } from '@backstage/plugin-techdocs';
 import { Entity } from '@backstage/catalog-model';
@@ -105,17 +105,17 @@ const tabsConfig = [
         title: 'Custom Documents Cards 1',
         description:
           'Explore your internal technical ecosystem through documentation.',
-        // sets maximum height of widget, as CSS maxHeight attribute
-        widgetMaxHeight: '400px'
-        widgetType: 'DocsCardGrid' as WidgetType,
+        panelType: 'DocsCardGrid' as PanelType,
+        // optional, is applied to a container of the panel (excludes header of panel)
+        panelCSS: { maxHeight: '400px' },
         filterPredicate: (entity: Entity) => !!entity.metadata.annotations?.['customCardAnnotationOne'];
     },
       {
         title: 'Custom Documents Cards 2',
         description:
           'Explore your internal technical ecosystem through documentation.',
-        widgetMaxHeight: '400px'
-        widgetType: 'DocsCardGrid' as WidgetType,
+        panelType: 'DocsCardGrid' as PanelType,
+        panelCSS: { maxHeight: '400px' },
         filterPredicate: (entity: Entity) => !!entity.metadata.annotations?.['customCardAnnotationTwo'];
       },
     ],
@@ -127,7 +127,7 @@ const tabsConfig = [
         title: 'Overview',
         description:
           'Explore your internal technical ecosystem through documentation.',
-        widgetType: 'DocsTable' as WidgetType,
+        panelType: 'DocsTable' as PanelType,
         filterPredicate: () => true,
       },
     ],
@@ -150,6 +150,10 @@ const routes = (
 An example of tabsConfig that corresponds to the default documentation home page
 can be found at `plugins/techdocs/src/home/components/TechDocsHome.tsx`.
 
+Currently `panelType` has DocsCardGrid and DocsTable available. We currently
+recommend that DocsCardGrid can be optionally vertically stacked by setting a
+maxHeight using `panelCSS`, and DocsTable to be in a tab by itself.
+
 ### 2nd way: Custom home page plugin
 
 A custom home page plugin can be built that uses the components extensions

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

@@ -90,7 +90,11 @@ export const DocsTable = ({
     <>
       {documents && documents.length > 0 ? (
         <Table
-          options={{ paging: true, pageSize: 20, search: true }}
+          options={{
+            paging: true,
+            pageSize: 20,
+            search: true,
+          }}
           data={documents}
           columns={columns}
           title={

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

@@ -19,7 +19,7 @@ import { CatalogApi, catalogApiRef } from '@backstage/plugin-catalog-react';
 import { renderInTestApp } from '@backstage/test-utils';
 import { screen } from '@testing-library/react';
 import React from 'react';
-import { TechDocsCustomHome, WidgetType } from './TechDocsCustomHome';
+import { TechDocsCustomHome, PanelType } from './TechDocsCustomHome';
 
 describe('TechDocsCustomHome', () => {
   const catalogApi: Partial<CatalogApi> = {
@@ -32,22 +32,22 @@ describe('TechDocsCustomHome', () => {
     const tabsConfig = [
       {
         label: 'First Tab',
-        widgets: [
+        panels: [
           {
             title: 'First Tab',
             description: 'First Tab Description',
-            widgetType: 'DocsCardGrid' as WidgetType,
+            panelType: 'DocsCardGrid' as PanelType,
             filterPredicate: () => true,
           },
         ],
       },
       {
         label: 'Second Tab ',
-        widgets: [
+        panels: [
           {
             title: 'Second Tab',
             description: 'Second Tab Description',
-            widgetType: 'DocsTable' as WidgetType,
+            panelType: 'DocsTable' as PanelType,
             filterPredicate: () => true,
           },
         ],

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

@@ -37,46 +37,46 @@ import {
 import { DocsTable } from './DocsTable';
 import { DocsCardGrid } from './DocsCardGrid';
 
-const widgets = {
+const panels = {
   DocsTable: DocsTable,
   DocsCardGrid: DocsCardGrid,
 };
 
-export type WidgetType = 'DocsCardGrid' | 'DocsTable';
+export type PanelType = 'DocsCardGrid' | 'DocsTable';
 
-export interface WidgetConfig {
+export interface PanelConfig {
   title: string;
   description: string;
-  widgetType: WidgetType;
-  widgetMaxHeight?: string;
+  panelType: PanelType;
+  panelCSS?: {};
   filterPredicate: (entity: Entity) => boolean;
 }
 
 export interface TabConfig {
   label: string;
-  widgets: WidgetConfig[];
+  panels: PanelConfig[];
 }
 
 export type TabsConfig = TabConfig[];
 
-const CustomWidget = ({
+const CustomPanel = ({
   config,
   entities,
   index,
 }: {
-  config: WidgetConfig;
+  config: PanelConfig;
   entities: Entity[];
   index: number;
 }) => {
   const useStyles = makeStyles({
-    widgetContainer: {
-      maxHeight: config.widgetMaxHeight || 'inherit',
+    panelContainer: {
       marginBottom: '2rem',
       overflow: 'auto',
+      ...(config.panelCSS ? config.panelCSS : {}),
     },
   });
   const classes = useStyles();
-  const Widget = widgets[config.widgetType];
+  const Panel = panels[config.panelType];
   const shownEntities = entities.filter(config.filterPredicate);
   return (
     <>
@@ -87,8 +87,8 @@ const CustomWidget = ({
           </SupportButton>
         ) : null}
       </ContentHeader>
-      <div className={classes.widgetContainer}>
-        <Widget entities={shownEntities} />
+      <div className={classes.panelContainer}>
+        <Panel entities={shownEntities} />
       </div>
     </>
   );
@@ -155,8 +155,8 @@ export const TechDocsCustomHome = ({
         }))}
       />
       <Content>
-        {currentTabConfig.widgets.map((config, index) => (
-          <CustomWidget
+        {currentTabConfig.panels.map((config, index) => (
+          <CustomPanel
             key={index}
             config={config}
             entities={!!entities ? entities : []}

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

@@ -18,7 +18,7 @@ import React from 'react';
 import { Entity } from '@backstage/catalog-model';
 import { useOwnUser } from '../hooks';
 import { isOwnerOf } from '@backstage/plugin-catalog-react';
-import { WidgetType, TechDocsCustomHome } from './TechDocsCustomHome';
+import { PanelType, TechDocsCustomHome } from './TechDocsCustomHome';
 
 export const TechDocsHome = () => {
   const { value: user } = useOwnUser();
@@ -26,23 +26,24 @@ export const TechDocsHome = () => {
   const tabsConfig = [
     {
       label: 'Overview',
-      widgets: [
+      panels: [
         {
           title: 'Overview',
           description:
             'Explore your internal technical ecosystem through documentation.',
-          widgetType: 'DocsCardGrid' as WidgetType,
+          panelType: 'DocsCardGrid' as PanelType,
           filterPredicate: () => true,
         },
       ],
     },
     {
       label: 'Owned',
-      widgets: [
+      panels: [
         {
           title: 'Owned documents',
           description: 'Access your documentation.',
-          widgetType: 'DocsTable' as WidgetType,
+          panelType: 'DocsTable' as PanelType,
+          paneCSS: { maxHeight: '200px' },
           filterPredicate: (entity: Entity) => {
             if (!user) {
               return false;

plugins/techdocs/src/index.ts

@@ -27,4 +27,4 @@ export {
 export { Router, EmbeddedDocsRouter } from './Router';
 export * from './reader';
 export * from './api';
-export type { WidgetType } from './home/components/TechDocsCustomHome';
+export type { PanelType } from './home/components/TechDocsCustomHome';