feat(drawer): add focus management to embedded drawers

.changeset/beige-lights-kick.md

@@ -0,0 +1,5 @@
+---
+'@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.

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,23 @@ const drawerTest = {
   title: 'Drawer title',
 } as const;
 
+const DrawerWithButton = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  const handleOpen = () => setIsOpen(true);
+  return (
+    <DrawerLayout
+      isDrawerOpen={isOpen}
+      onClose={() => setIsOpen(false)}
+      displayMode={DisplayMode.Embedded}
+    >
+      <button data-testid="open-drawer-button" onClick={handleOpen}>
+        Open Drawer
+      </button>
+      <Drawer title={drawerTest.title}>{drawerTest.content}</Drawer>
+    </DrawerLayout>
+  );
+};
+
 function renderDrawer(props: Partial<DrawerProps> = {}) {
   const utils = render(
     <DrawerStackProvider>
@@ -47,6 +65,45 @@ describe('packages/drawer', () => {
       const results = await axe(container);
       expect(results).toHaveNoViolations();
     });
+
+    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('displayMode prop', () => {

packages/drawer/src/Drawer/Drawer.tsx

@@ -1,6 +1,7 @@
 import React, { forwardRef, useEffect, useRef, useState } from 'react';
 import { useInView } from 'react-intersection-observer';
 
+import { VisuallyHidden } from '@leafygreen-ui/a11y';
 import {
   useIdAllocator,
   useIsomorphicLayoutEffect,
@@ -11,6 +12,7 @@ import IconButton from '@leafygreen-ui/icon-button';
 import LeafyGreenProvider, {
   useDarkMode,
 } from '@leafygreen-ui/leafygreen-provider';
+import { queryFirstFocusableElement } from '@leafygreen-ui/lib';
 import { usePolymorphic } from '@leafygreen-ui/polymorphic';
 import { Position, useResizable } from '@leafygreen-ui/resizable';
 import { BaseFontSize } from '@leafygreen-ui/tokens';
@@ -134,27 +136,58 @@ export const Drawer = forwardRef<HTMLDivElement, DrawerProps>(
       }
     }, [id, open, registerDrawer, unregisterDrawer]);
 
+    const previouslyFocusedRef = useRef<HTMLElement | null>(null);
+    const hasHandledFocusRef = useRef<boolean>(false);
+
     /**
-     * Focuses the first focusable element in the drawer when the animation ends. We have to manually handle this because we are hiding the drawer with visibility: hidden, which breaks the default focus behavior of dialog element.
+     * Focuses the first focusable element in the drawer when the drawer is opened.
+     * Also handles restoring focus when the drawer is closed.
      *
+     * This is only necessary for embedded drawers. Overlay drawers use the native focus behavior of the dialog element.
      */
-    const handleAnimationEnd = () => {
-      const drawerElement = ref.current;
+    useIsomorphicLayoutEffect(() => {
+      if (isOverlay) return;
 
-      // Check if the drawerElement is null or is a div, which means it is not a dialog element.
-      if (!drawerElement || drawerElement instanceof HTMLDivElement) {
-        return;
-      }
+      if (open && !hasHandledFocusRef.current) {
+        // Store the currently focused element when opening (only once per open session)
+        previouslyFocusedRef.current = document.activeElement as HTMLElement;
+        hasHandledFocusRef.current = true;
 
-      if (open) {
-        const firstFocusable = drawerElement.querySelector(
-          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
-        );
-        (firstFocusable as HTMLElement)?.focus();
+        if (ref.current === null) {
+          return;
+        }
+
+        // Find and focus the first focusable element in the drawer
+        const firstFocusableElement = queryFirstFocusableElement(ref.current);
+        firstFocusableElement?.focus();
+      } else if (!open && hasHandledFocusRef.current) {
+        // Check if the current focus is not in the drawer
+        // This means the user has navigated away from the drawer, like the toolbar, and we should not restore focus.
+        if (!ref.current?.contains(document.activeElement)) {
+          hasHandledFocusRef.current = false;
+          previouslyFocusedRef.current = null;
+          return;
+        }
+
+        // Restore focus when closing (only if we had handled focus during this session)
+        if (previouslyFocusedRef.current) {
+          // Check if the previously focused element is still in the DOM
+          if (document.contains(previouslyFocusedRef.current)) {
+            previouslyFocusedRef.current.focus();
+          } else {
+            // If the previously focused element is no longer in the DOM, focus the body
+            // This mimics the behavior of the native HTML Dialog element
+            document.body.focus();
+          }
+          previouslyFocusedRef.current = null; // Clear the ref
+        }
+        hasHandledFocusRef.current = false; // Reset for next open session
       }
-    };
+    }, [isOverlay, open]);
 
-    // Enables resizable functionality if the drawer is resizable, embedded and open.
+    /**
+     * Enables resizable functionality if the drawer is resizable, embedded and open.
+     */
     const {
       resizableRef,
       size: drawerSize,
@@ -218,6 +251,12 @@ export const Drawer = forwardRef<HTMLDivElement, DrawerProps>(
 
     return (
       <LeafyGreenProvider darkMode={darkMode}>
+        {/* Live region for announcing drawer state changes to screen readers */}
+        {open && (
+          <VisuallyHidden aria-live="polite" aria-atomic="true">
+            {`${title} drawer`}
+          </VisuallyHidden>
+        )}
         <Component
           aria-hidden={!open}
           aria-labelledby={titleId}
@@ -235,7 +274,6 @@ export const Drawer = forwardRef<HTMLDivElement, DrawerProps>(
           data-testid={lgIds.root}
           id={id}
           ref={drawerRef}
-          onAnimationEnd={handleAnimationEnd}
           inert={!open ? 'inert' : undefined}
           {...rest}
         >
@@ -246,6 +284,8 @@ export const Drawer = forwardRef<HTMLDivElement, DrawerProps>(
                 resizerClassName: resizerProps?.className,
                 hasToolbar,
               })}
+              data-lgid={lgIds.resizer}
+              data-testid={lgIds.resizer}
             />
           )}
           <div className={getDrawerShadowStyles({ theme, displayMode })}>

packages/drawer/src/DrawerToolbarLayout/DrawerToolbarLayout/DrawerToolbarLayout.interactions.stories.tsx

@@ -274,6 +274,92 @@
   });
 };
 
+// Reusable play function for testing focus management with toolbar buttons
+const playToolbarFocusManagement = async ({
+  canvasElement,
+}: {
+  canvasElement: HTMLElement;
+}) => {
+  const canvas = within(canvasElement);
+  const { getToolbarTestUtils, getCloseButtonUtils, isOpen, getDrawer } =
+    getTestUtils();
+  const { getToolbarIconButtonByLabel } = getToolbarTestUtils();
+  const codeButton = getToolbarIconButtonByLabel('Code')?.getElement();
+  // Wait for the component to be fully rendered and find the button by test ID
+  const openCodeButton = await canvas.findByTestId('open-code-drawer-button');
+
+  // Verify initial state
+  expect(isOpen()).toBe(false);
+  userEvent.click(openCodeButton);
+
+  await waitFor(() => {
+    expect(isOpen()).toBe(true);
+    expect(canvas.getByText('Code Title')).toBeVisible();
+    expect(getDrawer()).toContain(document.activeElement);
+  });
+
+  // Click the close button
+  userEvent.click(codeButton!);
+
+  await waitFor(() => {
+    expect(isOpen()).toBe(false);
+  });
+
+  // Focus should return to the original toolbar button that opened the drawer
+  await waitFor(() => {
+    expect(document.activeElement).toBe(codeButton);
+  });
+};
+
+// Reusable play function for testing focus management with main content button
+const playMainContentButtonFocusManagement = async ({
+  canvasElement,
+}: {
+  canvasElement: HTMLElement;
+}) => {
+  const canvas = within(canvasElement);
+  const { getCloseButtonUtils, isOpen, getDrawer } = getTestUtils();
+
+  // Wait for the component to be fully rendered and find the button by test ID
+  const openCodeButton = await canvas.findByTestId('open-code-drawer-button');
+
+  // Verify initial state
+  expect(isOpen()).toBe(false);
+  expect(openCodeButton).toBeInTheDocument();
+
+  // Focus and click the "Open Code Drawer" button to open drawer
+  openCodeButton.focus();
+
+  // Verify focus is on the button - wait for focus to be applied
+  await waitFor(() => {
+    expect(document.activeElement).toBe(openCodeButton);
+  });
+
+  userEvent.click(openCodeButton);
+
+  await waitFor(() => {
+    expect(isOpen()).toBe(true);
+    expect(canvas.getByText('Code Title')).toBeVisible();
+    expect(getDrawer()).toContain(document.activeElement);
+  });
+
+  // Get the close button from the drawer
+  const closeButton = getCloseButtonUtils().getButton();
+  expect(closeButton).toBeInTheDocument();
+
+  // Click the close button to close the drawer
+  userEvent.click(closeButton!);
+
+  await waitFor(() => {
+    expect(isOpen()).toBe(false);
+  });
+
+  // Focus should return to the original "Open Code Drawer" button
+  await waitFor(() => {
+    expect(document.activeElement).toBe(openCodeButton);
+  });
+};
+
 // For testing purposes. displayMode is read from the context, so we need to
 // pass it down to the DrawerToolbarLayoutProps.
 type DrawerToolbarLayoutPropsWithDisplayMode = DrawerToolbarLayoutProps & {
@@ -326,7 +412,12 @@
           padding: ${spacing[400]}px;
         `}
       >
-        <Button onClick={() => openDrawer('Code')}>Open Code Drawer</Button>
+        <Button
+          onClick={() => openDrawer('Code')}
+          data-testid="open-code-drawer-button"
+        >
+          Open Code Drawer
+        </Button>
         <LongContent />
         <LongContent />
       </main>
@@ -476,6 +567,24 @@
     play: playClosesDrawerWhenActiveItemIsRemovedFromToolbarData,
   };
 
+export const OverlayToolbarIsFocusedOnClose: StoryObj<DrawerToolbarLayoutPropsWithDisplayMode> =
+  {
+    render: (args: DrawerToolbarLayoutProps) => <Template {...args} />,
+    args: {
+      displayMode: DisplayMode.Overlay,
+    },
+    play: playToolbarFocusManagement,
+  };
+
+export const OverlayButtonIsFocusedOnClose: StoryObj<DrawerToolbarLayoutPropsWithDisplayMode> =
+  {
+    render: (args: DrawerToolbarLayoutProps) => <Template {...args} />,
+    args: {
+      displayMode: DisplayMode.Overlay,
+    },
+    play: playMainContentButtonFocusManagement,
+  };
+
 export const EmbeddedOpensFirstToolbarItem: StoryObj<DrawerToolbarLayoutPropsWithDisplayMode> =
   {
     render: (args: DrawerToolbarLayoutPropsWithDisplayMode) => (
@@ -542,6 +651,28 @@
     play: playClosesDrawerWhenActiveItemIsRemovedFromToolbarData,
   };
 
+export const EmbeddedToolbarIsFocusedOnClose: StoryObj<DrawerToolbarLayoutPropsWithDisplayMode> =
+  {
+    render: (args: DrawerToolbarLayoutPropsWithDisplayMode) => (
+      <Template {...args} />
+    ),
+    args: {
+      displayMode: DisplayMode.Embedded,
+    },
+    play: playToolbarFocusManagement,
+  };
+
+export const EmbeddedButtonIsFocusedOnClose: StoryObj<DrawerToolbarLayoutPropsWithDisplayMode> =
+  {
+    render: (args: DrawerToolbarLayoutPropsWithDisplayMode) => (
+      <Template {...args} />
+    ),
+    args: {
+      displayMode: DisplayMode.Embedded,
+    },
+    play: playMainContentButtonFocusManagement,
+  };
+
 interface MainContentProps {
   dashboardButtonRef: React.RefObject<HTMLButtonElement>;
   guideCueOpen: boolean;

packages/drawer/src/DrawerToolbarLayout/DrawerToolbarLayout/DrawerToolbarLayoutContent.tsx

@@ -88,8 +88,6 @@ export const DrawerToolbarLayoutContent = forwardRef<
           scrollable={scrollable}
           data-lgid={`${dataLgId}`}
           data-testid={`${dataLgId}`}
-          aria-live="polite"
-          aria-atomic="true"
         >
           {content}
         </Drawer>