Atomic authoring

Every edit, from a keystroke to a scripted batch, runs as a transaction that publishes one new immutable state.

How an edit flows

Use controller.transaction((edit) { ... }) for an atomic batch: it publishes once and is one undo unit. An invalid recipe rejects the whole batch.

import 'package:vyuh_document_editor/vyuh_document_editor.dart';

DocumentWorkflowResult appendSummary(DocumentEditorController controller) {
  return controller.transaction((edit) {
    edit.insert(
      ParagraphBlock.text(
        'A strong quarter.',
        id: 'quarter-summary',
        paragraphFormat: const ParagraphFormat(afterSpacing: 8),
      ),
      at: DocumentAnchors.documentEnd,
    );
    edit.insertText(
      ' Revenue grew.',
      at: const DocumentPosition(blockId: 'quarter-summary', offset: 17),
    );
  });
}

// Call appendSummary once for this identity; inspect result.committed and
// result.diagnostics. A committed recipe is one Undo unit.

Inspect the outcome

The result has committed, diagnostics and the published state. Check it before reporting success.

Later operations see earlier staged edits, so a recipe can insert a paragraph and then type into it. Give new nodes unique IDs. Keep callbacks synchronous; a recipe started during IME composition rejects with composition_active.

Author without Flutter

DocumentWorkflowSession runs the same recipes without a widget. Recipe operations include insert, insertAll, replace, removeBlock, insertText, deleteText, setParagraphFormat and setCharacterFormat; DocumentAnchors name where to insert. Installed operations run through edit.operation(CoreDocumentOperation.textInsert, payload), named by a typed DocumentOperationId.

For protected content, pass a protectionPolicy. Its identity callback reads the actor and roles from your host session; people and agents get the same checks. authorId attributes edits; it does not grant permission.

import 'package:vyuh_document/engine.dart';
import 'package:vyuh_document/types.dart';

DocumentWorkflowSession createProtectedWorkflow({
  required Document document,
  required String authorId,
  required DocumentSessionIdentity Function() resolveIdentity,
}) => DocumentWorkflowSession(
  document: document,
  authorId: authorId,
  protectionPolicy: DocumentProtectionPolicy(identity: resolveIdentity),
);

// resolveIdentity reads the current actor and roles from your authenticated
// host session. authorId attributes edits; it does not grant permission.
// Inspect each transaction's committed flag and diagnostics before saving.

Identity is checked when a recipe commits and when undo or redo touches protected content; a denied recipe rejects its whole batch. Only template-design mode may define protected regions.

See the complete recipe example.

Serialized operations

Decode operation envelopes, records and scripts through the installed DocumentOperationRegistry. Readers reject fields they do not consume.

Cell payloads take table_id plus cell_id; column payloads take table_id plus column_id. An ID follows its cell or column through row and column changes and wins over any row_index or column_index sent with it. An edit whose target is gone rejects.

How suggested changes appear

Suggestions use small marks so readers can still see the document's original colors, syntax highlighting, images and artwork.

Change	On the document	In the review panel
Added text	Green dashed underline	Addition
Removed text	Red dashed underline and strikethrough	Removal
Changed text formatting	Amber dotted underline on the affected text	Changed values, such as font size
Moved text	Amber dotted underline on the moved text at its new location	Previous and current location
Added or removed object	Green or red dashed rule at the object's edge	Addition or removal
Changed table row, column or cell	Amber dotted rule inside the affected cells	Changed values
Changed block properties	Amber dotted rule at the block's edge	Before and after values
Moved object	Amber dotted rule at its new position	From and To descriptions

Marks never add padding or a box around a block. Accepting or rejecting a suggestion clears its marks; undo restores them.

Review cell properties

In Suggesting mode, cell fill, padding, alignment, width, wrapping and borders create formatting suggestions. A multi-cell edit is one undo unit. Accept keeps the new properties; reject restores only what that suggestion changed.

Next

• Loading and saving
• Engine reference