Merge pull request #17607 from drodil/homepage_parameters

feat: allow more customization of the custom homepage

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';