feat(static-renderer): add @tiptap/static-renderer to enable static rendering of content

.github/workflows/build.yml

@@ -101,7 +101,7 @@ jobs:
 
       - name: Try to build the packages
         id: build-packages
-        run: npm run build:pm
+        run: npm run build
 
       - name: Test ${{ matrix.test-spec.name }}
         id: cypress

packages/core/src/Editor.ts

@@ -30,11 +30,13 @@ import { style } from './style.js'
 import {
   CanCommands,
   ChainedCommands,
+  DocumentType,
   EditorEvents,
   EditorOptions,
-  JSONContent,
+  NodeType as TNodeType,
   SingleCommands,
   TextSerializer,
+  TextType as TTextType,
 } from './types.js'
 import { createStyleTag } from './utilities/createStyleTag.js'
 import { isFunction } from './utilities/isFunction.js'
@@ -533,7 +535,10 @@ export class Editor extends EventEmitter<EditorEvents> {
   /**
    * Get the document as JSON.
    */
-  public getJSON(): JSONContent {
+  public getJSON(): DocumentType<
+  Record<string, any> | undefined,
+  TNodeType<string, undefined | Record<string, any>, any, (TNodeType | TTextType)[]>[]
+  > {
     return this.state.doc.toJSON()
   }
 

packages/core/src/ExtensionManager.ts

@@ -4,21 +4,24 @@ import { Plugin } from '@tiptap/pm/state'
 import { NodeViewConstructor } from '@tiptap/pm/view'
 
 import type { Editor } from './Editor.js'
-import { getAttributesFromExtensions } from './helpers/getAttributesFromExtensions.js'
-import { getExtensionField } from './helpers/getExtensionField.js'
-import { getNodeType } from './helpers/getNodeType.js'
-import { getRenderedAttributes } from './helpers/getRenderedAttributes.js'
-import { getSchemaByResolvedExtensions } from './helpers/getSchemaByResolvedExtensions.js'
-import { getSchemaTypeByName } from './helpers/getSchemaTypeByName.js'
-import { isExtensionRulesEnabled } from './helpers/isExtensionRulesEnabled.js'
-import { splitExtensions } from './helpers/splitExtensions.js'
+import {
+  flattenExtensions, getAttributesFromExtensions,
+  getExtensionField,
+  getNodeType,
+  getRenderedAttributes,
+  getSchemaByResolvedExtensions,
+  getSchemaTypeByName,
+  isExtensionRulesEnabled,
+  resolveExtensions,
+  sortExtensions,
+  splitExtensions,
+} from './helpers/index.js'
 import type { NodeConfig } from './index.js'
 import { InputRule, inputRulesPlugin } from './InputRule.js'
 import { Mark } from './Mark.js'
 import { PasteRule, pasteRulesPlugin } from './PasteRule.js'
 import { AnyConfig, Extensions, RawCommands } from './types.js'
 import { callOrReturn } from './utilities/callOrReturn.js'
-import { findDuplicates } from './utilities/findDuplicates.js'
 
 export class ExtensionManager {
   editor: Editor
@@ -31,87 +34,16 @@ export class ExtensionManager {
 
   constructor(extensions: Extensions, editor: Editor) {
     this.editor = editor
-    this.extensions = ExtensionManager.resolve(extensions)
+    this.extensions = resolveExtensions(extensions)
     this.schema = getSchemaByResolvedExtensions(this.extensions, editor)
     this.setupExtensions()
   }
 
-  /**
-   * Returns a flattened and sorted extension list while
-   * also checking for duplicated extensions and warns the user.
-   * @param extensions An array of Tiptap extensions
-   * @returns An flattened and sorted array of Tiptap extensions
-   */
-  static resolve(extensions: Extensions): Extensions {
-    const resolvedExtensions = ExtensionManager.sort(ExtensionManager.flatten(extensions))
-    const duplicatedNames = findDuplicates(resolvedExtensions.map(extension => extension.name))
-
-    if (duplicatedNames.length) {
-      console.warn(
-        `[tiptap warn]: Duplicate extension names found: [${duplicatedNames
-          .map(item => `'${item}'`)
-          .join(', ')}]. This can lead to issues.`,
-      )
-    }
-
-    return resolvedExtensions
-  }
-
-  /**
-   * Create a flattened array of extensions by traversing the `addExtensions` field.
-   * @param extensions An array of Tiptap extensions
-   * @returns A flattened array of Tiptap extensions
-   */
-  static flatten(extensions: Extensions): Extensions {
-    return (
-      extensions
-        .map(extension => {
-          const context = {
-            name: extension.name,
-            options: extension.options,
-            storage: extension.storage,
-          }
-
-          const addExtensions = getExtensionField<AnyConfig['addExtensions']>(
-            extension,
-            'addExtensions',
-            context,
-          )
-
-          if (addExtensions) {
-            return [extension, ...this.flatten(addExtensions())]
-          }
-
-          return extension
-        })
-        // `Infinity` will break TypeScript so we set a number that is probably high enough
-        .flat(10)
-    )
-  }
-
-  /**
-   * Sort extensions by priority.
-   * @param extensions An array of Tiptap extensions
-   * @returns A sorted array of Tiptap extensions by priority
-   */
-  static sort(extensions: Extensions): Extensions {
-    const defaultPriority = 100
-
-    return extensions.sort((a, b) => {
-      const priorityA = getExtensionField<AnyConfig['priority']>(a, 'priority') || defaultPriority
-      const priorityB = getExtensionField<AnyConfig['priority']>(b, 'priority') || defaultPriority
-
-      if (priorityA > priorityB) {
-        return -1
-      }
+  static resolve = resolveExtensions
 
-      if (priorityA < priorityB) {
-        return 1
-      }
+  static sort = sortExtensions
 
-      return 0
-    })
-  }
+  static flatten = flattenExtensions
 
   /**
    * Get all commands from the extensions.
@@ -156,7 +88,7 @@ export class ExtensionManager {
     // so it feels more natural to run plugins at the end of an array first.
     // That’s why we have to reverse the `extensions` array and sort again
     // based on the `priority` option.
-    const extensions = ExtensionManager.sort([...this.extensions].reverse())
+    const extensions = sortExtensions([...this.extensions].reverse())
 
     const inputRules: InputRule[] = []
     const pasteRules: PasteRule[] = []

packages/core/src/helpers/flattenExtensions.ts

@@ -0,0 +1,34 @@
+import { AnyConfig, Extensions } from '../types.js'
+import { getExtensionField } from './getExtensionField.js'
+
+/**
+ * Create a flattened array of extensions by traversing the `addExtensions` field.
+ * @param extensions An array of Tiptap extensions
+ * @returns A flattened array of Tiptap extensions
+ */
+export function flattenExtensions(extensions: Extensions): Extensions {
+  return (
+    extensions
+      .map(extension => {
+        const context = {
+          name: extension.name,
+          options: extension.options,
+          storage: extension.storage,
+        }
+
+        const addExtensions = getExtensionField<AnyConfig['addExtensions']>(
+          extension,
+          'addExtensions',
+          context,
+        )
+
+        if (addExtensions) {
+          return [extension, ...flattenExtensions(addExtensions())]
+        }
+
+        return extension
+      })
+      // `Infinity` will break TypeScript so we set a number that is probably high enough
+      .flat(10)
+  )
+}

packages/core/src/helpers/getSchema.ts

@@ -1,12 +1,12 @@
 import { Schema } from '@tiptap/pm/model'
 
 import { Editor } from '../Editor.js'
-import { ExtensionManager } from '../ExtensionManager.js'
 import { Extensions } from '../types.js'
 import { getSchemaByResolvedExtensions } from './getSchemaByResolvedExtensions.js'
+import { resolveExtensions } from './resolveExtensions.js'
 
 export function getSchema(extensions: Extensions, editor?: Editor): Schema {
-  const resolvedExtensions = ExtensionManager.resolve(extensions)
+  const resolvedExtensions = resolveExtensions(extensions)
 
   return getSchemaByResolvedExtensions(resolvedExtensions, editor)
 }

packages/core/src/helpers/index.ts

@@ -7,6 +7,7 @@ export * from './findChildren.js'
 export * from './findChildrenInRange.js'
 export * from './findParentNode.js'
 export * from './findParentNodeClosestToPos.js'
+export * from './flattenExtensions.js'
 export * from './generateHTML.js'
 export * from './generateJSON.js'
 export * from './generateText.js'
@@ -45,7 +46,9 @@ export * from './isNodeEmpty.js'
 export * from './isNodeSelection.js'
 export * from './isTextSelection.js'
 export * from './posToDOMRect.js'
+export * from './resolveExtensions.js'
 export * from './resolveFocusPosition.js'
 export * from './rewriteUnknownContent.js'
 export * from './selectionToInsertionEnd.js'
+export * from './sortExtensions.js'
 export * from './splitExtensions.js'

packages/core/src/helpers/resolveExtensions.ts

@@ -0,0 +1,25 @@
+import { Extensions } from '../types.js'
+import { findDuplicates } from '../utilities/findDuplicates.js'
+import { flattenExtensions } from './flattenExtensions.js'
+import { sortExtensions } from './sortExtensions.js'
+
+/**
+ * Returns a flattened and sorted extension list while
+ * also checking for duplicated extensions and warns the user.
+ * @param extensions An array of Tiptap extensions
+ * @returns An flattened and sorted array of Tiptap extensions
+ */
+export function resolveExtensions(extensions: Extensions): Extensions {
+  const resolvedExtensions = sortExtensions(flattenExtensions(extensions))
+  const duplicatedNames = findDuplicates(resolvedExtensions.map(extension => extension.name))
+
+  if (duplicatedNames.length) {
+    console.warn(
+      `[tiptap warn]: Duplicate extension names found: [${duplicatedNames
+        .map(item => `'${item}'`)
+        .join(', ')}]. This can lead to issues.`,
+    )
+  }
+
+  return resolvedExtensions
+}

packages/core/src/helpers/sortExtensions.ts

@@ -0,0 +1,26 @@
+import { AnyConfig, Extensions } from '../types.js'
+import { getExtensionField } from './getExtensionField.js'
+
+/**
+ * Sort extensions by priority.
+ * @param extensions An array of Tiptap extensions
+ * @returns A sorted array of Tiptap extensions by priority
+ */
+export function sortExtensions(extensions: Extensions): Extensions {
+  const defaultPriority = 100
+
+  return extensions.sort((a, b) => {
+    const priorityA = getExtensionField<AnyConfig['priority']>(a, 'priority') || defaultPriority
+    const priorityB = getExtensionField<AnyConfig['priority']>(b, 'priority') || defaultPriority
+
+    if (priorityA > priorityB) {
+      return -1
+    }
+
+    if (priorityA < priorityB) {
+      return 1
+    }
+
+    return 0
+  })
+}

packages/core/src/types.ts

@@ -159,6 +159,61 @@ export type JSONContent = {
   [key: string]: any;
 };
 
+/**
+ * A mark type is either a JSON representation of a mark or a Prosemirror mark instance
+ */
+export type MarkType<
+  Type extends string | { name: string } = any,
+  Attributes extends undefined | Record<string, any> = any,
+> = {
+  type: Type;
+  attrs: Attributes;
+};
+
+/**
+ * A node type is either a JSON representation of a node or a Prosemirror node instance
+ */
+export type NodeType<
+  Type extends string | { name: string } = any,
+  Attributes extends undefined | Record<string, any> = any,
+  NodeMarkType extends MarkType = any,
+  Content extends (NodeType | TextType)[] = any,
+> = {
+  type: Type;
+  attrs: Attributes;
+  content?: Content;
+  marks?: NodeMarkType[];
+};
+
+/**
+ * A node type is either a JSON representation of a doc node or a Prosemirror doc node instance
+ */
+export type DocumentType<
+  TDocAttributes extends Record<string, any> | undefined = Record<string, any>,
+  TContentType extends NodeType[] = NodeType[],
+> = Omit<NodeType<'doc', TDocAttributes, never, TContentType>, 'marks' | 'content'> & {content: TContentType};
+
+/**
+ * A node type is either a JSON representation of a text node or a Prosemirror text node instance
+ */
+export type TextType<TMarkType extends MarkType = MarkType> = {
+  type: 'text';
+  text: string;
+  marks: TMarkType[];
+};
+
+/**
+ * Describes the output of a `renderHTML` function in prosemirror
+ * @see https://prosemirror.net/docs/ref/#model.DOMOutputSpec
+ */
+export type DOMOutputSpecArray =
+  | [string]
+  | [string, Record<string, any>]
+  | [string, 0]
+  | [string, Record<string, any>, 0]
+  | [string, Record<string, any>, DOMOutputSpecArray | 0]
+  | [string, DOMOutputSpecArray];
+
 export type Content = HTMLContent | JSONContent | JSONContent[] | null;
 
 export type CommandProps = {