@tiptap/static-renderer 3.0.0-next.1

package/src/json/html-string/string.example.ts

@@ -0,0 +1,46 @@
+import { renderJSONContentToString } from './string.js'
+
+/**
+ * This example demonstrates how to render a JSON representation of a node to a string
+ * It does so without including Prosemirror or Tiptap, it is the lightest possible way to render JSON content
+ * But, since it doesn't include Prosemirror or Tiptap, it cannot automatically render marks or nodes for you.
+ * If you need that, you should use the `renderToHTMLString` from `@tiptap/static-renderer`
+ *
+ * You have complete control over the rendering process. And can replace how each Node/Mark is rendered.
+ */
+
+// eslint-disable-next-line no-console
+console.log(
+  renderJSONContentToString({
+    nodeMapping: {
+      text({ node }) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return node.text!
+      },
+      heading({ node, children }) {
+        const level = node.attrs?.level
+        const attrs = Object.entries(node.attrs || {})
+          .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+          .join(' ')
+
+        return `<h${level}${attrs ? ` ${attrs}` : ''}>${([] as string[])
+          .concat(children || '')
+          .filter(Boolean)
+          .join('\n')}</h${level}>`
+      },
+    },
+    markMapping: {},
+  })({
+    content: {
+      type: 'heading',
+      content: [
+        {
+          type: 'text',
+          text: 'hello world',
+          marks: [],
+        },
+      ],
+      attrs: { level: 2 },
+    },
+  }),
+)

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

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { MarkType, NodeType } from '../../types.js'
+import { TiptapStaticRenderer, TiptapStaticRendererOptions } from '../renderer.js'
+
+export function renderJSONContentToString<
+/**
+ * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+ */
+TMarkType extends { type: any } = MarkType,
+/**
+ * A node type is either a JSON representation of a node or a Prosemirror node instance
+ */
+TNodeType extends {
+  content?: { forEach:(cb: (node: TNodeType) => void) => void };
+  marks?: readonly TMarkType[];
+  type: string | { name: string };
+} = NodeType,
+>(options: TiptapStaticRendererOptions<string, TMarkType, TNodeType>) {
+  return TiptapStaticRenderer(ctx => {
+    return ctx.component(ctx.props as any)
+  }, options)
+}

package/src/json/react/index.ts

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

package/src/json/react/react.example.ts

@@ -0,0 +1,45 @@
+import React from 'react'
+
+import { NodeType } from '../../types.js'
+import { NodeProps } from '../renderer.js'
+import { renderJSONContentToReactElement } from './react.js'
+
+/**
+ * This example demonstrates how to render a JSON representation of a node to a React element
+ * It does so without including Prosemirror or Tiptap, it is the lightest possible way to render JSON content
+ * But, since it doesn't include Prosemirror or Tiptap, it cannot automatically render marks or nodes for you.
+ * If you need that, you should use the `renderToReactElement` from `@tiptap/static-renderer`
+ *
+ * You have complete control over the rendering process. And can replace how each Node/Mark is rendered.
+ */
+
+// eslint-disable-next-line no-console
+console.log(renderJSONContentToReactElement({
+  nodeMapping: {
+    text({ node }) {
+      return node.text ?? null
+    },
+    heading({
+      node,
+      children,
+    }: NodeProps<NodeType<'heading', { level: number }>, React.ReactNode>) {
+      const level = node.attrs.level
+      const hTag = `h${level}`
+
+      return React.createElement(hTag, node.attrs, children)
+    },
+  },
+  markMapping: {},
+})({
+  content: {
+    type: 'heading',
+    content: [
+      {
+        type: 'text',
+        text: 'hello world',
+        marks: [],
+      },
+    ],
+    attrs: { level: 2 },
+  },
+}))

package/src/json/react/react.tsx

@@ -0,0 +1,35 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import React from 'react'
+
+import { MarkType, NodeType } from '../../types.js'
+import { TiptapStaticRenderer, TiptapStaticRendererOptions } from '../renderer.js'
+
+export function renderJSONContentToReactElement<
+  /**
+   * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+   */
+  TMarkType extends { type: any } = MarkType,
+  /**
+   * A node type is either a JSON representation of a node or a Prosemirror node instance
+   */
+  TNodeType extends {
+    content?: { forEach:(cb: (node: TNodeType) => void) => void };
+    marks?: readonly TMarkType[];
+    type: string | { name: string };
+  } = NodeType,
+>(options: TiptapStaticRendererOptions<React.ReactNode, TMarkType, TNodeType>) {
+  let key = 0
+
+  return TiptapStaticRenderer<React.ReactNode, TMarkType, TNodeType>(
+    ({ component, props: { children, ...props } }) => {
+      return React.createElement(
+        component as React.FC<typeof props>,
+        // eslint-disable-next-line no-plusplus
+        Object.assign(props, { key: key++ }),
+        ([] as React.ReactNode[]).concat(children),
+      )
+    },
+    options,
+  )
+}

package/src/json/renderer.ts

@@ -0,0 +1,242 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { MarkType, NodeType } from '../types'
+
+/**
+ * Props for a node renderer
+ */
+export type NodeProps<TNodeType = any, TChildren = any> = {
+  /**
+   * The current node to render
+   */
+  node: TNodeType;
+  /**
+   * Unless the node is the root node, this will always be defined
+   */
+  parent?: TNodeType;
+  /**
+   * The children of the current node
+   */
+  children?: TChildren;
+  /**
+   * Render a child element
+   */
+  renderElement: (props: {
+    /**
+     * Tiptap JSON content to render
+     */
+    content: TNodeType;
+    /**
+     * The parent node of the current node
+     */
+    parent?: TNodeType;
+  }) => TChildren;
+};
+
+/**
+ * Props for a mark renderer
+ */
+export type MarkProps<TMarkType = any, TChildren = any, TNodeType = any> = {
+  /**
+   * The current mark to render
+   */
+  mark: TMarkType;
+  /**
+   * The children of the current mark
+   */
+  children?: TChildren;
+  /**
+   * The node the current mark is applied to
+   */
+  node: TNodeType;
+  /**
+   * The node the current mark is applied to
+   */
+  parent?: TNodeType;
+};
+
+export type TiptapStaticRendererOptions<
+  /**
+   * The return type of the render function (e.g. React.ReactNode, string)
+   */
+  TReturnType,
+  /**
+   * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+   */
+  TMarkType extends { type: any } = MarkType,
+  /**
+   * A node type is either a JSON representation of a node or a Prosemirror node instance
+   */
+  TNodeType extends {
+    content?: { forEach: (cb: (node: TNodeType) => void) => void };
+    marks?: readonly TMarkType[];
+    type: string | { name: string };
+  } = NodeType,
+  /**
+   * A node renderer is a function that takes a node and its children and returns the rendered output
+   */
+  TNodeRender extends (ctx: NodeProps<TNodeType, TReturnType | TReturnType[]>) => TReturnType = (
+    ctx: NodeProps<TNodeType, TReturnType | TReturnType[]>
+  ) => TReturnType,
+  /**
+   * A mark renderer is a function that takes a mark and its children and returns the rendered output
+   */
+  TMarkRender extends (ctx: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>) => TReturnType = (
+    ctx: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>
+  ) => TReturnType,
+> = {
+  /**
+   * Mapping of node types to react components
+   */
+  nodeMapping: Record<string, TNodeRender>;
+  /**
+   * Mapping of mark types to react components
+   */
+  markMapping: Record<string, TMarkRender>;
+  /**
+   * Component to render if a node type is not handled
+   */
+  unhandledNode?: TNodeRender;
+  /**
+   * Component to render if a mark type is not handled
+   */
+  unhandledMark?: TMarkRender;
+};
+
+/**
+ * Tiptap Static Renderer
+ * ----------------------
+ *
+ * This function is a basis to allow for different renderers to be created.
+ * Generic enough to be able to statically render Prosemirror JSON or Prosemirror Nodes.
+ *
+ * Using this function, you can create a renderer that takes a JSON representation of a Prosemirror document
+ * and renders it using a mapping of node types to React components or even to a string.
+ * This function is used as the basis to create the `reactRenderer` and `stringRenderer` functions.
+ */
+export function TiptapStaticRenderer<
+  /**
+   * The return type of the render function (e.g. React.ReactNode, string)
+   */
+  TReturnType,
+  /**
+   * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+   */
+  TMarkType extends { type: string | { name: string } } = MarkType,
+  /**
+   * A node type is either a JSON representation of a node or a Prosemirror node instance
+   */
+  TNodeType extends {
+    content?: { forEach:(
+cb: (node: TNodeType) => void) => void };
+    marks?: readonly TMarkType[];
+    type: string | { name: string };
+  } = NodeType,
+  /**
+   * A node renderer is a function that takes a node and its children and returns the rendered output
+   */
+  TNodeRender extends (ctx: NodeProps<TNodeType, TReturnType | TReturnType[]>) => TReturnType = (
+    ctx: NodeProps<TNodeType, TReturnType | TReturnType[]>
+  ) => TReturnType,
+  /**
+   * A mark renderer is a function that takes a mark and its children and returns the rendered output
+   */
+  TMarkRender extends (ctx: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>) => TReturnType = (
+    ctx: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>
+  ) => TReturnType,
+>(
+  /**
+   * The function that actually renders the component
+   */
+  renderComponent: (
+    ctx:
+      | {
+          component: TNodeRender;
+          props: NodeProps<TNodeType, TReturnType | TReturnType[]>;
+        }
+      | {
+          component: TMarkRender;
+          props: MarkProps<TMarkType, TReturnType | TReturnType[], TNodeType>;
+        }
+  ) => TReturnType,
+  {
+    nodeMapping,
+    markMapping,
+    unhandledNode,
+    unhandledMark,
+  }: TiptapStaticRendererOptions<TReturnType, TMarkType, TNodeType, TNodeRender, TMarkRender>,
+) {
+  /**
+   * Render Tiptap JSON and all its children using the provided node and mark mappings.
+   */
+  return function renderContent({
+    content,
+    parent,
+  }: {
+    /**
+     * Tiptap JSON content to render
+     */
+    content: TNodeType;
+    /**
+     * The parent node of the current node
+     */
+    parent?: TNodeType;
+  }): TReturnType {
+    const nodeType = typeof content.type === 'string' ? content.type : content.type.name
+    const NodeHandler = nodeMapping[nodeType] ?? unhandledNode
+
+    if (!NodeHandler) {
+      throw new Error(`missing handler for node type ${nodeType}`)
+    }
+
+    const nodeContent = renderComponent({
+      component: NodeHandler,
+      props: {
+        node: content,
+        parent,
+        renderElement: renderContent,
+        // Lazily compute the children to avoid unnecessary recursion
+        get children() {
+          // recursively render child content nodes
+          const children: TReturnType[] = []
+
+          if (content.content) {
+            content.content.forEach(child => {
+              children.push(
+                renderContent({
+                  content: child,
+                  parent: content,
+                }),
+              )
+            })
+          }
+
+          return children
+        },
+      },
+    })
+
+    // apply marks to the content
+    const markedContent = content.marks
+      ? content.marks.reduce((acc, mark) => {
+        const markType = typeof mark.type === 'string' ? mark.type : mark.type.name
+        const MarkHandler = markMapping[markType] ?? unhandledMark
+
+        if (!MarkHandler) {
+          throw new Error(`missing handler for mark type ${markType}`)
+        }
+
+        return renderComponent({
+          component: MarkHandler,
+          props: {
+            mark,
+            parent,
+            node: content,
+            children: acc,
+          },
+        })
+      }, nodeContent)
+      : nodeContent
+
+    return markedContent
+  }
+}

package/src/pm/extensionRenderer.ts

@@ -0,0 +1,230 @@
+/* eslint-disable no-plusplus */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  ExtensionAttribute,
+  Extensions,
+  getAttributesFromExtensions,
+  getExtensionField,
+  getSchemaByResolvedExtensions,
+  JSONContent,
+  Mark as MarkExtension,
+  MarkConfig,
+  Node as NodeExtension,
+  NodeConfig,
+  resolveExtensions,
+  splitExtensions,
+} from '@tiptap/core'
+import { DOMOutputSpec, Mark, Node } from '@tiptap/pm/model'
+
+import { getHTMLAttributes } from '../helpers.js'
+import { 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 })
+}