toolbox-x 2.0.13 → 2.2.0

package/dist/{basics-Bb5ovcvz.cjs → basics-byj0VH1c.cjs}

@@ -15,9 +15,9 @@
  */
 
 const require_primitives = require('./primitives-CBGICrDR.cjs');
-const require_timezone = require('./timezone-CSz7R0L6.cjs');
-const require_specials = require('./specials-dkYP1Nh2.cjs');
-const require_utilities = require('./utilities-CWV1GPGY.cjs');
+const require_specials = require('./specials-DU8u108m.cjs');
+const require_utilities = require('./utilities-BVpk3LKy.cjs');
+const require_guards = require('./guards-CqbVT4L5.cjs');
 
 //#region src/array/helpers.ts
 /**
@@ -133,99 +133,6 @@ function sortAnArray(array, options) {
 	return [...array];
 }
 
-//#endregion
-//#region src/date/guards.ts
-/**
-* * Checks if the provided value is a valid time string in "HH:MM" format.
-*
-* @param value - The value to check.
-* @returns `true` if the value is a valid time string, `false` otherwise.
-*/
-function isValidTime(value) {
-	if (!require_primitives.isNonEmptyString(value)) return false;
-	const [hourStr, minuteStr] = value.split(":");
-	if (!require_specials.isNumericString(hourStr) || !require_specials.isNumericString(minuteStr)) return false;
-	const hour = Number(hourStr);
-	const minute = Number(minuteStr);
-	return hour >= 0 && hour <= 23 && minute >= 0 && minute <= 59;
-}
-/**
-* * Checks if the provided value is a valid `UTCOffset` (e.g. `UTC-01:30`).
-*
-* @param value - The value to check.
-* @returns `true` if the value is a valid utc offset, `false` otherwise.
-*/
-function isValidUTCOffset(value) {
-	return require_primitives.isString(value) ? /^UTC[+-]?(?:0[0-9]|1[0-4]):(?:00|15|30|45)$/.test(value) : false;
-}
-/**
-* * Validates whether the provided value is a recognized IANA time zone identifier (excluding `"Factory"`), based on the {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones IANA TZ Database}.
-*
-* @remarks
-* - Relies on a large constant map of time zone identifiers, which can increase bundle size in browser environments. Matches against `597` identifiers.
-* - Prefer {@link isNativeTimeZoneId} when you want a lightweight, native-only validation approach. Matches against `418` identifiers.
-*
-* @param value Time zone identifier to validate.
-* @returns `true` if the value is a valid IANA time zone identifier, otherwise `false`.
-*/
-function isValidTimeZoneId(value) {
-	return require_primitives.isNonEmptyString(value) ? new Set([...require_timezone.IANA_TZ_IDS]).has(value) : false;
-}
-/**
-* * Validates whether the provided value is a supported time zone identifier using the native JavaScript API (`Intl.supportedValuesOf('timeZone')`).
-*
-* @remarks
-* - Uses only native {@link Intl} capabilities—minimal code footprint, highly performant. Matches against `418` identifiers.
-* - Prefer {@link isValidTimeZoneId} when validation must align strictly with the full
-*   {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones IANA TZ Database}. Matches against `597` identifiers.
-*
-* @param value Time zone identifier to validate.
-* @returns `true` if the value is a valid native JS-supported time zone identifier, otherwise `false`.
-*/
-function isNativeTimeZoneId(value) {
-	return require_primitives.isNonEmptyString(value) ? new Set(require_timezone.NATIVE_TZ_IDS).has(value) : false;
-}
-/**
-* * Checks if the year is a leap year.
-*
-* - A year is a leap year if it is divisible by 4, but not divisible by 100, unless it is also divisible by 400.
-* - For example, 2000 and 2400 are leap years, but 1900 and 2100 are not.
-* @param year The year to check.
-* @returns `true` if the year is a leap year, `false` otherwise.
-*/
-function isLeapYear(year) {
-	const $year = require_utilities.normalizeNumber(year);
-	return $year ? $year % 4 === 0 && $year % 100 !== 0 || $year % 400 === 0 : false;
-}
-/**
-* * Checks if a value is a date-like object from `Date`, `Chronos`, `Moment.js`, `Day.js`, `Luxon`, `JS-Joda`, or `Temporal`
-* @param value Value to check if it is date-like object.
-* @returns `true` if the value is date-like object, otherwise `false`.
-*/
-function isDateLike(value) {
-	if (value instanceof Date) return true;
-	if (require_specials.isObject(value)) {
-		if (require_specials.isFunction(value.format) && require_specials.isFunction(value.toJSON) && require_specials.isFunction(value.toISOString)) return true;
-		if (require_specials.isFunction(value.toISO) && require_specials.isFunction(value.toFormat) && require_primitives.isBoolean(value.isValid)) return true;
-		if (require_specials.isFunction(value.plus) && require_specials.isFunction(value.minus) && require_specials.isFunction(value.equals) && require_specials.isFunction(value.getClass)) return true;
-		if (require_specials.isFunction(value.toJSON) && require_specials.isFunction(value.toString) && [
-			"Instant",
-			"Duration",
-			"PlainDate",
-			"PlainTime",
-			"PlainDateTime",
-			"PlainMonthDay",
-			"PlainYearMonth",
-			"ZonedDateTime"
-		].includes(value.constructor?.name ?? "")) return true;
-	}
-	return false;
-}
-/** Checks if a value represents time value (number) with different forms of {@link TimeWithUnit units} */
-function isTimeWithUnit(value) {
-	return require_primitives.isNonEmptyString(value) && /^-?\d*\.?\d+ *(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|months?|mo|years?|yrs?|y)?$/i.test(value);
-}
-
 //#endregion
 //#region src/utils/index.ts
 /**
@@ -418,7 +325,7 @@ function getClassDetails(cls) {
 */
 function stableStringify(obj) {
 	const _replacer = (_, v) => v === void 0 ? null : v;
-	if (require_specials.isNotEmptyObject(obj)) return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k, _replacer) + ":" + (isDateLike(obj[k]) ? JSON.stringify(obj[k]) : stableStringify(obj[k]))).join(",") + "}";
+	if (require_specials.isNotEmptyObject(obj)) return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k, _replacer) + ":" + (require_guards.isDateLike(obj[k]) ? JSON.stringify(obj[k]) : stableStringify(obj[k]))).join(",") + "}";
 	if (require_specials.isValidArray(obj)) return "[" + obj.map((v) => stableStringify(v)).join(",") + "]";
 	return JSON.stringify(obj, _replacer);
 }
@@ -758,7 +665,7 @@ function bytesToBase64(bytes) {
 		const h2 = (o1 & 3) << 4 | o2 >> 4;
 		const h3 = (o2 & 15) << 2 | o3 >> 6;
 		const h4 = o3 & 63;
-		out += _b64chars[h1] + _b64chars[h2] + _b64chars[isNaN(o2) ? 64 : h3] + _b64chars[isNaN(o3) ? 64 : h4];
+		out += _b64chars[h1] + _b64chars[h2] + _b64chars[Number.isNaN(o2) ? 64 : h3] + _b64chars[Number.isNaN(o3) ? 64 : h4];
 	}
 	return out;
 }
@@ -1999,36 +1906,12 @@ Object.defineProperty(exports, 'intTo4BytesBE', {
     return intTo4BytesBE;
   }
 });
-Object.defineProperty(exports, 'isDateLike', {
-  enumerable: true,
-  get: function () {
-    return isDateLike;
-  }
-});
 Object.defineProperty(exports, 'isDeepEqual', {
   enumerable: true,
   get: function () {
     return isDeepEqual;
   }
 });
-Object.defineProperty(exports, 'isLeapYear', {
-  enumerable: true,
-  get: function () {
-    return isLeapYear;
-  }
-});
-Object.defineProperty(exports, 'isNativeTimeZoneId', {
-  enumerable: true,
-  get: function () {
-    return isNativeTimeZoneId;
-  }
-});
-Object.defineProperty(exports, 'isTimeWithUnit', {
-  enumerable: true,
-  get: function () {
-    return isTimeWithUnit;
-  }
-});
 Object.defineProperty(exports, 'isUUIDv1', {
   enumerable: true,
   get: function () {
@@ -2077,24 +1960,6 @@ Object.defineProperty(exports, 'isUUIDv8', {
     return isUUIDv8;
   }
 });
-Object.defineProperty(exports, 'isValidTime', {
-  enumerable: true,
-  get: function () {
-    return isValidTime;
-  }
-});
-Object.defineProperty(exports, 'isValidTimeZoneId', {
-  enumerable: true,
-  get: function () {
-    return isValidTimeZoneId;
-  }
-});
-Object.defineProperty(exports, 'isValidUTCOffset', {
-  enumerable: true,
-  get: function () {
-    return isValidUTCOffset;
-  }
-});
 Object.defineProperty(exports, 'md5', {
   enumerable: true,
   get: function () {

package/dist/colors.cjs

@@ -17,8 +17,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primitives = require('./primitives-CBGICrDR.cjs');
 const require_css_colors = require('./css-colors-DC7oZ46Y.cjs');
-const require_guards = require('./guards-DGN95D2h.cjs');
-const require_convert = require('./convert-Cqy2Llek.cjs');
+const require_guards = require('./guards-CrfVwk0-.cjs');
+const require_convert = require('./convert-BjKz_hhr.cjs');
+const require_utilities = require('./utilities-BVpk3LKy.cjs');
 const require_constants = require('./constants-BOs8tjzp.cjs');
 
 //#region src/colors/random.ts
@@ -158,6 +159,18 @@ var Color = class Color {
 		yield this.hsla;
 	}
 	/**
+	* Allows the color to be used in string and number contexts.
+	* @param hint The hint to determine the conversion type.
+	*/
+	[Symbol.toPrimitive](hint) {
+		if (hint === "string") return this.hex8;
+		else if (hint === "number") {
+			const hex = this.hex8.endsWith("FF") ? this.hex : this.hex8;
+			return parseInt(hex.replace("#", "0x"), 16);
+		}
+		return this;
+	}
+	/**
 	* @private Convert `Hex6` color format to `Hex8` by applying `100%` opacity.
 	* @param hex `Hex6` color to convert to `Hex8`.
 	*/
@@ -181,11 +194,12 @@ var Color = class Color {
 		return `hsla(${h}, ${s}%, ${l}%, 1)`;
 	}
 	/**
-	* @instance Applies or modifies the opacity of a color and returns a new instance.
+	* @instance Sets the opacity of this color to the given **absolute** percentage and returns a new instance.
 	*
 	* @remarks
+	* - This is an **absolute setter**: passing `50` means "set opacity to exactly 50%", regardless of the current opacity.
 	* - For solid colors ({@link Hex6}/{@link RGB}/{@link HSL}): Adds an alpha channel with the specified opacity.
-	* - For alpha colors ({@link Hex8}/{@link RGBA}/{@link HSLA}): Updates the existing alpha channel.
+	* - For alpha colors ({@link Hex8}/{@link RGBA}/{@link HSLA}): Replaces the existing alpha channel.
 	*
 	* @param opacity - A number between `0-100` representing the opacity percentage.
 	* @returns A new instance of `Color` containing all color formats with the applied opacity.
@@ -204,40 +218,81 @@ var Color = class Color {
 		return new Color(`${this.hex.slice(0, 7)}${require_convert.percentToHex(opacity)}`.toUpperCase());
 	}
 	/**
-	* @instance Darkens the color by reducing the lightness by the given percentage.
-	* @param percent - The percentage to darken (`0–100`).
-	* @returns A new `Color` instance with the modified darkness.
+	* @instance Darkens the color by **subtracting** the given percentage points from the current lightness in HSL space.
+	*
+	* @remarks
+	* - This is a **relative adjustment**: passing `20` means "reduce lightness by 20 percentage points" from its current value.
+	* - Lightness is clamped to `0%` at minimum.
+	* - The original alpha (opacity) is preserved in the returned color.
+	*
+	* @param percent - The percentage points to subtract from lightness (`0–100`).
+	* @returns A new `Color` instance with the reduced lightness.
+	*
+	* @example
+	* const blue = new Color("#0000ff"); // hsl(240, 100%, 50%)
+	* const darkerBlue = blue.applyDarkness(20);
+	* console.log(darkerBlue.hsl); // hsl(240, 100%, 30%)
 	*/
 	applyDarkness(percent) {
 		const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
 		return new Color(`hsl(${h}, ${s}%, ${Math.max(0, l - percent)}%)`).applyOpacity(a * 100);
 	}
 	/**
-	* @instance Lightens the color by increasing the lightness by the given percentage.
-	* @param percent - The percentage to brighten (`0–100`).
-	* @returns A new `Color` instance with the modified lightness.
+	* @instance Lightens the color by **adding** the given percentage points to the current lightness in HSL space.
+	*
+	* @remarks
+	* - This is a **relative adjustment**: passing `30` means "increase lightness by 30 percentage points" from its current value.
+	* - Lightness is clamped to `100%` at maximum.
+	* - The original alpha (opacity) is preserved in the returned color.
+	*
+	* @param percent - The percentage points to add to lightness (`0–100`).
+	* @returns A new `Color` instance with the increased lightness.
+	*
+	* @example
+	* const green = new Color("#008000"); // hsl(120, 100%, 25.1%)
+	* const lighterGreen = green.applyBrightness(30);
+	* console.log(lighterGreen.hsl); // hsl(120, 100%, 55.1%)
 	*/
 	applyBrightness(percent) {
 		const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
 		return new Color(`hsl(${h}, ${s}%, ${Math.min(100, l + percent)}%)`).applyOpacity(a * 100);
 	}
 	/**
-	* @instance Reduces the saturation of the color to make it appear duller.
-	* @param percent - The percentage to reduce saturation (`0–100`).
-	* @returns A new `Color` instance with the modified saturation.
+	* @instance Desaturates the color by **subtracting** the given percentage points from the current saturation in HSL space.
+	*
+	* @remarks
+	* - This is a **relative adjustment**: passing `50` means "reduce saturation by 50 percentage points" from its current value.
+	* - Saturation is clamped to `0%` at minimum (fully desaturated / grayscale).
+	* - The original alpha (opacity) is preserved in the returned color.
+	*
+	* @param percent - The percentage points to subtract from saturation (`0–100`).
+	* @returns A new `Color` instance with the reduced saturation.
+	*
+	* @example
+	* const pink = new Color("#ff69b4"); // hsl(330, 100%, 70.59%)
+	* const dullPink = pink.applyDullness(50);
+	* console.log(dullPink.hsl); // hsl(330, 50%, 70.59%)
 	*/
 	applyDullness(percent) {
 		const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
 		return new Color(`hsl(${h}, ${Math.max(0, s - percent)}%, ${l}%)`).applyOpacity(a * 100);
 	}
 	/**
-	* @instance Softens the color toward white by reducing saturation and increasing lightness based on a percentage.
+	* @instance Softens the color toward white by **proportionally** reducing saturation and increasing lightness.
 	*
 	* @remarks
-	* This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale).
+	* - This is a **proportional blend**: passing `40` means "move 40% of the *remaining distance* toward pure white".
+	* - Unlike {@link applyBrightness} or {@link applyDullness}, the effect scales relative to the current distance from white, producing a natural pastel/tint effect.
+	* - This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale).
+	* - The original alpha (opacity) is preserved in the returned color.
 	*
 	* @param percent - Value from `0` to `100` representing how far to push the color toward white.
 	* @returns A new `Color` instance shifted toward white.
+	*
+	* @example
+	* const purple = new Color("#800080"); // hsl(300, 100%, 25.1%)
+	* const softPurple = purple.applyWhiteShade(40);
+	* console.log(softPurple.hsl); // hsl(300, 60%, 55.06%)
 	*/
 	applyWhiteShade(percent) {
 		const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
@@ -258,14 +313,14 @@ var Color = class Color {
 	*/
 	blendWith(other, weight = .5) {
 		const w = Math.max(0, Math.min(1, weight));
-		const converted = Color.isCSSColor(other) ? new Color(other) : new Color(other);
-		const [r1, b1, g1, a1] = require_convert.extractAlphaColorValues(this.rgba);
-		const [r2, b2, g2, a2] = require_convert.extractAlphaColorValues(converted.rgba);
+		const converted = new Color(other);
+		const [r1, g1, b1, a1] = require_convert.extractAlphaColorValues(this.rgba);
+		const [r2, g2, b2, a2] = require_convert.extractAlphaColorValues(converted.rgba);
 		const alpha = Math.round((a1 * (1 - w) + a2 * w) * 100) / 100;
-		const blendChannel = (c1, c2) => {
+		const _blendChannel = (c1, c2) => {
 			return Math.round((c1 * a1 * (1 - w) + c2 * a2 * w) / alpha);
 		};
-		return new Color(`rgba(${blendChannel(r1, r2)}, ${blendChannel(g1, g2)}, ${blendChannel(b1, b2)}, ${alpha})`);
+		return new Color(`rgba(${_blendChannel(r1, r2)}, ${_blendChannel(g1, g2)}, ${_blendChannel(b1, b2)}, ${alpha})`);
 	}
 	/**
 	* @instance Calculates the contrast ratio between this color and another color (WCAG).
@@ -273,11 +328,11 @@ var Color = class Color {
 	* @returns A number representing the contrast ratio (rounded to 2 decimal places).
 	*/
 	contrastRatio(other) {
-		const newColor = Color.isCSSColor(other) ? new Color(other) : new Color(other);
+		const newColor = new Color(other);
 		const luminance = (rgb) => {
 			const [r, g, b] = require_convert.extractSolidColorValues(rgb).map((v) => {
 				const c = v / 255;
-				return c <= .03928 ? c / 12.92 : Math.pow((c + .055) / 1.055, 2.4);
+				return c <= .03928 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4;
 			});
 			return .2126 * r + .7152 * g + .0722 * b;
 		};
@@ -353,6 +408,35 @@ var Color = class Color {
 		].map((c) => c.applyOpacity(a * 100));
 	}
 	/**
+	* @instance Generates a color palette of evenly distributed hues based on the current color's saturation, lightness, and alpha.
+	*
+	* @remarks
+	* - Colors are spaced evenly around the color wheel (`360° / count` apart), starting from the current hue.
+	* - Saturation, lightness, and alpha from the source color are preserved across all generated colors.
+	*
+	* @typeParam N - A literal number type representing the palette size.
+	* @param count - The number of colors to generate in the palette (must be a positive integer ≥ `1`). Default: `7`.
+	* @param step - The step value (degree) to be added to the hue of the previous color. Default: `360 / count`.
+	* @returns Array of `Color` instances with the specified count.
+	*
+	* @example
+	* const red = new Color("#ff0000");
+	* const palette = red.generatePalette(4);
+	* console.log(palette.map((color) => color.hex));
+	* // ['#FF0000', '#80FF00', '#00FFFF', '#8000FF']
+	*/
+	generatePalette(count, step) {
+		const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
+		const clampedCount = require_utilities.clampNumber(count ?? 7, 1, 360);
+		const calculatedStep = step ? require_utilities.clampNumber(step, 1, 360) : 360 / clampedCount;
+		const colors = [];
+		for (let i = 0; i < clampedCount; i++) {
+			const color = new Color(`hsl(${(h + calculatedStep * i) % 360}, ${s}%, ${l}%)`).applyOpacity(a * 100);
+			colors.push(color);
+		}
+		return colors;
+	}
+	/**
 	* @instance Gets the `WCAG` accessibility rating between this and another color.
 	* @param other - The other color to test contrast against.
 	* @returns `'Fail'`, `'AA'`, or `'AAA'` based on `WCAG 2.1` contrast standards.
@@ -374,6 +458,28 @@ var Color = class Color {
 		return (r * 299 + g * 587 + b * 114) / 1e3 > Math.min(255, Math.max(0, threshold));
 	}
 	/**
+	* @instance Convert the color to string.
+	* @returns The `Hex8` representation of the color.
+	*
+	* @remarks
+	* - Called by `String()`, `Object.prototype.toString()` or in template literals.
+	* - Uses the same implementation as `toJSON()`.
+	*/
+	toString() {
+		return this.hex8;
+	}
+	/**
+	* @instance Convert the color to JSON.
+	* @returns The `Hex8` representation of the color.
+	*
+	* @remarks
+	* - Called by `JSON.stringify()`.
+	* - It uses the same implementation as `toString()`.
+	*/
+	toJSON() {
+		return this.hex8;
+	}
+	/**
 	* @static Checks if a color is in {@link Hex6} format.
 	*
 	* @param color Color to check.
@@ -525,10 +631,10 @@ function getColorForInitial(input = "", opacity = 100) {
 		return require_guards._applyOpacity(DEFAULT, hexOpacity);
 	} else if (Array.isArray(input)) {
 		if (input?.length < 1) return [...require_constants.ALPHABET_COLOR_PALETTE, ...require_constants.NUMBER_COLOR_PALETTE].map((color) => require_guards._applyOpacity(color, hexOpacity));
-		return input.map((el) => {
+		return input.flatMap((el) => {
 			if (Array.isArray(el)) return getColorForInitial(el, opacity);
 			return getColorForInitial(el, opacity);
-		}).flat();
+		});
 	}
 	return require_guards._applyOpacity(DEFAULT, hexOpacity);
 }

package/dist/colors.d.cts

@@ -15,7 +15,7 @@
  */
 
 import { er as Percent } from "./object-DyVg8BFt.cjs";
-import { C as RandomColorOptions, S as RandomColor, T as SolidValues, _ as Hex, a as AlphaValues, b as RGB, g as HSLA, h as HSL, l as ColorInputArray, n as $ColorType, t as Color, v as Hex6, x as RGBA, y as Hex8 } from "./Color-asKZqwDF.cjs";
+import { C as RandomColorOptions, S as RandomColor, T as SolidValues, _ as Hex, a as AlphaValues, b as RGB, g as HSLA, h as HSL, l as ColorInputArray, n as $ColorType, t as Color, v as Hex6, x as RGBA, y as Hex8 } from "./Color-CVRcGmWe.cjs";
 
 //#region src/colors/convert.d.ts
 /**
@@ -203,7 +203,7 @@ declare function convertColorCode(color: HSLA): {
 //#endregion
 //#region src/colors/initials.d.ts
 /**
- *  * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
+ * * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
  *
  * - For numbers, it uses 10 predefined colors (0-9).
  * - For letters, it uses 26 predefined colors (A-Z).

package/dist/colors.d.mts

@@ -15,7 +15,7 @@
  */
 
 import { er as Percent } from "./object-DyVg8BFt.mjs";
-import { C as RandomColorOptions, S as RandomColor, T as SolidValues, _ as Hex, a as AlphaValues, b as RGB, g as HSLA, h as HSL, l as ColorInputArray, n as $ColorType, t as Color, v as Hex6, x as RGBA, y as Hex8 } from "./Color-B2SgCGbm.mjs";
+import { C as RandomColorOptions, S as RandomColor, T as SolidValues, _ as Hex, a as AlphaValues, b as RGB, g as HSLA, h as HSL, l as ColorInputArray, n as $ColorType, t as Color, v as Hex6, x as RGBA, y as Hex8 } from "./Color-CInCJvH7.mjs";
 
 //#region src/colors/convert.d.ts
 /**
@@ -203,7 +203,7 @@ declare function convertColorCode(color: HSLA): {
 //#endregion
 //#region src/colors/initials.d.ts
 /**
- *  * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
+ * * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
  *
  * - For numbers, it uses 10 predefined colors (0-9).
  * - For letters, it uses 26 predefined colors (A-Z).