@oscarpalmer/atoms 0.188.0 → 0.189.0

package/src/color/misc/state.ts

@@ -1,40 +1,43 @@
 import {
-	ALPHA_FULL_VALUE,
 	DEFAULT_HSL,
+	DEFAULT_HWB,
 	DEFAULT_RGB,
 	HEX_BLACK,
 	KEYS_HSL,
+	KEYS_HWB,
 	KEYS_RGB,
 	LENGTH_LONG,
+	MAX_PERCENT,
 } from '../constants';
-import type {ColorState, HSLAColor, HSLColor, RGBAColor, RGBColor} from '../models';
-import {getNormalizedHex, hexToRgb} from '../space/hex';
-import {getHslValue, hslToRgb} from '../space/hsl';
-import {getRgbValue, rgbToHex, rgbToHsl} from '../space/rgb';
+import type {
+	ColorState,
+	HSLAColor,
+	HSLColor,
+	HWBAColor,
+	HWBColor,
+	RGBAColor,
+	RGBColor,
+} from '../models';
+import {getNormalizedHex, hexToHsl, hexToRgb} from '../space/hex';
+import {getHslValue, hslToHex, hslToHwb, hslToRgb} from '../space/hsl';
+import {getHwbValue, hwbToHex, hwbToHsl, hwbToRgb} from '../space/hwb';
+import {getRgbValue, rgbToHex, rgbToHsl, rgbToHwb} from '../space/rgb';
 import {getAlpha} from './alpha';
-import {getHexValue, getDegrees, getPercentage} from './get';
-import {isColor, isHexColor, isHslLike, isRgbLike} from './is';
+import {getDegrees, getHexValue, getPercentage} from './get';
+import {isColor, isHexColor, isHslLike, isHwbLike, isRgbLike} from './is';
 
 // #region Functions
 
 export function getColorState(value: unknown): ColorState {
 	if (typeof value === 'string') {
-		const normalized = getNormalizedHex(value, true);
-		const hex = normalized.slice(0, LENGTH_LONG);
-		const rgb = hexToRgb(hex);
-
-		return {
-			hex,
-			rgb,
-			alpha: getAlpha(normalized.slice(LENGTH_LONG)),
-			hsl: rgbToHsl(rgb),
-		};
+		return getColorStateForHex(value);
 	}
 
 	if (isColor(value)) {
 		return {
 			hex: value.hex,
 			hsl: value.hsl,
+			hwb: value.hwb,
 			rgb: value.rgb,
 			alpha: getAlpha(value.alpha),
 		};
@@ -46,26 +49,81 @@ export function getColorState(value: unknown): ColorState {
 		state.alpha = getAlpha((value as HSLAColor).alpha);
 
 		if (KEYS_HSL.every(key => key in value)) {
-			state.hsl = getHslValue(value as Record<keyof HSLColor, unknown>);
-			state.rgb = hslToRgb(state.hsl as HSLColor);
-			state.hex = rgbToHex(state.rgb as RGBColor);
+			return getColorStateForHsl(state, value as Record<keyof HSLColor, unknown>);
+		}
 
-			return state as ColorState;
+		if (KEYS_HWB.every(key => key in value)) {
+			return getColorStateForHwb(state, value as Record<keyof HWBColor, unknown>);
 		}
 
 		if (KEYS_RGB.every(key => key in value)) {
-			state.rgb = getRgbValue(value as Record<keyof RGBColor, unknown>);
-			state.hex = rgbToHex(state.rgb as RGBColor);
-			state.hsl = rgbToHsl(state.rgb as RGBColor);
-
-			return state as ColorState;
+			return getColorStateForRgb(state, value as Record<keyof RGBColor, unknown>);
 		}
 	}
 
-	state.alpha ??= getAlpha(ALPHA_FULL_VALUE);
-	state.hex ??= HEX_BLACK;
-	state.hsl ??= {...DEFAULT_HSL};
-	state.rgb ??= {...DEFAULT_RGB};
+	return getDefaultColorState(state);
+}
+
+function getColorStateForHex(value: string): ColorState {
+	const normalized = getNormalizedHex(value, true);
+	const hex = normalized.slice(0, LENGTH_LONG);
+
+	const hsl = hexToHsl(hex);
+
+	return {
+		hex,
+		hsl,
+		alpha: getAlpha(normalized.slice(LENGTH_LONG)),
+		hwb: hslToHwb(hsl),
+		rgb: hslToRgb(hsl),
+	};
+}
+
+function getColorStateForHsl(
+	state: Partial<ColorState>,
+	value: Record<keyof HSLColor, unknown>,
+): ColorState {
+	state.hsl = getHslValue(value);
+
+	state.rgb = hslToRgb(state.hsl);
+	state.hex = hslToHex(state.hsl);
+	state.hwb = hslToHwb(state.hsl);
+
+	return state as ColorState;
+}
+
+function getColorStateForHwb(
+	state: Partial<ColorState>,
+	value: Record<keyof HWBColor, unknown>,
+): ColorState {
+	state.hwb = getHwbValue(value);
+
+	state.hsl = hwbToHsl(state.hwb);
+	state.rgb = hwbToRgb(state.hwb);
+	state.hex = hwbToHex(state.hwb);
+
+	return state as ColorState;
+}
+
+function getColorStateForRgb(
+	state: Partial<ColorState>,
+	value: Record<keyof RGBColor, unknown>,
+): ColorState {
+	state.rgb = getRgbValue(value);
+
+	state.hex = rgbToHex(state.rgb);
+	state.hsl = rgbToHsl(state.rgb);
+	state.hwb = rgbToHwb(state.rgb);
+
+	return state as ColorState;
+}
+
+function getDefaultColorState(state: Partial<ColorState>): ColorState {
+	state.alpha = getAlpha(MAX_PERCENT);
+	state.hex = HEX_BLACK;
+	state.hsl = {...DEFAULT_HSL};
+	state.hwb = {...DEFAULT_HWB};
+	state.rgb = {...DEFAULT_RGB};
 
 	return state as ColorState;
 }
@@ -77,11 +135,13 @@ export function setHexColor(state: ColorState, value: string, alpha: boolean): v
 
 	const normalized = getNormalizedHex(value, true);
 	const hex = normalized.slice(0, LENGTH_LONG);
-	const rgb = hexToRgb(hex);
+	const hsl = hexToHsl(hex);
 
 	state.hex = hex;
-	state.hsl = rgbToHsl(rgb);
-	state.rgb = rgb;
+	state.hsl = hsl;
+
+	state.rgb = hslToRgb(hsl);
+	state.hwb = hslToHwb(hsl);
 
 	if (alpha) {
 		state.alpha = getAlpha(normalized.slice(LENGTH_LONG));
@@ -95,21 +155,43 @@ export function setHSLColor(state: ColorState, value: unknown, alpha: boolean):
 
 	const hsl = {
 		hue: getDegrees((value as HSLColor).hue),
-		lightness: getPercentage((value as HSLColor).lightness),
 		saturation: getPercentage((value as HSLColor).saturation),
+		lightness: getPercentage((value as HSLColor).lightness),
 	};
 
-	const rgb = hslToRgb(hsl);
-
-	state.hex = rgbToHex(rgb);
 	state.hsl = hsl;
-	state.rgb = rgb;
+
+	state.hex = hslToHex(hsl);
+	state.hwb = hslToHwb(hsl);
+	state.rgb = hslToRgb(hsl);
 
 	if (alpha) {
 		state.alpha = getAlpha((value as HSLAColor).alpha);
 	}
 }
 
+export function setHWBColor(state: ColorState, value: unknown, alpha: boolean): void {
+	if (!isHwbLike(value)) {
+		return;
+	}
+
+	const hwb = {
+		hue: getDegrees((value as HWBColor).hue),
+		whiteness: getPercentage((value as HWBColor).whiteness),
+		blackness: getPercentage((value as HWBColor).blackness),
+	};
+
+	state.hwb = hwb;
+
+	state.hex = hwbToHex(hwb);
+	state.hsl = hwbToHsl(hwb);
+	state.rgb = hwbToRgb(hwb);
+
+	if (alpha) {
+		state.alpha = getAlpha((value as HWBAColor).alpha);
+	}
+}
+
 export function setRGBColor(state: ColorState, value: unknown, alpha: boolean): void {
 	if (!isRgbLike(value)) {
 		return;
@@ -121,10 +203,14 @@ export function setRGBColor(state: ColorState, value: unknown, alpha: boolean):
 		red: getHexValue((value as RGBColor).red),
 	};
 
-	state.hex = rgbToHex(rgb);
-	state.hsl = rgbToHsl(rgb);
+	const hsl = rgbToHsl(rgb);
+
+	state.hsl = hsl;
 	state.rgb = rgb;
 
+	state.hex = hslToHex(hsl);
+	state.hwb = hslToHwb(hsl);
+
 	if (alpha) {
 		state.alpha = getAlpha((value as RGBAColor).alpha);
 	}

package/src/color/models.ts

@@ -35,6 +35,23 @@ export type HSLColor = {
 	saturation: number;
 };
 
+export type HWBColor = {
+	/**
+	 * Blackness of the color _(in percentage; 0-100)_
+	 */
+	blackness: number;
+	/**
+	 * Hue of the color _(in degrees; 0-360)_
+	 */
+	hue: number;
+	/**
+	 * Whiteness of the color _(in percentage; 0-100)_
+	 */
+	whiteness: number;
+};
+
+export type HWBAColor = HWBColor & ColorWithAlpha;
+
 /**
  * An _RGB_ color with an alpha channel _(opacity)_
  */
@@ -58,7 +75,7 @@ export type RGBColor = {
 	red: number;
 };
 
-export type ColorProperty = 'alpha' | 'blue' | 'green' | 'hue' | 'lightness' | 'red' | 'saturation';
+export type ColorProperty = 'alpha' | keyof HSLColor | keyof HWBColor | keyof RGBColor;
 
 export type ColorSpace = 'hsl' | 'rgb';
 
@@ -66,6 +83,7 @@ export type ColorState = {
 	alpha: Alpha;
 	hex: string;
 	hsl: HSLColor;
+	hwb: HWBColor;
 	rgb: RGBColor;
 };
 

package/src/color/space/hex.ts

@@ -9,9 +9,10 @@ import {
 	LENGTH_SHORT,
 	MAX_HEX,
 } from '../constants';
+import {getHexValue, getPercentage} from '../misc/get';
 import {isHexColor} from '../misc/is';
-import type {HSLAColor, HSLColor, RGBAColor, RGBColor} from '../models';
-import {convertRgbToHsla} from './rgb';
+import type {HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor} from '../models';
+import {convertRgbToHsla, convertRgbToHwba} from './rgb';
 
 // #region Functions
 
@@ -27,10 +28,10 @@ function convertHexToRgba(value: string): RGBAColor {
 	}
 
 	return {
-		alpha: values[3] / MAX_HEX,
-		blue: values[2],
-		green: values[1],
-		red: values[0],
+		alpha: getPercentage((values[3] / MAX_HEX) * 100),
+		blue: getHexValue(values[2]),
+		green: getHexValue(values[1]),
+		red: getHexValue(values[0]),
 	};
 }
 
@@ -66,6 +67,14 @@ export function getNormalizedHex(value: unknown, alpha?: boolean): string {
 	return `${hex}${a}`;
 }
 
+/**
+ * Convert a hex color string to a _HSL_ color
+ *
+ * _If the value is unable to be converted, a black _HSL_ color will be returned_
+ *
+ * @param value Hex color string
+ * @returns _HSL_ color
+ */
 export function hexToHsl(value: string): HSLColor {
 	const {hue, lightness, saturation} = hexToHsla(value);
 
@@ -76,14 +85,52 @@ export function hexToHsl(value: string): HSLColor {
 	};
 }
 
+/**
+ * Convert a hex color string to a _HSLA_ color
+ *
+ * _If the value is unable to be converted, a black _HSLA_ color will be returned_
+ *
+ * @param value Hex color string
+ * @returns _HSLA_ color
+ */
 export function hexToHsla(value: string): HSLAColor {
 	return convertRgbToHsla(convertHexToRgba(value));
 }
 
+/**
+ * Convert a hex color string to a _HWB_ color
+ *
+ * _If the value is unable to be converted, a black _HWB_ color will be returned_
+ *
+ * @param value Hex color string
+ * @returns _HWB_ color
+ */
+export function hexToHwb(value: string): HWBColor {
+	const {blackness, hue, whiteness} = hexToHwba(value);
+
+	return {
+		hue,
+		whiteness,
+		blackness,
+	};
+}
+
+/**
+ * Convert a hex color string to a _HWBA_ color
+ *
+ * _If the value is unable to be converted, a black _HWBA_ color will be returned_
+ *
+ * @param value Hex color string
+ * @returns _HWBA_ color
+ */
+export function hexToHwba(value: string): HWBAColor {
+	return convertRgbToHwba(convertHexToRgba(value));
+}
+
 /**
  * Convert a hex color to an _RGB_ color
  *
- * _If the value is unable to be converted, a black RGB color will be returned_
+ * _If the value is unable to be converted, a black _RGB_ color will be returned_
  *
  * @param value Original value
  * @returns _RGB_ color
@@ -97,7 +144,7 @@ export function hexToRgb(value: string): RGBColor {
 /**
  * Convert a hex color to an _RGBA_ color
  *
- * _If the value is unable to be converted, a black RGBA color with an alpha channel (opacity) of `0` will be returned_
+ * _If the value is unable to be converted, a black _RGBA_ color will be returned_
  *
  * @param value Original value
  * @returns _RGBA_ color

package/src/color/space/hsl.ts

@@ -1,24 +1,51 @@
-import {ALPHA_FULL_VALUE, DEFAULT_HSL, MAX_DEGREE, MAX_HEX, MAX_PERCENT} from '../constants';
+import {DEFAULT_HSL, MAX_DEGREE, MAX_HEX, MAX_PERCENT} from '../constants';
 import {getAlphaValue} from '../misc/alpha';
-import {getHexValue, getDegrees, getPercentage} from '../misc/get';
+import {getDegrees, getHexValue, getPercentage} from '../misc/get';
 import {isHslLike} from '../misc/is';
-import type {HSLAColor, HSLColor, RGBAColor, RGBColor} from '../models';
+import type {HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor} from '../models';
 import {convertRgbToHex} from './rgb';
 
 // #region Functions
 
-function convertHslToRgba(value: unknown): RGBAColor {
-	const hsl = isHslLike(value) ? getHslValue(value) : {...DEFAULT_HSL};
+function convertHslToHwba(input: unknown): HWBAColor {
+	const hsl = isHslLike(input) ? getHslValue(input) : {...DEFAULT_HSL};
+
+	let {hue, lightness, saturation} = hsl;
+
+	lightness /= MAX_PERCENT;
+	saturation /= MAX_PERCENT;
+
+	const value = lightness + saturation * Math.min(lightness, 1 - lightness);
+
+	if (value === 0) {
+		saturation = 0;
+	} else {
+		saturation = 2 * (1 - lightness / value);
+	}
+
+	const blackness = 1 - value;
+	const whiteness = (1 - saturation) * value;
+
+	return {
+		hue,
+		whiteness: whiteness * MAX_PERCENT,
+		blackness: blackness * MAX_PERCENT,
+		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? MAX_PERCENT),
+	};
+}
+
+function convertHslToRgba(input: unknown): RGBAColor {
+	const hsl = isHslLike(input) ? getHslValue(input) : {...DEFAULT_HSL};
 
 	const hue = hsl.hue % MAX_DEGREE;
 	const saturation = hsl.saturation / MAX_PERCENT;
 	const lightness = hsl.lightness / MAX_PERCENT;
 
 	return {
-		alpha: getAlphaValue((value as HSLAColor).alpha ?? ALPHA_FULL_VALUE),
-		blue: getHexValue(Math.round(getHexyValue(hue, lightness, saturation, 4))),
-		green: getHexValue(Math.round(getHexyValue(hue, lightness, saturation, 8))),
-		red: getHexValue(Math.round(getHexyValue(hue, lightness, saturation, 0))),
+		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? MAX_PERCENT),
+		blue: getHexValue(getHexyValue(hue, lightness, saturation, 4)),
+		green: getHexValue(getHexyValue(hue, lightness, saturation, 8)),
+		red: getHexValue(getHexyValue(hue, lightness, saturation, 0)),
 	};
 }
 
@@ -32,24 +59,63 @@ function getHexyValue(hue: number, lightness: number, saturation: number, value:
 export function getHslValue(value: Record<keyof HSLColor, unknown>): HSLColor {
 	return {
 		hue: getDegrees(value.hue),
-		lightness: getPercentage(value.lightness),
 		saturation: getPercentage(value.saturation),
+		lightness: getPercentage(value.lightness),
 	};
 }
 
+/**
+ * Convert an _HSL(A)_ color to a hex color _(with optional alpha channel, i.e., opacity)_
+ *
+ * _If the value is unable to be converted, a black hex color will be returned_
+ *
+ * @param hsl _HSL(A)_ color
+ * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+ * @returns Hex color string
+ */
 export function hslToHex(hsl: HSLAColor | HSLColor, alpha?: boolean): string {
 	return convertRgbToHex(convertHslToRgba(hsl), alpha ?? false);
 }
 
+/**
+ * Convert an _HSL(A)_ color to an _HWB_ color
+ *
+ * _If the value is unable to be converted, a black _HWB_ color will be returned_
+ *
+ * @param hsl HSL(A) color
+ * @returns _HWB_ color
+ */
+export function hslToHwb(hsl: HSLAColor | HSLColor): HWBColor {
+	const {blackness, hue, whiteness} = convertHslToHwba(hsl);
+
+	return {
+		hue,
+		whiteness,
+		blackness,
+	};
+}
+
+/**
+ * Convert an _HSL(A)_ color to an _HWBA_ color
+ *
+ * _If the value is unable to be converted, a black _HWBA_ color will be returned_
+ *
+ * @param hsl HSL(A) color
+ * @returns _HWBA_ color
+ */
+export function hslToHwba(hsl: HSLAColor | HSLColor): HWBAColor {
+	return convertHslToHwba(hsl);
+}
+
 /**
  * Convert an _HSL(A)_ color to an _RGB_ color
  *
- * _If the value is unable to be converted, a black RGB color will be returned_
+ * _If the value is unable to be converted, a black _RGB_ color will be returned_
  *
  * _Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61_
  *
  * @param hsl HSL(A) color
- * @returns RGB color
+ * @returns _RGB_ color
  */
 export function hslToRgb(hsl: HSLAColor | HSLColor): RGBColor {
 	const {blue, green, red} = convertHslToRgba(hsl);
@@ -64,12 +130,12 @@ export function hslToRgb(hsl: HSLAColor | HSLColor): RGBColor {
 /**
  * Convert an _HSL(A)_ color to an _RGBA_ color
  *
- * _If the value is unable to be converted, a black RGBA color with an alpha channel (opactiy) of `0` will be returned_
+ * _If the value is unable to be converted, a black _RGBA_ color will be returned_
  *
  * _Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61_
  *
  * @param hsl HSL(A) color
- * @returns RGBA color
+ * @returns _RGBA_ color
  */
 export function hslToRgba(hsl: HSLAColor | HSLColor): RGBAColor {
 	return convertHslToRgba(hsl);

package/src/color/space/hwb.ts

@@ -0,0 +1,123 @@
+import {DEFAULT_HWB, MAX_PERCENT} from '../constants';
+import {getAlphaValue} from '../misc/alpha';
+import {getDegrees, getPercentage} from '../misc/get';
+import {isHwbLike} from '../misc/is';
+import type {HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor} from '../models';
+import {hslToRgb, hslToRgba} from './hsl';
+import {rgbToHex} from './rgb';
+
+// #region Functions
+
+export function convertHwbToHsl(input: HWBAColor | HWBColor): HSLAColor {
+	let {blackness, hue, whiteness} = isHwbLike(input) ? getHwbValue(input) : DEFAULT_HWB;
+
+	blackness /= MAX_PERCENT;
+	whiteness /= MAX_PERCENT;
+
+	if (blackness + whiteness > 1) {
+		const total = blackness + whiteness;
+
+		blackness /= total;
+		whiteness /= total;
+	}
+
+	const lightness = (1 - blackness + whiteness) / 2;
+
+	const saturation = getHwbSaturation(blackness, whiteness, lightness);
+
+	return {
+		hue,
+		saturation: saturation * MAX_PERCENT,
+		lightness: lightness * MAX_PERCENT,
+		alpha: getAlphaValue((input as HWBAColor)?.alpha ?? MAX_PERCENT),
+	};
+}
+
+function getHwbSaturation(blackness: number, whiteness: number, lightness: number): number {
+	const value = 1 - blackness;
+
+	const hue = value - whiteness;
+
+	if (hue <= 0) {
+		return 0;
+	}
+
+	return hue / Math.min(2 * lightness, 2 - 2 * lightness);
+}
+
+export function getHwbValue(value: Record<keyof HWBColor, unknown>): HWBColor {
+	return {
+		hue: getDegrees(value.hue),
+		whiteness: getPercentage(value.whiteness),
+		blackness: getPercentage(value.blackness),
+	};
+}
+
+/**
+ * Convert an _HWB(A)_ color to a hex color _(with optional alpha channel, i.e., opacity)_
+ *
+ * _If the value is unable to be converted, a black hex color will be returned_
+ *
+ * @param hwb _HWB(A)_ color
+ * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+ * @returns Hex color string
+ */
+export function hwbToHex(hwb: HWBAColor | HWBColor, alpha?: boolean): string {
+	return rgbToHex(hwbToRgb(hwb), alpha);
+}
+
+/**
+ * Convert an _HWB(A)_ color to an _RGB_ color
+ *
+ * _If the value is unable to be converted, a black _RGB_ color will be returned_
+ *
+ * @param hwb _HWB(A)_ color
+ * @returns _RGB_ color
+ */
+export function hwbToHsl(hwb: HWBAColor | HWBColor): HSLColor {
+	const {hue, lightness, saturation} = convertHwbToHsl(hwb);
+
+	return {
+		hue,
+		lightness,
+		saturation,
+	};
+}
+
+/**
+ * Convert an _HWB(A)_ color to an _HSLA_ color
+ *
+ * _If the value is unable to be converted, a black _HSLA_ color will be returned_
+ *
+ * @param hwb _HWB(A)_ color
+ * @returns _HSLA_ color
+ */
+export function hwbToHsla(hwb: HWBAColor | HWBColor): HSLAColor {
+	return convertHwbToHsl(hwb);
+}
+
+/**
+ * Convert an _HWB(A)_ color to an _RGB_ color
+ *
+ * _If the value is unable to be converted, a black _RGB_ color will be returned_
+ *
+ * @param hwb _HWB(A)_ color
+ * @returns _RGB_ color
+ */
+export function hwbToRgb(hwb: HWBAColor | HWBColor): RGBColor {
+	return hslToRgb(hwbToHsl(hwb));
+}
+
+/**
+ * Convert an _HWB(A)_ color to an _RGBA_ color
+ *
+ * _If the value is unable to be converted, a black _RGBA_ color will be returned_
+ *
+ * @param hwb _HWB(A)_ color
+ * @returns _RGBA_ color
+ */
+export function hwbToRgba(hwb: HWBAColor | HWBColor): RGBAColor {
+	return hslToRgba(hwbToHsla(hwb));
+}
+
+// #endregion