prosemirror-utils

What is prosemirror-utils?

The prosemirror-utils package provides a set of utility functions to simplify common tasks when working with ProseMirror, a toolkit for building rich-text editors. These utilities help with node manipulation, selection handling, and other editor-related operations.

What are prosemirror-utils's main functionalities?

findParentNode

This utility function helps to find the closest parent node of a given type from the current selection. In this example, it finds the closest parent node of type 'paragraph'.

const { findParentNode } = require('prosemirror-utils');

const parentNode = findParentNode(node => node.type === schema.nodes.paragraph)(state.selection);
console.log(parentNode);

removeNodeAtPos

This function removes a node at a specific position in the document. In this example, it removes the node at position 5.

const { removeNodeAtPos } = require('prosemirror-utils');

const tr = removeNodeAtPos(5)(state.tr);
console.log(tr);

replaceText

This utility replaces text within a specified range. In this example, it replaces the text between positions 5 and 10 with 'new text'.

const { replaceText } = require('prosemirror-utils');

const tr = replaceText(5, 10, schema.text('new text'))(state.tr);
console.log(tr);

findSelectedNodeOfType

This function finds the selected node of a specific type. In this example, it finds the selected node of type 'paragraph'.

const { findSelectedNodeOfType } = require('prosemirror-utils');

const selectedNode = findSelectedNodeOfType(schema.nodes.paragraph)(state.selection);
console.log(selectedNode);

Other packages similar to prosemirror-utils

prosemirror-commands

The prosemirror-commands package provides a collection of command functions for ProseMirror. These commands are higher-level operations like toggling bold or inserting a blockquote. While prosemirror-utils focuses on utility functions for node and selection manipulation, prosemirror-commands offers predefined editor commands.

prosemirror-schema-basic

The prosemirror-schema-basic package provides a basic schema for ProseMirror, including nodes like paragraphs, headings, and lists. While it doesn't offer utility functions like prosemirror-utils, it provides a foundational schema that can be extended and used in conjunction with utility functions.

prosemirror-transform

The prosemirror-transform package provides tools for transforming ProseMirror documents, including steps and transactions. It offers lower-level transformation capabilities compared to the higher-level utility functions in prosemirror-utils.

README

Utils library for ProseMirror

How to

Test

npm run test

Build

npm run build_all

Quick Start

Install prosemirror-utils package from npm:

npm install prosemirror-utils

Public API documentation

Utils for working with selection

• findParentNode(predicate: fn(node: ProseMirrorNode) → boolean) → fn(selection: Selection) → ?{pos: number, start: number, depth: number, node: ProseMirrorNode}
  Iterates over parent nodes, returning the closest node and its start position predicate returns truthy for. start points to the start position of the node, pos points directly before the node.

  const predicate = node => node.type === schema.nodes.blockquote;
  const parent = findParentNode(predicate)(selection);
  

• findParentNodeClosestToPos($pos: ResolvedPos, predicate: fn(node: ProseMirrorNode) → boolean) → ?{pos: number, start: number, depth: number, node: ProseMirrorNode}
  Iterates over parent nodes starting from the given $pos, returning the closest node and its start position predicate returns truthy for. start points to the start position of the node, pos points directly before the node.

  const predicate = node => node.type === schema.nodes.blockquote;
  const parent = findParentNodeClosestToPos(state.doc.resolve(5), predicate);
  

• findParentDomRef(predicate: fn(node: ProseMirrorNode) → boolean, domAtPos: fn(pos: number) → {node: dom.Node, offset: number}) → fn(selection: Selection) → ?dom.Node
  Iterates over parent nodes, returning DOM reference of the closest node predicate returns truthy for.

  const domAtPos = view.domAtPos.bind(view);
  const predicate = node => node.type === schema.nodes.table;
  const parent = findParentDomRef(predicate, domAtPos)(selection); // <table>
  

• hasParentNode(predicate: fn(node: ProseMirrorNode) → boolean) → fn(selection: Selection) → boolean
  Checks if there's a parent node predicate returns truthy for.

  if (hasParentNode(node => node.type === schema.nodes.table)(selection)) {
    // ....
  }
  

• findParentNodeOfType(nodeType: NodeType | [NodeType]) → fn(selection: Selection) → ?{pos: number, start: number, depth: number, node: ProseMirrorNode}
  Iterates over parent nodes, returning closest node of a given nodeType. start points to the start position of the node, pos points directly before the node.

  const parent = findParentNodeOfType(schema.nodes.paragraph)(selection);
  

• findParentNodeOfTypeClosestToPos($pos: ResolvedPos, nodeType: NodeType | [NodeType]) → ?{pos: number, start: number, depth: number, node: ProseMirrorNode}
  Iterates over parent nodes starting from the given $pos, returning closest node of a given nodeType. start points to the start position of the node, pos points directly before the node.

  const parent = findParentNodeOfTypeClosestToPos(state.doc.resolve(10), schema.nodes.paragraph);
  

• hasParentNodeOfType(nodeType: NodeType | [NodeType]) → fn(selection: Selection) → boolean
  Checks if there's a parent node of a given nodeType.

  if (hasParentNodeOfType(schema.nodes.table)(selection)) {
    // ....
  }
  

• findParentDomRefOfType(nodeType: NodeType | [NodeType], domAtPos: fn(pos: number) → {node: dom.Node, offset: number}) → fn(selection: Selection) → ?dom.Node
  Iterates over parent nodes, returning DOM reference of the closest node of a given nodeType.

  const domAtPos = view.domAtPos.bind(view);
  const parent = findParentDomRefOfType(schema.nodes.codeBlock, domAtPos)(selection); // <pre>
  

• findSelectedNodeOfType(nodeType: NodeType | [NodeType]) → fn(selection: Selection) → ?{pos: number, start: number, depth: number, node: ProseMirrorNode}
  Returns a node of a given nodeType if it is selected. start points to the start position of the node, pos points directly before the node.

  const { extension, inlineExtension, bodiedExtension } = schema.nodes;
  const selectedNode = findSelectedNodeOfType([
    extension,
    inlineExtension,
    bodiedExtension,
  ])(selection);
  

• isNodeSelection(selection: Selection) → boolean
  Checks if current selection is a NodeSelection.

  if (isNodeSelection(tr.selection)) {
    // ...
  }
  

• findPositionOfNodeBefore(selection: Selection) → ?number
  Returns position of the previous node.

  const pos = findPositionOfNodeBefore(tr.selection);
  

• findDomRefAtPos(position: number, domAtPos: fn(pos: number) → {node: dom.Node, offset: number}) → dom.Node
  Returns DOM reference of a node at a given position. If the node type is of type TEXT_NODE it will return the reference of the parent node.

  const domAtPos = view.domAtPos.bind(view);
  const ref = findDomRefAtPos($from.pos, domAtPos);
  

Utils for working with ProseMirror node

• flatten(node: ProseMirrorNode, descend: ?boolean = true) → [{node: ProseMirrorNode, pos: number}]
  Flattens descendants of a given node. It doesn't descend into a node when descend argument is false (defaults to true).

  const children = flatten(node);
  

• findChildren(node: ProseMirrorNode, predicate: fn(node: ProseMirrorNode) → boolean, descend: ?boolean) → [{node: ProseMirrorNode, pos: number}]
  Iterates over descendants of a given node, returning child nodes predicate returns truthy for. It doesn't descend into a node when descend argument is false (defaults to true).

  const textNodes = findChildren(node, child => child.isText, false);
  

• findTextNodes(node: ProseMirrorNode, descend: ?boolean) → [{node: ProseMirrorNode, pos: number}]
  Returns text nodes of a given node. It doesn't descend into a node when descend argument is false (defaults to true).

  const textNodes = findTextNodes(node);
  

• findInlineNodes(node: ProseMirrorNode, descend: ?boolean) → [{node: ProseMirrorNode, pos: number}]
  Returns inline nodes of a given node. It doesn't descend into a node when descend argument is false (defaults to true).

  const inlineNodes = findInlineNodes(node);
  

• findBlockNodes(node: ProseMirrorNode, descend: ?boolean) → [{node: ProseMirrorNode, pos: number}]
  Returns block descendants of a given node. It doesn't descend into a node when descend argument is false (defaults to true).

  const blockNodes = findBlockNodes(node);
  

• findChildrenByAttr(node: ProseMirrorNode, predicate: fn(attrs: ?Object) → boolean, descend: ?boolean) → [{node: ProseMirrorNode, pos: number}]
  Iterates over descendants of a given node, returning child nodes predicate returns truthy for. It doesn't descend into a node when descend argument is false (defaults to true).

  const mergedCells = findChildrenByAttr(table, attrs => attrs.colspan === 2);
  

• findChildrenByType(node: ProseMirrorNode, nodeType: NodeType, descend: ?boolean) → [{node: ProseMirrorNode, pos: number}]
  Iterates over descendants of a given node, returning child nodes of a given nodeType. It doesn't descend into a node when descend argument is false (defaults to true).

  const cells = findChildrenByType(table, schema.nodes.tableCell);
  

• findChildrenByMark(node: ProseMirrorNode, markType: markType, descend: ?boolean) → [{node: ProseMirrorNode, pos: number}]
  Iterates over descendants of a given node, returning child nodes that have a mark of a given markType. It doesn't descend into a node when descend argument is false (defaults to true).

  const nodes = findChildrenByMark(state.doc, schema.marks.strong);
  

• contains(node: ProseMirrorNode, nodeType: NodeType) → boolean
  Returns true if a given node contains nodes of a given nodeType

  if (contains(panel, schema.nodes.listItem)) {
    // ...
  }
  

Utils for document transformation

• removeParentNodeOfType(nodeType: NodeType | [NodeType]) → fn(tr: Transaction) → Transaction
  Returns a new transaction that removes a node of a given nodeType. It will return an original transaction if parent node hasn't been found.

  dispatch(
    removeParentNodeOfType(schema.nodes.table)(tr)
  );
  

• replaceParentNodeOfType(nodeType: NodeType | [NodeType], content: ProseMirrorNode | Fragment) → fn(tr: Transaction) → Transaction
  Returns a new transaction that replaces parent node of a given nodeType with the given content. It will return an original transaction if either parent node hasn't been found or replacing is not possible.

  const node = schema.nodes.paragraph.createChecked({}, schema.text('new'));
  
  dispatch(
   replaceParentNodeOfType(schema.nodes.table, node)(tr)
  );
  

• removeSelectedNode(tr: Transaction) → Transaction
  Returns a new transaction that removes selected node. It will return an original transaction if current selection is not a NodeSelection.

  dispatch(
    removeSelectedNode(tr)
  );
  

• replaceSelectedNode(content: ProseMirrorNode | ProseMirrorFragment) → fn(tr: Transaction) → Transaction
  Returns a new transaction that replaces selected node with a given node, keeping NodeSelection on the new node. It will return the original transaction if either current selection is not a NodeSelection or replacing is not possible.

  const node = schema.nodes.paragraph.createChecked({}, schema.text('new'));
  dispatch(
    replaceSelectedNode(node)(tr)
  );
  

• canInsert($pos: ResolvedPos, content: ProseMirrorNode | Fragment) → boolean
  Checks if a given content can be inserted at the given $pos

  const { selection: { $from } } = state;
  const node = state.schema.nodes.atom.createChecked();
  if (canInsert($from, node)) {
    // ...
  }
  

• safeInsert(content: ProseMirrorNode | Fragment, position: ?number, tryToReplace: ?boolean) → fn(tr: Transaction) → Transaction
  Returns a new transaction that inserts a given content at the current cursor position, or at a given position, if it is allowed by schema. If schema restricts such nesting, it will try to find an appropriate place for a given node in the document, looping through parent nodes up until the root document node. If tryToReplace is true and current selection is a NodeSelection, it will replace selected node with inserted content if its allowed by schema. If cursor is inside of an empty paragraph, it will try to replace that paragraph with the given content. If insertion is successful and inserted node has content, it will set cursor inside of that content. It will return an original transaction if the place for insertion hasn't been found.

  const node = schema.nodes.extension.createChecked({});
  dispatch(
    safeInsert(node)(tr)
  );
  

• setParentNodeMarkup(nodeType: NodeType | [NodeType], type: ?NodeType | null, attrs: ?Object | null, marks: ?[Mark]) → fn(tr: Transaction) → Transaction
  Returns a transaction that changes the type, attributes, and/or marks of the parent node of a given nodeType.

  const node = schema.nodes.extension.createChecked({});
  dispatch(
    setParentNodeMarkup(schema.nodes.panel, null, { panelType })(tr);
  );
  

• selectParentNodeOfType(nodeType: NodeType | [NodeType]) → fn(tr: Transaction) → Transaction
  Returns a new transaction that sets a NodeSelection on a parent node of a given nodeType.

  dispatch(
    selectParentNodeOfType([tableCell, tableHeader])(state.tr)
  );
  

• removeNodeBefore(tr: Transaction) → Transaction
  Returns a new transaction that deletes previous node.

  dispatch(
    removeNodeBefore(state.tr)
  );
  

• setTextSelection(position: number, dir: ?number = 1) → fn(tr: Transaction) → Transaction
  Returns a new transaction that tries to find a valid cursor selection starting at the given position and searching back if dir is negative, and forward if positive. If a valid cursor position hasn't been found, it will return the original transaction.

  dispatch(
    setTextSelection(5)(tr)
  );
  

License

• Apache 2.0 : http://www.apache.org/licenses/LICENSE-2.0

Changelog

1.2.2 (2024-05-13)

Fixing package version numbers.