@brillout/docpress 0.15.10-commit-af2d9bc → 0.15.10-commit-317b144

package/components/CodeSnippets.css

@@ -1,3 +1,15 @@
+/* Wrapper */
+.code-snippet,
+.code-snippets {
+  position: relative;
+  &:hover {
+    button,
+    select {
+      opacity: 1;
+    }
+  }
+}
+
 /* Language select */
 .code-lang-select {
   right: 42px;
@@ -41,7 +53,9 @@
   border: 1px solid #ccc;
   border-radius: 5px;
   background-color: #f7f7f7;
-  &:hover {
+  opacity: 0;
+  transition: opacity 0.8s ease-in-out, background-color 0.4s ease-in-out;
+  &:not(:hover) {
     background-color: #eee;
   }
 }

package/components/CodeSnippets.tsx

@@ -18,7 +18,7 @@ function TypescriptOnly({ children }: { children: React.ReactNode }) {
 function CodeSnippets({ children }: { children: React.ReactNode }) {
   const [codeLangSelected, selectCodeLang] = useSelectCodeLang()
   return (
-    <div>
+    <div className="code-snippets">
       <form style={{ position: 'relative' }}>
         <select className="code-lang-select" onChange={onChange} value={codeLangSelected}>
           <option value="js">JavaScript</option>
@@ -43,7 +43,7 @@ function CodeSnippet({
   const displayStyle = tsOnly ? {} : { display: codeLangSelected === codeLang ? 'block' : 'none' }
 
   return (
-    <div style={{ ...displayStyle, position: 'relative' }}>
+    <div className="code-snippet" style={{ ...displayStyle }}>
       <CopyButton />
       {children}
     </div>

package/detypePlugin.ts

@@ -4,6 +4,7 @@ import type { PluginOption } from 'vite'
 import module from 'node:module'
 import { assertUsage } from './utils/assert.js'
 import pc from '@brillout/picocolors'
+import { getMagicString } from './utils/getMagicString.js'
 // 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')
@@ -32,7 +33,7 @@ const prettierOptions: NonNullable<Parameters<typeof detype>[2]>['prettierOption
 // >   const hello: string = 'world'
 // >   ```
 // ~~~
-const codeBlockRE = /^(.*)```(tsx?|vue)[^\n]*\n([\s\S]*?)```/gm
+const codeBlockRE = /^(.*)```(tsx?|vue|yaml)[^\n]*\n([\s\S]*?)```/gm
 
 function detypePlugin(): PluginOption {
   return {
@@ -40,8 +41,7 @@ function detypePlugin(): PluginOption {
     enforce: 'pre',
     transform: async (code: string, moduleId: string) => {
       if (!moduleId.endsWith('.mdx')) return
-      const codeNew = await transformCode(code, moduleId)
-      return codeNew
+      return await transformCode(code, moduleId)
     },
   }
 }
@@ -50,64 +50,94 @@ async function transformCode(code: string, moduleId: string) {
   const matches = Array.from(code.matchAll(codeBlockRE))
   if (matches.length === 0) return
 
-  let codeNew = `import { CodeSnippets, CodeSnippet } from '@brillout/docpress';\n\n`
-  let lastIndex = 0
+  const { magicString, getMagicStringResult } = getMagicString(code, moduleId)
 
-  for (const match of matches) {
+  magicString.prepend(`import { CodeSnippets, CodeSnippet } from '@brillout/docpress';\n\n`)
+
+  // [Claude AI] Process matches in reverse order to avoid offset issues
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const match = matches[i]
     const [codeBlockOuterStr, codeBlockIndent, codeBlockLang, codeBlockContentWithIndent] = match
+    const isYaml = codeBlockLang === 'yaml'
 
     // Remove indentation
     const codeBlockOpen = codeBlockOuterStr.split('\n')[0].slice(codeBlockIndent.length)
     const codeBlockContent = removeCodeBlockIndent(codeBlockContentWithIndent, codeBlockIndent, moduleId)
 
-    const blockStartIndex = match.index
-    const blockEndIndex = blockStartIndex + codeBlockOuterStr.length
-    codeNew += code.slice(lastIndex, blockStartIndex)
-
-    if (codeBlockOpen.includes('ts-only')) {
-      codeNew += `${codeBlockIndent}<CodeSnippet codeLang="ts" tsOnly>\n${codeBlockOuterStr}\n${codeBlockIndent}</CodeSnippet>`
+    let replacement: string
+    if (codeBlockOpen.includes('ts-only') && !isYaml) {
+      replacement = `${codeBlockIndent}<CodeSnippet codeLang="ts" tsOnly>\n${codeBlockOuterStr}\n${codeBlockIndent}</CodeSnippet>`
     } else {
       // someFileName.ts => someFileName.js
       let codeBlockContentJs = codeBlockContent.replaceAll('.ts', '.js')
+      const codeBlockClose = '```'
+      if (isYaml && codeBlockContentJs === codeBlockContent) {
+        continue
+      }
+
       // Remove TypeScript
-      codeBlockContentJs = await detype(codeBlockContentJs, `some-dummy-filename.${codeBlockLang}`, {
-        removeTsComments: true,
-        prettierOptions,
-      })
+      if (!isYaml) {
+        codeBlockContentJs = await detype(codeBlockContentJs, `some-dummy-filename.${codeBlockLang}`, {
+          customizeBabelConfig(config) {
+            // Add `onlyRemoveTypeImports: true` to the internal `@babel/preset-typescript` config
+            // See https://github.com/cyco130/detype/blob/main/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,
+        })
+        // Correct code diff comments
+        codeBlockContentJs = correctCodeDiffComments(codeBlockContentJs)
+      }
 
+      // Update code block open delimiter
       const codeBlockLangJs =
         codeBlockLang === 'vue'
           ? 'vue'
           : // ts => js | tsx => jsx
             codeBlockLang.replace('t', 'j')
       const codeBlockOpenJs = codeBlockOpen.replace(codeBlockLang, codeBlockLangJs)
-      const codeBlockClose = '```'
 
-      const codeSnippetTs = `<CodeSnippet codeLang="ts">\n${codeBlockOpen}\n${codeBlockContent}${codeBlockClose}\n</CodeSnippet>`
-      const codeSnippetJs = `<CodeSnippet codeLang="js">\n${codeBlockOpenJs}\n${codeBlockContentJs}${codeBlockClose}\n</CodeSnippet>`
-      const codeSnippets = restoreCodeBlockIndent(
-        `<CodeSnippets>\n${codeSnippetJs}\n${codeSnippetTs}\n</CodeSnippets>`,
-        codeBlockIndent,
-      )
+      // Wrap each with <CodeSnippet>
+      let codeSnippets = [
+        wrapCodeSnippet('ts', `${codeBlockOpen}\n${codeBlockContent}${codeBlockClose}`),
+        wrapCodeSnippet('js', `${codeBlockOpenJs}\n${codeBlockContentJs}${codeBlockClose}`),
+      ].join('\n')
+
+      // Wrap with <CodeSnippets> (if not YAML)
+      codeSnippets = isYaml
+        ? codeSnippets
+        : // Rename/Replace Words via Custom Magic Comments
+          processMagicComments(`<CodeSnippets>\n${codeSnippets}\n</CodeSnippets>`)
+
+      // Restore indentation
+      codeSnippets = restoreCodeBlockIndent(codeSnippets, codeBlockIndent)
 
-      codeNew += codeSnippets
+      // Done
+      replacement = codeSnippets
     }
 
-    lastIndex = blockEndIndex
+    const blockStartIndex = match.index!
+    const blockEndIndex = blockStartIndex + codeBlockOuterStr.length
+    magicString.overwrite(blockStartIndex, blockEndIndex, replacement)
   }
-  codeNew += code.slice(lastIndex)
 
-  return codeNew
+  return getMagicStringResult()
 }
 
+function wrapCodeSnippet(lang: string, content: string) {
+  return `<CodeSnippet codeLang="${lang}">\n${content}\n</CodeSnippet>`
+}
 function removeCodeBlockIndent(code: string, codeBlockIndent: string, moduleId: string) {
   if (!codeBlockIndent.length) return code
   return code
     .split('\n')
     .map((line) => {
+      const lineStart = codeBlockIndent.trimEnd()
       assertUsage(
-        line.startsWith(codeBlockIndent.trimEnd()),
-        `In ${pc.bold(pc.blue(moduleId))} the line ${pc.bold(line)} must start with ${pc.bold(codeBlockIndent)}`,
+        line.startsWith(lineStart),
+        `In ${pc.bold(pc.blue(moduleId))} the line '${pc.bold(line)}' must start with '${pc.bold(lineStart)}'`,
       )
       return line.slice(codeBlockIndent.length)
     })
@@ -120,3 +150,30 @@ function restoreCodeBlockIndent(code: string, codeBlockIndent: string) {
     .map((line) => `${codeBlockIndent}${line}`)
     .join('\n')
 }
+function processMagicComments(code: string) {
+  // @detype-rename DummyLayout>Layout
+  const renameCommentRE = /^\/\/\s@detype-rename\s(\w+)>(\w+)\n/gm
+  const matches = Array.from(code.matchAll(renameCommentRE))
+
+  if (matches.length) {
+    for (let i = 0; i < matches.length / 2; i++) {
+      const match = matches[i]
+      const [fullMatch, renameFrom, renameTo] = match
+      code = code.split(fullMatch).join('').replaceAll(renameFrom, renameTo)
+    }
+  }
+
+  return code.replaceAll('//~', '')
+}
+/**
+ * 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/dist/components/CodeSnippets.js

@@ -13,7 +13,7 @@ function TypescriptOnly({ children }) {
 }
 function CodeSnippets({ children }) {
     const [codeLangSelected, selectCodeLang] = useSelectCodeLang();
-    return (React.createElement("div", null,
+    return (React.createElement("div", { className: "code-snippets" },
         React.createElement("form", { style: { position: 'relative' } },
             React.createElement("select", { className: "code-lang-select", onChange: onChange, value: codeLangSelected },
                 React.createElement("option", { value: "js" }, "JavaScript"),
@@ -26,7 +26,7 @@ function CodeSnippets({ children }) {
 function CodeSnippet({ children, codeLang, tsOnly = false, }) {
     const [codeLangSelected] = useSelectCodeLang();
     const displayStyle = tsOnly ? {} : { display: codeLangSelected === codeLang ? 'block' : 'none' };
-    return (React.createElement("div", { style: { ...displayStyle, position: 'relative' } },
+    return (React.createElement("div", { className: "code-snippet", style: { ...displayStyle } },
         React.createElement(CopyButton, null),
         children));
 }

package/dist/detypePlugin.js

@@ -2,6 +2,7 @@ export { detypePlugin };
 import module from 'node:module';
 import { assertUsage } from './utils/assert.js';
 import pc from '@brillout/picocolors';
+import { getMagicString } from './utils/getMagicString.js';
 // 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');
@@ -29,7 +30,7 @@ const prettierOptions = {
 // >   const hello: string = 'world'
 // >   ```
 // ~~~
-const codeBlockRE = /^(.*)```(tsx?|vue)[^\n]*\n([\s\S]*?)```/gm;
+const codeBlockRE = /^(.*)```(tsx?|vue|yaml)[^\n]*\n([\s\S]*?)```/gm;
 function detypePlugin() {
     return {
         name: '@brillout/docpress:detypePlugin',
@@ -37,8 +38,7 @@ function detypePlugin() {
         transform: async (code, moduleId) => {
             if (!moduleId.endsWith('.mdx'))
                 return;
-            const codeNew = await transformCode(code, moduleId);
-            return codeNew;
+            return await transformCode(code, moduleId);
         },
     };
 }
@@ -46,42 +46,71 @@ async function transformCode(code, moduleId) {
     const matches = Array.from(code.matchAll(codeBlockRE));
     if (matches.length === 0)
         return;
-    let codeNew = `import { CodeSnippets, CodeSnippet } from '@brillout/docpress';\n\n`;
-    let lastIndex = 0;
-    for (const match of matches) {
+    const { magicString, getMagicStringResult } = getMagicString(code, moduleId);
+    magicString.prepend(`import { CodeSnippets, CodeSnippet } from '@brillout/docpress';\n\n`);
+    // [Claude AI] Process matches in reverse order to avoid offset issues
+    for (let i = matches.length - 1; i >= 0; i--) {
+        const match = matches[i];
         const [codeBlockOuterStr, codeBlockIndent, codeBlockLang, codeBlockContentWithIndent] = match;
+        const isYaml = codeBlockLang === 'yaml';
         // Remove indentation
         const codeBlockOpen = codeBlockOuterStr.split('\n')[0].slice(codeBlockIndent.length);
         const codeBlockContent = removeCodeBlockIndent(codeBlockContentWithIndent, codeBlockIndent, moduleId);
-        const blockStartIndex = match.index;
-        const blockEndIndex = blockStartIndex + codeBlockOuterStr.length;
-        codeNew += code.slice(lastIndex, blockStartIndex);
-        if (codeBlockOpen.includes('ts-only')) {
-            codeNew += `${codeBlockIndent}<CodeSnippet codeLang="ts" tsOnly>\n${codeBlockOuterStr}\n${codeBlockIndent}</CodeSnippet>`;
+        let replacement;
+        if (codeBlockOpen.includes('ts-only') && !isYaml) {
+            replacement = `${codeBlockIndent}<CodeSnippet codeLang="ts" tsOnly>\n${codeBlockOuterStr}\n${codeBlockIndent}</CodeSnippet>`;
         }
         else {
             // someFileName.ts => someFileName.js
             let codeBlockContentJs = codeBlockContent.replaceAll('.ts', '.js');
+            const codeBlockClose = '```';
+            if (isYaml && codeBlockContentJs === codeBlockContent) {
+                continue;
+            }
             // Remove TypeScript
-            codeBlockContentJs = await detype(codeBlockContentJs, `some-dummy-filename.${codeBlockLang}`, {
-                removeTsComments: true,
-                prettierOptions,
-            });
+            if (!isYaml) {
+                codeBlockContentJs = await detype(codeBlockContentJs, `some-dummy-filename.${codeBlockLang}`, {
+                    customizeBabelConfig(config) {
+                        // Add `onlyRemoveTypeImports: true` to the internal `@babel/preset-typescript` config
+                        // See https://github.com/cyco130/detype/blob/main/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,
+                });
+                // Correct code diff comments
+                codeBlockContentJs = correctCodeDiffComments(codeBlockContentJs);
+            }
+            // Update code block open delimiter
             const codeBlockLangJs = codeBlockLang === 'vue'
                 ? 'vue'
                 : // ts => js | tsx => jsx
                     codeBlockLang.replace('t', 'j');
             const codeBlockOpenJs = codeBlockOpen.replace(codeBlockLang, codeBlockLangJs);
-            const codeBlockClose = '```';
-            const codeSnippetTs = `<CodeSnippet codeLang="ts">\n${codeBlockOpen}\n${codeBlockContent}${codeBlockClose}\n</CodeSnippet>`;
-            const codeSnippetJs = `<CodeSnippet codeLang="js">\n${codeBlockOpenJs}\n${codeBlockContentJs}${codeBlockClose}\n</CodeSnippet>`;
-            const codeSnippets = restoreCodeBlockIndent(`<CodeSnippets>\n${codeSnippetJs}\n${codeSnippetTs}\n</CodeSnippets>`, codeBlockIndent);
-            codeNew += codeSnippets;
+            // Wrap each with <CodeSnippet>
+            let codeSnippets = [
+                wrapCodeSnippet('ts', `${codeBlockOpen}\n${codeBlockContent}${codeBlockClose}`),
+                wrapCodeSnippet('js', `${codeBlockOpenJs}\n${codeBlockContentJs}${codeBlockClose}`),
+            ].join('\n');
+            // Wrap with <CodeSnippets> (if not YAML)
+            codeSnippets = isYaml
+                ? codeSnippets
+                : // Rename/Replace Words via Custom Magic Comments
+                    processMagicComments(`<CodeSnippets>\n${codeSnippets}\n</CodeSnippets>`);
+            // Restore indentation
+            codeSnippets = restoreCodeBlockIndent(codeSnippets, codeBlockIndent);
+            // Done
+            replacement = codeSnippets;
         }
-        lastIndex = blockEndIndex;
+        const blockStartIndex = match.index;
+        const blockEndIndex = blockStartIndex + codeBlockOuterStr.length;
+        magicString.overwrite(blockStartIndex, blockEndIndex, replacement);
     }
-    codeNew += code.slice(lastIndex);
-    return codeNew;
+    return getMagicStringResult();
+}
+function wrapCodeSnippet(lang, content) {
+    return `<CodeSnippet codeLang="${lang}">\n${content}\n</CodeSnippet>`;
 }
 function removeCodeBlockIndent(code, codeBlockIndent, moduleId) {
     if (!codeBlockIndent.length)
@@ -89,7 +118,8 @@ function removeCodeBlockIndent(code, codeBlockIndent, moduleId) {
     return code
         .split('\n')
         .map((line) => {
-        assertUsage(line.startsWith(codeBlockIndent.trimEnd()), `In ${pc.bold(pc.blue(moduleId))} the line ${pc.bold(line)} must start with ${pc.bold(codeBlockIndent)}`);
+        const lineStart = codeBlockIndent.trimEnd();
+        assertUsage(line.startsWith(lineStart), `In ${pc.bold(pc.blue(moduleId))} the line '${pc.bold(line)}' must start with '${pc.bold(lineStart)}'`);
         return line.slice(codeBlockIndent.length);
     })
         .join('\n');
@@ -102,3 +132,28 @@ function restoreCodeBlockIndent(code, codeBlockIndent) {
         .map((line) => `${codeBlockIndent}${line}`)
         .join('\n');
 }
+function processMagicComments(code) {
+    // @detype-rename DummyLayout>Layout
+    const renameCommentRE = /^\/\/\s@detype-rename\s(\w+)>(\w+)\n/gm;
+    const matches = Array.from(code.matchAll(renameCommentRE));
+    if (matches.length) {
+        for (let i = 0; i < matches.length / 2; i++) {
+            const match = matches[i];
+            const [fullMatch, renameFrom, renameTo] = match;
+            code = code.split(fullMatch).join('').replaceAll(renameFrom, renameTo);
+        }
+    }
+    return code.replaceAll('//~', '');
+}
+/**
+ * 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) {
+    // 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/dist/utils/getMagicString.d.ts

@@ -0,0 +1,9 @@
+export { getMagicString };
+import MagicString from 'magic-string';
+declare function getMagicString(code: string, id: string): {
+    magicString: MagicString;
+    getMagicStringResult: () => {
+        code: string;
+        map: import("magic-string").SourceMap;
+    };
+};

package/dist/utils/getMagicString.js

@@ -0,0 +1,13 @@
+export { getMagicString };
+import MagicString from 'magic-string';
+// Used everywhere instead of `new MagicString()` for consistent source map generation
+function getMagicString(code, id) {
+    const magicString = new MagicString(code);
+    const getMagicStringResult = () => {
+        return {
+            code: magicString.toString(),
+            map: magicString.generateMap({ hires: true, source: id }),
+        };
+    };
+    return { magicString, getMagicStringResult };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brillout/docpress",
-  "version": "0.15.10-commit-af2d9bc",
+  "version": "0.15.10-commit-317b144",
   "type": "module",
   "dependencies": {
     "@brillout/picocolors": "^1.0.10",
@@ -12,6 +12,7 @@
     "@shikijs/transformers": "1.2.0",
     "@vitejs/plugin-react-swc": "^3.10.2",
     "detype": "^1.1.2",
+    "magic-string": "^0.30.18",
     "rehype-pretty-code": "0.13.0",
     "remark-gfm": "4.0.0",
     "shiki": "1.2.0",

package/utils/getMagicString.ts

@@ -0,0 +1,17 @@
+export { getMagicString }
+
+import MagicString from 'magic-string'
+
+// Used everywhere instead of `new MagicString()` for consistent source map generation
+function getMagicString(code: string, id: string) {
+  const magicString = new MagicString(code)
+
+  const getMagicStringResult = () => {
+    return {
+      code: magicString.toString(),
+      map: magicString.generateMap({ hires: true, source: id }),
+    }
+  }
+
+  return { magicString, getMagicStringResult }
+}