npm package: @hydrogen-ui/icons
Description: Icon library for Hydrogen UI with tree-shaking support and accessibility features
Latest version: 0.1.0

# @hydrogen-ui/icons

A comprehensive icon library for Hydrogen UI with 200+ optimized SVG icons. Features two variants (outlined and filled), TypeScript support, tree-shaking, and an icon provider for consistent styling.

## Installation

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

## Features

- 🎨 **200+ Icons** - Commerce, navigation, actions, and more
- 🎭 **Two Variants** - Outlined and filled styles
- ⚡ **Optimized** - SVGO-optimized for minimal file size
- 🌲 **Tree-shakeable** - Import only what you need
- 🔒 **TypeScript** - Full type safety and autocompletion
- ♿ **Accessible** - ARIA labels and proper semantics
- 🎯 **Icon Provider** - Global configuration support
- 📦 **Small Bundle** - Minimal impact on your app size

## Quick Start

```tsx
import { CartFilledIcon, HeartOutlinedIcon } from '@hydrogen-ui/icons';

function MyComponent() {
  return (
    <div>
      <CartFilledIcon size={24} color="#000" />
      <HeartOutlinedIcon size={20} color="red" />
    </div>
  );
}
```

## Icon Variants

Each icon comes in two variants:

- **Outlined** - Stroke-based design, lighter visual weight
- **Filled** - Solid fill design, heavier visual weight

```tsx
// Outlined variant
import { HomeOutlinedIcon } from '@hydrogen-ui/icons';

// Filled variant
import { HomeFilledIcon } from '@hydrogen-ui/icons';

// Some icons only have one variant
import { ChevronDownOutlinedIcon } from '@hydrogen-ui/icons';
```

## Icon Categories

### Commerce Icons
Shopping, payment, and e-commerce related icons:
- Cart, bag, credit card, shopping tag
- Barcode, receipt, label
- Delivery truck, package

### Navigation Icons
Directional and menu icons:
- Arrows, chevrons
- Menu burger, dots
- Home, search

### Action Icons
Interactive action icons:
- Plus, minus, close
- Copy, paste, link
- Upload, download, export
- Lock, unlock

### Status Icons
Information and state indicators:
- Info, question, warning circles
- Check, cross marks

### Object Icons
Files, folders, and media:
- File, folder, image
- Code, terminal
- Database, cloud

### Device Icons
Hardware and technology:
- Microchip, CPU, plug
- Microphone, camera
- Printer, scanner

## Usage

### Basic Usage

All icons accept standard SVG props plus some additional options:

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

<SearchAlt1FilledIcon 
  size={24}               // or width/height
  color="currentColor"    // or fill for filled, stroke for outlined
  className="search-icon"
  onClick={handleClick}
  title="Search"          // Adds accessible title
/>
```

### Icon Provider

Use the `IconProvider` to set default props for all child icons:

```tsx
import { IconProvider, CartFilledIcon, HeartFilledIcon } from '@hydrogen-ui/icons';

function App() {
  return (
    <IconProvider size={20} color="#333" className="app-icon">
      <CartFilledIcon />      {/* Inherits size=20, color=#333 */}
      <HeartFilledIcon />     {/* Inherits size=20, color=#333 */}
      <SearchIcon size={24} /> {/* Overrides size to 24 */}
    </IconProvider>
  );
}
```

### Dynamic Icon Selection

Load icons dynamically based on a string:

```tsx
import * as icons from '@hydrogen-ui/icons';

function DynamicIcon({ name, ...props }) {
  const Icon = icons[name as keyof typeof icons];
  
  if (!Icon) {
    console.warn(`Icon ${name} not found`);
    return null;
  }
  
  return <Icon {...props} />;
}

// Usage
<DynamicIcon name="CartFilledIcon" size={24} />
```

### Icon Catalog

Access icon metadata programmatically:

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

// Get all commerce icons
const commerceIcons = Object.entries(iconCatalog)
  .filter(([name, meta]) => meta.category === 'commerce')
  .map(([name]) => name);

// Search icons by keywords
const searchIcons = Object.entries(iconCatalog)
  .filter(([name, meta]) => 
    meta.keywords.some(keyword => 
      keyword.includes('search')
    )
  );
```

## Props

All icons accept these props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| size | number | 24 | Icon size (sets both width and height) |
| width | number | 24 | Icon width |
| height | number | 24 | Icon height |
| color | string | 'currentColor' | Icon color (fill for filled, stroke for outlined) |
| fill | string | - | SVG fill color |
| stroke | string | - | SVG stroke color |
| strokeWidth | number | 2 (outlined) / 0 (filled) | Stroke width |
| className | string | - | CSS class name |
| style | CSSProperties | - | Inline styles |
| title | string | - | Accessible title |
| titleId | string | - | ID for title element |
| ...svgProps | SVGAttributes | - | All standard SVG props |

## Accessibility

Icons include built-in accessibility features:

```tsx
// With title - icon is announced to screen readers
<CartFilledIcon title="Shopping cart" />
// Renders: <title id="...">Shopping cart</title>

// Without title - icon is decorative
<CartFilledIcon />
// Renders: aria-hidden="true"

// Custom title ID for ARIA labelling
<button aria-labelledby="cart-icon">
  <CartFilledIcon title="Shopping cart" titleId="cart-icon" />
</button>
```

## Available Icons

### Commerce (23 icons)
- `Bag4FilledIcon`, `BagFilledIcon`
- `Cart1FilledIcon`, `CartLarge2FilledIcon`, `CartPlusFilledIcon`, `CartShoppingFilledIcon`, `CartOutlinedIcon`
- `CreditCard1FilledIcon`, `CreditCardFilledIcon`, `CreditCardPlusFilledIcon`, `CreditCardScanFilledIcon`
- `LabelFilledIcon`, `LabelPriceSaleFilledIcon`
- `ShoppingTagFilledIcon`, `TagFilledIcon`, `TagOutlinedIcon`, `TagsFilledIcon`
- `BarcodeFilledIcon`, `ReceiptAlt1FilledIcon`
- `DeliveryFilledIcon`, `DeliveryTruckFilledIcon`

### Navigation (37 icons)
- Arrow variants: `AltArrowDownFilledIcon`, `AltArrowLeftFilledIcon`, `AltArrowRightFilledIcon`, `AltArrowUpFilledIcon`
- Chevron variants: All directions with filled and outlined options
- `MenuBurgerFilledIcon`, `MenuOutlinedIcon`
- `HomeFilledIcon`, `HomeOutlinedIcon`
- `SearchAlt1FilledIcon`, `MagnifyingGlassOutlinedIcon`

### Actions (45 icons)
- `PlusFilledIcon`, `PlusCircledOutlinedIcon`
- `CopyFilledIcon`, `CopyOutlinedIcon`, `ClipboardCopyOutlinedIcon`
- `LinkFilledIcon`, `PaperclipFilledIcon`, `PaperclipAltFilledIcon`
- `UploadFilledIcon`, `UploadMinimalisticFilledIcon`, `DownloadFilledIcon`
- `ExportFilledIcon`, `PrintFilledIcon`, `PrinterFilledIcon`
- `RefreshCwAlt1FilledIcon`, `RefreshCwAltFilledIcon`, `ReloadOutlinedIcon`
- `LockFilledIcon`, `LockAltFilledIcon`, `UnlockFilledIcon`
- `TrashOutlinedIcon`

### Status (9 icons)
- `CircleInfoFilledIcon`, `InfoCircledOutlinedIcon`
- `CircleQuestionFilledIcon`
- `CircleXmarkFilledIcon`, `CrossCircledOutlinedIcon`
- `CircleMinusFilledIcon`, `CirclePlusFilledIcon`

### Objects (48 icons)
- File variants: `FileFilledIcon`, `FilePlusFilledIcon`, `FileCopyFilledIcon`, `FileLockFilledIcon`
- Folder variants: `FolderFilledIcon`, `FolderPlusFilledIcon`, `FolderImageFilledIcon`
- `ImageFilledIcon`, `ImagePlusFilledIcon`, `ImageSquareFilledIcon`
- `CodeFilledIcon`, `CodeAltFilledIcon`, `CodeBranchFilledIcon`
- `DatabaseFilledIcon`, `CloudUploadFilledIcon`

### Device (12 icons)
- `MicrochipFilledIcon`, `CpuFilledIcon`, `ChipOutlinedIcon`
- `MicrophoneFilledIcon`, `MicrophoneAlt1FilledIcon`
- `CameraFilledIcon`
- `PrinterFilledIcon`, `PrinterOutlinedIcon`
- `ScannerFilledIcon`

## TypeScript

Full TypeScript support with type exports:

```typescript
import type { IconProps, IconName } from '@hydrogen-ui/icons';
import { CartFilledIcon } from '@hydrogen-ui/icons';

// Type-safe props
const iconProps: IconProps = {
  size: 24,
  color: 'blue',
  className: 'my-icon'
};

// Type-safe icon names
const iconName: IconName = 'CartFilledIcon';

// Component typing
const MyIcon: React.FC<IconProps> = (props) => {
  return <CartFilledIcon {...props} />;
};
```

## Performance

### Tree Shaking

Import only the icons you need:

```tsx
// ✅ Good - only imports one icon
import { CartFilledIcon } from '@hydrogen-ui/icons';

// ❌ Bad - imports entire library
import * as icons from '@hydrogen-ui/icons';
```

### Bundle Size

Each icon is approximately 1-2KB uncompressed. With tree-shaking, you only pay for what you use:

- Single icon: ~1-2KB
- 10 icons: ~10-20KB
- Provider overhead: ~2KB

### Optimization

All icons are pre-optimized with SVGO for minimal file size while maintaining visual quality.

## Advanced Usage

### Custom Icon Wrapper

Create your own icon wrapper with default styles:

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

function AppIcon({ name, ...props }) {
  const icons = {
    cart: CartFilledIcon,
    // ... other icons
  };
  
  const Icon = icons[name];
  
  return (
    <Icon
      size={20}
      className="app-icon"
      {...props}
    />
  );
}
```

### Icon Button Component

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

function IconButton({ icon: Icon, label, onClick, ...props }) {
  return (
    <button
      onClick={onClick}
      className="icon-button"
      aria-label={label}
      {...props}
    >
      <IconProvider size={16} color="currentColor">
        <Icon />
      </IconProvider>
    </button>
  );
}

// Usage
<IconButton 
  icon={CartFilledIcon} 
  label="Add to cart"
  onClick={handleAddToCart}
/>
```

### Animated Icons

Add animations with CSS:

```css
.icon-spin {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}
```

```tsx
<RefreshCwAltFilledIcon className="icon-spin" />
```

## Browser Support

- Modern browsers (Chrome, Firefox, Safari, Edge)
- IE11 requires SVG polyfills
- React Native supported via react-native-svg

## Contributing

### Adding New Icons

1. Add SVG files to `raw/archive/filled/` or `raw/archive/outlined/`
2. Run `npm run optimize` to optimize SVGs
3. Run `npm run generate` to create React components
4. Run `npm run build` to build the package

### Icon Guidelines

- Use 24x24 viewBox
- 2px stroke width for outlined icons
- Consistent style with existing icons
- Meaningful, searchable names

## License

MIT