# @helpers4/color

> Tree-shakable TypeScript utility functions for the `color` domain.
> Package: `@helpers4/color` — Version: 3.0.1
> License: LGPL-3.0-or-later

## Installation

```sh
npm install @helpers4/color
# or
pnpm add @helpers4/color
```

## Usage

```typescript
import { argbToRgb, hexToRgb, hslToRgb, ... } from '@helpers4/color';
```

## Functions

| Function | Description |
|---|---|
| `argbToRgb` | Converts a 32-bit packed ARGB integer (as used by e.g. Chromium's `Local State` profile `background_ |
| `hexToRgb` | Parses a hex color string (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` — the leading `#` is optional) in |
| `hslToRgb` | Converts an HSL(A) color into RGB(A). |
| `rgbToHex` | Converts an RGB(A) color into a hex color string.  `r`/`g`/`b` are clamped to 0-255 and rounded to t |
| `rgbToHsl` | Converts an RGB(A) color into HSL(A).  `h`/`s`/`l` are rounded to 1 decimal place to avoid floating- |

---

## API Reference

### `argbToRgb`

Converts a 32-bit packed ARGB integer (as used by e.g. Chromium's
`Local State` profile `background_color` field) into a CSS `rgb()` string.
The alpha byte (top 8 bits) is read but discarded — the result is always opaque.

```typescript
import { argbToRgb } from '@helpers4/color';

argbToRgb(argb: number): string
```

**Parameters:**

- `argb: number` — A 32-bit integer where bits 24-31 are alpha, 16-23 are red,
  8-15 are green, and 0-7 are blue

**Returns:** `string` — A `rgb(r,g,b)` CSS color string

**Examples:**

*Convert a packed ARGB integer to a CSS color*

The top byte (alpha) is discarded — the result is always opaque.

```typescript
argbToRgb(0xffff0000)
// => 'rgb(255,0,0)'
```

*Alpha byte does not affect the result*

Two ARGB values differing only in the alpha byte produce the same rgb() string.

```typescript
argbToRgb(0x00ff0000) === argbToRgb(0x80ff0000)
// => true
```

---

### `hexToRgb`

Parses a hex color string (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` — the
leading `#` is optional) into its RGB(A) channels.

```typescript
import { hexToRgb } from '@helpers4/color';

hexToRgb(hex: string): RgbColor | null
```

**Parameters:**

- `hex: string` — The hex color string to parse

**Returns:** `RgbColor | null` — The parsed color, or `null` if `hex` is not a valid hex color

**Examples:**

*Parse a hex color into RGB channels*

The leading # is optional; shorthand 3/4-digit forms are also supported.

```typescript
hexToRgb('#ff0000')
// => { r: 255, g: 0, b: 0, a: 1 }
```

*Returns null for an invalid color*

Lets you branch on parse failure instead of getting a garbage color.

```typescript
hexToRgb('not-a-color')
// => null
```

---

### `hslToRgb`

Converts an HSL(A) color into RGB(A).

```typescript
import { hslToRgb } from '@helpers4/color';

hslToRgb(color: HslColor): RgbColor
```

**Parameters:**

- `color: HslColor` — The color to convert. `h` is normalized modulo 360 (negative
  values wrap around), `s`/`l` are expected in 0-100, `a` defaults to 1
  (opaque) when omitted.

**Returns:** `RgbColor` — The equivalent RGB(A) color, with `r`/`g`/`b` rounded to 0-255

**Examples:**

*Convert an HSL color to RGB*

Useful after generating a hue programmatically (e.g. evenly spaced chart colors).

```typescript
hslToRgb({ h: 120, s: 100, l: 50 })
// => { r: 0, g: 255, b: 0, a: 1 }
```

*Hue wraps around 360 degrees*

Negative or out-of-range hues are normalized before conversion.

```typescript
hslToRgb({ h: -360, s: 100, l: 50 })
// => { r: 255, g: 0, b: 0, a: 1 }  (same as h: 0)
```

---

### `rgbToHex`

Converts an RGB(A) color into a hex color string.

`r`/`g`/`b` are clamped to 0-255 and rounded to the nearest integer before
formatting. The alpha channel is only appended (as `#rrggbbaa`) when it is
below 1 — fully opaque colors format as the plain 6-digit `#rrggbb`.

```typescript
import { rgbToHex } from '@helpers4/color';

rgbToHex(color: RgbColor): string
```

**Parameters:**

- `color: RgbColor` — The color to convert. `a` defaults to 1 (opaque) when omitted.

**Returns:** `string` — A lowercase hex color string

**Examples:**

*Format an opaque color as hex*

Alpha defaults to 1 (opaque) and is omitted from the output.

```typescript
rgbToHex({ r: 255, g: 0, b: 0 })
// => '#ff0000'
```

*Include alpha when the color is translucent*

A non-opaque color formats as an 8-digit #rrggbbaa string.

```typescript
rgbToHex({ r: 0, g: 255, b: 0, a: 0.5 })
// => '#00ff0080'
```

---

### `rgbToHsl`

Converts an RGB(A) color into HSL(A).

`h`/`s`/`l` are rounded to 1 decimal place to avoid floating-point noise.

```typescript
import { rgbToHsl } from '@helpers4/color';

rgbToHsl(color: RgbColor): HslColor
```

**Parameters:**

- `color: RgbColor` — The color to convert. `r`/`g`/`b` are expected in 0-255,
  `a` defaults to 1 (opaque) when omitted.

**Returns:** `HslColor` — The equivalent HSL(A) color: `h` in 0-360, `s`/`l` in 0-100

**Examples:**

*Convert an RGB color to HSL*

Useful for generating tints/shades by adjusting lightness.

```typescript
rgbToHsl({ r: 255, g: 0, b: 0 })
// => { h: 0, s: 100, l: 50, a: 1 }
```

*Grayscale colors have no saturation*

When r, g, and b are equal, the color is achromatic (s = 0).

```typescript
rgbToHsl({ r: 128, g: 128, b: 128 })
// => { h: 0, s: 0, l: 50.2, a: 1 }
```

---
