replace toaster with new useToaster api (#1351)

The `Toaster` class instance been replaced with a `useToaster` hook which returns an object that has properties matching the public functions in the old api. 

Dispatches reducer actions to update state in context. This state is then used by `Toaster` which gets automatically rendered by `ThemeProvider`.

.changeset/cold-needles-know.md

@@ -0,0 +1,5 @@
+---
+'@itwin/itwinui-react': major
+---
+
+`toaster` import has been removed and replaced with `useToaster` which returns a toaster object with the same API.

.changeset/rich-garlics-love.md

@@ -0,0 +1,5 @@
+---
+'@itwin/itwinui-css': patch
+---
+
+`.iui-toast-anchor` can now be applied on a `<button>`.

apps/storybook/src/Toasts.stories.tsx

@@ -4,7 +4,7 @@
  *--------------------------------------------------------------------------------------------*/
 import React from 'react';
 import { Story, Meta } from '@storybook/react';
-import { Button, toaster, ProgressRadial } from '@itwin/itwinui-react';
+import { Button, useToaster, ProgressRadial } from '@itwin/itwinui-react';
 import { ToastProps } from '@itwin/itwinui-react/esm/core/Toast/Toast';
 import { ToasterSettings } from '@itwin/itwinui-react/esm/core/Toast/Toaster';
 
@@ -87,6 +87,8 @@ export const Positive: Story<ToastProps & ToasterSettings> = ({
   placement,
   order,
 }) => {
+  const toaster = useToaster();
+
   const displayPositiveToast = () => {
     toaster.setSettings({
       placement: placement ?? 'top',
@@ -130,6 +132,8 @@ export const Negative: Story<ToastProps & ToasterSettings> = ({
   placement,
   order,
 }) => {
+  const toaster = useToaster();
+
   const displayNegativeToast = () => {
     toaster.setSettings({
       placement: placement ?? 'top',
@@ -173,6 +177,8 @@ export const Informational: Story<ToastProps & ToasterSettings> = ({
   placement,
   order,
 }) => {
+  const toaster = useToaster();
+
   const displayInformationalToast = () => {
     toaster.setSettings({
       placement: placement ?? 'top',
@@ -212,6 +218,8 @@ export const Warning: Story<ToastProps & ToasterSettings> = ({
   order,
   ...options
 }) => {
+  const toaster = useToaster();
+
   const displayWarningToast = () => {
     toaster.setSettings({
       placement: placement ?? 'top',
@@ -245,6 +253,8 @@ export const PositionChanged: Story<ToastProps & ToasterSettings> = ({
   order,
   ...options
 }) => {
+  const toaster = useToaster();
+
   const displayPositionChangedToast = () => {
     toaster.setSettings({
       placement: placement ?? 'bottom-end',
@@ -283,6 +293,8 @@ export const AnchorToButton: Story<ToastProps & ToasterSettings> = ({
   placement,
   order,
 }) => {
+  const toaster = useToaster();
+
   const buttonRef = React.useRef(null);
   const displayPositiveToast = () => {
     toaster.setSettings({
@@ -331,6 +343,8 @@ export const CloseIndividual: Story<ToastProps & ToasterSettings> = ({
   placement,
   order,
 }) => {
+  const toaster = useToaster();
+
   const displayProcessToast = () => {
     toaster.setSettings({
       placement: placement ?? 'top',

examples/Toast.main.tsx

@@ -3,9 +3,11 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-import { toaster, Button } from '@itwin/itwinui-react';
+import { useToaster, Button } from '@itwin/itwinui-react';
 
 export default () => {
+  const toaster = useToaster();
+
   return (
     <Button
       onClick={() => {

packages/itwinui-css/src/toast/toast.scss

@@ -151,6 +151,12 @@
   }
 
   &-anchor {
+    &:where(button) {
+      font-family: inherit;
+      border: none;
+      background: transparent;
+      padding: 0;
+    }
     @include anchor.iui-anchor-underline('on-initial');
     border-radius: var(--iui-border-radius-1);
     cursor: pointer;

packages/itwinui-react/src/core/ThemeProvider/ThemeProvider.tsx

@@ -7,6 +7,7 @@ import cx from 'classnames';
 import { useMediaQuery, useMergedRefs, Box } from '../utils/index.js';
 import type { PolymorphicForwardRefComponent } from '../utils/index.js';
 import { ThemeContext } from './ThemeContext.js';
+import { ToastProvider, Toaster } from '../Toast/Toaster.js';
 
 export type ThemeOptions = {
   /**
@@ -110,8 +111,12 @@ export const ThemeProvider = React.forwardRef((props, ref) => {
         ref={ref}
         {...rest}
       >
-        {children}
-        <div ref={portalContainerRef} />
+        <ToastProvider>
+          {children}
+          <div ref={portalContainerRef}>
+            <Toaster />
+          </div>
+        </ToastProvider>
       </Root>
     </ThemeContext.Provider>
   );

packages/itwinui-react/src/core/Toast/Toast.test.tsx

@@ -12,6 +12,7 @@ import {
   SvgStatusWarning,
 } from '../utils/index.js';
 import userEvent from '@testing-library/user-event';
+import { ToastProvider } from './Toaster.js';
 
 it('renders the category classes & icons correctly', () => {
   const categories: Array<ToastCategory> = [
@@ -22,13 +23,15 @@ it('renders the category classes & icons correctly', () => {
   ];
   categories.forEach((category) => {
     const { container } = render(
-      <Toast
-        isVisible={true}
-        type='persisting'
-        content='Job Processing Completed'
-        category={category}
-        id={1}
-      />,
+      <ToastProvider>
+        <Toast
+          isVisible={true}
+          type='persisting'
+          content='Job Processing Completed'
+          category={category}
+          id={1}
+        />
+      </ToastProvider>,
     );
 
     expect(container.querySelector(`.iui-toast.iui-${category}`)).toBeTruthy();
@@ -58,13 +61,15 @@ it('renders the category classes & icons correctly', () => {
 
 it('renders the message correctly', () => {
   const { getByText } = render(
-    <Toast
-      isVisible={true}
-      type='persisting'
-      content='Job Processing Completed'
-      category='positive'
-      id={1}
-    />,
+    <ToastProvider>
+      <Toast
+        isVisible={true}
+        type='persisting'
+        content='Job Processing Completed'
+        category='positive'
+        id={1}
+      />
+    </ToastProvider>,
   );
 
   getByText('Job Processing Completed');
@@ -73,17 +78,19 @@ it('renders the message correctly', () => {
 it('renders a report message Link correctly', async () => {
   const mockedFn = jest.fn();
   const { container } = render(
-    <Toast
-      isVisible={true}
-      type='persisting'
-      content='Job Processing Completed'
-      category='positive'
-      link={{
-        title: 'View Message Function',
-        onClick: mockedFn,
-      }}
-      id={1}
-    />,
+    <ToastProvider>
+      <Toast
+        isVisible={true}
+        type='persisting'
+        content='Job Processing Completed'
+        category='positive'
+        link={{
+          title: 'View Message Function',
+          onClick: mockedFn,
+        }}
+        id={1}
+      />
+    </ToastProvider>,
   );
 
   const link = container.querySelector('.iui-toast-anchor') as HTMLElement;
@@ -94,13 +101,15 @@ it('renders a report message Link correctly', async () => {
 
 it('renders the close icon correctly', () => {
   const { container } = render(
-    <Toast
-      isVisible={true}
-      type='persisting'
-      content='Job Processing Completed'
-      category='positive'
-      id={1}
-    />,
+    <ToastProvider>
+      <Toast
+        isVisible={true}
+        type='persisting'
+        content='Job Processing Completed'
+        category='positive'
+        id={1}
+      />
+    </ToastProvider>,
   );
 
   expect(
@@ -110,13 +119,15 @@ it('renders the close icon correctly', () => {
 
 it('not render close icon in temporary', () => {
   const { container } = render(
-    <Toast
-      isVisible={true}
-      type='temporary'
-      content='Job Processing Completed'
-      category='positive'
-      id={1}
-    />,
+    <ToastProvider>
+      <Toast
+        isVisible={true}
+        type='temporary'
+        content='Job Processing Completed'
+        category='positive'
+        id={1}
+      />
+    </ToastProvider>,
   );
 
   expect(
@@ -126,14 +137,16 @@ it('not render close icon in temporary', () => {
 
 it('renders the close icon when hasCloseButton', () => {
   const { container } = render(
-    <Toast
-      isVisible={true}
-      hasCloseButton={true}
-      type='temporary'
-      content='Job Processing Completed'
-      category='positive'
-      id={1}
-    />,
+    <ToastProvider>
+      <Toast
+        isVisible={true}
+        hasCloseButton={true}
+        type='temporary'
+        content='Job Processing Completed'
+        category='positive'
+        id={1}
+      />
+    </ToastProvider>,
   );
 
   expect(
@@ -146,14 +159,15 @@ it('should close temporary toast after 7s', () => {
 
   const mockedFn = jest.fn();
   const { container } = render(
-    <Toast
-      isVisible={true}
-      type='temporary'
-      content='Job Processing Completed'
-      category='informational'
-      id={1}
-      onRemove={mockedFn}
-    />,
+    <ToastProvider>
+      <Toast
+        type='temporary'
+        content='Job Processing Completed'
+        category='informational'
+        id={1}
+        onRemove={mockedFn}
+      />
+    </ToastProvider>,
   );
 
   expect(container.querySelector('.iui-toast-all')).toBeTruthy();