safe-mdx 1.4.0 → 1.6.0

package/src/safe-mdx.tsx

@@ -8,10 +8,10 @@ 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'
+import { extractComponentInfo, parseEsmImports } from './esm-parser.ts'
+import { resolveModulePath, type EagerModules } from './parse.ts'
+import { htmlToMdxAst } from './html/html-to-mdx-ast.ts'
+import { validHtmlElements, nativeTags } from './html/valid-html-elements.ts'
 
 export type MyRootContent = RootContent | Root
 
@@ -29,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
@@ -43,6 +46,18 @@ export type CreateElementFunction = (
     ...children: ReactNode[]
 ) => ReactNode
 
+export interface EvaluateOptions {
+    /** Enable function calls in expressions. Automatically enabled when `scope` is provided. */
+    functions?: boolean
+    /** Pass `escodegen.generate` to support inline function expressions
+     *  like arrow functions in `.map(x => x.name)`. Requires `functions: true`. */
+    generate?: (ast: any) => string
+    /** Force logical operators (`&&`, `||`) to return booleans. */
+    booleanLogicalOperators?: boolean
+    /** Throw when variables referenced in expressions are undefined. */
+    strict?: boolean
+}
+
 export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
     components,
     markdown = '',
@@ -54,6 +69,9 @@ export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
     addMarkdownLineNumbers = false,
     modules,
     baseUrl,
+    onError,
+    scope,
+    evaluateOptions,
 }: {
     components?: ComponentsMap
     markdown?: string
@@ -70,6 +88,18 @@ export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
     /** 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
+    /** Variables and functions available in MDX expressions.
+     *  When scope contains functions, function calls in expressions are
+     *  automatically enabled. */
+    scope?: Record<string, any>
+    /** Options passed to `eval-estree-expression` for expression evaluation.
+     *  Pass `{ functions: true }` to enable function calls, or
+     *  `{ functions: true, generate: escodegen.generate }` to also support
+     *  inline arrow functions and callbacks like `.map(x => x.name)`. */
+    evaluateOptions?: EvaluateOptions
 }) {
     const visitor = new MdastToJsx({
         markdown,
@@ -82,6 +112,9 @@ export const SafeMdxRenderer = React.memo(function SafeMdxRenderer({
         addMarkdownLineNumbers,
         modules,
         baseUrl,
+        onError,
+        scope,
+        evaluateOptions,
     })
     const result = visitor.run()
     return result
@@ -101,6 +134,9 @@ export class MdastToJsx {
     addMarkdownLineNumbers: boolean
     modules?: EagerModules
     baseUrl?: string
+    onError?: (error: SafeMdxError) => void
+    scope?: Record<string, any>
+    evaluateOptions?: EvaluateOptions
 
     constructor({
         markdown: code = '',
@@ -113,6 +149,9 @@ export class MdastToJsx {
         addMarkdownLineNumbers = false,
         modules,
         baseUrl,
+        onError,
+        scope,
+        evaluateOptions,
     }: {
         markdown?: string
         mdast: MyRootContent
@@ -127,6 +166,18 @@ export class MdastToJsx {
         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
+        /** Variables and functions available in MDX expressions.
+         *  When scope contains functions, function calls in expressions are
+         *  automatically enabled. */
+        scope?: Record<string, any>
+        /** Options passed to `eval-estree-expression` for expression evaluation.
+         *  Pass `{ functions: true }` to enable function calls, or
+         *  `{ functions: true, generate: escodegen.generate }` to also support
+         *  inline arrow functions and callbacks like `.map(x => x.name)`. */
+        evaluateOptions?: EvaluateOptions
     }) {
         this.str = code
 
@@ -144,6 +195,9 @@ export class MdastToJsx {
 
         this.modules = modules
         this.baseUrl = baseUrl
+        this.onError = onError
+        this.scope = scope
+        this.evaluateOptions = evaluateOptions
 
         this.c = {
             ...Object.fromEntries(
@@ -156,6 +210,11 @@ export class MdastToJsx {
 
     }
 
+    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)
@@ -234,7 +293,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('.'),
@@ -302,7 +362,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)
 
@@ -318,7 +378,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,
                         })
@@ -327,7 +388,7 @@ export class MdastToJsx {
                 }
 
                 let attrsList = this.getJsxAttrs(node, (err) => {
-                    this.errors.push(err)
+                    this.pushError(err)
                 })
 
                 let attrs = Object.fromEntries(attrsList)
@@ -365,6 +426,7 @@ export class MdastToJsx {
                         : null
                 if (!tagName) {
                     onError?.({
+                        type: 'expression',
                         message: 'JSX element missing component name',
                         line: line,
                     })
@@ -387,6 +449,7 @@ export class MdastToJsx {
                     Component = accessWithDot(this.c, tagName)
                     if (!Component) {
                         onError?.({
+                            type: 'missing-component',
                             message: `Unsupported jsx component ${tagName} in attribute`,
                             line: line,
                         })
@@ -454,6 +517,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'
                 }`,
@@ -464,6 +528,15 @@ export class MdastToJsx {
         return null
     }
 
+    evaluateExpression(expression: any) {
+        const hasScope = this.scope && Object.keys(this.scope).length > 0
+        const context = hasScope ? this.scope : undefined
+        const options = hasScope || this.evaluateOptions
+            ? { ...(hasScope ? { functions: true } : {}), ...this.evaluateOptions }
+            : undefined
+        return Evaluate.evaluate.sync(expression, context, options)
+    }
+
     getJsxAttrs(
         node: MdxJsxFlowElement | MdxJsxTextElement,
         onError: (err: SafeMdxError) => void = console.error,
@@ -476,14 +549,15 @@ export class MdastToJsx {
                 if (attr.data?.estree) {
                     try {
                         const program = attr.data.estree
+                        const firstBody = program.body?.[0]
                         if (
-                            program.body?.length > 0 &&
-                            program.body[0].type === 'ExpressionStatement'
+                            firstBody &&
+                            firstBody.type === 'ExpressionStatement'
                         ) {
-                            const expression = program.body[0].expression
+                            const expression = firstBody.expression
                             try {
                                 const result =
-                                    Evaluate.evaluate.sync(expression)
+                                    this.evaluateExpression(expression)
 
                                 // Handle spread syntax - merge the evaluated object
                                 if (
@@ -495,6 +569,7 @@ export class MdastToJsx {
                                 }
                             } catch (error) {
                                 onError({
+                                    type: 'expression',
                                     message: `Failed to evaluate expression attribute: ${attr.value
                                         .replace(/\n+/g, ' ')
                                         .replace(/ +/g, ' ')}. ${
@@ -508,6 +583,7 @@ export class MdastToJsx {
                         }
                     } catch (error) {
                         onError({
+                            type: 'expression',
                             message: `Failed to evaluate expression attribute: ${attr.value
                                 .replace(/\n+/g, ' ')
                                 .replace(/ +/g, ' ')}. ${
@@ -520,6 +596,7 @@ export class MdastToJsx {
                     }
                 } else {
                     onError({
+                        type: 'expression',
                         message: `Expressions in jsx props are not supported (${attr.value
                             .replace(/\n+/g, ' ')
                             .replace(/ +/g, ' ')})`,
@@ -531,6 +608,7 @@ export class MdastToJsx {
 
             if (attr.type !== 'mdxJsxAttribute') {
                 onError({
+                    type: 'expression',
                     message: `non mdxJsxAttribute attribute is not supported: ${attr}`,
                     line: node.position?.start?.line,
                 })
@@ -569,11 +647,12 @@ export class MdastToJsx {
                     try {
                         // Extract the expression from the Program body
                         const program = v.data.estree
+                        const firstBody = program.body?.[0]
                         if (
-                            program.body?.length > 0 &&
-                            program.body[0].type === 'ExpressionStatement'
+                            firstBody &&
+                            firstBody.type === 'ExpressionStatement'
                         ) {
-                            const expression = program.body[0].expression
+                            const expression = firstBody.expression
 
                             // Check if this is a JSX element
                             if (expression.type === 'JSXElement') {
@@ -592,11 +671,12 @@ export class MdastToJsx {
                             try {
                                 // Evaluate the expression synchronously
                                 const result =
-                                    Evaluate.evaluate.sync(expression)
+                                    this.evaluateExpression(expression)
                                 attrsList.push([attr.name, result])
                                 continue
                             } catch (error) {
                                 onError({
+                                    type: 'expression',
                                     message: `Failed to evaluate expression attribute: ${
                                         attr.name
                                     }={${v.value}}. ${
@@ -614,6 +694,7 @@ export class MdastToJsx {
                 }
 
                 onError({
+                    type: 'expression',
                     message: `Expressions in jsx prop not evaluated: (${attr.name}={${v.value}})`,
                     line: attr.position?.start?.line,
                 })
@@ -623,7 +704,7 @@ export class MdastToJsx {
     }
 
     run() {
-        const res = this.mdastTransformer(this.mdast, 'root') as ReactNode
+        const res = this.mdastTransformer(this.mdast, 'root')
         if (Array.isArray(res) && res.length === 1) {
             return res[0]
         }
@@ -639,7 +720,7 @@ export class MdastToJsx {
         if (this.renderNode) {
             const customResult = this.renderNode(
                 node,
-                (n: MyRootContent) => this.mdastTransformer(n, node.type),
+                (n) => this.mdastTransformer(n, node.type),
             )
             if (customResult !== undefined) {
                 return customResult
@@ -655,7 +736,7 @@ export class MdastToJsx {
                 // 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)
@@ -693,18 +774,20 @@ export class MdastToJsx {
                     try {
                         // Extract the expression from the Program body
                         const program = node.data.estree
+                        const firstBody = program.body?.[0]
                         if (
-                            program.body?.length > 0 &&
-                            program.body[0].type === 'ExpressionStatement'
+                            firstBody &&
+                            firstBody.type === 'ExpressionStatement'
                         ) {
-                            const expression = program.body[0].expression
+                            const expression = firstBody.expression
                             try {
                                 // Evaluate the expression synchronously
                                 const result =
-                                    Evaluate.evaluate.sync(expression)
+                                    this.evaluateExpression(expression)
                                 return result
                             } catch (error) {
-                                this.errors.push({
+                                this.pushError({
+                                    type: 'expression',
                                     message: `Failed to evaluate expression: ${
                                         node.value
                                     }. ${
@@ -717,7 +800,8 @@ export class MdastToJsx {
                             }
                         }
                     } catch (error) {
-                        this.errors.push({
+                        this.pushError({
+                            type: 'expression',
                             message: `Failed to evaluate expression: ${
                                 node.value
                             }. ${
@@ -1028,9 +1112,6 @@ export class MdastToJsx {
     }
 }
 
-function isTruthy<T>(val: T | undefined | null | false): val is T {
-    return Boolean(val)
-}
 
 function accessWithDot(obj, path: string) {
     return path
@@ -1061,14 +1142,6 @@ export function mdastBfs(
     return result
 }
 
-function safeJsonParse(str: string) {
-    try {
-        return JSON.parse(str)
-    } catch (err) {
-        return null
-    }
-}
-
 type ComponentsMap = { [k in (typeof nativeTags)[number]]?: any } & {
     [key: string]: any
 }

package/src/streaming.tsx

@@ -13,6 +13,7 @@ function matchJsxTag(code: string) {
     }
 
     const [fullMatch, tagName, attributes, selfClosing] = match
+    if (!tagName) return null
 
     const type = selfClosing
         ? 'self-closing'
@@ -24,7 +25,7 @@ function matchJsxTag(code: string) {
         tag: fullMatch,
         tagName,
         type,
-        attributes: attributes.trim(),
+        attributes: (attributes ?? '').trim(),
         startIndex: match.index,
         endIndex: match.index + fullMatch.length,
     }