Plite Authored Changes

import { createEditor, createEditorView } from 'plitejs';
import { authored } from 'plitejs/authored';
import { history } from 'plitejs/history';
 
const editor = createEditor({
  plugins: [
    authored({
      authorId: () => session.user.id,
    }),
    history(),
  ],
  initialValue,
});
 
const reviewView = createEditorView(editor, {
  authored: { intent: 'propose' },
});Copy

The author callback must return a nonempty author ID for every write. The application owns authentication.

Views

Call view.api.authored.setView(policy) to change one view. The source editor and sibling views keep their own policies and selections. Preview views throw on a plain edit, but some other writes still change the document, such as an update that makes a decision, undo and redo, and remote collaboration changes. Switching views does not decide suggestions. A switch requested during composition applies after composition ends.

A pending join can show a block away from where it is saved. The proposed preview shows a block split off the joined line, or inserted between the join's halves, after the joined line. An edit view and a propose view record Backspace or Delete across a moved block's edge as the merge it makes, except that a propose view refuses it when the moved line holds the owner of a content root. Both refuse these edits:

• Enter or a new block where a moved block meets its neighbours.
• An edit whose saved result would show in another order.
• An edit where the preview shows none of the selected letters between the selection's ends, but shows some of them elsewhere.

A format beside a moved paragraph formats what the proposed preview shows between the selection's ends, so it can format saved text outside the selection or leave a moved paragraph inside it plain. The editor does not refuse a command that names a place of its own, such as a link inserted at a given point, for the selection it started with. When that command also edits at the selection, it can change text outside it. Its edits at the places it names still refuse as above. Typing at a caret inside the joined line still applies. A refused edit applies nothing and reaches subscribeRefusals with code unrepresentable, and the edits above carry a reason such as crosses or reordered. Authored changes lists each case with its reason.

Propose and decide

Pass { changeId: id } to tx.authored.propose(...) to name the proposal or add the transaction's writes to the pending change with that ID. Decisions use the revisions of the changes you read. A blocked result names in with the changes to decide together; pass several decisions in one call to decide them together. Handle every AuthoredResult status.

Proposing the deletion of a block that owns a content root strikes the block and keeps the root unmarked until the deletion is decided. Authored changes covers accepting and rejecting it.

Import a comparison

Import validates the baseline, schema, document metadata, and selected groups before creating one native pending proposal. Pass groupIds to select groups; import includes their required dependency groups. The result maps comparison groups to the authored change ID. The input must be a TwoWayComparison.

Query changes

changes(query) reads pending changes in document order, 50 at a time by default and at most 200. Narrow it with at, authorId or group, and pass the page's cursor to read the next page. AuthoredChange exposes stable identity, author, createdAt, revision, kind, and current ranges. Use change(id) for keyed readers.

at names a place of the document the view shows. With no preview that is the stored document, and at takes a node key, path, point or range. On a preview, at takes the key or path of a node the preview shows, a block or one of its texts. The read returns the changes of the stored content that node shows, with what the preview hides inside it and the changes of each element around it that the preview takes away, such as a quote whose pending unwrap the preview applies. A block's read includes what the preview hides between two of its texts, and neither text's read does. On a preview, a point or a range throws AuthoredPlaceError, which plitejs/authored exports, and a key the preview lacks reads nothing. On a view of a content root the preview leaves out, every key and path reads nothing. A joined line reads a hidden block between its two halves. Otherwise no block reads the changes of a top-level block the preview hides; an edit or propose view reads them. A top-level block the preview adds to complete the document, as when its only block is deleted, reads nothing. A block it adds inside a container, as when a quote's only paragraph is deleted, can read the hidden paragraph it replaces. A block never reads the change of an element around it that the view still shows. A page cursor from a read with at works only on a view with the same root and preview. A change's ranges and the locations in details are always places of the stored document.

Except for a split or join inside a top-level block, no revision covers where a change sits, so an edit before it keeps it while its ranges move. A join, split, wrap or unwrap's revision ignores the text and leaves inside the element. It changes when the element's own fields change, or the order or shapes of the elements inside it. The revision of a split or join inside a top-level block, such as a quote, also covers its index inside that block, because a decision merges its line into the block before it. The index counts blocks, so it does not say which block comes before the line. After the blocks before it change order, or one of them is replaced or changes type, a decision read before still applies and merges the line into the block now before it. A block that lands between the halves of a top-level split or join also keeps the revision, and a decision read before merges the line into that block.

Review cards

A review card groups one author's adjacent pending changes:

groups({ at }) returns card summaries in document order: id, authorId, createdAt, changeCount, and revision. A card's ID is its oldest change. groupOf(changeId) returns the card that holds a change, and changes({ group: card.id }) pages its changes. A card decision reads as stale once the card's ID or revision moved. view.api.authored.subscribeChanges(listener) passes { blocks, changed, groups, removed } for each commit that changes the review. blocks names the view's top-level blocks whose reads may differ, which are each block a change reached or left and each block holding a change whose card ID changed. A change to a card's summary alone names no block, so a copy of its changeCount or revision held per block can trail until it reads again.

Local history

Use local undo and redo from plitejs/history for interaction history. They can reverse an authored transaction and restore its mapped selection, but they do not act as collaborative review decisions.

Persistence and collaboration

Save editor.read.value() as one document, including node review marks and document records. An editor with authored installed validates those marks and records on load.

Install yjs from plitejs/yjs on every peer to synchronize marked content and document records through the ordinary Yjs binding.

Format helpers

plitejs/authored exports pure document transforms. Use projectAuthoredDocument(document, { projection }) for a result containing document, diagnostics, pending, and ok, with projection accepted or proposed. Use projectAuthoredRange(document, projectedDocument, range) to map a stored-document range onto a projected document; it returns null when the projection keeps none of that content.

API reference