Skip to content

Commit 5e7fe69

Browse files
avivkelleravivkeller
committed
more
1 parent 5af0cd0 commit 5e7fe69

File tree

7 files changed

+105
-45
lines changed

7 files changed

+105
-45
lines changed

‎src/constants.mjs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,14 @@ export const DOC_NODE_CHANGELOG_URL =
99

1010
// The base URL for the Node.js website
1111
export const BASE_URL = 'https://nodejs.org/';
12+
13+
// This is the Node.js Base URL for viewing a file within GitHub UI
14+
export const DOC_NODE_BLOB_BASE_URL =
15+
'https://github.com/nodejs/node/blob/HEAD/';
16+
17+
// This is the Node.js API docs base URL for editing a file on GitHub UI
18+
export const DOC_API_BLOB_EDIT_BASE_URL =
19+
'https://github.com/nodejs/node/edit/main/doc/api/';
20+
21+
// Base URL for a specific Node.js version within the Node.js API docs
22+
export const DOC_API_BASE_URL_VERSION = 'https://nodejs.org/docs/latest-v';

‎src/generators/jsx/constants.mjs‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,24 @@
1+
// Maps the the stability index (0-3) to the level used by @node-core/ui-components
12
export const STABILITY_LEVELS = [
2-
'danger', // Deprecated
3-
'warning', // Experimental
4-
'success', // Stable
5-
'info', // Legacy
3+
'danger', // (0) Deprecated
4+
'warning', // (1) Experimental
5+
'success', // (2) Stable
6+
'info', // (3) Legacy
67
];
78

9+
// Maps HTML tags to corresponding component names in @node-core/ui-components
810
export const TAG_TRANSFORMS = {
911
pre: 'CodeBox',
1012
blockquote: 'Blockquote',
1113
};
14+
15+
// Maps types to icon symbols
16+
export const ICON_SYMBOL_MAP = {
17+
event: { symbol: 'E', color: 'red' },
18+
method: { symbol: 'M', color: 'red' },
19+
property: { symbol: 'P', color: 'red' },
20+
class: { symbol: 'C', color: 'red' },
21+
module: { symbol: 'M', color: 'red' },
22+
classMethod: { symbol: 'S', color: 'red' },
23+
ctor: { symbol: 'C', color: 'red' },
24+
};

‎src/generators/jsx/utils/buildContent.mjs‎

Lines changed: 68 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,101 @@
11
'use strict';
22

33
// External dependencies
4+
import { h as createElement } from 'hastscript';
45
import { u as createTree } from 'unist-builder';
56
import { SKIP, visit } from 'unist-util-visit';
67

78
// Internal dependencies
89
import createQueries from '../../../utils/queries/index.mjs';
910
import { createJSXElement } from './ast.mjs';
10-
import { STABILITY_LEVELS } from '../constants.mjs';
11+
import { ICON_SYMBOL_MAP, STABILITY_LEVELS } from '../constants.mjs';
12+
import { DOC_NODE_BLOB_BASE_URL } from '../../../constants.mjs';
1113

1214
/**
1315
* Transforms a stability node into an AlertBox JSX element
1416
*
15-
* @param {Object} node - The stability node to transform
17+
* @param {import('mdast').Blockquote} node - The stability node to transform
1618
* @param {number} index - The index of the node in its parent's children array
17-
* @param {Object} parent - The parent node containing the stability node
18-
* @returns {Array} - Returns [SKIP] to indicate this node should be skipped in further traversal
19+
* @param {import('unist').Node} parent - The parent node containing the stability node
1920
*/
2021
function visitStabilityNode(node, index, parent) {
21-
parent.children.splice(
22-
index,
23-
1,
24-
createJSXElement('AlertBox', {
25-
children: node.data.description,
26-
level: STABILITY_LEVELS[node.data.index],
27-
title: node.data.index,
28-
})
29-
);
22+
parent.children[index] = createJSXElement('AlertBox', {
23+
children: node.data.description,
24+
level: STABILITY_LEVELS[node.data.index],
25+
title: node.data.index,
26+
});
27+
return [SKIP];
28+
}
29+
30+
/**
31+
* Adds the metadata around the header node
32+
*
33+
* @param {ApiDocMetadataEntry} entry - The content object to process
34+
* @param {import('mdast').Heading} node - The stability node to transform
35+
* @param {number} index - The index of the node in its parent's children array
36+
* @param {import('unist').Node} parent - The parent node containing the stability node
37+
*/
38+
function visitHeadingNode(entry, { data, children }, index, parent) {
39+
console.error(data);
40+
// Add type icon if available
41+
if (ICON_SYMBOL_MAP[data.type]) {
42+
// TODO: This hasn't been implemented yet. This is an assumption of what a
43+
// potential implementation could look like
44+
children.unshift(
45+
createJSXElement('CircularIcon', ICON_SYMBOL_MAP[data.type])
46+
);
47+
}
48+
49+
// Replace node with proper heading and anchor
50+
parent.children[index] = createElement(`h${data.depth + 1}`, [
51+
createElement(`a.mark#${data.slug}`, { href: `#${data.slug}` }, children),
52+
]);
53+
54+
// Add source link if available
55+
if (entry.source_link) {
56+
parent.children.splice(
57+
index + 1,
58+
0,
59+
createElement('span', [
60+
'Source Code: ',
61+
createElement(
62+
'a',
63+
{ href: `${DOC_NODE_BLOB_BASE_URL}${entry.source_link}` },
64+
entry.source_link
65+
),
66+
])
67+
);
68+
}
69+
3070
return [SKIP];
3171
}
3272

3373
/**
3474
* Processes content by transforming stability nodes
3575
*
36-
* @param {Object} content - The content object to process
37-
* @returns {Object} - The processed content with stability nodes transformed
76+
* @param {ApiDocMetadataEntry} entry - The entry
3877
*/
39-
function processContent(content) {
40-
const contentCopy = { ...content };
41-
visit(contentCopy, createQueries.UNIST.isStabilityNode, visitStabilityNode);
42-
return contentCopy;
78+
function process(entry) {
79+
// Create a shallow copy to avoid modifying the original
80+
const content = structuredClone(entry.content);
81+
const { UNIST } = createQueries;
82+
83+
// Apply all transformations to the content
84+
visit(content, UNIST.isStabilityNode, visitStabilityNode);
85+
visit(content, UNIST.isHeading, (node, idx, parent) =>
86+
visitHeadingNode(entry, node, idx, parent)
87+
);
88+
89+
return content;
4390
}
4491

4592
/**
4693
* Transforms API metadata entries into processed MDX content
4794
*
48-
* @param {Array} metadataEntries - API documentation metadata entries
95+
* @param {Array<ApiDocMetadataEntry>} metadataEntries - API documentation metadata entries
4996
* @param {import('unified').Processor} remark - Remark processor instance for markdown processing
50-
* @returns {React.ReactElement} - Evaluated React element from processed MDX, ready for rendering
5197
*/
5298
export default function buildContent(metadataEntries, remark) {
53-
// Create and process the root node with all entries
54-
const rootNode = createTree(
55-
'root',
56-
metadataEntries.map(entry => processContent(entry.content))
57-
);
58-
99+
const rootNode = createTree('root', metadataEntries.map(process));
59100
return remark.stringify(remark.runSync(rootNode));
60101
}

‎src/generators/jsx/utils/transformer.mjs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,13 @@ import { TAG_TRANSFORMS } from '../constants.mjs';
1313
* @throws {ReferenceError} Will throw if 'tagMap' is not defined in scope
1414
*/
1515
export default () => tree => {
16+
// TODO(@avivkeller): Nodes like "Array<string>" return a "<string>" raw type,
17+
// which Recma does not understand, so we make them text.
18+
19+
visit(tree, 'raw', node => {
20+
node.type = 'text';
21+
});
22+
1623
visit(tree, 'element', node => {
1724
const replacement = TAG_TRANSFORMS[node.tagName];
1825
if (replacement) {

‎src/generators/legacy-html/constants.mjs‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎src/generators/legacy-html/utils/buildContent.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import buildExtraContent from './buildExtraContent.mjs';
88

99
import createQueries from '../../../utils/queries/index.mjs';
1010

11-
import { DOC_NODE_BLOB_BASE_URL } from '../constants.mjs';
11+
import { DOC_NODE_BLOB_BASE_URL } from '../../../constants.mjs';
1212

1313
/**
1414
* Builds a Markdown heading for a given node

‎src/generators/legacy-html/utils/buildDropdowns.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import {
1010
import {
1111
DOC_API_BASE_URL_VERSION,
1212
DOC_API_BLOB_EDIT_BASE_URL,
13-
} from '../constants.mjs';
13+
} from '../../../constants.mjs';
1414

1515
/**
1616
* Builds the Dropdown for the current Table of Contents

0 commit comments

Comments
 (0)