From b941eea6daba09d48a5d18ccc1b9a1d84b2249dd Mon Sep 17 00:00:00 2001 From: bdbch <6538827+bdbch@users.noreply.github.com> Date: Sat, 11 May 2024 14:30:44 +0200 Subject: [PATCH] feat: added jsdocs (#4356) * added JSDocs for almost all extensions * start adding commands jsdocs * add jsdocs for rest of extensions * add jsdocs for Extensions * add js docs for all extensions * add more jsdocs * add js docs for node spec definitions --- packages/core/src/Extension.ts | 143 +++++++++- packages/core/src/Mark.ts | 143 +++++++++- packages/core/src/Node.ts | 256 ++++++++++++++++-- packages/core/src/NodeView.ts | 4 + packages/core/src/PasteRule.ts | 4 + packages/core/src/commands/blur.ts | 1 + packages/core/src/commands/clearContent.ts | 2 + packages/core/src/commands/clearNodes.ts | 1 + packages/core/src/commands/command.ts | 6 + .../core/src/commands/createParagraphNear.ts | 1 + packages/core/src/commands/cut.ts | 5 + .../core/src/commands/deleteCurrentNode.ts | 1 + packages/core/src/commands/deleteNode.ts | 4 +- packages/core/src/commands/deleteRange.ts | 2 + packages/core/src/commands/deleteSelection.ts | 1 + packages/core/src/commands/enter.ts | 1 + packages/core/src/commands/exitCode.ts | 1 + packages/core/src/commands/extendMarkRange.ts | 13 +- packages/core/src/commands/first.ts | 2 + packages/core/src/commands/focus.ts | 12 + packages/core/src/commands/insertContent.ts | 16 ++ packages/core/src/commands/insertContentAt.ts | 19 ++ packages/core/src/commands/join.ts | 16 +- .../core/src/commands/joinItemBackward.ts | 3 +- packages/core/src/commands/joinItemForward.ts | 3 +- .../core/src/commands/keyboardShortcut.ts | 2 + packages/core/src/commands/lift.ts | 6 +- packages/core/src/commands/liftEmptyBlock.ts | 3 +- packages/core/src/commands/liftListItem.ts | 4 +- packages/core/src/commands/newlineInCode.ts | 1 + packages/core/src/commands/resetAttributes.ts | 3 + packages/core/src/commands/scrollIntoView.ts | 1 + packages/core/src/commands/selectAll.ts | 1 + .../core/src/commands/selectNodeBackward.ts | 1 + .../core/src/commands/selectNodeForward.ts | 1 + .../core/src/commands/selectParentNode.ts | 1 + .../core/src/commands/selectTextblockEnd.ts | 1 + .../core/src/commands/selectTextblockStart.ts | 1 + packages/core/src/commands/setContent.ts | 17 ++ packages/core/src/commands/setMark.ts | 2 + packages/core/src/commands/setMeta.ts | 3 + packages/core/src/commands/setNode.ts | 3 + .../core/src/commands/setNodeSelection.ts | 2 + .../core/src/commands/setTextSelection.ts | 2 + packages/core/src/commands/sinkListItem.ts | 2 + packages/core/src/commands/splitBlock.ts | 3 + packages/core/src/commands/splitListItem.ts | 2 + packages/core/src/commands/toggleList.ts | 5 + packages/core/src/commands/toggleMark.ts | 12 + packages/core/src/commands/toggleNode.ts | 4 + packages/core/src/commands/toggleWrap.ts | 3 + packages/core/src/commands/undoInputRule.ts | 1 + packages/core/src/commands/unsetAllMarks.ts | 1 + packages/core/src/commands/unsetMark.ts | 7 + .../core/src/commands/updateAttributes.ts | 10 + packages/core/src/commands/wrapIn.ts | 3 + packages/core/src/commands/wrapInList.ts | 3 + packages/core/src/inputRules/markInputRule.ts | 1 + packages/core/src/inputRules/nodeInputRule.ts | 1 + packages/core/src/inputRules/textInputRule.ts | 1 + .../src/inputRules/textblockTypeInputRule.ts | 1 + .../core/src/inputRules/wrappingInputRule.ts | 1 + packages/core/src/pasteRules/markPasteRule.ts | 1 + packages/core/src/pasteRules/nodePasteRule.ts | 1 + packages/core/src/pasteRules/textPasteRule.ts | 1 + .../extension-blockquote/src/blockquote.ts | 12 + packages/extension-bold/src/bold.ts | 24 ++ .../src/bubble-menu-plugin.ts | 32 +++ .../extension-bubble-menu/src/bubble-menu.ts | 9 + .../extension-bullet-list/src/bullet-list.ts | 32 +++ .../src/character-count.ts | 16 +- .../src/code-block-lowlight.ts | 13 + .../extension-code-block/src/code-block.ts | 23 +- packages/extension-code/src/code.ts | 16 ++ .../src/collaboration-cursor.ts | 48 ++++ .../src/collaboration.ts | 13 + .../src/helpers/isChangeOrigin.ts | 8 + packages/extension-color/src/color.ts | 13 + packages/extension-document/src/document.ts | 4 + .../extension-dropcursor/src/dropcursor.ts | 23 ++ .../src/floating-menu-plugin.ts | 29 ++ .../src/floating-menu.ts | 9 + packages/extension-focus/src/focus.ts | 20 ++ .../extension-font-family/src/font-family.ts | 12 + packages/extension-gapcursor/src/gapcursor.ts | 9 +- .../extension-hard-break/src/hard-break.ts | 16 ++ packages/extension-heading/src/heading.ts | 22 ++ packages/extension-highlight/src/highlight.ts | 27 ++ packages/extension-history/src/history.ts | 22 ++ .../src/horizontal-rule.ts | 10 + packages/extension-image/src/image.ts | 30 ++ packages/extension-italic/src/italic.ts | 27 ++ .../extension-link/src/helpers/autolink.ts | 16 ++ packages/extension-link/src/link.ts | 40 ++- packages/extension-list-item/src/list-item.ts | 21 ++ .../extension-list-keymap/src/list-keymap.ts | 12 + packages/extension-mention/src/mention.ts | 47 +++- .../src/ordered-list.ts | 33 +++ packages/extension-paragraph/src/paragraph.ts | 10 + .../extension-placeholder/src/placeholder.ts | 5 + packages/extension-strike/src/strike.ts | 19 ++ packages/extension-subscript/src/subscript.ts | 12 + .../extension-superscript/src/superscript.ts | 12 + .../extension-table-cell/src/table-cell.ts | 9 + .../src/table-header.ts | 10 + packages/extension-table-row/src/table-row.ts | 9 + packages/extension-table/src/table.ts | 165 ++++++++++- packages/extension-task-item/src/task-item.ts | 31 +++ packages/extension-task-list/src/task-list.ts | 16 ++ .../extension-text-align/src/text-align.ts | 24 ++ .../extension-text-style/src/text-style.ts | 11 + packages/extension-text/src/text.ts | 4 + .../extension-typography/src/typography.ts | 140 ++++++++++ packages/extension-underline/src/underline.ts | 12 + packages/extension-youtube/src/youtube.ts | 134 +++++++++ packages/html/src/generateHTML.ts | 23 ++ packages/html/src/generateJSON.ts | 11 + packages/html/src/getHTMLFromFragment.ts | 12 + packages/react/src/ReactRenderer.tsx | 51 ++++ packages/react/src/useEditor.ts | 7 + packages/starter-kit/src/starter-kit.ts | 94 +++++++ packages/suggestion/src/suggestion.ts | 116 ++++++++ packages/vue-2/src/VueRenderer.ts | 3 + packages/vue-3/src/VueRenderer.ts | 3 + 124 files changed, 2332 insertions(+), 78 deletions(-) diff --git a/packages/core/src/Extension.ts b/packages/core/src/Extension.ts index e13f4bf6be..225c929953 100644 --- a/packages/core/src/Extension.ts +++ b/packages/core/src/Extension.ts @@ -23,22 +23,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 @@ -46,7 +64,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 @@ -55,7 +79,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 @@ -65,7 +112,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 @@ -76,7 +130,14 @@ declare module '@tiptap/core' { }) => Partial /** - * 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 @@ -89,7 +150,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 @@ -100,7 +171,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 @@ -111,7 +192,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 @@ -122,7 +210,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 @@ -132,7 +229,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?: | (( @@ -147,7 +251,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?: | (( @@ -282,6 +393,10 @@ declare module '@tiptap/core' { } } +/** + * The Extension class is the base class for all extensions. + * @see https://tiptap.dev/api/extensions#create-a-new-extension + */ export class Extension { type = 'extension' diff --git a/packages/core/src/Mark.ts b/packages/core/src/Mark.ts index 3d56c85d26..8599bf339c 100644 --- a/packages/core/src/Mark.ts +++ b/packages/core/src/Mark.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 /** - * 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?: | (( @@ -414,6 +525,10 @@ declare module '@tiptap/core' { } } +/** + * The Mark class is used to create custom mark extensions. + * @see https://tiptap.dev/api/extensions#create-a-new-extension + */ export class Mark { type = 'mark' diff --git a/packages/core/src/Node.ts b/packages/core/src/Node.ts index c478992d29..cb7bc0cd8a 100644 --- a/packages/core/src/Node.ts +++ b/packages/core/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 /** - * 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 { type = 'node' diff --git a/packages/core/src/NodeView.ts b/packages/core/src/NodeView.ts index 6bd3b74df3..228237cff8 100644 --- a/packages/core/src/NodeView.ts +++ b/packages/core/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, diff --git a/packages/core/src/PasteRule.ts b/packages/core/src/PasteRule.ts index 1158cbb47c..a096967347 100644 --- a/packages/core/src/PasteRule.ts +++ b/packages/core/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 diff --git a/packages/core/src/commands/blur.ts b/packages/core/src/commands/blur.ts index 511137bc1b..87f65a5e23 100644 --- a/packages/core/src/commands/blur.ts +++ b/packages/core/src/commands/blur.ts @@ -5,6 +5,7 @@ declare module '@tiptap/core' { blur: { /** * Removes focus from the editor. + * @example editor.commands.blur() */ blur: () => ReturnType, } diff --git a/packages/core/src/commands/clearContent.ts b/packages/core/src/commands/clearContent.ts index 6385452256..c6fb89bcca 100644 --- a/packages/core/src/commands/clearContent.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/clearNodes.ts b/packages/core/src/commands/clearNodes.ts index aa41fcc3c1..1e124063ef 100644 --- a/packages/core/src/commands/clearNodes.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/command.ts b/packages/core/src/commands/command.ts index 9262495c62..062849bdca 100644 --- a/packages/core/src/commands/command.ts +++ b/packages/core/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[0]) => boolean) => ReturnType, } diff --git a/packages/core/src/commands/createParagraphNear.ts b/packages/core/src/commands/createParagraphNear.ts index c0103989f1..c956d40288 100644 --- a/packages/core/src/commands/createParagraphNear.ts +++ b/packages/core/src/commands/createParagraphNear.ts @@ -7,6 +7,7 @@ declare module '@tiptap/core' { createParagraphNear: { /** * Create a paragraph nearby. + * @example editor.commands.createParagraphNear() */ createParagraphNear: () => ReturnType } diff --git a/packages/core/src/commands/cut.ts b/packages/core/src/commands/cut.ts index 2a6ff7f3a6..3b60b33a72 100644 --- a/packages/core/src/commands/cut.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/deleteCurrentNode.ts b/packages/core/src/commands/deleteCurrentNode.ts index 5f5914dfe3..247f6cb75b 100644 --- a/packages/core/src/commands/deleteCurrentNode.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/deleteNode.ts b/packages/core/src/commands/deleteNode.ts index c1ddbecf01..fca4c9a826 100644 --- a/packages/core/src/commands/deleteNode.ts +++ b/packages/core/src/commands/deleteNode.ts @@ -7,7 +7,9 @@ declare module '@tiptap/core' { interface Commands { 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, } diff --git a/packages/core/src/commands/deleteRange.ts b/packages/core/src/commands/deleteRange.ts index 9c25a4c137..19a0723f85 100644 --- a/packages/core/src/commands/deleteRange.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/deleteSelection.ts b/packages/core/src/commands/deleteSelection.ts index a52b6b633b..61d751b1d9 100644 --- a/packages/core/src/commands/deleteSelection.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/enter.ts b/packages/core/src/commands/enter.ts index 5eb1e7265e..9693e0787c 100644 --- a/packages/core/src/commands/enter.ts +++ b/packages/core/src/commands/enter.ts @@ -5,6 +5,7 @@ declare module '@tiptap/core' { enter: { /** * Trigger enter. + * @example editor.commands.enter() */ enter: () => ReturnType, } diff --git a/packages/core/src/commands/exitCode.ts b/packages/core/src/commands/exitCode.ts index 5242b998bb..d288fee7e4 100644 --- a/packages/core/src/commands/exitCode.ts +++ b/packages/core/src/commands/exitCode.ts @@ -7,6 +7,7 @@ declare module '@tiptap/core' { exitCode: { /** * Exit from a code block. + * @example editor.commands.exitCode() */ exitCode: () => ReturnType } diff --git a/packages/core/src/commands/extendMarkRange.ts b/packages/core/src/commands/extendMarkRange.ts index 30e7c60a33..59a528fd70 100644 --- a/packages/core/src/commands/extendMarkRange.ts +++ b/packages/core/src/commands/extendMarkRange.ts @@ -9,10 +9,21 @@ declare module '@tiptap/core' { interface Commands { 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, ) => ReturnType } diff --git a/packages/core/src/commands/first.ts b/packages/core/src/commands/first.ts index cf686a770b..4819f288f8 100644 --- a/packages/core/src/commands/first.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/focus.ts b/packages/core/src/commands/focus.ts index c7f22ce5a7..edcb48ecb9 100644 --- a/packages/core/src/commands/focus.ts +++ b/packages/core/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, }, diff --git a/packages/core/src/commands/insertContent.ts b/packages/core/src/commands/insertContent.ts index 411213f9f7..37e9bb1481 100644 --- a/packages/core/src/commands/insertContent.ts +++ b/packages/core/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('

Example

') + * @example editor.commands.insertContent('

Example

', { 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 diff --git a/packages/core/src/commands/insertContentAt.ts b/packages/core/src/commands/insertContentAt.ts index 043b21c115..97232a12e8 100644 --- a/packages/core/src/commands/insertContentAt.ts +++ b/packages/core/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, '

Example

') */ 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 diff --git a/packages/core/src/commands/join.ts b/packages/core/src/commands/join.ts index 6e45f39ea2..b95d1ddfb3 100644 --- a/packages/core/src/commands/join.ts +++ b/packages/core/src/commands/join.ts @@ -11,25 +11,33 @@ declare module '@tiptap/core' { interface Commands { 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 } diff --git a/packages/core/src/commands/joinItemBackward.ts b/packages/core/src/commands/joinItemBackward.ts index 8a9b6434f9..bd64390db1 100644 --- a/packages/core/src/commands/joinItemBackward.ts +++ b/packages/core/src/commands/joinItemBackward.ts @@ -6,7 +6,8 @@ declare module '@tiptap/core' { interface Commands { joinItemBackward: { /** - * Join two nodes Forwards. + * Join two items backward. + * @example editor.commands.joinItemBackward() */ joinItemBackward: () => ReturnType } diff --git a/packages/core/src/commands/joinItemForward.ts b/packages/core/src/commands/joinItemForward.ts index ddcb196b96..fb84accde6 100644 --- a/packages/core/src/commands/joinItemForward.ts +++ b/packages/core/src/commands/joinItemForward.ts @@ -6,7 +6,8 @@ declare module '@tiptap/core' { interface Commands { joinItemForward: { /** - * Join two nodes Forwards. + * Join two items Forwards. + * @example editor.commands.joinItemForward() */ joinItemForward: () => ReturnType } diff --git a/packages/core/src/commands/keyboardShortcut.ts b/packages/core/src/commands/keyboardShortcut.ts index a9634f5784..f3686295e5 100644 --- a/packages/core/src/commands/keyboardShortcut.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/lift.ts b/packages/core/src/commands/lift.ts index 0ac6432df0..aef759f6b9 100644 --- a/packages/core/src/commands/lift.ts +++ b/packages/core/src/commands/lift.ts @@ -9,7 +9,11 @@ declare module '@tiptap/core' { interface Commands { 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) => ReturnType } diff --git a/packages/core/src/commands/liftEmptyBlock.ts b/packages/core/src/commands/liftEmptyBlock.ts index 1adfee5b2b..737610b3a8 100644 --- a/packages/core/src/commands/liftEmptyBlock.ts +++ b/packages/core/src/commands/liftEmptyBlock.ts @@ -6,7 +6,8 @@ declare module '@tiptap/core' { interface Commands { 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, } diff --git a/packages/core/src/commands/liftListItem.ts b/packages/core/src/commands/liftListItem.ts index ba9142f1c2..79910b17ba 100644 --- a/packages/core/src/commands/liftListItem.ts +++ b/packages/core/src/commands/liftListItem.ts @@ -8,7 +8,9 @@ declare module '@tiptap/core' { interface Commands { 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 } diff --git a/packages/core/src/commands/newlineInCode.ts b/packages/core/src/commands/newlineInCode.ts index 41e28648a9..d43a3e0af5 100644 --- a/packages/core/src/commands/newlineInCode.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/resetAttributes.ts b/packages/core/src/commands/resetAttributes.ts index df3918d9f4..b7a8bbd782 100644 --- a/packages/core/src/commands/resetAttributes.ts +++ b/packages/core/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, diff --git a/packages/core/src/commands/scrollIntoView.ts b/packages/core/src/commands/scrollIntoView.ts index efc66edfed..6eeb6a34bc 100644 --- a/packages/core/src/commands/scrollIntoView.ts +++ b/packages/core/src/commands/scrollIntoView.ts @@ -5,6 +5,7 @@ declare module '@tiptap/core' { scrollIntoView: { /** * Scroll the selection into view. + * @example editor.commands.scrollIntoView() */ scrollIntoView: () => ReturnType, } diff --git a/packages/core/src/commands/selectAll.ts b/packages/core/src/commands/selectAll.ts index 14cc9bb7b8..b29baa8b09 100644 --- a/packages/core/src/commands/selectAll.ts +++ b/packages/core/src/commands/selectAll.ts @@ -5,6 +5,7 @@ declare module '@tiptap/core' { selectAll: { /** * Select the whole document. + * @example editor.commands.selectAll() */ selectAll: () => ReturnType, } diff --git a/packages/core/src/commands/selectNodeBackward.ts b/packages/core/src/commands/selectNodeBackward.ts index 00a31fd305..937519b14c 100644 --- a/packages/core/src/commands/selectNodeBackward.ts +++ b/packages/core/src/commands/selectNodeBackward.ts @@ -7,6 +7,7 @@ declare module '@tiptap/core' { selectNodeBackward: { /** * Select a node backward. + * @example editor.commands.selectNodeBackward() */ selectNodeBackward: () => ReturnType } diff --git a/packages/core/src/commands/selectNodeForward.ts b/packages/core/src/commands/selectNodeForward.ts index 98f3551c66..84e60144a9 100644 --- a/packages/core/src/commands/selectNodeForward.ts +++ b/packages/core/src/commands/selectNodeForward.ts @@ -7,6 +7,7 @@ declare module '@tiptap/core' { selectNodeForward: { /** * Select a node forward. + * @example editor.commands.selectNodeForward() */ selectNodeForward: () => ReturnType } diff --git a/packages/core/src/commands/selectParentNode.ts b/packages/core/src/commands/selectParentNode.ts index eaed8b032e..35807258bb 100644 --- a/packages/core/src/commands/selectParentNode.ts +++ b/packages/core/src/commands/selectParentNode.ts @@ -7,6 +7,7 @@ declare module '@tiptap/core' { selectParentNode: { /** * Select the parent node. + * @example editor.commands.selectParentNode() */ selectParentNode: () => ReturnType } diff --git a/packages/core/src/commands/selectTextblockEnd.ts b/packages/core/src/commands/selectTextblockEnd.ts index 1893123bd9..f25ae46eb8 100644 --- a/packages/core/src/commands/selectTextblockEnd.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/selectTextblockStart.ts b/packages/core/src/commands/selectTextblockStart.ts index de122096a0..20bc76bc50 100644 --- a/packages/core/src/commands/selectTextblockStart.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/setContent.ts b/packages/core/src/commands/setContent.ts index 11cb11bf43..36fd75c3c9 100644 --- a/packages/core/src/commands/setContent.ts +++ b/packages/core/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('

Example text

') */ 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 } diff --git a/packages/core/src/commands/setMark.ts b/packages/core/src/commands/setMark.ts index 211369bb7c..d4a7e0dea8 100644 --- a/packages/core/src/commands/setMark.ts +++ b/packages/core/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) => ReturnType } diff --git a/packages/core/src/commands/setMeta.ts b/packages/core/src/commands/setMeta.ts index 56c89bf839..855a5d1ec0 100644 --- a/packages/core/src/commands/setMeta.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/setNode.ts b/packages/core/src/commands/setNode.ts index a3ad1d91ec..b48e1a3768 100644 --- a/packages/core/src/commands/setNode.ts +++ b/packages/core/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) => ReturnType } diff --git a/packages/core/src/commands/setNodeSelection.ts b/packages/core/src/commands/setNodeSelection.ts index 61aaf70bd6..80be01a83f 100644 --- a/packages/core/src/commands/setNodeSelection.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/setTextSelection.ts b/packages/core/src/commands/setTextSelection.ts index 077842b1b4..e8c8e1befe 100644 --- a/packages/core/src/commands/setTextSelection.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/sinkListItem.ts b/packages/core/src/commands/sinkListItem.ts index 111183b20c..74c80b6346 100644 --- a/packages/core/src/commands/sinkListItem.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/splitBlock.ts b/packages/core/src/commands/splitBlock.ts index f63c8f1587..483abb76c7 100644 --- a/packages/core/src/commands/splitBlock.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/splitListItem.ts b/packages/core/src/commands/splitListItem.ts index 3f08037e5c..d7323f483a 100644 --- a/packages/core/src/commands/splitListItem.ts +++ b/packages/core/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 } diff --git a/packages/core/src/commands/toggleList.ts b/packages/core/src/commands/toggleList.ts index 638fbe6782..226a88a8ab 100644 --- a/packages/core/src/commands/toggleList.ts +++ b/packages/core/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) => ReturnType; } diff --git a/packages/core/src/commands/toggleMark.ts b/packages/core/src/commands/toggleMark.ts index 7b2eb7eb83..f2abd58743 100644 --- a/packages/core/src/commands/toggleMark.ts +++ b/packages/core/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, + options?: { /** * Removes the mark even across the current selection. Defaults to `false`. diff --git a/packages/core/src/commands/toggleNode.ts b/packages/core/src/commands/toggleNode.ts index cbc4f6671e..0e24f861e6 100644 --- a/packages/core/src/commands/toggleNode.ts +++ b/packages/core/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, diff --git a/packages/core/src/commands/toggleWrap.ts b/packages/core/src/commands/toggleWrap.ts index b9638f3923..7ac387877a 100644 --- a/packages/core/src/commands/toggleWrap.ts +++ b/packages/core/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) => ReturnType } diff --git a/packages/core/src/commands/undoInputRule.ts b/packages/core/src/commands/undoInputRule.ts index 3c6f9b7c2e..741c5f8923 100644 --- a/packages/core/src/commands/undoInputRule.ts +++ b/packages/core/src/commands/undoInputRule.ts @@ -5,6 +5,7 @@ declare module '@tiptap/core' { undoInputRule: { /** * Undo an input rule. + * @example editor.commands.undoInputRule() */ undoInputRule: () => ReturnType, } diff --git a/packages/core/src/commands/unsetAllMarks.ts b/packages/core/src/commands/unsetAllMarks.ts index e3ae7ea239..5b472783fe 100644 --- a/packages/core/src/commands/unsetAllMarks.ts +++ b/packages/core/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, } diff --git a/packages/core/src/commands/unsetMark.ts b/packages/core/src/commands/unsetMark.ts index 1aef4b14b4..fd7ad19141 100644 --- a/packages/core/src/commands/unsetMark.ts +++ b/packages/core/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`. diff --git a/packages/core/src/commands/updateAttributes.ts b/packages/core/src/commands/updateAttributes.ts index 10b0d2e8e4..d6993b6d65 100644 --- a/packages/core/src/commands/updateAttributes.ts +++ b/packages/core/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, ) => ReturnType } diff --git a/packages/core/src/commands/wrapIn.ts b/packages/core/src/commands/wrapIn.ts index c9a0da169c..dd9dc6ae71 100644 --- a/packages/core/src/commands/wrapIn.ts +++ b/packages/core/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) => ReturnType } diff --git a/packages/core/src/commands/wrapInList.ts b/packages/core/src/commands/wrapInList.ts index 5140457f68..021b9e14bf 100644 --- a/packages/core/src/commands/wrapInList.ts +++ b/packages/core/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) => ReturnType } diff --git a/packages/core/src/inputRules/markInputRule.ts b/packages/core/src/inputRules/markInputRule.ts index 71dcd98d94..4e4c9aca9e 100644 --- a/packages/core/src/inputRules/markInputRule.ts +++ b/packages/core/src/inputRules/markInputRule.ts @@ -8,6 +8,7 @@ import { callOrReturn } from '../utilities/callOrReturn.js' /** * 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 */ export function markInputRule(config: { find: InputRuleFinder diff --git a/packages/core/src/inputRules/nodeInputRule.ts b/packages/core/src/inputRules/nodeInputRule.ts index b60f739975..2a8c88700f 100644 --- a/packages/core/src/inputRules/nodeInputRule.ts +++ b/packages/core/src/inputRules/nodeInputRule.ts @@ -7,6 +7,7 @@ import { callOrReturn } from '../utilities/callOrReturn.js' /** * 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 */ export function nodeInputRule(config: { /** diff --git a/packages/core/src/inputRules/textInputRule.ts b/packages/core/src/inputRules/textInputRule.ts index b9c1318b37..5d8c210f4c 100644 --- a/packages/core/src/inputRules/textInputRule.ts +++ b/packages/core/src/inputRules/textInputRule.ts @@ -3,6 +3,7 @@ import { InputRule, InputRuleFinder } from '../InputRule.js' /** * Build an input rule that replaces text when the * matched text is typed into it. + * @see https://tiptap.dev/guide/custom-extensions/#input-rules */ export function textInputRule(config: { find: InputRuleFinder, diff --git a/packages/core/src/inputRules/textblockTypeInputRule.ts b/packages/core/src/inputRules/textblockTypeInputRule.ts index 1abeb5a36d..60c4a60401 100644 --- a/packages/core/src/inputRules/textblockTypeInputRule.ts +++ b/packages/core/src/inputRules/textblockTypeInputRule.ts @@ -9,6 +9,7 @@ import { callOrReturn } from '../utilities/callOrReturn.js' * 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 */ export function textblockTypeInputRule(config: { find: InputRuleFinder diff --git a/packages/core/src/inputRules/wrappingInputRule.ts b/packages/core/src/inputRules/wrappingInputRule.ts index 8e39f74f4d..9148d0426d 100644 --- a/packages/core/src/inputRules/wrappingInputRule.ts +++ b/packages/core/src/inputRules/wrappingInputRule.ts @@ -19,6 +19,7 @@ import { callOrReturn } from '../utilities/callOrReturn.js' * 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 */ export function wrappingInputRule(config: { find: InputRuleFinder, diff --git a/packages/core/src/pasteRules/markPasteRule.ts b/packages/core/src/pasteRules/markPasteRule.ts index a95c437c6c..8e8bbb6c3c 100644 --- a/packages/core/src/pasteRules/markPasteRule.ts +++ b/packages/core/src/pasteRules/markPasteRule.ts @@ -8,6 +8,7 @@ import { callOrReturn } from '../utilities/callOrReturn.js' /** * 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 */ export function markPasteRule(config: { find: PasteRuleFinder diff --git a/packages/core/src/pasteRules/nodePasteRule.ts b/packages/core/src/pasteRules/nodePasteRule.ts index 4618a1a1ee..cad2b2b0a8 100644 --- a/packages/core/src/pasteRules/nodePasteRule.ts +++ b/packages/core/src/pasteRules/nodePasteRule.ts @@ -7,6 +7,7 @@ import { callOrReturn } from '../utilities/index.js' /** * 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 */ export function nodePasteRule(config: { find: PasteRuleFinder diff --git a/packages/core/src/pasteRules/textPasteRule.ts b/packages/core/src/pasteRules/textPasteRule.ts index ca8a645ec0..f7f67308d6 100644 --- a/packages/core/src/pasteRules/textPasteRule.ts +++ b/packages/core/src/pasteRules/textPasteRule.ts @@ -3,6 +3,7 @@ import { PasteRule, PasteRuleFinder } from '../PasteRule.js' /** * Build an paste rule that replaces text when the * matched text is pasted into it. + * @see https://tiptap.dev/guide/custom-extensions/#paste-rules */ export function textPasteRule(config: { find: PasteRuleFinder, diff --git a/packages/extension-blockquote/src/blockquote.ts b/packages/extension-blockquote/src/blockquote.ts index 4ff6a19d51..a0da895e19 100644 --- a/packages/extension-blockquote/src/blockquote.ts +++ b/packages/extension-blockquote/src/blockquote.ts @@ -1,6 +1,11 @@ import { mergeAttributes, Node, wrappingInputRule } from '@tiptap/core' export interface BlockquoteOptions { + /** + * HTML attributes to add to the blockquote element + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -23,8 +28,15 @@ declare module '@tiptap/core' { } } +/** + * Matches a blockquote to a `>` as input. + */ export const inputRegex = /^\s*>\s$/ +/** + * This extension allows you to create blockquotes. + * @see https://tiptap.dev/api/nodes/blockquote + */ export const Blockquote = Node.create({ name: 'blockquote', diff --git a/packages/extension-bold/src/bold.ts b/packages/extension-bold/src/bold.ts index 1ded5189a2..f3c6a2bb64 100644 --- a/packages/extension-bold/src/bold.ts +++ b/packages/extension-bold/src/bold.ts @@ -6,6 +6,11 @@ import { } from '@tiptap/core' export interface BoldOptions { + /** + * HTML attributes to add to the bold element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -28,11 +33,30 @@ declare module '@tiptap/core' { } } +/** + * Matches bold text via `**` as input. + */ export const starInputRegex = /(?:^|\s)(\*\*(?!\s+\*\*)((?:[^*]+))\*\*(?!\s+\*\*))$/ + +/** + * Matches bold text via `**` while pasting. + */ export const starPasteRegex = /(?:^|\s)(\*\*(?!\s+\*\*)((?:[^*]+))\*\*(?!\s+\*\*))/g + +/** + * Matches bold text via `__` as input. + */ export const underscoreInputRegex = /(?:^|\s)(__(?!\s+__)((?:[^_]+))__(?!\s+__))$/ + +/** + * Matches bold text via `__` while pasting. + */ export const underscorePasteRegex = /(?:^|\s)(__(?!\s+__)((?:[^_]+))__(?!\s+__))/g +/** + * This extension allows you to mark text as bold. + * @see https://tiptap.dev/api/marks/bold + */ export const Bold = Mark.create({ name: 'bold', diff --git a/packages/extension-bubble-menu/src/bubble-menu-plugin.ts b/packages/extension-bubble-menu/src/bubble-menu-plugin.ts index a92967b4c8..fc46c25425 100644 --- a/packages/extension-bubble-menu/src/bubble-menu-plugin.ts +++ b/packages/extension-bubble-menu/src/bubble-menu-plugin.ts @@ -6,11 +6,43 @@ import { EditorView } from '@tiptap/pm/view' import tippy, { Instance, Props } from 'tippy.js' export interface BubbleMenuPluginProps { + /** + * The plugin key. + * @type {PluginKey | string} + * @default 'bubbleMenu' + */ pluginKey: PluginKey | string + + /** + * The editor instance. + */ editor: Editor + + /** + * The DOM element that contains your menu. + * @type {HTMLElement} + * @default null + */ element: HTMLElement + + /** + * The options for the tippy.js instance. + * @see https://atomiks.github.io/tippyjs/v6/all-props/ + */ tippyOptions?: Partial + + /** + * The delay in milliseconds before the menu should be updated. + * This can be useful to prevent performance issues. + * @type {number} + * @default 250 + */ updateDelay?: number + + /** + * A function that determines whether the menu should be shown or not. + * If this function returns `false`, the menu will be hidden, otherwise it will be shown. + */ shouldShow?: | ((props: { editor: Editor diff --git a/packages/extension-bubble-menu/src/bubble-menu.ts b/packages/extension-bubble-menu/src/bubble-menu.ts index ba45d87d54..0897947738 100644 --- a/packages/extension-bubble-menu/src/bubble-menu.ts +++ b/packages/extension-bubble-menu/src/bubble-menu.ts @@ -3,9 +3,18 @@ import { Extension } from '@tiptap/core' import { BubbleMenuPlugin, BubbleMenuPluginProps } from './bubble-menu-plugin.js' export type BubbleMenuOptions = Omit & { + /** + * The DOM element that contains your menu. + * @type {HTMLElement} + * @default null + */ element: HTMLElement | null, } +/** + * This extension allows you to create a bubble menu. + * @see https://tiptap.dev/api/extensions/bubble-menu + */ export const BubbleMenu = Extension.create({ name: 'bubbleMenu', diff --git a/packages/extension-bullet-list/src/bullet-list.ts b/packages/extension-bullet-list/src/bullet-list.ts index 1bc8b99269..fe86ff1772 100644 --- a/packages/extension-bullet-list/src/bullet-list.ts +++ b/packages/extension-bullet-list/src/bullet-list.ts @@ -4,9 +4,32 @@ import ListItem from '../../extension-list-item/src/index.js' import TextStyle from '../../extension-text-style/src/index.js' export interface BulletListOptions { + /** + * The node name for the list items + * @default 'listItem' + * @example 'paragraph' + */ itemTypeName: string, + + /** + * HTML attributes to add to the bullet list element + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, + + /** + * Keep the marks when splitting the list + * @default false + * @example true + */ keepMarks: boolean, + + /** + * Keep the attributes when splitting the list + * @default false + * @example true + */ keepAttributes: boolean, } @@ -21,8 +44,17 @@ declare module '@tiptap/core' { } } +/** + * Matches a bullet list to a dash or asterisk. + */ export const inputRegex = /^\s*([-+*])\s$/ +/** + * This extension allows you to create bullet lists. + * This requires the ListItem extension + * @see https://tiptap.dev/api/nodes/bullet-list + * @see https://tiptap.dev/api/nodes/list-item. + */ export const BulletList = Node.create({ name: 'bulletList', diff --git a/packages/extension-character-count/src/character-count.ts b/packages/extension-character-count/src/character-count.ts index 587df25ed0..1108f4ca01 100644 --- a/packages/extension-character-count/src/character-count.ts +++ b/packages/extension-character-count/src/character-count.ts @@ -5,10 +5,15 @@ import { Plugin, PluginKey } from '@tiptap/pm/state' export interface CharacterCountOptions { /** * The maximum number of characters that should be allowed. Defaults to `0`. + * @default null + * @example 180 */ limit: number | null | undefined /** - * The mode by which the size is calculated. Defaults to 'textSize'. + * The mode by which the size is calculated. If set to `textSize`, the textContent of the document is used. + * If set to `nodeSize`, the nodeSize of the document is used. + * @default 'textSize' + * @example 'textSize' */ mode: 'textSize' | 'nodeSize' } @@ -16,15 +21,24 @@ export interface CharacterCountOptions { export interface CharacterCountStorage { /** * Get the number of characters for the current document. + * @param options The options for the character count. (optional) + * @param options.node The node to get the characters from. Defaults to the current document. + * @param options.mode The mode by which the size is calculated. If set to `textSize`, the textContent of the document is used. */ characters: (options?: { node?: ProseMirrorNode; mode?: 'textSize' | 'nodeSize' }) => number /** * Get the number of words for the current document. + * @param options The options for the character count. (optional) + * @param options.node The node to get the words from. Defaults to the current document. */ words: (options?: { node?: ProseMirrorNode }) => number } +/** + * This extension allows you to count the characters and words of your document. + * @see https://tiptap.dev/api/extensions/character-count + */ export const CharacterCount = Extension.create({ name: 'characterCount', diff --git a/packages/extension-code-block-lowlight/src/code-block-lowlight.ts b/packages/extension-code-block-lowlight/src/code-block-lowlight.ts index 55c5ddc2ae..c1eb4dcbfb 100644 --- a/packages/extension-code-block-lowlight/src/code-block-lowlight.ts +++ b/packages/extension-code-block-lowlight/src/code-block-lowlight.ts @@ -3,10 +3,23 @@ import CodeBlock, { CodeBlockOptions } from '@tiptap/extension-code-block' import { LowlightPlugin } from './lowlight-plugin.js' export interface CodeBlockLowlightOptions extends CodeBlockOptions { + /** + * The lowlight instance. + */ lowlight: any, + + /** + * The default language. + * @default null + * @example 'javascript' + */ defaultLanguage: string | null | undefined, } +/** + * This extension allows you to highlight code blocks with lowlight. + * @see https://tiptap.dev/api/nodes/code-block-lowlight + */ export const CodeBlockLowlight = CodeBlock.extend({ addOptions() { return { diff --git a/packages/extension-code-block/src/code-block.ts b/packages/extension-code-block/src/code-block.ts index ecb5a42e56..3c4a9f758d 100644 --- a/packages/extension-code-block/src/code-block.ts +++ b/packages/extension-code-block/src/code-block.ts @@ -4,21 +4,23 @@ import { Plugin, PluginKey, TextSelection } from '@tiptap/pm/state' export interface CodeBlockOptions { /** * Adds a prefix to language classes that are applied to code tags. - * Defaults to `'language-'`. + * @default 'language-' */ languageClassPrefix: string /** * Define whether the node should be exited on triple enter. - * Defaults to `true`. + * @default true */ exitOnTripleEnter: boolean /** * Define whether the node should be exited on arrow down if there is no node after it. - * Defaults to `true`. + * @default true */ exitOnArrowDown: boolean /** * Custom HTML attributes that should be added to the rendered HTML tag. + * @default {} + * @example { class: 'foo' } */ HTMLAttributes: Record } @@ -28,19 +30,34 @@ declare module '@tiptap/core' { codeBlock: { /** * Set a code block + * @param attributes Code block attributes + * @example editor.commands.setCodeBlock({ language: 'javascript' }) */ setCodeBlock: (attributes?: { language: string }) => ReturnType /** * Toggle a code block + * @param attributes Code block attributes + * @example editor.commands.toggleCodeBlock({ language: 'javascript' }) */ toggleCodeBlock: (attributes?: { language: string }) => ReturnType } } } +/** + * Matches a code block with backticks. + */ export const backtickInputRegex = /^```([a-z]+)?[\s\n]$/ + +/** + * Matches a code block with tildes. + */ export const tildeInputRegex = /^~~~([a-z]+)?[\s\n]$/ +/** + * This extension allows you to create code blocks. + * @see https://tiptap.dev/api/nodes/code-block + */ export const CodeBlock = Node.create({ name: 'codeBlock', diff --git a/packages/extension-code/src/code.ts b/packages/extension-code/src/code.ts index 9b7ce724a7..068804b512 100644 --- a/packages/extension-code/src/code.ts +++ b/packages/extension-code/src/code.ts @@ -6,6 +6,11 @@ import { } from '@tiptap/core' export interface CodeOptions { + /** + * The HTML attributes applied to the code element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -28,9 +33,20 @@ declare module '@tiptap/core' { } } +/** + * Matches inline code. + */ export const inputRegex = /(?:^|\s)(`(?!\s+`)((?:[^`]+))`(?!\s+`))$/ + +/** + * Matches inline code while pasting. + */ export const pasteRegex = /(?:^|\s)(`(?!\s+`)((?:[^`]+))`(?!\s+`))/g +/** + * This extension allows you to mark text as inline code. + * @see https://tiptap.dev/api/marks/code + */ export const Code = Mark.create({ name: 'code', diff --git a/packages/extension-collaboration-cursor/src/collaboration-cursor.ts b/packages/extension-collaboration-cursor/src/collaboration-cursor.ts index d8090cb4f3..ed17ad06f1 100644 --- a/packages/extension-collaboration-cursor/src/collaboration-cursor.ts +++ b/packages/extension-collaboration-cursor/src/collaboration-cursor.ts @@ -7,10 +7,53 @@ type CollaborationCursorStorage = { } export interface CollaborationCursorOptions { + /** + * The Hocuspocus provider instance. This can also be a TiptapCloudProvider instance. + * @type {HocuspocusProvider | TiptapCloudProvider} + * @example new HocuspocusProvider() + */ provider: any, + + /** + * The user details object – feel free to add properties to this object as needed + * @example { name: 'John Doe', color: '#305500' } + */ user: Record, + + /** + * A function that returns a DOM element for the cursor. + * @param user The user details object + * @example + * render: user => { + * const cursor = document.createElement('span') + * cursor.classList.add('collaboration-cursor__caret') + * cursor.setAttribute('style', `border-color: ${user.color}`) + * + * const label = document.createElement('div') + * label.classList.add('collaboration-cursor__label') + * label.setAttribute('style', `background-color: ${user.color}`) + * label.insertBefore(document.createTextNode(user.name), null) + * + * cursor.insertBefore(label, null) + * return cursor + * } + */ render (user: Record): HTMLElement, + + /** + * A function that returns a ProseMirror DecorationAttrs object for the selection. + * @param user The user details object + * @example + * selectionRender: user => { + * return { + * nodeName: 'span', + * class: 'collaboration-cursor__selection', + * style: `background-color: ${user.color}`, + * 'data-user': user.name, + * } + */ selectionRender (user: Record): DecorationAttrs + /** * @deprecated The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCursor.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-cursor */ @@ -22,6 +65,7 @@ declare module '@tiptap/core' { collaborationCursor: { /** * Update details of the current user + * @example editor.commands.updateUser({ name: 'John Doe', color: '#305500' }) */ updateUser: (attributes: Record) => ReturnType, /** @@ -45,6 +89,10 @@ const awarenessStatesToArray = (states: Map>) => { const defaultOnUpdate = () => null +/** + * This extension allows you to add collaboration cursors to your editor. + * @see https://tiptap.dev/api/extensions/collaboration-cursor + */ export const CollaborationCursor = Extension.create({ name: 'collaborationCursor', diff --git a/packages/extension-collaboration/src/collaboration.ts b/packages/extension-collaboration/src/collaboration.ts index 892441e3aa..e96fa5c3f5 100644 --- a/packages/extension-collaboration/src/collaboration.ts +++ b/packages/extension-collaboration/src/collaboration.ts @@ -16,10 +16,12 @@ declare module '@tiptap/core' { collaboration: { /** * Undo recent changes + * @example editor.commands.undo() */ undo: () => ReturnType, /** * Reapply reverted changes + * @example editor.commands.redo() */ redo: () => ReturnType, } @@ -29,16 +31,23 @@ declare module '@tiptap/core' { export interface CollaborationOptions { /** * An initialized Y.js document. + * @example new Y.Doc() */ document: any, + /** * Name of a Y.js fragment, can be changed to sync multiple fields with one Y.js document. + * @default 'default' + * @example 'my-custom-field' */ field: string, + /** * A raw Y.js fragment, can be used instead of `document` and `field`. + * @example new Y.Doc().getXmlFragment('body') */ fragment: any, + /** * Fired when the content from Yjs is initially rendered to Tiptap. */ @@ -47,6 +56,10 @@ export interface CollaborationOptions { ySyncOptions?: YSyncOpts } +/** + * This extension allows you to collaborate with others in real-time. + * @see https://tiptap.dev/api/extensions/collaboration + */ export const Collaboration = Extension.create({ name: 'collaboration', diff --git a/packages/extension-collaboration/src/helpers/isChangeOrigin.ts b/packages/extension-collaboration/src/helpers/isChangeOrigin.ts index 754b7fbf07..73cfa32907 100644 --- a/packages/extension-collaboration/src/helpers/isChangeOrigin.ts +++ b/packages/extension-collaboration/src/helpers/isChangeOrigin.ts @@ -1,6 +1,14 @@ import { Transaction } from '@tiptap/pm/state' import { ySyncPluginKey } from 'y-prosemirror' +/** + * Checks if a transaction was originated from a Yjs change. + * @param {Transaction} transaction - The transaction to check. + * @returns {boolean} - True if the transaction was originated from a Yjs change, false otherwise. + * @example + * const transaction = new Transaction(doc) + * const isOrigin = isChangeOrigin(transaction) // returns false + */ export function isChangeOrigin(transaction: Transaction): boolean { return !!transaction.getMeta(ySyncPluginKey) } diff --git a/packages/extension-color/src/color.ts b/packages/extension-color/src/color.ts index 7ccea3805e..cb55227741 100644 --- a/packages/extension-color/src/color.ts +++ b/packages/extension-color/src/color.ts @@ -3,6 +3,11 @@ import '@tiptap/extension-text-style' import { Extension } from '@tiptap/core' export type ColorOptions = { + /** + * The types where the color can be applied + * @default ['textStyle'] + * @example ['heading', 'paragraph'] + */ types: string[], } @@ -11,16 +16,24 @@ declare module '@tiptap/core' { color: { /** * Set the text color + * @param color The color to set + * @example editor.commands.setColor('red') */ setColor: (color: string) => ReturnType, + /** * Unset the text color + * @example editor.commands.unsetColor() */ unsetColor: () => ReturnType, } } } +/** + * This extension allows you to color your text. + * @see https://tiptap.dev/api/extensions/color + */ export const Color = Extension.create({ name: 'color', diff --git a/packages/extension-document/src/document.ts b/packages/extension-document/src/document.ts index 2046dc6548..ac636aa4b8 100644 --- a/packages/extension-document/src/document.ts +++ b/packages/extension-document/src/document.ts @@ -1,5 +1,9 @@ import { Node } from '@tiptap/core' +/** + * The default document node which represents the top level node of the editor. + * @see https://tiptap.dev/api/nodes/document + */ export const Document = Node.create({ name: 'doc', topNode: true, diff --git a/packages/extension-dropcursor/src/dropcursor.ts b/packages/extension-dropcursor/src/dropcursor.ts index 4cc0a4a20b..7a8358ee0a 100644 --- a/packages/extension-dropcursor/src/dropcursor.ts +++ b/packages/extension-dropcursor/src/dropcursor.ts @@ -2,11 +2,34 @@ import { Extension } from '@tiptap/core' import { dropCursor } from '@tiptap/pm/dropcursor' export interface DropcursorOptions { + /** + * The color of the drop cursor + * @default 'currentColor' + * @example 'red' + */ color: string | undefined, + + /** + * The width of the drop cursor + * @default 1 + * @example 2 + */ width: number | undefined, + + /** + * The class of the drop cursor + * @default undefined + * @example 'drop-cursor' + */ class: string | undefined, } +/** + * This extension allows you to add a drop cursor to your editor. + * A drop cursor is a line that appears when you drag and drop content + * inbetween nodes. + * @see https://tiptap.dev/api/extensions/dropcursor + */ export const Dropcursor = Extension.create({ name: 'dropCursor', diff --git a/packages/extension-floating-menu/src/floating-menu-plugin.ts b/packages/extension-floating-menu/src/floating-menu-plugin.ts index ed10798789..5db7d7a92a 100644 --- a/packages/extension-floating-menu/src/floating-menu-plugin.ts +++ b/packages/extension-floating-menu/src/floating-menu-plugin.ts @@ -4,10 +4,36 @@ import { EditorView } from '@tiptap/pm/view' import tippy, { Instance, Props } from 'tippy.js' export interface FloatingMenuPluginProps { + /** + * The plugin key for the floating menu. + * @default 'floatingMenu' + */ pluginKey: PluginKey | string + + /** + * The editor instance. + * @default null + */ editor: Editor + + /** + * The DOM element that contains your menu. + * @default null + */ element: HTMLElement + + /** + * The options for the tippy instance. + * @default {} + * @see https://atomiks.github.io/tippyjs/v6/all-props/ + */ tippyOptions?: Partial + + /** + * A function that determines whether the menu should be shown or not. + * If this function returns `false`, the menu will be hidden, otherwise it will be shown. + * @default null + */ shouldShow?: | ((props: { editor: Editor @@ -19,6 +45,9 @@ export interface FloatingMenuPluginProps { } export type FloatingMenuViewProps = FloatingMenuPluginProps & { + /** + * The editor view. + */ view: EditorView } diff --git a/packages/extension-floating-menu/src/floating-menu.ts b/packages/extension-floating-menu/src/floating-menu.ts index cd43952c93..891ce37131 100644 --- a/packages/extension-floating-menu/src/floating-menu.ts +++ b/packages/extension-floating-menu/src/floating-menu.ts @@ -3,9 +3,18 @@ import { Extension } from '@tiptap/core' import { FloatingMenuPlugin, FloatingMenuPluginProps } from './floating-menu-plugin.js' export type FloatingMenuOptions = Omit & { + /** + * The DOM element that contains your menu. + * @type {HTMLElement} + * @default null + */ element: HTMLElement | null, } +/** + * This extension allows you to create a floating menu. + * @see https://tiptap.dev/api/extensions/floating-menu + */ export const FloatingMenu = Extension.create({ name: 'floatingMenu', diff --git a/packages/extension-focus/src/focus.ts b/packages/extension-focus/src/focus.ts index 65e5e92442..12c8a51ba4 100644 --- a/packages/extension-focus/src/focus.ts +++ b/packages/extension-focus/src/focus.ts @@ -3,10 +3,30 @@ import { Plugin, PluginKey } from '@tiptap/pm/state' import { Decoration, DecorationSet } from '@tiptap/pm/view' export interface FocusOptions { + /** + * The class name that should be added to the focused node. + * @default 'has-focus' + * @example 'is-focused' + */ className: string + + /** + * The mode by which the focused node is determined. + * - All: All nodes are marked as focused. + * - Deepest: Only the deepest node is marked as focused. + * - Shallowest: Only the shallowest node is marked as focused. + * + * @default 'all' + * @example 'deepest' + * @example 'shallowest' + */ mode: 'all' | 'deepest' | 'shallowest' } +/** + * This extension allows you to add a class to the focused node. + * @see https://www.tiptap.dev/api/extensions/focus + */ export const FocusClasses = Extension.create({ name: 'focus', diff --git a/packages/extension-font-family/src/font-family.ts b/packages/extension-font-family/src/font-family.ts index da5f8488f3..4d85b06ec0 100644 --- a/packages/extension-font-family/src/font-family.ts +++ b/packages/extension-font-family/src/font-family.ts @@ -3,6 +3,11 @@ import '@tiptap/extension-text-style' import { Extension } from '@tiptap/core' export type FontFamilyOptions = { + /** + * A list of node names where the font family can be applied. + * @default ['textStyle'] + * @example ['heading', 'paragraph'] + */ types: string[], } @@ -11,16 +16,23 @@ declare module '@tiptap/core' { fontFamily: { /** * Set the font family + * @param fontFamily The font family + * @example editor.commands.setFontFamily('Arial') */ setFontFamily: (fontFamily: string) => ReturnType, /** * Unset the font family + * @example editor.commands.unsetFontFamily() */ unsetFontFamily: () => ReturnType, } } } +/** + * This extension allows you to set a font family for text. + * @see https://www.tiptap.dev/api/extensions/font-family + */ export const FontFamily = Extension.create({ name: 'fontFamily', diff --git a/packages/extension-gapcursor/src/gapcursor.ts b/packages/extension-gapcursor/src/gapcursor.ts index cabfc49e20..ba99152330 100644 --- a/packages/extension-gapcursor/src/gapcursor.ts +++ b/packages/extension-gapcursor/src/gapcursor.ts @@ -9,7 +9,8 @@ import { gapCursor } from '@tiptap/pm/gapcursor' declare module '@tiptap/core' { interface NodeConfig { /** - * Allow gap cursor + * A function to determine whether the gap cursor is allowed at the current position. Must return `true` or `false`. + * @default null */ allowGapCursor?: | boolean @@ -23,6 +24,12 @@ declare module '@tiptap/core' { } } +/** + * This extension allows you to add a gap cursor to your editor. + * A gap cursor is a cursor that appears when you click on a place + * where no content is present, for example inbetween nodes. + * @see https://tiptap.dev/api/extensions/gapcursor + */ export const Gapcursor = Extension.create({ name: 'gapCursor', diff --git a/packages/extension-hard-break/src/hard-break.ts b/packages/extension-hard-break/src/hard-break.ts index 34ff153767..6461faf5b5 100644 --- a/packages/extension-hard-break/src/hard-break.ts +++ b/packages/extension-hard-break/src/hard-break.ts @@ -1,7 +1,18 @@ import { mergeAttributes, Node } from '@tiptap/core' export interface HardBreakOptions { + /** + * Controls if marks should be kept after being split by a hard break. + * @default true + * @example false + */ keepMarks: boolean, + + /** + * HTML attributes to add to the hard break element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -10,12 +21,17 @@ declare module '@tiptap/core' { hardBreak: { /** * Add a hard break + * @example editor.commands.setHardBreak() */ setHardBreak: () => ReturnType, } } } +/** + * This extension allows you to insert hard breaks. + * @see https://www.tiptap.dev/api/nodes/hard-break + */ export const HardBreak = Node.create({ name: 'hardBreak', diff --git a/packages/extension-heading/src/heading.ts b/packages/extension-heading/src/heading.ts index cecde59f45..ff417a304d 100644 --- a/packages/extension-heading/src/heading.ts +++ b/packages/extension-heading/src/heading.ts @@ -1,9 +1,23 @@ import { mergeAttributes, Node, textblockTypeInputRule } from '@tiptap/core' +/** + * The heading level options. + */ export type Level = 1 | 2 | 3 | 4 | 5 | 6 export interface HeadingOptions { + /** + * The available heading levels. + * @default [1, 2, 3, 4, 5, 6] + * @example [1, 2, 3] + */ levels: Level[], + + /** + * The HTML attributes for a heading node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -12,16 +26,24 @@ declare module '@tiptap/core' { heading: { /** * Set a heading node + * @param attributes The heading attributes + * @example editor.commands.setHeading({ level: 1 }) */ setHeading: (attributes: { level: Level }) => ReturnType, /** * Toggle a heading node + * @param attributes The heading attributes + * @example editor.commands.toggleHeading({ level: 1 }) */ toggleHeading: (attributes: { level: Level }) => ReturnType, } } } +/** + * This extension allows you to create headings. + * @see https://www.tiptap.dev/api/nodes/heading + */ export const Heading = Node.create({ name: 'heading', diff --git a/packages/extension-highlight/src/highlight.ts b/packages/extension-highlight/src/highlight.ts index 89c806a6a1..05b9f7635b 100644 --- a/packages/extension-highlight/src/highlight.ts +++ b/packages/extension-highlight/src/highlight.ts @@ -6,7 +6,18 @@ import { } from '@tiptap/core' export interface HighlightOptions { + /** + * Allow multiple highlight colors + * @default false + * @example true + */ multicolor: boolean, + + /** + * HTML attributes to add to the highlight element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -15,23 +26,39 @@ declare module '@tiptap/core' { highlight: { /** * Set a highlight mark + * @param attributes The highlight attributes + * @example editor.commands.setHighlight({ color: 'red' }) */ setHighlight: (attributes?: { color: string }) => ReturnType, /** * Toggle a highlight mark + * @param attributes The highlight attributes + * @example editor.commands.toggleHighlight({ color: 'red' }) */ toggleHighlight: (attributes?: { color: string }) => ReturnType, /** * Unset a highlight mark + * @example editor.commands.unsetHighlight() */ unsetHighlight: () => ReturnType, } } } +/** + * Matches a highlight to a ==highlight== on input. + */ export const inputRegex = /(?:^|\s)(==(?!\s+==)((?:[^=]+))==(?!\s+==))$/ + +/** + * Matches a highlight to a ==highlight== on paste. + */ export const pasteRegex = /(?:^|\s)(==(?!\s+==)((?:[^=]+))==(?!\s+==))/g +/** + * This extension allows you to highlight text. + * @see https://www.tiptap.dev/api/marks/highlight + */ export const Highlight = Mark.create({ name: 'highlight', diff --git a/packages/extension-history/src/history.ts b/packages/extension-history/src/history.ts index b43cc75e5b..d19aeffffc 100644 --- a/packages/extension-history/src/history.ts +++ b/packages/extension-history/src/history.ts @@ -2,7 +2,18 @@ import { Extension } from '@tiptap/core' import { history, redo, undo } from '@tiptap/pm/history' export interface HistoryOptions { + /** + * The amount of history events that are collected before the oldest events are discarded. + * @default 100 + * @example 50 + */ depth: number, + + /** + * The delay (in milliseconds) between changes after which a new group should be started. + * @default 500 + * @example 1000 + */ newGroupDelay: number, } @@ -11,16 +22,27 @@ declare module '@tiptap/core' { history: { /** * Undo recent changes + * @example editor.commands.undo() */ undo: () => ReturnType, /** * Reapply reverted changes + * @example editor.commands.redo() */ redo: () => ReturnType, } } } +/** + * This extension allows you to undo and redo recent changes. + * @see https://www.tiptap.dev/api/extensions/history + * + * **Important**: If the `@tiptap/extension-collaboration` package is used, make sure to remove + * the `history` extension, as it is not compatible with the `collaboration` extension. + * + * `@tiptap/extension-collaboration` uses its own history implementation. + */ export const History = Extension.create({ name: 'history', diff --git a/packages/extension-horizontal-rule/src/horizontal-rule.ts b/packages/extension-horizontal-rule/src/horizontal-rule.ts index 7e94f6b3bd..a80e029688 100644 --- a/packages/extension-horizontal-rule/src/horizontal-rule.ts +++ b/packages/extension-horizontal-rule/src/horizontal-rule.ts @@ -2,6 +2,11 @@ import { mergeAttributes, Node, nodeInputRule } from '@tiptap/core' import { NodeSelection, TextSelection } from '@tiptap/pm/state' export interface HorizontalRuleOptions { + /** + * The HTML attributes for a horizontal rule node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record } @@ -10,12 +15,17 @@ declare module '@tiptap/core' { horizontalRule: { /** * Add a horizontal rule + * @example editor.commands.setHorizontalRule() */ setHorizontalRule: () => ReturnType } } } +/** + * This extension allows you to insert horizontal rules. + * @see https://www.tiptap.dev/api/nodes/horizontal-rule + */ export const HorizontalRule = Node.create({ name: 'horizontalRule', diff --git a/packages/extension-image/src/image.ts b/packages/extension-image/src/image.ts index d4547ca946..bb4f70dabf 100644 --- a/packages/extension-image/src/image.ts +++ b/packages/extension-image/src/image.ts @@ -5,8 +5,26 @@ import { } from '@tiptap/core' export interface ImageOptions { + /** + * Controls if the image node should be inline or not. + * @default false + * @example true + */ inline: boolean, + + /** + * Controls if base64 images are allowed. Enable this if you want to allow + * base64 image urls in the `src` attribute. + * @default false + * @example true + */ allowBase64: boolean, + + /** + * HTML attributes to add to the image element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -15,14 +33,26 @@ declare module '@tiptap/core' { image: { /** * Add an image + * @param options The image attributes + * @example + * editor + * .commands + * .setImage({ src: 'https://tiptap.dev/logo.png', alt: 'tiptap', title: 'tiptap logo' }) */ setImage: (options: { src: string, alt?: string, title?: string }) => ReturnType, } } } +/** + * Matches an image to a ![image](src "title") on input. + */ export const inputRegex = /(?:^|\s)(!\[(.+|:?)]\((\S+)(?:(?:\s+)["'](\S+)["'])?\))$/ +/** + * This extension allows you to insert images. + * @see https://www.tiptap.dev/api/nodes/image + */ export const Image = Node.create({ name: 'image', diff --git a/packages/extension-italic/src/italic.ts b/packages/extension-italic/src/italic.ts index 2e807404dd..6afc6b3288 100644 --- a/packages/extension-italic/src/italic.ts +++ b/packages/extension-italic/src/italic.ts @@ -6,6 +6,11 @@ import { } from '@tiptap/core' export interface ItalicOptions { + /** + * HTML attributes to add to the italic element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -14,25 +19,47 @@ declare module '@tiptap/core' { italic: { /** * Set an italic mark + * @example editor.commands.setItalic() */ setItalic: () => ReturnType, /** * Toggle an italic mark + * @example editor.commands.toggleItalic() */ toggleItalic: () => ReturnType, /** * Unset an italic mark + * @example editor.commands.unsetItalic() */ unsetItalic: () => ReturnType, } } } +/** + * Matches an italic to a *italic* on input. + */ export const starInputRegex = /(?:^|\s)(\*(?!\s+\*)((?:[^*]+))\*(?!\s+\*))$/ + +/** + * Matches an italic to a *italic* on paste. + */ export const starPasteRegex = /(?:^|\s)(\*(?!\s+\*)((?:[^*]+))\*(?!\s+\*))/g + +/** + * Matches an italic to a _italic_ on input. + */ export const underscoreInputRegex = /(?:^|\s)(_(?!\s+_)((?:[^_]+))_(?!\s+_))$/ + +/** + * Matches an italic to a _italic_ on paste. + */ export const underscorePasteRegex = /(?:^|\s)(_(?!\s+_)((?:[^_]+))_(?!\s+_))/g +/** + * This extension allows you to create italic text. + * @see https://www.tiptap.dev/api/marks/italic + */ export const Italic = Mark.create({ name: 'italic', diff --git a/packages/extension-link/src/helpers/autolink.ts b/packages/extension-link/src/helpers/autolink.ts index 05934e6b3d..adb451891a 100644 --- a/packages/extension-link/src/helpers/autolink.ts +++ b/packages/extension-link/src/helpers/autolink.ts @@ -36,13 +36,29 @@ type AutolinkOptions = { validate?: (url: string) => boolean } +/** + * This plugin allows you to automatically add links to your editor. + * @param options The plugin options + * @returns The plugin instance + */ export function autolink(options: AutolinkOptions): Plugin { return new Plugin({ key: new PluginKey('autolink'), appendTransaction: (transactions, oldState, newState) => { + /** + * Does the transaction change the document? + */ const docChanges = transactions.some(transaction => transaction.docChanged) && !oldState.doc.eq(newState.doc) + + /** + * Prevent autolink if the transaction is not a document change or if the transaction has the meta `preventAutolink`. + */ const preventAutolink = transactions.some(transaction => transaction.getMeta('preventAutolink')) + /** + * Prevent autolink if the transaction is not a document change + * or if the transaction has the meta `preventAutolink`. + */ if (!docChanges || preventAutolink) { return } diff --git a/packages/extension-link/src/link.ts b/packages/extension-link/src/link.ts index 8ef67ed97a..e3af421de6 100644 --- a/packages/extension-link/src/link.ts +++ b/packages/extension-link/src/link.ts @@ -9,7 +9,19 @@ import { clickHandler } from './helpers/clickHandler.js' import { pasteHandler } from './helpers/pasteHandler.js' export interface LinkProtocolOptions { + /** + * The protocol scheme to be registered. + * @default ''' + * @example 'ftp' + * @example 'git' + */ scheme: string; + + /** + * If enabled, it allows optional slashes after the protocol. + * @default false + * @example true + */ optionalSlashes?: boolean; } @@ -17,25 +29,40 @@ export const pasteRegex = /https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a export interface LinkOptions { /** - * If enabled, it adds links as you type. + * If enabled, the extension will automatically add links as you type. + * @default true + * @example false */ autolink: boolean + /** * An array of custom protocols to be registered with linkifyjs. + * @default [] + * @example ['ftp', 'git'] */ protocols: Array + /** * If enabled, links will be opened on click. + * @default true + * @example false + * @example 'whenNotEditable' */ openOnClick: boolean | 'whenNotEditable' /** * Adds a link to the current selection if the pasted content only contains an url. + * @default true + * @example false */ linkOnPaste: boolean + /** - * A list of HTML attributes to be rendered. + * HTML attributes to add to the link element. + * @default {} + * @example { class: 'foo' } */ HTMLAttributes: Record + /** * A validation function that modifies link verification for the auto linker. * @param url - The url to be validated. @@ -49,20 +76,29 @@ declare module '@tiptap/core' { link: { /** * Set a link mark + * @param attributes The link attributes + * @example editor.commands.setLink({ href: 'https://tiptap.dev' }) */ setLink: (attributes: { href: string; target?: string | null; rel?: string | null; class?: string | null }) => ReturnType /** * Toggle a link mark + * @param attributes The link attributes + * @example editor.commands.toggleLink({ href: 'https://tiptap.dev' }) */ toggleLink: (attributes: { href: string; target?: string | null; rel?: string | null; class?: string | null }) => ReturnType /** * Unset a link mark + * @example editor.commands.unsetLink() */ unsetLink: () => ReturnType } } } +/** + * This extension allows you to create links. + * @see https://www.tiptap.dev/api/marks/link + */ export const Link = Mark.create({ name: 'link', diff --git a/packages/extension-list-item/src/list-item.ts b/packages/extension-list-item/src/list-item.ts index cfbb526d04..d9d39613a9 100644 --- a/packages/extension-list-item/src/list-item.ts +++ b/packages/extension-list-item/src/list-item.ts @@ -1,11 +1,32 @@ import { mergeAttributes, Node } from '@tiptap/core' export interface ListItemOptions { + /** + * The HTML attributes for a list item node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, + + /** + * The node type for bulletList nodes + * @default 'bulletList' + * @example 'myCustomBulletList' + */ bulletListTypeName: string + + /** + * The node type for orderedList nodes + * @default 'orderedList' + * @example 'myCustomOrderedList' + */ orderedListTypeName: string } +/** + * This extension allows you to create list items. + * @see https://www.tiptap.dev/api/nodes/list-item + */ export const ListItem = Node.create({ name: 'listItem', diff --git a/packages/extension-list-keymap/src/list-keymap.ts b/packages/extension-list-keymap/src/list-keymap.ts index 7bada7d789..1c48d5fb77 100644 --- a/packages/extension-list-keymap/src/list-keymap.ts +++ b/packages/extension-list-keymap/src/list-keymap.ts @@ -3,12 +3,24 @@ import { Extension } from '@tiptap/core' import { handleBackspace, handleDelete } from './listHelpers/index.js' export type ListKeymapOptions = { + /** + * An array of list types. This is used for item and wrapper list matching. + * @default [] + * @example [{ itemName: 'listItem', wrapperNames: ['bulletList', 'orderedList'] }] + */ listTypes: Array<{ itemName: string, wrapperNames: string[], }> } +/** + * This extension registers custom keymaps to change the behaviour of the backspace and delete keys. + * By default Prosemirror keyhandling will always lift or sink items so paragraphs are joined into + * the adjacent or previous list item. This extension will prevent this behaviour and instead will + * try to join paragraphs from two list items into a single list item. + * @see https://www.tiptap.dev/api/extensions/list-keymap + */ export const ListKeymap = Extension.create({ name: 'listKeymap', diff --git a/packages/extension-mention/src/mention.ts b/packages/extension-mention/src/mention.ts index 5eaf4c4e54..701493f482 100644 --- a/packages/extension-mention/src/mention.ts +++ b/packages/extension-mention/src/mention.ts @@ -4,17 +4,62 @@ import { PluginKey } from '@tiptap/pm/state' import Suggestion, { SuggestionOptions } from '@tiptap/suggestion' export type MentionOptions = { + /** + * The HTML attributes for a mention node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record - /** @deprecated use renderText and renderHTML instead */ + + /** + * A function to render the label of a mention. + * @deprecated use renderText and renderHTML instead + * @param props The render props + * @returns The label + * @example ({ options, node }) => `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}` + */ renderLabel?: (props: { options: MentionOptions; node: ProseMirrorNode }) => string + + /** + * A function to render the text of a mention. + * @param props The render props + * @returns The text + * @example ({ options, node }) => `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}` + */ renderText: (props: { options: MentionOptions; node: ProseMirrorNode }) => string + + /** + * A function to render the HTML of a mention. + * @param props The render props + * @returns The HTML as a ProseMirror DOM Output Spec + * @example ({ options, node }) => ['span', { 'data-type': 'mention' }, `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`] + */ renderHTML: (props: { options: MentionOptions; node: ProseMirrorNode }) => DOMOutputSpec + + /** + * Whether to delete the trigger character with backspace. + * @default false + */ deleteTriggerWithBackspace: boolean + + /** + * The suggestion options. + * @default {} + * @example { char: '@', pluginKey: MentionPluginKey, command: ({ editor, range, props }) => { ... } } + */ suggestion: Omit } +/** + * The plugin key for the mention plugin. + * @default 'mention' + */ export const MentionPluginKey = new PluginKey('mention') +/** + * This extension allows you to insert mentions into the editor. + * @see https://www.tiptap.dev/api/extensions/mention + */ export const Mention = Node.create({ name: 'mention', diff --git a/packages/extension-ordered-list/src/ordered-list.ts b/packages/extension-ordered-list/src/ordered-list.ts index 6f70a89817..46679f96c3 100644 --- a/packages/extension-ordered-list/src/ordered-list.ts +++ b/packages/extension-ordered-list/src/ordered-list.ts @@ -4,9 +4,32 @@ import ListItem from '../../extension-list-item/src/index.js' import TextStyle from '../../extension-text-style/src/index.js' export interface OrderedListOptions { + /** + * The node type name for list items. + * @default 'listItem' + * @example 'myListItem' + */ itemTypeName: string, + + /** + * The HTML attributes for an ordered list node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, + + /** + * Keep the marks when splitting a list item. + * @default false + * @example true + */ keepMarks: boolean, + + /** + * Keep the attributes when splitting a list item. + * @default false + * @example true + */ keepAttributes: boolean, } @@ -15,14 +38,24 @@ declare module '@tiptap/core' { orderedList: { /** * Toggle an ordered list + * @example editor.commands.toggleOrderedList() */ toggleOrderedList: () => ReturnType, } } } +/** + * Matches an ordered list to a 1. on input (or any number followed by a dot). + */ export const inputRegex = /^(\d+)\.\s$/ +/** + * This extension allows you to create ordered lists. + * This requires the ListItem extension + * @see https://www.tiptap.dev/api/nodes/ordered-list + * @see https://www.tiptap.dev/api/nodes/list-item + */ export const OrderedList = Node.create({ name: 'orderedList', diff --git a/packages/extension-paragraph/src/paragraph.ts b/packages/extension-paragraph/src/paragraph.ts index 5f707511b1..d80355052c 100644 --- a/packages/extension-paragraph/src/paragraph.ts +++ b/packages/extension-paragraph/src/paragraph.ts @@ -1,6 +1,11 @@ import { mergeAttributes, Node } from '@tiptap/core' export interface ParagraphOptions { + /** + * The HTML attributes for a paragraph node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -9,12 +14,17 @@ declare module '@tiptap/core' { paragraph: { /** * Toggle a paragraph + * @example editor.commands.toggleParagraph() */ setParagraph: () => ReturnType, } } } +/** + * This extension allows you to create paragraphs. + * @see https://www.tiptap.dev/api/nodes/paragraph + */ export const Paragraph = Node.create({ name: 'paragraph', diff --git a/packages/extension-placeholder/src/placeholder.ts b/packages/extension-placeholder/src/placeholder.ts index cdbc20c66a..cf038a2b9a 100644 --- a/packages/extension-placeholder/src/placeholder.ts +++ b/packages/extension-placeholder/src/placeholder.ts @@ -68,6 +68,11 @@ export interface PlaceholderOptions { includeChildren: boolean } +/** + * This extension allows you to add a placeholder to your editor. + * A placeholder is a text that appears when the editor or a node is empty. + * @see https://www.tiptap.dev/api/extensions/placeholder + */ export const Placeholder = Extension.create({ name: 'placeholder', diff --git a/packages/extension-strike/src/strike.ts b/packages/extension-strike/src/strike.ts index d26fab6891..7d11ecdf3c 100644 --- a/packages/extension-strike/src/strike.ts +++ b/packages/extension-strike/src/strike.ts @@ -7,6 +7,11 @@ import { } from '@tiptap/core' export interface StrikeOptions { + /** + * HTML attributes to add to the strike element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -15,23 +20,37 @@ declare module '@tiptap/core' { strike: { /** * Set a strike mark + * @example editor.commands.setStrike() */ setStrike: () => ReturnType, /** * Toggle a strike mark + * @example editor.commands.toggleStrike() */ toggleStrike: () => ReturnType, /** * Unset a strike mark + * @example editor.commands.unsetStrike() */ unsetStrike: () => ReturnType, } } } +/** + * Matches a strike to a ~~strike~~ on input. + */ export const inputRegex = /(?:^|\s)(~~(?!\s+~~)((?:[^~]+))~~(?!\s+~~))$/ + +/** + * Matches a strike to a ~~strike~~ on paste. + */ export const pasteRegex = /(?:^|\s)(~~(?!\s+~~)((?:[^~]+))~~(?!\s+~~))/g +/** + * This extension allows you to create strike text. + * @see https://www.tiptap.dev/api/marks/strike + */ export const Strike = Mark.create({ name: 'strike', diff --git a/packages/extension-subscript/src/subscript.ts b/packages/extension-subscript/src/subscript.ts index f28851c926..d42f83f565 100644 --- a/packages/extension-subscript/src/subscript.ts +++ b/packages/extension-subscript/src/subscript.ts @@ -1,6 +1,11 @@ import { Mark, mergeAttributes } from '@tiptap/core' export interface SubscriptExtensionOptions { + /** + * HTML attributes to add to the subscript element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Object, } @@ -9,20 +14,27 @@ declare module '@tiptap/core' { subscript: { /** * Set a subscript mark + * @example editor.commands.setSubscript() */ setSubscript: () => ReturnType, /** * Toggle a subscript mark + * @example editor.commands.toggleSubscript() */ toggleSubscript: () => ReturnType, /** * Unset a subscript mark + * @example editor.commands.unsetSubscript() */ unsetSubscript: () => ReturnType, } } } +/** + * This extension allows you to create subscript text. + * @see https://www.tiptap.dev/api/marks/subscript + */ export const Subscript = Mark.create({ name: 'subscript', diff --git a/packages/extension-superscript/src/superscript.ts b/packages/extension-superscript/src/superscript.ts index d26bccaec5..9fce9cab2b 100644 --- a/packages/extension-superscript/src/superscript.ts +++ b/packages/extension-superscript/src/superscript.ts @@ -1,6 +1,11 @@ import { Mark, mergeAttributes } from '@tiptap/core' export interface SuperscriptExtensionOptions { + /** + * HTML attributes to add to the superscript element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Object, } @@ -9,20 +14,27 @@ declare module '@tiptap/core' { superscript: { /** * Set a superscript mark + * @example editor.commands.setSuperscript() */ setSuperscript: () => ReturnType, /** * Toggle a superscript mark + * @example editor.commands.toggleSuperscript() */ toggleSuperscript: () => ReturnType, /** * Unset a superscript mark + * @example editor.commands.unsetSuperscript() */ unsetSuperscript: () => ReturnType, } } } +/** + * This extension allows you to create superscript text. + * @see https://www.tiptap.dev/api/marks/superscript + */ export const Superscript = Mark.create({ name: 'superscript', diff --git a/packages/extension-table-cell/src/table-cell.ts b/packages/extension-table-cell/src/table-cell.ts index 08d0b9d6af..852c64fd63 100644 --- a/packages/extension-table-cell/src/table-cell.ts +++ b/packages/extension-table-cell/src/table-cell.ts @@ -1,9 +1,18 @@ import { mergeAttributes, Node } from '@tiptap/core' export interface TableCellOptions { + /** + * The HTML attributes for a table cell node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } +/** + * This extension allows you to create table cells. + * @see https://www.tiptap.dev/api/nodes/table-cell + */ export const TableCell = Node.create({ name: 'tableCell', diff --git a/packages/extension-table-header/src/table-header.ts b/packages/extension-table-header/src/table-header.ts index b7ba9faabc..4c6ce447df 100644 --- a/packages/extension-table-header/src/table-header.ts +++ b/packages/extension-table-header/src/table-header.ts @@ -1,8 +1,18 @@ import { mergeAttributes, Node } from '@tiptap/core' export interface TableHeaderOptions { + /** + * The HTML attributes for a table header node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } + +/** + * This extension allows you to create table headers. + * @see https://www.tiptap.dev/api/nodes/table-header + */ export const TableHeader = Node.create({ name: 'tableHeader', diff --git a/packages/extension-table-row/src/table-row.ts b/packages/extension-table-row/src/table-row.ts index 03356b880c..c5afa60ca6 100644 --- a/packages/extension-table-row/src/table-row.ts +++ b/packages/extension-table-row/src/table-row.ts @@ -1,9 +1,18 @@ import { mergeAttributes, Node } from '@tiptap/core' export interface TableRowOptions { + /** + * The HTML attributes for a table row node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } +/** + * This extension allows you to create table rows. + * @see https://www.tiptap.dev/api/nodes/table-row + */ export const TableRow = Node.create({ name: 'tableRow', diff --git a/packages/extension-table/src/table.ts b/packages/extension-table/src/table.ts index 3f871a85c4..bb9a38454d 100644 --- a/packages/extension-table/src/table.ts +++ b/packages/extension-table/src/table.ts @@ -30,47 +30,206 @@ import { createTable } from './utilities/createTable.js' import { deleteTableWhenAllCellsSelected } from './utilities/deleteTableWhenAllCellsSelected.js' export interface TableOptions { + /** + * HTML attributes for the table element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record + + /** + * Enables the resizing of tables. + * @default false + * @example true + */ resizable: boolean + + /** + * The width of the resize handle. + * @default 5 + * @example 10 + */ handleWidth: number + + /** + * The minimum width of a cell. + * @default 25 + * @example 50 + */ cellMinWidth: number + + /** + * The node view to render the table. + * @default TableView + */ View: NodeView + + /** + * Enables the resizing of the last column. + * @default true + * @example false + */ lastColumnResizable: boolean + + /** + * Allow table node selection. + * @default false + * @example true + */ allowTableNodeSelection: boolean } declare module '@tiptap/core' { interface Commands { table: { + /** + * Insert a table + * @param options The table attributes + * @returns True if the command was successful, otherwise false + * @example editor.commands.insertTable({ rows: 3, cols: 3, withHeaderRow: true }) + */ insertTable: (options?: { rows?: number cols?: number withHeaderRow?: boolean }) => ReturnType + + /** + * Add a column before the current column + * @returns True if the command was successful, otherwise false + * @example editor.commands.addColumnBefore() + */ addColumnBefore: () => ReturnType + + /** + * Add a column after the current column + * @returns True if the command was successful, otherwise false + * @example editor.commands.addColumnAfter() + */ addColumnAfter: () => ReturnType + + /** + * Delete the current column + * @returns True if the command was successful, otherwise false + * @example editor.commands.deleteColumn() + */ deleteColumn: () => ReturnType + + /** + * Add a row before the current row + * @returns True if the command was successful, otherwise false + * @example editor.commands.addRowBefore() + */ addRowBefore: () => ReturnType + + /** + * Add a row after the current row + * @returns True if the command was successful, otherwise false + * @example editor.commands.addRowAfter() + */ addRowAfter: () => ReturnType + + /** + * Delete the current row + * @returns True if the command was successful, otherwise false + * @example editor.commands.deleteRow() + */ deleteRow: () => ReturnType + + /** + * Delete the current table + * @returns True if the command was successful, otherwise false + * @example editor.commands.deleteTable() + */ deleteTable: () => ReturnType + + /** + * Merge the currently selected cells + * @returns True if the command was successful, otherwise false + * @example editor.commands.mergeCells() + */ mergeCells: () => ReturnType + + /** + * Split the currently selected cell + * @returns True if the command was successful, otherwise false + * @example editor.commands.splitCell() + */ splitCell: () => ReturnType + + /** + * Toggle the header column + * @returns True if the command was successful, otherwise false + * @example editor.commands.toggleHeaderColumn() + */ toggleHeaderColumn: () => ReturnType + + /** + * Toggle the header row + * @returns True if the command was successful, otherwise false + * @example editor.commands.toggleHeaderRow() + */ toggleHeaderRow: () => ReturnType + + /** + * Toggle the header cell + * @returns True if the command was successful, otherwise false + * @example editor.commands.toggleHeaderCell() + */ toggleHeaderCell: () => ReturnType + + /** + * Merge or split the currently selected cells + * @returns True if the command was successful, otherwise false + * @example editor.commands.mergeOrSplit() + */ mergeOrSplit: () => ReturnType + + /** + * Set a cell attribute + * @param name The attribute name + * @param value The attribute value + * @returns True if the command was successful, otherwise false + * @example editor.commands.setCellAttribute('align', 'right') + */ setCellAttribute: (name: string, value: any) => ReturnType + + /** + * Moves the selection to the next cell + * @returns True if the command was successful, otherwise false + * @example editor.commands.goToNextCell() + */ goToNextCell: () => ReturnType + + /** + * Moves the selection to the previous cell + * @returns True if the command was successful, otherwise false + * @example editor.commands.goToPreviousCell() + */ goToPreviousCell: () => ReturnType + + /** + * Try to fix the table structure if necessary + * @returns True if the command was successful, otherwise false + * @example editor.commands.fixTables() + */ fixTables: () => ReturnType + + /** + * Set a cell selection inside the current table + * @param position The cell position + * @returns True if the command was successful, otherwise false + * @example editor.commands.setCellSelection({ anchorCell: 1, headCell: 2 }) + */ setCellSelection: (position: { anchorCell: number; headCell?: number }) => ReturnType } } interface NodeConfig { /** - * Table Role + * A string or function to determine the role of the table. + * @default 'table' + * @example () => 'table' */ tableRole?: | string @@ -83,6 +242,10 @@ declare module '@tiptap/core' { } } +/** + * This extension allows you to create tables. + * @see https://www.tiptap.dev/api/nodes/table + */ export const Table = Node.create({ name: 'table', diff --git a/packages/extension-task-item/src/task-item.ts b/packages/extension-task-item/src/task-item.ts index 0874777cff..05c9d03451 100644 --- a/packages/extension-task-item/src/task-item.ts +++ b/packages/extension-task-item/src/task-item.ts @@ -4,14 +4,45 @@ import { import { Node as ProseMirrorNode } from '@tiptap/pm/model' export interface TaskItemOptions { + /** + * A callback function that is called when the checkbox is clicked while the editor is in readonly mode. + * @param node The prosemirror node of the task item + * @param checked The new checked state + * @returns boolean + */ onReadOnlyChecked?: (node: ProseMirrorNode, checked: boolean) => boolean + + /** + * Controls whether the task items can be nested or not. + * @default false + * @example true + */ nested: boolean + + /** + * HTML attributes to add to the task item element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record + + /** + * The node type for taskList nodes + * @default 'taskList' + * @example 'myCustomTaskList' + */ taskListTypeName: string } +/** + * Matches a task item to a - [ ] on input. + */ export const inputRegex = /^\s*(\[([( |x])?\])\s$/ +/** + * This extension allows you to create task items. + * @see https://www.tiptap.dev/api/nodes/task-item + */ export const TaskItem = Node.create({ name: 'taskItem', diff --git a/packages/extension-task-list/src/task-list.ts b/packages/extension-task-list/src/task-list.ts index 7e752bc879..b4d4fade60 100644 --- a/packages/extension-task-list/src/task-list.ts +++ b/packages/extension-task-list/src/task-list.ts @@ -1,7 +1,18 @@ import { mergeAttributes, Node } from '@tiptap/core' export interface TaskListOptions { + /** + * The node type name for a task item. + * @default 'taskItem' + * @example 'myCustomTaskItem' + */ itemTypeName: string, + + /** + * The HTML attributes for a task list node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -10,12 +21,17 @@ declare module '@tiptap/core' { taskList: { /** * Toggle a task list + * @example editor.commands.toggleTaskList() */ toggleTaskList: () => ReturnType, } } } +/** + * This extension allows you to create task lists. + * @see https://www.tiptap.dev/api/nodes/task-list + */ export const TaskList = Node.create({ name: 'taskList', diff --git a/packages/extension-text-align/src/text-align.ts b/packages/extension-text-align/src/text-align.ts index d9cc3a09b3..b6ef89aec2 100644 --- a/packages/extension-text-align/src/text-align.ts +++ b/packages/extension-text-align/src/text-align.ts @@ -1,8 +1,25 @@ import { Extension } from '@tiptap/core' export interface TextAlignOptions { + /** + * The types where the text align attribute can be applied. + * @default [] + * @example ['heading', 'paragraph'] + */ types: string[], + + /** + * The alignments which are allowed. + * @default ['left', 'center', 'right', 'justify'] + * @example ['left', 'right'] + */ alignments: string[], + + /** + * The default alignment. + * @default 'left' + * @example 'center' + */ defaultAlignment: string, } @@ -11,16 +28,23 @@ declare module '@tiptap/core' { textAlign: { /** * Set the text align attribute + * @param alignment The alignment + * @example editor.commands.setTextAlign('left') */ setTextAlign: (alignment: string) => ReturnType, /** * Unset the text align attribute + * @example editor.commands.unsetTextAlign() */ unsetTextAlign: () => ReturnType, } } } +/** + * This extension allows you to align text. + * @see https://www.tiptap.dev/api/extensions/text-align + */ export const TextAlign = Extension.create({ name: 'textAlign', diff --git a/packages/extension-text-style/src/text-style.ts b/packages/extension-text-style/src/text-style.ts index 23e09e5294..90c30d4d7a 100644 --- a/packages/extension-text-style/src/text-style.ts +++ b/packages/extension-text-style/src/text-style.ts @@ -5,6 +5,11 @@ import { } from '@tiptap/core' export interface TextStyleOptions { + /** + * HTML attributes to add to the span element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -13,12 +18,18 @@ declare module '@tiptap/core' { textStyle: { /** * Remove spans without inline style attributes. + * @example editor.commands.removeEmptyTextStyle() */ removeEmptyTextStyle: () => ReturnType, } } } +/** + * This extension allows you to create text styles. It is required by default + * for the `textColor` and `backgroundColor` extensions. + * @see https://www.tiptap.dev/api/marks/text-style + */ export const TextStyle = Mark.create({ name: 'textStyle', diff --git a/packages/extension-text/src/text.ts b/packages/extension-text/src/text.ts index 0755d5e7a4..2a5c90735d 100644 --- a/packages/extension-text/src/text.ts +++ b/packages/extension-text/src/text.ts @@ -1,5 +1,9 @@ import { Node } from '@tiptap/core' +/** + * This extension allows you to create text nodes. + * @see https://www.tiptap.dev/api/nodes/text + */ export const Text = Node.create({ name: 'text', group: 'inline', diff --git a/packages/extension-typography/src/typography.ts b/packages/extension-typography/src/typography.ts index 1c37644df8..cf424be161 100644 --- a/packages/extension-typography/src/typography.ts +++ b/packages/extension-typography/src/typography.ts @@ -1,27 +1,136 @@ import { Extension, textInputRule } from '@tiptap/core' export interface TypographyOptions { + /** + * The em dash character. + * @default '—' + */ emDash: false | string, + + /** + * The ellipsis character. + * @default '…' + */ ellipsis: false | string, + + /** + * The open double quote character. + * @default '“' + */ openDoubleQuote: false | string, + + /** + * The close double quote character. + * @default '”' + */ closeDoubleQuote: false | string, + + /** + * The open single quote character. + * @default '‘' + */ openSingleQuote: false | string, + + /** + * The close single quote character. + * @default '’' + */ closeSingleQuote: false | string, + + /** + * The left arrow character. + * @default '←' + */ leftArrow: false | string, + + /** + * The right arrow character. + * @default '→' + */ rightArrow: false | string, + + /** + * The copyright character. + * @default '©' + */ copyright: false | string, + + /** + * The trademark character. + * @default '™' + */ trademark: false | string, + + /** + * The servicemark character. + * @default '℠' + */ servicemark: false | string, + + /** + * The registered trademark character. + * @default '®' + */ registeredTrademark: false | string, + + /** + * The one half character. + * @default '½' + */ oneHalf: false | string, + + /** + * The plus minus character. + * @default '±' + */ plusMinus: false | string, + + /** + * The not equal character. + * @default '≠' + */ notEqual: false | string, + + /** + * The laquo character. + * @default '«' + */ laquo: false | string, + + /** + * The raquo character. + * @default '»' + */ raquo: false | string, + + /** + * The multiplication character. + * @default '×' + */ multiplication: false | string, + + /** + * The superscript two character. + * @default '²' + */ superscriptTwo: false | string, + + /** + * The superscript three character. + * @default '³' + */ superscriptThree: false | string, + + /** + * The one quarter character. + * @default '¼' + */ oneQuarter: false | string, + + /** + * The three quarters character. + * @default '¾' + */ threeQuarters: false | string, } @@ -135,9 +244,40 @@ export const threeQuarters = (override?: string) => textInputRule({ replace: override ?? '¾', }) +/** + * This extension allows you to add typography replacements for specific characters. + * @see https://www.tiptap.dev/api/extensions/typography + */ export const Typography = Extension.create({ name: 'typography', + addOptions() { + return { + closeDoubleQuote: '”', + closeSingleQuote: '’', + copyright: '©', + ellipsis: '…', + emDash: '—', + laquo: '«', + leftArrow: '←', + multiplication: '×', + notEqual: '≠', + oneHalf: '½', + oneQuarter: '¼', + openDoubleQuote: '“', + openSingleQuote: '‘', + plusMinus: '±', + raquo: '»', + registeredTrademark: '®', + rightArrow: '→', + servicemark: '℠', + superscriptThree: '³', + superscriptTwo: '²', + threeQuarters: '¾', + trademark: '™', + } + }, + addInputRules() { const rules = [] diff --git a/packages/extension-underline/src/underline.ts b/packages/extension-underline/src/underline.ts index 0e55734694..046670cc98 100644 --- a/packages/extension-underline/src/underline.ts +++ b/packages/extension-underline/src/underline.ts @@ -1,6 +1,11 @@ import { Mark, mergeAttributes } from '@tiptap/core' export interface UnderlineOptions { + /** + * HTML attributes to add to the underline element. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record, } @@ -9,20 +14,27 @@ declare module '@tiptap/core' { underline: { /** * Set an underline mark + * @example editor.commands.setUnderline() */ setUnderline: () => ReturnType, /** * Toggle an underline mark + * @example editor.commands.toggleUnderline() */ toggleUnderline: () => ReturnType, /** * Unset an underline mark + * @example editor.commands.unsetUnderline() */ unsetUnderline: () => ReturnType, } } } +/** + * This extension allows you to create underline text. + * @see https://www.tiptap.dev/api/marks/underline + */ export const Underline = Mark.create({ name: 'underline', diff --git a/packages/extension-youtube/src/youtube.ts b/packages/extension-youtube/src/youtube.ts index c680a0631a..3ddc279ed9 100644 --- a/packages/extension-youtube/src/youtube.ts +++ b/packages/extension-youtube/src/youtube.ts @@ -3,29 +3,157 @@ import { mergeAttributes, Node, nodePasteRule } from '@tiptap/core' import { getEmbedUrlFromYoutubeUrl, isValidYoutubeUrl, YOUTUBE_REGEX_GLOBAL } from './utils.js' export interface YoutubeOptions { + /** + * Controls if the paste handler for youtube videos should be added. + * @default true + * @example false + */ addPasteHandler: boolean; + + /** + * Controls if the youtube video should be allowed to go fullscreen. + * @default true + * @example false + */ allowFullscreen: boolean; + + /** + * Controls if the youtube video should autoplay. + * @default false + * @example true + */ autoplay: boolean; + + /** + * The language of the captions shown in the youtube video. + * @default undefined + * @example 'en' + */ ccLanguage?: string; + + /** + * Controls if the captions should be shown in the youtube video. + * @default undefined + * @example true + */ ccLoadPolicy?: boolean; + + /** + * Controls if the controls should be shown in the youtube video. + * @default true + * @example false + */ controls: boolean; + + /** + * Controls if the keyboard controls should be disabled in the youtube video. + * @default false + * @example true + */ disableKBcontrols: boolean; + + /** + * Controls if the iframe api should be enabled in the youtube video. + * @default false + * @example true + */ enableIFrameApi: boolean; + + /** + * The end time of the youtube video. + * @default 0 + * @example 120 + */ endTime: number; + + /** + * The height of the youtube video. + * @default 480 + * @example 720 + */ height: number; + + /** + * The language of the youtube video. + * @default undefined + * @example 'en' + */ interfaceLanguage?: string; + + /** + * Controls if the video annotations should be shown in the youtube video. + * @default 0 + * @example 1 + */ ivLoadPolicy: number; + + /** + * Controls if the youtube video should loop. + * @default false + * @example true + */ loop: boolean; + + /** + * Controls if the youtube video should show a small youtube logo. + * @default false + * @example true + */ modestBranding: boolean; + + /** + * The HTML attributes for a youtube video node. + * @default {} + * @example { class: 'foo' } + */ HTMLAttributes: Record; + + /** + * Controls if the youtube node should be inline or not. + * @default false + * @example true + */ inline: boolean; + + /** + * Controls if the youtube video should be loaded from youtube-nocookie.com. + * @default false + * @example true + */ nocookie: boolean; + + /** + * The origin of the youtube video. + * @default '' + * @example 'https://tiptap.dev' + */ origin: string; + + /** + * The playlist of the youtube video. + * @default '' + * @example 'PLQg6GaokU5CwiVmsZ0dZm6VeIg0V5z1tK' + */ playlist: string; + + /** + * The color of the youtube video progress bar. + * @default undefined + * @example 'red' + */ progressBarColor?: string; + + /** + * The width of the youtube video. + * @default 640 + * @example 1280 + */ width: number; } +/** + * The options for setting a youtube video. + */ type SetYoutubeVideoOptions = { src: string, width?: number, height?: number, start?: number } declare module '@tiptap/core' { @@ -33,12 +161,18 @@ declare module '@tiptap/core' { youtube: { /** * Insert a youtube video + * @param options The youtube video attributes + * @example editor.commands.setYoutubeVideo({ src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' }) */ setYoutubeVideo: (options: SetYoutubeVideoOptions) => ReturnType, } } } +/** + * This extension adds support for youtube videos. + * @see https://www.tiptap.dev/api/nodes/youtube + */ export const Youtube = Node.create({ name: 'youtube', diff --git a/packages/html/src/generateHTML.ts b/packages/html/src/generateHTML.ts index dc011e7920..27abd938a0 100644 --- a/packages/html/src/generateHTML.ts +++ b/packages/html/src/generateHTML.ts @@ -3,6 +3,29 @@ import { Node } from '@tiptap/pm/model' import { getHTMLFromFragment } from './getHTMLFromFragment.js' +/** + * Generates HTML from a ProseMirror JSON content object. + * @param doc - The ProseMirror JSON content object. + * @param extensions - The Tiptap extensions used to build the schema. + * @returns The generated HTML string. + * @example + * const doc = { + * type: 'doc', + * content: [ + * { + * type: 'paragraph', + * content: [ + * { + * type: 'text', + * text: 'Hello world!' + * } + * ] + * } + * ] + * } + * const extensions = [...] + * const html = generateHTML(doc, extensions) + */ export function generateHTML(doc: JSONContent, extensions: Extensions): string { const schema = getSchema(extensions) const contentNode = Node.fromJSON(schema, doc) diff --git a/packages/html/src/generateJSON.ts b/packages/html/src/generateJSON.ts index 63ec8e9617..babf983d9b 100644 --- a/packages/html/src/generateJSON.ts +++ b/packages/html/src/generateJSON.ts @@ -2,6 +2,17 @@ import { Extensions, getSchema } from '@tiptap/core' import { DOMParser } from '@tiptap/pm/model' import { parseHTML } from 'zeed-dom' +/** + * Generates a JSON object from the given HTML string and converts it into a Prosemirror node with content. + * @param {string} html - The HTML string to be converted into a Prosemirror node. + * @param {Extensions} extensions - The extensions to be used for generating the schema. + * @returns {Record} - The generated JSON object. + * @example + * const html = '

Hello, world!

' + * const extensions = [...] + * const json = generateJSON(html, extensions) + * console.log(json) // { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hello, world!' }] }] } + */ export function generateJSON(html: string, extensions: Extensions): Record { const schema = getSchema(extensions) const dom = parseHTML(html) as unknown as Node diff --git a/packages/html/src/getHTMLFromFragment.ts b/packages/html/src/getHTMLFromFragment.ts index f625e7b77d..5d7badc6cb 100644 --- a/packages/html/src/getHTMLFromFragment.ts +++ b/packages/html/src/getHTMLFromFragment.ts @@ -1,6 +1,18 @@ import { DOMSerializer, Node, Schema } from '@tiptap/pm/model' import { createHTMLDocument, VHTMLDocument } from 'zeed-dom' +/** + * Returns the HTML string representation of a given document node. + * + * @param doc - The document node to serialize. + * @param schema - The Prosemirror schema to use for serialization. + * @returns The HTML string representation of the document fragment. + * + * @example + * ```typescript + * const html = getHTMLFromFragment(doc, schema) + * ``` + */ export function getHTMLFromFragment(doc: Node, schema: Schema, options?: { document?: Document }): string { if (options?.document) { // The caller is relying on their own document implementation. Use this diff --git a/packages/react/src/ReactRenderer.tsx b/packages/react/src/ReactRenderer.tsx index 3151d39b30..4fde17bca3 100644 --- a/packages/react/src/ReactRenderer.tsx +++ b/packages/react/src/ReactRenderer.tsx @@ -3,6 +3,11 @@ import React from 'react' import { Editor as ExtendedEditor } from './Editor.js' +/** + * Check if a component is a class component. + * @param Component + * @returns {boolean} + */ function isClassComponent(Component: any) { return !!( typeof Component === 'function' @@ -11,6 +16,11 @@ function isClassComponent(Component: any) { ) } +/** + * Check if a component is a forward ref component. + * @param Component + * @returns {boolean} + */ function isForwardRefComponent(Component: any) { return !!( typeof Component === 'object' @@ -19,10 +29,40 @@ function isForwardRefComponent(Component: any) { } export interface ReactRendererOptions { + /** + * The editor instance. + * @type {Editor} + */ editor: Editor, + + /** + * The props for the component. + * @type {Record} + * @default {} + */ props?: Record, + + /** + * The tag name of the element. + * @type {string} + * @default 'div' + */ as?: string, + + /** + * The class name of the element. + * @type {string} + * @default '' + * @example 'foo bar' + */ className?: string, + + /** + * The attributes of the element. + * @type {Record} + * @default {} + * @example { 'data-foo': 'bar' } + */ attrs?: Record, } @@ -31,6 +71,17 @@ type ComponentType = React.FunctionComponent

| React.ForwardRefExoticComponent & React.RefAttributes>; +/** + * The ReactRenderer class. It's responsible for rendering React components inside the editor. + * @example + * new ReactRenderer(MyComponent, { + * editor, + * props: { + * foo: 'bar', + * }, + * as: 'span', + * }) +*/ export class ReactRenderer { id: string diff --git a/packages/react/src/useEditor.ts b/packages/react/src/useEditor.ts index 5b03a94047..c14114f8c0 100644 --- a/packages/react/src/useEditor.ts +++ b/packages/react/src/useEditor.ts @@ -8,6 +8,13 @@ import { import { Editor } from './Editor.js' +/** + * This hook allows you to create an editor instance. + * @param options The editor options + * @param deps The dependencies to watch for changes + * @returns The editor instance + * @example const editor = useEditor({ extensions: [...] }) + */ export const useEditor = (options: Partial = {}, deps: DependencyList = []) => { const editorRef = useRef(null) const [, forceUpdate] = useState({}) diff --git a/packages/starter-kit/src/starter-kit.ts b/packages/starter-kit/src/starter-kit.ts index b917543f0f..ad572d3fee 100644 --- a/packages/starter-kit/src/starter-kit.ts +++ b/packages/starter-kit/src/starter-kit.ts @@ -19,26 +19,120 @@ import { Strike, StrikeOptions } from '@tiptap/extension-strike' import { Text } from '@tiptap/extension-text' export interface StarterKitOptions { + /** + * If set to false, the blockquote extension will not be registered + * @example blockquote: false + */ blockquote: Partial | false, + + /** + * If set to false, the bold extension will not be registered + * @example bold: false + */ bold: Partial | false, + + /** + * If set to false, the bulletList extension will not be registered + * @example bulletList: false + */ bulletList: Partial | false, + + /** + * If set to false, the code extension will not be registered + * @example code: false + */ code: Partial | false, + + /** + * If set to false, the codeBlock extension will not be registered + * @example codeBlock: false + */ codeBlock: Partial | false, + + /** + * If set to false, the document extension will not be registered + * @example document: false + */ document: false, + + /** + * If set to false, the dropcursor extension will not be registered + * @example dropcursor: false + */ dropcursor: Partial | false, + + /** + * If set to false, the gapcursor extension will not be registered + * @example gapcursor: false + */ gapcursor: false, + + /** + * If set to false, the hardBreak extension will not be registered + * @example hardBreak: false + */ hardBreak: Partial | false, + + /** + * If set to false, the heading extension will not be registered + * @example heading: false + */ heading: Partial | false, + + /** + * If set to false, the history extension will not be registered + * @example history: false + */ history: Partial | false, + + /** + * If set to false, the horizontalRule extension will not be registered + * @example horizontalRule: false + */ horizontalRule: Partial | false, + + /** + * If set to false, the italic extension will not be registered + * @example italic: false + */ italic: Partial | false, + + /** + * If set to false, the listItem extension will not be registered + * @example listItem: false + */ listItem: Partial | false, + + /** + * If set to false, the orderedList extension will not be registered + * @example orderedList: false + */ orderedList: Partial | false, + + /** + * If set to false, the paragraph extension will not be registered + * @example paragraph: false + */ paragraph: Partial | false, + + /** + * If set to false, the strike extension will not be registered + * @example strike: false + */ strike: Partial | false, + + /** + * If set to false, the text extension will not be registered + * @example text: false + */ text: false, } +/** + * The starter kit is a collection of essential editor extensions. + * + * It’s a good starting point for building your own editor. + */ export const StarterKit = Extension.create({ name: 'starterKit', diff --git a/packages/suggestion/src/suggestion.ts b/packages/suggestion/src/suggestion.ts index bb6fdb868a..871c4528ad 100644 --- a/packages/suggestion/src/suggestion.ts +++ b/packages/suggestion/src/suggestion.ts @@ -5,16 +5,86 @@ import { Decoration, DecorationSet, EditorView } from '@tiptap/pm/view' import { findSuggestionMatch as defaultFindSuggestionMatch } from './findSuggestionMatch.js' export interface SuggestionOptions { + /** + * The plugin key for the suggestion plugin. + * @default 'suggestion' + * @example 'mention' + */ pluginKey?: PluginKey + + /** + * The editor instance. + * @default null + */ editor: Editor + + /** + * The character that triggers the suggestion. + * @default '@' + * @example '#' + */ char?: string + + /** + * Allow spaces in the suggestion query. + * @default false + * @example true + */ allowSpaces?: boolean + + /** + * Allow prefixes in the suggestion query. + * @default [' '] + * @example [' ', '@'] + */ allowedPrefixes?: string[] | null + + /** + * Only match suggestions at the start of the line. + * @default false + * @example true + */ startOfLine?: boolean + + /** + * The tag name of the decoration node. + * @default 'span' + * @example 'div' + */ decorationTag?: string + + /** + * The class name of the decoration node. + * @default 'suggestion' + * @example 'mention' + */ decorationClass?: string + + /** + * A function that is called when a suggestion is selected. + * @param props The props object. + * @param props.editor The editor instance. + * @param props.range The range of the suggestion. + * @param props.props The props of the selected suggestion. + * @returns void + * @example ({ editor, range, props }) => { props.command(props.props) } + */ command?: (props: { editor: Editor; range: Range; props: I }) => void + + /** + * A function that returns the suggestion items in form of an array. + * @param props The props object. + * @param props.editor The editor instance. + * @param props.query The current suggestion query. + * @returns An array of suggestion items. + * @example ({ editor, query }) => [{ id: 1, label: 'John Doe' }] + */ items?: (props: { query: string; editor: Editor }) => I[] | Promise + + /** + * The render function for the suggestion. + * @returns An object with render functions. + */ render?: () => { onBeforeStart?: (props: SuggestionProps) => void onStart?: (props: SuggestionProps) => void @@ -23,18 +93,60 @@ export interface SuggestionOptions { onExit?: (props: SuggestionProps) => void onKeyDown?: (props: SuggestionKeyDownProps) => boolean } + + /** + * A function that returns a boolean to indicate if the suggestion should be active. + * @param props The props object. + * @returns {boolean} + */ allow?: (props: { editor: Editor; state: EditorState; range: Range }) => boolean findSuggestionMatch?: typeof defaultFindSuggestionMatch } export interface SuggestionProps { + /** + * The editor instance. + */ editor: Editor + + /** + * The range of the suggestion. + */ range: Range + + /** + * The current suggestion query. + */ query: string + + /** + * The current suggestion text. + */ text: string + + /** + * The suggestion items array. + */ items: I[] + + /** + * A function that is called when a suggestion is selected. + * @param props The props object. + * @returns void + */ command: (props: I) => void + + /** + * The decoration node HTML element + * @default null + */ decorationNode: Element | null + + /** + * The function that returns the client rect + * @default null + * @example () => new DOMRect(0, 0, 0, 0) + */ clientRect?: (() => DOMRect | null) | null } @@ -46,6 +158,10 @@ export interface SuggestionKeyDownProps { export const SuggestionPluginKey = new PluginKey('suggestion') +/** + * This utility allows you to create suggestions. + * @see https://tiptap.dev/api/utilities/suggestion + */ export function Suggestion({ pluginKey = SuggestionPluginKey, editor, diff --git a/packages/vue-2/src/VueRenderer.ts b/packages/vue-2/src/VueRenderer.ts index 2458e7632a..0827c36c51 100644 --- a/packages/vue-2/src/VueRenderer.ts +++ b/packages/vue-2/src/VueRenderer.ts @@ -1,6 +1,9 @@ import Vue from 'vue' import { VueConstructor } from 'vue/types/umd' +/** + * The VueRenderer class is responsible for rendering a Vue component as a ProseMirror node view. + */ export class VueRenderer { ref!: Vue diff --git a/packages/vue-3/src/VueRenderer.ts b/packages/vue-3/src/VueRenderer.ts index ca75954bdd..6088013985 100644 --- a/packages/vue-3/src/VueRenderer.ts +++ b/packages/vue-3/src/VueRenderer.ts @@ -8,6 +8,9 @@ export interface VueRendererOptions { props?: Record, } +/** + * This class is used to render Vue components inside the editor. + */ export class VueRenderer { id: string