@codyswann/lisa 1.47.1 → 1.48.0

package/expo/copy-overwrite/.claude/skills/expo-router-best-practices/SKILL.md

@@ -1,431 +0,0 @@
----
-name: expo-router-best-practices
-description: This skill should be used when creating new routes, configuring navigation layouts, implementing deep linking, or organizing the app/ directory structure in Expo Router projects. It provides best practices for file-based routing patterns.
----
-
-# Expo Router Best Practices
-
-This skill provides guidance for implementing file-based routing with Expo Router following established best practices and official documentation patterns.
-
-## Core Principles
-
-### 1. Routes Are Thin Wrappers
-
-Route files in the `app/` directory should be minimal pass-throughs to feature screen components. Business logic and complex UI components belong in feature directories, not route files.
-
-```typescript
-// app/players/[playerId]/compare.tsx - CORRECT
-import { Main } from "@/features/compare-players/screens/Main";
-
-/**
- * Compare players route.
- * URL: /players/[playerId]/compare
- */
-export default function CompareScreen() {
-  return <Main />;
-}
-```
-
-```typescript
-// app/players/[playerId]/compare.tsx - INCORRECT
-export default function CompareScreen() {
-  const { playerId } = useLocalSearchParams();
-  const [data, setData] = useState(null);
-  // ... 200 lines of business logic
-  return <ComplexUI />;
-}
-```
-
-### 2. Descriptive Component Names
-
-Use descriptive names for route components, not generic names.
-
-```typescript
-// CORRECT
-export default function CompareScreen() { ... }
-export default function PlayerDetailScreen() { ... }
-export default function SettingsScreen() { ... }
-
-// INCORRECT
-export default function Screen() { ... }
-export default function Page() { ... }
-export default function Index() { ... }  // only acceptable for index.tsx files
-```
-
-### 3. Document Route URLs in JSDoc
-
-Include the URL pattern in route file documentation.
-
-```typescript
-/**
- * Player detail route.
- * URL: /players/[playerId]
- */
-export default function PlayerDetailScreen() {
-  return <Main />;
-}
-```
-
-## File Structure Patterns
-
-### Directory Organization
-
-```
-app/
-├── _layout.tsx              # Root layout (initialization, providers)
-├── index.tsx                # Default route (/)
-├── +not-found.tsx           # 404 handling
-├── +html.tsx                # Web HTML customization (optional)
-├── (tabs)/                  # Tab navigator group
-│   ├── _layout.tsx          # Tab configuration
-│   ├── index.tsx            # Default tab
-│   ├── feed/                # Stack within tab
-│   │   ├── _layout.tsx
-│   │   ├── index.tsx
-│   │   └── [postId].tsx
-│   └── settings.tsx
-├── (auth)/                  # Auth screens group
-│   ├── sign-in.tsx
-│   └── create-account.tsx
-└── modal.tsx                # Modal route
-```
-
-### Route Notation Reference
-
-| Notation         | Purpose                     | Example              | URL      |
-| ---------------- | --------------------------- | -------------------- | -------- |
-| `file.tsx`       | Static route                | `about.tsx`          | `/about` |
-| `[param].tsx`    | Dynamic route               | `[userId].tsx`       | `/123`   |
-| `[...slug].tsx`  | Catch-all route             | `[...path].tsx`      | `/a/b/c` |
-| `(group)/`       | Route group (no URL impact) | `(tabs)/`            | `/`      |
-| `index.tsx`      | Default route               | `feed/index.tsx`     | `/feed`  |
-| `_layout.tsx`    | Layout definition           | `(tabs)/_layout.tsx` | -        |
-| `+not-found.tsx` | 404 handler                 | `+not-found.tsx`     | -        |
-
-## Layout Patterns
-
-### Root Layout
-
-The root `_layout.tsx` replaces `App.jsx/tsx`. Place initialization code here.
-
-```typescript
-// app/_layout.tsx
-import { useFonts } from "expo-font";
-import { Stack } from "expo-router";
-import * as SplashScreen from "expo-splash-screen";
-import { useEffect } from "react";
-
-SplashScreen.preventAutoHideAsync();
-
-export default function RootLayout() {
-  const [loaded] = useFonts({
-    SpaceMono: require("../assets/fonts/SpaceMono-Regular.ttf"),
-  });
-
-  useEffect(() => {
-    if (loaded) {
-      SplashScreen.hide();
-    }
-  }, [loaded]);
-
-  if (!loaded) {
-    return null;
-  }
-
-  return <Stack />;
-}
-```
-
-### Stack Layout
-
-```typescript
-// app/products/_layout.tsx
-import { Stack } from "expo-router";
-
-export const unstable_settings = {
-  initialRouteName: "index",
-};
-
-export default function ProductsLayout() {
-  return (
-    <Stack>
-      <Stack.Screen name="index" options={{ title: "Products" }} />
-      <Stack.Screen name="[productId]" options={{ headerShown: false }} />
-    </Stack>
-  );
-}
-```
-
-### Tab Layout
-
-```typescript
-// app/(tabs)/_layout.tsx
-import { Tabs } from "expo-router";
-import MaterialIcons from "@expo/vector-icons/MaterialIcons";
-
-export default function TabLayout() {
-  return (
-    <Tabs screenOptions={{ headerShown: false }}>
-      <Tabs.Screen
-        name="index"
-        options={{
-          title: "Home",
-          tabBarIcon: ({ color }) => (
-            <MaterialIcons size={28} name="home" color={color} />
-          ),
-        }}
-      />
-      <Tabs.Screen name="feed" options={{ title: "Feed" }} />
-      <Tabs.Screen name="settings" options={{ title: "Settings" }} />
-    </Tabs>
-  );
-}
-```
-
-### Protected Routes (SDK 53+)
-
-```typescript
-// app/_layout.tsx
-import { Stack } from "expo-router";
-import { useAuthState } from "@/hooks/useAuthState";
-
-export default function RootLayout() {
-  const { isLoggedIn } = useAuthState();
-
-  return (
-    <Stack>
-      <Stack.Protected guard={isLoggedIn}>
-        <Stack.Screen name="(tabs)" />
-        <Stack.Screen name="modal" options={{ presentation: "modal" }} />
-      </Stack.Protected>
-
-      <Stack.Protected guard={!isLoggedIn}>
-        <Stack.Screen name="sign-in" />
-        <Stack.Screen name="create-account" />
-      </Stack.Protected>
-    </Stack>
-  );
-}
-```
-
-## Navigation Patterns
-
-### Declarative Navigation (Preferred)
-
-```typescript
-import { Link } from "expo-router";
-
-// Basic link
-<Link href="/about">About</Link>
-
-// With custom component
-<Link href="/profile" asChild>
-  <Pressable>
-    <Text>Profile</Text>
-  </Pressable>
-</Link>
-
-// Dynamic route
-<Link href={{ pathname: "/user/[id]", params: { id: "123" } }}>
-  View User
-</Link>
-
-// With prefetching
-<Link href="/heavy-page" prefetch>Heavy Page</Link>
-```
-
-### Imperative Navigation
-
-```typescript
-import { useRouter } from "expo-router";
-
-export default function Component() {
-  const router = useRouter();
-
-  const handleNavigate = () => {
-    // Navigate (adds to history)
-    router.navigate("/about");
-
-    // Push (always adds to stack)
-    router.push("/details");
-
-    // Replace (no back navigation)
-    router.replace("/home");
-
-    // Back
-    router.back();
-
-    // Dynamic route
-    router.navigate({
-      pathname: "/user/[id]",
-      params: { id: "123" },
-    });
-  };
-
-  return <Button onPress={handleNavigate} title="Navigate" />;
-}
-```
-
-### Defensive Navigation Guards
-
-Always validate parameters before navigation to prevent broken URLs.
-
-```typescript
-const handleNavigation = useCallback(() => {
-  if (!entityId) {
-    console.error("Cannot navigate: entity ID is missing");
-    return;
-  }
-  router.push(`/players/${entityId}`);
-}, [entityId, router]);
-```
-
-### Reading Route Parameters
-
-```typescript
-import { useLocalSearchParams, useGlobalSearchParams } from "expo-router";
-
-export default function UserPage() {
-  // Local params (current route only)
-  const { id, tab } = useLocalSearchParams<{ id: string; tab?: string }>();
-
-  // Global params (entire URL)
-  const globalParams = useGlobalSearchParams();
-
-  return <Text>User ID: {id}</Text>;
-}
-```
-
-## Deep Linking
-
-### Configure URL Scheme
-
-In `app.json` or `app.config.js`:
-
-```json
-{
-  "expo": {
-    "scheme": "myapp"
-  }
-}
-```
-
-### Initial Route for Deep Links
-
-Ensure proper back navigation when deep linking.
-
-```typescript
-// app/feed/_layout.tsx
-export const unstable_settings = {
-  initialRouteName: "index",
-};
-
-export default function FeedLayout() {
-  return <Stack />;
-}
-```
-
-### Deep Link with Anchor
-
-```typescript
-// Forces initial route to load first
-<Link href="/feed/post/123" withAnchor>
-  View Post
-</Link>
-```
-
-## Common Patterns
-
-### Stacks Inside Tabs
-
-```
-app/
-├── (tabs)/
-│   ├── _layout.tsx         # Tab navigator
-│   ├── index.tsx           # Home tab
-│   ├── feed/               # Feed tab with stack
-│   │   ├── _layout.tsx     # Stack navigator
-│   │   ├── index.tsx       # Feed list
-│   │   └── [postId].tsx    # Post detail
-│   └── settings.tsx        # Settings tab
-```
-
-### Shared Routes Between Tabs
-
-```
-app/
-├── (tabs)/
-│   ├── _layout.tsx
-│   ├── (feed)/             # Feed tab group
-│   │   └── index.tsx
-│   ├── (search)/           # Search tab group
-│   │   └── index.tsx
-│   └── (feed,search)/      # Shared between both
-│       └── users/
-│           └── [userId].tsx
-```
-
-### Modal Routes
-
-```typescript
-// app/_layout.tsx
-<Stack>
-  <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
-  <Stack.Screen
-    name="modal"
-    options={{
-      presentation: "modal",
-      animation: "slide_from_bottom",
-    }}
-  />
-</Stack>
-```
-
-## Anti-Patterns to Avoid
-
-### 1. Business Logic in Route Files
-
-Route files should only import and render feature components.
-
-### 2. Deeply Nested Navigators
-
-Avoid nesting stacks within stacks unnecessarily. Use route groups instead.
-
-### 3. Missing initialRouteName
-
-Always set `initialRouteName` in stack layouts for proper deep link behavior.
-
-### 4. Hardcoded Navigation Paths
-
-Use typed routes or constants instead of string literals.
-
-```typescript
-// AVOID
-router.push("/players/123/compare");
-
-// PREFER
-router.push({
-  pathname: "/players/[playerId]/compare",
-  params: { playerId: "123" },
-});
-```
-
-### 5. Using window APIs Without Platform Checks
-
-```typescript
-// AVOID
-const width = window.innerWidth;
-
-// PREFER
-import { useWindowDimensions } from "react-native";
-const { width } = useWindowDimensions();
-```
-
-## Resources
-
-For detailed documentation on specific topics, refer to:
-
-- `references/official-docs.md` - Condensed official Expo Router documentation
-- `scripts/generate-route.py` - Route scaffolding script
-
-Official Documentation: https://docs.expo.dev/router/introduction/

package/expo/copy-overwrite/.claude/skills/expo-router-best-practices/references/official-docs.md

@@ -1,290 +0,0 @@
-# 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/)