Reference manual
This is the reference manual for the
ProseMirror rich text editor. It
lists and describes the full public API exported by the library.
For more introductory material, please see the guides.
ProseMirror is distributed as a set of JavaScript modules. This
reference manual describes the exported API per module. So if you want
to use something from the edit module, you have to import
it from there.
var edit = require("prosemirror/dist/edit")
var editor = new edit.ProseMirror()
Or in ES6 syntax:
import {ProseMirror} from "prosemirror/dist/edit"
let editor = new ProseMirror()
Note that the content of the dist directory only exists in a built
version of code. If you are getting it from npm, you should be fine.
If you manually cloned the
git repository, you'll
need to npm install inside of it first.
This module implements the ProseMirror editor. It contains
functionality related to editing, selection, and integration with
the browser. ProseMirror is the class you'll want to instantiate
and interact with when using the editor.
Options
schema: Schema 📄The schema that the editor's document should use. Will
default to the schema of the doc option, if that is given.
doc: Node 📄The starting document.
place: ?union<DOMNode, fn(DOMNode)> 📄Determines the placement of the editor in the page. When null,
the editor is not placed. When a DOM node is given, the editor is
appended to that node. When a function is given, it is called
with the editor's wrapping DOM node, and is expected to place it
into the document.
historyDepth: number 📄The amount of history events that are collected before the oldest
events are discarded. Defaults to 100.
historyEventDelay: number 📄The amount of milliseconds that must pass between changes to
start a new history event. Defaults to 500.
scrollThreshold: number 📄The minimum distance to keep between the position of document
changes and the editor bounding rectangle before scrolling the view.
Defaults to 0.
scrollMargin: number 📄Determines how far to scroll when the scroll threshold is
surpassed. Defaults to 5.
keymap: Keymap 📄Sets the base keymap for the editor. Defaults to baseKeymap.
label: ?string 📄The label of the editor. When set, the editable DOM node gets an
aria-label attribute with this value.
translate(string) → string 📄Optional function to translate strings such as menu labels and prompts.
When set, should be a function that takes a string as argument and returns
a string, i.e. :: (string) → string
plugins: [Plugin] 📄A set of plugins to enable when the editor is initialized. Defaults
to the empty array.
This is the class used to represent instances of the editor. A
ProseMirror editor holds a document and a
selection, and displays an editable surface
representing that document in the browser document.
Constructor
new ProseMirror(opts: Object) 📄Construct a new editor from a set of options
and, if it has a place option, add it to the
document.
Properties
schema: Schema 📄The schema for this editor's document.
content: DOMNode 📄The editable DOM node containing the document.
wrapper: DOMNode 📄The outer DOM element of the editor.
on: Object<Subscription> 📄A wrapper object containing the various event
subscriptions
exposed by an editor instance.
change: Subscription<fn()> 📄Dispatched when the document has changed. See
setDoc and
transform for more specific
change-related events.
selectionChange: Subscription<fn()> 📄Indicates that the editor's selection has changed.
textInput: Subscription<fn(text: string)> 📄Dispatched when the user types text into the editor.
beforeSetDoc: Subscription<fn(doc: Node, selection: Selection)> 📄Dispatched when setDoc is called, before
the document is actually updated.
setDoc: Subscription<fn(doc: Node, selection: Selection)> 📄Dispatched when setDoc is called, after
the document is updated.
interaction: Subscription<fn()> 📄Dispatched when the user interacts with the editor, for example by
clicking on it or pressing a key while it is focused. Mostly
useful for closing or resetting transient UI state such as open
menus.
focus: Subscription<fn()> 📄Dispatched when the editor gains focus.
blur: Subscription<fn()> 📄Dispatched when the editor loses focus.
click: StoppableSubscription<fn(pos: number, event: DOMEvent)> 📄Dispatched when the editor is clicked. Return a truthy
value to indicate that the click was handled, and no further
action needs to be taken.
clickOn: StoppableSubscription<fn(pos: number, node: Node, nodePos: number, event: DOMEvent)> 📄Dispatched for every node around a click in the editor, before
click is dispatched, from inner to outer nodes. pos is
the position neares to the click, nodePos is the position
directly in front of node.
doubleClick: StoppableSubscription<fn(pos: number, event: DOMEvent)> 📄Dispatched when the editor is double-clicked.
doubleClickOn: StoppableSubscription<fn(pos: number, node: Node, nodePos: number, event: DOMEvent)> 📄Dispatched for every node around a double click in the
editor, before doubleClick is dispatched.
Dispatched when the context menu is opened on the editor.
Return a truthy value to indicate that you handled the event.
transformPasted: PipelineSubscription<fn(slice: Slice) → Slice> 📄Dispatched when something is pasted or dragged into the editor. The
given slice represents the pasted content, and your handler can
return a modified version to manipulate it before it is inserted
into the document.
transformPastedText: PipelineSubscription<fn(text: string) → string> 📄Dispatched when plain text is pasted. Handlers must return the given
string or a transformed version of it.
transformPastedHTML: PipelineSubscription<fn(html: string) → string> 📄Dispatched when html content is pasted or dragged into the editor.
Handlers must return the given string or a transformed
version of it.
transform: Subscription<fn(transform: Transform, selectionBeforeTransform: Selection, options: Object)> 📄Signals that a (non-empty) transformation has been aplied to
the editor. Passes the Transform, the selection before the
transform, and the options given to apply
as arguments to the handler.
beforeTransform: Subscription<fn(transform: Transform, options: Object)> 📄Indicates that the given transform is about to be
applied. The handler may add additional
steps to the transform, but it it not allowed to
interfere with the editor's state.
filterTransform: StoppableSubscription<fn(transform: Transform)> 📄Dispatched before a transform (applied without filter: false) is
applied. The handler can return a truthy value to cancel the
transform.
flushing: Subscription<fn()> 📄Dispatched when the editor is about to flush
an update to the DOM.
flush: Subscription<fn()> 📄Dispatched when the editor has finished
flushing an update to the DOM.
draw: Subscription<fn()> 📄Dispatched when the editor redrew its document in the DOM.
activeMarkChange: Subscription<fn()> 📄Dispatched when the set of active marks changes.
domPaste: StoppableSubscription<fn(DOMEvent)> 📄Dispatched when a DOM paste event happens on the editor.
Handlers may declare the event as being handled by calling
preventDefault on it or returning a truthy value.
domDrop: StoppableSubscription<fn(DOMEvent)> 📄Dispatched when a DOM drop event happens on the editor.
Handlers may declare the event as being handled by calling
preventDefault on it or returning a truthy value.
root: DOMDocument 📄The root document that the editor is part of. Initialized lazily
(falling back to the top-level document until the editor is
placed in the DOM) to make sure asynchronously adding the editor
to a shadow DOM works correctly.
selection: Selection 📄Get the current selection.
doc: Node 📄The current document.
history: History 📄The edit history for the editor.
tr: EditorTransform 📄Create an editor- and selection-aware Transform object for this
editor.
Methods
getOption(name: string) → any 📄Get the value of the given option.
setTextSelection(anchor: number, head: ?number = anchor) 📄Set the selection to a text selection from
anchor to head, or, if head is null, a cursor selection at
anchor.
setNodeSelection(pos: number) 📄Set the selection to a node selection on the node after pos.
setSelection(selection: Selection) 📄Set the selection to the given selection object.
setDoc(doc: Node, sel: ?Selection) 📄Set the editor's content, and optionally include a new selection.
apply(transform: Transform, options: ?Object = nullOptions) → Transform 📄Apply a transformation (which you might want to create with the
tr getter) to the document in the editor.
The following options are supported:
scrollIntoView: ?bool- When true, scroll the selection into view on the next
redraw.
selection: ?Selection- A new selection to set after the transformation is applied.
If
transform is an EditorTransform, this will default to
that object's current selection. If no selection is provided,
the new selection is determined by mapping
the existing selection through the transform.
filter: ?bool- When set to false, suppresses the ability of the
filterTransform event
to cancel this transform.
Returns the transform itself.
flush() → bool 📄Flush any pending changes to the DOM. When the document,
selection, or marked ranges in an editor change, the DOM isn't
updated immediately, but rather scheduled to be updated the next
time the browser redraws the screen. This method can be used to
force this to happen immediately. It can be useful when you, for
example, want to measure where on the screen a part of the
document ends up, immediately after changing the document.
Returns true when it updated the document DOM.
addKeymap(map: Keymap, priority: ?number = 0) 📄Add a
keymap
to the editor. Keymaps added in this way are queried before the
base keymap. The priority parameter can be used to
control when they are queried relative to other maps added like
this. Maps with a higher priority get queried first.
removeKeymap(map: union<string, Keymap>) 📄Remove the given keymap, or the keymap with the given name, from
the editor.
markRange(from: number, to: number, options: ?Object) → MarkedRange 📄Create a marked range between the given positions. Marked ranges
“track” the part of the document they point to—as the document
changes, they are updated to move, grow, and shrink along with
their content.
The options parameter may be an object containing these properties:
inclusiveLeft: bool = false- Whether the left side of the range is inclusive. When it is,
content inserted at that point will become part of the range.
When not, it will be outside of the range.
inclusiveRight: bool = false- Whether the right side of the range is inclusive.
removeWhenEmpty: bool = true- Whether the range should be forgotten when it becomes empty
(because all of its content was deleted).
className: string- A CSS class to add to the inline content that is part of this
range.
onRemove: fn(number, number)- When given, this function will be called when the range is
removed from the editor.
removeRange(range: MarkedRange) 📄Remove the given range from the editor.
activeMarks() → [Mark] 📄Get the marks at the cursor. By default, this yields the marks
associated with the content at the cursor, as per Node.marksAt.
But if the set of active marks was updated with
addActiveMark or
removeActiveMark, the updated
set is returned.
addActiveMark(mark: Mark) 📄Add a mark to the set of overridden active marks that will be
applied to subsequently typed text. Does not do anything when the
selection isn't collapsed.
removeActiveMark(markType: MarkType) 📄Remove any mark of the given type from the set of overidden active marks.
focus() 📄Give the editor focus.
hasFocus() → bool 📄Query whether the editor has focus.
posAtCoords(coords: {top: number, left: number}) → ?number 📄If the given coordinates (which should be relative to the top
left corner of the window—not the page) fall within the editable
content, this method will return the document position that
corresponds to those coordinates.
contextAtCoords(coords: {top: number, left: number}) → ?{pos: number, inside: [{pos: number, node: Node}]} 📄If the given coordinates fall within the editable content, this
method will return the document position that corresponds to
those coordinates, along with a stack of nodes and their
positions (excluding the top node) that the coordinates fall
into.
coordsAtPos(pos: number) → {top: number, left: number, bottom: number} 📄Find the screen coordinates (relative to top left corner of the
window) of the given document position.
scrollIntoView(pos: ?number = null) 📄Scroll the given position, or the cursor position if pos isn't
given, into view.
translate(string: string) → string 📄Return a translated string, if a translate function
has been supplied, or the original string.
scheduleDOMUpdate(f: fn() → ?fn() → ?fn()) 📄Schedule a DOM update function to be called either the next time
the editor is flushed, or if no flush happens
immediately, after 200 milliseconds. This is used to synchronize
DOM updates and read to prevent DOM layout
thrashing.
Often, your updates will need to both read and write from the DOM.
To schedule such access in lockstep with other modules, the
function you give can return another function, which may return
another function, and so on. The first call should write to the
DOM, and not read. If a read needs to happen, that should be
done in the function returned from the first call. If that has to
be followed by another write, that should be done in a function
returned from the second function, and so on.
unscheduleDOMUpdate(f: fn() → ?fn() → ?fn()) 📄Cancel an update scheduled with scheduleDOMUpdate. Calling this
with a function that is not actually scheduled is harmless.
updateScheduler(subscriptions: [Subscription], start: fn() → ?fn()) → UpdateScheduler 📄Creates an update scheduler for this editor. subscriptions
should be an array of subscriptions to listen for. start should
be a function as expected by
scheduleDOMUpdate.
An editor selection. Can be one of two selection types:
TextSelection or NodeSelection. Both have the properties
listed here, but also contain more information (such as the
selected node or the
head and anchor).
Properties
from: number 📄The left bound of the selection.
to: number 📄The right bound of the selection.
$from: ResolvedPos 📄The resolved left bound of the selection
$to: ResolvedPos 📄The resolved right bound of the selection
empty: bool 📄True if the selection is an empty text selection (head an anchor
are the same).
Methods
eq(other: Selection) → bool 📄Test whether the selection is the same as another selection.
map(doc: Node, mapping: Mappable) → Selection 📄Map this selection through a mappable thing. doc
should be the new document, to which we are mapping.
Extends Selection.
A text selection represents a classical editor
selection, with a head (the moving side) and anchor (immobile
side), both of which point into textblock nodes. It can be empty (a
regular cursor position).
Constructor
new TextSelection($anchor: ResolvedPos, $head: ?ResolvedPos = $anchor) 📄Construct a text selection. When head is not given, it defaults
to anchor.
Properties
anchor: number 📄The selection's immobile side (does not move when pressing
shift-arrow).
head: number 📄The selection's mobile side (the side that moves when pressing
shift-arrow).
$anchor: ResolvedPos 📄The resolved anchor of the selection.
$head: ResolvedPos 📄The resolved head of the selection.
Extends Selection.
A node selection is a selection that points at a
single node. All nodes marked selectable
can be the target of a node selection. In such an object, from
and to point directly before and after the selected node.
Constructor
new NodeSelection($from: ResolvedPos) 📄Create a node selection. Does not verify the validity of its
argument. Use ProseMirror.setNodeSelection for an easier,
error-checking way to create a node selection.
Properties
node: Node 📄The selected node.
A plugin is a piece of functionality that can be attached to a
ProseMirror instance. It may do something like show a
menu or wire in collaborative editing. The
plugin object is the interface to enabling and disabling the
plugin, and for those where this is relevant, for accessing its
state.
Constructor
new Plugin(State: constructor, options: ?Object) 📄Create a plugin object for the given state class. If desired, you
can pass a collection of options. When initializing the plugin,
it will receive the ProseMirror instance and the options as
arguments to its constructor.
Methods
get(pm: ProseMirror) → ?any 📄Return the plugin state for the given editor, if any.
attach(pm: ProseMirror) → any 📄Initialize the plugin for the given editor. If it was already
enabled, this throws an error.
detach(pm: ProseMirror) 📄Disable the plugin in the given editor. If the state has a
detach method, that will be called with the editor as argument,
to give it a chance to clean up.
ensure(pm: ProseMirror) → any 📄Get the plugin state for an editor. Initializes the plugin if it
wasn't already active.
config(options: ?Object) → Plugin 📄Configure the plugin. The given options will be combined with the
existing (default) options, with the newly provided ones taking
precedence. Returns a new plugin object with the new
configuration.
An undo/redo history manager for an editor instance.
Properties
undoDepth: number 📄The amount of undoable events available.
redoDepth: number 📄The amount of redoable events available.
Methods
undo() → bool 📄Undo one history event. The return value indicates whether
anything was actually undone. Note that in a collaborative
context, or when changes are applied
without adding them to the history, it is possible for
undoDepth to have a positive value, but
this method to still return false, when non-history changes
overwrote all remaining changes in the history.
redo() → bool 📄Redo one history event. The return value indicates whether
anything was actually redone.
getVersion() → Object 📄Get the current ‘version’ of the editor content. This can be used
to later check whether anything changed, or
to roll back to this version.
isAtVersion(version: Object) → bool 📄Returns true when the editor history is in the state that it
was when the given version was recorded.
That means either no changes were made, or changes were
done/undone and then undone/redone again.
backToVersion(version: Object) → bool 📄Rolls back all changes made since the given
version was recorded. Returns false if
that version was no longer found in the history, and thus the
action could not be completed.
A marked range as created by
markRange.
Properties
from: ?number 📄The current start position of the range. Updated whenever the
editor's document is changed. Set to null when the marked
range is removed.
to: ?number 📄The current end position of the range. Updated whenever the
editor's document is changed. Set to null when the marked
range is removed.
Extends Transform.
A selection-aware extension of Transform. Use
ProseMirror.tr to create an instance.
selection: Selection 📄The transform's current selection. This defaults to the
editor selection mapped through the steps in
this transform, but can be overwritten with
setSelection.
apply(options: ?Object) → EditorTransform 📄Apply the transformation. Returns the transform, or false it is
was empty.
applyAndScroll() → EditorTransform 📄Apply this transform with a {scrollIntoView: true} option.
setSelection(selection: Selection) → EditorTransform 📄Update the transform's current selection. This will determine the
selection that the editor gets when the transform is applied.
replaceSelection(node: ?Node, inheritMarks: ?bool) → EditorTransform 📄Replace the selection with the given node, or delete it if node
is null. When inheritMarks is true and the node is an inline
node, it inherits the marks from the place where it is inserted.
deleteSelection() → EditorTransform 📄Delete the selection.
typeText(text: string) → EditorTransform 📄Replace the selection with a text node containing the given string.
Helper for scheduling updates whenever any of a series of events
happen. Created with the
updateScheduler method.
Methods
detach() 📄Detach the event handlers registered by this scheduler.
force() 📄Force an update. Note that if the editor has scheduled a flush,
the update is still delayed until the flush occurs.
Constants
commands: Object 📄This object contains a number of ‘commands‘, functions that take a
ProseMirror instance and try to perform some action on it,
returning false if they don't apply. These are used to bind keys
to, and to define menu items.
Most of the command functions defined here take a second, optional,
boolean parameter. This can be set to false to do a ‘dry run’,
where the function won't take any actual action, but will return
information about whether it applies.
chainCommands(...commands: [fn(ProseMirror, ?bool) → bool]) → fn(ProseMirror, ?bool) → bool 📄Combine a number of command functions into a single function (which
calls them one by one until one returns something other than
false).
deleteSelection(pm: ProseMirror, apply: ?bool) → bool 📄Delete the selection, if there is one.
joinBackward(pm: ProseMirror, apply: ?bool) → bool 📄If the selection is empty and at the start of a textblock, move
that block closer to the block before it, by lifting it out of its
parent or, if it has no parent it doesn't share with the node
before it, moving it into a parent of that node, or joining it with
that.
joinForward(pm: ProseMirror, apply: ?bool) → bool 📄If the selection is empty and the cursor is at the end of a
textblock, move the node after it closer to the node with the
cursor (lifting it out of parents that aren't shared, moving it
into parents of the cursor block, or joining the two when they are
siblings).
deleteCharBefore(pm: ProseMirror, apply: ?bool) → bool 📄Delete the character before the cursor, if the selection is empty
and the cursor isn't at the start of a textblock.
deleteWordBefore(pm: ProseMirror, apply: ?bool) → bool 📄Delete the word before the cursor, if the selection is empty and
the cursor isn't at the start of a textblock.
deleteCharAfter(pm: ProseMirror, apply: ?bool) → bool 📄Delete the character after the cursor, if the selection is empty
and the cursor isn't at the end of its textblock.
deleteWordAfter(pm: ProseMirror, apply: ?bool) → bool 📄Delete the word after the cursor, if the selection is empty and the
cursor isn't at the end of a textblock.
joinUp(pm: ProseMirror, apply: ?bool) → bool 📄Join the selected block or, if there is a text selection, the
closest ancestor block of the selection that can be joined, with
the sibling above it.
joinDown(pm: ProseMirror, apply: ?bool) → bool 📄Join the selected block, or the closest ancestor of the selection
that can be joined, with the sibling after it.
lift(pm: ProseMirror, apply: ?bool) → bool 📄Lift the selected block, or the closest ancestor block of the
selection that can be lifted, out of its parent node.
newlineInCode(pm: ProseMirror, apply: ?bool) → bool 📄If the selection is in a node whose type has a truthy isCode
property, replace the selection with a newline character.
createParagraphNear(pm: ProseMirror, apply: ?bool) → bool 📄If a block node is selected, create an empty paragraph before (if
it is its parent's first child) or after it.
liftEmptyBlock(pm: ProseMirror, apply: ?bool) → bool 📄If the cursor is in an empty textblock that can be lifted, lift the
block.
splitBlock(pm: ProseMirror, apply: ?bool) → bool 📄Split the parent block of the selection. If the selection is a text
selection, delete it.
selectParentNode(pm: ProseMirror, apply: ?bool) → bool 📄Move the selection to the node wrapping the current selection, if
any. (Will not select the document node.)
undo(pm: ProseMirror, apply: ?bool) → bool 📄Undo the most recent change event, if any.
redo(pm: ProseMirror, apply: ?bool) → bool 📄Redo the most recently undone change event, if any.
wrapIn(nodeType: NodeType, attrs: ?Object) → fn(pm: ProseMirror, apply: ?bool) → bool 📄Wrap the selection in a node of the given type with the given
attributes. When apply is false, just tell whether this is
possible, without performing any action.
setBlockType(nodeType: NodeType, attrs: ?Object) → fn(pm: ProseMirror, apply: ?bool) → bool 📄Try to the textblock around the selection to the given node type
with the given attributes. Return true when this is possible. If
apply is false, just report whether the change is possible,
don't perform any action.
wrapInList(nodeType: NodeType, attrs: ?Object) → fn(pm: ProseMirror, apply: ?bool) → bool 📄Returns a command function that wraps the selection in a list with
the given type an attributes. If apply is false, only return a
value to indicate whether this is possible, but don't actually
perform the change.
splitListItem(nodeType: NodeType) → fn(pm: ProseMirror) → bool 📄Build a command that splits a non-empty textblock at the top level
of a list item by also splitting that list item.
liftListItem(nodeType: NodeType) → fn(pm: ProseMirror, apply: ?bool) → bool 📄Create a command to lift the list item around the selection up into
a wrapping list.
sinkListItem(nodeType: NodeType) → fn(pm: ProseMirror, apply: ?bool) → bool 📄Create a command to sink the list item around the selection down
into an inner list.
toggleMark(markType: MarkType, attrs: ?Object) → fn(pm: ProseMirror, apply: ?bool) → bool 📄Create a command function that toggles the given mark with the
given attributes. Will return false when the current selection
doesn't support that mark. If apply is not false, it will
remove the mark if any marks of that type exist in the selection,
or add it otherwise. If the selection is empty, this applies to the
active marks instead of a range of the
document.
baseKeymap: Keymap 📄
This module defines ProseMirror's document model, the data
structure used to define and inspect content documents. It
includes:
This module does not depend on the browser API being available
(i.e. you can load it into any JavaScript environment).
This class represents a node in the tree that makes up a
ProseMirror document. So a document is an instance of Node, with
children that are also instances of Node.
Nodes are persistent data structures. Instead of changing them, you
create new ones with the content you want. Old ones keep pointing
at the old document shape. This is made cheaper by sharing
structure between the old and new data as much as possible, which a
tree shape like this (without back pointers) makes easy.
Never directly mutate the properties of a Node object. See
this guide for more information.
Properties
type: NodeType 📄The type of node that this is.
attrs: Object 📄An object mapping attribute names to values. The kind of
attributes allowed and required are determined by the node
type.
content: Fragment 📄A container holding the node's children.
marks: [Mark] 📄The marks (things like whether it is emphasized or part of a
link) associated with this node.
text: ?string 📄For text nodes, this contains the node's text content.
nodeSize: number 📄The size of this node. For text nodes, this is the amount of
characters. For leaf nodes, it is one. And for non-leaf nodes, it
is the size of the content plus two (the start and end token).
childCount: number 📄The number of children that the node has.
textContent: string 📄Concatenates all the text nodes found in this fragment and its
children.
firstChild: ?Node 📄Returns this node's first child, or null if there are no
children.
lastChild: ?Node 📄Returns this node's last child, or null if there are no
children.
isBlock: bool 📄True when this is a block (non-inline node)
isTextblock: bool 📄True when this is a textblock node, a block node with inline
content.
isInline: bool 📄True when this is an inline node (a text node or a node that can
appear among text).
isText: bool 📄True when this is a text node.
Methods
child(index: number) → Node 📄Get the child node at the given index. Raises an error when the
index is out of range.
maybeChild(index: number) → ?Node 📄Get the child node at the given index, if it exists.
forEach(f: fn(node: Node, offset: number, index: number)) 📄Call f for every child node, passing the node, its offset
into this parent node, and its index.
textBetween(from: number, to: number, separator: ?string) → string 📄Get all text between positions from and to. When separator
is given, it will be inserted whenever a new block node is
started.
eq(other: Node) → bool 📄Test whether two nodes represent the same content.
sameMarkup(other: Node) → bool 📄Compare the markup (type, attributes, and marks) of this node to
those of another. Returns true if both have the same markup.
hasMarkup(type: NodeType, attrs: ?Object, marks: ?[Mark]) → bool 📄Check whether this node's markup correspond to the given type,
attributes, and marks.
copy(content: ?Fragment = null) → Node 📄Create a new node with the same markup as this node, containing
the given content (or empty, if no content is given).
mark(marks: [Mark]) → Node 📄Create a copy of this node, with the given set of marks instead
of the node's own marks.
cut(from: number, to: ?number) → Node 📄Create a copy of this node with only the content between the
given offsets. If to is not given, it defaults to the end of
the node.
slice(from: number, to: ?number = this.content.size) → Slice 📄Cut out the part of the document between the given positions, and
return it as a Slice object.
replace(from: number, to: number, slice: Slice) → Node 📄Replace the part of the document between the given positions with
the given slice. The slice must 'fit', meaning its open sides
must be able to connect to the surrounding content, and its
content nodes must be valid children for the node they are placed
into. If any of this is violated, an error of type ReplaceError
is thrown.
nodeAt(pos: number) → ?Node 📄Find the node after the given position.
childAfter(pos: number) → {node: ?Node, index: number, offset: number} 📄Find the (direct) child node after the given offset, if any,
and return it along with its index and offset relative to this
node.
childBefore(pos: number) → {node: ?Node, index: number, offset: number} 📄Find the (direct) child node before the given offset, if any,
and return it along with its index and offset relative to this
node.
nodesBetween(from: ?number, to: ?number, f: fn(node: Node, pos: number, parent: Node, index: number)) 📄Iterate over all nodes between the given two positions, calling
the callback with the node, its position, its parent
node, and its index in that node.
descendants(f: fn(node: Node, pos: number, parent: Node)) 📄Call the given callback for every descendant node.
resolve(pos: number) → ResolvedPos 📄Resolve the given position in the document, returning an object
describing its path through the document.
marksAt(pos: number) → [Mark] 📄Get the marks at the given position factoring in the surrounding marks'
inclusiveLeft and inclusiveRight properties. If the position is at the
start of a non-empty node, the marks of the node after it are returned.
rangeHasMark(from: ?number, to: ?number, type: MarkType) → bool 📄Test whether a mark of the given type occurs in this document
between the two given positions.
toString() → string 📄Return a string representation of this node for debugging
purposes.
contentMatchAt(index: number) → ContentMatch 📄Get the content match in this node at the given index.
canReplace(from: number, to: number, replacement: ?Fragment, start: ?number, end: ?number) → bool 📄Test whether replacing the range from to to (by index) with
the given replacement fragment (which defaults to the empty
fragment) would leave the node's content valid. You can
optionally pass start and end indices into the replacement
fragment.
canReplaceWith(from: number, to: number, type: NodeType, attrs: ?[Mark]) → bool 📄Test whether replacing the range from to to (by index) with a
node of the given type with the given attributes and marks would
be valid.
canAppend(other: Node) → bool 📄Test whether the given node's content could be appended to this
node. If that node is empty, this will only return true if there
is at least one node type that can appear in both nodes (to avoid
merging completely incompatible nodes).
toJSON() → Object 📄Return a JSON-serializeable representation of this node.
toDOM(options: ?Object = {}) → DOMNode 📄Serialize this node to a DOM node. This can be useful when you
need to serialize a part of a document, as opposed to the whole
document, but you'll usually want to do
doc.content.toDOM() instead.
Static properties
fromJSON(schema: Schema, json: Object) → Node 📄Deserialize a node from its JSON representation.
The usual way to represent positions in a document is with a
plain integer. Since those tell you very little about the context
of that position, you'll often have to 'resolve' a position to get
the context you need. Objects of this class represent such a
resolved position, providing various pieces of context information
and helper methods.
Throughout this interface, methods that take an optional depth
parameter will interpret undefined as this.depth and negative
numbers as this.depth + value.
Properties
pos: number 📄The position that was resolved.
depth: number 📄The number of levels the parent node is from the root. If this
position points directly into the root, it is 0. If it points
into a top-level paragraph, 1, and so on.
parentOffset: number 📄The offset this position has into its parent node.
parent: Node 📄The parent node that the position points into. Note that even if
a position points into a text node, that node is not considered
the parent—text nodes are 'flat' in this model.
atNodeBoundary: bool 📄True if this position points at a node boundary, false if it
points into a text node.
nodeAfter: ?Node 📄Get the node directly after the position, if any. If the position
points into a text node, only the part of that node after the
position is returned.
nodeBefore: ?Node 📄Get the node directly before the position, if any. If the
position points into a text node, only the part of that node
before the position is returned.
Methods
node(depth: ?number) → Node 📄The ancestor node at the given level. p.node(p.depth) is the
same as p.parent.
index(depth: ?number) → number 📄The index into the ancestor at the given level. If this points at
the 3rd node in the 2nd paragraph on the top level, for example,
p.index(0) is 2 and p.index(1) is 3.
indexAfter(depth: ?number) → number 📄The index pointing after this position into the ancestor at the
given level.
start(depth: ?number) → number 📄The (absolute) position at the start of the node at the given
level.
end(depth: ?number) → number 📄The (absolute) position at the end of the node at the given
level.
before(depth: ?number) → number 📄The (absolute) position directly before the node at the given
level, or, when level is this.level + 1, the original
position.
after(depth: ?number) → number 📄The (absolute) position directly after the node at the given
level, or, when level is this.level + 1, the original
position.
sameDepth(other: ResolvedPos) → number 📄The depth up to which this position and the other share the same
parent nodes.
blockRange(other: ?ResolvedPos = this, pred: ?fn(Node) → bool) → ?NodeRange 📄Returns a range based on the place where this position and the
given position diverge around block content. If both point into
the same textblock, for example, a range around that textblock
will be returned. If they point into different blocks, the range
around those blocks or their ancestors in their common ancestor
is returned. You can pass in an optional predicate that will be
called with a parent node to see if a range into that parent is
acceptable.
sameParent(other: ResolvedPos) → bool 📄Query whether the given position shares the same parent node.
Represents a flat range of content.
Properties
$from: ResolvedPos 📄A resolved position along the start of the
content. May have a depth greater than this object's depth
property, since these are the positions that were used to
compute the range, not re-resolved positions directly at its
boundaries.
$to: ResolvedPos 📄A position along the end of the content. See
caveat for from.
depth: number 📄The depth of the node that this range points into.
start: number 📄The position at the start of the range.
end: number 📄The position at the end of the range.
parent: Node 📄The parent node that the range points into.
startIndex: number 📄The start index of the range in the parent node.
endIndex: number 📄The end index of the range in the parent node.
Fragment is the type used to represent a node's collection of
child nodes.
Fragments are persistent data structures. That means you should
not mutate them or their content, but create new instances
whenever needed. The API tries to make this easy.
Properties
firstChild: ?Node 📄The first child of the fragment, or null if it is empty.
lastChild: ?Node 📄The last child of the fragment, or null if it is empty.
childCount: number 📄The number of child nodes in this fragment.
Methods
toString() → string 📄Return a debugging string that describes this fragment.
cut(from: number, to: ?number) → Fragment 📄Cut out the sub-fragment between the two given positions.
append(other: Fragment) → Fragment 📄Create a new fragment containing the content of this fragment and
other.
replaceChild(index: number, node: Node) → Fragment 📄Create a new fragment in which the node at the given index is
replaced by the given node.
toJSON() → ?Object 📄Create a JSON-serializeable representation of this fragment.
eq(other: Fragment) → bool 📄Compare this fragment to another one.
child(index: number) → Node 📄Get the child node at the given index. Raise an error when the
index is out of range.
maybeChild(index: number) → ?Node 📄Get the child node at the given index, if it exists.
forEach(f: fn(node: Node, offset: number, index: number)) 📄Call f for every child node, passing the node, its offset
into this parent node, and its index.
findDiffStart(other: Fragment) → ?number 📄Find the first position at which this fragment and another
fragment differ, or null if they are the same.
findDiffEnd(other: Node) → ?{a: number, b: number} 📄Find the first position, searching from the end, at which this
fragment and the given fragment differ, or null if they are the
same. Since this position will not be the same in both nodes, an
object with two separate positions is returned.
toDOM(options: ?Object = {}) → DOMFragment 📄Serialize the content of this fragment to a DOM fragment. When
not in the browser, the document option, containing a DOM
document, should be passed so that the serialize can create
nodes.
To specify rendering behavior for your own node and
mark types, define a toDOM
method on them.
Static properties
fromJSON(schema: Schema, value: ?Object) → Fragment 📄Deserialize a fragment from its JSON representation.
fromArray(array: [Node]) → Fragment 📄Build a fragment from an array of nodes. Ensures that adjacent
text nodes with the same style are joined together.
from(nodes: ?union<Fragment, Node, [Node]>) → Fragment 📄Create a fragment from something that can be interpreted as a set
of nodes. For null, it returns the empty fragment. For a
fragment, the fragment itself. For a node or array of nodes, a
fragment containing those nodes.
empty: Fragment 📄An empty fragment. Intended to be reused whenever a node doesn't
contain anything (rather than allocating a new empty fragment for
each leaf node).
Extends ProseMirrorError.
Error type raised by Node.replace when given an invalid
replacement.
A slice represents a piece cut out of a larger document. It
stores not only a fragment, but also the depth up to which nodes on
both side are 'open' / cut through.
Constructor
new Slice(content: Fragment, openLeft: number, openRight: number, possibleParent: ?Node) 📄
Properties
content: Fragment 📄The slice's content nodes.
openLeft: number 📄The open depth at the start.
openRight: number 📄The open depth at the end.
size: number 📄The size this slice would add when inserted into a document.
Methods
toJSON() → ?Object 📄Convert a slice to a JSON-serializable representation.
Static properties
fromJSON(schema: Schema, json: ?Object) → Slice 📄Deserialize a slice from its JSON representation.
empty: Slice 📄The empty slice.
A mark is a piece of information that can be attached to a node,
such as it being emphasized, in code font, or a link. It has a type
and optionally a set of attributes that provide further information
(such as the target of the link). Marks are created through a
Schema, which controls which types exist and which
attributes they have.
Properties
type: MarkType 📄The type of this mark.
attrs: Object 📄The attributes associated with this mark.
Methods
toJSON() → Object 📄Convert this mark to a JSON-serializeable representation.
addToSet(set: [Mark]) → [Mark] 📄Given a set of marks, create a new set which contains this one as
well, in the right position. If this mark is already in the set,
the set itself is returned. If a mark of this type with different
attributes is already in the set, a set in which it is replaced
by this one is returned.
removeFromSet(set: [Mark]) → [Mark] 📄Remove this mark from the given set, returning a new set. If this
mark is not in the set, the set itself is returned.
isInSet(set: [Mark]) → bool 📄Test whether this mark is in the given set of marks.
eq(other: Mark) → bool 📄Test whether this mark has the same type and attributes as
another mark.
Static properties
sameSet(a: [Mark], b: [Mark]) → bool 📄Test whether two sets of marks are identical.
setFrom(marks: ?union<Mark, [Mark]>) → [Mark] 📄Create a properly sorted mark set from null, a single mark, or an
unsorted array of marks.
none: [Mark] 📄The empty set of marks.
Node types are objects allocated once per Schema
and used to tag Node instances with a type. They are
instances of sub-types of this class, and contain information about
the node type (its name, its allowed attributes, methods for
serializing it to various formats, information to guide
deserialization, and so on).
Properties
name: string 📄The name the node type has in this schema.
schema: Schema 📄A link back to the Schema the node type belongs to.
attrs: Object<Attribute> 📄The attributes for this node type.
isBlock: bool 📄True if this is a block type.
isTextblock: bool 📄True if this is a textblock type, a block that contains inline
content.
isInline: bool 📄True if this is an inline type.
isText: bool 📄True if this is the text node type.
isLeaf: bool 📄True for node types that allow no content.
selectable: bool 📄Controls whether nodes of this type can be selected (as a node
selection).
draggable: bool 📄Determines whether nodes of this type can be dragged. Enabling it
causes ProseMirror to set a draggable attribute on its DOM
representation, and to put its HTML serialization into the drag
event's data
transfer
when dragged.
matchDOMTag: Object<union<ParseSpec, fn(DOMNode) → union<bool, ParseSpec>>> 📄Defines the way nodes of this type are parsed. Should, if
present, contain an object mapping CSS selectors (such as "p"
for <p> tags, or "div[data-type=foo]" for <div> tags with a
specific attribute) to parse specs or functions
that, when given a DOM node, return either false or a parse
spec.
Methods
create(attrs: ?Object, content: ?union<Fragment, Node, [Node]>, marks: ?[Mark]) → Node 📄Create a Node of this type. The given attributes are
checked and defaulted (you can pass null to use the type's
defaults entirely, if no required attributes exist). content
may be a Fragment, a node, an array of nodes, or
null. Similarly marks may be null to default to the empty
set of marks.
createChecked(attrs: ?Object, content: ?union<Fragment, Node, [Node]>, marks: ?[Mark]) → Node 📄Like create, but check the given content
against the node type's content restrictions, and throw an error
if it doesn't match.
createAndFill(attrs: ?Object, content: ?union<Fragment, Node, [Node]>, marks: ?[Mark]) → ?Node 📄Like create, but see if it is necessary to
add nodes to the start or end of the given fragment to make it
fit the node. If no fitting wrapping can be found, return null.
Note that, due to the fact that required nodes can always be
created, this will always succeed if you pass null or
Fragment.empty as content.
validContent(content: Fragment, attrs: ?Object) → bool 📄Returns true if the given fragment is valid content for this node
type with the given attributes.
toDOM(_: Node) → DOMOutputSpec 📄Defines the way a node of this type should be serialized to
DOM/HTML. Should return an array structure that
describes the resulting DOM structure, with an optional number
zero (“hole”) in it to indicate where the node's content should
be inserted.
Extends NodeType.
Base type for block nodetypes.
Extends NodeType.
Base type for inline node types.
Extends Inline.
The text node type.
Attributes are named values associated with nodes and marks.
Each node type or mark type has a fixed set of attributes, which
instances of this class are used to control. Attribute values must
be JSON-serializable.
Constructor
new Attribute(options: ?Object = {}) 📄Create an attribute. options is an object containing the
settings for the attributes. The following settings are
supported:
default: ?any- The default value for this attribute, to choose when no
explicit value is provided.
compute: ?() → any- A function that computes a default value for the attribute.
Attributes that have no default or compute property must be
provided whenever a node or mark of a type that has them is
created.
Like nodes, marks (which are associated with nodes to signify
things like emphasis or being part of a link) are tagged with type
objects, which are instantiated once per Schema.
Properties
name: string 📄The name of the mark type.
schema: Schema 📄The schema that this mark type instance is part of.
inclusiveRight: bool 📄Whether this mark should be active when the cursor is positioned
at the end of the mark.
matchDOMTag: Object<union<ParseSpec, fn(DOMNode) → union<bool, ParseSpec>>> 📄Defines the way marks of this type are parsed. Works just like
NodeType.matchTag, but produces marks rather than nodes.
matchDOMStyle: Object<union<?Object, fn(string) → union<bool, ?Object>>> 📄Defines the way DOM styles are mapped to marks of this type. Should
contain an object mapping CSS property names, as found in inline
styles, to either attributes for this mark (null for default
attributes), or a function mapping the style's value to either a
set of attributes or false to indicate that the style does not
match.
Methods
create(attrs: ?Object) → Mark 📄Create a mark of this type. attrs may be null or an object
containing only some of the mark's attributes. The others, if
they have defaults, will be added.
removeFromSet(set: [Mark]) → [Mark] 📄When there is a mark of this type in the given set, a new set
without it is returned. Otherwise, the input set is returned.
isInSet(set: [Mark]) → ?Mark 📄Tests whether there is a mark of this type in the given set.
toDOM(mark: Mark) → DOMOutputSpec 📄Defines the way marks of this type should be serialized to DOM/HTML.
An object describing a schema, as passed to the Schema
constructor.
nodes: union<Object<NodeSpec>, OrderedMap<NodeSpec>> 📄The node types in this schema. Maps names to NodeSpec objects
describing the node to be associated with that name. Their order is significant
marks: ?union<Object<constructor<MarkType>>, OrderedMap<constructor<MarkType>>> 📄The mark types that exist in this schema.
type: constructor<NodeType> 📄The NodeType class to be used for this node.
content: ?string 📄The content expression for this node, as described in the schema
guide. When not given, the node does not allow
any content.
group: ?string 📄The group or space-separated groups to which this node belongs, as
referred to in the content expressions for the schema.
Each document is based on a single schema, which provides the
node and mark types that it is made up of (which, in turn,
determine the structure it is allowed to have).
Constructor
new Schema(spec: SchemaSpec, data: ?any) 📄Construct a schema from a specification.
Properties
nodeSpec: OrderedMap<NodeSpec> 📄The node specs that the schema is based on.
markSpec: OrderedMap<constructor<MarkType>> 📄The mark spec that the schema is based on.
data: any 📄A generic field that you can use (by passing a value to
the constructor) to store arbitrary data or references in your
schema object, for use by node- or mark- methods.
nodes: Object<NodeType> 📄An object mapping the schema's node names to node type objects.
marks: Object<MarkType> 📄A map from mark names to mark type objects.
cached: Object 📄An object for storing whatever values modules may want to
compute and cache per schema. (If you want to store something
in it, try to use property names unlikely to clash.)
Methods
node(type: union<string, NodeType>, attrs: ?Object, content: ?union<Fragment, Node, [Node]>, marks: ?[Mark]) → Node 📄Create a node in this schema. The type may be a string or a
NodeType instance. Attributes will be extended
with defaults, content may be a Fragment,
null, a Node, or an array of nodes.
When creating a text node, content should be a string and is
interpreted as the node's text.
This method is bound to the Schema, meaning you don't have to
call it as a method, but can pass it to higher-order functions
and such.
text(text: string, marks: ?[Mark]) → Node 📄Create a text node in the schema. This method is bound to the
Schema. Empty text nodes are not allowed.
mark(name: string, attrs: ?Object) → Mark 📄Create a mark with the named type
nodeFromJSON(json: Object) → Node 📄Deserialize a node from its JSON representation. This method is
bound.
markFromJSON(json: Object) → Mark 📄Deserialize a mark from its JSON representation. This method is
bound.
nodeType(name: string) → NodeType 📄Get the NodeType associated with the given name in
this schema, or raise an error if it does not exist.
parseDOM(dom: DOMNode, options: ?Object = {}) → Node 📄Parse a document from the content of a DOM node. To provide an
explicit parent document (for example, when not in a browser
window environment, where we simply use the global document),
pass it as the document property of options.
Represents a partial match of a node type's content
expression, and can be used to find out whether further
content matches here, and whether a given position is a valid end
of the parent node.
Methods
matchNode(node: Node) → ?ContentMatch 📄Match a node, returning a new match after the node if successful.
matchType(type: NodeType, attrs: ?Object, marks: ?[Mark] = Mark.none) → ?ContentMatch 📄Match a node type and marks, returning an match after that node
if successful.
matchFragment(fragment: Fragment, from: ?number = 0, to: ?number = fragment.childCount) → ?union<ContentMatch, bool> 📄Try to match a fragment. Returns a new match when successful,
null when it ran into a required element it couldn't fit, and
false if it reached the end of the expression without
matching all nodes.
matchToEnd(fragment: Fragment, start: ?number, end: ?number) → bool 📄Returns true only if the fragment matches here, and reaches all
the way to the end of the content expression.
validEnd() → bool 📄Returns true if this position represents a valid end of the
expression (no required content follows after it).
fillBefore(after: Fragment, toEnd: bool, startIndex: ?number) → ?Fragment 📄Try to match the given fragment, and if that fails, see if it can
be made to match by inserting nodes in front of it. When
successful, return a fragment of inserted nodes (which may be
empty if nothing had to be inserted). When toEnd is true, only
return a fragment if the resulting match goes to the end of the
content expression.
allowsMark(markType: MarkType) → bool 📄Check whether a node with the given mark type is allowed after
this position.
findWrapping(target: NodeType, targetAttrs: ?Object) → ?[{type: NodeType, attrs: Object}] 📄Find a set of wrapping node types that would allow a node of type
target with attributes targetAttrs to appear at this
position. The result may be empty (when it fits directly) and
will be null when no such wrapping exists.
A value that describes how to parse a given DOM node as a
ProseMirror node or mark type. Specifies the attributes of the new
node or mark, along with optional information about the way the
node's content should be treated.
May either be a set of attributes, where null indicates the
node's default attributes, or an array containing first a set of
attributes and then an object describing the treatment of the
node's content. Such an object may have the following properties:
content: ?union<bool, DOMNode>- If this is
false, the content will be ignored. If it is not
given, the DOM node's children will be parsed as content of the
ProseMirror node or mark. If it is a DOM node, that DOM node's
content is treated as the content of the new node or mark (this
is useful if, for example, your DOM representation puts its
child nodes in an inner wrapping node).
preserveWhiteSpace: ?bool- When given, this enables or disables preserving of whitespace
when parsing the content.
A description of a DOM structure. Can be either a string, which is
interpreted as a text node, a DOM node, which is interpreted as
itself, or an array.
An array describes a DOM element. The first element in the array
should be a string, and is the name of the DOM element. If the
second element is a non-Array, non-DOM node object, it is
interpreted as an object providing the DOM element's attributes.
Any elements after that (including the 2nd if it's not an attribute
object) are interpreted as children of the DOM elements, and must
either be valid DOMOutputSpec values, or the number zero.
The number zero (pronounced “hole”) is used to indicate the place
where a ProseMirror node's content should be inserted.
This module defines a way to transform documents. Transforming
happens in Steps, which are atomic, well-defined modifications to
a document. Applying a step produces a new
document.
Each step provides a position map that maps positions in
the old document to position in the new document. Steps can be
inverted to create a step that undoes their effect,
and chained together in a convenience object called a Transform.
This module does not depend on the browser API being available
(i.e. you can load it into any JavaScript environment).
You can read more about transformations in this
guide.
A step object wraps an atomic operation. It generally applies
only to the document it was created for, since the positions
associated with it will only make sense for that document.
New steps are defined by creating classes that extend Step,
overriding the apply, invert, map, posMap and fromJSON
methods, and registering your class with a unique
JSON-serialization identifier using Step.jsonID.
Methods
apply(doc: Node) → StepResult 📄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.
posMap() → PosMap 📄Get the position map that represents the changes made by this
step.
invert(doc: Node) → Step 📄Create an inverted version of this step. Needs the document as it
was before the step as input.
map(mapping: Mappable) → ?Step 📄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.
toJSON() → Object 📄Create a JSON-serializeable representation of this step. By
default, it'll create an object with the step's JSON
id, and each of the steps's own properties,
automatically calling toJSON on the property values that have
such a method.
Static properties
fromJSON(schema: Schema, json: Object) → Step 📄Deserialize a step from its JSON representation. Will call
through to the step class' own implementation of this method.
jsonID(id: string, stepClass: constructor<Step>) 📄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.
The result of applying a step. Contains either a
new document or a failure value.
Properties
doc: ?Node 📄The transformed document.
failed: ?string 📄Text providing information about a failed step.
Static properties
ok(doc: Node) → StepResult 📄Create a successful step result.
fail(message: string) → StepResult 📄Create a failed step result.
fromReplace(doc: Node, from: number, to: number, slice: Slice) → StepResult 📄Call Node.replace with the given arguments. Create a successful
result if it succeeds, and a failed one if it throws a
ReplaceError.
Extends Step.
Add a mark to all inline content between two positions.
Constructor
new AddMarkStep(from: number, to: number, mark: Mark) 📄
Extends Step.
Remove a mark from all inline content between two positions.
Constructor
new RemoveMarkStep(from: number, to: number, mark: Mark) 📄
Extends Step.
Replace a part of the document with a slice of new content.
Constructor
new ReplaceStep(from: number, to: number, slice: Slice, structure: bool) 📄The given slice should fit the 'gap' between from and
to—the depths must line up, and the surrounding nodes must be
able to be joined with the open sides of the slice. When
structure is true, the step will fail if the content between
from and to is not just a sequence of closing and then opening
tokens (this is to guard against rebased replace steps
overwriting something they weren't supposed to).
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, structure: bool) 📄Create a replace-wrap step with the given range and gap. insert
should be the point in the slice into which the gap should be
moved. structure has the same meaning as it has in the
ReplaceStep class.
There are various things that positions can be mapped through.
We'll denote those as 'mappable'. This is not an actual class in
the codebase, only an agreed-on interface.
map(pos: number, bias: ?number) → number 📄Map a position through this object. When given, bias (should be
-1 or 1) determines in which direction to move when a chunk of
content is inserted at or around the mapped position.
mapResult(pos: number, bias: ?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.
An object representing a mapped position with some extra
information.
Properties
pos: number 📄The mapped version of the position.
deleted: bool 📄Tells you whether the position was deleted, that is,
whether the step removed its surroundings from the document.
A position map, holding information about the way positions in
the pre-step version of a document correspond to positions in the
post-step version. This class implements Mappable.
Constructor
new PosMap(ranges: [number]) 📄Create a position map. The modifications to the document are
represented as an array of numbers, in which each group of three
represents a modified chunk as [start, oldSize, newSize].
Methods
mapResult(pos: number, bias: ?number) → MapResult 📄Map the given position through this map. The bias parameter can
be used to control what happens when the transform inserted
content at (or around) this position—if bias is negative, the a
position before the inserted content will be returned, if it is
positive, a position after the insertion is returned.
map(pos: number, bias: ?number) → number 📄Map the given position through this map, returning only the
mapped position.
forEach(f: fn(oldStart: number, oldEnd: number, newStart: number, newEnd: number)) 📄Calls the given function on each of the changed ranges denoted by
this map.
invert() → PosMap 📄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.
A remapping represents a pipeline of zero or more mappings. It
is a specialized data structured used to manage mapping through a
series of steps, typically including inverted and non-inverted
versions of the same step. (This comes up when ‘rebasing’ steps for
collaboration or history management.) This class implements
Mappable.
Constructor
new Remapping(head: ?[PosMap] = [], tail: ?[PosMap] = []) 📄
Properties
head: [PosMap] 📄The maps in the head of the mapping are applied to input
positions first, back-to-front. So the map at the end of this
array (if any) is the very first one applied.
tail: [PosMap] 📄The maps in the tail are applied last, front-to-back.
Methods
addToFront(map: PosMap, corr: ?number) → number 📄Add a map to the mapping's front. If this map is the mirror image
(produced by an inverted step) of another map in this mapping,
that map's id (as returned by this method or
addToBack) should be passed as a second
parameter to register the correspondence.
addToBack(map: PosMap, corr: ?number) → number 📄Add a map to the mapping's back. If the map is the mirror image
of another mapping in this object, the id of that map should be
passed to register the correspondence.
mapResult(pos: number, bias: ?number) → MapResult 📄Map a position through this remapping, returning a mapping
result.
map(pos: number, bias: ?number) → number 📄Map a position through this remapping.
A change to a document often consists of a series of
steps. This class provides a convenience abstraction to
build up and track such an array of steps. A Transform object
implements Mappable.
The high-level transforming methods return the Transform object
itself, so that they can be chained.
new Transform(doc: Node) 📄Create a transformation that starts with the given document.
doc: Node 📄The current document (the result of applying the steps in the
transform).
steps: [Step] 📄The steps in this transform.
docs: [Node] 📄The documents before each of the steps.
maps: [PosMap] 📄The position maps for each of the steps in this transform.
before: Node 📄The document at the start of the transformation.
step(step: Step) → Transform 📄Apply a new step in this transformation, saving the result.
Throws an error when the step fails.
maybeStep(step: Step) → StepResult 📄Try to apply a step in this transformation, ignoring it if it
fails. Returns the step result.
mapResult(pos: number, bias: ?number) → MapResult 📄Map a position through the whole transformation (all the position
maps in maps), and return the result.
map(pos: number, bias: ?number) → number 📄Map a position through the whole transformation, and return the
mapped position.
addMark(from: number, to: number, mark: Mark) → Transform 📄Add the given mark to the inline content between from and to.
removeMark(from: number, to: number, mark: ?union<Mark, MarkType> = null) → Transform 📄Remove the given mark, or all marks of the given type, from inline
nodes between from and to.
clearMarkup(from: number, to: number) → Transform 📄Remove all marks and non-text inline nodes from the given range.
delete(from: number, to: number) → Transform 📄Delete the content between the given positions.
replace(from: number, to: ?number = from, slice: ?Slice = Slice.empty) → Transform 📄Replace the part of the document between from and to with the
part of the source between start and end.
replaceWith(from: number, to: number, content: union<Fragment, Node, [Node]>) → Transform 📄Replace the given range with the given content, which may be a
fragment, node, or array of nodes.
insert(pos: number, content: union<Fragment, Node, [Node]>) → Transform 📄Insert the given content at the given position.
insertText(pos: number, text: string) → Transform 📄Insert the given text at pos, inheriting the marks of the
existing content at that position.
insertInline(pos: number, node: Node) → Transform 📄Insert the given node at pos, inheriting the marks of the
existing content at that position.
lift(range: NodeRange, target: number) → Transform 📄Split the content in the given range off from its parent, if there
is subling 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, in order to be sure the lift is
valid.
wrap(range: NodeRange, wrappers: [{type: NodeType, attrs: ?Object}]) → Transform 📄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.
setBlockType(from: number, to: ?number = from, type: NodeType, attrs: ?Object) → Transform 📄Set the type of all textblocks (partly) between from and to to
the given node type with the given attributes.
setNodeType(pos: number, type: ?NodeType, attrs: ?Object) → Transform 📄Change the type and attributes of the node after pos.
split(pos: number, depth: ?number = 1, typeAfter: ?NodeType, attrsAfter: ?Object) → Transform 📄Split the node at the given position, and optionally, if depth is
greater than one, any number of nodes above that. By default, the part
split off will inherit the node type of the original node. This can
be changed by passing typeAfter and attrsAfter.
join(pos: number, depth: ?number = 1, silent: ?bool = false) → Transform 📄Join the blocks around the given position. When silent is true,
the method will return without raising an error if the position
isn't a valid place to join.
mapThrough(mappables: [Mappable], pos: number, bias: ?number, start: ?number) → number 📄Map the given position through an array of mappables. When start
is given, the mapping is started at that array position.
mapThroughResult(mappables: [Mappable], pos: number, bias: ?number, start: ?number) → MapResult 📄Map the given position through an array of mappables, returning a
MapResult object.
liftTarget(range: NodeRange) → ?number 📄Try to find a target depth to which the content in the given range
can be lifted.
findWrapping(range: NodeRange, nodeType: NodeType, attrs: ?Object) → ?[{type: NodeType, attrs: ?Object}] 📄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.
canSplit(doc: Node, pos: number, depth: ?NodeType = 1, typeAfter: ?Object) → bool 📄Check whether splitting at the given position is allowed.
joinable(doc: Node, pos: number) → bool 📄Test whether the blocks before and after a given position can be
joined.
joinPoint(doc: Node, pos: number, dir: ?number = -1) → ?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.
insertPoint(doc: Node, pos: number, nodeType: NodeType, attrs: ?Object) → ?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.
This module defines a number of basic node and mark types, and a
schema that combines them.
Extends Block.
A default top-level document node type.
Extends Block.
A blockquote node type.
Extends Block.
An ordered list node type. Has a single attribute, order,
which determines the number at which the list starts counting, and
defaults to 1.
Extends Block.
A bullet list node type.
Extends Block.
A list item node type.
Extends Block.
A node type for horizontal rules.
Extends Block.
A heading node type. Has a single attribute level, which
indicates the heading level, and defaults to 1.
Properties
maxLevel: number 📄Controls the maximum heading level. Has the value 6 in the
Heading class, but you can override it in a subclass.
Extends Block.
A code block / listing node type.
Extends Block.
A paragraph node type.
Extends Inline.
An inline image node type. Has these attributes:
src (required): The URL of the image.alt: The alt text.title: The title of the image.
Extends Inline.
A hard break node type.
Extends MarkType.
An emphasis mark type.
Extends MarkType.
A strong mark type.
Extends MarkType.
A link mark type. Has these attributes:
href (required): The link target.title: The link's title.
Extends MarkType.
A code font mark type.
Constants
schema: Schema 📄A basic document schema.
Defines a parser and serializer for
CommonMark text (registered in the
format module under "markdown").
A configuration of a Markdown parser. Such a parser uses
markdown-it to
tokenize a file, and then runs the custom rules it is given over
the tokens to create a ProseMirror document tree.
Constructor
new MarkdownParser(schema: Schema, tokenizer: MarkdownIt, tokens: Object) 📄Create a parser with the given configuration. You can configure
the markdown-it parser to parse the dialect you want, and provide
a description of the ProseMirror entities those tokens map to in
the tokens object, which maps token names to descriptions of
what to do with them. Such a description is an object, and may
have the following properties:
node: ?string- This token maps to a single node, whose type can be looked up
in the schema under the given name. Exactly one of
node,
block, or mark must be set.
block: ?string- This token comes in
_open and _close variants (which are
appended to the base token name provides a the object
property), and wraps a block of content. The block should be
wrapped in a node of the type named to by the property's
value.
mark: ?string- This token also comes in
_open and _close variants, but
should add a mark (named by the value) to its content, rather
than wrapping it in a node.
attrs: ?union<Object, (MarkdownToken) → Object>- If the mark or node to be created needs attributes, they can
be either given directly, or as a function that takes a
markdown-it
token and
returns an attribute object.
Properties
tokens: Object 📄The value of the tokens object used to construct
this parser. Can be useful to copy and modify to base other
parsers on.
Methods
parse(text: string) → Node 📄Parse a string as CommonMark markup,
and create a ProseMirror document as prescribed by this parser's
rules.
A specification for serializing a ProseMirror document as
Markdown/CommonMark text.
Constructor
new MarkdownSerializer(nodes: Object<fn(MarkdownSerializerState, Node)>, marks: Object) 📄
Properties
nodes: Object<fn(MarkdownSerializerState, Node)> 📄The node serializer
functions for this serializer.
marks: Object 📄The mark serializer info.
Methods
serialize(content: Node, options: ?Object) → string 📄Serialize the content of the given node to
CommonMark.
This is an object used to track state and expose
methods related to markdown serialization. Instances are passed to
node and mark serialization methods (see toMarkdown).
Properties
options: Object 📄The options passed to the serializer.
Methods
wrapBlock(delim: string, firstDelim: ?string, node: Node, f: fn()) 📄Render a block, prefixing each line with delim, and the first
line in firstDelim. node should be the node that is closed at
the end of the block, and f is a function that renders the
content of the block.
ensureNewLine() 📄Ensure the current content ends with a newline.
write(content: ?string) 📄Prepare the state for writing output (closing closed paragraphs,
adding delimiters, and so on), and then optionally add content
(unescaped) to the output.
closeBlock(node: Node) 📄Close the block for the given node.
text(text: string, escape: ?bool) 📄Add the given text to the document. When escape is not false,
it will be escaped.
render(node: Node) 📄Render the given node as a block.
renderContent(parent: Node) 📄Render the contents of parent as block nodes.
renderInline(parent: Node) 📄Render the contents of parent as inline content.
esc(str: string, startOfLine: ?bool) → string 📄Escape the given string so that it can safely appear in Markdown
content. If startOfLine is true, also escape characters that
has special meaning only at the start of the line.
repeat(str: string, n: number) → string 📄Repeat the given string n times.
Constants
defaultMarkdownParser: MarkdownParser 📄A parser parsing unextended CommonMark,
without inline HTML, and producing a document in the basic schema.
defaultMarkdownSerializer: MarkdownSerializer 📄A serializer for the basic schema.
This module defines a plugin for attaching ‘input rules’ to an
editor, which can react to or transform text typed by the user. It
also comes with a bunch of default rules that can be enabled in
this plugin.
Input rules are regular expressions describing a piece of text
that, when typed, causes something to happen. This might be
changing two dashes into an emdash, wrapping a paragraph starting
with "> " into a blockquote, or something entirely different.
new InputRule(match: RegExp, filter: ?string, handler: union<string, fn(pm: ProseMirror, match: [string], pos: number)>) 📄Create an input rule. The rule applies when the user typed
something and the text directly in front of the cursor matches
match, which should probably end with $. You can optionally
provide a filter, which should be a single character that always
appears at the end of the match, and will be used to only apply
the rule when there's an actual chance of it succeeding.
The handler can be a string, in which case the matched text
will simply be replaced by that string, or a function, which will
be called with the match array produced by
RegExp.exec,
and should produce the effect of the rule.
Manages the set of active input rules for an editor. Created
with the inputRules plugin.
addRule(rule: InputRule) 📄Add the given input rule to the editor.
removeRule(rule: InputRule) → bool 📄Remove the given input rule from the editor. Returns false if the
rule wasn't found.
wrappingInputRule(regexp: RegExp, filter: string, nodeType: NodeType, getAttrs: ?union<Object, fn([string]) → ?Object>, joinPredicate: ?fn([string], Node) → bool) → InputRule 📄Build an input rule for automatically wrapping a textblock when a
given string is typed. The regexp and filter arguments are
directly passed through to the InputRule constructor. You'll
probably want the regexp to start with ^, so that the pattern can
only occur at the start of a textblock.
nodeType is the type of node to wrap in. If it needs attributes,
you can either pass them directly, or pass a function that will
compute them from the regular expression match.
By default, if there's a node with the same type above the newly
wrapped node, the rule will try to join those
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.
textblockTypeInputRule(regexp: RegExp, filter: string, nodeType: NodeType, getAttrs: ?union<Object, fn([string]) → ?Object>) → InputRule 📄Build an input rule that changes the type of a textblock when the
matched text is typed into it. You'll usually want to start your
regexp with ^ to that it is only matched at the start of a
textblock. The optional getAttrs parameter can be used to compute
the new node's attributes, and works the same as in the
wrappingInputRule function.
blockQuoteRule(nodeType: NodeType) → InputRule 📄Given a blockquote node type, returns an input rule that turns "> "
at the start of a textblock into a blockquote.
orderedListRule(nodeType: NodeType) → InputRule 📄Given a list node type, returns an input rule that turns a number
followed by a dot at the start of a textblock into an ordered list.
bulletListRule(nodeType: NodeType) → InputRule 📄Given a list node type, returns an input rule that turns a bullet
(dash, plush, or asterisk) at the start of a textblock into a
bullet list.
codeBlockRule(nodeType: NodeType) → InputRule 📄Given a code block node type, returns an input rule that turns a
textblock starting with three backticks into a code block.
headingRule(nodeType: NodeType, maxLevel: number) → InputRule 📄Given a node type and a maximum level, creates an input rule that
turns up to that number of # characters followed by a space at
the start of a textblock into a heading whose level corresponds to
the number of # signs.
inputRules: Plugin 📄A plugin for adding input rules to an editor. A common pattern of
use is to call inputRules.ensure(editor).addRule(...) to get an
instance of the plugin state and add a rule to it.
Takes a single option, rules, which may be an array of
InputRules objects to initially add.
emDash: InputRule 📄Converts double dashes to an emdash.
ellipsis: InputRule 📄Converts three dots to an ellipsis character.
openDoubleQuote: InputRule 📄“Smart” opening double quotes.
closeDoubleQuote: InputRule 📄“Smart” closing double quotes.
openSingleQuote: InputRule 📄“Smart” opening single quotes.
closeSingleQuote: InputRule 📄“Smart” closing single quotes.
smartQuotes: [InputRule] 📄Smart-quote related input rules.
allInputRules: [InputRule] 📄All schema-independent input rules defined in this module.
This module defines a number of building blocks for ProseMirror
menus, along with two menu styles, menubar and
tooltipmenu.
The types defined in this module aren't the only thing you can
display in your menu. Anything that conforms to this interface can
be put into a menu structure.
Render the element for display in the menu. Returning null can be
used to signal that this element shouldn't be displayed for the
given editor state.
An icon or label that, when clicked, executes a command.
The spec used to create the menu item.
Renders the icon according to its display
spec, and adds an event handler which
executes the command when the representation is clicked.
The configuration object passed to the MenuItem constructor.
The function to execute when the menu item is activated.
Optional function that is used to determine whether the item is
appropriate at the moment.
Determines what happens when select
returns false. The default is to hide the item, you can set this to
"disable" to instead render the item with a disabled style.
A predicate function to determine whether the item is 'active' (for
example, the item for toggling the strong mark might be active then
the cursor is in strong text).
A function that renders the item. You must provide either this,
icon, or label.
Describes an icon to show for this item. The object may specify an
SVG icon, in which case its path property should be an SVG path
spec,
and width and height should provide the viewbox in which that
path exists. Alternatively, it may have a text property
specifying a string of text that makes up the icon, with an
optional css property giving additional CSS styling for the text.
Or it may contain dom property containing a DOM node.
Makes the item show up as a text label. Mostly useful for items
wrapped in a drop-down or similar menu. The object
should have a label property providing the text to display.
Defines DOM title (mouseover) text for the item.
Optionally adds a CSS class to the item's DOM representation.
Optionally adds a string of inline CSS to the item's DOM
representation.
Defines which event on the command's DOM representation should
trigger the execution of the command. Defaults to mousedown.
A drop-down menu, displayed as a label with a downwards-pointing
triangle to the right of it.
Constructor
new Dropdown(content: [MenuElement], options: ?Object) 📄Create a dropdown wrapping the elements. Options may include
the following properties:
label: string- The label to show on the drop-down control.
title: string- Sets the
title
attribute given to the menu control.
class: string- When given, adds an extra CSS class to the menu control.
css: string- When given, adds an extra set of CSS styles to the menu control.
Methods
render(pm: ProseMirror) → DOMNode 📄Returns a node showing the collapsed menu, which expands when clicked.
Represents a submenu wrapping a group of elements that start
hidden and expand to the right when hovered over or tapped.
Creates a submenu for the given group of menu elements. The
following options are recognized:
label: string- The label to show on the submenu.
Renders the submenu.
renderGrouped(pm: ProseMirror, content: [union<MenuElement, [MenuElement]>]) → ?DOMFragment 📄Render the given, possibly nested, array of menu elements into a
document fragment, placing separators between them (and ensuring no
superfluous separators appear when some of the groups turn out to
be empty).
toggleMarkItem(markType: MarkType, options: Object) → MenuItem 📄Create a menu item for toggling a mark on the selection. Will create
run, active, and select properties. Other properties have to
be supplied in the options object. When options.attrs is a
function, it will be called with (pm: ProseMirror, callback: (attrs: ?Object)) arguments, and should produce the attributes for
the mark and then call the callback. Otherwise, it may be an object
providing the attributes directly.
insertItem(nodeType: NodeType, options: Object) → MenuItem 📄Create a menu item for inserting a node of the given type. Adds
run and select properties to the ones provided in options.
options.attrs can be an object or a function, like in
toggleMarkItem.
wrapItem(nodeType: NodeType, options: Object) → MenuItem 📄Build a menu item for wrapping the selection in a given node type.
Adds run and select properties to the ones present in
options. options.attrs may be an object or a function, as in
toggleMarkItem.
blockTypeItem(nodeType: NodeType, options: Object) → MenuItem 📄Build a menu item for changing the type of the textblock around the
selection to the given type. Provides run, active, and select
properties. Others must be given in options. options.attrs may
be an object to provide the attributes for the textblock node.
wrapListItem(nodeType: NodeType, options: Object) → MenuItem 📄Build a menu item for wrapping the selection in a list.
options.attrs may be an object to provide the attributes for the
list node.
icons: Object 📄A set of basic editor-related icons. Contains the properties
join, lift, selectParentNode, undo, redo, strong, em,
code, link, bulletList, orderedList, and blockquote, each
holding an object that can be used as the icon option to
MenuItem.
joinUpItem: MenuItem 📄Menu item for the joinUp command.
liftItem: MenuItem 📄Menu item for the lift command.
selectParentNodeItem: MenuItem 📄Menu item for the selectParentNode command.
undoItem: MenuItem 📄Menu item for the undo command.
redoItem: MenuItem 📄Menu item for the redo command.
Plugin that enables the menu bar for an editor. The menu bar takes
up space above the editor, showing currently available commands
(that have been added to the menu). The
following options are supported:
float: bool = false- When enabled, causes the menu bar to stay visible when the
editor is partially scrolled out of view, by making it float at
the top of the viewport.
content: [MenuGroup]- Determines the content of the menu.
Enables the tooltip menu for this editor. This menu shows up when
there is a selection, and optionally in certain other
circumstances, providing context-relevant commands.
By default, the tooltip will show inline menu commands (registered
with the menuGroup command property)
when there is an inline selection, and block related commands when
there is a node selection on a block.
The plugin supports the following options:
showLinks: bool = true- Causes a tooltip with the link target to show up when the
cursor is inside of a link (without a selection).
selectedBlockMenu: bool = false- When enabled, and a whole block is selected or the cursor is
inside an empty block, the block menu gets shown.
inlineContent: [MenuGroup]- The menu elements to show when displaying the menu for inline
content.
blockContent: [MenuGroup]- The menu elements to show when displaying the menu for block
content.
selectedBlockContent: [MenuGroup]- The elements to show when a full block has been selected and
selectedBlockMenu is enabled. Defaults to concatenating
inlineContent and blockContent.
position: string- Where, relative to the selection, the tooltip should appear.
Defaults to
"above". Can also be set to "below".
This module implements some GUI primitives.
The prompting implementation gets the job done, roughly, but it's
rather primitive and you'll probably want to replace it in your own
system (or submit patches to improve this implementation).
Used to show tooltips. An instance of this class is a persistent
DOM node (to allow position and opacity animation) that can be
shown and hidden. It is positioned relative to a position (passed
when showing the tooltip), and points at that position with a
little arrow-like triangle attached to the node.
new Tooltip(wrapper: DOMNode, options: union<string, Object>) 📄Create a new tooltip that lives in the wrapper node, which should
be its offset anchor, i.e. it should have a relative or
absolute CSS position. You'll often want to pass an editor's
wrapper node. options may be an object
containg a direction string and a getBoundingRect function which
should return a rectangle determining the space in which the tooltip
may appear. Alternatively, options may be a string specifying the
direction. The direction can be "above", "below", "right",
"left", or "center". In the latter case, the tooltip has no arrow
and is positioned centered in its wrapper node.
detach() 📄Remove the tooltip from the DOM.
open(node: DOMNode, pos: ?{left: number, top: number}) 📄Make the tooltip visible, show the given node in it, and position
it relative to the given position. If pos is not given, the
tooltip stays in its previous place. Unless the tooltip's
direction is "center", pos should definitely be given the
first time it is shown.
close() 📄Close (hide) the tooltip.
This class represents a dialog that prompts for a set of
fields.
Constructor
new FieldPrompt(pm: ProseMirror, title: string, fields: [Field]) 📄Construct a prompt. Note that this does not
open it yet.
Properties
form: DOMNode 📄An HTML form wrapping the fields.
Methods
close() 📄Close the prompt.
open() 📄Open the prompt's dialog.
values() → ?[any] 📄Read the values from the form's field. Validate them, and when
one isn't valid (either has a validate function that produced an
error message, or has no validate function, no value, and no
default value), show the problem to the user and return null.
prompt() → {close: fn()} 📄Open a prompt with the parameter form in it. The default
implementation calls openPrompt.
reportInvalid(dom: DOMNode, message: string) 📄Report a field as invalid, showing the given message to the user.
The type of field that FieldPrompt expects to be passed to it.
Constructor
new Field(options: Object) 📄Create a field with the given options. Options support by all
field types are:
value: ?any- The starting value for the field.
label: string- The label for the field.
required: ?bool- Whether the field is required.
validate: ?(any) → ?string- A function to validate the given value. Should return an
error message if it is not valid.
Methods
render(pm: ProseMirror) → DOMNode 📄Render the field to the DOM. Should be implemented by all subclasses.
read(dom: DOMNode) → any 📄Read the field's value from its DOM node.
validateType(_value: any) → ?string 📄A field-type-specific validation function.
Extends Field.
A field class for single-line text fields.
Extends Field.
A field class for dropdown fields based on a plain <select>
tag. Expects an option options, which should be an array of
{value: string, label: string} objects, or a function taking a
ProseMirror instance and returning such an array.
Functions
openPrompt(pm: ProseMirror, content: DOMNode, options: ?Object) → {close: fn()} 📄Open a dialog box for the given editor, putting content inside of
it. The close method on the return value can be used to
explicitly close the dialog again. The following options are
supported:
pos: {left: number, top: number}- Provide an explicit position for the element. By default, it'll
be placed in the center of the editor.
onClose: fn()- A function to be called when the dialog is closed.
This module implements an API into which a communication channel
for collaborative editing can be hooked. See this
guide for more details and an example.
This class accumulates changes that have to be sent to the
central authority in the collaborating group, signals an event when
it has something to send, and makes it possible to integrate
changes made by peers into our local document. It is created and
attached to the editor when the plugin is enabled,
and can be accessed with
collabEditing.get.
Properties
version: number 📄The version number of the last update received from the central
authority. Starts at 0 or the value of the version property
in the option object, for the editor's value when the option
was enabled.
mustSend: Subscription<fn()> 📄Fired when there are new steps to send to the central
authority. Consumers should respond by calling
sendableSteps and pushing those to the authority.
receivedTransform: Subscription<fn(transform: Transform, selectionBeforeTransform: Selection)> 📄Signals that a transformation has been aplied to the editor.
Passes the Transform and the selection before the transform
as arguments to the handler.
Methods
hasSendableSteps() → bool 📄Reports whether the editor has any unsent steps.
sendableSteps() → {version: number, steps: [Step]} 📄Provides the data describing the editor's unconfirmed steps. The
version and array of steps are the things you'd send to the
central authority. The whole return value must be passed to
confirmSteps when the steps go through.
receive(steps: [Step], clientIDs: [number]) → [PosMap] 📄Pushes a set of steps (received from the central authority) into
the editor. Will recognize its own changes, and confirm
unconfirmed steps as appropriate. Remaining unconfirmed steps
will be rebased over remote steps.
Returns the position maps produced by applying the
steps.
Constants
collabEditing: Plugin 📄Enables the collaborative editing framework for the editor.
You can pass a version option, which determines the starting
version number of the collaborative editing, and defaults to 0.
This module exports helper functions for deriving a set of basic
menu items, input rules, or key bindings from a schema. These
values need to know about the schema for two reasons—they need
access to specific instances of node and mark types, and they need
to know which of the node and mark types that they know about are
actually present in the schema.
The exampleSetup plugin ties these together into a plugin that
will automatically enable this basic functionality in an editor.
Functions
buildInputRules(schema: Schema) → [InputRule] 📄A set of input rules for creating the basic block quotes, lists,
code blocks, and heading.
buildKeymap(schema: Schema, mapKeys: ?Object) → Keymap 📄Inspect the given schema looking for marks and nodes from the
basic schema, and if found, add key bindings related to them.
This will add:
- Mod-B for toggling strong
- Mod-I for toggling emphasis
- Mod-` for toggling code font
- Ctrl-Shift-0 for making the current textblock a paragraph
- Ctrl-Shift-1 to Ctrl-Shift-6 for making the current
textblock a heading of the corresponding level
- Ctrl-Shift-\ to make the current textblock a code block
- Ctrl-Shift-8 to wrap the selection in an ordered list
- Ctrl-Shift-9 to wrap the selection in a bullet list
- Ctrl-Shift-. to wrap the selection in a block quote
- Enter to split a non-empty textblock in a list item while at
the same time splitting the list item
- Mod-Enter to insert a hard break
- Mod-Shift-minus to insert a horizontal rule
You can suppress or map these bindings by passing a mapKeys
argument, which maps key names (say "Mod-B" to either false, to
remove the binding, or a new key name string.
Given a schema, look for default mark and node types in it and
return an object with relevant menu items relating to those marks:
toggleStrong: MenuItem- A menu item to toggle the strong mark.
toggleEm: MenuItem- A menu item to toggle the emphasis mark.
toggleCode: MenuItem- A menu item to toggle the code font mark.
toggleLink: MenuItem- A menu item to toggle the link mark.
insertImage: MenuItem- A menu item to insert an image.
wrapBulletList: MenuItem- A menu item to wrap the selection in a bullet list.
wrapOrderedList: MenuItem- A menu item to wrap the selection in an ordered list.
wrapBlockQuote: MenuItem- A menu item to wrap the selection in a block quote.
makeParagraph: MenuItem- A menu item to set the current textblock to be a normal
paragraph.
makeCodeBlock: MenuItem- A menu item to set the current textblock to be a
code block.
insertTable: MenuItem- An item to insert a table.
addRowBefore, addRowAfter, removeRow, addColumnBefore, addColumnAfter, removeColumn: MenuItem- Table-manipulation items.
makeHead[N]: MenuItem- Where N is 1 to 6. Menu items to set the current textblock to
be a heading of level N.
insertHorizontalRule: MenuItem- A menu item to insert a horizontal rule.
The return value also contains some prefabricated menu elements and
menus, that you can use instead of composing your own menu from
scratch:
insertMenu: Dropdown- A dropdown containing the
insertImage and
insertHorizontalRule items.
typeMenu: Dropdown- A dropdown containing the items for making the current
textblock a paragraph, code block, or heading.
inlineMenu: [[MenuElement]]- An array of arrays of menu elements for use as the inline menu
to, for example, a tooltip menu.
blockMenu: [[MenuElement]]- An array of arrays of menu elements for use as the block menu
to, for example, a tooltip menu.
fullMenu: [[MenuElement]]- An array of arrays of menu elements for use as the full menu
for, for example the menu bar.
Constants
exports
Persistent data structure representing an ordered mapping from
strings to values, with some convenient update methods.
Properties
size: number 📄The amount of keys in this map.
Methods
get(key: string) → ?any 📄Retrieve the value stored under key, or return undefined when
no such key exists.
update(key: string, value: any, newKey: ?string) → OrderedMap 📄Create a new map by replacing the value of key with a new
value, or adding a binding to the end of the map. If newKey is
given, the key of the binding will be replaced with that key.
remove(key: string) → OrderedMap 📄Return a map with the given key removed, if it existed.
addToStart(key: string, value: any) → OrderedMap 📄Add a new key to the start of the map.
addToEnd(key: string, value: any) → OrderedMap 📄Add a new key to the end of the map.
addBefore(place: string, key: string, value: any) → OrderedMap 📄Add a key after the given key. If place is not found, the new
key is added to the end.
forEach(f: fn(key: string, value: any)) 📄Call the given function for each key/value pair in the map, in
order.
prepend(map: union<Object, OrderedMap>) → OrderedMap 📄Create a new map by prepending the keys in this map that don't
appear in map before the keys in map.
append(map: union<Object, OrderedMap>) → OrderedMap 📄Create a new map by appending the keys in this map that don't
appear in map after the keys in map.
subtract(map: union<Object, OrderedMap>) → OrderedMap 📄Create a map containing all the keys in this map that don't
appear in map.
Static properties
from(value: ?union<Object, OrderedMap>) → OrderedMap 📄Return a map with the given content. If null, create an empty
map. If given an ordered map, return that map itself. If given an
object, create a map from the object's properties.