@tiptap/core 2.3.2 → 2.4.0

package/src/Node.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?:
       | ((
@@ -312,12 +423,22 @@ declare module '@tiptap/core' {
       | null
 
     /**
-     * TopNode
+     * Defines if this node should be a top level node (doc)
+     * @default false
+     * @example true
      */
     topNode?: boolean
 
     /**
-     * Content
+     * The content expression for this node, as described in the [schema
+     * guide](/docs/guide/#schema.content_expressions). When not given,
+     * the node does not allow any content.
+     *
+     * You can read more about it on the Prosemirror documentation here
+     * @see https://prosemirror.net/docs/guide/#schema.content_expressions
+     * @default undefined
+     * @example content: 'block+'
+     * @example content: 'headline paragraph block*'
      */
     content?:
       | NodeSpec['content']
@@ -330,7 +451,13 @@ declare module '@tiptap/core' {
         }) => NodeSpec['content'])
 
     /**
-     * Marks
+     * The marks that are allowed inside of this node. May be a
+     * space-separated string referring to mark names or groups, `"_"`
+     * to explicitly allow all marks, or `""` to disallow marks. When
+     * not given, nodes with inline content default to allowing all
+     * marks, other nodes default to not allowing marks.
+     *
+     * @example marks: 'strong em'
      */
     marks?:
       | NodeSpec['marks']
@@ -343,7 +470,16 @@ declare module '@tiptap/core' {
         }) => NodeSpec['marks'])
 
     /**
-     * Group
+     * The group or space-separated groups to which this node belongs,
+     * which can be referred to in the content expressions for the
+     * schema.
+     *
+     * By default Tiptap uses the groups 'block' and 'inline' for nodes. You
+     * can also use custom groups if you want to group specific nodes together
+     * and handle them in your schema.
+     * @example group: 'block'
+     * @example group: 'inline'
+     * @example group: 'customBlock' // this uses a custom group
      */
     group?:
       | NodeSpec['group']
@@ -356,7 +492,7 @@ declare module '@tiptap/core' {
         }) => NodeSpec['group'])
 
     /**
-     * Inline
+     * Should be set to true for inline nodes. (Implied for text nodes.)
      */
     inline?:
       | NodeSpec['inline']
@@ -369,7 +505,11 @@ declare module '@tiptap/core' {
         }) => NodeSpec['inline'])
 
     /**
-     * Atom
+     * Can be set to true to indicate that, though this isn't a [leaf
+     * node](https://prosemirror.net/docs/ref/#model.NodeType.isLeaf), it doesn't have directly editable
+     * content and should be treated as a single unit in the view.
+     *
+     * @example atom: true
      */
     atom?:
       | NodeSpec['atom']
@@ -382,7 +522,12 @@ declare module '@tiptap/core' {
         }) => NodeSpec['atom'])
 
     /**
-     * Selectable
+     * Controls whether nodes of this type can be selected as a [node
+     * selection](https://prosemirror.net/docs/ref/#state.NodeSelection). Defaults to true for non-text
+     * nodes.
+     *
+     * @default true
+     * @example selectable: false
      */
     selectable?:
       | NodeSpec['selectable']
@@ -395,7 +540,11 @@ declare module '@tiptap/core' {
         }) => NodeSpec['selectable'])
 
     /**
-     * Draggable
+     * Determines whether nodes of this type can be dragged without
+     * being selected. Defaults to false.
+     *
+     * @default: false
+     * @example: draggable: true
      */
     draggable?:
       | NodeSpec['draggable']
@@ -408,7 +557,8 @@ declare module '@tiptap/core' {
         }) => NodeSpec['draggable'])
 
     /**
-     * Code
+     * Can be used to indicate that this node contains code, which
+     * causes some commands to behave differently.
      */
     code?:
       | NodeSpec['code']
@@ -421,7 +571,15 @@ declare module '@tiptap/core' {
         }) => NodeSpec['code'])
 
     /**
-     * Whitespace
+     * Controls way whitespace in this a node is parsed. The default is
+     * `"normal"`, which causes the [DOM parser](https://prosemirror.net/docs/ref/#model.DOMParser) to
+     * collapse whitespace in normal mode, and normalize it (replacing
+     * newlines and such with spaces) otherwise. `"pre"` causes the
+     * parser to preserve spaces inside the node. When this option isn't
+     * given, but [`code`](https://prosemirror.net/docs/ref/#model.NodeSpec.code) is true, `whitespace`
+     * will default to `"pre"`. Note that this option doesn't influence
+     * the way the node is rendered—that should be handled by `toDOM`
+     * and/or styling.
      */
     whitespace?:
       | NodeSpec['whitespace']
@@ -434,7 +592,12 @@ declare module '@tiptap/core' {
         }) => NodeSpec['whitespace'])
 
     /**
-     * Defining
+     * When enabled, enables both
+     * [`definingAsContext`](https://prosemirror.net/docs/ref/#model.NodeSpec.definingAsContext) and
+     * [`definingForContent`](https://prosemirror.net/docs/ref/#model.NodeSpec.definingForContent).
+     *
+     * @default false
+     * @example isolating: true
      */
     defining?:
       | NodeSpec['defining']
@@ -447,7 +610,10 @@ declare module '@tiptap/core' {
         }) => NodeSpec['defining'])
 
     /**
-     * Isolating
+     * When enabled (default is false), the sides of nodes of this type
+     * count as boundaries that regular editing operations, like
+     * backspacing or lifting, won't cross. An example of a node that
+     * should probably have this enabled is a table cell.
      */
     isolating?:
       | NodeSpec['isolating']
@@ -460,7 +626,14 @@ declare module '@tiptap/core' {
         }) => NodeSpec['isolating'])
 
     /**
-     * Parse HTML
+     * Associates DOM parser information with this node, which can be
+     * used by [`DOMParser.fromSchema`](https://prosemirror.net/docs/ref/#model.DOMParser^fromSchema) to
+     * automatically derive a parser. The `node` field in the rules is
+     * implied (the name of this node will be filled in automatically).
+     * If you supply your own parser, you do not need to also specify
+     * parsing rules in your schema.
+     *
+     * @example parseHTML: [{ tag: 'div', attrs: { 'data-id': 'my-block' } }]
      */
     parseHTML?: (this: {
       name: string
@@ -471,7 +644,24 @@ declare module '@tiptap/core' {
     }) => NodeSpec['parseDOM']
 
     /**
-     * Render HTML
+     * A description of a DOM structure. Can be either a string, which is
+     * interpreted as a text node, a DOM node, which is interpreted as
+     * itself, a `{dom, contentDOM}` object, or an array.
+     *
+     * An array describes a DOM element. The first value in the array
+     * should be a string—the name of the DOM element, optionally prefixed
+     * by a namespace URL and a space. If the second element is plain
+     * object, it is interpreted as a set of attributes for the element.
+     * Any elements after that (including the 2nd if it's not an attribute
+     * object) are interpreted as children of the DOM elements, and must
+     * either be valid `DOMOutputSpec` values, or the number zero.
+     *
+     * The number zero (pronounced “hole”) is used to indicate the place
+     * where a node's child nodes should be inserted. If it occurs in an
+     * output spec, it should be the only child element in its parent
+     * node.
+     *
+     * @example toDOM: ['div[data-id="my-block"]', { class: 'my-block' }, 0]
      */
     renderHTML?:
       | ((
@@ -490,7 +680,8 @@ declare module '@tiptap/core' {
       | null
 
     /**
-     * Render Text
+     * renders the node as text
+     * @example renderText: () => 'foo
      */
     renderText?:
       | ((
@@ -511,7 +702,8 @@ declare module '@tiptap/core' {
       | null
 
     /**
-     * Add Attributes
+     * Add attributes to the node
+     * @example addAttributes: () => ({ class: 'foo' })
      */
     addAttributes?: (this: {
       name: string
@@ -523,6 +715,10 @@ declare module '@tiptap/core' {
   }
 }
 
+/**
+ * The Node class is used to create custom node extensions.
+ * @see https://tiptap.dev/api/extensions#create-a-new-extension
+ */
 export class Node<Options = any, Storage = any> {
   type = 'node'
 

package/src/NodeView.ts

@@ -8,6 +8,10 @@ import { DecorationWithType, NodeViewRendererOptions, NodeViewRendererProps } fr
 import { isAndroid } from './utilities/isAndroid.js'
 import { isiOS } from './utilities/isiOS.js'
 
+/**
+ * Node views are used to customize the rendered DOM structure of a node.
+ * @see https://tiptap.dev/guide/node-views
+ */
 export class NodeView<
   Component,
   NodeEditor extends CoreEditor = CoreEditor,

package/src/PasteRule.ts

@@ -23,6 +23,10 @@ export type PasteRuleMatch = {
 
 export type PasteRuleFinder = RegExp | ((text: string, event?: ClipboardEvent | null) => PasteRuleMatch[] | null | undefined)
 
+/**
+ * Paste rules are used to react to pasted content.
+ * @see https://tiptap.dev/guide/custom-extensions/#paste-rules
+ */
 export class PasteRule {
   find: PasteRuleFinder
 

package/src/commands/blur.ts

@@ -5,6 +5,7 @@ declare module '@tiptap/core' {
     blur: {
       /**
        * Removes focus from the editor.
+       * @example editor.commands.blur()
        */
       blur: () => ReturnType,
     }

package/src/commands/clearContent.ts

@@ -5,6 +5,8 @@ declare module '@tiptap/core' {
     clearContent: {
       /**
        * Clear the whole document.
+       * @param emitUpdate Whether to emit an update event.
+       * @example editor.commands.clearContent()
        */
       clearContent: (emitUpdate?: boolean) => ReturnType,
     }

package/src/commands/clearNodes.ts

@@ -7,6 +7,7 @@ declare module '@tiptap/core' {
     clearNodes: {
       /**
        * Normalize nodes to a simple paragraph.
+       * @example editor.commands.clearNodes()
        */
       clearNodes: () => ReturnType,
     }

package/src/commands/command.ts

@@ -5,6 +5,12 @@ declare module '@tiptap/core' {
     command: {
       /**
        * Define a command inline.
+       * @param fn The command function.
+       * @example
+       * editor.commands.command(({ tr, state }) => {
+       *   ...
+       *   return true
+       * })
        */
       command: (fn: (props: Parameters<Command>[0]) => boolean) => ReturnType,
     }

package/src/commands/createParagraphNear.ts

@@ -7,6 +7,7 @@ declare module '@tiptap/core' {
     createParagraphNear: {
       /**
        * Create a paragraph nearby.
+       * @example editor.commands.createParagraphNear()
        */
       createParagraphNear: () => ReturnType
     }

package/src/commands/cut.ts

@@ -7,6 +7,11 @@ declare module '@tiptap/core' {
     cut: {
       /**
        * Cuts content from a range and inserts it at a given position.
+       * @param range The range to cut.
+       * @param range.from The start position of the range.
+       * @param range.to The end position of the range.
+       * @param targetPos The position to insert the content at.
+       * @example editor.commands.cut({ from: 1, to: 3 }, 5)
        */
       cut: ({ from, to }: { from: number, to: number }, targetPos: number) => ReturnType,
     }

package/src/commands/deleteCurrentNode.ts

@@ -5,6 +5,7 @@ declare module '@tiptap/core' {
     deleteCurrentNode: {
       /**
        * Delete the node that currently has the selection anchor.
+       * @example editor.commands.deleteCurrentNode()
        */
       deleteCurrentNode: () => ReturnType,
     }

package/src/commands/deleteNode.ts

@@ -7,7 +7,9 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     deleteNode: {
       /**
-       * Delete a node.
+       * Delete a node with a given type or name.
+       * @param typeOrName The type or name of the node.
+       * @example editor.commands.deleteNode('paragraph')
        */
       deleteNode: (typeOrName: string | NodeType) => ReturnType,
     }

package/src/commands/deleteRange.ts

@@ -5,6 +5,8 @@ declare module '@tiptap/core' {
     deleteRange: {
       /**
        * Delete a given range.
+       * @param range The range to delete.
+       * @example editor.commands.deleteRange({ from: 1, to: 3 })
        */
       deleteRange: (range: Range) => ReturnType,
     }

package/src/commands/deleteSelection.ts

@@ -7,6 +7,7 @@ declare module '@tiptap/core' {
     deleteSelection: {
       /**
        * Delete the selection, if there is one.
+       * @example editor.commands.deleteSelection()
        */
       deleteSelection: () => ReturnType
     }

package/src/commands/enter.ts

@@ -5,6 +5,7 @@ declare module '@tiptap/core' {
     enter: {
       /**
        * Trigger enter.
+       * @example editor.commands.enter()
        */
       enter: () => ReturnType,
     }

package/src/commands/exitCode.ts

@@ -7,6 +7,7 @@ declare module '@tiptap/core' {
     exitCode: {
       /**
        * Exit from a code block.
+       * @example editor.commands.exitCode()
        */
       exitCode: () => ReturnType
     }

package/src/commands/extendMarkRange.ts

@@ -9,10 +9,21 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     extendMarkRange: {
       /**
-       * Extends the text selection to the current mark.
+       * Extends the text selection to the current mark by type or name.
+       * @param typeOrName The type or name of the mark.
+       * @param attributes The attributes of the mark.
+       * @example editor.commands.extendMarkRange('bold')
+       * @example editor.commands.extendMarkRange('mention', { userId: "1" })
        */
       extendMarkRange: (
+        /**
+         * The type or name of the mark.
+         */
         typeOrName: string | MarkType,
+
+        /**
+         * The attributes of the mark.
+         */
         attributes?: Record<string, any>,
       ) => ReturnType
     }

package/src/commands/first.ts

@@ -5,6 +5,8 @@ declare module '@tiptap/core' {
     first: {
       /**
        * Runs one command after the other and stops at the first which returns true.
+       * @param commands The commands to run.
+       * @example editor.commands.first([command1, command2])
        */
       first: (commands: Command[] | ((props: CommandProps) => Command[])) => ReturnType,
     }

package/src/commands/focus.ts

@@ -8,9 +8,21 @@ declare module '@tiptap/core' {
     focus: {
       /**
        * Focus the editor at the given position.
+       * @param position The position to focus at.
+       * @param options.scrollIntoView Scroll the focused position into view after focusing
+       * @example editor.commands.focus()
+       * @example editor.commands.focus(32, { scrollIntoView: false })
        */
       focus: (
+        /**
+         * The position to focus at.
+         */
         position?: FocusPosition,
+
+        /**
+         * Optional options
+         * @default { scrollIntoView: true }
+         */
         options?: {
           scrollIntoView?: boolean,
         },

package/src/commands/insertContent.ts

@@ -7,11 +7,27 @@ declare module '@tiptap/core' {
     insertContent: {
       /**
        * Insert a node or string of HTML at the current position.
+       * @example editor.commands.insertContent('<h1>Example</h1>')
+       * @example editor.commands.insertContent('<h1>Example</h1>', { updateSelection: false })
        */
       insertContent: (
+        /**
+         * 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