Add mission TOC link, more comments in example app

README.md

@@ -18,6 +18,7 @@ API that will deliver auto-updating streams for your queries.
       - [Ordering](#ordering)
     + [Updates and deletes](#updates-and-deletes)
     + [Inserts](#inserts)
+    + [Custom statements](#custom-statements)
   * [Migrations](#migrations)
   * [TODO-List and current limitations](#todo-list-and-current-limitations)
     + [Limitations (at the moment)](#limitations-at-the-moment)

sally_flutter/README.md

@@ -18,6 +18,7 @@ API that will deliver auto-updating streams for your queries.
       - [Ordering](#ordering)
     + [Updates and deletes](#updates-and-deletes)
     + [Inserts](#inserts)
+    + [Custom statements](#custom-statements)
   * [Migrations](#migrations)
   * [TODO-List and current limitations](#todo-list-and-current-limitations)
     + [Limitations (at the moment)](#limitations-at-the-moment)

sally_flutter/example/lib/main.dart

@@ -11,6 +11,8 @@ class MyApp extends StatefulWidget {
   }
 }
 
+// We use this widget to set up the material app and provide an InheritedWidget that
+// the rest of this simple app can then use to access the database
 class MyAppState extends State<MyApp> {
   Database _db;
 
@@ -25,7 +27,7 @@ class MyAppState extends State<MyApp> {
     return DatabaseProvider(
       db: _db,
       child: MaterialApp(
-        title: 'Flutter Demo',
+        title: 'Sally Demo',
         theme: ThemeData(
           primarySwatch: Colors.purple,
         ),

sally_flutter/example/lib/widgets/homescreen.dart

@@ -13,8 +13,11 @@ class HomeScreen extends StatefulWidget {
   }
 }
 
+/// Shows a list of todo entries and displays a text input to add another one
 class HomeScreenState extends State<HomeScreen> {
+  // we only use this to reset the input field at the bottom when a entry has been added 
   final TextEditingController controller = TextEditingController();
+
   Database get db => DatabaseProvider.provideDb(context);
 
   @override
@@ -23,50 +26,65 @@ class HomeScreenState extends State<HomeScreen> {
       appBar: AppBar(
         title: Text('Todo list'),
       ),
+      // A SallyAnimatedList automatically animates incoming and leaving items, we only
+      // have to tell it what data to display and how to turn data into widgets.
       body: SallyAnimatedList<TodoEntry>(
-        stream: db.allEntries(),
-        itemBuilder: (ctx, dynamic item, animation) {
+        stream: db.allEntries(), // we want to show an updating stream of all todo entries
+        itemBuilder: (ctx, item, animation) {
+          // When a new item arrives, it will expand verticallly
           return SizeTransition(
-            key: ObjectKey((item as TodoEntry).id),
+            key: ObjectKey(item.id),
             sizeFactor: animation,
             axis: Axis.vertical,
-            child: TodoCard(item as TodoEntry),
+            child: TodoCard(item),
           );
         },
-        removedItemBuilder: (ctx, dynamic item, animation) {
+        removedItemBuilder: (ctx, item, animation) {
+          // and it will leave the same way after being deleted.
           return SizeTransition(
-            key: ObjectKey((item as TodoEntry).id),
+            key: ObjectKey(item.id),
             sizeFactor: animation,
             axis: Axis.vertical,
-            child: TodoCard(item as TodoEntry),
+            child: AnimatedBuilder(
+              animation: CurvedAnimation(parent: animation, curve: Curves.easeOut),
+              child: TodoCard(item),
+              builder: (context, child) {
+                return Opacity(
+                  opacity: animation.value,
+                  child: child,
+                );
+              }
+            ),
           );
         },
       ),
       bottomSheet: Material(
         elevation: 12.0,
-        child: Padding(
-          padding: const EdgeInsets.all(8.0),
-          child: Column(
-            mainAxisSize: MainAxisSize.min,
-            crossAxisAlignment: CrossAxisAlignment.start,
-            children: <Widget>[
-              Text('What needs to be done?'),
-              Row(
-                children: <Widget>[
-                  Expanded(
-                    child: TextField(
-                      controller: controller,
-                      onSubmitted: (_) => _createTodoEntry(),
+        child: SafeArea(
+          child: Padding(
+            padding: const EdgeInsets.all(8.0),
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: <Widget>[
+                Text('What needs to be done?'),
+                Row(
+                  children: <Widget>[
+                    Expanded(
+                      child: TextField(
+                        controller: controller,
+                        onSubmitted: (_) => _createTodoEntry(),
+                      ),
                     ),
-                  ),
-                  IconButton(
-                    icon: Icon(Icons.send),
-                    color: Theme.of(context).accentColor,
-                    onPressed: _createTodoEntry,
-                  ),
-                ],
-              ),
-            ],
+                    IconButton(
+                      icon: Icon(Icons.send),
+                      color: Theme.of(context).accentColor,
+                      onPressed: _createTodoEntry,
+                    ),
+                  ],
+                ),
+              ],
+            ),
           ),
         ),
       ),

sally_flutter/example/lib/widgets/todo_card.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:sally_example/database.dart';
 import 'package:sally_example/main.dart';
 
+/// Card that displays a todo entry and an icon button to delete that entry
 class TodoCard extends StatelessWidget {
   final TodoEntry entry;
 
@@ -20,6 +21,8 @@ class TodoCard extends StatelessWidget {
               icon: const Icon(Icons.delete),
               color: Colors.red,
               onPressed: () {
+                // We delete the entry here. Again, notice how we don't have to call setState() or
+                // inform the parent widget. The animated list will take care of this automatically.
                 DatabaseProvider.provideDb(context).deleteEntry(entry);
               },
             )

sally_flutter/lib/src/animated_list.dart

@@ -20,8 +20,8 @@ class SallyAnimatedList<T> extends StatefulWidget {
       @required this.removedItemBuilder});
 
   @override
-  _SallyAnimatedListState createState() {
-    return _SallyAnimatedListState();
+  _SallyAnimatedListState<T> createState() {
+    return _SallyAnimatedListState<T>();
   }
 }