@kaizen/components 1.43.0 → 1.44.0

package/dist/types/Modal/ConfirmationModal/ConfirmationModal.d.ts

@@ -13,6 +13,9 @@ export type ConfirmationModalProps = {
     title: string;
     onConfirm?: () => void;
     onDismiss: () => void;
+    /** A callback that is triggered after the modal is opened. */
+    onAfterEnter?: () => void;
+    /** A callback that is triggered after the modal is closed. */
     onAfterLeave?: () => void;
     confirmLabel?: string;
     dismissLabel?: string;
@@ -32,7 +35,7 @@ type Mood = "positive" | "informative" | "negative" | "cautionary" | "assertive"
  * {@link https://cultureamp.design/?path=/docs/components-modals-confirmationmodal--docs Storybook}
  */
 export declare const ConfirmationModal: {
-    ({ isOpen, isProminent, unpadded, mood, title, onConfirm, onAfterLeave, confirmLabel, dismissLabel, confirmWorking, onDismiss: propsOnDismiss, children, ...props }: ConfirmationModalProps): JSX.Element;
+    ({ isOpen, isProminent, unpadded, mood, title, onConfirm, onAfterLeave, onAfterEnter, confirmLabel, dismissLabel, confirmWorking, onDismiss: propsOnDismiss, children, ...props }: ConfirmationModalProps): JSX.Element;
     displayName: string;
 };
 export {};

package/dist/types/Modal/ContextModal/ContextModal.d.ts

@@ -16,6 +16,9 @@ export type ContextModalProps = Readonly<{
     title: string;
     onConfirm?: () => void;
     onDismiss: () => void;
+    /** A callback that is triggered after the modal is opened. */
+    onAfterEnter?: () => void;
+    /** A callback that is triggered after the modal is closed. */
     onAfterLeave?: () => void;
     confirmLabel?: string;
     confirmWorking?: {
@@ -36,6 +39,6 @@ export type ContextModalProps = Readonly<{
  * {@link https://cultureamp.design/?path=/docs/components-modals--contextmodal--docs Storybook}
  */
 export declare const ContextModal: {
-    ({ isOpen, unpadded, layout, title, onConfirm, onDismiss: propsOnDismiss, onAfterLeave, confirmLabel, confirmWorking, renderBackground, children, contentHeader, image, secondaryLabel, onSecondaryAction, ...props }: ContextModalProps): JSX.Element;
+    ({ isOpen, unpadded, layout, title, onConfirm, onDismiss: propsOnDismiss, onAfterLeave, onAfterEnter, confirmLabel, confirmWorking, renderBackground, children, contentHeader, image, secondaryLabel, onSecondaryAction, ...props }: ContextModalProps): JSX.Element;
     displayName: string;
 };

package/dist/types/Modal/GenericModal/GenericModal.d.ts

@@ -6,9 +6,12 @@ export type GenericModalProps = {
     focusLockDisabled?: boolean;
     onEscapeKeyup?: (event: KeyboardEvent) => void;
     onOutsideModalClick?: (event: React.MouseEvent) => void;
+    /** A callback that is triggered after the modal is opened. */
+    onAfterEnter?: () => void;
+    /** A callback that is triggered after the modal is closed. */
     onAfterLeave?: () => void;
 };
 export declare const GenericModal: {
-    ({ id: propsId, children, isOpen, focusLockDisabled, onEscapeKeyup, onOutsideModalClick, onAfterLeave: propsOnAfterLeave, }: GenericModalProps): JSX.Element;
+    ({ id: propsId, children, isOpen, focusLockDisabled, onEscapeKeyup, onOutsideModalClick, onAfterEnter, onAfterLeave: propsOnAfterLeave, }: GenericModalProps): JSX.Element;
     displayName: string;
 };

package/dist/types/Modal/InputEditModal/InputEditModal.d.ts

@@ -7,6 +7,9 @@ export type InputEditModalProps = {
     onSubmit: () => void;
     onSecondaryAction?: () => void;
     onDismiss: () => void;
+    /** A callback that is triggered after the modal is opened. */
+    onAfterEnter?: () => void;
+    /** A callback that is triggered after the modal is closed. */
     onAfterLeave?: () => void;
     localeDirection?: "rtl" | "ltr";
     submitLabel?: string;
@@ -27,6 +30,6 @@ export type InputEditModalProps = {
  * {@link https://cultureamp.design/?path=/docs/components-modals-inputeditmodal--docs Storybook}
  */
 export declare const InputEditModal: {
-    ({ isOpen, mood, title, onSubmit, onSecondaryAction, onAfterLeave, localeDirection, submitLabel, dismissLabel, secondaryLabel, submitWorking, children, unpadded, onDismiss: propsOnDismiss, ...props }: InputEditModalProps): JSX.Element;
+    ({ isOpen, mood, title, onSubmit, onSecondaryAction, onAfterLeave, localeDirection, submitLabel, dismissLabel, secondaryLabel, submitWorking, children, unpadded, onDismiss: propsOnDismiss, onAfterEnter, ...props }: InputEditModalProps): JSX.Element;
     displayName: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",

package/src/Modal/ConfirmationModal/ConfirmationModal.tsx

@@ -39,6 +39,9 @@ export type ConfirmationModalProps = {
   title: string
   onConfirm?: () => void
   onDismiss: () => void
+  /** A callback that is triggered after the modal is opened. */
+  onAfterEnter?: () => void
+  /** A callback that is triggered after the modal is closed. */
   onAfterLeave?: () => void
   confirmLabel?: string
   dismissLabel?: string
@@ -99,6 +102,7 @@ export const ConfirmationModal = ({
   title,
   onConfirm,
   onAfterLeave,
+  onAfterEnter,
   confirmLabel = "Confirm",
   dismissLabel = "Cancel",
   confirmWorking,
@@ -134,6 +138,7 @@ export const ConfirmationModal = ({
       onEscapeKeyup={onDismiss}
       onOutsideModalClick={onDismiss}
       onAfterLeave={onAfterLeave}
+      onAfterEnter={onAfterEnter}
     >
       <div className={styles.modal} data-modal {...props}>
         <ModalHeader onDismiss={onDismiss}>

package/src/Modal/ContextModal/ContextModal.tsx

@@ -32,6 +32,9 @@ export type ContextModalProps = Readonly<
     title: string
     onConfirm?: () => void
     onDismiss: () => void
+    /** A callback that is triggered after the modal is opened. */
+    onAfterEnter?: () => void
+    /** A callback that is triggered after the modal is closed. */
     onAfterLeave?: () => void
     confirmLabel?: string
     confirmWorking?: { label: string; labelHidden?: boolean }
@@ -59,6 +62,7 @@ export const ContextModal = ({
   onConfirm,
   onDismiss: propsOnDismiss,
   onAfterLeave,
+  onAfterEnter,
   confirmLabel = "Confirm",
   confirmWorking,
   renderBackground,
@@ -100,6 +104,7 @@ export const ContextModal = ({
       onEscapeKeyup={onDismiss}
       onOutsideModalClick={onDismiss}
       onAfterLeave={onAfterLeave}
+      onAfterEnter={onAfterEnter}
     >
       <div className={styles.modal} data-modal {...props}>
         {renderBackground && renderBackground()}

package/src/Modal/GenericModal/GenericModal.tsx

@@ -13,6 +13,9 @@ export type GenericModalProps = {
   focusLockDisabled?: boolean
   onEscapeKeyup?: (event: KeyboardEvent) => void
   onOutsideModalClick?: (event: React.MouseEvent) => void
+  /** A callback that is triggered after the modal is opened. */
+  onAfterEnter?: () => void
+  /** A callback that is triggered after the modal is closed. */
   onAfterLeave?: () => void
 }
 
@@ -23,6 +26,7 @@ export const GenericModal = ({
   focusLockDisabled,
   onEscapeKeyup,
   onOutsideModalClick,
+  onAfterEnter,
   onAfterLeave: propsOnAfterLeave,
 }: GenericModalProps): JSX.Element => {
   const reactId = useId()
@@ -50,18 +54,19 @@ export const GenericModal = ({
     }
   }
 
-  const focusAccessibleLabel = (): void => {
-    if (modalLayer) {
-      const labelElement: HTMLElement | null =
-        document.getElementById(labelledByID)
-      if (labelElement) {
-        labelElement.focus()
-      }
+  const focusOnAccessibleLabel = (): void => {
+    // Check if focus already exists within the modal
+    if (modalLayer?.contains(document.activeElement)) {
+      return
     }
+
+    const labelElement: HTMLElement | null =
+      document.getElementById(labelledByID)
+
+    labelElement?.focus()
   }
 
   const a11yWarn = (): void => {
-    if (!modalLayer) return
     // Ensure that consumers have provided an element that labels the modal
     // to meet ARIA accessibility guidelines.
     if (!document.getElementById(labelledByID)) {
@@ -86,8 +91,11 @@ export const GenericModal = ({
 
   const onAfterEnterHandler = (): void => {
     scrollModalToTop()
-    focusAccessibleLabel()
-    a11yWarn()
+    if (modalLayer) {
+      onAfterEnter?.()
+      focusOnAccessibleLabel()
+      a11yWarn()
+    }
   }
 
   const onBeforeEnterHandler = (): void => {

package/src/Modal/GenericModal/_docs/GenericModal.spec.stories.tsx

@@ -0,0 +1,124 @@
+import React from "react"
+import { action } from "@storybook/addon-actions"
+import { Meta, StoryObj } from "@storybook/react"
+import { expect, userEvent, within, waitFor } from "@storybook/test"
+
+import {
+  GenericModal,
+  ModalAccessibleLabel,
+  ModalBody,
+  ModalHeader,
+} from "../index"
+
+const meta: Meta<typeof GenericModal> = {
+  title: "Components/Modals/Generic Modal/Tests",
+  component: GenericModal,
+}
+
+export default meta
+
+type Story = StoryObj<typeof GenericModal>
+
+export const TestBase: Story = {
+  render: ({ isOpen: propsIsOpen, ...args }) => {
+    const [isOpen, setIsOpen] = React.useState<boolean>(propsIsOpen)
+    const handleDismiss = (): void => setIsOpen(false)
+
+    return (
+      <>
+        <button
+          type="button"
+          className="border border-gray-500"
+          onClick={() => setIsOpen(true)}
+        >
+          Open Modal
+        </button>
+        <GenericModal
+          {...args}
+          isOpen={isOpen}
+          onOutsideModalClick={handleDismiss}
+          onEscapeKeyup={handleDismiss}
+          id="GenericModalTestId"
+        >
+          <ModalHeader>
+            <ModalAccessibleLabel>Test Modal</ModalAccessibleLabel>
+          </ModalHeader>
+          <ModalBody>
+            <form>
+              <label htmlFor="modal-input-play-test">Add link</label>
+              <input type="text" id="modal-input-play-test" />
+            </form>
+          </ModalBody>
+        </GenericModal>
+      </>
+    )
+  },
+  play: async ({ canvasElement, step }) => {
+    const { getByRole } = within(canvasElement)
+
+    const openModalButton = getByRole("button", { name: "Open Modal" })
+
+    await step("Open modal", async () => {
+      await userEvent.click(openModalButton)
+    })
+
+    await step("Default focus is shifted to the Accessible title", async () => {
+      await waitFor(() => {
+        // document has to be use as Modal will append to document body
+        expect(document.activeElement).toHaveTextContent("Test Modal")
+      })
+    })
+  },
+}
+
+export const ModalAccessibleLabelRetainsFocus: Story = {
+  ...TestBase,
+  name: "ModalAccessibleLabel retains focus if onAfterEnter is called",
+  args: {
+    onAfterEnter: () => action("openCallBack"),
+  },
+  play: async ({ canvasElement, step }) => {
+    const { getByRole } = within(canvasElement)
+
+    const openModalButton = getByRole("button", { name: "Open Modal" })
+
+    await step("Open modal", async () => {
+      await userEvent.click(openModalButton)
+    })
+
+    await step("Accessible title still has focus", async () => {
+      await waitFor(() => {
+        expect(document.activeElement).toHaveTextContent("Test Modal")
+      })
+    })
+  },
+}
+
+export const TriggerOnAfterEnterFocus: Story = {
+  ...TestBase,
+  args: {
+    onAfterEnter: () =>
+      document.getElementById("modal-input-play-test")?.focus(),
+  },
+  name: "onAfterEnter can shift focus to internal elements of the modal",
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement)
+    const openModalButton = canvas.getByRole("button", { name: "Open Modal" })
+
+    await step("Open modal", async () => {
+      await userEvent.click(openModalButton)
+    })
+
+    await step("Expect activeElement to be the Input", async () => {
+      await waitFor(() => {
+        expect(document.activeElement).toHaveAccessibleName("Add link")
+      })
+    })
+
+    await step("Expect to be able to type without shifting focus", async () => {
+      await userEvent.keyboard(
+        "All lorem and no ipsum make dolar a dull boy..."
+      )
+    })
+  },
+}

package/src/Modal/InputEditModal/InputEditModal.tsx

@@ -19,6 +19,9 @@ export type InputEditModalProps = {
   onSubmit: () => void
   onSecondaryAction?: () => void
   onDismiss: () => void
+  /** A callback that is triggered after the modal is opened. */
+  onAfterEnter?: () => void
+  /** A callback that is triggered after the modal is closed. */
   onAfterLeave?: () => void
   localeDirection?: "rtl" | "ltr"
   submitLabel?: string
@@ -51,6 +54,7 @@ export const InputEditModal = ({
   children,
   unpadded = false,
   onDismiss: propsOnDismiss,
+  onAfterEnter,
   ...props
 }: InputEditModalProps): JSX.Element => {
   const onDismiss = submitWorking ? undefined : propsOnDismiss
@@ -79,6 +83,7 @@ export const InputEditModal = ({
       isOpen={isOpen}
       onEscapeKeyup={onDismiss}
       onAfterLeave={onAfterLeave}
+      onAfterEnter={onAfterEnter}
     >
       <div className={styles.modal} dir={localeDirection} data-modal {...props}>
         <ModalHeader onDismiss={onDismiss}>

package/src/Modal/InputEditModal/_docs/InputEditModal.mdx

@@ -39,3 +39,14 @@ When your modal is preforming a destructive action eg. delete customer data.
 ### Unpadded
 
 <Canvas of={InputEditModalStories.Unpadded} />
+
+## onAfterEnter and shifting focus
+
+It is an important accessibility consideration that any time we shift focus on the page, no important content is skipped that may provide context to assistive technologies. This is why the default behaviour for our modals is to shift focus to the accessible title.
+
+There are instances, such as single input modals, where shifting focus may not impact the users context. In these instances, we can leverage the `onAfterEnter` callback to shift focus to an input.
+
+<Canvas of={InputEditModalStories.OnAfterEnter} sourceState="shown" />
+
+As both the button and input label have clear intent and the focus does not skip past crucial content, this should provide enough context for an end user.
+

package/src/Modal/InputEditModal/_docs/InputEditModal.stories.tsx

@@ -1,4 +1,4 @@
-import React, { useState } from "react"
+import React, { useRef, useState } from "react"
 import { Meta, StoryObj } from "@storybook/react"
 import { fn } from "@storybook/test"
 import isChromatic from "chromatic"
@@ -101,3 +101,65 @@ export const Unpadded: Story = {
   args: { unpadded: true },
   ...chromaticModalSettings,
 }
+
+export const OnAfterEnter: Story = {
+  ...chromaticModalSettings,
+  args: {
+    title: "Create new link",
+    submitLabel: "Add link",
+  },
+  render: args => {
+    const [isOpen, setIsOpen] = useState(IS_CHROMATIC)
+    const inputRef = useRef<HTMLInputElement>(null)
+    const handleOpen = (): void => setIsOpen(true)
+    const handleClose = (): void => setIsOpen(false)
+
+    return (
+      <>
+        <button
+          type="button"
+          className="border border-gray-500"
+          onClick={handleOpen}
+        >
+          Create a link
+        </button>
+        <InputEditModal
+          {...args}
+          isOpen={isOpen}
+          onSubmit={handleClose}
+          onDismiss={handleClose}
+          onAfterEnter={() => inputRef.current?.focus()}
+        >
+          <form>
+            <TextField inputRef={inputRef} labelText="Link URL" />
+          </form>
+        </InputEditModal>
+      </>
+    )
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `
+        // The label of the button and the input it is focused to may provide enough context.
+        <button
+          onClick={handleOpen}
+        >
+          Create a link
+        </button>
+        <InputEditModal
+          {...args}
+          isOpen={isOpen}
+          onSubmit={handleClose}
+          onDismiss={handleClose}
+          onAfterEnter={() => inputRef.current?.focus()}
+        >
+          <form>
+            <TextField inputRef={inputRef} labelText="Link URL" />
+          </form>
+        </InputEditModal>
+        `,
+      },
+    },
+  },
+}

package/src/RichTextEditor/utils/plugins/LinkManager/components/LinkModal/LinkModal.tsx

@@ -44,6 +44,7 @@ export const LinkModal = ({
       onSubmit={handleSubmit}
       onDismiss={onDismiss}
       onAfterLeave={onAfterLeave}
+      onAfterEnter={() => inputRef.current?.focus()}
     >
       <TextField
         id="href"