codecruise 0.1.0

package/config/agents/stack/expo/rules/critical.md

@@ -0,0 +1,427 @@
+# Critical Rules - Expo/React Native
+
+Must-follow rules. Violations block PR merge.
+
+---
+
+## Component Patterns
+
+### RN-001: Use correct components
+
+```typescript
+// BAD - Web components don't work
+<div className="container">
+<span>Text</span>
+<img src={url} />
+
+// GOOD - React Native components
+<View className="container">
+<Text>Text content</Text>
+<Image source={{ uri: url }} />
+
+// Text must be wrapped
+// BAD
+<View>Hello World</View>
+
+// GOOD
+<View><Text>Hello World</Text></View>
+```
+
+### RN-002: Handle text properly
+
+```typescript
+// All text must be in Text component
+// BAD
+<View>{user.name}</View>
+
+// GOOD
+<View><Text>{user.name}</Text></View>
+
+// Nested text is OK
+<Text>
+  Hello <Text className="font-bold">{name}</Text>!
+</Text>
+
+// String interpolation OK in Text
+<Text>{`Welcome, ${name}`}</Text>
+```
+
+### RN-003: Use Pressable for touch
+
+```typescript
+// GOOD - Pressable with feedback
+<Pressable
+  onPress={handlePress}
+  className="active:opacity-70"
+  hitSlop={8} // Increase touch target
+>
+  <Text>Tap me</Text>
+</Pressable>
+
+// With proper states
+<Pressable
+  onPress={handlePress}
+  className={({ pressed }) =>
+    `p-4 rounded-lg ${pressed ? 'bg-gray-200' : 'bg-white'}`
+  }
+>
+  {({ pressed }) => (
+    <Text className={pressed ? 'text-gray-600' : 'text-black'}>
+      Tap me
+    </Text>
+  )}
+</Pressable>
+
+// Avoid TouchableOpacity (deprecated feel)
+```
+
+---
+
+## Platform Safety
+
+### RN-004: Handle platform differences
+
+```typescript
+import { Platform } from 'react-native';
+
+// Platform-specific code
+if (Platform.OS === 'ios') {
+  // iOS only
+}
+
+if (Platform.OS === 'android') {
+  // Android only
+}
+
+// Platform.select for values
+const styles = {
+  shadow: Platform.select({
+    ios: {
+      shadowColor: '#000',
+      shadowOffset: { width: 0, height: 2 },
+      shadowOpacity: 0.1,
+      shadowRadius: 4,
+    },
+    android: {
+      elevation: 4,
+    },
+  }),
+};
+```
+
+### RN-005: Safe area handling
+
+```typescript
+import { SafeAreaView } from 'react-native-safe-area-context';
+
+// Wrap screens that need safe area
+export default function HomeScreen() {
+  return (
+    <SafeAreaView className="flex-1 bg-white" edges={['top']}>
+      <ScrollView>
+        {/* Content */}
+      </ScrollView>
+    </SafeAreaView>
+  );
+}
+
+// Or use safe area hooks
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+function Header() {
+  const insets = useSafeAreaInsets();
+  return (
+    <View style={{ paddingTop: insets.top }}>
+      {/* Header content */}
+    </View>
+  );
+}
+```
+
+### RN-006: Keyboard handling
+
+```typescript
+import { KeyboardAvoidingView, Platform } from 'react-native';
+
+function LoginScreen() {
+  return (
+    <KeyboardAvoidingView
+      behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+      className="flex-1"
+    >
+      <ScrollView keyboardShouldPersistTaps="handled">
+        <TextInput placeholder="Email" />
+        <TextInput placeholder="Password" secureTextEntry />
+        <Button title="Login" onPress={handleLogin} />
+      </ScrollView>
+    </KeyboardAvoidingView>
+  );
+}
+```
+
+---
+
+## Performance
+
+### RN-007: Avoid inline styles in lists
+
+```typescript
+// BAD - Creates new object every render
+<FlatList
+  data={items}
+  renderItem={({ item }) => (
+    <View style={{ padding: 16, margin: 8 }}>  {/* New object! */}
+      <Text>{item.name}</Text>
+    </View>
+  )}
+/>
+
+// GOOD - Use className or StyleSheet
+<FlatList
+  data={items}
+  renderItem={({ item }) => (
+    <View className="p-4 m-2">
+      <Text>{item.name}</Text>
+    </View>
+  )}
+/>
+
+// Or memoized styles
+const styles = StyleSheet.create({
+  item: { padding: 16, margin: 8 },
+});
+```
+
+### RN-008: Use FlashList for long lists
+
+```typescript
+import { FlashList } from '@shopify/flash-list';
+
+// GOOD - Better performance than FlatList
+<FlashList
+  data={items}
+  keyExtractor={(item) => item.id}
+  renderItem={({ item }) => <ItemCard item={item} />}
+  estimatedItemSize={80}  // Required!
+/>
+
+// FlatList OK for short lists (<50 items)
+```
+
+### RN-009: Memoize expensive renders
+
+```typescript
+import { memo, useCallback, useMemo } from 'react';
+
+// Memoize list items
+const ItemCard = memo(function ItemCard({ item, onPress }) {
+  return (
+    <Pressable onPress={() => onPress(item.id)}>
+      <Text>{item.name}</Text>
+    </Pressable>
+  );
+});
+
+// Memoize callbacks
+function ItemList({ items }) {
+  const handlePress = useCallback((id: string) => {
+    router.push(`/items/${id}`);
+  }, []);
+
+  // Memoize computed values
+  const sortedItems = useMemo(
+    () => [...items].sort((a, b) => a.name.localeCompare(b.name)),
+    [items]
+  );
+
+  return (
+    <FlashList
+      data={sortedItems}
+      renderItem={({ item }) => (
+        <ItemCard item={item} onPress={handlePress} />
+      )}
+    />
+  );
+}
+```
+
+---
+
+## Security
+
+### RN-010: Secure storage for sensitive data
+
+```typescript
+// BAD - AsyncStorage for tokens
+import AsyncStorage from '@react-native-async-storage/async-storage';
+await AsyncStorage.setItem('token', token); // Not encrypted!
+
+// GOOD - SecureStore for sensitive data
+import * as SecureStore from 'expo-secure-store';
+await SecureStore.setItemAsync('token', token); // Encrypted
+
+// Use AsyncStorage only for non-sensitive data
+await AsyncStorage.setItem('theme', 'dark'); // OK
+await AsyncStorage.setItem('onboarded', 'true'); // OK
+```
+
+### RN-011: Validate deep links
+
+```typescript
+// app.json
+{
+  "expo": {
+    "scheme": "myapp"
+  }
+}
+
+// Validate incoming links
+import { useURL } from 'expo-linking';
+
+function DeepLinkHandler() {
+  const url = useURL();
+
+  useEffect(() => {
+    if (url) {
+      const parsed = Linking.parse(url);
+
+      // Validate before navigating
+      if (isValidPath(parsed.path)) {
+        router.push(parsed.path);
+      }
+    }
+  }, [url]);
+}
+```
+
+### RN-012: Never hardcode secrets
+
+```typescript
+// BAD
+const API_KEY = 'sk_live_xxxxx';
+
+// GOOD - Use environment variables
+// app.config.js
+export default {
+  expo: {
+    extra: {
+      apiUrl: process.env.API_URL,
+    },
+  },
+};
+
+// Access via Constants
+import Constants from 'expo-constants';
+const apiUrl = Constants.expoConfig?.extra?.apiUrl;
+```
+
+---
+
+## Accessibility
+
+### RN-013: Add accessibility labels
+
+```typescript
+<Pressable
+  onPress={handleDelete}
+  accessibilityLabel="Delete item"
+  accessibilityRole="button"
+  accessibilityHint="Removes this item from your list"
+>
+  <TrashIcon />
+</Pressable>
+
+<Image
+  source={{ uri: user.avatar }}
+  accessibilityLabel={`Profile picture of ${user.name}`}
+/>
+
+// For decorative elements
+<Image
+  source={decorativeImage}
+  accessibilityElementsHidden={true}
+/>
+```
+
+### RN-014: Support screen readers
+
+```typescript
+// Group related elements
+<View accessibilityRole="summary">
+  <Text>Order Total</Text>
+  <Text>${total}</Text>
+</View>
+
+// Live regions for updates
+<View
+  accessibilityLiveRegion="polite"
+  accessibilityLabel={`${count} items in cart`}
+>
+  <Text>{count}</Text>
+</View>
+
+// State changes
+<Pressable
+  accessibilityState={{ selected: isSelected }}
+  accessibilityRole="checkbox"
+>
+  <Text>Option {isSelected ? '(selected)' : ''}</Text>
+</Pressable>
+```
+
+---
+
+## Error Handling
+
+### RN-015: Handle errors gracefully
+
+```typescript
+import { ErrorBoundary } from 'react-error-boundary';
+
+function ErrorFallback({ error, resetErrorBoundary }) {
+  return (
+    <View className="flex-1 items-center justify-center p-4">
+      <Text className="text-lg font-bold text-red-500">
+        Something went wrong
+      </Text>
+      <Text className="text-gray-600 mt-2">{error.message}</Text>
+      <Pressable
+        onPress={resetErrorBoundary}
+        className="mt-4 bg-blue-500 px-4 py-2 rounded"
+      >
+        <Text className="text-white">Try Again</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+// Wrap screens
+<ErrorBoundary FallbackComponent={ErrorFallback}>
+  <HomeScreen />
+</ErrorBoundary>
+```
+
+### RN-016: Handle network errors
+
+```typescript
+import NetInfo from '@react-native-community/netinfo';
+
+function useNetworkStatus() {
+  const [isConnected, setIsConnected] = useState(true);
+
+  useEffect(() => {
+    return NetInfo.addEventListener((state) => {
+      setIsConnected(state.isConnected ?? true);
+    });
+  }, []);
+
+  return isConnected;
+}
+
+// In components
+const isConnected = useNetworkStatus();
+
+if (!isConnected) {
+  return <OfflineScreen />;
+}
+```