feat(notifications): allow placement customizations for toast

packages/notifications/.size-snapshot.json

@@ -1,20 +1,20 @@
 {
   "index.cjs.js": {
-    "bundled": 34872,
-    "minified": 23552,
-    "gzipped": 5979
+    "bundled": 35167,
+    "minified": 23692,
+    "gzipped": 6006
   },
   "index.esm.js": {
-    "bundled": 32792,
-    "minified": 21697,
-    "gzipped": 5851,
+    "bundled": 33087,
+    "minified": 21837,
+    "gzipped": 5879,
     "treeshaked": {
       "rollup": {
         "code": 11732,
         "import_statements": 379
       },
       "webpack": {
-        "code": 19833
+        "code": 19932
       }
     }
   }

packages/notifications/src/elements/toaster/ToastProvider.spec.tsx

@@ -8,12 +8,12 @@
 import React from 'react';
 import userEvent from '@testing-library/user-event';
 import { render, renderRtl } from 'garden-test-utils';
-import { useToast, ToastProvider } from '../../';
+import { useToast, ToastProvider, IToastProviderProps } from '../../';
 
 import { config } from 'react-transition-group';
 config.disabled = true;
 
-const ToastExample = () => {
+const ToastExample: React.FC<IToastProviderProps> = props => {
   const NotificationExample = () => {
     const { addToast } = useToast();
 
@@ -27,7 +27,7 @@ const ToastExample = () => {
   };
 
   return (
-    <ToastProvider zIndex={100}>
+    <ToastProvider {...props}>
       <NotificationExample />
     </ToastProvider>
   );
@@ -75,12 +75,33 @@ describe('ToastProvider', () => {
   });
 
   it('renders toasts with provided zIndex', () => {
-    const { getByRole, getByText } = render(<ToastExample />);
+    const { getByRole, getByText } = render(<ToastExample zIndex={100} />);
 
     userEvent.click(getByRole('button'));
     const notificationElement = getByText('notification');
 
     expect(notificationElement).toBeInTheDocument();
     expect(notificationElement.parentElement?.parentElement).toHaveStyleRule('z-index', '100');
   });
+
+  it('applies placementProps when provided', () => {
+    const customizationProps = { 'data-test-id': 'placement-prop' } as any;
+
+    const { getAllByTestId } = render(
+      <ToastExample
+        placementProps={{
+          'top-start': customizationProps,
+          top: customizationProps,
+          'top-end': customizationProps,
+          'bottom-start': customizationProps,
+          bottom: customizationProps,
+          'bottom-end': customizationProps
+        }}
+      />
+    );
+
+    const customizedPlacements = getAllByTestId('placement-prop');
+
+    expect(customizedPlacements).toHaveLength(6);
+  });
 });

packages/notifications/src/elements/toaster/ToastProvider.tsx

@@ -5,7 +5,14 @@
  * found at http://www.apache.org/licenses/LICENSE-2.0.
  */
 
-import React, { createContext, useReducer, Dispatch, useCallback, useMemo } from 'react';
+import React, {
+  createContext,
+  useReducer,
+  Dispatch,
+  useCallback,
+  useMemo,
+  HTMLAttributes
+} from 'react';
 import PropTypes from 'prop-types';
 
 import {
@@ -30,9 +37,19 @@ export interface IToastProviderProps {
    * Sets the `z-index` of the toast
    */
   zIndex?: number;
+  /**
+   * Props to be spread onto the wrapping element for each Toast placement.
+   * Can be used to customize the positioning of a placement.
+   */
+  placementProps?: Partial<Record<ToastPlacement, HTMLAttributes<HTMLDivElement>>>;
 }
 
-export const ToastProvider: React.FC<IToastProviderProps> = ({ limit, zIndex, children }) => {
+export const ToastProvider: React.FC<IToastProviderProps> = ({
+  limit,
+  zIndex,
+  placementProps = {},
+  children
+}) => {
   const [state, dispatch] = useReducer(toasterReducer, getInitialState());
 
   const contextValue = useMemo(() => ({ state, dispatch }), [state, dispatch]);
@@ -46,10 +63,16 @@ export const ToastProvider: React.FC<IToastProviderProps> = ({ limit, zIndex, ch
       }
 
       return (
-        <ToastSlot placement={placement} toasts={matchingToasts} zIndex={zIndex} limit={limit!} />
+        <ToastSlot
+          placement={placement}
+          toasts={matchingToasts}
+          zIndex={zIndex}
+          limit={limit!}
+          {...placementProps[placement]}
+        />
       );
     },
-    [limit, state.toasts, zIndex]
+    [limit, state.toasts, zIndex, placementProps]
   );
 
   return (

packages/notifications/src/elements/toaster/ToastSlot.tsx

@@ -5,22 +5,28 @@
  * found at http://www.apache.org/licenses/LICENSE-2.0.
  */
 
-import React, { useCallback, useContext, useEffect, useState } from 'react';
+import React, { HTMLAttributes, useCallback, useContext, useEffect, useState } from 'react';
 import { ThemeContext } from 'styled-components';
 import { CSSTransition } from 'react-transition-group';
 import { useDocument } from '@zendeskgarden/react-theming';
 import { IToast, ToastPlacement } from './reducer';
 import { Toast } from './Toast';
 import { StyledFadeInTransition, StyledTransitionGroup, TRANSITION_CLASS } from './styled';
 
-interface IToastSlotProps {
+interface IToastSlotProps extends HTMLAttributes<HTMLDivElement> {
   toasts: IToast[];
   placement: ToastPlacement;
   limit: number;
   zIndex?: number;
 }
 
-export const ToastSlot: React.FC<IToastSlotProps> = ({ toasts, placement, zIndex, limit }) => {
+export const ToastSlot: React.FC<IToastSlotProps> = ({
+  toasts,
+  placement,
+  zIndex,
+  limit,
+  ...props
+}) => {
   const [pauseTimers, setPauseTimers] = useState(false);
   const theme = useContext(ThemeContext);
   const environment = useDocument(theme);
@@ -71,6 +77,7 @@ export const ToastSlot: React.FC<IToastSlotProps> = ({ toasts, placement, zIndex
       $zIndex={zIndex}
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
+      {...props}
     >
       {toasts.map((toast, index) => {
         const transitionRef = React.createRef<HTMLDivElement>();

packages/notifications/src/elements/toaster/useToast.spec.tsx

@@ -132,7 +132,9 @@ describe('useToast()', () => {
 
       expect(queryByRole('alert')).toBeInTheDocument();
 
-      jest.runOnlyPendingTimers();
+      act(() => {
+        jest.runOnlyPendingTimers();
+      });
 
       expect(queryByRole('alert')).not.toBeInTheDocument();
     });
@@ -146,7 +148,9 @@ describe('useToast()', () => {
 
       expect(queryByRole('alert')).toBeInTheDocument();
 
-      jest.runOnlyPendingTimers();
+      act(() => {
+        jest.runOnlyPendingTimers();
+      });
 
       expect(queryByRole('alert')).toBeInTheDocument();
     });