@readme/markdown 13.7.2 → 13.7.3

package/components/CodeTabs/index.tsx

@@ -1,7 +1,7 @@
 import type { Mermaid } from 'mermaid';
 
 import syntaxHighlighterUtils from '@readme/syntax-highlighter/utils';
-import React, { useContext, useEffect } from 'react';
+import React, { useContext, useEffect, useRef } from 'react';
 
 import ThemeContext from '../../contexts/Theme';
 import useHydrated from '../../hooks/useHydrated';
@@ -10,6 +10,47 @@ let mermaid: Mermaid;
 
 const { uppercase } = syntaxHighlighterUtils;
 
+// Module-level queue that batches mermaid nodes across all CodeTabs instances into a
+// single mermaid.run() call. This is necessary because mermaid generates SVG element IDs
+// using Date.now(), which collides when multiple diagrams render in the same millisecond.
+// Colliding IDs cause diagrams to overlap or break layout.
+//
+// Why not use `deterministicIDSeed` with a unique ID per diagram? Mermaid's implementation
+// only uses seed.length (not the seed value) to compute the starting ID, so every UUID
+// (36 chars) produces the same `mermaid-36` prefix — the collision remains.
+// See: https://github.com/mermaid-js/mermaid/blob/mermaid%4011.12.0/packages/mermaid/src/utils.ts#L755-L761
+//
+// These vars must be module-scoped (not per-instance refs) because the batching requires
+// cross-instance coordination. They are short-lived: the queue drains on the next macrotask
+// and cleanup clears everything on unmount.
+let mermaidQueue: HTMLPreElement[] = [];
+let mermaidFlushTimer: ReturnType<typeof setTimeout> | null = null;
+let currentTheme: string | undefined;
+
+function queueMermaidNode(node: HTMLPreElement, theme: string) {
+  mermaidQueue.push(node);
+  currentTheme = theme;
+
+  if (!mermaidFlushTimer) {
+    // setTimeout(0) defers to a macrotask, after all useEffects have queued their nodes
+    mermaidFlushTimer = setTimeout(async () => {
+      const nodes = [...mermaidQueue];
+      mermaidQueue = [];
+      mermaidFlushTimer = null;
+
+      const module = await import('mermaid');
+      mermaid = module.default;
+      mermaid.initialize({
+        startOnLoad: false,
+        theme: currentTheme === 'dark' ? 'dark' : 'default',
+        deterministicIds: true,
+      });
+
+      await mermaid.run({ nodes });
+    }, 0);
+  }
+}
+
 interface Props {
   children: JSX.Element | JSX.Element[];
 }
@@ -18,6 +59,7 @@ const CodeTabs = (props: Props) => {
   const { children } = props;
   const theme = useContext(ThemeContext);
   const isHydrated = useHydrated();
+  const mermaidRef = useRef<HTMLPreElement>(null);
 
   // Handle both array (from rehype-react in rendering mdxish) and single element (MDX/JSX runtime) cases
   // The children here is the individual code block objects
@@ -32,22 +74,21 @@ const CodeTabs = (props: Props) => {
 
   const containAtLeastOneMermaid = childrenArray.some(pre => getCodeComponent(pre)?.props?.lang === 'mermaid');
 
-  // Render Mermaid diagram
   useEffect(() => {
-    // Ensure we only render mermaids when frontend is hydrated to avoid hydration errors
-    // because mermaid mutates the DOM before react hydrates
-    if (typeof window !== 'undefined' && containAtLeastOneMermaid && isHydrated) {
-      import('mermaid').then(module => {
-        mermaid = module.default;
-        mermaid.initialize({
-          startOnLoad: false,
-          theme: theme === 'dark' ? 'dark' : 'default',
-        });
-        mermaid.run({
-          nodes: document.querySelectorAll('.mermaid-render'),
-        });
-      });
+    // Wait for hydration so mermaid's DOM mutations don't cause mismatches
+    if (typeof window !== 'undefined' && containAtLeastOneMermaid && isHydrated && mermaidRef.current) {
+      queueMermaidNode(mermaidRef.current, theme);
     }
+
+    return () => {
+      // Clear the batch timer on unmount to prevent mermaid from running
+      // after the DOM is torn down
+      if (mermaidFlushTimer) {
+        clearTimeout(mermaidFlushTimer);
+        mermaidFlushTimer = null;
+        mermaidQueue = [];
+      }
+    };
   }, [containAtLeastOneMermaid, theme, isHydrated]);
 
   function handleClick({ target }, index: number) {
@@ -67,7 +108,11 @@ const CodeTabs = (props: Props) => {
     const codeComponent = getCodeComponent(childrenArray[0]);
     if (codeComponent?.props?.lang === 'mermaid') {
       const value = codeComponent?.props?.value;
-      return <pre className="mermaid-render mermaid_single">{value}</pre>;
+      return (
+        <pre ref={mermaidRef} className="mermaid-render mermaid_single">
+          {value}
+        </pre>
+      );
     }
   }
 
@@ -76,9 +121,7 @@ const CodeTabs = (props: Props) => {
       <div className="CodeTabs-toolbar">
         {childrenArray.map((pre, i) => {
           // the first or only child should be our Code component
-          const tabCodeComponent = Array.isArray(pre.props?.children)
-            ? pre.props.children[0]
-            : pre.props?.children;
+          const tabCodeComponent = Array.isArray(pre.props?.children) ? pre.props.children[0] : pre.props?.children;
           const lang = tabCodeComponent?.props?.lang;
           const meta = tabCodeComponent?.props?.meta;
 

package/components/TailwindStyle/index.tsx

@@ -97,10 +97,11 @@ const TailwindStyle = ({ children, darkModeDataAttribute }: Props) => {
           shouldUpdate = true;
         }
 
-        if (shouldUpdate) {
-          setClasses(Array.from(classesSet.current));
-        }
       });
+
+      if (shouldUpdate) {
+        setClasses(Array.from(classesSet.current));
+      }
     });
 
     observer.observe(ref.current.parentElement, {

package/dist/main.js

@@ -11704,10 +11704,47 @@ var dist_utils_default = /*#__PURE__*/__webpack_require__.n(dist_utils);
 
 let mermaid;
 const { uppercase } = (dist_utils_default());
+// Module-level queue that batches mermaid nodes across all CodeTabs instances into a
+// single mermaid.run() call. This is necessary because mermaid generates SVG element IDs
+// using Date.now(), which collides when multiple diagrams render in the same millisecond.
+// Colliding IDs cause diagrams to overlap or break layout.
+//
+// Why not use `deterministicIDSeed` with a unique ID per diagram? Mermaid's implementation
+// only uses seed.length (not the seed value) to compute the starting ID, so every UUID
+// (36 chars) produces the same `mermaid-36` prefix — the collision remains.
+// See: https://github.com/mermaid-js/mermaid/blob/mermaid%4011.12.0/packages/mermaid/src/utils.ts#L755-L761
+//
+// These vars must be module-scoped (not per-instance refs) because the batching requires
+// cross-instance coordination. They are short-lived: the queue drains on the next macrotask
+// and cleanup clears everything on unmount.
+let mermaidQueue = [];
+let mermaidFlushTimer = null;
+let currentTheme;
+function queueMermaidNode(node, theme) {
+    mermaidQueue.push(node);
+    currentTheme = theme;
+    if (!mermaidFlushTimer) {
+        // setTimeout(0) defers to a macrotask, after all useEffects have queued their nodes
+        mermaidFlushTimer = setTimeout(async () => {
+            const nodes = [...mermaidQueue];
+            mermaidQueue = [];
+            mermaidFlushTimer = null;
+            const module = await Promise.resolve(/* import() */).then(__webpack_require__.t.bind(__webpack_require__, 1387, 23));
+            mermaid = module.default;
+            mermaid.initialize({
+                startOnLoad: false,
+                theme: currentTheme === 'dark' ? 'dark' : 'default',
+                deterministicIds: true,
+            });
+            await mermaid.run({ nodes });
+        }, 0);
+    }
+}
 const CodeTabs = (props) => {
     const { children } = props;
     const theme = (0,external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.useContext)(Theme);
     const isHydrated = useHydrated();
+    const mermaidRef = (0,external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.useRef)(null);
     // Handle both array (from rehype-react in rendering mdxish) and single element (MDX/JSX runtime) cases
     // The children here is the individual code block objects
     const childrenArray = Array.isArray(children) ? children : [children];
@@ -11718,22 +11755,20 @@ const CodeTabs = (props) => {
         return Array.isArray(pre?.props?.children) ? pre.props.children[0] : pre?.props?.children;
     };
     const containAtLeastOneMermaid = childrenArray.some(pre => getCodeComponent(pre)?.props?.lang === 'mermaid');
-    // Render Mermaid diagram
     (0,external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.useEffect)(() => {
-        // Ensure we only render mermaids when frontend is hydrated to avoid hydration errors
-        // because mermaid mutates the DOM before react hydrates
-        if (typeof window !== 'undefined' && containAtLeastOneMermaid && isHydrated) {
-            Promise.resolve(/* import() */).then(__webpack_require__.t.bind(__webpack_require__, 1387, 23)).then(module => {
-                mermaid = module.default;
-                mermaid.initialize({
-                    startOnLoad: false,
-                    theme: theme === 'dark' ? 'dark' : 'default',
-                });
-                mermaid.run({
-                    nodes: document.querySelectorAll('.mermaid-render'),
-                });
-            });
-        }
+        // Wait for hydration so mermaid's DOM mutations don't cause mismatches
+        if (typeof window !== 'undefined' && containAtLeastOneMermaid && isHydrated && mermaidRef.current) {
+            queueMermaidNode(mermaidRef.current, theme);
+        }
+        return () => {
+            // Clear the batch timer on unmount to prevent mermaid from running
+            // after the DOM is torn down
+            if (mermaidFlushTimer) {
+                clearTimeout(mermaidFlushTimer);
+                mermaidFlushTimer = null;
+                mermaidQueue = [];
+            }
+        };
     }, [containAtLeastOneMermaid, theme, isHydrated]);
     function handleClick({ target }, index) {
         const $wrap = target.parentElement.parentElement;
@@ -11749,15 +11784,13 @@ const CodeTabs = (props) => {
         const codeComponent = getCodeComponent(childrenArray[0]);
         if (codeComponent?.props?.lang === 'mermaid') {
             const value = codeComponent?.props?.value;
-            return external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_default().createElement("pre", { className: "mermaid-render mermaid_single" }, value);
+            return (external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_default().createElement("pre", { ref: mermaidRef, className: "mermaid-render mermaid_single" }, value));
         }
     }
     return (external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_default().createElement("div", { className: `CodeTabs CodeTabs_initial theme-${theme}` },
         external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_default().createElement("div", { className: "CodeTabs-toolbar" }, childrenArray.map((pre, i) => {
             // the first or only child should be our Code component
-            const tabCodeComponent = Array.isArray(pre.props?.children)
-                ? pre.props.children[0]
-                : pre.props?.children;
+            const tabCodeComponent = Array.isArray(pre.props?.children) ? pre.props.children[0] : pre.props?.children;
             const lang = tabCodeComponent?.props?.lang;
             const meta = tabCodeComponent?.props?.meta;
             /* istanbul ignore next */
@@ -12330,10 +12363,10 @@ const TailwindStyle = ({ children, darkModeDataAttribute }) => {
                     addClasses(record.target);
                     shouldUpdate = true;
                 }
-                if (shouldUpdate) {
-                    setClasses(Array.from(classesSet.current));
-                }
             });
+            if (shouldUpdate) {
+                setClasses(Array.from(classesSet.current));
+            }
         });
         observer.observe(ref.current.parentElement, {
             subtree: true,
@@ -96062,11 +96095,33 @@ const parseBlock = (text) => {
     const tree = contentParser.runSync(contentParser.parse(text));
     return tree.children;
 };
-const parseInline = (text) => {
+/**
+ * Minimal parser for api-header titles.
+ * Disables markdown constructs that are not parsed in legacy (headings, lists)
+ */
+const apiHeaderTitleParser = unified()
+    .data('micromarkExtensions', [
+    legacyVariable(),
+    looseHtmlEntity(),
+    {
+        disable: {
+            null: [
+                'blockQuote',
+                'headingAtx',
+                'list',
+                'thematicBreak',
+            ],
+        },
+    },
+])
+    .data('fromMarkdownExtensions', [legacyVariableFromMarkdown(), looseHtmlEntityFromMarkdown()])
+    .use(remarkParse)
+    .use(remarkGfm);
+const parseApiHeaderTitle = (text) => {
     if (!text.trim())
         return textToInline(text);
-    const tree = contentParser.runSync(contentParser.parse(text));
-    return tree.children;
+    const tree = apiHeaderTitleParser.runSync(apiHeaderTitleParser.parse(text));
+    return tree.children.flatMap(n => n.type === 'paragraph' && 'children' in n ? n.children : [n]);
 };
 /**
  * Transform a magicBlock node into final MDAST nodes.
@@ -96125,7 +96180,7 @@ function transformMagicBlock(blockType, data, rawValue, options = {}) {
             const depth = headerJson.level || (compatibilityMode ? 1 : 2);
             return [
                 wrapPinnedBlocks({
-                    children: 'title' in headerJson ? parseInline(headerJson.title || '') : [],
+                    children: 'title' in headerJson ? parseApiHeaderTitle(headerJson.title || '') : [],
                     depth,
                     type: 'heading',
                 }, data),

package/dist/main.node.js

@@ -19358,10 +19358,47 @@ var dist_utils_default = /*#__PURE__*/__webpack_require__.n(dist_utils);
 
 let mermaid;
 const { uppercase } = (dist_utils_default());
+// Module-level queue that batches mermaid nodes across all CodeTabs instances into a
+// single mermaid.run() call. This is necessary because mermaid generates SVG element IDs
+// using Date.now(), which collides when multiple diagrams render in the same millisecond.
+// Colliding IDs cause diagrams to overlap or break layout.
+//
+// Why not use `deterministicIDSeed` with a unique ID per diagram? Mermaid's implementation
+// only uses seed.length (not the seed value) to compute the starting ID, so every UUID
+// (36 chars) produces the same `mermaid-36` prefix — the collision remains.
+// See: https://github.com/mermaid-js/mermaid/blob/mermaid%4011.12.0/packages/mermaid/src/utils.ts#L755-L761
+//
+// These vars must be module-scoped (not per-instance refs) because the batching requires
+// cross-instance coordination. They are short-lived: the queue drains on the next macrotask
+// and cleanup clears everything on unmount.
+let mermaidQueue = [];
+let mermaidFlushTimer = null;
+let currentTheme;
+function queueMermaidNode(node, theme) {
+    mermaidQueue.push(node);
+    currentTheme = theme;
+    if (!mermaidFlushTimer) {
+        // setTimeout(0) defers to a macrotask, after all useEffects have queued their nodes
+        mermaidFlushTimer = setTimeout(async () => {
+            const nodes = [...mermaidQueue];
+            mermaidQueue = [];
+            mermaidFlushTimer = null;
+            const module = await __webpack_require__.e(/* import() */ 486).then(__webpack_require__.bind(__webpack_require__, 5486));
+            mermaid = module.default;
+            mermaid.initialize({
+                startOnLoad: false,
+                theme: currentTheme === 'dark' ? 'dark' : 'default',
+                deterministicIds: true,
+            });
+            await mermaid.run({ nodes });
+        }, 0);
+    }
+}
 const CodeTabs = (props) => {
     const { children } = props;
     const theme = (0,external_react_.useContext)(Theme);
     const isHydrated = useHydrated();
+    const mermaidRef = (0,external_react_.useRef)(null);
     // Handle both array (from rehype-react in rendering mdxish) and single element (MDX/JSX runtime) cases
     // The children here is the individual code block objects
     const childrenArray = Array.isArray(children) ? children : [children];
@@ -19372,22 +19409,20 @@ const CodeTabs = (props) => {
         return Array.isArray(pre?.props?.children) ? pre.props.children[0] : pre?.props?.children;
     };
     const containAtLeastOneMermaid = childrenArray.some(pre => getCodeComponent(pre)?.props?.lang === 'mermaid');
-    // Render Mermaid diagram
     (0,external_react_.useEffect)(() => {
-        // Ensure we only render mermaids when frontend is hydrated to avoid hydration errors
-        // because mermaid mutates the DOM before react hydrates
-        if (typeof window !== 'undefined' && containAtLeastOneMermaid && isHydrated) {
-            __webpack_require__.e(/* import() */ 486).then(__webpack_require__.bind(__webpack_require__, 5486)).then(module => {
-                mermaid = module.default;
-                mermaid.initialize({
-                    startOnLoad: false,
-                    theme: theme === 'dark' ? 'dark' : 'default',
-                });
-                mermaid.run({
-                    nodes: document.querySelectorAll('.mermaid-render'),
-                });
-            });
-        }
+        // Wait for hydration so mermaid's DOM mutations don't cause mismatches
+        if (typeof window !== 'undefined' && containAtLeastOneMermaid && isHydrated && mermaidRef.current) {
+            queueMermaidNode(mermaidRef.current, theme);
+        }
+        return () => {
+            // Clear the batch timer on unmount to prevent mermaid from running
+            // after the DOM is torn down
+            if (mermaidFlushTimer) {
+                clearTimeout(mermaidFlushTimer);
+                mermaidFlushTimer = null;
+                mermaidQueue = [];
+            }
+        };
     }, [containAtLeastOneMermaid, theme, isHydrated]);
     function handleClick({ target }, index) {
         const $wrap = target.parentElement.parentElement;
@@ -19403,15 +19438,13 @@ const CodeTabs = (props) => {
         const codeComponent = getCodeComponent(childrenArray[0]);
         if (codeComponent?.props?.lang === 'mermaid') {
             const value = codeComponent?.props?.value;
-            return external_react_default().createElement("pre", { className: "mermaid-render mermaid_single" }, value);
+            return (external_react_default().createElement("pre", { ref: mermaidRef, className: "mermaid-render mermaid_single" }, value));
         }
     }
     return (external_react_default().createElement("div", { className: `CodeTabs CodeTabs_initial theme-${theme}` },
         external_react_default().createElement("div", { className: "CodeTabs-toolbar" }, childrenArray.map((pre, i) => {
             // the first or only child should be our Code component
-            const tabCodeComponent = Array.isArray(pre.props?.children)
-                ? pre.props.children[0]
-                : pre.props?.children;
+            const tabCodeComponent = Array.isArray(pre.props?.children) ? pre.props.children[0] : pre.props?.children;
             const lang = tabCodeComponent?.props?.lang;
             const meta = tabCodeComponent?.props?.meta;
             /* istanbul ignore next */
@@ -24926,10 +24959,10 @@ const TailwindStyle = ({ children, darkModeDataAttribute }) => {
                     addClasses(record.target);
                     shouldUpdate = true;
                 }
-                if (shouldUpdate) {
-                    setClasses(Array.from(classesSet.current));
-                }
             });
+            if (shouldUpdate) {
+                setClasses(Array.from(classesSet.current));
+            }
         });
         observer.observe(ref.current.parentElement, {
             subtree: true,
@@ -116256,11 +116289,33 @@ const parseBlock = (text) => {
     const tree = contentParser.runSync(contentParser.parse(text));
     return tree.children;
 };
-const parseInline = (text) => {
+/**
+ * Minimal parser for api-header titles.
+ * Disables markdown constructs that are not parsed in legacy (headings, lists)
+ */
+const apiHeaderTitleParser = unified()
+    .data('micromarkExtensions', [
+    legacyVariable(),
+    looseHtmlEntity(),
+    {
+        disable: {
+            null: [
+                'blockQuote',
+                'headingAtx',
+                'list',
+                'thematicBreak',
+            ],
+        },
+    },
+])
+    .data('fromMarkdownExtensions', [legacyVariableFromMarkdown(), looseHtmlEntityFromMarkdown()])
+    .use(remarkParse)
+    .use(remarkGfm);
+const parseApiHeaderTitle = (text) => {
     if (!text.trim())
         return textToInline(text);
-    const tree = contentParser.runSync(contentParser.parse(text));
-    return tree.children;
+    const tree = apiHeaderTitleParser.runSync(apiHeaderTitleParser.parse(text));
+    return tree.children.flatMap(n => n.type === 'paragraph' && 'children' in n ? n.children : [n]);
 };
 /**
  * Transform a magicBlock node into final MDAST nodes.
@@ -116319,7 +116374,7 @@ function transformMagicBlock(blockType, data, rawValue, options = {}) {
             const depth = headerJson.level || (compatibilityMode ? 1 : 2);
             return [
                 wrapPinnedBlocks({
-                    children: 'title' in headerJson ? parseInline(headerJson.title || '') : [],
+                    children: 'title' in headerJson ? parseApiHeaderTitle(headerJson.title || '') : [],
                     depth,
                     type: 'heading',
                 }, data),