Updated documentation for Toast component (#2261)

Co-authored-by: Rohan <[email protected]>
Co-authored-by: Mayank <[email protected]>
Co-authored-by: Uyen Doan <[email protected]>
Co-authored-by: Rohan <[email protected]>

apps/website/src/content/docs/toast.mdx

@@ -1,18 +1,102 @@
 ---
 title: Toast
-description: A Toast is a non modal, unobtrusive window element used to display small amount of information to a user.
+description: A toast is a non-disruptive message that provides feedback based on a user action.
 thumbnail: Toast
 ---
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='toasts--positive' />
+## Usage
+
+Before triggering a toast, you need to call the `useToaster` hook, which returns an object containing various methods for triggering the toast and changing the toaster settings.
 
 <LiveExample src='Toast.main.jsx'>
   <AllExamples.ToastMainExample client:load />
 </LiveExample>
 
-A toast notification provides a brief message about app processes at the top of the screen. Because these messages are so prominent, we need to be careful not to overuse or misuse them.
+**Note**: `useToaster` must be called from the top level of a component which is rendered as a descendant of [`ThemeProvider`](/docs/themeprovider).
+
+### Status
+
+Toasts can be triggered using the status methods provided by the toaster object. The status method takes in a toast message and an `options` object for further customization. Four available statuses are:
+
+- `positive()`
+- `negative()`
+- `warning()`
+- `informational()`
+
+<LiveExample src='Toast.status.jsx'>
+  <AllExamples.ToastStatusExample client:load />
+</LiveExample>
+
+For further customization with `options`, you can utilize `link`, which allows taking further actions directly from the toast, such as navigating to another page or triggering a specific function.
+
+<LiveExample src='Toast.link.jsx'>
+  <AllExamples.ToastLinkExample client:load />
+</LiveExample>
+
+### Settings
+
+The object returned by `useToaster` also provides a `setSettings` method, which can be used to customize the `placement` and `order` of toasts.
+
+`placement` supports the following values:
+
+- `"top"` (default)
+- `"top-start"`
+- `"top-end"`
+- `"bottom"`
+- `"bottom-start"`
+- `"bottom-end"`
+
+`"start"` indicates the left side of viewport, while `"end"` represents the right side.
+
+<LiveExample src='Toast.placement.jsx'>
+  <AllExamples.ToastPlacementExample client:load />
+</LiveExample>
+
+`order` supports the following values:
+
+- `"auto"` (default)
+- `"descending"`
+- `"ascending"`
+
+When set to `"descending"`, the most recent toasts are on top. When set to `"ascending"`, the most recent toasts are on bottom. When set to `"auto"`, it will behave like `"descending"` when `placement` is set to a value beginning with `"top"`, otherwise it will behave like `"ascending"`.
+
+<LiveExample src='Toast.order.jsx'>
+  <AllExamples.ToastOrderExample client:load />
+</LiveExample>
+
+### Closing toasts
+
+When setting the `hasCloseButton` option available in the status method to `true`, each toast will be displayed with a close button, which allows the end user to close the toast manually.
+
+<LiveExample src='Toast.hasCloseButton.jsx'>
+  <AllExamples.ToastHasCloseButtonExample client:load />
+</LiveExample>
+
+Additionally, to implement further actions upon the closing of each toast or to chain one toast after another, you can call the `close()` function returned from the status method.
+
+<LiveExample src='Toast.close.jsx'>
+  <AllExamples.ToastCloseExample client:load />
+</LiveExample>
+
+Closing also depends on the type of toast when used without `hasCloseButton`. By default, persisting toasts will not be closed automatically and will contain a close button while temporary toasts will automatically close after 7 seconds and will not contain a close button. The type of toasts can be specified by passing either `"persisting"` or `"temporary"` into the `type` option.
+
+<LiveExample src='Toast.type.jsx'>
+  <AllExamples.ToastTypeExample client:load />
+</LiveExample>
+
+To close all currently open toasts at once, use the `closeAll()` method offered by the toaster object.
+
+<LiveExample src='Toast.closeAll.jsx'>
+  <AllExamples.ToastCloseAllExample client:load />
+</LiveExample>
+
+The `animateOutTo` prop allows you to control the direction to which the toast animates out when closing. Specifically, it helps determine an "anchor" element that the toast will go towards when it is dismissed. This can be useful, for example, when you want to indicate to the user that the toasts are being saved into a "notifications" panel.
+
+<LiveExample src='Toast.anchorToButton.jsx'>
+  <AllExamples.ToastAnchorToButtonExample client:load />
+</LiveExample>
 
 ## Props
 

examples/Toast.anchorToButton.css

@@ -0,0 +1,5 @@
+.demo-container {
+  display: flex;
+  align-items: center;
+  flex-direction: column;
+}

examples/Toast.anchorToButton.jsx

@@ -0,0 +1,32 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { useToaster, Button } from '@itwin/itwinui-react';
+
+export default () => {
+  const toaster = useToaster();
+  const buttonRef = React.useRef(null);
+
+  React.useEffect(() => {
+    toaster.setSettings({
+      placement: 'top-end',
+    });
+  }, []);
+
+  return (
+    <div className='demo-container'>
+      <Button
+        ref={buttonRef}
+        onClick={() =>
+          toaster.positive('This is a positive toast message', {
+            animateOutTo: buttonRef.current,
+          })
+        }
+      >
+        Anchor to button
+      </Button>
+    </div>
+  );
+};

examples/Toast.close.jsx

@@ -0,0 +1,28 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { useToaster, Button, Flex, ProgressRadial } from '@itwin/itwinui-react';
+
+export default () => {
+  const toaster = useToaster();
+
+  const displayProcessToast = () => {
+    const { close } = toaster.informational(
+      <Flex>
+        <ProgressRadial size='small' />
+        Your process is running...
+      </Flex>,
+    );
+
+    setTimeout(() => {
+      close();
+      toaster.positive('Process completed', {
+        hasCloseButton: true,
+      });
+    }, 1000);
+  };
+
+  return <Button onClick={displayProcessToast}>Start process</Button>;
+};

examples/Toast.closeAll.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  align-items: center;
+  flex-direction: column;
+  gap: var(--iui-size-xs);
+}

examples/Toast.closeAll.jsx

@@ -0,0 +1,22 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { useToaster, Button } from '@itwin/itwinui-react';
+
+export default () => {
+  const toaster = useToaster();
+
+  return (
+    <div className='demo-container'>
+      <Button onClick={() => toaster.positive('Job 1 processing completed.')}>
+        Open toast 1
+      </Button>
+      <Button onClick={() => toaster.positive('Job 2 processing completed.')}>
+        Open toast 2
+      </Button>
+      <Button onClick={() => toaster.closeAll()}>Close All</Button>
+    </div>
+  );
+};

examples/Toast.hasCloseButton.jsx

@@ -0,0 +1,24 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { useToaster, Button } from '@itwin/itwinui-react';
+
+export default () => {
+  const toaster = useToaster();
+
+  return (
+    <div className='demo-container'>
+      <Button
+        onClick={() =>
+          toaster.positive('This is a positive message', {
+            hasCloseButton: true,
+          })
+        }
+      >
+        Open toast
+      </Button>
+    </div>
+  );
+};

examples/Toast.link.jsx

@@ -0,0 +1,27 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { useToaster, Button } from '@itwin/itwinui-react';
+
+export default () => {
+  const toaster = useToaster();
+
+  const displayToast = () => {
+    toaster.positive('Job processing completed.', {
+      link: {
+        title: 'Link',
+        onClick: () => {
+          alert('Link was clicked!');
+        },
+      },
+    });
+  };
+
+  return (
+    <div className='demo-container'>
+      <Button onClick={displayToast}>Toast with link</Button>
+    </div>
+  );
+};

examples/Toast.main.css

@@ -0,0 +1,5 @@
+.demo-container {
+  display: flex;
+  align-items: center;
+  flex-direction: column;
+}

examples/Toast.main.jsx

@@ -9,22 +9,10 @@ export default () => {
   const toaster = useToaster();
 
   return (
-    <Button
-      onClick={() => {
-        toaster.setSettings({
-          placement: 'bottom-end',
-          order: 'ascending',
-        });
-        toaster.positive('Job processing completed.', {
-          hasCloseButton: true,
-          link: {
-            onClick: () => {},
-            title: 'View the report',
-          },
-        });
-      }}
-    >
-      Open toast
-    </Button>
+    <div className='demo-container'>
+      <Button onClick={() => toaster.positive('Job processing completed.')}>
+        Open toast
+      </Button>
+    </div>
   );
 };

examples/Toast.order.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  align-items: center;
+  flex-direction: column;
+  gap: var(--iui-size-xs);
+}

examples/Toast.order.jsx

@@ -0,0 +1,34 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { useToaster, Button, Select } from '@itwin/itwinui-react';
+
+export default () => {
+  const toaster = useToaster();
+
+  return (
+    <div className='demo-container'>
+      <Select
+        triggerProps={{
+          'aria-label': 'Order',
+        }}
+        placeholder='Select order'
+        options={[
+          { value: 'ascending', label: 'Ascending' },
+          { value: 'descending', label: 'Descending' },
+          { value: 'auto', label: 'Auto' },
+        ]}
+        onChange={(value) =>
+          toaster.setSettings({
+            order: value,
+          })
+        }
+      />
+      <Button onClick={() => toaster.informational('This is a toast message.')}>
+        Open toast
+      </Button>
+    </div>
+  );
+};

examples/Toast.placement.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  align-items: center;
+  flex-direction: column;
+  gap: var(--iui-size-xs);
+}

examples/Toast.placement.jsx

@@ -0,0 +1,37 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { useToaster, Button, Select } from '@itwin/itwinui-react';
+
+export default () => {
+  const toaster = useToaster();
+
+  return (
+    <div className='demo-container'>
+      <Select
+        placeholder='Select placement'
+        triggerProps={{
+          'aria-label': 'Placement',
+        }}
+        options={[
+          { value: 'top', label: 'Top' },
+          { value: 'top-start', label: 'Top start' },
+          { value: 'top-end', label: 'Top end' },
+          { value: 'bottom', label: 'Bottom' },
+          { value: 'bottom-start', label: 'Bottom start' },
+          { value: 'bottom-end', label: 'Bottom end' },
+        ]}
+        onChange={(value) =>
+          toaster.setSettings({
+            placement: value,
+          })
+        }
+      />
+      <Button onClick={() => toaster.informational('This is a toast message.')}>
+        Open toast
+      </Button>
+    </div>
+  );
+};

examples/Toast.status.css

@@ -0,0 +1,4 @@
+.demo-container {
+  display: flex;
+  gap: var(--iui-size-xs);
+}