@oscarpalmer/atoms 0.186.2 → 0.187.1

package/src/array/to-map.ts

@@ -40,14 +40,14 @@ function getMapValues(
 }
 
 /**
- * Create a Map from an array of items using callbacks
+ * Create a _Map_ from an array of items using callbacks
  *
  * If multiple items have the same key, the latest item's value will be used
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
- * @returns Map of keyed values
+ * @returns _Map_ of keyed values
  *
  * @example
  * ```typescript
@@ -69,14 +69,14 @@ export function toMap<
 ): Map<ReturnType<KeyCallback>, ReturnType<ValueCallback>>;
 
 /**
- * Create a Map from an array of items using a callback and value
+ * Create a _Map_ from an array of items using a callback and value
  *
  * If multiple items have the same key, the latest item's value will be used
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
- * @returns Map of keyed values
+ * @returns _Map_ of keyed values
  *
  * @example
  * ```typescript
@@ -94,14 +94,14 @@ export function toMap<
 >(array: Item[], key: KeyCallback, value: ItemValue): Map<ReturnType<KeyCallback>, Item[ItemValue]>;
 
 /**
- * Create a Map from an array of items using a key and callback
+ * Create a _Map_ from an array of items using a key and callback
  *
  * If multiple items have the same key, the latest item's value will be used
  *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
- * @returns Map of keyed values
+ * @returns _Map_ of keyed values
  *
  * @example
  * ```typescript
@@ -119,14 +119,14 @@ export function toMap<
 >(array: Item[], key: ItemKey, value: ValueCallback): Map<Item[ItemKey], ReturnType<ValueCallback>>;
 
 /**
- * Create a Map from an array of items using a key and value
+ * Create a _Map_ from an array of items using a key and value
  *
  * If multiple items have the same key, the latest item's value will be used
  *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Key to use for value
- * @returns Map of keyed values
+ * @returns _Map_ of keyed values
  *
  * @example
  * ```typescript
@@ -144,13 +144,13 @@ export function toMap<
 >(array: Item[], key: ItemKey, value: ItemValue): Map<Item[ItemKey], Item[ItemValue]>;
 
 /**
- * Create a Map from an array of items using a callback
+ * Create a _Map_ from an array of items using a callback
  *
  * If multiple items have the same key, the latest item will be used
  *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
- * @returns Map of keyed items
+ * @returns _Map_ of keyed items
  *
  * @example
  * ```typescript
@@ -166,13 +166,13 @@ export function toMap<Item, Callback extends (item: Item, index: number, array:
 ): Map<ReturnType<Callback>, Item>;
 
 /**
- * Create a Map from an array of items using a key
+ * Create a _Map_ from an array of items using a key
  *
  * If multiple items have the same key, the latest item will be used
  *
  * @param array Array to convert
  * @param key Key to use for grouping
- * @returns Map of keyed items
+ * @returns _Map_ of keyed items
  *
  * @example
  * ```typescript
@@ -188,10 +188,10 @@ export function toMap<Item extends PlainObject, ItemKey extends keyof Item>(
 ): Map<Item[ItemKey], Item>;
 
 /**
- * Create a Map from an array of items _(using indices as keys)_
+ * Create a _Map_ from an array of items _(using indices as keys)_
  *
  * @param array Array to convert
- * @returns Map of indiced items
+ * @returns _Map_ of indiced items
  *
  * @example
  * ```typescript
@@ -209,14 +209,14 @@ export function toMap(array: unknown[], first?: unknown, second?: unknown): unkn
 toMap.arrays = toMapArrays;
 
 /**
- * Create a Map from an array of items using callbacks, grouping values into arrays
+ * Create a _Map_ from an array of items using callbacks, grouping values into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
- * @returns Map of keyed arrays of values
+ * @returns _Map_ of keyed arrays of values
  *
  * @example
  * ```typescript
@@ -238,14 +238,14 @@ export function toMapArrays<
 ): Map<ReturnType<KeyCallback>, ReturnType<ValueCallback>[]>;
 
 /**
- * Create a Map from an array of items using a callback and value, grouping values into arrays
+ * Create a _Map_ from an array of items using a callback and value, grouping values into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
- * @returns Map of keyed arrays of values
+ * @returns _Map_ of keyed arrays of values
  *
  * @example
  * ```typescript
@@ -267,14 +267,14 @@ export function toMapArrays<
 ): Map<ReturnType<KeyCallback>, Item[ItemValue][]>;
 
 /**
- * Create a Map from an array of items using a key and callback, grouping values into arrays
+ * Create a _Map_ from an array of items using a key and callback, grouping values into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
- * @returns Map of keyed arrays of values
+ * @returns _Map_ of keyed arrays of values
  *
  * @example
  * ```typescript
@@ -296,14 +296,14 @@ export function toMapArrays<
 ): Map<Item[ItemKey], ReturnType<ValueCallback>[]>;
 
 /**
- * Create a Map from an array of items using a key and value, grouping values into arrays
+ * Create a _Map_ from an array of items using a key and value, grouping values into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Key to use for value
- * @returns Map of keyed arrays of values
+ * @returns _Map_ of keyed arrays of values
  *
  * @example
  * ```typescript
@@ -321,13 +321,13 @@ export function toMapArrays<
 >(array: Item[], key: ItemKey, value: ItemValue): Map<Item[ItemKey], Item[ItemValue][]>;
 
 /**
- * Create a Map from an array of items using a callback, grouping items into arrays
+ * Create a _Map_ from an array of items using a callback, grouping items into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
- * @returns Map of keyed arrays of items
+ * @returns _Map_ of keyed arrays of items
  *
  * @example
  * ```typescript
@@ -343,13 +343,13 @@ export function toMapArrays<
 >(array: Item[], callback: Callback): Map<ReturnType<Callback>, Item[]>;
 
 /**
- * Create a Map from an array of items using a key, grouping items into arrays
+ * Create a _Map_ from an array of items using a key, grouping items into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
- * @returns Map of keyed arrays of items
+ * @returns _Map_ of keyed arrays of items
  *
  * @example
  * ```typescript

package/src/array/to-record.ts

@@ -187,7 +187,7 @@ toRecord.arrays = toRecordArrays;
 /**
  * Create a record from an array of items using callbacks, grouping values into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
@@ -216,7 +216,7 @@ export function toRecordArrays<
 /**
  * Create a record from an array of items using a callback and value, grouping values into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
@@ -245,7 +245,7 @@ export function toRecordArrays<
 /**
  * Create a record from an array of items using a key and callback, grouping values into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
@@ -274,7 +274,7 @@ export function toRecordArrays<
 /**
  * Create a record from an array of items using a key and value, grouping values into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
@@ -303,7 +303,7 @@ export function toRecordArrays<
 /**
  * Create a record from an array of items using a callback, grouping items into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
@@ -325,7 +325,7 @@ export function toRecordArrays<
 /**
  * Create a record from an array of items using a key, grouping items into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping

package/src/array/to-set.ts

@@ -4,11 +4,11 @@ import type {PlainObject} from '../models';
 // #region Functions
 
 /**
- * Create a Set from an array of items using a callback
+ * Create a _Set_ from an array of items using a callback
  *
  * @param array Array to convert
  * @param callback Callback to get an item's value
- * @returns Set of values
+ * @returns _Set_ of values
  *
  * @example
  * ```typescript
@@ -24,11 +24,11 @@ export function toSet<Item, Callback extends (item: Item, index: number, array:
 ): Set<ReturnType<Callback>>;
 
 /**
- * Create a Set from an array of items using a key
+ * Create a _Set_ from an array of items using a key
  *
  * @param array Array to convert
  * @param key Key to use for value
- * @returns Set of values
+ * @returns _Set_ of values
  *
  * @example
  * ```typescript
@@ -44,10 +44,10 @@ export function toSet<Item extends PlainObject, ItemKey extends keyof Item>(
 ): Set<Item[ItemKey]>;
 
 /**
- * Create a Set from an array of items
+ * Create a _Set_ from an array of items
  *
  * @param array Array to convert
- * @returns Set of items
+ * @returns _Set_ of items
  *
  * @example
  * ```typescript

package/src/beacon.ts

@@ -58,6 +58,7 @@ class Beacon<Value> {
 
 	/**
 	 * Emit a new value
+	 *
 	 * @param value Value to set and emit
 	 * @param finish Finish the beacon after emitting? _(defaults to `false`)_
 	 */
@@ -67,6 +68,7 @@ class Beacon<Value> {
 
 	/**
 	 * Emit an error
+	 *
 	 * @param value Error to emit
 	 * @param finish Finish the beacon after emitting? _(defaults to `false`)_
 	 */
@@ -110,6 +112,7 @@ class Beacon<Value> {
 type BeaconOptions<Value> = {
 	/**
 	 * Method for comparing values for equality
+	 *
 	 * @param first First value
 	 * @param second Second value
 	 * @returns `true` if the values are equal, otherwise `false`
@@ -148,6 +151,7 @@ class Observable<Value> {
 
 	/**
 	 * Subscribe to value changes
+	 *
 	 * @param onNext Callback for when the observable receives a new value
 	 * @param onError Callback for when the observable receives an error
 	 * @param onComplete Callback for when the observable is completed
@@ -161,6 +165,7 @@ class Observable<Value> {
 
 	/**
 	 * Subscribe to value changes
+	 *
 	 * @param observer Observer for changes
 	 * @returns Subscription to the observable
 	 */
@@ -265,6 +270,7 @@ type SubscriptionState<Value> = {
 
 /**
  * Create a new beacon
+ *
  * @param value Initial value
  * @param options Beacon options
  * @returns Beacon instance

package/src/color/index.ts

@@ -5,9 +5,13 @@ import type {HSLAColor, HSLColor, RGBAColor, RGBColor} from './models';
 // #region Functions
 
 /**
- * Get a Color from any kind of value
+ * Get a _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 is unable to be parsed, a black _Color_ will be returned
+ *
  * @param value Original value
- * @returns Color instance
+ * @returns _Color_ instance
  */
 export function getColor(value: unknown): Color {
 	return isColor(value) ? value : new Color(value);

package/src/color/instance.ts

@@ -20,14 +20,21 @@ export class Color {
 	readonly #state: ColorState;
 
 	/**
-	 * Get the alpha channel
+	 * Get the alpha channel _(opacity)_ of the color
+	 *
+	 * @returns Current alpha channel value between `0` and `1`
 	 */
 	get alpha(): number {
 		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: number) {
 		if (typeof value === 'number' && !Number.isNaN(value)) {
@@ -36,49 +43,73 @@ export class Color {
 	}
 
 	/**
-	 * 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(): string {
 		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: string) {
 		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(): string {
 		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: string) {
 		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(): HSLColor {
 		return this.#state.hsl;
 	}
 
 	/**
-	 * Set colors from an HSL color
+	 * Set colors from an _HSL_ color
+	 *
+	 * @param value New _HSL_ color
 	 */
 	set hsl(value: HSLColor) {
 		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(): HSLAColor {
 		return {
@@ -88,28 +119,36 @@ export class Color {
 	}
 
 	/**
-	 * Set colors and alpha from an HSLA color
+	 * Set colors and alpha from an _HSLA_ color
+	 *
+	 * @param value New _HSLA_ color
 	 */
 	set hsla(value: HSLAColor) {
 		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(): RGBColor {
 		return this.#state.rgb;
 	}
 
 	/**
-	 * Set colors from an RGB color
+	 * Set colors from an _RGB_ color
+	 *
+	 * @param value New _RGB_ color
 	 */
 	set rgb(value: RGBColor) {
 		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(): RGBAColor {
 		return {
@@ -119,7 +158,9 @@ export class Color {
 	}
 
 	/**
-	 * Set colors and alpha from an RGBA color
+	 * Set colors and alpha from an _RGBA_ color
+	 *
+	 * @param value New _RGBA_ color
 	 */
 	set rgba(value: RGBAColor) {
 		setRGBColor(this.#state, value, true);
@@ -133,18 +174,41 @@ export class Color {
 		});
 	}
 
+	/**
+	 * Get the color as a hex string
+	 *
+	 * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+	 * @returns Hex color string
+	 */
 	toHexString(alpha?: boolean): string {
 		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?: boolean): string {
 		return formatColor(SPACE_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?: boolean): string {
 		return formatColor(SPACE_RGB, this, alpha === true);
 	}
 
+	/**
+	 * Get the color as a hex color string
+	 *
+	 * @returns Hex color string
+	 */
 	toString(): string {
 		return this.toHexString();
 	}

package/src/color/misc/get.ts

@@ -27,6 +27,10 @@ function getClampedValue(value: unknown, minimum: number, maximum: number): numb
 
 /**
  * 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
  */
@@ -58,9 +62,13 @@ export 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
  */
 export function getHexaColor(value: unknown): string {
 	const {alpha, hex} = getColorState(value);
@@ -70,8 +78,12 @@ export 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
  */
 export function getHexColor(value: unknown): string {
 	return getColorState(value).hex;
@@ -86,9 +98,13 @@ export 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
  */
 export function getHslaColor(value: unknown): HSLAColor {
 	const {alpha, hsl} = getColorState(value);
@@ -100,9 +116,13 @@ export 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
  */
 export function getHslColor(value: unknown): HSLColor {
 	return getColorState(value).hsl;
@@ -113,9 +133,13 @@ export 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
  */
 export function getRgbaColor(value: unknown): RGBAColor {
 	const {alpha, rgb} = getColorState(value);
@@ -127,9 +151,13 @@ export 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
  */
 export function getRgbColor(value: unknown): RGBColor {
 	return getColorState(value).rgb;