@sv443-network/userutils 7.3.0 → 8.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @sv443-network/userutils
 
+## 8.0.0
+
+### Major Changes
+
+- 54ee0ce: Changed `hexToRgb()` and `rgbToHex()` to support `#RGBA` and `#RRGGBBAA` color codes (with an alpha channel).
+  Both functions now have an `alpha` value immediately after `blue`, which can be set to `undefined` to restore the old behavior.
+
+### Minor Changes
+
+- 54ee0ce: Added parameter `upperCase` (false by default) to `lightenColor()` and `darkenColor()`
+
+### Patch Changes
+
+- 54ee0ce: Consolidated behavior of `lightenColor()` and `darkenColor()` when using non-number values
+
 ## 7.3.0
 
 ### Minor Changes

package/README.md

@@ -69,8 +69,8 @@ View the documentation of previous major releases:
     - [`tr.getLanguage()`](#trgetlanguage) - returns the currently active language
     - [`tr.getTranslations()`](#trgettranslations) - returns the translations for the given language or the currently active one
   - [**Colors:**](#colors)
-    - [`hexToRgb()`](#hextorgb) - convert a hex color string to an RGB number tuple
-    - [`rgbToHex()`](#rgbtohex) - convert RGB numbers to a hex color string
+    - [`hexToRgb()`](#hextorgb) - convert a hex color string to an RGB or RGBA value tuple
+    - [`rgbToHex()`](#rgbtohex) - convert RGB or RGBA values to a hex color string
     - [`lightenColor()`](#lightencolor) - lighten a CSS color string (hex, rgb or rgba) by a given percentage
     - [`darkenColor()`](#darkencolor) - darken a CSS color string (hex, rgb or rgba) by a given percentage
   - [**Utility types for TypeScript:**](#utility-types)
@@ -2154,20 +2154,23 @@ The color functions are used to manipulate and convert colors in various formats
 ### hexToRgb()
 Usage:  
 ```ts
-hexToRgb(hex: string): [red: number, green: number, blue: number]
+hexToRgb(hex: string): [red: number, green: number, blue: number, alpha?: number]
 ```  
   
-Converts a hex color string to an RGB color tuple array.  
-Accepts the formats `#RRGGBB` and `#RGB`, with or without the hash symbol.  
+Converts a hex color string to an RGB or RGBA color tuple array.  
+The values of R, G and B will be in the range of 0-255, while the alpha value will be in the range of 0-1.  
+Accepts the formats `#RRGGBB`, `#RRGGBBAA`, `#RGB` and `#RGBA`, with or without the hash symbol.  
   
 <details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { hexToRgb } from "@sv443-network/userutils";
 
-hexToRgb("#ff0000"); // [255, 0, 0]
-hexToRgb("0032ef");  // [0, 50, 239]
-hexToRgb("#0f0");    // [0, 255, 0]
+hexToRgb("#aaff85aa"); // [170, 255, 133, 0.6666666666666666]
+hexToRgb("#ff0000");   // [255, 0, 0, undefined]
+hexToRgb("0032ef");    // [0, 50, 239, undefined]
+hexToRgb("#0f0");      // [0, 255, 0, undefined]
+hexToRgb("0f0f");      // [0, 255, 0, 1]
 ```
 </details>
 
@@ -2176,10 +2179,10 @@ hexToRgb("#0f0");    // [0, 255, 0]
 ### rgbToHex()
 Usage:  
 ```ts
-rgbToHex(red: number, green: number, blue: number, withHash?: boolean, upperCase?: boolean): string
+rgbToHex(red: number, green: number, blue: number, alpha?: number, withHash?: boolean, upperCase?: boolean): string
 ```  
   
-Converts RGB color values to a hex color string.  
+Converts RGB or RGBA color values to a hex color string.  
 The `withHash` parameter determines if the hash symbol should be included in the output (true by default).  
 The `upperCase` parameter determines if the output should be in uppercase (false by default).  
   
@@ -2188,9 +2191,9 @@ The `upperCase` parameter determines if the output should be in uppercase (false
 ```ts
 import { rgbToHex } from "@sv443-network/userutils";
 
-rgbToHex(255, 0, 0);             // "#ff0000"
-rgbToHex(255, 0, 0, false);      // "ff0000"
-rgbToHex(255, 0, 0, true, true); // "#FF0000"
+rgbToHex(255, 0, 0);                        // "#ff0000" (with hash symbol, lowercase)
+rgbToHex(255, 0, 0, 0.5, false);            // "ff000080" (with alpha, no hash symbol, lowercase)
+rgbToHex(255, 0, 0, undefined, true, true); // "#FF0000" (no alpha, with hash symbol, uppercase)
 ```
 </details>
 
@@ -2199,11 +2202,12 @@ rgbToHex(255, 0, 0, true, true); // "#FF0000"
 ### lightenColor()
 Usage:  
 ```ts
-lightenColor(color: string, percent: number): string
+lightenColor(color: string, percent: number, upperCase?: boolean): string
 ```  
   
 Lightens a CSS color value (in hex, RGB or RGBA format) by a given percentage.  
 Will not exceed the maximum range (00-FF or 0-255).  
+If the `upperCase` parameter is set to true (default is false), the output will be in uppercase.  
 Throws an error if the color format is invalid or not supported.  
   
 <details><summary><b>Example - click to view</b></summary>
@@ -2212,6 +2216,7 @@ Throws an error if the color format is invalid or not supported.
 import { lightenColor } from "@sv443-network/userutils";
 
 lightenColor("#ff0000", 20);              // "#ff3333"
+lightenColor("#ff0000", 20, true);        // "#FF3333"
 lightenColor("rgb(0, 255, 0)", 50);       // "rgb(128, 255, 128)"
 lightenColor("rgba(0, 255, 0, 0.5)", 50); // "rgba(128, 255, 128, 0.5)"
 ```
@@ -2222,11 +2227,12 @@ lightenColor("rgba(0, 255, 0, 0.5)", 50); // "rgba(128, 255, 128, 0.5)"
 ### darkenColor()
 Usage:  
 ```ts
-darkenColor(color: string, percent: number): string
+darkenColor(color: string, percent: number, upperCase?: boolean): string
 ```  
   
 Darkens a CSS color value (in hex, RGB or RGBA format) by a given percentage.  
 Will not exceed the maximum range (00-FF or 0-255).  
+If the `upperCase` parameter is set to true (default is false), the output will be in uppercase.  
 Throws an error if the color format is invalid or not supported.  
   
 <details><summary><b>Example - click to view</b></summary>
@@ -2235,6 +2241,7 @@ Throws an error if the color format is invalid or not supported.
 import { darkenColor } from "@sv443-network/userutils";
 
 darkenColor("#ff0000", 20);              // "#cc0000"
+darkenColor("#ff0000", 20, true);        // "#CC0000"
 darkenColor("rgb(0, 255, 0)", 50);       // "rgb(0, 128, 0)"
 darkenColor("rgba(0, 255, 0, 0.5)", 50); // "rgba(0, 128, 0, 0.5)"
 ```

package/dist/index.global.js

@@ -8,7 +8,7 @@
 // ==UserLibrary==
 // @name         UserUtils
 // @description  Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more
-// @version      7.3.0
+// @version      8.0.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -130,21 +130,26 @@ var UserUtils = (function (exports) {
 
   // lib/colors.ts
   function hexToRgb(hex) {
-    hex = hex.trim();
-    const bigint = parseInt(hex.startsWith("#") ? hex.slice(1) : hex, 16);
+    hex = (hex.startsWith("#") ? hex.slice(1) : hex).trim();
+    const a = hex.length === 8 || hex.length === 4 ? parseInt(hex.slice(-(hex.length / 4)), 16) / (hex.length === 8 ? 255 : 15) : void 0;
+    if (!isNaN(Number(a)))
+      hex = hex.slice(0, -(hex.length / 4));
+    if (hex.length === 3 || hex.length === 4)
+      hex = hex.split("").map((c) => c + c).join("");
+    const bigint = parseInt(hex, 16);
     const r = bigint >> 16 & 255;
     const g = bigint >> 8 & 255;
     const b = bigint & 255;
-    return [clamp(r, 0, 255), clamp(g, 0, 255), clamp(b, 0, 255)];
+    return [clamp(r, 0, 255), clamp(g, 0, 255), clamp(b, 0, 255), typeof a === "number" ? clamp(a, 0, 1) : void 0];
   }
-  function rgbToHex(red, green, blue, withHash = true, upperCase = false) {
+  function rgbToHex(red, green, blue, alpha, withHash = true, upperCase = false) {
     const toHexVal = (n) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0")[upperCase ? "toUpperCase" : "toLowerCase"]();
-    return `${withHash ? "#" : ""}${toHexVal(red)}${toHexVal(green)}${toHexVal(blue)}`;
+    return `${withHash ? "#" : ""}${toHexVal(red)}${toHexVal(green)}${toHexVal(blue)}${alpha ? toHexVal(alpha * 255) : ""}`;
   }
-  function lightenColor(color, percent) {
-    return darkenColor(color, percent * -1);
+  function lightenColor(color, percent, upperCase = false) {
+    return darkenColor(color, percent * -1, upperCase);
   }
-  function darkenColor(color, percent) {
+  function darkenColor(color, percent, upperCase = false) {
     var _a;
     color = color.trim();
     const darkenRgb = (r2, g2, b2, percent2) => {
@@ -154,23 +159,21 @@ var UserUtils = (function (exports) {
       return [r2, g2, b2];
     };
     let r, g, b, a;
-    const isHexCol = color.match(/^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/);
+    const isHexCol = color.match(/^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/);
     if (isHexCol)
-      [r, g, b] = hexToRgb(color);
+      [r, g, b, a] = hexToRgb(color);
     else if (color.startsWith("rgb")) {
       const rgbValues = (_a = color.match(/\d+(\.\d+)?/g)) == null ? void 0 : _a.map(Number);
-      if (rgbValues)
-        [r, g, b, a] = rgbValues;
-      else
+      if (!rgbValues)
         throw new Error("Invalid RGB/RGBA color format");
+      [r, g, b, a] = rgbValues;
     } else
       throw new Error("Unsupported color format");
     [r, g, b] = darkenRgb(r, g, b, percent);
-    const upperCase = color.match(/[A-F]/) !== null;
     if (isHexCol)
-      return rgbToHex(r, g, b, color.startsWith("#"), upperCase);
+      return rgbToHex(r, g, b, a, color.startsWith("#"), upperCase);
     else if (color.startsWith("rgba"))
-      return `rgba(${r}, ${g}, ${b}, ${a})`;
+      return `rgba(${r}, ${g}, ${b}, ${a != null ? a : NaN})`;
     else if (color.startsWith("rgb"))
       return `rgb(${r}, ${g}, ${b})`;
     else

package/dist/index.js

@@ -110,21 +110,26 @@ function randomizeArray(array) {
 
 // lib/colors.ts
 function hexToRgb(hex) {
-  hex = hex.trim();
-  const bigint = parseInt(hex.startsWith("#") ? hex.slice(1) : hex, 16);
+  hex = (hex.startsWith("#") ? hex.slice(1) : hex).trim();
+  const a = hex.length === 8 || hex.length === 4 ? parseInt(hex.slice(-(hex.length / 4)), 16) / (hex.length === 8 ? 255 : 15) : void 0;
+  if (!isNaN(Number(a)))
+    hex = hex.slice(0, -(hex.length / 4));
+  if (hex.length === 3 || hex.length === 4)
+    hex = hex.split("").map((c) => c + c).join("");
+  const bigint = parseInt(hex, 16);
   const r = bigint >> 16 & 255;
   const g = bigint >> 8 & 255;
   const b = bigint & 255;
-  return [clamp(r, 0, 255), clamp(g, 0, 255), clamp(b, 0, 255)];
+  return [clamp(r, 0, 255), clamp(g, 0, 255), clamp(b, 0, 255), typeof a === "number" ? clamp(a, 0, 1) : void 0];
 }
-function rgbToHex(red, green, blue, withHash = true, upperCase = false) {
+function rgbToHex(red, green, blue, alpha, withHash = true, upperCase = false) {
   const toHexVal = (n) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0")[upperCase ? "toUpperCase" : "toLowerCase"]();
-  return `${withHash ? "#" : ""}${toHexVal(red)}${toHexVal(green)}${toHexVal(blue)}`;
+  return `${withHash ? "#" : ""}${toHexVal(red)}${toHexVal(green)}${toHexVal(blue)}${alpha ? toHexVal(alpha * 255) : ""}`;
 }
-function lightenColor(color, percent) {
-  return darkenColor(color, percent * -1);
+function lightenColor(color, percent, upperCase = false) {
+  return darkenColor(color, percent * -1, upperCase);
 }
-function darkenColor(color, percent) {
+function darkenColor(color, percent, upperCase = false) {
   var _a;
   color = color.trim();
   const darkenRgb = (r2, g2, b2, percent2) => {
@@ -134,23 +139,21 @@ function darkenColor(color, percent) {
     return [r2, g2, b2];
   };
   let r, g, b, a;
-  const isHexCol = color.match(/^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/);
+  const isHexCol = color.match(/^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/);
   if (isHexCol)
-    [r, g, b] = hexToRgb(color);
+    [r, g, b, a] = hexToRgb(color);
   else if (color.startsWith("rgb")) {
     const rgbValues = (_a = color.match(/\d+(\.\d+)?/g)) == null ? void 0 : _a.map(Number);
-    if (rgbValues)
-      [r, g, b, a] = rgbValues;
-    else
+    if (!rgbValues)
       throw new Error("Invalid RGB/RGBA color format");
+    [r, g, b, a] = rgbValues;
   } else
     throw new Error("Unsupported color format");
   [r, g, b] = darkenRgb(r, g, b, percent);
-  const upperCase = color.match(/[A-F]/) !== null;
   if (isHexCol)
-    return rgbToHex(r, g, b, color.startsWith("#"), upperCase);
+    return rgbToHex(r, g, b, a, color.startsWith("#"), upperCase);
   else if (color.startsWith("rgba"))
-    return `rgba(${r}, ${g}, ${b}, ${a})`;
+    return `rgba(${r}, ${g}, ${b}, ${a != null ? a : NaN})`;
   else if (color.startsWith("rgb"))
     return `rgb(${r}, ${g}, ${b})`;
   else

package/dist/lib/colors.d.ts

@@ -1,18 +1,21 @@
-/** Converts a hex color string to a tuple of RGB values */
-export declare function hexToRgb(hex: string): [red: number, green: number, blue: number];
-/** Converts RGB values to a hex color string */
-export declare function rgbToHex(red: number, green: number, blue: number, withHash?: boolean, upperCase?: boolean): string;
 /**
- * Lightens a CSS color value (in hex, RGB or RGBA format) by a given percentage.
+ * Converts a hex color string in the format `#RRGGBB`, `#RRGGBBAA` (or even `RRGGBB` and `RGB`) to a tuple.
+ * @returns Returns a tuple array where R, G and B are an integer from 0-255 and alpha is a float from 0 to 1, or undefined if no alpha channel exists.
+ */
+export declare function hexToRgb(hex: string): [red: number, green: number, blue: number, alpha?: number];
+/** Converts RGB or RGBA number values to a hex color string in the format `#RRGGBB` or `#RRGGBBAA` */
+export declare function rgbToHex(red: number, green: number, blue: number, alpha?: number, withHash?: boolean, upperCase?: boolean): string;
+/**
+ * Lightens a CSS color value (in #HEX, rgb() or rgba() format) by a given percentage.
  * Will not exceed the maximum range (00-FF or 0-255).
  * @returns Returns the new color value in the same format as the input
  * @throws Throws if the color format is invalid or not supported
  */
-export declare function lightenColor(color: string, percent: number): string;
+export declare function lightenColor(color: string, percent: number, upperCase?: boolean): string;
 /**
- * Darkens a CSS color value (in hex, RGB or RGBA format) by a given percentage.
+ * Darkens a CSS color value (in #HEX, rgb() or rgba() format) by a given percentage.
  * Will not exceed the maximum range (00-FF or 0-255).
  * @returns Returns the new color value in the same format as the input
  * @throws Throws if the color format is invalid or not supported
  */
-export declare function darkenColor(color: string, percent: number): string;
+export declare function darkenColor(color: string, percent: number, upperCase?: boolean): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "7.3.0",
+  "version": "8.0.0",
   "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",