@tiptap/static-renderer 3.0.0-beta.0

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@tiptap/static-renderer",
+  "description": "statically render Tiptap JSON",
+  "version": "3.0.0-beta.0",
+  "homepage": "https://tiptap.dev",
+  "keywords": [
+    "tiptap",
+    "tiptap static renderer",
+    "tiptap react renderer"
+  ],
+  "license": "MIT",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/ueberdosis"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./json/react": {
+      "types": {
+        "import": "./dist/json/react/index.d.ts",
+        "require": "./dist/json/react/index.d.cts"
+      },
+      "import": "./dist/json/react/index.js",
+      "require": "./dist/json/react/index.cjs"
+    },
+    "./json/html-string": {
+      "types": {
+        "import": "./dist/json/html-string/index.d.ts",
+        "require": "./dist/json/html-string/index.d.cts"
+      },
+      "import": "./dist/json/html-string/index.js",
+      "require": "./dist/json/html-string/index.cjs"
+    },
+    "./pm/react": {
+      "types": {
+        "import": "./dist/pm/react/index.d.ts",
+        "require": "./dist/pm/react/index.d.cts"
+      },
+      "import": "./dist/pm/react/index.js",
+      "require": "./dist/pm/react/index.cjs"
+    },
+    "./pm/html-string": {
+      "types": {
+        "import": "./dist/pm/html-string/index.d.ts",
+        "require": "./dist/pm/html-string/index.d.cts"
+      },
+      "import": "./dist/pm/html-string/index.js",
+      "require": "./dist/pm/html-string/index.cjs"
+    },
+    "./pm/markdown": {
+      "types": {
+        "import": "./dist/pm/markdown/index.d.ts",
+        "require": "./dist/pm/markdown/index.d.cts"
+      },
+      "import": "./dist/pm/markdown/index.js",
+      "require": "./dist/pm/markdown/index.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "devDependencies": {
+    "@tiptap/core": "^3.0.0-beta.0",
+    "@tiptap/pm": "^3.0.0-beta.0",
+    "@types/react": "^18.2.14",
+    "@types/react-dom": "^18.2.6",
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "peerDependencies": {
+    "@tiptap/core": "^3.0.0-beta.0",
+    "@tiptap/pm": "^3.0.0-beta.0"
+  },
+  "optionalDependencies": {
+    "@types/react": "^18.2.14",
+    "@types/react-dom": "^18.2.6",
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ueberdosis/tiptap",
+    "directory": "packages/static-renderer"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "prettier ./src/ --check && eslint --cache --quiet --no-error-on-unmatched-pattern ./src/"
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,54 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { type ExtensionAttribute, type MarkType, type NodeType, mergeAttributes } from '@tiptap/core'
+
+/**
+ * This function returns the attributes of a node or mark that are defined by the given extension attributes.
+ * @param nodeOrMark The node or mark to get the attributes from
+ * @param extensionAttributes The extension attributes to use
+ * @param onlyRenderedAttributes If true, only attributes that are rendered in the HTML are returned
+ */
+export function getAttributes(
+  nodeOrMark: NodeType | MarkType,
+  extensionAttributes: ExtensionAttribute[],
+  onlyRenderedAttributes?: boolean,
+): Record<string, any> {
+  const nodeOrMarkAttributes = nodeOrMark.attrs
+
+  if (!nodeOrMarkAttributes) {
+    return {}
+  }
+
+  return extensionAttributes
+    .filter(item => {
+      if (item.type !== (typeof nodeOrMark.type === 'string' ? nodeOrMark.type : nodeOrMark.type.name)) {
+        return false
+      }
+      if (onlyRenderedAttributes) {
+        return item.attribute.rendered
+      }
+      return true
+    })
+    .map(item => {
+      if (!item.attribute.renderHTML) {
+        return {
+          [item.name]: item.name in nodeOrMarkAttributes ? nodeOrMarkAttributes[item.name] : item.attribute.default,
+        }
+      }
+
+      return (
+        item.attribute.renderHTML(nodeOrMarkAttributes) || {
+          [item.name]: item.name in nodeOrMarkAttributes ? nodeOrMarkAttributes[item.name] : item.attribute.default,
+        }
+      )
+    })
+    .reduce((attributes, attribute) => mergeAttributes(attributes, attribute), {})
+}
+
+/**
+ * This function returns the HTML attributes of a node or mark that are defined by the given extension attributes.
+ * @param nodeOrMark The node or mark to get the attributes from
+ * @param extensionAttributes The extension attributes to use
+ */
+export function getHTMLAttributes(nodeOrMark: NodeType | MarkType, extensionAttributes: ExtensionAttribute[]) {
+  return getAttributes(nodeOrMark, extensionAttributes, true)
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './helpers.js'
+export * from './json/html-string/index.js'
+export * from './json/react/index.js'
+export * from './pm/html-string/index.js'
+export * from './pm/markdown/index.js'
+export * from './pm/react/index.js'

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

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

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

@@ -0,0 +1,49 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { MarkType, NodeType } from '@tiptap/core'
+
+import type { TiptapStaticRendererOptions } from '../renderer.js'
+import { TiptapStaticRenderer } 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)
+}
+
+/**
+ * Serialize the attributes of a node or mark to a string
+ * @param attrs The attributes to serialize
+ * @returns The serialized attributes as a string
+ */
+export function serializeAttrsToHTMLString(attrs: Record<string, any> | undefined | null): string {
+  const output = Object.entries(attrs || {})
+    .map(([key, value]) => `${key.split(' ').at(-1)}=${JSON.stringify(value)}`)
+    .join(' ')
+
+  return output ? ` ${output}` : ''
+}
+
+/**
+ * Serialize the children of a node or mark to a string
+ * @param children The children to serialize
+ * @returns The serialized children as a string
+ */
+export function serializeChildrenToHTMLString(children?: string | string[]): string {
+  return ([] as string[])
+    .concat(children || '')
+    .filter(Boolean)
+    .join('')
+}

package/src/json/react/index.ts

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

package/src/json/react/react.ts

@@ -0,0 +1,33 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { MarkType, NodeType } from '@tiptap/core'
+import React from 'react'
+
+import type { TiptapStaticRendererOptions } from '../renderer.js'
+import { TiptapStaticRenderer } 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,241 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { MarkType, NodeType } from '@tiptap/core'
+
+/**
+ * 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, NoInfer<TNodeRender>>
+  /**
+   * Mapping of mark types to react components
+   */
+  markMapping: Record<string, NoInfer<TMarkRender>>
+  /**
+   * Component to render if a node type is not handled
+   */
+  unhandledNode?: NoInfer<TNodeRender>
+  /**
+   * Component to render if a mark type is not handled
+   */
+  unhandledMark?: NoInfer<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
+  }
+}