refactor(core): add jsdocs for utility functions (#5141)

* refactor(core): add jsdocs to utilitiy functions

* refactor(core): add jsdocs to more utility functions

packages/core/src/helpers/combineTransactionSteps.ts

@@ -4,6 +4,9 @@ import { Transform } from '@tiptap/pm/transform'
 
 /**
  * Returns a new `Transform` based on all steps of the passed transactions.
+ * @param oldDoc The Prosemirror node to start from
+ * @param transactions The transactions to combine
+ * @returns A new `Transform` with all steps of the passed transactions
  */
 export function combineTransactionSteps(
   oldDoc: ProseMirrorNode,

packages/core/src/helpers/createChainableState.ts

@@ -1,5 +1,10 @@
 import { EditorState, Transaction } from '@tiptap/pm/state'
 
+/**
+ * Takes a Transaction & Editor State and turns it into a chainable state object
+ * @param config The transaction and state to create the chainable state from
+ * @returns A chainable Editor state object
+ */
 export function createChainableState(config: {
   transaction: Transaction
   state: EditorState

packages/core/src/helpers/createDocument.ts

@@ -3,6 +3,13 @@ import { Node as ProseMirrorNode, ParseOptions, Schema } from '@tiptap/pm/model'
 import { Content } from '../types.js'
 import { createNodeFromContent } from './createNodeFromContent.js'
 
+/**
+ * Create a new Prosemirror document node from content.
+ * @param content The JSON or HTML content to create the document from
+ * @param schema The Prosemirror schema to use for the document
+ * @param parseOptions Options for the parser
+ * @returns The created Prosemirror document node
+ */
 export function createDocument(
   content: Content,
   schema: Schema,

packages/core/src/helpers/createNodeFromContent.ts

@@ -14,6 +14,13 @@ export type CreateNodeFromContentOptions = {
   parseOptions?: ParseOptions
 }
 
+/**
+ * Takes a JSON or HTML content and creates a Prosemirror node or fragment from it.
+ * @param content The JSON or HTML content to create the node from
+ * @param schema The Prosemirror schema to use for the node
+ * @param options Options for the parser
+ * @returns The created Prosemirror node or fragment
+ */
 export function createNodeFromContent(
   content: Content,
   schema: Schema,
@@ -25,9 +32,15 @@ export function createNodeFromContent(
     ...options,
   }
 
-  if (typeof content === 'object' && content !== null) {
+  const isJSONContent = typeof content === 'object' && content !== null
+  const isTextContent = typeof content === 'string'
+
+  if (isJSONContent) {
     try {
-      if (Array.isArray(content) && content.length > 0) {
+      const isArrayContent = Array.isArray(content) && content.length > 0
+
+      // if the JSON Content is an array of nodes, create a fragment for each node
+      if (isArrayContent) {
         return Fragment.fromArray(content.map(item => schema.nodeFromJSON(item)))
       }
 
@@ -39,7 +52,7 @@ export function createNodeFromContent(
     }
   }
 
-  if (typeof content === 'string') {
+  if (isTextContent) {
     const parser = DOMParser.fromSchema(schema)
 
     return options.slice

packages/core/src/helpers/defaultBlockAt.ts

@@ -1,5 +1,10 @@
 import { ContentMatch, NodeType } from '@tiptap/pm/model'
 
+/**
+ * Gets the default block type at a given match
+ * @param match The content match to get the default block type from
+ * @returns The default block type or null
+ */
 export function defaultBlockAt(match: ContentMatch): NodeType | null {
   for (let i = 0; i < match.edgeCount; i += 1) {
     const { type } = match.edge(i)

packages/core/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[] = []
 

packages/core/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,

packages/core/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)
 }

packages/core/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,

packages/core/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)

packages/core/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)

packages/core/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,

packages/core/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,

packages/core/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)

packages/core/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
 }

packages/core/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'

packages/core/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,

packages/core/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?: {

packages/core/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,

packages/core/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 = ''
 

packages/core/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)