feat(dashboard): introduces the business logic layer for the dashboard feature.

It includes:

- DashboardState: Defines the possible states for the dashboard UI (initial, loading, success, failure) and holds the - DashboardSummary data.

- DashboardEvent: Defines the events that can be dispatched to the BLoC, starting with DashboardSummaryLoaded.

- DashboardBloc: Manages the dashboard's state by fetching summary data from the HtDataRepository<DashboardSummary> and emitting the appropriate states.
dashboard.dart: A barrel file for easy importing of BLoC components.

The new DashboardBloc has also been registered in app.dart using BlocProvider, making it available throughout the widget tree for the upcoming UI implementation.

Author: fulleni

lib/app/view/app.dart

@@ -11,6 +11,7 @@ import 'package:ht_dashboard/app/config/app_environment.dart';
 import 'package:ht_dashboard/app_configuration/bloc/app_configuration_bloc.dart';
 import 'package:ht_dashboard/authentication/bloc/authentication_bloc.dart';
 import 'package:ht_dashboard/content_management/bloc/content_management_bloc.dart';
+import 'package:ht_dashboard/dashboard/bloc/dashboard_bloc.dart';
 import 'package:ht_dashboard/l10n/app_localizations.dart';
 import 'package:ht_dashboard/router/router.dart';
 // Import for app_theme.dart
@@ -102,6 +103,12 @@ class App extends StatelessWidget {
               sourcesRepository: context.read<HtDataRepository<Source>>(),
             ),
           ),
+          BlocProvider(
+            create: (context) => DashboardBloc(
+              dashboardSummaryRepository: context
+                  .read<HtDataRepository<DashboardSummary>>(),
+            ),
+          ),
         ],
         child: _AppView(
           htAuthenticationRepository: _htAuthenticationRepository,

lib/dashboard/bloc/dashboard_bloc.dart

@@ -0,0 +1,52 @@
+import 'package:bloc/bloc.dart';
+import 'package:equatable/equatable.dart';
+import 'package:ht_data_repository/ht_data_repository.dart';
+import 'package:ht_shared/ht_shared.dart';
+
+part 'dashboard_event.dart';
+part 'dashboard_state.dart';
+
+/// A BLoC to manage the state of the dashboard.
+class DashboardBloc extends Bloc<DashboardEvent, DashboardState> {
+  /// {@macro dashboard_bloc}
+  DashboardBloc({
+    required HtDataRepository<DashboardSummary> dashboardSummaryRepository,
+  }) : _dashboardSummaryRepository = dashboardSummaryRepository,
+       super(const DashboardState()) {
+    on<DashboardSummaryLoaded>(_onDashboardSummaryLoaded);
+  }
+
+  final HtDataRepository<DashboardSummary> _dashboardSummaryRepository;
+
+  Future<void> _onDashboardSummaryLoaded(
+    DashboardSummaryLoaded event,
+    Emitter<DashboardState> emit,
+  ) async {
+    emit(state.copyWith(status: DashboardStatus.loading));
+    try {
+      // The dashboard summary is a singleton-like resource, fetched by a
+      // well-known ID.
+      final summary = await _dashboardSummaryRepository.read(id: 'summary');
+      emit(
+        state.copyWith(
+          status: DashboardStatus.success,
+          summary: summary,
+        ),
+      );
+    } on HtHttpException catch (e) {
+      emit(
+        state.copyWith(
+          status: DashboardStatus.failure,
+          errorMessage: e.message,
+        ),
+      );
+    } catch (e) {
+      emit(
+        state.copyWith(
+          status: DashboardStatus.failure,
+          errorMessage: 'An unknown error occurred: $e',
+        ),
+      );
+    }
+  }
+}

lib/dashboard/bloc/dashboard_event.dart

@@ -0,0 +1,12 @@
+part of 'dashboard_bloc.dart';
+
+/// Base class for dashboard events.
+sealed class DashboardEvent extends Equatable {
+  const DashboardEvent();
+
+  @override
+  List<Object> get props => [];
+}
+
+/// Event to load the dashboard summary data.
+final class DashboardSummaryLoaded extends DashboardEvent {}

lib/dashboard/bloc/dashboard_state.dart

@@ -0,0 +1,44 @@
+part of 'dashboard_bloc.dart';
+
+/// Represents the status of the dashboard data loading.
+enum DashboardStatus {
+  /// Initial state.
+  initial,
+
+  /// Data is being loaded.
+  loading,
+
+  /// Data has been successfully loaded.
+  success,
+
+  /// An error occurred while loading data.
+  failure,
+}
+
+/// The state for the [DashboardBloc].
+final class DashboardState extends Equatable {
+  const DashboardState({
+    this.status = DashboardStatus.initial,
+    this.summary,
+    this.errorMessage,
+  });
+
+  final DashboardStatus status;
+  final DashboardSummary? summary;
+  final String? errorMessage;
+
+  DashboardState copyWith({
+    DashboardStatus? status,
+    DashboardSummary? summary,
+    String? errorMessage,
+  }) {
+    return DashboardState(
+      status: status ?? this.status,
+      summary: summary ?? this.summary,
+      errorMessage: errorMessage ?? this.errorMessage,
+    );
+  }
+
+  @override
+  List<Object?> get props => [status, summary, errorMessage];
+}