moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-lang-flutter/SKILL.md

@@ -1,13 +1,15 @@
 ---
-name: moai-lang-flutter
-description: Flutter 3.24+ / Dart 3.5+ development specialist covering Riverpod, go_router, and cross-platform patterns. Use when building cross-platform mobile apps, desktop apps, or web applications with Flutter.
-version: 1.0.0
-category: language
-tags: [flutter, dart, riverpod, cross-platform, mobile, desktop]
-context7-libraries: [/flutter/flutter, /rrousselgit/riverpod, /flutter/packages]
-related-skills: [moai-lang-swift, moai-lang-kotlin]
-updated: 2025-12-07
-status: active
+name: "moai-lang-flutter"
+description: "Flutter 3.24+ / Dart 3.5+ development specialist covering Riverpod, go_router, and cross-platform patterns. Use when building cross-platform mobile apps, desktop apps, or web applications with Flutter."
+version: 1.1.0
+category: "language"
+modularized: false
+user-invocable: false
+tags: ['flutter', 'dart', 'riverpod', 'cross-platform', 'mobile', 'desktop']
+context7-libraries: ['/flutter/flutter', '/rrousselgit/riverpod', '/flutter/packages']
+related-skills: ['moai-lang-swift', 'moai-lang-kotlin']
+updated: 2026-01-11
+status: "active"
 ---
 
 ## Quick Reference (30 seconds)
@@ -17,6 +19,7 @@ Flutter/Dart Development Expert - Dart 3.5+, Flutter 3.24+ with modern patterns.
 Auto-Triggers: Flutter projects (`.dart` files, `pubspec.yaml`), cross-platform apps, widget development
 
 Core Capabilities:
+
 - Dart 3.5: Patterns, records, sealed classes, extension types
 - Flutter 3.24: Widget tree, Material 3, adaptive layouts
 - Riverpod: State management with code generation
@@ -28,417 +31,44 @@ Core Capabilities:
 
 ### Dart 3.5 Language Features
 
-Pattern Matching with Sealed Classes:
-```dart
-sealed class Result<T> {
-  const Result();
-}
-class Success<T> extends Result<T> {
-  final T data;
-  const Success(this.data);
-}
-class Failure<T> extends Result<T> {
-  final String error;
-  const Failure(this.error);
-}
-
-// Exhaustive switch expression
-String handleResult(Result<User> result) => switch (result) {
-  Success(:final data) => 'User: ${data.name}',
-  Failure(:final error) => 'Error: $error',
-};
-
-// Guard clauses in patterns
-String describeUser(User user) => switch (user) {
-  User(age: var a) when a < 18 => 'Minor',
-  User(age: var a) when a >= 65 => 'Senior',
-  User(name: var n, age: var a) => '$n, age $a',
-};
-```
-
-Records and Destructuring:
-```dart
-typedef UserRecord = ({String name, int age, String email});
-
-// Multiple return values
-(String name, int age) parseUser(Map<String, dynamic> json) {
-  return (json['name'] as String, json['age'] as int);
-}
-
-// Destructuring
-void processUser(Map<String, dynamic> json) {
-  final (name, age) = parseUser(json);
-  print('$name is $age years old');
-}
-
-// Record patterns in collections
-void processUsers(List<UserRecord> users) {
-  for (final (:name, :age, :email) in users) {
-    print('$name ($age): $email');
-  }
-}
-```
-
-Extension Types:
-```dart
-extension type UserId(String value) {
-  factory UserId.generate() => UserId(Uuid().v4());
-  bool get isValid => value.isNotEmpty;
-}
-
-extension type Email(String value) {
-  bool get isValid => value.contains('@') && value.contains('.');
-  String get domain => value.split('@').last;
-}
-```
+Pattern Matching with Sealed Classes: Define a sealed class Result with generic type parameter T. Create subclasses Success containing data field and Failure containing error string. Use switch expressions with pattern matching on the sealed type. Patterns use colon syntax to extract named fields. Add guard clauses with when keyword for conditional matching based on field values.
+
+Records and Destructuring: Define type aliases for records using parentheses with named fields. Create functions returning multiple values as record tuples with positional elements. Use destructuring syntax with parentheses on the left side of assignment. In for loops, destructure named record fields directly using colon syntax.
+
+Extension Types: Define extension types with the type keyword, wrapping a base type in parentheses. Add factory constructors for validation logic. Define getters for computed properties on the underlying value.
 
 ### Riverpod State Management
 
-Provider Definitions:
-```dart
-import 'package:riverpod_annotation/riverpod_annotation.dart';
-part 'providers.g.dart';
-
-@riverpod
-UserRepository userRepository(Ref ref) {
-  return UserRepository(ref.read(dioProvider));
-}
-
-@riverpod
-Future<User> user(Ref ref, String userId) async {
-  return ref.watch(userRepositoryProvider).getUser(userId);
-}
-
-@riverpod
-class UserNotifier extends _$UserNotifier {
-  @override
-  FutureOr<User?> build() => null;
-
-  Future<void> loadUser(String id) async {
-    state = const AsyncLoading();
-    state = await AsyncValue.guard(
-      () => ref.read(userRepositoryProvider).getUser(id),
-    );
-  }
-
-  Future<void> updateUser(User user) async {
-    state = const AsyncLoading();
-    state = await AsyncValue.guard(
-      () => ref.read(userRepositoryProvider).updateUser(user),
-    );
-  }
-}
-
-@riverpod
-Stream<List<Message>> messages(Ref ref, String chatId) {
-  return ref.watch(chatRepositoryProvider).watchMessages(chatId);
-}
-```
-
-Widget Integration:
-```dart
-class UserScreen extends ConsumerWidget {
-  final String userId;
-  const UserScreen({required this.userId, super.key});
-
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final userAsync = ref.watch(userProvider(userId));
-
-    return Scaffold(
-      appBar: AppBar(title: const Text('User Profile')),
-      body: userAsync.when(
-        data: (user) => UserProfile(user: user),
-        loading: () => const Center(child: CircularProgressIndicator()),
-        error: (error, stack) => Center(
-          child: Column(
-            mainAxisAlignment: MainAxisAlignment.center,
-            children: [
-              Text('Error: $error'),
-              ElevatedButton(
-                onPressed: () => ref.invalidate(userProvider(userId)),
-                child: const Text('Retry'),
-              ),
-            ],
-          ),
-        ),
-      ),
-    );
-  }
-}
-```
-
-StatefulWidget with Riverpod:
-```dart
-class EditUserScreen extends ConsumerStatefulWidget {
-  const EditUserScreen({super.key});
-  @override
-  ConsumerState<EditUserScreen> createState() => _EditUserScreenState();
-}
-
-class _EditUserScreenState extends ConsumerState<EditUserScreen> {
-  final _formKey = GlobalKey<FormState>();
-  late TextEditingController _nameController;
-
-  @override
-  void initState() {
-    super.initState();
-    _nameController = TextEditingController();
-  }
-
-  @override
-  void dispose() {
-    _nameController.dispose();
-    super.dispose();
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    ref.listen(userNotifierProvider, (prev, next) {
-      next.whenOrNull(
-        error: (e, _) => ScaffoldMessenger.of(context).showSnackBar(
-          SnackBar(content: Text('Error: $e')),
-        ),
-      );
-    });
-
-    final isLoading = ref.watch(userNotifierProvider).isLoading;
-
-    return Form(
-      key: _formKey,
-      child: Column(
-        children: [
-          TextFormField(
-            controller: _nameController,
-            validator: (v) => v?.isEmpty ?? true ? 'Required' : null,
-          ),
-          ElevatedButton(
-            onPressed: isLoading ? null : () async {
-              if (_formKey.currentState!.validate()) {
-                await ref.read(userNotifierProvider.notifier)
-                    .updateUser(User(name: _nameController.text));
-              }
-            },
-            child: isLoading
-                ? const CircularProgressIndicator()
-                : const Text('Save'),
-          ),
-        ],
-      ),
-    );
-  }
-}
-```
+Provider Definitions: Import riverpod_annotation and add part directive for generated file. Use @riverpod annotation on functions to create simple providers. Return repository instances reading other providers with ref.read. Create async providers by returning Future types. For stateful providers, create classes extending the generated underscore class, override build method for initial state, and add methods that modify state using AsyncValue.guard.
+
+Widget Integration: Create ConsumerWidget subclasses. In build method, receive WidgetRef as second parameter. Use ref.watch to observe provider values. Handle AsyncValue with when method providing data, loading, and error callbacks. Use ref.invalidate to refresh data. Use ref.listen in StatefulWidget for side effects like showing snackbars.
+
+StatefulWidget with Riverpod: Extend ConsumerStatefulWidget and ConsumerState. Initialize TextEditingController in initState and dispose in dispose. Use ref.listen in build for side effects. Check isLoading state to disable buttons during async operations. Access notifier methods with ref.read and the notifier getter.
 
 ### go_router Navigation
 
-Router Configuration:
-```dart
-final router = GoRouter(
-  initialLocation: '/',
-  routes: [
-    GoRoute(
-      path: '/',
-      name: 'home',
-      builder: (context, state) => const HomeScreen(),
-      routes: [
-        GoRoute(
-          path: 'user/:id',
-          name: 'user-detail',
-          builder: (context, state) => UserDetailScreen(
-            userId: state.pathParameters['id']!,
-          ),
-        ),
-      ],
-    ),
-    ShellRoute(
-      builder: (context, state, child) => MainShell(child: child),
-      routes: [
-        GoRoute(
-          path: '/feed',
-          pageBuilder: (_, __) => const NoTransitionPage(child: FeedScreen()),
-        ),
-        GoRoute(
-          path: '/search',
-          pageBuilder: (_, __) => const NoTransitionPage(child: SearchScreen()),
-        ),
-        GoRoute(
-          path: '/profile',
-          pageBuilder: (_, __) => const NoTransitionPage(child: ProfileScreen()),
-        ),
-      ],
-    ),
-  ],
-  redirect: (context, state) {
-    final isLoggedIn = authNotifier.isLoggedIn;
-    final isLoggingIn = state.matchedLocation == '/login';
-    if (!isLoggedIn && !isLoggingIn) return '/login';
-    if (isLoggedIn && isLoggingIn) return '/';
-    return null;
-  },
-  errorBuilder: (context, state) => ErrorScreen(error: state.error),
-);
-
-// Navigation methods
-void navigateToUser(BuildContext context, String userId) {
-  context.go('/user/$userId');
-}
-
-void goBack(BuildContext context) {
-  if (context.canPop()) context.pop();
-  else context.go('/');
-}
-```
+Router Configuration: Create GoRouter instance with initialLocation. Define routes array with GoRoute objects containing path, name, and builder. Nest child routes in routes array. Use ShellRoute for persistent navigation shells. Create pageBuilder using NoTransitionPage for tab navigation. Implement redirect callback checking authentication state and returning redirect path or null to allow navigation. Define errorBuilder for error handling.
+
+Navigation methods: Use context.go for declarative navigation with path. Use context.canPop to check before context.pop.
 
 ### Platform Channels
 
-Dart Implementation:
-```dart
-class NativeBridge {
-  static const _channel = MethodChannel('com.example.app/native');
-  static const _eventChannel = EventChannel('com.example.app/events');
-
-  Future<String> getPlatformVersion() async {
-    try {
-      final version = await _channel.invokeMethod<String>('getPlatformVersion');
-      return version ?? 'Unknown';
-    } on PlatformException catch (e) {
-      throw NativeBridgeException('Failed: ${e.message}');
-    }
-  }
-
-  Future<void> shareContent({required String text, String? title}) async {
-    await _channel.invokeMethod('share', {
-      'text': text,
-      if (title != null) 'title': title,
-    });
-  }
-
-  Stream<BatteryState> watchBatteryState() {
-    return _eventChannel.receiveBroadcastStream().map((event) {
-      final data = event as Map<dynamic, dynamic>;
-      return BatteryState(
-        level: data['level'] as int,
-        isCharging: data['isCharging'] as bool,
-      );
-    });
-  }
-
-  void setupMethodCallHandler() {
-    _channel.setMethodCallHandler((call) async {
-      switch (call.method) {
-        case 'onNativeEvent':
-          // Handle native event
-          return true;
-        default:
-          throw MissingPluginException('Not implemented: ${call.method}');
-      }
-    });
-  }
-}
-
-class BatteryState {
-  final int level;
-  final bool isCharging;
-  const BatteryState({required this.level, required this.isCharging});
-}
-```
+Dart Implementation: Define class with MethodChannel and EventChannel constants using channel name strings. Create async methods that invoke methods on the channel with invokeMethod, catching PlatformException. For streaming data, call receiveBroadcastStream on EventChannel and map events to typed objects. Set up method call handler with setMethodCallHandler to receive calls from native code.
 
 ### Widget Patterns
 
-Adaptive Layouts:
-```dart
-class AdaptiveScaffold extends StatelessWidget {
-  final Widget child;
-  final List<NavigationDestination> destinations;
-  final int selectedIndex;
-  final ValueChanged<int> onDestinationSelected;
-
-  const AdaptiveScaffold({
-    required this.child,
-    required this.destinations,
-    required this.selectedIndex,
-    required this.onDestinationSelected,
-    super.key,
-  });
-
-  @override
-  Widget build(BuildContext context) {
-    final width = MediaQuery.sizeOf(context).width;
-
-    if (width < 600) {
-      return Scaffold(
-        body: child,
-        bottomNavigationBar: NavigationBar(
-          selectedIndex: selectedIndex,
-          onDestinationSelected: onDestinationSelected,
-          destinations: destinations,
-        ),
-      );
-    }
-
-    if (width < 840) {
-      return Scaffold(
-        body: Row(children: [
-          NavigationRail(
-            selectedIndex: selectedIndex,
-            onDestinationSelected: onDestinationSelected,
-            destinations: destinations.map((d) => NavigationRailDestination(
-              icon: d.icon, selectedIcon: d.selectedIcon, label: Text(d.label),
-            )).toList(),
-          ),
-          const VerticalDivider(thickness: 1, width: 1),
-          Expanded(child: child),
-        ]),
-      );
-    }
-
-    return Scaffold(
-      body: Row(children: [
-        NavigationDrawer(
-          selectedIndex: selectedIndex,
-          onDestinationSelected: onDestinationSelected,
-          children: destinations.map((d) => NavigationDrawerDestination(
-            icon: d.icon, selectedIcon: d.selectedIcon ?? d.icon, label: Text(d.label),
-          )).toList(),
-        ),
-        const VerticalDivider(thickness: 1, width: 1),
-        Expanded(child: child),
-      ]),
-    );
-  }
-}
-```
+Adaptive Layouts: Create StatelessWidget with required parameters for child, destinations, selectedIndex, and onDestinationSelected callback. In build, get width using MediaQuery.sizeOf. Use conditional returns based on width breakpoints. Under 600 pixels, return Scaffold with NavigationBar in bottomNavigationBar. Under 840 pixels, return Scaffold with Row containing NavigationRail and expanded child. Above 840 pixels, return Scaffold with Row containing NavigationDrawer and expanded child.
 
 ### Testing
 
-Widget Test Example:
-```dart
-void main() {
-  testWidgets('UserScreen displays data', (tester) async {
-    final container = ProviderContainer(overrides: [
-      userRepositoryProvider.overrideWithValue(MockUserRepository()),
-    ]);
-
-    await tester.pumpWidget(
-      UncontrolledProviderScope(
-        container: container,
-        child: const MaterialApp(home: UserScreen(userId: '1')),
-      ),
-    );
-
-    expect(find.byType(CircularProgressIndicator), findsOneWidget);
-    await tester.pumpAndSettle();
-    expect(find.text('Test User'), findsOneWidget);
-  });
-}
-```
+Widget Test Example: In test main function, create ProviderContainer with overrides for mock providers. Use tester.pumpWidget with UncontrolledProviderScope wrapping MaterialApp with the widget under test. Assert initial loading state with find.byType. Call tester.pumpAndSettle to wait for async operations. Assert final state with find.text.
 
 For comprehensive testing patterns, see [examples.md](examples.md).
 
 ## Advanced Patterns
 
 For comprehensive coverage including:
+
 - Clean Architecture with Riverpod
 - Isolates for compute-heavy operations
 - Custom render objects and painting
@@ -450,14 +80,17 @@ See: [reference.md](reference.md) and [examples.md](examples.md)
 ## Context7 Library Mappings
 
 Flutter/Dart Core:
+
 - `/flutter/flutter` - Flutter framework
 - `/dart-lang/sdk` - Dart SDK
 
 State Management:
+
 - `/rrousselGit/riverpod` - Riverpod state management
 - `/felangel/bloc` - BLoC pattern
 
 Navigation and Storage:
+
 - `/flutter/packages` - go_router and official packages
 - `/cfug/dio` - HTTP client
 - `/isar/isar` - NoSQL database
@@ -469,9 +102,3 @@ Navigation and Storage:
 - `moai-domain-backend` - API integration and backend communication
 - `moai-quality-security` - Mobile security best practices
 - `moai-essentials-debug` - Flutter debugging and DevTools
-
----
-
-Version: 1.0.0
-Last Updated: 2025-12-07
-Status: Production Ready