better sidebar gen

Author: avivkeller

src/generators/jsx/constants.mjs

@@ -1,18 +1,18 @@
-// Maps the the stability index (0-3) to the level used by @node-core/ui-components
+// Maps Node.js API stability indices (0-3) to UI component stability levels.
 export const STABILITY_LEVELS = [
   'danger', // (0) Deprecated
   'warning', // (1) Experimental
   'success', // (2) Stable
   'info', // (3) Legacy
 ];
 
-// Maps HTML tags to corresponding component names in @node-core/ui-components
+// Maps HTML tags to corresponding component names in @node-core/ui-components.
 export const TAG_TRANSFORMS = {
   pre: 'CodeBox',
   blockquote: 'Blockquote',
 };
 
-// Maps types to icon symbols
+// Maps API heading types to their CircularIcon props.
 export const ICON_SYMBOL_MAP = {
   event: { symbol: 'E', color: 'red' },
   method: { symbol: 'M', color: 'red' },
@@ -23,6 +23,7 @@ export const ICON_SYMBOL_MAP = {
   ctor: { symbol: 'C', color: 'red' },
 };
 
+// Maps API lifecycle change type identifiers to their human-readable labels.
 export const CHANGE_TYPES = {
   added_in: 'Added in',
   deprecated_in: 'Deprecated in',

src/generators/jsx/index.mjs

@@ -1,11 +1,10 @@
 import {
-  coerceSemVer,
   getCompatibleVersions,
   groupNodesByModule,
 } from '../../utils/generators.mjs';
 import buildContent from './utils/buildContent.mjs';
 import { getRemarkRecma } from '../../utils/remark.mjs';
-import { major } from 'semver';
+import { buildSideBarDocPages } from './utils/buildBarProps.mjs';
 
 /**
  * This generator generates a JSX AST from an input MDAST
@@ -37,24 +36,19 @@ export default {
       .sort((a, b) => a.heading.data.name.localeCompare(b.heading.data.name));
 
     // Generate table of contents
-    const docPages = headNodes.map(node => [
-      node.heading.data.name,
-      `${node.api}.html`,
-    ]);
+    const docPages = buildSideBarDocPages(groupedModules, headNodes);
 
     // Process each head node and build content
     const results = await Promise.all(
       headNodes.map(entry => {
-        const coercedMajor = major(coerceSemVer(entry.introduced_in));
-        const otherVersions = getCompatibleVersions(
+        const versions = getCompatibleVersions(
           entry.introduced_in,
-          releases
-        ).filter(({ version }) => version.major != coercedMajor);
+          releases,
+          true
+        );
 
         const sideBarProps = {
-          otherVersions: otherVersions.map(
-            ({ version }) => `v${version.major}.x`
-          ),
+          versions: versions.map(({ version }) => `v${version.version}`),
           currentVersion: `v${version.version}`,
           currentPage: `${entry.api}.html`,
           docPages,

src/generators/jsx/utils/buildBarProps.mjs

@@ -0,0 +1,51 @@
+import readingTime from 'reading-time';
+import { DOC_API_BLOB_EDIT_BASE_URL } from '../../../constants.mjs';
+import { visit } from 'unist-util-visit';
+
+/**
+ * Builds sidebar navigation for API documentation pages
+ *
+ * @param {Map<string, Array<ApiDocMetadataEntry>>} groupedModules - Modules grouped by API
+ * @param {Array<ApiDocMetadataEntry>} headNodes - Main entry nodes for each API
+ */
+export const buildSideBarDocPages = (groupedModules, headNodes) =>
+  headNodes.map(node => {
+    const moduleEntries = groupedModules.get(node.api);
+
+    return {
+      title: node.heading.data.name,
+      doc: `${node.api}.html`,
+      headings: moduleEntries
+        .filter(entry => entry.heading?.data?.name && entry.heading.depth === 2)
+        .map(entry => [entry.heading.data.name, `#${entry.heading.data.slug}`]),
+    };
+  });
+
+/**
+ * Builds metadata for the sidebar and meta bar
+ *
+ * @param {ApiDocMetadataEntry} head - Main API metadata entry
+ * @param {Array<ApiDocMetadataEntry>} entries - All API metadata entries
+ */
+export function buildMetaBarProps(head, entries) {
+  // Extract text content for reading time calculation
+  let textContent = '';
+  entries.forEach(entry => {
+    visit(entry.content, ['text', 'code'], node => {
+      textContent += node.value || '';
+    });
+  });
+
+  return {
+    headings: entries
+      .filter(entry => entry.heading?.data?.name)
+      .map(entry => ({
+        depth: entry.heading.depth,
+        value: entry.heading.data.name,
+      })),
+    addedIn: head.introduced_in || head.added_in || '',
+    readingTime: readingTime(textContent).text,
+    viewAs: [['JSON', `${head.api}.json`]],
+    editThisPage: `${DOC_API_BLOB_EDIT_BASE_URL}${head.api}.md`,
+  };
+}

src/generators/jsx/utils/buildContent.mjs

@@ -11,12 +11,9 @@ import {
   STABILITY_LEVELS,
   CHANGE_TYPES,
 } from '../constants.mjs';
-import {
-  DOC_API_BLOB_EDIT_BASE_URL,
-  DOC_NODE_BLOB_BASE_URL,
-} from '../../../constants.mjs';
+import { DOC_NODE_BLOB_BASE_URL } from '../../../constants.mjs';
 import { enforceArray, sortChanges } from '../../../utils/generators.mjs';
-import readingTime from 'reading-time';
+import { buildMetaBarProps } from './buildBarProps.mjs';
 
 /**
  * Transforms a stability node into an AlertBox JSX element
@@ -151,50 +148,6 @@ function processEntry(entry) {
   return content;
 }
 
-/**
- * Collects text content from nodes for reading time calculation
- *
- * @param {Array<ApiDocMetadataEntry>} entries - The API metadata entries
- * @returns {string} Concatenated text content
- */
-function collectTextContent(entries) {
-  let text = '';
-  entries.forEach(entry => {
-    visit(entry.content, ['text', 'code'], node => {
-      text += node.value || '';
-    });
-  });
-  return text;
-}
-
-/**
- * Builds the metadata for the sidebar and meta bar
- *
- * @param {ApiDocMetadataEntry} head - The main API metadata entry
- * @param {Array<ApiDocMetadataEntry>} entries - The API metadata entries
- * @returns {Object} Props for meta bar including headings and reading time
- */
-function buildMetaBarProps(head, entries) {
-  // Extract headings in one pass
-  const headings = entries
-    .filter(({ heading }) => heading?.data?.name)
-    .map(({ heading }) => ({
-      depth: heading.depth,
-      value: heading.data.name,
-    }));
-
-  // Calculate reading time
-  const text = collectTextContent(entries);
-
-  return {
-    headings,
-    addedIn: head.introduced_in || head.added_in || '',
-    readingTime: readingTime(text).text,
-    viewAs: [['JSON', `${head.api}.json`]],
-    editThisPage: `${DOC_API_BLOB_EDIT_BASE_URL}${head.api}.md`,
-  };
-}
-
 /**
  * Creates the overall content structure with processed entries
  *

src/generators/jsx/utils/transformer.mjs

@@ -1,21 +1,13 @@
-/**
- * Imports the visit utility from unist-util-visit for traversing syntax trees.
- */
 import { visit } from 'unist-util-visit';
 import { TAG_TRANSFORMS } from '../constants.mjs';
 
 /**
- * Transforms elements in a syntax tree by replacing tag names according to a mapping.
- * Traverses the tree and replaces any element's tagName if it exists as a key in the tagMap.
+ * Transforms elements in a syntax tree by replacing tag names according to the mapping.
  *
  * @param {Object} tree - The abstract syntax tree to transform
  * @returns {Object} The transformed tree (modified in place)
- * @throws {ReferenceError} Will throw if 'tagMap' is not defined in scope
  */
 export default () => tree => {
-  // TODO(@avivkeller): Nodes like "Array<string>" return a "<string>" raw type,
-  //                    which Recma does not understand, so we make them text.
-
   visit(tree, 'raw', node => {
     node.type = 'text';
   });

src/utils/generators.mjs

@@ -59,10 +59,10 @@ export const coerceSemVer = version => {
  *
  * @param {string | import('semver').SemVer} introduced
  * @param {Array<Release>} releases
+ * @param {Boolean} [includeNonMajor=false]
  * @returns {Array<Release>}
  */
 export const getCompatibleVersions = (introduced, releases) => {
-  if (!introduced) return releases;
   const coercedMajor = major(coerceSemVer(introduced));
   // All Node.js versions that support the current API; If there's no "introduced_at" field,
   // we simply show all versions, as we cannot pinpoint the exact version