feat: Implement HeadlinesFeedBloc

- Added HeadlinesFeedBloc
- Manages headlines feed state
- Fetches headlines from repository

Author: fulleni

analysis_options.yaml

@@ -1,3 +1,6 @@
+analyzer:
+  errors:
+    avoid_catches_without_on_clauses: ignore
 include: package:very_good_analysis/analysis_options.7.0.0.yaml
 linter:
   rules:

lib/headlines-feed/bloc/headlines_feed_bloc.dart

@@ -0,0 +1,109 @@
+import 'package:bloc/bloc.dart';
+import 'package:bloc_concurrency/bloc_concurrency.dart';
+import 'package:equatable/equatable.dart';
+import 'package:ht_headlines_repository/ht_headlines_repository.dart';
+
+part 'headlines_feed_event.dart';
+part 'headlines_feed_state.dart';
+
+/// {@template headlines_feed_bloc}
+/// A Bloc that manages the headlines feed.
+///
+/// It handles fetching and refreshing headlines data using the
+/// [HtHeadlinesRepository].
+/// {@endtemplate}
+class HeadlinesFeedBloc extends Bloc<HeadlinesFeedEvent, HeadlinesFeedState> {
+  /// {@macro headlines_feed_bloc}
+  HeadlinesFeedBloc({required HtHeadlinesRepository headlinesRepository})
+      : _headlinesRepository = headlinesRepository,
+        super(HeadlinesFeedInitial()) {
+    on<HeadlinesFeedFetchRequested>(
+      _onHeadlinesFeedFetchRequested,
+      transformer: sequential(),
+    );
+    on<HeadlinesFeedRefreshRequested>(
+      _onHeadlinesFeedRefreshRequested,
+      transformer: restartable(),
+    );
+  }
+
+  final HtHeadlinesRepository _headlinesRepository;
+
+  /// Handles [HeadlinesFeedFetchRequested] events.
+  ///
+  /// Fetches headlines from the repository and emits
+  /// [HeadlinesFeedLoading], and either [HeadlinesFeedLoaded] or
+  /// [HeadlinesFeedError] states.
+  Future<void> _onHeadlinesFeedFetchRequested(
+    HeadlinesFeedFetchRequested event,
+    Emitter<HeadlinesFeedState> emit,
+  ) async {
+    if (state is HeadlinesFeedLoaded &&
+        (state as HeadlinesFeedLoaded).hasMore) {
+      final currentState = state as HeadlinesFeedLoaded;
+      emit(HeadlinesFeedLoading());
+      try {
+        final response = await _headlinesRepository.getHeadlines(
+          limit: 20,
+          startAfterId: currentState.cursor,
+        );
+        emit(
+          HeadlinesFeedLoaded(
+            headlines: currentState.headlines + response.items,
+            hasMore: response.hasMore,
+            cursor: response.cursor,
+          ),
+        );
+      } on HeadlinesFetchException catch (e) {
+        emit(HeadlinesFeedError(message: e.message));
+      } catch (_) {
+        emit(const HeadlinesFeedError(message: 'An unexpected error occurred'));
+      }
+    } else {
+      emit(HeadlinesFeedLoading());
+      try {
+        final response = await _headlinesRepository.getHeadlines(limit: 20);
+        emit(
+          HeadlinesFeedLoaded(
+            headlines: response.items,
+            hasMore: response.hasMore,
+            cursor: response.cursor,
+          ),
+        );
+      } on HeadlinesFetchException catch (e) {
+        emit(HeadlinesFeedError(message: e.message));
+      } catch (_) {
+        emit(const HeadlinesFeedError(message: 'An unexpected error occurred'));
+      }
+    }
+  }
+
+  /// Handles [HeadlinesFeedRefreshRequested] events.
+  ///
+  /// Fetches headlines from the repository and emits
+  /// [HeadlinesFeedLoading], and either [HeadlinesFeedLoaded] or
+  /// [HeadlinesFeedError] states.
+  ///
+  /// Uses `restartable` transformer to ensure that only the latest
+  /// refresh request is processed.
+  Future<void> _onHeadlinesFeedRefreshRequested(
+    HeadlinesFeedRefreshRequested event,
+    Emitter<HeadlinesFeedState> emit,
+  ) async {
+    emit(HeadlinesFeedLoading());
+    try {
+      final response = await _headlinesRepository.getHeadlines(limit: 20);
+      emit(
+        HeadlinesFeedLoaded(
+          headlines: response.items,
+          hasMore: response.hasMore,
+          cursor: response.cursor,
+        ),
+      );
+    } on HeadlinesFetchException catch (e) {
+      emit(HeadlinesFeedError(message: e.message));
+    } catch (_) {
+      emit(const HeadlinesFeedError(message: 'An unexpected error occurred'));
+    }
+  }
+}

lib/headlines-feed/bloc/headlines_feed_event.dart

@@ -0,0 +1,22 @@
+part of 'headlines_feed_bloc.dart';
+
+/// {@template headlines_feed_event}
+/// Base class for all events related to the headlines feed.
+/// {@endtemplate}
+sealed class HeadlinesFeedEvent extends Equatable {
+  /// {@macro headlines_feed_event}
+  const HeadlinesFeedEvent();
+
+  @override
+  List<Object> get props => [];
+}
+
+/// {@template headlines_feed_fetch_requested}
+/// Event triggered when the headlines feed needs to be fetched.
+/// {@endtemplate}
+final class HeadlinesFeedFetchRequested extends HeadlinesFeedEvent {}
+
+/// {@template headlines_feed_refresh_requested}
+/// Event triggered when the headlines feed needs to be refreshed.
+/// {@endtemplate}
+final class HeadlinesFeedRefreshRequested extends HeadlinesFeedEvent {}

lib/headlines-feed/bloc/headlines_feed_state.dart

@@ -0,0 +1,60 @@
+part of 'headlines_feed_bloc.dart';
+
+/// {@template headlines_feed_state}
+/// Base class for all states related to the headlines feed.
+/// {@endtemplate}
+sealed class HeadlinesFeedState extends Equatable {
+  /// {@macro headlines_feed_state}
+  const HeadlinesFeedState();
+
+  @override
+  List<Object> get props => [];
+}
+
+/// {@template headlines_feed_initial}
+/// The initial state of the headlines feed.
+/// {@endtemplate}
+final class HeadlinesFeedInitial extends HeadlinesFeedState {}
+
+/// {@template headlines_feed_loading}
+/// State indicating that the headlines feed is being loaded.
+/// {@endtemplate}
+final class HeadlinesFeedLoading extends HeadlinesFeedState {}
+
+/// {@template headlines_feed_loaded}
+/// State indicating that the headlines feed has been loaded successfully.
+/// {@endtemplate}
+final class HeadlinesFeedLoaded extends HeadlinesFeedState {
+  /// {@macro headlines_feed_loaded}
+  const HeadlinesFeedLoaded({
+    required this.headlines,
+    required this.hasMore,
+    this.cursor,
+  });
+
+  /// The headlines data.
+  final List<Headline> headlines;
+
+  /// Indicates if there are more headlines.
+  final bool hasMore;
+
+  /// The cursor for the next page.
+  final String? cursor;
+
+  @override
+  List<Object> get props => [headlines, hasMore, cursor ?? ''];
+}
+
+/// {@template headlines_feed_error}
+/// State indicating that an error occurred while loading the headlines feed.
+/// {@endtemplate}
+final class HeadlinesFeedError extends HeadlinesFeedState {
+  /// {@macro headlines_feed_error}
+  const HeadlinesFeedError({required this.message});
+
+  /// The error message.
+  final String message;
+
+  @override
+  List<Object> get props => [message];
+}

pubspec.lock

@@ -41,6 +41,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "9.0.0"
+  bloc_concurrency:
+    dependency: "direct main"
+    description:
+      name: bloc_concurrency
+      sha256: "86b7b17a0a78f77fca0d7c030632b59b593b22acea2d96972588f40d4ef53a94"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.3.0"
   bloc_test:
     dependency: "direct dev"
     description:
@@ -598,6 +606,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.1.4"
+  stream_transform:
+    dependency: transitive
+    description:
+      name: stream_transform
+      sha256: ad47125e588cfd37a9a7f86c7d6356dde8dfe89d071d293f80ca9e9273a33871
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.1"
   string_scanner:
     dependency: transitive
     description:

pubspec.yaml

@@ -1,13 +1,14 @@
 name: ht_main
 description: main headlines toolkit mobile app.
-version: 0.5.5
+version: 0.6.5
 publish_to: none
-repository: https://github.com/Headlines-Toolkit/ht-main
+repository: https://github.com/headlines-toolkit/ht-main
 environment:
   sdk: ^3.5.0
 
 dependencies:
   bloc: ^9.0.0
+  bloc_concurrency: ^0.3.0
   equatable: ^2.0.7
   flex_color_scheme: ^8.1.1
   flutter: