@valentia-ai-skills/framework 1.0.0

package/skills/stack/react-native/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: react-native-patterns
+description: >
+  React Native and mobile development patterns for mobile teams. Use this skill
+  whenever writing, reviewing, or designing mobile app code using React Native,
+  Expo, or related mobile frameworks. Triggers on: "React Native", "mobile app",
+  "Expo", "iOS", "Android", "navigation", "react-navigation", "native module",
+  "mobile performance", "offline", "push notification", "deep link", "app store",
+  "mobile UI", "gesture", "animation", "Reanimated", "AsyncStorage", "MMKV",
+  "native bridge", "mobile testing", "Detox", "Appium". Applies to mobile teams.
+version: "1.0.0"
+scope: stack
+stack: react-native
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# React Native Patterns
+
+## Overview
+
+Mobile development has unique constraints — performance on constrained devices,
+offline support, platform differences, and app store requirements. These patterns
+extend the React patterns skill with mobile-specific conventions.
+
+**Prerequisite**: All rules from `stack/react/SKILL.md` apply to React Native code.
+This skill adds mobile-specific patterns on top.
+
+## 1. Project Structure
+
+```
+src/
+  components/           # Shared UI components
+    ui/                 # Design system primitives
+    forms/              # Form components
+  screens/              # Screen-level components (1:1 with routes)
+    home/
+      home-screen.tsx
+      home-screen.test.tsx
+  navigation/           # Navigation configuration
+    root-navigator.tsx
+    tab-navigator.tsx
+    types.ts            # Navigation type definitions
+  services/             # API clients, business logic
+  hooks/                # Shared custom hooks
+  stores/               # State management (Zustand)
+  utils/                # Pure utility functions
+  constants/            # App-wide constants
+  types/                # Shared TypeScript types
+  assets/               # Images, fonts, animations
+```
+
+### Rules
+- Screens in `screens/` — one directory per screen with co-located tests
+- Navigation config in `navigation/` — typed with React Navigation's TypeScript support
+- Platform-specific files use `.ios.tsx` / `.android.tsx` extension (only when necessary)
+
+## 2. Navigation
+
+### Type-Safe Navigation
+Always type your navigation params:
+
+```tsx
+// navigation/types.ts
+export type RootStackParamList = {
+  Home: undefined;
+  UserProfile: { userId: string };
+  Settings: undefined;
+  OrderDetails: { orderId: string; fromNotification?: boolean };
+};
+
+// In a screen:
+type Props = NativeStackScreenProps<RootStackParamList, "UserProfile">;
+
+export function UserProfileScreen({ route, navigation }: Props) {
+  const { userId } = route.params;  // typed!
+  // ...
+}
+```
+
+### Rules
+- All navigation params must be typed
+- Use `navigation.navigate` — never `navigation.dispatch` for standard flows
+- Deep links must be handled in navigation config, not in components
+- Always handle the "back" action gracefully
+
+## 3. Performance
+
+### FlatList Rules (critical)
+```tsx
+// ✅ Good: Optimized FlatList
+<FlatList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={item => item.id}
+  getItemLayout={(data, index) => ({
+    length: ITEM_HEIGHT,
+    offset: ITEM_HEIGHT * index,
+    index,
+  })}
+  maxToRenderPerBatch={10}
+  windowSize={5}
+  removeClippedSubviews={true}
+/>
+
+// Extract renderItem outside component or use useCallback
+const renderItem = useCallback(({ item }: { item: Product }) => (
+  <ProductCard product={item} onPress={handlePress} />
+), [handlePress]);
+```
+
+### Rules
+- Always provide `keyExtractor` — never use array index as key
+- Use `getItemLayout` for fixed-height items
+- Extract `renderItem` to prevent re-renders
+- Use `React.memo` on list item components
+- Test with 1000+ items to catch performance issues
+
+### Image Optimization
+- Use `react-native-fast-image` for cached image loading
+- Always specify image dimensions (width/height)
+- Use appropriate resolution for device density
+- Lazy load images below the fold
+
+### Animation Rules
+- Use `react-native-reanimated` for smooth 60fps animations
+- Run animations on the UI thread (`useAnimatedStyle`, `withTiming`)
+- Never use `Animated` from React Native for complex animations
+- Test animations on low-end Android devices
+
+## 4. Offline-First Pattern
+
+Mobile apps must handle offline gracefully:
+
+```tsx
+// Pattern: Optimistic update with sync queue
+function useOfflineReady<T>(
+  queryKey: string[],
+  fetcher: () => Promise<T>,
+  mutator: (data: T) => Promise<T>,
+) {
+  const networkState = useNetworkState();
+  
+  // Read from cache first
+  const { data, isLoading } = useQuery({
+    queryKey,
+    queryFn: fetcher,
+    staleTime: 5 * 60 * 1000,  // 5 min
+    cacheTime: 24 * 60 * 60 * 1000,  // 24 hours
+  });
+
+  const mutation = useMutation({
+    mutationFn: mutator,
+    onMutate: async (newData) => {
+      // Optimistic update
+      queryClient.setQueryData(queryKey, newData);
+    },
+    onError: (err, newData, context) => {
+      // Rollback on failure
+      queryClient.setQueryData(queryKey, context?.previous);
+    },
+    retry: networkState.isConnected ? 3 : false,
+  });
+
+  return { data, isLoading, mutate: mutation.mutate };
+}
+```
+
+### Rules
+- Cache API responses locally (TanStack Query + MMKV)
+- Show cached data immediately, refresh in background
+- Queue mutations when offline, sync when online
+- Always show clear offline indicator in the UI
+- Test the full offline → online sync flow
+
+## 5. Platform-Specific Code
+
+### When to Split
+Only use platform-specific files when the UI or behavior fundamentally differs:
+
+```
+// button.tsx          — shared logic (95% of cases)
+// button.ios.tsx      — iOS-only implementation
+// button.android.tsx  — Android-only implementation
+```
+
+### Prefer Platform.select
+For small differences, use inline platform checks:
+
+```tsx
+import { Platform, StyleSheet } from "react-native";
+
+const styles = StyleSheet.create({
+  shadow: Platform.select({
+    ios: {
+      shadowColor: "#000",
+      shadowOffset: { width: 0, height: 2 },
+      shadowOpacity: 0.1,
+      shadowRadius: 4,
+    },
+    android: {
+      elevation: 4,
+    },
+  }),
+});
+```
+
+### Rules
+- Default to shared code — split only when genuinely needed
+- Platform checks for: shadows, status bar, haptics, keyboard behavior
+- Test on both platforms before merging
+
+## 6. Local Storage
+
+```tsx
+// Use MMKV (fast, synchronous) for simple key-value storage
+import { MMKV } from "react-native-mmkv";
+
+const storage = new MMKV();
+
+// Store
+storage.set("user.token", token);
+storage.set("user.preferences", JSON.stringify(prefs));
+
+// Retrieve
+const token = storage.getString("user.token");
+const prefs = JSON.parse(storage.getString("user.preferences") || "{}");
+```
+
+### Rules
+- Use MMKV over AsyncStorage (faster, synchronous)
+- Never store sensitive data in plain storage — use encrypted storage or Keychain
+- Prefix keys by domain: `user.token`, `cache.products`, `settings.theme`
+- Clear storage on logout (except device preferences)
+
+## 7. App Lifecycle
+
+- Handle app state changes (active, background, inactive)
+- Refresh data when app returns to foreground
+- Save draft state when app goes to background
+- Handle push notification deep links on cold start AND warm start
+
+## Checklist
+
+Before finalizing mobile code:
+- [ ] All React patterns from stack/react still apply
+- [ ] Navigation params are fully typed
+- [ ] FlatList has keyExtractor, getItemLayout, and memoized renderItem
+- [ ] Images have fixed dimensions and use fast-image
+- [ ] Animations use Reanimated (UI thread)
+- [ ] Offline state handled with cache + sync queue
+- [ ] Platform differences handled minimally
+- [ ] Sensitive data NOT in plain MMKV — use Keychain/encrypted storage
+- [ ] Tested on both iOS and Android
+- [ ] Tested on low-end device for performance

package/skills/stack/react-native/tests/test-prompts.md

@@ -0,0 +1,26 @@
+## Test 1: List Screen
+**Prompt**: "Build a product listing screen with infinite scroll, pull-to-refresh, and a search bar"
+**Expected**:
+- FlatList with keyExtractor, getItemLayout
+- Memoized renderItem
+- Pagination with onEndReached
+- RefreshControl for pull-to-refresh
+- Loading/empty/error states
+
+## Test 2: Offline Data Handling
+**Prompt**: "Create a form that saves user profile data, works offline, and syncs when back online"
+**Expected**:
+- Optimistic update pattern
+- MMKV or TanStack Query cache
+- Queue mutations when offline
+- Online/offline UI indicator
+- Sync on reconnection
+
+## Test 3: Navigation Setup
+**Prompt**: "Set up navigation for an app with: tab bar (Home, Search, Profile), stack navigation within each tab, and a modal for settings"
+**Expected**:
+- Typed RootStackParamList
+- Tab navigator with nested stack navigators
+- Modal presentation for settings
+- Deep link configuration
+- Type-safe navigation hooks