Addon Docs: Fix Primary and Controls blocks not rendering in custom MDX pages

[NYCU-Chung]

Closes #33829

What I did

Fixed <Primary /> and <Controls /> doc blocks silently not rendering in custom MDX documentation pages. This is a regression introduced in v10.2.0 by PR #32712.

Root cause: usePrimaryStory was changed to only return stories with the autodocs tag. In custom MDX docs pages, component stories don't carry this tag — and users cannot add it, because doing so triggers a separate error in StoryIndexGenerator ("You created a component docs page but also tagged the CSF file with 'autodocs'"). This creates a catch-22 where neither option works.

Fix: Added a two-stage lookup in usePrimaryStory:

1. First, find a story with autodocs tag (preserves autodocs behavior and the original fix from Addon Docs: Skip !autodocs stories when computing primary story #32712 for [Bug]: !autodocs does not hide the preview of the story in the documentation if it is the first story #32683)
2. If none found, fall back to the first story without an explicit !autodocs tag (restores custom MDX page 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

1. Run a sandbox: yarn task --task sandbox --start-from auto --template react-vite/default-ts
2. Create a custom MDX docs page that references a component's stories using <Meta of={ComponentStories} />
3. Add <Primary /> and <Controls /> blocks
4. Verify they render correctly (before this fix, they silently show nothing)
5. Verify that autodocs pages still work correctly (no regression)

Documentation

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

Summary by CodeRabbit

• Bug Fixes
  • Improved primary story selection logic in auto-generated documentation to better handle fallback scenarios when preferred stories are unavailable.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 53c73821-79a6-4b38-b018-c1e265ac7388

📥 Commits

Reviewing files that changed from the base of the PR and between ad5c2a9 and 3951dd5.

📒 Files selected for processing (2)

• code/addons/docs/src/blocks/blocks/usePrimaryStory.test.tsx
• code/addons/docs/src/blocks/blocks/usePrimaryStory.ts

---

📝 Walkthrough

Walkthrough

Updated the story selection logic in usePrimaryStory to prioritize stories tagged with autodocs, and fall back to the first story without the !autodocs negation tag when no autodocs-tagged stories exist. Test expectations were updated to reflect this new fallback behavior.

Changes

Cohort / File(s)	Summary
usePrimaryStory Hook Updates code/addons/docs/src/blocks/blocks/usePrimaryStory.ts, code/addons/docs/src/blocks/blocks/usePrimaryStory.test.tsx	Modified story selection preference to first check for Tag.AUTODOCS-tagged stories, then fall back to the first story without !autodocs tag. Updated test assertions to expect fallback behavior and added test case for scenario where all stories have the !autodocs tag.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• #32712: Touches the same usePrimaryStory hook and !autodocs tag skipping logic; this PR refines the fallback behavior when no autodocs-tagged stories are available.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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