[LG-4952] feat(modal): Modal renders as dialog element in top layer (#3048)

* chore(modal): add @leafygreen-ui/toast as dev dep

* feat(modal): add focusModalChildElement util

* [breaking] refactor(modal): use <dialog> element in LG modals, remove initialFocus prop, and update custom styling props

* docs(modals): update READMEs

* chore(modals): changeset

* chore(modal): remove unused deps

* [LG-4952] feat(codemods): add modal-v20 codemod for automatic Modal v20 upgrade (#3049)

* feat(codemods): modal-v20 🚀

* docs: update codemods README with modal-v20 details and add modal package upgrade guide

* chore: modal and codemods changesets

* refactor: feedback

Author: stephl3

.changeset/famous-dancers-wink.md

@@ -0,0 +1,5 @@
+---
+'@lg-tools/codemods': minor
+---
+
+[LG-4952](https://jira.mongodb.org/browse/LG-4952): Add `modal-v20` codemod which can be used when upgrading to `@leafygreen-ui/modal` v20+ and other LG modals. More details in [codemods README](https://github.com/mongodb/leafygreen-ui/tree/main/tools/codemods#modal-v20)

.changeset/plain-banks-take.md

@@ -0,0 +1,28 @@
+---
+'@leafygreen-ui/confirmation-modal': major
+'@leafygreen-ui/marketing-modal': major
+'@leafygreen-ui/modal': major
+---
+
+[LG-4952](https://jira.mongodb.org/browse/LG-4952)
+
+#### Breaking Changes
+
+- **Top layer rendering**: Component renders in [top layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer) instead of portaling
+- **Props**: `className` → `backdropClassName`, `contentClassName` → `className`, `initialFocus` prop removed
+- **Backdrop styling**: `backdropClassName` deprecated in favor of CSS `::backdrop` pseudo-element
+- **Focus management**: Specifying `autoFocus` on focusable child element replaces manual `initialFocus` prop
+- **Type changes**: Component now extends `HTMLElementProps<'dialog'>` instead of `HTMLElementProps<'div'>`
+
+#### Migration Guide
+
+Use the [modal-v20 codemod]([popover-v12 codemod](https://github.com/mongodb/leafygreen-ui/tree/main/tools/codemods#modal-v20) for migration assistance.
+
+```shell
+pnpm lg codemod modal-v20 <path>
+```
+
+The codemod will:
+1. Rename `className` prop to `backdropClassName`
+2. Rename `contentClassName` prop to `className`
+3. Remove `initialFocus` prop and add guidance comments

packages/confirmation-modal/README.md

@@ -26,7 +26,7 @@ npm install @leafygreen-ui/confirmation-modal
 
 ## Example
 
-```js
+```tsx
 import ConfirmationModal from '@leafygreen-ui/confirmation-modal';
 
 function ExampleComponent() {

packages/confirmation-modal/src/ConfirmationModal/ConfirmationModal.spec.tsx

@@ -1,10 +1,5 @@
 import React, { useState } from 'react';
-import {
-  act,
-  fireEvent,
-  render,
-  waitForElementToBeRemoved,
-} from '@testing-library/react';
+import { act, render, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { axe } from 'jest-axe';
 
@@ -42,14 +37,35 @@ function renderModal(
 }
 
 describe('packages/confirmation-modal', () => {
+  // Mock dialog methods for JSDOM environment
+  beforeAll(() => {
+    HTMLDialogElement.prototype.show = jest.fn(function mock(
+      this: HTMLDialogElement,
+    ) {
+      this.open = true;
+    });
+
+    HTMLDialogElement.prototype.showModal = jest.fn(function mock(
+      this: HTMLDialogElement,
+    ) {
+      this.open = true;
+    });
+
+    HTMLDialogElement.prototype.close = jest.fn(function mock(
+      this: HTMLDialogElement,
+    ) {
+      this.open = false;
+    });
+  });
+
   describe('a11y', () => {
     test('does not have basic accessibility issues', async () => {
       const { container, getByText } = renderModal({ open: true });
       const results = await axe(container);
       expect(results).toHaveNoViolations();
 
       let newResults = null as any;
-      act(() => void fireEvent.click(getByText('Confirm')));
+      act(() => void userEvent.click(getByText('Confirm')));
       await act(async () => {
         newResults = await axe(container);
       });
@@ -58,8 +74,8 @@ describe('packages/confirmation-modal', () => {
   });
 
   test('does not render if closed', () => {
-    renderModal();
-    expect(document.body.innerHTML).toEqual('<div></div>');
+    const { getByText } = renderModal();
+    expect(getByText('Content text')).not.toBeVisible();
   });
 
   test('renders if open', () => {
@@ -122,7 +138,7 @@ describe('packages/confirmation-modal', () => {
       const button = getByText('Confirm');
       expect(button).toBeVisible();
 
-      fireEvent.click(button);
+      userEvent.click(button);
       expect(confirmSpy).toHaveBeenCalledTimes(1);
       expect(cancelSpy).not.toHaveBeenCalled();
     });
@@ -141,7 +157,7 @@ describe('packages/confirmation-modal', () => {
       const button = getByText('Confirm');
       expect(button).toBeVisible();
 
-      fireEvent.click(button);
+      userEvent.click(button);
       expect(confirmSpy).toHaveBeenCalledTimes(1);
     });
   });
@@ -161,7 +177,7 @@ describe('packages/confirmation-modal', () => {
       const button = getByText('Cancel');
       expect(button).toBeVisible();
 
-      fireEvent.click(button);
+      userEvent.click(button);
       expect(confirmSpy).not.toHaveBeenCalled();
       expect(cancelSpy).toHaveBeenCalledTimes(1);
     });
@@ -181,7 +197,7 @@ describe('packages/confirmation-modal', () => {
       const button = getByText('Cancel');
       expect(button).toBeVisible();
 
-      fireEvent.click(button);
+      userEvent.click(button);
       expect(confirmSpy).not.toHaveBeenCalled();
       expect(cancelSpy).toHaveBeenCalledTimes(1);
     });
@@ -192,19 +208,19 @@ describe('packages/confirmation-modal', () => {
       const { getByRole } = renderModal({ open: true });
       const modal = getByRole('dialog');
 
-      fireEvent.keyDown(document, { key: 'Escape', keyCode: 27 });
+      userEvent.keyboard('{Escape}');
 
-      await waitForElementToBeRemoved(modal);
+      await waitFor(() => expect(modal).not.toBeVisible());
     });
 
     test('x icon is clicked', async () => {
       const { getByLabelText, getByRole } = renderModal({ open: true });
       const modal = getByRole('dialog');
 
       const x = getByLabelText('Close modal');
-      fireEvent.click(x);
+      userEvent.click(x);
 
-      await waitForElementToBeRemoved(modal);
+      await waitFor(() => expect(modal).not.toBeVisible());
     });
   });
 
@@ -227,18 +243,22 @@ describe('packages/confirmation-modal', () => {
       expect(textInput).toBe(document.activeElement);
 
       // Should still be disabled after partial entry
-      fireEvent.change(textInput, { target: { value: 'Confir' } });
+      userEvent.clear(textInput);
+      userEvent.type(textInput, 'Confir');
       expect(confirmationButton).toHaveAttribute('aria-disabled', 'true');
 
-      fireEvent.change(textInput, { target: { value: 'Confirm' } });
+      userEvent.clear(textInput);
+      userEvent.type(textInput, 'Confirm');
       expect(confirmationButton).not.toHaveAttribute('aria-disabled', 'true');
 
       // Should be disabled again
-      fireEvent.change(textInput, { target: { value: 'Confirm?' } });
+      userEvent.clear(textInput);
+      userEvent.type(textInput, 'Confirm?');
       expect(confirmationButton).toHaveAttribute('aria-disabled', 'true');
 
       // Case matters
-      fireEvent.change(textInput, { target: { value: 'confirm' } });
+      userEvent.clear(textInput);
+      userEvent.type(textInput, 'confirm');
       expect(confirmationButton).toHaveAttribute('aria-disabled', 'true');
     });
 
@@ -287,9 +307,8 @@ describe('packages/confirmation-modal', () => {
             textInput = getByLabelText(
               `Type "${requiredInputText}" to confirm your action`,
             );
-            fireEvent.change(textInput, {
-              target: { value: requiredInputText },
-            });
+            userEvent.clear(textInput);
+            userEvent.type(textInput, requiredInputText);
             expect(confirmationButton).not.toHaveAttribute(
               'aria-disabled',
               'true',
@@ -298,7 +317,7 @@ describe('packages/confirmation-modal', () => {
 
           userEvent.click(buttonToClick);
 
-          await waitForElementToBeRemoved(modal);
+          await waitFor(() => expect(modal).not.toBeVisible());
 
           rerender(
             <ConfirmationModal
@@ -354,8 +373,8 @@ describe('packages/confirmation-modal', () => {
       expect(button).toBeVisible();
 
       // Modal doesn't close when button is clicked
-      fireEvent.click(button);
-      await waitForElementToBeRemoved(modal);
+      userEvent.click(button);
+      await waitFor(() => expect(modal).not.toBeVisible());
     });
 
     test('"confirmButtonProps" has "disabled: false"', async () => {
@@ -374,8 +393,8 @@ describe('packages/confirmation-modal', () => {
       expect(button).toBeVisible();
 
       // Modal doesn't close when button is clicked
-      fireEvent.click(button);
-      await waitForElementToBeRemoved(modal);
+      userEvent.click(button);
+      await waitFor(() => expect(modal).not.toBeVisible());
     });
   });
 
@@ -395,7 +414,7 @@ describe('packages/confirmation-modal', () => {
       expect(button).toBeVisible();
 
       // Modal doesn't close when button is clicked
-      fireEvent.click(button);
+      userEvent.click(button);
       expect(button).toBeVisible();
     });
 
@@ -413,7 +432,7 @@ describe('packages/confirmation-modal', () => {
       expect(button).toBeVisible();
 
       // Modal doesn't close when button is clicked
-      fireEvent.click(button);
+      userEvent.click(button);
       expect(button).toBeVisible();
     });
 
@@ -434,7 +453,7 @@ describe('packages/confirmation-modal', () => {
       expect(button).toBeVisible();
 
       // Modal doesn't close when button is clicked
-      fireEvent.click(button);
+      userEvent.click(button);
       expect(button).toBeVisible();
     });
 
@@ -453,7 +472,8 @@ describe('packages/confirmation-modal', () => {
       const textInput = getByLabelText('Type "Confirm" to confirm your action');
       expect(textInput).toBeVisible();
 
-      fireEvent.change(textInput, { target: { value: 'Confirm' } });
+      userEvent.clear(textInput);
+      userEvent.type(textInput, 'Confirm');
       expect(confirmationButton).toHaveAttribute('aria-disabled', 'true');
     });
 
@@ -471,7 +491,8 @@ describe('packages/confirmation-modal', () => {
       const textInput = getByLabelText('Type "Confirm" to confirm your action');
       expect(textInput).toBeVisible();
 
-      fireEvent.change(textInput, { target: { value: 'Confirm' } });
+      userEvent.clear(textInput);
+      userEvent.type(textInput, 'Confirm');
       expect(confirmationButton).toHaveAttribute('aria-disabled', 'true');
     });
   });

packages/confirmation-modal/src/ConfirmationModal/ConfirmationModal.tsx

@@ -1,4 +1,4 @@
-import React, { useMemo, useState } from 'react';
+import React, { forwardRef, useMemo, useState } from 'react';
 
 import Button from '@leafygreen-ui/button';
 import { cx } from '@leafygreen-ui/emotion';
@@ -27,7 +27,10 @@ import {
 /**
  * Modals can be used to display a simple task, confirm actions, prompt users to input information, or display additional information.
  */
-export const ConfirmationModal = React.forwardRef(
+export const ConfirmationModal = forwardRef<
+  HTMLDialogElement,
+  ConfirmationModalProps
+>(
   (
     {
       children,
@@ -43,8 +46,8 @@ export const ConfirmationModal = React.forwardRef(
       cancelButtonProps = {},
       'data-lgid': dataLgId,
       ...modalProps
-    }: ConfirmationModalProps,
-    forwardRef: React.ForwardedRef<HTMLDivElement | null>,
+    },
+    fwdRef,
   ) => {
     const [confirmEnabled, setConfirmEnabled] = useState(!requiredInputText);
     const { theme, darkMode } = useDarkMode(darkModeProp);
@@ -105,10 +108,10 @@ export const ConfirmationModal = React.forwardRef(
         data-testid={lgIds.root}
         data-lgid={lgIds.root}
         {...modalProps}
-        contentClassName={baseModalStyle}
+        className={baseModalStyle}
         setOpen={handleCancel}
         darkMode={darkMode}
-        ref={forwardRef}
+        ref={fwdRef}
       >
         <div
           className={cx(contentStyle, contentVariantStyles[variant], {

packages/marketing-modal/README.md

@@ -26,7 +26,9 @@ npm install @leafygreen-ui/marketing-modal
 
 ## Example
 
-```js
+```tsx
+import MarketingModal from '@leafygreen-ui/marketing-modal';
+
 function Example() {
   const [open, setOpen] = useState(false);
 

packages/marketing-modal/src/MarketingModal/MarketingModal.spec.tsx

@@ -1,5 +1,5 @@
 import React, { useState } from 'react';
-import { act, render, waitForElementToBeRemoved } from '@testing-library/react';
+import { act, render, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { axe } from 'jest-axe';
 
@@ -41,6 +41,27 @@ function renderModal(
 }
 
 describe('packages/marketing-modal', () => {
+  // Mock dialog methods for JSDOM environment
+  beforeAll(() => {
+    HTMLDialogElement.prototype.show = jest.fn(function mock(
+      this: HTMLDialogElement,
+    ) {
+      this.open = true;
+    });
+
+    HTMLDialogElement.prototype.showModal = jest.fn(function mock(
+      this: HTMLDialogElement,
+    ) {
+      this.open = true;
+    });
+
+    HTMLDialogElement.prototype.close = jest.fn(function mock(
+      this: HTMLDialogElement,
+    ) {
+      this.open = false;
+    });
+  });
+
   describe('a11y', () => {
     test('does not have basic accessibility issues', async () => {
       const { container, getByText } = renderModal({ open: true });
@@ -56,8 +77,8 @@ describe('packages/marketing-modal', () => {
     });
   });
   test('does not render if closed', () => {
-    renderModal();
-    expect(document.body.innerHTML).toEqual('<div></div>');
+    const { getByText } = renderModal();
+    expect(getByText('Content text')).not.toBeVisible();
   });
 
   test('renders if open', () => {
@@ -125,7 +146,7 @@ describe('packages/marketing-modal', () => {
 
       userEvent.keyboard('{Escape}');
 
-      await waitForElementToBeRemoved(modal);
+      await waitFor(() => expect(modal).not.toBeVisible());
     });
 
     test('x icon is clicked', async () => {
@@ -135,7 +156,7 @@ describe('packages/marketing-modal', () => {
       const x = getByLabelText('Close modal');
       userEvent.click(x);
 
-      await waitForElementToBeRemoved(modal);
+      await waitFor(() => expect(modal).not.toBeVisible());
     });
   });