@tiptap/core 2.3.1 → 2.4.0

package/src/helpers/findChildren.ts

@@ -2,6 +2,12 @@ import { Node as ProseMirrorNode } from '@tiptap/pm/model'
 
 import { NodeWithPos, Predicate } from '../types.js'
 
+/**
+ * Find children inside a Prosemirror node that match a predicate.
+ * @param node The Prosemirror node to search in
+ * @param predicate The predicate to match
+ * @returns An array of nodes with their positions
+ */
 export function findChildren(node: ProseMirrorNode, predicate: Predicate): NodeWithPos[] {
   const nodesWithPos: NodeWithPos[] = []
 

package/src/helpers/findChildrenInRange.ts

@@ -4,6 +4,10 @@ import { NodeWithPos, Predicate, Range } from '../types.js'
 
 /**
  * Same as `findChildren` but searches only within a `range`.
+ * @param node The Prosemirror node to search in
+ * @param range The range to search in
+ * @param predicate The predicate to match
+ * @returns An array of nodes with their positions
  */
 export function findChildrenInRange(
   node: ProseMirrorNode,

package/src/helpers/findParentNode.ts

@@ -3,6 +3,14 @@ import { Selection } from '@tiptap/pm/state'
 import { Predicate } from '../types.js'
 import { findParentNodeClosestToPos } from './findParentNodeClosestToPos.js'
 
+/**
+ * Finds the closest parent node to the current selection that matches a predicate.
+ * @param predicate The predicate to match
+ * @returns A command that finds the closest parent node to the current selection that matches the predicate
+ * @example ```js
+ * findParentNode(node => node.type.name === 'paragraph')
+ * ```
+ */
 export function findParentNode(predicate: Predicate) {
   return (selection: Selection) => findParentNodeClosestToPos(selection.$from, predicate)
 }

package/src/helpers/findParentNodeClosestToPos.ts

@@ -2,6 +2,15 @@ import { Node as ProseMirrorNode, ResolvedPos } from '@tiptap/pm/model'
 
 import { Predicate } from '../types.js'
 
+/**
+ * Finds the closest parent node to a resolved position that matches a predicate.
+ * @param $pos The resolved position to search from
+ * @param predicate The predicate to match
+ * @returns The closest parent node to the resolved position that matches the predicate
+ * @example ```js
+ * findParentNodeClosestToPos($from, node => node.type.name === 'paragraph')
+ * ```
+ */
 export function findParentNodeClosestToPos(
   $pos: ResolvedPos,
   predicate: Predicate,

package/src/helpers/generateHTML.ts

@@ -4,6 +4,12 @@ import { Extensions, JSONContent } from '../types.js'
 import { getHTMLFromFragment } from './getHTMLFromFragment.js'
 import { getSchema } from './getSchema.js'
 
+/**
+ * Generate HTML from a JSONContent
+ * @param doc The JSONContent to generate HTML from
+ * @param extensions The extensions to use for the schema
+ * @returns The generated HTML
+ */
 export function generateHTML(doc: JSONContent, extensions: Extensions): string {
   const schema = getSchema(extensions)
   const contentNode = Node.fromJSON(schema, doc)

package/src/helpers/generateJSON.ts

@@ -4,6 +4,12 @@ import { Extensions } from '../types.js'
 import { elementFromString } from '../utilities/elementFromString.js'
 import { getSchema } from './getSchema.js'
 
+/**
+ * Generate JSONContent from HTML
+ * @param html The HTML to generate JSONContent from
+ * @param extensions The extensions to use for the schema
+ * @returns The generated JSONContent
+ */
 export function generateJSON(html: string, extensions: Extensions): Record<string, any> {
   const schema = getSchema(extensions)
   const dom = elementFromString(html)

package/src/helpers/generateText.ts

@@ -5,6 +5,13 @@ import { getSchema } from './getSchema.js'
 import { getText } from './getText.js'
 import { getTextSerializersFromSchema } from './getTextSerializersFromSchema.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 function generateText(
   doc: JSONContent,
   extensions: Extensions,

package/src/helpers/getAttributes.ts

@@ -5,6 +5,12 @@ import { getMarkAttributes } from './getMarkAttributes.js'
 import { getNodeAttributes } from './getNodeAttributes.js'
 import { getSchemaTypeNameByName } from './getSchemaTypeNameByName.js'
 
+/**
+ * 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 function getAttributes(
   state: EditorState,
   typeOrName: string | NodeType | MarkType,

package/src/helpers/getExtensionField.ts

@@ -1,5 +1,12 @@
 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 function getExtensionField<T = any>(
   extension: AnyExtension,
   field: string,

package/src/helpers/getSchemaByResolvedExtensions.ts

@@ -23,6 +23,12 @@ function cleanUpSchemaItem<T>(data: T) {
   ) as T
 }
 
+/**
+ * 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 function getSchemaByResolvedExtensions(extensions: Extensions, editor?: Editor): Schema {
   const allAttributes = getAttributesFromExtensions(extensions)
   const { nodeExtensions, markExtensions } = splitExtensions(extensions)

package/src/helpers/getSchemaTypeByName.ts

@@ -1,5 +1,11 @@
 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 function getSchemaTypeByName(name: string, schema: Schema): NodeType | MarkType | null {
   return schema.nodes[name] || schema.marks[name] || null
 }

package/src/helpers/getSchemaTypeNameByName.ts

@@ -1,5 +1,11 @@
 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 function getSchemaTypeNameByName(name: string, schema: Schema): 'node' | 'mark' | null {
   if (schema.nodes[name]) {
     return 'node'

package/src/helpers/getSplittedAttributes.ts

@@ -1,5 +1,12 @@
 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 function getSplittedAttributes(
   extensionAttributes: ExtensionAttribute[],
   typeName: string,

package/src/helpers/getText.ts

@@ -3,6 +3,15 @@ import { Node as ProseMirrorNode } from '@tiptap/pm/model'
 import { TextSerializer } from '../types.js'
 import { getTextBetween } from './getTextBetween.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 function getText(
   node: ProseMirrorNode,
   options?: {

package/src/helpers/getTextBetween.ts

@@ -2,6 +2,14 @@ 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 function getTextBetween(
   startNode: ProseMirrorNode,
   range: Range,
@@ -13,17 +21,15 @@ export function getTextBetween(
   const { from, to } = range
   const { blockSeparator = '\n\n', textSerializers = {} } = options || {}
   let text = ''
-  let separated = true
 
   startNode.nodesBetween(from, to, (node, pos, parent, index) => {
+    if (node.isBlock && pos > from) {
+      text += blockSeparator
+    }
+
     const textSerializer = textSerializers?.[node.type.name]
 
     if (textSerializer) {
-      if (node.isBlock && !separated) {
-        text += blockSeparator
-        separated = true
-      }
-
       if (parent) {
         text += textSerializer({
           node,
@@ -39,10 +45,6 @@ export function getTextBetween(
 
     if (node.isText) {
       text += node?.text?.slice(Math.max(from, pos) - pos, to - pos) // eslint-disable-line
-      separated = false
-    } else if (node.isBlock && !separated) {
-      text += blockSeparator
-      separated = true
     }
   })
 

package/src/helpers/getTextContentFromNodes.ts

@@ -1,5 +1,11 @@
 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 const getTextContentFromNodes = ($from: ResolvedPos, maxMatch = 500) => {
   let textBefore = ''
 

package/src/helpers/getTextSerializersFromSchema.ts

@@ -2,6 +2,11 @@ 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 function getTextSerializersFromSchema(schema: Schema): Record<string, TextSerializer> {
   return Object.fromEntries(
     Object.entries(schema.nodes)

package/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

package/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: {
   /**

package/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,

package/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

package/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,

package/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

package/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

package/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,