@kaizen/components 1.35.1 → 1.36.0

package/src/Notification/ToastNotification/ToastNotification/ToastNotification.spec.tsx

@@ -0,0 +1,33 @@
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import { ToastNotification, ToastNotificationProps } from "../ToastNotification"
+import { ToastNotificationsList } from "../ToastNotificationsList"
+import { ToastNotificationProvider } from "../context/ToastNotificationContext"
+
+const ToastNotificationWrapper = ({
+  children,
+  ...props
+}: Partial<ToastNotificationProps>): JSX.Element => (
+  <ToastNotificationProvider>
+    <ToastNotificationsList />
+    <ToastNotification type="positive" title="Success" {...props}>
+      {children ?? "It worked!"}
+    </ToastNotification>
+  </ToastNotificationProvider>
+)
+
+describe("<ToastNotification />", () => {
+  it('creates a single "status" container for notifications', async () => {
+    render(<ToastNotificationWrapper />)
+
+    const toastPortalManager = screen.getAllByRole("status")
+    expect(toastPortalManager).toHaveLength(1)
+  })
+
+  it("renders a basic notification correctly", async () => {
+    render(<ToastNotificationWrapper />)
+
+    const notification = await screen.findByText("Success")
+    expect(notification).toBeInTheDocument()
+  })
+})

package/src/Notification/ToastNotification/ToastNotification/ToastNotification.tsx

@@ -0,0 +1,48 @@
+import React, { useEffect, useId } from "react"
+import { useToastNotificationContext } from "../context/ToastNotificationContext"
+import { ToastNotificationObj } from "../types"
+
+export type ToastNotificationProps = Omit<
+  ToastNotificationObj,
+  "id" | "message" | "persistent"
+> & {
+  children: React.ReactNode
+  id?: string
+  /**
+   * Removes the dismiss trigger. Functions the same as `persistent` in `addToastNotification`.
+   * If this is true you will need to manage the removal of notifications manually.
+   * @default false
+   */
+  hideCloseIcon?: boolean
+}
+
+export const ToastNotification = ({
+  id: propsId,
+  hideCloseIcon = false,
+  type,
+  title,
+  onHide,
+  children,
+  ...restProps
+}: ToastNotificationProps): null => {
+  const reactId = useId()
+  const id = propsId || reactId
+  const { addToastNotification } = useToastNotificationContext()
+  const persistent = hideCloseIcon
+
+  useEffect(() => {
+    addToastNotification({
+      id,
+      type,
+      title,
+      message: children,
+      persistent,
+      onHide,
+      ...restProps,
+    })
+  }, [])
+
+  return null
+}
+
+ToastNotification.displayName = "ToastNotification"

package/src/Notification/ToastNotification/ToastNotification/index.ts

@@ -0,0 +1 @@
+export * from "./ToastNotification"

package/src/Notification/ToastNotification/{subcomponents/ToastNotificationsList → ToastNotificationsList}/ToastNotificationsList.module.scss

@@ -1,7 +1,7 @@
 @import "~@kaizen/design-tokens/sass/spacing";
 @import "~@kaizen/design-tokens/sass/layout";
 
-.list {
+.toastNotificationsList {
   display: flex;
   flex-direction: column;
   align-items: flex-end;

package/src/Notification/ToastNotification/ToastNotificationsList/ToastNotificationsList.tsx

@@ -0,0 +1,40 @@
+import React from "react"
+import { createPortal } from "react-dom"
+import { useToastNotificationContext } from "../context/ToastNotificationContext"
+import { ToastNotificationsMap } from "./subcomponents/ToastNotificationsMap"
+import styles from "./ToastNotificationsList.module.scss"
+
+export const ToastNotificationsList = (): JSX.Element => {
+  const { notifications, removeToastNotification } =
+    useToastNotificationContext()
+
+  const containers = document.querySelectorAll(
+    '[data-testid="toast-notifications-list"'
+  )
+
+  if (containers) {
+    // Remove any duplicate instances
+    // (eg. Storybook docs page has multiple stories each with their own context)
+    containers.forEach((c, i) => {
+      if (i === 0) return
+      c.remove()
+    })
+  }
+
+  return createPortal(
+    <div
+      data-testid="toast-notifications-list"
+      role="status"
+      className={styles.toastNotificationsList}
+    >
+      <ToastNotificationsMap
+        notifications={notifications}
+        onHide={removeToastNotification}
+        container={containers[0]}
+      />
+    </div>,
+    document.body
+  )
+}
+
+ToastNotificationsList.displayName = "ToastNotificationsList"

package/src/Notification/ToastNotification/ToastNotificationsList/subcomponents/ToastNotificationsMap/ToastNotificationsMap.tsx

@@ -0,0 +1,49 @@
+import React, { HTMLAttributes } from "react"
+import { createPortal } from "react-dom"
+import { GenericNotification } from "~components/Notification/subcomponents/GenericNotification"
+import { OverrideClassName } from "~types/OverrideClassName"
+import { ToastNotificationObj } from "../../../types"
+
+export type ToastNotificationsMapProps = {
+  notifications: ToastNotificationObj[]
+  onHide: (notificationId: string) => void
+  container: Element | null
+} & OverrideClassName<HTMLAttributes<HTMLDivElement>>
+
+export const ToastNotificationsMap = ({
+  notifications,
+  onHide: defaultOnHide,
+  container,
+}: ToastNotificationsMapProps): JSX.Element | null => {
+  if (!container) return null
+
+  // To consolidate all notifications into a single list when there are multiple contexts,
+  // this list cannot render with a container (must be portalled into one).
+  return createPortal(
+    <>
+      {notifications.map(
+        ({ id, type, title, persistent, onHide, message, ...restProps }) => (
+          <GenericNotification
+            key={id}
+            style="toast"
+            type={type}
+            title={title}
+            persistent={persistent}
+            onHide={(): void => {
+              if (typeof onHide !== "undefined") {
+                onHide()
+              }
+              defaultOnHide(id)
+            }}
+            {...restProps}
+          >
+            {message}
+          </GenericNotification>
+        )
+      )}
+    </>,
+    container
+  )
+}
+
+ToastNotificationsMap.displayName = "ToastNotificationsMap"

package/src/Notification/ToastNotification/ToastNotificationsList/subcomponents/ToastNotificationsMap/index.ts

@@ -0,0 +1 @@
+export * from "./ToastNotificationsMap"

package/src/Notification/ToastNotification/_docs/ToastNotification.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Controls, Meta } from "@storybook/blocks"
-import { ResourceLinks, KaioNotification, Installation } from "~storybook/components"
+import { ResourceLinks, KaioNotification, Installation, LinkTo } from "~storybook/components"
 import * as ToastNotificationStories from "./ToastNotification.stories"
 
 <Meta title="Components/Notifications/ToastNotification" />
@@ -17,51 +17,56 @@ import * as ToastNotificationStories from "./ToastNotification.stories"
 
 <Installation
   installCommand="yarn add @kaizen/components"
-  importStatement='import { addToastNotification, removeToastNotification, clearToastNotifications, ToastNotification } from "@kaizen/components"'
+  importStatement='import { addToastNotification } from "@kaizen/components"'
 />
 
 ## Overview
 
-Toast notifications are used to notifying a user of an outcome for an action they have taken. They appended to the root of the document body and will render in the top corner of the window.
+Toast notifications are used to notifying a user of an outcome for an action they have taken.
+They appended to the root of the document body and will render in the top corner of the window.
+
+**Note:** Toast notifications must be used within <LinkTo pageId="components-kaizen-provider-installation">KaizenProvider</LinkTo>.
 
 <Canvas of={ToastNotificationStories.Playground} />
 <Controls of={ToastNotificationStories.Playground} />
 
 ## API
 
-In addition to the `ToastNotification` JSX element, there are three API methods exported from this package to create and manage Toast notifications.
+Use the following helper methods available through the `useToastNotification` hook to create and manage Toast notifications.
 
 ### addToastNotification
-Creates an instance of the the Toast Notification manager and appends new notifications to the list.
+
+Adds and appends a new notification to the list.
 
 <Canvas of={ToastNotificationStories.CreateNotification} />
 
-If `addToastNotification` is called with an `id` that matches an existing notification, then it will update the content of that component.
+### updateToastNotification
 
-This will also be invoked if you use the `ToastNotification` component.
+Updates a single notification that matches the `id` passed to the function.
 
 <Canvas of={ToastNotificationStories.UpdateNotification} />
 
-
 ### removeToastNotification
 
 Removes a single notification that matches the `id` passed to the function.
 
 <Canvas of={ToastNotificationStories.RemoveNotification} />
 
-
 ### clearToastNotifications
 
 Clears all notifications currently held in state.
 
-<Canvas of={ToastNotificationStories.ClearNotifications} />
+Note that since each story has an individual context, this example will only clear the ones it adds.
 
+<Canvas of={ToastNotificationStories.ClearNotifications} />
 
 ## Accessibility and removal of notifications
 
-Any notification that is temporarily rendered on screen should provide a user ample time to read its contents and provide a way to stop its removal ([WCAG guidline here](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits.html)
-)).
+Any notification that is temporarily rendered on screen should provide a user ample time to read its contents and
+provide a way to stop its removal ([WCAG guidline here](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits.html)).
 
-By default, all Toast notifications will remain on screen until dismissed. This ensures the accessibility is met and does not require additional intervention.
+By default, all Toast notifications will remain on screen until dismissed.
+This ensures the accessibility is met and does not require additional intervention.
 
-If you required to be automatically removed, you must provide a means of stopping and re-enabling its removal and ensures that a user can reasonably access this before it is removed.
+If you required to be automatically removed, you must provide a means of stopping and re-enabling its
+removal and ensures that a user can reasonably access this before it is removed.

package/src/Notification/ToastNotification/_docs/ToastNotification.stickersheet.stories.tsx

@@ -1,7 +1,7 @@
 import React from "react"
 import { Meta } from "@storybook/react"
 import { StickerSheetStory } from "~storybook/components/StickerSheet"
-import { addToastNotification } from "../subcomponents/ToastNotificationManager"
+import { ToastNotification } from "../ToastNotification"
 
 export default {
   title: "Components/Notifications/ToastNotification",
@@ -12,75 +12,38 @@ export default {
 } satisfies Meta
 
 const StickerSheetTemplate: StickerSheetStory = {
-  render: () => {
-    React.useEffect(() => {
-      addToastNotification({
-        type: "positive",
-        title: "Positive",
-        message: (
-          <>
-            New user data, imported by mackenzie@hooli.com has successfully
-            uploaded. <a href="/">Manage users is now available</a>
-          </>
-        ),
-      })
-      addToastNotification({
-        type: "informative",
-        title: "Informative",
-        message: (
-          <>
-            New user data is currently being processed. We’ll let you know when
-            the process is completed. <a href="/">Manage users</a>
-          </>
-        ),
-      })
-      addToastNotification({
-        type: "cautionary",
-        title: "Cautionary",
-        message: (
-          <>
-            New user data, imported by mackenzie@hooli.com has uploaded with
-            some minor issues. <a href="/">View issues</a>
-          </>
-        ),
-      })
-      addToastNotification({
-        type: "security",
-        title: "Security",
-        message: (
-          <>
-            Results hidden to protect confidentiality of individuals and small
-            groups. <a href="/">Learn more</a>
-          </>
-        ),
-      })
-      addToastNotification({
-        type: "negative",
-        title: "Negative",
-        message: (
-          <>
-            Check your connection and try again. <a href="/">Refresh</a>.
-          </>
-        ),
-      })
-      addToastNotification({
-        type: "positive",
-        title:
-          "Very long Title Example Very long title Example VerylongTitleExampleVerylongtitleExample ",
-        message: (
-          <>
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla
-            semper odio vitae sem gravida rutrum. Praesent vel sapien eget eros
-            dictum luctus scelerisque eu nibh. Etiam ullamcorper lobortis
-            gravida. Suspendisse massa tortor, ultricies et ipsum at, iaculis
-            bibendum est.
-          </>
-        ),
-      })
-    }, [])
-
-    return <></>
-  },
+  render: () => (
+    <>
+      <ToastNotification type="positive" title="Positive">
+        New user data, imported by mackenzie@hooli.com has successfully
+        uploaded. <a href="/">Manage users is now available</a>
+      </ToastNotification>
+      <ToastNotification type="informative" title="Informative">
+        New user data is currently being processed. We&apos;ll let you know when
+        the process is completed. <a href="/">Manage users</a>
+      </ToastNotification>
+      <ToastNotification type="cautionary" title="Cautionary">
+        New user data, imported by mackenzie@hooli.com has uploaded with some
+        minor issues. <a href="/">View issues</a>
+      </ToastNotification>
+      <ToastNotification type="security" title="Security">
+        Results hidden to protect confidentiality of individuals and small
+        groups. <a href="/">Learn more</a>
+      </ToastNotification>
+      <ToastNotification type="negative" title="Negative">
+        Check your connection and try again. <a href="/">Refresh</a>.
+      </ToastNotification>
+      <ToastNotification
+        type="positive"
+        title="Very long Title Example Very long title Example VerylongTitleExampleVerylongtitleExample"
+      >
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla semper
+        odio vitae sem gravida rutrum. Praesent vel sapien eget eros dictum
+        luctus scelerisque eu nibh. Etiam ullamcorper lobortis gravida.
+        Suspendisse massa tortor, ultricies et ipsum at, iaculis bibendum est.
+      </ToastNotification>
+    </>
+  ),
 }
 
 export const StickerSheetDefault: StickerSheetStory = {

package/src/Notification/ToastNotification/_docs/ToastNotification.stories.tsx

@@ -1,12 +1,7 @@
-import React from "react"
+import React, { useEffect, useId } from "react"
 import { Meta, StoryObj } from "@storybook/react"
 import { Button } from "~components/Button"
-import {
-  addToastNotification,
-  removeToastNotification,
-  clearToastNotifications,
-  ToastNotification,
-} from "../index"
+import { ToastNotification, useToastNotification } from "../index"
 
 const meta = {
   title: "Components/Notifications/ToastNotification",
@@ -28,7 +23,26 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
+const ToastNotificationTemplate: Story = {
+  render: args => {
+    const reactId = useId()
+    const { updateToastNotification } = useToastNotification()
+
+    useEffect(() => {
+      updateToastNotification({
+        ...args,
+        id: args.id ?? reactId,
+        message: args.children,
+        persistent: args.hideCloseIcon,
+      })
+    }, [args])
+
+    return <ToastNotification {...args} />
+  },
+}
+
 export const Playground: Story = {
+  ...ToastNotificationTemplate,
   parameters: {
     docs: {
       canvas: {
@@ -39,104 +53,120 @@ export const Playground: Story = {
 }
 
 export const CreateNotification: Story = {
-  render: () => (
-    <Button
-      label="Create notification"
-      onClick={() =>
-        addToastNotification({
-          title: "Informative",
-          type: "informative",
-          message: "New notification!",
-        })
-      }
-    />
-  ),
-}
+  render: () => {
+    const { addToastNotification } = useToastNotification()
 
-export const UpdateNotification: Story = {
-  render: () => (
-    <>
+    return (
       <Button
         label="Create notification"
-        classNameOverride="!mr-12"
-        onClick={() =>
-          addToastNotification({
-            id: "id--update-example",
-            title: "Cautionary",
-            type: "cautionary",
-            message: "This content will be updated",
-          })
-        }
-      />
-      <Button
-        label="Update notification"
         onClick={() =>
           addToastNotification({
-            id: "id--update-example",
-            title: "Success",
-            type: "positive",
-            message: "The content was successfully updated",
+            title: "Informative",
+            type: "informative",
+            message: "New notification!",
           })
         }
       />
-    </>
-  ),
+    )
+  },
+}
+
+export const UpdateNotification: Story = {
+  render: () => {
+    const { addToastNotification, updateToastNotification } =
+      useToastNotification()
+    return (
+      <>
+        <Button
+          label="Create notification"
+          classNameOverride="!mr-12"
+          onClick={() =>
+            addToastNotification({
+              id: "id--update-example",
+              title: "Cautionary",
+              type: "cautionary",
+              message: "This content will be updated",
+            })
+          }
+        />
+        <Button
+          label="Update notification"
+          onClick={() =>
+            updateToastNotification({
+              id: "id--update-example",
+              title: "Success",
+              type: "positive",
+              message: "The content was successfully updated",
+            })
+          }
+        />
+      </>
+    )
+  },
 }
 
 export const RemoveNotification: Story = {
-  render: () => (
-    <>
-      <Button
-        label="Create notification"
-        classNameOverride="!mr-12"
-        onClick={() =>
-          addToastNotification({
-            id: "id--remove-example",
-            title: "Remove",
-            type: "negative",
-            message: "This notification will be removed",
-          })
-        }
-      />
-      <Button
-        label="Remove notification"
-        onClick={() => removeToastNotification("id--remove-example")}
-      />
-    </>
-  ),
+  render: () => {
+    const { addToastNotification, removeToastNotification } =
+      useToastNotification()
+    return (
+      <>
+        <Button
+          label="Create notification"
+          classNameOverride="!mr-12"
+          onClick={() =>
+            addToastNotification({
+              id: "id--remove-example",
+              title: "Remove",
+              type: "negative",
+              message: "This notification will be removed",
+            })
+          }
+        />
+        <Button
+          label="Remove notification"
+          onClick={() => removeToastNotification("id--remove-example")}
+        />
+      </>
+    )
+  },
 }
 
 export const ClearNotifications: Story = {
-  render: () => (
-    <>
-      <Button
-        label="Create notifications"
-        classNameOverride="!mr-12"
-        onClick={() => {
-          addToastNotification({
-            id: "id--clear-example-1",
-            title: "First",
-            type: "positive",
-            message: "This notification will be removed",
-          })
-          addToastNotification({
-            id: "id--clear-example-2",
-            title: "Second",
-            type: "cautionary",
-            message: "This notification will also be removed",
-          })
-          addToastNotification({
-            id: "id--clear-example-3",
-            title: "Third",
-            type: "negative",
-            message: "This notification will also also be removed",
-          })
-        }}
-      />
-      <Button
-        label="Clear notifications"
-        onClick={() => clearToastNotifications()}
-      />
-    </>
-  ),
+  render: () => {
+    const { addToastNotification, clearToastNotifications } =
+      useToastNotification()
+    return (
+      <>
+        <Button
+          label="Create notifications"
+          classNameOverride="!mr-12"
+          onClick={() => {
+            addToastNotification({
+              id: "id--clear-example-1",
+              title: "First",
+              type: "positive",
+              message: "This notification will be removed",
+            })
+            addToastNotification({
+              id: "id--clear-example-2",
+              title: "Second",
+              type: "cautionary",
+              message: "This notification will also be removed",
+            })
+            addToastNotification({
+              id: "id--clear-example-3",
+              title: "Third",
+              type: "negative",
+              message: "This notification will also also be removed",
+            })
+          }}
+        />
+        <Button
+          label="Clear notifications"
+          onClick={() => clearToastNotifications()}
+        />
+      </>
+    )
+  },
 }