Typed identifiers
No public API takes a string to name an action, a toolbar section, an operation or a mark. You pass a typed value, such as MarkActionId.bold, TableActionId.insert, CoreDocumentOperation.textInsert or TextMark.bold, so a typo fails at compile time and your editor lists what exists.
Who declares what
Each owner declares its own closed set next to its code: an enum, or a final class when an identifier carries data.
| Identifies | Interface | Declared by |
|---|---|---|
| Editor actions | EditorActionId | The editor (HistoryActionId, MarkActionId, TableActionId, WorkspaceCommandId, …) and each extension (KatexActionId, MermaidActionId, DiagramActionId, CitationActionId) |
| Toolbar sections | DocumentToolbarSectionId | The editor (EditorToolbarSectionId) and extensions |
| Document operations | DocumentOperationId | The core (CoreDocumentOperation, DocumentWorkflowOperation) and extensions |
| Marks | TextMark | The core |
Declare and use action IDs
dart
import 'package:vyuh_document_editor/vyuh_document_editor.dart';
// An extension declares its actions as one closed set. `key` is the persisted
// spelling (saved toolbar settings, widget keys); it is written only here.
enum StampActionId with EditorActionKey implements EditorActionId {
approved('stamp-approved'),
rejected('stamp-rejected');
const StampActionId(this.key);
@override
final String key;
}
// Hosts name actions by value, so a typo or a missing action does not compile.
final configuration = DocumentEditorConfiguration(
toolbar: DocumentToolbarConfiguration(
actionIds: {
HistoryActionId.undo,
MarkActionId.bold,
StampActionId.approved,
},
),
);
// Removing an action is a host extension in the controller's extension list.
final stampsPolicy = DocumentHostExtension(
id: 'app.stamps-policy',
register: (registry) => registry.unregisterAction(StampActionId.rejected),
);Register each action with its typed id (EditorAction.toolbar(id: StampActionId.approved, …)). Toolbars, menus, the command palette, the action catalog and unregisterAction then refer to it by that value.
Typed values
Colours and review IDs are typed too.
| Value | Type | Use |
|---|---|---|
| A colour | DocumentColor | DocumentColor.hex('#7B1FA2') parses #RGB, #ARGB, #RRGGBB or #AARRGGBB once and throws a FormatException otherwise; DocumentColor.argb(0xFF7B1FA2) is a const. .hex is the stored form (upper-case #RRGGBB, or #AARRGGBB when translucent). In Flutter, color.toColor() and flutterColor.toDocumentColor() convert. |
| A suggestion | RevisionId | DocumentRevision.id, acceptRevision, rejectRevision, acceptAllRevisions(revisionIds:), rejectAllRevisions(revisionIds:); in the typed API Suggestion.id, AcceptSuggestion, RejectSuggestion |
| A comment | CommentId | DocumentComment.id, addCommentToSelection (returns one; id: lets the host choose it), addReplyToComment, updateComment, deleteComment, setCommentResolved; in the typed API AddComment (returns one), ReplyToComment, EditComment, ResolveComment, ReopenComment, DeleteComment, Comment.id |
A host that keeps comment bodies elsewhere passes its own id and an empty text: addCommentToSelection('', id: CommentId('thread-42')). The anchor and the id round-trip through canonical JSON; an id already in the document is refused with DocumentCommentRefusalReason.duplicateId. Try it live.
The selection colour readbacks (selectionTextColor, selectionHighlightColor, textHighlighterColor) return DocumentColor?, where null means automatic (or mixed, or no highlight). setSelectionTextColor takes a DocumentColor; to return the selection to automatic, clear the property: clearSelectionCharacterProperties({CharacterFormatProperty.color}). setTextHighlighterColor(null) makes the highlighter clear highlight.
RevisionId and CommentId wrap the stored string at no cost and read as a String, but a string never becomes one by accident: write RevisionId('r1') when you have an ID from elsewhere. Canonical JSON is unchanged: the same hex strings and ID strings as before.
Where strings remain
Strings appear only where something is stored or sent:
- Saved keys.
id.keyis what saved toolbar settings and widget keys hold.registry.decodeActionKeys(keys)reads them back, returning the matchingidsand anyunknownKeys. - The wire format. Transactions and receipts carry an operation's
wireName(text.insert). - Content data. Block IDs and source IDs are your own strings.
- Stored model colours. Model fields such as
CharacterFormat.colorhold the canonical string, which may also be a keyword such asautofrom an imported Word file.DocumentColor.tryParsereads one.