Core: Update getDocsUrl to add a default ref param and set guide as ref for links in the Guide

[ghengeveld]

What I did

Updated api.getDocsUrl (manager-api):

• Updated asset option to take a subpath string rather than a boolean, to avoid having to set subpath as well.
• Added ref option with 'ui' as default
• Generated URLs include this ref as query param (unless set to '')
• Refactored and added unit tests

Updated checklistData:

• All generated links now specify 'guide' as ref option.

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

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

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.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

• Refactor
  • Enhanced documentation URL generation to support reference tracking parameters, enabling better identification and organization of documentation resources. All documentation links, assets, and references throughout the application have been updated to utilize this improved URL structure. These changes improve how documentation sources are categorized and accessed.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the getDocsUrl API to change the asset option from boolean to string path-like values and introduced a new optional ref parameter for reference tracking. Updated corresponding tests and all documentation URL constructions throughout the codebase to use the new API signature with ref parameter.

Changes

Cohort / File(s)	Summary
API Definition code/core/src/manager-api/modules/versions.ts	Updated getDocsUrl interface: changed asset parameter type from boolean to string, added new optional ref?: string parameter. Implementation now includes default handling for subpath and ref ('ui'), and appends ref query parameter to generated URLs.
Test Updates code/core/src/manager-api/tests/versions.test.js	Introduced helper setVersions() to centralize version state setup. Updated test expectations to include ?ref=ui query parameter in documentation URLs. Added tests for custom ref values and asset/subpath URL generation using the new API.
Usage Updates code/core/src/shared/checklist-store/checklistData.tsx	Updated all getDocsUrl calls to include ref: 'guide' parameter. Replaced previous patterns combining subpath with renderer: true (and asset: true for images) with new combined forms that explicitly pass the ref parameter.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• API signature change: Verify the change from asset: boolean to asset: string doesn't break backward compatibility or introduce unexpected behavior in existing callers not yet updated.
• Default parameter handling: Confirm default values for subpath and ref are correctly applied in the getDocsUrl implementation.
• Test coverage: Ensure new test cases adequately cover the updated ref parameter behavior and custom ref values.
• Consistency across files: Verify all getDocsUrl invocations in checklistData.tsx use consistent ref parameter values ('guide') and match the new API expectations.

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c1faf97 and c95eee9.

📒 Files selected for processing (3)

• code/core/src/manager-api/modules/versions.ts (3 hunks)
• code/core/src/manager-api/tests/versions.test.js (8 hunks)
• code/core/src/shared/checklist-store/checklistData.tsx (35 hunks)

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-11-05T09:38:47.712Z

Learnt from: Sidnioulz
Repo: storybookjs/storybook PR: 32458
File: code/core/src/components/components/Select/Select.tsx:200-204
Timestamp: 2025-11-05T09:38:47.712Z
Learning: Repo: storybookjs/storybook — Guidance: Until Storybook 11 is released, do not suggest using React.useId anywhere (e.g., in code/core/src/components/components/Select/Select.tsx) to maintain compatibility with React 17 runtimes. Prefer advising: accept a caller-provided props.id and, if needed, generate a client-only fallback id to minimize SSR hydration issues — but avoid useId. Resume prompting for useId after Storybook 11.

Applied to files:

• code/core/src/shared/checklist-store/checklistData.tsx

📚 Learning: 2025-10-01T15:24:01.060Z

Learnt from: Sidnioulz
Repo: storybookjs/storybook PR: 32594
File: code/core/src/components/components/Popover/WithPopover.tsx:7-9
Timestamp: 2025-10-01T15:24:01.060Z
Learning: In the Storybook repository, "react-aria-components/patched-dist/*" (e.g., "react-aria-components/patched-dist/Dialog", "react-aria-components/patched-dist/Popover", "react-aria-components/patched-dist/Tooltip") are valid import paths created by a patch applied to the react-aria-components package. These imports should not be flagged as broken or invalid until a maintainer explicitly states they are no longer acceptable.

Applied to files:

• code/core/src/shared/checklist-store/checklistData.tsx

🧬 Code graph analysis (1)

code/core/src/manager-api/tests/versions.test.js (1)

code/core/src/manager-api/modules/versions.ts (1)

• init (74-192)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: daily
• GitHub Check: Core Unit Tests, windows-latest

🔇 Additional comments (9)

code/core/src/shared/checklist-store/checklistData.tsx (3)

199-257: LGTM! Consistent ref parameter additions.

The addition of ref: 'guide' to these documentation links is consistent with the PR objectives. The pattern correctly maintains the existing subpath and renderer parameters while adding the new tracking reference.

---

279-282: LGTM! Asset parameter correctly updated.

The asset parameter is now correctly used as a string path rather than a boolean. The new API automatically uses the asset value as the subpath (per line 104 in versions.ts), so explicitly passing subpath is no longer needed.

---

287-1245: LGTM! All documentation URL updates are consistent.

All remaining getDocsUrl calls consistently add the ref: 'guide' parameter. The changes are mechanical and correct, properly migrating to the new API signature throughout the checklist data.

code/core/src/manager-api/tests/versions.test.js (3)

51-81: LGTM! Well-structured test data and helper.

The version test data objects provide good coverage of different version scenarios (matching versions, patch/minor/major differences, prereleases). The setVersions helper consolidates repetitive state setup logic, making tests more maintainable.

---

154-215: LGTM! Tests correctly updated for default ref behavior.

All existing tests are properly updated to expect the ?ref=ui parameter in documentation URLs, which aligns with the default value specified in the implementation. The query parameter ordering (renderer before ref) correctly reflects the implementation logic.

---

217-252: LGTM! Excellent coverage of new functionality.

The new tests thoroughly cover:

1. Custom ref values (line 225-227): Correctly expects custom ref in URL
2. Empty ref (line 238): Correctly expects no ref parameter when explicitly set to empty string
3. Asset path (line 249-251): Correctly validates the new string-based asset parameter with versioned path

These tests ensure the implementation handles all intended use cases and edge cases.

code/core/src/manager-api/modules/versions.ts (3)

52-65: LGTM! Clear documentation and type signatures.

The JSDoc comments clearly explain the purpose of both the asset and ref parameters. The type change from asset?: boolean to asset?: string is well-aligned with the PR objectives to avoid separately setting subpath.

---

104-104: LGTM! Smart parameter defaults.

The default subpath = asset is elegant and eliminates the need to pass both parameters when using assets. The ref = 'ui' default provides sensible tracking for UI-initiated documentation access. Both defaults can be overridden when needed, providing flexibility.

---

140-142: LGTM! Correct query parameter handling.

The ref parameter logic correctly:

1. Skips appending when ref is empty string (falsy check)
2. Uses appropriate separator based on existing query parameters (? vs &)
3. Is positioned correctly in the URL construction sequence (after renderer, before hash)

This implementation aligns perfectly with the test expectations.

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit c95eee9

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	42s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-11-21 11:20:34 UTC