feat: implement client-side state management hooks

- Created useSearch hook for search state and debouncing - Created useFilters hook for filter state management - Created useOptimisticUpdate hook for optimistic UI updates - Created useScrollPosition hook for scroll preservation - Updated SearchBar, GlobalSearch, and ListDetailView to use new hooks - Added comprehensive documentation for all hooks Validates: Requirements 6.4, 7.3, 7.4, 8.3 Task: 9. Implement client-side state management
2025-12-01 20:11:41 +00:00
parent 0143097e69
commit e2e3581d06
10 changed files with 821 additions and 52 deletions
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -0,0 +1,232 @@
+# Custom Hooks Documentation
+
+This directory contains custom React hooks for client-side state management in the Ultimate Lists App.
+
+## Hooks Overview
+
+### `useSearch`
+
+Manages search state with debouncing functionality.
+
+**Features:**
+- Automatic debouncing of search queries
+- Immediate clear functionality
+- Tracks debouncing state
+
+**Usage:**
+```typescript
+import { useSearch } from '@/hooks'
+
+function MyComponent() {
+  const { query, setQuery, debouncedQuery, isDebouncing, clearSearch } = useSearch({
+    debounceMs: 300,
+    onSearch: async (query) => {
+      // Perform search with debounced query
+      const results = await searchItems(query)
+    }
+  })
+
+  return (
+    <input 
+      value={query} 
+      onChange={(e) => setQuery(e.target.value)} 
+    />
+  )
+}
+```
+
+### `useFilters`
+
+Manages filter state for sorting and filtering items.
+
+**Features:**
+- Centralized filter state management
+- Detects active filters
+- Easy filter clearing
+- Individual filter updates
+
+**Usage:**
+```typescript
+import { useFilters } from '@/hooks'
+
+function MyComponent() {
+  const { filters, setFilters, updateFilter, clearFilters, hasActiveFilters } = useFilters({
+    initialFilters: { sortBy: 'createdAt' },
+    onFiltersChange: async (filters) => {
+      // Apply filters
+      const results = await getItemsByFilter(listId, filters)
+    }
+  })
+
+  return (
+    <div>
+      <button onClick={() => updateFilter('priority', 'high')}>
+        High Priority
+      </button>
+      {hasActiveFilters && (
+        <button onClick={clearFilters}>Clear Filters</button>
+      )}
+    </div>
+  )
+}
+```
+
+### `useOptimisticUpdate`
+
+Provides optimistic UI updates for better perceived performance.
+
+**Features:**
+- Immediate UI feedback
+- Automatic rollback on error
+- Pending state tracking
+- Error handling
+
+**Usage:**
+```typescript
+import { useOptimisticUpdate } from '@/hooks'
+
+function MyComponent() {
+  const { optimisticData, isPending, error, performUpdate } = useOptimisticUpdate({
+    onUpdate: async (data) => {
+      await updateItem(data.id, data)
+    },
+    onError: (error) => {
+      console.error('Update failed:', error)
+    }
+  })
+
+  const handleToggle = async () => {
+    await performUpdate({ id: '123', completed: true })
+  }
+
+  return (
+    <button onClick={handleToggle} disabled={isPending}>
+      {isPending ? 'Updating...' : 'Toggle'}
+    </button>
+  )
+}
+```
+
+### `useOptimisticList`
+
+Specialized hook for managing lists with optimistic updates.
+
+**Usage:**
+```typescript
+import { useOptimisticList } from '@/hooks'
+
+function MyComponent({ initialItems }) {
+  const { optimisticList, isPending, addItem, updateItem, removeItem } = useOptimisticList(
+    initialItems,
+    async (updatedList) => {
+      // Sync with server
+      await syncList(updatedList)
+    }
+  )
+
+  return (
+    <div>
+      {optimisticList.map(item => (
+        <div key={item.id}>
+          {item.title}
+          <button onClick={() => removeItem(item.id)}>Delete</button>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### `useScrollPosition`
+
+Preserves scroll position across navigation for better UX.
+
+**Features:**
+- Automatic scroll position saving
+- Restoration on component mount
+- Debounced save operations
+- SessionStorage-based persistence
+
+**Usage:**
+```typescript
+import { useScrollPosition } from '@/hooks'
+
+function MyComponent({ listId }) {
+  // Automatically saves and restores scroll position
+  useScrollPosition({ 
+    key: `list-${listId}`,
+    enabled: true,
+    debounceMs: 100
+  })
+
+  return (
+    <div>
+      {/* Your scrollable content */}
+    </div>
+  )
+}
+```
+
+### `useContainerScrollPosition`
+
+Similar to `useScrollPosition` but for specific container elements.
+
+**Usage:**
+```typescript
+import { useContainerScrollPosition } from '@/hooks'
+
+function MyComponent({ listId }) {
+  const { containerRef } = useContainerScrollPosition({ 
+    key: `container-${listId}` 
+  })
+
+  return (
+    <div ref={containerRef} style={{ height: '400px', overflow: 'auto' }}>
+      {/* Your scrollable content */}
+    </div>
+  )
+}
+```
+
+## Requirements Validation
+
+These hooks implement the following requirements from the specification:
+
+- **Requirement 6.4**: Filter state management and clearing
+- **Requirement 7.3**: Visual feedback for user actions (optimistic updates)
+- **Requirement 7.4**: Scroll position preservation
+- **Requirement 8.3**: Search clearing and restoration
+
+## Best Practices
+
+1. **Search Debouncing**: Use appropriate debounce times (300ms is a good default)
+2. **Filter State**: Keep filter state in sync with URL params for shareable links
+3. **Optimistic Updates**: Always provide rollback on error
+4. **Scroll Position**: Use unique keys for different views to avoid conflicts
+5. **Error Handling**: Always handle errors in async callbacks
+
+## Testing
+
+These hooks are designed to be testable with React Testing Library:
+
+```typescript
+import { renderHook, act } from '@testing-library/react'
+import { useSearch } from '@/hooks'
+
+test('useSearch debounces queries', async () => {
+  const onSearch = jest.fn()
+  const { result } = renderHook(() => useSearch({ onSearch, debounceMs: 100 }))
+  
+  act(() => {
+    result.current.setQuery('test')
+  })
+  
+  expect(onSearch).not.toHaveBeenCalled()
+  
+  await act(async () => {
+    await new Promise(resolve => setTimeout(resolve, 150))
+  })
+  
+  expect(onSearch).toHaveBeenCalledWith('test')
+})
+```
--- a/hooks/index.ts
+++ b/hooks/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Custom hooks for client-side state management
+ * Implements task 9 from the Ultimate Lists App specification
+ */
+
+export { useSearch } from './useSearch'
+export { useFilters } from './useFilters'
+export type { FilterState } from './useFilters'
+export { useOptimisticUpdate, useOptimisticList } from './useOptimisticUpdate'
+export { useScrollPosition, useContainerScrollPosition } from './useScrollPosition'
--- a/hooks/useFilters.ts
+++ b/hooks/useFilters.ts
@@ -0,0 +1,97 @@
+'use client'
+
+import { useState, useCallback, useMemo } from 'react'
+
+export interface FilterState {
+  priority: 'low' | 'medium' | 'high' | null
+  completed: boolean | null
+  tags: string[]
+  dueDateRange: { start: Date | null; end: Date | null }
+  sortBy: 'createdAt' | 'dueDate' | 'priority' | 'title'
+  sortOrder: 'asc' | 'desc'
+}
+
+interface UseFiltersOptions {
+  initialFilters?: Partial<FilterState>
+  onFiltersChange?: (filters: FilterState) => void | Promise<void>
+}
+
+interface UseFiltersReturn {
+  filters: FilterState
+  setFilters: (filters: FilterState) => void
+  updateFilter: <K extends keyof FilterState>(key: K, value: FilterState[K]) => void
+  clearFilters: () => void
+  hasActiveFilters: boolean
+}
+
+const DEFAULT_FILTERS: FilterState = {
+  priority: null,
+  completed: null,
+  tags: [],
+  dueDateRange: { start: null, end: null },
+  sortBy: 'createdAt',
+  sortOrder: 'desc'
+}
+
+/**
+ * Custom hook for managing filter state
+ * Validates: Requirements 6.4
+ */
+export function useFilters(options: UseFiltersOptions = {}): UseFiltersReturn {
+  const { initialFilters = {}, onFiltersChange } = options
+  
+  const [filters, setFiltersState] = useState<FilterState>({
+    ...DEFAULT_FILTERS,
+    ...initialFilters
+  })
+
+  // Check if any filters are active (excluding sort options)
+  const hasActiveFilters = useMemo(() => {
+    return (
+      filters.priority !== null ||
+      filters.completed !== null ||
+      filters.tags.length > 0 ||
+      filters.dueDateRange.start !== null ||
+      filters.dueDateRange.end !== null
+    )
+  }, [filters])
+
+  // Set filters with callback
+  const setFilters = useCallback((newFilters: FilterState) => {
+    setFiltersState(newFilters)
+    if (onFiltersChange) {
+      onFiltersChange(newFilters)
+    }
+  }, [onFiltersChange])
+
+  // Update a single filter property
+  const updateFilter = useCallback(<K extends keyof FilterState>(
+    key: K,
+    value: FilterState[K]
+  ) => {
+    setFiltersState(prev => {
+      const newFilters = { ...prev, [key]: value }
+      if (onFiltersChange) {
+        onFiltersChange(newFilters)
+      }
+      return newFilters
+    })
+  }, [onFiltersChange])
+
+  // Clear all filters (reset to defaults)
+  const clearFilters = useCallback(() => {
+    const clearedFilters = { ...DEFAULT_FILTERS }
+    setFiltersState(clearedFilters)
+    if (onFiltersChange) {
+      onFiltersChange(clearedFilters)
+    }
+  }, [onFiltersChange])
+
+  return {
+    filters,
+    setFilters,
+    updateFilter,
+    clearFilters,
+    hasActiveFilters
+  }
+}
--- a/hooks/useOptimisticUpdate.ts
+++ b/hooks/useOptimisticUpdate.ts
@@ -0,0 +1,138 @@
+'use client'
+
+import { useState, useCallback, useTransition } from 'react'
+
+interface UseOptimisticUpdateOptions<T> {
+  onUpdate: (data: T) => Promise<void>
+  onError?: (error: Error) => void
+}
+
+interface UseOptimisticUpdateReturn<T> {
+  optimisticData: T | null
+  isPending: boolean
+  error: Error | null
+  performUpdate: (data: T) => Promise<void>
+  reset: () => void
+}
+
+/**
+ * Custom hook for optimistic UI updates
+ * Provides immediate UI feedback while server action is processing
+ * Validates: Requirements 7.3
+ */
+export function useOptimisticUpdate<T>(
+  options: UseOptimisticUpdateOptions<T>
+): UseOptimisticUpdateReturn<T> {
+  const { onUpdate, onError } = options
+  
+  const [isPending, startTransition] = useTransition()
+  const [optimisticData, setOptimisticData] = useState<T | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+
+  const performUpdate = useCallback(async (data: T) => {
+    // Clear any previous errors
+    setError(null)
+    
+    // Set optimistic data immediately for instant UI feedback
+    setOptimisticData(data)
+
+    // Perform the actual update in a transition
+    startTransition(async () => {
+      try {
+        await onUpdate(data)
+        // Clear optimistic data after successful update
+        setOptimisticData(null)
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Update failed')
+        setError(error)
+        // Clear optimistic data on error
+        setOptimisticData(null)
+        
+        if (onError) {
+          onError(error)
+        }
+      }
+    })
+  }, [onUpdate, onError])
+
+  const reset = useCallback(() => {
+    setOptimisticData(null)
+    setError(null)
+  }, [])
+
+  return {
+    optimisticData,
+    isPending,
+    error,
+    performUpdate,
+    reset
+  }
+}
+
+/**
+ * Simplified hook for optimistic list updates
+ * Useful for managing lists of items with optimistic updates
+ */
+export function useOptimisticList<T extends { id: string }>(
+  initialData: T[],
+  onUpdate: (data: T[]) => Promise<void>
+) {
+  const [optimisticList, setOptimisticList] = useState<T[]>(initialData)
+  const [isPending, startTransition] = useTransition()
+
+  const addItem = useCallback((item: T) => {
+    setOptimisticList(prev => [...prev, item])
+    
+    startTransition(async () => {
+      try {
+        await onUpdate([...optimisticList, item])
+      } catch (error) {
+        // Rollback on error
+        setOptimisticList(initialData)
+        console.error('Failed to add item:', error)
+      }
+    })
+  }, [optimisticList, initialData, onUpdate])
+
+  const updateItem = useCallback((id: string, updates: Partial<T>) => {
+    setOptimisticList(prev =>
+      prev.map(item => (item.id === id ? { ...item, ...updates } : item))
+    )
+    
+    startTransition(async () => {
+      try {
+        const updatedList = optimisticList.map(item =>
+          item.id === id ? { ...item, ...updates } : item
+        )
+        await onUpdate(updatedList)
+      } catch (error) {
+        // Rollback on error
+        setOptimisticList(initialData)
+        console.error('Failed to update item:', error)
+      }
+    })
+  }, [optimisticList, initialData, onUpdate])
+
+  const removeItem = useCallback((id: string) => {
+    setOptimisticList(prev => prev.filter(item => item.id !== id))
+    
+    startTransition(async () => {
+      try {
+        const updatedList = optimisticList.filter(item => item.id !== id)
+        await onUpdate(updatedList)
+      } catch (error) {
+        // Rollback on error
+        setOptimisticList(initialData)
+        console.error('Failed to remove item:', error)
+      }
+    })
+  }, [optimisticList, initialData, onUpdate])
+
+  return {
+    optimisticList,
+    isPending,
+    addItem,
+    updateItem,
+    removeItem
+  }
+}
--- a/hooks/useScrollPosition.ts
+++ b/hooks/useScrollPosition.ts
@@ -0,0 +1,208 @@
+'use client'
+
+import { useEffect, useRef, useCallback } from 'react'
+
+interface UseScrollPositionOptions {
+  key: string
+  enabled?: boolean
+  debounceMs?: number
+}
+
+/**
+ * Custom hook for preserving scroll position across navigation
+ * Validates: Requirements 7.4
+ */
+export function useScrollPosition(options: UseScrollPositionOptions) {
+  const { key, enabled = true, debounceMs = 100 } = options
+  
+  const scrollPositionRef = useRef<number>(0)
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const isRestoringRef = useRef(false)
+
+  // Save scroll position to sessionStorage
+  const saveScrollPosition = useCallback((position: number) => {
+    if (!enabled) return
+    
+    try {
+      sessionStorage.setItem(`scroll-${key}`, position.toString())
+      scrollPositionRef.current = position
+    } catch (error) {
+      console.warn('Failed to save scroll position:', error)
+    }
+  }, [key, enabled])
+
+  // Restore scroll position from sessionStorage
+  const restoreScrollPosition = useCallback(() => {
+    if (!enabled) return
+    
+    try {
+      const savedPosition = sessionStorage.getItem(`scroll-${key}`)
+      if (savedPosition !== null) {
+        const position = parseInt(savedPosition, 10)
+        if (!isNaN(position)) {
+          isRestoringRef.current = true
+          window.scrollTo(0, position)
+          scrollPositionRef.current = position
+          
+          // Reset flag after a short delay
+          setTimeout(() => {
+            isRestoringRef.current = false
+          }, 100)
+        }
+      }
+    } catch (error) {
+      console.warn('Failed to restore scroll position:', error)
+    }
+  }, [key, enabled])
+
+  // Clear saved scroll position
+  const clearScrollPosition = useCallback(() => {
+    try {
+      sessionStorage.removeItem(`scroll-${key}`)
+      scrollPositionRef.current = 0
+    } catch (error) {
+      console.warn('Failed to clear scroll position:', error)
+    }
+  }, [key])
+
+  // Handle scroll events with debouncing
+  useEffect(() => {
+    if (!enabled) return
+
+    const handleScroll = () => {
+      // Don't save position if we're currently restoring
+      if (isRestoringRef.current) return
+
+      // Clear existing timeout
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+
+      // Debounce the save operation
+      timeoutRef.current = setTimeout(() => {
+        const position = window.scrollY || window.pageYOffset
+        saveScrollPosition(position)
+      }, debounceMs)
+    }
+
+    window.addEventListener('scroll', handleScroll, { passive: true })
+
+    return () => {
+      window.removeEventListener('scroll', handleScroll)
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+    }
+  }, [enabled, debounceMs, saveScrollPosition])
+
+  // Restore scroll position on mount
+  useEffect(() => {
+    if (enabled) {
+      // Use requestAnimationFrame to ensure DOM is ready
+      requestAnimationFrame(() => {
+        restoreScrollPosition()
+      })
+    }
+  }, [enabled, restoreScrollPosition])
+
+  return {
+    saveScrollPosition,
+    restoreScrollPosition,
+    clearScrollPosition,
+    currentPosition: scrollPositionRef.current
+  }
+}
+
+/**
+ * Hook for preserving scroll position within a specific container element
+ */
+export function useContainerScrollPosition(options: UseScrollPositionOptions) {
+  const { key, enabled = true, debounceMs = 100 } = options
+  
+  const containerRef = useRef<HTMLElement | null>(null)
+  const scrollPositionRef = useRef<number>(0)
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const isRestoringRef = useRef(false)
+
+  // Save scroll position
+  const saveScrollPosition = useCallback((position: number) => {
+    if (!enabled) return
+    
+    try {
+      sessionStorage.setItem(`container-scroll-${key}`, position.toString())
+      scrollPositionRef.current = position
+    } catch (error) {
+      console.warn('Failed to save container scroll position:', error)
+    }
+  }, [key, enabled])
+
+  // Restore scroll position
+  const restoreScrollPosition = useCallback(() => {
+    if (!enabled || !containerRef.current) return
+    
+    try {
+      const savedPosition = sessionStorage.getItem(`container-scroll-${key}`)
+      if (savedPosition !== null) {
+        const position = parseInt(savedPosition, 10)
+        if (!isNaN(position)) {
+          isRestoringRef.current = true
+          containerRef.current.scrollTop = position
+          scrollPositionRef.current = position
+          
+          setTimeout(() => {
+            isRestoringRef.current = false
+          }, 100)
+        }
+      }
+    } catch (error) {
+      console.warn('Failed to restore container scroll position:', error)
+    }
+  }, [key, enabled])
+
+  // Clear saved scroll position
+  const clearScrollPosition = useCallback(() => {
+    try {
+      sessionStorage.removeItem(`container-scroll-${key}`)
+      scrollPositionRef.current = 0
+    } catch (error) {
+      console.warn('Failed to clear container scroll position:', error)
+    }
+  }, [key])
+
+  // Set up scroll listener on container
+  useEffect(() => {
+    if (!enabled || !containerRef.current) return
+
+    const container = containerRef.current
+
+    const handleScroll = () => {
+      if (isRestoringRef.current) return
+
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+
+      timeoutRef.current = setTimeout(() => {
+        const position = container.scrollTop
+        saveScrollPosition(position)
+      }, debounceMs)
+    }
+
+    container.addEventListener('scroll', handleScroll, { passive: true })
+
+    return () => {
+      container.removeEventListener('scroll', handleScroll)
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+    }
+  }, [enabled, debounceMs, saveScrollPosition])
+
+  return {
+    containerRef,
+    saveScrollPosition,
+    restoreScrollPosition,
+    clearScrollPosition,
+    currentPosition: scrollPositionRef.current
+  }
+}
--- a/hooks/useSearch.ts
+++ b/hooks/useSearch.ts
@@ -0,0 +1,84 @@
+'use client'
+
+import { useState, useEffect, useCallback, useRef } from 'react'
+
+interface UseSearchOptions {
+  debounceMs?: number
+  onSearch?: (query: string) => void | Promise<void>
+}
+
+interface UseSearchReturn {
+  query: string
+  setQuery: (query: string) => void
+  debouncedQuery: string
+  isDebouncing: boolean
+  clearSearch: () => void
+}
+
+/**
+ * Custom hook for managing search state with debouncing
+ * Validates: Requirements 6.4, 8.3
+ */
+export function useSearch(options: UseSearchOptions = {}): UseSearchReturn {
+  const { debounceMs = 300, onSearch } = options
+  
+  const [query, setQuery] = useState('')
+  const [debouncedQuery, setDebouncedQuery] = useState('')
+  const [isDebouncing, setIsDebouncing] = useState(false)
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null)
+
+  // Debounce the query
+  useEffect(() => {
+    // If query is empty, update immediately
+    if (!query.trim()) {
+      setDebouncedQuery('')
+      setIsDebouncing(false)
+      return
+    }
+
+    setIsDebouncing(true)
+
+    // Clear existing timeout
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+    }
+
+    // Set new timeout
+    timeoutRef.current = setTimeout(() => {
+      setDebouncedQuery(query)
+      setIsDebouncing(false)
+    }, debounceMs)
+
+    // Cleanup
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+    }
+  }, [query, debounceMs])
+
+  // Call onSearch callback when debounced query changes
+  useEffect(() => {
+    if (onSearch) {
+      onSearch(debouncedQuery)
+    }
+  }, [debouncedQuery, onSearch])
+
+  // Clear search function
+  const clearSearch = useCallback(() => {
+    setQuery('')
+    setDebouncedQuery('')
+    setIsDebouncing(false)
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+    }
+  }, [])
+
+  return {
+    query,
+    setQuery,
+    debouncedQuery,
+    isDebouncing,
+    clearSearch
+  }
+}