# @datatechsolutions/ui

React component library for the Datatech Solutions platform. 130+ components spanning core UI, forms, data display, gestures, geo maps, notifications, and marketing layouts. Includes Brazil and US regional themes.

## Install

```bash
npm install @datatechsolutions/ui
```

**Published as source TypeScript** — no build step. Your bundler (Next.js, Vite, etc.) compiles it directly.

## Design Principles

- **iOS-inspired** — Liquid glass aesthetic, haptic feedback hooks, gesture-first mobile components
- **Accessible** — Built on Radix UI and Headless UI primitives
- **Motion-rich** — Framer Motion animations with reduced-motion support
- **Theme-aware** — Regional subdivision themes (Brazil states, US states) with palettes, flag URLs, and geo coordinates
- **i18n-ready** — Integrates with next-intl for localized labels

## Component Categories

| Category | Examples | Count |
|----------|---------|-------|
| Core | Button, Card, Input, Select, MetricCard | ~15 |
| Layout | HeroSection, Container, PageHeading, SafeArea, Dock | ~10 |
| Navigation | Pagination, Breadcrumb, NavigationProgress, LanguageSwitcher | ~5 |
| Forms | FormField, FormInput, FormSelect, FormToggle, FormCheckbox, BaseForm, StepFormPage, DatePicker, TimePicker | ~20 |
| Data Display | Table suite (12 variants), EntityCard, EntityDrawer, ListItem, CollapsibleRegionList | ~15 |
| Feedback | Spinner, StatusBadge, Badge, GrowthIndicator, ProcessStatusBadge, NotificationBadge | ~10 |
| Pickers | StationPicker, ChipPicker, SubdivisionPicker, BrandPicker, WheelPicker, MonthPicker | ~7 |
| Filters | FilterTileButton, FilterPill, SegmentedControl, CategoryTab/Tabs, SearchFilterToolbar | ~8 |
| Gestures | SwipeableRow (+ action presets), PullToRefreshContainer, EdgeSwipeIndicator | ~5 |
| States | EmptyState, ErrorState, OfflineState, NoResultsState, PageEmptyState, PageLoadingState | ~7 |
| Notifications | DynamicIsland, NotificationProvider, NotificationBellButton, NotificationHistoryDrawer | ~5 |
| Skeletons | CardGridSkeleton, StatCardSkeleton, RegionFilterSkeleton, AnalysisSkeleton, DockSkeleton | ~8 |
| Radiant (Marketing) | RadiantHeading, BentoCard, PlusGrid, RadiantStatCard, FeatureCard, AnimatedNumber | ~12 |
| Geo Maps | InteractiveGeoMap, GeoMapCanvas, MapZoomControls, GeoMapLegend | ~5 |
| Misc | Avatar, CookieConsent, DevModeBanner, Divider, Dropdown, ForceTouchMenu, ThemeToggle | ~15 |

## Themes

### Brazil
`src/lib/themes/brazil.ts` — State palettes, accent maps, coordinates, macro regions, flag URL helpers.

### US
`src/lib/themes/us.ts` — State palettes, accent maps, coordinates, macro regions, flag URL helpers.

### Custom
`registerSubdivisionTheme()` to add your own regional theme with palettes, flags, and geo data.

## Hooks

| Hook | Purpose |
|------|---------|
| `useHaptic` / `triggerHaptic` | Haptic feedback for touch interactions |
| `usePullToRefresh` | Pull-to-refresh interaction pattern |
| `useGeoMapState` | State management for interactive geo maps |
| `useNotifications` | Notification system state and actions |

## Styles

Import the liquid glass stylesheet:

```typescript
import '@datatechsolutions/ui/styles'
```

## Peer Dependencies

@headlessui/react, @heroicons/react, @radix-ui/react-dialog, @radix-ui/react-popover, clsx, date-fns, framer-motion, lucide-react, next, next-intl, react, react-dom, react-transition-progress, d3-geo, zod.

## Scripts

| Script | Command | Description |
|--------|---------|-------------|
| `test` | `vitest run` | Run component tests |
| `test:watch` | `vitest` | Watch mode |
| `lint` | `tsc --noEmit` | Type check (no build step) |
