npm package: @hydrogen-ui/ui
Description: A complete UI library for Shopify Hydrogen storefronts
Author: Hydrogen UI Team
Latest version: 0.2.2

# @hydrogen-ui/ui

The complete UI library for building Shopify Hydrogen storefronts. One package, everything included.

## Installation

```bash
npm install @hydrogen-ui/ui
# or
yarn add @hydrogen-ui/ui  
# or
pnpm add @hydrogen-ui/ui
```

## What's Included

- 🎨 **Design Tokens** - Comprehensive token system with theme support
- 🧩 **Components** - 40+ React components built for ecommerce
- 🎭 **Themes** - Multiple theme presets (Dawn, Craft, Studio, B2B, Thnk)
- 🪝 **Hooks** - Custom React hooks for Shopify functionality
- 🛠️ **Utilities** - Helper functions for common tasks
- 🎯 **Icons** - Optimized icon library
- 🛍️ **Shopify Integration** - Deep integration with Shopify APIs

## Quick Start

```tsx
import { HydrogenUIProvider, ThemeProvider, Button, ProductCard } from '@hydrogen-ui/ui';

function App() {
  return (
    <HydrogenUIProvider>
      <ThemeProvider theme="dawn">
        <Button variant="primary">Shop Now</Button>
        <ProductCard product={product} />
      </ThemeProvider>
    </HydrogenUIProvider>
  );
}
```

## Import Methods

### Import everything (not recommended for bundle size):
```tsx
import * as HydrogenUI from '@hydrogen-ui/ui';
```

### Import specific components (recommended):
```tsx
import { Button, Card, Input } from '@hydrogen-ui/ui';
```

### Import from sub-paths for better tree-shaking:
```tsx
import { Button } from '@hydrogen-ui/ui/components';
import { useCart } from '@hydrogen-ui/ui/hooks';
import { formatMoney } from '@hydrogen-ui/ui/utils';
import { CartIcon } from '@hydrogen-ui/ui/icons';
import { dawn } from '@hydrogen-ui/ui/themes';
```

## Available Imports

### Components
- `AddToCartButton`
- `Analytics` (Provider, Views)
- `Box`, `Flex`, `Grid`, `Stack`
- `Button`
- `CartForm`, `CartLineItem`, `CartSummary`
- `Checkbox`, `Radio`, `Select`, `Input`
- `CollectionGrid`
- `Drawer`, `Modal`
- `FilterDrawer`
- `Footer`, `Header`
- `Heading`, `Text`, `Code`
- `Image`, `Video`, `ExternalVideo`
- `Link`
- `MediaFile`, `ModelViewer`
- `Money`
- `OptimisticInput`
- `Pagination`
- `ProductCard`, `ProductImage`, `ProductPrice`
- `RichText`
- `Script`, `Seo`
- `ShopPayButton`
- `VariantSelector`
- And more...

### Hooks
- `useCart`, `useCartDrawer`, `useOptimisticCart`
- `useCustomer`, `useAddresses`
- `useProduct`, `useProductRecommendations`, `useProductSearch`
- `useAnalytics`
- `useTheme`, `useToken`
- `useDebouncedValue`, `useMediaQuery`, `useLocalStorage`
- And more...

### Themes
- `dawn` - Clean, minimal theme
- `craft` - Artisan-focused theme
- `studio` - Modern, bold theme
- `b2b` - Business-focused theme
- `thnk` - Custom brand theme

### Utilities
- **Formatters**: `formatMoney`, `formatDate`, `formatTax`
- **Validators**: `validateEmail`, `validatePhone`, `validatePostalCode`
- **Helpers**: `getImageUrl`, `getProductOptions`, `parseGid`
- **API**: `createStorefrontClient`, `rateLimiter`

### Icons
- 200+ optimized SVG icons
- Tree-shakeable icon components
- Customizable size and color

## Theme Usage

```tsx
import { ThemeProvider } from '@hydrogen-ui/ui';

// Use a preset theme
<ThemeProvider theme="dawn">
  {/* Your app */}
</ThemeProvider>

// Or use a custom theme
<ThemeProvider theme={{
  name: 'custom',
  tokens: {
    colors: {
      primary: '#007bff',
      // ... your tokens
    }
  }
}}>
  {/* Your app */}
</ThemeProvider>
```

## TypeScript Support

Full TypeScript support with exported types:

```tsx
import type { 
  Theme,
  Product,
  Cart,
  ButtonProps,
  ThemeTokens 
} from '@hydrogen-ui/ui';
```

## Requirements

- React 18.0.0 or higher
- Shopify Hydrogen 2024.0.0 or higher (for Shopify integration features)
- Node.js 18.0.0 or higher

## License

MIT

## Documentation

For detailed documentation, visit [hydrogen-ui.dev](https://hydrogen-ui.dev)