Improve keyboard focus management for GlPopover component

Problem to solve

The GlPopover component does not currently shift keyboard focus into the popover content when it appears. When a user activates a popover trigger (via click or keyboard), focus remains on the trigger button rather than moving into the popover content. This creates accessibility barriers for keyboard and screen reader users who must perform additional tab actions to access popover content.

Intended users

Frontend developers using GitLab UI components and end-users relying on keyboard navigation or assistive technologies.

Proposal

Update the GlPopover component to:

  1. Move keyboard focus to the popover content (or its first focusable element) when opened
  2. Ensure the popover content appears next in the DOM order for proper keyboard navigation
  3. Implement focus trapping within the popover while it's open
  4. Return focus to the trigger element when the popover is closed

Implementation details

  • The component should follow the WAI-ARIA Authoring Practices for Dialog Modal pattern
  • Focus management should be handled using refs to track and manipulate focus state
  • Add event handlers to manage focus movement and trapping
  • Update component documentation to note the focus behavior

Use case in GitLab

This issue was identified in MR !184733 for the GitLab project where a "More topics" popover button was implemented in global search results. The current implementation does not shift focus into the popover when opened, creating a keyboard navigation barrier.

Evidence

Referenced in GitLab MR gitlab-org/gitlab!184733 (merged):

"issue: when the popover opens the focus should move into the popover. I'm not sure if this is a limitation of the current component" - @danmh

"I don't believe we move focus to the popover content [...] It probs should be next in DOM order to be selected with keyboard navigation if possible." - @sdejonge

Links / references