npm package: @neowhale/ui
Description: Shared React component library for WhaleTools storefronts
Author: WhaleTools
Latest version: 0.1.8

<p align="center">
  <img src="whale-logo.png" alt="WhaleTools" width="80" />
</p>

<h1 align="center">@neowhale/ui</h1>

<p align="center">
  React component library for WhaleTools storefronts — animation, commerce, layout, theming, and utilities.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@neowhale/ui"><img src="https://img.shields.io/npm/v/@neowhale/ui.svg" alt="npm version" /></a>
  <a href="https://whaletools.dev/docs"><img src="https://img.shields.io/badge/docs-whaletools.dev-blue" alt="docs" /></a>
  <a href="https://github.com/neowhale/ui/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@neowhale/ui" alt="license" /></a>
</p>

---

## Install

```bash
npm install @neowhale/ui
```

**Peer dependencies:** `react >=18`, `react-dom >=18`, `framer-motion >=12`, `@neowhale/storefront >=0.1.0`, and optionally `next >=14`.

## Entry Points

| Import | Description |
|--------|-------------|
| `@neowhale/ui` | Everything (re-exports all subpaths) |
| `@neowhale/ui/animation` | Scroll reveals, parallax, cursors, magnetic buttons, text effects |
| `@neowhale/ui/commerce` | Cart, checkout, product cards, search, navbar, account |
| `@neowhale/ui/layout` | Provider factory, footer |
| `@neowhale/ui/utility` | Lightbox, lazy video, scroll progress, focus trap |
| `@neowhale/ui/theme` | Theme provider, tokens, dark theme defaults |

## Quick Start

```tsx
import { createProviders } from '@neowhale/ui/layout'
import { ThemeProvider } from '@neowhale/ui/theme'
import { CartDrawer, ProductCard } from '@neowhale/ui/commerce'
import { ScrollReveal } from '@neowhale/ui/animation'

const Providers = createProviders({
  storeId: 'your-store-id',
  apiKey: 'your-api-key',
})

export default function App({ children }) {
  return (
    <Providers>
      <ThemeProvider>
        <CartDrawer />
        {children}
      </ThemeProvider>
    </Providers>
  )
}
```

## Components

### Animation

| Component | Description |
|-----------|-------------|
| `ScrollReveal` | Intersection-observer animations — fadeUp, fadeIn, scaleIn, blurIn, stagger |
| `ParallaxSection` | Image parallax with configurable speed and overlay |
| `TextReveal` | Word-by-word or line-by-line text reveal on scroll |
| `MagneticButton` | Cursor-attracted button with configurable strength |
| `CustomCursor` | Custom cursor overlay with configurable color and size |
| `FilmGrain` | Film grain texture overlay |
| `SmoothScroll` | Smooth scroll wrapper |

### Commerce

| Component | Description |
|-----------|-------------|
| `CartDrawer` | Slide-out cart with quantity controls, promo slots, shipping info |
| `CartButton` | Cart icon with item count badge |
| `AddToCart` | Add-to-cart button with product binding |
| `ProductCard` | Product card with image, price, tag |
| `CheckoutForm` | Full checkout flow with address, payment, order creation |
| `PaymentForm` | Standalone payment form (card/cash) |
| `SearchBar` | Product search with keyboard shortcuts |
| `Navbar` | Storefront navigation bar |
| `StatusBadge` | Order/status badge with automatic color mapping |
| `AccountDashboard` | Customer account overview |
| `OrderHistory` | Order list with status tracking |

### Layout

| Export | Description |
|--------|-------------|
| `createProviders(config)` | Factory — creates a configured `Providers` wrapper with storefront SDK |
| `Footer` | Storefront footer with sections, social links, legal notice |

### Utility

| Export | Description |
|--------|-------------|
| `Lightbox` | Image lightbox with keyboard navigation and swipe |
| `LazyVideo` | Lazy-loaded video with poster image fallback |
| `ScrollProgress` | Fixed scroll progress bar |
| `useFocusTrap(ref, isOpen)` | Hook — traps keyboard focus within a container |

### Theme

| Export | Description |
|--------|-------------|
| `ThemeProvider` | Wraps app with theme context, injects CSS variables |
| `useTheme()` | Hook — returns current `ThemeTokens` |
| `defaultDarkTheme` | Default dark theme object |
| `ThemeTokens` | TypeScript interface for theme configuration |

```ts
interface ThemeTokens {
  background: string
  foreground: string
  surface: string
  accent: string
  muted: string
  border: string
  fontDisplay: string
  fontBody: string
  cursorColor?: string
  grainOpacity?: number
  radius?: string
  shadow?: string
  statusSuccess?: string
  statusWarning?: string
  statusError?: string
}
```

## Tree-Shakeable

All exports support tree-shaking. Import from subpaths to minimize bundle size:

```tsx
// Only pulls in animation code
import { ScrollReveal } from '@neowhale/ui/animation'

// Only pulls in commerce components
import { ProductCard, CartDrawer } from '@neowhale/ui/commerce'
```

All components include the `"use client"` directive for Next.js App Router compatibility.

## License

MIT