docs: add hooks review and finalize task plan
- Added comprehensive hooks/REVIEW.md analyzing all 15 hooks - Marked all completed phases in task_plan.md - Documented SDK limitations and TODO items All major development work completed: - 4 UI components created with TDD - 3 hooks enhanced with tests - 7 pages integrated with new components - All with proper pagination, refresh, and error handling Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
imeepos
parent
1d1d382822
commit
3171b7c3bf
|
|
@ -0,0 +1,404 @@
|
|||
# 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
|
||||
Loading…
Reference in New Issue