safe-mdx 1.3.1 → 1.3.3

package/src/html/html-to-mdx-ast.test.ts

@@ -0,0 +1,365 @@
+import { test, expect, describe } from 'vitest'
+import React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import {
+    parseHtmlToMdxAst,
+    htmlToMdxAst,
+    remarkMdxJsxNormalize,
+} from './html-to-mdx-ast.js'
+import { unified } from 'unified'
+import remarkMdx from 'remark-mdx'
+import remarkStringify from 'remark-stringify'
+import remarkParse from 'remark-parse'
+import type { RootContent } from 'mdast'
+import { mdxParse } from '../parse.js'
+import { MdastToJsx } from '../safe-mdx.js'
+
+// Default components for testing
+const components = {
+    Heading({ level, children, ...props }) {
+        return React.createElement('h1', props, children)
+    },
+    Cards({ level, children, ...props }) {
+        return React.createElement('div', props, children)
+    },
+}
+
+// Helper to convert HTML to MDX string and rendered HTML
+async function htmlToMdxString({
+    html,
+    withProcessor = false,
+    onError,
+    convertTagName,
+    convertAttributeValue,
+}: {
+    html: string
+    withProcessor?: boolean
+    onError?: (error: unknown, text: string) => void
+    convertTagName?: (args: { tagName: string }) => string
+    convertAttributeValue?: (args: {
+        name: string
+        value: string
+        tagName: string
+    }) => string
+}): Promise<{ mdx: string; html: string }> {
+    // If withProcessor is true, create a textToMdast that parses markdown
+    const textToMdast = withProcessor
+        ? ({ text }: { text: string }) => {
+              const markdownProcessor = unified()
+                  .use(remarkParse)
+                  .use(remarkMdx)
+              const mdast = markdownProcessor.parse(text) as any
+              markdownProcessor.runSync(mdast)
+              // Return the children of the root node
+              return mdast.children || []
+          }
+        : undefined
+
+    const mdxAst = parseHtmlToMdxAst({
+        html,
+        textToMdast,
+        onError,
+        convertTagName,
+        convertAttributeValue,
+    })
+
+    // Generate MDX string
+    const processor = unified().use(remarkMdx).use(remarkStringify, {
+        // bullet: '-',
+        // fence: '`',
+        // fences: true
+    })
+
+    // Create a root node with the content
+    const root = {
+        type: 'root',
+        children: mdxAst,
+    }
+
+    const mdx = processor.stringify(root as any)
+
+    // Generate HTML using MdastToJsx like in safe-mdx.test.tsx
+    // First parse the MDX to get the full AST
+    const mdast = mdxParse(mdx)
+    const visitor = new MdastToJsx({ markdown: mdx, mdast, components })
+    const jsx = visitor.run()
+    const renderedHtml = renderToStaticMarkup(jsx)
+
+    return { mdx, html: renderedHtml }
+}
+
+describe('parseHtmlToMdxAst', () => {
+    test('parses simple HTML element', () => {
+        const result = parseHtmlToMdxAst({ html: '<div>Hello</div>' })
+        expect(result).toMatchInlineSnapshot(`
+          [
+            {
+              "attributes": [],
+              "children": [
+                {
+                  "type": "text",
+                  "value": "Hello",
+                },
+              ],
+              "name": "div",
+              "type": "mdxJsxTextElement",
+            },
+          ]
+        `)
+    })
+
+    test('filters out non-HTML elements when convertTagName returns empty string', () => {
+        const result = parseHtmlToMdxAst({
+            html: '<custom-element>Hello <span>world</span></custom-element>',
+            convertTagName: ({ tagName }) => {
+                // Only keep span, filter out custom-element
+                if (tagName === 'span') return 'span'
+                return tagName
+            },
+        })
+        expect(result).toMatchInlineSnapshot(`
+          [
+            {
+              "attributes": [],
+              "children": [
+                {
+                  "type": "text",
+                  "value": "Hello ",
+                },
+                {
+                  "attributes": [],
+                  "children": [
+                    {
+                      "type": "text",
+                      "value": "world",
+                    },
+                  ],
+                  "name": "span",
+                  "type": "mdxJsxTextElement",
+                },
+              ],
+              "name": "custom-element",
+              "type": "mdxJsxTextElement",
+            },
+          ]
+        `)
+    })
+
+    test('handles self-closing tags', () => {
+        const result = parseHtmlToMdxAst({
+            html: '<img src="https://example.com/img.jpg" />',
+        })
+        expect(result).toMatchInlineSnapshot(`
+          [
+            {
+              "attributes": [
+                {
+                  "name": "src",
+                  "type": "mdxJsxAttribute",
+                  "value": "https://example.com/img.jpg",
+                },
+              ],
+              "children": [],
+              "name": "img",
+              "type": "mdxJsxTextElement",
+            },
+          ]
+        `)
+    })
+
+    test('handles span with attributes', () => {
+        const result = parseHtmlToMdxAst({
+            html: '<span color="blue">colored text</span>',
+        })
+        expect(result).toMatchInlineSnapshot(`
+          [
+            {
+              "attributes": [
+                {
+                  "name": "color",
+                  "type": "mdxJsxAttribute",
+                  "value": "blue",
+                },
+              ],
+              "children": [
+                {
+                  "type": "text",
+                  "value": "colored text",
+                },
+              ],
+              "name": "span",
+              "type": "mdxJsxTextElement",
+            },
+          ]
+        `)
+    })
+
+    test('handles mixed content', () => {
+        const result = parseHtmlToMdxAst({
+            html: 'Some text <strong>bold</strong> more text',
+        })
+        expect(result).toMatchInlineSnapshot(`
+          [
+            {
+              "type": "text",
+              "value": "Some text ",
+            },
+            {
+              "attributes": [],
+              "children": [
+                {
+                  "type": "text",
+                  "value": "bold",
+                },
+              ],
+              "name": "strong",
+              "type": "mdxJsxTextElement",
+            },
+            {
+              "type": "text",
+              "value": " more text",
+            },
+          ]
+        `)
+    })
+
+    test('handles comments', () => {
+        const result = parseHtmlToMdxAst({ html: '<!-- This is a comment -->' })
+        expect(result).toMatchInlineSnapshot(`[]`)
+    })
+
+    test('handles table with attributes', () => {
+        const result = parseHtmlToMdxAst({
+            html: '<table class="data-table"><tr><td>Cell</td></tr></table>',
+        })
+        expect(result).toMatchInlineSnapshot(`
+          [
+            {
+              "attributes": [
+                {
+                  "name": "className",
+                  "type": "mdxJsxAttribute",
+                  "value": "data-table",
+                },
+              ],
+              "children": [
+                {
+                  "attributes": [],
+                  "children": [
+                    {
+                      "attributes": [],
+                      "children": [
+                        {
+                          "type": "text",
+                          "value": "Cell",
+                        },
+                      ],
+                      "name": "td",
+                      "type": "mdxJsxTextElement",
+                    },
+                  ],
+                  "name": "tr",
+                  "type": "mdxJsxTextElement",
+                },
+              ],
+              "name": "table",
+              "type": "mdxJsxTextElement",
+            },
+          ]
+        `)
+    })
+})
+
+describe('parseHtmlToMdxAst with markdown processor', () => {
+    test('parses markdown inside HTML tags', async () => {
+        const htmlToConvert = '<div>This is **bold** text</div>'
+        const result = await htmlToMdxString({
+            html: htmlToConvert,
+            withProcessor: true,
+            onError: (e) => {
+                throw e
+            },
+        })
+        expect(result).toMatchInlineSnapshot(`
+          {
+            "html": "<div>This is <strong>bold</strong> text</div>",
+            "mdx": "<div>This is **bold** text</div>
+          ",
+          }
+        `)
+    })
+
+    test('handles mixed markdown and HTML inside tags', async () => {
+        const htmlToConvert = '<div>**Bold text:** <a href="#">link</a></div>'
+        const result = await htmlToMdxString({
+            html: htmlToConvert,
+            withProcessor: true,
+            onError: (e) => {
+                throw e
+            },
+        })
+        expect(result).toMatchInlineSnapshot(`
+          {
+            "html": "<div><strong>Bold text:</strong><a href="#">link</a></div>",
+            "mdx": "<div>**Bold text:**<a href="#">link</a></div>
+          ",
+          }
+        `)
+    })
+
+    test('handles markdown inside table cells', async () => {
+        const htmlToConvert =
+            '<table><tr><td>**Bold** text and [link](http://example.com)</td></tr></table>'
+        const result = await htmlToMdxString({
+            html: htmlToConvert,
+            withProcessor: true,
+            onError: (e) => {
+                throw e
+            },
+        })
+        expect(result).toMatchInlineSnapshot(`
+          {
+            "html": "<table><tr><td><strong>Bold</strong> text and <a href="http://example.com" title="">link</a></td></tr></table>",
+            "mdx": "<table><tr><td>**Bold** text and [link](http://example.com)</td></tr></table>
+          ",
+          }
+        `)
+    })
+
+    test('preserves plain text when no markdown', async () => {
+        const htmlToConvert = '<div>Plain text without markdown</div>'
+        const result = await htmlToMdxString({
+            html: htmlToConvert,
+            withProcessor: true,
+            onError: (e) => {
+                throw e
+            },
+        })
+        expect(result).toMatchInlineSnapshot(`
+          {
+            "html": "<div>Plain text without markdown</div>",
+            "mdx": "<div>Plain text without markdown</div>
+          ",
+          }
+        `)
+    })
+
+    test('handles nested HTML tags with markdown', async () => {
+        const htmlToConvert =
+            '<div><span>**Bold** and <a href="#">link</a></span></div>'
+        const result = await htmlToMdxString({
+            html: htmlToConvert,
+            withProcessor: true,
+            onError: (e) => {
+                throw e
+            },
+        })
+        expect(result).toMatchInlineSnapshot(`
+          {
+            "html": "<div><span><strong>Bold</strong> and<a href="#">link</a></span></div>",
+            "mdx": "<div><span>**Bold** and<a href="#">link</a></span></div>
+          ",
+          }
+        `)
+    })
+})

package/src/html/html-to-mdx-ast.ts

@@ -0,0 +1,304 @@
+import type { Root, RootContent, Text as MdastText } from 'mdast'
+import type {
+    MdxJsxAttribute,
+    MdxJsxAttributeValueExpression,
+    MdxJsxTextElement,
+} from 'mdast-util-mdx-jsx'
+import type { Processor } from 'unified'
+import { convertAttributeNameToJSX } from './convert-attributes.js'
+import { parseHTML } from './domparser.js'
+
+// Re-export the normalize plugin
+export { default as remarkMdxJsxNormalize } from './remark-mdx-jsx-normalize.js'
+
+// Type for converting tag names
+export type ConvertTagName = (args: { tagName: string }) => string
+
+// Type for converting text to mdast nodes - now returns AST nodes directly
+export type TextToMdast = (args: {
+    text: string
+}) => RootContent | RootContent[]
+
+// Type for converting attribute values
+export type ConvertAttributeValue = (args: {
+    name: string
+    value: string
+    tagName: string
+}) => string
+
+// Options for parsing HTML to MDX AST
+export interface ParseHtmlToMdxAstOptions {
+    html: string
+    onError?: (error: unknown, text: string) => void
+    convertTagName?: ConvertTagName
+    textToMdast?: TextToMdast
+    convertAttributeValue?: ConvertAttributeValue
+}
+
+// Type guard functions for DOM nodes
+function isCommentNode(node: Node): node is Comment {
+    return node.nodeType === 8 // Node.COMMENT_NODE
+}
+
+function isTextNode(node: Node): node is Text {
+    return node.nodeType === 3 // Node.TEXT_NODE
+}
+
+function isElementNode(node: Node): node is Element {
+    return node.nodeType === 1 // Node.ELEMENT_NODE
+}
+
+// Default tag name converter (no transformation)
+function defaultConvertTagName({ tagName }: { tagName: string }): string {
+    return tagName.toLowerCase()
+}
+
+// Default attribute value converter (no transformation)
+function defaultConvertAttributeValue({
+    value,
+}: {
+    name: string
+    value: string
+    tagName: string
+}): string {
+    return value
+}
+
+// Convert HTML attribute to MDX JSX attribute
+function convertAttribute(
+    attr: Attr,
+    tagName: string,
+    options?: ParseHtmlToMdxAstOptions,
+): MdxJsxAttribute {
+    let jsxName = convertAttributeNameToJSX(attr.name)
+
+    // Apply attribute value transformation
+    const convertAttrValue =
+        options?.convertAttributeValue || defaultConvertAttributeValue
+    let value = convertAttrValue({
+        name: attr.name,
+        value: attr.value,
+        tagName,
+    })
+
+    // Handle boolean attributes
+    if (value === '' || value === attr.name) {
+        return {
+            type: 'mdxJsxAttribute',
+            name: jsxName,
+            value: null, // boolean true
+        }
+    }
+
+    // Handle special number attributes
+    const numberAttrs = [
+        'tabIndex',
+        'cols',
+        'rows',
+        'size',
+        'span',
+        'colSpan',
+        'rowSpan',
+        'border',
+    ]
+    if (numberAttrs.includes(jsxName) && value && !isNaN(Number(value))) {
+        return {
+            type: 'mdxJsxAttribute',
+            name: jsxName,
+            value: {
+                type: 'mdxJsxAttributeValueExpression',
+                value: value,
+                data: {
+                    estree: {
+                        type: 'Program',
+                        sourceType: 'module',
+                        body: [
+                            {
+                                type: 'ExpressionStatement',
+                                expression: {
+                                    type: 'Literal',
+                                    value: Number(value),
+                                },
+                            },
+                        ],
+                    },
+                },
+            } satisfies MdxJsxAttributeValueExpression,
+        }
+    }
+
+    // Handle style attribute - for now keep as string
+    // if (jsxName === 'style' && value.includes(':')) {
+    //     // Could enhance to parse CSS to object
+    //     return {
+    //         type: 'mdxJsxAttribute',
+    //         name: jsxName,
+    //         value: {
+    //             type: 'mdxJsxAttributeValueExpression',
+    //             value: `{${JSON.stringify(parseStyleString(value))}}`,
+    //             data: {
+    //                 estree: parseExpression(JSON.stringify(parseStyleString(value))),
+    //             },
+    //         },
+    //     }
+    // }
+
+    // String value
+    return {
+        type: 'mdxJsxAttribute',
+        name: jsxName,
+        value: value,
+    }
+}
+
+// Convert DOM node to MDX AST nodes
+function htmlNodeToMdxAst(
+    node: Node,
+    options?: ParseHtmlToMdxAstOptions,
+): RootContent | RootContent[] {
+    if (isCommentNode(node)) {
+        // Convert comments to MDX JSX expression with comment
+        // For now, return as HTML node
+        // return {
+        //     type: 'html',
+        //     value: `<!-- ${node.data} -->`
+        // } as Html
+        return []
+    }
+
+    if (isTextNode(node)) {
+        const textValue = node.textContent || ''
+
+        // If we have a textToMdast converter, use it
+        if (options?.textToMdast) {
+            try {
+                const result = options.textToMdast({ text: textValue })
+                return result
+            } catch (error) {
+                // Call onError callback if provided, otherwise log
+                if (options.onError) {
+                    options.onError(error, textValue)
+                } else {
+                    console.error('Failed to convert text to mdast:', error)
+                    console.error('Text content:', textValue)
+                }
+                // Fallback to simple text node
+                return {
+                    type: 'text',
+                    value: textValue,
+                } satisfies MdastText
+            }
+        }
+
+        // Default: return simple text node
+        return {
+            type: 'text',
+            value: textValue,
+        } satisfies MdastText
+    }
+
+    if (!isElementNode(node)) {
+        return []
+    }
+
+    const convertTagNameFn = options?.convertTagName || defaultConvertTagName
+    // Use localName which is always lowercase in both browser and linkedom
+    const componentName = convertTagNameFn({ tagName: node.localName })
+
+    // If convertTagName returns empty string, skip this element and only return its children
+    if (componentName === '') {
+        // Process children but skip the element wrapper
+        const children: RootContent[] = []
+        for (const child of Array.from(node.childNodes)) {
+            const result = htmlNodeToMdxAst(child, options)
+            if (Array.isArray(result)) {
+                children.push(...result)
+            } else {
+                children.push(result)
+            }
+        }
+        return children
+    }
+
+    // Convert attributes
+    const attributes: MdxJsxAttribute[] = []
+    for (const attr of Array.from(node.attributes)) {
+        attributes.push(convertAttribute(attr, node.tagName, options))
+    }
+
+    // Process children
+    const children: RootContent[] = []
+    for (const child of Array.from(node.childNodes)) {
+        const result = htmlNodeToMdxAst(child, options)
+        if (Array.isArray(result)) {
+            children.push(...result)
+        } else {
+            children.push(result)
+        }
+    }
+
+    // Always create MdxJsxTextElement initially
+    // The conversion to MdxJsxFlowElement will be handled by a separate plugin
+    const element: MdxJsxTextElement = {
+        type: 'mdxJsxTextElement',
+        name: componentName,
+        attributes,
+        children: children as any,
+    }
+    return element
+}
+
+// Main function to parse HTML and return MDX AST
+export function htmlToMdxAst(
+    options: ParseHtmlToMdxAstOptions,
+): RootContent | RootContent[] {
+    // Parse HTML with linkedom
+    const { document } = parseHTML(options.html.trim())
+
+    // linkedom behavior:
+    // - If input is a fragment (like "<div>Hello</div>"), the content becomes direct children of document
+    // - If input has body tag, it creates proper body element
+    // - We need to handle both cases
+
+    // linkedom behavior:
+    // - When parsing fragments, content becomes direct children of document
+    // - Accessing document.body on fragments auto-creates HEAD and BODY as children
+    // - We must avoid accessing document.body to prevent this
+
+    // Just use document's direct children and filter for relevant nodes
+    const childNodes = Array.from(document.childNodes).filter(
+        (node) =>
+            node.nodeType === 1 || // Element nodes
+            node.nodeType === 3 || // Text nodes
+            node.nodeType === 8, // Comment nodes
+    )
+
+    if (childNodes.length === 0) {
+        return []
+    }
+
+    if (childNodes.length === 1) {
+        return htmlNodeToMdxAst(childNodes[0]!, options)
+    }
+
+    // Multiple nodes - return as array
+    const results: RootContent[] = []
+    for (const node of childNodes) {
+        const result = htmlNodeToMdxAst(node, options)
+        if (Array.isArray(result)) {
+            results.push(...result)
+        } else {
+            results.push(result)
+        }
+    }
+
+    return results
+}
+
+// Export a wrapper that always returns an array for consistency
+export function parseHtmlToMdxAst(
+    options: ParseHtmlToMdxAstOptions,
+): RootContent[] {
+    const result = htmlToMdxAst(options)
+    return Array.isArray(result) ? result : [result]
+}