add layout, changehistory element

Author: avivkeller

package.json

@@ -44,6 +44,7 @@
     "acorn": "^8.14.1",
     "commander": "^13.1.0",
     "dedent": "^1.5.3",
+    "estree-util-value-to-estree": "^3.4.0",
     "estree-util-visit": "^2.0.0",
     "github-slugger": "^2.0.0",
     "glob": "^11.0.1",

pnpm-lock.yaml

@@ -1,34 +1,74 @@
 'use strict';
 
 import { u as createTree } from 'unist-builder';
+import { valueToEstree } from 'estree-util-value-to-estree';
 
 /**
- * Creates an MDX JSX element.
+ * Creates an MDX JSX element with support for complex attribute values.
  *
  * @param {string} name - The name of the JSX element
  * @param {{
  * inline?: boolean,
  * children?: string | import('unist').Node[],
- * [key: string]: string
+ * [key: string]: any
  * }} [options={}] - Options including type, children, and JSX attributes
  * @returns {import('unist').Node} The created MDX JSX element node
  */
 export const createJSXElement = (
   name,
   { inline = true, children = [], ...attributes } = {}
 ) => {
+  // Process children: convert string to text node or use array as is
   const processedChildren =
     typeof children === 'string'
       ? [createTree('text', { value: children })]
       : (children ?? []);
 
+  // Create attribute nodes, handling complex objects and primitive values differently
   const attrs = Object.entries(attributes).map(([key, value]) =>
-    createTree('mdxJsxAttribute', { name: key, value: String(value) })
+    createAttributeNode(key, value)
   );
 
+  // Create and return the appropriate JSX element type
   return createTree(inline ? 'mdxJsxTextElement' : 'mdxJsxFlowElement', {
     name,
     attributes: attrs,
     children: processedChildren,
   });
 };
+
+/**
+ * Creates an MDX JSX attribute node from the input.
+ *
+ * @param {string} name - The attribute name
+ * @param {any} value - The attribute value (can be any valid JS value)
+ * @returns {import('unist').Node} The MDX JSX attribute node
+ */
+function createAttributeNode(name, value) {
+  // For objects and arrays, create expression nodes to preserve structure
+  if (value !== null && typeof value === 'object') {
+    return createTree('mdxJsxAttribute', {
+      name,
+      value: createTree('mdxJsxAttributeValueExpression', {
+        data: {
+          estree: {
+            type: 'Program',
+            body: [
+              {
+                type: 'ExpressionStatement',
+                expression: valueToEstree(value),
+              },
+            ],
+            sourceType: 'module',
+          },
+        },
+      }),
+    });
+  }
+
+  // For primitives, use simple string conversion
+  return createTree('mdxJsxAttribute', {
+    name,
+    value: String(value),
+  });
+}

src/generators/jsx/utils/ast.mjs

@@ -1,15 +1,15 @@
 'use strict';
 
-// External dependencies
 import { h as createElement } from 'hastscript';
 import { u as createTree } from 'unist-builder';
 import { SKIP, visit } from 'unist-util-visit';
+import { rcompare } from 'semver';
 
-// Internal dependencies
-import createQueries from '../../../utils/queries/index.mjs';
+import { UNIST } from '../../../utils/queries/index.mjs';
 import { createJSXElement } from './ast.mjs';
 import { ICON_SYMBOL_MAP, STABILITY_LEVELS } from '../constants.mjs';
 import { DOC_NODE_BLOB_BASE_URL } from '../../../constants.mjs';
+import { enforceArray } from '../../../utils/generators.mjs';
 
 /**
  * Transforms a stability node into an AlertBox JSX element
@@ -28,28 +28,75 @@ function visitStabilityNode(node, index, parent) {
 }
 
 /**
- * Adds the metadata around the header node
+ * Builds a history of changes for an API element
  *
- * @param {ApiDocMetadataEntry} entry - The content object to process
- * @param {import('mdast').Heading} node - The stability node to transform
+ * @param {ApiDocMetadataEntry} entry - The metadata entry containing change information
+ */
+function buildChangeElement(entry) {
+  // Create change entries from version fields (added, deprecated, etc.)
+  const changeTypes = {
+    added_in: 'Added in',
+    deprecated_in: 'Deprecated in',
+    removed_in: 'Removed in',
+    introduced_in: 'Introduced in',
+  };
+
+  const history = Object.entries(changeTypes)
+    .filter(([field]) => entry[field])
+    .map(([field, label]) => {
+      const versions = enforceArray(entry[field]);
+      return {
+        versions,
+        label: `${label}: ${versions.join(', ')}`,
+      };
+    });
+
+  // Add explicit changes
+  if (entry.changes) {
+    const changesHistory = entry.changes.map(change => ({
+      versions: enforceArray(change.version),
+      label: change.description,
+      url: change['pr-url'],
+    }));
+    history.push(...changesHistory);
+  }
+
+  // Sort by version, newest first
+  return createJSXElement('ChangeHistory', {
+    changes: history.sort((a, b) => rcompare(a.versions[0], b.versions[0])),
+  });
+}
+
+/**
+ * Enhances a heading node with metadata, source links, and styling
+ *
+ * @param {ApiDocMetadataEntry} entry - The API metadata entry
+ * @param {import('mdast').Heading} node - The heading node to transform
  * @param {number} index - The index of the node in its parent's children array
- * @param {import('unist').Node} parent - The parent node containing the stability node
+ * @param {import('unist').Node} parent - The parent node containing the heading
  */
-function visitHeadingNode(entry, { data, children }, index, parent) {
-  console.error(data);
+function visitHeadingNode(entry, node, index, parent) {
+  const { data, children } = node;
+  const headerChildren = [
+    createElement(`h${data.depth + 1}`, [
+      createElement(`a.mark#${data.slug}`, { href: `#${data.slug}` }, children),
+    ]),
+  ];
+
   // Add type icon if available
   if (ICON_SYMBOL_MAP[data.type]) {
-    // TODO: This hasn't been implemented yet. This is an assumption of what a
-    // potential implementation could look like
-    children.unshift(
+    headerChildren.unshift(
       createJSXElement('CircularIcon', ICON_SYMBOL_MAP[data.type])
     );
   }
 
-  // Replace node with proper heading and anchor
-  parent.children[index] = createElement(`h${data.depth + 1}`, [
-    createElement(`a.mark#${data.slug}`, { href: `#${data.slug}` }, children),
-  ]);
+  const changeElement = buildChangeElement(entry);
+  if (changeElement) {
+    headerChildren.push(changeElement);
+  }
+
+  // Replace node with new heading and anchor
+  parent.children[index] = createElement('div', headerChildren);
 
   // Add source link if available
   if (entry.source_link) {
@@ -71,14 +118,13 @@ function visitHeadingNode(entry, { data, children }, index, parent) {
 }
 
 /**
- * Processes content by transforming stability nodes
+ * Processes an API documentation entry by applying transformations to its content
  *
- * @param {ApiDocMetadataEntry} entry - The entry
+ * @param {ApiDocMetadataEntry} entry - The API metadata entry to process
  */
 function process(entry) {
-  // Create a shallow copy to avoid modifying the original
+  // Create a deep copy to avoid modifying the original
   const content = structuredClone(entry.content);
-  const { UNIST } = createQueries;
 
   // Apply all transformations to the content
   visit(content, UNIST.isStabilityNode, visitStabilityNode);
@@ -92,10 +138,23 @@ function process(entry) {
 /**
  * Transforms API metadata entries into processed MDX content
  *
- * @param {Array<ApiDocMetadataEntry>} metadataEntries - API documentation metadata entries
+ * @param {ApiDocMetadataEntry[]} metadataEntries - API documentation metadata entries
  * @param {import('unified').Processor} remark - Remark processor instance for markdown processing
  */
 export default function buildContent(metadataEntries, remark) {
-  const rootNode = createTree('root', metadataEntries.map(process));
-  return remark.stringify(remark.runSync(rootNode));
+  const root = createTree('root', [
+    createJSXElement('NavBar'),
+    createJSXElement('MainLayout', {
+      children: [
+        createJSXElement('SideBar'),
+        createElement('div', [
+          createElement('main', metadataEntries.map(process)),
+          createElement('MetaBar'),
+        ]),
+        createJSXElement('Footer'),
+      ],
+    }),
+  ]);
+
+  return remark.stringify(remark.runSync(root));
 }

src/generators/jsx/utils/buildContent.mjs

@@ -3,15 +3,7 @@ import { getRemarkRehype } from '../../../utils/remark.mjs';
 import { transformNodesToString } from '../../../utils/unist.mjs';
 import { parseList } from './parseList.mjs';
 import { SECTION_TYPE_PLURALS, UNPROMOTED_KEYS } from '../constants.mjs';
-
-/**
- * Converts a value to an array.
- * @template T
- * @param {T | T[]} val - The value to convert.
- * @returns {T[]} The value as an array.
- */
-const enforceArray = val => (Array.isArray(val) ? val : [val]);
-
+import { enforceArray } from '../../../utils/generators.mjs';
 /**
  *
  */

src/generators/legacy-json/utils/buildSection.mjs

@@ -1,6 +1,7 @@
 import { LINT_MESSAGES } from '../constants.mjs';
 import { valid, parse } from 'semver';
 import { env } from 'node:process';
+import { enforceArray } from '../../utils/generators.mjs';
 
 const NODE_RELEASED_VERSIONS = env.NODE_RELEASED_VERSIONS?.split(',');
 
@@ -56,7 +57,7 @@ const isInvalid = NODE_RELEASED_VERSIONS
 export const invalidChangeVersion = entries =>
   entries.flatMap(({ changes, api_doc_source, yaml_position }) =>
     changes.flatMap(({ version }) =>
-      (Array.isArray(version) ? version : [version])
+      enforceArray(version)
         .filter(isInvalid)
         .map(version => ({
           level: 'error',

src/linter/rules/invalid-change-version.mjs

@@ -53,3 +53,11 @@ export const coerceSemVer = version => {
 
   return coercedVersion;
 };
+
+/**
+ * Converts a value to an array.
+ * @template T
+ * @param {T | T[]} val - The value to convert.
+ * @returns {T[]} The value as an array.
+ */
+export const enforceArray = val => (Array.isArray(val) ? val : [val]);