Todos example
This example leverages the power of the Solid
widgets using signals
and providers
.
TodosPage#
In this example we've a TodosPage
that is the starting point of our todos feature.
The TodosPage
uses a Solid
widget to provide a TodosController
to descendants.
class TodosPage extends StatelessWidget {
const TodosPage({super.key});
@override
Widget build(BuildContext context) {
// Using SolidProvider here to provide the [TodosController] to descendants.
return Solid(
providers: [
SolidProvider<TodosController>(
create: () => TodosController(initialTodos: Todo.sample),
dispose: (controller) => controller.dispose(),
),
],
child: const TodosPageView(),
);
}
}
TodosController#
Let's jump into the TodosController
and let's check what is responsible for.
The TodosController
is where the business logic lives.
It keep the whole todos list state and allows us to add, remove or toggle a Todo.
The TodosController
can have an initialValue, that is the initial list of todos.
@immutable
class TodosController {
TodosController({
List<Todo> initialTodos = const [],
}) : _todos = createSignal(initialTodos);
// Keep the editable todos signal private
// only the TodoController can mutate the value.
final Signal<List<Todo>> _todos;
// Expose the list of todos as a ReadSignal so the
// user cannot mutate directly the object.
ReadSignal<List<Todo>> get todos => _todos.toReadSignal();
void add(Todo todo) {
_todos.update((value) => [...value, todo]);
}
void remove(String id) {
_todos.update(
(value) => value.where((todo) => todo.id != id).toList(),
);
}
void toggle(String id) {
_todos.update(
(value) => [
for (final todo in value)
if (todo.id != id) todo else todo.copyWith(completed: !todo.completed)
],
);
}
void dispose() {
_todos.dispose();
}
}
As you can see the TodosController
can get an initialTodos
list. This is going to be its initial state.
When the constructor is runned, the _todos
signal is populated with the provided initialTodos
.
The thing to note here is that _todos
is private by choice. Instead the user has to use the todos
getter.
The todos
getter is a ReadSignal
. This means that the user won't be able to mutate its value directly.
The add
method uses the update
function of a Signal
to append the new todo
to the current list of todos.
In a similar way the remove
and toggle
methods update the signal value.
In the remove
method we remove from the list the todo with the id
provided.
In the toggle
method we loop through each todo and toggle the completed state of the todo with the given id
.
TodosPageView#
Let's jump back to the UI and let's see the TodosPageView
widget:
class TodosPageView extends StatelessWidget {
const TodosPageView({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('Todos'),
),
body: const Padding(
padding: EdgeInsets.all(8.0),
child: TodosBody(),
),
);
}
}
This widget is the child of the TodosPage
and is the base structure of our page.
You may wonder why I haven't placed this code in the TodosPage
.
This is necessary (only) for testing, so I can easily mock the TodosController
and just test the view.
TodosBody#
Let's continue to the TodosBody
.
The TodosBody
is the body of our feature, it has a text input on top where you can write a new todo, a Toolbar and the TodoList.
class TodosBody extends StatefulWidget {
const TodosBody({super.key});
@override
State<TodosBody> createState() => _TodosBodyState();
}
class _TodosBodyState extends State<TodosBody> {
final textController = TextEditingController();
@override
void dispose() {
textController.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
// retrieve the [TodosController], you're safe to `get` a Signal or Provider
// in both the `initState` and `build` methods.
final todosController = context.get<TodosController>();
return Solid(
signals: {
// make the active filter signal visible only to descendants.
// created here because this is where it starts to be necessary.
SignalId.activeTodoFilter: () =>
createSignal<TodosFilter>(TodosFilter.all),
// Registering two new signals, the list of completed and uncompleted todos.
// These are derived [ReadSignal]s.
// Provided through a [Solid] because their value is used by the [TodoList]
// and [Toolbar].
// This is preferable over passing the signals as parameters down to descendants,
// expecially when the usage is very deep in the tree.
SignalId.completedTodos: () => todosController.todos.select<List<Todo>>(
(value) => value.where((element) => element.completed).toList(),
),
SignalId.uncompletedTodos: () =>
todosController.todos.select<List<Todo>>(
(value) => value.where((element) => !element.completed).toList(),
),
},
child: Column(
children: [
TextFormField(
controller: textController,
decoration: const InputDecoration(
hintText: 'Write new todo',
),
validator: (v) {
if (v == null || v.isEmpty) {
return 'Cannot be empty';
}
return null;
},
onFieldSubmitted: (task) {
if (task.isEmpty) return;
final newTodo = Todo.create(task);
todosController.add(newTodo);
textController.clear();
},
),
const SizedBox(height: 16),
const Toolbar(),
const SizedBox(height: 16),
Expanded(
child: TodoList(
onTodoToggle: (id) {
todosController.toggle(id);
},
),
),
],
),
);
}
}
The important parts here are two.
- We're retrieving the
todosController
with the syntaxcontext.get<TodosController>()
. This is how we access providers from descendants. You can safely run this method in theinitState
, in thebuild
method or even inside a callback likeonPressed
. - We're creating a new
Solid
widget. Yes, you can create many Solid widgets inside your app, this the ideal usage. Don't use a singleSolid
widget but many. Place thesignals
andproviders
only where needed.
Here we're creating the a signal with id SignalId.activeTodoFilter
with an initial value of TodosFilter.all
. This signals keeps the state of the current selected tab.
We're also creating two derived signals, the list of completedTodos
and uncompletedTodos
using the select
method of the todos list signal.
In the TextFormField
when the field is submitted we add the new todo simply using:
// skip if the task is empty
if (task.isEmpty) return;
// create the new todo
final newTodo = Todo.create(task);
// add it to the todosList using our todosController
todosController.add(newTodo);
// clear the text field in order to be able to enter a new todo
textController.clear();
Toolbar#
The toolbar shows 3 tabs (or filters).
- All the todos
- The uncompleted todos list
- The completed todos list
Each tab contain the number of todos present in the current tab.
class Toolbar extends StatefulWidget {
const Toolbar({super.key});
@override
State<Toolbar> createState() => _ToolbarState();
}
class _ToolbarState extends State<Toolbar> {
/// All the derived signals
late final ReadSignal<int> allTodosCount;
late final ReadSignal<int> uncompletedTodosCount;
late final ReadSignal<int> completedTodosCount;
@override
void initState() {
super.initState();
// retrieve the todos from TodosController.
final todos = context.get<TodosController>().todos;
// create derived signals based on the list of todos
// no need to dispose them because they already dispose when the parent (todos) disposes.
allTodosCount = todos.select((value) => value.length);
// retrieve the list of completed count and select just the length.
final completedTodos =
context.get<ReadSignal<List<Todo>>>(SignalId.completedTodos);
completedTodosCount = completedTodos.select((value) => value.length);
// retrieve the list of uncompleted count and select just the length.
final uncompletedTodos =
context.get<ReadSignal<List<Todo>>>(SignalId.uncompletedTodos);
uncompletedTodosCount = uncompletedTodos.select((value) => value.length);
}
/// Maps the given [filter] to the correct list of todos
ReadSignal<int> mapFilterToTodosList(TodosFilter filter) {
switch (filter) {
case TodosFilter.all:
return allTodosCount;
case TodosFilter.uncompleted:
return uncompletedTodosCount;
case TodosFilter.completed:
return completedTodosCount;
}
}
@override
Widget build(BuildContext context) {
return DefaultTabController(
length: TodosFilter.values.length,
initialIndex: 0,
child: TabBar(
labelColor: Colors.black,
tabs: TodosFilter.values.map(
(filter) {
final todosCount = mapFilterToTodosList(filter);
// Each tab bar is using its specific todos count signal
return SignalBuilder(
signal: todosCount,
builder: (context, todosCount, _) {
return Tab(text: '${filter.name} ($todosCount)');
},
);
},
).toList(),
onTap: (index) {
// update the current active filter
context.update<TodosFilter>(
SignalId.activeTodoFilter,
(_) => TodosFilter.values[index],
);
},
),
);
}
}
To get the total number of todos we've used the select
method of signals.
It subscribes to the signal and updates only when the selected value changes.
Then we have used a SignalBuilder
to rebuild every time the count signal changes.
Finally, when a tab is tapped, we update
the activeTodoFilter
signal to set the new active tab.
TodosList#
The TodosList
renders all the todos based on the current activeFilter
.
In order to react to the active filter it uses the observe
extension on BuildContext
that subscribes to the signal provided and rebuilds every time the value changes.
class TodoList extends StatefulWidget {
const TodoList({
super.key,
this.onTodoToggle,
});
final ValueChanged<String>? onTodoToggle;
@override
State<TodoList> createState() => _TodoListState();
}
class _TodoListState extends State<TodoList> {
late final ReadSignal<List<Todo>> todos;
late final ReadSignal<List<Todo>> completedTodos;
late final ReadSignal<List<Todo>> uncompletedTodos;
@override
void initState() {
super.initState();
// retrieve the whole todos list and the filtered ones
// this can be done here in the initState, or in the build method.
// You're not going to experience any performance issues writing the
// lines below in the build method. Used the initState here just
// to show you that it's possible.
// NOTE: If you need to `select` a value from a signal, do it always in the `initState`.
// The `select` method creates a new signal every time it runs, and you don't want this to happen.
todos = context.get<TodosController>().todos;
completedTodos =
context.get<ReadSignal<List<Todo>>>(SignalId.completedTodos);
uncompletedTodos =
context.get<ReadSignal<List<Todo>>>(SignalId.uncompletedTodos);
}
// Given a [filter] return the correct list of todos
ReadSignal<List<Todo>> mapFilterToTodosList(TodosFilter filter) {
switch (filter) {
case TodosFilter.all:
return todos;
case TodosFilter.uncompleted:
return uncompletedTodos;
case TodosFilter.completed:
return completedTodos;
}
}
@override
Widget build(BuildContext context) {
// rebuilds this BuildContext every time the `activeFilter` value changes
final activeFilter =
context.observe<TodosFilter>(SignalId.activeTodoFilter);
return SignalBuilder(
// react to the correct list of todos list
signal: mapFilterToTodosList(activeFilter),
builder: (_, todos, __) {
return ListView.builder(
itemCount: todos.length,
itemBuilder: (BuildContext context, int index) {
final todo = todos[index];
return TodoItem(
todo: todo,
onStatusChanged: (_) {
widget.onTodoToggle?.call(todo.id);
},
);
},
);
},
);
}
}
Testing#
Here we're going to separate the widgets tests from the business logic tests.
We're going to write unit tests just for the TodosController
and then we're going to write widgets tests for the whole feature.
TodosController tests#
Check that the TodosController
emits the initialTodos
as a value
test(' When providing initialTodos, `todos` emits the correct state', () {
// create controller with an initial value
const initialTodos = [
Todo(id: '1', task: 'mock1', completed: false),
Todo(id: '2', task: 'mock2', completed: false),
];
final controller = TodosController(initialTodos: initialTodos);
// cleanup resources
addTearDown(controller.dispose);
// verify that the list of todos has 2 items
expect(controller.todos.value, hasLength(2));
});
Test that we are able to add a new Todo
.
test('Add a todo', () {
// create controller
final controller = TodosController();
// cleanup resources
addTearDown(controller.dispose);
// verify that the list of todos is empty
expect(controller.todos.value, isEmpty);
// add a todo with id '1'
controller.add(const Todo(id: '1', task: 'mock1', completed: false));
// verify that the list of todos increased
expect(controller.todos.value, hasLength(1));
});
Test that we are able to remove an existing Todo
by its id
.
test('Remove a todo', () {
// create controller with an initial value
const initialTodos = [
Todo(id: '1', task: 'mock1', completed: false),
Todo(id: '2', task: 'mock2', completed: false),
];
final controller = TodosController(initialTodos: initialTodos);
// cleanup resources
addTearDown(controller.dispose);
// verify that the list of todos starts with 2 items
expect(controller.todos.value, hasLength(2));
// remove the todo with id '1'
controller.remove('1');
// verify that the list of todos decreased
expect(controller.todos.value, hasLength(1));
// verify that the remained todo has id '2'
expect(controller.todos.value.first.id, '2');
});
Test that we are able to toggle a Todo
in order to mark it as completed.
test('Toggle a todo', () {
// create controller with an initial value
const initialTodos = [
Todo(id: '1', task: 'mock1', completed: false),
];
final controller = TodosController(initialTodos: initialTodos);
// cleanup resources
addTearDown(controller.dispose);
// verify that the first todo is not completed
expect(controller.todos.value.first.completed, false);
// complete the first todo
controller.toggle('1');
// verify that the first todo is completed
expect(controller.todos.value.first.completed, true);
});
Widgets tests#
To easily test the Widgets I really suggest you to split the Solid
widget that provides providers
to descendants from descendants.
Like how I did with the TodosPage
and TodosPageView
:
class TodosPage extends StatelessWidget {
const TodosPage({super.key});
@override
Widget build(BuildContext context) {
// Using SolidProvider here to provide the [TodosController] to descendants.
return Solid(
providers: [
SolidProvider<TodosController>(
create: () => TodosController(initialTodos: Todo.sample),
dispose: (controller) => controller.dispose(),
),
],
child: const TodosPageView(),
);
}
}
class TodosPageView extends StatelessWidget {
const TodosPageView({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('Todos'),
),
body: const Padding(
padding: EdgeInsets.all(8.0),
child: TodosBody(),
),
);
}
}
As you can see I'm separating the creation of the Solid widget from the descendants.
This is necessary for testing, so I can easily mock the TodosController
and just test the view.
So let's start writing the widgets tests.
I'm going to use an helper function in all the tests to easily mock the TodosController
, here it is the source code:
// Utility function to easily wrap a [child] into a mocked todos controller.
Widget wrapWithMockedTodosController({
required Widget child,
required TodosController todosController,
}) {
return MaterialApp(
home: Solid(
providers: [
SolidProvider<TodosController>(
create: () => todosController,
dispose: (controller) => controller.dispose(),
),
],
child: child,
),
);
}
Check that the TodosController
emits the initialTodos
as a value
testWidgets('Todos with initial value', (WidgetTester tester) async {
// create controller with an initial value
final initialTodos = List.generate(
3,
(i) => Todo(id: "$i", task: 'mock$i', completed: false),
);
// Build our TodosPageView and trigger a frame.
await tester.pumpWidget(
wrapWithMockedTodosController(
todosController: TodosController(initialTodos: initialTodos),
child: const TodosPageView(),
),
);
// verify that there are 3 todos rendered initially
expect(tester.widgetList(find.byType(TodoItem)).length, 3);
// Verify that the todos list contains 'mock0'
expect(find.text('mock0'), findsOneWidget);
// Verify that the todos list contains 'mock1'
expect(find.text('mock1'), findsOneWidget);
// Verify that the todos list contains 'mock2'
expect(find.text('mock2'), findsOneWidget);
});
Test that we are able to add a new Todo
.
testWidgets('Add a todo', (WidgetTester tester) async {
// Build our TodosPageView and trigger a frame.
await tester.pumpWidget(
wrapWithMockedTodosController(
todosController: TodosController(),
child: const TodosPageView(),
),
);
// verify that there are 0 todos rendered initially
expect(tester.widgetList(find.byType(TodoItem)).length, 0);
// write and add a new todo
await tester.enterText(find.byType(TextFormField), 'test todo');
await tester.testTextInput.receiveAction(TextInputAction.done);
await tester.pump();
// verify that there is 1 todos now
expect(tester.widgetList(find.byType(TodoItem)).length, 1);
// Verify that the todos list contains 'test todo'
expect(find.text('test todo'), findsOneWidget);
});
Test that we are able to remove an existing Todo
by its id
.
testWidgets('Remove a todo', (WidgetTester tester) async {
// create controller with an initial value
final initialTodos = List.generate(
3,
(i) => Todo(id: "$i", task: 'mock$i', completed: false),
);
// Build our TodosPageView and trigger a frame.
await tester.pumpWidget(
wrapWithMockedTodosController(
todosController: TodosController(initialTodos: initialTodos),
child: const TodosPageView(),
),
);
// verify that there are 3 todos rendered initially
expect(tester.widgetList(find.byType(TodoItem)).length, 3);
final firstTodoItem = find.byType(TodoItem).first;
// simulate the drag from right to left
await tester.fling(
firstTodoItem,
const Offset(-300, 0),
1000,
);
await tester.pumpAndSettle();
// verify that there are 2 todos rendered now
expect(tester.widgetList(find.byType(TodoItem)).length, 2);
// Verify that the todos list doesn't contain 'mock0'
expect(find.text('mock0'), findsNothing);
});
Test that we are able to toggle a Todo
in order to mark it as completed.
testWidgets('Toggle a todo', (WidgetTester tester) async {
// create controller with an initial value
final initialTodos = List.generate(
2,
(i) => Todo(id: "$i", task: 'mock$i', completed: false),
);
final todosController = TodosController(initialTodos: initialTodos);
// Build our TodosPageView and trigger a frame.
await tester.pumpWidget(
wrapWithMockedTodosController(
todosController: todosController,
child: const TodosPageView(),
),
);
// verify that the completed tabs starts with 0 todos
expect(find.text('completed (0)'), findsOneWidget);
// toggle the first todo
await tester.tap(find.byType(CheckboxListTile).first);
await tester.pump();
// verify that the completed tab shows 1 todo now
expect(find.text('completed (1)'), findsOneWidget);
// tap in the completed tab
await tester.tap(find.text('completed (1)'));
await tester.pump();
// Verify that the completed todos list contains 'mock0'
expect(find.text('mock0'), findsOneWidget);
// Verify that the completed todos list not contains 'mock1'
expect(find.text('mock1'), findsNothing);
});