@tiptap/core 2.3.1 → 2.4.0

package/dist/packages/core/src/helpers/generateText.d.ts

@@ -1,4 +1,11 @@
 import { Extensions, JSONContent, TextSerializer } from '../types.js';
+/**
+ * Generate raw text from a JSONContent
+ * @param doc The JSONContent to generate text from
+ * @param extensions The extensions to use for the schema
+ * @param options Options for the text generation f.e. blockSeparator or textSerializers
+ * @returns The generated text
+ */
 export declare function generateText(doc: JSONContent, extensions: Extensions, options?: {
     blockSeparator?: string;
     textSerializers?: Record<string, TextSerializer>;

package/dist/packages/core/src/helpers/getAttributes.d.ts

@@ -1,3 +1,9 @@
 import { MarkType, NodeType } from '@tiptap/pm/model';
 import { EditorState } from '@tiptap/pm/state';
+/**
+ * Get node or mark attributes by type or name on the current editor state
+ * @param state The current editor state
+ * @param typeOrName The node or mark type or name
+ * @returns The attributes of the node or mark or an empty object
+ */
 export declare function getAttributes(state: EditorState, typeOrName: string | NodeType | MarkType): Record<string, any>;

package/dist/packages/core/src/helpers/getExtensionField.d.ts

@@ -1,2 +1,9 @@
 import { AnyExtension, MaybeThisParameterType, RemoveThis } from '../types.js';
+/**
+ * Returns a field from an extension
+ * @param extension The Tiptap extension
+ * @param field The field, for example `renderHTML` or `priority`
+ * @param context The context object that should be passed as `this` into the function
+ * @returns The field value
+ */
 export declare function getExtensionField<T = any>(extension: AnyExtension, field: string, context?: Omit<MaybeThisParameterType<T>, 'parent'>): RemoveThis<T>;

package/dist/packages/core/src/helpers/getSchemaByResolvedExtensions.d.ts

@@ -1,4 +1,10 @@
 import { Schema } from '@tiptap/pm/model';
 import { Editor } from '../index.js';
 import { Extensions } from '../types.js';
+/**
+ * Creates a new Prosemirror schema based on the given extensions.
+ * @param extensions An array of Tiptap extensions
+ * @param editor The editor instance
+ * @returns A Prosemirror schema
+ */
 export declare function getSchemaByResolvedExtensions(extensions: Extensions, editor?: Editor): Schema;

package/dist/packages/core/src/helpers/getSchemaTypeByName.d.ts

@@ -1,2 +1,8 @@
 import { MarkType, NodeType, Schema } from '@tiptap/pm/model';
+/**
+ * Tries to get a node or mark type by its name.
+ * @param name The name of the node or mark type
+ * @param schema The Prosemiror schema to search in
+ * @returns The node or mark type, or null if it doesn't exist
+ */
 export declare function getSchemaTypeByName(name: string, schema: Schema): NodeType | MarkType | null;

package/dist/packages/core/src/helpers/getSchemaTypeNameByName.d.ts

@@ -1,2 +1,8 @@
 import { Schema } from '@tiptap/pm/model';
+/**
+ * Get the type of a schema item by its name.
+ * @param name The name of the schema item
+ * @param schema The Prosemiror schema to search in
+ * @returns The type of the schema item (`node` or `mark`), or null if it doesn't exist
+ */
 export declare function getSchemaTypeNameByName(name: string, schema: Schema): 'node' | 'mark' | null;

package/dist/packages/core/src/helpers/getSplittedAttributes.d.ts

@@ -1,2 +1,9 @@
 import { ExtensionAttribute } from '../types.js';
+/**
+ * Return attributes of an extension that should be splitted by keepOnSplit flag
+ * @param extensionAttributes Array of extension attributes
+ * @param typeName The type of the extension
+ * @param attributes The attributes of the extension
+ * @returns The splitted attributes
+ */
 export declare function getSplittedAttributes(extensionAttributes: ExtensionAttribute[], typeName: string, attributes: Record<string, any>): Record<string, any>;

package/dist/packages/core/src/helpers/getText.d.ts

@@ -1,5 +1,14 @@
 import { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import { TextSerializer } from '../types.js';
+/**
+ * Gets the text of a Prosemirror node
+ * @param node The Prosemirror node
+ * @param options Options for the text serializer & block separator
+ * @returns The text of the node
+ * @example ```js
+ * const text = getText(node, { blockSeparator: '\n' })
+ * ```
+ */
 export declare function getText(node: ProseMirrorNode, options?: {
     blockSeparator?: string;
     textSerializers?: Record<string, TextSerializer>;

package/dist/packages/core/src/helpers/getTextBetween.d.ts

@@ -1,5 +1,13 @@
 import { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import { Range, TextSerializer } from '../types.js';
+/**
+ * Gets the text between two positions in a Prosemirror node
+ * and serializes it using the given text serializers and block separator (see getText)
+ * @param startNode The Prosemirror node to start from
+ * @param range The range of the text to get
+ * @param options Options for the text serializer & block separator
+ * @returns The text between the two positions
+ */
 export declare function getTextBetween(startNode: ProseMirrorNode, range: Range, options?: {
     blockSeparator?: string;
     textSerializers?: Record<string, TextSerializer>;

package/dist/packages/core/src/helpers/getTextContentFromNodes.d.ts

@@ -1,2 +1,8 @@
 import { ResolvedPos } from '@tiptap/pm/model';
+/**
+ * Returns the text content of a resolved prosemirror position
+ * @param $from The resolved position to get the text content from
+ * @param maxMatch The maximum number of characters to match
+ * @returns The text content
+ */
 export declare const getTextContentFromNodes: ($from: ResolvedPos, maxMatch?: number) => string;

package/dist/packages/core/src/helpers/getTextSerializersFromSchema.d.ts

@@ -1,3 +1,8 @@
 import { Schema } from '@tiptap/pm/model';
 import { TextSerializer } from '../types.js';
+/**
+ * Find text serializers `toText` in a Prosemirror schema
+ * @param schema The Prosemirror schema to search in
+ * @returns A record of text serializers by node name
+ */
 export declare function getTextSerializersFromSchema(schema: Schema): Record<string, TextSerializer>;

package/dist/packages/core/src/inputRules/markInputRule.d.ts

@@ -4,6 +4,7 @@ import { ExtendedRegExpMatchArray } from '../types.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 declare function markInputRule(config: {
     find: InputRuleFinder;

package/dist/packages/core/src/inputRules/nodeInputRule.d.ts

@@ -4,6 +4,7 @@ import { ExtendedRegExpMatchArray } from '../types.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 declare function nodeInputRule(config: {
     /**

package/dist/packages/core/src/inputRules/textInputRule.d.ts

@@ -2,6 +2,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 declare function textInputRule(config: {
     find: InputRuleFinder;

package/dist/packages/core/src/inputRules/textblockTypeInputRule.d.ts

@@ -6,6 +6,7 @@ import { ExtendedRegExpMatchArray } from '../types.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 declare function textblockTypeInputRule(config: {
     find: InputRuleFinder;

package/dist/packages/core/src/inputRules/wrappingInputRule.d.ts

@@ -15,6 +15,7 @@ import { ExtendedRegExpMatchArray } from '../types.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 declare function wrappingInputRule(config: {
     find: InputRuleFinder;

package/dist/packages/core/src/pasteRules/markPasteRule.d.ts

@@ -4,6 +4,7 @@ import { ExtendedRegExpMatchArray } from '../types.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 declare function markPasteRule(config: {
     find: PasteRuleFinder;

package/dist/packages/core/src/pasteRules/nodePasteRule.d.ts

@@ -4,6 +4,7 @@ import { ExtendedRegExpMatchArray } from '../types.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 declare function nodePasteRule(config: {
     find: PasteRuleFinder;

package/dist/packages/core/src/pasteRules/textPasteRule.d.ts

@@ -2,6 +2,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 declare function textPasteRule(config: {
     find: PasteRuleFinder;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiptap/core",
   "description": "headless rich text editor",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "homepage": "https://tiptap.dev",
   "keywords": [
     "tiptap",
@@ -32,7 +32,7 @@
     "dist"
   ],
   "devDependencies": {
-    "@tiptap/pm": "^2.3.1"
+    "@tiptap/pm": "^2.4.0"
   },
   "peerDependencies": {
     "@tiptap/pm": "^2.0.0"

package/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<RawCommands>
 
     /**
-     * Keyboard shortcuts
+     * This function registers keyboard shortcuts.
+     * @see https://tiptap.dev/guide/custom-extensions#keyboard-shortcuts
+     * @example
+     * addKeyboardShortcuts() {
+     *   return {
+     *     'Mod-l': () => this.editor.commands.toggleBulletList(),
+     *   }
+     * },
      */
     addKeyboardShortcuts?: (this: {
       name: string
@@ -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<Options = any, Storage = any> {
   type = 'extension'
 
@@ -342,6 +457,7 @@ export class Extension<Options = any, Storage = any> {
     // with different calls of `configure`
     const extension = this.extend()
 
+    extension.parent = this.parent
     extension.options = mergeDeep(this.options as Record<string, any>, options) as Options
 
     extension.storage = callOrReturn(