Updated documentation for Toast component

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

@@ -1,18 +1,100 @@
 ---
 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, the toaster needs to be initialized using the `useToaster` hook. This hook returns an object which provides 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.
+### Status
+
+Toast statuses can be set 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 you 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 chain one toast after another, you can retrieve 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 toasters on viewport 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 by pointing to a ref passed into that element.
+
+<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.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();
+
+  React.useEffect(() => {
+    toaster.setSettings({
+      order: 'ascending',
+    });
+  }, []);
+
+  return (
+    <div className='demo-container'>
+      <Button onClick={() => toaster.informational('This is a toast message.')}>
+        Ascending toast
+      </Button>
+    </div>
+  );
+};

examples/Toast.placement.css

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

examples/Toast.placement.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();
+
+  React.useEffect(() => {
+    toaster.setSettings({
+      placement: 'bottom-end',
+    });
+  }, []);
+
+  return (
+    <div className='demo-container'>
+      <Button onClick={() => toaster.informational('This is a toast message.')}>
+        Bottom-end toast
+      </Button>
+    </div>
+  );
+};

examples/Toast.status.css

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

examples/Toast.status.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 } from '@itwin/itwinui-react';
+
+export default () => {
+  const toaster = useToaster();
+
+  return (
+    <div className='demo-container'>
+      <Button
+        onClick={() => toaster.positive('This is a positive toast message.')}
+      >
+        Positive
+      </Button>
+      <Button
+        onClick={() => toaster.negative('This is a negative toast message.')}
+      >
+        Negative
+      </Button>
+      <Button
+        onClick={() => toaster.warning('This is a warning toast message.')}
+      >
+        Warning
+      </Button>
+      <Button
+        onClick={() =>
+          toaster.informational('This is an informational toast message.')
+        }
+      >
+        Informational
+      </Button>
+    </div>
+  );
+};

examples/Toast.type.css

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