prosekit/pm/transform

AddMarkStep

Extends Step

Add a mark to all inline content between two positions.

constructor

new AddMarkStep(from: number, to: number, mark: Mark): AddMarkStep

from: number

The start of the marked range.

mark: Mark

The mark to add.

to: number

The end of the marked range.

apply

Applies this step to the given document, returning a result object that either indicates failure, if the step can not be applied to this document, or indicates success by containing a transformed document.

const apply: (doc: ProseMirrorNode) => StepResult

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: () => Step

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => null | Step

merge

Try to merge this step with another one, to be applied directly after it. Returns the merged step when possible, null if the steps can’t be merged.

const merge: (other: Step) => null | Step

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

AddNodeMarkStep

Extends Step

Add a mark to a specific node.

constructor

new AddNodeMarkStep(pos: number, mark: Mark): AddNodeMarkStep

mark: Mark

The mark to add.

pos: number

The position of the target node.

apply

const apply: (doc: ProseMirrorNode) => StepResult

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: (doc: ProseMirrorNode) => Step

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => null | Step

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

AttrStep

Extends Step

Update an attribute in a specific node.

constructor

new AttrStep(pos: number, attr: string, value: any): AttrStep

attr: string

The attribute to set.

pos: number

The position of the target node.

value: any

apply

const apply: (doc: ProseMirrorNode) => StepResult

getMap

Get the step map that represents the changes made by this step, and which can be used to transform between positions in the old and the new document.

const getMap: () => StepMap

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: (doc: ProseMirrorNode) => AttrStep

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => null | AttrStep

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

fromJSON

Deserialize a step from its JSON representation. Will call through to the step class’ own implementation of this method.

const fromJSON: (schema: Schema, json: any) => AttrStep

DocAttrStep

Extends Step

Update an attribute in the doc node.

constructor

new DocAttrStep(attr: string, value: any): DocAttrStep

attr: string

The attribute to set.

value: any

apply

const apply: (doc: ProseMirrorNode) => StepResult

getMap

Get the step map that represents the changes made by this step, and which can be used to transform between positions in the old and the new document.

const getMap: () => StepMap

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: (doc: ProseMirrorNode) => DocAttrStep

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => this

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

fromJSON

Deserialize a step from its JSON representation. Will call through to the step class’ own implementation of this method.

const fromJSON: (schema: Schema, json: any) => DocAttrStep

Mapping

A mapping represents a pipeline of zero or more step maps. It has special provisions for losslessly handling mapping positions through a series of steps in which some steps are inverted versions of earlier steps. (This comes up when ‘rebasing’ steps for collaboration or history management.)

constructor

new Mapping(maps?: readonly StepMap[], from?: number, to?: number): Mapping

from: number

The starting position in the maps array, used when map or mapResult is called.

to: number

The end position in the maps array.

get maps(): readonly StepMap[]

The step maps in this mapping.

appendMap

Add a step map to the end of this mapping. If mirrors is given, it should be the index of the step map that is the mirror image of this one.

const appendMap: (map: StepMap, mirrors?: number) => void

appendMapping

Add all the step maps in a given mapping to this one (preserving mirroring information).

const appendMapping: (mapping: Mapping) => void

appendMappingInverted

Append the inverse of the given mapping to this one.

const appendMappingInverted: (mapping: Mapping) => void

getMirror

Finds the offset of the step map that mirrors the map at the given offset, in this mapping (as per the second argument to appendMap).

const getMirror: (n: number) => undefined | number

invert

Create an inverted version of this mapping.

const invert: () => Mapping

map

Map a position through this mapping.

const map: (pos: number, assoc?: number) => number

mapResult

Map a position through this mapping, returning a mapping result.

const mapResult: (pos: number, assoc?: number) => MapResult

slice

Create a mapping that maps only through a part of this one.

const slice: (from?: number, to?: number) => Mapping

MapResult

An object representing a mapped position with extra information.

constructor

new MapResult(): MapResult

pos: number

The mapped version of the position.

get deleted(): boolean

Tells you whether the position was deleted, that is, whether the step removed the token on the side queried (via the assoc) argument from the document.

get deletedAcross(): boolean

Tells whether any of the steps mapped through deletes across the position (including both the token before and after the position).

get deletedAfter(): boolean

True when the token after the mapped position was deleted.

get deletedBefore(): boolean

Tells you whether the token before the mapped position was deleted.

RemoveMarkStep

Extends Step

Remove a mark from all inline content between two positions.

constructor

new RemoveMarkStep(from: number, to: number, mark: Mark): RemoveMarkStep

from: number

The start of the unmarked range.

mark: Mark

The mark to remove.

to: number

The end of the unmarked range.

apply

const apply: (doc: ProseMirrorNode) => StepResult

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: () => Step

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => null | Step

merge

Try to merge this step with another one, to be applied directly after it. Returns the merged step when possible, null if the steps can’t be merged.

const merge: (other: Step) => null | Step

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

RemoveNodeMarkStep

Extends Step

Remove a mark from a specific node.

constructor

new RemoveNodeMarkStep(pos: number, mark: Mark): RemoveNodeMarkStep

mark: Mark

The mark to remove.

pos: number

The position of the target node.

apply

const apply: (doc: ProseMirrorNode) => StepResult

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: (doc: ProseMirrorNode) => Step

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => null | Step

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

ReplaceAroundStep

Extends Step

Replace a part of the document with a slice of content, but preserve a range of the replaced content by moving it into the slice.

constructor

new ReplaceAroundStep(from: number, to: number, gapFrom: number, gapTo: number, slice: Slice, insert: number): ReplaceAroundStep

from: number

The start position of the replaced range.

gapFrom: number

The start of preserved range.

gapTo: number

The end of preserved range.

insert: number

The position in the slice where the preserved range should be inserted.

slice: Slice

The slice to insert.

to: number

The end position of the replaced range.

apply

const apply: (doc: ProseMirrorNode) => StepResult

getMap

Get the step map that represents the changes made by this step, and which can be used to transform between positions in the old and the new document.

const getMap: () => StepMap

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: (doc: ProseMirrorNode) => ReplaceAroundStep

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => null | ReplaceAroundStep

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

ReplaceStep

Extends Step

Replace a part of the document with a slice of new content.

constructor

new ReplaceStep(from: number, to: number, slice: Slice): ReplaceStep

from: number

The start position of the replaced range.

slice: Slice

The slice to insert.

to: number

The end position of the replaced range.

apply

const apply: (doc: ProseMirrorNode) => StepResult

getMap

Get the step map that represents the changes made by this step, and which can be used to transform between positions in the old and the new document.

const getMap: () => StepMap

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: (doc: ProseMirrorNode) => ReplaceStep

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => null | ReplaceStep

merge

Try to merge this step with another one, to be applied directly after it. Returns the merged step when possible, null if the steps can’t be merged.

const merge: (other: Step) => null | ReplaceStep

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

Step

A step object represents an atomic change. It generally applies only to the document it was created for, since the positions stored in it will only make sense for that document.

New steps are defined by creating classes that extend Step, overriding the apply, invert, map, getMap and fromJSON methods, and registering your class with a unique JSON-serialization identifier using Step.jsonID.

constructor

new Step(): Step

apply

const apply: (doc: ProseMirrorNode) => StepResult

getMap

Get the step map that represents the changes made by this step, and which can be used to transform between positions in the old and the new document.

const getMap: () => StepMap

invert

Create an inverted version of this step. Needs the document as it was before the step as argument.

const invert: (doc: ProseMirrorNode) => Step

map

Map this step through a mappable thing, returning either a version of that step with its positions adjusted, or null if the step was entirely deleted by the mapping.

const map: (mapping: Mappable) => null | Step

merge

Try to merge this step with another one, to be applied directly after it. Returns the merged step when possible, null if the steps can’t be merged.

const merge: (other: Step) => null | Step

toJSON

Create a JSON-serializeable representation of this step. When defining this for a custom subclass, make sure the result object includes the step type’s JSON id under the stepType property.

const toJSON: () => any

fromJSON

Deserialize a step from its JSON representation. Will call through to the step class’ own implementation of this method.

const fromJSON: (schema: Schema, json: any) => Step

jsonID

To be able to serialize steps to JSON, each step needs a string ID to attach to its JSON representation. Use this method to register an ID for your step classes. Try to pick something that’s unlikely to clash with steps from other modules.

const jsonID: (id: string, stepClass: { fromJSON: any }) => { fromJSON: any }

StepMap

A map describing the deletions and insertions made by a step, which can be used to find the correspondence between positions in the pre-step version of a document and the same position in the post-step version.

constructor

new StepMap(): StepMap

empty: StepMap

A StepMap that contains no changed ranges.

forEach

Calls the given function on each of the changed ranges included in this map.

const forEach: (f: (oldStart: number, oldEnd: number, newStart: number, newEnd: number) => void) => void

invert

Create an inverted version of this map. The result can be used to map positions in the post-step document to the pre-step document.

const invert: () => StepMap

map

Map a position through this object. When given, assoc (should be -1 or 1, defaults to 1) determines with which side the position is associated, which determines in which direction to move when a chunk of content is inserted at the mapped position.

const map: (pos: number, assoc?: number) => number

mapResult

Map a position, and return an object containing additional information about the mapping. The result’s deleted field tells you whether the position was deleted (completely enclosed in a replaced range) during the mapping. When content on only one side is deleted, the position itself is only considered deleted when assoc points in the direction of the deleted content.

const mapResult: (pos: number, assoc?: number) => MapResult

offset

Create a map that moves all positions by offset n (which may be negative). This can be useful when applying steps meant for a sub-document to a larger document, or vice-versa.

const offset: (n: number) => StepMap

StepResult

The result of applying a step. Contains either a new document or a failure value.

constructor

new StepResult(): StepResult

doc: null | ProseMirrorNode

The transformed document, if successful.

failed: null | string

The failure message, if unsuccessful.

fail

Create a failed step result.

const fail: (message: string) => StepResult

fromReplace

Call Node.replace with the given arguments. Create a successful result if it succeeds, and a failed one if it throws a ReplaceError.

const fromReplace: (doc: ProseMirrorNode, from: number, to: number, slice: Slice) => StepResult

ok

Create a successful step result.

const ok: (doc: ProseMirrorNode) => StepResult

Transform

Abstraction to build up and track an array of steps representing a document transformation.

Most transforming methods return the Transform object itself, so that they can be chained.

constructor

new Transform(doc: ProseMirrorNode): Transform

doc: ProseMirrorNode

The current document (the result of applying the steps in the transform).

docs: ProseMirrorNode[]

The documents before each of the steps.

mapping: Mapping

A mapping with the maps for each of the steps in this transform.

steps: Step[]

The steps in this transform.

get before(): ProseMirrorNode

The starting document.

get docChanged(): boolean

True when the document has been changed (when there are any steps).

addMark

Add the given mark to the inline content between from and to.

const addMark: (from: number, to: number, mark: Mark) => this

addNodeMark

Add a mark to the node at position pos.

const addNodeMark: (pos: number, mark: Mark) => this

clearIncompatible

Removes all marks and nodes from the content of the node at pos that don’t match the given new parent node type. Accepts an optional starting content match as third argument.

const clearIncompatible: (pos: number, parentType: NodeType, match?: ContentMatch) => this

delete

Delete the content between the given positions.

const delete: (from: number, to: number) => this

deleteRange

Delete the given range, expanding it to cover fully covered parent nodes until a valid replace is found.

const deleteRange: (from: number, to: number) => this

insert

Insert the given content at the given position.

const insert: (pos: number, content: ProseMirrorNode | ProseMirrorFragment | readonly ProseMirrorNode[]) => this

join

Join the blocks around the given position. If depth is 2, their last and first siblings are also joined, and so on.

const join: (pos: number, depth?: number) => this

lift

Split the content in the given range off from its parent, if there is sibling content before or after it, and move it up the tree to the depth specified by target. You’ll probably want to use liftTarget to compute target, to make sure the lift is valid.

const lift: (range: NodeRange, target: number) => this

maybeStep

Try to apply a step in this transformation, ignoring it if it fails. Returns the step result.

const maybeStep: (step: Step) => StepResult

removeMark

Remove marks from inline nodes between from and to. When mark is a single mark, remove precisely that mark. When it is a mark type, remove all marks of that type. When it is null, remove all marks of any type.

const removeMark: (from: number, to: number, mark?: null | MarkType | Mark) => this

removeNodeMark

Remove a mark (or all marks of the given type) from the node at position pos.

const removeNodeMark: (pos: number, mark: MarkType | Mark) => this

replace

Replace the part of the document between from and to with the given slice.

const replace: (from: number, to?: number, slice?: Slice) => this

replaceRange

Replace a range of the document with a given slice, using from, to, and the slice’s openStart property as hints, rather than fixed start and end points. This method may grow the replaced area or close open nodes in the slice in order to get a fit that is more in line with WYSIWYG expectations, by dropping fully covered parent nodes of the replaced region when they are marked non-defining as context, or including an open parent node from the slice that is marked as defining its content.

This is the method, for example, to handle paste. The similar replace method is a more primitive tool which will not move the start and end of its given range, and is useful in situations where you need more precise control over what happens.

const replaceRange: (from: number, to: number, slice: Slice) => this

replaceRangeWith

Replace the given range with a node, but use from and to as hints, rather than precise positions. When from and to are the same and are at the start or end of a parent node in which the given node doesn’t fit, this method may move them out towards a parent that does allow the given node to be placed. When the given range completely covers a parent node, this method may completely replace that parent node.

const replaceRangeWith: (from: number, to: number, node: ProseMirrorNode) => this

replaceWith

Replace the given range with the given content, which may be a fragment, node, or array of nodes.

const replaceWith: (from: number, to: number, content: ProseMirrorNode | ProseMirrorFragment | readonly ProseMirrorNode[]) => this

setBlockType

Set the type of all textblocks (partly) between from and to to the given node type with the given attributes.

const setBlockType: (from: number, to: undefined | number, type: NodeType, attrs?: null | Attrs | ((oldNode: ProseMirrorNode) => Attrs)) => this

setDocAttribute

Set a single attribute on the document to a new value.

const setDocAttribute: (attr: string, value: any) => this

setNodeAttribute

Set a single attribute on a given node to a new value. The pos addresses the document content. Use setDocAttribute to set attributes on the document itself.

const setNodeAttribute: (pos: number, attr: string, value: any) => this

setNodeMarkup

Change the type, attributes, and/or marks of the node at pos. When type isn’t given, the existing node type is preserved,

const setNodeMarkup: (pos: number, type?: null | NodeType, attrs?: null | Attrs, marks?: readonly Mark[]) => this

split

Split the node at the given position, and optionally, if depth is greater than one, any number of nodes above that. By default, the parts split off will inherit the node type of the original node. This can be changed by passing an array of types and attributes to use after the split (with the outermost nodes coming first).

const split: (pos: number, depth?: number, typesAfter?: (null | ({ attrs?: null | Attrs; type: NodeType }))[]) => this

step

Apply a new step in this transform, saving the result. Throws an error when the step fails.

const step: (step: Step) => this

wrap

Wrap the given range in the given set of wrappers. The wrappers are assumed to be valid in this position, and should probably be computed with findWrapping.

const wrap: (range: NodeRange, wrappers: readonly { attrs?: null | Attrs; type: NodeType }[]) => this

Mappable

There are several things that positions can be mapped through. Such objects conform to this interface.

map: (pos: number, assoc?: number) => number: Map a position through this object. When given, assoc (should be -1 or 1, defaults to 1) determines with which side the position is associated, which determines in which direction to move when a chunk of content is inserted at the mapped position.
mapResult: (pos: number, assoc?: number) => MapResult: Map a position, and return an object containing additional information about the mapping. The result’s deleted field tells you whether the position was deleted (completely enclosed in a replaced range) during the mapping. When content on only one side is deleted, the position itself is only considered deleted when assoc points in the direction of the deleted content.

canJoin

function canJoin(doc: ProseMirrorNode, pos: number): boolean

Test whether the blocks before and after a given position can be joined.

canSplit

function canSplit(doc: ProseMirrorNode, pos: number, depth?: number, typesAfter?: (null | ({ attrs?: null | Attrs; type: NodeType }))[]): boolean

Check whether splitting at the given position is allowed.

dropPoint

function dropPoint(doc: ProseMirrorNode, pos: number, slice: Slice): null | number

Finds a position at or around the given position where the given slice can be inserted. Will look at parent nodes’ nearest boundary and try there, even if the original position wasn’t directly at the start or end of that node. Returns null when no position was found.

findWrapping

function findWrapping(range: NodeRange, nodeType: NodeType, attrs?: null | Attrs, innerRange?: NodeRange): null | { attrs: null | Attrs; type: NodeType }[]

Try to find a valid way to wrap the content in the given range in a node of the given type. May introduce extra nodes around and inside the wrapper node, if necessary. Returns null if no valid wrapping could be found. When innerRange is given, that range’s content is used as the content to fit into the wrapping, instead of the content of range.

insertPoint

function insertPoint(doc: ProseMirrorNode, pos: number, nodeType: NodeType): null | number

Try to find a point where a node of the given type can be inserted near pos, by searching up the node hierarchy when pos itself isn’t a valid place but is at the start or end of a node. Return null if no position was found.

joinPoint

function joinPoint(doc: ProseMirrorNode, pos: number, dir?: number): undefined | number

Find an ancestor of the given position that can be joined to the block before (or after if dir is positive). Returns the joinable point, if any.

liftTarget

function liftTarget(range: NodeRange): null | number

Try to find a target depth to which the content in the given range can be lifted. Will not go across isolating parent nodes.

replaceStep

function replaceStep(doc: ProseMirrorNode, from: number, to?: number, slice?: Slice): null | Step

‘Fit’ a slice into a given position in the document, producing a step that inserts it. Will return null if there’s no meaningful way to insert the slice here, or inserting it would be a no-op (an empty slice over an empty range).