prosemirror-model

A Slice represents a portion of a document cut out from a larger one. It contains a Fragment (the content) and two depth values, openStart and openEnd, which indicate how many levels of nodes are 'open' (cut through) at the beginning and end of the fragment.

This allows a slice to represent not just a flat list of nodes, but a piece of a document that maintains its structural relationship with the surrounding nodes (e.g., a slice that starts inside a paragraph and ends inside a paragraph).

Key Properties

• content: The Fragment contained in the slice.
• openStart: The depth at which the start of the fragment is open.
• openEnd: The depth at which the end of the fragment is open.
• size: The number of positions the slice adds when inserted into a document (this.content.size - this.openStart - this.openEnd).

Common Creation Methods

• Slice.empty: An empty slice with no content and zero open depth.
• Slice.maxOpen(fragment, [openIsolating]): Creates a slice from a Fragment by calculating the maximum possible open depth on both sides. Use this when you want the slice to automatically 'fit' into the surrounding structure of the fragment's nodes.

import {Slice} from "@prosemirror/model";

// Create an empty slice
const emptySlice = Slice.empty;

// Create a slice from a fragment with maximum open depth
const slice = Slice.maxOpen(myFragment);

// Check equality
const isSame = slice.eq(otherSlice);

// Convert to JSON
const json = slice.toJSON();
const restoredSlice = Slice.fromJSON(schema, json);

A Node represents an element in the ProseMirror document tree. A document is itself a Node containing child Node instances.

Key Characteristics:

• Persistent Data Structures: Nodes are immutable. Instead of mutating a node, you must create a new one using methods like copy(), mark(), or cut(). This allows for efficient structure sharing between old and new versions of the document.
• Markup: Nodes carry marks (e.g., emphasis, links) and attrs (attributes defined by the node's type).
• Content: Non-leaf nodes contain a Fragment of child nodes. Text nodes contain a text string.
• Indexing: Nodes use an integer-based indexing scheme. The nodeSize of a text node is its character length; a leaf node is 1; a non-leaf node is 2 + content.size (accounting for start and end tokens).

import { Node } from "prosemirror-model"
// Note: You typically interact with Nodes via a Schema, 
// rather than instantiating them directly with the constructor.

A Schema defines the structure of a document by specifying which nodes and marks are allowed. You create a schema by providing a SchemaSpec object containing nodes (mapping names to NodeSpec) and marks (mapping names to MarkSpec).

NodeSpec Options

• content: A string describing the allowed content (e.g., "block+", "inline*").
• marks: A string specifying allowed marks. "_" allows all marks, "" disallows all marks, or a space-separated list of mark names/groups.
• group: A space-separated list of groups this node belongs to.
• inline: Boolean; if true, the node is an inline type.
• attrs: An object defining the attributes for this node type using AttributeSpec.
• toDOM: A function to serialize the node to DOM/HTML.
• parseDOM: Rules for parsing the node from the DOM.

MarkSpec Options

• attrs: Attributes for the mark.
• excludes: A space-separated list of marks that this mark cannot coexist with. Use "_" to exclude all marks.
• group: The group(s) this mark belongs to.
• toDOM: A function to serialize the mark to DOM/HTML.

import {Schema} from "prosemirror-model"

const mySchema = new Schema({
  nodes: {
    doc: { content: "block+" },
    paragraph: { group: "block", content: "inline*", marks: true },
    text: {}}},
  marks: {
    strong: { "text": "bold" }
  }
})

The ContentMatch class represents the state of a node type's content expression (the rules defining what children a node can have). It is used to determine if a specific sequence of nodes is valid according to the schema and to find valid positions for new nodes.

Key capabilities:

• Matching Types: Check if a specific NodeType can follow the current position using matchType(type).
• Matching Fragments: Validate an entire Fragment of nodes against the current match state using matchFragment(frag, start, end).
• Finding Wrappers: Determine which parent nodes must wrap a target node to make it valid at the current position using findWrapping(target).
• Filling Content: Automatically generate the necessary nodes to make a fragment valid at a specific position using fillBefore(after, toEnd, startIndex).
• Default Nodes: Identify the first valid node type that can be generated at the current position using the defaultType getter.

import { ContentMatch } from "prosemirror-model"

// Assuming you have access to a NodeType from your schema
// matchType returns the next ContentMatch state if the type matches
const nextMatch = currentMatch.matchType(myNodeType);

if (nextMatch) {
  // The node type matched, we are now in the state represented by nextMatch
}

// findWrapping returns an array of node types that would wrap the target
const wrappers = currentMatch.findWrapping(targetNodeType);
// returns e.g., [paragraphNodeType, blockquoteNodeType]