feat: add live preview gallery to the home page add widget dialog

.changeset/widget-preview-gallery.md

@@ -0,0 +1,10 @@
+---
+'@openchoreo/backstage-portal-app': minor
+---
+
+Replace the plain Add widget list on the home page with a live preview gallery.
+
+- Shows each available widget as a card with a live preview, title and description in a three column grid.
+- Adds a search box that filters widgets by title and description, with an empty state when nothing matches.
+- Copies Backstage's `CustomHomepageGrid` and its supporting files into the portal app, because the add widget dialog is private to `@backstage/plugin-home`.
+- Declares the `react-grid-layout`, `react-resizable`, `lodash` and `zod` dependencies that the copied files import.

packages/portal-app/package.json

@@ -92,8 +92,12 @@
     "d3-zoom": "^3.0.0",
     "devicons-react": "^1.5.0",
     "json-schema": "0.4.0",
+    "lodash": "^4.18.1",
+    "react-grid-layout": "1.3.4",
+    "react-resizable": "^3.0.5",
     "react-use": "17.6.0",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.1",
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "react": "^18.0.0",
@@ -109,7 +113,9 @@
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "14.3.1",
     "@testing-library/user-event": "14.6.1",
+    "@types/lodash": "^4",
     "@types/react-dom": "*",
+    "@types/react-grid-layout": "^1.3.5",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "react-router-dom": "6.30.1"

packages/portal-app/src/components/Home/AddWidgetDialog.test.tsx

@@ -0,0 +1,103 @@
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { renderInTestApp } from '@backstage/test-utils';
+import { AddWidgetDialog } from './AddWidgetDialog';
+import type { Widget } from './types';
+
+const makeWidget = (
+  name: string,
+  title: string,
+  description: string,
+): Widget => ({
+  name,
+  title,
+  description,
+  component: <div data-testid={`preview-${name}`}>{title} preview</div>,
+});
+
+const widgets: Widget[] = [
+  makeWidget('Projects', 'My Projects', 'Project and component counts'),
+  makeWidget('Deployments', 'Recent Deployments', 'Latest releases'),
+  makeWidget('Visited', 'Recently Visited', 'Pages you visited recently'),
+];
+
+const renderDialog = (items: Widget[] = widgets, handleAdd = jest.fn()) =>
+  renderInTestApp(<AddWidgetDialog widgets={items} handleAdd={handleAdd} />);
+
+describe('AddWidgetDialog', () => {
+  it('shows every available widget with its title and description', async () => {
+    await renderDialog();
+
+    expect(screen.getByText('My Projects')).toBeInTheDocument();
+    expect(screen.getByText('Recent Deployments')).toBeInTheDocument();
+    expect(screen.getByText('Latest releases')).toBeInTheDocument();
+    expect(screen.getAllByRole('button')).toHaveLength(widgets.length);
+  });
+
+  it('filters widgets by title as the user types', async () => {
+    await renderDialog();
+
+    await userEvent.type(screen.getByPlaceholderText('Search widgets'), 'proj');
+
+    expect(screen.getByText('My Projects')).toBeInTheDocument();
+    expect(screen.queryByText('Recent Deployments')).not.toBeInTheDocument();
+    expect(screen.queryByText('Recently Visited')).not.toBeInTheDocument();
+  });
+
+  it('also matches on description, ignoring case', async () => {
+    await renderDialog();
+
+    await userEvent.type(
+      screen.getByPlaceholderText('Search widgets'),
+      'LATEST',
+    );
+
+    expect(screen.getByText('Recent Deployments')).toBeInTheDocument();
+    expect(screen.queryByText('My Projects')).not.toBeInTheDocument();
+  });
+
+  it('shows a message when nothing matches the search', async () => {
+    await renderDialog();
+
+    await userEvent.type(
+      screen.getByPlaceholderText('Search widgets'),
+      'xyz123',
+    );
+
+    expect(
+      screen.getByText('No widgets match your search.'),
+    ).toBeInTheDocument();
+    expect(screen.queryByText('My Projects')).not.toBeInTheDocument();
+  });
+
+  it('calls handleAdd with the widget when its card is clicked', async () => {
+    const handleAdd = jest.fn();
+    await renderDialog(widgets, handleAdd);
+
+    await userEvent.click(screen.getByText('Recent Deployments'));
+
+    expect(handleAdd).toHaveBeenCalledTimes(1);
+    expect(handleAdd).toHaveBeenCalledWith(widgets[1]);
+  });
+
+  it('shows the empty message and no search box when no widgets are left', async () => {
+    await renderDialog([]);
+
+    expect(
+      screen.getByText(
+        'All available widgets have been added to the dashboard.',
+      ),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByPlaceholderText('Search widgets'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('hides live previews from assistive tech and the tab order', async () => {
+    await renderDialog();
+
+    const preview = screen.getByTestId('preview-Projects').parentElement;
+    expect(preview).toHaveAttribute('aria-hidden', 'true');
+    expect(preview).toHaveAttribute('inert');
+  });
+});

packages/portal-app/src/components/Home/AddWidgetDialog.tsx

@@ -0,0 +1,209 @@
+/*
+ * Copyright 2023 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 { useMemo, useState } from 'react';
+import { Widget } from './types';
+import Box from '@material-ui/core/Box';
+import DialogContent from '@material-ui/core/DialogContent';
+import DialogTitle from '@material-ui/core/DialogTitle';
+import Typography from '@material-ui/core/Typography';
+import ButtonBase from '@material-ui/core/ButtonBase';
+import TextField from '@material-ui/core/TextField';
+import InputAdornment from '@material-ui/core/InputAdornment';
+import SearchIcon from '@material-ui/icons/Search';
+import { makeStyles, createStyles, Theme } from '@material-ui/core/styles';
+import { useTranslationRef } from '@backstage/frontend-plugin-api';
+import { homeTranslationRef } from './translation';
+
+interface AddWidgetDialogProps {
+  widgets: Widget[];
+  handleAdd: (widget: Widget) => void;
+}
+
+const getTitle = (widget: Widget) => {
+  return widget.title || widget.name;
+};
+
+const useStyles = makeStyles((theme: Theme) =>
+  createStyles({
+    grid: {
+      display: 'flex',
+      flexWrap: 'wrap',
+      justifyContent: 'center',
+      gap: theme.spacing(2),
+      maxHeight: '60vh',
+      overflowY: 'auto',
+      padding: theme.spacing(0.5),
+    },
+    card: {
+      flex: `0 0 calc((100% - ${theme.spacing(2) * 2}px) / 3)`,
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'stretch',
+      justifyContent: 'flex-start',
+      borderRadius: theme.spacing(1),
+      border: `1px solid ${theme.palette.divider}`,
+      overflow: 'hidden',
+      textAlign: 'left',
+      transition: 'box-shadow 0.15s ease, transform 0.15s ease',
+      '&:hover': {
+        boxShadow: theme.shadows[4],
+        transform: 'translateY(-2px)',
+      },
+      '&:hover $addOverlay': {
+        opacity: 1,
+      },
+    },
+    previewFrame: {
+      position: 'relative',
+      height: 160,
+      overflow: 'hidden',
+      backgroundColor: theme.palette.background.default,
+      pointerEvents: 'none',
+      display: 'flex',
+      alignItems: 'flex-start',
+      justifyContent: 'center',
+    },
+    previewScale: {
+      position: 'absolute',
+      top: 0,
+      left: '50%',
+      width: '166%',
+      height: '166%',
+      transform: 'translate(-50%, 0) scale(0.6)',
+      transformOrigin: 'top center',
+    },
+    clickBlocker: {
+      position: 'absolute',
+      inset: 0,
+    },
+    addOverlay: {
+      position: 'absolute',
+      inset: 0,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      backgroundColor: 'rgba(0, 0, 0, 0.45)',
+      color: theme.palette.common.white,
+      opacity: 0,
+      transition: 'opacity 0.15s ease',
+      fontWeight: 600,
+    },
+    meta: {
+      padding: theme.spacing(1.5),
+    },
+    searchField: {
+      marginBottom: theme.spacing(2),
+    },
+  }),
+);
+
+export const AddWidgetDialog = (props: AddWidgetDialogProps) => {
+  const { widgets, handleAdd } = props;
+  const { t } = useTranslationRef(homeTranslationRef);
+  const classes = useStyles();
+  const [searchQuery, setSearchQuery] = useState('');
+
+  const filteredWidgets = useMemo(() => {
+    const query = searchQuery.trim().toLowerCase();
+    if (!query) {
+      return widgets;
+    }
+    return widgets.filter(widget => {
+      const title = getTitle(widget).toLowerCase();
+      const description = (widget.description ?? '').toLowerCase();
+      return title.includes(query) || description.includes(query);
+    });
+  }, [widgets, searchQuery]);
+
+  return (
+    <>
+      <DialogTitle>{t('addWidgetDialog.title')}</DialogTitle>
+      <DialogContent>
+        {widgets.length === 0 ? (
+          <Box pb={3} textAlign="center">
+            <Typography variant="body1" color="textSecondary">
+              {t('addWidgetDialog.noAvailableWidgets')}
+            </Typography>
+          </Box>
+        ) : (
+          <>
+            <TextField
+              className={classes.searchField}
+              fullWidth
+              variant="outlined"
+              size="small"
+              placeholder={t('addWidgetDialog.searchPlaceholder')}
+              value={searchQuery}
+              onChange={e => setSearchQuery(e.target.value)}
+              InputProps={{
+                startAdornment: (
+                  <InputAdornment position="start">
+                    <SearchIcon fontSize="small" />
+                  </InputAdornment>
+                ),
+              }}
+            />
+            {filteredWidgets.length === 0 ? (
+              <Box pb={3} textAlign="center">
+                <Typography variant="body1" color="textSecondary">
+                  {t('addWidgetDialog.noMatchingWidgets')}
+                </Typography>
+              </Box>
+            ) : (
+              <div className={classes.grid}>
+                {filteredWidgets.map(widget => (
+                  <ButtonBase
+                    key={widget.name}
+                    className={classes.card}
+                    onClick={() => handleAdd(widget)}
+                    focusRipple
+                  >
+                    <div className={classes.previewFrame}>
+                      <div
+                        className={classes.previewScale}
+                        aria-hidden="true"
+                        {...{ inert: '' }}
+                      >
+                        {widget.component}
+                      </div>
+                      <div className={classes.clickBlocker} />
+                      <div className={classes.addOverlay}>
+                        <Typography variant="button" style={{ color: '#fff' }}>
+                          + {t('addWidgetDialog.title')}
+                        </Typography>
+                      </div>
+                    </div>
+                    <div className={classes.meta}>
+                      <Typography variant="subtitle2" color="textPrimary">
+                        {getTitle(widget)}
+                      </Typography>
+                      {widget.description && (
+                        <Typography variant="caption" color="textSecondary">
+                          {widget.description}
+                        </Typography>
+                      )}
+                    </div>
+                  </ButtonBase>
+                ))}
+              </div>
+            )}
+          </>
+        )}
+      </DialogContent>
+    </>
+  );
+};