npm package: @rockstarpabitra/colorify
Description: Tiny color converter: hex ↔ rgb ↔ hsl (with alpha), zero deps.
Author: Pabitra Banerjee
Latest version: 2.0.0

<h1 align="center">🎨 Colorify.js v2.0.0</h1>

<p align="center">
  <b>A modular, dependency-free JavaScript library to convert colors between HEX, RGB, and HSL formats — now faster, cleaner, and smarter.</b><br>
  <i>Lightweight • Accurate • Typed • Zero Dependencies</i>
</p>

<p align="center">
  <img src="https://img.shields.io/npm/v/@rockstarpabitra/colorify?color=brightgreen&label=version&style=flat-square" alt="npm version">
  <img src="https://img.shields.io/npm/dt/@rockstarpabitra/colorify?style=flat-square&color=blue" alt="downloads">
  <img src="https://img.shields.io/bundlephobia/minzip/@rockstarpabitra/colorify?label=size&style=flat-square&color=orange" alt="bundle size">
  <img src="https://img.shields.io/npm/l/@rockstarpabitra/colorify?style=flat-square&color=yellow" alt="license">
</p>

---

## ✨ Features

- 🔁 Convert seamlessly between **HEX ↔ RGB ↔ HSL**
- 🌈 Supports **alpha transparency** (`RGBA` / `HSLA` / `HEXA`)
- ⚙️ Fully **TypeScript-based and tree-shakeable**
- ⚡ **Zero dependencies** — small and lightning-fast
- 🧩 Modular architecture — built for extension (CMYK, LAB, etc.)
- 📦 Works in **Browser**, **Node.js**, **Deno**, and **modern bundlers**

---

## 🆕 What’s New in v2.0.0

Version **2.0.0** marks a **major refactor** of the entire library for performance, scalability, and clarity.

- 🚀 **Completely Modular Codebase** — split into `models/`, `utils/`, and `types/`
- ⚙️ **Improved precision & validation** for all color conversions
- 🧱 **Better TypeScript exports** and tree-shakable structure
- 🧪 **Refined unit tests** with consistent precision rounding
- 💡 **Future-ready architecture** for new color models (CMYK, LAB, HSV)
- 🧠 Code rewritten for **clarity, safety, and learning**

---

## 📦 Installation

Using **npm**:

```bash
npm install @rockstarpabitra/colorify
````

Using **yarn**:

```bash
yarn add @rockstarpabitra/colorify
```

Using **pnpm**:

```bash
pnpm add @rockstarpabitra/colorify
```

---

## 🚀 Quick Start

### ✅ ESM Import

```js
import { hexToRgb, rgbToHex, rgbToHsl, hslToRgb } from "@rockstarpabitra/colorify";

console.log(hexToRgb("#3498db"));
// → { r: 52, g: 152, b: 219 }

console.log(rgbToHex(255, 0, 0, 0.5));
// → "#ff000080"

console.log(rgbToHsl(255, 0, 0));
// → { h: 0, s: 100, l: 50 }

console.log(hslToRgb(120, 100, 50));
// → { r: 0, g: 255, b: 0 }
```

### ✅ CommonJS Require

```js
const { hexToRgb, rgbToHex } = require("@rockstarpabitra/colorify");

console.log(hexToRgb("#00ff00"));
// → { r: 0, g: 255, b: 0 }
```

---

## 🧠 API Reference

### 🎨 `hexToRgb(hex: string)`

Converts a HEX color string to an RGB object.

| Input       | Output Example                     |
| ----------- | ---------------------------------- |
| `#3498db`   | `{ r: 52, g: 152, b: 219 }`        |
| `#ff000080` | `{ r: 255, g: 0, b: 0, a: 0.502 }` |

---

### 🌈 `rgbToHex(r: number, g: number, b: number, a?: number)`

Converts RGB values to a HEX color string. Supports optional alpha (`0 → 1`).

| Input              | Output        |
| ------------------ | ------------- |
| `(255, 0, 0)`      | `"#ff0000"`   |
| `(255, 0, 0, 0.5)` | `"#ff000080"` |

---

### 🔵 `rgbToHsl(r: number, g: number, b: number, a?: number)`

Converts RGB to HSL format.

| Input         | Output                      |
| ------------- | --------------------------- |
| `(255, 0, 0)` | `{ h: 0, s: 100, l: 50 }`   |
| `(0, 255, 0)` | `{ h: 120, s: 100, l: 50 }` |

---

### 🟢 `hslToRgb(h: number, s: number, l: number, a?: number)`

Converts HSL values to RGB.

| Input            | Output                     |
| ---------------- | -------------------------- |
| `(240, 100, 50)` | `{ r: 0, g: 0, b: 255 }`   |
| `(60, 100, 50)`  | `{ r: 255, g: 255, b: 0 }` |

---

### 🟣 `hexToHsl(hex: string)`

Converts HEX directly to HSL.

| Input     | Output                    |
| --------- | ------------------------- |
| `#ff0000` | `{ h: 0, s: 100, l: 50 }` |

---

### 🔴 `hslToHex(h: number, s: number, l: number, a?: number)`

Converts HSL directly to HEX.

| Input                | Output        |
| -------------------- | ------------- |
| `(120, 100, 50)`     | `"#00ff00"`   |
| `(60, 100, 50, 0.5)` | `"#ffff0080"` |

---

## ⚙️ Notes

* ✅ Supports **short** (`#abc`, `#abcd`) and **long** (`#aabbcc`, `#aabbccdd`) HEX formats
* 🔢 Alpha values normalized between `0–1`
* 🎚 RGB uses 0–255, HSL uses 0–360° hue and 0–100% saturation/lightness
* 🧮 All values automatically **clamped and rounded**

---

## 🧩 Example Use Case

```js
import { hexToRgb, rgbToHsl, hslToHex } from "@rockstarpabitra/colorify";

// Lighten a color by 10%
function lighten(hex, percent = 10) {
  const hsl = rgbToHsl(...Object.values(hexToRgb(hex)));
  const lighter = { ...hsl, l: Math.min(hsl.l + percent, 100) };
  return hslToHex(lighter.h, lighter.s, lighter.l);
}

console.log(lighten("#e74c3c", 15)); 
// → "#ff7d6e"
```

---

## 🧪 Tests

All functions are unit-tested using **Vitest**.

Run tests locally:

```bash
npm test
```

---

## 🧱 Build Instructions

To build from source:

```bash
npm run build
```

Generated output:

```
dist/
 ├─ index.js       → ESM build
 ├─ index.cjs      → CommonJS build
 └─ index.d.ts     → Type definitions
```

---

## ✅ Summary Checklist — v2.0.0

| Status | Category | Description |
|:------:|:----------|:-------------|
| 🟢 | **Version** | Latest stable release — `v2.0.0` |
| 🟢 | **Language** | Written in **TypeScript** with full type definitions |
| 🟢 | **Architecture** | Modular structure (`models/`, `utils/`, `types/`) |
| 🟢 | **Compatibility** | Works with **Browser**, **Node.js**, and **Deno** |
| 🟢 | **Dependencies** | **Zero** — 100% pure JavaScript |
| 🟢 | **Testing** | Covered with **Vitest** unit tests |
| 🟢 | **Build System** | Compiles via `tsc` and ships ESM + CJS builds |
| 🟢 | **Documentation** | Complete `README`, `LEARN.md`, and `DEVELOPERS_GUIDE.md` |
| 🟢 | **License** | Open Source under **MIT License** |
| 🟢 | **Performance** | Optimized conversion logic & precision math |
| 🟢 | **Future-Ready** | Designed for expansion — CMYK, LAB, HSV coming soon |

> 💡 *Colorify.js v2.0.0 is clean, modular, and built for both developers and learners — blending math, code, and color in one elegant package.*

---

## 🌍 Browser (CDN)

Use **Colorify.js** directly in the browser via [jsDelivr](https://www.jsdelivr.com/):

```html
<script type="module">
  import { hexToRgb } from "https://cdn.jsdelivr.net/npm/@rockstarpabitra/colorify@2.0.0/dist/index.js";
  console.log(hexToRgb("#ff00ff"));
</script>
```

---

## 🧩 Developer Resources

📘 [Learn Colorify.js](./LEARN.md)
💡 [Developer’s Guide](./DEVELOPERS_GUIDE.md)
🧾 [Changelog](./CHANGELOG.md)

---

## 🧑‍💻 Author

**Pabitra Banerjee**
🧠 Full-Stack AI Engineer • Founder & CEO of [MB WEBBER’S](https://mbwebbers.dev)
💬 Passionate about technology, open source, and education.
🌐 [sdepabitra.me](https://sdepabitra.me)

---

## 📜 License

This project is licensed under the **MIT License**.
See the [LICENSE](./LICENSE) file for details.

---

<p align="center">
  <a href="https://sdepabitra.me" target="_blank">
    <img src="https://img.shields.io/static/v1?label=Made%20With%20💖%20By&message=Pabitra%20Banerjee&color=8A2BE2&labelColor=black&style=for-the-badge" alt="Made with love by Pabitra Banerjee">
  </a>
  <br>
  <a href="https://mbwebbers.dev" target="_blank">
    <img src="https://img.shields.io/static/v1?label=MB%20WEBBER'S&message=Open%20Source%20Initiative&color=00C896&labelColor=black&style=for-the-badge" alt="MB WEBBER'S Open Source Initiative">
  </a>
</p>