docs: link the successor inline in the deprecation callout - #2962
Merged
Conversation
The deprecation callout rendered the successor as a separate "Ersatz:" line below the notice text. Reading it meant parsing two sentences that say the same thing. The successor belongs in the sentence that names it. `deprecationNotice` is now rendered as MDX with the same component mapping the page content uses, so a Markdown link in the notice becomes a Flow `Link` and routes client-side. `replacedBy` loses its only consumer and goes away with `resolveReplacedBy` and `ReplacementLink`. Trade-off: `replacedBy` also validated its target at build time — an unknown component name failed the build. A hand-written href in the notice has no such guard. Accepted deliberately; the docs app validates no internal link anywhere today, so this adds no new class of breakage. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
Coverage Report for ./packages/components/
File CoverageNo changed files found. |
Contributor
🚀 Preview DeploymentPreview environments are ready:
Images:
|
There was a problem hiding this comment.
Pull request overview
This PR refactors how deprecated component pages in apps/docs render their deprecation notice so the successor component can be linked inline (Markdown/MDX), and removes the now-redundant replacedBy frontmatter + resolver.
Changes:
- Compile
deprecationNoticefrontmatter to anMDXRemoteSerializeResulton the server and render it in the client-side status callout viaMDXRemote+createCustomComponents(). - Remove
replacedByfrontmatter and its build-time resolver (resolveReplacedBy/ReplacementLink) since the successor link now lives in the notice text. - Update the deprecated component pages (Align, SegmentedControl) to link successors inline.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| apps/docs/src/lib/mdx/MdxFile.ts | Updates frontmatter docs for deprecationNotice (now Markdown) and removes replacedBy metadata. |
| apps/docs/src/lib/componentStatus/replacedBy.ts | Deletes the replacedBy resolver and related types. |
| apps/docs/src/lib/componentStatus/index.ts | Re-exports the new deprecation notice serializer instead of replacedBy utilities. |
| apps/docs/src/lib/componentStatus/deprecationNotice.ts | Adds server-side serialization for Markdown/MDX deprecation notices. |
| apps/docs/src/lib/componentStatus/ComponentStatusCallout.tsx | Renders the serialized notice via MDXRemote using the shared MDX custom components. |
| apps/docs/src/content/04-components/structure/align/index.mdx | Converts deprecation notice to include an inline successor link; removes replacedBy. |
| apps/docs/src/content/04-components/form-controls/segmented-control/index.mdx | Converts deprecation notice to include inline successor links; removes replacedBy. |
| apps/docs/src/app/_components/layout/ComponentContent/ComponentContent.tsx | Serializes deprecationNotice server-side and stops resolving/passing replacedBy. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…styling Two review findings on the MDX notice: `deprecationNotice:` with nothing behind it is YAML `null`, and an empty string is a string — both passed the `=== undefined` check and reached `serialize()`, so the callout rendered an empty body instead of the generic fallback sentence. Blank copy now resolves to `undefined`. The page-body MDX mapping caps paragraphs at `--max-text-width` (960px), the article column's measure. Reusing it wholesale applied that cap inside the callout, wrapping the notice narrower than the alert it sits in. `p` is now overridden to a plain `Text` so the callout's layout no longer depends on page-body styling; the link and inline-code mapping stays shared. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Lisa18289
approved these changes
Aug 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The deprecation callout rendered the successor component as a separate
Ersatz:line below the notice text:Two lines saying the same thing. The successor belongs in the sentence that
names it:
deprecationNoticefrontmatter is now Markdown.ComponentContentserializesit server-side (
serialize()withremarkGfm, same options as the pagecontent) and
ComponentStatusCalloutrenders it withMDXRemoteandcreateCustomComponents()— so a link in the notice becomes a FlowLink inlineinside a
RouterProviderand routes client-side, exactly like a link in thebody.
replacedByloses its only consumer and goes away, together withresolveReplacedByandReplacementLink.Affects the two deprecated component pages: Align and SegmentedControl.
Trade-off a reviewer should weigh
replacedBywas not just the href source — it validated the target at buildtime, and an unknown component name failed the build. A hand-written href in
the notice has no such guard. This was an explicit call: the docs app validates
no internal link anywhere today (five are already dead), so it adds no new class
of breakage. A content-wide link check would be the real fix, and is its own
change.
Verification
tsc --noEmitand ESLint clean. Checked both pages in the dev server: thenotice renders as one line with the successors inline, no console errors, and
clicking the link navigates.
apps/docshas no test suite.Base branch & title
docs:→ basemain. Docs-only, so the merge publishes nothing.Checklist
pnpm lintis clean (0 errors; the 119selector-max-typewarnings arepre-existing) and
pnpm affected:testruns no tasks —apps/docshas notest targets
de-DEanden-USlocale files(n/a — docs content, not component UI text)
updated snapshots / the
update-screenshotslabel (n/a — no componentrenders changed)