Commands
Every edit is a command with a typed result. Shared families come with the core; each element package adds its own.
dart
controller.run(SetText(cell, 'forty-two'));
controller.run(SetAttribute(intro, Heading.level, HeadingLevel.h2));
controller.preview(RemoveRow(table, at: 0)); // dry run
controller.run(const Undo());Shared families
Available in every configuration (from package:vyuh_document/vyuh_document.dart).
| Family | Command | Result | Does |
|---|---|---|---|
| Text | InsertText(position, text) | void | Inserts text at a position |
DeleteRange(range) | void | Deletes text in one block | |
SetText(ref, text) | void | Replaces a block's (or a cell's) text | |
SplitBlock(position) | Ref<Node> | Splits a block; returns the new block | |
ToggleMark(mark, range) | void | Bold(), Italic(), Underline(), Strike(), Superscript(), Subscript() | |
SetAlignment(ref, alignment) | void | Alignment.start, center, end, justify | |
| Structure | InsertBlock(block, after: ref) | Ref<T> | Also InsertBlock.before(block, before:) and InsertBlock.inside(block, container, at:) |
MoveBlock(ref, after: ref) | void | Moves a block | |
RemoveBlock(ref) | void | Removes a block | |
SetAttribute(ref, attribute, value) | void | Sets a declared attribute, checked against its range | |
| History | Undo(), Redo() | void | This controller's own changes only |
| Review | AcceptSuggestion(id), RejectSuggestion(id) | void | Decide one pending suggestion by its RevisionId; from package:vyuh_document/review.dart |
AcceptAllSuggestions(), RejectAllSuggestions() | int | Decide every pending suggestion | |
| Comments | AddComment(range, text:, id:) | CommentId | Anchors a comment on text inside one block; from package:vyuh_document/comments.dart |
ReplyToComment(id, text:, id:) | CommentId | Replies to a thread | |
EditComment(id, text) | void | Replaces a comment's text | |
ResolveComment(id), ReopenComment(id) | void | Resolves or reopens a comment | |
DeleteComment(id) | void | Deletes a comment and, for a thread's first, its replies |
Each controller runs commands in its own mode (DocumentInteractionMode): suggesting records content commands as suggestions attributed to it, and viewing, commenting and reviewing refuse them with NotAllowed. Comment commands run in every mode but viewing, and review decisions in editing, suggesting and reviewing. Deciding another participant's suggestion, or resolving, editing or deleting another's comment, also needs its grant (see Grants); a participant's own need none.
Element families
Each element package declares its own family, exported from package:<package>/element.dart (or all at once from vyuh_document_elements).
| Element | Package | Commands (result) |
|---|---|---|
Paragraph | vyuh_document (elements.dart) | Attributes Paragraph.alignment, Paragraph.keepWithNext |
Heading | vyuh_document_extension_heading | Attribute Heading.level |
Footnote, Endnote | vyuh_document (elements.dart) | InsertFootnote(at, text) (Ref<Footnote>), InsertEndnote(at, text) (Ref<Endnote>), SetFootnoteText, SetEndnoteText |
Table, Row, Cell | vyuh_document_extension_table | InsertRow(table, at:) (Ref<Row>), RemoveRow, InsertColumn, MergeCells(table, CellRange(...)) (Ref<Cell>); attribute Table.headerRows |
ListItem | vyuh_document_extension_list | Indent(item), Outdent(item), ToggleOrdered(item) |
Task | vyuh_document_extension_checklist | ToggleChecked(task); attribute Task.checked |
Code | vyuh_document_extension_code | SetLanguage(code, language:) |
Image | vyuh_document_extension_image | ResizeImage(image, width:, height:), SetAltText(image, text) |
Quote | vyuh_document_extension_block_quote | Blocks go in with InsertBlock.inside(block, quote) |
Divider | vyuh_document_extension_divider | Attribute Divider.thickness (0.25 to 12) |
Shape | vyuh_document_extension_shape | SetShapeKind(shape, ShapeKind.ellipse), ResizeShape(shape, width:, height:) |
TextBox | vyuh_document_extension_text_box | ResizeTextBox(box, width:, height:) |
Field (inline) | vyuh_document_extension_field | InsertField(position, FieldKind.page); kinds page, pageCount, sectionPage, sectionPageCount, section, date, time, title, author, wordCount |
TableOfContents | vyuh_document_extension_table_of_contents | InsertTableOfContents(after:, fromLevel:, toLevel:) (Ref<TableOfContents>), UpdateTableOfContents(toc) |
Equation | vyuh_document_extension_katex | SetEquation(equation, source) |
MermaidDiagram | vyuh_document_extension_mermaid | SetDiagramSource(diagram, source) |
Diagram | vyuh_document_extension_diagram | ResizeDiagram(diagram, width:, height:), SetDiagramAltText(diagram, text) |
Element constructors
| Constructor | Notes |
|---|---|
Paragraph(text, alignment:, keepWithNext:) | |
Heading(text, level: HeadingLevel.h2) | h1 to h6 |
Table([['a', 'b'], ['c', 'd']]), Table.grid(rows:, columns:) | |
ListItem(text, ordered:, level:, inListOf:) | inListOf continues an existing list |
Task(text, checked:) | |
Code(source, language:) | |
Image(asset, altText:, width:, height:) | asset is an asset ID your app resolves |
Quote([blocks]), Shape(kind:, width:, height:, blocks:), TextBox(width:, height:, blocks:) | Containers with their own story |
Divider(thickness:), Equation(source), MermaidDiagram(source), Diagram(width:, height:, altText:) |
A command must be configured
An unconfigured element fails with Unsupported; a result the grammar refuses fails with NotAllowed. Nothing is applied.
Next
- Collaboration: several controllers on one document.
- Agents: the same commands as JSON.
- Declare an element: add your own family.