@tiptap/core 2.3.2 → 2.4.0

package/dist/index.umd.js

@@ -4,6 +4,11 @@
   (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["@tiptap/core"] = {}, global.state, global.view, global.keymap, global.model, global.transform, global.commands$1, global.schemaList));
 })(this, (function (exports, state, view, keymap, model, transform, commands$1, schemaList) { 'use strict';
 
+  /**
+   * Takes a Transaction & Editor State and turns it into a chainable state object
+   * @param config The transaction and state to create the chainable state from
+   * @returns A chainable Editor state object
+   */
   function createChainableState(config) {
       const { state, transaction } = config;
       let { selection } = transaction;
@@ -170,6 +175,13 @@
       }
   }
 
+  /**
+   * Returns a field from an extension
+   * @param extension The Tiptap extension
+   * @param field The field, for example `renderHTML` or `priority`
+   * @param context The context object that should be passed as `this` into the function
+   * @returns The field value
+   */
   function getExtensionField(extension, field, context) {
       if (extension.config[field] === undefined && extension.parent) {
           return getExtensionField(extension.parent, field, context);
@@ -414,6 +426,12 @@
           return value !== null && value !== undefined;
       }));
   }
+  /**
+   * Creates a new Prosemirror schema based on the given extensions.
+   * @param extensions An array of Tiptap extensions
+   * @param editor The editor instance
+   * @returns A Prosemirror schema
+   */
   function getSchemaByResolvedExtensions(extensions, editor) {
       var _a;
       const allAttributes = getAttributesFromExtensions(extensions);
@@ -515,6 +533,12 @@
       });
   }
 
+  /**
+   * Tries to get a node or mark type by its name.
+   * @param name The name of the node or mark type
+   * @param schema The Prosemiror schema to search in
+   * @returns The node or mark type, or null if it doesn't exist
+   */
   function getSchemaTypeByName(name, schema) {
       return schema.nodes[name] || schema.marks[name] || null;
   }
@@ -531,6 +555,12 @@
       return enabled;
   }
 
+  /**
+   * Returns the text content of a resolved prosemirror position
+   * @param $from The resolved position to get the text content from
+   * @param maxMatch The maximum number of characters to match
+   * @returns The text content
+   */
   const getTextContentFromNodes = ($from, maxMatch = 500) => {
       let textBefore = '';
       const sliceEndPos = $from.parentOffset;
@@ -738,6 +768,10 @@
       return typeof value === 'number';
   }
 
+  /**
+   * Paste rules are used to react to pasted content.
+   * @see https://tiptap.dev/guide/custom-extensions/#paste-rules
+   */
   class PasteRule {
       constructor(config) {
           this.find = config.find;
@@ -936,57 +970,14 @@
           this.editor = editor;
           this.extensions = ExtensionManager.resolve(extensions);
           this.schema = getSchemaByResolvedExtensions(this.extensions, editor);
-          this.extensions.forEach(extension => {
-              var _a;
-              // 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 = (_a = callOrReturn(getExtensionField(extension, 'keepOnSplit', context))) !== null && _a !== void 0 ? _a : true;
-                  if (keepOnSplit) {
-                      this.splittableMarks.push(extension.name);
-                  }
-              }
-              const onBeforeCreate = getExtensionField(extension, 'onBeforeCreate', context);
-              if (onBeforeCreate) {
-                  this.editor.on('beforeCreate', onBeforeCreate);
-              }
-              const onCreate = getExtensionField(extension, 'onCreate', context);
-              if (onCreate) {
-                  this.editor.on('create', onCreate);
-              }
-              const onUpdate = getExtensionField(extension, 'onUpdate', context);
-              if (onUpdate) {
-                  this.editor.on('update', onUpdate);
-              }
-              const onSelectionUpdate = getExtensionField(extension, 'onSelectionUpdate', context);
-              if (onSelectionUpdate) {
-                  this.editor.on('selectionUpdate', onSelectionUpdate);
-              }
-              const onTransaction = getExtensionField(extension, 'onTransaction', context);
-              if (onTransaction) {
-                  this.editor.on('transaction', onTransaction);
-              }
-              const onFocus = getExtensionField(extension, 'onFocus', context);
-              if (onFocus) {
-                  this.editor.on('focus', onFocus);
-              }
-              const onBlur = getExtensionField(extension, 'onBlur', context);
-              if (onBlur) {
-                  this.editor.on('blur', onBlur);
-              }
-              const onDestroy = getExtensionField(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) {
           const resolvedExtensions = ExtensionManager.sort(ExtensionManager.flatten(extensions));
           const duplicatedNames = findDuplicates(resolvedExtensions.map(extension => extension.name));
@@ -997,6 +988,11 @@
           }
           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) {
           return (extensions
               .map(extension => {
@@ -1014,6 +1010,11 @@
               // `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) {
           const defaultPriority = 100;
           return extensions.sort((a, b) => {
@@ -1028,6 +1029,10 @@
               return 0;
           });
       }
+      /**
+       * 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() {
           return this.extensions.reduce((commands, extension) => {
               const context = {
@@ -1047,6 +1052,10 @@
               };
           }, {});
       }
+      /**
+       * Get all registered Prosemirror plugins from the extensions.
+       * @returns An array of Prosemirror plugins
+       */
       get plugins() {
           const { editor } = this;
           // With ProseMirror, first plugins within an array are executed first.
@@ -1109,9 +1118,17 @@
               ...allPlugins,
           ];
       }
+      /**
+       * 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);
@@ -1144,6 +1161,62 @@
               return [extension.name, nodeview];
           }));
       }
+      /**
+       * Go through all extensions, create extension storages & setup marks
+       * & bind editor event listener.
+       */
+      setupExtensions() {
+          this.extensions.forEach(extension => {
+              var _a;
+              // 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 = (_a = callOrReturn(getExtensionField(extension, 'keepOnSplit', context))) !== null && _a !== void 0 ? _a : true;
+                  if (keepOnSplit) {
+                      this.splittableMarks.push(extension.name);
+                  }
+              }
+              const onBeforeCreate = getExtensionField(extension, 'onBeforeCreate', context);
+              const onCreate = getExtensionField(extension, 'onCreate', context);
+              const onUpdate = getExtensionField(extension, 'onUpdate', context);
+              const onSelectionUpdate = getExtensionField(extension, 'onSelectionUpdate', context);
+              const onTransaction = getExtensionField(extension, 'onTransaction', context);
+              const onFocus = getExtensionField(extension, 'onFocus', context);
+              const onBlur = getExtensionField(extension, 'onBlur', context);
+              const onDestroy = getExtensionField(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);
+              }
+          });
+      }
   }
 
   // see: https://github.com/mesqueeb/is-what/blob/88d6e4ca92fb2baab6003c54e02eedf4e729e5ab/src/index.ts
@@ -1177,6 +1250,10 @@
       return output;
   }
 
+  /**
+   * The Extension class is the base class for all extensions.
+   * @see https://tiptap.dev/api/extensions#create-a-new-extension
+   */
   class Extension {
       constructor(config = {}) {
           this.type = 'extension';
@@ -1214,6 +1291,7 @@
           // return a new instance so we can use the same extension
           // with different calls of `configure`
           const extension = this.extend();
+          extension.parent = this.parent;
           extension.options = mergeDeep(this.options, options);
           extension.storage = callOrReturn(getExtensionField(extension, 'addStorage', {
               name: extension.name,
@@ -1240,19 +1318,25 @@
       }
   }
 
+  /**
+   * Gets the text between two positions in a Prosemirror node
+   * and serializes it using the given text serializers and block separator (see getText)
+   * @param startNode The Prosemirror node to start from
+   * @param range The range of the text to get
+   * @param options Options for the text serializer & block separator
+   * @returns The text between the two positions
+   */
   function getTextBetween(startNode, range, options) {
       const { from, to } = range;
       const { blockSeparator = '\n\n', textSerializers = {} } = options || {};
       let text = '';
-      let separated = true;
       startNode.nodesBetween(from, to, (node, pos, parent, index) => {
           var _a;
+          if (node.isBlock && pos > from) {
+              text += blockSeparator;
+          }
           const textSerializer = textSerializers === null || textSerializers === void 0 ? void 0 : textSerializers[node.type.name];
           if (textSerializer) {
-              if (node.isBlock && !separated) {
-                  text += blockSeparator;
-                  separated = true;
-              }
               if (parent) {
                   text += textSerializer({
                       node,
@@ -1267,16 +1351,16 @@
           }
           if (node.isText) {
               text += (_a = node === null || node === void 0 ? void 0 : node.text) === null || _a === void 0 ? void 0 : _a.slice(Math.max(from, pos) - pos, to - pos); // eslint-disable-line
-              separated = false;
-          }
-          else if (node.isBlock && !separated) {
-              text += blockSeparator;
-              separated = true;
           }
       });
       return text;
   }
 
+  /**
+   * Find text serializers `toText` in a Prosemirror schema
+   * @param schema The Prosemirror schema to search in
+   * @returns A record of text serializers by node name
+   */
   function getTextSerializersFromSchema(schema) {
       return Object.fromEntries(Object.entries(schema.nodes)
           .filter(([, node]) => node.spec.toText)
@@ -1659,15 +1743,26 @@
       return removeWhitespaces(html);
   }
 
+  /**
+   * Takes a JSON or HTML content and creates a Prosemirror node or fragment from it.
+   * @param content The JSON or HTML content to create the node from
+   * @param schema The Prosemirror schema to use for the node
+   * @param options Options for the parser
+   * @returns The created Prosemirror node or fragment
+   */
   function createNodeFromContent(content, schema, options) {
       options = {
           slice: true,
           parseOptions: {},
           ...options,
       };
-      if (typeof content === 'object' && content !== null) {
+      const isJSONContent = typeof content === 'object' && content !== null;
+      const isTextContent = typeof content === 'string';
+      if (isJSONContent) {
           try {
-              if (Array.isArray(content) && content.length > 0) {
+              const isArrayContent = Array.isArray(content) && content.length > 0;
+              // if the JSON Content is an array of nodes, create a fragment for each node
+              if (isArrayContent) {
                   return model.Fragment.fromArray(content.map(item => schema.nodeFromJSON(item)));
               }
               return schema.nodeFromJSON(content);
@@ -1677,7 +1772,7 @@
               return createNodeFromContent('', schema, options);
           }
       }
-      if (typeof content === 'string') {
+      if (isTextContent) {
           const parser = model.DOMParser.fromSchema(schema);
           return options.slice
               ? parser.parseSlice(elementFromString(content), options.parseOptions).content
@@ -1977,6 +2072,12 @@
       return commands$1.newlineInCode(state, dispatch);
   };
 
+  /**
+   * Get the type of a schema item by its name.
+   * @param name The name of the schema item
+   * @param schema The Prosemiror schema to search in
+   * @returns The type of the schema item (`node` or `mark`), or null if it doesn't exist
+   */
   function getSchemaTypeNameByName(name, schema) {
       if (schema.nodes[name]) {
           return 'node';
@@ -2074,6 +2175,13 @@
       return commands$1.selectTextblockStart(state, dispatch);
   };
 
+  /**
+   * Create a new Prosemirror document node from content.
+   * @param content The JSON or HTML content to create the document from
+   * @param schema The Prosemirror schema to use for the document
+   * @param parseOptions Options for the parser
+   * @returns The created Prosemirror document node
+   */
   function createDocument(content, schema, parseOptions = {}) {
       return createNodeFromContent(content, schema, { slice: false, parseOptions });
   }
@@ -2111,6 +2219,9 @@
 
   /**
    * Returns a new `Transform` based on all steps of the passed transactions.
+   * @param oldDoc The Prosemirror node to start from
+   * @param transactions The transactions to combine
+   * @returns A new `Transform` with all steps of the passed transactions
    */
   function combineTransactionSteps(oldDoc, transactions) {
       const transform$1 = new transform.Transform(oldDoc);
@@ -2122,6 +2233,11 @@
       return transform$1;
   }
 
+  /**
+   * Gets the default block type at a given match
+   * @param match The content match to get the default block type from
+   * @returns The default block type or null
+   */
   function defaultBlockAt(match) {
       for (let i = 0; i < match.edgeCount; i += 1) {
           const { type } = match.edge(i);
@@ -2132,6 +2248,12 @@
       return null;
   }
 
+  /**
+   * Find children inside a Prosemirror node that match a predicate.
+   * @param node The Prosemirror node to search in
+   * @param predicate The predicate to match
+   * @returns An array of nodes with their positions
+   */
   function findChildren(node, predicate) {
       const nodesWithPos = [];
       node.descendants((child, pos) => {
@@ -2147,6 +2269,10 @@
 
   /**
    * Same as `findChildren` but searches only within a `range`.
+   * @param node The Prosemirror node to search in
+   * @param range The range to search in
+   * @param predicate The predicate to match
+   * @returns An array of nodes with their positions
    */
   function findChildrenInRange(node, range, predicate) {
       const nodesWithPos = [];
@@ -2170,6 +2296,15 @@
       return nodesWithPos;
   }
 
+  /**
+   * Finds the closest parent node to a resolved position that matches a predicate.
+   * @param $pos The resolved position to search from
+   * @param predicate The predicate to match
+   * @returns The closest parent node to the resolved position that matches the predicate
+   * @example ```js
+   * findParentNodeClosestToPos($from, node => node.type.name === 'paragraph')
+   * ```
+   */
   function findParentNodeClosestToPos($pos, predicate) {
       for (let i = $pos.depth; i > 0; i -= 1) {
           const node = $pos.node(i);
@@ -2184,6 +2319,14 @@
       }
   }
 
+  /**
+   * Finds the closest parent node to the current selection that matches a predicate.
+   * @param predicate The predicate to match
+   * @returns A command that finds the closest parent node to the current selection that matches the predicate
+   * @example ```js
+   * findParentNode(node => node.type.name === 'paragraph')
+   * ```
+   */
   function findParentNode(predicate) {
       return (selection) => findParentNodeClosestToPos(selection.$from, predicate);
   }
@@ -2201,18 +2344,39 @@
       return getSchemaByResolvedExtensions(resolvedExtensions, editor);
   }
 
+  /**
+   * Generate HTML from a JSONContent
+   * @param doc The JSONContent to generate HTML from
+   * @param extensions The extensions to use for the schema
+   * @returns The generated HTML
+   */
   function generateHTML(doc, extensions) {
       const schema = getSchema(extensions);
       const contentNode = model.Node.fromJSON(schema, doc);
       return getHTMLFromFragment(contentNode.content, schema);
   }
 
+  /**
+   * Generate JSONContent from HTML
+   * @param html The HTML to generate JSONContent from
+   * @param extensions The extensions to use for the schema
+   * @returns The generated JSONContent
+   */
   function generateJSON(html, extensions) {
       const schema = getSchema(extensions);
       const dom = elementFromString(html);
       return model.DOMParser.fromSchema(schema).parse(dom).toJSON();
   }
 
+  /**
+   * Gets the text of a Prosemirror node
+   * @param node The Prosemirror node
+   * @param options Options for the text serializer & block separator
+   * @returns The text of the node
+   * @example ```js
+   * const text = getText(node, { blockSeparator: '\n' })
+   * ```
+   */
   function getText(node, options) {
       const range = {
           from: 0,
@@ -2221,6 +2385,13 @@
       return getTextBetween(node, range, options);
   }
 
+  /**
+   * Generate raw text from a JSONContent
+   * @param doc The JSONContent to generate text from
+   * @param extensions The extensions to use for the schema
+   * @param options Options for the text generation f.e. blockSeparator or textSerializers
+   * @returns The generated text
+   */
   function generateText(doc, extensions, options) {
       const { blockSeparator = '\n\n', textSerializers = {} } = options || {};
       const schema = getSchema(extensions);
@@ -2248,6 +2419,12 @@
       return { ...node.attrs };
   }
 
+  /**
+   * Get node or mark attributes by type or name on the current editor state
+   * @param state The current editor state
+   * @param typeOrName The node or mark type or name
+   * @returns The attributes of the node or mark or an empty object
+   */
   function getAttributes(state, typeOrName) {
       const schemaType = getSchemaTypeNameByName(typeof typeOrName === 'string' ? typeOrName : typeOrName.name, state.schema);
       if (schemaType === 'node') {
@@ -2432,6 +2609,13 @@
       return [node, currentDepth];
   };
 
+  /**
+   * Return attributes of an extension that should be splitted by keepOnSplit flag
+   * @param extensionAttributes Array of extension attributes
+   * @param typeName The type of the extension
+   * @param attributes The attributes of the extension
+   * @returns The splitted attributes
+   */
   function getSplittedAttributes(extensionAttributes, typeName, attributes) {
       return Object.fromEntries(Object
           .entries(attributes)
@@ -3282,7 +3466,12 @@
                   const isAtStart = (parentIsIsolating && $parentPos.parent.childCount === 1)
                       ? parentPos === $anchor.pos
                       : state.Selection.atStart(doc).from === pos;
-                  if (!empty || !isAtStart || !parent.type.isTextblock || parent.textContent.length) {
+                  if (!empty
+                      || !parent.type.isTextblock
+                      || parent.textContent.length
+                      || !isAtStart
+                      || (isAtStart && $anchor.parent.type.name === 'paragraph') // prevent clearNodes when no nodes to clear, otherwise history stack is appended
+                  ) {
                       return false;
                   }
                   return commands.clearNodes();
@@ -4054,6 +4243,7 @@ img.ProseMirror-separator {
   /**
    * Build an input rule that adds a mark when the
    * matched text is typed into it.
+   * @see https://tiptap.dev/guide/custom-extensions/#input-rules
    */
   function markInputRule(config) {
       return new InputRule({
@@ -4097,6 +4287,7 @@ img.ProseMirror-separator {
   /**
    * Build an input rule that adds a node when the
    * matched text is typed into it.
+   * @see https://tiptap.dev/guide/custom-extensions/#input-rules
    */
   function nodeInputRule(config) {
       return new InputRule({
@@ -4135,6 +4326,7 @@ img.ProseMirror-separator {
    * matched text is typed into it. When using a regular expresion you’ll
    * probably want the regexp to start with `^`, so that the pattern can
    * only occur at the start of a textblock.
+   * @see https://tiptap.dev/guide/custom-extensions/#input-rules
    */
   function textblockTypeInputRule(config) {
       return new InputRule({
@@ -4155,6 +4347,7 @@ img.ProseMirror-separator {
   /**
    * Build an input rule that replaces text when the
    * matched text is typed into it.
+   * @see https://tiptap.dev/guide/custom-extensions/#input-rules
    */
   function textInputRule(config) {
       return new InputRule({
@@ -4191,6 +4384,7 @@ img.ProseMirror-separator {
    * two nodes. You can pass a join predicate, which takes a regular
    * expression match and the node before the wrapped node, and can
    * return a boolean to indicate whether a join should happen.
+   * @see https://tiptap.dev/guide/custom-extensions/#input-rules
    */
   function wrappingInputRule(config) {
       return new InputRule({
@@ -4230,6 +4424,10 @@ img.ProseMirror-separator {
       });
   }
 
+  /**
+   * The Mark class is used to create custom mark extensions.
+   * @see https://tiptap.dev/api/extensions#create-a-new-extension
+   */
   class Mark {
       constructor(config = {}) {
           this.type = 'mark';
@@ -4313,6 +4511,10 @@ img.ProseMirror-separator {
       }
   }
 
+  /**
+   * The Node class is used to create custom node extensions.
+   * @see https://tiptap.dev/api/extensions#create-a-new-extension
+   */
   class Node {
       constructor(config = {}) {
           this.type = 'node';
@@ -4380,6 +4582,10 @@ img.ProseMirror-separator {
       return navigator.platform === 'Android' || /android/i.test(navigator.userAgent);
   }
 
+  /**
+   * Node views are used to customize the rendered DOM structure of a node.
+   * @see https://tiptap.dev/guide/node-views
+   */
   class NodeView {
       constructor(component, props, options) {
           this.isDragging = false;
@@ -4570,6 +4776,7 @@ img.ProseMirror-separator {
   /**
    * Build an paste rule that adds a mark when the
    * matched text is pasted into it.
+   * @see https://tiptap.dev/guide/custom-extensions/#paste-rules
    */
   function markPasteRule(config) {
       return new PasteRule({
@@ -4623,6 +4830,7 @@ img.ProseMirror-separator {
   /**
    * Build an paste rule that adds a node when the
    * matched text is pasted into it.
+   * @see https://tiptap.dev/guide/custom-extensions/#paste-rules
    */
   function nodePasteRule(config) {
       return new PasteRule({
@@ -4645,6 +4853,7 @@ img.ProseMirror-separator {
   /**
    * Build an paste rule that replaces text when the
    * matched text is pasted into it.
+   * @see https://tiptap.dev/guide/custom-extensions/#paste-rules
    */
   function textPasteRule(config) {
       return new PasteRule({