feat(drawer): add focus management to embedded drawers

.changeset/beige-lights-kick.md

@@ -0,0 +1,7 @@
+---
+'@leafygreen-ui/drawer': minor
+---
+
+- Adds focus management to embedded drawers. Embedded drawers will now automatically focus the first focusable element when opened and restore focus to the previously focused element when closed. Overlay drawers use the native focus behavior of the dialog element.
+- Adds visually hidden element to announce drawer state changes to screen readers.
+- Removes CSS visibility check from the `isOpen` test utility since `opacity, `visibility` and `display` properties do not change when the drawer is opened or closed.

packages/drawer/package.json

@@ -28,6 +28,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@leafygreen-ui/a11y": "workspace:^",
     "@leafygreen-ui/button": "workspace:^",
     "@leafygreen-ui/emotion": "workspace:^",
     "@leafygreen-ui/hooks": "workspace:^",
@@ -37,7 +38,6 @@
     "@leafygreen-ui/palette": "workspace:^",
     "@leafygreen-ui/polymorphic": "workspace:^",
     "@leafygreen-ui/resizable": "workspace:^",
-    "@leafygreen-ui/tabs": "workspace:^",
     "@leafygreen-ui/tokens": "workspace:^",
     "@leafygreen-ui/toolbar": "workspace:^",
     "@leafygreen-ui/typography": "workspace:^",

packages/drawer/src/Drawer/Drawer.spec.tsx

@@ -1,8 +1,9 @@
-import React from 'react';
-import { render } from '@testing-library/react';
+import React, { useState } from 'react';
+import { render, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { axe } from 'jest-axe';
 
+import { DrawerLayout } from '../DrawerLayout';
 import { DrawerStackProvider } from '../DrawerStackContext';
 import { getTestUtils } from '../testing';
 
@@ -13,6 +14,31 @@ const drawerTest = {
   title: 'Drawer title',
 } as const;
 
+const DrawerWithButton = ({
+  displayMode = DisplayMode.Embedded,
+}: { displayMode?: DisplayMode } = {}) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const handleOpen = () => setIsOpen(true);
+  const buttonRef = React.useRef<HTMLButtonElement>(null);
+  return (
+    <DrawerLayout
+      isDrawerOpen={isOpen}
+      onClose={() => setIsOpen(false)}
+      displayMode={displayMode}
+    >
+      <button data-testid="open-drawer-button" onClick={handleOpen}>
+        Open Drawer
+      </button>
+      <Drawer title={drawerTest.title}>
+        <button data-testid="primary-button">Primary</button>
+        <button data-testid="secondary-button" ref={buttonRef}>
+          Secondary
+        </button>
+      </Drawer>
+    </DrawerLayout>
+  );
+};
+
 function renderDrawer(props: Partial<DrawerProps> = {}) {
   const utils = render(
     <DrawerStackProvider>
@@ -47,6 +73,247 @@ describe('packages/drawer', () => {
       const results = await axe(container);
       expect(results).toHaveNoViolations();
     });
+
+    describe('initialFocus prop', () => {
+      describe('auto', () => {
+        test('focus is on the first focusable element when the drawer is opened by pressing the enter key on the open button', async () => {
+          const { getByTestId } = render(<DrawerWithButton />);
+          const { isOpen, getCloseButtonUtils } = getTestUtils();
+
+          expect(isOpen()).toBe(false);
+          const openDrawerButton = getByTestId('open-drawer-button');
+          openDrawerButton.focus();
+          userEvent.keyboard('{enter}');
+
+          await waitFor(() => {
+            expect(isOpen()).toBe(true);
+            const closeButton = getCloseButtonUtils().getButton();
+            expect(closeButton).toHaveFocus();
+          });
+        });
+
+        test('focus returns to the open button when the drawer is closed', async () => {
+          const { getByTestId } = render(<DrawerWithButton />);
+          const { isOpen, getCloseButtonUtils } = getTestUtils();
+
+          expect(isOpen()).toBe(false);
+          const openDrawerButton = getByTestId('open-drawer-button');
+          openDrawerButton.focus();
+          userEvent.keyboard('{enter}');
+
+          await waitFor(() => {
+            expect(isOpen()).toBe(true);
+            const closeButton = getCloseButtonUtils().getButton();
+            expect(closeButton).toHaveFocus();
+          });
+
+          userEvent.keyboard('{enter}');
+
+          await waitFor(() => {
+            expect(isOpen()).toBe(false);
+            expect(openDrawerButton).toHaveFocus();
+          });
+        });
+      });
+
+      describe('string selector', () => {
+        describe.each([DisplayMode.Embedded, DisplayMode.Overlay])(
+          'displayMode: %s',
+          displayMode => {
+            test('focus is on the initial focus string selector', async () => {
+              const TestComponent = () => {
+                return (
+                  <DrawerLayout
+                    isDrawerOpen={true}
+                    onClose={() => {}}
+                    displayMode={displayMode}
+                    initialFocus="#secondary-button"
+                  >
+                    <Drawer title={drawerTest.title}>
+                      <button data-testid="primary-button">Primary</button>
+                      <button
+                        data-testid="secondary-button"
+                        id="secondary-button"
+                      >
+                        Secondary
+                      </button>
+                    </Drawer>
+                  </DrawerLayout>
+                );
+              };
+
+              const { getByTestId } = render(<TestComponent />);
+
+              const secondaryButton = getByTestId('secondary-button');
+              expect(secondaryButton).toHaveFocus();
+            });
+          },
+        );
+
+        test('focus returns to the open button when the drawer is closed', async () => {
+          const TestComponent = () => {
+            const [isOpen, setIsOpen] = useState(false);
+            const handleOpen = () => setIsOpen(true);
+            return (
+              <DrawerLayout
+                isDrawerOpen={isOpen}
+                onClose={() => setIsOpen(false)}
+                displayMode={DisplayMode.Embedded}
+                initialFocus="#secondary-button"
+              >
+                <button data-testid="open-drawer-button" onClick={handleOpen}>
+                  Open Drawer
+                </button>
+                <Drawer title={drawerTest.title}>
+                  <button data-testid="primary-button">Primary</button>
+                  <button data-testid="secondary-button" id="secondary-button">
+                    Secondary
+                  </button>
+                </Drawer>
+              </DrawerLayout>
+            );
+          };
+
+          const { getByTestId } = render(<TestComponent />);
+          const { isOpen, getCloseButtonUtils } = getTestUtils();
+
+          const openDrawerButton = getByTestId('open-drawer-button');
+          openDrawerButton.focus();
+          userEvent.keyboard('{enter}');
+
+          await waitFor(() => {
+            expect(isOpen()).toBe(true);
+          });
+
+          const secondaryButton = getByTestId('secondary-button');
+          expect(secondaryButton).toHaveFocus();
+
+          const closeButton = getCloseButtonUtils().getButton();
+          closeButton.focus();
+          userEvent.keyboard('{enter}');
+
+          await waitFor(() => {
+            expect(isOpen()).toBe(false);
+            expect(openDrawerButton).toHaveFocus();
+          });
+        });
+      });
+
+      describe('ref', () => {
+        describe.each([DisplayMode.Embedded, DisplayMode.Overlay])(
+          'displayMode: %s',
+          displayMode => {
+            test('focus is on the initial focus ref', async () => {
+              const TestComponent = () => {
+                const buttonRef = React.useRef<HTMLButtonElement>(null);
+                return (
+                  <DrawerLayout
+                    isDrawerOpen={true}
+                    onClose={() => {}}
+                    displayMode={displayMode}
+                    initialFocus={buttonRef}
+                  >
+                    <Drawer title={drawerTest.title}>
+                      <button data-testid="primary-button">Primary</button>
+                      <button data-testid="secondary-button" ref={buttonRef}>
+                        Secondary
+                      </button>
+                    </Drawer>
+                  </DrawerLayout>
+                );
+              };
+
+              const { getByTestId } = render(<TestComponent />);
+
+              const secondaryButton = getByTestId('secondary-button');
+              expect(secondaryButton).toHaveFocus();
+            });
+          },
+        );
+
+        test('focus returns to the open button when the drawer is closed', async () => {
+          const TestComponent = () => {
+            const [isOpen, setIsOpen] = useState(false);
+            const handleOpen = () => setIsOpen(true);
+            const buttonRef = React.useRef<HTMLButtonElement>(null);
+            return (
+              <DrawerLayout
+                isDrawerOpen={isOpen}
+                onClose={() => setIsOpen(false)}
+                displayMode={DisplayMode.Embedded}
+                initialFocus={buttonRef}
+              >
+                <button data-testid="open-drawer-button" onClick={handleOpen}>
+                  Open Drawer
+                </button>
+                <Drawer title={drawerTest.title}>
+                  <button data-testid="primary-button">Primary</button>
+                  <button data-testid="secondary-button" ref={buttonRef}>
+                    Secondary
+                  </button>
+                </Drawer>
+              </DrawerLayout>
+            );
+          };
+
+          const { getByTestId } = render(<TestComponent />);
+          const { isOpen, getCloseButtonUtils } = getTestUtils();
+
+          const openDrawerButton = getByTestId('open-drawer-button');
+          openDrawerButton.focus();
+          userEvent.keyboard('{enter}');
+
+          await waitFor(() => {
+            expect(isOpen()).toBe(true);
+          });
+
+          const secondaryButton = getByTestId('secondary-button');
+          expect(secondaryButton).toHaveFocus();
+
+          const closeButton = getCloseButtonUtils().getButton();
+          closeButton.focus();
+          userEvent.keyboard('{enter}');
+
+          await waitFor(() => {
+            expect(isOpen()).toBe(false);
+            expect(openDrawerButton).toHaveFocus();
+          });
+        });
+      });
+
+      describe('autoFocus attribute', () => {
+        test('focus is on the element with the autoFocus attribute', async () => {
+          const TestComponent = () => {
+            return (
+              <DrawerLayout
+                isDrawerOpen={true}
+                onClose={() => {}}
+                displayMode={DisplayMode.Embedded}
+              >
+                <Drawer title={drawerTest.title}>
+                  <button data-testid="primary-button">Primary</button>
+                  <button
+                    data-testid="secondary-button"
+                    id="secondary-button"
+                    // eslint-disable-next-line jsx-a11y/no-autofocus
+                    autoFocus={true}
+                    // react does not add the autofocus attribute to the button element, so it needs to be added manually for embedded mode
+                    {...{ autofocus: '' }}
+                  >
+                    Secondary
+                  </button>
+                </Drawer>
+              </DrawerLayout>
+            );
+          };
+
+          const { getByTestId } = render(<TestComponent />);
+
+          const secondaryButton = getByTestId('secondary-button');
+          expect(secondaryButton).toHaveFocus();
+        });
+      });
+    });
   });
 
   describe('displayMode prop', () => {