shelving/util/colormodule

A Color class and accompanying helpers for parsing, representing, and converting CSS hex colours. Useful for theming, accessibility checks, and anywhere a component or tool needs to inspect or manipulate a colour value.

  • Parses 3-digit (#RGB) and 6/8-digit (#RRGGBB / #RRGGBBAA) hex strings, with or without the # prefix.
  • Channel values (Color.r, Color.g, Color.b, Color.a) are clamped to 0–255.
  • Color.isLight / Color.isDark use the sRGB luminance formula (threshold: luminance > 140 = light).

Usage

Creating a Color

ts
import { getColor, requireColor } from "shelving/util";

const c = getColor("#ff6600");   // Color instance
const c2 = getColor("F60");      // 3-digit shorthand, no '#'
getColor("not-a-color");         // undefined

requireColor("#ff6600");         // same but throws RequiredError on failure

Converting and inspecting

ts
import { getColor } from "shelving/util";

const c = getColor("#3399ff")!;
c.hex;        // "#3399ff"
c.rgb;        // "rgb(51, 153, 255)"
c.rgba;       // "rgba(51, 153, 255, 1)"
c.luminance;  // number
c.isLight;    // boolean
c.isDark;     // boolean

Type guard and assertion

ts
import { isColor, assertColor } from "shelving/util";

isColor(value);          // true if Color instance
assertColor(value);      // throws RequiredError if not

Using the class directly

ts
import { Color } from "shelving/util";

const white = new Color(255, 255, 255);
const transparent = new Color(0, 0, 0, 0);
Color.from("#abc");  // same as getColor

Functions

Go

isColor()function

Is an unknown value a Color instance?

isColor(value: unknown): value is Color
Go

assertColor()function

Assert that an unknown value is a Color instance.

assertColor(value: unknown, caller: AnyCaller = assertColor): asserts value is Color
Go

getColor()function

Convert an unknown value to a Color instance, or return undefined if conversion fails.

getColor(value: unknown): Color | undefined
Go

requireColor()function

Convert a possible color to a Color instance, or throw RequiredError if it can't be converted.

requireColor(value: PossibleColor, caller: AnyCaller = requireColor): Color

Classes

Go

Colorclass

Represents an RGBA color with red, green, blue, and alpha channels (each 0–255).

new Color(r = 255, g = 255, b = 255, a = 255)

Types

Go

PossibleColortype

Things that can be converted to a Color instance.

Color | string

Constants

Go

HEX3_REGEXPconstant

Regular expression matching a three-digit hex color (e.g. #F00), capturing each channel.

Go

HEX6_REGEXPconstant

Regular expression matching a six or eight digit hex color (e.g. #FF0000 or #FF0000FF), capturing each channel.