# colour

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`colour.ts` implements the `Colour` class — an immutable, chainable colour value object. It wraps an internal `RGBA` state and exposes methods for manipulation, analysis, conversion, and output formatting. The class is the primary public API surface for the package and is used by the `colour-factories` helpers.

## Features

- Immutable chainable manipulation (lighten, darken, saturate, desaturate, rotate, alpha, fade, opaquer)
- Colour-space conversion methods (hex, RGB, HSL, HSV, LAB, LCH, OKLAB, OKLCH, CMYK)
- Analysis methods (luminance, perceived brightness, contrast ratio, isDark, isLight, best contrast, distance)
- Utility methods (negate, grayscale, mix, clone, equals, toString)
- Pure functional implementation with no mutation of internal state

## Usage: Basic Example

```ts
import { Colour } from "@suaveplan/colours/colour";

const c = new Colour("#ff9900");
console.log(c.lighten(0.2).toHex()); // "#ffb34d"
console.log(c.isDark()); // false
```

## Usage: Advanced Example

```ts
import { Colour } from "@suaveplan/colours/colour";

const brand = new Colour("#3b82f6");
const text = brand.bestContrast("#ffffff", "#1f2937");
console.log(text.toHex()); // "#ffffff"
```

## API Reference

### Constructor

- `new Colour(input: ColourInput)` — parses any supported colour input into an immutable `Colour` instance.

### Manipulation

- `lighten(amount: number): Colour`
- `darken(amount: number): Colour`
- `saturate(amount: number): Colour`
- `desaturate(amount: number): Colour`
- `rotate(degrees: number): Colour`
- `alpha(a: number): Colour`
- `fade(amount: number): Colour`
- `opaquer(amount: number): Colour`
- `negate(): Colour`
- `grayscale(): Colour`
- `mix(other: ColourInput, amount?: number): Colour`

### Analysis

- `luminance(): number`
- `perceivedBrightness(): number`
- `contrast(other: ColourInput): number`
- `isDark(): boolean`
- `isLight(): boolean`
- `bestContrast(...candidates: (Colour | string)[]): Colour`
- `distance(other: ColourInput, mode?: DistanceMode): number`
- `equals(other: ColourInput): boolean`

### Output

- `toHex(): string`
- `toHex3(): string`
- `toHex8(): string`
- `toRgb(): RGB`
- `toRgba(): RGBA`
- `toHsl(): HSL`
- `toHsv(): HSV`
- `toLab(): LAB`
- `toLch(): LCH`
- `toOklab(): OKLAB`
- `toOklch(): OKLCH`
- `toCmyk(): CMYK`
- `toString(): string`

## Implementation Notes

The internal `_rgba` state is never mutated. Every chainable method returns a new `Colour` instance. Conversion methods delegate to the `conversions` module. Analysis methods use the standard WCAG 2.1 luminance formula and sRGB gamma. The `bestContrast` helper uses the APCA-like perceived brightness for candidate ranking.