CRDT LF Quill

package badge pub points pub likes codecov ci badge license pub publisher

Collaborative rich text for flutter_quill. CrdtQuillBinder keeps a QuillController in step with a CRDTFugueRichTextHandler from crdt_lf, so several peers edit the same page, with bold, links, headings and lists.

Read the full documentation

πŸ“– The full guide β€” embeds, undo, remote cursors, limits β€” is on mattiapispisa.it/crdt.

Features

  • πŸ…±οΈ Formats: inline and block attributes, merged per key
  • πŸ–ΌοΈ Embeds: images and videos shared with crdt_lf, plus your own types
  • ↩️ Undo: Quill's own history, or a CRDTUndoManager that knows formats and peers
  • πŸ‘₯ Remote cursors: CrdtQuillCursorsOverlay, on stable positions
  • πŸ˜€ Emoji-safe: offsets converted between Quill's UTF-16 and the handler's runes
  • βœ… Self-checking: the binder compares the editor and the handler after every change
  • βž• …and more: everything else is in the documentation
crdt_lf_quill_example

Quick start

flutter pub add crdt_lf crdt_lf_flutter crdt_lf_hive crdt_lf_quill flutter_quill hive path_provider
flutter pub add flutter_localizations --sdk=flutter

flutter_quill needs its localizations in the app. Hive keeps the page on the device:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // On the web Hive uses IndexedDB and needs no path.
  if (!kIsWeb) {
    Hive.init((await getApplicationDocumentsDirectory()).path);
  }
  CRDTHive.initialize();
  final backend = await CRDTHive.open();

  runApp(EditorApp(backend: backend));
}

/// The app: one rich text page stored in [backend].
class EditorApp extends StatelessWidget {
  /// Creates the app of the page stored in [backend].
  const EditorApp({required this.backend, super.key});

  /// Where the page is stored.
  final CRDTStorageBackend backend;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Editor',
      // flutter_quill reads its texts from here, and throws without them.
      localizationsDelegates: const [
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        FlutterQuillLocalizations.delegate,
      ],
      home: EditorPage(backend: backend),
    );
  }
}

The page opens the stored page, owns the controller and the undo manager, and binds them to a CRDTFugueRichTextHandler registered as 'page':

// The State owns these: the binder never disposes them, and a new
// FocusNode on each build would drop the keyboard.
final _controller = QuillController.basic();
final _focusNode = FocusNode();
final _scrollController = ScrollController();

PersistentDocument? _page;
CRDTUndoManager? _undo;

@override
void initState() {
  super.initState();
  unawaited(_open());
}

Future<void> _open() async {
  final page = await widget.backend.openDocument('page');
  final text = CRDTFugueRichTextHandler(page.document, 'page');
  // Records only the edits made in this editor.
  final undo = CRDTUndoManager(
    page.document,
    trackedOrigins: {crdtQuillOrigin},
  )..track(text);

  if (!mounted) {
    undo.dispose();
    return _close(page);
  }
  setState(() {
    _page = page;
    _undo = undo;
  });
}

@override
void dispose() {
  _controller.dispose();
  _focusNode.dispose();
  _scrollController.dispose();
  _undo?.dispose();
  final page = _page;
  if (page != null) {
    unawaited(_close(page));
  }
  super.dispose();
}

static Future<void> _close(PersistentDocument page) async {
  await page.persistence.dispose(); // writes what is still waiting
  page.document.dispose();
  await page.persistence.storage.close();
}

@override
Widget build(BuildContext context) {
  final page = _page;
  if (page == null) {
    return const Scaffold(body: Center(child: CircularProgressIndicator()));
  }

  return Scaffold(
    appBar: AppBar(title: const Text('Editor')),
    body: CrdtProvider.value(
      value: page.document,
      child: CrdtQuillBinder(
        id: 'page',
        controller: _controller,
        // The editor, its shortcuts and the toolbar buttons undo through it.
        undoManager: _undo,
        builder:
            (context) => Column(
              children: [
                // The binder gives the controller a new document: key the
                // toolbar on it, so its undo and redo buttons follow.
                ListenableBuilder(
                  listenable: _controller,
                  builder:
                      (context, _) => QuillSimpleToolbar(
                        key: ObjectKey(_controller.document),
                        controller: _controller,
                        config: const QuillSimpleToolbarConfig(
                          multiRowsDisplay: false,
                        ),
                      ),
                ),
                const Divider(height: 1),
                Expanded(
                  child: QuillEditor.basic(
                    controller: _controller,
                    focusNode: _focusNode,
                    scrollController: _scrollController,
                    config: QuillEditorConfig(
                      padding: const EdgeInsets.all(16),
                      // Shows an embed of another peer that has no builder.
                      unknownEmbedBuilder: crdtQuillUnknownEmbedBuilder(),
                    ),
                  ),
                ),
              ],
            ),
      ),
    ),
  );
}

The complete editor, saved on the device with undo and tested in CI, is the recipe. The example shows two editors on two simulated peers, with each other's cursors.

Documentation

Roadmap

Roadmap: done, in progress, to do

πŸ—ΊοΈ The project board shows what is done, what is in progress and what comes next, for this package and the rest of the workspace. Missing something? Open an issue: requests go on the board too.

Apps

Packages

Other bricks of the crdt "system" are:

Libraries

crdt_lf_quill