A11y: Ensure popover dialogs have an ARIA label by gayanMatch · Pull Request #33500 · storybookjs/storybook

gayanMatch · 2026-01-09T17:51:55Z

Closes #33494

What I did

Added accessibility improvements to PopoverProvider component:

Added ariaLabel prop that provides an accessible label for the popover dialog, announced by screen readers when the popover opens
Added deprecation warning when ariaLabel is not provided (will become mandatory in Storybook 11)
Automatically injects aria-haspopup="dialog" to trigger elements, informing assistive technology that the button opens a dialog
Updated all existing PopoverProvider usages in the codebase with appropriate aria labels
Updated MIGRATION.md with documentation for the new prop and behavior

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

stories
unit tests
integration tests
end-to-end tests

Manual testing

Run yarn storybook:ui in the code directory
Navigate to Overlay/PopoverProvider stories
Open browser DevTools and inspect a trigger button
Verify aria-haspopup="dialog" is present on the trigger
Click the trigger to open the popover
Verify aria-expanded="true" appears on the trigger when open
Inspect the popover element and verify aria-label is set

Documentation

Add or update documentation reflecting your changes
If you are deprecating/removing a feature, make sure to update
MIGRATION.MD

Checklist for Maintainers

When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts
Make sure this PR contains one of the labels below:
Available labels
- bug: Internal changes that fixes incorrect behavior.
- maintenance: User-facing maintenance tasks.
- dependencies: Upgrading (sometimes downgrading) dependencies.
- build: Internal-facing build tooling & test updates. Will not show up in release changelog.
- cleanup: Minor cleanup style change. Will not show up in release changelog.
- documentation: Documentation only changes. Will not show up in release changelog.
- feature request: Introducing a new feature.
- BREAKING CHANGE: Changes that break compatibility in some way with current major version.
- other: Changes that don't fit in the above categories.

Summary by CodeRabbit

New Features
- Popovers now support an ariaLabel for improved accessibility; many popovers and stories include example labels.
- Tooltip system reimplemented as TooltipProvider with a new triggerOnFocusOnly option and defaultVisible control.
Breaking Changes
- WithTooltip public API simplified: removed trigger, interactive, followCursor, closeOnOutsideClick, closeOnTriggerHidden, withArrows, strategy, mutationObserverOptions, hasChrome.

Contribution by Gittensor, see my contribution statistics at https://gittensor.io/miners/details?githubId=132382032

coderabbitai · 2026-01-09T17:55:47Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds an optional ariaLabel prop to PopoverProvider (emits a deprecation notice when omitted), injects aria-haspopup="dialog" on trigger children, forwards aria-label to the upstream popover, updates many PopoverProvider call sites with contextual ariaLabel values, removes a manual aria-haspopup in TagsFilter, and documents WithTooltip → TooltipProvider API changes in MIGRATION.md.

Changes

Cohort / File(s)	Summary
PopoverProvider core `code/core/src/components/components/Popover/PopoverProvider.tsx`, `code/core/src/components/components/Popover/PopoverProvider.stories.tsx`	Add optional `ariaLabel?: string` prop; emit deprecation notice when missing; clone trigger child to add `aria-haspopup="dialog"`; forward `aria-label` to upstream Popover and set upstream container outline to `none`; story meta adds `ariaLabel` arg.
Migration / Tooltip API docs `MIGRATION.md`	Document migration from `WithTooltip` → `TooltipProvider`: rename `startOpen` → `defaultVisible`, add `triggerOnFocusOnly`, and list removed props (`trigger`, `svg`, `strategy`, `withArrows`, `mutationObserverOptions`, `hasChrome`, `closeOnTriggerHidden`, `followCursor`, `closeOnOutsideClick`, `interactive`).
Docs & controls `code/addons/docs/src/blocks/components/ArgsTable/ArgValue.tsx`, `code/addons/docs/src/blocks/controls/Color.tsx`	Add contextual `ariaLabel` values to `PopoverProvider` usages (e.g., `"Arg value details"`, `"Color picker"`).
Manager sidebar components `code/core/src/manager/components/sidebar/...` `code/core/src/manager/components/sidebar/Menu.tsx`, `.../ContextMenu.tsx`, `.../ChecklistWidget.tsx`, `.../RefBlocks.tsx`, `.../RefIndicator.tsx`, `.../TagsFilter.tsx`	Add descriptive `ariaLabel` strings to multiple `PopoverProvider` usages (e.g., `"Storybook menu"`, `"Context menu"`, `"Onboarding guide menu"`, `"Error details"`, `"Composed Storybook status"`) and remove a manual `aria-haspopup` from the TagsFilter toggle.
Manager preview, stories & tabs `code/core/src/manager/components/preview/tools/share.tsx`, `code/core/src/manager/container/Menu.stories.tsx`, `code/core/src/components/components/Tabs/Tabs.hooks.tsx`, `code/core/src/components/components/tooltip/TooltipMessage.stories.tsx`	Add `ariaLabel` to various `PopoverProvider` usages in stories and UI (e.g., `"Share this story"`, `"Menu"`, `"Additional tabs"`, `"Tooltip message"`).

Sequence Diagram(s)

(omitted — changes are accessibility additions and documentation updates without a multi-component control flow requiring sequence visualization)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Docs-Blocks: Fix broken tooltip in ArgValue details #33264 — Direct overlap on PopoverProvider internals and ArgValue usage updates.
Core: Minor UI fixes #33218 — Touches similar Popover/tooltip accessibility surface and ARIA propagation adjustments.
Core: Significantly improve Storybook's own accessibility #32458 — Related refactor of PopoverProvider/TooltipProvider and ARIA-label handling.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (3)

MIGRATION.md (1)

630-643: Add a brief note about trigger prop-forwarding + consider adding these new subsections to the TOC

The “Automatic aria-haspopup” behavior (Line 642) will only work if the trigger element ultimately renders a DOM element that receives aria-* props (not just a forwarded ref). Consider a short note like: “If you use a custom trigger component, ensure it forwards aria-* props to the underlying DOM element.”

For discoverability/consistency with nearby sections, consider adding TOC entries for:

“Added: ariaLabel”

“Automatic aria-haspopup”

code/core/src/manager/components/sidebar/TagsFilter.tsx (1)

215-215: LGTM! Accessibility label added correctly.

The ariaLabel="Tag filters" provides an accessible name for the popover dialog. The PopoverProvider will now automatically inject aria-haspopup="dialog" on the trigger button.

💡 Optional: Consider differentiating the button and dialog labels

Both the trigger button (line 238) and the popover dialog use the same label "Tag filters". While functional, slightly different labels could provide clearer context:

Button: "Tag filters" (what the button does)

Popover: "Filter options" or "Tag filter panel" (what the dialog contains)

This is a minor refinement and the current implementation is acceptable.

code/core/src/components/components/Popover/PopoverProvider.tsx (1)

105-111: Consider removing the Pressable wrapper.

DialogTrigger from react-aria-components already manages trigger interactions and dialog state. Since all PopoverProvider children are interactive elements (Button, SidebarToggleButton, etc.) that forwarding refs correctly, the additional Pressable wrapper adds unnecessary indirection and may cause double-wrapping of press handlers. DialogTrigger should handle press interactions directly without needing an explicit Pressable wrapper around the child trigger.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9511a9c and f2c5ecf.

📒 Files selected for processing (15)

MIGRATION.md
code/addons/docs/src/blocks/components/ArgsTable/ArgValue.tsx
code/addons/docs/src/blocks/controls/Color.tsx
code/core/src/components/components/Popover/PopoverProvider.stories.tsx
code/core/src/components/components/Popover/PopoverProvider.tsx
code/core/src/components/components/Tabs/Tabs.hooks.tsx
code/core/src/components/components/tooltip/TooltipMessage.stories.tsx
code/core/src/manager/components/preview/tools/share.tsx
code/core/src/manager/components/sidebar/ChecklistWidget.tsx
code/core/src/manager/components/sidebar/ContextMenu.tsx
code/core/src/manager/components/sidebar/Menu.tsx
code/core/src/manager/components/sidebar/RefBlocks.tsx
code/core/src/manager/components/sidebar/RefIndicator.tsx
code/core/src/manager/components/sidebar/TagsFilter.tsx
code/core/src/manager/container/Menu.stories.tsx

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{js,jsx,ts,tsx,json,md,html,css,scss}