diff --git a/.changeset/react-kitten-package.md b/.changeset/react-kitten-package.md new file mode 100644 index 00000000..9a794126 --- /dev/null +++ b/.changeset/react-kitten-package.md @@ -0,0 +1,11 @@ +--- +'@doc-kittens/react': major +'@node-core/doc-kit': minor +--- + +The React/JSX-based generators (`html` — previously `web` —, `jsx-ast`, +`llms-txt`, `sitemap`, and `orama-db`) now live in the new +`@doc-kittens/react` package and are loaded via import specifiers such as +`@doc-kittens/react/html`. The `web` generator is renamed to `html`: the CLI +shorthand `web` keeps working as a deprecated alias, but the configuration +key is now `html` instead of `web`. diff --git a/eslint.config.mjs b/eslint.config.mjs index 197acf57..9e92946a 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -96,7 +96,7 @@ export default defineConfig([ { files: [ 'packages/core/src/generators/legacy-html/assets/*.js', - 'packages/core/src/generators/web/ui/**/*', + 'packages/react/src/html/ui/**/*', ], languageOptions: { globals: { diff --git a/package-lock.json b/package-lock.json index feac5df1..d2ad6593 100644 --- a/package-lock.json +++ b/package-lock.json @@ -405,6 +405,10 @@ "url": "https://github.com/prettier/prettier?sponsor=1" } }, + "node_modules/@doc-kittens/react": { + "resolved": "packages/react", + "link": true + }, "node_modules/@emnapi/core": { "version": "1.11.1", "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.1.tgz", @@ -11342,33 +11346,18 @@ "version": "1.4.3", "dependencies": { "@actions/core": "^3.0.0", - "@fontsource-variable/open-sans": "^5.3.0", - "@fontsource/ibm-plex-mono": "^5.3.0", - "@heroicons/react": "^2.2.0", "@node-core/rehype-shiki": "^1.4.2", - "@node-core/ui-components": "^1.7.2", - "@orama/orama": "^3.1.18", - "@orama/ui": "^1.5.4", "@swc/html-wasm": "^1.15.43", "@swc/wasm": "^1.15.46", "acorn": "^8.17.0", "commander": "^15.0.0", "cosmiconfig": "^9.0.2", "dedent": "^1.7.2", - "estree-util-to-js": "^2.0.0", "estree-util-visit": "^2.0.0", "github-slugger": "^2.0.0", "glob-parent": "^6.0.2", - "hast-util-to-string": "^3.0.1", "hastscript": "^9.0.1", - "mdast-util-slice-markdown": "^2.0.1", "piscina": "^5.2.0", - "preact": "^10.29.2", - "preact-render-to-string": "^6.7.0", - "reading-time": "^1.5.0", - "recma-jsx": "^1.0.1", - "rehype-raw": "^7.0.0", - "rehype-recma": "^1.0.0", "rehype-stringify": "^10.0.1", "remark-gfm": "^4.0.1", "remark-mdx": "^3.1.1", @@ -11385,12 +11374,43 @@ "unist-util-remove": "^4.0.0", "unist-util-select": "^5.1.0", "unist-util-visit": "^5.1.0", - "vite": "~8.1.5", "yaml": "^2.9.0" }, "bin": { "doc-kit": "bin/cli.mjs" } + }, + "packages/react": { + "name": "@doc-kittens/react", + "version": "1.0.0", + "dependencies": { + "@fontsource-variable/open-sans": "^5.3.0", + "@fontsource/ibm-plex-mono": "^5.3.0", + "@heroicons/react": "^2.2.0", + "@node-core/doc-kit": "^1.4.3", + "@node-core/rehype-shiki": "^1.4.2", + "@node-core/ui-components": "^1.7.2", + "@orama/orama": "^3.1.18", + "@orama/ui": "^1.5.4", + "estree-util-to-js": "^2.0.0", + "hast-util-to-string": "^3.0.1", + "hastscript": "^9.0.1", + "mdast-util-slice-markdown": "^2.0.1", + "preact": "^10.29.2", + "preact-render-to-string": "^6.7.0", + "reading-time": "^1.5.0", + "recma-jsx": "^1.0.1", + "recma-stringify": "^1.0.0", + "rehype-raw": "^7.0.0", + "rehype-recma": "^1.0.0", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.1.2", + "semver": "^7.8.5", + "unified": "^11.0.5", + "unist-builder": "^4.0.0", + "unist-util-visit": "^5.1.0", + "vite": "~8.1.5" + } } } } diff --git a/packages/core/package.json b/packages/core/package.json index b5f668a7..0852355e 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -23,17 +23,12 @@ "./ast": "./src/generators/ast/index.mjs", "./ast-js": "./src/generators/ast-js/index.mjs", "./json-simple": "./src/generators/json-simple/index.mjs", - "./jsx-ast": "./src/generators/jsx-ast/index.mjs", "./legacy-html": "./src/generators/legacy-html/index.mjs", "./legacy-html-all": "./src/generators/legacy-html-all/index.mjs", "./legacy-json": "./src/generators/legacy-json/index.mjs", "./legacy-json-all": "./src/generators/legacy-json-all/index.mjs", - "./llms-txt": "./src/generators/llms-txt/index.mjs", "./man-page": "./src/generators/man-page/index.mjs", "./metadata": "./src/generators/metadata/index.mjs", - "./orama-db": "./src/generators/orama-db/index.mjs", - "./sitemap": "./src/generators/sitemap/index.mjs", - "./web": "./src/generators/web/index.mjs", "./package.json": "./package.json", "./shiki.config.mjs": "./shiki.config.mjs", "./src/*": "./src/*", @@ -54,33 +49,18 @@ ], "dependencies": { "@actions/core": "^3.0.0", - "@fontsource-variable/open-sans": "^5.3.0", - "@fontsource/ibm-plex-mono": "^5.3.0", - "@heroicons/react": "^2.2.0", "@node-core/rehype-shiki": "^1.4.2", - "@node-core/ui-components": "^1.7.2", - "@orama/orama": "^3.1.18", - "@orama/ui": "^1.5.4", "@swc/html-wasm": "^1.15.43", "@swc/wasm": "^1.15.46", "acorn": "^8.17.0", "commander": "^15.0.0", "cosmiconfig": "^9.0.2", "dedent": "^1.7.2", - "estree-util-to-js": "^2.0.0", "estree-util-visit": "^2.0.0", "github-slugger": "^2.0.0", "glob-parent": "^6.0.2", - "hast-util-to-string": "^3.0.1", "hastscript": "^9.0.1", - "mdast-util-slice-markdown": "^2.0.1", "piscina": "^5.2.0", - "preact": "^10.29.2", - "preact-render-to-string": "^6.7.0", - "reading-time": "^1.5.0", - "recma-jsx": "^1.0.1", - "rehype-raw": "^7.0.0", - "rehype-recma": "^1.0.0", "rehype-stringify": "^10.0.1", "remark-gfm": "^4.0.1", "remark-mdx": "^3.1.1", @@ -97,7 +77,6 @@ "unist-util-remove": "^4.0.0", "unist-util-select": "^5.1.0", "unist-util-visit": "^5.1.0", - "vite": "~8.1.5", "yaml": "^2.9.0" } } diff --git a/packages/core/src/generators/__tests__/index.test.mjs b/packages/core/src/generators/__tests__/index.test.mjs index cd3bfdcf..e0af8670 100644 --- a/packages/core/src/generators/__tests__/index.test.mjs +++ b/packages/core/src/generators/__tests__/index.test.mjs @@ -1,13 +1,25 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; -import { allGenerators, publicGenerators } from '../index.mjs'; +import { + allGenerators, + deprecatedGenerators, + publicGenerators, +} from '../index.mjs'; import { loadGenerator, resolveGeneratorSpecifier } from '../loader.mjs'; const validDependencies = Object.values(allGenerators); +// Deprecated aliases intentionally have keys that differ from the +// generator's name, so they are excluded from the name-match assertions. +const currentGenerators = Object.fromEntries( + Object.entries(allGenerators).filter( + ([name]) => !(name in deprecatedGenerators) + ) +); + const loadedGenerators = await Promise.all( - Object.entries(allGenerators).map(async ([name, specifier]) => [ + Object.entries(currentGenerators).map(async ([name, specifier]) => [ name, specifier, await loadGenerator(specifier), @@ -50,6 +62,15 @@ describe('All Generators', () => { }); }); + it('should resolve deprecated aliases to loadable generators', async () => { + for (const [name, specifier] of Object.entries(deprecatedGenerators)) { + assert.equal(resolveGeneratorSpecifier(name), specifier); + + const generator = await loadGenerator(specifier); + assert.ok(generator.name, `Deprecated alias "${name}" must load`); + } + }); + it('should have ast generator as a top-level generator with no dependencies', async () => { const ast = await loadGenerator(allGenerators.ast); assert.ok(ast, 'ast generator should exist'); diff --git a/packages/core/src/generators/index.mjs b/packages/core/src/generators/index.mjs index a8b1a68f..9e6d313a 100644 --- a/packages/core/src/generators/index.mjs +++ b/packages/core/src/generators/index.mjs @@ -2,7 +2,7 @@ /** * Maps the shorthand names accepted by the CLI and configuration files - * (e.g. `--target web`) to the import specifiers they resolve to. + * (e.g. `--target html`) to the import specifiers they resolve to. * * Generators are loaded dynamically by specifier (see `./loader.mjs`), so this * module must not import any generator code — it is purely a lookup table. @@ -18,10 +18,10 @@ export const publicGenerators = { 'legacy-json-all': '@node-core/doc-kit/legacy-json-all', 'addon-verify': '@node-core/doc-kit/addon-verify', 'api-links': '@node-core/doc-kit/api-links', - 'orama-db': '@node-core/doc-kit/orama-db', - 'llms-txt': '@node-core/doc-kit/llms-txt', - sitemap: '@node-core/doc-kit/sitemap', - web: '@node-core/doc-kit/web', + 'orama-db': '@doc-kittens/react/orama-db', + 'llms-txt': '@doc-kittens/react/llms-txt', + sitemap: '@doc-kittens/react/sitemap', + html: '@doc-kittens/react/html', }; // These ones are special since they don't produce standard output, @@ -30,11 +30,19 @@ export const publicGenerators = { const internalGenerators = { ast: '@node-core/doc-kit/ast', metadata: '@node-core/doc-kit/metadata', - 'jsx-ast': '@node-core/doc-kit/jsx-ast', + 'jsx-ast': '@doc-kittens/react/jsx-ast', 'ast-js': '@node-core/doc-kit/ast-js', }; +// Former names kept resolvable for existing invocations and config files. +// Unlike the maps above, keys here intentionally differ from the generator's +// `name` property. +export const deprecatedGenerators = { + web: '@doc-kittens/react/html', +}; + export const allGenerators = { ...publicGenerators, ...internalGenerators, + ...deprecatedGenerators, }; diff --git a/packages/core/src/generators/web/template.html b/packages/core/src/generators/web/template.html deleted file mode 100644 index e3792678..00000000 --- a/packages/core/src/generators/web/template.html +++ /dev/null @@ -1,22 +0,0 @@ - - - - - - - ${title} - - - - ${head} - - - - - - - -
${dehydrated}
- - - diff --git a/packages/core/src/utils/remark.mjs b/packages/core/src/utils/remark.mjs index 1aacd37a..3935b7ea 100644 --- a/packages/core/src/utils/remark.mjs +++ b/packages/core/src/utils/remark.mjs @@ -1,10 +1,5 @@ 'use strict'; -import rehypeShikiji from '@node-core/rehype-shiki/plugin'; -import recmaJsx from 'recma-jsx'; -import recmaStringify from 'recma-stringify'; -import rehypeRaw from 'rehype-raw'; -import rehypeRecma from 'rehype-recma'; import rehypeStringify from 'rehype-stringify'; import remarkGfm from 'remark-gfm'; import remarkMdx from 'remark-mdx'; @@ -12,49 +7,24 @@ import remarkParse from 'remark-parse'; import remarkRehype from 'remark-rehype'; import remarkStringify from 'remark-stringify'; import { unified } from 'unified'; -import { visit } from 'unist-util-visit'; -import syntaxHighlighter, { highlighter } from './highlighter.mjs'; +import syntaxHighlighter from './highlighter.mjs'; import { lazy } from './misc.mjs'; -import { - typeAnnotationToHast, - typeAnnotationToHighlightedHast, -} from './type-annotations/hast.mjs'; +import { typeAnnotationToHast } from './type-annotations/hast.mjs'; import remarkTypeAnnotations from './type-annotations/remark.mjs'; -import { AST_NODE_TYPES } from '../generators/jsx-ast/constants.mjs'; -import transformAlerts from '../generators/jsx-ast/utils/plugins/alerts.mjs'; -import transformElements from '../generators/jsx-ast/utils/plugins/transformer.mjs'; -const passThrough = ['element', ...Object.values(AST_NODE_TYPES.MDX)]; -const codeMetaProperty = 'codeMeta'; - -/** - * Stores fenced code metadata on properties before rehypeRaw reparses the tree. - */ -const preserveCodeMeta = () => tree => { - visit(tree, 'element', node => { - const meta = node.data?.meta; - - if (node.tagName === 'code' && typeof meta === 'string') { - node.properties ||= {}; - node.properties[codeMetaProperty] = meta; - } - }); -}; - -/** - * Restores fenced code metadata so the Shiki plugin can read displayName. - */ -const restoreCodeMeta = () => tree => { - visit(tree, 'element', node => { - const meta = node.properties?.[codeMetaProperty]; - - if (node.tagName === 'code' && typeof meta === 'string') { - node.data = { ...node.data, meta }; - delete node.properties[codeMetaProperty]; - } - }); -}; +// MDX node types that may appear in trees parsed by `getRemarkMdx`; the +// rehype pipelines pass them through untouched. +const passThrough = [ + 'element', + 'mdxJsxTextElement', + 'mdxJsxFlowElement', + 'mdxJsxAttribute', + 'mdxJsxAttributeValueExpression', + 'mdxFlowExpression', + 'mdxTextExpression', + 'mdxjsEsm', +]; /** * Retrieves an instance of Remark configured to parse GFM (GitHub Flavored Markdown) @@ -125,34 +95,3 @@ export const getRemarkRehypeWithShiki = lazy(() => // and we trust the sources of the Markdown files .use(rehypeStringify, { allowDangerousHtml: true }) ); - -const singletonShiki = await rehypeShikiji({ highlighter }); - -/** - * Retrieves an instance of Remark configured to output JSX code. - * including parsing Code Boxes with syntax highlighting - */ -export const getRemarkRecma = lazy(() => - unified() - .use(remarkParse) - .use(transformAlerts) - // We make Rehype ignore existing HTML nodes, and JSX nodes - // as these are nodes we manually created during the generation process - // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown - // and we trust the sources of the Markdown files - .use(remarkRehype, { - allowDangerousHtml: true, - passThrough, - // The web pipeline gets Shiki-highlighted types with embedded links - handlers: { typeAnnotation: typeAnnotationToHighlightedHast }, - }) - .use(preserveCodeMeta) - // Any `raw` HTML in the markdown must be converted to AST in order for Recma to understand it - .use(rehypeRaw, { passThrough }) - .use(restoreCodeMeta) - .use(() => singletonShiki) - .use(transformElements) - .use(rehypeRecma) - .use(recmaJsx) - .use(recmaStringify) -); diff --git a/packages/react/package.json b/packages/react/package.json new file mode 100644 index 00000000..531a7bdb --- /dev/null +++ b/packages/react/package.json @@ -0,0 +1,55 @@ +{ + "name": "@doc-kittens/react", + "type": "module", + "version": "0.0.0", + "description": "React/JSX-based generators for @node-core/doc-kit: html, jsx-ast, llms-txt, sitemap, and orama-db", + "repository": { + "type": "git", + "url": "git+https://github.com/nodejs/doc-kit.git", + "directory": "packages/react" + }, + "exports": { + "./html": "./src/html/index.mjs", + "./jsx-ast": "./src/jsx-ast/index.mjs", + "./llms-txt": "./src/llms-txt/index.mjs", + "./orama-db": "./src/orama-db/index.mjs", + "./sitemap": "./src/sitemap/index.mjs", + "./package.json": "./package.json" + }, + "files": [ + "src", + "!src/**/*.test.mjs", + "!src/**/__tests__", + "CHANGELOG.md", + "LICENSE", + "README.md" + ], + "dependencies": { + "@fontsource-variable/open-sans": "^5.3.0", + "@fontsource/ibm-plex-mono": "^5.3.0", + "@heroicons/react": "^2.2.0", + "@node-core/doc-kit": "^1.4.3", + "@node-core/rehype-shiki": "^1.4.2", + "@node-core/ui-components": "^1.7.2", + "@orama/orama": "^3.1.18", + "@orama/ui": "^1.5.4", + "estree-util-to-js": "^2.0.0", + "hast-util-to-string": "^3.0.1", + "hastscript": "^9.0.1", + "mdast-util-slice-markdown": "^2.0.1", + "preact": "^10.29.2", + "preact-render-to-string": "^6.7.0", + "reading-time": "^1.5.0", + "recma-jsx": "^1.0.1", + "recma-stringify": "^1.0.0", + "rehype-raw": "^7.0.0", + "rehype-recma": "^1.0.0", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.1.2", + "semver": "^7.8.5", + "unified": "^11.0.5", + "unist-builder": "^4.0.0", + "unist-util-visit": "^5.1.0", + "vite": "~8.1.5" + } +} diff --git a/packages/core/src/generators/web/README.md b/packages/react/src/html/README.md similarity index 100% rename from packages/core/src/generators/web/README.md rename to packages/react/src/html/README.md diff --git a/packages/core/src/generators/web/__tests__/generate.test.mjs b/packages/react/src/html/__tests__/generate.test.mjs similarity index 93% rename from packages/core/src/generators/web/__tests__/generate.test.mjs rename to packages/react/src/html/__tests__/generate.test.mjs index bb052f99..0445a621 100644 --- a/packages/core/src/generators/web/__tests__/generate.test.mjs +++ b/packages/react/src/html/__tests__/generate.test.mjs @@ -4,9 +4,9 @@ import { tmpdir } from 'node:os'; import { dirname, join } from 'node:path'; import { describe, it } from 'node:test'; +import { setConfig } from '@node-core/doc-kit/utils/configuration/index.mjs'; import { jsx, toJs } from 'estree-util-to-js'; -import { setConfig } from '../../../utils/configuration/index.mjs'; import buildContent from '../../jsx-ast/utils/buildContent.mjs'; import { buildNotFoundPage } from '../../jsx-ast/utils/synthetic/404.mjs'; import { createViteBundler } from '../bundlers/vite.mjs'; @@ -53,12 +53,12 @@ const createTestConfiguration = async context => { context.after(() => rm(output, { recursive: true, force: true })); const config = await setConfig({ - target: ['web'], + target: ['html'], output, version: 'v22.0.0', changelog: [], generators: { - web: {}, + html: {}, }, }); @@ -93,7 +93,7 @@ describe('web generate', () => { it('renders the configurable head without hardcoded defaults', async context => { const { config, output } = await createTestConfiguration(context); - config.web.head = { + config.html.head = { meta: [ { name: 'description', content: 'Custom project docs' }, { property: 'og:image', content: 'https://example.com/og.png' }, @@ -116,8 +116,8 @@ describe('web generate', () => { it('uses Vite base URLs for absolute client assets', async context => { const { config, output } = await createTestConfiguration(context); - config.web.useAbsoluteURLs = true; - config.web.baseURL = 'https://example.com/docs'; + config.html.useAbsoluteURLs = true; + config.html.baseURL = 'https://example.com/docs'; const notFoundPage = buildNotFoundPage(); const content = await buildContent(notFoundPage.entries, notFoundPage.head); @@ -130,7 +130,7 @@ describe('web generate', () => { it('applies configured Vite plugins', async context => { const { config, output } = await createTestConfiguration(context); - config.web.bundler = createViteBundler({ + config.html.bundler = createViteBundler({ plugins: [ { name: 'test-html-transform', @@ -158,7 +158,7 @@ describe('web generate', () => { const { config, output } = await createTestConfiguration(context); const calls = []; - config.web.bundler = { + config.html.bundler = { getEntryId(api) { calls.push(`entry:${api}`); return `/custom/${api}.js`; @@ -166,7 +166,7 @@ describe('web generate', () => { async render({ entries, virtualImports, config: receivedConfig }) { calls.push('server'); - assert.strictEqual(receivedConfig, config.web); + assert.strictEqual(receivedConfig, config.html); assert.ok(entries.has('fs.jsx')); assert.match(virtualImports['#theme/config'], /export const pages/); assert.match( @@ -181,7 +181,7 @@ describe('web generate', () => { async build({ entries, virtualImports, pages, config: receivedConfig }) { calls.push('client'); - assert.strictEqual(receivedConfig, config.web); + assert.strictEqual(receivedConfig, config.html); assert.ok(entries.has('fs.jsx')); assert.match( virtualImports['#theme/config'], diff --git a/packages/core/src/generators/web/bundlers/__tests__/vite.test.mjs b/packages/react/src/html/bundlers/__tests__/vite.test.mjs similarity index 94% rename from packages/core/src/generators/web/bundlers/__tests__/vite.test.mjs rename to packages/react/src/html/bundlers/__tests__/vite.test.mjs index 7ff724c6..0d8486ed 100644 --- a/packages/core/src/generators/web/bundlers/__tests__/vite.test.mjs +++ b/packages/react/src/html/bundlers/__tests__/vite.test.mjs @@ -7,7 +7,8 @@ import { describe, it } from 'node:test'; import { default as getConfig, setConfig, -} from '../../../../utils/configuration/index.mjs'; +} from '@node-core/doc-kit/utils/configuration/index.mjs'; + import { createVirtualModulesPlugin, createViteConfig, @@ -17,12 +18,12 @@ import { const output = join(tmpdir(), 'doc-kit-vite-test-output'); await setConfig({ - target: ['web'], + target: ['html'], output, version: 'v22.0.0', changelog: [], generators: { - web: {}, + html: {}, }, }); @@ -66,7 +67,7 @@ describe('Vite configuration', () => { sources: new Map(), input, server: false, - config: getConfig('web'), + config: getConfig('html'), vite, }); @@ -97,7 +98,7 @@ describe('Vite configuration', () => { input, server: true, serverOutDir: serverOutput, - config: getConfig('web'), + config: getConfig('html'), vite, }); @@ -125,7 +126,7 @@ describe('Vite SSR temporary output', () => { ], ]), virtualImports: {}, - config: getConfig('web'), + config: getConfig('html'), vite: {}, createTemporaryDirectory: async () => temporaryDirectory, }), diff --git a/packages/core/src/generators/web/bundlers/index.mjs b/packages/react/src/html/bundlers/index.mjs similarity index 100% rename from packages/core/src/generators/web/bundlers/index.mjs rename to packages/react/src/html/bundlers/index.mjs diff --git a/packages/core/src/generators/web/bundlers/vite.mjs b/packages/react/src/html/bundlers/vite.mjs similarity index 99% rename from packages/core/src/generators/web/bundlers/vite.mjs rename to packages/react/src/html/bundlers/vite.mjs index ceeab15a..5638a2b9 100644 --- a/packages/core/src/generators/web/bundlers/vite.mjs +++ b/packages/react/src/html/bundlers/vite.mjs @@ -3,6 +3,7 @@ import { tmpdir } from 'node:os'; import { basename, isAbsolute, join, resolve } from 'node:path'; import { pathToFileURL } from 'node:url'; +import { minifyHTML } from '@node-core/doc-kit/utils/html-minifier.mjs'; import { build as viteBuild, defaultClientConditions, @@ -10,8 +11,6 @@ import { mergeConfig, } from 'vite'; -import { minifyHTML } from '../../../utils/html-minifier.mjs'; - const VIRTUAL_PREFIX = 'virtual:doc-kit/'; const RESOLVED_VIRTUAL_PREFIX = '\0doc-kit:'; diff --git a/packages/core/src/generators/web/constants.mjs b/packages/react/src/html/constants.mjs similarity index 100% rename from packages/core/src/generators/web/constants.mjs rename to packages/react/src/html/constants.mjs diff --git a/packages/core/src/generators/web/generate.mjs b/packages/react/src/html/generate.mjs similarity index 92% rename from packages/core/src/generators/web/generate.mjs rename to packages/react/src/html/generate.mjs index 6903f67d..09ce5cef 100644 --- a/packages/core/src/generators/web/generate.mjs +++ b/packages/react/src/html/generate.mjs @@ -2,9 +2,10 @@ import { readFile } from 'node:fs/promises'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; + import { copyStaticAssets } from './utils/copying.mjs'; import { createCodeConverter, processBundles } from './utils/processing.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; /** * Main generation function that sends per-page JSX code to the web bundler. @@ -17,7 +18,7 @@ import getConfig from '../../utils/configuration/index.mjs'; * @type {import('./types').Generator['generate']} */ export async function generate(input) { - const config = getConfig('web'); + const config = getConfig('html'); const template = await readFile(config.templatePath, 'utf-8'); diff --git a/packages/core/src/generators/web/index.mjs b/packages/react/src/html/index.mjs similarity index 94% rename from packages/core/src/generators/web/index.mjs rename to packages/react/src/html/index.mjs index 67e1ab4c..3a1d2700 100644 --- a/packages/core/src/generators/web/index.mjs +++ b/packages/react/src/html/index.mjs @@ -2,8 +2,9 @@ import { join } from 'node:path'; +import { GITHUB_EDIT_URL } from '@node-core/doc-kit/utils/configuration/templates.mjs'; + import { generate } from './generate.mjs'; -import { GITHUB_EDIT_URL } from '../../utils/configuration/templates.mjs'; /** * Web generator - transforms JSX AST entries into complete web bundles. @@ -25,14 +26,14 @@ import { GITHUB_EDIT_URL } from '../../utils/configuration/templates.mjs'; * @type {import('./types').Generator} */ export default { - name: 'web', + name: 'html', description: 'Generates HTML/CSS/JS bundles from JSX AST entries', - dependsOn: '@node-core/doc-kit/jsx-ast', + dependsOn: '@doc-kittens/react/jsx-ast', /** - * @param {import('../../utils/configuration/types').Configuration} config + * @param {import('@node-core/doc-kit/utils/configuration/types').Configuration} config */ defaultConfiguration: config => ({ templatePath: join(import.meta.dirname, 'template.html'), diff --git a/packages/react/src/html/template.html b/packages/react/src/html/template.html new file mode 100644 index 00000000..b702d8e5 --- /dev/null +++ b/packages/react/src/html/template.html @@ -0,0 +1,25 @@ + + + + + + ${title} + + + + ${head} + + + + + + + +
${dehydrated}
+ + + diff --git a/packages/core/src/generators/web/types.d.ts b/packages/react/src/html/types.d.ts similarity index 96% rename from packages/core/src/generators/web/types.d.ts rename to packages/react/src/html/types.d.ts index 4398651b..24c2256a 100644 --- a/packages/core/src/generators/web/types.d.ts +++ b/packages/react/src/html/types.d.ts @@ -1,5 +1,5 @@ import type { JSXContent } from '../jsx-ast/utils/buildContent.mjs'; -import type { GlobalConfiguration } from '../../utils/configuration/types'; +import type { GlobalConfiguration } from '@node-core/doc-kit/utils/configuration/types'; // An attribute bag rendered into an HTML tag. `true` becomes a valueless // attribute (e.g. `crossorigin`); `false`/`null`/`undefined` are omitted. diff --git a/packages/core/src/generators/web/ui/components/Banner.jsx b/packages/react/src/html/ui/components/Banner.jsx similarity index 100% rename from packages/core/src/generators/web/ui/components/Banner.jsx rename to packages/react/src/html/ui/components/Banner.jsx diff --git a/packages/core/src/generators/web/ui/components/CodeBox.jsx b/packages/react/src/html/ui/components/CodeBox.jsx similarity index 100% rename from packages/core/src/generators/web/ui/components/CodeBox.jsx rename to packages/react/src/html/ui/components/CodeBox.jsx diff --git a/packages/core/src/generators/web/ui/components/Layout/index.jsx b/packages/react/src/html/ui/components/Layout/index.jsx similarity index 100% rename from packages/core/src/generators/web/ui/components/Layout/index.jsx rename to packages/react/src/html/ui/components/Layout/index.jsx diff --git a/packages/core/src/generators/web/ui/components/MetaBar/index.jsx b/packages/react/src/html/ui/components/MetaBar/index.jsx similarity index 100% rename from packages/core/src/generators/web/ui/components/MetaBar/index.jsx rename to packages/react/src/html/ui/components/MetaBar/index.jsx diff --git a/packages/core/src/generators/web/ui/components/MetaBar/index.module.css b/packages/react/src/html/ui/components/MetaBar/index.module.css similarity index 100% rename from packages/core/src/generators/web/ui/components/MetaBar/index.module.css rename to packages/react/src/html/ui/components/MetaBar/index.module.css diff --git a/packages/core/src/generators/web/ui/components/NavBar.jsx b/packages/react/src/html/ui/components/NavBar.jsx similarity index 100% rename from packages/core/src/generators/web/ui/components/NavBar.jsx rename to packages/react/src/html/ui/components/NavBar.jsx diff --git a/packages/core/src/generators/web/ui/components/NoOp.jsx b/packages/react/src/html/ui/components/NoOp.jsx similarity index 100% rename from packages/core/src/generators/web/ui/components/NoOp.jsx rename to packages/react/src/html/ui/components/NoOp.jsx diff --git a/packages/core/src/generators/web/ui/components/SearchBox/index.jsx b/packages/react/src/html/ui/components/SearchBox/index.jsx similarity index 100% rename from packages/core/src/generators/web/ui/components/SearchBox/index.jsx rename to packages/react/src/html/ui/components/SearchBox/index.jsx diff --git a/packages/core/src/generators/web/ui/components/SearchBox/index.module.css b/packages/react/src/html/ui/components/SearchBox/index.module.css similarity index 100% rename from packages/core/src/generators/web/ui/components/SearchBox/index.module.css rename to packages/react/src/html/ui/components/SearchBox/index.module.css diff --git a/packages/core/src/generators/web/ui/components/SideBar/index.jsx b/packages/react/src/html/ui/components/SideBar/index.jsx similarity index 100% rename from packages/core/src/generators/web/ui/components/SideBar/index.jsx rename to packages/react/src/html/ui/components/SideBar/index.jsx diff --git a/packages/core/src/generators/web/ui/components/SideBar/index.module.css b/packages/react/src/html/ui/components/SideBar/index.module.css similarity index 100% rename from packages/core/src/generators/web/ui/components/SideBar/index.module.css rename to packages/react/src/html/ui/components/SideBar/index.module.css diff --git a/packages/core/src/generators/web/ui/hooks/useBanners.mjs b/packages/react/src/html/ui/hooks/useBanners.mjs similarity index 100% rename from packages/core/src/generators/web/ui/hooks/useBanners.mjs rename to packages/react/src/html/ui/hooks/useBanners.mjs diff --git a/packages/core/src/generators/web/ui/hooks/useOrama.mjs b/packages/react/src/html/ui/hooks/useOrama.mjs similarity index 100% rename from packages/core/src/generators/web/ui/hooks/useOrama.mjs rename to packages/react/src/html/ui/hooks/useOrama.mjs diff --git a/packages/core/src/generators/web/ui/hooks/useTheme.mjs b/packages/react/src/html/ui/hooks/useTheme.mjs similarity index 100% rename from packages/core/src/generators/web/ui/hooks/useTheme.mjs rename to packages/react/src/html/ui/hooks/useTheme.mjs diff --git a/packages/core/src/generators/web/ui/index.css b/packages/react/src/html/ui/index.css similarity index 100% rename from packages/core/src/generators/web/ui/index.css rename to packages/react/src/html/ui/index.css diff --git a/packages/core/src/generators/web/ui/package.json b/packages/react/src/html/ui/package.json similarity index 100% rename from packages/core/src/generators/web/ui/package.json rename to packages/react/src/html/ui/package.json diff --git a/packages/core/src/generators/web/ui/theme-script.mjs b/packages/react/src/html/ui/theme-script.mjs similarity index 100% rename from packages/core/src/generators/web/ui/theme-script.mjs rename to packages/react/src/html/ui/theme-script.mjs diff --git a/packages/core/src/generators/web/ui/types.d.ts b/packages/react/src/html/ui/types.d.ts similarity index 89% rename from packages/core/src/generators/web/ui/types.d.ts rename to packages/react/src/html/ui/types.d.ts index 620e628f..2374e4e4 100644 --- a/packages/core/src/generators/web/ui/types.d.ts +++ b/packages/react/src/html/ui/types.d.ts @@ -1,5 +1,5 @@ -import { GlobalConfiguration } from '../../../utils/configuration/types'; -import { MetadataEntry } from '../../metadata/types'; +import { GlobalConfiguration } from '@node-core/doc-kit/utils/configuration/types'; +import { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types'; import { Configuration } from '../types'; import { SemVer } from 'semver'; diff --git a/packages/core/src/generators/web/ui/utils/relativeOrAbsolute.mjs b/packages/react/src/html/ui/utils/relativeOrAbsolute.mjs similarity index 89% rename from packages/core/src/generators/web/ui/utils/relativeOrAbsolute.mjs rename to packages/react/src/html/ui/utils/relativeOrAbsolute.mjs index e08b4876..1ec84378 100644 --- a/packages/core/src/generators/web/ui/utils/relativeOrAbsolute.mjs +++ b/packages/react/src/html/ui/utils/relativeOrAbsolute.mjs @@ -1,4 +1,4 @@ -import { relative } from '../../../../utils/url.mjs'; +import { relative } from '@node-core/doc-kit/utils/url.mjs'; import { useAbsoluteURLs, baseURL } from '#theme/config'; diff --git a/packages/core/src/generators/web/ui/utils/renderLabel.jsx b/packages/react/src/html/ui/utils/renderLabel.jsx similarity index 100% rename from packages/core/src/generators/web/ui/utils/renderLabel.jsx rename to packages/react/src/html/ui/utils/renderLabel.jsx diff --git a/packages/core/src/generators/web/utils/__tests__/config.test.mjs b/packages/react/src/html/utils/__tests__/config.test.mjs similarity index 97% rename from packages/core/src/generators/web/utils/__tests__/config.test.mjs rename to packages/react/src/html/utils/__tests__/config.test.mjs index 4a64149b..b9f3bcfa 100644 --- a/packages/core/src/generators/web/utils/__tests__/config.test.mjs +++ b/packages/react/src/html/utils/__tests__/config.test.mjs @@ -1,10 +1,9 @@ import assert from 'node:assert/strict'; import { describe, it, mock } from 'node:test'; +import { setConfig } from '@node-core/doc-kit/utils/configuration/index.mjs'; import { SemVer } from 'semver'; -import { setConfig } from '../../../../utils/configuration/index.mjs'; - mock.module('@node-core/rehype-shiki', { namedExports: { LANGS: [ @@ -25,7 +24,7 @@ await setConfig({ { version: new SemVer('22.0.0'), isLts: false, isCurrent: true }, ], generators: { - web: { + html: { title: 'Node.js', repository: 'nodejs/node', ref: 'main', diff --git a/packages/core/src/generators/web/utils/__tests__/copying.test.mjs b/packages/react/src/html/utils/__tests__/copying.test.mjs similarity index 95% rename from packages/core/src/generators/web/utils/__tests__/copying.test.mjs rename to packages/react/src/html/utils/__tests__/copying.test.mjs index 385ab714..807b9b1f 100644 --- a/packages/core/src/generators/web/utils/__tests__/copying.test.mjs +++ b/packages/react/src/html/utils/__tests__/copying.test.mjs @@ -8,7 +8,7 @@ mock.module('node:fs/promises', { }); const mockLogError = mock.fn(); -mock.module('../../../../logger/index.mjs', { +mock.module('@node-core/doc-kit/logger/index.mjs', { defaultExport: { error: mockLogError }, }); @@ -120,7 +120,7 @@ describe('copyStaticAssets', () => { const logMessage = mockLogError.mock.calls[0].arguments[0]; assert.match( logMessage, - /\[web-generator\] Failed to copy asset from protected-file to \/out\/protected-file: Permission denied/ + /\[html-generator\] Failed to copy asset from protected-file to \/out\/protected-file: Permission denied/ ); }); }); diff --git a/packages/core/src/generators/web/utils/__tests__/processing.test.mjs b/packages/react/src/html/utils/__tests__/processing.test.mjs similarity index 96% rename from packages/core/src/generators/web/utils/__tests__/processing.test.mjs rename to packages/react/src/html/utils/__tests__/processing.test.mjs index bd0b4c5b..985a49dc 100644 --- a/packages/core/src/generators/web/utils/__tests__/processing.test.mjs +++ b/packages/react/src/html/utils/__tests__/processing.test.mjs @@ -4,7 +4,8 @@ import { describe, it } from 'node:test'; import { default as getConfig, setConfig, -} from '../../../../utils/configuration/index.mjs'; +} from '@node-core/doc-kit/utils/configuration/index.mjs'; + import { buildHead, populateWithEvaluation, @@ -12,11 +13,11 @@ import { } from '../processing.mjs'; await setConfig({ - target: ['web'], + target: ['html'], version: 'v22.0.0', changelog: [], generators: { - web: { + html: { useAbsoluteURLs: false, baseURL: 'https://nodejs.org/docs', }, @@ -97,7 +98,7 @@ describe('resolvePageRoot', () => { }); it('uses the configured base URL for synthetic pages with absolute URLs', async () => { - getConfig('web').useAbsoluteURLs = true; + getConfig('html').useAbsoluteURLs = true; const result = resolvePageRoot({ path: '/404', @@ -105,7 +106,7 @@ describe('resolvePageRoot', () => { }); assert.strictEqual(result, 'https://nodejs.org/docs/'); - getConfig('web').useAbsoluteURLs = false; + getConfig('html').useAbsoluteURLs = false; }); }); diff --git a/packages/core/src/generators/web/utils/__tests__/relativeOrAbsolute.test.mjs b/packages/react/src/html/utils/__tests__/relativeOrAbsolute.test.mjs similarity index 90% rename from packages/core/src/generators/web/utils/__tests__/relativeOrAbsolute.test.mjs rename to packages/react/src/html/utils/__tests__/relativeOrAbsolute.test.mjs index 998d22e5..e191ff3c 100644 --- a/packages/core/src/generators/web/utils/__tests__/relativeOrAbsolute.test.mjs +++ b/packages/react/src/html/utils/__tests__/relativeOrAbsolute.test.mjs @@ -4,15 +4,16 @@ import { beforeEach, describe, it } from 'node:test'; import { setConfig, default as getConfig, -} from '../../../../utils/configuration/index.mjs'; +} from '@node-core/doc-kit/utils/configuration/index.mjs'; + import { relativeOrAbsolute } from '../relativeOrAbsolute.mjs'; await setConfig({ - target: ['web'], + target: ['html'], version: 'v22.0.0', changelog: [], generators: { - web: { + html: { useAbsoluteURLs: false, baseURL: 'https://nodejs.org/docs', }, @@ -21,7 +22,7 @@ await setConfig({ describe('relativeOrAbsolute (relative mode)', () => { beforeEach(() => { - getConfig('web').useAbsoluteURLs = false; + getConfig('html').useAbsoluteURLs = false; }); it('returns a relative path from a nested page to root', () => { @@ -47,7 +48,7 @@ describe('relativeOrAbsolute (relative mode)', () => { describe('relativeOrAbsolute (absolute mode)', () => { beforeEach(() => { - getConfig('web').useAbsoluteURLs = true; + getConfig('html').useAbsoluteURLs = true; }); it('returns an absolute URL to root', () => { diff --git a/packages/core/src/generators/web/utils/config.mjs b/packages/react/src/html/utils/config.mjs similarity index 90% rename from packages/core/src/generators/web/utils/config.mjs rename to packages/react/src/html/utils/config.mjs index 042f1fcc..b32f937a 100644 --- a/packages/core/src/generators/web/utils/config.mjs +++ b/packages/react/src/html/utils/config.mjs @@ -1,11 +1,11 @@ 'use strict'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs'; +import { getVersionFromSemVer } from '@node-core/doc-kit/utils/generators.mjs'; +import { omitKeys } from '@node-core/doc-kit/utils/misc.mjs'; import { LANGS } from '@node-core/rehype-shiki'; -import getConfig from '../../../utils/configuration/index.mjs'; -import { populate } from '../../../utils/configuration/templates.mjs'; -import { getVersionFromSemVer } from '../../../utils/generators.mjs'; -import { omitKeys } from '../../../utils/misc.mjs'; import { getSortedHeadNodes } from '../../jsx-ast/utils/getSortedHeadNodes.mjs'; /** @@ -74,7 +74,7 @@ export function buildLanguageDisplayNameMap() { * @returns {string} JavaScript source code string with named exports */ export default function createConfigSource(input, server = false) { - const { version: configVersion, ...config } = getConfig('web'); + const { version: configVersion, ...config } = getConfig('html'); const editURL = populate(config.editURL, { ...config, diff --git a/packages/core/src/generators/web/utils/copying.mjs b/packages/react/src/html/utils/copying.mjs similarity index 86% rename from packages/core/src/generators/web/utils/copying.mjs rename to packages/react/src/html/utils/copying.mjs index 20bd5d12..084b6414 100644 --- a/packages/core/src/generators/web/utils/copying.mjs +++ b/packages/react/src/html/utils/copying.mjs @@ -1,7 +1,7 @@ import { cp } from 'node:fs/promises'; import { join, basename } from 'node:path'; -import logger from '../../../logger/index.mjs'; +import logger from '@node-core/doc-kit/logger/index.mjs'; /** * Copies static directories/files defined in `pathsToCopy` to the output directory. @@ -28,7 +28,7 @@ export async function copyStaticAssets(config) { } catch (err) { if (err.code !== 'ENOENT') { logger.error( - `[web-generator] Failed to copy asset from ${src} to ${dest}: ${err.message}` + `[html-generator] Failed to copy asset from ${src} to ${dest}: ${err.message}` ); } } diff --git a/packages/core/src/generators/web/utils/generate.mjs b/packages/react/src/html/utils/generate.mjs similarity index 96% rename from packages/core/src/generators/web/utils/generate.mjs rename to packages/react/src/html/utils/generate.mjs index be2eb23a..1eaef82e 100644 --- a/packages/core/src/generators/web/utils/generate.mjs +++ b/packages/react/src/html/utils/generate.mjs @@ -1,6 +1,7 @@ import { resolve } from 'node:path'; -import getConfig from '../../../utils/configuration/index.mjs'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; + import { JSX_IMPORTS, ROOT } from '../constants.mjs'; /** @@ -54,7 +55,7 @@ export const createImportDeclaration = ( */ export default () => { // User-configured components (for JSX-in-MDX), merged with the built-ins. - const { components } = getConfig('web'); + const { components } = getConfig('html'); // Generate import statements for all JSX components // TODO: Optimize by conditionally including server-only or client-only imports diff --git a/packages/core/src/generators/web/utils/processing.mjs b/packages/react/src/html/utils/processing.mjs similarity index 85% rename from packages/core/src/generators/web/utils/processing.mjs rename to packages/react/src/html/utils/processing.mjs index 483d5559..8a56da3e 100644 --- a/packages/core/src/generators/web/utils/processing.mjs +++ b/packages/react/src/html/utils/processing.mjs @@ -1,8 +1,9 @@ +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs'; + import createConfigSource from './config.mjs'; import createASTBuilder from './generate.mjs'; import { relativeOrAbsolute } from './relativeOrAbsolute.mjs'; -import getConfig from '../../../utils/configuration/index.mjs'; -import { populate } from '../../../utils/configuration/templates.mjs'; import { resolveBundler } from '../bundlers/index.mjs'; import { SPECULATION_RULES } from '../constants.mjs'; import { THEME_SCRIPT } from '../ui/theme-script.mjs'; @@ -10,7 +11,7 @@ import { THEME_SCRIPT } from '../ui/theme-script.mjs'; /** * Creates the virtual imports for one bundle target. * - * @param {Array<{ data: import('../../metadata/types').MetadataEntry }>} sidebarEntries + * @param {Array<{ data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry }>} sidebarEntries * @param {Record} virtualImports * @param {boolean} server * @returns {Record} @@ -38,12 +39,12 @@ export const populateWithEvaluation = (template, config) => { }; /** - * @param {import('../../metadata/types').MetadataEntry} data + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} data * @returns {string} */ export const resolvePageRoot = data => { if (data.synthetic === true) { - const { baseURL, useAbsoluteURLs } = getConfig('web'); + const { baseURL, useAbsoluteURLs } = getConfig('html'); return useAbsoluteURLs ? String(baseURL).replace(/\/?$/, '/') : '/'; } @@ -91,7 +92,7 @@ export const buildHead = ({ meta = [], links = [], html = [] }) => * string upstream (in the `jsx-ast` worker), so the heavy AST never reaches * the main thread — only the code string and page metadata stream in here. * - * @returns {{ add: (item: { data: import('../../metadata/types').MetadataEntry, code: string }) => void, serverCodeMap: Map, clientCodeMap: Map }} + * @returns {{ add: (item: { data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry, code: string }) => void, serverCodeMap: Map, clientCodeMap: Map }} */ export function createCodeConverter() { const { buildServerProgram, buildClientProgram } = createASTBuilder(); @@ -103,7 +104,7 @@ export function createCodeConverter() { /** * Records the server/client programs for a single page's JSX code. * - * @param {{ data: import('../../metadata/types').MetadataEntry, code: string }} item + * @param {{ data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry, code: string }} item */ add: ({ data, code }) => { const fileName = `${data.api}.jsx`; @@ -128,8 +129,8 @@ export function createCodeConverter() { * @param {object} params * @param {Map} params.serverCodeMap - Server-side code per page. * @param {Map} params.clientCodeMap - Client-side code per page. - * @param {Array} params.datas - Per-page metadata, in render order. - * @param {Array<{ data: import('../../metadata/types').MetadataEntry }>} params.sidebarEntries - Entries used to build the sidebar page list (real module pages only). + * @param {Array} params.datas - Per-page metadata, in render order. + * @param {Array<{ data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry }>} params.sidebarEntries - Entries used to build the sidebar page list (real module pages only). * @param {string} params.template - The HTML template string for the output pages. */ export async function processBundles({ @@ -139,7 +140,7 @@ export async function processBundles({ sidebarEntries, template, }) { - const config = getConfig('web'); + const config = getConfig('html'); const bundler = await resolveBundler(config.bundler); const serverPages = await bundler.render({ diff --git a/packages/core/src/generators/web/utils/relativeOrAbsolute.mjs b/packages/react/src/html/utils/relativeOrAbsolute.mjs similarity index 69% rename from packages/core/src/generators/web/utils/relativeOrAbsolute.mjs rename to packages/react/src/html/utils/relativeOrAbsolute.mjs index a37be0e3..cc85803d 100644 --- a/packages/core/src/generators/web/utils/relativeOrAbsolute.mjs +++ b/packages/react/src/html/utils/relativeOrAbsolute.mjs @@ -1,5 +1,5 @@ -import getConfig from '../../../utils/configuration/index.mjs'; -import { relative } from '../../../utils/url.mjs'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { relative } from '@node-core/doc-kit/utils/url.mjs'; /** * Returns an absolute URL (based on baseURL) or a relative URL, @@ -10,7 +10,7 @@ import { relative } from '../../../utils/url.mjs'; * @returns {string} */ export const relativeOrAbsolute = (to, from) => { - const { useAbsoluteURLs, baseURL } = getConfig('web'); + const { useAbsoluteURLs, baseURL } = getConfig('html'); return useAbsoluteURLs ? new URL(`.${to}`, baseURL.replace(/\/?$/, '/')).href diff --git a/packages/core/src/generators/jsx-ast/README.md b/packages/react/src/jsx-ast/README.md similarity index 100% rename from packages/core/src/generators/jsx-ast/README.md rename to packages/react/src/jsx-ast/README.md diff --git a/packages/core/src/generators/jsx-ast/__tests__/generate.test.mjs b/packages/react/src/jsx-ast/__tests__/generate.test.mjs similarity index 96% rename from packages/core/src/generators/jsx-ast/__tests__/generate.test.mjs rename to packages/react/src/jsx-ast/__tests__/generate.test.mjs index e1f52e76..4894c7e7 100644 --- a/packages/core/src/generators/jsx-ast/__tests__/generate.test.mjs +++ b/packages/react/src/jsx-ast/__tests__/generate.test.mjs @@ -1,7 +1,10 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; -import getConfig, { setConfig } from '../../../utils/configuration/index.mjs'; +import getConfig, { + setConfig, +} from '@node-core/doc-kit/utils/configuration/index.mjs'; + import { generate, processChunk } from '../generate.mjs'; const createEntry = (api, name, { stabilityIndex = '2' } = {}) => { diff --git a/packages/core/src/generators/jsx-ast/constants.mjs b/packages/react/src/jsx-ast/constants.mjs similarity index 99% rename from packages/core/src/generators/jsx-ast/constants.mjs rename to packages/react/src/jsx-ast/constants.mjs index dddad667..ffeec38c 100644 --- a/packages/core/src/generators/jsx-ast/constants.mjs +++ b/packages/react/src/jsx-ast/constants.mjs @@ -1,4 +1,4 @@ -import { JSX_IMPORTS } from '../web/constants.mjs'; +import { JSX_IMPORTS } from '../html/constants.mjs'; /** * UI classes for Node.js API stability levels diff --git a/packages/core/src/generators/jsx-ast/generate.mjs b/packages/react/src/jsx-ast/generate.mjs similarity index 91% rename from packages/core/src/generators/jsx-ast/generate.mjs rename to packages/react/src/jsx-ast/generate.mjs index 055e0efb..89f69e93 100644 --- a/packages/core/src/generators/jsx-ast/generate.mjs +++ b/packages/react/src/jsx-ast/generate.mjs @@ -1,3 +1,5 @@ +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { groupNodesByModule } from '@node-core/doc-kit/utils/generators.mjs'; import { jsx, toJs } from 'estree-util-to-js'; import buildContent from './utils/buildContent.mjs'; @@ -5,8 +7,6 @@ import { getSortedHeadNodes } from './utils/getSortedHeadNodes.mjs'; import { buildNotFoundPage } from './utils/synthetic/404.mjs'; import { buildAllPage } from './utils/synthetic/all.mjs'; import { buildIndexPage } from './utils/synthetic/index.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; -import { groupNodesByModule } from '../../utils/generators.mjs'; /** * Builds the `{ head, entries }` page descriptors for all configured synthetic @@ -14,7 +14,7 @@ import { groupNodesByModule } from '../../utils/generators.mjs'; * runs later in a worker (via `processChunk`), so the very large synthetic * `all` page is never built on the main thread. * - * @param {Array} input + * @param {Array} input */ const buildSyntheticDescriptors = input => { const config = getConfig('jsx-ast'); diff --git a/packages/core/src/generators/jsx-ast/index.mjs b/packages/react/src/jsx-ast/index.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/index.mjs rename to packages/react/src/jsx-ast/index.mjs diff --git a/packages/core/src/generators/jsx-ast/types.d.ts b/packages/react/src/jsx-ast/types.d.ts similarity index 82% rename from packages/core/src/generators/jsx-ast/types.d.ts rename to packages/react/src/jsx-ast/types.d.ts index 672c5a4f..cffbb835 100644 --- a/packages/core/src/generators/jsx-ast/types.d.ts +++ b/packages/react/src/jsx-ast/types.d.ts @@ -1,4 +1,4 @@ -import type { MetadataEntry } from '../metadata/types'; +import type { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types'; import type { JSXContent } from './utils/buildContent.mjs'; export type Generator = GeneratorMetadata< diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/ast.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/ast.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/__tests__/ast.test.mjs rename to packages/react/src/jsx-ast/utils/__tests__/ast.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/buildBarProps.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs rename to packages/react/src/jsx-ast/utils/__tests__/buildBarProps.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/buildContent.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/buildContent.test.mjs similarity index 95% rename from packages/core/src/generators/jsx-ast/utils/__tests__/buildContent.test.mjs rename to packages/react/src/jsx-ast/utils/__tests__/buildContent.test.mjs index afb86405..e1c21538 100644 --- a/packages/core/src/generators/jsx-ast/utils/__tests__/buildContent.test.mjs +++ b/packages/react/src/jsx-ast/utils/__tests__/buildContent.test.mjs @@ -1,7 +1,8 @@ import assert from 'node:assert/strict'; import { describe, it } from 'node:test'; -import { setConfig } from '../../../../utils/configuration/index.mjs'; +import { setConfig } from '@node-core/doc-kit/utils/configuration/index.mjs'; + import { transformHeadingNode } from '../buildContent.mjs'; const heading = { diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/overloads.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/overloads.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/__tests__/overloads.test.mjs rename to packages/react/src/jsx-ast/utils/__tests__/overloads.test.mjs diff --git a/packages/core/src/utils/__tests__/remark.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/remark.test.mjs similarity index 100% rename from packages/core/src/utils/__tests__/remark.test.mjs rename to packages/react/src/jsx-ast/utils/__tests__/remark.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/signature.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/signature.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/__tests__/signature.test.mjs rename to packages/react/src/jsx-ast/utils/__tests__/signature.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/types.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/types.test.mjs similarity index 99% rename from packages/core/src/generators/jsx-ast/utils/__tests__/types.test.mjs rename to packages/react/src/jsx-ast/utils/__tests__/types.test.mjs index 0c4a7c3e..de963d4f 100644 --- a/packages/core/src/generators/jsx-ast/utils/__tests__/types.test.mjs +++ b/packages/react/src/jsx-ast/utils/__tests__/types.test.mjs @@ -2,7 +2,7 @@ import assert from 'node:assert/strict'; import { describe, it, mock } from 'node:test'; // Mock remark -mock.module('../../../../utils/remark.mjs', { +mock.module('../remark.mjs', { namedExports: { getRemarkRecma: () => ({ runSync: () => ({ diff --git a/packages/core/src/generators/jsx-ast/utils/ast.mjs b/packages/react/src/jsx-ast/utils/ast.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/ast.mjs rename to packages/react/src/jsx-ast/utils/ast.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/buildBarProps.mjs b/packages/react/src/jsx-ast/utils/buildBarProps.mjs similarity index 83% rename from packages/core/src/generators/jsx-ast/utils/buildBarProps.mjs rename to packages/react/src/jsx-ast/utils/buildBarProps.mjs index d535c30a..367d96ea 100644 --- a/packages/core/src/generators/jsx-ast/utils/buildBarProps.mjs +++ b/packages/react/src/jsx-ast/utils/buildBarProps.mjs @@ -12,7 +12,7 @@ const FUNCTION_HEADING_TYPES = new Set(['method', 'ctor', 'classMethod']); /** * Generate a combined plain text string from all MDAST entries for estimating reading time. * - * @param {Array} entries - API documentation entries + * @param {Array} entries - API documentation entries */ export const extractTextContent = entries => { return entries.reduce((acc, entry) => { @@ -25,7 +25,7 @@ export const extractTextContent = entries => { /** * Determines if an entry should be included in the Table of Contents. - * @param {import('../../metadata/types').MetadataEntry} entry + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry */ const shouldIncludeEntryInToC = ({ heading }) => // Only include headings with text, @@ -41,7 +41,7 @@ const shouldIncludeEntryInToC = ({ heading }) => * other headings keep their plain text, with CLI flags / env vars and leading * prefixes (i.e. `Class:`) stripped. * - * @param {import('../../metadata/types').HeadingData} data + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingData} data */ const headingLabel = data => { if (FUNCTION_HEADING_TYPES.has(data.type)) { @@ -70,7 +70,7 @@ const headingLabel = data => { /** * Extracts and formats heading information from an API documentation entry. - * @param {import('../../metadata/types').MetadataEntry} entry + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry */ const extractHeading = entry => { const data = entry.heading.data; @@ -88,7 +88,7 @@ const extractHeading = entry => { * Build the list of heading metadata for sidebar navigation. Overload headings * are dropped so each function contributes a single entry. * - * @param {Array} entries - All API metadata entries + * @param {Array} entries - All API metadata entries */ export const extractHeadings = entries => entries diff --git a/packages/core/src/generators/jsx-ast/utils/buildContent.mjs b/packages/react/src/jsx-ast/utils/buildContent.mjs similarity index 83% rename from packages/core/src/generators/jsx-ast/utils/buildContent.mjs rename to packages/react/src/jsx-ast/utils/buildContent.mjs index dd621eec..3b1ac769 100644 --- a/packages/core/src/generators/jsx-ast/utils/buildContent.mjs +++ b/packages/react/src/jsx-ast/utils/buildContent.mjs @@ -1,5 +1,13 @@ 'use strict'; +import { enforceArray } from '@node-core/doc-kit/utils/array.mjs'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { + GITHUB_BLOB_URL, + populate, +} from '@node-core/doc-kit/utils/configuration/templates.mjs'; +import { omitKeys } from '@node-core/doc-kit/utils/misc.mjs'; +import { UNIST } from '@node-core/doc-kit/utils/queries/index.mjs'; import { h as createElement } from 'hastscript'; import { slice } from 'mdast-util-slice-markdown'; import readingTime from 'reading-time'; @@ -9,9 +17,8 @@ import { SKIP, visit } from 'unist-util-visit'; import { createJSXElement } from './ast.mjs'; import { extractHeadings, extractTextContent } from './buildBarProps.mjs'; import { annotateOverloads } from './overloads.mjs'; -import { enforceArray } from '../../../utils/array.mjs'; -import { omitKeys } from '../../../utils/misc.mjs'; -import { JSX_IMPORTS } from '../../web/constants.mjs'; +import { getRemarkRecma as remark } from './remark.mjs'; +import { JSX_IMPORTS } from '../../html/constants.mjs'; import { STABILITY_LEVELS, LIFECYCLE_LABELS, @@ -27,17 +34,10 @@ import { createSignatureTable, getFullName, } from './signature.mjs'; -import getConfig from '../../../utils/configuration/index.mjs'; -import { - GITHUB_BLOB_URL, - populate, -} from '../../../utils/configuration/templates.mjs'; -import { UNIST } from '../../../utils/queries/index.mjs'; -import { getRemarkRecma as remark } from '../../../utils/remark.mjs'; /** * Processes lifecycle and change history data into a sorted array of change entries. - * @param {import('../../metadata/types').MetadataEntry} entry - The metadata entry + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The metadata entry */ export const gatherChangeEntries = entry => { // Lifecycle changes (e.g., added, deprecated) @@ -61,7 +61,7 @@ export const gatherChangeEntries = entry => { /** * Creates a JSX ChangeHistory element or returns null if no changes. - * @param {import('../../metadata/types').MetadataEntry} entry - The metadata entry + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The metadata entry */ export const createChangeElement = entry => { const changes = gatherChangeEntries(entry); @@ -128,7 +128,7 @@ export const extractHeadingContent = content => { /** * Creates a heading wrapper element with anchors, icons, and optional change history. - * @param {import('../../metadata/types').HeadingNode} content - The content node to extract text from + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} content - The content node to extract text from * @param {import('unist').Node|null} changeElement - The change history element, if available */ export const createHeadingElement = (content, changeElement) => { @@ -166,7 +166,7 @@ export const createHeadingElement = (content, changeElement) => { /** * Converts a stability note node to an AlertBox JSX element - * @param {import('../../metadata/types').StabilityNode} node - The stability node to transform + * @param {import('@node-core/doc-kit/generators/metadata/types').StabilityNode} node - The stability node to transform * @param {number} index - The index of the node in its parent's children array * @param {import('unist').Parent} parent - The parent node containing the stability node */ @@ -200,8 +200,8 @@ const getLevelFromDeprecationType = typeText => { /** * Transforms a heading node by injecting metadata, source links, and signatures. - * @param {import('../../metadata/types').MetadataEntry} entry - The API metadata entry - * @param {import('../../metadata/types').HeadingNode} node - The heading node to transform + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The API metadata entry + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} node - The heading node to transform * @param {number} index - The index of the node in its parent's children array * @param {import('unist').Parent} parent - The parent node containing the heading */ @@ -250,7 +250,7 @@ export const transformHeadingNode = async (entry, node, index, parent) => { /** * Processes a single API documentation entry's content - * @param {import('../../metadata/types').MetadataEntry} entry - The API metadata entry to process + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The API metadata entry to process */ export const processEntry = entry => { // Visit and transform stability nodes @@ -276,7 +276,7 @@ export const processEntry = entry => { /** * Builds the overall document layout tree - * @param {Array} entries - API documentation metadata entries + * @param {Array} entries - API documentation metadata entries * @param {Object} metadata - Raw page metadata from the head entry */ export const createDocumentLayout = (entries, metadata) => { @@ -295,11 +295,11 @@ export const createDocumentLayout = (entries, metadata) => { }; /** - * @typedef {import('estree').Node & { data: import('../../metadata/types').MetadataEntry }} JSXContent + * @typedef {import('estree').Node & { data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry }} JSXContent * * Transforms API metadata entries into processed MDX content - * @param {Array} metadataEntries - API documentation metadata entries - * @param {import('../../metadata/types').MetadataEntry} head - Main API metadata entry with version information + * @param {Array} metadataEntries - API documentation metadata entries + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} head - Main API metadata entry with version information * @returns {Promise} */ const buildContent = async (metadataEntries, head) => { diff --git a/packages/core/src/generators/jsx-ast/utils/getSortedHeadNodes.mjs b/packages/react/src/jsx-ast/utils/getSortedHeadNodes.mjs similarity index 66% rename from packages/core/src/generators/jsx-ast/utils/getSortedHeadNodes.mjs rename to packages/react/src/jsx-ast/utils/getSortedHeadNodes.mjs index c0f0c54c..b28460cc 100644 --- a/packages/core/src/generators/jsx-ast/utils/getSortedHeadNodes.mjs +++ b/packages/react/src/jsx-ast/utils/getSortedHeadNodes.mjs @@ -4,8 +4,8 @@ import { OVERRIDDEN_POSITIONS } from '../constants.mjs'; /** * Sorts entries by OVERRIDDEN_POSITIONS and then heading name. - * @param {import('../../metadata/types').MetadataEntry} a - * @param {import('../../metadata/types').MetadataEntry} b + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} a + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} b * @returns {number} */ const headingSortFn = (a, b) => { @@ -29,8 +29,8 @@ const headingSortFn = (a, b) => { /** * Filters and sorts entries by OVERRIDDEN_POSITIONS and then heading name. - * @param {Array} entries - * @returns {Array} + * @param {Array} entries + * @returns {Array} */ export const getSortedHeadNodes = entries => entries.filter(node => node.heading.depth === 1).toSorted(headingSortFn); diff --git a/packages/core/src/generators/jsx-ast/utils/overloads.mjs b/packages/react/src/jsx-ast/utils/overloads.mjs similarity index 78% rename from packages/core/src/generators/jsx-ast/utils/overloads.mjs rename to packages/react/src/jsx-ast/utils/overloads.mjs index b35ad093..f6feee03 100644 --- a/packages/core/src/generators/jsx-ast/utils/overloads.mjs +++ b/packages/react/src/jsx-ast/utils/overloads.mjs @@ -8,8 +8,8 @@ const OVERLOADABLE_TYPES = new Set(['method', 'ctor', 'classMethod']); * Two headings document the same function (i.e. are overloads of one another) * when they sit at the same depth and share the same resolved name and type. * - * @param {import('../../metadata/types').HeadingNode} a - * @param {import('../../metadata/types').HeadingNode} b + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} a + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} b */ const isSameFunction = (a, b) => a.depth === b.depth && @@ -26,8 +26,8 @@ const isSameFunction = (a, b) => * rendering in full on the page. The first (most stable) heading is left as-is, * and the ToC links to its existing anchor. * - * @param {Array} entries - Page entries, in render order. - * @returns {Array} The same entries (mutated). + * @param {Array} entries - Page entries, in render order. + * @returns {Array} The same entries (mutated). */ export const annotateOverloads = entries => { for (let i = 0; i < entries.length; i++) { diff --git a/packages/core/src/generators/jsx-ast/utils/plugins/__tests__/alerts.test.mjs b/packages/react/src/jsx-ast/utils/plugins/__tests__/alerts.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/plugins/__tests__/alerts.test.mjs rename to packages/react/src/jsx-ast/utils/plugins/__tests__/alerts.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/plugins/__tests__/transformer.test.mjs b/packages/react/src/jsx-ast/utils/plugins/__tests__/transformer.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/plugins/__tests__/transformer.test.mjs rename to packages/react/src/jsx-ast/utils/plugins/__tests__/transformer.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/plugins/alerts.mjs b/packages/react/src/jsx-ast/utils/plugins/alerts.mjs similarity index 97% rename from packages/core/src/generators/jsx-ast/utils/plugins/alerts.mjs rename to packages/react/src/jsx-ast/utils/plugins/alerts.mjs index 1abe1940..4ede03e5 100644 --- a/packages/core/src/generators/jsx-ast/utils/plugins/alerts.mjs +++ b/packages/react/src/jsx-ast/utils/plugins/alerts.mjs @@ -2,7 +2,7 @@ import { SKIP, visit } from 'unist-util-visit'; -import { JSX_IMPORTS } from '../../../web/constants.mjs'; +import { JSX_IMPORTS } from '../../../html/constants.mjs'; import { ALERT_MARKER, GITHUB_ALERT_TYPES } from '../../constants.mjs'; import { createJSXElement } from '../ast.mjs'; diff --git a/packages/core/src/generators/jsx-ast/utils/plugins/transformer.mjs b/packages/react/src/jsx-ast/utils/plugins/transformer.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/plugins/transformer.mjs rename to packages/react/src/jsx-ast/utils/plugins/transformer.mjs diff --git a/packages/react/src/jsx-ast/utils/remark.mjs b/packages/react/src/jsx-ast/utils/remark.mjs new file mode 100644 index 00000000..889244f3 --- /dev/null +++ b/packages/react/src/jsx-ast/utils/remark.mjs @@ -0,0 +1,80 @@ +'use strict'; + +import { highlighter } from '@node-core/doc-kit/utils/highlighter.mjs'; +import { lazy } from '@node-core/doc-kit/utils/misc.mjs'; +import { typeAnnotationToHighlightedHast } from '@node-core/doc-kit/utils/type-annotations/hast.mjs'; +import rehypeShikiji from '@node-core/rehype-shiki/plugin'; +import recmaJsx from 'recma-jsx'; +import recmaStringify from 'recma-stringify'; +import rehypeRaw from 'rehype-raw'; +import rehypeRecma from 'rehype-recma'; +import remarkParse from 'remark-parse'; +import remarkRehype from 'remark-rehype'; +import { unified } from 'unified'; +import { visit } from 'unist-util-visit'; + +import { AST_NODE_TYPES } from '../constants.mjs'; +import transformAlerts from './plugins/alerts.mjs'; +import transformElements from './plugins/transformer.mjs'; + +const passThrough = ['element', ...Object.values(AST_NODE_TYPES.MDX)]; +const codeMetaProperty = 'codeMeta'; + +/** + * Stores fenced code metadata on properties before rehypeRaw reparses the tree. + */ +const preserveCodeMeta = () => tree => { + visit(tree, 'element', node => { + const meta = node.data?.meta; + + if (node.tagName === 'code' && typeof meta === 'string') { + node.properties ||= {}; + node.properties[codeMetaProperty] = meta; + } + }); +}; + +/** + * Restores fenced code metadata so the Shiki plugin can read displayName. + */ +const restoreCodeMeta = () => tree => { + visit(tree, 'element', node => { + const meta = node.properties?.[codeMetaProperty]; + + if (node.tagName === 'code' && typeof meta === 'string') { + node.data = { ...node.data, meta }; + delete node.properties[codeMetaProperty]; + } + }); +}; + +const singletonShiki = await rehypeShikiji({ highlighter }); + +/** + * Retrieves an instance of Remark configured to output JSX code. + * including parsing Code Boxes with syntax highlighting + */ +export const getRemarkRecma = lazy(() => + unified() + .use(remarkParse) + .use(transformAlerts) + // We make Rehype ignore existing HTML nodes, and JSX nodes + // as these are nodes we manually created during the generation process + // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown + // and we trust the sources of the Markdown files + .use(remarkRehype, { + allowDangerousHtml: true, + passThrough, + // The web pipeline gets Shiki-highlighted types with embedded links + handlers: { typeAnnotation: typeAnnotationToHighlightedHast }, + }) + .use(preserveCodeMeta) + // Any `raw` HTML in the markdown must be converted to AST in order for Recma to understand it + .use(rehypeRaw, { passThrough }) + .use(restoreCodeMeta) + .use(() => singletonShiki) + .use(transformElements) + .use(rehypeRecma) + .use(recmaJsx) + .use(recmaStringify) +); diff --git a/packages/core/src/generators/jsx-ast/utils/signature.mjs b/packages/react/src/jsx-ast/utils/signature.mjs similarity index 83% rename from packages/core/src/generators/jsx-ast/utils/signature.mjs rename to packages/react/src/jsx-ast/utils/signature.mjs index f7220d02..8ffedcc4 100644 --- a/packages/core/src/generators/jsx-ast/utils/signature.mjs +++ b/packages/react/src/jsx-ast/utils/signature.mjs @@ -1,18 +1,18 @@ +import { highlighter } from '@node-core/doc-kit/utils/highlighter.mjs'; +import { UNIST } from '@node-core/doc-kit/utils/queries/index.mjs'; +import { parseListItem } from '@node-core/doc-kit/utils/signature/parseList.mjs'; +import parseSignature from '@node-core/doc-kit/utils/signature/parseSignature.mjs'; import { h as createElement } from 'hastscript'; import { createJSXElement } from './ast.mjs'; import { parseListIntoProperties } from './types.mjs'; -import { highlighter } from '../../../utils/highlighter.mjs'; -import { UNIST } from '../../../utils/queries/index.mjs'; -import { parseListItem } from '../../../utils/signature/parseList.mjs'; -import parseSignature from '../../../utils/signature/parseSignature.mjs'; -import { JSX_IMPORTS } from '../../web/constants.mjs'; +import { JSX_IMPORTS } from '../../html/constants.mjs'; /** * Generates a string representation of a function or class signature. * * @param {string} functionName - The name of the function or class. - * @param {import('../../../utils/signature/types').MethodSignature} signature - The parsed signature object. + * @param {import('@node-core/doc-kit/utils/signature/types').MethodSignature} signature - The parsed signature object. * @param {string} prefix - Optional prefix, i.e. `'new '` for constructors. */ export const generateSignature = ( @@ -52,7 +52,7 @@ export const generateSignature = ( * Creates a syntax-highlighted code block for a signature using rehype-shiki. * * @param {string} functionName - The function name to display. - * @param {import('../../../utils/signature/types').MethodSignature} signature - Signature object with parameter and return type info. + * @param {import('@node-core/doc-kit/utils/signature/types').MethodSignature} signature - Signature object with parameter and return type info. * @param {string} prefix - Optional prefix like `'new '`. */ export const createSignatureCodeBlock = (functionName, signature, prefix) => { @@ -66,7 +66,7 @@ export const createSignatureCodeBlock = (functionName, signature, prefix) => { * Infers the "real" function name from a heading node. * Useful when auto-generated headings differ from code tokens. * - * @param {import('../../metadata/types').HeadingData} heading - Metadata with name and text fields. + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingData} heading - Metadata with name and text fields. * @param {any} fallback - Fallback value if inference fails. */ export const getFullName = ({ name, text }, fallback = name) => { @@ -91,7 +91,7 @@ export const getFullName = ({ name, text }, fallback = name) => { * Mutates the `children` array by injecting the signature HAST node. * * @param {import('@types/mdast').Parent} parent - The parent MDAST node (usually a section). - * @param {import('../../metadata/types').HeadingNode} heading - The heading node with metadata. + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} heading - The heading node with metadata. * @param {number} idx - The index at which the heading occurs in `parent.children`. */ export const insertSignatureCodeBlock = ({ children }, { data }, idx) => { diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/404.mjs b/packages/react/src/jsx-ast/utils/synthetic/404.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/synthetic/404.mjs rename to packages/react/src/jsx-ast/utils/synthetic/404.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/404.test.mjs b/packages/react/src/jsx-ast/utils/synthetic/__tests__/404.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/404.test.mjs rename to packages/react/src/jsx-ast/utils/synthetic/__tests__/404.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/all.test.mjs b/packages/react/src/jsx-ast/utils/synthetic/__tests__/all.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/all.test.mjs rename to packages/react/src/jsx-ast/utils/synthetic/__tests__/all.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/index.test.mjs b/packages/react/src/jsx-ast/utils/synthetic/__tests__/index.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/index.test.mjs rename to packages/react/src/jsx-ast/utils/synthetic/__tests__/index.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/synthetic.test.mjs b/packages/react/src/jsx-ast/utils/synthetic/__tests__/synthetic.test.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/synthetic.test.mjs rename to packages/react/src/jsx-ast/utils/synthetic/__tests__/synthetic.test.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/all.mjs b/packages/react/src/jsx-ast/utils/synthetic/all.mjs similarity index 70% rename from packages/core/src/generators/jsx-ast/utils/synthetic/all.mjs rename to packages/react/src/jsx-ast/utils/synthetic/all.mjs index a25894ed..79537e4f 100644 --- a/packages/core/src/generators/jsx-ast/utils/synthetic/all.mjs +++ b/packages/react/src/jsx-ast/utils/synthetic/all.mjs @@ -5,7 +5,7 @@ import { createSyntheticHead } from './synthetic.mjs'; /** * Builds the page descriptor for `all.html` * - * @param {Array} entries + * @param {Array} entries */ export const buildAllPage = entries => ({ head: createSyntheticHead('all', 'All'), diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/index.mjs b/packages/react/src/jsx-ast/utils/synthetic/index.mjs similarity index 88% rename from packages/core/src/generators/jsx-ast/utils/synthetic/index.mjs rename to packages/react/src/jsx-ast/utils/synthetic/index.mjs index 423d11a0..f040e98b 100644 --- a/packages/core/src/generators/jsx-ast/utils/synthetic/index.mjs +++ b/packages/react/src/jsx-ast/utils/synthetic/index.mjs @@ -3,7 +3,7 @@ import { h as createElement } from 'hastscript'; import { createSyntheticHead, wrapAsEntry } from './synthetic.mjs'; -import { JSX_IMPORTS } from '../../../web/constants.mjs'; +import { JSX_IMPORTS } from '../../../html/constants.mjs'; import { createJSXElement } from '../ast.mjs'; import { getSortedHeadNodes } from '../getSortedHeadNodes.mjs'; @@ -28,7 +28,7 @@ const getStabilityBadgeKind = index => * Builds the Stability Overview table from module heads that declare a * top-level stability index, mirroring the `legacy-html-all` overview. * - * @param {Array} headEntries + * @param {Array} headEntries */ export const buildStabilityOverview = headEntries => createElement('table', [ @@ -64,7 +64,7 @@ export const buildStabilityOverview = headEntries => /** * Builds the page descriptor for `index.html` * - * @param {Array} entries + * @param {Array} entries */ export const buildIndexPage = entries => { const head = createSyntheticHead('index', 'Index'); diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/synthetic.mjs b/packages/react/src/jsx-ast/utils/synthetic/synthetic.mjs similarity index 100% rename from packages/core/src/generators/jsx-ast/utils/synthetic/synthetic.mjs rename to packages/react/src/jsx-ast/utils/synthetic/synthetic.mjs diff --git a/packages/core/src/generators/jsx-ast/utils/types.mjs b/packages/react/src/jsx-ast/utils/types.mjs similarity index 90% rename from packages/core/src/generators/jsx-ast/utils/types.mjs rename to packages/react/src/jsx-ast/utils/types.mjs index 706f7dd9..1d5867b8 100644 --- a/packages/core/src/generators/jsx-ast/utils/types.mjs +++ b/packages/react/src/jsx-ast/utils/types.mjs @@ -1,9 +1,9 @@ +import { QUERIES, UNIST } from '@node-core/doc-kit/utils/queries/index.mjs'; +import { DEFAULT_EXPRESSION } from '@node-core/doc-kit/utils/signature/constants.mjs'; +import { transformNodesToString } from '@node-core/doc-kit/utils/unist.mjs'; import { u as createTree } from 'unist-builder'; -import { QUERIES, UNIST } from '../../../utils/queries/index.mjs'; -import { getRemarkRecma as remark } from '../../../utils/remark.mjs'; -import { DEFAULT_EXPRESSION } from '../../../utils/signature/constants.mjs'; -import { transformNodesToString } from '../../../utils/unist.mjs'; +import { getRemarkRecma as remark } from './remark.mjs'; import { TRIMMABLE_PADDING_REGEX } from '../constants.mjs'; /** diff --git a/packages/core/src/generators/llms-txt/README.md b/packages/react/src/llms-txt/README.md similarity index 100% rename from packages/core/src/generators/llms-txt/README.md rename to packages/react/src/llms-txt/README.md diff --git a/packages/core/src/generators/llms-txt/generate.mjs b/packages/react/src/llms-txt/generate.mjs similarity index 84% rename from packages/core/src/generators/llms-txt/generate.mjs rename to packages/react/src/llms-txt/generate.mjs index 0610b73c..730cbcdc 100644 --- a/packages/core/src/generators/llms-txt/generate.mjs +++ b/packages/react/src/llms-txt/generate.mjs @@ -3,9 +3,10 @@ import { readFile } from 'node:fs/promises'; import { join } from 'node:path'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { writeFile } from '@node-core/doc-kit/utils/file.mjs'; + import { buildApiDocLink } from './utils/buildApiDocLink.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; -import { writeFile } from '../../utils/file.mjs'; /** * Generates a llms.txt file diff --git a/packages/core/src/generators/llms-txt/index.mjs b/packages/react/src/llms-txt/index.mjs similarity index 100% rename from packages/core/src/generators/llms-txt/index.mjs rename to packages/react/src/llms-txt/index.mjs diff --git a/packages/core/src/generators/llms-txt/template.txt b/packages/react/src/llms-txt/template.txt similarity index 100% rename from packages/core/src/generators/llms-txt/template.txt rename to packages/react/src/llms-txt/template.txt diff --git a/packages/core/src/generators/llms-txt/types.d.ts b/packages/react/src/llms-txt/types.d.ts similarity index 66% rename from packages/core/src/generators/llms-txt/types.d.ts rename to packages/react/src/llms-txt/types.d.ts index 85c720ed..d84cf4e5 100644 --- a/packages/core/src/generators/llms-txt/types.d.ts +++ b/packages/react/src/llms-txt/types.d.ts @@ -1,4 +1,4 @@ -import { MetadataEntry } from '../metadata/types'; +import { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types'; export type Generator = GeneratorMetadata< { diff --git a/packages/core/src/generators/llms-txt/utils/__tests__/buildApiDocLink.test.mjs b/packages/react/src/llms-txt/utils/__tests__/buildApiDocLink.test.mjs similarity index 100% rename from packages/core/src/generators/llms-txt/utils/__tests__/buildApiDocLink.test.mjs rename to packages/react/src/llms-txt/utils/__tests__/buildApiDocLink.test.mjs diff --git a/packages/core/src/generators/llms-txt/utils/buildApiDocLink.mjs b/packages/react/src/llms-txt/utils/buildApiDocLink.mjs similarity index 70% rename from packages/core/src/generators/llms-txt/utils/buildApiDocLink.mjs rename to packages/react/src/llms-txt/utils/buildApiDocLink.mjs index 271249d0..e061d513 100644 --- a/packages/core/src/generators/llms-txt/utils/buildApiDocLink.mjs +++ b/packages/react/src/llms-txt/utils/buildApiDocLink.mjs @@ -1,12 +1,12 @@ -import { populate } from '../../../utils/configuration/templates.mjs'; -import { transformNodeToString } from '../../../utils/unist.mjs'; +import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs'; +import { transformNodeToString } from '@node-core/doc-kit/utils/unist.mjs'; /** * Retrieves the description of a given API doc entry. It first checks whether * the entry has a llm_description property. If not, it extracts the first * paragraph from the entry's content. * - * @param {import('../../metadata/types').MetadataEntry} entry + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry * @returns {string} */ export const getEntryDescription = entry => { @@ -32,8 +32,8 @@ export const getEntryDescription = entry => { /** * Builds a markdown link for an API doc entry * - * @param {import('../../metadata/types').MetadataEntry} entry - * @param {import('../../../utils/configuration/types').Configuration['llms-txt']} + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry + * @param {import('@node-core/doc-kit/utils/configuration/types').Configuration['llms-txt']} * @returns {string} */ export const buildApiDocLink = (entry, config) => { diff --git a/packages/core/src/generators/orama-db/README.md b/packages/react/src/orama-db/README.md similarity index 100% rename from packages/core/src/generators/orama-db/README.md rename to packages/react/src/orama-db/README.md diff --git a/packages/core/src/generators/orama-db/constants.mjs b/packages/react/src/orama-db/constants.mjs similarity index 100% rename from packages/core/src/generators/orama-db/constants.mjs rename to packages/react/src/orama-db/constants.mjs diff --git a/packages/core/src/generators/orama-db/generate.mjs b/packages/react/src/orama-db/generate.mjs similarity index 83% rename from packages/core/src/generators/orama-db/generate.mjs rename to packages/react/src/orama-db/generate.mjs index e8ec639d..a7f1b663 100644 --- a/packages/core/src/generators/orama-db/generate.mjs +++ b/packages/react/src/orama-db/generate.mjs @@ -2,14 +2,14 @@ import { join } from 'node:path'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { writeFile } from '@node-core/doc-kit/utils/file.mjs'; +import { groupNodesByModule } from '@node-core/doc-kit/utils/generators.mjs'; +import { transformNodeToString } from '@node-core/doc-kit/utils/unist.mjs'; import { create, save, insertMultiple } from '@orama/orama'; import { SCHEMA } from './constants.mjs'; import { buildHierarchicalTitle } from './utils/title.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; -import { writeFile } from '../../utils/file.mjs'; -import { groupNodesByModule } from '../../utils/generators.mjs'; -import { transformNodeToString } from '../../utils/unist.mjs'; /** * Generates the Orama database. diff --git a/packages/core/src/generators/orama-db/index.mjs b/packages/react/src/orama-db/index.mjs similarity index 100% rename from packages/core/src/generators/orama-db/index.mjs rename to packages/react/src/orama-db/index.mjs diff --git a/packages/core/src/generators/orama-db/types.d.ts b/packages/react/src/orama-db/types.d.ts similarity index 87% rename from packages/core/src/generators/orama-db/types.d.ts rename to packages/react/src/orama-db/types.d.ts index 8c8c14db..6f6fbca7 100644 --- a/packages/core/src/generators/orama-db/types.d.ts +++ b/packages/react/src/orama-db/types.d.ts @@ -1,5 +1,5 @@ import type { Orama, RawData } from '@orama/orama'; -import type { MetadataEntry } from '../metadata/types'; +import type { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types'; /** * Schema for the Orama database entry diff --git a/packages/core/src/generators/orama-db/utils/__tests__/title.test.mjs b/packages/react/src/orama-db/utils/__tests__/title.test.mjs similarity index 100% rename from packages/core/src/generators/orama-db/utils/__tests__/title.test.mjs rename to packages/react/src/orama-db/utils/__tests__/title.test.mjs diff --git a/packages/core/src/generators/orama-db/utils/title.mjs b/packages/react/src/orama-db/utils/title.mjs similarity index 100% rename from packages/core/src/generators/orama-db/utils/title.mjs rename to packages/react/src/orama-db/utils/title.mjs diff --git a/packages/core/src/generators/sitemap/README.md b/packages/react/src/sitemap/README.md similarity index 100% rename from packages/core/src/generators/sitemap/README.md rename to packages/react/src/sitemap/README.md diff --git a/packages/core/src/generators/sitemap/entry-template.xml b/packages/react/src/sitemap/entry-template.xml similarity index 100% rename from packages/core/src/generators/sitemap/entry-template.xml rename to packages/react/src/sitemap/entry-template.xml diff --git a/packages/core/src/generators/sitemap/generate.mjs b/packages/react/src/sitemap/generate.mjs similarity index 86% rename from packages/core/src/generators/sitemap/generate.mjs rename to packages/react/src/sitemap/generate.mjs index 9ec9786a..808c0ca0 100644 --- a/packages/core/src/generators/sitemap/generate.mjs +++ b/packages/react/src/sitemap/generate.mjs @@ -3,10 +3,11 @@ import { readFile } from 'node:fs/promises'; import { join } from 'node:path'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs'; +import { writeFile } from '@node-core/doc-kit/utils/file.mjs'; + import { createPageSitemapEntry } from './utils/createPageSitemapEntry.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; -import { populate } from '../../utils/configuration/templates.mjs'; -import { writeFile } from '../../utils/file.mjs'; /** * Generates a sitemap.xml file diff --git a/packages/core/src/generators/sitemap/index.mjs b/packages/react/src/sitemap/index.mjs similarity index 100% rename from packages/core/src/generators/sitemap/index.mjs rename to packages/react/src/sitemap/index.mjs diff --git a/packages/core/src/generators/sitemap/template.xml b/packages/react/src/sitemap/template.xml similarity index 100% rename from packages/core/src/generators/sitemap/template.xml rename to packages/react/src/sitemap/template.xml diff --git a/packages/core/src/generators/sitemap/types.d.ts b/packages/react/src/sitemap/types.d.ts similarity index 81% rename from packages/core/src/generators/sitemap/types.d.ts rename to packages/react/src/sitemap/types.d.ts index abad2fd1..569fec49 100644 --- a/packages/core/src/generators/sitemap/types.d.ts +++ b/packages/react/src/sitemap/types.d.ts @@ -1,4 +1,4 @@ -import type { MetadataEntry } from '../metadata/types'; +import type { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types'; export interface SitemapEntry { loc: string; diff --git a/packages/core/src/generators/sitemap/utils/createPageSitemapEntry.mjs b/packages/react/src/sitemap/utils/createPageSitemapEntry.mjs similarity index 52% rename from packages/core/src/generators/sitemap/utils/createPageSitemapEntry.mjs rename to packages/react/src/sitemap/utils/createPageSitemapEntry.mjs index fb74faa4..b25ae7f2 100644 --- a/packages/core/src/generators/sitemap/utils/createPageSitemapEntry.mjs +++ b/packages/react/src/sitemap/utils/createPageSitemapEntry.mjs @@ -1,10 +1,10 @@ -import { populate } from '../../../utils/configuration/templates.mjs'; +import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs'; /** * Builds an API doc sitemap url. * - * @param {import('../../metadata/types').MetadataEntry} entry - * @param {import('../../../utils/configuration/types').Configuration['sitemap']} config + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry + * @param {import('@node-core/doc-kit/utils/configuration/types').Configuration['sitemap']} config * @returns {import('../types').SitemapEntry} */ export const createPageSitemapEntry = (entry, config, lastmod) => ({ diff --git a/scripts/vercel-build.sh b/scripts/vercel-build.sh index a9f5fd9a..5940b71f 100755 --- a/scripts/vercel-build.sh +++ b/scripts/vercel-build.sh @@ -9,7 +9,7 @@ node packages/core/bin/cli.mjs generate \ -t orama-db \ -t legacy-json \ -t llms-txt \ - -t web \ + -t html \ -i "./node/doc/api/*.md" \ --ignore "./node/doc/api/quic.md" \ -o "./out" \