feat(`web`): introduce stability overview by AugustinMauroy · Pull Request #644 · nodejs/doc-kit

AugustinMauroy · 2026-03-05T09:15:45Z

Description

introduce stability overview on new web generator

Validation

It's should be cool 😎

Related Issues

Close #357

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format & node --run lint.
I've covered new added functionality with unit tests if necessary.

vercel · 2026-03-05T09:15:50Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Mar 5, 2026 9:44pm

codecov · 2026-03-05T09:16:33Z

Codecov Report

❌ Patch coverage is 75.40984% with 45 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.93%. Comparing base (acb4c34) to head (83203ee).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/generators/jsx-ast/generate.mjs	0.00%	24 Missing ⚠️
src/generators/jsx-ast/utils/buildContent.mjs	12.50%	21 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #644      +/-   ##
==========================================
+ Coverage   75.90%   75.93%   +0.02%     
==========================================
  Files         145      147       +2     
  Lines       13735    13910     +175     
  Branches      992     1001       +9     
==========================================
+ Hits        10426    10562     +136     
- Misses       3303     3342      +39     
  Partials        6        6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-03-05T09:17:55Z

`web` Generator

File	Base	Head	Diff
`documentation.html`	36.92 KB	50.38 KB	+13.46 KB (+36.44%)
`documentation.js`	9.74 KB	21.57 KB	+11.83 KB (+121.41%)
`styles.css`	137.01 KB	141.80 KB	+4.79 KB (+3.50%)
`index.js`	9.69 KB	9.70 KB	+15.00 B (+0.15%)
`embedding.js`	37.29 KB	37.30 KB	+5.00 B (+0.01%)
`intl.js`	37.08 KB	37.08 KB	+5.00 B (+0.01%)
`synopsis.js`	15.72 KB	15.72 KB	+5.00 B (+0.03%)

Copilot

Pull request overview

Introduces a “Stability Overview” table to the new web generator output, mirroring the legacy generator’s ability to render a stability summary on the “About”/documentation page when slot tags are present.

Changes:

Add StabilityOverview UI component (CSS + JSX) and register it in web JSX import mapping.
Precompute and pass stability overview entries through the jsx-ast generator pipeline, injecting the table when the slot tag is present.
Ensure the web generator creates the output directory before writing HTML/JS/CSS artifacts.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/generators/web/ui/components/StabilityOverview/index.module.css	Adds minimal layout styling for the stability overview table and badge cell.
src/generators/web/ui/components/StabilityOverview/index.jsx	Implements the stability overview table UI using `Badge` tooltips.
src/generators/web/generate.mjs	Creates `config.output` directory before emitting generated files.
src/generators/web/constants.mjs	Registers `StabilityOverview` in `JSX_IMPORTS` for bundling/import generation.
src/generators/jsx-ast/utils/buildContent.mjs	Threads stability overview entries through `processEntry` and injects the component when slot tags are present.
src/generators/jsx-ast/generate.mjs	Precomputes stability overview data once and passes it to workers via the `extra` stream context.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/generators/jsx-ast/utils/buildContent.mjs

src/generators/web/ui/components/StabilityOverview/index.jsx

src/generators/web/generate.mjs

avivkeller

I wonder if adding stability to the sidebar would be better?

AugustinMauroy · 2026-03-07T22:29:44Z

I wonder if adding stability to the sidebar would be better?

It's should be on toc ? it's already

ovflowd · 2026-03-08T02:13:26Z

I wonder if adding stability to the sidebar would be better?

It's should be on toc ? it's already

I wonder if Aviv meant completely being there or maybe always being there? Although that seems a discussion for another issue.

ovflowd · 2026-03-08T02:13:48Z

src/generators/jsx-ast/utils/buildStabilityOverview.mjs

+
+const STABILITY_KINDS = ['error', 'warning', 'default', 'info'];
+
+/**


nit: remove this empty doc

if we remove it es-lint ask for it but it's doesn't require any jsdoc

ovflowd · 2026-03-08T02:14:53Z

src/generators/jsx-ast/generate.mjs

+    .filter(node => node.stability?.children?.length)
+    .map(({ api, heading, stability }) => {
+      const [{ data }] = stability.children;
+      return {


Could this map fn be moved to a dedicated function and be unit tested? Thanks!

seem reasonable

ovflowd · 2026-03-08T02:15:01Z

src/generators/jsx-ast/generate.mjs


+  // Pre-compute stability overview data once — avoid serialising full AST nodes to workers
+  const stabilityOverviewEntries = headNodes
+    .filter(node => node.stability?.children?.length)


Suggested change

.filter(node => node.stability?.children?.length)

.filter(node => !!node.stability?.children?.length)

oh 🤓 that's smart

ovflowd · 2026-03-08T02:23:51Z

src/generators/jsx-ast/utils/buildContent.mjs

  );

+  // Inject the stability overview table where the slot tag is present
+  if (


I wonder how optimal this is... I wonder if a visit statement is better here, I also kinda dislike this method of inserting the stability index.

ovflowd

This method would make sense for legacy docs. For the new docs, this method isn't really acceptable. The stability overview must be a React component now for the web generator, and all that we must do here is replace the STABILITY_OVERVIEW_SLOT_BEGIN or IDK with a slot for the component.

This would also make it easier to maintain the component.

AugustinMauroy · 2026-03-08T09:43:56Z

This method would make sense for legacy docs. For the new docs, this method isn't really acceptable. The stability overview must be a React component now for the web generator, and all that we must do here is replace the STABILITY_OVERVIEW_SLOT_BEGIN or IDK with a slot for the component.

This would also make it easier to maintain the component.

i do that but aviv ask for AST approach #644 (comment)

So what should I do ?

feat(web): introduce stability overview

113fbbe

Copilot AI review requested due to automatic review settings March 5, 2026 09:15

AugustinMauroy requested a review from a team as a code owner March 5, 2026 09:15

Copilot started reviewing on behalf of AugustinMauroy March 5, 2026 09:16 View session

AugustinMauroy marked this pull request as draft March 5, 2026 09:22

Copilot AI reviewed Mar 5, 2026

View reviewed changes

src/generators/jsx-ast/utils/buildContent.mjs Outdated Show resolved Hide resolved

src/generators/jsx-ast/utils/buildContent.mjs Show resolved Hide resolved

src/generators/web/ui/components/StabilityOverview/index.jsx Outdated Show resolved Hide resolved

avivkeller reviewed Mar 5, 2026

View reviewed changes

src/generators/web/ui/components/StabilityOverview/index.jsx Outdated Show resolved Hide resolved

src/generators/web/generate.mjs Outdated Show resolved Hide resolved

Update generate.mjs

df3c7a5

vercel bot deployed to Preview March 5, 2026 20:55 View deployment

update

95229d1

vercel bot deployed to Preview March 5, 2026 21:33 View deployment

Create buildStabilityOverview.test.mjs

f2b9366

vercel bot deployed to Preview March 5, 2026 21:43 View deployment

Merge branch 'main' into augu-stability-overview-web

83203ee

AugustinMauroy marked this pull request as ready for review March 5, 2026 21:44

vercel bot deployed to Preview March 5, 2026 21:44 View deployment

avivkeller reviewed Mar 7, 2026

View reviewed changes

ovflowd reviewed Mar 8, 2026

View reviewed changes

ovflowd requested changes Mar 8, 2026

View reviewed changes


		const STABILITY_KINDS = ['error', 'warning', 'default', 'info'];

		/**

	.filter(node => node.stability?.children?.length)
	.filter(node => !!node.stability?.children?.length)

Conversation

AugustinMauroy commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Validation

Related Issues

Check List

Uh oh!

vercel bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

web Generator

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avivkeller left a comment

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ovflowd commented Mar 8, 2026

Uh oh!

ovflowd Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ovflowd left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy commented Mar 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AugustinMauroy commented Mar 5, 2026 •

edited

Loading

vercel bot commented Mar 5, 2026 •

edited

Loading

codecov bot commented Mar 5, 2026 •

edited

Loading

github-actions bot commented Mar 5, 2026 •

edited

Loading

`web` Generator

AugustinMauroy commented Mar 7, 2026 •

edited

Loading

ovflowd Mar 8, 2026 •

edited

Loading

ovflowd left a comment •

edited

Loading