@tiptap/core 2.3.2 → 2.5.0-beta.0

package/src/ExtensionManager.ts

@@ -13,8 +13,8 @@ import { getSchemaTypeByName } from './helpers/getSchemaTypeByName.js'
 import { isExtensionRulesEnabled } from './helpers/isExtensionRulesEnabled.js'
 import { splitExtensions } from './helpers/splitExtensions.js'
 import { Mark, NodeConfig } from './index.js'
-import { inputRulesPlugin } from './InputRule.js'
-import { pasteRulesPlugin } from './PasteRule.js'
+import { InputRule, inputRulesPlugin } from './InputRule.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'
@@ -32,89 +32,15 @@ export class ExtensionManager {
     this.editor = editor
     this.extensions = ExtensionManager.resolve(extensions)
     this.schema = getSchemaByResolvedExtensions(this.extensions, editor)
-
-    this.extensions.forEach(extension => {
-      // store extension storage in editor
-      this.editor.extensionStorage[extension.name] = extension.storage
-
-      const context = {
-        name: extension.name,
-        options: extension.options,
-        storage: extension.storage,
-        editor: this.editor,
-        type: getSchemaTypeByName(extension.name, this.schema),
-      }
-
-      if (extension.type === 'mark') {
-        const keepOnSplit = callOrReturn(getExtensionField(extension, 'keepOnSplit', context)) ?? true
-
-        if (keepOnSplit) {
-          this.splittableMarks.push(extension.name)
-        }
-      }
-
-      const onBeforeCreate = getExtensionField<AnyConfig['onBeforeCreate']>(
-        extension,
-        'onBeforeCreate',
-        context,
-      )
-
-      if (onBeforeCreate) {
-        this.editor.on('beforeCreate', onBeforeCreate)
-      }
-
-      const onCreate = getExtensionField<AnyConfig['onCreate']>(extension, 'onCreate', context)
-
-      if (onCreate) {
-        this.editor.on('create', onCreate)
-      }
-
-      const onUpdate = getExtensionField<AnyConfig['onUpdate']>(extension, 'onUpdate', context)
-
-      if (onUpdate) {
-        this.editor.on('update', onUpdate)
-      }
-
-      const onSelectionUpdate = getExtensionField<AnyConfig['onSelectionUpdate']>(
-        extension,
-        'onSelectionUpdate',
-        context,
-      )
-
-      if (onSelectionUpdate) {
-        this.editor.on('selectionUpdate', onSelectionUpdate)
-      }
-
-      const onTransaction = getExtensionField<AnyConfig['onTransaction']>(
-        extension,
-        'onTransaction',
-        context,
-      )
-
-      if (onTransaction) {
-        this.editor.on('transaction', onTransaction)
-      }
-
-      const onFocus = getExtensionField<AnyConfig['onFocus']>(extension, 'onFocus', context)
-
-      if (onFocus) {
-        this.editor.on('focus', onFocus)
-      }
-
-      const onBlur = getExtensionField<AnyConfig['onBlur']>(extension, 'onBlur', context)
-
-      if (onBlur) {
-        this.editor.on('blur', onBlur)
-      }
-
-      const onDestroy = getExtensionField<AnyConfig['onDestroy']>(extension, 'onDestroy', context)
-
-      if (onDestroy) {
-        this.editor.on('destroy', onDestroy)
-      }
-    })
+    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))
@@ -130,6 +56,11 @@ export class ExtensionManager {
     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
@@ -157,6 +88,11 @@ export class ExtensionManager {
     )
   }
 
+  /**
+   * 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
 
@@ -176,6 +112,10 @@ export class ExtensionManager {
     })
   }
 
+  /**
+   * Get all commands from the extensions.
+   * @returns An object with all commands where the key is the command name and the value is the command function
+   */
   get commands(): RawCommands {
     return this.extensions.reduce((commands, extension) => {
       const context = {
@@ -203,6 +143,10 @@ export class ExtensionManager {
     }, {} as RawCommands)
   }
 
+  /**
+   * Get all registered Prosemirror plugins from the extensions.
+   * @returns An array of Prosemirror plugins
+   */
   get plugins(): Plugin[] {
     const { editor } = this
 
@@ -213,8 +157,8 @@ export class ExtensionManager {
     // based on the `priority` option.
     const extensions = ExtensionManager.sort([...this.extensions].reverse())
 
-    const inputRules: any[] = []
-    const pasteRules: any[] = []
+    const inputRules: InputRule[] = []
+    const pasteRules: PasteRule[] = []
 
     const allPlugins = extensions
       .map(extension => {
@@ -304,10 +248,18 @@ export class ExtensionManager {
     ]
   }
 
+  /**
+   * Get all attributes from the extensions.
+   * @returns An array of attributes
+   */
   get attributes() {
     return getAttributesFromExtensions(this.extensions)
   }
 
+  /**
+   * Get all node views from the extensions.
+   * @returns An object with all node views where the key is the node name and the value is the node view function
+   */
   get nodeViews() {
     const { editor } = this
     const { nodeExtensions } = splitExtensions(this.extensions)
@@ -358,4 +310,84 @@ export class ExtensionManager {
         }),
     )
   }
+
+  /**
+   * Go through all extensions, create extension storages & setup marks
+   * & bind editor event listener.
+   */
+  private setupExtensions() {
+    this.extensions.forEach(extension => {
+      // store extension storage in editor
+      this.editor.extensionStorage[extension.name] = extension.storage
+
+      const context = {
+        name: extension.name,
+        options: extension.options,
+        storage: extension.storage,
+        editor: this.editor,
+        type: getSchemaTypeByName(extension.name, this.schema),
+      }
+
+      if (extension.type === 'mark') {
+        const keepOnSplit = callOrReturn(getExtensionField(extension, 'keepOnSplit', context)) ?? true
+
+        if (keepOnSplit) {
+          this.splittableMarks.push(extension.name)
+        }
+      }
+
+      const onBeforeCreate = getExtensionField<AnyConfig['onBeforeCreate']>(
+        extension,
+        'onBeforeCreate',
+        context,
+      )
+      const onCreate = getExtensionField<AnyConfig['onCreate']>(extension, 'onCreate', context)
+      const onUpdate = getExtensionField<AnyConfig['onUpdate']>(extension, 'onUpdate', context)
+      const onSelectionUpdate = getExtensionField<AnyConfig['onSelectionUpdate']>(
+        extension,
+        'onSelectionUpdate',
+        context,
+      )
+      const onTransaction = getExtensionField<AnyConfig['onTransaction']>(
+        extension,
+        'onTransaction',
+        context,
+      )
+      const onFocus = getExtensionField<AnyConfig['onFocus']>(extension, 'onFocus', context)
+      const onBlur = getExtensionField<AnyConfig['onBlur']>(extension, 'onBlur', context)
+      const onDestroy = getExtensionField<AnyConfig['onDestroy']>(extension, 'onDestroy', context)
+
+      if (onBeforeCreate) {
+        this.editor.on('beforeCreate', onBeforeCreate)
+      }
+
+      if (onCreate) {
+        this.editor.on('create', onCreate)
+      }
+
+      if (onUpdate) {
+        this.editor.on('update', onUpdate)
+      }
+
+      if (onSelectionUpdate) {
+        this.editor.on('selectionUpdate', onSelectionUpdate)
+      }
+
+      if (onTransaction) {
+        this.editor.on('transaction', onTransaction)
+      }
+
+      if (onFocus) {
+        this.editor.on('focus', onFocus)
+      }
+
+      if (onBlur) {
+        this.editor.on('blur', onBlur)
+      }
+
+      if (onDestroy) {
+        this.editor.on('destroy', onDestroy)
+      }
+    })
+  }
 }

package/src/Mark.ts

@@ -26,22 +26,40 @@ declare module '@tiptap/core' {
     [key: string]: any
 
     /**
-     * Name
+     * The extension name - this must be unique.
+     * It will be used to identify the extension.
+     *
+     * @example 'myExtension'
      */
     name: string
 
     /**
-     * Priority
+     * The priority of your extension. The higher, the later it will be called
+     * and will take precedence over other extensions with a lower priority.
+     * @default 1000
+     * @example 1001
      */
     priority?: number
 
     /**
-     * Default options
+     * The default options for this extension.
+     * @example
+     * defaultOptions: {
+     *   myOption: 'foo',
+     *   myOtherOption: 10,
+     * }
      */
     defaultOptions?: Options
 
     /**
-     * Default Options
+     * This method will add options to this extension
+     * @see https://tiptap.dev/guide/custom-extensions#settings
+     * @example
+     * addOptions() {
+     *  return {
+     *    myOption: 'foo',
+     *    myOtherOption: 10,
+     * }
      */
     addOptions?: (this: {
       name: string
@@ -49,7 +67,13 @@ declare module '@tiptap/core' {
     }) => Options
 
     /**
-     * Default Storage
+     * The default storage this extension can save data to.
+     * @see https://tiptap.dev/guide/custom-extensions#storage
+     * @example
+     * defaultStorage: {
+     *   prefetchedUsers: [],
+     *   loading: false,
+     * }
      */
     addStorage?: (this: {
       name: string
@@ -58,7 +82,30 @@ declare module '@tiptap/core' {
     }) => Storage
 
     /**
-     * Global attributes
+     * This function adds globalAttributes to specific nodes.
+     * @see https://tiptap.dev/guide/custom-extensions#global-attributes
+     * @example
+     * addGlobalAttributes() {
+     *   return [
+     *     {
+             // Extend the following extensions
+     *       types: [
+     *         'heading',
+     *         'paragraph',
+     *       ],
+     *       // … with those attributes
+     *       attributes: {
+     *         textAlign: {
+     *           default: 'left',
+     *           renderHTML: attributes => ({
+     *             style: `text-align: ${attributes.textAlign}`,
+     *           }),
+     *           parseHTML: element => element.style.textAlign || 'left',
+     *         },
+     *       },
+     *     },
+     *   ]
+     * }
      */
     addGlobalAttributes?: (this: {
       name: string
@@ -68,7 +115,14 @@ declare module '@tiptap/core' {
     }) => GlobalAttributes | {}
 
     /**
-     * Raw
+     * This function adds commands to the editor
+     * @see https://tiptap.dev/guide/custom-extensions#keyboard-shortcuts
+     * @example
+     * addCommands() {
+     *   return {
+     *     myCommand: () => ({ chain }) => chain().setMark('type', 'foo').run(),
+     *   }
+     * }
      */
     addCommands?: (this: {
       name: string
@@ -80,7 +134,14 @@ declare module '@tiptap/core' {
     }) => Partial<RawCommands>
 
     /**
-     * Keyboard shortcuts
+     * This function registers keyboard shortcuts.
+     * @see https://tiptap.dev/guide/custom-extensions#keyboard-shortcuts
+     * @example
+     * addKeyboardShortcuts() {
+     *   return {
+     *     'Mod-l': () => this.editor.commands.toggleBulletList(),
+     *   }
+     * },
      */
     addKeyboardShortcuts?: (this: {
       name: string
@@ -94,7 +155,17 @@ declare module '@tiptap/core' {
     }
 
     /**
-     * Input rules
+     * This function adds input rules to the editor.
+     * @see https://tiptap.dev/guide/custom-extensions#input-rules
+     * @example
+     * addInputRules() {
+     *   return [
+     *     markInputRule({
+     *       find: inputRegex,
+     *       type: this.type,
+     *     }),
+     *   ]
+     * },
      */
     addInputRules?: (this: {
       name: string
@@ -106,7 +177,17 @@ declare module '@tiptap/core' {
     }) => InputRule[]
 
     /**
-     * Paste rules
+     * This function adds paste rules to the editor.
+     * @see https://tiptap.dev/guide/custom-extensions#paste-rules
+     * @example
+     * addPasteRules() {
+     *   return [
+     *     markPasteRule({
+     *       find: pasteRegex,
+     *       type: this.type,
+     *     }),
+     *   ]
+     * },
      */
     addPasteRules?: (this: {
       name: string
@@ -118,7 +199,14 @@ declare module '@tiptap/core' {
     }) => PasteRule[]
 
     /**
-     * ProseMirror plugins
+     * This function adds Prosemirror plugins to the editor
+     * @see https://tiptap.dev/guide/custom-extensions#prosemirror-plugins
+     * @example
+     * addProseMirrorPlugins() {
+     *   return [
+     *     customPlugin(),
+     *   ]
+     * }
      */
     addProseMirrorPlugins?: (this: {
       name: string
@@ -130,7 +218,16 @@ declare module '@tiptap/core' {
     }) => Plugin[]
 
     /**
-     * Extensions
+     * This function adds additional extensions to the editor. This is useful for
+     * building extension kits.
+     * @example
+     * addExtensions() {
+     *   return [
+     *     BulletList,
+     *     OrderedList,
+     *     ListItem
+     *   ]
+     * }
      */
     addExtensions?: (this: {
       name: string
@@ -140,7 +237,14 @@ declare module '@tiptap/core' {
     }) => Extensions
 
     /**
-     * Extend Node Schema
+     * This function extends the schema of the node.
+     * @example
+     * extendNodeSchema() {
+     *   return {
+     *     group: 'inline',
+     *     selectable: false,
+     *   }
+     * }
      */
     extendNodeSchema?:
       | ((
@@ -155,7 +259,14 @@ declare module '@tiptap/core' {
       | null
 
     /**
-     * Extend Mark Schema
+     * This function extends the schema of the mark.
+     * @example
+     * extendMarkSchema() {
+     *   return {
+     *     group: 'inline',
+     *     selectable: false,
+     *   }
+     * }
      */
     extendMarkSchema?:
       | ((
@@ -414,6 +525,10 @@ declare module '@tiptap/core' {
   }
 }
 
+/**
+ * The Mark class is used to create custom mark extensions.
+ * @see https://tiptap.dev/api/extensions#create-a-new-extension
+ */
 export class Mark<Options = any, Storage = any> {
   type = 'mark'