feat(a11y): keyboard navigation and focus management

[AbhishekChorotiya]

Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

This PR improves keyboard navigation and focus management for the payment experience. It adds shared keyboard activation and focus primitives, applies clearer expanded/dialog state where relevant, and keeps non-native interactive controls operable with keyboard expectations that match native controls.

The user impact is smoother keyboard traversal, clearer assistive-technology context for dialogs and expandable controls, and fewer focus traps or dead ends during payment selection.

This PR is stacked after the form-control accessibility PR because it reuses the shared accessibility helper module introduced there.

Closes #1647

How did you test it?

Validated as part of the completed accessibility stack. The checks cover the combined flow after all stacked PRs are applied, including keyboard and focus behavior exercised during the local accessibility smoke checks.

• Ran npm run re:build on the completed accessibility stack.
• Ran npm run test:hooks on the completed accessibility stack.
• Ran npm run build on the completed accessibility stack.
• Ran committed-range whitespace validation on the completed accessibility stack.

Checklist

• I ran npm run re:build
• I reviewed submitted code
• I added unit tests for my changes where possible

[semanticdiff-com]

Review changes with  

[XyneSpaces]

Review Summary

PR: #1648 - feat(a11y): keyboard navigation and focus management

Findings

1. Good: New FocusHooks.res provides reusable focus management primitives (useFocusTrap, useEscapeKey, useReturnFocus).

2. Good: Accordion component implements roving tabindex pattern with proper ArrowUp/ArrowDown keyboard navigation.

3. Good: Modal component includes role="dialog", ariaModal={true}, and ariaLabel for proper screen reader announcement.

4. Issue: The focusableSelector in AccessibilityUtils.res uses a hardcoded CSS selector string:

   let focusableSelector = "button, [href], input, select, textarea, [tabindex]:not([tabindex='-1'])"

   Suggestion: Consider also including audio[controls], video[controls], and [contenteditable] elements for completeness per WCAG guidelines.

5. Good: Locale strings for closeLabel, dialogLabel, and paymentMethodsGroupLabel are properly added across locale files.

No blocking issues. The implementation follows ARIA authoring practices for keyboard navigation.

[XyneSpaces]

⚠️ Verify postMessage origin validation in focus delegation

The keyboard navigation and focus management PR introduces cross-iframe communication. Ensure any postMessage calls for focus delegation validate the target origin — do not use "*" as targetOrigin.

Flag any instances of:

Window.postMessage(message, "*")

Use GlobalVars.hyperSwitchSdkUrl or a whitelist of allowed origins instead.

[XyneSpaces]

⚠️ New focus management hook missing error boundaries

The new UseFocusManager.res hook manages DOM focus and keyboard navigation. If any of the ref callbacks or focus calls fail (e.g., element removed from DOM between render and effect), the error is unhandled. Consider wrapping focus attempts in try/catch and logging failures, or document the invariant that refs are always valid when focus is called.

Also verify this hook is compatible with React 18's concurrent features — synchronous focus management during render can cause issues with time-slicing.

[aritro2002]

Suggested change

	}, [enabled])
	}, (enabled, onEscape))

[aritro2002]

check if locale support is working in modal flows or not.

[aritro2002]

we have same in cardUtils.res