codecruise 0.1.0

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

@@ -0,0 +1,445 @@
+# Navigation Rules - Expo Router
+
+File-based routing patterns for Expo.
+
+---
+
+## Route Structure
+
+### NAV-001: File naming conventions
+
+```
+app/
+├── _layout.tsx          # Root layout (required)
+├── index.tsx            # Home screen (/)
+├── settings.tsx         # Settings screen (/settings)
+├── (tabs)/              # Tab group (hidden from URL)
+│   ├── _layout.tsx      # Tab navigator
+│   ├── home.tsx         # /home
+│   └── profile.tsx      # /profile
+├── (auth)/              # Auth group (hidden from URL)
+│   ├── _layout.tsx      # Auth stack
+│   ├── login.tsx        # /login
+│   └── register.tsx     # /register
+├── users/
+│   ├── index.tsx        # /users
+│   └── [id].tsx         # /users/:id
+└── +not-found.tsx       # 404 screen
+```
+
+### NAV-002: Layout components
+
+```typescript
+// app/_layout.tsx - Root layout
+import { Stack } from 'expo-router';
+import { ThemeProvider } from '@/components/theme-provider';
+
+export default function RootLayout() {
+  return (
+    <ThemeProvider>
+      <Stack>
+        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+        <Stack.Screen name="(auth)" options={{ headerShown: false }} />
+        <Stack.Screen
+          name="modal"
+          options={{ presentation: 'modal' }}
+        />
+      </Stack>
+    </ThemeProvider>
+  );
+}
+
+// app/(tabs)/_layout.tsx - Tab layout
+import { Tabs } from 'expo-router';
+
+export default function TabLayout() {
+  return (
+    <Tabs>
+      <Tabs.Screen name="home" options={{ title: 'Home' }} />
+      <Tabs.Screen name="profile" options={{ title: 'Profile' }} />
+    </Tabs>
+  );
+}
+```
+
+### NAV-003: Group routes logically
+
+```typescript
+// Groups with () don't affect URL
+// (auth) group -> /login, not /(auth)/login
+
+// Shared layout for multiple screens
+// app/(settings)/_layout.tsx
+export default function SettingsLayout() {
+  return (
+    <Stack>
+      <Stack.Screen name="index" options={{ title: 'Settings' }} />
+      <Stack.Screen name="account" options={{ title: 'Account' }} />
+      <Stack.Screen name="privacy" options={{ title: 'Privacy' }} />
+    </Stack>
+  );
+}
+```
+
+---
+
+## Navigation Actions
+
+### NAV-004: Programmatic navigation
+
+```typescript
+import { router } from 'expo-router';
+
+// Push (adds to stack)
+router.push('/users/123');
+
+// Replace (replaces current)
+router.replace('/home');
+
+// Back
+router.back();
+
+// Dismiss modal
+router.dismiss();
+
+// Navigate (smart - uses push or replace)
+router.navigate('/settings');
+
+// Reset stack
+router.replace('/');
+```
+
+### NAV-005: Type-safe navigation
+
+```typescript
+// types/routes.ts
+export type AppRoutes = {
+  '/': undefined;
+  '/users/[id]': { id: string };
+  '/search': { query?: string };
+};
+
+// hooks/use-typed-router.ts
+import { router } from 'expo-router';
+
+export function useTypedRouter() {
+  return {
+    push: <T extends keyof AppRoutes>(
+      route: T,
+      params?: AppRoutes[T]
+    ) => {
+      router.push({ pathname: route, params } as any);
+    },
+  };
+}
+
+// Usage
+const { push } = useTypedRouter();
+push('/users/[id]', { id: '123' });
+```
+
+### NAV-006: With params and options
+
+```typescript
+// Navigate with params
+router.push({
+  pathname: '/users/[id]',
+  params: { id: '123' },
+});
+
+// With Link component
+import { Link } from 'expo-router';
+
+<Link href="/settings" asChild>
+  <Pressable>
+    <Text>Settings</Text>
+  </Pressable>
+</Link>
+
+<Link
+  href={{
+    pathname: '/users/[id]',
+    params: { id: user.id },
+  }}
+>
+  <Text>{user.name}</Text>
+</Link>
+```
+
+---
+
+## Route Parameters
+
+### NAV-007: Access route params
+
+```typescript
+// app/users/[id].tsx
+import { useLocalSearchParams } from 'expo-router';
+
+export default function UserScreen() {
+  // Type the params
+  const { id } = useLocalSearchParams<{ id: string }>();
+
+  // Use in query
+  const { data } = useQuery({
+    queryKey: ['user', id],
+    queryFn: () => fetchUser(id),
+  });
+
+  return <UserProfile user={data} />;
+}
+```
+
+### NAV-008: Query parameters
+
+```typescript
+// URL: /search?query=hello&category=books
+import { useLocalSearchParams } from 'expo-router';
+
+export default function SearchScreen() {
+  const { query, category } = useLocalSearchParams<{
+    query?: string;
+    category?: string;
+  }>();
+
+  // Handle arrays (multiple values)
+  const tags = useLocalSearchParams<{ tags: string[] }>();
+  // URL: /search?tags=a&tags=b -> tags.tags = ['a', 'b']
+}
+```
+
+### NAV-009: Catch-all routes
+
+```typescript
+// app/docs/[...slug].tsx
+// Matches /docs/a, /docs/a/b, /docs/a/b/c
+
+export default function DocsScreen() {
+  const { slug } = useLocalSearchParams<{ slug: string[] }>();
+  // /docs/api/auth -> slug = ['api', 'auth']
+
+  return <DocViewer path={slug.join('/')} />;
+}
+```
+
+---
+
+## Protected Routes
+
+### NAV-010: Auth-protected layouts
+
+```typescript
+// app/(protected)/_layout.tsx
+import { Redirect, Stack } from 'expo-router';
+import { useAuth } from '@/hooks/use-auth';
+
+export default function ProtectedLayout() {
+  const { user, isLoading } = useAuth();
+
+  if (isLoading) {
+    return <LoadingScreen />;
+  }
+
+  if (!user) {
+    return <Redirect href="/login" />;
+  }
+
+  return (
+    <Stack>
+      <Stack.Screen name="dashboard" />
+      <Stack.Screen name="settings" />
+    </Stack>
+  );
+}
+```
+
+### NAV-011: Redirect after auth
+
+```typescript
+// app/(auth)/login.tsx
+import { router, useLocalSearchParams } from 'expo-router';
+
+export default function LoginScreen() {
+  const { redirect } = useLocalSearchParams<{ redirect?: string }>();
+
+  const handleLogin = async (credentials) => {
+    await login(credentials);
+
+    // Redirect to original destination or home
+    router.replace(redirect ?? '/(tabs)/home');
+  };
+
+  return <LoginForm onSubmit={handleLogin} />;
+}
+
+// When redirecting to login
+router.push({
+  pathname: '/login',
+  params: { redirect: '/settings' },
+});
+```
+
+---
+
+## Modals & Sheets
+
+### NAV-012: Modal presentation
+
+```typescript
+// app/_layout.tsx
+<Stack>
+  <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+  <Stack.Screen
+    name="modal"
+    options={{
+      presentation: 'modal',
+      animation: 'slide_from_bottom',
+    }}
+  />
+  <Stack.Screen
+    name="sheet"
+    options={{
+      presentation: 'transparentModal',
+      animation: 'fade',
+    }}
+  />
+</Stack>
+
+// Open modal
+router.push('/modal');
+
+// Dismiss
+router.dismiss();
+// or
+router.back();
+```
+
+### NAV-013: Full-screen modals
+
+```typescript
+// app/create-post.tsx
+export default function CreatePostModal() {
+  return (
+    <View className="flex-1 bg-white">
+      <View className="flex-row justify-between p-4 border-b">
+        <Pressable onPress={() => router.dismiss()}>
+          <Text>Cancel</Text>
+        </Pressable>
+        <Pressable onPress={handleSave}>
+          <Text className="font-bold text-blue-500">Post</Text>
+        </Pressable>
+      </View>
+      <PostForm />
+    </View>
+  );
+}
+```
+
+---
+
+## Deep Linking
+
+### NAV-014: Configure deep links
+
+```javascript
+// app.json
+{
+  "expo": {
+    "scheme": "myapp",
+    "web": {
+      "bundler": "metro"
+    }
+  }
+}
+
+// Links:
+// myapp://users/123 -> /users/123
+// myapp://settings -> /settings
+```
+
+### NAV-015: Handle incoming links
+
+```typescript
+// app/_layout.tsx
+import { useURL } from 'expo-linking';
+import { router } from 'expo-router';
+
+export default function RootLayout() {
+  const url = useURL();
+
+  useEffect(() => {
+    if (url) {
+      // Expo Router handles most routing automatically
+      // Custom handling if needed:
+      const { path, queryParams } = Linking.parse(url);
+
+      if (path?.startsWith('invite/')) {
+        // Handle invite links specially
+        handleInvite(queryParams?.code);
+      }
+    }
+  }, [url]);
+
+  return <Stack />;
+}
+```
+
+---
+
+## Navigation State
+
+### NAV-016: Track navigation state
+
+```typescript
+import { usePathname, useSegments } from 'expo-router';
+
+function NavigationTracker() {
+  const pathname = usePathname();
+  const segments = useSegments();
+
+  useEffect(() => {
+    // Analytics
+    analytics.screen(pathname);
+  }, [pathname]);
+
+  // segments = ['(tabs)', 'home'] for /(tabs)/home
+  const isInTabs = segments[0] === '(tabs)';
+
+  return null;
+}
+```
+
+### NAV-017: Prevent back navigation
+
+```typescript
+import { useNavigation } from 'expo-router';
+import { useEffect } from 'react';
+
+export default function CheckoutScreen() {
+  const navigation = useNavigation();
+
+  useEffect(() => {
+    // Prevent hardware back on Android
+    const unsubscribe = navigation.addListener('beforeRemove', (e) => {
+      if (hasUnsavedChanges) {
+        e.preventDefault();
+        // Show confirmation
+        Alert.alert(
+          'Discard changes?',
+          'You have unsaved changes.',
+          [
+            { text: 'Stay', style: 'cancel' },
+            {
+              text: 'Discard',
+              style: 'destructive',
+              onPress: () => navigation.dispatch(e.data.action),
+            },
+          ]
+        );
+      }
+    });
+
+    return unsubscribe;
+  }, [hasUnsavedChanges]);
+}
+```