pastel-wasm/README.md

# pastel-wasm

**WebAssembly color manipulation library** - All the power of color operations in your browser, with zero server calls!

[![Bundle Size](https://img.shields.io/badge/bundle-132KB-brightgreen)](https://github.com/pastel-wasm/pastel-wasm)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue)](LICENSE)

## Overview

`pastel-wasm` is a high-performance WebAssembly library that provides comprehensive color manipulation capabilities directly in the browser. Built with Rust and compiled to WASM, it offers:

- ✨ **Zero latency** - All processing happens client-side
- 🚀 **Blazing fast** - Native performance via WebAssembly
- 📦 **Lightweight** - Only 132KB WASM bundle
- 🎨 **Feature-complete** - All essential color operations
- 🔒 **Type-safe** - Full TypeScript support
- 🌐 **Works offline** - No internet connection required

## Features

### Color Operations
- Parse any color format (hex, rgb, hsl, named colors)
- Convert between color spaces (RGB, HSL, HSV, Lab, LCH)
- Lighten, darken, saturate, desaturate
- Rotate hue, complement, mix colors
- Calculate luminance, brightness, contrast

### Color Generation
- Random color generation (vivid or normal)
- Color gradients
- Color harmony palettes (monochromatic, analogous, complementary, triadic, tetradic)

### Accessibility
- Color blindness simulation (protanopia, deuteranopia, tritanopia)
- Text color optimization for contrast
- WCAG contrast ratio calculation

### Named Colors
- 148 CSS/X11 named colors
- Search and filter by name

## Installation

```bash
npm install pastel-wasm
# or
yarn add pastel-wasm
# or
pnpm add pastel-wasm
```

## Usage

### Basic Example

```typescript
import * as pastel from 'pastel-wasm';

// Initialize (call once)
pastel.init();

// Parse a color
const info = pastel.parse_color('#ff0099');
console.log(info);
// {
//   input: "#ff0099",
//   hex: "#ff0099",
//   rgb: [255, 0, 153],
//   hsl: [320, 1.0, 0.5],
//   brightness: 0.498,
//   luminance: 0.286,
//   is_light: false
// }

// Manipulate colors
const lighter = pastel.lighten_color('#ff0099', 0.2);    // "#ff66c2"
const darker = pastel.darken_color('#ff0099', 0.1);      // "#cc007a"
const saturated = pastel.saturate_color('#888888', 0.5); // "#cc4444"

// Mix colors
const mixed = pastel.mix_colors('#ff0000', '#0000ff', 0.5); // "#800080"

// Generate palettes
const palette = pastel.generate_palette('#3498db', 'triadic');
// ["#3498db", "#34db98", "#db9834"]

// Generate gradients
const gradient = pastel.generate_gradient('#ff0000', '#0000ff', 10);
// Array of 10 colors from red to blue

// Random colors
const random = pastel.generate_random_colors(5, true); // 5 vivid colors
```

### Accessibility

```typescript
// Get optimal text color for a background
const textColor = pastel.get_text_color('#3498db');
console.log(textColor); // "#ffffff" (white text on blue background)

// Calculate contrast ratio
const contrast = pastel.calculate_contrast('#3498db', '#ffffff');
console.log(contrast); // 4.35

// Simulate color blindness
const protanopia = pastel.simulate_protanopia('#ff0099');
const deuteranopia = pastel.simulate_deuteranopia('#ff0099');
const tritanopia = pastel.simulate_tritanopia('#ff0099');
```

### Named Colors

```typescript
// Get all named colors
const allColors = pastel.get_all_named_colors();
console.log(allColors.length); // 148

// Search named colors
const results = pastel.search_named_colors('blue');
// [{name: "blue", hex: "#0000ff"}, {name: "darkblue", hex: "#00008b"}, ...]
```

### Color Distance

```typescript
// Calculate color distance (CIE76 or CIEDE2000)
const distance = pastel.color_distance('#ff0000', '#00ff00', true);
console.log(distance); // Perceptual distance using CIEDE2000
```

## Supported Color Formats

### Input Formats
- Hex: `#ff0099`, `#f09`, `ff0099`, `#ff0099aa`
- RGB: `rgb(255, 0, 153)`, `rgba(255, 0, 153, 0.5)`
- HSL: `hsl(280, 100%, 50%)`, `hsla(280, 100%, 50%, 0.8)`
- Named: `red`, `rebeccapurple`, `lightslategray`

### Color Spaces
- **RGB** - Red, Green, Blue
- **HSL** - Hue, Saturation, Lightness
- **HSV** - Hue, Saturation, Value
- **Lab** - CIELab (perceptually uniform)
- **LCH** - Cylindrical Lab

## API Reference

### Color Information
- `parse_color(color: string): ColorInfo` - Parse and analyze a color

### Color Manipulation
- `lighten_color(color: string, amount: number): string`
- `darken_color(color: string, amount: number): string`
- `saturate_color(color: string, amount: number): string`
- `desaturate_color(color: string, amount: number): string`
- `rotate_hue(color: string, degrees: number): string`
- `complement_color(color: string): string`
- `mix_colors(color1: string, color2: string, fraction: number): string`

### Color Generation
- `generate_random_colors(count: number, vivid: boolean): string[]`
- `generate_gradient(start: string, end: string, steps: number): string[]`
- `generate_palette(base: string, scheme: string): string[]`
  - Schemes: `monochromatic`, `analogous`, `complementary`, `triadic`, `tetradic`

### Accessibility
- `get_text_color(bg_color: string): string`
- `calculate_contrast(color1: string, color2: string): number`
- `simulate_protanopia(color: string): string`
- `simulate_deuteranopia(color: string): string`
- `simulate_tritanopia(color: string): string`

### Named Colors
- `get_all_named_colors(): NamedColor[]`
- `search_named_colors(query: string): NamedColor[]`

### Utilities
- `color_distance(color1: string, color2: string, use_ciede2000: boolean): number`
- `version(): string`

## Performance

| Operation | Time (avg) |
|-----------|------------|
| Parse color | < 0.1ms |
| Lighten/Darken | < 0.1ms |
| Generate gradient (10 steps) | < 0.5ms |
| Generate palette | < 0.3ms |
| Colorblind simulation | < 0.2ms |

*Benchmarks run on M1 MacBook Pro*

## Browser Support

- ✅ Chrome 57+
- ✅ Firefox 52+
- ✅ Safari 11+
- ✅ Edge 16+

Requires WebAssembly support.

## Development

### Build from Source

```bash
# Install Rust and wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Clone the repository
git clone https://github.com/pastel-wasm/pastel-wasm
cd pastel-wasm

# Build
wasm-pack build --target bundler --out-dir pkg

# Build for different targets
wasm-pack build --target web --out-dir pkg-web      # For vanilla JS
wasm-pack build --target nodejs --out-dir pkg-node  # For Node.js
```

### Run Tests

```bash
wasm-pack test --headless --firefox --chrome
```

## Comparison

### vs pastel-api (REST API)
| Feature | pastel-wasm | pastel-api |
|---------|-------------|------------|
| Latency | ~0ms | ~50-200ms |
| Offline | ✅ Yes | ❌ No |
| Server required | ❌ No | ✅ Yes |
| Bundle size | 132KB | N/A |
| Rate limiting | ❌ No | ✅ Yes |

**Recommendation:** Use `pastel-wasm` for client-side applications (React, Vue, Svelte, etc). Use `pastel-api` for server-side integrations or sharing color operations via URLs.

### vs JavaScript Libraries
- **Smaller** - Many JS color libraries are 150-300KB
- **Faster** - WebAssembly native performance
- **More accurate** - Precise color space conversions

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Related Projects

- [pastel](https://github.com/sharkdp/pastel) - The original CLI tool
- [pastel-api](https://github.com/pastel-api/pastel-api) - REST API wrapper
- [pastel-ui](https://github.com/pastel-ui/pastel-ui) - Web UI for color manipulation

## Acknowledgments

Inspired by the excellent [pastel](https://github.com/sharkdp/pastel) CLI tool by [@sharkdp](https://github.com/sharkdp).