@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/flutter/localization/references/REFERENCE.md

@@ -0,0 +1,48 @@
+# Localization Reference
+
+## Easy Localization Setup
+
+Basic implementation in `main.dart`.
+
+```dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await EasyLocalization.ensureInitialized();
+
+  runApp(
+    EasyLocalization(
+      supportedLocales: const [Locale('en'), Locale('vi')],
+      path: 'assets/translations', // <-- Path to translations
+      fallbackLocale: const Locale('en'),
+      child: const MyApp(),
+    ),
+  );
+}
+```
+
+## JSON Translation Format
+
+Default format for project assets.
+
+```json
+// en.json
+{
+  "app_title": "My App",
+  "welcome": "Welcome, {}!",
+  "items_count": {
+    "zero": "No items",
+    "one": "{} item",
+    "other": "{} items"
+  }
+}
+```
+
+## Google Sheets Integration
+
+Use `sheet_loader_localization` to fetch and generate localizations from Google Sheets.
+
+1. Add to `pubspec.yaml` under `dev_dependencies`.
+2. Configure sheets URL/ID in `pubspec.yaml` or separate config.
+3. Run `flutter pub run sheet_loader_localization:main`.
+
+See [Sheet Loader Example](sheet-loader.md).

package/rules/flutter/localization/references/sheet-loader.md

@@ -0,0 +1,33 @@
+# Google Sheets Localization Loader
+
+Automating translation updates from Google Sheets using `sheet_loader_localization`.
+
+## Configuration (`pubspec.yaml`)
+
+```yaml
+dev_dependencies:
+  sheet_loader_localization: ^0.1.0
+
+sheet_loader_localization:
+  # Google Sheet ID (find in the URL of your sheet)
+  doc_id: 'your_google_sheet_id_here'
+  sheet_id: '0' # Usually 0 for first sheet
+  output_path: 'assets/translations'
+  output_format: 'json' # Can be csv or json
+```
+
+## Typical Sheet Format ([example sheet](https://docs.google.com/spreadsheets/d/1v2Y3e0Uvn0JTwHvsduNT70u7Fy9TG43DIcZYJxPu1ZA/edit?gid=1013756643#gid=1013756643))
+
+| key            | en            | vi         |
+| :------------- | :------------ | :--------- |
+| welcome        | Welcome!      | Chào mừng! |
+| login.button   | Login         | Đăng nhập  |
+| errors.network | Network Error | Lỗi mạng   |
+
+## CLI Command
+
+Run this command to synchronize your local asset files with the Google Sheet:
+
+```bash
+flutter pub run sheet_loader_localization:main
+```

package/rules/flutter/navigator-v1-navigation/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: Flutter Navigator v1 (Imperative)
+description: Standard Flutter navigation using Navigator 1.0 (push/pop).
+metadata:
+  labels: [navigation, navigator, flutter-core]
+  triggers:
+    files: ['**/app.dart']
+    keywords: [Navigator, push, pop, MaterialPageRoute, onGenerateRoute]
+---
+
+# Navigator v1 Navigation
+
+## **Priority: P0 (CRITICAL)**
+
+Standard imperative navigation system built into Flutter using `Navigator` and `MaterialPageRoute`.
+
+## Implementation Guidelines
+
+- **Standard Push**: Use `Navigator.of(context).push(MaterialPageRoute(builder: (_) => Screen()))`.
+- **Named Routes**: Define `routes` map in `MaterialApp` or use `onGenerateRoute` for dynamic routing.
+- **Passing Arguments**:
+  - For named routes: Use `Navigator.pushNamed(context, '/path', arguments: data)`.
+  - For `onGenerateRoute`: Extract arguments using `settings.arguments`.
+- **Returning Data**: `final result = await Navigator.push(...)` and `Navigator.pop(context, data)`.
+- **Replacing Screens**: Use `pushReplacement` or `pushAndRemoveUntil` for auth/splash flows.
+
+## Code Example
+
+```dart
+// Basic Push
+Navigator.push(
+  context,
+  MaterialPageRoute(builder: (context) => const DetailScreen()),
+);
+
+// Named Routes Configuration
+MaterialApp(
+  initialRoute: '/',
+  onGenerateRoute: (settings) {
+    if (settings.name == '/details') {
+      final args = settings.arguments as Map;
+      return MaterialPageRoute(
+        builder: (context) => DetailScreen(id: args['id']),
+      );
+    }
+    return null;
+  },
+);
+
+// Navigation with Arguments
+Navigator.pushNamed(
+  context,
+  '/details',
+  arguments: {'id': 123},
+);
+```
+
+## Anti-Patterns
+
+- **Deep Nesting**: Avoid anonymous routes for complex apps; use `onGenerateRoute`.
+- **Manual String Paths**: Always use constants for route names.
+- **Context Leaks**: Ensure `BuildContext` is valid when calling `Navigator.of(context)`. Use `ScaffoldMessenger` or global keys if navigation is needed outside `build`.
+
+## Reference & Examples
+
+For centralized `onGenerateRoute` implementation:
+See [references/on-generate-route.md](references/on-generate-route.md).
+
+## Related Topics
+
+idiomatic-flutter | widgets

package/rules/flutter/navigator-v1-navigation/references/on-generate-route.md

@@ -0,0 +1,48 @@
+# Navigator v1: Centralized onGenerateRoute
+
+Using an abstract class for route names and a centralized router for navigation logic.
+
+```dart
+// route_names.dart
+abstract class Routes {
+  static const home = '/';
+  static const details = '/details';
+}
+
+// app_router.dart
+class AppRouter {
+  static Route<dynamic> onGenerateRoute(RouteSettings settings) {
+    switch (settings.name) {
+      case Routes.home:
+        return MaterialPageRoute(builder: (_) => const HomeScreen());
+
+      case Routes.details:
+        // Safe argument extraction
+        final args = settings.arguments;
+        if (args is int) {
+          return MaterialPageRoute(
+            builder: (_) => DetailScreen(id: args),
+          );
+        }
+        return _errorRoute();
+
+      default:
+        return _errorRoute();
+    }
+  }
+
+  static Route<dynamic> _errorRoute() {
+    return MaterialPageRoute(
+      builder: (_) => const Scaffold(body: Center(child: Text('Error'))),
+    );
+  }
+}
+
+// main.dart
+MaterialApp(
+  onGenerateRoute: AppRouter.onGenerateRoute,
+)
+
+// Usage
+Navigator.pushNamed(context, Routes.details, arguments: 42);
+```

package/rules/flutter/performance/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: Flutter Performance
+description: Optimization standards for rebuilds and memory.
+metadata:
+  labels: [performance]
+  triggers:
+    files: ['lib/presentation/**', 'pubspec.yaml']
+    keywords: [const, buildWhen, ListView.builder, Isolate, RepaintBoundary]
+---
+
+# Performance (P1)
+
+- **Rebuilds**: Use `const` widgets and `buildWhen` / `select` for granular updates.
+- **Lists**: Always use `ListView.builder` for item recycling.
+- **Heavy Tasks**: Use `compute()` or `Isolates` for parsing/logic.
+- **Repaints**: Use `RepaintBoundary` for complex animations. Use `debugRepaintRainbowEnabled` to debug.
+- **Images**: Use `CachedNetworkImage` + `memCacheWidth`. `precachePicture` for SVGs.
+
+```dart
+BlocBuilder<UserBloc, UserState>(
+  buildWhen: (p, c) => p.id != c.id,
+  builder: (context, state) => Text(state.name),
+)
+```

package/rules/flutter/retrofit-networking/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: Flutter Networking (Retrofit & Dio)
+description: HTTP networking standards using Dio and Retrofit with Auth interceptors.
+metadata:
+  labels: [networking, retrofit, dio]
+  triggers:
+    files: ['**/data_sources/**', '**/api/**']
+    keywords: [Retrofit, Dio, RestClient, GET, POST, Interceptor, refreshing]
+---
+
+# Retrofit & Dio Networking
+
+## **Priority: P0 (CRITICAL)**
+
+Type-safe REST API communication using `Dio` and `Retrofit`.
+
+## Structure
+
+```text
+infrastructure/
+├── data_sources/
+│   ├── remote/ # Retrofit abstract classes
+│   └── local/ # Cache/Storage
+└── network/
+    ├── dio_client.dart # Custom Dio setup
+    └── interceptors/ # Auth, Logging, Cache
+```
+
+## Implementation Guidelines
+
+- **Retrofit Clients**: Define abstract classes with `@RestApi()`. Use standard HTTP annotations (`@GET`, `@POST`).
+- **DTOs (Data Transfer Objects)**: Use `@freezed` and `json_serializable` for all response/request bodies.
+- **Mapping**: Data sources MUST map DTOs to Domain Entities (e.g., `userDto.toDomain()`).
+- **AuthInterceptor**: Logic for `Authorization: Bearer <token>` injection in `onRequest`.
+- **Token Refresh**: Handle `401 Unauthorized` in `onError` by locking Dio, refreshing, and retrying.
+- **Failures**: Map `DioException` to custom `Failure` objects (ServerFailure, NetworkFailure).
+
+## Anti-Patterns
+
+- **No Manual JSON Parsing**: Do not use `jsonDecode(response.body)`; use Retrofit's generated mappers.
+- **No Global Dio**: Do not use a static global Dio instance; use dependency injection.
+- **No Try-Catch in API**: Do not put `try-catch` inside the Retrofit interface methods.
+
+## Reference & Examples
+
+For RestClient definitions and Auth Interceptor implementation:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+feature-based-clean-architecture | error-handling

package/rules/flutter/retrofit-networking/references/REFERENCE.md

@@ -0,0 +1,19 @@
+# Retrofit & Dio Reference
+
+Standards for API communication and networking logic.
+
+## References
+
+- [**RestClient Setup**](client-definition.md) - Standard Retrofit interface examples.
+- [**Auth Interceptors**](auth-interceptor.md) - Handling Bearer tokens and Auth headers.
+- [**Token Refresh Logic**](token-refresh.md) - The 401 Lock-Refresh-Retry pattern.
+
+## **Quick Definition**
+
+```dart
+@RestApi()
+abstract class ApiClient {
+  @GET("/items")
+  Future<List<ItemDto>> getItems(@Query("limit") int limit);
+}
+```

package/rules/flutter/retrofit-networking/references/token-refresh.md

@@ -0,0 +1,40 @@
+# Token Refresh Pattern
+
+When a `401 Unauthorized` error occurs, the networking layer should handle the refresh cycle transparently.
+
+## **Implementation Flow (Dio Interceptor)**
+
+```dart
+class AuthInterceptor extends QueuedInterceptorsWrapper {
+  final Dio dio;
+  final SecureStorage storage;
+
+  AuthInterceptor(this.dio, this.storage);
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (err.response?.statusCode == 401) {
+      // 1. Refresh the token
+      final newToken = await _performRefresh();
+      
+      if (newToken != null) {
+        // 2. Retry the original request with new token
+        final options = err.requestOptions;
+        options.headers['Authorization'] = 'Bearer $newToken';
+        
+        final response = await dio.fetch(options);
+        return handler.resolve(response);
+      }
+    }
+    return handler.next(err);
+  }
+
+  Future<String?> _performRefresh() async {
+    // Logic to call refresh endpoint and update storage
+  }
+}
+```
+
+## **Why QueuedInterceptorsWrapper?**
+
+Using `QueuedInterceptorsWrapper` ensures that if multiple requests trigger a 401 at the same time, they are queued while the first one performs the token refresh, preventing multiple redundant refresh calls.

package/rules/flutter/riverpod-state-management/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: Flutter Riverpod State Management
+description: Reactive state management using Riverpod 2.0 with code generation.
+metadata:
+  labels: [state-management, riverpod, dependency-injection, reactive]
+  triggers:
+    files: ['**_provider.dart', '**_notifier.dart']
+    keywords: [riverpod, ProviderScope, ConsumerWidget, Notifier, AsyncValue, ref.watch, "@riverpod"]
+---
+
+# Riverpod State Management
+
+## **Priority: P0 (CRITICAL)**
+
+Type-safe, compile-time safe reactive state management using `riverpod` and `riverpod_generator`.
+
+## Structure
+
+```text
+lib/
+├── providers/ # Global providers and services
+└── features/
+    └── user/
+        ├── providers/ # Feature-specific providers
+        └── models/    # @freezed domain models
+```
+
+## Implementation Guidelines
+
+- **Generator First**: Use `@riverpod` annotations and `riverpod_generator`. Avoid manual `Provider` definitions.
+- **Immutability**: Maintain immutable states. Use `Freezed` for all state models.
+- **Provider Methods**:
+  - `ref.watch()`: Use inside `build()` to rebuild on changes.
+  - `ref.listen()`: Use for side-effects (navigation, dialogs).
+  - `ref.read()`: Use ONLY in callbacks (onPressed).
+- **Asynchronous Data**: Use `AsyncNotifier` for complex async logic. Access data via `.when()` or `AsyncValue` pattern-matching.
+- **Architecture**: Enforce 3-layer separation (Data, Domain, Presentation).
+- **Linting**: Enable `riverpod_lint` and `custom_lint` for dependency cycle detection.
+
+## Anti-Patterns
+
+- **Building Inside Providers**: Don't perform side-effects inside provider initialization.
+- **Context Access**: Never pass `BuildContext` into a Notifier/Provider.
+- **Dynamic Providers**: Avoid local provider instantiation; keep them global.
+
+## Reference & Examples
+
+For architecture details, best practices, and testing overrides:
+See [references/architecture.md](references/architecture.md), [references/best-practices.md](references/best-practices.md), and [references/testing.md](references/testing.md).
+
+## Related Topics
+
+feature-based-clean-architecture | dependency-injection | testing

package/rules/flutter/riverpod-state-management/references/architecture.md

@@ -0,0 +1,124 @@
+# Architecture & Layers
+
+## 1. Data Layer: Repository Interface & Providers
+
+Always separate interface from implementation to enable easy mocking.
+
+```dart
+// domain/repository/user_repository.dart
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../data/repository/api_user_repository.dart';
+import '../models/user.dart';
+
+part 'user_repository.g.dart';
+
+// 1. Define the Provider returning the INTERFACE
+@riverpod
+UserRepository userRepository(UserRepositoryRef ref) {
+  // Return the specific implementation here.
+  // Can be swapped for MockUserRepository based on environment flags.
+  return ApiUserRepository(ref.watch(apiClientProvider));
+}
+
+// 2. Define the Interface
+abstract interface class UserRepository {
+  Future<List<User>> getAllUsers();
+  Future<void> deleteUser(String id);
+}
+```
+
+```dart
+// data/repository/api_user_repository.dart
+class ApiUserRepository implements UserRepository {
+  final UserApiClient _client;
+
+  ApiUserRepository(this._client);
+
+  @override
+  Future<List<User>> getAllUsers() async {
+    return _client.fetchUsers();
+  }
+}
+```
+
+## 2. Presentation Layer: AsyncNotifier Controller
+
+Use `AsyncNotifier` (via `@riverpod` class) to handle loading/error/data states naturally.
+
+```dart
+// features/users/user_controller.dart
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../domain/repository/user_repository.dart';
+import '../../domain/models/user.dart';
+
+part 'user_controller.g.dart';
+
+@riverpod
+class UserController extends _$UserController {
+  @override
+  FutureOr<List<User>> build() async {
+    // 1. Fetch initial data
+    return ref.watch(userRepositoryProvider).getAllUsers();
+  }
+
+  // 2. Mutation Methods
+  Future<void> deleteUser(String id) async {
+    // Set loading state (optional, for optimisic UI usually prefer local)
+    // state = const AsyncLoading();
+
+    // Perform action
+    state = await AsyncValue.guard(() async {
+      await ref.read(userRepositoryProvider).deleteUser(id);
+      // Refresh logic:
+      // Option A: Refetch everything
+      return ref.refresh(userRepositoryProvider).getAllUsers();
+
+      // Option B: Optimistic Update (Better performance)
+      // final currentList = state.requireValue;
+      // return currentList.where((u) => u.id != id).toList();
+    });
+  }
+}
+```
+
+## 3. UI Layer: ConsumerWidget
+
+Handle all 3 states (`data`, `loading`, `error`) using `.when`.
+
+```dart
+// features/users/user_list_screen.dart
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+class UserListScreen extends ConsumerWidget {
+  const UserListScreen({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    // 1. Watch the Notifier Provider
+    final state = ref.watch(userControllerProvider);
+
+    return Scaffold(
+      body: state.when(
+        data: (users) => ListView.builder(
+          itemCount: users.length,
+          itemBuilder: (ctx, index) {
+            final user = users[index];
+            return ListTile(
+              title: Text(user.name),
+              // 2. Call mutation methods via .read()
+              trailing: IconButton(
+                icon: const Icon(Icons.delete),
+                onPressed: () {
+                  ref.read(userControllerProvider.notifier).deleteUser(user.id);
+                },
+              ),
+            );
+          },
+        ),
+        loading: () => const Center(child: CircularProgressIndicator()),
+        error: (err, st) => Center(child: Text('Error: $err')),
+      ),
+    );
+  }
+}
+```

package/rules/flutter/riverpod-state-management/references/best-practices.md

@@ -0,0 +1,89 @@
+# Best Practices & DCM Rules
+
+## Code Generation (`riverpod_generator`)
+
+Always use code generation. It prevents syntax errors and handles "family" parameters automatically.
+
+**❌ Bad (Legacy)**
+
+```dart
+final myProvider = Provider<String>((ref) => 'Hello'); // Manual typing, error prone
+```
+
+**✅ Good (Generated)**
+
+```dart
+@riverpod
+String my(MyRef ref) => 'Hello'; // Type-safe, auto-disposal by default
+```
+
+## Immutability & State Updates
+
+Riverpod relies on strict object equality (`==`) to detect changes.
+
+**❌ Bad (Mutation)**
+
+```dart
+state.add(newItem); // Same reference, listeners won't fire
+state = state;
+```
+
+**✅ Good (New Reference)**
+
+```dart
+state = [...state, newItem]; // New list, new reference
+```
+
+## DCM & Linter Rules (`riverpod_lint`)
+
+Enable strict rules in `analysis_options.yaml` via `custom_lint`.
+
+### 1. `avoid-ref-read-inside-build`
+
+**Rule**: Never use `ref.read` inside the `build()` method. It causes bugs where widgets don't update on change.
+**Correct**: Use `ref.watch`.
+
+### 2. `avoid-calling-notifier-members-inside-build`
+
+**Rule**: Do not trigger side effects (API calls, internal mutations) inside `build`.
+**Correct**: Use `build()` purely for initialization. Trigger actions via user interaction (onPressed) or `useEffect` (flutter_hooks).
+
+### 3. `dispose-provided-instances`
+
+**Rule**: If a provider creates a `ChangeNotifier` or stream controller, make sure it is disposed.
+**Correct**:
+
+```dart
+@riverpod
+StreamController myController(Ref ref) {
+  final controller = StreamController();
+  ref.onDispose(controller.close); // ✅ Register disposal
+  return controller;
+}
+```
+
+### 4. `use-ref-and-state-synchronously`
+
+**Rule**: Don't use `ref` or setter `state` after an `await` without checking if the provider is still active.
+**Context**: If a provider is disposed (e.g. user leaves screen) while an async task is running, setting state will throw.
+
+**✅ Good**:
+
+```dart
+final result = await repo.fetch();
+if (ref.context.mounted) { // Or simply rely on `AsyncValue.guard` which handles this somewhat safely
+   state = AsyncData(result);
+}
+```
+
+## `keepAlive` Strategy
+
+By default, auto-generated providers are `autoDispose`. This is good for memory but bad for caching.
+
+- **Use `keepAlive: true`** for global data (User Session, App Config).
+- **Use Default (`keepAlive: false`)** for screen-specific data (Product Details), so it clears to save memory when the screen is popped.
+
+```dart
+@Riverpod(keepAlive: true)
+class UserSession extends _$UserSession { ... }
+```

package/rules/flutter/riverpod-state-management/references/testing.md

@@ -0,0 +1,73 @@
+# Testing with Riverpod
+
+Riverpod is designed for testability. You do not need complex dependency injection containers; you simply "override" providers in the test scope.
+
+## Unit Testing (Notifiers)
+
+Test notifiers in isolation using a `ProviderContainer`.
+
+```dart
+test('increment adds 1 to state', () {
+  // 1. Create container
+  final container = ProviderContainer();
+  addTearDown(container.dispose);
+
+  // 2. Listen to provider (required to initialize it)
+  container.listen(counterProvider, (_, __) {});
+
+  // 3. Act
+  container.read(counterProvider.notifier).increment();
+
+  // 4. Assert
+  expect(container.read(counterProvider), 1);
+});
+```
+
+## Widget/Integration Testing (Overrides)
+
+When testing widgets, wrap them in a `ProviderScope` and override the repository providers with mocks.
+
+```dart
+testWidgets('shows loading then data', (tester) async {
+  final mockRepo = MockUserRepository();
+  when(() => mockRepo.getAllUsers()).thenAnswer((_) async => [User(id: 1, name: 'Bob')]);
+
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        // 🔑 Replace the REAL repository with the MOCK
+        userRepositoryProvider.overrideWithValue(mockRepo),
+      ],
+      child: const MaterialApp(home: UserListScreen()),
+    ),
+  );
+
+  // Assert Loading
+  expect(find.byType(CircularProgressIndicator), findsOneWidget);
+
+  // Assert Data
+  await tester.pumpAndSettle();
+  expect(find.text('Bob'), findsOneWidget);
+});
+```
+
+## Mocking `AsyncNotifiers`
+
+Sometimes you want to mock the _entire_ Controller/Notifier state, not just the repository.
+
+```dart
+// 1. Extend the generated class (or create a mock)
+class MockUserController extends AutoDisposeAsyncNotifier<List<User>>
+    implements UserController {
+  @override
+  FutureOr<List<User>> build() => [];
+}
+
+// 2. Override in ProviderScope
+ProviderScope(
+  overrides: [
+    userControllerProvider.overrideWith(() => MockUserController()),
+  ],
+  child: ...
+)
+```