Typed Document API reference
dart
import 'package:vyuh_document/vyuh_document.dart';
import 'package:vyuh_document/elements.dart';Pure Dart. Guide: Typed Document API.
Documents and configuration
| Type | Purpose | Key members |
|---|---|---|
DocumentConfiguration | The elements and marks a document may use | DocumentConfiguration(elements:, marks:), richText, elements, marks, elementOf<T>(), allowsMark(mark), decodeCommand(json), describe(), commandNames |
Document | Immutable content read through its configuration | Document.of(config, blocks), Document.fromJson(config, json), body, section(i), sectionCount, footnotes, read(ref), plainText, suggestions, comments, toJson() |
Node, Block | Base classes of element content | declaration |
Alignment | Text alignment | start, center, end, justify |
Controller
| Type | Purpose | Key members |
|---|---|---|
DocumentController | One participant's live session | DocumentController(config, document:, author:), open(...) (returns Result), document, state, configuration, author, participantId, run(command), preview(command), select(range), join(author:, mode:), mode, setMode(mode), modeChanges, changes, close() |
DocumentState | Immutable snapshot | document, revision, selection, canUndo, canRedo, mode |
DocumentInteractionMode | A participant's mode | editing, suggesting (edits become suggestions), commenting, reviewing, viewing (content commands refused with NotAllowed) |
Author | Who made a change | Author.person(name), Author.agent(name), id, isAgent |
Change | One applied change | author, participantId, revision, command, document |
ParticipantId | A joined controller's identity, unique even when two share an author; an extension type over String, ordered by value | ParticipantId(value), value, compareTo |
Addressing
| Type | Purpose | Key members |
|---|---|---|
Ref<T> | A typed reference that survives edits | element, exists, description, toJson() |
Position | An offset inside a node's text | Position(ref, offset:) |
Range | Text between two positions in one node | Range(start, end), Range.at(position), isCollapsed |
Story | One flow of blocks | at<T>(i), first<T>(), where<T>(test), all<T>(), label |
Section | A section's body, headers and footers | body, header(kind), footer(kind) |
Notes | The document's footnotes | length, at(i) |
HeaderKind | Which header or footer | primary, first, even |
Guide: Addressing.
Commands
| Type | Purpose |
|---|---|
Command<R> | Base of every command; name, toJson() |
TextCommand: InsertText, DeleteRange, SetText, SplitBlock, ToggleMark, SetAlignment | Text edits |
Mark: Bold, Italic, Underline, Strike, Superscript, Subscript | Marks for ToggleMark and configurations (superscript and subscript replace each other) |
StructureCommand: InsertBlock (.before, .inside), MoveBlock, RemoveBlock, SetAttribute | Block structure and attributes |
HistoryCommand: Undo, Redo | This controller's own history |
Guide: Commands.
Results and errors
| Type | Purpose | Key members |
|---|---|---|
Result<T> | Success or a typed error | valueOrNull, errorOrNull, isDone, then, map |
Done<T>, Failed<T> | The two outcomes | value, error |
DocumentError | Base of every error | message, where, expected, found, hint, toJson(), DocumentError.fromJson(json) |
NotFound, NotAllowed, InvalidAttribute, Unsupported, Conflict, InvalidDocument | Error kinds | |
UnknownCommand | An undeclared command name | didYouMean |
elements.dart
| Type | Purpose | Key members |
|---|---|---|
Paragraph | Text with marks | Paragraph(text, alignment:, keepWithNext:), text, Paragraph.element, Paragraph.alignment, Paragraph.keepWithNext |
PageBreak, ColumnBreak | Authored physical flow boundaries, retained in pageless flow | PageBreak(), ColumnBreak(), .element |
Heading | Text at an outline level | Heading(text, level:), text, Heading.element, Heading.level |
HeadingLevel | h1 to h6 | |
HeadingAddress | Story.heading(text:) | |
Footnote, Endnote | Note elements | .element |
FootnoteAddress | Notes.note(i) | |
NoteCommand: InsertFootnote, InsertEndnote, SetFootnoteText, SetEndnoteText | Note commands |
review.dart
| Type | Purpose | Key members |
|---|---|---|
ReviewCommand: AcceptSuggestion, RejectSuggestion | Decide one pending suggestion by its RevisionId; an unknown id is NotFound | suggestion |
ReviewCommand: AcceptAllSuggestions, RejectAllSuggestions | Decide every pending suggestion as one change; returns how many | |
Suggestion | One pending suggestion | id (RevisionId), authorId, kind, summary, toJson() |
SuggestionKind | What it proposes | insertion, deletion, formatting |
RevisionId | A suggestion's identity; an extension type over String | RevisionId(value), value |
Deciding another participant's suggestion needs the decideSuggestions grant; a participant's own suggestions need none.
comments.dart
Comment commands run in every mode but viewing. Changing another author's comment needs a grant: resolveComments, deleteComments or editComments.
| Type | Purpose | Key members |
|---|---|---|
AddComment | Anchors a comment on a Range inside one block; returns its CommentId (id: chooses it, and must be new). text may be empty | range, text, id |
ReplyToComment | Replies to a thread; returns the reply's CommentId | comment, text, id |
EditComment | Replaces a comment's text | comment, text |
ResolveComment, ReopenComment | Resolve or reopen a comment | comment |
DeleteComment | Deletes a comment; a thread's first comment takes its replies | comment |
Comment | One comment or reply, from Document.comments | id, authorId, text, replyTo, resolved, toJson() |
CommentId | A comment's identity; an extension type over String | CommentId(value), value |
Refusals: a range across blocks or an empty one is NotAllowed whose found is multiBlockAnchor or emptyAnchor; an unknown id is NotFound and an id already taken is Conflict, each with the id as found.
editor_binding.dart (adapters only)
For editor adapters that mount a DocumentController. Applications do not need it.
| Name | Purpose |
|---|---|
DocumentControllerBinding | Extension on DocumentController: canonicalDocument, commandsBetween, adoptCanonical, publishCaret(selection), otherCarets, presenceChanges |
EditorEdit | The command recorded for an edit made in an editor |
ParticipantCaret | Another participant's published caret: author, participantId, and selection (the caret at its extent, with its affinity and range) |