@readme/markdown 14.10.3 → 14.11.0

package/dist/processor/transform/mdxish/remove-jsx-comments.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Removes JSX-style comments (e.g., { /* comment *\/ }) from content.
+ *
+ * `@param` content
+ * `@returns` Content with JSX comments removed
+ * `@example`
+ * ```typescript
+ * removeJSXComments('Text {/* comment *\/} more text') // => 'Text  more text'
+ * ```
+ */
+export declare function removeJSXComments(content: string): string;

package/dist/processor/transform/mdxish/resolve-esm-imports.d.ts

@@ -0,0 +1,13 @@
+import type { ImportDeclaration } from 'estree';
+export type ModuleRegistry = Record<string, unknown>;
+export declare const defaultModuleRegistry: ModuleRegistry;
+/**
+ * Turn `import` declarations into a flat map of binding → value.
+ *
+ * A "binding" is a mapping of a local name to the value of it in the module exports
+ * Example: `import { useState } from 'react'` yields `{ useState: React.useState }`.
+ *
+ * Unsupported specifiers are skipped with a warning rather than throwing, so a
+ * single unknown import can't break the rest of the document.
+ */
+export declare const collectImportValues: (importDeclarations: ImportDeclaration[], registry?: ModuleRegistry) => Record<string, unknown>;

package/dist/render-fixture.node.js

@@ -120921,12 +120921,60 @@ function restoreSnakeCase(placeholderName, mapping) {
     return matchingKey ? mapping[matchingKey] : placeholderName;
 }
 
+;// ./processor/transform/mdxish/resolve-esm-imports.ts
+
+// We provide React as a default module so that components can use hooks
+// and it's a common use case. Add other common libraries here.
+const defaultModuleRegistry = { react: (external_react_default()) };
+const isRecord = (value) => typeof value === 'object' && value !== null;
+// Get the value of a named export from a module
+const getModuleExport = (module, importedName) => isRecord(module) && importedName in module ? module[importedName] : undefined;
+/**
+ * Turn `import` declarations into a flat map of binding → value.
+ *
+ * A "binding" is a mapping of a local name to the value of it in the module exports
+ * Example: `import { useState } from 'react'` yields `{ useState: React.useState }`.
+ *
+ * Unsupported specifiers are skipped with a warning rather than throwing, so a
+ * single unknown import can't break the rest of the document.
+ */
+const collectImportValues = (importDeclarations, registry = defaultModuleRegistry) => {
+    const importValues = {};
+    importDeclarations.forEach(declaration => {
+        const libraryName = declaration.source.value;
+        if (typeof libraryName !== 'string')
+            return;
+        if (!(libraryName in registry)) {
+            // eslint-disable-next-line no-console
+            console.warn(`[WARNING] Cannot resolve import "${libraryName}"; it is not a supported library.`);
+            return;
+        }
+        const module = registry[libraryName];
+        declaration.specifiers.forEach(spec => {
+            // Default (`import React`) and namespace (`import * as React`) both bind
+            // the whole module under the local name.
+            if (spec.type === 'ImportDefaultSpecifier' || spec.type === 'ImportNamespaceSpecifier') {
+                importValues[spec.local.name] = module;
+            }
+            else if (spec.type === 'ImportSpecifier') {
+                // Named imports (e.g. `import { useState } from 'react'`, useState is the import name)
+                const importName = spec.imported.type === 'Identifier' ? spec.imported.name : spec.imported.value;
+                if (typeof importName === 'string') {
+                    importValues[spec.local.name] = getModuleExport(module, importName);
+                }
+            }
+        });
+    });
+    return importValues;
+};
+
 ;// ./processor/transform/mdxish/evaluate-exports.ts
 
 
 
 
 
+
 /**
  * Recursively extract all identifier names introduced by a binding pattern.
  * Handles destructuring (`{ a, b }`, `[x, y]`), rest elements (`...rest`),
@@ -120974,6 +121022,7 @@ const collectExportNames = (declaration) => {
 const evaluateExports = () => (tree, file) => {
     const programBody = [];
     const exportNames = [];
+    const importDeclarations = [];
     const nodesToRemove = [];
     lib_visit(tree, isMDXEsm, (node, index, parent) => {
         if (parent && typeof index === 'number') {
@@ -120987,6 +121036,10 @@ const evaluateExports = () => (tree, file) => {
         // handled the same as a named export — the inner declaration carries the
         // binding name
         estreeBody.forEach(statement => {
+            if (statement.type === 'ImportDeclaration') {
+                importDeclarations.push(statement);
+                return;
+            }
             let declaration = null;
             if (statement.type === 'ExportNamedDeclaration' && statement.declaration) {
                 declaration = statement.declaration;
@@ -121014,9 +121067,11 @@ const evaluateExports = () => (tree, file) => {
         const program = { type: 'Program', sourceType: 'module', body: programBody };
         buildJsx(program, { runtime: 'classic', pragma: 'React.createElement', pragmaFrag: 'React.Fragment' });
         const { value: source } = toJs(program);
+        // Make sure import values are available in the scope
+        const importValues = collectImportValues(importDeclarations);
         // Evaluate and build on the expression source
         // Use react to compile JSX codes
-        const evaluatedExports = evaluate(`(() => { ${source}\nreturn { ${exportNames.join(', ')} }; })()`, { React: (external_react_default()) });
+        const evaluatedExports = evaluate(`(() => { ${source}\nreturn { ${exportNames.join(', ')} }; })()`, { React: (external_react_default()), ...importValues });
         Object.assign(scope, evaluatedExports);
     }
     catch (error) {
@@ -124388,214 +124443,21 @@ const normalizeMdxJsxNodes = () => tree => {
  */
 const JSX_COMMENT_REGEX = /\{\/\*[^*]*(?:\*(?!\/)[^*]*)*\*\/\}/g;
 
-;// ./processor/transform/mdxish/preprocess-jsx-expressions.ts
-
+;// ./processor/transform/mdxish/remove-jsx-comments.ts
 
 /**
  * Removes JSX-style comments (e.g., { /* comment *\/ }) from content.
  *
- * @param content
- * @returns Content with JSX comments removed
- * @example
+ * `@param` content
+ * `@returns` Content with JSX comments removed
+ * `@example`
  * ```typescript
- * removeJSXComments('Text { /* comment *\/ } more text')
- * // Returns: 'Text  more text'
+ * removeJSXComments('Text {/* comment *\/} more text') // => 'Text  more text'
  * ```
  */
 function removeJSXComments(content) {
     return content.replace(JSX_COMMENT_REGEX, '');
 }
-const HTML_ELEM_PLACEHOLDER_PREFIX = '___MDXISH_HTML_ELEM_';
-const HTML_ELEM_PLACEHOLDER = new RegExp(`${HTML_ELEM_PLACEHOLDER_PREFIX}(\\d+)___`, 'g');
-// Matches an HTML element that starts at a line boundary and ends at a line boundary.
-// Allows optional leading indentation and lazily matches until the same closing tag.
-const BLOCK_HTML_RE = /(?<=^|\n)[ \t]*<([a-z][a-zA-Z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>[ \t]*(?=\n|$)/g;
-/**
- * Hides line-anchored HTML elements from the brace-escaping pass so we don't leak `\{`
- * into rendered output (rehypeRaw renders the `\` literally, e.g. `<div>{foo</div>`).
- *
- * One carve-out: if an interior line at column 0 has bare text containing `{`, mdxish
- * parses that line as a paragraph and the mdxExpression step would throw without an
- * escape — so we leave that case to the brace balancer.
- */
-function protectHTMLElements(content) {
-    const htmlElements = [];
-    const protectedContent = content.replace(BLOCK_HTML_RE, match => {
-        // Look at the lines between the open and close tags. If any of them starts
-        // at column 0 with bare text (not whitespace, not another tag) and contains
-        // `{`, mdxish will parse that line as a paragraph and the brace as an MDX
-        // expression, which would throw an error. So we let the brace balancer escape it.
-        // Otherwise, we need to extract the sequence to protect it from the brace escaping.
-        const interior = match.split('\n').slice(1, -1);
-        const hazard = interior.some(line => line.length > 0 && line[0] !== ' ' && line[0] !== '\t' && line[0] !== '<' && line.includes('{'));
-        if (hazard)
-            return match;
-        htmlElements.push(match);
-        return `${HTML_ELEM_PLACEHOLDER_PREFIX}${htmlElements.length - 1}___`;
-    });
-    return { htmlElements, protectedContent };
-}
-function restoreHTMLElements(content, htmlElements) {
-    if (htmlElements.length === 0)
-        return content;
-    return content.replace(HTML_ELEM_PLACEHOLDER, (_m, idx) => htmlElements[parseInt(idx, 10)]);
-}
-const ESM_DECLARATION_START = /^(?:export|import)\b/;
-/**
- * Whether a line begins a top-level `export`/`import` declaration. Its braces
- * are valid JS owned by the mdxjsEsm tokenizer (which tolerates blank lines),
- * so escaping them would corrupt the source and break acorn parsing.
- */
-function startsEsmDeclaration(chars, lineStart) {
-    return ESM_DECLARATION_START.test(chars.slice(lineStart, lineStart + 7).join(''));
-}
-function isBlankLine(chars, lineStart) {
-    for (let i = lineStart; i < chars.length; i += 1) {
-        if (chars[i] === '\n')
-            return true;
-        if (chars[i] !== ' ' && chars[i] !== '\t')
-            return false;
-    }
-    return true;
-}
-/**
- * Escapes unbalanced and paragraph-spanning braces so MDX doesn't trip on them.
- */
-function escapeProblematicBraces(content) {
-    const { htmlElements, protectedContent } = protectHTMLElements(content);
-    let strDelim = null;
-    let strEscaped = false;
-    // Track position of last newline (outside strings) to detect blank lines
-    // -2 means no recent newline
-    let lastNewlinePos = -2;
-    // Character state machine trackers
-    const toEscape = new Set();
-    // Convert to array of Unicode code points so that emojis and multi-byte characters are correctly tracked
-    const chars = Array.from(protectedContent);
-    const openStack = [];
-    // Whether the current top-level statement is an `export`/`import` declaration.
-    let insideEsmDeclaration = false;
-    for (let i = 0; i < chars.length; i += 1) {
-        const ch = chars[i];
-        // At a top-level (brace depth 0) line start, decide whether we're inside an
-        // ESM declaration. The flag persists across the declaration's own lines.
-        if (openStack.length === 0 && (i === 0 || chars[i - 1] === '\n')) {
-            if (startsEsmDeclaration(chars, i))
-                insideEsmDeclaration = true;
-            else if (isBlankLine(chars, i))
-                insideEsmDeclaration = false;
-        }
-        // Track string delimiters inside expressions to ignore braces within them
-        if (openStack.length > 0) {
-            if (strDelim) {
-                if (strEscaped)
-                    strEscaped = false;
-                else if (ch === '\\')
-                    strEscaped = true;
-                else if (ch === strDelim)
-                    strDelim = null;
-                // eslint-disable-next-line no-continue
-                continue;
-            }
-            if (ch === '"' || ch === "'" || ch === '`') {
-                strDelim = ch;
-                // eslint-disable-next-line no-continue
-                continue;
-            }
-            if (ch === '\n') {
-                if (lastNewlinePos >= 0) {
-                    const between = chars.slice(lastNewlinePos + 1, i).join('');
-                    if (/^[ \t]*$/.test(between)) {
-                        openStack.forEach(entry => { entry.hasBlankLine = true; });
-                    }
-                }
-                lastNewlinePos = i;
-            }
-        }
-        // Skip already-escaped braces (odd run of preceding backslashes).
-        if (ch === '{' || ch === '}') {
-            let bs = 0;
-            for (let j = i - 1; j >= 0 && chars[j] === '\\'; j -= 1)
-                bs += 1;
-            if (bs % 2 === 1) {
-                // eslint-disable-next-line no-continue
-                continue;
-            }
-        }
-        if (ch === '{') {
-            // `=` (after whitespace) before `{` ⇒ JSX attribute expression. The
-            // mdxComponent tokenizer captures the whole component, so blank lines
-            // inside attribute values are harmless. Nested `{` inherits the flag.
-            let isAttrExpr = false;
-            for (let j = i - 1; j >= 0; j -= 1) {
-                const pc = chars[j];
-                if (pc === '=') {
-                    isAttrExpr = true;
-                    break;
-                }
-                if (pc !== ' ' && pc !== '\t')
-                    break;
-            }
-            // Nested `{ ... }` inside an attribute value (e.g. `data={[{ ... }]}` or
-            // `data={{ a: { b: 1 } }}`) must inherit the same exemption; only the
-            // outer `{` is directly after `=`.
-            if (!isAttrExpr && openStack.length > 0 && openStack[openStack.length - 1].isAttrExpr) {
-                isAttrExpr = true;
-            }
-            openStack.push({ pos: i, hasBlankLine: false, isAttrExpr, isEsmDeclaration: insideEsmDeclaration });
-            lastNewlinePos = -2;
-        }
-        else if (ch === '}') {
-            if (openStack.length > 0) {
-                const entry = openStack.pop();
-                // The declaration's braces are closed; later top-level braces are not ESM.
-                if (openStack.length === 0)
-                    insideEsmDeclaration = false;
-                // Pure `{/* ... */}` comments are handled downstream by the jsxComment
-                // tokenizer — escaping their braces would prevent it from running.
-                const isPureJsxComment = chars[entry.pos + 1] === '/' &&
-                    chars[entry.pos + 2] === '*' &&
-                    chars[i - 1] === '/' &&
-                    chars[i - 2] === '*';
-                if (entry.hasBlankLine && !isPureJsxComment && !entry.isAttrExpr && !entry.isEsmDeclaration) {
-                    toEscape.add(entry.pos);
-                    toEscape.add(i);
-                }
-            }
-            else {
-                toEscape.add(i);
-            }
-        }
-        else if (ch === ';' && openStack.length === 0) {
-            // A top-level `;` ends the current statement, ESM or otherwise.
-            insideEsmDeclaration = false;
-        }
-    }
-    // Anything still open is unbalanced.
-    openStack.forEach(entry => {
-        if (!entry.isEsmDeclaration)
-            toEscape.add(entry.pos);
-    });
-    // Reconstruct the content with the escaped braces.
-    const escapedContent = toEscape.size === 0 ? protectedContent : chars.map((ch, i) => (toEscape.has(i) ? `\\${ch}` : ch)).join('');
-    return restoreHTMLElements(escapedContent, htmlElements);
-}
-/**
- * Preprocesses JSX-like markdown content before parsing.
- *
- * JSX attribute expressions (`href={baseUrl}`) are no longer rewritten here —
- * they flow through the tokenizer as `mdxJsxAttributeValueExpression` nodes
- * and are evaluated at the hast handler step.
- *
- * @param content
- * @returns Preprocessed content ready for markdown parsing
- */
-function preprocessJSXExpressions(content) {
-    const { protectedCode, protectedContent } = protectCodeBlocks(content);
-    let processed = escapeProblematicBraces(protectedContent);
-    processed = restoreCodeBlocks(processed, protectedCode);
-    return processed;
-}
 
 ;// ./processor/transform/mdxish/resolve-deferred-attribute-expression-props.ts
 
@@ -125570,6 +125432,85 @@ function syntax_jsxTable() {
 ;// ./lib/micromark/jsx-table/index.ts
 
 
+;// ./lib/micromark/mdx-expression-lenient/syntax.ts
+
+
+/**
+ * Lenient MDX text-expression tokenizer (agnostic / no acorn).
+ *
+ * Matches a balanced `{ ... }` run — tracking nested braces and spanning soft
+ * line breaks — and emits the standard `mdxTextExpression*` tokens so the
+ * upstream `mdxExpressionFromMarkdown()` builds the node.
+ *
+ * Reimplements the official micromark mdxExpression, but an unbalanced brace that
+ * reaches end of input returns `nok` instead of throwing: micromark rolls back
+ * and the `{` renders as literal text, making the pipeline forgiving of stray
+ * braces that upstream would hard-error on.
+ */
+function tokenizeTextExpression(effects, ok, nok) {
+    let depth = 0;
+    return start;
+    function start(code) {
+        if (code !== codes.leftCurlyBrace)
+            return nok(code);
+        effects.enter('mdxTextExpression');
+        effects.enter('mdxTextExpressionMarker');
+        effects.consume(code);
+        effects.exit('mdxTextExpressionMarker');
+        return before;
+    }
+    function before(code) {
+        if (code === codes.eof) {
+            effects.exit('mdxTextExpression');
+            return nok(code);
+        }
+        if (markdownLineEnding(code)) {
+            effects.enter('lineEnding');
+            effects.consume(code);
+            effects.exit('lineEnding');
+            return before;
+        }
+        if (code === codes.rightCurlyBrace && depth === 0) {
+            return close(code);
+        }
+        effects.enter('mdxTextExpressionChunk');
+        return inside(code);
+    }
+    function inside(code) {
+        if (code === codes.eof || markdownLineEnding(code)) {
+            effects.exit('mdxTextExpressionChunk');
+            return before(code);
+        }
+        if (code === codes.rightCurlyBrace && depth === 0) {
+            effects.exit('mdxTextExpressionChunk');
+            return close(code);
+        }
+        if (code === codes.leftCurlyBrace)
+            depth += 1;
+        else if (code === codes.rightCurlyBrace)
+            depth -= 1;
+        effects.consume(code);
+        return inside;
+    }
+    function close(code) {
+        effects.enter('mdxTextExpressionMarker');
+        effects.consume(code);
+        effects.exit('mdxTextExpressionMarker');
+        effects.exit('mdxTextExpression');
+        return ok;
+    }
+}
+function mdxExpressionLenient() {
+    return {
+        text: {
+            [codes.leftCurlyBrace]: {
+                name: 'mdxTextExpression',
+                tokenize: tokenizeTextExpression,
+            },
+        },
+    };
+}
+
 ;// ./lib/utils/mdxish/mdxish-load-components.ts
 
 
@@ -125682,7 +125623,7 @@ const defaultTransformers = [
  * 1. Normalize malformed table separator syntax (e.g., `|: ---` → `| :---`)
  * 2. Terminate HTML flow blocks so subsequent content isn't swallowed
  * 3. Close invalid "self-closing" HTML tags (e.g., `<i />` → `<i></i>`)
- * 4. Escape problematic braces so MDX expression parsing doesn't choke
+ * 4. Normalize compact ATX headings (e.g., `#Heading` → `# Heading`)
  * 5. Replace snake_case component names with parser-safe placeholders
  */
 function preprocessContent(content, opts) {
@@ -125691,7 +125632,6 @@ function preprocessContent(content, opts) {
     result = terminateHtmlFlowBlocks(result);
     result = closeSelfClosingHtmlTags(result);
     result = normalizeCompactHeadings(result);
-    result = preprocessJSXExpressions(result);
     return processSnakeCaseComponent(result, { knownComponents });
 }
 function mdxishAstProcessor(mdContent, opts = {}) {
@@ -125708,12 +125648,8 @@ function mdxishAstProcessor(mdContent, opts = {}) {
         acc[key] = String(value);
         return acc;
     }, {});
-    // Get mdxExpression extension and remove its flow construct to prevent
-    // `{...}` from interrupting paragraphs (which breaks multiline magic blocks)
-    const mdxExprExt = syntax_mdxExpression({ allowEmpty: true });
-    const mdxExprTextOnly = {
-        text: mdxExprExt.text,
-    };
+    // Parser extension for MDX expressions {}
+    const mdxExprTextOnly = mdxExpressionLenient();
     const micromarkExts = [
         syntax_jsxTable(),
         syntax_magicBlock(),