fix: return focus to legend item on Tab when tooltip is visible by albadra2 · Pull Request #217 · cloudscape-design/chart-components

albadra2 · 2026-05-06T15:18:19Z

Description

When a chart legend tooltip is visible and the user presses Tab, focus falls to <body> instead of returning to the legend item that triggered the tooltip. This is a WCAG 2.4.3 (Focus Order) violation.

This revision implements the approach suggested in review: an unconditional dismiss button with invisible tab-trap elements to forward focus into the tooltip, rather than capturing Tab keypresses.

Changes

1. Unconditional dismiss button.

The tooltip now always renders a dismiss (X) button — both on hover and on keyboard focus. This engages the popover's built-in focus trap unconditionally, so Tab always cycles through the tooltip's interactive content. Activating the dismiss button (Enter/Space) closes the tooltip and returns focus to the legend item.

2. Invisible tab-trap <div tabIndex={0}> elements.

Two invisible focusable elements are rendered — one before and one after the tooltip (inside a wrapper div). The entry trap forwards focus into the tooltip when tabbing from the legend; the exit trap cycles focus back to the dismiss button when tabbing past the tooltip's last element. This replaces the need for a custom onBlur focus-return and works consistently across browsers.

3. Tightened <SingleTabStopNavigationProvider> scope.

Previously, <SingleTabStopNavigationProvider> wrapped both the legend item list AND the tooltip. Because Cloudscape's Button, Link, and other interactive components consume useSingleTabStopNavigation from the context, every focusable element inside the tooltip received tabindex="-1" — making them keyboard-unreachable.

The provider now wraps only the legend item list:

<div role="toolbar">
  <SingleTabStopNavigationProvider>
    {legend items}
  </SingleTabStopNavigationProvider>
  {tab trap}
  {tooltip}
</div>

This aligns with the pattern used by Cloudscape's other navigable components — Tabs (tab-header-bar.tsx), NavigableGroup, TreeView, and Table all scope <SingleTabStopNavigationProvider> to the navigable region only.

Behavior

Action	Result
Hover legend item	Tooltip appears with dismiss button
Tab to legend item	Tooltip appears with dismiss button; focus stays on legend item
Tab again	Focus forwards to dismiss button via tab trap
Tab	Cycles through tooltip's interactive content
Enter/Space on dismiss	Tooltip closes, focus returns to the legend item
Escape	Tooltip closes, focus returns to the legend item
Arrow keys on legend	Move between legend items; tooltip follows

Implementation note

Uses disableDismissAutoFocus={true} (added in cloudscape-design/components#4510) to prevent the tooltip's built-in FocusLock from stealing focus from the legend item on mount.

Tab traps use getAllFocusables(tooltipRef.current)[1] rather than [0] because index 0 is FocusLock's internal leading TabTrap — focusing it would trigger focusLast instead of targeting the dismiss button.

Related links, issue #, if available: Blocking accessibility compliance reports (ACRs):

How has this been tested?

Manually tested in CloudWatch Console on the pages where the issue was originally reported.
Manually tested in chart-components's own dev pages (pages/03-core/core-legend.page.tsx) using npm start.
Verified: Tab on legend item → tooltip appears with dismiss button → Tab → focus forwards to dismiss button → Tab cycles through interactive content.
Verified: Activating dismiss button closes tooltip and returns focus to legend item.
Verified: Escape closes tooltip and returns focus to legend item.
Verified: Arrow key navigation between legend items still works.
Verified: Mouse hover shows tooltip with dismiss button (unconditional).
Verified: Tooltip content elements no longer have tabindex="-1" after provider restructure.

Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

Changes include appropriate documentation updates. N/A — no public API change.
Changes are backward-compatible if not indicated, see CONTRIBUTING.md. ✓ Backward-compatible. Tooltip interactive content is now keyboard-reachable — a strict accessibility improvement.
Changes do not include unsupported browser features, see CONTRIBUTING.md. ✓ Uses existing toolkit utilities (KeyCode, SingleTabStopNavigationProvider).
Changes were manually tested for accessibility, see accessibility guidelines. ✓ Tested with keyboard-only navigation in both Cloudscape's dev environment and CloudWatch Console.

Security

If the code handles URLs: all URLs are validated through the checkSafeUrl function. N/A — no URL handling.

Testing

Changes are covered with new/existing unit tests? Existing tests cover the Escape path. Happy to add tests for the tab-trap focus forwarding and the provider restructure regression guard.
Changes are covered with new/existing integration tests? Manually tested in both CloudWatch Console and chart-components's npm start dev environment.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

…abStopNavigationProvider scope

pan-kot · 2026-05-08T17:50:21Z


  function onKeyDown(event: React.KeyboardEvent<HTMLElement>) {
+    if (event.keyCode === KeyCode.tab && !event.shiftKey && tooltipRef.current) {
+      if (focusFirstInteractiveInTooltip(tooltipRef.current)) {


Can we avoid capturing the tab keypress? This impl depends on the component types and might work inconsistently across browsers.

I recommend trying an alternative approach: when a legend item is focused (and also when hovered - why not? - we can generalise it for when it is highlighted and tooltip exists), we can render an invisible <div tabIndex={0} /> - to capture the Tab press and forward it to the tooltip. The tooltip content can be wrapped in a focus lock, that already support auto-focus. We can consider adding this component to the toolkit, or else an similar implementation can be used - utilising getAllFocusables to find the first focusable element in the tooltip, or maybe better just focusing the dismissButtonRef.current.focus() - provided the dismiss button is always there.

feedback

pan-kot · 2026-05-12T07:09:32Z

Good work, @albadra2 - the UX changes to the legend tooltip significantly improve UX and accessibility of the legend item tooltips!

pan-kot · 2026-05-12T07:16:27Z

+          onMouseLeave={() => hideTooltip()}
+          onBlur={(event) => {
+            const trigger = elementsByIdRef.current[tooltipTarget.id];
+            if (focusStaysInTooltipScope(event.relatedTarget, tooltipRef.current, trigger)) {


Can we use exit tab trap instead? There is already a tab trap (an invisible element with tabIndex=0) before the tooltip - we can also add one after it, so that every time it gets focused - the focus is goes to back to the dismiss button.

pan-kot · 2026-05-12T07:19:01Z

+        <div
+          ref={tabTrapRef}
+          tabIndex={0}
+          onFocus={() => tooltipRef.current?.querySelector<HTMLElement>("button")?.focus()}


Let's use getAllFocusables()[0]?.focus() instead - to make the code better general and better readable at the same time.

pan-kot · 2026-05-12T07:19:53Z

+          ref={tabTrapRef}
+          tabIndex={0}
+          onFocus={() => tooltipRef.current?.querySelector<HTMLElement>("button")?.focus()}
+          style={{ position: "absolute", width: 0, height: 0, overflow: "hidden" }}


why are these styles needed?

pan-kot · 2026-05-12T07:22:19Z


-    // Hide tooltip and clear highlight unless focus moves inside tooltip;
-    if (tooltipRef.current && event.relatedTarget && !tooltipRef.current.contains(event.relatedTarget)) {
+    // Hide tooltip and clear highlight unless focus moves inside tooltip or to the tab trap;


Can we wrap the tooltip and its tab traps in a div and check that div instead?

<div ref={tooltipWrapperRef}> <div tabIndex={0} /> <Tooltip ... /> <div tabIndex={0} /> </div>

pan-kot · 2026-05-12T07:36:09Z

+  // Remove this once InternalChartTooltip supports a `disableAutoFocus` prop.
+  useEffect(() => {
+    if (tooltipItemId) {
+      elementsByIdRef.current[tooltipItemId]?.focus({ preventScroll: true });


This is shaky as the auto-focus can theoretically happen after we re-focus the item (e.g. in certain browsers). Also, some screen-readers might be quick enough to announce the dismiss button if it was focused for a split-second before the focus was restored. A proper change, as per the comments, is to add the ability to disable the built-in auto-focus. Let's do it.

PR for the tooltip: cloudscape-design/components#4510

…bleDismissAutoFocus

pan-kot · 2026-05-15T08:54:05Z

+      </SingleTabStopNavigationProvider>
+      {tooltipContent && (
+        <div ref={tooltipWrapperRef}>
+          {/* [1] skips FocusLock's leading TabTrap to target the dismiss button. */}


This is a hack that we better avoid. Besides, we don't really need focus traps around the tooltip because tooltip itself has some. The only issue is that when the tooltip's first focus trap gets focused - the focus goes to the last element. I believe we can fix it in the tooltip itself - let me check it.

This should address it: cloudscape-design/components#4518

pan-kot · 2026-05-15T09:25:08Z

            onMouseEnter={() => showTooltip(tooltipTarget.id)}
            onMouseLeave={() => hideTooltip()}
-            onBlur={() => hideTooltip()}
+            onBlur={(event) => {


Is this onBlur needed at all?

fix: return focus to legend item on Tab when tooltip is visible

3fa30a1

Copilot AI review requested due to automatic review settings May 6, 2026 15:18

albadra2 requested a review from a team as a code owner May 6, 2026 15:18

albadra2 requested review from cansuaa and removed request for a team May 6, 2026 15:18

Copilot started reviewing on behalf of albadra2 May 6, 2026 15:19 View session

albadra2 had a problem deploying to dev-pages May 7, 2026 09:18 — with GitHub Actions Failure

Replace Tab interception with dismiss-button approach and fix SingleT…

364bcc1

…abStopNavigationProvider scope

albadra2 had a problem deploying to dev-pages May 8, 2026 17:38 — with GitHub Actions Failure

pan-kot reviewed May 8, 2026

View reviewed changes

Rework: unconditional dismiss button with invisible tab trap per review

b0df621

feedback

pan-kot reviewed May 12, 2026

View reviewed changes

pan-kot mentioned this pull request May 12, 2026

chore: Adds disable dismiss auto-focis for internal chart tooltip cloudscape-design/components#4510

Merged

Address review feedback: replace Tab capture with tab traps, use disa…

00f75bf

…bleDismissAutoFocus

albadra2 had a problem deploying to dev-pages May 15, 2026 08:43 — with GitHub Actions Failure

pan-kot reviewed May 15, 2026

View reviewed changes

pan-kot mentioned this pull request May 15, 2026

fix: Focus lock uses correct direction when initial focus is outside the lock cloudscape-design/components#4518

Open

pan-kot reviewed May 15, 2026

View reviewed changes

Address review feedback: Remove onBlur

f11a1b8

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: return focus to legend item on Tab when tooltip is visible#217

fix: return focus to legend item on Tab when tooltip is visible#217
albadra2 wants to merge 5 commits into
cloudscape-design:mainfrom
albadra2:fix/legend-tooltip-focus-return

albadra2 commented May 6, 2026 •

edited

Loading

Uh oh!

pan-kot May 8, 2026

Uh oh!

pan-kot commented May 12, 2026

Uh oh!

pan-kot May 12, 2026

Uh oh!

pan-kot May 12, 2026

Uh oh!

pan-kot May 12, 2026

Uh oh!

pan-kot May 12, 2026

Uh oh!

pan-kot May 12, 2026

Uh oh!

pan-kot May 12, 2026

Uh oh!

pan-kot May 15, 2026 •

edited

Loading

Uh oh!

pan-kot May 15, 2026

Uh oh!

pan-kot May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

albadra2 commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Behavior

Implementation note

How has this been tested?

Correctness

Security

Testing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pan-kot commented May 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pan-kot May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

albadra2 commented May 6, 2026 •

edited

Loading

pan-kot May 15, 2026 •

edited

Loading