@buivietphi/skill-mobile-mt 2.1.0 → 2.2.0

package/shared/navigation-patterns.md

@@ -0,0 +1,375 @@
+# Navigation Patterns — Complex Flows
+
+> On-demand module. Loaded when implementing auth flows, deep links, modals, or tab navigation.
+> Contains production patterns for React Native, Flutter, iOS, and Android.
+
+---
+
+## Auth-Based Navigation Flow
+
+### React Native (React Navigation)
+
+```typescript
+// navigation/RootNavigator.tsx
+import { NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import { useAuthStore, useIsLoggedIn } from '@/stores/useAuthStore';
+
+const Stack = createNativeStackNavigator<RootStackParamList>();
+
+export function RootNavigator() {
+  const isLoggedIn = useIsLoggedIn();
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    // Check stored token on app start
+    async function bootstrap() {
+      const hasToken = useAuthStore.getState().token;
+      if (hasToken) {
+        const valid = await useAuthStore.getState().refreshSession();
+        if (!valid) useAuthStore.getState().logout();
+      }
+      setIsReady(true);
+    }
+    bootstrap();
+  }, []);
+
+  if (!isReady) return <SplashScreen />;
+
+  return (
+    <NavigationContainer>
+      <Stack.Navigator screenOptions={{ headerShown: false }}>
+        {isLoggedIn ? (
+          // Authenticated stack
+          <>
+            <Stack.Screen name="MainTabs" component={MainTabNavigator} />
+            <Stack.Screen name="ProductDetail" component={ProductDetailScreen} />
+            <Stack.Screen name="Settings" component={SettingsScreen} />
+            {/* Modals */}
+            <Stack.Group screenOptions={{ presentation: 'modal' }}>
+              <Stack.Screen name="EditProfile" component={EditProfileScreen} />
+              <Stack.Screen name="ImageViewer" component={ImageViewerScreen} />
+            </Stack.Group>
+          </>
+        ) : (
+          // Unauthenticated stack
+          <>
+            <Stack.Screen name="Onboarding" component={OnboardingScreen} />
+            <Stack.Screen name="Login" component={LoginScreen} />
+            <Stack.Screen name="Register" component={RegisterScreen} />
+            <Stack.Screen name="ForgotPassword" component={ForgotPasswordScreen} />
+          </>
+        )}
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+### Flutter (GoRouter)
+
+```dart
+// navigation/app_router.dart
+import 'package:go_router/go_router.dart';
+
+final appRouter = GoRouter(
+  initialLocation: '/',
+  redirect: (context, state) {
+    final isLoggedIn = ref.read(authProvider).isLoggedIn;
+    final isAuthRoute = state.matchedLocation.startsWith('/auth');
+
+    if (!isLoggedIn && !isAuthRoute) return '/auth/login';
+    if (isLoggedIn && isAuthRoute) return '/';
+    return null;
+  },
+  routes: [
+    // Auth routes
+    GoRoute(path: '/auth/login', builder: (_, __) => const LoginScreen()),
+    GoRoute(path: '/auth/register', builder: (_, __) => const RegisterScreen()),
+
+    // App routes with bottom nav shell
+    ShellRoute(
+      builder: (_, __, child) => ScaffoldWithNavBar(child: child),
+      routes: [
+        GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
+        GoRoute(path: '/search', builder: (_, __) => const SearchScreen()),
+        GoRoute(path: '/cart', builder: (_, __) => const CartScreen()),
+        GoRoute(path: '/profile', builder: (_, __) => const ProfileScreen()),
+      ],
+    ),
+
+    // Detail routes (no bottom nav)
+    GoRoute(
+      path: '/product/:id',
+      builder: (_, state) => ProductDetailScreen(id: state.pathParameters['id']!),
+    ),
+  ],
+);
+```
+
+---
+
+## Deep Linking
+
+### React Native (Expo Router)
+
+```typescript
+// app/_layout.tsx — Expo Router handles deep links automatically via file structure
+// URL: myapp://product/abc-123 → app/product/[id].tsx
+
+// app/product/[id].tsx
+import { useLocalSearchParams } from 'expo-router';
+
+export default function ProductDetailScreen() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+
+  // Validate param exists
+  if (!id) return <NotFoundScreen />;
+
+  // Fetch and render
+  const { data, isLoading } = useProductDetail(id as ProductId);
+  // ...
+}
+```
+
+### React Navigation Deep Link Config
+
+```typescript
+// navigation/linking.ts
+const linking: LinkingOptions<RootStackParamList> = {
+  prefixes: ['myapp://', 'https://myapp.com'],
+  config: {
+    screens: {
+      MainTabs: {
+        screens: {
+          Home: 'home',
+          Profile: 'profile/:userId',
+        },
+      },
+      ProductDetail: 'product/:productId',
+      Settings: 'settings',
+    },
+  },
+};
+
+// Handle notification deep links
+import * as Notifications from 'expo-notifications';
+
+function useNotificationDeepLink() {
+  const navigation = useAppNavigation();
+
+  useEffect(() => {
+    const sub = Notifications.addNotificationResponseReceivedListener(response => {
+      const data = response.notification.request.content.data;
+      if (data.screen === 'ProductDetail' && data.productId) {
+        navigation.navigate('ProductDetail', { productId: data.productId as ProductId });
+      }
+    });
+    return () => sub.remove();
+  }, [navigation]);
+}
+```
+
+---
+
+## Bottom Tab Navigation
+
+### React Native — Lazy Tabs with State Preservation
+
+```typescript
+// navigation/MainTabNavigator.tsx
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+
+const Tab = createBottomTabNavigator<MainTabParamList>();
+
+export function MainTabNavigator() {
+  return (
+    <Tab.Navigator
+      screenOptions={{
+        headerShown: false,
+        // Lazy load: render tab only when first visited
+        lazy: true,
+        // Freeze inactive tabs (prevent re-renders)
+        freezeOnBlur: true,
+        tabBarActiveTintColor: theme.colors.primary,
+      }}
+    >
+      <Tab.Screen
+        name="Home"
+        component={HomeScreen}
+        options={{
+          tabBarIcon: ({ color, size }) => <HomeIcon color={color} size={size} />,
+          tabBarLabel: 'Home',
+        }}
+      />
+      <Tab.Screen
+        name="Search"
+        component={SearchScreen}
+        options={{
+          tabBarIcon: ({ color, size }) => <SearchIcon color={color} size={size} />,
+        }}
+      />
+      <Tab.Screen
+        name="Cart"
+        component={CartScreen}
+        options={{
+          tabBarIcon: ({ color, size }) => <CartIcon color={color} size={size} />,
+          tabBarBadge: cartCount > 0 ? cartCount : undefined,
+        }}
+      />
+      <Tab.Screen
+        name="Profile"
+        component={ProfileScreen}
+        options={{
+          tabBarIcon: ({ color, size }) => <ProfileIcon color={color} size={size} />,
+        }}
+      />
+    </Tab.Navigator>
+  );
+}
+```
+
+---
+
+## Modal Navigation
+
+### React Native — Modal Stack
+
+```typescript
+// Present as modal (slides up from bottom on iOS)
+navigation.navigate('EditProfile'); // registered in modal group
+
+// Dismiss modal
+navigation.goBack();
+
+// Modal with result — pass callback via params or use event
+// Option A: Use navigation params
+navigation.navigate('SelectAddress', {
+  onSelect: (address: Address) => {
+    // handle selected address
+  },
+});
+
+// Option B: Use event emitter
+import { DeviceEventEmitter } from 'react-native';
+// In modal: DeviceEventEmitter.emit('addressSelected', address);
+// In parent: DeviceEventEmitter.addListener('addressSelected', handler);
+```
+
+### Flutter — Modal Bottom Sheet
+
+```dart
+// Modal bottom sheet
+showModalBottomSheet(
+  context: context,
+  isScrollControlled: true, // full-height if needed
+  useSafeArea: true,
+  builder: (context) => DraggableScrollableSheet(
+    initialChildSize: 0.6,
+    minChildSize: 0.3,
+    maxChildSize: 0.9,
+    builder: (_, controller) => AddressPickerSheet(scrollController: controller),
+  ),
+);
+```
+
+---
+
+## Push Notification Navigation
+
+### React Native (Expo Notifications)
+
+```typescript
+// hooks/useNotificationSetup.ts
+import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+
+export function useNotificationSetup() {
+  useEffect(() => {
+    registerForPush();
+  }, []);
+
+  async function registerForPush() {
+    if (!Device.isDevice) return; // skip simulator
+
+    const { status } = await Notifications.getPermissionsAsync();
+    let finalStatus = status;
+
+    if (status !== 'granted') {
+      const { status: newStatus } = await Notifications.requestPermissionsAsync();
+      finalStatus = newStatus;
+    }
+
+    if (finalStatus !== 'granted') return;
+
+    const token = (await Notifications.getExpoPushTokenAsync()).data;
+    await userService.registerPushToken(token);
+  }
+}
+
+// Notification handler — runs when app receives notification
+Notifications.setNotificationHandler({
+  handleNotification: async () => ({
+    shouldShowAlert: true,
+    shouldPlaySound: true,
+    shouldSetBadge: true,
+  }),
+});
+```
+
+---
+
+## Permissions Handling Pattern
+
+```typescript
+// hooks/usePermission.ts
+import * as Location from 'expo-location';
+import * as Camera from 'expo-camera';
+import { Alert, Linking } from 'react-native';
+
+type PermissionType = 'camera' | 'location' | 'notifications';
+
+export function usePermission(type: PermissionType) {
+  const [granted, setGranted] = useState<boolean | null>(null);
+
+  const request = useCallback(async () => {
+    let result: { status: string };
+
+    switch (type) {
+      case 'camera':
+        result = await Camera.requestCameraPermissionsAsync();
+        break;
+      case 'location':
+        result = await Location.requestForegroundPermissionsAsync();
+        break;
+      case 'notifications':
+        result = await Notifications.requestPermissionsAsync();
+        break;
+    }
+
+    if (result.status === 'granted') {
+      setGranted(true);
+      return true;
+    }
+
+    // Permission denied — guide user to settings
+    Alert.alert(
+      'Permission Required',
+      `Please enable ${type} access in Settings to use this feature.`,
+      [
+        { text: 'Cancel', style: 'cancel' },
+        { text: 'Open Settings', onPress: () => Linking.openSettings() },
+      ]
+    );
+    setGranted(false);
+    return false;
+  }, [type]);
+
+  return { granted, request };
+}
+
+// Usage:
+// const camera = usePermission('camera');
+// const canUse = await camera.request();
+// if (canUse) { /* proceed */ }
+```

package/shared/spec-to-code.md

@@ -0,0 +1,293 @@
+# Spec-to-Code — From Requirements to Implementation
+
+> On-demand module. Loaded when building new features from specs, user stories, or vague descriptions.
+> Bridges the gap between "what to build" and "how to implement it".
+
+---
+
+## Spec → Code Pipeline
+
+```
+STEP 1: PARSE SPEC (extract structured requirements)
+STEP 2: DEPENDENCY GRAPH (map what depends on what)
+STEP 3: FILE PLAN (which files to create/modify)
+STEP 4: TYPE DEFINITIONS (interfaces + branded types)
+STEP 5: IMPLEMENT (bottom-up: types → services → hooks → screens)
+STEP 6: VERIFY (against original spec checklist)
+```
+
+---
+
+## Step 1: Parse Spec → Structured Requirements
+
+Given ANY feature description, extract these 8 items:
+
+```
+┌─────────────────────────────────────────┐
+│ 1. ENTITY       What data objects?      │
+│ 2. FIELDS       What properties each?   │
+│ 3. ACTIONS      What can user do?       │
+│ 4. STATES       Loading/error/empty/ok  │
+│ 5. NAVIGATION   From where? To where?   │
+│ 6. API          Which endpoints?        │
+│ 7. STORAGE      Persist anything local? │
+│ 8. VALIDATION   Input rules?            │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Step 2: Dependency Graph Template
+
+```
+[FeatureName]Screen
+├── Components
+│   ├── [Name]Header
+│   ├── [Name]List / [Name]Card
+│   ├── [Name]Form (if editable)
+│   └── [Name]Empty / [Name]Error / [Name]Skeleton
+│
+├── Hook: use[FeatureName]
+│   ├── Query: use[Entity]Query (GET data)
+│   ├── Mutation: use[Action]Mutation (POST/PUT/DELETE)
+│   └── State: use[Store]Store (local state)
+│
+├── Service: [entity]Service.ts
+│   ├── get[Entity](params) → API call
+│   ├── create[Entity](data) → API call
+│   ├── update[Entity](id, data) → API call
+│   └── delete[Entity](id) → API call
+│
+├── Types: [entity].types.ts
+│   ├── [Entity] interface
+│   ├── Create[Entity]Input
+│   ├── Update[Entity]Input
+│   └── [Entity]Params (filters, pagination)
+│
+└── Navigation: registered in navigator
+```
+
+---
+
+## Step 3: File Plan — What Goes Where
+
+```
+RULE: Follow existing project structure. NEVER invent new patterns.
+RULE: Scan project for a SIMILAR feature. Clone its file structure.
+
+TYPICAL FILE PLAN:
+
+  src/features/[feature]/
+  ├── [Feature]Screen.tsx          ← Screen component (4 states)
+  ├── components/
+  │   ├── [Feature]Header.tsx      ← Header with title + actions
+  │   ├── [Feature]List.tsx        ← List/grid of items
+  │   ├── [Feature]Card.tsx        ← Single item card
+  │   ├── [Feature]Form.tsx        ← Form (if editable)
+  │   ├── [Feature]Skeleton.tsx    ← Loading skeleton
+  │   └── [Feature]Empty.tsx       ← Empty state
+  ├── hooks/
+  │   └── use[Feature].ts          ← Business logic hook
+  ├── services/
+  │   └── [feature]Service.ts      ← API calls
+  └── types/
+      └── [feature].types.ts       ← TypeScript interfaces
+
+  ALSO UPDATE:
+  ├── navigation/                  ← Register new screen
+  └── stores/ (if new store)       ← Only if feature needs global state
+```
+
+---
+
+## Step 4: Type-First Development
+
+```
+ALWAYS write types BEFORE implementation.
+
+ORDER:
+  1. Entity types (what data looks like)
+  2. Input types (what user submits)
+  3. API response types (what server returns)
+  4. Screen param types (navigation params)
+
+WHY: Types catch integration errors before runtime.
+     Types serve as documentation for the feature.
+     Types make code review faster (reviewer reads types first).
+```
+
+---
+
+## Step 5: Implementation Order (Bottom-Up)
+
+```
+WRONG ORDER (causes integration bugs):
+  Screen → Hook → Service → Types
+  (screen written before knowing what data looks like)
+
+RIGHT ORDER:
+  1. types/[feature].types.ts     ← Define the contract
+  2. services/[feature]Service.ts ← Implement API calls
+  3. hooks/use[Feature].ts        ← Wire service + state
+  4. components/                   ← Build UI pieces
+  5. [Feature]Screen.tsx           ← Compose everything
+  6. navigation/                   ← Register route
+
+Each step VERIFIES against the previous:
+  Service matches types? ✓
+  Hook calls service correctly? ✓
+  Component renders hook data? ✓
+  Screen composes components? ✓
+```
+
+---
+
+## Full Walkthrough Example
+
+### Spec: "Product Detail Screen"
+
+**User says:** "I need a product detail screen showing images, title, price, description, reviews, and an 'Add to Cart' button. Cart persists offline."
+
+### Parse:
+
+```
+1. ENTITY:      Product, CartItem, Review
+2. FIELDS:
+   Product  → id, title, price, description, images[], category, inStock
+   CartItem → productId, quantity, price
+   Review   → id, userId, rating, comment, createdAt
+3. ACTIONS:     View product, Add to cart, View reviews, Share
+4. STATES:      Loading (skeleton), Error (retry), Empty (404), Success
+5. NAVIGATION:  From: ProductList → To: Cart, ReviewList
+6. API:         GET /products/:id, POST /cart/items, GET /products/:id/reviews
+7. STORAGE:     Cart stored locally (MMKV) for offline
+8. VALIDATION:  Quantity ≥ 1, max 99
+```
+
+### Dependency Graph:
+
+```
+ProductDetailScreen
+├── ImageCarousel          ← Horizontal scroll, snap, indicators
+├── ProductInfo            ← Title, price, description, stock badge
+├── ReviewSummary          ← Average rating, count, "See all" link
+├── AddToCartButton        ← Quantity selector + CTA
+│
+├── useProductDetail(id)
+│   ├── useQuery(['product', id], () => productService.getById(id))
+│   └── useQuery(['reviews', id], () => productService.getReviews(id))
+│
+├── useCartStore (Zustand + MMKV persist)
+│   ├── addItem(productId, quantity, price)
+│   ├── removeItem(productId)
+│   └── items: CartItem[]
+│
+├── productService.ts
+│   ├── getById(id: ProductId): Promise<Product>
+│   └── getReviews(id: ProductId): Promise<Review[]>
+│
+└── Types
+    ├── Product, CartItem, Review
+    ├── ProductDetailParams = { productId: ProductId }
+    └── AddToCartInput = { productId: ProductId; quantity: number }
+```
+
+### File Plan:
+
+```
+src/features/product/
+├── ProductDetailScreen.tsx
+├── components/
+│   ├── ImageCarousel.tsx
+│   ├── ProductInfo.tsx
+│   ├── ReviewSummary.tsx
+│   ├── AddToCartButton.tsx
+│   └── ProductDetailSkeleton.tsx
+├── hooks/
+│   └── useProductDetail.ts
+├── services/
+│   └── productService.ts
+└── types/
+    └── product.types.ts
+
+src/stores/useCartStore.ts           ← Global (shared across features)
+navigation/types.ts                  ← Add ProductDetail params
+```
+
+### Implementation (abbreviated — types first):
+
+```typescript
+// 1. types/product.types.ts
+export interface Product {
+  id: ProductId;
+  title: string;
+  price: number;
+  description: string;
+  images: string[];
+  category: string;
+  inStock: boolean;
+}
+
+export interface Review {
+  id: string;
+  userId: UserId;
+  rating: number;  // 1-5
+  comment: string;
+  createdAt: string;
+}
+
+export interface AddToCartInput {
+  productId: ProductId;
+  quantity: number;
+}
+
+// 2. services/productService.ts
+export const productService = {
+  getById: (id: ProductId) => api.get<Product>(`/products/${id}`),
+  getReviews: (id: ProductId) => api.get<Review[]>(`/products/${id}/reviews`),
+};
+
+// 3. hooks/useProductDetail.ts
+export function useProductDetail(productId: ProductId) {
+  const product = useQuery({ queryKey: ['product', productId], queryFn: () => productService.getById(productId) });
+  const reviews = useQuery({ queryKey: ['reviews', productId], queryFn: () => productService.getReviews(productId) });
+  const addToCart = useCartStore(state => state.addItem);
+
+  return {
+    product: product.data,
+    reviews: reviews.data,
+    isLoading: product.isLoading,
+    error: product.error,
+    refetch: product.refetch,
+    handleAddToCart: (quantity: number) => {
+      if (!product.data) return;
+      addToCart(product.data.id, quantity, product.data.price);
+    },
+  };
+}
+
+// 4-5. Screen composes hook + components with 4 states
+// → Loading: <ProductDetailSkeleton />
+// → Error: <ErrorView onRetry={refetch} />
+// → Empty: <NotFoundView />
+// → Success: <ImageCarousel /> + <ProductInfo /> + <ReviewSummary /> + <AddToCartButton />
+```
+
+---
+
+## Checklist: Verify Against Spec
+
+```
+After implementing, check EVERY item from the parsed spec:
+
+□ All ENTITIES defined in types?
+□ All FIELDS present in interfaces?
+□ All ACTIONS wired to handlers?
+□ All 4 STATES rendered?
+□ NAVIGATION registered + params typed?
+□ All API endpoints called correctly?
+□ STORAGE persisted where needed?
+□ VALIDATION applied to inputs?
+□ Accessibility labels on interactive elements?
+□ Platform-specific behavior handled (iOS vs Android)?
+```