Install

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

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 |

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:

// 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