@tiptap/static-renderer 3.0.0-beta.0

package/src/pm/extensionRenderer.ts

@@ -0,0 +1,215 @@
+/* eslint-disable no-plusplus */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type {
+  ExtensionAttribute,
+  Extensions,
+  JSONContent,
+  Mark as MarkExtension,
+  MarkConfig,
+  Node as NodeExtension,
+  NodeConfig,
+} from '@tiptap/core'
+import {
+  getAttributesFromExtensions,
+  getExtensionField,
+  getSchemaByResolvedExtensions,
+  resolveExtensions,
+  splitExtensions,
+} from '@tiptap/core'
+import type { DOMOutputSpec, Mark } from '@tiptap/pm/model'
+import { Node } from '@tiptap/pm/model'
+
+import { getHTMLAttributes } from '../helpers.js'
+import type { MarkProps, NodeProps, TiptapStaticRendererOptions } from '../json/renderer.js'
+
+export type DomOutputSpecToElement<T> = (content: DOMOutputSpec) => (children?: T | T[]) => T
+
+/**
+ * This takes a NodeExtension and maps it to a React component
+ * @param extension The node extension to map to a React component
+ * @param extensionAttributes All available extension attributes
+ * @returns A tuple with the name of the extension and a React component that renders the extension
+ */
+export function mapNodeExtensionToReactNode<T>(
+  domOutputSpecToElement: DomOutputSpecToElement<T>,
+  extension: NodeExtension,
+  extensionAttributes: ExtensionAttribute[],
+  options?: Partial<Pick<TiptapStaticRendererOptions<T, Mark, Node>, 'unhandledNode'>>,
+): [string, (props: NodeProps<Node, T | T[]>) => T] {
+  const context = {
+    name: extension.name,
+    options: extension.options,
+    storage: extension.storage,
+    parent: extension.parent,
+  }
+
+  const renderToHTML = getExtensionField<NodeConfig['renderHTML']>(extension, 'renderHTML', context)
+
+  if (!renderToHTML) {
+    if (options?.unhandledNode) {
+      return [extension.name, options.unhandledNode]
+    }
+    return [
+      extension.name,
+      () => {
+        throw new Error(
+          `[tiptap error]: Node ${extension.name} cannot be rendered, it is missing a "renderToHTML" method, please implement it or override the corresponding "nodeMapping" method to have a custom rendering`,
+        )
+      },
+    ]
+  }
+
+  return [
+    extension.name,
+    ({ node, children }) => {
+      try {
+        return domOutputSpecToElement(
+          renderToHTML({
+            node,
+            HTMLAttributes: getHTMLAttributes(node, extensionAttributes),
+          }),
+        )(children)
+      } catch (e) {
+        throw new Error(
+          `[tiptap error]: Node ${
+            extension.name
+          } cannot be rendered, it's "renderToHTML" method threw an error: ${(e as Error).message}`,
+          { cause: e },
+        )
+      }
+    },
+  ]
+}
+
+/**
+ * This takes a MarkExtension and maps it to a React component
+ * @param extension The mark extension to map to a React component
+ * @param extensionAttributes All available extension attributes
+ * @returns A tuple with the name of the extension and a React component that renders the extension
+ */
+export function mapMarkExtensionToReactNode<T>(
+  domOutputSpecToElement: DomOutputSpecToElement<T>,
+  extension: MarkExtension,
+  extensionAttributes: ExtensionAttribute[],
+  options?: Partial<Pick<TiptapStaticRendererOptions<T, Mark, Node>, 'unhandledMark'>>,
+): [string, (props: MarkProps<Mark, T | T[]>) => T] {
+  const context = {
+    name: extension.name,
+    options: extension.options,
+    storage: extension.storage,
+    parent: extension.parent,
+  }
+
+  const renderToHTML = getExtensionField<MarkConfig['renderHTML']>(extension, 'renderHTML', context)
+
+  if (!renderToHTML) {
+    if (options?.unhandledMark) {
+      return [extension.name, options.unhandledMark]
+    }
+    return [
+      extension.name,
+      () => {
+        throw new Error(`Node ${extension.name} cannot be rendered, it is missing a "renderToHTML" method`)
+      },
+    ]
+  }
+
+  return [
+    extension.name,
+    ({ mark, children }) => {
+      try {
+        return domOutputSpecToElement(
+          renderToHTML({
+            mark,
+            HTMLAttributes: getHTMLAttributes(mark, extensionAttributes),
+          }),
+        )(children)
+      } catch (e) {
+        throw new Error(
+          `[tiptap error]: Mark ${
+            extension.name
+          } cannot be rendered, it's "renderToHTML" method threw an error: ${(e as Error).message}`,
+          { cause: e },
+        )
+      }
+    },
+  ]
+}
+
+/**
+ * This function will statically render a Prosemirror Node to a target element type using the given extensions
+ * @param renderer The renderer to use to render the Prosemirror Node to the target element type
+ * @param domOutputSpecToElement A function that takes a Prosemirror DOMOutputSpec and returns a function that takes children and returns the target element type
+ * @param mapDefinedTypes An object with functions to map the doc and text types to the target element type
+ * @param content The Prosemirror Node to render
+ * @param extensions The extensions to use to render the Prosemirror Node
+ * @param options Additional options to pass to the renderer that can override the default behavior
+ * @returns The rendered target element type
+ */
+export function renderToElement<T>({
+  renderer,
+  domOutputSpecToElement,
+  mapDefinedTypes,
+  content,
+  extensions,
+  options,
+}: {
+  renderer: (options: TiptapStaticRendererOptions<T, Mark, Node>) => (ctx: { content: Node }) => T
+  domOutputSpecToElement: DomOutputSpecToElement<T>
+  mapDefinedTypes: {
+    doc: (props: NodeProps<Node, T | T[]>) => T
+    text: (props: NodeProps<Node, T | T[]>) => T
+  }
+  content: Node | JSONContent
+  extensions: Extensions
+  options?: Partial<TiptapStaticRendererOptions<T, Mark, Node>>
+}): T {
+  // get all extensions in order & split them into nodes and marks
+  extensions = resolveExtensions(extensions)
+  const extensionAttributes = getAttributesFromExtensions(extensions)
+  const { nodeExtensions, markExtensions } = splitExtensions(extensions)
+
+  if (!(content instanceof Node)) {
+    content = Node.fromJSON(getSchemaByResolvedExtensions(extensions), content)
+  }
+
+  return renderer({
+    ...options,
+    nodeMapping: {
+      ...Object.fromEntries(
+        nodeExtensions
+          .filter(e => {
+            if (e.name in mapDefinedTypes) {
+              // These are predefined types that we don't need to map
+              return false
+            }
+            // No need to generate mappings for nodes that are already mapped
+            if (options?.nodeMapping) {
+              return !(e.name in options.nodeMapping)
+            }
+            return true
+          })
+          .map(nodeExtension =>
+            mapNodeExtensionToReactNode<T>(domOutputSpecToElement, nodeExtension, extensionAttributes, options),
+          ),
+      ),
+      ...mapDefinedTypes,
+      ...options?.nodeMapping,
+    },
+    markMapping: {
+      ...Object.fromEntries(
+        markExtensions
+          .filter(e => {
+            // No need to generate mappings for marks that are already mapped
+            if (options?.markMapping) {
+              return !(e.name in options.markMapping)
+            }
+            return true
+          })
+          .map(mark => mapMarkExtensionToReactNode<T>(domOutputSpecToElement, mark, extensionAttributes, options)),
+      ),
+      ...options?.markMapping,
+    },
+  })({ content })
+}

package/src/pm/html-string/html-string.ts

@@ -0,0 +1,105 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { DOMOutputSpecArray, Extensions, JSONContent } from '@tiptap/core'
+import type { DOMOutputSpec, Mark, Node } from '@tiptap/pm/model'
+
+import {
+  renderJSONContentToString,
+  serializeAttrsToHTMLString,
+  serializeChildrenToHTMLString,
+} from '../../json/html-string/string.js'
+import type { TiptapStaticRendererOptions } from '../../json/renderer.js'
+import { renderToElement } from '../extensionRenderer.js'
+
+export { serializeAttrsToHTMLString, serializeChildrenToHTMLString } from '../../json/html-string/string.js'
+
+/**
+ * Take a DOMOutputSpec and return a function that can render it to a string
+ * @param content The DOMOutputSpec to convert to a string
+ * @returns A function that can render the DOMOutputSpec to a string
+ */
+export function domOutputSpecToHTMLString(content: DOMOutputSpec): (children?: string | string[]) => string {
+  if (typeof content === 'string') {
+    return () => content
+  }
+  if (typeof content === 'object' && 'length' in content) {
+    const [_tag, attrs, children, ...rest] = content as DOMOutputSpecArray
+    let tag = _tag
+    const parts = tag.split(' ')
+
+    if (parts.length > 1) {
+      tag = `${parts[1]} xmlns="${parts[0]}"`
+    }
+
+    if (attrs === undefined) {
+      return () => `<${tag}/>`
+    }
+    if (attrs === 0) {
+      return child => `<${tag}>${serializeChildrenToHTMLString(child)}</${tag}>`
+    }
+    if (typeof attrs === 'object') {
+      if (Array.isArray(attrs)) {
+        if (children === undefined) {
+          return child => `<${tag}>${domOutputSpecToHTMLString(attrs as DOMOutputSpecArray)(child)}</${tag}>`
+        }
+        if (children === 0) {
+          return child => `<${tag}>${domOutputSpecToHTMLString(attrs as DOMOutputSpecArray)(child)}</${tag}>`
+        }
+        return child =>
+          `<${tag}>${domOutputSpecToHTMLString(attrs as DOMOutputSpecArray)(child)}${[children]
+            .concat(rest)
+            .map(a => domOutputSpecToHTMLString(a)(child))}</${tag}>`
+      }
+      if (children === undefined) {
+        return () => `<${tag}${serializeAttrsToHTMLString(attrs)}/>`
+      }
+      if (children === 0) {
+        return child => `<${tag}${serializeAttrsToHTMLString(attrs)}>${serializeChildrenToHTMLString(child)}</${tag}>`
+      }
+
+      return child =>
+        `<${tag}${serializeAttrsToHTMLString(attrs)}>${[children]
+          .concat(rest)
+          .map(a => domOutputSpecToHTMLString(a)(child))
+          .join('')}</${tag}>`
+    }
+  }
+
+  // TODO support DOM elements? How to handle them?
+  throw new Error(
+    '[tiptap error]: Unsupported DomOutputSpec type, check the `renderHTML` method output or implement a node mapping',
+    {
+      cause: content,
+    },
+  )
+}
+
+/**
+ * This function will statically render a Prosemirror Node to HTML using the provided extensions and options
+ * @param content The content to render to HTML
+ * @param extensions The extensions to use for rendering
+ * @param options The options to use for rendering
+ * @returns The rendered HTML string
+ */
+export function renderToHTMLString({
+  content,
+  extensions,
+  options,
+}: {
+  content: Node | JSONContent
+  extensions: Extensions
+  options?: Partial<TiptapStaticRendererOptions<string, Mark, Node>>
+}): string {
+  return renderToElement<string>({
+    renderer: renderJSONContentToString,
+    domOutputSpecToElement: domOutputSpecToHTMLString,
+    mapDefinedTypes: {
+      // Map a doc node to concatenated children
+      doc: ({ children }) => serializeChildrenToHTMLString(children),
+      // Map a text node to its text content
+      text: ({ node }) => node.text ?? '',
+    },
+    content,
+    extensions,
+    options,
+  })
+}

package/src/pm/html-string/index.ts

@@ -0,0 +1,2 @@
+export * from '../extensionRenderer.js'
+export * from './html-string.js'

package/src/pm/markdown/index.ts

@@ -0,0 +1,2 @@
+export * from '../extensionRenderer.js'
+export * from './markdown.js'

package/src/pm/markdown/markdown.ts

@@ -0,0 +1,142 @@
+import type { Extensions, JSONContent } from '@tiptap/core'
+import type { Mark, Node } from '@tiptap/pm/model'
+
+import type { TiptapStaticRendererOptions } from '../../json/renderer.js'
+import { renderToHTMLString, serializeChildrenToHTMLString } from '../html-string/html-string.js'
+
+/**
+ * This code is just to show the flexibility of this renderer. We can potentially render content to any format we want.
+ * This is a simple example of how we can render content to markdown. This is not a full implementation of a markdown renderer.
+ */
+export function renderToMarkdown({
+  content,
+  extensions,
+  options,
+}: {
+  content: Node | JSONContent
+  extensions: Extensions
+  options?: Partial<TiptapStaticRendererOptions<string, Mark, Node>>
+}) {
+  return renderToHTMLString({
+    content,
+    extensions,
+    options: {
+      nodeMapping: {
+        bulletList({ children }) {
+          return `\n${serializeChildrenToHTMLString(children)}`
+        },
+        orderedList({ children }) {
+          return `\n${serializeChildrenToHTMLString(children)}`
+        },
+        listItem({ node, children, parent }) {
+          if (parent?.type.name === 'bulletList') {
+            return `- ${serializeChildrenToHTMLString(children).trim()}\n`
+          }
+          if (parent?.type.name === 'orderedList') {
+            let number = parent.attrs.start || 1
+
+            parent.forEach((parentChild, _offset, index) => {
+              if (node === parentChild) {
+                number = index + 1
+              }
+            })
+
+            return `${number}. ${serializeChildrenToHTMLString(children).trim()}\n`
+          }
+
+          return serializeChildrenToHTMLString(children)
+        },
+        paragraph({ children }) {
+          return `\n${serializeChildrenToHTMLString(children)}\n`
+        },
+        heading({ node, children }) {
+          const level = node.attrs.level as number
+
+          return `${new Array(level).fill('#').join('')} ${children}\n`
+        },
+        codeBlock({ node, children }) {
+          return `\n\`\`\`${node.attrs.language}\n${serializeChildrenToHTMLString(children)}\n\`\`\`\n`
+        },
+        blockquote({ children }) {
+          return `\n${serializeChildrenToHTMLString(children)
+            .trim()
+            .split('\n')
+            .map(a => `> ${a}`)
+            .join('\n')}`
+        },
+        image({ node }) {
+          return `![${node.attrs.alt}](${node.attrs.src})`
+        },
+        hardBreak() {
+          return '\n'
+        },
+        horizontalRule() {
+          return '\n---\n'
+        },
+        table({ children, node }) {
+          if (!Array.isArray(children)) {
+            return `\n${serializeChildrenToHTMLString(children)}\n`
+          }
+
+          return `\n${serializeChildrenToHTMLString(children[0])}| ${new Array(node.childCount - 2).fill('---').join(' | ')} |\n${serializeChildrenToHTMLString(children.slice(1))}\n`
+        },
+        tableRow({ children }) {
+          if (Array.isArray(children)) {
+            return `| ${children.join(' | ')} |\n`
+          }
+          return `${serializeChildrenToHTMLString(children)}\n`
+        },
+        tableHeader({ children }) {
+          return serializeChildrenToHTMLString(children).trim()
+        },
+        tableCell({ children }) {
+          return serializeChildrenToHTMLString(children).trim()
+        },
+        ...options?.nodeMapping,
+      },
+      markMapping: {
+        bold({ children }) {
+          return `**${serializeChildrenToHTMLString(children)}**`
+        },
+        italic({ children, node }) {
+          let isBoldToo = false
+
+          // Check if the node being wrapped also has a bold mark, if so, we need to use the bold markdown syntax
+          if (node?.marks.some(m => m.type.name === 'bold')) {
+            isBoldToo = true
+          }
+
+          if (isBoldToo) {
+            // If the content is bold, just wrap the bold content in italic markdown syntax with another set of asterisks
+            return `*${serializeChildrenToHTMLString(children)}*`
+          }
+
+          return `_${serializeChildrenToHTMLString(children)}_`
+        },
+        code({ children }) {
+          return `\`${serializeChildrenToHTMLString(children)}\``
+        },
+        strike({ children }) {
+          return `~~${serializeChildrenToHTMLString(children)}~~`
+        },
+        underline({ children }) {
+          return `<u>${serializeChildrenToHTMLString(children)}</u>`
+        },
+        subscript({ children }) {
+          return `<sub>${serializeChildrenToHTMLString(children)}</sub>`
+        },
+        superscript({ children }) {
+          return `<sup>${serializeChildrenToHTMLString(children)}</sup>`
+        },
+        link({ node, children }) {
+          return `[${serializeChildrenToHTMLString(children)}](${node.attrs.href})`
+        },
+        highlight({ children }) {
+          return `==${serializeChildrenToHTMLString(children)}==`
+        },
+        ...options?.markMapping,
+      },
+      ...options,
+    },
+  })
+}

package/src/pm/react/index.ts

@@ -0,0 +1,2 @@
+export * from '../extensionRenderer.js'
+export * from './react.js'

package/src/pm/react/react.ts

@@ -0,0 +1,152 @@
+/* eslint-disable no-plusplus, @typescript-eslint/no-explicit-any */
+import type { DOMOutputSpecArray, Extensions, JSONContent } from '@tiptap/core'
+import type { DOMOutputSpec, Mark, Node } from '@tiptap/pm/model'
+import React from 'react'
+
+import { renderJSONContentToReactElement } from '../../json/react/react.js'
+import type { TiptapStaticRendererOptions } from '../../json/renderer.js'
+import { renderToElement } from '../extensionRenderer.js'
+
+/**
+ * This function maps the attributes of a node or mark to HTML attributes
+ * @param attrs The attributes to map
+ * @param key The key to use for the React element
+ * @returns The mapped HTML attributes as an object
+ */
+function mapAttrsToHTMLAttributes(attrs?: Record<string, any>, key?: string): Record<string, any> {
+  if (!attrs) {
+    return { key }
+  }
+  return Object.entries(attrs).reduce(
+    (acc, [name, value]) => {
+      if (name === 'class') {
+        return Object.assign(acc, { className: value })
+      }
+      return Object.assign(acc, { [name]: value })
+    },
+    { key },
+  )
+}
+
+/**
+ * Take a DOMOutputSpec and return a function that can render it to a React element
+ * @param content The DOMOutputSpec to convert to a React element
+ * @returns A function that can render the DOMOutputSpec to a React element
+ */
+export function domOutputSpecToReactElement(
+  content: DOMOutputSpec,
+  key = 0,
+): (children?: React.ReactNode) => React.ReactNode {
+  if (typeof content === 'string') {
+    return () => content
+  }
+  if (typeof content === 'object' && 'length' in content) {
+    // eslint-disable-next-line prefer-const
+    let [tag, attrs, children, ...rest] = content as DOMOutputSpecArray
+    const parts = tag.split(' ')
+
+    if (parts.length > 1) {
+      tag = parts[1]
+      if (attrs === undefined) {
+        attrs = {
+          xmlns: parts[0],
+        }
+      }
+      if (attrs === 0) {
+        attrs = {
+          xmlns: parts[0],
+        }
+        children = 0
+      }
+      if (typeof attrs === 'object') {
+        attrs = Object.assign(attrs, { xmlns: parts[0] })
+      }
+    }
+
+    if (attrs === undefined) {
+      return () => React.createElement(tag, mapAttrsToHTMLAttributes(undefined, key.toString()))
+    }
+    if (attrs === 0) {
+      return child => React.createElement(tag, mapAttrsToHTMLAttributes(undefined, key.toString()), child)
+    }
+    if (typeof attrs === 'object') {
+      if (Array.isArray(attrs)) {
+        if (children === undefined) {
+          return child =>
+            React.createElement(
+              tag,
+              mapAttrsToHTMLAttributes(undefined, key.toString()),
+              domOutputSpecToReactElement(attrs as DOMOutputSpecArray, key++)(child),
+            )
+        }
+        if (children === 0) {
+          return child =>
+            React.createElement(
+              tag,
+              mapAttrsToHTMLAttributes(undefined, key.toString()),
+              domOutputSpecToReactElement(attrs as DOMOutputSpecArray, key++)(child),
+            )
+        }
+        return child =>
+          React.createElement(
+            tag,
+            mapAttrsToHTMLAttributes(undefined, key.toString()),
+            domOutputSpecToReactElement(attrs as DOMOutputSpecArray)(child),
+            [children].concat(rest).map(outputSpec => domOutputSpecToReactElement(outputSpec, key++)(child)),
+          )
+      }
+      if (children === undefined) {
+        return () => React.createElement(tag, mapAttrsToHTMLAttributes(attrs, key.toString()))
+      }
+      if (children === 0) {
+        return child => React.createElement(tag, mapAttrsToHTMLAttributes(attrs, key.toString()), child)
+      }
+
+      return child =>
+        React.createElement(
+          tag,
+          mapAttrsToHTMLAttributes(attrs, key.toString()),
+          [children].concat(rest).map(outputSpec => domOutputSpecToReactElement(outputSpec, key++)(child)),
+        )
+    }
+  }
+
+  // TODO support DOM elements? How to handle them?
+  throw new Error(
+    '[tiptap error]: Unsupported DomOutputSpec type, check the `renderHTML` method output or implement a node mapping',
+    {
+      cause: content,
+    },
+  )
+}
+
+/**
+ * This function will statically render a Prosemirror Node to a React component using the given extensions
+ * @param content The content to render to a React component
+ * @param extensions The extensions to use for rendering
+ * @param options The options to use for rendering
+ * @returns The React element that represents the rendered content
+ */
+export function renderToReactElement({
+  content,
+  extensions,
+  options,
+}: {
+  content: Node | JSONContent
+  extensions: Extensions
+  options?: Partial<TiptapStaticRendererOptions<React.ReactNode, Mark, Node>>
+}): React.ReactNode {
+  return renderToElement<React.ReactNode>({
+    renderer: renderJSONContentToReactElement,
+    domOutputSpecToElement: domOutputSpecToReactElement,
+    mapDefinedTypes: {
+      // Map a doc node to concatenated children
+      doc: ({ children }) => React.createElement(React.Fragment, {}, children),
+      // Map a text node to its text content
+      text: ({ node }) => node.text ?? '',
+    },
+    content,
+    extensions,
+    options,
+  })
+}