CRDT LF Flutter

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

Flutter reactivity for crdt_lf. Rebuild your widgets when the CRDT state changes, for the whole document or for one handler, and bind text fields and editors to collaborative text. Built on provider.

Read the full documentation

πŸ“– The full Flutter guide β€” widgets, delta widgets, text fields, editors, presence β€” is on mattiapispisa.it/crdt.

Features

  • 🌳 CrdtProvider: provides a CRDTDocument to the subtree
  • πŸ” CrdtBuilder / CrdtSelector: rebuild on every document update, or on a slice
  • 🎯 CrdtHandlerBuilder / Selector / Listener: rebuild only when one handler changes, nested ones included
  • πŸ” CrdtHandlerDeltaBuilder / Listener: follow what each change did, for long lists and AnimatedList
  • ✍️ CrdtTextFieldBuilder: a TextEditingController bound to a text handler, IME included, zero rebuilds
  • πŸ…±οΈ CrdtRichTextFieldBuilder: inline formats in a TextField, with undo
  • 🧩 CrdtEditorBinder: the sync loop for any editor (used by crdt_lf_quill)
  • πŸ‘₯ CrdtTextCursorsOverlay / CrdtAwarenessCursorsOverlay: the other peers' carets and pointers
  • βž• …and more: everything else is in the documentation

See it live

Greyhound Markdown is built with crdt_lf and crdt_lf_flutter. Open it on two devices, join the same room and edit together.

Open the live demo

The example app shows every widget on one screen, with a ⟳ rebuilt Γ—N badge on each region:

crdt_lf_flutter_example

Quick start

flutter pub add crdt_lf crdt_lf_flutter

Provide the document to the tree:

void main() {
  runApp(
    MaterialApp(
      title: 'Todos',
      home: CrdtProvider(
        // In memory: the provider creates the document and disposes it.
        create: (_) {
          final document = CRDTDocument();
          todosOf(document); // the widgets read the list under 'todos'
          return document;
        },
        child: const TodoPage(),
      ),
    ),
  );
}

Rebuild on one handler, and read it once for an action:

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(title: const Text('Todos')),
    floatingActionButton: FloatingActionButton(
      tooltip: 'New todo',
      // An action needs no rebuild: read the handler once.
      onPressed:
          () => addTodo(
            context.crdtHandler<CRDTMovableListRefHandler>('todos'),
          ),
      child: const Icon(Icons.add),
    ),
    // Rebuilds when a todo is added, removed or moved. An edit of one item
    // rebuilds only what follows it in its tile.
    body: CrdtHandlerBuilder<CRDTMovableListRefHandler>(
      id: 'todos',
      builder: (context, todos) {
        return ReorderableListView(
          // `to` is the place after the move, as `move` counts it.
          onReorderItem: todos.move,
          children: [
            // One tile per reference, so a tile index is the list index.
            for (final (index, ref) in todos.childRefs().indexed)
              switch (todos.doc.resolveHandler(ref)) {
                final CRDTMapRefHandler todo => TodoTile(
                  key: ValueKey(ref.id),
                  todo: todo,
                  onDelete: () => todos.removeChildAt(index),
                ),
                // A kind this peer does not know, from a newer peer.
                _ => ListTile(
                  key: ValueKey(ref.id),
                  title: const Text('Unknown item'),
                ),
              },
          ],
        );
      },
    ),
  );
}

onReorderItem is recent in Flutter. On an older Flutter, use onReorder and lower to by one when it is after from.

The whole app (todosOf, addTodo, TodoTile), tested in CI, is the todo list recipe. For a text field, see the note recipe.

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_flutter
Flutter reactivity for crdt_lf package.