Loading and persistence
DocumentEditorController.fromSource resolves a DocumentSource and then builds the controller. Saving is yours: read controller.document and store its JSON wherever your app keeps data.
dart
import 'package:vyuh_document_editor/vyuh_document_editor.dart';
Future<DocumentEditorController> loadNote(String savedJson) {
return DocumentEditorController.fromSource(
source: DocumentSource.jsonString(savedJson),
extensions: DocumentExtension.richText,
schema: DocumentSchemaPolicy.richText(),
);
}
// Dispose the returned controller when its owning widget is disposed.
// Capture controller.toJsonString() when saving; storage is host-owned.Present preparation
Import package:vyuh_document_editor/document_editor_view.dart for the host view capabilities. Set DocumentEditorTheme.preparingBuilder through the editor's theme scope or runtime configuration. It receives one immutable DocumentPreparationStatus for cold content, unavailable geometry or progress. Use its reason enum; diagnostic message text is not an action code. Progress is bounded below completion and physical admitted-page counts are absent in a continuous view. The progress surface overlays the existing content box.
The standard surface routes its labels through DocumentEditorLocalizations.preparationLabel. Override that method and the cold-page semantic getters through the same app localization delegate. Restore the standard treatment with defaultDocumentPreparingBuilder.
Keep the editor mounted while presenting a loading surface. Listen to its DocumentView: inputPhase is null between mounts and immediately preparing when a new mounted runtime is opened, before first paint. Exact mounted publication admits input; physical page prefixes remain previews. A runtime controller used headlessly can legitimately start admitted.
Runtime hosts listen to DocumentEditorController and read its inputPhase getter, which is also null without a bound viewport. This projects the existing query ownership and canonical phase; it does not store another ready flag.
Releasing the current runtime viewport returns its controller to headless admission, including an open abandoned before paint. A retiring viewport cannot release its successor's authority. Explicit suspension and termination persist.
After opening, admitted describes canonical input authority. Streaming typing and terminal layout-failure recovery can retain earlier paint; inspect the revision-matched layout/paint publication when current geometry is required. The action catalog and authority still decide which operations are allowed.
Animated preparation surfaces are supported: bounded cold-open work continues as event-loop tasks while unrelated animation frames are scheduled. An actual page-prefix publication explicitly yields to paint before further shaping.
dart
import 'package:material_ui/material_ui.dart';
import 'package:vyuh_document_editor/document_editor_view.dart';
import 'package:vyuh_document_editor/vyuh_document_editor.dart' as runtime;
// Install above either the typed or runtime DocumentEditor. The same hook
// handles the cold scene, unavailable geometry and non-displacing progress.
Widget withHostPreparation(Widget editor) => DocumentEditorThemeScope(
theme: DocumentEditorTheme.light().copyWith(
preparingBuilder: hostPreparation,
),
child: editor,
);
Widget hostPreparation(BuildContext context, DocumentPreparationStatus status) {
if (status.reason == DocumentPreparationReason.progress) {
return LinearProgressIndicator(value: status.progress);
}
return Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
const CircularProgressIndicator(),
Text(DocumentEditorLocalizations.of(context).preparationLabel(status)),
],
),
);
}
// Listen to this same view for changes. The phase is absent before mounting,
// immediately preparing on mount, and admitted only through the actual input
// publication gate. Admitted input does not mean every action is permitted.
bool hasAdmittedDocumentInput(DocumentView view) =>
view.inputPhase == DocumentInputPhase.admitted;
// Runtime hosts use the same getter name and canonical enum; listen to the
// controller itself. No frame counter or cached ready boolean is needed.
bool hasAdmittedRuntimeInput(runtime.DocumentEditorController controller) =>
controller.inputPhase == DocumentInputPhase.admitted;
class HostLoadingStrings extends DocumentEditorLocalizations {
const HostLoadingStrings();
@override
String get updatingDocumentLayout => 'Mise en page du document';
@override
String get documentPagesPreparing => 'Préparation des pages';
@override
String preparationLabel(DocumentPreparationStatus status) =>
switch (status.reason) {
DocumentPreparationReason.content => 'Préparation du document',
DocumentPreparationReason.decoration =>
'Préparation de la présentation',
DocumentPreparationReason.geometry => 'Préparation de la géométrie',
DocumentPreparationReason.progress =>
status.admittedPageCount == null
? 'Chargement du document'
: '${status.admittedPageCount} pages prêtes',
};
}
// Install alongside the app's Flutter localization delegates.
final hostLoadingStrings = DocumentEditorLocalizations.delegateFor(
(locale) => locale.languageCode == 'fr'
? const HostLoadingStrings()
: const DocumentEditorLocalizations(),
);Save a snapshot
controller.document.toJson() (or toJsonString()) is the value to store. Your app owns authentication, storage, autosave and conflicts.
Keep one controller for the editing session and dispose it with its widget.
Replace or stream
replaceDocument starts a new session. When a stream emits, your app decides whether that is a replacement or a collaborative change.
Files and resources
Byte sources take your decoder; URI sources take your loader. Fonts and image bytes are separate resources from the document JSON.
Headless extension decoding
Install an extension's canonical element collection before decoding its stored nodes. Installation registers that definition's decoder automatically, including divider and block-quote nodes without extension_kind. Decode in a worker only after activating the registry in that isolate. Repeating the same definitions is safe. A different decoder for the same schema remains rejected; do not wrap an existing codec in a new registration closure.
dart
import 'package:vyuh_document/types.dart';
import 'package:vyuh_document_extension_divider/vyuh_document_extension_divider.dart';
import 'package:vyuh_document_extension_block_quote/vyuh_document_extension_block_quote.dart';
// Definitions install their canonical codecs automatically. No Flutter editor
// or manual registerDocumentBlockDecoder closure is required.
DocumentElementRegistry headlessElements() =>
createCoreDocumentElementRegistry()
..install(createDividerDocumentElementCollection())
..install(createBlockQuoteDocumentElementCollection());
Document decodeStoredDocument(
JsonObject json,
DocumentElementRegistry elements,
) {
// Decoder tables are isolate-local. Reactivate a received registry before
// decoding in a worker; repeated activation of the same definitions is safe.
elements.activateInCurrentIsolate();
return Document.fromJson(json);
}