BLoC & Clean Architecture Learning Guide

┌─────────────────────────────────────────────────┐
│ PRESENTATION LAYER (UI)                         │
│ - StudyHomePage (the screen users see)          │
│ - StudyBloc (state management)                  │
│ - StudyItemView (UI model)                      │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│ DOMAIN LAYER (Business Logic)                   │
│ - Study (entity/model)                          │
│ - StudyRepository (interface)                   │
│ - GetStudies (usecase/business logic)           │
└─────────────────────────────────────────────────┘
                        ↓
┌──────────────────────────────────────────────────┐
│ DATA LAYER (Data Sources)                        │
│ - StudyLocalDataSource (where data comes from)   │
│ - StudyRepositoryImpl (repository implementation)│
└──────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│ EXTERNAL (Databases, APIs, Files)               │
│ - Local database, REST API, JSON files, etc.    │
└─────────────────────────────────────────────────┘

1. StudyHomePage.initState()
   └─→ Sends StudyLoadRequested event to StudyBloc

2. StudyBloc receives the event
   └─→ Emits StudyLoading state (UI shows spinner)
   └─→ Calls GetStudies.call() from DOMAIN layer

3. GetStudies.call() (Domain Logic)
   └─→ Calls StudyRepository.getStudies() from DATA layer

4. StudyRepositoryImpl (Data Layer)
   └─→ Calls StudyLocalDataSource.fetch()
   └─→ Converts raw Map data → Study entities
   └─→ Returns List<Study>

5. GetStudies receives List<Study>
   └─→ Returns it to BLoC

6. StudyBloc transforms Study → StudyItemView
   └─→ Emits StudyLoaded state with transformed data

7. BlocBuilder in StudyHomePage
   └─→ Detects state change
   └─→ Rebuilds UI with the new data
   └─→ Displays GridView of study cards

class StudyLoadRequested extends StudyEvent {
  const StudyLoadRequested();
}

class StudyLoaded extends StudyState {
  final List<StudyItemView> items;
  const StudyLoaded(this.items);
}

class StudyBloc extends Bloc<StudyEvent, StudyState> {
  Future<void> _onStudyLoadRequested(...) async {
    emit(const StudyLoading()); // Show spinner
    final studies = await _getStudies(); // Get data
    emit(StudyLoaded(items)); // Show data
  }
}

Create BLoC instance (in main.dart via BlocProvider)
         ↓
User interacts with UI
         ↓
Event is added to BLoC (context.read<StudyBloc>().add(...))
         ↓
BLoC listens for that event type
         ↓
BLoC's handler is called (e.g., _onStudyLoadRequested)
         ↓
BLoC emits states as it processes
         ↓
BlocBuilder listens to states
         ↓
UI rebuilds when state changes

// ❌ Bad (no DI)
class StudyBloc extends Bloc<StudyEvent, StudyState> {
  final GetStudies getStudies = GetStudies(...); // Creates its own
}

// ✅ Good (with DI)
class StudyBloc extends Bloc<StudyEvent, StudyState> {
  final GetStudies getStudies;
  StudyBloc(this.getStudies); // Receives it
}

StudyBloc createStudyBloc() {
  // Layer 1: DATA - Raw data source
  final dataSource = StudyLocalDataSource();

  // Layer 2: DATA - Repository implementation
  final repository = StudyRepositoryImpl(dataSource);

  // Layer 3: DOMAIN - Business logic
  final getStudies = GetStudies(repository);

  // Layer 4: PRESENTATION - State management
  final bloc = StudyBloc(getStudies);

  return bloc;
}

// In your test file
class FakeDataSource extends StudyLocalDataSource {
  @override
  Future<List<Map>> fetch() async {
    return [/* test data */]; // No real database!
  }
}

// Test the BLoC with fake data
final testBloc = StudyBloc(
  GetStudies(StudyRepositoryImpl(FakeDataSource()))
);

// Event handler - listens for events and processes them
Future<void> _onStudyLoadRequested(...) async {
  emit(const StudyLoading()); // Emit state
  try {
    final data = await _usecase(); // Call domain
    emit(StudyLoaded(data)); // Emit success
  } catch (e) {
    emit(StudyError(e.toString())); // Emit error
  }
}

// Trigger events in initState or callbacks
@override
void initState() {
  super.initState();
  context.read<StudyBloc>().add(const StudyLoadRequested());
}

// Listen to states and rebuild UI
BlocBuilder<StudyBloc, StudyState>(
  builder: (context, state) {
    if (state is StudyLoading) return Spinner();
    if (state is StudyLoaded) return GridView(...);
    if (state is StudyError) return ErrorWidget();
  }
)

┌─────────────────────────────────────┐
│   StudyHomePage (StatefulWidget)    │
│   - Uses BlocBuilder                │
│   - Listens to StudyBloc states     │
│   - Sends StudyLoadRequested event  │
└──────────────┬──────────────────────┘
               │ event
               ▼
┌──────────────────────────────┐
│   StudyBloc (Business Logic) │
│   - _onStudyLoadRequested()  │
│   - _toViewModel().          │
│   - Emits states             │
└──────────────┬───────────────┘
               │ calls
               ▼
┌──────────────────────────────┐
│   GetStudies (Domain Usecase)│
│   - call() method            │
│   - Pure business logic.     │
└──────────────┬───────────────┘
               │ calls
               ▼
┌──────────────────────────────┐
│   StudyRepository (Interface)│
│   - getStudies()             │
└──────────────┬───────────────┘
               │ implemented by
               ▼
┌──────────────────────────────┐
│   StudyRepositoryImpl (Data) │
│   - Transforms Map → Study.  │
└──────────────┬───────────────┘
               │ uses
               ▼
┌──────────────────────────────┐
│   StudyLocalDataSource (Data)│
│   - fetch() returns raw data │
└──────────────┬───────────────┘
               │ represents
               ▼
        [Hardcoded Data]
      (Database/API in real app)