@ngxtm/devkit 3.4.0 → 3.4.1

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

@@ -0,0 +1,76 @@
+---
+name: Flutter GetX State Management
+description: Simple and powerful reactive state management using GetX.
+metadata:
+  labels: [state-management, getx, controller, reactive]
+  triggers:
+    files: ['**_controller.dart', '**/bindings/*.dart']
+    keywords:
+      [GetxController, Obx, GetBuilder, .obs, Get.put, Get.find, Get.lazyPut]
+---
+
+# GetX State Management
+
+## **Priority: P0 (CRITICAL)**
+
+Reactive and lightweight state management separating business logic from UI using `GetX`.
+
+## Structure
+
+```text
+lib/app/modules/home/
+├── controllers/
+│   └── home_controller.dart
+├── bindings/
+│   └── home_binding.dart
+└── views/
+    └── home_view.dart
+```
+
+## Implementation Guidelines
+
+- **Controllers**: Extend `GetxController`. Store logic and state variables here.
+- **Reactivity**:
+  - Use `.obs` for observable variables (e.g., `final count = 0.obs;`).
+  - Wrap UI in `Obx(() => ...)` to listen for changes.
+  - For simple state, use `update()` in controller and `GetBuilder` in UI.
+- **Dependency Injection**:
+  - **Bindings**: Use `Bindings` class to decouple DI from UI.
+  - **Lazy Load**: Prefer `Get.lazyPut(() => Controller())` in Bindings.
+  - **Lifecycle**: Let GetX handle disposal. Avoid `permanent: true`.
+- **Hooks**: Use `onInit()`, `onReady()`, `onClose()` instead of `initState`/`dispose`.
+- **Architecture**: Use `get_cli` for modular MVVM (data, models, modules).
+
+## Anti-Patterns
+
+- **Ctx in Logic**: Pass no `BuildContext` to controllers.
+- **Inline DI**: Avoid `Get.put()` in widgets; use Bindings + `Get.find`.
+- **Fat Views**: Keep views pure UI; delegate all logic to controller.
+
+## Code Example
+
+```dart
+class UserController extends GetxController {
+  final name = "User".obs;
+  void updateName(String val) => name.value = val;
+}
+
+class UserView extends GetView<UserController> {
+  @override
+  Widget build(ctx) => Scaffold(
+    body: Obx(() => Text(controller.name.value)),
+    floatingActionButton: FloatingActionButton(
+      onPressed: () => controller.updateName("New"),
+    ),
+  );
+}
+```
+
+## Reference & Examples
+
+For DI Bindings and Reactive patterns:
+See [references/binding-example.md](references/binding-example.md) and [references/reactive-vs-simple.md](references/reactive-vs-simple.md).
+
+## Related Topics
+
+getx-navigation | feature-based-clean-architecture | dependency-injection

package/rules/flutter/getx-state-management/references/binding-example.md

@@ -0,0 +1,32 @@
+# GetX Binding Example
+
+Using Bindings ensures that dependencies are only in memory when the associated route is active.
+
+```dart
+// 1. Define the Binding
+class HomeBinding extends Bindings {
+  @override
+  void dependencies() {
+    // lazyPut only initializes the controller when it's first used (Get.find)
+    Get.lazyPut<HomeController>(() => HomeController());
+    Get.lazyPut<HomeRepository>(() => HomeRepositoryImpl());
+  }
+}
+
+// 2. Attach to Route
+GetPage(
+  name: '/home',
+  page: () => HomeView(),
+  binding: HomeBinding(),
+)
+
+// 3. Use in View via GetView (automatically finds the controller)
+class HomeView extends GetView<HomeController> {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Obx(() => Text(controller.title.value)),
+    );
+  }
+}
+```

package/rules/flutter/getx-state-management/references/reactive-vs-simple.md

@@ -0,0 +1,39 @@
+# Reactive vs. Simple State Management
+
+GetX provides two ways to manage state. Choose based on complexity and performance needs.
+
+## 1. Reactive (.obs + Obx)
+
+Best for: Highly interactive UIs, streams, and granular updates.
+
+```dart
+class UserController extends GetxController {
+  final name = "Guest".obs;
+  final age = 18.obs;
+
+  void updateName(String newName) => name.value = newName;
+}
+
+// UI
+Obx(() => Text(controller.name.value));
+```
+
+### 2. Simple state management
+
+Best for: Large objects, low-frequency updates, or reducing memory overhead of many streams.
+
+```dart
+class UserController extends GetxController {
+  String name = "Guest";
+
+  void updateName(String newName) {
+    name = newName;
+    update(); // Manually notify listeners
+  }
+}
+
+// UI
+GetBuilder<UserController>(
+  builder: (controller) => Text(controller.name),
+);
+```

package/rules/flutter/go-router-navigation/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: Flutter GoRouter Navigation
+description: Typed routes, route state, and redirection using go_router.
+metadata:
+  labels: [navigation, go-router, routing]
+  triggers:
+    files: ['**/router.dart', '**/app_router.dart']
+    keywords: [GoRouter, GoRoute, StatefulShellRoute, redirection, typed-routes]
+---
+
+# GoRouter Navigation
+
+## **Priority: P0 (CRITICAL)**
+
+Type-safe deep linking and routing system using `go_router` and `go_router_builder`.
+
+## Structure
+
+```text
+core/router/
+├── app_router.dart # Router configuration
+└── routes.dart # Typed route definitions (GoRouteData)
+```
+
+## Implementation Guidelines
+
+- **Typed Routes**: Always use `GoRouteData` from `go_router_builder`. Never use raw path strings.
+- **Root Router**: One global `GoRouter` instance registered in DI.
+- **Sub-Routes**: Nest related routes using `TypedGoRoute` and children lists.
+- **Redirection**: Handle Auth (Login check) in the `redirect` property of the `GoRouter` config.
+- **Parameters**: Use `@TypedGoRoute` to define paths with `:id` parameters.
+- **Transitions**: Define standard transitions (Fade, Slide) in `buildPage`.
+- **Navigation**: Use `MyRoute().go(context)` or `MyRoute().push(context)`.
+
+## Code
+
+```dart
+// Route Definition
+@TypedGoRoute<HomeRoute>(path: '/')
+class HomeRoute extends GoRouteData {
+  @override
+  Widget build(context, state) => const HomePage();
+}
+
+// Router Config
+final router = GoRouter(
+  routes: $appRoutes,
+  redirect: (context, state) {
+    if (notAuthenticated) return '/login';
+    return null;
+  },
+);
+```
+
+## Related Topics
+
+layer-based-clean-architecture | auto-route-navigation | security

package/rules/flutter/idiomatic-flutter/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: Idiomatic Flutter
+description: Modern layout and widget composition standards.
+metadata:
+  labels: [flutter, clean-code, widgets]
+  triggers:
+    files: ['lib/presentation/**/*.dart']
+    keywords: [context.mounted, SizedBox, Gap, composition, shrink]
+---
+
+# Idiomatic Flutter (P1)
+
+- **Async Gaps**: Check `if (context.mounted)` before using `BuildContext` after `await`.
+- **Composition**: Extract complex UI into small widgets. Avoid deep nesting or large helper methods.
+- **Layout**:
+  - Spacing: Use `Gap(n)` or `SizedBox` over `Padding` for simple gaps.
+  - Empty UI: Use `const SizedBox.shrink()`.
+  - Intrinsic: Avoid `IntrinsicWidth/Height`; use `Stack` + `FractionallySizedBox` for overlays.
+- **Optimization**: Use `ColoredBox`/`Padding`/`DecoratedBox` instead of `Container` when possible.
+- **Themes**: Use extensions for `Theme.of(context)` access.

package/rules/flutter/layer-based-clean-architecture/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: Flutter Layer-based Clean Architecture + DDD
+description: Standards for separation of concerns, layer dependency rules, and DDD in Flutter.
+metadata:
+  labels: [architecture, clean-architecture, layers, ddd]
+  triggers:
+    files: ['lib/domain/**', 'lib/infrastructure/**', 'lib/application/**']
+    keywords: [domain, infrastructure, application, presentation, layers, dto, mapper]
+---
+
+# Layer-Based Clean Architecture
+
+## **Priority: P0 (CRITICAL)**
+
+Standardized separation of concerns and dependency flow using DDD principles.
+
+## Structure
+
+```text
+lib/
+├── domain/ # Pure Dart: entities (@freezed), failures, repository interfaces
+├── infrastructure/ # Implementation: DTOs, data sources, mappers, repo impls
+├── application/ # Orchestration: BLoCs / Cubits
+└── presentation/ # UI: Screens, reusable components
+```
+
+## Implementation Guidelines
+
+- **Dependency Flow**: `Presentation -> Application -> Domain <- Infrastructure`. Dependencies point inward.
+- **Pure Domain**: No Flutter (Material/Store) or Infrastructure (Dio/Hive) dependencies in `Domain`.
+- **Functional Error Handling**: Repositories must return `Either<Failure, Success>`.
+- **Always Map**: Infrastructure must map DTOs to Domain Entities; do not leak DTOs to UI.
+- **Immutability**: Use `@freezed` for all entities and failures.
+- **Logic Placement**: No business logic in UI; widgets only display state and emit events.
+- **Inversion of Control**: Use `get_it` to inject repository implementations into BLoCs.
+
+## Anti-Patterns
+
+- **No DTOs in UI**: Never import a `.g.dart` or Data class directly in a Widget.
+- **No Material in Domain**: Do not import `package:flutter/material.dart` in the `domain` layer.
+- **No Shared Prefs in Repo**: Do not use `shared_preferences` directly in a Repository; use a Data Source.
+
+## Reference & Examples
+
+For full implementation templates and DTO-to-Domain mapping examples:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+feature-based-clean-architecture | bloc-state-management | dependency-injection | error-handling

package/rules/flutter/layer-based-clean-architecture/references/REFERENCE.md

@@ -0,0 +1,60 @@
+# Reference: Layer-based Clean Architecture Examples
+
+## **Full Layer Implementation**
+
+### 1. Domain Layer (Entity)
+
+```dart
+@freezed
+class Bank with _$Bank {
+  const factory Bank({
+    required String id,
+    required String name,
+    required String branchCode,
+  }) = _Bank;
+
+  factory Bank.fromJson(Map<String, dynamic> json) => _$BankFromJson(json);
+}
+```
+
+### 2. Infrastructure Layer (DTO & Mapper)
+
+```dart
+@freezed
+class BankDto with _$BankDto {
+  const factory BankDto({
+    @JsonKey(name: 'bank_id') required String id,
+    @JsonKey(name: 'bank_name') required String name,
+    @JsonKey(name: 'code') required String branchCode,
+  }) = _BankDto;
+
+  factory BankDto.fromJson(Map<String, dynamic> json) => _$BankDtoFromJson(json);
+
+  Bank toDomain() => Bank(
+    id: id,
+    name: name,
+    branchCode: branchCode,
+  );
+}
+```
+
+### 3. Application Layer (BLoC)
+
+```dart
+class BankBloc extends Bloc<BankEvent, BankState> {
+  final IBankRepository repository;
+
+  BankBloc(this.repository) : super(const BankState.initial()) {
+    on<_Fetch>(_onFetch);
+  }
+
+  Future<void> _onFetch(_Fetch event, Emitter<BankState> emit) async {
+    emit(const BankState.loading());
+    final failureOrBanks = await repository.fetchBanks();
+    emit(failureOrBanks.fold(
+      (f) => BankState.error(f.message),
+      (banks) => BankState.loaded(banks),
+    ));
+  }
+}
+```

package/rules/flutter/layer-based-clean-architecture/references/repository-mapping.md

@@ -0,0 +1,50 @@
+# Repositories & DTO Mapping Reference
+
+## **Data Transfer Object (DTO)**
+
+DTOs live in the **Infrastructure** layer and represent the raw JSON response.
+
+```dart
+@freezed
+class BankDto with _$BankDto {
+  const BankDto._();
+  
+  const factory BankDto({
+    @JsonKey(name: 'bank_id') required String id,
+    @JsonKey(name: 'bank_name') required String name,
+    @JsonKey(name: 'code') required String branchCode,
+  }) = _BankDto;
+
+  factory BankDto.fromJson(Map<String, dynamic> json) => _$BankDtoFromJson(json);
+
+  // Mapping to Domain Entity
+  Bank toDomain() => Bank(
+    id: id,
+    name: name,
+    branchCode: branchCode,
+  );
+}
+```
+
+## **Repository Implementation**
+
+The implementation handles the actual data fetching (Remote/Local) and mapping.
+
+```dart
+class BankRepository implements IBankRepository {
+  final BankRemoteDataSource remoteDataSource;
+
+  BankRepository(this.remoteDataSource);
+
+  @override
+  Future<Either<ApiFailure, List<Bank>>> fetchBanks() async {
+    try {
+      final dtoList = await remoteDataSource.getBanks();
+      // Perform the mapping here
+      return right(dtoList.map((dto) => dto.toDomain()).toList());
+    } catch (e) {
+      return left(ApiFailure.fromException(e));
+    }
+  }
+}
+```

package/rules/flutter/localization/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: Flutter Localization
+description: Standards for multi-language support using easy_localization and JSON/CSV assets.
+metadata:
+  labels: [localization, l10n, i18n, easy_localization]
+  triggers:
+    files: ['**/assets/translations/*.json', 'main.dart']
+    keywords:
+      [localization, multi-language, translation, tr(), easy_localization]
+---
+
+# Localization
+
+## **Priority: P1 (STANDARD)**
+
+Consistent multi-language support using `easy_localization`.
+
+## Structure
+
+```text
+assets/
+└── translations/
+    ├── en.json
+    └── vi.json
+```
+
+## Implementation Guidelines
+
+- **Bootstrap**: Wrap root with `EasyLocalization`. Always use `await EasyLocalization.ensureInitialized()`.
+- **Format**: Default to JSON. Store in `assets/translations/`.
+- **Lookup**: Use `.tr()` extension on strings.
+- **Locale**: Change via `context.setLocale(Locale('code'))`.
+- **Params**: Use `{}` in JSON; pass via `tr(args: [...])`.
+- **Counting**: Use `plural()` for quantities.
+- **Sheets**: Sync via `sheet_loader_localization` from Google Sheets for Online file storage to JSON/CSV.
+
+## Anti-Patterns
+
+- **Hardcoding**: No raw strings in UI; use keys.
+- **Manual L10n**: Avoid standard `Localizations.of`; use GetX or `easy_localization` context methods.
+- **Desync**: Keep keys identical across all locale files.
+
+## Reference & Examples
+
+For setup and Google Sheets automation:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+idiomatic-flutter | widgets

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),
+)
+```