docs(guides): add troubleshooting for SSR, portals, and focus

[kotAPI]

Summary

• Adds a troubleshooting guide covering hydration mismatches, portal containers, focus restoration, focus traps, overlay flashes, and scroll locking.
• Links the guide from SSR docs and the guides navigation.

Closes #1841.

Test plan

• Docs page follows existing guide structure.
• Verify the page renders at /docs/guides/troubleshooting.

Made with Cursor

Summary by CodeRabbit

• Documentation
  • Added a Troubleshooting guide accessible from the main Guides navigation and linked from the SSR integration guide. It covers hydration mismatches, portal container issues, focus restoration and focus-trap problems, overlays flashing or failing on first paint, and scroll-lock side effects. The guide also explains when and how to open an issue with reproduction details and environment versions.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0e738a7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4e5267dd-4f7a-4216-a369-8fca35fbc55e

📥 Commits

Reviewing files that changed from the base of the PR and between 2f63b63 and 0e738a7.

📒 Files selected for processing (1)

• docs/app/docs/docsNavigationSections.tsx

✅ Files skipped from review due to trivial changes (1)

• docs/app/docs/docsNavigationSections.tsx

---

📝 Walkthrough

Walkthrough

Adds a new Troubleshooting guide (MDX) covering SSR/portal/focus/overlay/scroll-lock issues, plus page wiring and SEO metadata; registers the guide in docs navigation and cross-links it from the SSR-and-no-JS fallback guide.

Changes

Troubleshooting Guide Content and Wiring

Layer / File(s)	Summary
Troubleshooting guide content, page wiring, and SEO metadata docs/app/docs/guides/troubleshooting/content.mdx, docs/app/docs/guides/troubleshooting/page.tsx, docs/app/docs/guides/troubleshooting/seo.ts	New guide covers hydration mismatches, portal container issues, focus restoration and trapping, overlay first-paint problems, and scroll-lock side effects. Page factory wires the MDX content and exports SEO metadata with title and description.
Navigation entry and cross-reference from SSR guide docs/app/docs/docsNavigationSections.tsx, docs/app/docs/guides/ssr-and-no-js-fallback/content.mdx	Adds a "Troubleshooting" item under Guides in the docs navigation and inserts a link to the Troubleshooting guide from the SSR-and-no-JS fallback guide.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• rad-ui/ui#1882: Related edits extending the Guides navigation structure where this new entry is added.
• rad-ui/ui#1064: Related SEO metadata generation utilities used by the new troubleshooting page.

Suggested labels

codex

Poem

🐰 A rabbit peeks through docs tonight,
Troubleshooting tips tucked soft and light.
Portals, focus, hydration too —
A hop of fixes just for you.
May readers find the answers right.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main change—adding a troubleshooting guide for SSR, portals, and focus issues—matching the primary objectives.
Linked Issues check	✅ Passed	The PR comprehensively addresses all coding objectives from issue #1841: troubleshooting documentation covering SSR/hydration, portals, and focus; framework-specific guidance; practical fixes; and integration with navigation and relevant docs.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to creating the troubleshooting guide and integrating it into navigation and existing docs, with no unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-1841-troubleshooting-guide

---

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

[github-actions]

Coverage

This report compares the PR with the base branch. "Δ" shows how the PR affects each metric.

Metric	PR	Δ
Statements	75.73%	+0.00%
Branches	59.17%	+0.00%
Functions	61.75%	+0.00%
Lines	77.26%	+0.00%

Coverage improved or stayed the same. Great job!

Run npm run coverage:ci locally for detailed reports and target untested areas to raise these numbers.