@oscarpalmer/atoms 0.186.2 → 0.187.0

package/dist/color/instance.mjs

@@ -9,55 +9,86 @@ import { getColorState, setHSLColor, setHexColor, setRGBColor } from "./misc/sta
 var Color = class {
 	#state;
 	/**
-	* Get the alpha channel
+	* Get the alpha channel _(opacity)_ of the color
+	*
+	* @returns Current alpha channel value between `0` and `1`
 	*/
 	get alpha() {
 		return this.#state.alpha.value;
 	}
 	/**
-	* Set the alpha channel
+	* Set the alpha channel _(opacity)_ of the color, as:
+	*
+	* - A number between `0` and `1`, where `0` is fully transparent and `1` is fully opaque
+	* - A number between `0` and `100`, where `0` is fully transparent and `100` is fully opaque
+	*
+	* @param value New alpha channel value
 	*/
 	set alpha(value) {
 		if (typeof value === "number" && !Number.isNaN(value)) this.#state.alpha = getAlpha(value);
 	}
 	/**
-	* Get the color as a hex color
+	* Get the color as a hex color string
+	*
+	* _Hex color string is returned with no `#`-prefix or alpha channel (opacity)_
+	*
+	* @returns Current color as a hex color string
 	*/
 	get hex() {
 		return this.#state.hex;
 	}
 	/**
-	* Set colors from a hex color
+	* Set the color from a hex color string
+	*
+	* - `#`-prefix is optional
+	* - Alpha channel _(opacity)_ will be ignored
+	*
+	* @param value New hex color string
 	*/
 	set hex(value) {
 		setHexColor(this.#state, value, false);
 	}
 	/**
-	* Get the color as a hex color with an alpha channel
+	* Get the color as a hex color with an alpha channel _(opacity)_
+	*
+	* _Hex color string is returned with alpha channel (opacity), but without `#`-prefix_
+	*
+	* @returns Current color as a hex color string
 	*/
 	get hexa() {
 		return `${this.#state.hex}${this.#state.alpha.hex}`;
 	}
 	/**
-	* Set colors and alpha from a hex color with an alpha channel
+	* Set the color from a hex color string with an alpha channel _(opacity)_
+	*
+	* - `#`-prefix is optional
+	* - Alpha channel _(opacity)_ will be respected
+	*
+	* @param value New hex color string
 	*/
 	set hexa(value) {
 		setHexColor(this.#state, value, true);
 	}
 	/**
-	* Get the color as an HSL color
+	* Get the color as an _HSL_ color
+	*
+	* @returns Current color as an _HSL_ color
 	*/
 	get hsl() {
 		return this.#state.hsl;
 	}
 	/**
-	* Set colors from an HSL color
+	* Set colors from an _HSL_ color
+	*
+	* @param value New _HSL_ color
 	*/
 	set hsl(value) {
 		setHSLColor(this.#state, value, false);
 	}
 	/**
-	* Get the color as an HSLA color
+	* Get the color as an _HSLA_ color
+	*
+	* @returns Current color as an _HSLA_ color
 	*/
 	get hsla() {
 		return {
@@ -66,25 +97,33 @@ var Color = class {
 		};
 	}
 	/**
-	* Set colors and alpha from an HSLA color
+	* Set colors and alpha from an _HSLA_ color
+	*
+	* @param value New _HSLA_ color
 	*/
 	set hsla(value) {
 		setHSLColor(this.#state, value, true);
 	}
 	/**
-	* Get the color as an RGB color
+	* Get the color as an _RGB_ color
+	*
+	* @returns Current color as an _RGB_ color
 	*/
 	get rgb() {
 		return this.#state.rgb;
 	}
 	/**
-	* Set colors from an RGB color
+	* Set colors from an _RGB_ color
+	*
+	* @param value New _RGB_ color
 	*/
 	set rgb(value) {
 		setRGBColor(this.#state, value, false);
 	}
 	/**
-	* Get the color as an RGBA color
+	* Get the color as an _RGBA_ color
+	*
+	* @returns Current color as an _RGBA_ color
 	*/
 	get rgba() {
 		return {
@@ -93,7 +132,9 @@ var Color = class {
 		};
 	}
 	/**
-	* Set colors and alpha from an RGBA color
+	* Set colors and alpha from an _RGBA_ color
+	*
+	* @param value New _RGBA_ color
 	*/
 	set rgba(value) {
 		setRGBColor(this.#state, value, true);
@@ -102,15 +143,38 @@ var Color = class {
 		this.#state = getColorState(value);
 		Object.defineProperty(this, "$color", { value: true });
 	}
+	/**
+	* Get the color as a hex string
+	*
+	* @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+	* @returns Hex color string
+	*/
 	toHexString(alpha) {
 		return `#${alpha === true ? this.hexa : this.hex}`;
 	}
+	/**
+	* Get the color as an _HSL(A)_ string
+	*
+	* @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+	* @returns _HSL(A)_ color string
+	*/
 	toHslString(alpha) {
 		return formatColor("hsl", this, alpha === true);
 	}
+	/**
+	* Get the color as an _RGB(A)_ string
+	*
+	* @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+	* @returns _RGB(A)_ color string
+	*/
 	toRgbString(alpha) {
 		return formatColor("rgb", this, alpha === true);
 	}
+	/**
+	* Get the color as a hex color string
+	*
+	* @returns Hex color string
+	*/
 	toString() {
 		return this.toHexString();
 	}

package/dist/color/misc/get.d.mts

@@ -4,47 +4,75 @@ import { Color } from "../instance.mjs";
 //#region src/color/misc/get.d.ts
 /**
  * Get a foreground color _(usually text)_ based on a background color's luminance
+ *
+ * - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+ * - If the value cannot be parsed, a white foreground color will be returned
+ *
  * @param value Original value
  * @returns Foreground color
  */
 declare function getForegroundColor(value: unknown): Color;
 /**
- * Get the hex color _(with alpha channel)_ from any kind of value
+ * Get the hex color _(with alpha channel, i.e., opacity)_ from any kind of value
+ *
+ * - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+ * - If the value cannot be parsed, a black hex color with an alpha channel of `0` will be returned
+ *
  * @param value Original value
- * @returns Hex color
+ * @returns Hex color string
  */
 declare function getHexaColor(value: unknown): string;
 /**
  * Get the hex color from any kind of value
+ *
+ * - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+ * - If the value cannot be parsed, a black hex color will be returned
+ *
  * @param value Original value
- * @returns Hex color
+ * @returns Hex color string
  */
 declare function getHexColor(value: unknown): string;
 declare function getHexValue(value: unknown): number;
 declare function getDegrees(value: unknown): number;
 /**
- * Get the HSLA color from any kind of value
+ * Get the _HSLA_ color from any kind of value
+ *
+ * - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+ * - If the value cannot be parsed, a black _HSLA_ color with an alpha channel _(opacity)_ of `0` will be returned
+ *
  * @param value Original value
- * @returns HSLA color
+ * @returns _HSLA_ color
  */
 declare function getHslaColor(value: unknown): HSLAColor;
 /**
- * Get the HSL color from any kind of value
+ * Get the _HSL_ color from any kind of value
+ *
+ * - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+ * - If the value cannot be parsed, a black _HSL_ color will be returned
+ *
  * @param value Original value
- * @returns HSL color
+ * @returns _HSL_ color
  */
 declare function getHslColor(value: unknown): HSLColor;
 declare function getPercentage(value: unknown): number;
 /**
- * Get the RGBA color from any kind of value
+ * Get the _RGBA_ color from any kind of value
+ *
+ * - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+ * - If the value cannot be parsed, a black _RGBA_ color with an alpha channel _(opacity)_ of `0` will be returned
+ *
  * @param value Original value
- * @returns RGBA color
+ * @returns _RGBA_ color
  */
 declare function getRgbaColor(value: unknown): RGBAColor;
 /**
- * Get the RGB color from any kind of value
+ * Get the _RGB_ color from any kind of value
+ *
+ * - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+ * - If the value cannot be parsed, a black _RGB_ color will be returned
+ *
  * @param value Original value
- * @returns RGB color
+ * @returns _RGB_ color
  */
 declare function getRgbColor(value: unknown): RGBColor;
 //#endregion

package/dist/color/misc/get.mjs

@@ -8,6 +8,10 @@ function getClampedValue(value, minimum, maximum) {
 }
 /**
 * Get a foreground color _(usually text)_ based on a background color's luminance
+*
+* - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+* - If the value cannot be parsed, a white foreground color will be returned
+*
 * @param value Original value
 * @returns Foreground color
 */
@@ -27,9 +31,13 @@ function getForegroundColor(value) {
 	return new Color(.2126 * values[2] + .7152 * values[1] + .0722 * values[0] > .625 ? HEX_BLACK : HEX_WHITE);
 }
 /**
-* Get the hex color _(with alpha channel)_ from any kind of value
+* Get the hex color _(with alpha channel, i.e., opacity)_ from any kind of value
+*
+* - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+* - If the value cannot be parsed, a black hex color with an alpha channel of `0` will be returned
+*
 * @param value Original value
-* @returns Hex color
+* @returns Hex color string
 */
 function getHexaColor(value) {
 	const { alpha, hex } = getColorState(value);
@@ -37,8 +45,12 @@ function getHexaColor(value) {
 }
 /**
 * Get the hex color from any kind of value
+*
+* - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+* - If the value cannot be parsed, a black hex color will be returned
+*
 * @param value Original value
-* @returns Hex color
+* @returns Hex color string
 */
 function getHexColor(value) {
 	return getColorState(value).hex;
@@ -50,9 +62,13 @@ function getDegrees(value) {
 	return getClampedValue(value, 0, 360);
 }
 /**
-* Get the HSLA color from any kind of value
+* Get the _HSLA_ color from any kind of value
+*
+* - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+* - If the value cannot be parsed, a black _HSLA_ color with an alpha channel _(opacity)_ of `0` will be returned
+*
 * @param value Original value
-* @returns HSLA color
+* @returns _HSLA_ color
 */
 function getHslaColor(value) {
 	const { alpha, hsl } = getColorState(value);
@@ -62,9 +78,13 @@ function getHslaColor(value) {
 	};
 }
 /**
-* Get the HSL color from any kind of value
+* Get the _HSL_ color from any kind of value
+*
+* - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+* - If the value cannot be parsed, a black _HSL_ color will be returned
+*
 * @param value Original value
-* @returns HSL color
+* @returns _HSL_ color
 */
 function getHslColor(value) {
 	return getColorState(value).hsl;
@@ -73,9 +93,13 @@ function getPercentage(value) {
 	return getClampedValue(value, 0, 100);
 }
 /**
-* Get the RGBA color from any kind of value
+* Get the _RGBA_ color from any kind of value
+*
+* - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+* - If the value cannot be parsed, a black _RGBA_ color with an alpha channel _(opacity)_ of `0` will be returned
+*
 * @param value Original value
-* @returns RGBA color
+* @returns _RGBA_ color
 */
 function getRgbaColor(value) {
 	const { alpha, rgb } = getColorState(value);
@@ -85,9 +109,13 @@ function getRgbaColor(value) {
 	};
 }
 /**
-* Get the RGB color from any kind of value
+* Get the _RGB_ color from any kind of value
+*
+* - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+* - If the value cannot be parsed, a black _RGB_ color will be returned
+*
 * @param value Original value
-* @returns RGB color
+* @returns _RGB_ color
 */
 function getRgbColor(value) {
 	return getColorState(value).rgb;

package/dist/color/misc/is.d.mts

@@ -3,41 +3,56 @@ import { Color } from "../instance.mjs";
 
 //#region src/color/misc/is.d.ts
 /**
- * Is the value a Color?
+ * Is the value a _Color_?
+ *
  * @param value Value to check
- * @returns `true` if the value is a Color, otherwise `false`
+ * @returns `true` if the value is a _Color_, otherwise `false`
  */
 declare function isColor(value: unknown): value is Color;
 /**
  * Is the value a hex color?
+ *
  * @param value Value to check
- * @param alpha Allow alpha channel? _(defaults to `true`)_
+ * @param alpha Allow alpha channel _(opacity)_? _(defaults to `true`)_
  * @returns `true` if the value is a hex color, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * isHexColor('ff0000');  // => true
+ * isHexColor('#ff0000'); // => true
+ *
+ * isHexColor('#ff000050');        // => true
+ * isHexColor('#ff000050', false); // => false
+ * ```
  */
 declare function isHexColor(value: unknown, alpha?: boolean): value is string;
 /**
- * Is the value an HSLA color?
+ * Is the value an _HSLA_ color?
+ *
  * @param value Value to check
- * @returns `true` if the value is an HSLA color, otherwise `false`
+ * @returns `true` if the value is an _HSLA_ color, otherwise `false`
  */
 declare function isHslaColor(value: unknown): value is HSLAColor;
 /**
- * Is the value an HSL color?
+ * Is the value an _HSL_ color?
+ *
  * @param value Value to check
- * @returns `true` if the value is an HSL color, otherwise `false`
+ * @returns `true` if the value is an _HSL_ color, otherwise `false`
  */
 declare function isHslColor(value: unknown): value is HSLColor;
 declare function isHslLike(value: unknown): value is Record<keyof HSLColor, unknown>;
 /**
- * Is the value an RGBA color?
+ * Is the value an _RGBA_ color?
+ *
  * @param value Value to check
- * @returns `true` if the value is an RGBA color, otherwise `false`
+ * @returns `true` if the value is an _RGBA_ color, otherwise `false`
  */
 declare function isRgbaColor(value: unknown): value is RGBAColor;
 /**
- * Is the value an RGB color?
+ * Is the value an _RGB_ color?
+ *
  * @param value Value to check
- * @returns `true` if the value is an RGB color, otherwise `false`
+ * @returns `true` if the value is an _RGB_ color, otherwise `false`
  */
 declare function isRgbColor(value: unknown): value is RGBColor;
 declare function isRgbLike(value: unknown): value is Record<keyof RGBColor, unknown>;

package/dist/color/misc/is.mjs

@@ -11,9 +11,10 @@ function isBytey(value) {
 	return typeof value === "number" && between(value, 0, 255);
 }
 /**
-* Is the value a Color?
+* Is the value a _Color_?
+*
 * @param value Value to check
-* @returns `true` if the value is a Color, otherwise `false`
+* @returns `true` if the value is a _Color_, otherwise `false`
 */
 function isColor(value) {
 	return typeof value === "object" && value !== null && "$color" in value && value.$color === true;
@@ -34,9 +35,19 @@ function isDegree(value) {
 }
 /**
 * Is the value a hex color?
+*
 * @param value Value to check
-* @param alpha Allow alpha channel? _(defaults to `true`)_
+* @param alpha Allow alpha channel _(opacity)_? _(defaults to `true`)_
 * @returns `true` if the value is a hex color, otherwise `false`
+*
+* @example
+* ```typescript
+* isHexColor('ff0000');  // => true
+* isHexColor('#ff0000'); // => true
+*
+* isHexColor('#ff000050');        // => true
+* isHexColor('#ff000050', false); // => false
+* ```
 */
 function isHexColor(value, alpha) {
 	if (typeof value !== "string") return false;
@@ -45,17 +56,19 @@ function isHexColor(value, alpha) {
 	return true;
 }
 /**
-* Is the value an HSLA color?
+* Is the value an _HSLA_ color?
+*
 * @param value Value to check
-* @returns `true` if the value is an HSLA color, otherwise `false`
+* @returns `true` if the value is an _HSLA_ color, otherwise `false`
 */
 function isHslaColor(value) {
 	return isColorValue(value, KEYS_HSLA);
 }
 /**
-* Is the value an HSL color?
+* Is the value an _HSL_ color?
+*
 * @param value Value to check
-* @returns `true` if the value is an HSL color, otherwise `false`
+* @returns `true` if the value is an _HSL_ color, otherwise `false`
 */
 function isHslColor(value) {
 	return isColorValue(value, KEYS_HSLA) || isColorValue(value, KEYS_HSL);
@@ -64,17 +77,19 @@ function isHslLike(value) {
 	return hasKeys(value, KEYS_HSL);
 }
 /**
-* Is the value an RGBA color?
+* Is the value an _RGBA_ color?
+*
 * @param value Value to check
-* @returns `true` if the value is an RGBA color, otherwise `false`
+* @returns `true` if the value is an _RGBA_ color, otherwise `false`
 */
 function isRgbaColor(value) {
 	return isColorValue(value, KEYS_RGBA);
 }
 /**
-* Is the value an RGB color?
+* Is the value an _RGB_ color?
+*
 * @param value Value to check
-* @returns `true` if the value is an RGB color, otherwise `false`
+* @returns `true` if the value is an _RGB_ color, otherwise `false`
 */
 function isRgbColor(value) {
 	return isColorValue(value, KEYS_RGBA) || isColorValue(value, KEYS_RGB);

package/dist/color/misc/state.mjs

@@ -41,7 +41,7 @@ function getColorState(value) {
 		}
 	}
 	state.alpha ??= getAlpha(1);
-	state.hex ??= String(HEX_BLACK);
+	state.hex ??= HEX_BLACK;
 	state.hsl ??= { ...DEFAULT_HSL };
 	state.rgb ??= { ...DEFAULT_RGB };
 	return state;

package/dist/color/models.d.mts

@@ -4,14 +4,17 @@ type Alpha = {
   value: number;
 };
 type ColorWithAlpha = {
+  /**
+   * Alpha channel _(opacity)_ of the color _(in percentage; 0-100)_
+   */
   alpha: number;
 };
 /**
- * An _HSL_-color with an alpha channel
+ * An _HSL_ color with an alpha channel _(opacity)_
  */
 type HSLAColor = HSLColor & ColorWithAlpha;
 /**
- * An _HSL_-color
+ * An _HSL_ color
  */
 type HSLColor = {
   /**
@@ -28,11 +31,11 @@ type HSLColor = {
   saturation: number;
 };
 /**
- * An _RGB_-color with an alpha channel
+ * An _RGB_ color with an alpha channel _(opacity)_
  */
 type RGBAColor = RGBColor & ColorWithAlpha;
 /**
- * An _RGB_-color
+ * An _RGB_ color
  */
 type RGBColor = {
   /**

package/dist/color/space/hex.d.mts

@@ -3,23 +3,32 @@ import { HSLAColor, HSLColor, RGBAColor, RGBColor } from "../models.mjs";
 //#region src/color/space/hex.d.ts
 /**
  * Get the normalized hex color from a value
+ *
+ * _If the value is unable to be parsed or normalized, a hex color of `000000` will be returned, with the alpha channel _(opacity)_ value `0` included, if specified_
+ *
  * @param value Value to normalize
- * @param alpha Include alpha channel? _(defaults to `false`)_
- * @returns Normalized hex color, or `000000` if the value is unable to be normalized
+ * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+ * @returns Normalized hex color
  */
 declare function getNormalizedHex(value: unknown, alpha?: boolean): string;
 declare function hexToHsl(value: string): HSLColor;
 declare function hexToHsla(value: string): HSLAColor;
 /**
- * Convert a hex color to an RGB color
+ * Convert a hex color to an _RGB_ color
+ *
+ * _If the value is unable to be converted, a black RGB color will be returned_
+ *
  * @param value Original value
- * @returns RGB color
+ * @returns _RGB_ color
  */
 declare function hexToRgb(value: string): RGBColor;
 /**
- * Convert a hex color to an RGBA color
+ * 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_
+ *
  * @param value Original value
- * @returns RGBA color
+ * @returns _RGBA_ color
  */
 declare function hexToRgba(value: string): RGBAColor;
 //#endregion

package/dist/color/space/hex.mjs

@@ -18,9 +18,12 @@ function convertHexToRgba(value) {
 }
 /**
 * Get the normalized hex color from a value
+*
+* _If the value is unable to be parsed or normalized, a hex color of `000000` will be returned, with the alpha channel _(opacity)_ value `0` included, if specified_
+*
 * @param value Value to normalize
-* @param alpha Include alpha channel? _(defaults to `false`)_
-* @returns Normalized hex color, or `000000` if the value is unable to be normalized
+* @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+* @returns Normalized hex color
 */
 function getNormalizedHex(value, alpha) {
 	const includeAlpha = alpha ?? false;
@@ -41,9 +44,12 @@ function hexToHsla(value) {
 	return convertRgbToHsla(convertHexToRgba(value));
 }
 /**
-* Convert a hex color to an RGB color
+* Convert a hex color to an _RGB_ color
+*
+* _If the value is unable to be converted, a black RGB color will be returned_
+*
 * @param value Original value
-* @returns RGB color
+* @returns _RGB_ color
 */
 function hexToRgb(value) {
 	const { blue, green, red } = convertHexToRgba(value);
@@ -54,9 +60,12 @@ function hexToRgb(value) {
 	};
 }
 /**
-* Convert a hex color to an RGBA color
+* 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_
+*
 * @param value Original value
-* @returns RGBA color
+* @returns _RGBA_ color
 */
 function hexToRgba(value) {
 	return convertHexToRgba(value);

package/dist/color/space/hsl.d.mts

@@ -4,17 +4,23 @@ import { HSLAColor, HSLColor, RGBAColor, RGBColor } from "../models.mjs";
 declare function getHslValue(value: Record<keyof HSLColor, unknown>): HSLColor;
 declare function hslToHex(hsl: HSLAColor | HSLColor, alpha?: boolean): string;
 /**
- * Convert an HSL(A) color to an RGB color
+ * Convert an _HSL(A)_ color to an _RGB_ color
+ *
+ * _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_
  *
- * Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61
  * @param hsl HSL(A) color
  * @returns RGB color
  */
 declare function hslToRgb(hsl: HSLAColor | HSLColor): RGBColor;
 /**
- * Convert an HSL(A) color to an RGBA color
+ * 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_
+ *
+ * _Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61_
  *
- * Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61
  * @param hsl HSL(A) color
  * @returns RGBA color
  */