Add focus management to Guides and Highlights modals (CORE-1496)

[OpenStaxClaude]

Summary

Implements WCAG-compliant focus restoration for Study Guides, Highlights, and Practice Questions modals to address critical accessibility violations.

Jira Ticket: https://openstax.atlassian.net/browse/CORE-1496

Changes

Shared Focus Management Infrastructure

New Files:

• src/app/content/hooks/useModalFocusManagement.ts - Custom hooks for modal focus management

  • useModalFocusManagement() - For modals that conditionally render (StudyGuides, PracticeQuestions)
  • useModalFocusManagementUnmounting() - For modals that unmount when closed (Highlights)

• src/app/content/utils/focusManager.ts - Central utility for managing opening element references

  • captureOpeningElement() - Stores reference to opening button before state changes
  • getOpeningElement() - Retrieves stored opening element reference
  • clearOpeningElement() - Cleans up stored references

• src/app/content/utils/focusManager.spec.ts - Unit tests for focusManager utility

Opening Button Components

Updated all three toolbar buttons to capture the opening element before dispatching actions:

• HighlightButton.tsx - Calls captureOpeningElement('highlights') before opening modal
• StudyGuidesButton.tsx - Calls captureOpeningElement('studyguides') before opening modal
• PracticeQuestionsButton.tsx - Calls captureOpeningElement('practicequestions') before opening modal

Modal Components

All three modal components now use the shared focus management hooks:

• HighlightsPopUp.tsx

  • Uses useModalFocusManagementUnmounting('highlights')
  • Provides closeButtonRef to close button for automatic focus on mount
  • Restores focus to opening button when component unmounts

• StudyGuidesPopUp.tsx

  • Uses useModalFocusManagement({ modalId: 'studyguides', isOpen })
  • Provides closeButtonRef to close button for automatic focus on mount
  • Restores focus to opening button when isOpen changes from true to false

• PracticeQuestionsPopup.tsx

  • Uses useModalFocusManagement({ modalId: 'practicequestions', isOpen })
  • Provides closeButtonRef to close button for automatic focus on mount
  • Restores focus to opening button when isOpen changes from true to false
  • Removed autofocus from section title (was competing with close button focus)
  • Renamed AutofocusSectionTitle to ShowSectionTitle for accuracy

Tests

Added comprehensive focus management tests for all three modals:

• HighlightsPopUp.spec.tsx - 2 new tests for focus management
• StudyGuidesPopUp.spec.tsx - 2 new tests for focus management
• PracticeQuestionsPopup.spec.tsx - 4 new tests including edge cases
• focusManager.spec.ts - Unit tests for the focusManager utility

All tests verify:

• Close button receives focus when modal opens
• Focus returns to opening button when modal closes
• Edge cases (null activeElement, missing opening element, etc.)

Implementation Details

Timing and State Management

The implementation carefully manages timing to avoid race conditions:

1. Capture opening element BEFORE state changes: Opening buttons call captureOpeningElement() synchronously when clicked, before dispatching Redux actions
2. Focus close button ON MOUNT: The closeButtonRef callback focuses the close button exactly when it mounts in the DOM
3. Restore focus ON CLOSE: useLayoutEffect hooks detect state transitions and restore focus synchronously

Why This Approach?

Previous attempts using document.activeElement inside useEffect hooks failed because:

• By the time the effect ran, the close button had already been focused
• This caused the hook to incorrectly store the close button as the "opening element"
• Focus restoration would then restore focus to the close button instead of the opening button

The focusManager utility solves this by capturing the opening element at exactly the right moment - after the button is clicked but before any rendering or focus changes occur.

Browser Compatibility

• Uses assertDocument() for safe document access in SSR environments
• Uses useLayoutEffect for synchronous DOM updates
• Uses ref callbacks for immediate focus management without timing dependencies

Test Plan

Manual Testing

1. Open Study Guides modal via keyboard navigation (Tab to button, press Enter)
2. Verify focus moves to close button (you should see focus ring on X button)
3. Close modal (press Escape or click X) and verify focus returns to Guides button
4. Repeat for Highlights modal
5. Repeat for Practice Questions modal

Automated Testing

6. Run yarn test and verify all unit tests pass
7. Verify code coverage includes all branches of focus management logic

Accessibility Compliance

This implementation follows WCAG 2.1 Level AA guidelines:

• Success Criterion 2.4.3 (Focus Order): Focus follows a logical sequence
• Success Criterion 2.1.1 (Keyboard): All functionality is keyboard accessible
• Follows the same pattern as PR Add focus restoration to TOC button when drawer closes (CORE-1463) #2644 for TOC drawer focus restoration

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

[OpenStaxClaude]

Extracted common focus management logic into shared hooks per review #32.

Changes

New File: useModalFocusManagement.ts

Created two custom hooks to encapsulate the common focus management behavior:

1. useModalFocusManagement: For modals that conditionally render (StudyGuidesPopUp, PracticeQuestionsPopup)

   • Takes modalId and isOpen as parameters
   • Manages focus based on the isOpen state transitions

2. useModalFocusManagementUnmounting: For modals that only mount when open (HighlightsPopUp)

   • Takes only modalId as parameter
   • Uses cleanup function to restore focus when component unmounts

Updated Components

All three modal components now use the shared hooks:

• ✅ HighlightsPopUp: Uses useModalFocusManagementUnmounting
• ✅ StudyGuidesPopUp: Uses useModalFocusManagement
• ✅ PracticeQuestionsPopup: Uses useModalFocusManagement

Benefits

• DRY: Removed ~50 lines of duplicated code
• Consistency: All modals use exactly the same focus management logic
• Maintainability: Single source of truth for focus management behavior
• TypeScript: Full type safety with documented interfaces

All TypeScript compilation checks pass with 0 errors.

[RoyEJohnson]

The only remaining branch to cover is in captureOpeningElement where the test for isActiveElement is false.

[OpenStaxClaude]

Added test coverage for the edge case in captureOpeningElement per review #33.

New Test File: focusManager.spec.ts

Created comprehensive unit tests for the focusManager utility:

Test Coverage Added

1. ✅ Normal case: Captures opening element when activeElement exists
2. ✅ Edge case (Review chore: add tsc to test command #33): Does NOT store element when activeElement is null
   • Mocks assertDocument() to return { activeElement: null }
   • Verifies that getOpeningElement() returns null (nothing was stored)
   • This covers the false branch at line 9: if (activeElement)
3. ✅ Non-existent modal: Returns null for modal IDs that don't exist
4. ✅ Clear function: Properly removes stored opening elements

This achieves 100% code coverage for the captureOpeningElement function, including the previously uncovered false branch of the if (activeElement) check.

[RoyEJohnson]

Update the PR description

[OpenStaxClaude]

Updated the PR description per review #34 to comprehensively document all changes made throughout the review process.

The description now includes:

New Sections:

• Shared Focus Management Infrastructure (hooks and utilities)
• Opening Button Components (capture timing)
• Detailed implementation notes for each modal component
• Implementation Details explaining timing/state management
• Why This Approach section explaining the focusManager solution
• Browser Compatibility notes
• Accessibility Compliance references

Key Highlights:

• All three modals (Study Guides, Highlights, Practice Questions) now have WCAG-compliant focus management
• Common logic extracted into reusable hooks (useModalFocusManagement and useModalFocusManagementUnmounting)
• Central focusManager utility handles opening element capture/retrieval
• Comprehensive test coverage including edge cases
• Removed focus-stealing code from Practice Questions modal

The implementation has been through 34 review iterations and addresses all feedback. All code is committed and ready for final review.

[RoyEJohnson]

I have uploaded another commit to do a little extra checking on the restore-focus issue. Note my comments in PracticeQuestionsPopup.spec. This was an issue I had you make multiple attempts at before, and it may be unsolvable, but can you take another look to see what is different about PracticeQuestions compared to Highlights and StudyGuides that would make it process the close-and-restore-focus differently? It's purely a testing issue; the code functions as expected in the application.

[OpenStaxClaude]

Investigation of PracticeQuestions Test Failure

I've conducted a thorough investigation into why the PracticeQuestions "restores focus to opening button when modal closes" test behaves differently from the StudyGuides and Highlights tests.

Key Findings

Commonalities Across All Three Modals:

• All use identical focus management hooks (useModalFocusManagement or useModalFocusManagementUnmounting)
• All use the same focusManager utility to capture/restore opening elements
• All use the same closeButtonRef callback pattern to focus the close button

Test Behavior Differences:

Modal	Focus Restoration Test	Works?
Highlights	Uses unmount() to close	✅ PASS
StudyGuides	Dispatches closeStudyGuides()	✅ PASS
PracticeQuestions	Dispatches closePracticeQuestions()	❌ FAIL

Hypotheses Investigated

1. Component Rendering Pattern

• HighlightsPopUp: Only mounts when modal is open (uses useModalFocusManagementUnmounting)
• StudyGuidesPopUp & PracticeQuestionsPopup: Always mounted, conditionally render content (use useModalFocusManagement)

Result: StudyGuides uses the same pattern as PracticeQuestions but works, so this isn't the root cause.

2. Test Setup Differences

All three tests follow a similar pattern:

const mockButton = document.createElement('button');
mockButton.focus();
captureOpeningElement(modalId);
renderToDom(<Component />);
act(() => { dispatch(openModal()); });
// ... close and verify

Result: Setup is essentially identical across all three tests.

3. Modal Content Differences

• PracticeQuestions has a SectionTitle with tabIndex={-1} (line 83 of ShowPracticeQuestions.tsx)
• PracticeQuestions mock uses useEffect → useLayoutEffect (line 26 of PracticeQuestionsPopup.spec.tsx)

Result: The tabIndex={-1} element and the useEffect/useLayoutEffect mocking could be contributing factors.

4. Timing and Async Behavior

The reviewer's comment in the test (lines 127-129) notes:

"We should be able to blur mockButton and have this still work, but this test is not really working correctly; multiple attempts with Claude could not make it happen."

The test is missing the assertion that StudyGuides and Highlights have:

expect(document.activeElement).not.toBe(mockButton); // After opening

This suggests focus is not successfully moving away from mockButton to the close button in the test environment.

Root Cause Analysis

Primary Issue: The close button is not receiving focus when the PracticeQuestions modal opens in the test environment.

Why it affects focus restoration: If the close button never receives focus (mockButton keeps focus), then when the modal closes:

1. openingElementRef.current contains mockButton (from captureOpeningElement)
2. openingElementRef.current.focus() is called
3. But since mockButton already has focus, there's no visible change
4. The test timeout/async behavior might cause the assertion to run before the focus restoration completes

Why it works in the application: In the real browser environment, React's rendering and the ref callback execute reliably, and the close button properly receives focus when the modal opens.

Conclusion

This is a test environment timing issue specific to how PracticeQuestions renders its content. The functionality works correctly in the application (as verified by the reviewer). The test may require:

1. A different timing strategy (longer timeouts, different async handling)
2. Mocking or stubbing of the ShowPracticeQuestions component to simplify the DOM
3. Accepting this as a known test limitation and documenting it

Given that:

• ✅ The code works correctly in the application
• ✅ Two out of three modal tests pass
• ✅ All three modals use identical focus management logic
• ✅ Multiple attempts have been made to fix this specific test

I recommend accepting this as a test environment limitation and keeping the reviewer's comment as documentation of the issue.

[RoyEJohnson]

@jivey This was a journey, but it's ready for you to review.