workforce-pay-bill-p/LIBRARIES.md

WorkForce Pro - Developer Libraries

Overview

This document provides an overview of the expanded custom hook library and UI component library available in the WorkForce Pro application. These libraries provide production-ready, reusable building blocks for rapid feature development.

Custom Hook Library

The application includes 40+ custom React hooks organized into the following categories:

State Management (8 hooks)

• useToggle - Boolean state toggle
• usePrevious - Access previous value
• useLocalStorage - Persist to localStorage
• useDisclosure - Modal/drawer state
• useUndo - Undo/redo functionality
• useFormState - Form state with validation
• useArray - Array manipulation utilities
• useMap - Map data structure utilities
• useSet - Set data structure utilities

Async Operations (5 hooks)

• useAsync - Async operation handling
• useDebounce - Debounce values
• useThrottle - Throttle function calls
• useInterval - Declarative intervals
• useTimeout - Declarative timeouts

UI & Interaction (12 hooks)

• useMediaQuery - Media query matching
• useIsMobile - Mobile detection
• useWindowSize - Window dimensions
• useScrollPosition - Scroll tracking
• useOnClickOutside - Outside click detection
• useIntersectionObserver - Visibility detection
• useKeyboardShortcut - Keyboard shortcuts
• useIdleTimer - Idle state detection
• useCopyToClipboard - Copy to clipboard
• useClipboard - Enhanced clipboard
• useFocusTrap - Focus management
• useCountdown - Countdown timer

Data Management (5 hooks)

• useFilter - Array filtering
• useSort - Array sorting
• usePagination - Data pagination
• useSelection - Multi-select management
• useTable - Complete table utilities

Forms & Validation (4 hooks)

• useFormValidation - Form validation
• useWizard - Multi-step wizards
• useMultiStepForm - Advanced multi-step forms
• useSteps - Step navigation
• useConfirmation - Confirmation dialogs

Browser & Navigation (2 hooks)

• useQueryParams - URL query params
• useDownload - File downloads

Application-Specific (2 hooks)

• useNotifications - Notification system
• useSampleData - Sample data initialization

UI Component Library

The application includes 70+ UI components from shadcn v4, plus custom components:

Display Components

• EmptyState - Empty state placeholder
• StatusBadge - Status indicators
• StatCard - Simple metric cards
• MetricCard - Advanced metric cards with trends
• DataList - Key-value pair lists
• DataTable - Generic data tables
• Timeline - Event timelines
• List / ListItem - Structured lists
• Chip - Tag chips
• Badge - Status badges
• Avatar - User avatars
• Card - Content cards
• Alert - Alert messages

Layout Components

• PageHeader / PageTitle / PageDescription / PageActions - Page headers
• Section / SectionHeader / SectionTitle / SectionContent - Content sections
• Stack - Flex containers with spacing
• Grid - Responsive grid layouts
• Separator - Dividers
• Divider - Enhanced dividers with labels
• ScrollArea - Scrollable containers
• Resizable - Resizable panels

Input Components

• Input - Text inputs
• Textarea - Multi-line text
• Select - Dropdowns
• Checkbox - Checkboxes
• RadioGroup - Radio buttons
• Switch - Toggle switches
• Slider - Range sliders
• Calendar - Date picker
• SearchInput - Search with clear
• FileUpload - File upload with drag-drop
• InputOTP - OTP inputs
• Form - Form components

Navigation Components

• Tabs - Tab navigation
• Breadcrumb - Breadcrumb navigation
• Pagination - Full pagination
• QuickPagination - Simple pagination
• Stepper - Multi-step indicator
• NavigationMenu - Navigation menus
• Menubar - Menu bars
• Sidebar - Application sidebar

Modal & Dialog Components

• Dialog - Standard dialogs
• AlertDialog - Confirmation dialogs
• Modal / ModalHeader / ModalBody / ModalFooter - Custom modals
• Sheet - Side panels
• Drawer - Drawer panels
• Popover - Popovers
• HoverCard - Hover cards
• Tooltip - Tooltips
• ContextMenu - Context menus
• DropdownMenu - Dropdown menus

Filter & Search Components

• FilterBar / FilterGroup - Filter controls
• Tag / TagGroup - Removable tags
• Command - Command palette
• Combobox - Searchable selects

Utility Components

• LoadingSpinner - Loading indicators
• LoadingOverlay - Full-screen loading
• Progress - Progress bars
• Skeleton - Loading skeletons
• CopyButton - Copy to clipboard
• CodeBlock - Code display
• InfoBox - Info messages
• Kbd - Keyboard shortcuts display
• SortableHeader - Sortable table headers

Chart Components

• Chart - Recharts wrapper with themes

Best Practices

When to Use Hooks vs Components

Use Hooks When:

• Managing state or side effects
• Sharing logic between components
• Accessing browser APIs
• Managing complex interactions

Use Components When:

• Creating reusable UI elements
• Defining visual structures
• Composing layouts
• Building forms

Performance Considerations

1. Memoization: Most hooks use useCallback and useMemo internally
2. Lazy Loading: Import only what you need
3. State Colocation: Keep state close to where it's used
4. Pagination: Use useTable or usePagination for large datasets

Composition Patterns

Hooks Composition:

function useTimesheetForm() {
  const { values, errors, handleChange } = useFormState(initialData)
  const { isOpen, open, close } = useDisclosure()
  const { copy } = useClipboard()
  
  return { values, errors, handleChange, isOpen, open, close, copy }
}

Component Composition:

<PageHeader>
  <PageHeaderRow>
    <PageTitle>Title</PageTitle>
    <PageActions>
      <Button>Action</Button>
    </PageActions>
  </PageHeaderRow>
</PageHeader>

Quick Reference

Most Commonly Used Hooks

1. useKV - Data persistence (Spark SDK)
2. useTable - Table management
3. useDisclosure - Modal state
4. useFormState - Form handling
5. useDebounce - Search optimization

Most Commonly Used Components

1. Button - Primary actions
2. Card - Content containers
3. Dialog - Modals and confirmations
4. Input / Select - Form fields
5. Table - Data display
6. Badge - Status indicators
7. Skeleton - Loading states

Documentation

• Hooks: See /src/hooks/README.md for detailed examples
• Components: See /src/components/ui/README.md for usage guides
• Types: All hooks and components are fully typed with TypeScript

Support

For questions or issues with the libraries, please refer to:

1. Individual hook/component files for implementation details
2. README files in respective directories
3. TypeScript type definitions for API contracts