skillstore-cli 1.0.0

package/data/shared/framework/skills/mobile-development/references/mobile-patterns.md

@@ -0,0 +1,681 @@
+# Mobile Development Patterns
+
+## React Native Patterns
+
+### Functional Components with Hooks
+All components should be functional. Use hooks for lifecycle and side effects.
+
+```typescript
+// Screen component with data fetching
+function OrderListScreen() {
+  const navigation = useNavigation<OrderStackNav>();
+  const { data, isLoading, refetch } = useOrders();
+  const insets = useSafeAreaInsets();
+
+  if (isLoading) return <OrderListSkeleton />;
+
+  return (
+    <View style={{ paddingTop: insets.top }}>
+      <FlatList
+        data={data}
+        renderItem={({ item }) => (
+          <OrderCard
+            order={item}
+            onPress={() => navigation.navigate('OrderDetail', { id: item.id })}
+          />
+        )}
+        keyExtractor={(item) => item.id}
+        onRefresh={refetch}
+        refreshing={isLoading}
+      />
+    </View>
+  );
+}
+```
+
+### Custom Hooks for Business Logic
+Separate data logic from UI. Every hook has a single responsibility.
+
+```typescript
+// useOrders.ts — encapsulates order fetching, caching, and mutation
+export function useOrders(filters?: OrderFilters) {
+  return useQuery({
+    queryKey: ['orders', filters],
+    queryFn: () => orderApi.list(filters),
+    staleTime: 30_000,
+  });
+}
+
+export function useCreateOrder() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: orderApi.create,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['orders'] }),
+  });
+}
+```
+
+### Navigation (React Navigation)
+
+```typescript
+// Type-safe navigation setup
+type RootStackParamList = {
+  Home: undefined;
+  OrderDetail: { id: string };
+  Checkout: { cartId: string };
+};
+
+const Stack = createNativeStackNavigator<RootStackParamList>();
+
+function AppNavigator() {
+  const { isAuthenticated } = useAuth();
+
+  return (
+    <Stack.Navigator>
+      {isAuthenticated ? (
+        <>
+          <Stack.Screen name="Home" component={HomeScreen} />
+          <Stack.Screen name="OrderDetail" component={OrderDetailScreen} />
+          <Stack.Screen
+            name="Checkout"
+            component={CheckoutScreen}
+            options={{ presentation: 'modal' }}
+          />
+        </>
+      ) : (
+        <Stack.Screen name="Login" component={LoginScreen} />
+      )}
+    </Stack.Navigator>
+  );
+}
+```
+
+### State Management (Zustand)
+
+```typescript
+// Lightweight global store — no boilerplate
+interface CartStore {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (id: string) => void;
+  total: () => number;
+  clear: () => void;
+}
+
+export const useCartStore = create<CartStore>((set, get) => ({
+  items: [],
+  addItem: (item) => set((s) => ({ items: [...s.items, item] })),
+  removeItem: (id) => set((s) => ({ items: s.items.filter((i) => i.id !== id) })),
+  total: () => get().items.reduce((sum, i) => sum + i.price * i.quantity, 0),
+  clear: () => set({ items: [] }),
+}));
+```
+
+### Native Modules
+When you need platform APIs not exposed by React Native:
+
+```typescript
+// Turbo Module (New Architecture)
+import { TurboModuleRegistry } from 'react-native';
+
+interface HapticSpec extends TurboModule {
+  impact(style: 'light' | 'medium' | 'heavy'): void;
+  notification(type: 'success' | 'warning' | 'error'): void;
+}
+
+export const HapticModule = TurboModuleRegistry.getEnforcing<HapticSpec>('Haptic');
+```
+
+**Rule**: Prefer community libraries (`react-native-haptic-feedback`) over writing native modules. Only write custom modules for proprietary SDK integrations.
+
+## Flutter Patterns
+
+### Widget Composition
+Build complex UIs by composing small, focused widgets.
+
+```dart
+// Screen widget — orchestrates layout
+class OrderListScreen extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('Orders')),
+      body: const OrderListBody(),
+      floatingActionButton: const NewOrderFab(),
+    );
+  }
+}
+
+// Extracted widget — testable, reusable
+class OrderCard extends StatelessWidget {
+  final Order order;
+  final VoidCallback onTap;
+
+  const OrderCard({required this.order, required this.onTap});
+
+  @override
+  Widget build(BuildContext context) {
+    return Card(
+      child: ListTile(
+        title: Text(order.title),
+        subtitle: Text(order.status.label),
+        trailing: Text('\$${order.total.toStringAsFixed(2)}'),
+        onTap: onTap,
+      ),
+    );
+  }
+}
+```
+
+### State Management (Riverpod)
+
+```dart
+// Provider for order list
+final ordersProvider = FutureProvider.autoDispose<List<Order>>((ref) {
+  return ref.read(orderRepositoryProvider).fetchOrders();
+});
+
+// In widget
+class OrderListBody extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final ordersAsync = ref.watch(ordersProvider);
+
+    return ordersAsync.when(
+      data: (orders) => ListView.builder(
+        itemCount: orders.length,
+        itemBuilder: (_, i) => OrderCard(
+          order: orders[i],
+          onTap: () => context.push('/orders/${orders[i].id}'),
+        ),
+      ),
+      loading: () => const OrderListSkeleton(),
+      error: (e, _) => ErrorRetry(onRetry: () => ref.invalidate(ordersProvider)),
+    );
+  }
+}
+```
+
+### BLoC Pattern (for complex event-driven flows)
+
+```dart
+// Events
+sealed class CartEvent {}
+class AddToCart extends CartEvent { final Product product; AddToCart(this.product); }
+class RemoveFromCart extends CartEvent { final String productId; RemoveFromCart(this.productId); }
+
+// State
+class CartState {
+  final List<CartItem> items;
+  double get total => items.fold(0, (sum, i) => sum + i.price * i.quantity);
+  const CartState({this.items = const []});
+}
+
+// BLoC
+class CartBloc extends Bloc<CartEvent, CartState> {
+  CartBloc() : super(const CartState()) {
+    on<AddToCart>((event, emit) {
+      emit(CartState(items: [...state.items, CartItem.fromProduct(event.product)]));
+    });
+    on<RemoveFromCart>((event, emit) {
+      emit(CartState(items: state.items.where((i) => i.productId != event.productId).toList()));
+    });
+  }
+}
+```
+
+### Navigation (GoRouter)
+
+```dart
+final router = GoRouter(
+  initialLocation: '/',
+  redirect: (context, state) {
+    final isAuth = ref.read(authProvider).isAuthenticated;
+    if (!isAuth && !state.matchedLocation.startsWith('/login')) return '/login';
+    return null;
+  },
+  routes: [
+    GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
+    GoRoute(
+      path: '/orders/:id',
+      builder: (_, state) => OrderDetailScreen(id: state.pathParameters['id']!),
+    ),
+    ShellRoute(
+      builder: (_, __, child) => MainShell(child: child),
+      routes: [
+        GoRoute(path: '/home', builder: (_, __) => const HomeTab()),
+        GoRoute(path: '/search', builder: (_, __) => const SearchTab()),
+        GoRoute(path: '/profile', builder: (_, __) => const ProfileTab()),
+      ],
+    ),
+  ],
+);
+```
+
+### Platform Channels (for native interop)
+
+```dart
+// Dart side
+class NativePayment {
+  static const _channel = MethodChannel('com.app/payment');
+
+  static Future<PaymentResult> processPayment(PaymentRequest req) async {
+    final result = await _channel.invokeMethod('processPayment', req.toJson());
+    return PaymentResult.fromJson(result);
+  }
+}
+```
+
+## Expo vs Bare Workflow
+
+### Decision Matrix
+
+| Factor | Expo Managed | Bare Workflow |
+|--------|-------------|---------------|
+| **Setup time** | Minutes | Hours (Xcode + Android Studio) |
+| **OTA updates** | EAS Update built-in | Manual CodePush setup |
+| **Native modules** | Expo Modules API | Direct Turbo Modules |
+| **CI/CD** | EAS Build (cloud) | Self-hosted or Fastlane |
+| **Custom native code** | Via config plugins or dev client | Full native access |
+| **App size** | Larger (includes Expo runtime) | Smaller (only what you use) |
+| **Upgrade path** | `npx expo install` | Manual RN upgrade (can be painful) |
+
+**Start with Expo Managed** unless you need:
+- A specific native SDK with no Expo wrapper (rare — check expo packages first)
+- Custom build configurations not supported by config plugins
+- App size under 15MB (games, utilities)
+
+### Expo Router (File-Based Routing)
+
+```
+app/
+├── _layout.tsx          ← Root layout (providers, fonts)
+├── (tabs)/
+│   ├── _layout.tsx      ← Tab navigator
+│   ├── index.tsx         ← Home tab
+│   ├── search.tsx        ← Search tab
+│   └── profile.tsx       ← Profile tab
+├── restaurant/
+│   └── [id].tsx          ← Dynamic route /restaurant/123
+├── checkout/
+│   ├── _layout.tsx       ← Checkout stack
+│   ├── cart.tsx
+│   └── payment.tsx
+└── +not-found.tsx        ← 404 screen
+```
+
+```typescript
+// app/restaurant/[id].tsx
+import { useLocalSearchParams } from 'expo-router';
+
+export default function RestaurantScreen() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+  // fetch restaurant by id...
+}
+```
+
+### EAS Build + EAS Update
+
+```bash
+# Build for internal testing
+eas build --platform all --profile preview
+
+# OTA update (no app store review needed)
+eas update --branch production --message "Fix cart total calculation"
+
+# Build for store submission
+eas build --platform all --profile production
+eas submit --platform all
+```
+
+**OTA Update Rules**:
+- JS-only changes: OTA safe (bug fixes, UI tweaks, copy changes)
+- Native dependency changes: requires new build (new SDK, permission changes)
+- Always test OTA updates on preview branch before production
+
+### Crash Reporting Setup
+
+```typescript
+// Sentry integration (works with Expo)
+import * as Sentry from '@sentry/react-native';
+
+Sentry.init({
+  dsn: process.env.EXPO_PUBLIC_SENTRY_DSN,
+  tracesSampleRate: 0.2,  // 20% of transactions
+  profilesSampleRate: 0.1,
+  enableAutoSessionTracking: true,
+  attachStacktrace: true,
+});
+
+// Wrap root component
+export default Sentry.wrap(App);
+
+// Manual breadcrumbs for important actions
+Sentry.addBreadcrumb({
+  category: 'order',
+  message: `Order placed: ${orderId}`,
+  level: 'info',
+});
+```
+
+**Source Maps**: EAS Build automatically uploads source maps to Sentry when configured:
+```json
+// app.json
+{
+  "expo": {
+    "plugins": ["@sentry/react-native/expo"]
+  }
+}
+```
+
+### Native Module Decision Tree
+
+```
+Need native functionality?
+  │
+  ├─ Check expo packages first (expo-camera, expo-location, etc.)
+  │   → Found? Use it. Done.
+  │
+  ├─ Check community libraries (react-native-*)
+  │   → Found + maintained? Use it. Done.
+  │
+  ├─ Expo Modules API (write once, both platforms)
+  │   → Preferred for new modules. Swift + Kotlin.
+  │
+  └─ Turbo Modules (React Native core)
+      → For performance-critical or complex native code.
+      → Requires C++ for shared implementation.
+```
+
+## Cross-Platform Considerations
+
+### Shared Logic vs Platform-Specific UI
+
+```
+Shared (80%+):              Platform-specific (20%):
+├── Business logic          ├── Navigation transitions
+├── API clients             ├── Date/time pickers
+├── State management        ├── Action sheets vs bottom sheets
+├── Data models             ├── Pull-to-refresh behavior
+├── Validation rules        ├── Haptic feedback patterns
+└── Utility functions       └── System settings integration
+```
+
+### Decision Matrix
+
+| Concern | React Native Approach | Flutter Approach |
+|---------|----------------------|------------------|
+| Navigation | React Navigation | GoRouter |
+| State (simple) | Zustand / Jotai | Riverpod |
+| State (complex) | Redux Toolkit | BLoC |
+| Server state | TanStack Query | Riverpod + Repository |
+| Local DB | WatermelonDB / MMKV | Drift / Hive |
+| Styling | StyleSheet + Nativewind | Theme + custom widgets |
+| Native access | Turbo Modules | Platform channels |
+| Testing | Jest + Detox | flutter_test + integration_test |
+
+## Navigation Patterns
+
+### Stack Navigation
+Primary screens push onto a stack. Use for drill-down flows.
+```
+Home → Product List → Product Detail → Add to Cart
+```
+
+### Tab Navigation
+Top-level sections. 3-5 tabs maximum. Each tab maintains its own stack.
+```
+┌─────────┬──────────┬─────────┬──────────┐
+│  Home   │  Search  │  Orders │ Profile  │
+└─────────┴──────────┴─────────┴──────────┘
+```
+
+### Drawer Navigation
+Side menu for apps with many sections. Less common in modern apps — prefer tabs.
+
+### Deep Linking
+Essential for push notification taps, email links, and sharing.
+
+```typescript
+// React Native — linking config
+const linking = {
+  prefixes: ['myapp://', 'https://myapp.com'],
+  config: {
+    screens: {
+      Home: '',
+      OrderDetail: 'orders/:id',
+      Checkout: 'checkout/:cartId',
+    },
+  },
+};
+```
+
+**Test deep links**: `npx uri-scheme open myapp://orders/123 --ios` or `adb shell am start -d "myapp://orders/123"`.
+
+## State Management Comparison
+
+Pick the simplest option that satisfies your needs:
+
+| Complexity | RN Solution | Flutter Solution | When |
+|-----------|-------------|------------------|------|
+| Single component | `useState` | `StatefulWidget` / `ValueNotifier` | Toggle, input, animation |
+| Parent-child | Props + callbacks | Constructor params + callbacks | Shared between 2-3 widgets |
+| Feature scope | Context + `useReducer` | `Riverpod` scoped provider | Auth, theme, feature settings |
+| Global | Zustand / Redux Toolkit | BLoC / Riverpod global | Cart, notifications, complex flows |
+| Server data | TanStack Query | Riverpod `FutureProvider` | API data with cache + revalidation |
+
+**Rule**: If data comes from an API, use a server-state library first. Only copy to global state if multiple features need to mutate it independently.
+
+## Offline-First Patterns
+
+### Architecture
+
+```
+┌─────────────────────────────────────────┐
+│              UI Layer                    │
+├─────────────────────────────────────────┤
+│          Repository Layer                │
+│  ┌──────────┐  ┌──────────────────────┐ │
+│  │ Local DB │←→│   Sync Engine        │ │
+│  │ (source  │  │ ┌──────────────────┐ │ │
+│  │ of truth)│  │ │  Pending Queue   │ │ │
+│  └──────────┘  │ │  Conflict Resolver│ │ │
+│                │ │  Retry Manager    │ │ │
+│                │ └──────────────────┘ │ │
+│                └───────────┬──────────┘ │
+├────────────────────────────┼────────────┤
+│                     Remote API          │
+└─────────────────────────────────────────┘
+```
+
+### Sync Queue
+Queue mutations when offline. Process when connection returns.
+
+```typescript
+interface PendingAction {
+  id: string;
+  type: 'CREATE' | 'UPDATE' | 'DELETE';
+  entity: string;
+  payload: any;
+  createdAt: number;
+  retryCount: number;
+}
+
+// On reconnect: process queue in order, handle conflicts
+async function processSyncQueue(queue: PendingAction[]) {
+  for (const action of queue.sort((a, b) => a.createdAt - b.createdAt)) {
+    try {
+      await syncAction(action);
+      await removeFromQueue(action.id);
+    } catch (error) {
+      if (isConflict(error)) {
+        await resolveConflict(action, error);
+      } else if (action.retryCount < MAX_RETRIES) {
+        await incrementRetry(action.id);
+      } else {
+        await moveToDeadLetter(action);
+      }
+    }
+  }
+}
+```
+
+### Conflict Resolution Strategies
+
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| Last write wins | Timestamp-based, latest change wins | Simple fields (name, status) |
+| Server wins | Server version always takes precedence | Financial data, inventory |
+| Client wins | Client version takes precedence | Draft content, user preferences |
+| Manual merge | Show both versions, let user choose | Collaborative editing |
+
+## Push Notifications
+
+### Setup Checklist
+
+1. **FCM/APNs configuration**: Register app with Firebase/Apple Developer portal
+2. **Token management**: Store device token on backend, refresh on app launch
+3. **Permission request**: Ask at a contextual moment, not on first launch
+4. **Payload handling**: Handle notification when app is in foreground, background, and terminated
+5. **Channel management** (Android): Create channels for different notification types
+
+### Token Lifecycle
+
+```typescript
+// On app launch — always refresh token
+async function initPushNotifications() {
+  const permission = await requestPermission();
+  if (permission !== 'granted') return;
+
+  const token = await getDeviceToken();
+  await api.registerDevice({ token, platform: Platform.OS });
+
+  // Listen for token refresh
+  onTokenRefresh((newToken) => {
+    api.registerDevice({ token: newToken, platform: Platform.OS });
+  });
+}
+```
+
+### Notification Handling
+
+```typescript
+// Foreground — show in-app banner (not system notification)
+onForegroundMessage((message) => {
+  showInAppNotification({
+    title: message.title,
+    body: message.body,
+    onPress: () => navigateToScreen(message.data),
+  });
+});
+
+// Background/terminated — user tapped notification
+onNotificationOpened((message) => {
+  navigateToScreen(message.data);
+});
+
+// Data-only notifications — silent processing
+onBackgroundMessage(async (message) => {
+  await syncDataInBackground(message.data);
+});
+```
+
+## Permissions Handling
+
+### Request Pattern
+
+Never request permissions at app launch. Request at the moment of need with context.
+
+```typescript
+async function requestCameraPermission(): Promise<boolean> {
+  const status = await check(PERMISSIONS.IOS.CAMERA);
+
+  switch (status) {
+    case 'granted':
+      return true;
+    case 'denied':
+      // First time — show system dialog
+      const result = await request(PERMISSIONS.IOS.CAMERA);
+      return result === 'granted';
+    case 'blocked':
+      // Previously denied — show explanation and link to settings
+      showPermissionDialog({
+        title: 'Camera Access Needed',
+        message: 'To scan barcodes, allow camera access in Settings.',
+        onOpenSettings: () => openSettings(),
+      });
+      return false;
+    default:
+      return false;
+  }
+}
+```
+
+### Permissions Checklist
+
+| Permission | When to Request | Fallback |
+|-----------|----------------|----------|
+| Camera | User taps "Scan" or "Take Photo" | Manual text input |
+| Location | User opens map or delivery tracking | Manual address entry |
+| Notifications | After first meaningful action (first order) | In-app notification center |
+| Photo Library | User taps "Upload Photo" | Camera capture instead |
+| Contacts | User taps "Invite Friends" | Share link manually |
+
+## App Lifecycle Management
+
+### States and Transitions
+
+```
+┌──────────┐     ┌────────────┐     ┌────────────┐
+│ Launched  │────→│ Foreground │←───→│ Background │
+└──────────┘     └────────────┘     └─────┬──────┘
+                                          │
+                                    ┌─────▼──────┐
+                                    │ Terminated  │
+                                    └─────────────┘
+```
+
+### What to Do in Each State
+
+| Transition | Action |
+|-----------|--------|
+| Launch → Foreground | Init services, check auth, fetch fresh data |
+| Foreground → Background | Save draft state, pause timers, disconnect sockets |
+| Background → Foreground | Refresh stale data, reconnect sockets, check auth |
+| Background → Terminated | Persist critical state to local DB |
+
+```typescript
+// React Native
+useEffect(() => {
+  const sub = AppState.addEventListener('change', (state) => {
+    if (state === 'active') {
+      queryClient.refetchQueries({ type: 'active', stale: true });
+      reconnectWebSocket();
+    }
+    if (state === 'background') {
+      saveDraftState();
+      disconnectWebSocket();
+    }
+  });
+  return () => sub.remove();
+}, []);
+```
+
+```dart
+// Flutter
+class _AppLifecycleState extends State<App> with WidgetsBindingObserver {
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    switch (state) {
+      case AppLifecycleState.resumed:
+        ref.invalidate(ordersProvider);  // Refresh data
+        break;
+      case AppLifecycleState.paused:
+        ref.read(draftProvider.notifier).saveToDisk();
+        break;
+      default:
+        break;
+    }
+  }
+}
+```