nhb-toolbox 4.0.46 → 4.0.50

package/dist/cjs/colors/Color.js

@@ -156,10 +156,10 @@ class Color {
      * @returns A new `Color` instance with the modified darkness.
      */
     applyDarkness(percent) {
-        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const [h, s, l, a] = (0, helpers_1._extractAlphaColorValues)(this.hsla);
         const newL = Math.max(0, l - percent);
         const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Lightens the color by increasing the lightness by the given percentage.
@@ -167,10 +167,10 @@ class Color {
      * @returns A new `Color` instance with the modified lightness.
      */
     applyBrightness(percent) {
-        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const [h, s, l, a] = (0, helpers_1._extractAlphaColorValues)(this.hsla);
         const newL = Math.min(100, l + percent);
         const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Reduces the saturation of the color to make it appear duller.
@@ -178,10 +178,10 @@ class Color {
      * @returns A new `Color` instance with the modified saturation.
      */
     applyDullness(percent) {
-        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const [h, s, l, a] = (0, helpers_1._extractAlphaColorValues)(this.hsla);
         const newS = Math.max(0, s - percent);
         const newHSL = `hsl(${h}, ${newS}%, ${l}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Softens the color toward white by reducing saturation and increasing lightness based on a percentage.
@@ -190,15 +190,17 @@ class Color {
      * @returns A new `Color` instance shifted toward white.
      */
     applyWhiteShade(percent) {
-        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const [h, s, l, a] = (0, helpers_1._extractAlphaColorValues)(this.hsla);
         // Cap values to avoid overshooting
         const newS = Math.max(0, s - (s * percent) / 100);
         const newL = Math.min(100, l + ((100 - l) * percent) / 100);
         const newHSL = `hsl(${h}, ${newS}%, ${newL}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Blends the current color with another color based on the given weight.
+     *
+     * - **NOTE:** *If any of the input colors has opacity (alpha channel), it might be lost from the generated alpha variants of the respective color formats.*
      * @param other - The color in any 6 `(Hex, Hex8 RGB, RGBA, HSL or HSLA)` to blend with.
      * @param weight - A number from 0 to 1 indicating the weight of the other color. Defaults to `0.5`.
      * 				 - `weight = 0` → only the original color (this)
@@ -209,11 +211,20 @@ class Color {
     blendWith(other, weight = 0.5) {
         const w = Math.max(0, Math.min(1, weight));
         const converted = new Color(other);
-        const rgb1 = (0, helpers_1._extractSolidColorValues)(this.rgb);
-        const rgb2 = (0, helpers_1._extractSolidColorValues)(converted.rgb);
-        const blended = rgb1.map((c, i) => Math.round(c * (1 - w) + rgb2[i] * w));
-        const blendedRGB = `rgb(${blended[0]}, ${blended[1]}, ${blended[2]})`;
-        return new Color(blendedRGB);
+        const [r1, b1, g1, a1] = (0, helpers_1._extractAlphaColorValues)(this.rgba);
+        const [r2, b2, g2, a2] = (0, helpers_1._extractAlphaColorValues)(converted.rgba);
+        const alpha = a1 * (1 - w) + a2 * w;
+        // ! Original code for solid color
+        // const blended = rgb1.map((c, i) =>
+        // 	Math.round(c * (1 - w) + rgb2[i] * w),
+        // ) as ColorNumbers;
+        // const blendedRGB = `rgb(${blended[0]}, ${blended[1]}, ${blended[2]})`;
+        const blendChannel = (c1, c2) => Math.round((c1 * a1 * (1 - w) + c2 * a2 * w) / alpha);
+        const r = blendChannel(r1, r2);
+        const g = blendChannel(g1, g2);
+        const b = blendChannel(b1, b2);
+        const blended = `rgba(${r}, ${g}, ${b}, ${+alpha.toFixed(2)})`;
+        return new Color(blended);
     }
     /**
      * @instance Calculates the contrast ratio between this color and another color (WCAG).
@@ -243,10 +254,10 @@ class Color {
      * @returns A new Color that is the complement of the current color.
      */
     getComplementaryColor() {
-        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const [h, s, l, a] = (0, helpers_1._extractAlphaColorValues)(this.hsla);
         const newHue = (h + 180) % 360;
         const newHSL = `hsl(${newHue}, ${s}%, ${l}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Generates a color scheme of analogous colors, including the base color.
@@ -254,10 +265,11 @@ class Color {
      * @returns An array of three Color instances: [base, left, right].
      */
     getAnalogousColors() {
-        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const [h, s, l, a] = (0, helpers_1._extractAlphaColorValues)(this.hsla);
         const left = `hsl(${(h + 330) % 360}, ${s}%, ${l}%)`;
         const right = `hsl(${(h + 30) % 360}, ${s}%, ${l}%)`;
-        return [this, new Color(left), new Color(right)];
+        const analogous = [this, new Color(left), new Color(right)];
+        return analogous.map((c) => c.applyOpacity((a * 100)));
     }
     /**
      * @instance Generates a color triad scheme including the base color.
@@ -265,10 +277,11 @@ class Color {
      * @returns An array of three Color instances: [base, triad1, triad2].
      */
     getTriadColors() {
-        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const [h, s, l, a] = (0, helpers_1._extractAlphaColorValues)(this.hsla);
         const c1 = `hsl(${(h + 120) % 360}, ${s}%, ${l}%)`;
         const c2 = `hsl(${(h + 240) % 360}, ${s}%, ${l}%)`;
-        return [this, new Color(c1), new Color(c2)];
+        const triad = [this, new Color(c1), new Color(c2)];
+        return triad.map((c) => c.applyOpacity((a * 100)));
     }
     /**
      * @instance Generates a tetradic color scheme including the base color.
@@ -276,11 +289,12 @@ class Color {
      * @returns An array of four Color instances: [base, tetrad1, tetrad2, tetrad3].
      */
     getTetradColors() {
-        const [h, s, l] = (0, helpers_1._extractSolidColorValues)(this.hsl);
+        const [h, s, l, a] = (0, helpers_1._extractAlphaColorValues)(this.hsla);
         const c1 = `hsl(${(h + 90) % 360}, ${s}%, ${l}%)`;
         const c2 = `hsl(${(h + 180) % 360}, ${s}%, ${l}%)`;
         const c3 = `hsl(${(h + 270) % 360}, ${s}%, ${l}%)`;
-        return [this, new Color(c1), new Color(c2), new Color(c3)];
+        const tetrad = [this, new Color(c1), new Color(c2), new Color(c3)];
+        return tetrad.map((c) => c.applyOpacity((a * 100)));
     }
     /**
      * @instance Gets the `WCAG` accessibility rating between this and another color.

package/dist/cjs/form/convert.js

@@ -212,18 +212,6 @@ const createControlledFormData = (data, configs) => {
                     _addToFormData(key, JSON.stringify(value));
                 }
             }
-            // else if (Array.isArray(value) && value.every(isNotEmptyObject)) {
-            // 	if (shouldDotNotate(fullKey)) {
-            // 		value.forEach((item, index) =>
-            // 			_addToFormData(`${fullKey}[${index}]`, item),
-            // 		);
-            // 	} else if (shouldStringify(fullKey)) {
-            // 		_addToFormData(
-            // 			key,
-            // 			value.map((item) => _processObject(item, parentKey)),
-            // 		);
-            // 	}
-            // }
             else {
                 // * For other cases, just append as key-value
                 _addToFormData(key, value);

package/dist/cjs/object/sanitize.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sanitizeData = sanitizeData;
 exports.parseObjectValues = parseObjectValues;
+const guards_1 = require("../form/guards");
 const non_primitives_1 = require("../guards/non-primitives");
+const primitives_1 = require("../guards/primitives");
 const basics_1 = require("../string/basics");
 /**
  * * Sanitizes a string, array of strings, an object or array of objects by ignoring specified keys and trimming string values.
@@ -13,9 +15,46 @@ const basics_1 = require("../string/basics");
  * @returns A new string, object or array of strings or objects with the specified modifications.
  */
 function sanitizeData(input, options) {
-    const { keysToIgnore: ignoreKeys = [], trimStrings = true, ignoreNullish = false, } = options || {};
+    const { keysToIgnore = [], requiredKeys = [], trimStrings = true, ignoreNullish = false, ignoreFalsy = false, } = options || {};
     // Flatten the object keys and use the keys for comparison
-    const ignoreKeySet = new Set(ignoreKeys);
+    const ignoreKeySet = new Set(keysToIgnore);
+    const isRequiredKey = (key) => {
+        return Array.isArray(requiredKeys) ?
+            requiredKeys.some((path) => key === path || key.startsWith(`${path}.`))
+            : requiredKeys === '*';
+    };
+    /**
+     * * Recursively process an array and its nested content(s).
+     * @param arr Array to process.
+     * @param path Full path as dot notation if needed.
+     * @returns Processed array.
+     */
+    const _processArray = (arr, path) => {
+        return arr
+            .map((item) => {
+            if ((0, primitives_1.isString)(item) && trimStrings) {
+                return (0, basics_1.trimString)(item);
+            }
+            if (Array.isArray(item)) {
+                // Recursive sanitize
+                return _processArray(item, path);
+            }
+            if ((0, non_primitives_1.isObject)(item)) {
+                return _processObject(item, path);
+            }
+            return item;
+        })
+            .filter((v) => {
+            if (ignoreNullish && v == null)
+                return false;
+            if (ignoreFalsy && !v)
+                return false;
+            if (ignoreFalsy && (0, non_primitives_1.isObject)(v) && !(0, non_primitives_1.isNotEmptyObject)(v)) {
+                return false;
+            }
+            return true;
+        });
+    };
     /**
      * * Helper function to process a single object.
      *
@@ -30,23 +69,38 @@ function sanitizeData(input, options) {
             return acc;
         }
         // Exclude nullish values if specified
-        if (ignoreNullish && (value === null || value === undefined)) {
+        if (ignoreNullish && !isRequiredKey(fullKeyPath) && value == null) {
             return acc;
         }
-        // Trim string values if enabled
-        if (typeof value === 'string' && trimStrings) {
+        // Exclude falsy values `0`, `false`, `null` and `undefined`
+        if (ignoreFalsy && !value && !isRequiredKey(fullKeyPath)) {
+            return acc;
+        }
+        if ((0, primitives_1.isString)(value) && trimStrings) {
+            // Trim string values if enabled
             acc[key] = (0, basics_1.trimString)(value);
         }
-        else if (value &&
-            typeof value === 'object' &&
-            !Array.isArray(value)) {
+        else if (value && (0, non_primitives_1.isObject)(value)) {
             // Recursively process nested objects
             const processedValue = _processObject(value, fullKeyPath);
-            // Only add the property if it's not an empty object
-            if ((0, non_primitives_1.isNotEmptyObject)(processedValue)) {
+            // Add the property conditionally if it's not an empty object
+            if (!ignoreFalsy ||
+                isRequiredKey(fullKeyPath) ||
+                (0, non_primitives_1.isNotEmptyObject)(processedValue)) {
                 acc[key] = processedValue;
             }
         }
+        else if (value && Array.isArray(value)) {
+            // Keep file arrays untouched
+            if ((0, guards_1.isFileArray)(value) || (0, guards_1.isCustomFileArray)(value)) {
+                acc[key] = value;
+            }
+            // acc[key as keyof T] = value.map(sanitizeData) as T[keyof T];
+            const sanitizedArray = _processArray(value, fullKeyPath);
+            if (!ignoreFalsy || sanitizedArray.length > 0) {
+                acc[key] = sanitizedArray;
+            }
+        }
         else {
             // Add other values as-is
             acc[key] = value;
@@ -54,22 +108,31 @@ function sanitizeData(input, options) {
         return acc;
     }, {});
     // Process strings
-    if (typeof input === 'string') {
+    if ((0, primitives_1.isString)(input)) {
         return (0, basics_1.trimString)(input);
     }
     // Process array of strings and objects
     if (Array.isArray(input)) {
         // Process array of strings
-        if (typeof input[0] === 'string') {
+        if ((0, non_primitives_1.isArrayOfType)(input, primitives_1.isString)) {
             return (0, basics_1.trimString)(input);
         }
-        // Process array of objects
+        // * Handle arrays with nested strings/arrays/objects
         return input
-            .map((obj) => _processObject(obj))
-            .filter((obj) => (0, non_primitives_1.isNotEmptyObject)(obj));
+            .map((item) => sanitizeData(item, options))
+            .filter((val) => {
+            if (ignoreNullish && val == null)
+                return false;
+            if (ignoreFalsy && !val)
+                return false;
+            if (ignoreFalsy && (0, non_primitives_1.isObject)(val) && !(0, non_primitives_1.isNotEmptyObject)(val)) {
+                return false;
+            }
+            return true;
+        });
     }
     // Process object
-    if (typeof input === 'object' && input !== null) {
+    if ((0, non_primitives_1.isObject)(input)) {
         return _processObject(input);
     }
     return input;
@@ -87,7 +150,7 @@ function parseObjectValues(object) {
     const parsedBody = {};
     if ((0, non_primitives_1.isNotEmptyObject)(object)) {
         Object.entries(object).forEach(([key, value]) => {
-            if (typeof value !== 'string') {
+            if (!(0, primitives_1.isString)(value)) {
                 parsedBody[key] = value;
                 return;
             }

package/dist/dts/colors/Color.d.ts

@@ -1,4 +1,4 @@
-import type { ColorType, Hex6, Hex8, HSL, HSLA, Percent, RGB, RGBA } from './types';
+import type { Analogous, ColorType, Hex6, Hex8, HSL, HSLA, Percent, RGB, RGBA, Tetrad, Triad } from './types';
 /**
  * * Class representing a color and its conversions among `Hex`, `Hex8` `RGB`, `RGBA`, `HSL` and `HSLA` formats.
  * * It has 13 instance methods to manipulate and play with the color values.
@@ -82,7 +82,7 @@ export declare class Color {
      */
     constructor(toConvert: ColorType);
     /** - Iterates over the color representations (Hex, RGB, HSL). */
-    [Symbol.iterator](): Generator<Hex6 | RGB | HSL | Hex8 | RGBA | HSLA, void, unknown>;
+    [Symbol.iterator](): Generator<RGB | HSL | Hex6 | RGBA | Hex8 | HSLA, void, unknown>;
     /**
      * @instance Applies or modifies the opacity of a color. Mutate the original instance.
      * - For solid colors (Hex6/RGB/HSL): Adds an alpha channel with the specified opacity.
@@ -129,6 +129,8 @@ export declare class Color {
     applyWhiteShade(percent: Percent): Color;
     /**
      * @instance Blends the current color with another color based on the given weight.
+     *
+     * - **NOTE:** *If any of the input colors has opacity (alpha channel), it might be lost from the generated alpha variants of the respective color formats.*
      * @param other - The color in any 6 `(Hex, Hex8 RGB, RGBA, HSL or HSLA)` to blend with.
      * @param weight - A number from 0 to 1 indicating the weight of the other color. Defaults to `0.5`.
      * 				 - `weight = 0` → only the original color (this)
@@ -153,19 +155,19 @@ export declare class Color {
      * Analogous colors are next to each other on the color wheel (±30°).
      * @returns An array of three Color instances: [base, left, right].
      */
-    getAnalogousColors(): [Color, Color, Color];
+    getAnalogousColors(): Analogous;
     /**
      * @instance Generates a color triad scheme including the base color.
      * Triadic colors are evenly spaced (120° apart) on the color wheel.
      * @returns An array of three Color instances: [base, triad1, triad2].
      */
-    getTriadColors(): [Color, Color, Color];
+    getTriadColors(): Triad;
     /**
      * @instance Generates a tetradic color scheme including the base color.
      * Tetradic colors form a rectangle on the color wheel (90° apart).
      * @returns An array of four Color instances: [base, tetrad1, tetrad2, tetrad3].
      */
-    getTetradColors(): [Color, Color, Color, Color];
+    getTetradColors(): Tetrad;
     /**
      * @instance Gets the `WCAG` accessibility rating between this and another color.
      * @param other - The other color to test contrast against.

package/dist/dts/colors/Color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Color.d.ts","sourceRoot":"","sources":["../../../src/colors/Color.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAIX,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,OAAO,EACP,GAAG,EACH,IAAI,EAEJ,MAAM,SAAS,CAAC;AAKjB;;;;;;;;;;;GAWG;AACH,qBAAa,KAAK;;IACV,GAAG,EAAE,IAAI,CAAC;IACV,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;OAsBG;;IAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;gBACS,SAAS,EAAE,SAAS;IAwFhC,iEAAiE;IAChE,CAAC,MAAM,CAAC,QAAQ,CAAC;IASlB;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAkBrC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUtC;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUxC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUtC;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAYxC;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,SAAM,GAAG,KAAK;IAgBhD;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM;IAyBvC;;;OAGG;IACH,qBAAqB,IAAI,KAAK;IAU9B;;;;OAIG;IACH,kBAAkB,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;IAS3C;;;;OAIG;IACH,cAAc,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;IASvC;;;;OAIG;IACH,eAAe,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;IAU/C;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK;IAQtD;;;OAGG;IACH,YAAY,IAAI,OAAO;IAQvB;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG;IAIzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG;IAIzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;CAkD3C"}
+{"version":3,"file":"Color.d.ts","sourceRoot":"","sources":["../../../src/colors/Color.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEX,SAAS,EAET,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,OAAO,EACP,GAAG,EACH,IAAI,EAEJ,MAAM,EACN,KAAK,EACL,MAAM,SAAS,CAAC;AAKjB;;;;;;;;;;;GAWG;AACH,qBAAa,KAAK;;IACV,GAAG,EAAE,IAAI,CAAC;IACV,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,IAAI,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;OAsBG;;IAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;gBACS,SAAS,EAAE,SAAS;IAwFhC,iEAAiE;IAChE,CAAC,MAAM,CAAC,QAAQ,CAAC;IASlB;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAkBrC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUtC;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUxC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAUtC;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAYxC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,SAAM,GAAG,KAAK;IA4BhD;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM;IAyBvC;;;OAGG;IACH,qBAAqB,IAAI,KAAK;IAU9B;;;;OAIG;IACH,kBAAkB,IAAI,SAAS;IAa/B;;;;OAIG;IACH,cAAc,IAAI,KAAK;IAWvB;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAczB;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK;IAQtD;;;OAGG;IACH,YAAY,IAAI,OAAO;IAQvB;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG;IAIzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;IAI3C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG;IAIzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI;CAkD3C"}

package/dist/dts/colors/types.d.ts

@@ -1,4 +1,5 @@
 import type { Branded } from '../types';
+import type { Color } from './Color';
 /** - A string, number for generating color. */
 export type ColorInput = string | number;
 /** - An array of strings/numbers or nested arrays of strings/numbers for generating colors. */
@@ -115,4 +116,7 @@ export interface Colors {
     /** - `HSLA` color (e.g., `hsla(14, 100%, 60%, 1)`) */
     hsla: HSLA;
 }
+export type Analogous = [Color, Color, Color];
+export type Triad = [Color, Color, Color];
+export type Tetrad = [Color, Color, Color, Color];
 //# sourceMappingURL=types.d.ts.map

package/dist/dts/colors/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/colors/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/colors/types.ts"],"names":[],"mappings":"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"}

package/dist/dts/form/convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/form/convert.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAEX,aAAa,EAEb,MAAM,iBAAiB,CAAC;AAQzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,aAAa,QACzD,CAAC,YACG,eAAe,CAAC,CAAC,CAAC,KAC1B,QAkQF,CAAC"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/form/convert.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAEX,aAAa,EAEb,MAAM,iBAAiB,CAAC;AAQzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,aAAa,QACzD,CAAC,YACG,eAAe,CAAC,CAAC,CAAC,KAC1B,QAqPF,CAAC"}

package/dist/dts/object/sanitize.d.ts

@@ -10,14 +10,14 @@ import type { GenericObject, SanitizeOptions, StrictObject } from './types';
  */
 export declare function sanitizeData<T extends GenericObject>(object: T, options?: SanitizeOptions<T>): FlattenPartial<T>;
 /**
- * * Sanitizes an array of objects by ignoring specified keys and trimming string values based on options provided.
- * * Also excludes nullish values (null, undefined) if specified. Always ignores empty nested object(s).
+ * * Sanitizes a deeply nested array that may contain arrays, objects or other (mixed) data types.
+ * * Preserves structure while removing empty values and trimming strings and other operations.
  *
- * @param object - The object to sanitize.
- * @param options - Options that define which keys to ignore, whether to trim string values, and whether to exclude nullish values.
- * @returns A new array of objects with the specified modifications.
+ * @param array - A mixed array that may contain arrays, objects or other data types.
+ * @param options - Options to trim and filter values.
+ * @returns A new sanitized array with the specified modifications.
  */
-export declare function sanitizeData<T extends GenericObject>(array: T[], options?: SanitizeOptions<T>): FlattenPartial<T>[];
+export declare function sanitizeData<T>(array: T[], options?: SanitizeOptions<T>): FlattenPartial<T>[];
 /**
  * * Trims all the words in a string.
  *

package/dist/dts/object/sanitize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/object/sanitize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAEX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EACnD,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,CAAC;AAErB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EACnD,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;AAEvB;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;AA4FxD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAgCrE"}
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/object/sanitize.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAEX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EACnD,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,CAAC;AAErB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;AAEvB;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;AAgKxD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAgCrE"}

package/dist/dts/object/types.d.ts

@@ -41,14 +41,26 @@ export type NestedKeyString<T> = T extends AdvancedTypes ? never : T extends Gen
 export type NestedPrimitiveKey<T> = T extends AdvancedTypes ? never : T extends GenericObject ? {
     [K in keyof T & string]: NonNullable<T[K]> extends Primitive ? K : NonNullable<T[K]> extends GenericObject ? `${K}.${NestedPrimitiveKey<NonNullable<T[K]>>}` : never;
 }[keyof T & string] : never;
-/** - Options for `sanitizeData` */
-export interface SanitizeOptions<T extends GenericObject> {
-    /** Keys to ignore */
+/** - Options for `sanitizeData` utility. */
+export interface SanitizeOptions<T> {
+    /**
+     * An array of dot-notation keys to exclude from the sanitized output.
+     * This is only applicable when sanitizing plain objects or arrays of objects.
+     * When applied to nested or irregular array structures, behavior may be inconsistent or partially ignored.
+     */
     keysToIgnore?: DotNotationKey<T>[];
-    /** Whether to trim string values. Defaults to `true` */
+    /** Whether to trim string values. Defaults to `true`. */
     trimStrings?: boolean;
-    /** Whether to exclude nullish (null or undefined) values. Defaults to `false` */
+    /** Whether to exclude nullish (`null` or `undefined`) values. Defaults to `false`. */
     ignoreNullish?: boolean;
+    /** Whether to exclude all falsy values (`false`, `0`, `empty string: ''`, `null`, `undefined` and `empty object and arrays` (`{}`, `[]`)). Defaults to `false`. */
+    ignoreFalsy?: boolean;
+    /**
+     * An array of dot-notation key paths that must be preserved in the sanitized output.
+     * Use `"*"` to retain all keys. This applies primarily to plain or nested objects and arrays of objects.
+     * When applied to nested or irregular array structures, behavior may be inconsistent or partially ignored.
+     */
+    requiredKeys?: '*' | DotNotationKey<T>[];
 }
 /** - Data after sanitization.
  * ! Unused

package/dist/dts/object/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/object/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/object/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/colors/Color.js

@@ -153,10 +153,10 @@ export class Color {
      * @returns A new `Color` instance with the modified darkness.
      */
     applyDarkness(percent) {
-        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const [h, s, l, a] = _extractAlphaColorValues(this.hsla);
         const newL = Math.max(0, l - percent);
         const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Lightens the color by increasing the lightness by the given percentage.
@@ -164,10 +164,10 @@ export class Color {
      * @returns A new `Color` instance with the modified lightness.
      */
     applyBrightness(percent) {
-        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const [h, s, l, a] = _extractAlphaColorValues(this.hsla);
         const newL = Math.min(100, l + percent);
         const newHSL = `hsl(${h}, ${s}%, ${newL}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Reduces the saturation of the color to make it appear duller.
@@ -175,10 +175,10 @@ export class Color {
      * @returns A new `Color` instance with the modified saturation.
      */
     applyDullness(percent) {
-        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const [h, s, l, a] = _extractAlphaColorValues(this.hsla);
         const newS = Math.max(0, s - percent);
         const newHSL = `hsl(${h}, ${newS}%, ${l}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Softens the color toward white by reducing saturation and increasing lightness based on a percentage.
@@ -187,15 +187,17 @@ export class Color {
      * @returns A new `Color` instance shifted toward white.
      */
     applyWhiteShade(percent) {
-        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const [h, s, l, a] = _extractAlphaColorValues(this.hsla);
         // Cap values to avoid overshooting
         const newS = Math.max(0, s - (s * percent) / 100);
         const newL = Math.min(100, l + ((100 - l) * percent) / 100);
         const newHSL = `hsl(${h}, ${newS}%, ${newL}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Blends the current color with another color based on the given weight.
+     *
+     * - **NOTE:** *If any of the input colors has opacity (alpha channel), it might be lost from the generated alpha variants of the respective color formats.*
      * @param other - The color in any 6 `(Hex, Hex8 RGB, RGBA, HSL or HSLA)` to blend with.
      * @param weight - A number from 0 to 1 indicating the weight of the other color. Defaults to `0.5`.
      * 				 - `weight = 0` → only the original color (this)
@@ -206,11 +208,20 @@ export class Color {
     blendWith(other, weight = 0.5) {
         const w = Math.max(0, Math.min(1, weight));
         const converted = new Color(other);
-        const rgb1 = _extractSolidColorValues(this.rgb);
-        const rgb2 = _extractSolidColorValues(converted.rgb);
-        const blended = rgb1.map((c, i) => Math.round(c * (1 - w) + rgb2[i] * w));
-        const blendedRGB = `rgb(${blended[0]}, ${blended[1]}, ${blended[2]})`;
-        return new Color(blendedRGB);
+        const [r1, b1, g1, a1] = _extractAlphaColorValues(this.rgba);
+        const [r2, b2, g2, a2] = _extractAlphaColorValues(converted.rgba);
+        const alpha = a1 * (1 - w) + a2 * w;
+        // ! Original code for solid color
+        // const blended = rgb1.map((c, i) =>
+        // 	Math.round(c * (1 - w) + rgb2[i] * w),
+        // ) as ColorNumbers;
+        // const blendedRGB = `rgb(${blended[0]}, ${blended[1]}, ${blended[2]})`;
+        const blendChannel = (c1, c2) => Math.round((c1 * a1 * (1 - w) + c2 * a2 * w) / alpha);
+        const r = blendChannel(r1, r2);
+        const g = blendChannel(g1, g2);
+        const b = blendChannel(b1, b2);
+        const blended = `rgba(${r}, ${g}, ${b}, ${+alpha.toFixed(2)})`;
+        return new Color(blended);
     }
     /**
      * @instance Calculates the contrast ratio between this color and another color (WCAG).
@@ -240,10 +251,10 @@ export class Color {
      * @returns A new Color that is the complement of the current color.
      */
     getComplementaryColor() {
-        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const [h, s, l, a] = _extractAlphaColorValues(this.hsla);
         const newHue = (h + 180) % 360;
         const newHSL = `hsl(${newHue}, ${s}%, ${l}%)`;
-        return new Color(newHSL);
+        return new Color(newHSL).applyOpacity((a * 100));
     }
     /**
      * @instance Generates a color scheme of analogous colors, including the base color.
@@ -251,10 +262,11 @@ export class Color {
      * @returns An array of three Color instances: [base, left, right].
      */
     getAnalogousColors() {
-        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const [h, s, l, a] = _extractAlphaColorValues(this.hsla);
         const left = `hsl(${(h + 330) % 360}, ${s}%, ${l}%)`;
         const right = `hsl(${(h + 30) % 360}, ${s}%, ${l}%)`;
-        return [this, new Color(left), new Color(right)];
+        const analogous = [this, new Color(left), new Color(right)];
+        return analogous.map((c) => c.applyOpacity((a * 100)));
     }
     /**
      * @instance Generates a color triad scheme including the base color.
@@ -262,10 +274,11 @@ export class Color {
      * @returns An array of three Color instances: [base, triad1, triad2].
      */
     getTriadColors() {
-        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const [h, s, l, a] = _extractAlphaColorValues(this.hsla);
         const c1 = `hsl(${(h + 120) % 360}, ${s}%, ${l}%)`;
         const c2 = `hsl(${(h + 240) % 360}, ${s}%, ${l}%)`;
-        return [this, new Color(c1), new Color(c2)];
+        const triad = [this, new Color(c1), new Color(c2)];
+        return triad.map((c) => c.applyOpacity((a * 100)));
     }
     /**
      * @instance Generates a tetradic color scheme including the base color.
@@ -273,11 +286,12 @@ export class Color {
      * @returns An array of four Color instances: [base, tetrad1, tetrad2, tetrad3].
      */
     getTetradColors() {
-        const [h, s, l] = _extractSolidColorValues(this.hsl);
+        const [h, s, l, a] = _extractAlphaColorValues(this.hsla);
         const c1 = `hsl(${(h + 90) % 360}, ${s}%, ${l}%)`;
         const c2 = `hsl(${(h + 180) % 360}, ${s}%, ${l}%)`;
         const c3 = `hsl(${(h + 270) % 360}, ${s}%, ${l}%)`;
-        return [this, new Color(c1), new Color(c2), new Color(c3)];
+        const tetrad = [this, new Color(c1), new Color(c2), new Color(c3)];
+        return tetrad.map((c) => c.applyOpacity((a * 100)));
     }
     /**
      * @instance Gets the `WCAG` accessibility rating between this and another color.

package/dist/esm/form/convert.js

@@ -209,18 +209,6 @@ export const createControlledFormData = (data, configs) => {
                     _addToFormData(key, JSON.stringify(value));
                 }
             }
-            // else if (Array.isArray(value) && value.every(isNotEmptyObject)) {
-            // 	if (shouldDotNotate(fullKey)) {
-            // 		value.forEach((item, index) =>
-            // 			_addToFormData(`${fullKey}[${index}]`, item),
-            // 		);
-            // 	} else if (shouldStringify(fullKey)) {
-            // 		_addToFormData(
-            // 			key,
-            // 			value.map((item) => _processObject(item, parentKey)),
-            // 		);
-            // 	}
-            // }
             else {
                 // * For other cases, just append as key-value
                 _addToFormData(key, value);

package/dist/esm/object/sanitize.js

@@ -1,4 +1,6 @@
-import { isNotEmptyObject } from '../guards/non-primitives';
+import { isCustomFileArray, isFileArray } from '../form/guards';
+import { isArrayOfType, isNotEmptyObject, isObject, } from '../guards/non-primitives';
+import { isString } from '../guards/primitives';
 import { trimString } from '../string/basics';
 /**
  * * Sanitizes a string, array of strings, an object or array of objects by ignoring specified keys and trimming string values.
@@ -9,9 +11,46 @@ import { trimString } from '../string/basics';
  * @returns A new string, object or array of strings or objects with the specified modifications.
  */
 export function sanitizeData(input, options) {
-    const { keysToIgnore: ignoreKeys = [], trimStrings = true, ignoreNullish = false, } = options || {};
+    const { keysToIgnore = [], requiredKeys = [], trimStrings = true, ignoreNullish = false, ignoreFalsy = false, } = options || {};
     // Flatten the object keys and use the keys for comparison
-    const ignoreKeySet = new Set(ignoreKeys);
+    const ignoreKeySet = new Set(keysToIgnore);
+    const isRequiredKey = (key) => {
+        return Array.isArray(requiredKeys) ?
+            requiredKeys.some((path) => key === path || key.startsWith(`${path}.`))
+            : requiredKeys === '*';
+    };
+    /**
+     * * Recursively process an array and its nested content(s).
+     * @param arr Array to process.
+     * @param path Full path as dot notation if needed.
+     * @returns Processed array.
+     */
+    const _processArray = (arr, path) => {
+        return arr
+            .map((item) => {
+            if (isString(item) && trimStrings) {
+                return trimString(item);
+            }
+            if (Array.isArray(item)) {
+                // Recursive sanitize
+                return _processArray(item, path);
+            }
+            if (isObject(item)) {
+                return _processObject(item, path);
+            }
+            return item;
+        })
+            .filter((v) => {
+            if (ignoreNullish && v == null)
+                return false;
+            if (ignoreFalsy && !v)
+                return false;
+            if (ignoreFalsy && isObject(v) && !isNotEmptyObject(v)) {
+                return false;
+            }
+            return true;
+        });
+    };
     /**
      * * Helper function to process a single object.
      *
@@ -26,23 +65,38 @@ export function sanitizeData(input, options) {
             return acc;
         }
         // Exclude nullish values if specified
-        if (ignoreNullish && (value === null || value === undefined)) {
+        if (ignoreNullish && !isRequiredKey(fullKeyPath) && value == null) {
             return acc;
         }
-        // Trim string values if enabled
-        if (typeof value === 'string' && trimStrings) {
+        // Exclude falsy values `0`, `false`, `null` and `undefined`
+        if (ignoreFalsy && !value && !isRequiredKey(fullKeyPath)) {
+            return acc;
+        }
+        if (isString(value) && trimStrings) {
+            // Trim string values if enabled
             acc[key] = trimString(value);
         }
-        else if (value &&
-            typeof value === 'object' &&
-            !Array.isArray(value)) {
+        else if (value && isObject(value)) {
             // Recursively process nested objects
             const processedValue = _processObject(value, fullKeyPath);
-            // Only add the property if it's not an empty object
-            if (isNotEmptyObject(processedValue)) {
+            // Add the property conditionally if it's not an empty object
+            if (!ignoreFalsy ||
+                isRequiredKey(fullKeyPath) ||
+                isNotEmptyObject(processedValue)) {
                 acc[key] = processedValue;
             }
         }
+        else if (value && Array.isArray(value)) {
+            // Keep file arrays untouched
+            if (isFileArray(value) || isCustomFileArray(value)) {
+                acc[key] = value;
+            }
+            // acc[key as keyof T] = value.map(sanitizeData) as T[keyof T];
+            const sanitizedArray = _processArray(value, fullKeyPath);
+            if (!ignoreFalsy || sanitizedArray.length > 0) {
+                acc[key] = sanitizedArray;
+            }
+        }
         else {
             // Add other values as-is
             acc[key] = value;
@@ -50,22 +104,31 @@ export function sanitizeData(input, options) {
         return acc;
     }, {});
     // Process strings
-    if (typeof input === 'string') {
+    if (isString(input)) {
         return trimString(input);
     }
     // Process array of strings and objects
     if (Array.isArray(input)) {
         // Process array of strings
-        if (typeof input[0] === 'string') {
+        if (isArrayOfType(input, isString)) {
             return trimString(input);
         }
-        // Process array of objects
+        // * Handle arrays with nested strings/arrays/objects
         return input
-            .map((obj) => _processObject(obj))
-            .filter((obj) => isNotEmptyObject(obj));
+            .map((item) => sanitizeData(item, options))
+            .filter((val) => {
+            if (ignoreNullish && val == null)
+                return false;
+            if (ignoreFalsy && !val)
+                return false;
+            if (ignoreFalsy && isObject(val) && !isNotEmptyObject(val)) {
+                return false;
+            }
+            return true;
+        });
     }
     // Process object
-    if (typeof input === 'object' && input !== null) {
+    if (isObject(input)) {
         return _processObject(input);
     }
     return input;
@@ -83,7 +146,7 @@ export function parseObjectValues(object) {
     const parsedBody = {};
     if (isNotEmptyObject(object)) {
         Object.entries(object).forEach(([key, value]) => {
-            if (typeof value !== 'string') {
+            if (!isString(value)) {
                 parsedBody[key] = value;
                 return;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.0.46",
+  "version": "4.0.50",
   "description": "A versatile collection of smart, efficient, and reusable utility functions for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",