feat: implement two-sided pagination

Author: demchenkoalex

examples/flyer_chat/lib/hive_chat_controller.dart

@@ -13,25 +13,33 @@ class HiveChatController
   List<Message>? _cachedMessages;
 
   @override
-  Future<void> insertMessage(Message message, {int? index}) async {
+  Future<void> insertMessage(
+    Message message, {
+    int? index,
+    bool animated = true,
+  }) async {
     if (_box.containsKey(message.id)) return;
 
     // Index is ignored because Hive does not maintain order
     await _box.put(message.id, message.toJson());
     _invalidateCache();
-    _operationsController.add(ChatOperation.insert(message, _box.length - 1));
+    _operationsController.add(
+      ChatOperation.insert(message, _box.length - 1, animated: animated),
+    );
   }
 
   @override
-  Future<void> removeMessage(Message message) async {
+  Future<void> removeMessage(Message message, {bool animated = true}) async {
     final sortedMessages = List.from(messages);
     final index = sortedMessages.indexWhere((m) => m.id == message.id);
 
     if (index != -1) {
       final messageToRemove = sortedMessages[index];
       await _box.delete(messageToRemove.id);
       _invalidateCache();
-      _operationsController.add(ChatOperation.remove(messageToRemove, index));
+      _operationsController.add(
+        ChatOperation.remove(messageToRemove, index, animated: animated),
+      );
     }
   }
 
@@ -56,11 +64,14 @@ class HiveChatController
   }
 
   @override
-  Future<void> setMessages(List<Message> messages) async {
+  Future<void> setMessages(
+    List<Message> messages, {
+    bool animated = true,
+  }) async {
     await _box.clear();
     if (messages.isEmpty) {
       _invalidateCache();
-      _operationsController.add(ChatOperation.set([]));
+      _operationsController.add(ChatOperation.set([], animated: false));
       return;
     } else {
       await _box.putAll(
@@ -70,12 +81,18 @@ class HiveChatController
             .reduce((acc, map) => {...acc, ...map}),
       );
       _invalidateCache();
-      _operationsController.add(ChatOperation.set(messages));
+      _operationsController.add(
+        ChatOperation.set(messages, animated: animated),
+      );
     }
   }
 
   @override
-  Future<void> insertAllMessages(List<Message> messages, {int? index}) async {
+  Future<void> insertAllMessages(
+    List<Message> messages, {
+    int? index,
+    bool animated = true,
+  }) async {
     if (messages.isEmpty) return;
 
     // Index is ignored because Hive does not maintain order
@@ -88,7 +105,7 @@ class HiveChatController
     );
     _invalidateCache();
     _operationsController.add(
-      ChatOperation.insertAll(messages, originalLength),
+      ChatOperation.insertAll(messages, originalLength, animated: animated),
     );
   }
 

examples/flyer_chat/lib/main.dart

@@ -12,7 +12,8 @@ import 'api_get_initial_messages.dart';
 import 'basic.dart';
 import 'gemini.dart';
 import 'local.dart';
-import 'pagination.dart';
+import 'pagination_newer.dart';
+import 'pagination_older.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
@@ -268,11 +269,22 @@ class _FlyerChatHomePageState extends State<FlyerChatHomePage> {
               ),
               ElevatedButton(
                 onPressed: () {
-                  Navigator.of(
-                    context,
-                  ).push(MaterialPageRoute(builder: (context) => Pagination()));
+                  Navigator.of(context).push(
+                    MaterialPageRoute(
+                      builder: (context) => const PaginationOlder(),
+                    ),
+                  );
                 },
-                child: const Text('pagination'),
+                child: const Text('pagination (get older)'),
+              ),
+              const SizedBox(height: 8),
+              ElevatedButton(
+                onPressed: () => Navigator.of(context).push(
+                  MaterialPageRoute(
+                    builder: (context) => const PaginationNewer(),
+                  ),
+                ),
+                child: const Text('pagination (get newer)'),
               ),
               const SizedBox(height: 8),
               ElevatedButton(

examples/flyer_chat/lib/pagination_mock_database.dart

@@ -0,0 +1,69 @@
+import 'dart:math';
+
+import 'package:flutter_chat_core/flutter_chat_core.dart';
+
+const _mockDatabaseDelay = Duration(milliseconds: 500);
+
+class MockDatabase {
+  static final _messages = List.generate(100, (i) {
+    final random = Random();
+    final numLines = random.nextInt(4) + 1;
+    final text = List.generate(
+      numLines,
+      (lineIndex) => 'Message ${i + 1} - Line ${lineIndex + 1}',
+    ).join('\n');
+    return Message.text(
+      id: (i + 1).toString(),
+      authorId: 'me',
+      createdAt: DateTime.fromMillisecondsSinceEpoch(
+        1736893310000 - ((100 - i) * 1000),
+        isUtc: true,
+      ),
+      text: text,
+    );
+  });
+
+  static final List<Message> initialNewerMessages = _messages
+      .take(20)
+      .toList()
+      .reversed
+      .toList();
+
+  static final List<Message> initialOlderMessages = _messages
+      .skip(80)
+      .take(20)
+      .toList()
+      .reversed
+      .toList();
+
+  static Future<List<Message>> getOlderMessages({
+    required int limit,
+    MessageID? lastMessageId,
+  }) async {
+    await Future.delayed(_mockDatabaseDelay);
+
+    final start = lastMessageId == null
+        ? 20
+        : _messages.indexWhere((m) => m.id == lastMessageId) + 1;
+
+    if (start >= _messages.length) return [];
+
+    return _messages.skip(start).take(limit).toList().reversed.toList();
+  }
+
+  static Future<List<Message>> getNewerMessages({
+    required int limit,
+    MessageID? newestMessageId,
+  }) async {
+    await Future.delayed(_mockDatabaseDelay);
+    final end = newestMessageId == null
+        ? 80
+        : _messages.indexWhere((m) => m.id == newestMessageId);
+
+    if (end <= 0) return [];
+
+    final start = (end - limit).clamp(0, end);
+
+    return _messages.sublist(start, end).reversed.toList();
+  }
+}

examples/flyer_chat/lib/pagination_newer.dart

@@ -0,0 +1,85 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_chat_core/flutter_chat_core.dart';
+import 'package:flutter_chat_ui/flutter_chat_ui.dart';
+
+import 'pagination_mock_database.dart';
+
+class PaginationNewer extends StatefulWidget {
+  const PaginationNewer({super.key});
+
+  @override
+  PaginationNewerState createState() => PaginationNewerState();
+}
+
+class PaginationNewerState extends State<PaginationNewer> {
+  final _chatController = InMemoryChatController(
+    messages: List.from(MockDatabase.initialOlderMessages),
+  );
+  final _currentUser = const User(id: 'me');
+
+  bool _hasMore = true;
+  bool _isLoading = false;
+
+  @override
+  void dispose() {
+    _chatController.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+
+    return Scaffold(
+      appBar: AppBar(title: const Text('Pagination (get newer)')),
+      body: Chat(
+        builders: Builders(
+          chatAnimatedListBuilder: (context, itemBuilder) {
+            return ChatAnimatedList(
+              itemBuilder: itemBuilder,
+              onStartReached: _loadNewerMessages,
+              initialScrollToEndMode: InitialScrollToEndMode.none,
+            );
+          },
+        ),
+        chatController: _chatController,
+        currentUserId: _currentUser.id,
+        resolveUser: (id) => Future.value(switch (id) {
+          'me' => _currentUser,
+          _ => null,
+        }),
+        theme: ChatTheme.fromThemeData(theme),
+      ),
+    );
+  }
+
+  Future<void> _loadNewerMessages() async {
+    if (!_hasMore || _isLoading) return;
+
+    _isLoading = true;
+
+    // The visually bottommost message is the last in our data list.
+    final newestMessageId = _chatController.messages.last.id;
+    final messages = await MockDatabase.getNewerMessages(
+      limit: 20,
+      newestMessageId: newestMessageId,
+    );
+
+    if (messages.isEmpty) {
+      _hasMore = false;
+    } else {
+      // Append newer messages to the visual bottom of the list.
+      await _chatController.insertAllMessages(
+        messages,
+        index: _chatController.messages.length,
+        // Important: we don't want to animate the insertion of the messages
+        // because pagination logic relies on messages to be inserted instantly.
+        // There is no need for animation anyway as all newer messages are out of
+        // visible range.
+        animated: false,
+      );
+    }
+
+    _isLoading = false;
+  }
+}