Document API

Reference for the document facade, its operations and results, order and capability queries, change events and attribution.

document.facade is the one read and write surface of a document: every structural and text edit, and every read of the tree, goes through it. It is the same whether you use it headlessly or from a view. For the document object itself (history, providers, readiness), see Documents; for the tree model, see the document model.

import { createDocument, defaultSemantics } from 'edytor';

const { facade } = createDocument({
  value: { children: [{ type: 'paragraph', id: 'p1', content: [{ text: 'hello' }] }] },
  semantics: defaultSemantics // the bundled kinds' roles; views add their plugins' own
});

facade.insertText('p1', 5, ' world'); // { status: 'applied', ids: ['p1'] }
facade.insertText('p1', 0, ''); // { status: 'noop', ids: [] }
facade.insertBlock({ parent: null, index: 1 }, { id: 'p2', type: 'paragraph' });
facade.insertBlock({ parent: null, index: 1 }, { id: 'p2', type: 'paragraph' }); // refused: id taken

defaultSemantics, richTextSemantics, codeSemantics and imageSemantics are frozen and shared by every document. To add your own kinds, build their config with semanticsOf (kind rows in, { roles, rendersContent, defaultChild } out) and merge it into the bundled one field by field. Spreading the two configs at the top level would keep only your roles, and drop the divider, image and code rules:

import { createDocument, defaultSemantics, semanticsOf } from 'edytor';

const mine = semanticsOf({ embed: { void: true, rendersContent: false } });

export const semantics = {
  roles: { ...defaultSemantics.roles, ...mine.roles },
  rendersContent: { ...defaultSemantics.rendersContent, ...mine.rendersContent },
  defaultChild: { ...defaultSemantics.defaultChild, ...mine.defaultChild }
};

export const document = createDocument({ semantics }); // divider stays void, code an island

Shapes

Offsets count what the block displays: one per UTF-16 text unit and one per inline block. Offsets out of range are clamped.

toBlockSpec(block, { freshIds? }) (from edytor or edytor/crdt/edytor) turns a canonical JSONBlock (from toJSON, blockJSON, a template or an import) into a BlockSpec: it keeps the ids the JSON carries and mints the missing ones; freshIds: true mints every id, so the result can be inserted beside its source.

import { toBlockSpec } from 'edytor/crdt/edytor';

facade.insertBlock({ parent: null, index: 1 }, toBlockSpec(facade.blockJSON('p1'), { freshIds: true }));

Results

Every operation returns an OpResult:

type OpResult = {
  status: 'applied' | 'noop' | 'refused';
  ids: readonly BlockId[]; // what the op is about; empty unless applied
  reason?: string; // e.g. 'id-collision'
};

• applied: the operation wrote to the document.
• noop: nothing to do (inserting '', an empty range, formatting with the value already there, moveBlocks([])). Nothing is written.
• refused: the operation is not allowed here (a missing or deleted block, an id already taken, a move into an island). Nothing is written.

Block operations

Text operations

Text operations also work inside void blocks, which may hold a caption.

Ranges and flows

The prepared plan of these operations carries at, the DocPosition where the caret should land.

Prepare, apply, compose

Every operation also exists in two phases. facade.prepare.<op>(…) checks it and returns a plan without writing; facade.apply(plan) writes it in one transaction. Calling facade.<op>(…) is apply(prepare.<op>(…)).

const plan = facade.prepare.splitBlock('p1', 5, 'p1b');
if ('writes' in plan) {
  plan.effect; // { creates: ['p1b'], removes: [], merges: [], moves: [], meta: [], textRanges: [...] }
  facade.apply(plan); // { status: 'applied', ids: ['p1b'] }
}

// Independent edits as one plan, one transaction, one undo step:
facade.apply(
  facade.compose(
    facade.prepare.setBlockType('p2', 'heading'),
    facade.prepare.setBlockData('p2', { level: 2 })
  )
);

A plan is { ids, writes, effect, version, at? }; a refusal is returned as its OpResult. A plan is valid only at the version it was prepared against and in the same synchronous turn: applying it after the document changed throws. compose(...plans) joins plans prepared at the same version whose steps do not depend on each other.

Reads

Order and capability

Whether a block type renders its own content is a document-level question: document.rendersContent(type).

Changes

facade.onChange(callback) calls back once per committed transaction that changed the visible document, local or remote, and returns an unsubscribe function.

const off = facade.onChange((change) => {
  if (!change.local) console.log('remote edit in', [...change.content.keys()]);
});

transact(fn, origin?) groups several operations into one transaction and one change event. Prefer document.transact(fn), which also makes it one undo step.

Block handles

facade.block(id) returns a handle over one block, with the same operations bound to that id. Handles are cached per id and safe on missing ids (operations are refused).

const block = facade.block('p1');
block.insertText(0, '> ');
block.items; // ContentItem[]
block.split(2, 'p1-tail');
block.delete(); // children take its place; delete({ keepChildren: false }) removes them too

Members: id, attribution, items, runs, length, childIds(), insertText, deleteText, format, setMark, unsetMark, clearMarks, insertInline, removeInline, setInlineData, insertChild(index, spec), moveTo({ parent, index }), nestUnder(parent), unNest(), split(offset, newId, tail?), mergeBackward(), mergeForward(), mergeFrom(other), delete(opts?), setType, setData, set(value), duplicate(freshId) (the same callback as duplicateBlock).

Attribution

Each block records who created it and who changed it, as actor ids (actor.id from createDocument):

document.attribution.block('p3');
// { createdBy: 'user-42', contributors: Set { 'user-42' }, lastChangedBy: 'user-42' }
facade.blockAttribution('p3'); // the same record
document.attribution.actors.get('user-42'); // { name: 'Ada', color: '#7559ee' }

attribution.actorOf(clientID) maps a CRDT client id to its actor, attribution.setProfile({ name, color }) republishes the local actor’s profile, and attribution.history(id) returns earlier versions of a block when the document was created with lineage: { depth }.