Hooks Directory

Location: src/hooks/

Purpose: Custom React hooks for reusable client-side logic. Hooks here are split between signature-entry workflow hooks (under add-signatures/) and shared UI/data utilities.

Structure

hooks/
├── add-signatures/                  # Signature entry workflow hooks
│   ├── useESValidation.tsx          # Per-row Elasticsearch validation against /api/essearch
│   ├── useFocusManagement.tsx       # Keyboard focus / tab order across signature rows
│   ├── usePostSubmitNavigation.tsx  # Decides where to send the user after signature submission
│   └── useSignatureForm.tsx         # Local form state + draft handling for the signature grid
│
├── use-debounce.ts                  # Generic debounce hook
├── use-media-query.tsx              # Tailwind/JS media-query observer
├── use-toast.ts                     # shadcn/ui toast bridge
├── useFetchUsersList.tsx            # Paginated user search (members / circulators picker)
├── useGetSignedURL.tsx              # Supabase Storage signed-URL generator
├── useHydration.ts                  # SSR hydration guard
├── usePermissionsManager.tsx        # (Disabled / legacy) — manage role↔permission edits client-side
└── usePetitionGetUsers.ts           # Petition-scoped user lookup

Hook Categories

Category	Hooks
Signature entry	useESValidation, useSignatureForm, useFocusManagement, usePostSubmitNavigation
Forms / lookups	useFetchUsersList, usePetitionGetUsers
UI utilities	use-toast, use-media-query, use-debounce, useHydration
Storage	useGetSignedURL
Legacy/disabled	usePermissionsManager (file kept as commented-out reference)

Notes

• useESValidation integrates with the duplicate-checker (/api/duplicate) and the Directus-backed Elasticsearch endpoint (/api/essearch). See complex-logic/signature-search--validation.
• Signature workflow hooks are designed to be composed by src/components/signature/** and rely on SignatureStepContext + signatureResultsContext.

---