feat: implement countries filter bloc

- Fetches countries for filtering
- Implements pagination
- Handles loading and error states

Author: fulleni

lib/headlines-feed/bloc/countries_filter_bloc.dart

@@ -0,0 +1,132 @@
+import 'dart:async';
+
+import 'package:bloc/bloc.dart';
+import 'package:bloc_concurrency/bloc_concurrency.dart'; // For transformers
+import 'package:equatable/equatable.dart';
+import 'package:ht_countries_client/ht_countries_client.dart'; // For Country model and exceptions
+import 'package:ht_countries_repository/ht_countries_repository.dart';
+import 'package:ht_shared/ht_shared.dart'; // For PaginatedResponse
+
+part 'countries_filter_event.dart';
+part 'countries_filter_state.dart';
+
+/// {@template countries_filter_bloc}
+/// Manages the state for fetching and displaying countries for filtering.
+///
+/// Handles initial fetching and pagination of countries using the
+/// provided [HtCountriesRepository].
+/// {@endtemplate}
+class CountriesFilterBloc extends Bloc<CountriesFilterEvent, CountriesFilterState> {
+  /// {@macro countries_filter_bloc}
+  ///
+  /// Requires a [HtCountriesRepository] to interact with the data layer.
+  CountriesFilterBloc({required HtCountriesRepository countriesRepository})
+      : _countriesRepository = countriesRepository,
+        super(const CountriesFilterState()) {
+    on<CountriesFilterRequested>(
+      _onCountriesFilterRequested,
+      transformer: restartable(), // Only process the latest request
+    );
+    on<CountriesFilterLoadMoreRequested>(
+      _onCountriesFilterLoadMoreRequested,
+      transformer: droppable(), // Ignore new requests while one is processing
+    );
+  }
+
+  final HtCountriesRepository _countriesRepository;
+
+  /// Number of countries to fetch per page.
+  static const _countriesLimit = 20;
+
+  /// Handles the initial request to fetch countries.
+  Future<void> _onCountriesFilterRequested(
+    CountriesFilterRequested event,
+    Emitter<CountriesFilterState> emit,
+  ) async {
+    // Prevent fetching if already loading or successful
+    if (state.status == CountriesFilterStatus.loading ||
+        state.status == CountriesFilterStatus.success) {
+      return;
+    }
+
+    emit(state.copyWith(status: CountriesFilterStatus.loading));
+
+    try {
+      // Note: Repository uses 'cursor' parameter name here
+      final response = await _countriesRepository.fetchCountries(
+        limit: _countriesLimit,
+        cursor: null, // Explicitly null for initial fetch
+      );
+      emit(
+        state.copyWith(
+          status: CountriesFilterStatus.success,
+          countries: response.items,
+          hasMore: response.hasMore,
+          cursor: response.cursor,
+          clearError: true, // Clear any previous error
+        ),
+      );
+    } on CountryFetchFailure catch (e) {
+      emit(
+        state.copyWith(
+          status: CountriesFilterStatus.failure,
+          error: e,
+        ),
+      );
+    } catch (e) {
+      // Catch unexpected errors
+      emit(
+        state.copyWith(
+          status: CountriesFilterStatus.failure,
+          error: e,
+        ),
+      );
+    }
+  }
+
+  /// Handles the request to load more countries for pagination.
+  Future<void> _onCountriesFilterLoadMoreRequested(
+    CountriesFilterLoadMoreRequested event,
+    Emitter<CountriesFilterState> emit,
+  ) async {
+    // Only proceed if currently successful and has more items
+    if (state.status != CountriesFilterStatus.success || !state.hasMore) {
+      return;
+    }
+
+    emit(state.copyWith(status: CountriesFilterStatus.loadingMore));
+
+    try {
+      // Note: Repository uses 'cursor' parameter name here
+      final response = await _countriesRepository.fetchCountries(
+        limit: _countriesLimit,
+        cursor: state.cursor, // Use the cursor from the current state
+      );
+      emit(
+        state.copyWith(
+          status: CountriesFilterStatus.success,
+          // Append new countries to the existing list
+          countries: List.of(state.countries)..addAll(response.items),
+          hasMore: response.hasMore,
+          cursor: response.cursor,
+        ),
+      );
+    } on CountryFetchFailure catch (e) {
+      // Keep existing data but indicate failure
+      emit(
+        state.copyWith(
+          status: CountriesFilterStatus.failure,
+          error: e,
+        ),
+      );
+    } catch (e) {
+      // Catch unexpected errors
+      emit(
+        state.copyWith(
+          status: CountriesFilterStatus.failure,
+          error: e,
+        ),
+      );
+    }
+  }
+}

lib/headlines-feed/bloc/countries_filter_event.dart

@@ -0,0 +1,22 @@
+part of 'countries_filter_bloc.dart';
+
+/// {@template countries_filter_event}
+/// Base class for events related to fetching and managing country filters.
+/// {@endtemplate}
+sealed class CountriesFilterEvent extends Equatable {
+  /// {@macro countries_filter_event}
+  const CountriesFilterEvent();
+
+  @override
+  List<Object> get props => [];
+}
+
+/// {@template countries_filter_requested}
+/// Event triggered to request the initial list of countries.
+/// {@endtemplate}
+final class CountriesFilterRequested extends CountriesFilterEvent {}
+
+/// {@template countries_filter_load_more_requested}
+/// Event triggered to request the next page of countries for pagination.
+/// {@endtemplate}
+final class CountriesFilterLoadMoreRequested extends CountriesFilterEvent {}

lib/headlines-feed/bloc/countries_filter_state.dart

@@ -0,0 +1,78 @@
+part of 'countries_filter_bloc.dart';
+
+// Import removed, will be added to the main bloc file.
+
+/// Enum representing the different statuses of the country filter data fetching.
+enum CountriesFilterStatus {
+  /// Initial state, no data loaded yet.
+  initial,
+
+  /// Currently fetching the first page of countries.
+  loading,
+
+  /// Successfully loaded countries. May be loading more in the background.
+  success,
+
+  /// An error occurred while fetching countries.
+  failure,
+
+  /// Loading more countries for pagination (infinity scroll).
+  loadingMore,
+}
+
+/// {@template countries_filter_state}
+/// Represents the state for the country filter feature.
+///
+/// Contains the list of fetched countries, pagination information,
+/// loading/error status.
+/// {@endtemplate}
+final class CountriesFilterState extends Equatable {
+  /// {@macro countries_filter_state}
+  const CountriesFilterState({
+    this.status = CountriesFilterStatus.initial,
+    this.countries = const [],
+    this.hasMore = true,
+    this.cursor,
+    this.error,
+  });
+
+  /// The current status of fetching countries.
+  final CountriesFilterStatus status;
+
+  /// The list of [Country] objects fetched so far.
+  final List<Country> countries;
+
+  /// Flag indicating if there are more countries available to fetch.
+  final bool hasMore;
+
+  /// The cursor string to fetch the next page of countries.
+  /// This is typically the ID of the last fetched country.
+  final String? cursor;
+
+  /// An optional error object if the status is [CountriesFilterStatus.failure].
+  final Object? error;
+
+  /// Creates a copy of this state with the given fields replaced.
+  CountriesFilterState copyWith({
+    CountriesFilterStatus? status,
+    List<Country>? countries,
+    bool? hasMore,
+    String? cursor,
+    Object? error,
+    bool clearError = false, // Flag to explicitly clear the error
+    bool clearCursor = false, // Flag to explicitly clear the cursor
+  }) {
+    return CountriesFilterState(
+      status: status ?? this.status,
+      countries: countries ?? this.countries,
+      hasMore: hasMore ?? this.hasMore,
+      // Allow explicitly setting cursor to null or clearing it
+      cursor: clearCursor ? null : (cursor ?? this.cursor),
+      // Clear error if requested, otherwise keep existing or use new one
+      error: clearError ? null : error ?? this.error,
+    );
+  }
+
+  @override
+  List<Object?> get props => [status, countries, hasMore, cursor, error];
+}