@tiptap/core 2.3.2 → 2.4.0

package/src/commands/insertContentAt.ts

@@ -9,12 +9,31 @@ declare module '@tiptap/core' {
     insertContentAt: {
       /**
        * Insert a node or string of HTML at a specific position.
+       * @example editor.commands.insertContentAt(0, '<h1>Example</h1>')
        */
       insertContentAt: (
+        /**
+         * The position to insert the content at.
+         */
         position: number | Range,
+
+        /**
+         * The ProseMirror content to insert.
+         */
         value: Content,
+
+        /**
+         * Optional options
+         */
         options?: {
+          /**
+           * Options for parsing the content.
+           */
           parseOptions?: ParseOptions
+
+          /**
+           * Whether to update the selection after inserting the content.
+           */
           updateSelection?: boolean
           applyInputRules?: boolean
           applyPasteRules?: boolean

package/src/commands/join.ts

@@ -11,25 +11,33 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     joinUp: {
       /**
-       * Join two nodes Up.
+       * Join the selected block or, if there is a text selection, the closest ancestor block of the selection that can be joined, with the sibling above it.
+       * @example editor.commands.joinUp()
        */
       joinUp: () => ReturnType
     }
     joinDown: {
       /**
-       * Join two nodes Down.
+       * Join the selected block, or the closest ancestor of the selection that can be joined, with the sibling after it.
+       * @example editor.commands.joinDown()
        */
       joinDown: () => ReturnType
     }
     joinBackward: {
       /**
-       * Join two nodes Backwards.
+       * If the selection is empty and at the start of a textblock, try to reduce the distance between that block and the one before it—if there's a block directly before it that can be joined, join them.
+       * If not, try to move the selected block closer to the next one in the document structure by lifting it out of its
+       * parent or moving it into a parent of the previous block. Will use the view for accurate (bidi-aware) start-of-textblock detection if given.
+       * @example editor.commands.joinBackward()
        */
       joinBackward: () => ReturnType
     }
     joinForward: {
       /**
-       * Join two nodes Forwards.
+       * If the selection is empty and the cursor is at the end of a textblock, try to reduce or remove the boundary between that block and the one after it,
+       * either by joining them or by moving the other block closer to this one in the tree structure.
+       * Will use the view for accurate start-of-textblock detection if given.
+       * @example editor.commands.joinForward()
        */
       joinForward: () => ReturnType
     }

package/src/commands/joinItemBackward.ts

@@ -6,7 +6,8 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     joinItemBackward: {
       /**
-       * Join two nodes Forwards.
+       * Join two items backward.
+       * @example editor.commands.joinItemBackward()
        */
       joinItemBackward: () => ReturnType
     }

package/src/commands/joinItemForward.ts

@@ -6,7 +6,8 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     joinItemForward: {
       /**
-       * Join two nodes Forwards.
+       * Join two items Forwards.
+       * @example editor.commands.joinItemForward()
        */
       joinItemForward: () => ReturnType
     }

package/src/commands/keyboardShortcut.ts

@@ -61,6 +61,8 @@ declare module '@tiptap/core' {
     keyboardShortcut: {
       /**
        * Trigger a keyboard shortcut.
+       * @param name The name of the keyboard shortcut.
+       * @example editor.commands.keyboardShortcut('Mod-b')
        */
       keyboardShortcut: (name: string) => ReturnType,
     }

package/src/commands/lift.ts

@@ -9,7 +9,11 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     lift: {
       /**
-       * Removes an existing wrap.
+       * Removes an existing wrap if possible lifting the node out of it
+       * @param typeOrName The type or name of the node.
+       * @param attributes The attributes of the node.
+       * @example editor.commands.lift('paragraph')
+       * @example editor.commands.lift('heading', { level: 1 })
        */
       lift: (typeOrName: string | NodeType, attributes?: Record<string, any>) => ReturnType
     }

package/src/commands/liftEmptyBlock.ts

@@ -6,7 +6,8 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     liftEmptyBlock: {
       /**
-       * Lift block if empty.
+       * If the cursor is in an empty textblock that can be lifted, lift the block.
+       * @example editor.commands.liftEmptyBlock()
        */
       liftEmptyBlock: () => ReturnType,
     }

package/src/commands/liftListItem.ts

@@ -8,7 +8,9 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     liftListItem: {
       /**
-       * Lift the list item into a wrapping list.
+       * Create a command to lift the list item around the selection up into a wrapping list.
+       * @param typeOrName The type or name of the node.
+       * @example editor.commands.liftListItem('listItem')
        */
       liftListItem: (typeOrName: string | NodeType) => ReturnType
     }

package/src/commands/newlineInCode.ts

@@ -7,6 +7,7 @@ declare module '@tiptap/core' {
     newlineInCode: {
       /**
        * Add a newline character in code.
+       * @example editor.commands.newlineInCode()
        */
       newlineInCode: () => ReturnType
     }

package/src/commands/resetAttributes.ts

@@ -11,6 +11,9 @@ declare module '@tiptap/core' {
     resetAttributes: {
       /**
        * Resets some node attributes to the default value.
+       * @param typeOrName The type or name of the node.
+       * @param attributes The attributes of the node to reset.
+       * @example editor.commands.resetAttributes('heading', 'level')
        */
       resetAttributes: (
         typeOrName: string | NodeType | MarkType,

package/src/commands/scrollIntoView.ts

@@ -5,6 +5,7 @@ declare module '@tiptap/core' {
     scrollIntoView: {
       /**
        * Scroll the selection into view.
+       * @example editor.commands.scrollIntoView()
        */
       scrollIntoView: () => ReturnType,
     }

package/src/commands/selectAll.ts

@@ -5,6 +5,7 @@ declare module '@tiptap/core' {
     selectAll: {
       /**
        * Select the whole document.
+       * @example editor.commands.selectAll()
        */
       selectAll: () => ReturnType,
     }

package/src/commands/selectNodeBackward.ts

@@ -7,6 +7,7 @@ declare module '@tiptap/core' {
     selectNodeBackward: {
       /**
        * Select a node backward.
+       * @example editor.commands.selectNodeBackward()
        */
       selectNodeBackward: () => ReturnType
     }

package/src/commands/selectNodeForward.ts

@@ -7,6 +7,7 @@ declare module '@tiptap/core' {
     selectNodeForward: {
       /**
        * Select a node forward.
+       * @example editor.commands.selectNodeForward()
        */
       selectNodeForward: () => ReturnType
     }

package/src/commands/selectParentNode.ts

@@ -7,6 +7,7 @@ declare module '@tiptap/core' {
     selectParentNode: {
       /**
        * Select the parent node.
+       * @example editor.commands.selectParentNode()
        */
       selectParentNode: () => ReturnType
     }

package/src/commands/selectTextblockEnd.ts

@@ -9,6 +9,7 @@ declare module '@tiptap/core' {
     selectTextblockEnd: {
       /**
        * Moves the cursor to the end of current text block.
+       * @example editor.commands.selectTextblockEnd()
        */
       selectTextblockEnd: () => ReturnType
     }

package/src/commands/selectTextblockStart.ts

@@ -9,6 +9,7 @@ declare module '@tiptap/core' {
     selectTextblockStart: {
       /**
        * Moves the cursor to the start of current text block.
+       * @example editor.commands.selectTextblockStart()
        */
       selectTextblockStart: () => ReturnType
     }

package/src/commands/setContent.ts

@@ -8,10 +8,27 @@ declare module '@tiptap/core' {
     setContent: {
       /**
        * Replace the whole document with new content.
+       * @param content The new content.
+       * @param emitUpdate Whether to emit an update event.
+       * @param parseOptions Options for parsing the content.
+       * @example editor.commands.setContent('<p>Example text</p>')
        */
       setContent: (
+        /**
+         * The new content.
+         */
         content: Content,
+
+        /**
+         * Whether to emit an update event.
+         * @default false
+         */
         emitUpdate?: boolean,
+
+        /**
+         * Options for parsing the content.
+         * @default {}
+         */
         parseOptions?: ParseOptions,
       ) => ReturnType
     }

package/src/commands/setMark.ts

@@ -11,6 +11,8 @@ declare module '@tiptap/core' {
     setMark: {
       /**
        * Add a mark with new attributes.
+       * @param typeOrName The mark type or name.
+       * @example editor.commands.setMark('bold', { level: 1 })
        */
       setMark: (typeOrName: string | MarkType, attributes?: Record<string, any>) => ReturnType
     }

package/src/commands/setMeta.ts

@@ -5,6 +5,9 @@ declare module '@tiptap/core' {
     setMeta: {
       /**
        * Store a metadata property in the current transaction.
+       * @param key The key of the metadata property.
+       * @param value The value to store.
+       * @example editor.commands.setMeta('foo', 'bar')
        */
       setMeta: (key: string, value: any) => ReturnType,
     }

package/src/commands/setNode.ts

@@ -9,6 +9,9 @@ declare module '@tiptap/core' {
     setNode: {
       /**
        * Replace a given range with a node.
+       * @param typeOrName The type or name of the node
+       * @param attributes The attributes of the node
+       * @example editor.commands.setNode('paragraph')
        */
       setNode: (typeOrName: string | NodeType, attributes?: Record<string, any>) => ReturnType
     }

package/src/commands/setNodeSelection.ts

@@ -8,6 +8,8 @@ declare module '@tiptap/core' {
     setNodeSelection: {
       /**
        * Creates a NodeSelection.
+       * @param position - Position of the node.
+       * @example editor.commands.setNodeSelection(10)
        */
       setNodeSelection: (position: number) => ReturnType
     }

package/src/commands/setTextSelection.ts

@@ -8,6 +8,8 @@ declare module '@tiptap/core' {
     setTextSelection: {
       /**
        * Creates a TextSelection.
+       * @param position The position of the selection.
+       * @example editor.commands.setTextSelection(10)
        */
       setTextSelection: (position: number | Range) => ReturnType
     }

package/src/commands/sinkListItem.ts

@@ -9,6 +9,8 @@ declare module '@tiptap/core' {
     sinkListItem: {
       /**
        * Sink the list item down into an inner list.
+       * @param typeOrName The type or name of the node.
+       * @example editor.commands.sinkListItem('listItem')
        */
       sinkListItem: (typeOrName: string | NodeType) => ReturnType
     }

package/src/commands/splitBlock.ts

@@ -20,6 +20,9 @@ declare module '@tiptap/core' {
     splitBlock: {
       /**
        * Forks a new node from an existing node.
+       * @param options.keepMarks Keep marks from the previous node.
+       * @example editor.commands.splitBlock()
+       * @example editor.commands.splitBlock({ keepMarks: true })
        */
       splitBlock: (options?: { keepMarks?: boolean }) => ReturnType
     }

package/src/commands/splitListItem.ts

@@ -13,6 +13,8 @@ declare module '@tiptap/core' {
     splitListItem: {
       /**
        * Splits one list item into two list items.
+       * @param typeOrName The type or name of the node.
+       * @example editor.commands.splitListItem('listItem')
        */
       splitListItem: (typeOrName: string | NodeType) => ReturnType
     }

package/src/commands/toggleList.ts

@@ -62,6 +62,11 @@ declare module '@tiptap/core' {
     toggleList: {
       /**
        * Toggle between different list types.
+       * @param listTypeOrName The type or name of the list.
+       * @param itemTypeOrName The type or name of the list item.
+       * @param keepMarks Keep marks when toggling.
+       * @param attributes Attributes for the new list.
+       * @example editor.commands.toggleList('bulletList', 'listItem')
        */
       toggleList: (listTypeOrName: string | NodeType, itemTypeOrName: string | NodeType, keepMarks?: boolean, attributes?: Record<string, any>) => ReturnType;
     }

package/src/commands/toggleMark.ts

@@ -9,10 +9,22 @@ declare module '@tiptap/core' {
     toggleMark: {
       /**
        * Toggle a mark on and off.
+       * @param typeOrName The mark type or name.
+       * @param attributes The attributes of the mark.
+       * @param options.extendEmptyMarkRange Removes the mark even across the current selection. Defaults to `false`.
+       * @example editor.commands.toggleMark('bold')
        */
       toggleMark: (
+        /**
+         * The mark type or name.
+         */
         typeOrName: string | MarkType,
+
+        /**
+         * The attributes of the mark.
+         */
         attributes?: Record<string, any>,
+
         options?: {
           /**
            * Removes the mark even across the current selection. Defaults to `false`.

package/src/commands/toggleNode.ts

@@ -9,6 +9,10 @@ declare module '@tiptap/core' {
     toggleNode: {
       /**
        * Toggle a node with another node.
+       * @param typeOrName The type or name of the node.
+       * @param toggleTypeOrName The type or name of the node to toggle.
+       * @param attributes The attributes of the node.
+       * @example editor.commands.toggleNode('heading', 'paragraph')
        */
       toggleNode: (
         typeOrName: string | NodeType,

package/src/commands/toggleWrap.ts

@@ -9,6 +9,9 @@ declare module '@tiptap/core' {
     toggleWrap: {
       /**
        * Wraps nodes in another node, or removes an existing wrap.
+       * @param typeOrName The type or name of the node.
+       * @param attributes The attributes of the node.
+       * @example editor.commands.toggleWrap('blockquote')
        */
       toggleWrap: (typeOrName: string | NodeType, attributes?: Record<string, any>) => ReturnType
     }

package/src/commands/undoInputRule.ts

@@ -5,6 +5,7 @@ declare module '@tiptap/core' {
     undoInputRule: {
       /**
        * Undo an input rule.
+       * @example editor.commands.undoInputRule()
        */
       undoInputRule: () => ReturnType,
     }

package/src/commands/unsetAllMarks.ts

@@ -5,6 +5,7 @@ declare module '@tiptap/core' {
     unsetAllMarks: {
       /**
        * Remove all marks in the current selection.
+       * @example editor.commands.unsetAllMarks()
        */
       unsetAllMarks: () => ReturnType,
     }

package/src/commands/unsetMark.ts

@@ -9,9 +9,16 @@ declare module '@tiptap/core' {
     unsetMark: {
       /**
        * Remove all marks in the current selection.
+       * @param typeOrName The mark type or name.
+       * @param options.extendEmptyMarkRange Removes the mark even across the current selection. Defaults to `false`.
+       * @example editor.commands.unsetMark('bold')
        */
       unsetMark: (
+        /**
+         * The mark type or name.
+         */
         typeOrName: string | MarkType,
+
         options?: {
           /**
            * Removes the mark even across the current selection. Defaults to `false`.

package/src/commands/updateAttributes.ts

@@ -10,9 +10,19 @@ declare module '@tiptap/core' {
     updateAttributes: {
       /**
        * Update attributes of a node or mark.
+       * @param typeOrName The type or name of the node or mark.
+       * @param attributes The attributes of the node or mark.
+       * @example editor.commands.updateAttributes('mention', { userId: "2" })
        */
       updateAttributes: (
+        /**
+         * The type or name of the node or mark.
+         */
         typeOrName: string | NodeType | MarkType,
+
+        /**
+         * The attributes of the node or mark.
+         */
         attributes: Record<string, any>,
       ) => ReturnType
     }

package/src/commands/wrapIn.ts

@@ -9,6 +9,9 @@ declare module '@tiptap/core' {
     wrapIn: {
       /**
        * Wraps nodes in another node.
+       * @param typeOrName The type or name of the node.
+       * @param attributes The attributes of the node.
+       * @example editor.commands.wrapIn('blockquote')
        */
       wrapIn: (typeOrName: string | NodeType, attributes?: Record<string, any>) => ReturnType
     }

package/src/commands/wrapInList.ts

@@ -9,6 +9,9 @@ declare module '@tiptap/core' {
     wrapInList: {
       /**
        * Wrap a node in a list.
+       * @param typeOrName The type or name of the node.
+       * @param attributes The attributes of the node.
+       * @example editor.commands.wrapInList('bulletList')
        */
       wrapInList: (typeOrName: string | NodeType, attributes?: Record<string, any>) => ReturnType
     }

package/src/extensions/keymap.ts

@@ -27,7 +27,13 @@ export const Keymap = Extension.create({
           ? parentPos === $anchor.pos
           : 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
         }
 

package/src/helpers/combineTransactionSteps.ts

@@ -4,6 +4,9 @@ import { Transform } from '@tiptap/pm/transform'
 
 /**
  * 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
  */
 export function combineTransactionSteps(
   oldDoc: ProseMirrorNode,

package/src/helpers/createChainableState.ts

@@ -1,5 +1,10 @@
 import { EditorState, Transaction } from '@tiptap/pm/state'
 
+/**
+ * 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
+ */
 export function createChainableState(config: {
   transaction: Transaction
   state: EditorState

package/src/helpers/createDocument.ts

@@ -3,6 +3,13 @@ import { Node as ProseMirrorNode, ParseOptions, Schema } from '@tiptap/pm/model'
 import { Content } from '../types.js'
 import { createNodeFromContent } from './createNodeFromContent.js'
 
+/**
+ * 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
+ */
 export function createDocument(
   content: Content,
   schema: Schema,

package/src/helpers/createNodeFromContent.ts

@@ -14,6 +14,13 @@ export type CreateNodeFromContentOptions = {
   parseOptions?: ParseOptions
 }
 
+/**
+ * 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
+ */
 export function createNodeFromContent(
   content: Content,
   schema: Schema,
@@ -25,9 +32,15 @@ export function createNodeFromContent(
     ...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 Fragment.fromArray(content.map(item => schema.nodeFromJSON(item)))
       }
 
@@ -39,7 +52,7 @@ export function createNodeFromContent(
     }
   }
 
-  if (typeof content === 'string') {
+  if (isTextContent) {
     const parser = DOMParser.fromSchema(schema)
 
     return options.slice

package/src/helpers/defaultBlockAt.ts

@@ -1,5 +1,10 @@
 import { ContentMatch, NodeType } from '@tiptap/pm/model'
 
+/**
+ * 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
+ */
 export function defaultBlockAt(match: ContentMatch): NodeType | null {
   for (let i = 0; i < match.edgeCount; i += 1) {
     const { type } = match.edge(i)

package/src/helpers/findChildren.ts

@@ -2,6 +2,12 @@ import { Node as ProseMirrorNode } from '@tiptap/pm/model'
 
 import { NodeWithPos, Predicate } from '../types.js'
 
+/**
+ * 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
+ */
 export function findChildren(node: ProseMirrorNode, predicate: Predicate): NodeWithPos[] {
   const nodesWithPos: NodeWithPos[] = []
 

package/src/helpers/findChildrenInRange.ts

@@ -4,6 +4,10 @@ import { NodeWithPos, Predicate, Range } from '../types.js'
 
 /**
  * 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
  */
 export function findChildrenInRange(
   node: ProseMirrorNode,

package/src/helpers/findParentNode.ts

@@ -3,6 +3,14 @@ import { Selection } from '@tiptap/pm/state'
 import { Predicate } from '../types.js'
 import { findParentNodeClosestToPos } from './findParentNodeClosestToPos.js'
 
+/**
+ * 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')
+ * ```
+ */
 export function findParentNode(predicate: Predicate) {
   return (selection: Selection) => findParentNodeClosestToPos(selection.$from, predicate)
 }

package/src/helpers/findParentNodeClosestToPos.ts

@@ -2,6 +2,15 @@ import { Node as ProseMirrorNode, ResolvedPos } from '@tiptap/pm/model'
 
 import { Predicate } from '../types.js'
 
+/**
+ * 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')
+ * ```
+ */
 export function findParentNodeClosestToPos(
   $pos: ResolvedPos,
   predicate: Predicate,