@tiptap/core 2.3.2 → 2.4.0

package/dist/index.cjs

@@ -10,6 +10,11 @@ var transform = require('@tiptap/pm/transform');
 var commands$1 = require('@tiptap/pm/commands');
 var schemaList = require('@tiptap/pm/schema-list');
 
+/**
+ * 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;
@@ -176,6 +181,13 @@ class EventEmitter {
     }
 }
 
+/**
+ * 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);
@@ -420,6 +432,12 @@ function cleanUpSchemaItem(data) {
         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);
@@ -521,6 +539,12 @@ function getSchemaByResolvedExtensions(extensions, editor) {
     });
 }
 
+/**
+ * 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;
 }
@@ -537,6 +561,12 @@ function isExtensionRulesEnabled(extension, enabled) {
     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;
@@ -744,6 +774,10 @@ function isNumber(value) {
     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;
@@ -942,57 +976,14 @@ class ExtensionManager {
         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));
@@ -1003,6 +994,11 @@ 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) {
         return (extensions
             .map(extension => {
@@ -1020,6 +1016,11 @@ class ExtensionManager {
             // `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) => {
@@ -1034,6 +1035,10 @@ class ExtensionManager {
             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 = {
@@ -1053,6 +1058,10 @@ class ExtensionManager {
             };
         }, {});
     }
+    /**
+     * 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.
@@ -1115,9 +1124,17 @@ class ExtensionManager {
             ...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);
@@ -1150,6 +1167,62 @@ class ExtensionManager {
             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
@@ -1183,6 +1256,10 @@ function mergeDeep(target, source) {
     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';
@@ -1220,6 +1297,7 @@ class Extension {
         // 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,
@@ -1246,19 +1324,25 @@ class Extension {
     }
 }
 
+/**
+ * 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,
@@ -1273,16 +1357,16 @@ function getTextBetween(startNode, range, options) {
         }
         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)
@@ -1665,15 +1749,26 @@ function elementFromString(value) {
     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);
@@ -1683,7 +1778,7 @@ function createNodeFromContent(content, schema, options) {
             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
@@ -1983,6 +2078,12 @@ const newlineInCode = () => ({ state, dispatch }) => {
     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';
@@ -2080,6 +2181,13 @@ const selectTextblockStart = () => ({ state, dispatch }) => {
     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 });
 }
@@ -2117,6 +2225,9 @@ function getMarkAttributes(state, typeOrName) {
 
 /**
  * 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);
@@ -2128,6 +2239,11 @@ function combineTransactionSteps(oldDoc, transactions) {
     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);
@@ -2138,6 +2254,12 @@ function defaultBlockAt(match) {
     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) => {
@@ -2153,6 +2275,10 @@ function findChildren(node, predicate) {
 
 /**
  * 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 = [];
@@ -2176,6 +2302,15 @@ function findChildrenInRange(node, range, predicate) {
     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);
@@ -2190,6 +2325,14 @@ function findParentNodeClosestToPos($pos, predicate) {
     }
 }
 
+/**
+ * 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);
 }
@@ -2207,18 +2350,39 @@ function getSchema(extensions, editor) {
     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,
@@ -2227,6 +2391,13 @@ function getText(node, options) {
     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);
@@ -2254,6 +2425,12 @@ function getNodeAttributes(state, typeOrName) {
     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') {
@@ -2438,6 +2615,13 @@ const getNodeAtPosition = (state, typeOrName, pos, maxDepth = 20) => {
     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)
@@ -3288,7 +3472,12 @@ const Keymap = Extension.create({
                 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();
@@ -4060,6 +4249,7 @@ class Editor extends EventEmitter {
 /**
  * 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({
@@ -4103,6 +4293,7 @@ function markInputRule(config) {
 /**
  * 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({
@@ -4141,6 +4332,7 @@ function nodeInputRule(config) {
  * 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({
@@ -4161,6 +4353,7 @@ function textblockTypeInputRule(config) {
 /**
  * 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({
@@ -4197,6 +4390,7 @@ function textInputRule(config) {
  * 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({
@@ -4236,6 +4430,10 @@ function wrappingInputRule(config) {
     });
 }
 
+/**
+ * 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';
@@ -4319,6 +4517,10 @@ class Mark {
     }
 }
 
+/**
+ * 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';
@@ -4386,6 +4588,10 @@ function isAndroid() {
     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;
@@ -4576,6 +4782,7 @@ class NodeView {
 /**
  * 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({
@@ -4629,6 +4836,7 @@ function isString(value) {
 /**
  * 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({
@@ -4651,6 +4859,7 @@ function nodePasteRule(config) {
 /**
  * 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({