feat: allow more customization of the custom homepage

This allows users to modify the actual grid properties from backstage
interface.

Signed-off-by: Heikki Hellgren <heikki.hellgren@op.fi>

.changeset/dull-bottles-teach.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-home': patch
+---
+
+Allow more customization for the CustomHomepageGrid

packages/app/src/components/home/templates/CustomizableTemplate.stories.tsx

@@ -0,0 +1,153 @@
+/*
+ * 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 {
+  HomePageStarredEntities,
+  HomePageRandomJoke,
+  CustomHomepageGrid,
+} from '@backstage/plugin-home';
+import {
+  starredEntitiesApiRef,
+  MockStarredEntitiesApi,
+  entityRouteRef,
+  catalogApiRef,
+} from '@backstage/plugin-catalog-react';
+import { wrapInTestApp, TestApiProvider } from '@backstage/test-utils';
+import { configApiRef } from '@backstage/core-plugin-api';
+import { ConfigReader } from '@backstage/config';
+import { searchApiRef } from '@backstage/plugin-search-react';
+import { HomePageSearchBar, searchPlugin } from '@backstage/plugin-search';
+import { HomePageCalendar } from '@backstage/plugin-gcalendar';
+import { MicrosoftCalendarCard } from '@backstage/plugin-microsoft-calendar';
+import React, { ComponentType } from 'react';
+
+const entities = [
+  {
+    apiVersion: '1',
+    kind: 'Component',
+    metadata: {
+      name: 'mock-starred-entity',
+      title: 'Mock Starred Entity!',
+    },
+  },
+  {
+    apiVersion: '1',
+    kind: 'Component',
+    metadata: {
+      name: 'mock-starred-entity-2',
+      title: 'Mock Starred Entity 2!',
+    },
+  },
+  {
+    apiVersion: '1',
+    kind: 'Component',
+    metadata: {
+      name: 'mock-starred-entity-3',
+      title: 'Mock Starred Entity 3!',
+    },
+  },
+  {
+    apiVersion: '1',
+    kind: 'Component',
+    metadata: {
+      name: 'mock-starred-entity-4',
+      title: 'Mock Starred Entity 4!',
+    },
+  },
+];
+
+const mockCatalogApi = {
+  getEntities: async () => ({ items: entities }),
+};
+
+const starredEntitiesApi = new MockStarredEntitiesApi();
+starredEntitiesApi.toggleStarred('component:default/example-starred-entity');
+starredEntitiesApi.toggleStarred('component:default/example-starred-entity-2');
+starredEntitiesApi.toggleStarred('component:default/example-starred-entity-3');
+starredEntitiesApi.toggleStarred('component:default/example-starred-entity-4');
+
+export default {
+  title: 'Plugins/Home/Templates',
+  decorators: [
+    (Story: ComponentType<{}>) =>
+      wrapInTestApp(
+        <>
+          <TestApiProvider
+            apis={[
+              [catalogApiRef, mockCatalogApi],
+              [starredEntitiesApiRef, starredEntitiesApi],
+              [searchApiRef, { query: () => Promise.resolve({ results: [] }) }],
+              [
+                configApiRef,
+                new ConfigReader({
+                  backend: {
+                    baseUrl: 'https://localhost:7007',
+                  },
+                }),
+              ],
+            ]}
+          >
+            <Story />
+          </TestApiProvider>
+        </>,
+        {
+          mountedRoutes: {
+            '/hello-company': searchPlugin.routes.root,
+            '/catalog/:namespace/:kind/:name': entityRouteRef,
+          },
+        },
+      ),
+  ],
+};
+export const CustomizableTemplate = () => {
+  // This is the default configuration that is shown to the user
+  // when first arriving to the homepage.
+  const defaultConfig = [
+    {
+      component: 'HomePageSearchBar',
+      x: 0,
+      y: 0,
+      width: 12,
+      height: 5,
+    },
+    {
+      component: 'HomePageRandomJoke',
+      x: 0,
+      y: 2,
+      width: 6,
+      height: 16,
+    },
+    {
+      component: 'HomePageStarredEntities',
+      x: 6,
+      y: 2,
+      width: 6,
+      height: 12,
+    },
+  ];
+
+  return (
+    <CustomHomepageGrid config={defaultConfig} rowHeight={10}>
+      // Insert the allowed widgets inside the grid. User can add, organize and
+      // remove the widgets as they want.
+      <HomePageSearchBar />
+      <HomePageRandomJoke />
+      <HomePageCalendar />
+      <MicrosoftCalendarCard />
+      <HomePageStarredEntities />
+    </CustomHomepageGrid>
+  );
+};

plugins/home/README.md

@@ -247,4 +247,5 @@ Additionally, the API is at a very early state, so contributing with additional
 
 ### Homepage Templates
 
-We are hoping that we together can build up a collection of Homepage templates. We therefore put together a place where we can collect all the templates for the Home Plugin in the [storybook](https://backstage.io/storybook/?path=/story/plugins-home-templates). If you would like to contribute with a template, start by taking a look at the [DefaultTemplate storybook example to create your own](/packages/app/src/components/home/templates/DefaultTemplate.stories.tsx), and then open a PR with your suggestion.
+We are hoping that we together can build up a collection of Homepage templates. We therefore put together a place where we can collect all the templates for the Home Plugin in the [storybook](https://backstage.io/storybook/?path=/story/plugins-home-templates).
+If you would like to contribute with a template, start by taking a look at the [DefaultTemplate storybook example](/packages/app/src/components/home/templates/DefaultTemplate.stories.tsx) or [CustomizableTemplate storybook example](/packages/app/src/components/home/templates/CustomizableTemplate.stories.tsx) to create your own, and then open a PR with your suggestion.

plugins/home/api-report.md

@@ -19,6 +19,9 @@ import { ReactNode } from 'react';
 import { RendererProps as RendererProps_2 } from '@backstage/plugin-home-react';
 import { RouteRef } from '@backstage/core-plugin-api';
 
+// @public
+export type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
 // @public @deprecated (undocumented)
 export type CardConfig = CardConfig_2;
 
@@ -77,11 +80,20 @@ export const CustomHomepageGrid: (
   props: CustomHomepageGridProps,
 ) => JSX.Element;
 
-// @public (undocumented)
+// @public
 export type CustomHomepageGridProps = {
   children?: ReactNode;
   config?: LayoutConfiguration[];
   rowHeight?: number;
+  breakpoints?: Record<Breakpoint, number>;
+  cols?: Record<Breakpoint, number>;
+  containerPadding?: [number, number] | Record<Breakpoint, [number, number]>;
+  containerMargin?: [number, number] | Record<Breakpoint, [number, number]>;
+  maxRows?: number;
+  style?: React_2.CSSProperties;
+  compactType?: 'vertical' | 'horizontal' | null;
+  allowOverlap?: boolean;
+  preventCollision?: boolean;
 };
 
 // @public

plugins/home/src/components/CustomHomepage/CustomHomepageButtons.tsx

@@ -20,6 +20,7 @@ import SaveIcon from '@material-ui/icons/Save';
 import DeleteIcon from '@material-ui/icons/Delete';
 import AddIcon from '@material-ui/icons/Add';
 import EditIcon from '@material-ui/icons/Edit';
+import CancelIcon from '@material-ui/icons/Cancel';
 
 const useStyles = makeStyles((theme: Theme) =>
   createStyles({
@@ -41,6 +42,8 @@ interface CustomHomepageButtonsProps {
   clearLayout: () => void;
   setAddWidgetDialogOpen: (open: boolean) => void;
   changeEditMode: (mode: boolean) => void;
+  defaultConfigAvailable: boolean;
+  restoreDefault: () => void;
 }
 export const CustomHomepageButtons = (props: CustomHomepageButtonsProps) => {
   const {
@@ -49,6 +52,8 @@ export const CustomHomepageButtons = (props: CustomHomepageButtonsProps) => {
     clearLayout,
     setAddWidgetDialogOpen,
     changeEditMode,
+    defaultConfigAvailable,
+    restoreDefault,
   } = props;
   const styles = useStyles();
 
@@ -59,27 +64,41 @@ export const CustomHomepageButtons = (props: CustomHomepageButtonsProps) => {
           variant="contained"
           color="primary"
           onClick={() => changeEditMode(true)}
+          size="small"
           startIcon={<EditIcon />}
         >
           Edit
         </Button>
       ) : (
         <>
+          {defaultConfigAvailable && (
+            <Button
+              variant="contained"
+              className={styles.contentHeaderBtn}
+              onClick={restoreDefault}
+              size="small"
+              startIcon={<CancelIcon />}
+            >
+              Restore defaults
+            </Button>
+          )}
           {numWidgets > 0 && (
             <Button
               variant="contained"
               color="secondary"
               className={styles.contentHeaderBtn}
               onClick={clearLayout}
+              size="small"
               startIcon={<DeleteIcon />}
             >
-              Clear
+              Clear all
             </Button>
           )}
           <Button
             variant="contained"
             className={styles.contentHeaderBtn}
             onClick={() => setAddWidgetDialogOpen(true)}
+            size="small"
             startIcon={<AddIcon />}
           >
             Add widget
@@ -90,6 +109,7 @@ export const CustomHomepageButtons = (props: CustomHomepageButtonsProps) => {
               variant="contained"
               color="primary"
               onClick={() => changeEditMode(false)}
+              size="small"
               startIcon={<SaveIcon />}
             >
               Save

plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx

@@ -25,7 +25,13 @@ import {
 } from '@backstage/core-plugin-api';
 import 'react-grid-layout/css/styles.css';
 import 'react-resizable/css/styles.css';
-import { createStyles, Dialog, makeStyles, Theme } from '@material-ui/core';
+import {
+  createStyles,
+  Dialog,
+  makeStyles,
+  useTheme,
+  Theme,
+} from '@material-ui/core';
 import { compact } from 'lodash';
 import useObservable from 'react-use/lib/useObservable';
 import { ContentHeader, ErrorBoundary } from '@backstage/core-components';
@@ -62,10 +68,14 @@ const useStyles = makeStyles((theme: Theme) =>
       marginLeft: theme.spacing(2),
     },
     widgetWrapper: {
-      '& > *:first-child': {
+      overflow: 'hidden',
+      '& > div[class*="MuiCard-root"]': {
         width: '100%',
         height: '100%',
       },
+      '& div[class*="MuiCardContent-root"]': {
+        overflow: 'auto',
+      },
       '& + .react-grid-placeholder': {
         backgroundColor: theme.palette.primary.light,
       },
@@ -180,12 +190,79 @@ const availableWidgetsFilter = (elements: ElementCollection) => {
 };
 
 /**
+ * Breakpoint options for <CustomHomepageGridProps/>
+ *
+ * @public
+ */
+export type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Props customizing the <CustomHomepageGrid/> component.
+ *
  * @public
  */
 export type CustomHomepageGridProps = {
+  /**
+   * Children contain all widgets user can configure on their own homepage.
+   */
   children?: ReactNode;
+  /**
+   * Default layout for the homepage before users have modified it.
+   */
   config?: LayoutConfiguration[];
+  /**
+   * Height of grid row in pixels.
+   * @defaultValue 60
+   */
   rowHeight?: number;
+  /**
+   * Screen width in pixels for different breakpoints.
+   * @defaultValue theme breakpoints
+   */
+  breakpoints?: Record<Breakpoint, number>;
+  /**
+   * Number of grid columns for different breakpoints.
+   * @defaultValue \{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 \}
+   */
+  cols?: Record<Breakpoint, number>;
+  /**
+   * Grid container padding (x, y) in pixels for all or specific breakpoints.
+   * @defaultValue [0, 0]
+   * @example [10, 10]
+   * @example \{ lg: [10, 10] \}
+   */
+  containerPadding?: [number, number] | Record<Breakpoint, [number, number]>;
+  /**
+   * Grid container margin (x, y) in pixels for all or specific breakpoints.
+   * @defaultValue [0, 0]
+   * @example [10, 10]
+   * @example \{ lg: [10, 10] \}
+   */
+  containerMargin?: [number, number] | Record<Breakpoint, [number, number]>;
+  /**
+   * Maximum number of rows user can have in the grid.
+   * @defaultValue unlimited
+   */
+  maxRows?: number;
+  /**
+   * Custom style for grid.
+   */
+  style?: React.CSSProperties;
+  /**
+   * Compaction type of widgets in the grid. This controls where widgets are moved in case
+   * they are overlapping in the grid.
+   */
+  compactType?: 'vertical' | 'horizontal' | null;
+  /**
+   * Controls if widgets can overlap in the grid. If true, grid can be placed one over the other.
+   * @defaultValue false
+   */
+  allowOverlap?: boolean;
+  /**
+   * Controls if widgets can collide with each other. If true, grid items won't change position when being dragged over.
+   * @defaultValue false
+   */
+  preventCollision?: boolean;
 };
 
 /**
@@ -195,6 +272,7 @@ export type CustomHomepageGridProps = {
  */
 export const CustomHomepageGrid = (props: CustomHomepageGridProps) => {
   const styles = useStyles();
+  const theme = useTheme();
   const availableWidgets = useElementFilter(
     props.children,
     availableWidgetsFilter,
@@ -290,6 +368,10 @@ export const CustomHomepageGrid = (props: CustomHomepageGridProps) => {
     }
   };
 
+  const handleRestoreDefaultConfig = () => {
+    setWidgets(defaultLayout);
+  };
+
   return (
     <>
       <ContentHeader title="">
@@ -299,6 +381,8 @@ export const CustomHomepageGrid = (props: CustomHomepageGridProps) => {
           clearLayout={clearLayout}
           setAddWidgetDialogOpen={setAddWidgetDialogOpen}
           changeEditMode={changeEditMode}
+          defaultConfigAvailable={props.config !== undefined}
+          restoreDefault={handleRestoreDefaultConfig}
         />
       </ContentHeader>
       <Dialog
@@ -315,10 +399,19 @@ export const CustomHomepageGrid = (props: CustomHomepageGridProps) => {
       <ResponsiveGrid
         className={styles.responsiveGrid}
         measureBeforeMount
-        compactType="horizontal"
+        compactType={props.compactType}
+        style={props.style}
+        allowOverlap={props.allowOverlap}
+        preventCollision={props.preventCollision}
         draggableCancel=".overlayGridItem,.widgetSettingsDialog"
-        breakpoints={{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }}
-        cols={{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }}
+        containerPadding={props.containerPadding}
+        margin={props.containerMargin}
+        breakpoints={
+          props.breakpoints ? props.breakpoints : theme.breakpoints.values
+        }
+        cols={
+          props.cols ? props.cols : { lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }
+        }
         rowHeight={props.rowHeight ?? 60}
         onLayoutChange={handleLayoutChange}
         layouts={{ lg: widgets.map(w => w.layout) }}

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

@@ -14,5 +14,5 @@
  * limitations under the License.
  */
 export { CustomHomepageGrid } from './CustomHomepageGrid';
-export type { CustomHomepageGridProps } from './CustomHomepageGrid';
+export type { CustomHomepageGridProps, Breakpoint } from './CustomHomepageGrid';
 export type { LayoutConfiguration } from './types';