UI: Add renderAriaLabel and a context argument to renderLabel

[Sidnioulz]

Closes #

What I did

Part of the Sidebar 2.0 stack (#33422): extends the sidebar label-rendering API so labels can adapt to where they render and expose proper accessible names.

• sidebar.renderLabel receives a third context argument: { isMobile: boolean; location: 'sidebar' | 'bottom-bar' }. The parameter is typed optional, so existing two-argument consumers keep compiling; Storybook itself always passes it.
• New sidebar.renderAriaLabel option: the accessible counterpart, which must return a plain string. It feeds accessible names for entries and the mobile bottom bar's current-page announcement. Both callbacks are stamped onto every entry in the story hash and share the API_SidebarOptions types so the config and entry surfaces can't drift.
• The mobile bottom bar concatenates names into plain strings for its visible label and its screen-reader announcement, so a renderLabel returning a React element (the long-documented pattern) now falls back to the entry name instead of stringifying to [object Object] — and the announcement uses the aria chain. Merging every ref index moves behind a memo (it allocates an object as large as the whole sidebar and ran on every state-driven re-render).
• API_TestEntry.parent becomes required: a test entry is always nested under its story.
• Docs: option tables and the label-context table in features-and-behavior.mdx, the manager snippet, and a MIGRATION entry.

The new sidebar tree (#33422) consumes the same context for its rows; this PR wires the mobile bottom bar and the API surface so that consumption is a drop-in.

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

Caution

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

1. cd code && yarn storybook:ui — the internal manager.tsx config now sets both renderLabel and renderAriaLabel.
2. Inspect a sidebar group row: its accessible name (devtools accessibility pane) follows renderAriaLabel ("<type> <name>") while the visible label follows renderLabel.
3. Switch to a mobile viewport, open a story, and check the bottom bar shows the concatenated story path and announces "Current page: …" from the aria chain (sb-sr-only span).

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

• Declare whether manual QA will be needed for this PR during the next release, through qa:needed or qa:skip

• 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.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WSk2g5RrcpxacMMUTRv9HK

---

Generated by Claude Code

[storybook-app-bot]

Package Benchmarks

^{Commit: 7aee4ab, ran on 11 September 2026 at 13:19:45 UTC}

The following packages have significant changes to their size or dependencies:

storybook

	Before	After	Difference
Dependency count	74	74	0
Self size	21.67 MB	21.63 MB	🎉 -38 KB 🎉
Dependency size	31.22 MB	31.22 MB	0 B
Bundle Size Analyzer	Link	Link

@storybook/nextjs

	Before	After	Difference
Dependency count	447	536	🚨 +89 🚨
Self size	641 KB	640 KB	🎉 -682 B 🎉
Dependency size	61.23 MB	64.97 MB	🚨 +3.74 MB 🚨
Bundle Size Analyzer	Link	Link

@storybook/cli

	Before	After	Difference
Dependency count	180	180	0
Self size	883 KB	883 KB	🎉 -90 B 🎉
Dependency size	86.81 MB	86.77 MB	🎉 -38 KB 🎉
Bundle Size Analyzer	Link	Link

@storybook/codemod

	Before	After	Difference
Dependency count	173	173	0
Self size	44 KB	44 KB	0 B
Dependency size	85.29 MB	85.25 MB	🎉 -38 KB 🎉
Bundle Size Analyzer	Link	Link

create-storybook

	Before	After	Difference
Dependency count	75	75	0
Self size	1.07 MB	1.07 MB	0 B
Dependency size	52.89 MB	52.85 MB	🎉 -38 KB 🎉
Bundle Size Analyzer	node	node

[coderabbitai]

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

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Essentials

Run ID: 6f5fd3e1-e290-45a0-89b4-51eb9249525b

📥 Commits

Reviewing files that changed from the base of the PR and between 7c77dfc and 7aee4ab.

📒 Files selected for processing (1)

• docs/_snippets/storybook-manager-render-label-stories.md

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

Walkthrough

The sidebar API now supports renderAriaLabel and contextual renderLabel callbacks. Story entries propagate these callbacks. Mobile navigation uses full ARIA labels for announcements while keeping visible labels truncated.

Changes

Sidebar label rendering

Layer / File(s)	Summary
Label API and story index propagation code/core/src/types/modules/api.ts, code/core/src/types/modules/api-stories.ts, code/core/src/manager-api/lib/stories.ts	The sidebar API defines typed renderAriaLabel and contextual renderLabel callbacks. Generated story entries carry both callbacks.
Mobile label and announcement flow code/core/src/manager/components/mobile/navigation/MobileNavigation.tsx, code/.storybook/manager.tsx	Mobile navigation passes bottom-bar context to label rendering, separates visible and ARIA labels, and uses the full ARIA label for current-page announcements.
Documentation and snapshot updates code/core/src/manager-api/tests/stories.test.ts, MIGRATION.md, docs/_snippets/storybook-manager-render-label-stories.md, docs/configure/user-interface/features-and-behavior.mdx	Snapshots include renderAriaLabel. Documentation describes the callbacks, context values, and mobile bottom-bar behavior.

Sequence Diagram(s)

sequenceDiagram
  participant MobileNavigation
  participant SidebarCallbacks
  participant MobileBottomBarContent
  MobileNavigation->>SidebarCallbacks: Render label with bottom-bar context
  SidebarCallbacks-->>MobileNavigation: Return visible and ARIA labels
  MobileNavigation->>MobileBottomBarContent: Pass visible name and full ARIA label
  MobileBottomBarContent->>MobileBottomBarContent: Announce current page with ARIA label

Loading

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 7aee4

The documented sidebar label and announcement changes are consistent, with no remaining merge-blocking risk.

---

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