# Hooks Review & Analysis

## Overview
This document provides a comprehensive analysis of all 15 custom hooks in the project. The hooks follow a DI pattern using `root.get(Controller)` for API access and use `handleError()` for error handling.

## Hooks Inventory

| Hook | Type | Loading | Error | Pagination | Refresh | Auto-load | Store |
|------|------|---------|-------|------------|---------|-----------|-------|
| `useActivates` | API | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `useCategories` | API | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ Zustand |
| `useTags` | API | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `useTemplates` | API | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `useTemplateDetail` | API | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
| `useTemplateActions` | API | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `useTemplateGenerations` | API | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `useSearchHistory` | Storage | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
| `useResource` | Utility | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `useColorScheme` | Native | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `useColorScheme.web` | Native | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `useThemeColor` | Utility | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `useError` | Utility | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |

## Detailed Analysis

### 1. useActivates
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-activates.ts`

**Purpose:** Fetches activity list from API

**Current Features:**
- Loading state
- Error handling
- Manual load function

**Missing Features:**
- ❌ Pagination support
- ❌ Refresh/refetch function
- ❌ LoadMore for infinite scroll
- ❌ Auto-load on mount
- ❌ Caching/memoization

**Issues:**
- Hardcoded defaults (page: 1, limit: 10)
- No pagination despite API supporting it
- Inconsistent with `useTemplates` pattern

---

### 2. useCategories
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-categories.ts`

**Purpose:** Fetches categories with Zustand global store

**Current Features:**
- Loading state (dual: store + local)
- Error handling
- Auto-load on mount
- Global state via Zustand
- Prevents duplicate loads

**Missing Features:**
- ❌ Pagination (uses limit: 1000)
- ❌ Refresh function
- ❌ Cache invalidation

**Issues:**
- Dual loading states (`store.loading` + `localLoading`) is confusing
- Large limit (1000) may cause performance issues
- `hasLoaded` flag prevents re-fetching even when needed
- No way to force refresh

---

### 3. useTags
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-tags.ts`

**Purpose:** Fetches tag list from API

**Current Features:**
- Loading state
- Error handling
- Manual load function

**Missing Features:**
- ❌ Pagination support
- ❌ Refresh/refetch function
- ❌ LoadMore for infinite scroll
- ❌ Auto-load on mount

**Issues:**
- Nearly identical to `useActivates` - could be abstracted
- Hardcoded OWNER_ID from env
- No pagination despite API supporting it

---

### 4. useTemplates
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-templates.ts`

**Purpose:** Fetches template list with full pagination support

**Current Features:**
- Loading state
- LoadingMore state for pagination
- Error handling
- Pagination with `loadMore()`
- Refresh with `refetch()`
- HasMore tracking
- Proper data accumulation

**Missing Features:**
- ❌ Auto-load on mount
- ❌ Pull-to-refresh integration
- ❌ Optimistic updates

**Issues:**
- None - this is the gold standard pattern

---

### 5. useTemplateDetail
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-template-detail.ts`

**Purpose:** Fetches single template details

**Current Features:**
- Loading state
- Error handling
- Execute function with params
- Refetch function

**Missing Features:**
- ❌ Auto-load on mount
- ❌ Caching (re-fetches same ID)

**Issues:**
- Requires manual `execute()` call
- No memoization of fetched data by ID

---

### 6. useTemplateActions
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-template-actions.ts`

**Purpose:** Runs template generation action

**Current Features:**
- Loading state
- Error handling
- Returns generationId on success

**Missing Features:**
- ❌ Success callback
- ❌ Optimistic updates
- ❌ Retry logic

**Issues:**
- Single action only (could support more actions)
- No mutation state management

---

### 7. useTemplateGenerations
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-template-generations.ts`

**Purpose:** Fetches template generation history with pagination

**Current Features:**
- Loading state
- LoadingMore state
- Error handling
- Pagination with `loadMore()`
- Refresh with `refetch()`
- HasMore tracking

**Missing Features:**
- ❌ Auto-load on mount
- ❌ Real-time updates for pending generations

**Issues:**
- HasMore logic uses length check instead of totalPages
- Inconsistent with `useTemplates` pagination pattern

---

### 8. useSearchHistory
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-search-history.ts`

**Purpose:** Manages local search history in AsyncStorage

**Current Features:**
- Loading state
- Auto-load on mount
- Add/remove/clear operations
- Max length limit (10)
- Deduplication

**Missing Features:**
- ❌ Error handling (silently fails)
- ❌ Sync across tabs/devices

**Issues:**
- No error state exposed
- Silent failures in catch blocks

---

### 9. useResource
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-resource.tsx`

**Purpose:** Transforms video URLs to Cloudflare CDN format with thumbnails

**Current Features:**
- Video detection
- Thumbnail generation
- URL transformation
- React Native resource handling

**Missing Features:**
- None - utility hook

**Issues:**
- None - works as intended

---

### 10. useColorScheme / useColorScheme.web
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-color-scheme.ts`

**Purpose:** Platform-specific color scheme detection

**Current Features:**
- Native: Direct export from React Native
- Web: Hydration-safe with SSR support

**Missing Features:**
- None - utility hook

**Issues:**
- None

---

### 11. useThemeColor
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-theme-color.ts`

**Purpose:** Returns theme-aware colors

**Current Features:**
- Light/dark mode support
- Prop overrides
- Fallback to theme constants

**Missing Features:**
- None - utility hook

**Issues:**
- None

---

### 12. useError (handleError utility)
**File:** `C:\Users\imeep\Desktop\shopify\expo-popcore-app\hooks\use-error.ts`

**Purpose:** Error handling wrapper for async operations

**Current Features:**
- Try-catch wrapper
- Consistent error format

**Missing Features:**
- ❌ Error logging/reporting
- ❌ Retry logic
- ❌ Error transformation

**Issues:**
- Very basic - could add more features

---

## Patterns & Inconsistencies

### Pattern A: Simple Load (useActivates, useTags)
```typescript
const { load, loading, error, data } = useHook()
// Manual load() call required
```

### Pattern B: Execute/Refetch (useTemplateDetail, useTemplateActions)
```typescript
const { execute, refetch, loading, error, data } = useHook()
// Manual execute(params) call required
```

### Pattern C: Full Pagination (useTemplates, useTemplateGenerations)
```typescript
const { execute, refetch, loadMore, loading, loadingMore, error, data, hasMore } = useHook()
// Manual execute() call required
```

### Pattern D: Auto-load with Store (useCategories)
```typescript
const { load, loading, error, data } = useCategories()
// Auto-loads on mount, uses Zustand store
```

### Pattern E: Storage (useSearchHistory)
```typescript
const { history, addToHistory, removeFromHistory, clearHistory, isLoading } = useSearchHistory()
// Auto-loads on mount
```

## Priority Enhancements

### P0 - Critical
1. **Standardize API hook pattern** - Choose one pattern for all API hooks
2. **Add auto-load option** - Most hooks require manual load() call
3. **Fix useCategories dual loading** - Simplify loading state management
4. **Add error handling to useSearchHistory** - Currently silently fails

### P1 - High
5. **Add pagination to useActivates** - Currently missing despite API support
6. **Add pagination to useTags** - Currently missing despite API support
7. **Standardize hasMore logic** - useTemplateGenerations uses length, useTemplates uses totalPages
8. **Add caching to useTemplateDetail** - Avoid re-fetching same ID

### P2 - Medium
9. **Add retry logic to API hooks** - Handle transient failures
10. **Add optimistic updates to useTemplateActions** - Better UX
11. **Add pull-to-refresh support** - Mobile UX pattern
12. **Abstract common API hook logic** - Reduce duplication

### P3 - Low
13. **Add error logging/reporting** - Track errors in production
14. **Add real-time updates** - For useTemplateGenerations pending status
15. **Add cache invalidation** - For useCategories

## Recommended Standard Pattern

Based on `useTemplates` (the most complete implementation), all API hooks should follow:

```typescript
export const useApiHook = (initialParams?: Params) => {
    const [loading, setLoading] = useState(false)
    const [loadingMore, setLoadingMore] = useState(false)
    const [error, setError] = useState<ApiError | null>(null)
    const [data, setData] = useState<Result>()
    const currentPageRef = useRef(1)
    const hasMoreRef = useRef(true)

    // Optional: Auto-load on mount
    useEffect(() => {
        if (autoLoad) execute()
    }, [])

    const execute = useCallback(async (params?: Params) => {
        // Implementation
    }, [initialParams])

    const loadMore = useCallback(async () => {
        // Implementation (if paginated)
    }, [loading, loadingMore, initialParams])

    const refetch = useCallback(() => {
        hasMoreRef.current = true
        return execute()
    }, [execute])

    return {
        data,
        loading,
        loadingMore, // if paginated
        error,
        execute,
        refetch,
        loadMore, // if paginated
        hasMore: hasMoreRef.current, // if paginated
    }
}
```

## Summary

**Total Hooks:** 13 (excluding test file and index)
- **API Hooks:** 7 (useActivates, useCategories, useTags, useTemplates, useTemplateDetail, useTemplateActions, useTemplateGenerations)
- **Storage Hooks:** 1 (useSearchHistory)
- **Utility Hooks:** 5 (useResource, useColorScheme x2, useThemeColor, useError)

**Key Findings:**
- `useTemplates` is the gold standard - most complete implementation
- Inconsistent patterns across API hooks (5 different patterns)
- Missing pagination in 4 out of 7 API hooks
- Only 2 hooks auto-load on mount
- Error handling is consistent but basic
- No caching/memoization strategy
- No retry logic anywhere

**Next Steps:**
1. Decide on standard pattern (recommend Pattern C with auto-load option)
2. Refactor all API hooks to match standard
3. Add missing pagination support
4. Implement caching strategy
5. Add retry logic and error reporting