Review and comments
You will add tracked changes (suggesting mode), comments with replies, and accept/reject from code.
Packages
None: review is part of the core and the editor.
The code
dart
import 'package:material_ui/material_ui.dart';
import 'package:vyuh_document_editor/vyuh_document_editor.dart';
/// Comments and suggested changes on the same controller.
Widget buildReviewEditor(
DocumentEditorController controller,
DocumentInteractionMode mode,
) => DocumentEditor(
controller: controller,
// editing, suggesting (tracked changes), commenting, reviewing or viewing.
interactionMode: mode,
configuration: DocumentEditorConfiguration(
review: DocumentReviewConfiguration(
showComments: true,
showRevisions: true,
// Collect comment text in your own UI; return null to cancel.
commentComposer: (controller, selection) async => 'Please cite this.',
),
),
);
void reviewFromCode(DocumentEditorController controller) {
// Comment the current selection, then reply to it. A comment anchors
// text inside one block; anything else throws DocumentCommentRefusal.
if (controller.canAddComment(controller.textRange)) {
final commentId = controller.addCommentToSelection('Is this final?');
controller.addReplyToComment(commentId, 'Yes, approved.');
controller.setCommentResolved(commentId, true);
}
// Accept or reject every recorded suggestion.
for (final revision in controller.document.revisions) {
controller.acceptRevision(revision.id);
}
}Switch mode to DocumentInteractionMode.suggesting and type: insertions get a green dashed underline, deletions a red strikethrough. In commenting mode, selecting a word asks your commentComposer for the text; it is the one comment prompt, so Add comment is offered only when you supply it.
Interaction modes
DocumentInteractionMode | Users can |
|---|---|
editing | Edit directly |
suggesting | Edit; every change is recorded as a suggestion |
commenting | Select and comment, not edit |
reviewing | Review suggestions and comments |
viewing | Read and select |
Set it on the widget (DocumentEditor(interactionMode:)) or the controller (configureInteractionMode).
Review API on the controller
For a read/export view, call document.withRevisions(accepted: true) or accepted: false rather than accepting/rejecting the live document and undoing it. The typed API exports this extension from package:vyuh_document/review.dart; the canonical model exports it from engine.dart. only: limits the pending revision IDs to complete. Completed records retain their decision for provenance. Unsupported legacy completion metadata throws instead of returning a partial view. A canonical caller can pass its installed elements: registry.
document.commentThreads derives root/reply records in recorded order. commentThread(id) resolves either a root or reply. anchoredText(id) quotes the canonical text units, and isCommentOrphaned(id) reports missing, deleted or invalid anchors. Typed hosts import comments.dart; runtime controllers expose these same queries. There is no host-maintained thread shadow.
Comments carry optional authorName, editedAt and JSON metadata. AddComment, ReplyToComment and EditComment accept name/metadata arguments in Dart and generated agent JSON. Runtime updateCommentDetails updates the same record. Edits stamp their time and Undo restores the whole record. Metadata is deeply owned at the document boundary and round-trips in canonical JSON. DOCX keeps supported detail provenance beside native Word comment data; native text, anchors, creation time and thread state remain authoritative.
dart
import 'package:vyuh_document/vyuh_document.dart' as document;
import 'package:vyuh_document/review.dart' as document;
import 'package:vyuh_document/comments.dart' as document;
import 'package:vyuh_document/engine.dart' as engine;
import 'package:vyuh_document/types.dart' as core;
import 'package:vyuh_document_editor/vyuh_document_editor.dart' as editor;
// A pure view. The source and the live controller's Undo history are untouched.
document.Document acceptedView(document.Document source) =>
source.withRevisions(accepted: true);
List<engine.DocumentCommentThread> threads(document.Document source) =>
source.commentThreads;
String? quote(document.Document source, core.CommentId comment) =>
source.anchoredText(comment);
// Runtime controllers project the same records; edits use the existing
// command service and canonical permission/history pipeline.
void updateDetails(
editor.DocumentEditorController controller,
core.CommentId id,
) {
controller.updateCommentDetails(
id,
authorName: 'Asha',
metadata: {'attachment': 'file-1'},
);
}
String? namedStyle(
editor.DocumentEditorController controller,
core.DocumentBlock block,
) => controller.effectiveStyleIdOf(block);
// Portable ids are an authoring vocabulary. A heading does not acquire a
// named style merely because its level matches one of these ids.
String headingStyle(int level) => core.headingStyleIdFor(level);| Method | Does |
|---|---|
canAddComment(selection) | Whether a comment can anchor there: text inside one block |
addCommentToSelection(text, id:) | Adds a comment and returns its CommentId; id: chooses it, and text may be empty |
requestComment() | Asks your commentComposer for the text, adds the comment and returns the new DocumentComment; the one path the Add comment action, its shortcut, the right-click menu and a double tap in commenting mode all take |
addReplyToComment(id, text), updateComment, deleteComment | Thread management |
setCommentResolved(id, resolved) | Resolve or reopen |
acceptRevision(id), rejectRevision(id) | Decide a suggestion by its RevisionId |
acceptAllRevisions(), rejectAllRevisions() | Decide every pending suggestion, or only the IDs in revisionIds: |
protectSelection(), unprotectSelection() | Protected regions (template design) |
A comment action that can't be done throws DocumentCommentRefusal, whose reason says why: multiBlockAnchor or emptyAnchor for the selection, unknownComment, duplicateId, or refused when the mode, protection or grants refuse it. Anyone may change their own comments; changing another author's needs the resolveComments, deleteComments or editComments grant, which the host gives through the controller's authority: (DocumentAuthority(actor: () => DocumentActor(id: ..., grants: ...))). The editor checks no author itself: the review panel's buttons ask the same gate (controller.refusalOf(...)), so they are enabled exactly when the change would be admitted. Try it live.
Accept or reject everything
acceptAllRevisions() and rejectAllRevisions() decide every pending suggestion as one edit: one undo brings them all back. Pass revisionIds: to decide only some of them. Both return how many they completed; 0 means nothing changed. A suggestion that can't be completed is skipped and the rest still go through.
dart
import 'dart:async';
import 'package:material_ui/material_ui.dart';
import 'package:vyuh_document_editor/vyuh_document_editor.dart';
void main() => runApp(const MaterialApp(home: BatchReview()));
class BatchReview extends StatefulWidget {
const BatchReview({super.key});
@override
State<BatchReview> createState() => _BatchReviewState();
}
class _BatchReviewState extends State<BatchReview> {
// A note whose revisions were recorded in suggesting mode.
final controller = DocumentEditorController.richText(
layoutMode: DocumentEditorLayoutMode.pageless,
document: loadSuggestedNote(),
);
// Batches, undo and typed suggestions all arrive on the change feed.
late final StreamSubscription<Object?> changes;
String result = '';
@override
void initState() {
super.initState();
changes = controller.changes.listen((_) => setState(() {}));
}
// Pending revisions are read from the canonical document.
List<DocumentRevision> get pending => [
for (final revision in controller.document.revisions)
if (revision.status == RevisionStatus.pending) revision,
];
// Each call is one edit and one undo step; it returns how many completed
// (0 means nothing was committed).
void run(String label, int Function() batch) =>
setState(() => result = '$label: ${batch()}');
@override
void dispose() {
changes.cancel();
controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) => Scaffold(
body: Column(
children: [
Wrap(
spacing: 8,
children: [
FilledButton(
onPressed: () => run('Accepted', controller.acceptAllRevisions),
child: const Text('Accept all'),
),
OutlinedButton(
onPressed: () => run('Rejected', controller.rejectAllRevisions),
child: const Text('Reject all'),
),
// A subset: pass the ids to complete together.
OutlinedButton(
onPressed: () => run(
'Accepted',
() => controller.acceptAllRevisions(
revisionIds: [
for (final revision in pending)
if (revision.type == RevisionType.insertion) revision.id,
],
),
),
child: const Text('Accept insertions only'),
),
// One undo restores the whole batch.
TextButton(onPressed: controller.undo, child: const Text('Undo')),
],
),
Text('${pending.length} pending. $result'),
Expanded(
child: DocumentEditor(
controller: controller,
interactionMode: DocumentInteractionMode.suggesting,
configuration: DocumentEditorConfiguration.richText(),
),
),
],
),
);
}
// Your saved document, with its pending revisions.
Document loadSuggestedNote() => Document.empty(title: 'Release note');How each kind of suggestion looks is described in Transactions and history.