safe-mdx 1.3.10 → 1.5.0

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'
 
@@ -28,7 +29,10 @@ export type RenderNode = (
     transform: (node: MyRootContent) => ReactNode,
 ) => ReactNode | undefined
 
+export type SafeMdxErrorType = 'validation' | 'missing-component' | 'expression' | 'esm-import'
+
 export interface SafeMdxError {
+    type: SafeMdxErrorType
     message: string
     line?: number
     schemaPath?: string
@@ -51,6 +55,9 @@ export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
     createElement,
     allowClientEsmImports = false,
     addMarkdownLineNumbers = false,
+    modules,
+    baseUrl,
+    onError,
 }: {
     components?: ComponentsMap
     markdown?: string
@@ -60,6 +67,16 @@ 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
+    /** Called for each error during rendering (missing components, invalid props, failed expressions).
+     *  Throw inside this callback to stop rendering on first error. */
+    onError?: (error: SafeMdxError) => void
 }) {
     const visitor = new MdastToJsx({
         markdown,
@@ -70,6 +87,9 @@ export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
         createElement,
         allowClientEsmImports,
         addMarkdownLineNumbers,
+        modules,
+        baseUrl,
+        onError,
     })
     const result = visitor.run()
     return result
@@ -87,6 +107,9 @@ export class MdastToJsx {
     esmImports: Map<string, string> = new Map()
     allowClientEsmImports: boolean
     addMarkdownLineNumbers: boolean
+    modules?: EagerModules
+    baseUrl?: string
+    onError?: (error: SafeMdxError) => void
 
     constructor({
         markdown: code = '',
@@ -97,6 +120,9 @@ export class MdastToJsx {
         createElement = React.createElement,
         allowClientEsmImports = false,
         addMarkdownLineNumbers = false,
+        modules,
+        baseUrl,
+        onError,
     }: {
         markdown?: string
         mdast: MyRootContent
@@ -109,6 +135,11 @@ export class MdastToJsx {
         createElement?: CreateElementFunction
         allowClientEsmImports?: boolean
         addMarkdownLineNumbers?: boolean
+        modules?: EagerModules
+        baseUrl?: string
+        /** Called for each error during rendering (missing components, invalid props, failed expressions).
+         *  Throw inside this callback to stop rendering on first error. */
+        onError?: (error: SafeMdxError) => void
     }) {
         this.str = code
 
@@ -124,6 +155,10 @@ export class MdastToJsx {
 
         this.addMarkdownLineNumbers = addMarkdownLineNumbers
 
+        this.modules = modules
+        this.baseUrl = baseUrl
+        this.onError = onError
+
         this.c = {
             ...Object.fromEntries(
                 nativeTags.map((tag) => {
@@ -132,6 +167,50 @@ export class MdastToJsx {
             ),
             ...components,
         }
+
+    }
+
+    pushError(error: SafeMdxError): void {
+        this.errors.push(error)
+        this.onError?.(error)
+    }
+
+    /**
+     * 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(
@@ -174,7 +253,8 @@ export class MdastToJsx {
             if (result.issues) {
                 result.issues.forEach((issue) => {
                     const propPath = issue.path?.join('.') || 'unknown'
-                    this.errors.push({
+                    this.pushError({
+                        type: 'validation',
                         message: `Invalid props for component "${componentName}" at "${propPath}": ${issue.message}`,
                         line,
                         schemaPath: issue.path?.join('.'),
@@ -242,7 +322,7 @@ export class MdastToJsx {
                         extractComponentInfo(esmImportInfo)
                     Component = DynamicEsmComponent
                     let attrsList = this.getJsxAttrs(node, (err) => {
-                        this.errors.push(err)
+                        this.pushError(err)
                     })
                     let attrs = Object.fromEntries(attrsList)
 
@@ -258,7 +338,8 @@ export class MdastToJsx {
                     Component = accessWithDot(this.c, node.name)
 
                     if (!Component) {
-                        this.errors.push({
+                        this.pushError({
+                            type: 'missing-component',
                             message: `Unsupported jsx component ${node.name}`,
                             line: node.position?.start?.line,
                         })
@@ -267,7 +348,7 @@ export class MdastToJsx {
                 }
 
                 let attrsList = this.getJsxAttrs(node, (err) => {
-                    this.errors.push(err)
+                    this.pushError(err)
                 })
 
                 let attrs = Object.fromEntries(attrsList)
@@ -305,6 +386,7 @@ export class MdastToJsx {
                         : null
                 if (!tagName) {
                     onError?.({
+                        type: 'expression',
                         message: 'JSX element missing component name',
                         line: line,
                     })
@@ -327,6 +409,7 @@ export class MdastToJsx {
                     Component = accessWithDot(this.c, tagName)
                     if (!Component) {
                         onError?.({
+                            type: 'missing-component',
                             message: `Unsupported jsx component ${tagName} in attribute`,
                             line: line,
                         })
@@ -394,6 +477,7 @@ export class MdastToJsx {
         } catch (error) {
             // Return null if transformation fails
             onError?.({
+                type: 'expression',
                 message: `Failed to transform JSX element: ${
                     error instanceof Error ? error.message : 'Unknown error'
                 }`,
@@ -435,6 +519,7 @@ export class MdastToJsx {
                                 }
                             } catch (error) {
                                 onError({
+                                    type: 'expression',
                                     message: `Failed to evaluate expression attribute: ${attr.value
                                         .replace(/\n+/g, ' ')
                                         .replace(/ +/g, ' ')}. ${
@@ -448,6 +533,7 @@ export class MdastToJsx {
                         }
                     } catch (error) {
                         onError({
+                            type: 'expression',
                             message: `Failed to evaluate expression attribute: ${attr.value
                                 .replace(/\n+/g, ' ')
                                 .replace(/ +/g, ' ')}. ${
@@ -460,6 +546,7 @@ export class MdastToJsx {
                     }
                 } else {
                     onError({
+                        type: 'expression',
                         message: `Expressions in jsx props are not supported (${attr.value
                             .replace(/\n+/g, ' ')
                             .replace(/ +/g, ' ')})`,
@@ -471,6 +558,7 @@ export class MdastToJsx {
 
             if (attr.type !== 'mdxJsxAttribute') {
                 onError({
+                    type: 'expression',
                     message: `non mdxJsxAttribute attribute is not supported: ${attr}`,
                     line: node.position?.start?.line,
                 })
@@ -537,6 +625,7 @@ export class MdastToJsx {
                                 continue
                             } catch (error) {
                                 onError({
+                                    type: 'expression',
                                     message: `Failed to evaluate expression attribute: ${
                                         attr.name
                                     }={${v.value}}. ${
@@ -554,6 +643,7 @@ export class MdastToJsx {
                 }
 
                 onError({
+                    type: 'expression',
                     message: `Expressions in jsx prop not evaluated: (${attr.name}={${v.value}})`,
                     line: attr.position?.start?.line,
                 })
@@ -588,10 +678,14 @@ 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),
+                        this.pushError(err),
                     )
                     parsedImports.forEach((value, key) => {
                         this.esmImports.set(key, value)
@@ -640,7 +734,8 @@ export class MdastToJsx {
                                     Evaluate.evaluate.sync(expression)
                                 return result
                             } catch (error) {
-                                this.errors.push({
+                                this.pushError({
+                                    type: 'expression',
                                     message: `Failed to evaluate expression: ${
                                         node.value
                                     }. ${
@@ -653,7 +748,8 @@ export class MdastToJsx {
                             }
                         }
                     } catch (error) {
-                        this.errors.push({
+                        this.pushError({
+                            type: 'expression',
                             message: `Failed to evaluate expression: ${
                                 node.value
                             }. ${