safe-mdx 1.3.2 → 1.3.6

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

@@ -0,0 +1,327 @@
+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 { unified } from 'unified'
+import { convertAttributeNameToJSX } from './convert-attributes.js'
+import { parseHTML } from './domparser.js'
+import { remarkMdxJsxNormalize } from './remark-mdx-jsx-normalize.js'
+
+// Re-export the normalize plugin
+export { remarkMdxJsxNormalize }
+
+// 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
+    parentType?: 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 - always returns an array
+function htmlNodeToMdxAst(
+    node: Node,
+    options?: ParseHtmlToMdxAstOptions,
+): RootContent[] {
+    if (isCommentNode(node)) {
+        // Convert comments to MDX JSX expression with comment
+        // For now, return empty array
+        // 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 Array.isArray(result) ? result : [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)) {
+            children.push(...htmlNodeToMdxAst(child, options))
+        }
+        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)) {
+        children.push(...htmlNodeToMdxAst(child, options))
+    }
+
+    // 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 - always returns an array
+export function htmlToMdxAst(options: ParseHtmlToMdxAstOptions): 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
+    )
+
+    let results: RootContent[] = []
+
+    for (const node of childNodes) {
+        results.push(...htmlNodeToMdxAst(node, options))
+    }
+
+    // Apply the normalize plugin if we have a parentType
+    if (options.parentType && results.length > 0) {
+        // Create a temporary AST node with the same parent type
+        const parentType = options.parentType
+        const tempRoot: Root = {
+            type: 'root',
+            children: results,
+        }
+
+        // If we have a specific parent type, wrap the content in that parent
+        // to provide proper context for the normalize plugin
+        let astToProcess: Root
+        if (parentType !== 'root') {
+            // Create a parent node of the specified type with our content as children
+            const parentNode: any = {
+                type: parentType,
+                children: tempRoot.children,
+            }
+            astToProcess = {
+                type: 'root',
+                children: [parentNode],
+            }
+        } else {
+            astToProcess = tempRoot
+        }
+
+        // Create a simple processor and run the normalize plugin
+        const processor = unified().use(remarkMdxJsxNormalize)
+        processor.runSync(astToProcess)
+
+        // Extract the result back
+        if (parentType !== 'root') {
+            // Get the children from the parent node we created
+            const processedParent = astToProcess.children[0] as any
+            results = processedParent.children as RootContent[]
+        } else {
+            // Get children directly from root
+            results = astToProcess.children
+        }
+    }
+
+    return results
+}
+
+// Export a wrapper that always returns an array for consistency
+// Note: htmlToMdxAst now already returns an array, so this is just an alias
+export function parseHtmlToMdxAst(
+    options: ParseHtmlToMdxAstOptions,
+): RootContent[] {
+    return htmlToMdxAst(options)
+}

package/src/html/remark-mdx-jsx-normalize.ts

@@ -0,0 +1,209 @@
+import type { Root, RootContent, PhrasingContent } from 'mdast'
+import type { MdxJsxTextElement, MdxJsxFlowElement } from 'mdast-util-mdx-jsx'
+import { visitParents } from 'unist-util-visit-parents'
+import type { Node, Parent } from 'unist'
+
+// Type definitions for MDX and MDAST content types
+// type FlowContent = Blockquote | Code | Heading | Html | List | ThematicBreak | Content
+// type PhrasingContent = Break | Emphasis | Html | Image | ImageReference | InlineCode | Link | LinkReference | Strong | Text
+// type MdxJsxFlowContent = MdxJsxFlowElement | FlowContent
+// type MdxJsxPhrasingContent = MdxJsxTextElement | PhrasingContent
+
+/** Parents that require phrasing/inline children */
+const PHRASE_CONTAINERS = new Set([
+    'paragraph',
+    'heading',
+    'emphasis',
+    'strong',
+    'delete',
+    'link',
+    'linkReference',
+    'tableCell',
+    'mdxJsxTextElement', // MDX JSX text elements should contain phrasing
+])
+
+/** HTML tags that require phrasing/inline children */
+const PHRASE_HTML_CONTAINERS = new Set([
+    'p',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'em',
+    'strong',
+    'b',
+    'i',
+    'u',
+    's',
+    'del',
+    'ins',
+    'mark',
+    'small',
+    'sub',
+    'sup',
+    'a',
+    'abbr',
+    'cite',
+    'code',
+    'dfn',
+    'kbd',
+    'q',
+    'samp',
+    'span',
+    'time',
+    'var',
+])
+
+/** Parents that accept/expect flow (block) content */
+const FLOW_CONTAINERS = new Set([
+    'root',
+    'listItem',
+    'blockquote',
+    'footnoteDefinition',
+    'mdxJsxFlowElement', // MDX JSX flow elements should contain flow
+])
+
+/** Check if a node represents phrasing content */
+function isPhrasing(node: Node): boolean {
+    const phrasingTypes = new Set([
+        'text',
+        'emphasis',
+        'strong',
+        'delete',
+        'html',
+        'image',
+        'imageReference',
+        'inlineCode',
+        'link',
+        'linkReference',
+        'break',
+        'mdxJsxTextElement',
+    ])
+    return phrasingTypes.has(node.type)
+}
+
+/** Tags that are typically block-level elements */
+const blockLevelTags = new Set([
+    'div',
+    'p',
+    'blockquote',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'ul',
+    'ol',
+    'li',
+    'pre',
+    'hr',
+    'table',
+    'thead',
+    'tbody',
+    'tfoot',
+    'tr',
+    'th',
+    'td',
+    'section',
+    'article',
+    'aside',
+    'nav',
+    'header',
+    'footer',
+    'main',
+    'figure',
+    'figcaption',
+    // Notion-specific block elements
+    'callout',
+    'columns',
+    'column',
+    'page',
+    'database',
+    'data-source',
+    'audio',
+    'video',
+    'file',
+    'pdf',
+    'embed',
+    'synced_block',
+    'synced_block_reference',
+    'meeting-notes',
+    'summary',
+    'notes',
+    'transcript',
+    'table_of_contents',
+    'unknown',
+    'image', // Images can be block-level in Notion
+])
+
+/**
+ * remark plugin: make mdxJsx* element kinds match their context.
+ * - Inside phrasing parents → mdxJsxTextElement
+ * - Inside flow parents → mdxJsxFlowElement
+ * - Elements with block-level tag names → mdxJsxFlowElement
+ * - Elements containing non-phrasing children → mdxJsxFlowElement
+ */
+export function remarkMdxJsxNormalize() {
+    return function transform(tree: Root) {
+        visitParents(tree, isMdxJsx, (node, ancestors) => {
+            const element = node as MdxJsxTextElement | MdxJsxFlowElement
+            const parent = ancestors[ancestors.length - 1] as Parent | undefined
+            if (!parent) return
+
+            // Check if parent expects phrasing or flow content
+            let parentExpectsPhrasing = false
+            let parentExpectsFlow = false
+            
+            if ((parent.type === 'mdxJsxFlowElement' || parent.type === 'mdxJsxTextElement') && 
+                (parent as any).name) {
+                // For MDX JSX elements, check the tag name
+                const parentTagName = (parent as any).name.toLowerCase()
+                parentExpectsPhrasing = PHRASE_HTML_CONTAINERS.has(parentTagName)
+                // If not phrasing and is a block-level tag, it expects flow
+                parentExpectsFlow = !parentExpectsPhrasing && blockLevelTags.has(parentTagName)
+            } else {
+                // For mdast nodes, check the type
+                parentExpectsPhrasing = PHRASE_CONTAINERS.has(parent.type)
+                parentExpectsFlow = FLOW_CONTAINERS.has(parent.type)
+            }
+
+            // Check element properties
+            const hasBlockTag = element.name
+                ? blockLevelTags.has(element.name.toLowerCase())
+                : false
+            const children = (element.children || []) as RootContent[]
+            const containsNonPhrasing = children.some((c) => !isPhrasing(c))
+
+            // Determine desired type
+            let desired: 'mdxJsxTextElement' | 'mdxJsxFlowElement' =
+                element.type
+
+            // Priority rules:
+            // 1. If it has a block-level tag name, it should be flow
+            // 2. If it contains non-phrasing children, it should be flow
+            // 3. Otherwise, match parent context
+            if (hasBlockTag || containsNonPhrasing) {
+                desired = 'mdxJsxFlowElement'
+            } else if (parentExpectsPhrasing) {
+                desired = 'mdxJsxTextElement'
+            } else if (parentExpectsFlow) {
+                desired = 'mdxJsxFlowElement'
+            }
+
+            // Apply the change if needed
+            if (element.type !== desired) {
+                element.type = desired
+            }
+        })
+    }
+}
+
+/** Check if a node is an MDX JSX element */
+function isMdxJsx(node: Node): boolean {
+    return (
+        node.type === 'mdxJsxTextElement' || node.type === 'mdxJsxFlowElement'
+    )
+}

package/src/html/valid-html-elements.ts

@@ -0,0 +1,65 @@
+// List of valid HTML elements that should be preserved
+// All other elements will be filtered out (return empty string)
+export const validHtmlElements = new Set([
+    // Document metadata
+    'base', 'head', 'link', 'meta', 'style', 'title',
+    
+    // Content sectioning
+    'address', 'article', 'aside', 'footer', 'header', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'main', 'nav', 'section',
+    
+    // Text content
+    'blockquote', 'dd', 'div', 'dl', 'dt', 'figcaption', 'figure', 'hr', 'li', 'ol', 'p', 'pre', 'ul',
+    
+    // Inline text semantics
+    'a', 'abbr', 'b', 'bdi', 'bdo', 'br', 'cite', 'code', 'data', 'dfn', 'em', 'i', 'kbd',
+    'mark', 'q', 'rp', 'rt', 'ruby', 's', 'samp', 'small', 'span', 'strong', 'sub', 'sup',
+    'time', 'u', 'var', 'wbr',
+    
+    // Image and multimedia
+    'area', 'audio', 'img', 'map', 'track', 'video',
+    
+    // Embedded content
+    'embed', 'iframe', 'object', 'param', 'picture', 'portal', 'source',
+    
+    // SVG and MathML
+    'svg', 'math', 'path', // Added 'path' from nativeTags
+    
+    // Scripting
+    'canvas', 'noscript', 'script',
+    
+    // Demarcating edits
+    'del', 'ins',
+    
+    // Table content
+    'caption', 'col', 'colgroup', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'tr',
+    
+    // Forms
+    'button', 'datalist', 'fieldset', 'form', 'input', 'label', 'legend', 'meter', 'optgroup',
+    'option', 'output', 'progress', 'select', 'textarea',
+    
+    // Interactive elements
+    'details', 'dialog', 'menu', 'summary',
+    
+    // Web Components
+    'slot', 'template',
+])
+
+// Export as an array for backward compatibility with nativeTags
+export const nativeTags = Array.from(validHtmlElements) as readonly string[]
+
+/**
+ * Convert HTML tag name to JSX component name
+ * Returns empty string if the tag is not a valid HTML element
+ */
+export function htmlTagNameConverter({ tagName }: { tagName: string }): string {
+    const lowerTag = tagName.toLowerCase()
+    
+    // Check if it's a valid HTML element
+    if (validHtmlElements.has(lowerTag)) {
+        return lowerTag
+    }
+    
+    // Return empty string for non-HTML elements
+    return ''
+}

package/src/parse.ts

@@ -5,6 +5,9 @@ import { Root, RootContent } from 'mdast'
 import { remark } from 'remark'
 import remarkGfm from 'remark-gfm'
 import remarkMdx from 'remark-mdx'
+import { parseHtmlToMdxAst, remarkMdxJsxNormalize } from './html/html-to-mdx-ast.js'
+
+export { parseHtmlToMdxAst, remarkMdxJsxNormalize }
 
 export function mdxParse(code: string) {
     const file = mdxProcessor.processSync(code)