toolbox-x 2.0.14 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/dist/{Color-B2SgCGbm.d.mts → Color-D6qMZgDm.d.mts} +104 -14
  2. package/dist/{Color-asKZqwDF.d.cts → Color-SUPeP6fO.d.cts} +104 -14
  3. package/dist/{Stylog-CRNMQ_uV.d.cts → Stylog-B8sKWvn_.d.mts} +1 -1
  4. package/dist/{Stylog-Cvzo5z86.d.mts → Stylog-DdPP_CJf.d.cts} +1 -1
  5. package/dist/{basics-Dald7J6c.mjs → basics-20lm69yy.mjs} +5 -98
  6. package/dist/{basics-Bb5ovcvz.cjs → basics-byj0VH1c.cjs} +5 -140
  7. package/dist/colors.cjs +139 -27
  8. package/dist/colors.d.cts +2 -2
  9. package/dist/colors.d.mts +2 -2
  10. package/dist/colors.mjs +139 -27
  11. package/dist/constants.cjs +14 -14
  12. package/dist/constants.mjs +1 -1
  13. package/dist/{convert-Cqy2Llek.cjs → convert-BjKz_hhr.cjs} +6 -2
  14. package/dist/{convert-lXdkXPJR.mjs → convert-DRZXcjcS.mjs} +6 -2
  15. package/dist/date.cjs +6 -6
  16. package/dist/date.mjs +4 -4
  17. package/dist/dom.cjs +9 -8
  18. package/dist/dom.mjs +4 -3
  19. package/dist/{guards-D8Iz6EEy.cjs → guards-BSwFQX1M.cjs} +3 -3
  20. package/dist/{guards-DziDBD0p.mjs → guards-CNG9gnvL.mjs} +1 -1
  21. package/dist/guards-CqbVT4L5.cjs +156 -0
  22. package/dist/{guards-DGN95D2h.cjs → guards-CrfVwk0-.cjs} +1 -1
  23. package/dist/guards-DKGBsd6x.mjs +115 -0
  24. package/dist/{guards-D1et4U32.mjs → guards-Dc9MB9on.mjs} +3 -3
  25. package/dist/guards.cjs +37 -36
  26. package/dist/guards.d.cts +1 -1
  27. package/dist/guards.d.mts +1 -1
  28. package/dist/guards.mjs +5 -4
  29. package/dist/hash.cjs +8 -8
  30. package/dist/hash.mjs +8 -8
  31. package/dist/index.cjs +12 -12
  32. package/dist/index.d.cts +2 -3
  33. package/dist/index.d.mts +2 -3
  34. package/dist/index.mjs +12 -12
  35. package/dist/{parse-DUJ0YThn.mjs → parse-TuFyLeVH.mjs} +3 -3
  36. package/dist/{parse-CbVVRoFY.cjs → parse-jh637S25.cjs} +4 -4
  37. package/dist/pluralizer.cjs +1 -1
  38. package/dist/pluralizer.mjs +1 -1
  39. package/dist/{query-B4Lrr5Vt.mjs → query-BomnyWh3.mjs} +5 -5
  40. package/dist/{query-BUBCpo-q.cjs → query-sWSi-d7u.cjs} +10 -10
  41. package/dist/{specials-dkYP1Nh2.cjs → specials-DU8u108m.cjs} +1 -1
  42. package/dist/{specials-Hq5Ncd6y.mjs → specials-krf7zsqI.mjs} +1 -1
  43. package/dist/stylog.cjs +3 -3
  44. package/dist/stylog.d.cts +2 -2
  45. package/dist/stylog.d.mts +2 -2
  46. package/dist/stylog.mjs +3 -3
  47. package/dist/types/colors.d.cts +1 -1
  48. package/dist/types/colors.d.mts +1 -1
  49. package/dist/types/stylog.d.cts +1 -1
  50. package/dist/types/stylog.d.mts +1 -1
  51. package/dist/{utilities-DPscNbS1.mjs → utilities-BSv8VbnM.mjs} +1 -1
  52. package/dist/{utilities-CWV1GPGY.cjs → utilities-BVpk3LKy.cjs} +1 -1
  53. package/package.json +6 -6
@@ -15,9 +15,9 @@
15
15
  */
16
16
 
17
17
  const require_primitives = require('./primitives-CBGICrDR.cjs');
18
- const require_timezone = require('./timezone-CSz7R0L6.cjs');
19
- const require_specials = require('./specials-dkYP1Nh2.cjs');
20
- const require_utilities = require('./utilities-CWV1GPGY.cjs');
18
+ const require_specials = require('./specials-DU8u108m.cjs');
19
+ const require_utilities = require('./utilities-BVpk3LKy.cjs');
20
+ const require_guards = require('./guards-CqbVT4L5.cjs');
21
21
 
22
22
  //#region src/array/helpers.ts
23
23
  /**
@@ -133,99 +133,6 @@ function sortAnArray(array, options) {
133
133
  return [...array];
134
134
  }
135
135
 
136
- //#endregion
137
- //#region src/date/guards.ts
138
- /**
139
- * * Checks if the provided value is a valid time string in "HH:MM" format.
140
- *
141
- * @param value - The value to check.
142
- * @returns `true` if the value is a valid time string, `false` otherwise.
143
- */
144
- function isValidTime(value) {
145
- if (!require_primitives.isNonEmptyString(value)) return false;
146
- const [hourStr, minuteStr] = value.split(":");
147
- if (!require_specials.isNumericString(hourStr) || !require_specials.isNumericString(minuteStr)) return false;
148
- const hour = Number(hourStr);
149
- const minute = Number(minuteStr);
150
- return hour >= 0 && hour <= 23 && minute >= 0 && minute <= 59;
151
- }
152
- /**
153
- * * Checks if the provided value is a valid `UTCOffset` (e.g. `UTC-01:30`).
154
- *
155
- * @param value - The value to check.
156
- * @returns `true` if the value is a valid utc offset, `false` otherwise.
157
- */
158
- function isValidUTCOffset(value) {
159
- return require_primitives.isString(value) ? /^UTC[+-]?(?:0[0-9]|1[0-4]):(?:00|15|30|45)$/.test(value) : false;
160
- }
161
- /**
162
- * * 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}.
163
- *
164
- * @remarks
165
- * - Relies on a large constant map of time zone identifiers, which can increase bundle size in browser environments. Matches against `597` identifiers.
166
- * - Prefer {@link isNativeTimeZoneId} when you want a lightweight, native-only validation approach. Matches against `418` identifiers.
167
- *
168
- * @param value Time zone identifier to validate.
169
- * @returns `true` if the value is a valid IANA time zone identifier, otherwise `false`.
170
- */
171
- function isValidTimeZoneId(value) {
172
- return require_primitives.isNonEmptyString(value) ? new Set([...require_timezone.IANA_TZ_IDS]).has(value) : false;
173
- }
174
- /**
175
- * * Validates whether the provided value is a supported time zone identifier using the native JavaScript API (`Intl.supportedValuesOf('timeZone')`).
176
- *
177
- * @remarks
178
- * - Uses only native {@link Intl} capabilities—minimal code footprint, highly performant. Matches against `418` identifiers.
179
- * - Prefer {@link isValidTimeZoneId} when validation must align strictly with the full
180
- * {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones IANA TZ Database}. Matches against `597` identifiers.
181
- *
182
- * @param value Time zone identifier to validate.
183
- * @returns `true` if the value is a valid native JS-supported time zone identifier, otherwise `false`.
184
- */
185
- function isNativeTimeZoneId(value) {
186
- return require_primitives.isNonEmptyString(value) ? new Set(require_timezone.NATIVE_TZ_IDS).has(value) : false;
187
- }
188
- /**
189
- * * Checks if the year is a leap year.
190
- *
191
- * - A year is a leap year if it is divisible by 4, but not divisible by 100, unless it is also divisible by 400.
192
- * - For example, 2000 and 2400 are leap years, but 1900 and 2100 are not.
193
- * @param year The year to check.
194
- * @returns `true` if the year is a leap year, `false` otherwise.
195
- */
196
- function isLeapYear(year) {
197
- const $year = require_utilities.normalizeNumber(year);
198
- return $year ? $year % 4 === 0 && $year % 100 !== 0 || $year % 400 === 0 : false;
199
- }
200
- /**
201
- * * Checks if a value is a date-like object from `Date`, `Chronos`, `Moment.js`, `Day.js`, `Luxon`, `JS-Joda`, or `Temporal`
202
- * @param value Value to check if it is date-like object.
203
- * @returns `true` if the value is date-like object, otherwise `false`.
204
- */
205
- function isDateLike(value) {
206
- if (value instanceof Date) return true;
207
- if (require_specials.isObject(value)) {
208
- if (require_specials.isFunction(value.format) && require_specials.isFunction(value.toJSON) && require_specials.isFunction(value.toISOString)) return true;
209
- if (require_specials.isFunction(value.toISO) && require_specials.isFunction(value.toFormat) && require_primitives.isBoolean(value.isValid)) return true;
210
- if (require_specials.isFunction(value.plus) && require_specials.isFunction(value.minus) && require_specials.isFunction(value.equals) && require_specials.isFunction(value.getClass)) return true;
211
- if (require_specials.isFunction(value.toJSON) && require_specials.isFunction(value.toString) && [
212
- "Instant",
213
- "Duration",
214
- "PlainDate",
215
- "PlainTime",
216
- "PlainDateTime",
217
- "PlainMonthDay",
218
- "PlainYearMonth",
219
- "ZonedDateTime"
220
- ].includes(value.constructor?.name ?? "")) return true;
221
- }
222
- return false;
223
- }
224
- /** Checks if a value represents time value (number) with different forms of {@link TimeWithUnit units} */
225
- function isTimeWithUnit(value) {
226
- 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);
227
- }
228
-
229
136
  //#endregion
230
137
  //#region src/utils/index.ts
231
138
  /**
@@ -418,7 +325,7 @@ function getClassDetails(cls) {
418
325
  */
419
326
  function stableStringify(obj) {
420
327
  const _replacer = (_, v) => v === void 0 ? null : v;
421
- 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(",") + "}";
328
+ 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(",") + "}";
422
329
  if (require_specials.isValidArray(obj)) return "[" + obj.map((v) => stableStringify(v)).join(",") + "]";
423
330
  return JSON.stringify(obj, _replacer);
424
331
  }
@@ -758,7 +665,7 @@ function bytesToBase64(bytes) {
758
665
  const h2 = (o1 & 3) << 4 | o2 >> 4;
759
666
  const h3 = (o2 & 15) << 2 | o3 >> 6;
760
667
  const h4 = o3 & 63;
761
- out += _b64chars[h1] + _b64chars[h2] + _b64chars[isNaN(o2) ? 64 : h3] + _b64chars[isNaN(o3) ? 64 : h4];
668
+ out += _b64chars[h1] + _b64chars[h2] + _b64chars[Number.isNaN(o2) ? 64 : h3] + _b64chars[Number.isNaN(o3) ? 64 : h4];
762
669
  }
763
670
  return out;
764
671
  }
@@ -1999,36 +1906,12 @@ Object.defineProperty(exports, 'intTo4BytesBE', {
1999
1906
  return intTo4BytesBE;
2000
1907
  }
2001
1908
  });
2002
- Object.defineProperty(exports, 'isDateLike', {
2003
- enumerable: true,
2004
- get: function () {
2005
- return isDateLike;
2006
- }
2007
- });
2008
1909
  Object.defineProperty(exports, 'isDeepEqual', {
2009
1910
  enumerable: true,
2010
1911
  get: function () {
2011
1912
  return isDeepEqual;
2012
1913
  }
2013
1914
  });
2014
- Object.defineProperty(exports, 'isLeapYear', {
2015
- enumerable: true,
2016
- get: function () {
2017
- return isLeapYear;
2018
- }
2019
- });
2020
- Object.defineProperty(exports, 'isNativeTimeZoneId', {
2021
- enumerable: true,
2022
- get: function () {
2023
- return isNativeTimeZoneId;
2024
- }
2025
- });
2026
- Object.defineProperty(exports, 'isTimeWithUnit', {
2027
- enumerable: true,
2028
- get: function () {
2029
- return isTimeWithUnit;
2030
- }
2031
- });
2032
1915
  Object.defineProperty(exports, 'isUUIDv1', {
2033
1916
  enumerable: true,
2034
1917
  get: function () {
@@ -2077,24 +1960,6 @@ Object.defineProperty(exports, 'isUUIDv8', {
2077
1960
  return isUUIDv8;
2078
1961
  }
2079
1962
  });
2080
- Object.defineProperty(exports, 'isValidTime', {
2081
- enumerable: true,
2082
- get: function () {
2083
- return isValidTime;
2084
- }
2085
- });
2086
- Object.defineProperty(exports, 'isValidTimeZoneId', {
2087
- enumerable: true,
2088
- get: function () {
2089
- return isValidTimeZoneId;
2090
- }
2091
- });
2092
- Object.defineProperty(exports, 'isValidUTCOffset', {
2093
- enumerable: true,
2094
- get: function () {
2095
- return isValidUTCOffset;
2096
- }
2097
- });
2098
1963
  Object.defineProperty(exports, 'md5', {
2099
1964
  enumerable: true,
2100
1965
  get: function () {
package/dist/colors.cjs CHANGED
@@ -17,8 +17,9 @@
17
17
  Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
18
18
  const require_primitives = require('./primitives-CBGICrDR.cjs');
19
19
  const require_css_colors = require('./css-colors-DC7oZ46Y.cjs');
20
- const require_guards = require('./guards-DGN95D2h.cjs');
21
- const require_convert = require('./convert-Cqy2Llek.cjs');
20
+ const require_guards = require('./guards-CrfVwk0-.cjs');
21
+ const require_convert = require('./convert-BjKz_hhr.cjs');
22
+ const require_utilities = require('./utilities-BVpk3LKy.cjs');
22
23
  const require_constants = require('./constants-BOs8tjzp.cjs');
23
24
 
24
25
  //#region src/colors/random.ts
@@ -95,11 +96,17 @@ function generateRandomColor(options) {
95
96
  * @property `hsla` - {@link HSLA} color representation including alpha.
96
97
  */
97
98
  var Color = class Color {
99
+ /** {@link Hex6 Hex} color representation (without alpha). */
98
100
  hex;
101
+ /** {@link Hex8} color representation including alpha. */
99
102
  hex8;
103
+ /** {@link RGB} color representation (without alpha). */
100
104
  rgb;
105
+ /** {@link RGBA} color representation including alpha. */
101
106
  rgba;
107
+ /** {@link HSL} color representation (without alpha). */
102
108
  hsl;
109
+ /** {@link HSLA} color representation including alpha. */
103
110
  hsla;
104
111
  /**
105
112
  * * Creates a new `Color` instance and automatically converts the input color to all other supported formats: {@link Hex6 Hex}, {@link Hex8}, {@link RGB}, {@link RGBA}, {@link HSL}, and {@link HSLA}.
@@ -158,6 +165,18 @@ var Color = class Color {
158
165
  yield this.hsla;
159
166
  }
160
167
  /**
168
+ * Allows the color to be used in string and number contexts.
169
+ * @param hint The hint to determine the conversion type.
170
+ */
171
+ [Symbol.toPrimitive](hint) {
172
+ if (hint === "string") return this.hex8;
173
+ else if (hint === "number") {
174
+ const hex = this.hex8.endsWith("FF") ? this.hex : this.hex8;
175
+ return parseInt(hex.replace("#", "0x"), 16);
176
+ }
177
+ return this;
178
+ }
179
+ /**
161
180
  * @private Convert `Hex6` color format to `Hex8` by applying `100%` opacity.
162
181
  * @param hex `Hex6` color to convert to `Hex8`.
163
182
  */
@@ -181,11 +200,12 @@ var Color = class Color {
181
200
  return `hsla(${h}, ${s}%, ${l}%, 1)`;
182
201
  }
183
202
  /**
184
- * @instance Applies or modifies the opacity of a color and returns a new instance.
203
+ * @instance Sets the opacity of this color to the given **absolute** percentage and returns a new instance.
185
204
  *
186
205
  * @remarks
206
+ * - This is an **absolute setter**: passing `50` means "set opacity to exactly 50%", regardless of the current opacity.
187
207
  * - For solid colors ({@link Hex6}/{@link RGB}/{@link HSL}): Adds an alpha channel with the specified opacity.
188
- * - For alpha colors ({@link Hex8}/{@link RGBA}/{@link HSLA}): Updates the existing alpha channel.
208
+ * - For alpha colors ({@link Hex8}/{@link RGBA}/{@link HSLA}): Replaces the existing alpha channel.
189
209
  *
190
210
  * @param opacity - A number between `0-100` representing the opacity percentage.
191
211
  * @returns A new instance of `Color` containing all color formats with the applied opacity.
@@ -204,40 +224,81 @@ var Color = class Color {
204
224
  return new Color(`${this.hex.slice(0, 7)}${require_convert.percentToHex(opacity)}`.toUpperCase());
205
225
  }
206
226
  /**
207
- * @instance Darkens the color by reducing the lightness by the given percentage.
208
- * @param percent - The percentage to darken (`0–100`).
209
- * @returns A new `Color` instance with the modified darkness.
227
+ * @instance Darkens the color by **subtracting** the given percentage points from the current lightness in HSL space.
228
+ *
229
+ * @remarks
230
+ * - This is a **relative adjustment**: passing `20` means "reduce lightness by 20 percentage points" from its current value.
231
+ * - Lightness is clamped to `0%` at minimum.
232
+ * - The original alpha (opacity) is preserved in the returned color.
233
+ *
234
+ * @param percent - The percentage points to subtract from lightness (`0–100`).
235
+ * @returns A new `Color` instance with the reduced lightness.
236
+ *
237
+ * @example
238
+ * const blue = new Color("#0000ff"); // hsl(240, 100%, 50%)
239
+ * const darkerBlue = blue.applyDarkness(20);
240
+ * console.log(darkerBlue.hsl); // hsl(240, 100%, 30%)
210
241
  */
211
242
  applyDarkness(percent) {
212
243
  const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
213
244
  return new Color(`hsl(${h}, ${s}%, ${Math.max(0, l - percent)}%)`).applyOpacity(a * 100);
214
245
  }
215
246
  /**
216
- * @instance Lightens the color by increasing the lightness by the given percentage.
217
- * @param percent - The percentage to brighten (`0–100`).
218
- * @returns A new `Color` instance with the modified lightness.
247
+ * @instance Lightens the color by **adding** the given percentage points to the current lightness in HSL space.
248
+ *
249
+ * @remarks
250
+ * - This is a **relative adjustment**: passing `30` means "increase lightness by 30 percentage points" from its current value.
251
+ * - Lightness is clamped to `100%` at maximum.
252
+ * - The original alpha (opacity) is preserved in the returned color.
253
+ *
254
+ * @param percent - The percentage points to add to lightness (`0–100`).
255
+ * @returns A new `Color` instance with the increased lightness.
256
+ *
257
+ * @example
258
+ * const green = new Color("#008000"); // hsl(120, 100%, 25.1%)
259
+ * const lighterGreen = green.applyBrightness(30);
260
+ * console.log(lighterGreen.hsl); // hsl(120, 100%, 55.1%)
219
261
  */
220
262
  applyBrightness(percent) {
221
263
  const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
222
264
  return new Color(`hsl(${h}, ${s}%, ${Math.min(100, l + percent)}%)`).applyOpacity(a * 100);
223
265
  }
224
266
  /**
225
- * @instance Reduces the saturation of the color to make it appear duller.
226
- * @param percent - The percentage to reduce saturation (`0–100`).
227
- * @returns A new `Color` instance with the modified saturation.
267
+ * @instance Desaturates the color by **subtracting** the given percentage points from the current saturation in HSL space.
268
+ *
269
+ * @remarks
270
+ * - This is a **relative adjustment**: passing `50` means "reduce saturation by 50 percentage points" from its current value.
271
+ * - Saturation is clamped to `0%` at minimum (fully desaturated / grayscale).
272
+ * - The original alpha (opacity) is preserved in the returned color.
273
+ *
274
+ * @param percent - The percentage points to subtract from saturation (`0–100`).
275
+ * @returns A new `Color` instance with the reduced saturation.
276
+ *
277
+ * @example
278
+ * const pink = new Color("#ff69b4"); // hsl(330, 100%, 70.59%)
279
+ * const dullPink = pink.applyDullness(50);
280
+ * console.log(dullPink.hsl); // hsl(330, 50%, 70.59%)
228
281
  */
229
282
  applyDullness(percent) {
230
283
  const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
231
284
  return new Color(`hsl(${h}, ${Math.max(0, s - percent)}%, ${l}%)`).applyOpacity(a * 100);
232
285
  }
233
286
  /**
234
- * @instance Softens the color toward white by reducing saturation and increasing lightness based on a percentage.
287
+ * @instance Softens the color toward white by **proportionally** reducing saturation and increasing lightness.
235
288
  *
236
289
  * @remarks
237
- * This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale).
290
+ * - This is a **proportional blend**: passing `40` means "move 40% of the *remaining distance* toward pure white".
291
+ * - Unlike {@link applyBrightness} or {@link applyDullness}, the effect scales relative to the current distance from white, producing a natural pastel/tint effect.
292
+ * - This creates a soft UI-like white shade effect (similar to some UI libraries' light color scale).
293
+ * - The original alpha (opacity) is preserved in the returned color.
238
294
  *
239
295
  * @param percent - Value from `0` to `100` representing how far to push the color toward white.
240
296
  * @returns A new `Color` instance shifted toward white.
297
+ *
298
+ * @example
299
+ * const purple = new Color("#800080"); // hsl(300, 100%, 25.1%)
300
+ * const softPurple = purple.applyWhiteShade(40);
301
+ * console.log(softPurple.hsl); // hsl(300, 60%, 55.06%)
241
302
  */
242
303
  applyWhiteShade(percent) {
243
304
  const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
@@ -258,14 +319,14 @@ var Color = class Color {
258
319
  */
259
320
  blendWith(other, weight = .5) {
260
321
  const w = Math.max(0, Math.min(1, weight));
261
- const converted = Color.isCSSColor(other) ? new Color(other) : new Color(other);
262
- const [r1, b1, g1, a1] = require_convert.extractAlphaColorValues(this.rgba);
263
- const [r2, b2, g2, a2] = require_convert.extractAlphaColorValues(converted.rgba);
322
+ const otherColor = new Color(other);
323
+ const [r1, g1, b1, a1] = require_convert.extractAlphaColorValues(this.rgba);
324
+ const [r2, g2, b2, a2] = require_convert.extractAlphaColorValues(otherColor.rgba);
264
325
  const alpha = Math.round((a1 * (1 - w) + a2 * w) * 100) / 100;
265
- const blendChannel = (c1, c2) => {
326
+ const _blendChannel = (c1, c2) => {
266
327
  return Math.round((c1 * a1 * (1 - w) + c2 * a2 * w) / alpha);
267
328
  };
268
- return new Color(`rgba(${blendChannel(r1, r2)}, ${blendChannel(g1, g2)}, ${blendChannel(b1, b2)}, ${alpha})`);
329
+ return new Color(`rgba(${_blendChannel(r1, r2)}, ${_blendChannel(g1, g2)}, ${_blendChannel(b1, b2)}, ${alpha})`);
269
330
  }
270
331
  /**
271
332
  * @instance Calculates the contrast ratio between this color and another color (WCAG).
@@ -273,16 +334,16 @@ var Color = class Color {
273
334
  * @returns A number representing the contrast ratio (rounded to 2 decimal places).
274
335
  */
275
336
  contrastRatio(other) {
276
- const newColor = Color.isCSSColor(other) ? new Color(other) : new Color(other);
277
- const luminance = (rgb) => {
337
+ const otherColor = new Color(other);
338
+ const _luminance = (rgb) => {
278
339
  const [r, g, b] = require_convert.extractSolidColorValues(rgb).map((v) => {
279
340
  const c = v / 255;
280
- return c <= .03928 ? c / 12.92 : Math.pow((c + .055) / 1.055, 2.4);
341
+ return c <= .03928 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4;
281
342
  });
282
343
  return .2126 * r + .7152 * g + .0722 * b;
283
344
  };
284
- const lum1 = luminance(this.rgb);
285
- const lum2 = luminance(newColor.rgb);
345
+ const lum1 = _luminance(this.rgb);
346
+ const lum2 = _luminance(otherColor.rgb);
286
347
  const brighter = Math.max(lum1, lum2);
287
348
  const darker = Math.min(lum1, lum2);
288
349
  const ratio = (brighter + .05) / (darker + .05);
@@ -353,6 +414,35 @@ var Color = class Color {
353
414
  ].map((c) => c.applyOpacity(a * 100));
354
415
  }
355
416
  /**
417
+ * @instance Generates a color palette of evenly distributed hues based on the current color's saturation, lightness, and alpha.
418
+ *
419
+ * @remarks
420
+ * - Colors are spaced evenly around the color wheel (`360° / count` apart), starting from the current hue.
421
+ * - Saturation, lightness, and alpha from the source color are preserved across all generated colors.
422
+ *
423
+ * @typeParam N - A literal number type representing the palette size.
424
+ * @param count - The number of colors to generate in the palette (must be a positive integer ≥ `1`). Default: `7`.
425
+ * @param step - The step value (degree) to be added to the hue of the previous color. Default: `360 / count`.
426
+ * @returns Array of `Color` instances with the specified count.
427
+ *
428
+ * @example
429
+ * const red = new Color("#ff0000");
430
+ * const palette = red.generatePalette(4);
431
+ * console.log(palette.map((color) => color.hex));
432
+ * // ['#FF0000', '#80FF00', '#00FFFF', '#8000FF']
433
+ */
434
+ generatePalette(count, step) {
435
+ const [h, s, l, a] = require_convert.extractAlphaColorValues(this.hsla);
436
+ const clampedCount = require_utilities.clampNumber(count ?? 7, 1, 360);
437
+ const calculatedStep = step ? require_utilities.clampNumber(step, 1, 360) : 360 / clampedCount;
438
+ const colors = [];
439
+ for (let i = 0; i < clampedCount; i++) {
440
+ const color = new Color(`hsl(${(h + calculatedStep * i) % 360}, ${s}%, ${l}%)`).applyOpacity(a * 100);
441
+ colors.push(color);
442
+ }
443
+ return colors;
444
+ }
445
+ /**
356
446
  * @instance Gets the `WCAG` accessibility rating between this and another color.
357
447
  * @param other - The other color to test contrast against.
358
448
  * @returns `'Fail'`, `'AA'`, or `'AAA'` based on `WCAG 2.1` contrast standards.
@@ -374,6 +464,28 @@ var Color = class Color {
374
464
  return (r * 299 + g * 587 + b * 114) / 1e3 > Math.min(255, Math.max(0, threshold));
375
465
  }
376
466
  /**
467
+ * @instance Convert the color to string.
468
+ * @returns The `Hex8` representation of the color.
469
+ *
470
+ * @remarks
471
+ * - Called by `String()`, `Object.prototype.toString()` or in template literals.
472
+ * - Uses the same implementation as `toJSON()`.
473
+ */
474
+ toString() {
475
+ return this.hex8;
476
+ }
477
+ /**
478
+ * @instance Convert the color to JSON.
479
+ * @returns The `Hex8` representation of the color.
480
+ *
481
+ * @remarks
482
+ * - Called by `JSON.stringify()`.
483
+ * - It uses the same implementation as `toString()`.
484
+ */
485
+ toJSON() {
486
+ return this.hex8;
487
+ }
488
+ /**
377
489
  * @static Checks if a color is in {@link Hex6} format.
378
490
  *
379
491
  * @param color Color to check.
@@ -525,10 +637,10 @@ function getColorForInitial(input = "", opacity = 100) {
525
637
  return require_guards._applyOpacity(DEFAULT, hexOpacity);
526
638
  } else if (Array.isArray(input)) {
527
639
  if (input?.length < 1) return [...require_constants.ALPHABET_COLOR_PALETTE, ...require_constants.NUMBER_COLOR_PALETTE].map((color) => require_guards._applyOpacity(color, hexOpacity));
528
- return input.map((el) => {
640
+ return input.flatMap((el) => {
529
641
  if (Array.isArray(el)) return getColorForInitial(el, opacity);
530
642
  return getColorForInitial(el, opacity);
531
- }).flat();
643
+ });
532
644
  }
533
645
  return require_guards._applyOpacity(DEFAULT, hexOpacity);
534
646
  }
package/dist/colors.d.cts CHANGED
@@ -15,7 +15,7 @@
15
15
  */
16
16
 
17
17
  import { er as Percent } from "./object-DyVg8BFt.cjs";
18
- 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";
18
+ 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-SUPeP6fO.cjs";
19
19
 
20
20
  //#region src/colors/convert.d.ts
21
21
  /**
@@ -203,7 +203,7 @@ declare function convertColorCode(color: HSLA): {
203
203
  //#endregion
204
204
  //#region src/colors/initials.d.ts
205
205
  /**
206
- * * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
206
+ * * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
207
207
  *
208
208
  * - For numbers, it uses 10 predefined colors (0-9).
209
209
  * - For letters, it uses 26 predefined colors (A-Z).
package/dist/colors.d.mts CHANGED
@@ -15,7 +15,7 @@
15
15
  */
16
16
 
17
17
  import { er as Percent } from "./object-DyVg8BFt.mjs";
18
- 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";
18
+ 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-D6qMZgDm.mjs";
19
19
 
20
20
  //#region src/colors/convert.d.ts
21
21
  /**
@@ -203,7 +203,7 @@ declare function convertColorCode(color: HSLA): {
203
203
  //#endregion
204
204
  //#region src/colors/initials.d.ts
205
205
  /**
206
- * * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
206
+ * * Generates a hex (`Hex8` format) color based on the first character (initial) of a string or number.
207
207
  *
208
208
  * - For numbers, it uses 10 predefined colors (0-9).
209
209
  * - For letters, it uses 26 predefined colors (A-Z).