feat(useToast): added hook for accessing adding and removal of toasts

Author: liamross

src/__stories__/3_hooks/useToast.stories.mdx

@@ -0,0 +1,45 @@
+import { options, output } from './useToastHelpers';
+import { Meta, Props, Story, Preview } from '@storybook/addon-docs/blocks';
+import { LinkTo } from '../../storybook-helpers/mdx';
+
+<Meta title="Hooks/useToast" parameters={{previewTabs: {canvas: {hidden: true}}}} />
+
+# useToast
+
+A hook that provides the context value
+of <LinkTo title="Components/ToastProvider" story="Basic">ToastProvider</LinkTo> in
+order to add or remove Toast notifications. Make sure that you have a
+`ToastProvider` somewhere further up in your React project, or this will not
+work.
+
+```ts
+const { add, remove } = useToast();
+
+const toastId = add({
+  heading: 'You are not able to do that',
+  children: 'The action you are attempting to do is not possible.',
+  toastType: 'warning',
+  action: { text: 'Try Again', onClick: tryAgain },
+  closable: true,
+  timeout: 4000,
+});
+
+// Later, if you want to remove:
+remove(toastId);
+```
+
+## `ToastContextValue` (return value)
+
+<Props of={output} />
+
+## `AddToast`
+
+<Props of={options} />
+
+## Example
+
+Here's the hook in action:
+
+<Preview>
+  <Story inline={false} height="550px" id="components-toastprovider--basic" />
+</Preview>

src/__stories__/3_hooks/useToastHelpers.ts

@@ -0,0 +1,10 @@
+import { ToastProps } from '../../components';
+import { AddToast, ToastContextValue } from '../../hooks/useToast';
+import { Include } from '../../utils';
+
+/* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-empty-function */
+
+interface Test extends AddToast, Include<ToastProps, 'heading' | 'children' | 'toastType' | 'action'> {}
+
+export function options(x: Test) {}
+export function output(x: ToastContextValue) {}

src/hooks/index.ts

@@ -7,3 +7,4 @@ export * from './useFocusTrap';
 export * from './useKeyForClick';
 export * from './useManagedFiles';
 export * from './useOnClick';
+export * from './useToast';

src/hooks/useToast.ts

@@ -0,0 +1,63 @@
+import { createContext, MouseEventHandler, ReactNode, useContext } from 'react';
+
+export interface CommonToastProps {
+  /**
+   * The heading to display on the toast. Use this for a brief overview of the
+   * reason for the toast.
+   */
+  heading: ReactNode;
+  /**
+   * The body of the toast. This is where you can elaborate with more
+   * information about the toast.
+   */
+  children?: ReactNode;
+  /**
+   * The type of message the toast is displaying. Will change the color and
+   * icon of the toast.
+   * @default "info"
+   */
+  toastType?: 'info' | 'success' | 'warning' | 'error';
+  /**
+   * Adds an action button to the toast. Will position to the left of the close
+   * button if `onClose` was provided.
+   */
+  action?: {
+    text: ReactNode;
+    onClick: MouseEventHandler<HTMLButtonElement>;
+  };
+}
+
+export interface AddToast extends CommonToastProps {
+  /**
+   * If true, toast will have a close button.
+   */
+  closable?: boolean;
+  /**
+   * If provided, will set a timeout for the toast to disappear. This will
+   * override the `defaultTimeout` prop from `ToastProvider`.
+   */
+  timeout?: number;
+}
+
+export interface ToastContextValue {
+  /**
+   * Add a toast with parameters outlined by the `AddToast` object.
+   * @param toast Adds this toast to the end of the queue.
+   * @returns The ID of the added toast to use for early removal.
+   */
+  add(toast: AddToast): number;
+  /**
+   * Remove a toast by ID. If no ID provided, removes the current toast.
+   * @param toastId The ID of the toast to remove.
+   */
+  remove(toastId?: number): void;
+}
+
+export const ToastContext = createContext<ToastContextValue>({} as ToastContextValue);
+
+/**
+ * Returns the toast context object for managing toasts.
+ */
+export function useToast() {
+  return useContext(ToastContext);
+}