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.

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.

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.

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