@tiptap/core 2.3.1 → 2.4.0

package/dist/packages/core/src/Node.d.ts

@@ -9,26 +9,50 @@ declare module '@tiptap/core' {
     interface NodeConfig<Options = any, Storage = any> {
         [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;
             parent: Exclude<ParentConfig<NodeConfig<Options, Storage>>['addOptions'], undefined>;
         }) => 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;
@@ -36,7 +60,30 @@ declare module '@tiptap/core' {
             parent: Exclude<ParentConfig<NodeConfig<Options, Storage>>['addStorage'], undefined>;
         }) => 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;
@@ -45,7 +92,14 @@ declare module '@tiptap/core' {
             parent: ParentConfig<NodeConfig<Options, Storage>>['addGlobalAttributes'];
         }) => 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;
@@ -56,7 +110,14 @@ declare module '@tiptap/core' {
             parent: ParentConfig<NodeConfig<Options, Storage>>['addCommands'];
         }) => 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;
@@ -69,7 +130,17 @@ declare module '@tiptap/core' {
             [key: string]: KeyboardShortcutCommand;
         };
         /**
-         * 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;
@@ -80,7 +151,17 @@ declare module '@tiptap/core' {
             parent: ParentConfig<NodeConfig<Options, Storage>>['addInputRules'];
         }) => 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;
@@ -91,7 +172,14 @@ declare module '@tiptap/core' {
             parent: ParentConfig<NodeConfig<Options, Storage>>['addPasteRules'];
         }) => 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;
@@ -102,7 +190,16 @@ declare module '@tiptap/core' {
             parent: ParentConfig<NodeConfig<Options, Storage>>['addProseMirrorPlugins'];
         }) => 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;
@@ -111,7 +208,14 @@ declare module '@tiptap/core' {
             parent: ParentConfig<NodeConfig<Options, Storage>>['addExtensions'];
         }) => Extensions;
         /**
-         * Extend Node Schema
+         * This function extends the schema of the node.
+         * @example
+         * extendNodeSchema() {
+         *   return {
+         *     group: 'inline',
+         *     selectable: false,
+         *   }
+         * }
          */
         extendNodeSchema?: ((this: {
             name: string;
@@ -120,7 +224,14 @@ declare module '@tiptap/core' {
             parent: ParentConfig<NodeConfig<Options, Storage>>['extendNodeSchema'];
         }, extension: Node) => Record<string, any>) | null;
         /**
-         * Extend Mark Schema
+         * This function extends the schema of the mark.
+         * @example
+         * extendMarkSchema() {
+         *   return {
+         *     group: 'inline',
+         *     selectable: false,
+         *   }
+         * }
          */
         extendMarkSchema?: ((this: {
             name: string;
@@ -235,11 +346,21 @@ declare module '@tiptap/core' {
             parent: ParentConfig<NodeConfig<Options, Storage>>['addNodeView'];
         }) => NodeViewRenderer) | 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'] | ((this: {
             name: string;
@@ -249,7 +370,13 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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'] | ((this: {
             name: string;
@@ -259,7 +386,16 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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'] | ((this: {
             name: string;
@@ -269,7 +405,7 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => NodeSpec['group']);
         /**
-         * Inline
+         * Should be set to true for inline nodes. (Implied for text nodes.)
          */
         inline?: NodeSpec['inline'] | ((this: {
             name: string;
@@ -279,7 +415,11 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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'] | ((this: {
             name: string;
@@ -289,7 +429,12 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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'] | ((this: {
             name: string;
@@ -299,7 +444,11 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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'] | ((this: {
             name: string;
@@ -309,7 +458,8 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => NodeSpec['draggable']);
         /**
-         * Code
+         * Can be used to indicate that this node contains code, which
+         * causes some commands to behave differently.
          */
         code?: NodeSpec['code'] | ((this: {
             name: string;
@@ -319,7 +469,15 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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'] | ((this: {
             name: string;
@@ -329,7 +487,12 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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'] | ((this: {
             name: string;
@@ -339,7 +502,10 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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'] | ((this: {
             name: string;
@@ -349,7 +515,14 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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;
@@ -359,7 +532,24 @@ declare module '@tiptap/core' {
             editor?: Editor;
         }) => 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?: ((this: {
             name: string;
@@ -372,7 +562,8 @@ declare module '@tiptap/core' {
             HTMLAttributes: Record<string, any>;
         }) => DOMOutputSpec) | null;
         /**
-         * Render Text
+         * renders the node as text
+         * @example renderText: () => 'foo
          */
         renderText?: ((this: {
             name: string;
@@ -387,7 +578,8 @@ declare module '@tiptap/core' {
             index: number;
         }) => string) | null;
         /**
-         * Add Attributes
+         * Add attributes to the node
+         * @example addAttributes: () => ({ class: 'foo' })
          */
         addAttributes?: (this: {
             name: string;
@@ -398,6 +590,10 @@ declare module '@tiptap/core' {
         }) => Attributes | {};
     }
 }
+/**
+ * The Node class is used to create custom node extensions.
+ * @see https://tiptap.dev/api/extensions#create-a-new-extension
+ */
 export declare class Node<Options = any, Storage = any> {
     type: string;
     name: string;

package/dist/packages/core/src/NodeView.d.ts

@@ -3,6 +3,10 @@ import { NodeView as ProseMirrorNodeView } from '@tiptap/pm/view';
 import { Editor as CoreEditor } from './Editor.js';
 import { Node } from './Node.js';
 import { DecorationWithType, NodeViewRendererOptions, NodeViewRendererProps } from './types.js';
+/**
+ * Node views are used to customize the rendered DOM structure of a node.
+ * @see https://tiptap.dev/guide/node-views
+ */
 export declare class NodeView<Component, NodeEditor extends CoreEditor = CoreEditor, Options extends NodeViewRendererOptions = NodeViewRendererOptions> implements ProseMirrorNodeView {
     component: Component;
     editor: NodeEditor;

package/dist/packages/core/src/PasteRule.d.ts

@@ -9,6 +9,10 @@ export declare type PasteRuleMatch = {
     data?: Record<string, any>;
 };
 export declare 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 declare class PasteRule {
     find: PasteRuleFinder;
     handler: (props: {

package/dist/packages/core/src/commands/blur.d.ts

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

package/dist/packages/core/src/commands/clearContent.d.ts

@@ -4,6 +4,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/dist/packages/core/src/commands/clearNodes.d.ts

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

package/dist/packages/core/src/commands/command.d.ts

@@ -4,6 +4,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/dist/packages/core/src/commands/createParagraphNear.d.ts

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

package/dist/packages/core/src/commands/cut.d.ts

@@ -4,6 +4,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;

package/dist/packages/core/src/commands/deleteCurrentNode.d.ts

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

package/dist/packages/core/src/commands/deleteNode.d.ts

@@ -4,7 +4,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/dist/packages/core/src/commands/deleteRange.d.ts

@@ -4,6 +4,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/dist/packages/core/src/commands/deleteSelection.d.ts

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

package/dist/packages/core/src/commands/enter.d.ts

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

package/dist/packages/core/src/commands/exitCode.d.ts

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

package/dist/packages/core/src/commands/extendMarkRange.d.ts

@@ -4,9 +4,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: (typeOrName: string | MarkType, attributes?: Record<string, any>) => ReturnType;
+            extendMarkRange: (
+            /**
+             * The type or name of the mark.
+             */
+            typeOrName: string | MarkType, 
+            /**
+             * The attributes of the mark.
+             */
+            attributes?: Record<string, any>) => ReturnType;
         };
     }
 }

package/dist/packages/core/src/commands/first.d.ts

@@ -4,6 +4,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/dist/packages/core/src/commands/focus.d.ts

@@ -4,8 +4,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: (position?: FocusPosition, options?: {
+            focus: (
+            /**
+             * The position to focus at.
+             */
+            position?: FocusPosition, 
+            /**
+             * Optional options
+             * @default { scrollIntoView: true }
+             */
+            options?: {
                 scrollIntoView?: boolean;
             }) => ReturnType;
         };