@tiptap/core 3.6.7 → 3.7.0

package/src/utilities/markdown/createAtomBlockMarkdownSpec.ts

@@ -0,0 +1,141 @@
+import type {
+  JSONContent,
+  MarkdownParseHelpers,
+  MarkdownParseResult,
+  MarkdownToken,
+  MarkdownTokenizer,
+} from '../../types.js'
+import {
+  parseAttributes as defaultParseAttributes,
+  serializeAttributes as defaultSerializeAttributes,
+} from './attributeUtils.js'
+
+export interface AtomBlockMarkdownSpecOptions {
+  /** The Tiptap node name this spec is for */
+  nodeName: string
+  /** The markdown syntax name (defaults to nodeName if not provided) */
+  name?: string
+  /** Function to parse attributes from token attribute string */
+  parseAttributes?: (attrString: string) => Record<string, any>
+  /** Function to serialize attributes back to string for rendering */
+  serializeAttributes?: (attrs: Record<string, any>) => string
+  /** Default attributes to apply when parsing */
+  defaultAttributes?: Record<string, any>
+  /** Required attributes that must be present for successful parsing */
+  requiredAttributes?: string[]
+  /** Attributes that are allowed to be rendered back to markdown (whitelist) */
+  allowedAttributes?: string[]
+}
+
+/**
+ * Creates a complete markdown spec for atomic block nodes using Pandoc syntax.
+ *
+ * The generated spec handles:
+ * - Parsing self-closing blocks with `:::blockName {attributes}`
+ * - Extracting and parsing attributes
+ * - Validating required attributes
+ * - Rendering blocks back to markdown
+ *
+ * @param options - Configuration for the atomic block markdown spec
+ * @returns Complete markdown specification object
+ *
+ * @example
+ * ```ts
+ * const youtubeSpec = createAtomBlockMarkdownSpec({
+ *   nodeName: 'youtube',
+ *   requiredAttributes: ['src'],
+ *   defaultAttributes: { start: 0 },
+ *   allowedAttributes: ['src', 'start', 'width', 'height'] // Only these get rendered to markdown
+ * })
+ *
+ * // Usage in extension:
+ * export const Youtube = Node.create({
+ *   // ... other config
+ *   markdown: youtubeSpec
+ * })
+ * ```
+ */
+export function createAtomBlockMarkdownSpec(options: AtomBlockMarkdownSpecOptions): {
+  parseMarkdown: (token: MarkdownToken, h: MarkdownParseHelpers) => MarkdownParseResult
+  markdownTokenizer: MarkdownTokenizer
+  renderMarkdown: (node: JSONContent) => string
+} {
+  const {
+    nodeName,
+    name: markdownName,
+    parseAttributes = defaultParseAttributes,
+    serializeAttributes = defaultSerializeAttributes,
+    defaultAttributes = {},
+    requiredAttributes = [],
+    allowedAttributes,
+  } = options
+
+  // Use markdownName for syntax, fallback to nodeName
+  const blockName = markdownName || nodeName
+
+  // Helper function to filter attributes based on allowlist
+  const filterAttributes = (attrs: Record<string, any>) => {
+    if (!allowedAttributes) {
+      return attrs
+    }
+
+    const filtered: Record<string, any> = {}
+    allowedAttributes.forEach(key => {
+      if (key in attrs) {
+        filtered[key] = attrs[key]
+      }
+    })
+    return filtered
+  }
+
+  return {
+    parseMarkdown: (token: MarkdownToken, h: MarkdownParseHelpers) => {
+      const attrs = { ...defaultAttributes, ...token.attributes }
+      return h.createNode(nodeName, attrs, [])
+    },
+
+    markdownTokenizer: {
+      name: nodeName,
+      level: 'block' as const,
+      start(src: string) {
+        const regex = new RegExp(`^:::${blockName}(?:\\s|$)`, 'm')
+        const index = src.match(regex)?.index
+        return index !== undefined ? index : -1
+      },
+      tokenize(src, _tokens, _lexer) {
+        // Use non-global regex to match from the start of the string
+        // Include optional newline to ensure we consume the entire line
+        const regex = new RegExp(`^:::${blockName}(?:\\s+\\{([^}]*)\\})?\\s*:::(?:\\n|$)`)
+        const match = src.match(regex)
+
+        if (!match) {
+          return undefined
+        }
+
+        // Parse attributes if present
+        const attrString = match[1] || ''
+        const attributes = parseAttributes(attrString)
+
+        // Validate required attributes
+        const missingRequired = requiredAttributes.find(required => !(required in attributes))
+        if (missingRequired) {
+          return undefined
+        }
+
+        return {
+          type: nodeName,
+          raw: match[0],
+          attributes,
+        }
+      },
+    },
+
+    renderMarkdown: node => {
+      const filteredAttrs = filterAttributes(node.attrs || {})
+      const attrs = serializeAttributes(filteredAttrs)
+      const attrString = attrs ? ` {${attrs}}` : ''
+
+      return `:::${blockName}${attrString} :::`
+    },
+  }
+}

package/src/utilities/markdown/createBlockMarkdownSpec.ts

@@ -0,0 +1,225 @@
+import type {
+  JSONContent,
+  MarkdownParseHelpers,
+  MarkdownParseResult,
+  MarkdownRendererHelpers,
+  MarkdownToken,
+  MarkdownTokenizer,
+} from '../../types.js'
+import {
+  parseAttributes as defaultParseAttributes,
+  serializeAttributes as defaultSerializeAttributes,
+} from './attributeUtils.js'
+
+export interface BlockMarkdownSpecOptions {
+  /** The Tiptap node name this spec is for */
+  nodeName: string
+  /** The markdown syntax name (defaults to nodeName if not provided) */
+  name?: string
+  /** Function to extract content from the node for serialization */
+  getContent?: (token: MarkdownToken) => string
+  /** Function to parse attributes from the attribute string */
+  parseAttributes?: (attrString: string) => Record<string, any>
+  /** Function to serialize attributes to string */
+  serializeAttributes?: (attrs: Record<string, any>) => string
+  /** Default attributes to apply when parsing */
+  defaultAttributes?: Record<string, any>
+  /** Content type: 'block' allows paragraphs/lists/etc, 'inline' only allows bold/italic/links/etc */
+  content?: 'block' | 'inline'
+  /** Allowlist of attributes to include in markdown (if not provided, all attributes are included) */
+  allowedAttributes?: string[]
+}
+
+/**
+ * Creates a complete markdown spec for block-level nodes using Pandoc syntax.
+ *
+ * The generated spec handles:
+ * - Parsing blocks with `:::blockName {attributes}` syntax
+ * - Extracting and parsing attributes
+ * - Rendering blocks back to markdown with proper formatting
+ * - Nested content support
+ *
+ * @param options - Configuration for the block markdown spec
+ * @returns Complete markdown specification object
+ *
+ * @example
+ * ```ts
+ * const calloutSpec = createBlockMarkdownSpec({
+ *   nodeName: 'callout',
+ *   defaultAttributes: { type: 'info' },
+ *   allowedAttributes: ['type', 'title'] // Only these get rendered to markdown
+ * })
+ *
+ * // Usage in extension:
+ * export const Callout = Node.create({
+ *   // ... other config
+ *   markdown: calloutSpec
+ * })
+ * ```
+ */
+export function createBlockMarkdownSpec(options: BlockMarkdownSpecOptions): {
+  parseMarkdown: (token: MarkdownToken, h: MarkdownParseHelpers) => MarkdownParseResult
+  markdownTokenizer: MarkdownTokenizer
+  renderMarkdown: (node: JSONContent, h: MarkdownRendererHelpers) => string
+} {
+  const {
+    nodeName,
+    name: markdownName,
+    getContent,
+    parseAttributes = defaultParseAttributes,
+    serializeAttributes = defaultSerializeAttributes,
+    defaultAttributes = {},
+    content = 'block',
+    allowedAttributes,
+  } = options
+
+  // Use markdownName for syntax, fallback to nodeName
+  const blockName = markdownName || nodeName
+
+  // Helper function to filter attributes based on allowlist
+  const filterAttributes = (attrs: Record<string, any>) => {
+    if (!allowedAttributes) {
+      return attrs
+    }
+
+    const filtered: Record<string, any> = {}
+    allowedAttributes.forEach(key => {
+      if (key in attrs) {
+        filtered[key] = attrs[key]
+      }
+    })
+    return filtered
+  }
+
+  return {
+    parseMarkdown: (token, h) => {
+      let nodeContent: JSONContent[]
+
+      if (getContent) {
+        const contentResult = getContent(token)
+        // If getContent returns a string, wrap it in a text node
+        nodeContent = typeof contentResult === 'string' ? [{ type: 'text', text: contentResult }] : contentResult
+      } else if (content === 'block') {
+        nodeContent = h.parseChildren(token.tokens || [])
+      } else {
+        nodeContent = h.parseInline(token.tokens || [])
+      }
+
+      const attrs = { ...defaultAttributes, ...token.attributes }
+
+      return h.createNode(nodeName, attrs, nodeContent)
+    },
+
+    markdownTokenizer: {
+      name: nodeName,
+      level: 'block' as const,
+      start(src) {
+        const regex = new RegExp(`^:::${blockName}`, 'm')
+        const index = src.match(regex)?.index
+        return index !== undefined ? index : -1
+      },
+      tokenize(src, _tokens, lexer) {
+        // Match the opening tag with optional attributes
+        const openingRegex = new RegExp(`^:::${blockName}(?:\\s+\\{([^}]*)\\})?\\s*\\n`)
+        const openingMatch = src.match(openingRegex)
+
+        if (!openingMatch) {
+          return undefined
+        }
+
+        const [openingTag, attrString = ''] = openingMatch
+        const attributes = parseAttributes(attrString)
+
+        // Find the matching closing tag by tracking nesting level
+        let level = 1
+        const position = openingTag.length
+        let matchedContent = ''
+
+        // Pattern to match any block opening (:::word) or closing (:::)
+        const blockPattern = /^:::([\w-]*)(\s.*)?/gm
+        const remaining = src.slice(position)
+
+        blockPattern.lastIndex = 0
+
+        // run until no more matches are found
+        for (;;) {
+          const match = blockPattern.exec(remaining)
+          if (match === null) {
+            break
+          }
+          const matchPos = match.index
+          const blockType = match[1] // Empty string for closing tag, block name for opening
+
+          if (match[2]?.endsWith(':::')) {
+            // this is an atom ::: node, we skip it
+            continue
+          }
+
+          if (blockType) {
+            // Opening tag found - increase level
+            level += 1
+          } else {
+            // Closing tag found - decrease level
+            level -= 1
+
+            if (level === 0) {
+              // Found our matching closing tag
+              // Don't trim yet - keep newlines for tokenizer regex matching
+              const rawContent = remaining.slice(0, matchPos)
+              matchedContent = rawContent.trim()
+              const fullMatch = src.slice(0, position + matchPos + match[0].length)
+
+              // Tokenize the content
+              let contentTokens: MarkdownToken[] = []
+              if (matchedContent) {
+                if (content === 'block') {
+                  // Use rawContent for tokenization to preserve line boundaries for regex matching
+                  contentTokens = lexer.blockTokens(rawContent)
+
+                  // Parse inline tokens for any token that has text content but no tokens
+                  contentTokens.forEach(token => {
+                    if (token.text && (!token.tokens || token.tokens.length === 0)) {
+                      token.tokens = lexer.inlineTokens(token.text)
+                    }
+                  })
+
+                  // Clean up empty trailing paragraphs
+                  while (contentTokens.length > 0) {
+                    const lastToken = contentTokens[contentTokens.length - 1]
+                    if (lastToken.type === 'paragraph' && (!lastToken.text || lastToken.text.trim() === '')) {
+                      contentTokens.pop()
+                    } else {
+                      break
+                    }
+                  }
+                } else {
+                  contentTokens = lexer.inlineTokens(matchedContent)
+                }
+              }
+
+              return {
+                type: nodeName,
+                raw: fullMatch,
+                attributes,
+                content: matchedContent,
+                tokens: contentTokens,
+              }
+            }
+          }
+        }
+
+        // No matching closing tag found
+        return undefined
+      },
+    },
+
+    renderMarkdown: (node, h) => {
+      const filteredAttrs = filterAttributes(node.attrs || {})
+      const attrs = serializeAttributes(filteredAttrs)
+      const attrString = attrs ? ` {${attrs}}` : ''
+      const renderedContent = h.renderChildren(node.content || [], '\n\n')
+
+      return `:::${blockName}${attrString}\n\n${renderedContent}\n\n:::`
+    },
+  }
+}

package/src/utilities/markdown/createInlineMarkdownSpec.ts

@@ -0,0 +1,236 @@
+import type {
+  JSONContent,
+  MarkdownParseHelpers,
+  MarkdownParseResult,
+  MarkdownToken,
+  MarkdownTokenizer,
+} from '../../types.js'
+
+/**
+ * Parse shortcode attributes like 'id="madonna" handle="john" name="John Doe"'
+ * Requires all values to be quoted with either single or double quotes
+ */
+function parseShortcodeAttributes(attrString: string): Record<string, any> {
+  if (!attrString.trim()) {
+    return {}
+  }
+
+  const attributes: Record<string, any> = {}
+  // Match key=value pairs, only accepting quoted values
+  const regex = /(\w+)=(?:"([^"]*)"|'([^']*)')/g
+  let match = regex.exec(attrString)
+
+  while (match !== null) {
+    const [, key, doubleQuoted, singleQuoted] = match
+    attributes[key] = doubleQuoted || singleQuoted
+    match = regex.exec(attrString)
+  }
+
+  return attributes
+}
+
+/**
+ * Serialize attributes back to shortcode format
+ * Always quotes all values with double quotes
+ */
+function serializeShortcodeAttributes(attrs: Record<string, any>): string {
+  return Object.entries(attrs)
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([key, value]) => `${key}="${value}"`)
+    .join(' ')
+}
+
+export interface InlineMarkdownSpecOptions {
+  /** The Tiptap node name this spec is for */
+  nodeName: string
+  /** The shortcode name (defaults to nodeName if not provided) */
+  name?: string
+  /** Function to extract content from the node for serialization */
+  getContent?: (node: any) => string
+  /** Function to parse attributes from the attribute string */
+  parseAttributes?: (attrString: string) => Record<string, any>
+  /** Function to serialize attributes to string */
+  serializeAttributes?: (attrs: Record<string, any>) => string
+  /** Default attributes to apply when parsing */
+  defaultAttributes?: Record<string, any>
+  /** Whether this is a self-closing shortcode (no content, like [emoji name=party]) */
+  selfClosing?: boolean
+  /** Allowlist of attributes to include in markdown (if not provided, all attributes are included) */
+  allowedAttributes?: string[]
+}
+
+/**
+ * Creates a complete markdown spec for inline nodes using attribute syntax.
+ *
+ * The generated spec handles:
+ * - Parsing shortcode syntax with `[nodeName attributes]content[/nodeName]` format
+ * - Self-closing shortcodes like `[emoji name=party_popper]`
+ * - Extracting and parsing attributes from the opening tag
+ * - Rendering inline elements back to shortcode markdown
+ * - Supporting both content-based and self-closing inline elements
+ *
+ * @param options - Configuration for the inline markdown spec
+ * @returns Complete markdown specification object
+ *
+ * @example
+ * ```ts
+ * // Self-closing mention: [mention id="madonna" label="Madonna"]
+ * const mentionSpec = createInlineMarkdownSpec({
+ *   nodeName: 'mention',
+ *   selfClosing: true,
+ *   defaultAttributes: { type: 'user' },
+ *   allowedAttributes: ['id', 'label'] // Only these get rendered to markdown
+ * })
+ *
+ * // Self-closing emoji: [emoji name="party_popper"]
+ * const emojiSpec = createInlineMarkdownSpec({
+ *   nodeName: 'emoji',
+ *   selfClosing: true,
+ *   allowedAttributes: ['name']
+ * })
+ *
+ * // With content: [highlight color="yellow"]text[/highlight]
+ * const highlightSpec = createInlineMarkdownSpec({
+ *   nodeName: 'highlight',
+ *   selfClosing: false,
+ *   allowedAttributes: ['color', 'style']
+ * })
+ *
+ * // Usage in extension:
+ * export const Mention = Node.create({
+ *   name: 'mention', // Must match nodeName
+ *   // ... other config
+ *   markdown: mentionSpec
+ * })
+ * ```
+ */
+export function createInlineMarkdownSpec(options: InlineMarkdownSpecOptions): {
+  parseMarkdown: (token: MarkdownToken, h: MarkdownParseHelpers) => MarkdownParseResult
+  markdownTokenizer: MarkdownTokenizer
+  renderMarkdown: (node: JSONContent) => string
+} {
+  const {
+    nodeName,
+    name: shortcodeName,
+    getContent,
+    parseAttributes = parseShortcodeAttributes,
+    serializeAttributes = serializeShortcodeAttributes,
+    defaultAttributes = {},
+    selfClosing = false,
+    allowedAttributes,
+  } = options
+
+  // Use shortcodeName for markdown syntax, fallback to nodeName
+  const shortcode = shortcodeName || nodeName
+
+  // Helper function to filter attributes based on allowlist
+  const filterAttributes = (attrs: Record<string, any>) => {
+    if (!allowedAttributes) {
+      return attrs
+    }
+
+    const filtered: Record<string, any> = {}
+    allowedAttributes.forEach(key => {
+      if (key in attrs) {
+        filtered[key] = attrs[key]
+      }
+    })
+    return filtered
+  }
+
+  // Escape special regex characters in shortcode name
+  const escapedShortcode = shortcode.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+  return {
+    parseMarkdown: (token: MarkdownToken, h: MarkdownParseHelpers) => {
+      const attrs = { ...defaultAttributes, ...token.attributes }
+
+      if (selfClosing) {
+        // Self-closing nodes like mentions are atomic - no content
+        return h.createNode(nodeName, attrs)
+      }
+
+      // Nodes with content
+      const content = getContent ? getContent(token) : token.content || ''
+      if (content) {
+        // For inline content, create text nodes using the proper helper
+        return h.createNode(nodeName, attrs, [h.createTextNode(content)])
+      }
+      return h.createNode(nodeName, attrs, [])
+    },
+
+    markdownTokenizer: {
+      name: nodeName,
+      level: 'inline' as const,
+      start(src: string) {
+        // Create a non-global version for finding the start position
+        const startPattern = selfClosing
+          ? new RegExp(`\\[${escapedShortcode}\\s*[^\\]]*\\]`)
+          : new RegExp(`\\[${escapedShortcode}\\s*[^\\]]*\\][\\s\\S]*?\\[\\/${escapedShortcode}\\]`)
+
+        const match = src.match(startPattern)
+        const index = match?.index
+        return index !== undefined ? index : -1
+      },
+      tokenize(src, _tokens, _lexer) {
+        // Use non-global regex to match from the start of the string
+        const tokenPattern = selfClosing
+          ? new RegExp(`^\\[${escapedShortcode}\\s*([^\\]]*)\\]`)
+          : new RegExp(`^\\[${escapedShortcode}\\s*([^\\]]*)\\]([\\s\\S]*?)\\[\\/${escapedShortcode}\\]`)
+
+        const match = src.match(tokenPattern)
+
+        if (!match) {
+          return undefined
+        }
+
+        let content = ''
+        let attrString = ''
+
+        if (selfClosing) {
+          // Self-closing: [shortcode attr="value"]
+          const [, attrs] = match
+          attrString = attrs
+        } else {
+          // With content: [shortcode attr="value"]content[/shortcode]
+          const [, attrs, contentMatch] = match
+          attrString = attrs
+          content = contentMatch || ''
+        }
+
+        // Parse attributes from the attribute string
+        const attributes = parseAttributes(attrString.trim())
+
+        return {
+          type: nodeName,
+          raw: match[0],
+          content: content.trim(),
+          attributes,
+        }
+      },
+    },
+
+    renderMarkdown: (node: JSONContent) => {
+      let content = ''
+      if (getContent) {
+        content = getContent(node)
+      } else if (node.content && node.content.length > 0) {
+        // Extract text from content array for inline nodes
+        content = node.content
+          .filter((child: any) => child.type === 'text')
+          .map((child: any) => child.text)
+          .join('')
+      }
+
+      const filteredAttrs = filterAttributes(node.attrs || {})
+      const attrs = serializeAttributes(filteredAttrs)
+      const attrString = attrs ? ` ${attrs}` : ''
+
+      if (selfClosing) {
+        return `[${shortcode}${attrString}]`
+      }
+
+      return `[${shortcode}${attrString}]${content}[/${shortcode}]`
+    },
+  }
+}

package/src/utilities/markdown/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Markdown utilities for creating standardized markdown specs.
+ *
+ * This module provides utilities for creating complete markdown specifications
+ * for different types of nodes using unified syntax patterns.
+ */
+
+export * from './attributeUtils.js'
+export * from './createAtomBlockMarkdownSpec.js'
+export * from './createBlockMarkdownSpec.js'
+export * from './createInlineMarkdownSpec.js'
+export * from './parseIndentedBlocks.js'
+export * from './renderNestedMarkdownContent.js'