mobile-ai-agents 1.0.23

package/agents/flutter/bloc-feature-builder/example-output.md

@@ -0,0 +1,838 @@
+# Example Output — Flutter BLoC Feature Builder
+
+Generated from [`example-input.md`](example-input.md).
+
+---
+
+## File: domain/entities/product.dart
+
+```dart
+import 'package:equatable/equatable.dart';
+import 'package:meta/meta.dart';
+
+@immutable
+class Product extends Equatable {
+  const Product({
+    required this.id,
+    required this.name,
+    required this.price,
+    required this.imageUrl,
+    required this.rating,
+    required this.category,
+  });
+
+  final String id;
+  final String name;
+  final double price;
+  final String imageUrl;
+  final double rating;
+  final String category;
+
+  @override
+  List<Object?> get props => [id, name, price, imageUrl, rating, category];
+}
+```
+
+---
+
+## File: domain/repositories/product_catalog_repository.dart
+
+```dart
+import 'package:dartz/dartz.dart';
+import '../entities/product.dart';
+import '../failures/failure.dart';
+
+abstract class ProductCatalogRepository {
+  Future<Either<Failure, ProductPage>> getProducts({
+    String? category,
+    required int page,
+    required int limit,
+  });
+}
+
+/// Value object returned by getProducts.
+class ProductPage {
+  const ProductPage({
+    required this.products,
+    required this.total,
+    required this.currentPage,
+    required this.hasMore,
+  });
+
+  final List<Product> products;
+  final int total;
+  final int currentPage;
+  final bool hasMore;
+}
+```
+
+---
+
+## File: domain/failures/failure.dart
+
+```dart
+abstract class Failure {
+  const Failure();
+}
+
+class ServerFailure extends Failure {
+  const ServerFailure(this.message);
+  final String message;
+}
+
+class NetworkFailure extends Failure {
+  const NetworkFailure();
+}
+
+class CacheFailure extends Failure {
+  const CacheFailure();
+}
+```
+
+---
+
+## File: domain/usecases/get_products_usecase.dart
+
+```dart
+import 'package:dartz/dartz.dart';
+import '../entities/product.dart';
+import '../failures/failure.dart';
+import '../repositories/product_catalog_repository.dart';
+
+class GetProductsParams {
+  const GetProductsParams({
+    this.category,
+    required this.page,
+    this.limit = 20,
+  });
+
+  final String? category;
+  final int page;
+  final int limit;
+}
+
+class GetProductsUseCase {
+  const GetProductsUseCase(this.repository);
+
+  final ProductCatalogRepository repository;
+
+  Future<Either<Failure, ProductPage>> call(GetProductsParams params) =>
+      repository.getProducts(
+        category: params.category,
+        page: params.page,
+        limit: params.limit,
+      );
+}
+```
+
+---
+
+## File: data/models/product_model.dart
+
+```dart
+import '../../domain/entities/product.dart';
+
+class ProductModel extends Product {
+  const ProductModel({
+    required super.id,
+    required super.name,
+    required super.price,
+    required super.imageUrl,
+    required super.rating,
+    required super.category,
+  });
+
+  factory ProductModel.fromJson(Map<String, dynamic> json) => ProductModel(
+        id:       json['id'] as String,
+        name:     json['name'] as String,
+        price:    (json['price'] as num).toDouble(),
+        imageUrl: json['imageUrl'] as String,
+        rating:   (json['rating'] as num).toDouble(),
+        category: json['category'] as String,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'id':       id,
+        'name':     name,
+        'price':    price,
+        'imageUrl': imageUrl,
+        'rating':   rating,
+        'category': category,
+      };
+
+  // Converts to the pure domain entity.
+  Product toEntity() => Product(
+        id:       id,
+        name:     name,
+        price:    price,
+        imageUrl: imageUrl,
+        rating:   rating,
+        category: category,
+      );
+}
+
+class ProductPageModel {
+  const ProductPageModel({
+    required this.products,
+    required this.total,
+    required this.currentPage,
+    required this.hasMore,
+  });
+
+  final List<ProductModel> products;
+  final int total;
+  final int currentPage;
+  final bool hasMore;
+
+  factory ProductPageModel.fromJson(Map<String, dynamic> json) {
+    final data = json['data'] as List<dynamic>;
+    final meta = json['meta'] as Map<String, dynamic>;
+    return ProductPageModel(
+      products:    data.map((e) => ProductModel.fromJson(e as Map<String, dynamic>)).toList(),
+      total:       meta['total'] as int,
+      currentPage: meta['page'] as int,
+      hasMore:     meta['hasMore'] as bool,
+    );
+  }
+}
+```
+
+---
+
+## File: data/datasources/product_catalog_remote_datasource.dart
+
+```dart
+import 'package:dio/dio.dart';
+import '../models/product_model.dart';
+import '../../domain/usecases/get_products_usecase.dart';
+
+class ServerException implements Exception {
+  const ServerException(this.message);
+  final String message;
+}
+
+class ProductCatalogRemoteDataSource {
+  const ProductCatalogRemoteDataSource(this.dio);
+
+  final Dio dio;
+
+  Future<ProductPageModel> getProducts(GetProductsParams params) async {
+    try {
+      final queryParams = <String, dynamic>{
+        'page':  params.page,
+        'limit': params.limit,
+      };
+      if (params.category != null) {
+        queryParams['category'] = params.category;
+      }
+
+      final response = await dio.get<Map<String, dynamic>>(
+        '/v1/products',
+        queryParameters: queryParams,
+      );
+
+      if (response.data == null) {
+        throw const ServerException('Empty response body');
+      }
+
+      return ProductPageModel.fromJson(response.data!);
+    } on DioException catch (e) {
+      final message = (e.response?.data as Map<String, dynamic>?)?['message'] as String?
+          ?? e.message
+          ?? 'Request failed';
+      throw ServerException(message);
+    }
+  }
+}
+```
+
+---
+
+## File: data/repositories/product_catalog_repository_impl.dart
+
+```dart
+import 'dart:io';
+import 'package:dartz/dartz.dart';
+import '../../domain/entities/product.dart';
+import '../../domain/failures/failure.dart';
+import '../../domain/repositories/product_catalog_repository.dart';
+import '../../domain/usecases/get_products_usecase.dart';
+import '../datasources/product_catalog_remote_datasource.dart';
+
+class ProductCatalogRepositoryImpl implements ProductCatalogRepository {
+  const ProductCatalogRepositoryImpl(this.remoteDataSource);
+
+  final ProductCatalogRemoteDataSource remoteDataSource;
+
+  @override
+  Future<Either<Failure, ProductPage>> getProducts({
+    String? category,
+    required int page,
+    required int limit,
+  }) async {
+    try {
+      final pageModel = await remoteDataSource.getProducts(
+        GetProductsParams(category: category, page: page, limit: limit),
+      );
+      return Right(ProductPage(
+        products:    pageModel.products.map((m) => m.toEntity()).toList(),
+        total:       pageModel.total,
+        currentPage: pageModel.currentPage,
+        hasMore:     pageModel.hasMore,
+      ));
+    } on ServerException catch (e) {
+      return Left(ServerFailure(e.message));
+    } on SocketException {
+      return const Left(NetworkFailure());
+    }
+  }
+}
+```
+
+---
+
+## File: presentation/cubit/product_catalog_state.dart
+
+```dart
+import 'package:equatable/equatable.dart';
+import '../../domain/entities/product.dart';
+
+sealed class ProductCatalogState extends Equatable {
+  const ProductCatalogState();
+
+  @override
+  List<Object?> get props => [];
+}
+
+final class ProductCatalogInitial extends ProductCatalogState {
+  const ProductCatalogInitial();
+}
+
+final class ProductCatalogLoading extends ProductCatalogState {
+  const ProductCatalogLoading();
+}
+
+/// Emitted while more pages are being fetched (pagination).
+/// The existing [products] list is still shown.
+final class ProductCatalogLoadingMore extends ProductCatalogState {
+  const ProductCatalogLoadingMore({
+    required this.products,
+    required this.selectedCategory,
+  });
+
+  final List<Product> products;
+  final String? selectedCategory;
+
+  @override
+  List<Object?> get props => [products, selectedCategory];
+}
+
+final class ProductCatalogLoaded extends ProductCatalogState {
+  const ProductCatalogLoaded({
+    required this.products,
+    required this.selectedCategory,
+    required this.currentPage,
+    required this.hasMore,
+  });
+
+  final List<Product> products;
+  final String? selectedCategory;
+  final int currentPage;
+  final bool hasMore;
+
+  ProductCatalogLoaded copyWith({
+    List<Product>? products,
+    String? selectedCategory,
+    int? currentPage,
+    bool? hasMore,
+  }) =>
+      ProductCatalogLoaded(
+        products:         products ?? this.products,
+        selectedCategory: selectedCategory ?? this.selectedCategory,
+        currentPage:      currentPage ?? this.currentPage,
+        hasMore:          hasMore ?? this.hasMore,
+      );
+
+  @override
+  List<Object?> get props => [products, selectedCategory, currentPage, hasMore];
+}
+
+final class ProductCatalogEmpty extends ProductCatalogState {
+  const ProductCatalogEmpty({this.category});
+  final String? category;
+
+  @override
+  List<Object?> get props => [category];
+}
+
+final class ProductCatalogError extends ProductCatalogState {
+  const ProductCatalogError(this.message);
+  final String message;
+
+  @override
+  List<Object?> get props => [message];
+}
+```
+
+---
+
+## File: presentation/cubit/product_catalog_cubit.dart
+
+```dart
+import 'package:flutter_bloc/flutter_bloc.dart';
+import '../../domain/entities/product.dart';
+import '../../domain/failures/failure.dart';
+import '../../domain/usecases/get_products_usecase.dart';
+import 'product_catalog_state.dart';
+
+class ProductCatalogCubit extends Cubit<ProductCatalogState> {
+  ProductCatalogCubit(this._getProducts) : super(const ProductCatalogInitial());
+
+  final GetProductsUseCase _getProducts;
+
+  static const int _pageSize = 20;
+
+  Future<void> loadProducts({String? category}) async {
+    emit(const ProductCatalogLoading());
+    final result = await _getProducts(
+      GetProductsParams(category: category, page: 1, limit: _pageSize),
+    );
+    result.fold(
+      (failure) => emit(ProductCatalogError(_mapFailure(failure))),
+      (page) => page.products.isEmpty
+          ? emit(ProductCatalogEmpty(category: category))
+          : emit(ProductCatalogLoaded(
+              products:         page.products,
+              selectedCategory: category,
+              currentPage:      1,
+              hasMore:          page.hasMore,
+            )),
+    );
+  }
+
+  Future<void> loadMore() async {
+    final current = state;
+    if (current is! ProductCatalogLoaded || !current.hasMore) return;
+
+    emit(ProductCatalogLoadingMore(
+      products:         current.products,
+      selectedCategory: current.selectedCategory,
+    ));
+
+    final result = await _getProducts(
+      GetProductsParams(
+        category: current.selectedCategory,
+        page:     current.currentPage + 1,
+        limit:    _pageSize,
+      ),
+    );
+
+    result.fold(
+      // On load-more failure, restore the previous loaded state without losing existing items.
+      (failure) => emit(current),
+      (page) => emit(current.copyWith(
+        products:    List.of(current.products)..addAll(page.products),
+        currentPage: page.currentPage,
+        hasMore:     page.hasMore,
+      )),
+    );
+  }
+
+  Future<void> refresh() => loadProducts(
+        category: state is ProductCatalogLoaded
+            ? (state as ProductCatalogLoaded).selectedCategory
+            : null,
+      );
+
+  Future<void> filterByCategory(String? category) => loadProducts(category: category);
+
+  String _mapFailure(Failure failure) => switch (failure) {
+        ServerFailure f => f.message,
+        NetworkFailure _ => 'No internet connection. Check your network and try again.',
+        CacheFailure _  => 'Local data error. Please try again.',
+        _ => 'An unexpected error occurred.',
+      };
+}
+```
+
+---
+
+## File: presentation/pages/product_catalog_page.dart
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_bloc/flutter_bloc.dart';
+import '../cubit/product_catalog_cubit.dart';
+import '../cubit/product_catalog_state.dart';
+import '../widgets/product_card.dart';
+import '../widgets/category_filter_chips.dart';
+
+class ProductCatalogPage extends StatefulWidget {
+  const ProductCatalogPage({super.key});
+
+  @override
+  State<ProductCatalogPage> createState() => _ProductCatalogPageState();
+}
+
+class _ProductCatalogPageState extends State<ProductCatalogPage> {
+  final _scrollController = ScrollController();
+
+  @override
+  void initState() {
+    super.initState();
+    context.read<ProductCatalogCubit>().loadProducts();
+    _scrollController.addListener(_onScroll);
+  }
+
+  @override
+  void dispose() {
+    _scrollController
+      ..removeListener(_onScroll)
+      ..dispose();
+    super.dispose();
+  }
+
+  void _onScroll() {
+    if (_scrollController.position.pixels >=
+        _scrollController.position.maxScrollExtent - 200) {
+      context.read<ProductCatalogCubit>().loadMore();
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Products'),
+        centerTitle: true,
+      ),
+      body: Column(
+        children: [
+          // Category filter chips
+          BlocBuilder<ProductCatalogCubit, ProductCatalogState>(
+            buildWhen: (prev, curr) =>
+                curr is ProductCatalogLoaded || curr is ProductCatalogLoading,
+            builder: (context, state) {
+              final selected = state is ProductCatalogLoaded
+                  ? state.selectedCategory
+                  : null;
+              return CategoryFilterChips(
+                selected: selected,
+                onSelected: context.read<ProductCatalogCubit>().filterByCategory,
+              );
+            },
+          ),
+          // Main content
+          Expanded(
+            child: BlocBuilder<ProductCatalogCubit, ProductCatalogState>(
+              builder: (context, state) => switch (state) {
+                ProductCatalogInitial() || ProductCatalogLoading() =>
+                  const Center(child: CircularProgressIndicator()),
+
+                ProductCatalogEmpty(:final category) => _EmptyView(
+                    category:   category,
+                    onRefresh: context.read<ProductCatalogCubit>().refresh,
+                  ),
+
+                ProductCatalogError(:final message) => _ErrorView(
+                    message: message,
+                    onRetry: context.read<ProductCatalogCubit>().refresh,
+                  ),
+
+                ProductCatalogLoaded(:final products, :final hasMore) ||
+                ProductCatalogLoadingMore(:final products) => RefreshIndicator(
+                    onRefresh: context.read<ProductCatalogCubit>().refresh,
+                    child: GridView.builder(
+                      controller: _scrollController,
+                      padding: const EdgeInsets.all(12),
+                      gridDelegate:
+                          const SliverGridDelegateWithFixedCrossAxisCount(
+                        crossAxisCount: 2,
+                        crossAxisSpacing: 12,
+                        mainAxisSpacing: 12,
+                        childAspectRatio: 0.75,
+                      ),
+                      itemCount: products.length + (state is ProductCatalogLoadingMore ? 1 : 0),
+                      itemBuilder: (context, index) {
+                        if (index >= products.length) {
+                          return const Center(child: CircularProgressIndicator());
+                        }
+                        final product = products[index];
+                        return ProductCard(
+                          key: ValueKey(product.id),
+                          product: product,
+                          onTap: () =>
+                              Navigator.of(context).pushNamed('/product/${product.id}'),
+                        );
+                      },
+                    ),
+                  ),
+
+                _ => const SizedBox.shrink(),
+              },
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+class _EmptyView extends StatelessWidget {
+  const _EmptyView({required this.onRefresh, this.category});
+  final String? category;
+  final VoidCallback onRefresh;
+
+  @override
+  Widget build(BuildContext context) {
+    final message = category != null
+        ? 'No products found in "$category"'
+        : 'No products found';
+    return Center(
+      child: Column(
+        mainAxisAlignment: MainAxisAlignment.center,
+        children: [
+          const Icon(Icons.inventory_2_outlined, size: 72),
+          const SizedBox(height: 16),
+          Text(message, style: Theme.of(context).textTheme.titleMedium),
+          const SizedBox(height: 24),
+          FilledTonalButton(onPressed: onRefresh, child: const Text('Refresh')),
+        ],
+      ),
+    );
+  }
+}
+
+class _ErrorView extends StatelessWidget {
+  const _ErrorView({required this.message, required this.onRetry});
+  final String message;
+  final VoidCallback onRetry;
+
+  @override
+  Widget build(BuildContext context) {
+    return Center(
+      child: Padding(
+        padding: const EdgeInsets.all(24),
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            const Icon(Icons.error_outline, size: 48),
+            const SizedBox(height: 16),
+            Text('Failed to load products',
+                style: Theme.of(context).textTheme.titleMedium),
+            const SizedBox(height: 8),
+            Text(message,
+                style: Theme.of(context).textTheme.bodySmall,
+                textAlign: TextAlign.center),
+            const SizedBox(height: 24),
+            FilledButton(onPressed: onRetry, child: const Text('Retry')),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+---
+
+## File: presentation/widgets/product_card.dart
+
+```dart
+import 'package:cached_network_image/cached_network_image.dart';
+import 'package:flutter/material.dart';
+import '../../domain/entities/product.dart';
+
+class ProductCard extends StatelessWidget {
+  const ProductCard({super.key, required this.product, required this.onTap});
+
+  final Product product;
+  final VoidCallback onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    return Card(
+      clipBehavior: Clip.antiAlias,
+      child: InkWell(
+        onTap: onTap,
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Expanded(
+              child: CachedNetworkImage(
+                imageUrl: product.imageUrl,
+                fit: BoxFit.cover,
+                width: double.infinity,
+                placeholder: (_, __) =>
+                    const ColoredBox(color: Color(0xFFE0E0E0)),
+                errorWidget: (_, __, ___) =>
+                    const Icon(Icons.broken_image_outlined),
+              ),
+            ),
+            Padding(
+              padding: const EdgeInsets.all(8),
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  Text(
+                    product.name,
+                    style: Theme.of(context).textTheme.bodyMedium,
+                    maxLines: 2,
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                  const SizedBox(height: 4),
+                  Text(
+                    '\$${product.price.toStringAsFixed(2)}',
+                    style: Theme.of(context)
+                        .textTheme
+                        .titleSmall
+                        ?.copyWith(color: Theme.of(context).colorScheme.primary),
+                  ),
+                  const SizedBox(height: 4),
+                  Row(
+                    children: [
+                      const Icon(Icons.star_rounded, size: 14, color: Color(0xFFFFC107)),
+                      const SizedBox(width: 2),
+                      Text(
+                        product.rating.toStringAsFixed(1),
+                        style: Theme.of(context).textTheme.bodySmall,
+                      ),
+                    ],
+                  ),
+                ],
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+---
+
+## File: test/product_catalog_cubit_test.dart (stub)
+
+```dart
+import 'package:bloc_test/bloc_test.dart';
+import 'package:dartz/dartz.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+
+// Replace with your actual import paths
+import '../lib/domain/entities/product.dart';
+import '../lib/domain/failures/failure.dart';
+import '../lib/domain/repositories/product_catalog_repository.dart';
+import '../lib/domain/usecases/get_products_usecase.dart';
+import '../lib/presentation/cubit/product_catalog_cubit.dart';
+import '../lib/presentation/cubit/product_catalog_state.dart';
+
+class MockGetProductsUseCase extends Mock implements GetProductsUseCase {}
+
+void main() {
+  late MockGetProductsUseCase mockUseCase;
+  late ProductCatalogCubit cubit;
+
+  const testProducts = [
+    Product(id: '1', name: 'Widget A', price: 9.99, imageUrl: '', rating: 4.2, category: 'tools'),
+    Product(id: '2', name: 'Widget B', price: 14.99, imageUrl: '', rating: 3.8, category: 'tools'),
+  ];
+
+  setUp(() {
+    mockUseCase = MockGetProductsUseCase();
+    cubit = ProductCatalogCubit(mockUseCase);
+  });
+
+  tearDown(() => cubit.close());
+
+  group('loadProducts', () {
+    blocTest<ProductCatalogCubit, ProductCatalogState>(
+      'emits [Loading, Loaded] when products are returned',
+      build: () {
+        when(() => mockUseCase(any())).thenAnswer((_) async => Right(ProductPage(
+              products: testProducts, total: 2, currentPage: 1, hasMore: false)));
+        return cubit;
+      },
+      act: (c) => c.loadProducts(),
+      expect: () => [
+        isA<ProductCatalogLoading>(),
+        isA<ProductCatalogLoaded>().having((s) => s.products.length, 'length', 2),
+      ],
+    );
+
+    blocTest<ProductCatalogCubit, ProductCatalogState>(
+      'emits [Loading, Empty] when API returns empty list',
+      build: () {
+        when(() => mockUseCase(any())).thenAnswer((_) async => Right(ProductPage(
+              products: [], total: 0, currentPage: 1, hasMore: false)));
+        return cubit;
+      },
+      act: (c) => c.loadProducts(),
+      expect: () => [isA<ProductCatalogLoading>(), isA<ProductCatalogEmpty>()],
+    );
+
+    blocTest<ProductCatalogCubit, ProductCatalogState>(
+      'emits [Loading, Error] on NetworkFailure',
+      build: () {
+        when(() => mockUseCase(any()))
+            .thenAnswer((_) async => const Left(NetworkFailure()));
+        return cubit;
+      },
+      act: (c) => c.loadProducts(),
+      expect: () => [
+        isA<ProductCatalogLoading>(),
+        isA<ProductCatalogError>()
+            .having((s) => s.message, 'message', contains('internet')),
+      ],
+    );
+  });
+}
+```
+
+---
+
+## Dependency Injection (get_it)
+
+```dart
+// injection_container.dart — add these registrations
+
+void _registerProductCatalog(GetIt sl) {
+  // Data sources
+  sl.registerLazySingleton<ProductCatalogRemoteDataSource>(
+    () => ProductCatalogRemoteDataSource(sl<Dio>()),
+  );
+
+  // Repositories
+  sl.registerLazySingleton<ProductCatalogRepository>(
+    () => ProductCatalogRepositoryImpl(sl<ProductCatalogRemoteDataSource>()),
+  );
+
+  // Use cases
+  sl.registerLazySingleton(
+    () => GetProductsUseCase(sl<ProductCatalogRepository>()),
+  );
+
+  // Cubit — registerFactory so each page gets a fresh instance
+  sl.registerFactory(
+    () => ProductCatalogCubit(sl<GetProductsUseCase>()),
+  );
+}
+```
+
+---
+
+## pubspec.yaml additions
+
+```yaml
+dependencies:
+  flutter_bloc: ^8.1.6
+  equatable: ^2.0.5
+  dartz: ^0.10.1
+  dio: ^5.7.0
+  cached_network_image: ^3.4.1
+
+dev_dependencies:
+  bloc_test: ^9.1.7
+  mocktail: ^1.0.4
+```