feat(web): introduce stability overview

Author: AugustinMauroy

src/generators/jsx-ast/generate.mjs

@@ -16,7 +16,11 @@ const remarkRecma = getRemarkRecma();
  *
  * @type {import('./types').Generator['processChunk']}
  */
-export async function processChunk(slicedInput, itemIndices, docPages) {
+export async function processChunk(
+  slicedInput,
+  itemIndices,
+  { docPages, stabilityOverviewEntries }
+) {
   const results = [];
 
   for (const idx of itemIndices) {
@@ -28,7 +32,8 @@ export async function processChunk(slicedInput, itemIndices, docPages) {
       entries,
       head,
       sideBarProps,
-      remarkRecma
+      remarkRecma,
+      stabilityOverviewEntries
     );
 
     results.push(content);
@@ -54,14 +59,30 @@ export async function* generate(input, worker) {
     ? config.index.map(({ section, api }) => [section, `${api}.html`])
     : headNodes.map(node => [node.heading.data.name, `${node.api}.html`]);
 
+  // Pre-compute stability overview data once — avoid serialising full AST nodes to workers
+  const stabilityOverviewEntries = headNodes
+    .filter(node => node.stability?.children?.length)
+    .map(({ api, heading, stability }) => {
+      const [{ data }] = stability.children;
+      return {
+        api,
+        name: heading.data.name,
+        stabilityIndex: parseInt(data.index, 10),
+        stabilityDescription: data.description.split('. ')[0],
+      };
+    });
+
   // Create sliced input: each item contains head + its module's entries
   // This avoids sending all 4700+ entries to every worker
   const entries = headNodes.map(head => ({
     head,
     entries: groupedModules.get(head.api),
   }));
 
-  for await (const chunkResult of worker.stream(entries, entries, docPages)) {
+  for await (const chunkResult of worker.stream(entries, entries, {
+    docPages,
+    stabilityOverviewEntries,
+  })) {
     yield chunkResult;
   }
 }

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

@@ -253,7 +253,7 @@ export const transformHeadingNode = async (
  * @param {ApiDocMetadataEntry} entry - The API metadata entry to process
  * @param {import('unified').Processor} remark - The remark processor
  */
-export const processEntry = (entry, remark) => {
+export const processEntry = (entry, remark, stabilityOverviewEntries = []) => {
   // Deep copy content to avoid mutations on original
   const content = structuredClone(entry.content);
 
@@ -272,6 +272,18 @@ export const processEntry = (entry, remark) => {
     (node, idx, parent) => (parent.children[idx] = createPropertyTable(node))
   );
 
+  // Inject the stability overview table where the slot tag is present
+  if (
+    stabilityOverviewEntries.length &&
+    entry.tags.includes('STABILITY_OVERVIEW_SLOT_BEGIN')
+  ) {
+    content.children.push(
+      createJSXElement(JSX_IMPORTS.StabilityOverview.name, {
+        entries: stabilityOverviewEntries,
+      })
+    );
+  }
+
   return content;
 };
 
@@ -286,7 +298,8 @@ export const createDocumentLayout = (
   entries,
   sideBarProps,
   metaBarProps,
-  remark
+  remark,
+  stabilityOverviewEntries = []
 ) =>
   createTree('root', [
     createJSXElement(JSX_IMPORTS.NavBar.name),
@@ -302,7 +315,9 @@ export const createDocumentLayout = (
             createElement('br'),
             createElement(
               'main',
-              entries.map(entry => processEntry(entry, remark))
+              entries.map(entry =>
+                processEntry(entry, remark, stabilityOverviewEntries)
+              )
             ),
           ]),
           createJSXElement(JSX_IMPORTS.MetaBar.name, metaBarProps),
@@ -321,7 +336,13 @@ export const createDocumentLayout = (
  * @param {import('unified').Processor} remark - Remark processor instance for markdown processing
  * @returns {Promise<JSXContent>}
  */
-const buildContent = async (metadataEntries, head, sideBarProps, remark) => {
+const buildContent = async (
+  metadataEntries,
+  head,
+  sideBarProps,
+  remark,
+  stabilityOverviewEntries = []
+) => {
   // Build props for the MetaBar from head and entries
   const metaBarProps = buildMetaBarProps(head, metadataEntries);
 
@@ -330,7 +351,8 @@ const buildContent = async (metadataEntries, head, sideBarProps, remark) => {
     metadataEntries,
     sideBarProps,
     metaBarProps,
-    remark
+    remark,
+    stabilityOverviewEntries
   );
 
   // Run remark processor to transform AST (parse markdown, plugins, etc.)

src/generators/web/constants.mjs

@@ -86,6 +86,10 @@ export const JSX_IMPORTS = {
     name: 'ArrowUpRightIcon',
     source: '@heroicons/react/24/solid/ArrowUpRightIcon',
   },
+  StabilityOverview: {
+    name: 'StabilityOverview',
+    source: resolve(ROOT, './ui/components/StabilityOverview'),
+  },
 };
 
 /**

src/generators/web/generate.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import { readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 
@@ -35,6 +35,8 @@ export async function generate(input) {
 
   // Process all entries together (required for code-split bundles)
   if (config.output) {
+    await mkdir(config.output, { recursive: true });
+
     // Write HTML files
     for (const { html, api } of results) {
       await writeFile(join(config.output, `${api}.html`), html, 'utf-8');

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

@@ -0,0 +1,56 @@
+import Badge from '@node-core/ui-components/Common/Badge';
+
+import styles from './index.module.css';
+
+const STABILITY_KINDS = ['error', 'warning', 'success', 'info'];
+const STABILITY_TOOLTIPS = ['Deprecated', 'Experimental', 'Stable', 'Legacy'];
+
+/**
+ * @typedef StabilityOverviewEntry
+ * @property {string} api - The API identifier (basename, e.g. "fs")
+ * @property {string} name - The human-readable display name of the API module
+ * @property {number} stabilityIndex - The stability level index (0–3)
+ * @property {string} stabilityDescription - First sentence of the stability description
+ */
+
+/**
+ * Renders a table summarising the stability level of each API module.
+ *
+ * @param {{ entries: Array<StabilityOverviewEntry> }} props
+ */
+export default ({ entries = [] }) => {
+  if (!entries.length) {
+    return null;
+  }
+
+  return (
+    <table className={styles.table}>
+      <thead>
+        <tr>
+          <th>API</th>
+          <th>Stability</th>
+        </tr>
+      </thead>
+      <tbody>
+        {entries.map(({ api, name, stabilityIndex, stabilityDescription }) => (
+          <tr key={api}>
+            <td>
+              <a href={`${api}.html`}>{name}</a>
+            </td>
+            <td className={styles.stabilityCell}>
+              <Badge
+                kind={STABILITY_KINDS[stabilityIndex]}
+                data-tooltip={STABILITY_TOOLTIPS[stabilityIndex]}
+                aria-label={`Stability: ${STABILITY_TOOLTIPS[stabilityIndex]}`}
+              >
+                {stabilityIndex}
+              </Badge>
+
+              {` ${stabilityDescription}`}
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+};

src/generators/web/ui/components/StabilityOverview/index.module.css

@@ -0,0 +1,10 @@
+.table {
+  width: 100%;
+}
+
+.stabilityCell {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  flex-wrap: wrap;
+}