Add pagination to the toolkit

Author: NRijnberg

lib/dcc_toolkit.dart

@@ -7,6 +7,10 @@ export 'common/extensions/text_theme.dart';
 export 'common/result/result.dart';
 export 'common/type_defs.dart';
 export 'logger/bolt_logger.dart';
+export 'pagination/paginated_scroll_view.dart';
+export 'pagination/pagination_interface.dart';
+export 'pagination/pagination_mixin.dart';
+export 'pagination/pagination_state.dart';
 export 'style/style.dart';
 export 'test_util/devices_sizes.dart';
 export 'test_util/presentation_event_catcher.dart';

lib/pagination/paginated_scroll_view.dart

@@ -0,0 +1,77 @@
+import 'package:dcc_toolkit/dcc_toolkit.dart';
+import 'package:flutter/material.dart';
+
+/// A widget that displays a list of items with pagination.
+///
+/// This widget is a [CustomScrollView] that displays a paginated list of items.
+/// It uses a [PaginationState] to manage the behavior of the widget.
+/// It also uses a [NotificationListener] to listen for scroll events and load more items when the user scrolls to the bottom of the list.
+class PaginatedScrollView<T> extends StatelessWidget {
+  /// Creates a new [PaginatedScrollView].
+  const PaginatedScrollView({
+    required this.state,
+    required this.itemBuilder,
+    this.onLoadMore,
+    this.topWidget,
+    this.bottomWidget,
+    super.key,
+  });
+
+  /// The state of the pagination.
+  final PaginationState<T> state;
+
+  /// The builder for the items.
+  final Widget Function(BuildContext, T) itemBuilder;
+
+  /// The function to call when the user scrolls to the bottom of the list, to load more items.
+  final void Function()? onLoadMore;
+
+  /// Optional widget to display at the top of the list.
+  final Widget? topWidget;
+
+  /// Optional widget to display at the bottom of the list.
+  final Widget? bottomWidget;
+
+  int get _itemCount => state.items.length;
+
+  T _fetchItem(int index) {
+    return state.items[index];
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return NotificationListener<ScrollNotification>(
+      onNotification:
+          onLoadMore != null
+              ? (notification) {
+                final metrics = notification.metrics;
+                if (metrics.extentAfter == metrics.minScrollExtent) {
+                  // We don't trigger loading if no next page is available or while we are already fetching more
+                  if (state.hasNextPage && !state.isLoading) {
+                    onLoadMore?.call();
+                    return true;
+                  }
+                }
+                return false;
+              }
+              : null,
+      child: CustomScrollView(
+        physics: const AlwaysScrollableScrollPhysics(),
+        slivers: [
+          if (topWidget != null) SliverToBoxAdapter(child: topWidget),
+          SliverList.builder(
+            itemCount: _itemCount,
+            itemBuilder: (context, index) => itemBuilder(context, _fetchItem(index)),
+          ),
+          if (state.hasNextPage)
+            const SliverToBoxAdapter(
+              child: Padding(padding: EdgeInsets.all(Sizes.m), child: Center(child: CircularProgressIndicator())),
+            ),
+          if (bottomWidget != null) SliverToBoxAdapter(child: bottomWidget),
+          //Bottom insets to be able to scroll the entire content above the FloatingActionButton
+          const SliverPadding(padding: Paddings.vertical48),
+        ],
+      ),
+    );
+  }
+}

lib/pagination/pagination_interface.dart

@@ -0,0 +1,7 @@
+import 'package:dcc_toolkit/pagination/pagination_state.dart';
+
+/// Interface for pagination which is used on your bloc state.
+abstract interface class PaginationInterface<T> {
+  /// The current pagination state.
+  PaginationState<T> get paginationState;
+}

lib/pagination/pagination_mixin.dart

@@ -0,0 +1,55 @@
+import 'package:dcc_toolkit/pagination/pagination_interface.dart';
+import 'package:dcc_toolkit/pagination/pagination_state.dart';
+import 'package:flutter_bloc/flutter_bloc.dart';
+
+/// Mixin for pagination.
+///
+/// This mixin is used to handle pagination in a bloc.
+/// It provides a method to fetch the items for a given page and a method to initialize the pagination state.
+/// It also provides a method to load the next page.
+///
+/// Example:
+/// ```dart
+/// class MyBloc extends Bloc<MyEvent, MyState> with PaginationMixin<MyItem, MyState> {
+///   @override
+///   Future<List<MyItem>?> fetchPageItems(int page, String? searchQuery) async {
+///     // Fetch items logic
+///   }
+///
+///   @override
+///   Future<void> initializeState({String? searchQuery}) async {
+///     // Initialize state logic
+///   }
+/// 
+///   @override
+///   Future<void> loadNextPage(void Function(PaginationState<T>) emitState) async {
+///     // Load next page logic
+///   }
+/// }
+/// ```
+mixin PaginationMixin<T, S extends PaginationInterface<T>> on Cubit<S> {
+  /// Fetches the items for the given page
+  Future<List<T>?> fetchPageItems({required int page, String? searchQuery});
+
+  /// Initializes the pagination state
+  Future<void> initializeState({String? searchQuery});
+
+  /// Loads the next page
+  Future<void> loadNextPage(void Function(PaginationState<T>) emitState) async {
+    final paginationState = state.paginationState;
+    if (paginationState.currentPage < paginationState.lastPage) {
+      emitState(paginationState.copyWith(isLoading: true));
+      final nextPage = paginationState.currentPage + 1;
+      final nextItems = await fetchPageItems(page: nextPage, searchQuery: paginationState.searchQuery);
+      if (nextItems?.isNotEmpty ?? false) {
+        emitState(
+          paginationState.copyWith(
+            items: [...paginationState.items, ...nextItems!],
+            currentPage: nextPage,
+            isLoading: false,
+          ),
+        );
+      }
+    }
+  }
+}

lib/pagination/pagination_state.dart

@@ -0,0 +1,64 @@
+/// State for pagination.
+class PaginationState<T> {
+  /// Creates a new [PaginationState] with the given values.
+  PaginationState({
+    this.items = const [],
+    this.currentPage = 1,
+    this.lastPage = 1,
+    this.isLoading = false,
+    this.loadingInitialPage = true,
+    this.hasError = false,
+    this.total = 0,
+    this.searchQuery,
+  });
+
+  /// All items fetched so far for the loaded pages.
+  final List<T> items;
+
+  /// The current page in the pagination process.
+  final int currentPage;
+
+  /// The last page in the pagination process.
+  final int lastPage;
+
+  /// Whether the current page is being loaded.
+  final bool isLoading;
+
+  /// Whether the initial page is being loaded.
+  final bool loadingInitialPage;
+
+  /// Whether there is an error loading the current page.
+  final bool hasError;
+
+  /// The total number of items.
+  final int total;
+
+  /// The search query to filter the items.
+  final String? searchQuery;
+
+  /// Checks if there is a next page to load for the current [PaginationState].
+  bool get hasNextPage => currentPage < lastPage;
+
+  /// Copies the current state with the given values.
+  PaginationState<T> copyWith({
+    List<T>? items,
+    int? currentPage,
+    int? lastPage,
+    bool? isLoading,
+    bool? loadingInitialPage,
+    bool? hasError,
+    int? total,
+    String? searchQuery,
+  }) {
+    return PaginationState<T>(
+      items: items ?? this.items,
+      currentPage: currentPage ?? this.currentPage,
+      lastPage: lastPage ?? this.lastPage,
+      isLoading: isLoading ?? this.isLoading,
+      loadingInitialPage: loadingInitialPage ?? this.loadingInitialPage,
+      hasError: hasError ?? this.hasError,
+      total: total ?? this.total,
+      searchQuery: searchQuery ?? this.searchQuery,
+    );
+  }
+}