@codyswann/lisa 2.195.4 → 2.195.7

package/plugins/lisa-expo/.codex-plugin/skills/expo-router-best-practices/references/official-docs.md

@@ -0,0 +1,290 @@
+# Expo Router Official Documentation Reference
+
+This reference contains condensed official documentation from Expo Router.
+
+## Core Concepts
+
+### The Six Rules of Expo Router
+
+1. **All screens/pages are files inside the app directory** - Every file inside `app/` has a default export that defines a distinct page (except `_layout` files).
+
+2. **All pages have a URL** - All pages have a URL path matching the file's location, enabling universal deep-linking across platforms.
+
+3. **First index.tsx is the initial route** - Expo Router looks for the first `index.tsx` file matching the `/` URL. Use route groups `(groupName)` to organize without affecting URLs.
+
+4. **Root \_layout.tsx replaces App.jsx/tsx** - The root layout is rendered before any other route and contains initialization code (fonts, splash screen, providers).
+
+5. **Non-navigation components live outside app directory** - Components, hooks, utilities belong in other top-level directories. Alternatively, use `src/app/` with `src/components/`, `src/utils/`, etc.
+
+6. **It's still React Navigation under the hood** - Expo Router translates file structure into React Navigation components. Same options apply for styling/configuration.
+
+## Navigation Methods
+
+### Link Component (Declarative)
+
+```typescript
+import { Link } from "expo-router";
+
+// Basic
+<Link href="/about">About</Link>
+
+// With custom component
+<Link href="/profile" asChild>
+  <Pressable><Text>Profile</Text></Pressable>
+</Link>
+
+// Dynamic route with params object
+<Link href={{ pathname: "/user/[id]", params: { id: "bacon" } }}>
+  View User
+</Link>
+
+// Prefetching
+<Link href="/about" prefetch />
+```
+
+### useRouter Hook (Imperative)
+
+```typescript
+import { useRouter } from "expo-router";
+
+const router = useRouter();
+
+// Navigate (adds to history, won't duplicate)
+router.navigate("/about");
+
+// Push (always adds to stack)
+router.push("/details");
+
+// Replace (no back navigation)
+router.replace("/home");
+
+// Back
+router.back();
+
+// Dismiss modal
+router.dismiss();
+
+// Dismiss all modals
+router.dismissAll();
+
+// Can go back check
+router.canGoBack();
+```
+
+### Redirect Component
+
+```typescript
+import { Redirect } from "expo-router";
+
+export default function Page() {
+  if (!isAuthenticated) {
+    return <Redirect href="/sign-in" />;
+  }
+  return <Content />;
+}
+```
+
+## Route Parameters
+
+### Reading Parameters
+
+```typescript
+import { useLocalSearchParams, useGlobalSearchParams } from "expo-router";
+
+// Local params (current route only)
+const { id, tab } = useLocalSearchParams<{ id: string; tab?: string }>();
+
+// Global params (entire URL tree)
+const params = useGlobalSearchParams();
+```
+
+### Updating Parameters Without Navigation
+
+```typescript
+// Via Link
+<Link href={{ pathname: "/current", params: { filter: "new" } }}>
+  Update Filter
+</Link>
+
+// Via router
+router.setParams({ filter: "new" });
+```
+
+## Layout Components
+
+### Stack Navigator
+
+```typescript
+import { Stack } from "expo-router";
+
+export default function Layout() {
+  return (
+    <Stack
+      screenOptions={{
+        headerStyle: { backgroundColor: "#f4511e" },
+        headerTintColor: "#fff",
+      }}
+    >
+      <Stack.Screen name="index" options={{ title: "Home" }} />
+      <Stack.Screen name="[id]" options={{ headerShown: false }} />
+    </Stack>
+  );
+}
+```
+
+### Tab Navigator
+
+```typescript
+import { Tabs } from "expo-router";
+
+export default function Layout() {
+  return (
+    <Tabs screenOptions={{ tabBarActiveTintColor: "blue" }}>
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: "Home",
+          tabBarIcon: ({ color }) => <Icon name="home" color={color} />,
+        }}
+      />
+    </Tabs>
+  );
+}
+```
+
+### Drawer Navigator
+
+```typescript
+import { Drawer } from "expo-router/drawer";
+
+export default function Layout() {
+  return (
+    <Drawer>
+      <Drawer.Screen name="index" options={{ title: "Home" }} />
+      <Drawer.Screen name="settings" options={{ title: "Settings" }} />
+    </Drawer>
+  );
+}
+```
+
+### Slot (No Navigator)
+
+```typescript
+import { Slot } from "expo-router";
+
+export default function Layout() {
+  return (
+    <>
+      <Header />
+      <Slot />
+      <Footer />
+    </>
+  );
+}
+```
+
+## Protected Routes (SDK 53+)
+
+```typescript
+import { Stack } from "expo-router";
+
+export default function RootLayout() {
+  const { isLoggedIn } = useAuth();
+
+  return (
+    <Stack>
+      <Stack.Protected guard={isLoggedIn}>
+        <Stack.Screen name="(app)" />
+      </Stack.Protected>
+      <Stack.Protected guard={!isLoggedIn}>
+        <Stack.Screen name="sign-in" />
+      </Stack.Protected>
+    </Stack>
+  );
+}
+```
+
+## Special Files
+
+| File                 | Purpose                        |
+| -------------------- | ------------------------------ |
+| `_layout.tsx`        | Define navigator for directory |
+| `index.tsx`          | Default route for directory    |
+| `+not-found.tsx`     | 404 error page                 |
+| `+html.tsx`          | Custom HTML wrapper (web)      |
+| `+native-intent.tsx` | Handle unmatched deep links    |
+
+## unstable_settings
+
+```typescript
+export const unstable_settings = {
+  // Initial route for deep links
+  initialRouteName: "index",
+
+  // Anchor for route groups
+  anchor: "(root)",
+};
+```
+
+## Testing
+
+```typescript
+import { renderRouter, screen } from "expo-router/testing-library";
+
+it("navigates correctly", async () => {
+  renderRouter(
+    {
+      index: () => <Home />,
+      "user/[id]": () => <User />,
+    },
+    { initialUrl: "/" }
+  );
+
+  expect(screen).toHavePathname("/");
+});
+```
+
+### Test Matchers
+
+- `expect(screen).toHavePathname("/path")`
+- `expect(screen).toHavePathnameWithParams("/path?q=test")`
+- `expect(screen).toHaveSegments(["[id]"])`
+- `expect(screen).useLocalSearchParams({ id: "123" })`
+
+## Hooks Reference
+
+| Hook                          | Purpose                 |
+| ----------------------------- | ----------------------- |
+| `useRouter()`                 | Imperative navigation   |
+| `useLocalSearchParams()`      | Current route params    |
+| `useGlobalSearchParams()`     | All URL params          |
+| `useSegments()`               | Current route segments  |
+| `usePathname()`               | Current pathname        |
+| `useNavigation()`             | React Navigation object |
+| `useFocusEffect()`            | Run effect on focus     |
+| `useNavigationContainerRef()` | Navigation ref          |
+
+## URL Scheme Configuration
+
+```json
+// app.json
+{
+  "expo": {
+    "scheme": "myapp",
+    "web": {
+      "bundler": "metro"
+    }
+  }
+}
+```
+
+## Sources
+
+- [Introduction to Expo Router](https://docs.expo.dev/router/introduction/)
+- [Core Concepts](https://docs.expo.dev/router/basics/core-concepts/)
+- [Router Notation](https://docs.expo.dev/router/basics/notation/)
+- [Navigation Layouts](https://docs.expo.dev/router/basics/layout/)
+- [Navigation](https://docs.expo.dev/router/basics/navigation/)
+- [Common Patterns](https://docs.expo.dev/router/basics/common-navigation-patterns/)
+- [Authentication](https://docs.expo.dev/router/advanced/authentication/)
+- [Testing](https://docs.expo.dev/router/reference/testing/)

package/plugins/lisa-expo/.codex-plugin/skills/expo-router-best-practices/scripts/generate-route.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+"""
+Route Generator for Expo Router
+
+Creates route files following best practices:
+- Thin wrapper pattern (imports feature screen)
+- Descriptive component names
+- JSDoc with URL pattern
+- Proper TypeScript types
+
+Usage:
+    generate-route.py <route-path> <feature-name> [--layout] [--dynamic]
+
+Examples:
+    generate-route.py players/compare compare-players
+    generate-route.py players/[playerId] player-detail --dynamic
+    generate-route.py (tabs)/feed feed --layout
+"""
+
+import sys
+import os
+from pathlib import Path
+
+
+def to_pascal_case(name: str) -> str:
+    """Convert hyphen-case to PascalCase."""
+    return ''.join(word.capitalize() for word in name.replace('_', '-').split('-'))
+
+
+def get_route_url(route_path: str) -> str:
+    """Convert file path to URL pattern."""
+    # Remove file extension if present
+    route_path = route_path.replace('.tsx', '')
+
+    # Handle route groups - they don't appear in URL
+    parts = []
+    for part in route_path.split('/'):
+        if not part.startswith('(') or not part.endswith(')'):
+            parts.append(part)
+
+    url = '/' + '/'.join(parts)
+    return url if url != '/' else '/'
+
+
+def generate_route_content(route_path: str, feature_name: str, is_dynamic: bool = False) -> str:
+    """Generate route file content."""
+    pascal_feature = to_pascal_case(feature_name)
+
+    # Determine screen name from route path
+    path_parts = route_path.replace('.tsx', '').split('/')
+    last_part = path_parts[-1] if path_parts else 'Index'
+
+    # Handle dynamic routes
+    if last_part.startswith('[') and last_part.endswith(']'):
+        # [playerId] -> PlayerDetail
+        param_name = last_part[1:-1]
+        screen_name = to_pascal_case(param_name.replace('Id', '')) + 'DetailScreen'
+    elif last_part == 'index':
+        screen_name = pascal_feature + 'Screen'
+    else:
+        screen_name = to_pascal_case(last_part) + 'Screen'
+
+    url_pattern = get_route_url(route_path)
+
+    return f'''import {{ Main }} from "@/features/{feature_name}/screens/Main";
+
+/**
+ * {screen_name.replace('Screen', '')} route.
+ * URL: {url_pattern}
+ */
+export default function {screen_name}() {{
+  return <Main />;
+}}
+'''
+
+
+def generate_layout_content(route_path: str) -> str:
+    """Generate layout file content."""
+    # Determine if this is tabs, stack, or drawer
+    path_parts = route_path.split('/')
+
+    # Check for (tabs) in path
+    is_tabs = any(part == '(tabs)' for part in path_parts)
+
+    if is_tabs:
+        return '''import { Tabs } from "expo-router";
+
+/**
+ * Tab layout configuration.
+ */
+export default function TabLayout() {
+  return (
+    <Tabs screenOptions={{ headerShown: false }}>
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: "Home",
+        }}
+      />
+      {/* Add more tabs here */}
+    </Tabs>
+  );
+}
+'''
+    else:
+        return '''import { Stack } from "expo-router";
+
+export const unstable_settings = {
+  initialRouteName: "index",
+};
+
+/**
+ * Stack layout configuration.
+ */
+export default function StackLayout() {
+  return (
+    <Stack>
+      <Stack.Screen name="index" options={{ headerShown: true }} />
+    </Stack>
+  );
+}
+'''
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: generate-route.py <route-path> <feature-name> [--layout] [--dynamic]")
+        print("")
+        print("Arguments:")
+        print("  route-path    Path relative to app/ directory (e.g., players/[playerId])")
+        print("  feature-name  Feature directory name (e.g., player-detail)")
+        print("")
+        print("Options:")
+        print("  --layout      Generate a _layout.tsx file instead of a route")
+        print("  --dynamic     Indicates this is a dynamic route with parameters")
+        print("")
+        print("Examples:")
+        print("  generate-route.py players/compare compare-players")
+        print("  generate-route.py players/[playerId] player-detail --dynamic")
+        print("  generate-route.py \"(tabs)/feed\" feed --layout")
+        sys.exit(1)
+
+    route_path = sys.argv[1]
+    feature_name = sys.argv[2]
+    is_layout = '--layout' in sys.argv
+    is_dynamic = '--dynamic' in sys.argv
+
+    if is_layout:
+        content = generate_layout_content(route_path)
+        filename = '_layout.tsx'
+    else:
+        content = generate_route_content(route_path, feature_name, is_dynamic)
+        # Determine filename from path
+        path_parts = route_path.split('/')
+        filename = path_parts[-1] if path_parts else 'index'
+        if not filename.endswith('.tsx'):
+            filename += '.tsx'
+
+    print(f"Generated {filename}:")
+    print("-" * 40)
+    print(content)
+    print("-" * 40)
+    print("")
+    print("To create this file, save the above content to:")
+    print(f"  app/{route_path.rsplit('/', 1)[0] + '/' if '/' in route_path else ''}{filename}")
+
+
+if __name__ == "__main__":
+    main()