89 lines
2.7 KiB
Markdown
89 lines
2.7 KiB
Markdown
# 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.
|