@oscarpalmer/atoms 0.190.0 → 0.192.0

package/src/color/models.ts

@@ -1,5 +1,8 @@
 // #region Types
 
+import type {Subscription} from '../internal/subscription';
+import type {COLOR_ALPHA, COLOR_TYPE} from './constants';
+
 export type Alpha = {
 	hex: string;
 	value: number;
@@ -117,6 +120,13 @@ export type Color = {
 	 */
 	set hwba(value: HWBAColor);
 
+	/**
+	 * Last color format that was set on the color
+	 *
+	 * @returns Color type
+	 */
+	get origin(): ColorType;
+
 	/**
 	 * Get the color as an _RGB_ color
 	 *
@@ -145,6 +155,85 @@ export type Color = {
 	 */
 	set rgba(value: RGBAColor);
 
+	/**
+	 * Subscribe to alpha channel _(opacity)_ changes of the color
+	 *
+	 * @param key Color property to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: 'alpha', callback: (value: number) => void): Subscription;
+
+	/**
+	 * Subscribe to hex color changes of the color
+	 *
+	 * @param key Color type to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: typeof COLOR_TYPE.hex, callback: (value: string) => void): Subscription;
+
+	/**
+	 * Subscribe to hex color changes of the color with alpha channel _(opacity)_
+	 *
+	 * @param key Color type to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: typeof COLOR_TYPE.hexa, callback: (value: string) => void): Subscription;
+
+	/**
+	 * Subscribe to _HSL_ color changes of the color
+	 *
+	 * @param key Color type to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: typeof COLOR_TYPE.hsl, callback: (value: HSLColor) => void): Subscription;
+
+	/**
+	 * Subscribe to _HSL(A)_ color changes of the color
+	 *
+	 * @param key Color type to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: typeof COLOR_TYPE.hsla, callback: (value: HSLAColor) => void): Subscription;
+
+	/**
+	 * Subscribe to _HWB_ color changes of the color
+	 *
+	 * @param key Color type to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: typeof COLOR_TYPE.hwb, callback: (value: HWBColor) => void): Subscription;
+
+	/**
+	 * Subscribe to _HWB(A)_ color changes of the color
+	 *
+	 * @param key Color type to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: typeof COLOR_TYPE.hwba, callback: (value: HWBAColor) => void): Subscription;
+
+	/**
+	 * Subscribe to _RGB_ color changes of the color
+	 *
+	 * @param key Color type to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: typeof COLOR_TYPE.rgb, callback: (value: RGBColor) => void): Subscription;
+
+	/**
+	 * Subscribe to _RGBA_ color changes of the color
+	 *
+	 * @param key Color type to subscribe to
+	 * @param callback Callback function for changes
+	 */
+	subscribe(key: typeof COLOR_TYPE.rgba, callback: (value: RGBAColor) => void): Subscription;
+
+	/**
+	 * Subscribe to any color changes of the color
+	 *
+	 * @param callback Callback function for changes
+	 */
+	subscribe(callback: (value: Color) => void): Subscription;
+
 	/**
 	 * Get the color as a hex string
 	 *
@@ -183,6 +272,13 @@ export type Color = {
 	 * @returns Hex color string
 	 */
 	toString(): string;
+
+	/**
+	 * Unsubscribe from all color changes of the color
+	 *
+	 * _(To unsubscribe from a specific color change, use the `unsubscribe()` method on the `Subscription` returned by the individual `subscribe()` method)_
+	 */
+	unsubscribe(): void;
 };
 
 type ColorWithAlpha = {
@@ -255,14 +351,39 @@ export type RGBColor = {
 	red: number;
 };
 
-export type ColorProperty = 'alpha' | keyof HSLColor | keyof HWBColor | keyof RGBColor;
+export type ColorProperty =
+	| typeof COLOR_ALPHA.name
+	| keyof HSLColor
+	| keyof HWBColor
+	| keyof RGBColor;
 
 export type ColorState = {
 	alpha: Alpha;
-	hex: string;
-	hsl: HSLColor;
-	hwb: HWBColor;
-	rgb: RGBColor;
+	hex?: string;
+	hsl?: HSLColor;
+	hwb?: HWBColor;
+	origin: ColorType;
+	rgb?: RGBColor;
 };
 
+/**
+ * Base color types
+ */
+export type ColorType = 'hex' | 'hsl' | 'hwb' | 'rgb';
+
+/**
+ * Extended color types
+ */
+export type ColorTypeExtended = ColorType | 'hsla' | 'hwba' | 'rgba';
+
+/**
+ * Base color values
+ */
+export type ColorValue = string | HSLColor | HWBColor | RGBColor;
+
+/**
+ * Extended color values
+ */
+export type ColorValueExtended = ColorValue | HSLAColor | HWBAColor | RGBAColor;
+
 // #endregion

package/src/color/space/hex.ts

@@ -1,24 +1,31 @@
 import {join} from '../../internal/string';
 import {
-	ALPHA_FULL_HEX_LONG,
-	ALPHA_FULL_HEX_SHORT,
-	EXPRESSION_HEX_LONG,
-	EXPRESSION_PREFIX,
-	HEX_BLACK,
-	LENGTH_LONG,
-	LENGTH_SHORT,
-	MAX_HEX,
+	COLOR_ALPHA,
+	COLOR_DEFAULTS,
+	COLOR_EXPRESSION,
+	COLOR_LENGTHS,
+	COLOR_MAX,
+	COLOR_TYPE,
 } from '../constants';
 import {getHexValue, getPercentage} from '../misc/get';
 import {isHexColor} from '../misc/is';
-import type {HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor} from '../models';
+import type {
+	ColorState,
+	ColorType,
+	HSLAColor,
+	HSLColor,
+	HWBAColor,
+	HWBColor,
+	RGBAColor,
+	RGBColor,
+} from '../models';
 import {convertRgbToHsla, convertRgbToHwba} from './rgb';
 
 // #region Functions
 
 function convertHexToRgba(value: string): RGBAColor {
 	const normalized = getNormalizedHex(value, true);
-	const pairs = EXPRESSION_HEX_LONG.exec(normalized) as RegExpExecArray;
+	const pairs = COLOR_EXPRESSION.hexLong.exec(normalized) as RegExpExecArray;
 	const values: number[] = [];
 
 	const {length} = pairs;
@@ -28,13 +35,34 @@ function convertHexToRgba(value: string): RGBAColor {
 	}
 
 	return {
-		alpha: getPercentage((values[3] / MAX_HEX) * 100),
+		alpha: getPercentage((values[3] / COLOR_MAX.hex) * 100),
 		blue: getHexValue(values[2]),
 		green: getHexValue(values[1]),
 		red: getHexValue(values[0]),
 	};
 }
 
+export function getColorFromHex<Type extends ColorType>(
+	state: ColorState,
+	type: Type,
+): NonNullable<ColorState[Type]> {
+	switch (type) {
+		case COLOR_TYPE.hsl:
+			state.hsl ??= hexToHsl(state.hex!);
+			break;
+
+		case COLOR_TYPE.hwb:
+			state.hwb ??= hexToHwb(state.hex!);
+			break;
+
+		case COLOR_TYPE.rgb:
+			state.rgb ??= hexToRgb(state.hex!);
+			break;
+	}
+
+	return state[type]!;
+}
+
 /**
  * Get the normalized hex color from a value
  *
@@ -48,21 +76,21 @@ export function getNormalizedHex(value: unknown, alpha?: boolean): string {
 	const includeAlpha = alpha ?? false;
 
 	if (!isHexColor(value)) {
-		return `${HEX_BLACK}${includeAlpha ? ALPHA_FULL_HEX_LONG : ''}`;
+		return `${COLOR_DEFAULTS.hexBlack}${includeAlpha ? COLOR_ALPHA.fullHexLong : ''}`;
 	}
 
-	const normalized = value.replace(EXPRESSION_PREFIX, '');
+	const normalized = value.replace(COLOR_EXPRESSION.prefix, '');
 
-	if (normalized.length < LENGTH_LONG) {
-		const hex = normalized.slice(0, LENGTH_SHORT);
-		const a = includeAlpha ? (normalized[LENGTH_SHORT] ?? ALPHA_FULL_HEX_SHORT) : '';
+	if (normalized.length < COLOR_LENGTHS.hexLong) {
+		const hex = normalized.slice(0, COLOR_LENGTHS.hexShort);
+		const a = includeAlpha ? (normalized[COLOR_LENGTHS.hexShort] ?? COLOR_ALPHA.fullHexShort) : '';
 
 		return join(`${hex}${a}`.split('').map(character => character.repeat(2)));
 	}
 
-	const hex = normalized.slice(0, LENGTH_LONG);
+	const hex = normalized.slice(0, COLOR_LENGTHS.hexLong);
 
-	const a = includeAlpha ? normalized.slice(LENGTH_LONG) || ALPHA_FULL_HEX_LONG : '';
+	const a = includeAlpha ? normalized.slice(COLOR_LENGTHS.hexLong) || COLOR_ALPHA.fullHexLong : '';
 
 	return `${hex}${a}`;
 }

package/src/color/space/hsl.ts

@@ -1,19 +1,28 @@
-import {DEFAULT_HSL, MAX_DEGREE, MAX_HEX, MAX_PERCENT} from '../constants';
+import {COLOR_DEFAULTS, COLOR_MAX, COLOR_TYPE} from '../constants';
 import {getAlphaValue} from '../misc/alpha';
 import {getDegrees, getHexValue, getPercentage} from '../misc/get';
 import {isHslLike} from '../misc/is';
-import type {HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor} from '../models';
+import type {
+	ColorState,
+	ColorType,
+	HSLAColor,
+	HSLColor,
+	HWBAColor,
+	HWBColor,
+	RGBAColor,
+	RGBColor,
+} from '../models';
 import {convertRgbToHex} from './rgb';
 
 // #region Functions
 
 function convertHslToHwba(input: unknown): HWBAColor {
-	const hsl = isHslLike(input) ? getHslValue(input) : {...DEFAULT_HSL};
+	const hsl = isHslLike(input) ? getHslValue(input) : {...COLOR_DEFAULTS.hsl};
 
 	let {hue, lightness, saturation} = hsl;
 
-	lightness /= MAX_PERCENT;
-	saturation /= MAX_PERCENT;
+	lightness /= COLOR_MAX.percent;
+	saturation /= COLOR_MAX.percent;
 
 	const value = lightness + saturation * Math.min(lightness, 1 - lightness);
 
@@ -28,32 +37,53 @@ function convertHslToHwba(input: unknown): HWBAColor {
 
 	return {
 		hue,
-		whiteness: whiteness * MAX_PERCENT,
-		blackness: blackness * MAX_PERCENT,
-		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? MAX_PERCENT),
+		whiteness: whiteness * COLOR_MAX.percent,
+		blackness: blackness * COLOR_MAX.percent,
+		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? COLOR_MAX.percent),
 	};
 }
 
 function convertHslToRgba(input: unknown): RGBAColor {
-	const hsl = isHslLike(input) ? getHslValue(input) : {...DEFAULT_HSL};
+	const hsl = isHslLike(input) ? getHslValue(input) : {...COLOR_DEFAULTS.hsl};
 
-	const hue = hsl.hue % MAX_DEGREE;
-	const saturation = hsl.saturation / MAX_PERCENT;
-	const lightness = hsl.lightness / MAX_PERCENT;
+	const hue = hsl.hue % COLOR_MAX.degree;
+	const saturation = hsl.saturation / COLOR_MAX.percent;
+	const lightness = hsl.lightness / COLOR_MAX.percent;
 
 	return {
-		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? MAX_PERCENT),
+		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? COLOR_MAX.percent),
 		blue: getHexValue(getHexyValue(hue, lightness, saturation, 4)),
 		green: getHexValue(getHexyValue(hue, lightness, saturation, 8)),
 		red: getHexValue(getHexyValue(hue, lightness, saturation, 0)),
 	};
 }
 
+export function getColorFromHsl<Type extends ColorType>(
+	state: ColorState,
+	type: Type,
+): NonNullable<ColorState[Type]> {
+	switch (type) {
+		case COLOR_TYPE.hex:
+			state.hex = hslToHex(state.hsl!);
+			break;
+
+		case COLOR_TYPE.hwb:
+			state.hwb = hslToHwb(state.hsl!);
+			break;
+
+		case COLOR_TYPE.rgb:
+			state.rgb = hslToRgb(state.hsl!);
+			break;
+	}
+
+	return state[type]!;
+}
+
 function getHexyValue(hue: number, lightness: number, saturation: number, value: number): number {
 	const part = (value + hue / 30) % 12;
 	const mod = saturation * Math.min(lightness, 1 - lightness);
 
-	return (lightness - mod * Math.max(-1, Math.min(part - 3, 9 - part, 1))) * MAX_HEX;
+	return (lightness - mod * Math.max(-1, Math.min(part - 3, 9 - part, 1))) * COLOR_MAX.hex;
 }
 
 export function getHslValue(value: Record<keyof HSLColor, unknown>): HSLColor {

package/src/color/space/hwb.ts

@@ -1,18 +1,27 @@
-import {DEFAULT_HWB, MAX_PERCENT} from '../constants';
+import {COLOR_DEFAULTS, COLOR_MAX, COLOR_TYPE} 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 type {
+	ColorState,
+	ColorType,
+	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;
+	let {blackness, hue, whiteness} = isHwbLike(input) ? getHwbValue(input) : COLOR_DEFAULTS.hwb;
 
-	blackness /= MAX_PERCENT;
-	whiteness /= MAX_PERCENT;
+	blackness /= COLOR_MAX.percent;
+	whiteness /= COLOR_MAX.percent;
 
 	if (blackness + whiteness > 1) {
 		const total = blackness + whiteness;
@@ -27,12 +36,33 @@ export function convertHwbToHsl(input: HWBAColor | HWBColor): HSLAColor {
 
 	return {
 		hue,
-		saturation: saturation * MAX_PERCENT,
-		lightness: lightness * MAX_PERCENT,
-		alpha: getAlphaValue((input as HWBAColor)?.alpha ?? MAX_PERCENT),
+		saturation: saturation * COLOR_MAX.percent,
+		lightness: lightness * COLOR_MAX.percent,
+		alpha: getAlphaValue((input as HWBAColor)?.alpha ?? COLOR_MAX.percent),
 	};
 }
 
+export function getColorFromHwb<Type extends ColorType>(
+	state: ColorState,
+	type: Type,
+): NonNullable<ColorState[Type]> {
+	switch (type) {
+		case COLOR_TYPE.hex:
+			state.hex = hwbToHex(state.hwb!);
+			break;
+
+		case COLOR_TYPE.hsl:
+			state.hsl = hwbToHsl(state.hwb!);
+			break;
+
+		case COLOR_TYPE.rgb:
+			state.rgb = hwbToRgb(state.hwb!);
+			break;
+	}
+
+	return state[type]!;
+}
+
 function getHwbSaturation(blackness: number, whiteness: number, lightness: number): number {
 	const value = 1 - blackness;
 

package/src/color/space/rgb.ts

@@ -1,9 +1,18 @@
 import {join} from '../../internal/string';
-import {DEFAULT_RGB, MAX_HEX, MAX_PERCENT} from '../constants';
+import {COLOR_DEFAULTS, COLOR_MAX, COLOR_TYPE} from '../constants';
 import {getAlpha, getAlphaValue} from '../misc/alpha';
 import {getHexValue} from '../misc/get';
 import {isRgbLike} from '../misc/is';
-import type {HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor} from '../models';
+import type {
+	ColorState,
+	ColorType,
+	HSLAColor,
+	HSLColor,
+	HWBAColor,
+	HWBColor,
+	RGBAColor,
+	RGBColor,
+} from '../models';
 
 // #region Types
 
@@ -32,14 +41,14 @@ export function convertRgbToHex(rgb: RGBAColor | RGBColor, alpha: boolean): stri
 	let a = '';
 
 	if (typeof alpha === 'boolean' && alpha) {
-		a = getAlpha((rgb as RGBAColor).alpha).hex;
+		a = getAlpha((rgb as RGBAColor).alpha, false).hex;
 	}
 
 	return `${hex}${a}`;
 }
 
 export function convertRgbToHsla(value: unknown): HSLAColor {
-	const rgb = isRgbLike(value) ? getRgbValue(value) : {...DEFAULT_RGB};
+	const rgb = isRgbLike(value) ? getRgbValue(value) : {...COLOR_DEFAULTS.rgb};
 	const values = getRgbValues(rgb);
 
 	const {delta, max, min} = values;
@@ -59,14 +68,14 @@ export function convertRgbToHsla(value: unknown): HSLAColor {
 
 	return {
 		hue,
-		saturation: saturation * MAX_PERCENT,
-		lightness: lightness * MAX_PERCENT,
-		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? MAX_PERCENT),
+		saturation: saturation * COLOR_MAX.percent,
+		lightness: lightness * COLOR_MAX.percent,
+		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? COLOR_MAX.percent),
 	};
 }
 
 export function convertRgbToHwba(value: unknown): HWBAColor {
-	const rgb = isRgbLike(value) ? getRgbValue(value) : {...DEFAULT_RGB};
+	const rgb = isRgbLike(value) ? getRgbValue(value) : {...COLOR_DEFAULTS.rgb};
 	const values = getRgbValues(rgb);
 
 	const {delta, max, min} = values;
@@ -81,12 +90,33 @@ export function convertRgbToHwba(value: unknown): HWBAColor {
 
 	return {
 		hue,
-		whiteness: min * MAX_PERCENT,
-		blackness: (1 - max) * MAX_PERCENT,
-		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? MAX_PERCENT),
+		whiteness: min * COLOR_MAX.percent,
+		blackness: (1 - max) * COLOR_MAX.percent,
+		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? COLOR_MAX.percent),
 	};
 }
 
+export function getColorFromRgb<Type extends ColorType>(
+	state: ColorState,
+	type: Type,
+): NonNullable<ColorState[Type]> {
+	switch (type) {
+		case COLOR_TYPE.hex:
+			state.hex = rgbToHex(state.rgb!);
+			break;
+
+		case COLOR_TYPE.hsl:
+			state.hsl = rgbToHsl(state.rgb!);
+			break;
+
+		case COLOR_TYPE.hwb:
+			state.hwb = rgbToHwb(state.rgb!);
+			break;
+	}
+
+	return state[type]!;
+}
+
 function getRgbHue(values: RgbValues): number {
 	const {blue, delta, green, max, red} = values;
 
@@ -111,9 +141,9 @@ export function getRgbValue(value: Record<keyof RGBColor, unknown>): RGBColor {
 }
 
 function getRgbValues(rgb: RGBColor): RgbValues {
-	const blue = rgb.blue / MAX_HEX;
-	const green = rgb.green / MAX_HEX;
-	const red = rgb.red / MAX_HEX;
+	const blue = rgb.blue / COLOR_MAX.hex;
+	const green = rgb.green / COLOR_MAX.hex;
+	const red = rgb.red / COLOR_MAX.hex;
 
 	const max = Math.max(blue, green, red);
 	const min = Math.min(blue, green, red);
@@ -133,7 +163,10 @@ function getRgbValues(rgb: RGBColor): RgbValues {
  * @returns Hex color string
  */
 export function rgbToHex(rgb: RGBAColor | RGBColor, alpha?: boolean): string {
-	return convertRgbToHex(isRgbLike(rgb) ? getRgbValue(rgb) : {...DEFAULT_RGB}, alpha ?? false);
+	return convertRgbToHex(
+		isRgbLike(rgb) ? getRgbValue(rgb) : {...COLOR_DEFAULTS.rgb},
+		alpha ?? false,
+	);
 }
 
 /**

package/src/herald.ts

@@ -1,5 +1,5 @@
 import {noop} from './internal/function/misc';
-import type {GenericCallback} from './models';
+import type {GenericCallback, Unsubscriber} from './models';
 
 // #region Types
 
@@ -57,8 +57,6 @@ export type Herald<Map extends Record<string, GenericCallback>> = {
 	unsubscribe<Event extends keyof Map>(event: Event, callback?: Map[Event]): void;
 };
 
-export type Unsubscriber = () => void;
-
 // #endregion
 
 // #region Functions

package/src/index.ts

@@ -21,6 +21,7 @@ export * from './herald';
 
 export * from './internal/function/misc';
 export * from './internal/string';
+export {isSubscription, type Subscription} from './internal/subscription';
 export * from './internal/value/compare';
 export * from './internal/value/equal';
 export * from './internal/value/get';