@brillout/docpress 0.15.10 → 0.15.11

package/rehypeMetaToProps.ts

@@ -0,0 +1,69 @@
+export { rehypeMetaToProps }
+
+import { visit } from 'unist-util-visit'
+import type { ElementData, Root } from 'hast'
+
+/**
+ * Rehype plugin to extract metadata from `<code>` blocks in markdown
+ * and attach them as props to the parent `<pre>` element.
+ *
+ * This allows using those props inside a custom `<Pre>` component.
+ *
+ * Example:
+ * ~~~mdx
+ * ```js foo="bar" hide_copy='true'
+ * export function add(a, b) {
+ *   return a + b
+ * }
+ * ```
+ * ~~~
+ * These props are then added to the `<pre>` element
+ */
+function rehypeMetaToProps() {
+  return (tree: Root) => {
+    visit(tree, 'element', (node, _index, parent) => {
+      if (node.tagName === 'code' && parent?.type === 'element' && parent.tagName === 'pre') {
+        const props = parseMetaString(node.data?.meta)
+        parent.properties ??= {}
+        parent.properties = { ...parent.properties, ...props }
+      }
+    })
+  }
+}
+
+/**
+ * Minimal parser for a metadata string into key-value pairs.
+ *
+ * Supports simple patterns: key or key="value".
+ *
+ * Keys must contain only letters, dashes, or underscores (no digits).
+ * Keys are converted to kebab-case. Values default to "true" if missing.
+ *
+ * Example:
+ *   parseMetaString('foo fooBar="value"')
+ *   => { foo: 'true', foo_bar: 'value' }
+ *
+ * @param metaString - The input metadata string.
+ * @returns A plain object of parsed key-value pairs.
+ */
+function parseMetaString(metaString: ElementData['meta']): Record<string, string> {
+  if (!metaString) return {}
+
+  const props: Record<string, string> = {}
+
+  const keyValuePairRE = /([a-zA-Z_-]+)(?:="([^"]*)")?(?=\s|$)/g
+  for (const match of metaString.matchAll(keyValuePairRE)) {
+    let [_, key, value] = match
+    props[kebabCase(key)] = value || 'true'
+  }
+
+  return props
+}
+
+// Simple function to convert a camelCase or PascalCase string to kebab-case.
+function kebabCase(str: string) {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace('_', '-')
+    .toLowerCase()
+}

package/remarkDetype.ts

@@ -0,0 +1,172 @@
+export { remarkDetype }
+
+import type { Root, Parent, Code } from 'mdast'
+import type { VFile } from '@mdx-js/mdx/internal-create-format-aware-processors'
+import { visit } from 'unist-util-visit'
+import { assertUsage } from './utils/assert.js'
+import pc from '@brillout/picocolors'
+import module from 'node:module'
+// Cannot use `import { transform } from 'detype'` as it results in errors,
+// and the package has no default export. Using `module.createRequire` instead.
+const { transform: detype } = module.createRequire(import.meta.url)('detype') as typeof import('detype')
+
+const prettierOptions: NonNullable<Parameters<typeof detype>[2]>['prettierOptions'] = {
+  semi: false,
+  singleQuote: true,
+  printWidth: 100,
+  trailingComma: 'none',
+}
+
+type CodeNode = {
+  codeBlock: Code
+  index: number
+  parent: Parent
+}
+
+function remarkDetype() {
+  return async function transformer(tree: Root, file: VFile) {
+    const code_nodes: CodeNode[] = []
+
+    visit(tree, 'code', (node, index, parent) => {
+      if (!parent || typeof index === 'undefined') return
+      // Skip if `node.lang` is not ts, tsx, vue, or yaml
+      if (!['ts', 'tsx', 'vue', 'yaml'].includes(node.lang || '')) return
+
+      // Skip if 'ts-only' meta is present
+      if (node.meta?.includes('ts-only')) return
+
+      // Collect this node for post-processing
+      code_nodes.push({ codeBlock: node, index, parent })
+    })
+
+    for (const node of code_nodes.reverse()) {
+      if (node.codeBlock.lang === 'yaml') {
+        transformYaml(node)
+      } else {
+        await transformTsToJs(node, file)
+      }
+    }
+  }
+}
+
+function transformYaml(node: CodeNode) {
+  const { codeBlock, index, parent } = node
+  const codeBlockContentJs = replaceFileNameSuffixes(codeBlock.value)
+
+  // Skip wrapping if the YAML code block hasn't changed
+  if (codeBlockContentJs === codeBlock.value) return
+
+  const { position, ...rest } = codeBlock
+
+  // Create a new code node for the JS version based on the modified YAML
+  const yamlJsCode: Code = {
+    ...rest,
+    value: codeBlockContentJs,
+  }
+
+  // Wrap both the original YAML and `yamlJsCode` with <CodeSnippets>
+  const yamlContainer = {
+    type: 'mdxJsxFlowElement' as const,
+    name: 'CodeSnippets',
+    children: [yamlJsCode, codeBlock],
+    attributes: [],
+  }
+  parent.children.splice(index, 1, yamlContainer)
+}
+
+async function transformTsToJs(node: CodeNode, file: VFile) {
+  const { codeBlock, index, parent } = node
+  let codeBlockContentJs = replaceFileNameSuffixes(codeBlock.value)
+
+  // Remove TypeScript from the TS/TSX/Vue code node
+  try {
+    codeBlockContentJs = await detype(codeBlockContentJs, `some-dummy-filename.${codeBlock.lang}`, {
+      customizeBabelConfig(config) {
+        // Add `onlyRemoveTypeImports: true` to the internal `@babel/preset-typescript` config
+        // https://github.com/cyco130/detype/blob/46ec867e9efd31d31a312a215ca169bd6bff4726/src/transform.ts#L206
+        assertUsage(config.presets && config.presets.length === 1, 'Unexpected Babel config presets')
+        config.presets = [[config.presets[0], { onlyRemoveTypeImports: true }]]
+      },
+      removeTsComments: true,
+      prettierOptions,
+    })
+  } catch (error) {
+    // Log errors and return original content instead of throwing
+    console.error(pc.red((error as SyntaxError).message))
+    console.error(
+      [
+        `Failed to transform the code block in: ${pc.bold(pc.blue(file.path))}.`,
+        "This likely happened due to invalid TypeScript syntax (see detype's error message above). You can either:",
+        '- Fix the code block syntax',
+        '- Set the code block language to js instead of ts',
+        '- Use custom meta or comments https://github.com/brillout/docpress#detype',
+      ].join('\n') + '\n',
+    )
+    return
+  }
+
+  // Clean up both JS and TS code contents: correct diff comments (for js only) and apply custom magic comment replacements
+  codeBlockContentJs = cleanUpCode(codeBlockContentJs.trimEnd(), true)
+  codeBlock.value = cleanUpCode(codeBlock.value)
+
+  // No wrapping needed if JS and TS code are still identical
+  if (codeBlockContentJs === codeBlock.value) return
+
+  const { position, lang, ...rest } = codeBlock
+
+  const jsCode: Code = {
+    ...rest,
+    // The jsCode lang should be js|jsx|vue
+    lang: lang!.replace('t', 'j'),
+    value: codeBlockContentJs,
+  }
+
+  // Wrap both the original `codeBlock` and `jsCode` with <CodeSnippets>
+  const container = {
+    type: 'mdxJsxFlowElement' as const,
+    name: 'CodeSnippets',
+    children: [jsCode, codeBlock],
+    attributes: [],
+  }
+  parent.children.splice(index, 1, container)
+}
+
+// Replace all '.ts' extensions with '.js'
+function replaceFileNameSuffixes(codeBlockValue: string) {
+  return codeBlockValue.replaceAll('.ts', '.js')
+}
+
+function cleanUpCode(code: string, isJsCode: boolean = false) {
+  if (isJsCode) {
+    code = correctCodeDiffComments(code)
+  }
+  return processMagicComments(code)
+}
+function processMagicComments(code: string) {
+  // @detype-replace DummyLayout Layout
+  const renameCommentRE = /^\/\/\s@detype-replace\s([^ ]+) ([^ ]+)\n/gm
+  const matches = Array.from(code.matchAll(renameCommentRE))
+
+  if (matches.length) {
+    for (let i = matches.length - 1; i >= 0; i--) {
+      const match = matches[i]
+      const [fullMatch, renameFrom, renameTo] = match
+      code = code.split(fullMatch).join('').replaceAll(renameFrom, renameTo)
+    }
+  }
+  code = code.replaceAll('// @detype-uncomment ', '')
+
+  return code
+}
+/**
+ * Correct code diff comments that detype() unexpectedly reformatted (using Prettier and Babel internally)
+ * after removing TypeScript.
+ * See https://github.com/brillout/docpress/pull/47#issuecomment-3263953899
+ * @param code Transformed Javascript code.
+ * @returns The corrected code.
+ */
+function correctCodeDiffComments(code: string) {
+  // Expected to match the code diff comments: `// [!code ++]` and `// [!code --]` started with newline and optional spaces
+  const codeDiffRE = /\n\s*\/\/\s\[!code.+\]/g
+  return code.replaceAll(codeDiffRE, (codeDiff) => codeDiff.trimStart())
+}

package/resolvePageContext.ts

@@ -13,7 +13,7 @@ import type {
   HeadingDetachedResolved,
   StringArray,
 } from './types/Heading'
-import { assert } from './utils/assert'
+import { assert, assertUsage } from './utils/assert'
 import { jsxToTextContent } from './utils/jsxToTextContent'
 import pc from '@brillout/picocolors'
 import { parseMarkdownMini } from './parseMarkdownMini'
@@ -149,6 +149,16 @@ function getActiveHeading(
   headingsDetachedResolved: HeadingDetachedResolved[],
   urlPathname: string,
 ) {
+  const URLs =
+    '\n' +
+    [...headingsResolved, ...headingsDetachedResolved]
+      .filter(Boolean)
+      .map((h) => h.url)
+      .sort()
+      .map((url) => `  ${url}`)
+      .join('\n')
+  const errNotFound = `URL ${pc.bold(urlPathname)} not found in following URLs:${URLs}`
+  const errFoundTwice = `URL ${pc.bold(urlPathname)} found twice in following URLs:${URLs}`
   let activeHeading: HeadingResolved | HeadingDetachedResolved | null = null
   let activeCategoryName = 'Miscellaneous'
   let headingCategory: string | undefined
@@ -158,6 +168,7 @@ function getActiveHeading(
       headingCategory = heading.title
     }
     if (heading.url === urlPathname) {
+      assertUsage(!activeHeading, errFoundTwice)
       activeHeading = heading
       assert(headingCategory)
       activeCategoryName = headingCategory
@@ -167,21 +178,14 @@ function getActiveHeading(
   }
   const isDetachedPage = !activeHeading
   if (!activeHeading) {
-    activeHeading = headingsDetachedResolved.find(({ url }) => urlPathname === url) ?? null
-  }
-  if (!activeHeading) {
-    throw new Error(
-      [
-        `URL ${pc.bold(urlPathname)} not found in following URLs:`,
-        [...headingsResolved, ...headingsDetachedResolved]
-          .filter(Boolean)
-          .map((h) => h.url)
-          .sort()
-          .map((url) => `  ${url}`)
-          .join('\n'),
-      ].join('\n'),
-    )
+    const found = headingsDetachedResolved.filter(({ url }) => urlPathname === url)
+    if (found.length > 0) {
+      assertUsage(found.length === 1, errFoundTwice)
+      assertUsage(!activeHeading, errFoundTwice)
+      activeHeading = found[0]!
+    }
   }
+  assertUsage(activeHeading, errNotFound)
   if (activeHeading.category) activeCategoryName = activeHeading.category
   return { activeHeading, isDetachedPage, activeCategoryName }
 }

package/tsconfig.json

@@ -2,7 +2,8 @@
   "compilerOptions": {
     "outDir": "./dist/",
     "jsx": "react",
-    "module": "ES2020",
+    "module": "ES2022",
+    "target": "ES2022",
     "moduleResolution": "Bundler",
     "lib": ["DOM", "DOM.Iterable", "ESNext"],
     "types": ["vite/client"],

package/vite.config.ts

@@ -7,17 +7,22 @@ import { parsePageSections } from './parsePageSections.js'
 import rehypePrettyCode from 'rehype-pretty-code'
 import remarkGfm from 'remark-gfm'
 import { transformerNotationDiff } from '@shikijs/transformers'
+import { remarkDetype } from './remarkDetype.js'
+import { rehypeMetaToProps } from './rehypeMetaToProps.js'
 
 const root = process.cwd()
-const prettyCode = [rehypePrettyCode, { theme: 'github-light', transformers: [transformerNotationDiff()] }]
-const rehypePlugins: any = [prettyCode]
-const remarkPlugins = [remarkGfm]
+const prettyCode = [
+  rehypePrettyCode,
+  { theme: 'github-light', keepBackground: false, transformers: [transformerNotationDiff()] },
+]
+const rehypePlugins: any = [prettyCode, [rehypeMetaToProps]]
+const remarkPlugins = [remarkGfm, remarkDetype]
 
 const config: UserConfig = {
   root,
   plugins: [
     parsePageSections(),
-    mdx({ rehypePlugins, remarkPlugins }) as PluginOption,
+    mdx({ rehypePlugins, remarkPlugins, providerImportSource: '@brillout/docpress' }) as PluginOption,
     // @vitejs/plugin-react-swc needs to be added *after* the mdx plugins
     react(),
   ],