Skip to main content

React Hooks API Reference

This document provides API documentation for the custom React hooks in the Kuviq application.

Overview​

Custom hooks encapsulate reusable stateful logic and provide clean interfaces for components. They follow React conventions and handle:

  • Data fetching and caching
  • Form management
  • Authentication state
  • Permission checks
  • Real-time updates

Data Fetching Hooks​

useInspections​

Fetches and manages inspection data with filtering, sorting, and pagination.

import { useInspections } from '@/hooks/useInspections'

Parameters​

interface UseInspectionsParams {
  filters?: Record<string, string | string[]>
  search?: string
  sortField?: string
  sortDirection?: 'asc' | 'desc'
  page?: number
  pageSize?: number
}

Returns​

{
  inspections: Inspection[]
  loading: boolean
  error: ContextError | null
  totalCount: number
}

Example​

const { inspections, loading, error } = useInspections({
  filters: { status: 'pending' },
  sortField: 'dueDate',
  sortDirection: 'asc',
  pageSize: 25,
})

useItems​

Fetches and manages item data.

import { useItems } from '@/hooks/useItems'

Returns​

{
  items: Item[]
  loading: boolean
  error: ContextError | null
  refetch: () => Promise<void>
  createItem: (item: Partial<Item>) => Promise<Item>
  updateItem: (id: string, updates: Partial<Item>) => Promise<void>
  deleteItem: (id: string) => Promise<void>
}

useInspectionTemplates​

Manages inspection templates.

import { useInspectionTemplates } from '@/hooks/useInspectionTemplates'

Returns​

{
  templates: InspectionTemplate[]
  loading: boolean
  error: ContextError | null
  createTemplate: (template: Partial<InspectionTemplate>) => Promise<InspectionTemplate>
  updateTemplate: (id: string, updates: Partial<InspectionTemplate>) => Promise<void>
  deleteTemplate: (id: string) => Promise<void>
}

useInspectionSchedules​

Manages inspection schedules.

import { useInspectionSchedules } from '@/hooks/useInspectionSchedules'

Returns​

{
  schedules: InspectionSchedule[]
  loading: boolean
  error: ContextError | null
  createSchedule: (schedule: Partial<InspectionSchedule>) => Promise<InspectionSchedule>
  updateSchedule: (id: string, updates: Partial<InspectionSchedule>) => Promise<void>
  deleteSchedule: (id: string) => Promise<void>
}

useGroups​

Manages item groups.

import { useGroups } from '@/hooks/useGroups'

Returns​

{
  groups: ItemGroup[]
  loading: boolean
  error: ContextError | null
  createGroup: (group: Partial<ItemGroup>) => Promise<ItemGroup>
  updateGroup: (id: string, updates: Partial<ItemGroup>) => Promise<void>
  deleteGroup: (id: string) => Promise<void>
}

Authentication & Authorization Hooks​

useAuth​

Provides authentication state and methods.

import { useAuth } from '@/hooks/useAuth'

Returns​

{
  user: User | null
  loading: boolean
  error: Error | null
  signIn: (email: string, password: string) => Promise<void>
  signOut: () => Promise<void>
  signUp: (email: string, password: string, displayName: string) => Promise<void>
  resetPassword: (email: string) => Promise<void>
  updateProfile: (updates: Partial<User>) => Promise<void>
}

usePermissions​

Checks user permissions for actions.

import { usePermissions } from '@/hooks/usePermissions'

Returns​

{
  hasPermission: (permission: Permission) => boolean
  hasAnyPermission: (permissions: Permission[]) => boolean
  hasAllPermissions: (permissions: Permission[]) => boolean
  userRole: UserRole
  isAdmin: boolean
  isSuperAdmin: boolean
}

Example​

const { hasPermission, isAdmin } = usePermissions()

if (hasPermission('items.create')) {
  // Show create button
}

useSession​

Manages user session with timeout warnings.

import { useSession } from '@/hooks/useSession'

Returns​

{
  isSessionValid: boolean
  timeRemaining: number // seconds
  showWarning: boolean
  extendSession: () => void
  endSession: () => void
}

useFeatureGate​

Checks if features are available for the current subscription.

import { useFeatureGate } from '@/hooks/useFeatureGate'

Parameters​

useFeatureGate(featureName: string)

Returns​

{
  hasAccess: boolean
  loading: boolean
  feature: FeatureConfig | null
}

Example​

const { hasAccess } = useFeatureGate('advanced_reports')

if (!hasAccess) {
  return <UpgradePrompt feature="Advanced Reports" />
}

Form Hooks​

useFormManagement​

Provides form state management with validation.

import { useFormManagement } from '@/hooks/useFormManagement'

Parameters​

interface UseFormManagementParams<T> {
  initialValues: T
  validationSchema?: ValidationSchema<T>
  onSubmit: (values: T) => Promise<void>
}

Returns​

{
  values: T
  errors: Record<string, string>
  touched: Record<string, boolean>
  isSubmitting: boolean
  isValid: boolean
  isDirty: boolean
  handleChange: (field: string, value: any) => void
  handleBlur: (field: string) => void
  handleSubmit: (e?: FormEvent) => Promise<void>
  resetForm: () => void
  setFieldValue: (field: string, value: any) => void
  setFieldError: (field: string, error: string) => void
}

useFormSubmission​

Handles form submission with loading and error states.

import { useFormSubmission } from '@/hooks/useFormSubmission'

Returns​

{
  isSubmitting: boolean
  error: Error | null
  submit: <T>(fn: () => Promise<T>) => Promise<T | undefined>
  reset: () => void
}

useFormOptimization​

Optimizes form performance for large forms.

import { useFormOptimization } from '@/hooks/useFormOptimization'

Returns​

{
  debouncedValue: <T>(value: T, delay?: number) => T
  memoizedCallback: <T extends Function>(callback: T, deps: any[]) => T
}

useMemoizedValidation​

Memoizes validation results for performance.

import { useMemoizedValidation } from '@/hooks/useMemoizedValidation'

Utility Hooks​

useDebounce​

Debounces a value.

import { useDebounce } from '@/hooks/useDebounce'

Parameters​

useDebounce<T>(value: T, delay: number): T

Example​

const [searchTerm, setSearchTerm] = useState('')
const debouncedSearch = useDebounce(searchTerm, 300)

// Use debouncedSearch for API calls

useNetwork​

Monitors network connectivity.

import { useNetwork } from '@/hooks/useNetwork'

Returns​

{
  isOnline: boolean
  wasOffline: boolean // was offline since mount
  connectionType: string | null // 'wifi', '4g', etc.
}

useNotification​

Shows toast notifications.

import { useNotification } from '@/hooks/useNotification'

Returns​

{
  showSuccess: (message: string) => void
  showError: (message: string | Error) => void
  showWarning: (message: string) => void
  showInfo: (message: string) => void
}

Example​

const { showSuccess, showError } = useNotification()

try {
  await saveItem(item)
  showSuccess('Item saved successfully')
} catch (error) {
  showError(error)
}

useInfiniteScroll​

Implements infinite scroll pagination.

import { useInfiniteScroll } from '@/hooks/useInfiniteScroll'

Parameters​

interface UseInfiniteScrollParams {
  fetchMore: () => Promise<void>
  hasMore: boolean
  threshold?: number // pixels from bottom
}

Returns​

{
  ref: RefObject<HTMLElement> // attach to scroll container
  isLoading: boolean
}

Export Hooks​

useExport​

Handles data export functionality.

import { useExport } from '@/hooks/useExport'

Returns​

{
  exportToExcel: (data: any[], filename: string) => Promise<void>
  exportToCsv: (data: any[], filename: string) => Promise<void>
  exportToPdf: (data: any[], config: PdfConfig) => Promise<void>
  isExporting: boolean
  error: Error | null
}

useDashboardExport​

Exports dashboard data and charts.

import { useDashboardExport } from '@/hooks/useDashboardExport'

Returns​

{
  exportDashboard: (format: 'pdf' | 'png') => Promise<void>
  isExporting: boolean
}

useUnifiedImportExport​

Unified import/export operations.

import { useUnifiedImportExport } from '@/hooks/useUnifiedImportExport'

Returns​

{
  importData: (entityType: string, file: File) => Promise<ImportResult>
  exportData: (entityType: string, format: string) => Promise<void>
  isImporting: boolean
  isExporting: boolean
  importProgress: number
  exportProgress: number
  error: Error | null
}

Performance Hooks​

usePerformanceMonitoring​

Monitors component performance.

import { usePerformanceMonitoring } from '@/hooks/usePerformanceMonitoring'

Parameters​

usePerformanceMonitoring(componentName: string)

Returns​

{
  trackRender: () => void
  trackInteraction: (name: string) => void
}

useMonitoring​

Application-level monitoring integration.

import { useMonitoring } from '@/hooks/useMonitoring'

Returns​

{
  trackError: (error: Error, context?: object) => void
  trackEvent: (name: string, properties?: object) => void
  startSpan: (name: string) => Span
}

useImagePreloader​

Preloads images for better UX.

import { useImagePreloader } from '@/hooks/useImagePreloader'

Parameters​

useImagePreloader(urls: string[])

Returns​

{
  loaded: boolean
  progress: number // 0-100
  errors: string[] // failed URLs
}

Inspection Execution Hooks​

useInspectionExecution​

Manages inspection execution workflow.

import { useInspectionExecution } from '@/hooks/useInspectionExecution'

Returns​

{
  currentInspection: Inspection | null
  inspectionData: InspectionData
  isExecuting: boolean
  startInspection: (inspectionId: string) => Promise<void>
  pauseInspection: () => Promise<void>
  resumeInspection: () => Promise<void>
  completeInspection: (results: InspectionResults) => Promise<void>
  cancelInspection: () => Promise<void>
  updateResponse: (elementId: string, value: any) => void
}

useInspectionTracking​

Tracks inspection progress and time.

import { useInspectionTracking } from '@/hooks/useInspectionTracking'

Returns​

{
  startTime: Date | null
  elapsedTime: number // seconds
  completedElements: number
  totalElements: number
  progress: number // 0-100
}

useInspectionFilters​

URL-based inspection filtering.

import { useInspectionFilters } from '@/hooks/useInspectionFilters'

Returns​

{
  filters: Record<string, string>
  activeView: string | null
  getViewTitle: () => string
  setFilter: (key: string, value: string) => void
  clearFilters: () => void
  hasActiveFilters: boolean
}

Upload Hooks​

useUploadProgress​

Tracks file upload progress.

import { useUploadProgress } from '@/hooks/useUploadProgress'

Returns​

{
  progress: number // 0-100
  isUploading: boolean
  error: Error | null
  upload: (file: File, path: string) => Promise<string> // returns URL
  cancel: () => void
}

Best Practices​

Error Handling​

All hooks that fetch data include error states:

const { data, loading, error } = useSomeHook()

if (error) {
  return <ErrorDisplay error={error} />
}

if (loading) {
  return <LoadingSpinner />
}

Cleanup​

Hooks automatically handle cleanup on unmount. No manual cleanup needed.

Memoization​

Use hooks with useMemo and useCallback when passing to child components:

const filters = useMemo(() => ({ status: 'active' }), [])
const { items } = useItems(filters)

Context Dependencies​

Many hooks require context providers:

// App.tsx
<AuthProvider>
  <OrganizationProvider>
    <FirestoreProvider>
      {children}
    </FirestoreProvider>
  </OrganizationProvider>
</AuthProvider>