safe-mdx 1.3.10 → 1.4.0

package/src/parse.ts

@@ -9,6 +9,62 @@ import { parseHtmlToMdxAst, remarkMdxJsxNormalize } from './html/html-to-mdx-ast
 
 export { parseHtmlToMdxAst, remarkMdxJsxNormalize }
 
+/* ── Import extraction ──────────────────────────────────────────────── */
+
+export type MdxImportSpecifier = {
+    /** Name used in MDX (e.g. `Card`, `MyButton`, `Utils`) */
+    local: string
+    /** Original export name. `'default'` for default imports, local name for named, `'*'` for namespace */
+    imported: string
+    type: 'named' | 'default' | 'namespace'
+}
+
+export type MdxImport = {
+    /** Raw source string as written: `'./card'`, `'/snippets/ui'`, `'some-pkg'` */
+    source: string
+    specifiers: MdxImportSpecifier[]
+}
+
+/**
+ * Extract all import declarations from a parsed mdast tree.
+ * Unlike `parseEsmImports`, this accepts ANY source (not just HTTPS URLs).
+ */
+export function extractImports(ast: Root): MdxImport[] {
+    const imports: MdxImport[] = []
+
+    for (const node of ast.children) {
+        if (node.type !== 'mdxjsEsm') continue
+        const estree = (node as any).data?.estree
+        if (!estree) continue
+
+        for (const statement of estree.body) {
+            if (statement.type !== 'ImportDeclaration') continue
+            const source = statement.source?.value
+            if (typeof source !== 'string') continue
+
+            const specifiers: MdxImportSpecifier[] = []
+            for (const spec of statement.specifiers ?? []) {
+                if (spec.type === 'ImportDefaultSpecifier') {
+                    specifiers.push({ local: spec.local.name, imported: 'default', type: 'default' })
+                } else if (spec.type === 'ImportSpecifier') {
+                    const importedName = spec.imported.type === 'Identifier'
+                        ? spec.imported.name
+                        : String(spec.imported.value)
+                    specifiers.push({ local: spec.local.name, imported: importedName, type: 'named' })
+                } else if (spec.type === 'ImportNamespaceSpecifier') {
+                    specifiers.push({ local: spec.local.name, imported: '*', type: 'namespace' })
+                }
+            }
+
+            if (specifiers.length > 0) {
+                imports.push({ source, specifiers })
+            }
+        }
+    }
+
+    return imports
+}
+
 export function mdxParse(code: string) {
     const file = mdxProcessor.processSync(code)
     return file.data.ast as Root
@@ -95,6 +151,115 @@ export function remarkMarkAndUnravel() {
     }
 }
 
+/* ── Module resolution ───────────────────────────────────────────────── */
+
+/** Extensions tried when resolving a bare import against glob keys */
+const RESOLVE_EXTENSIONS = [
+    '', '.tsx', '.ts', '.jsx', '.js', '.mdx', '.md',
+    '/index.tsx', '/index.ts', '/index.jsx', '/index.js',
+]
+
+/**
+ * Given an import source and a baseUrl, resolve the source to a key
+ * that exists in `moduleKeys`. Handles:
+ * - Relative imports (`./card`) resolved from `baseUrl`
+ * - Absolute imports (`/snippets/card`) normalized to `./snippets/card`
+ * - Extension resolution (tries .tsx, .ts, .jsx, .js, .mdx, .md, /index.*)
+ */
+export function resolveModulePath(
+    source: string,
+    baseUrl: string,
+    moduleKeys: string[],
+): string | undefined {
+    let normalized: string
+
+    if (source.startsWith('/')) {
+        // Absolute import from project root: /snippets/card → ./snippets/card
+        normalized = '.' + source
+    } else if (source.startsWith('./') || source.startsWith('../')) {
+        // Relative import: resolve from baseUrl
+        const joined = joinPaths(baseUrl, source)
+        if (!joined) return undefined // .. escaped above root
+        normalized = joined
+    } else {
+        // Bare specifier (npm package etc.) — not resolvable from glob
+        return undefined
+    }
+
+    // Try each extension
+    for (const ext of RESOLVE_EXTENSIONS) {
+        const candidate = normalized + ext
+        if (moduleKeys.includes(candidate)) {
+            return candidate
+        }
+    }
+
+    return undefined
+}
+
+/** Simple path join that normalizes `./a/b/../c` segments.
+ *  Both inputs and output use `./` prefix (matching Vite glob key format).
+ *  Returns `undefined` if `..` escapes above the project root. */
+function joinPaths(base: string, relative: string): string | undefined {
+    // Strip ./ prefix and trailing /
+    const baseParts = base.replace(/^\.\//, '').replace(/\/$/, '').split('/').filter(Boolean)
+    const relParts = relative.replace(/^\.\//, '').split('/').filter(Boolean)
+
+    for (const part of relParts) {
+        if (part === '..') {
+            if (baseParts.length === 0) return undefined // escaped above root
+            baseParts.pop()
+        } else if (part !== '.') {
+            baseParts.push(part)
+        }
+    }
+
+    return './' + baseParts.join('/')
+}
+
+export type LazyGlob = Record<string, () => Promise<Record<string, any>>>
+export type EagerModules = Record<string, Record<string, any>>
+
+/**
+ * Given a lazy Vite glob and a parsed mdast, resolve only the imported
+ * modules eagerly. Returns the exact shape `SafeMdxRenderer.modules` expects.
+ *
+ * Usage:
+ * ```ts
+ * const lazyGlob = import.meta.glob('./snippets/*.tsx')
+ * const mdast = mdxParse(mdxString)
+ * const modules = await resolveModules({ glob: lazyGlob, mdast, baseUrl: './pages/' })
+ * <SafeMdxRenderer modules={modules} baseUrl="./pages/" ... />
+ * ```
+ */
+export async function resolveModules({
+    glob,
+    mdast,
+    baseUrl,
+}: {
+    glob: LazyGlob
+    mdast: Root
+    baseUrl: string
+}): Promise<EagerModules> {
+    const imports = extractImports(mdast)
+    if (imports.length === 0) return {}
+
+    const keys = Object.keys(glob)
+    const result: EagerModules = {}
+
+    await Promise.all(
+        imports.map(async (imp) => {
+            const resolved = resolveModulePath(imp.source, baseUrl, keys)
+            if (!resolved || !glob[resolved]) return
+            // Avoid loading the same module twice
+            if (result[resolved]) return
+            result[resolved] = await glob[resolved]()
+        }),
+    )
+
+    return result
+}
+
 const mdxProcessor = remark()
     .use(remarkMdx)
     .use(remarkFrontmatter, ['yaml', 'toml'])

package/src/safe-mdx.test.tsx

@@ -3498,5 +3498,118 @@ test("skip unknown elements in complex nested HTML structures", () => {
 </div>
 `);
   
-  expect(html).toMatchInlineSnapshot(`"<h1>Main Title</h1><article><header><h1>Article Title</h1></header><section><blockquote><p>A famous quote</p></blockquote></section><footer></footer></article><h2>Another Section</h2><div></div>"`);
+   expect(html).toMatchInlineSnapshot(`"<h1>Main Title</h1><article><header><h1>Article Title</h1></header><section><blockquote><p>A famous quote</p></blockquote></section><footer></footer></article><h2>Another Section</h2><div></div>"`);
 });
+
+/* ── modules prop tests ─────────────────────────────────────────────── */
+
+test('modules prop: resolves named import from absolute path', () => {
+    function CustomBadge({ label }: { label: string }) {
+        return <span className="badge">{label}</span>
+    }
+
+    const code = dedent`
+        import { CustomBadge } from '/snippets/badge'
+
+        # Hello
+
+        <CustomBadge label="Works" />
+    `
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        modules: {
+            './snippets/badge.tsx': { CustomBadge },
+        },
+        baseUrl: './pages/',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toMatchInlineSnapshot(`"<h1>Hello</h1><span class="badge">Works</span>"`)
+    expect(visitor.errors).toMatchInlineSnapshot(`[]`)
+})
+
+test('modules prop: resolves default import from relative path', () => {
+    function MyCard({ children }: { children?: React.ReactNode }) {
+        return <div className="card">{children}</div>
+    }
+
+    const code = dedent`
+        import MyCard from './card'
+
+        <MyCard>content</MyCard>
+    `
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        modules: {
+            './pages/card.tsx': { default: MyCard },
+        },
+        baseUrl: './pages/',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toMatchInlineSnapshot(`"<div class="card">content</div>"`)
+    expect(visitor.errors).toMatchInlineSnapshot(`[]`)
+})
+
+test('modules prop: resolves namespace import with dot notation', () => {
+    function Card({ title }: { title: string }) {
+        return <div>{title}</div>
+    }
+    function Badge({ label }: { label: string }) {
+        return <span>{label}</span>
+    }
+
+    const code = dedent`
+        import * as UI from './ui'
+
+        <UI.Card title="hello" />
+        <UI.Badge label="tag" />
+    `
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        modules: {
+            './components/ui.tsx': { Card, Badge },
+        },
+        baseUrl: './components/',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toMatchInlineSnapshot(`"<div>hello</div><span>tag</span>"`)
+    expect(visitor.errors).toMatchInlineSnapshot(`[]`)
+})
+
+test('modules prop: unresolved import produces error', () => {
+    const code = dedent`
+        import { Missing } from './nonexistent'
+
+        <Missing />
+    `
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        modules: {},
+        baseUrl: './pages/',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toMatchInlineSnapshot(`""`)
+    expect(visitor.errors).toMatchInlineSnapshot(`
+      [
+        {
+          "line": 3,
+          "message": "Unsupported jsx component Missing",
+        },
+      ]
+    `)
+})

package/src/safe-mdx.tsx

@@ -9,6 +9,7 @@ import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx-jsx'
 import { Fragment, ReactNode } from 'react'
 import { DynamicEsmComponent } from 'safe-mdx/client'
 import { extractComponentInfo, parseEsmImports } from './esm-parser.js'
+import { resolveModulePath, type EagerModules } from './parse.js'
 import { htmlToMdxAst } from './html/html-to-mdx-ast.js'
 import { validHtmlElements, nativeTags } from './html/valid-html-elements.js'
 
@@ -51,6 +52,8 @@ export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
     createElement,
     allowClientEsmImports = false,
     addMarkdownLineNumbers = false,
+    modules,
+    baseUrl,
 }: {
     components?: ComponentsMap
     markdown?: string
@@ -60,6 +63,13 @@ export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
     createElement?: CreateElementFunction
     allowClientEsmImports?: boolean
     addMarkdownLineNumbers?: boolean
+    /** Pre-resolved modules keyed by file path (e.g. from `import.meta.glob`).
+     *  When MDX contains `import { Card } from './card'`, the import source is
+     *  resolved against these keys using `baseUrl` for relative paths. */
+    modules?: EagerModules
+    /** Directory of the current MDX file, used to resolve relative import
+     *  sources against `modules` keys. E.g. `'./pages/getting-started/'` */
+    baseUrl?: string
 }) {
     const visitor = new MdastToJsx({
         markdown,
@@ -70,6 +80,8 @@ export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
         createElement,
         allowClientEsmImports,
         addMarkdownLineNumbers,
+        modules,
+        baseUrl,
     })
     const result = visitor.run()
     return result
@@ -87,6 +99,8 @@ export class MdastToJsx {
     esmImports: Map<string, string> = new Map()
     allowClientEsmImports: boolean
     addMarkdownLineNumbers: boolean
+    modules?: EagerModules
+    baseUrl?: string
 
     constructor({
         markdown: code = '',
@@ -97,6 +111,8 @@ export class MdastToJsx {
         createElement = React.createElement,
         allowClientEsmImports = false,
         addMarkdownLineNumbers = false,
+        modules,
+        baseUrl,
     }: {
         markdown?: string
         mdast: MyRootContent
@@ -109,6 +125,8 @@ export class MdastToJsx {
         createElement?: CreateElementFunction
         allowClientEsmImports?: boolean
         addMarkdownLineNumbers?: boolean
+        modules?: EagerModules
+        baseUrl?: string
     }) {
         this.str = code
 
@@ -124,6 +142,9 @@ export class MdastToJsx {
 
         this.addMarkdownLineNumbers = addMarkdownLineNumbers
 
+        this.modules = modules
+        this.baseUrl = baseUrl
+
         this.c = {
             ...Object.fromEntries(
                 nativeTags.map((tag) => {
@@ -132,6 +153,45 @@ export class MdastToJsx {
             ),
             ...components,
         }
+
+    }
+
+    /**
+     * Resolve import declarations from an mdxjsEsm node against `this.modules`.
+     * Resolved components are added directly to `this.c` (the component map)
+     * so the existing `accessWithDot` lookup finds them.
+     */
+    resolveImportsFromModules(node: MyRootContent): void {
+        const estree = (node as any).data?.estree
+        if (!estree) return
+
+        const moduleKeys = Object.keys(this.modules!)
+
+        for (const statement of estree.body) {
+            if (statement.type !== 'ImportDeclaration') continue
+            const source: string = statement.source?.value
+            if (typeof source !== 'string') continue
+
+            const resolved = resolveModulePath(source, this.baseUrl || './', moduleKeys)
+            if (!resolved) continue
+            const mod = this.modules![resolved]
+            if (!mod) continue
+
+            for (const spec of statement.specifiers ?? []) {
+                if (spec.type === 'ImportDefaultSpecifier') {
+                    this.c[spec.local.name] = mod.default ?? mod
+                } else if (spec.type === 'ImportSpecifier') {
+                    const importedName = spec.imported.type === 'Identifier'
+                        ? spec.imported.name
+                        : String(spec.imported.value)
+                    this.c[spec.local.name] = mod[importedName]
+                } else if (spec.type === 'ImportNamespaceSpecifier') {
+                    // Namespace import: import * as UI from '...'
+                    // Supports <UI.Card> via accessWithDot
+                    this.c[spec.local.name] = mod
+                }
+            }
+        }
     }
 
     addLineNumberToProps(
@@ -588,7 +648,11 @@ export class MdastToJsx {
 
         switch (node.type) {
             case 'mdxjsEsm': {
-                // Parse ESM imports and merge into our imports map (only if allowed)
+                // Resolve imports from pre-loaded modules (server-side)
+                if (this.modules) {
+                    this.resolveImportsFromModules(node)
+                }
+                // Parse ESM imports for client-side dynamic loading (only if allowed)
                 if (this.allowClientEsmImports) {
                     const parsedImports = parseEsmImports(node, (err) =>
                         this.errors.push(err),