codecruise 0.1.0

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

@@ -0,0 +1,455 @@
+# Native Features - Expo SDK
+
+Patterns for native APIs and device features.
+
+---
+
+## Storage
+
+### NATIVE-001: Secure storage for sensitive data
+
+```typescript
+import * as SecureStore from 'expo-secure-store';
+
+const secureStorage = {
+  async get(key: string): Promise<string | null> {
+    try {
+      return await SecureStore.getItemAsync(key);
+    } catch {
+      return null;
+    }
+  },
+
+  async set(key: string, value: string): Promise<void> {
+    await SecureStore.setItemAsync(key, value);
+  },
+
+  async remove(key: string): Promise<void> {
+    await SecureStore.deleteItemAsync(key);
+  },
+};
+
+// Use for: tokens, credentials, sensitive user data
+await secureStorage.set('auth_token', token);
+```
+
+### NATIVE-002: AsyncStorage for preferences
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const storage = {
+  async get<T>(key: string): Promise<T | null> {
+    const value = await AsyncStorage.getItem(key);
+    return value ? JSON.parse(value) : null;
+  },
+
+  async set<T>(key: string, value: T): Promise<void> {
+    await AsyncStorage.setItem(key, JSON.stringify(value));
+  },
+
+  async remove(key: string): Promise<void> {
+    await AsyncStorage.removeItem(key);
+  },
+};
+
+// Use for: preferences, cache, non-sensitive data
+await storage.set('theme', 'dark');
+await storage.set('onboarded', true);
+```
+
+---
+
+## Camera & Images
+
+### NATIVE-003: Image picker
+
+```typescript
+import * as ImagePicker from 'expo-image-picker';
+
+async function pickImage() {
+  // Request permission
+  const { status } = await ImagePicker.requestMediaLibraryPermissionsAsync();
+
+  if (status !== 'granted') {
+    Alert.alert('Permission needed', 'Please allow access to photos.');
+    return null;
+  }
+
+  const result = await ImagePicker.launchImageLibraryAsync({
+    mediaTypes: ImagePicker.MediaTypeOptions.Images,
+    allowsEditing: true,
+    aspect: [1, 1],
+    quality: 0.8,
+  });
+
+  if (result.canceled) return null;
+
+  return result.assets[0];
+}
+
+async function takePhoto() {
+  const { status } = await ImagePicker.requestCameraPermissionsAsync();
+
+  if (status !== 'granted') {
+    Alert.alert('Permission needed', 'Please allow camera access.');
+    return null;
+  }
+
+  const result = await ImagePicker.launchCameraAsync({
+    allowsEditing: true,
+    aspect: [1, 1],
+    quality: 0.8,
+  });
+
+  if (result.canceled) return null;
+
+  return result.assets[0];
+}
+```
+
+### NATIVE-004: Image upload
+
+```typescript
+async function uploadImage(uri: string) {
+  const formData = new FormData();
+
+  formData.append('image', {
+    uri,
+    type: 'image/jpeg',
+    name: 'photo.jpg',
+  } as any);
+
+  const response = await fetch('/api/upload', {
+    method: 'POST',
+    body: formData,
+    headers: {
+      'Content-Type': 'multipart/form-data',
+    },
+  });
+
+  return response.json();
+}
+```
+
+---
+
+## Location
+
+### NATIVE-005: Get current location
+
+```typescript
+import * as Location from 'expo-location';
+
+async function getCurrentLocation() {
+  const { status } = await Location.requestForegroundPermissionsAsync();
+
+  if (status !== 'granted') {
+    throw new Error('Location permission denied');
+  }
+
+  const location = await Location.getCurrentPositionAsync({
+    accuracy: Location.Accuracy.Balanced,
+  });
+
+  return {
+    latitude: location.coords.latitude,
+    longitude: location.coords.longitude,
+  };
+}
+```
+
+### NATIVE-006: Watch location
+
+```typescript
+import * as Location from 'expo-location';
+
+function useLocation() {
+  const [location, setLocation] = useState<Location.LocationObject | null>(null);
+
+  useEffect(() => {
+    let subscription: Location.LocationSubscription;
+
+    (async () => {
+      const { status } = await Location.requestForegroundPermissionsAsync();
+      if (status !== 'granted') return;
+
+      subscription = await Location.watchPositionAsync(
+        {
+          accuracy: Location.Accuracy.High,
+          timeInterval: 5000,
+          distanceInterval: 10,
+        },
+        (newLocation) => {
+          setLocation(newLocation);
+        }
+      );
+    })();
+
+    return () => subscription?.remove();
+  }, []);
+
+  return location;
+}
+```
+
+---
+
+## Push Notifications
+
+### NATIVE-007: Register for notifications
+
+```typescript
+import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+import { Platform } from 'react-native';
+
+// Configure notification handling
+Notifications.setNotificationHandler({
+  handleNotification: async () => ({
+    shouldShowAlert: true,
+    shouldPlaySound: true,
+    shouldSetBadge: true,
+  }),
+});
+
+async function registerForPushNotifications() {
+  if (!Device.isDevice) {
+    console.log('Push notifications require a physical device');
+    return null;
+  }
+
+  const { status: existingStatus } = await Notifications.getPermissionsAsync();
+  let finalStatus = existingStatus;
+
+  if (existingStatus !== 'granted') {
+    const { status } = await Notifications.requestPermissionsAsync();
+    finalStatus = status;
+  }
+
+  if (finalStatus !== 'granted') {
+    return null;
+  }
+
+  // Android channel
+  if (Platform.OS === 'android') {
+    await Notifications.setNotificationChannelAsync('default', {
+      name: 'Default',
+      importance: Notifications.AndroidImportance.MAX,
+      vibrationPattern: [0, 250, 250, 250],
+    });
+  }
+
+  const token = await Notifications.getExpoPushTokenAsync({
+    projectId: 'your-project-id',
+  });
+
+  return token.data;
+}
+```
+
+### NATIVE-008: Handle notifications
+
+```typescript
+import * as Notifications from 'expo-notifications';
+import { router } from 'expo-router';
+
+function useNotificationHandlers() {
+  useEffect(() => {
+    // Notification received while app is foregrounded
+    const foregroundSubscription = Notifications.addNotificationReceivedListener(
+      (notification) => {
+        console.log('Notification received:', notification);
+      }
+    );
+
+    // User tapped notification
+    const responseSubscription = Notifications.addNotificationResponseReceivedListener(
+      (response) => {
+        const data = response.notification.request.content.data;
+
+        // Navigate based on notification data
+        if (data.screen) {
+          router.push(data.screen as string);
+        }
+      }
+    );
+
+    return () => {
+      foregroundSubscription.remove();
+      responseSubscription.remove();
+    };
+  }, []);
+}
+```
+
+---
+
+## Haptics
+
+### NATIVE-009: Haptic feedback
+
+```typescript
+import * as Haptics from 'expo-haptics';
+
+// Light - selections, toggles
+function handleSelect() {
+  Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+}
+
+// Medium - button presses
+function handlePress() {
+  Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium);
+}
+
+// Heavy - significant actions
+function handleDrop() {
+  Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Heavy);
+}
+
+// Success/error feedback
+function handleSuccess() {
+  Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+}
+
+function handleError() {
+  Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
+}
+
+// Selection changed (subtle)
+function handleSelectionChange() {
+  Haptics.selectionAsync();
+}
+```
+
+---
+
+## Biometrics
+
+### NATIVE-010: Biometric authentication
+
+```typescript
+import * as LocalAuthentication from 'expo-local-authentication';
+
+async function authenticateWithBiometrics() {
+  // Check hardware support
+  const hasHardware = await LocalAuthentication.hasHardwareAsync();
+  if (!hasHardware) {
+    return { success: false, error: 'No biometric hardware' };
+  }
+
+  // Check enrollment
+  const isEnrolled = await LocalAuthentication.isEnrolledAsync();
+  if (!isEnrolled) {
+    return { success: false, error: 'No biometrics enrolled' };
+  }
+
+  // Authenticate
+  const result = await LocalAuthentication.authenticateAsync({
+    promptMessage: 'Authenticate to continue',
+    cancelLabel: 'Cancel',
+    disableDeviceFallback: false, // Allow PIN fallback
+  });
+
+  return { success: result.success, error: result.error };
+}
+```
+
+---
+
+## Share & Clipboard
+
+### NATIVE-011: Share content
+
+```typescript
+import { Share } from 'react-native';
+
+async function shareContent(title: string, message: string, url?: string) {
+  try {
+    await Share.share({
+      title,
+      message: url ? `${message}\n${url}` : message,
+      url, // iOS only
+    });
+  } catch (error) {
+    console.error('Share failed:', error);
+  }
+}
+
+// Usage
+shareContent('Check this out!', 'Amazing article', 'https://example.com');
+```
+
+### NATIVE-012: Clipboard
+
+```typescript
+import * as Clipboard from 'expo-clipboard';
+
+async function copyToClipboard(text: string) {
+  await Clipboard.setStringAsync(text);
+  // Show toast/feedback
+}
+
+async function pasteFromClipboard(): Promise<string> {
+  return Clipboard.getStringAsync();
+}
+
+// With haptic feedback
+async function copyWithFeedback(text: string) {
+  await Clipboard.setStringAsync(text);
+  Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+  Toast.show('Copied!');
+}
+```
+
+---
+
+## Device Info
+
+### NATIVE-013: Device information
+
+```typescript
+import * as Device from 'expo-device';
+import { Platform } from 'react-native';
+
+const deviceInfo = {
+  brand: Device.brand,
+  modelName: Device.modelName,
+  osName: Device.osName,
+  osVersion: Device.osVersion,
+  isDevice: Device.isDevice,
+  platform: Platform.OS,
+};
+
+// Check if physical device
+if (!Device.isDevice) {
+  console.log('Running in simulator/emulator');
+}
+```
+
+### NATIVE-014: App state
+
+```typescript
+import { useAppState } from '@react-native-community/hooks';
+import { AppState } from 'react-native';
+
+function useAppStateListener(callback: (state: string) => void) {
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', callback);
+    return () => subscription.remove();
+  }, [callback]);
+}
+
+// Refresh data when app comes to foreground
+function DataRefresher() {
+  const queryClient = useQueryClient();
+
+  useAppStateListener((state) => {
+    if (state === 'active') {
+      queryClient.invalidateQueries();
+    }
+  });
+
+  return null;
+}
+```