@sv443-network/userutils 7.0.1 → 7.2.0

package/README.md

@@ -1,10 +1,10 @@
 <div style="text-align: center;" align="center">
 
-<!-- #MARKER Description -->
+<!-- #region Description -->
 ## UserUtils
-Zero-dependency 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.  
+Lightweight 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.  
   
-Contains builtin TypeScript declarations. Fully web compatible and supports ESM and CJS imports and global declaration.  
+Contains builtin TypeScript declarations. Supports ESM and CJS imports via a bundler and UMD / global declaration via `@require`.  
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
 
 <br>
@@ -19,7 +19,7 @@ View the documentation of previous major releases:
 </div>
 <br>
 
-<!-- #MARKER Table of Contents -->
+<!-- #region Table of Contents -->
 ## Table of Contents:
 - [**Installation**](#installation)
 - [**Preamble** (info about the documentation)](#preamble)
@@ -37,6 +37,7 @@ View the documentation of previous major releases:
     - [`isScrollable()`](#isscrollable) - check if an element has a horizontal or vertical scroll bar
     - [`observeElementProp()`](#observeelementprop) - observe changes to an element's property that can't be observed with MutationObserver
     - [`getSiblingsFrame()`](#getsiblingsframe) - returns a frame of an element's siblings, with a given alignment and size
+    - [`setInnerHtmlUnsafe()`](#setinnerhtmlunsafe) - set the innerHTML of an element using a [Trusted Types policy](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) without sanitizing or escaping it
   - [**Math:**](#math)
     - [`clamp()`](#clamp) - constrain a number between a min and max value
     - [`mapRange()`](#maprange) - map a number from one range to the same spot in another range
@@ -44,6 +45,8 @@ View the documentation of previous major releases:
   - [**Misc:**](#misc)
     - [`DataStore`](#datastore) - class that manages a hybrid sync & async persistent JSON database, including data migration
     - [`DataStoreSerializer`](#datastoreserializer) - class for importing & exporting data of multiple DataStore instances, including compression, checksumming and running migrations
+    - [`Dialog`](#dialog) - class for creating custom modal dialogs with a promise-based API and a generic, default style
+    - [`NanoEmitter`](#nanoemitter) - tiny event emitter class with a focus on performance and simplicity (based on [nanoevents](https://npmjs.com/package/nanoevents))
     - [`autoPlural()`](#autoplural) - automatically pluralize a string
     - [`pauseFor()`](#pausefor) - pause the execution of a function for a given amount of time
     - [`debounce()`](#debounce) - call a function only once in a series of calls, after or before a given timeout
@@ -60,9 +63,14 @@ View the documentation of previous major releases:
     - [`randomizeArray()`](#randomizearray) - returns a copy of the array with its items in a random order
   - [**Translation:**](#translation)
     - [`tr()`](#tr) - simple translation of a string to another language
-    - [tr.addLanguage()](#traddlanguage) - add a language and its translations
-    - [tr.setLanguage()](#trsetlanguage) - set the currently active language for translations
-    - [tr.getLanguage()](#trgetlanguage) - returns the currently active language
+    - [`tr.addLanguage()`](#traddlanguage) - add a language and its translations
+    - [`tr.setLanguage()`](#trsetlanguage) - set the currently active language for translations
+    - [`tr.getLanguage()`](#trgetlanguage) - returns the currently active language
+  - [**Colors:**](#colors)
+    - [`hexToRgb()`](#hextorgb) - convert a hex color string to an RGB number tuple
+    - [`rgbToHex()`](#rgbtohex) - convert RGB numbers 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)
     - [`Stringifiable`](#stringifiable) - any value that is a string or can be converted to one (implicitly or explicitly)
     - [`NonEmptyArray`](#nonemptyarray) - any array that should have at least one item
@@ -71,12 +79,15 @@ View the documentation of previous major releases:
 
 <br><br>
 
-<!-- #MARKER Installation -->
+<!-- #region Installation -->
 ## Installation:
-- If you are using a bundler like webpack, you can install this package using npm:
+Shameless plug: I made a [template for userscripts in TypeScript](https://github.com/Sv443/Userscript.ts) that you can use to get started quickly. It also includes this library by default.  
+  
+- If you are using a bundler (like webpack, rollup, vite, etc.), you can install this package using npm:
   ```
   npm i @sv443-network/userutils
   ```
+  <sup>For other package managers, check out the respective install command on the [JavaScript Registry](https://jsr.io/@sv443-network/userutils)</sup>  
   Then, import it in your script as usual:
   ```ts
   import { addGlobalStyle } from "@sv443-network/userutils";
@@ -85,18 +96,17 @@ View the documentation of previous major releases:
 
   import * as UserUtils from "@sv443-network/userutils";
   ```
-  Shameless plug: I made a [template for userscripts in TypeScript](https://github.com/Sv443/Userscript.ts) that you can use to get started quickly. It also includes this library by default.
 
 <br>
 
-- If you are not using a bundler, you can include the latest release by adding one of these directives to the userscript header, depending on your preferred CDN:
+- If you are not using a bundler or want to reduce the size of your userscript, you can include the latest release by adding one of these directives to the userscript header, depending on your preferred CDN:
   ```
   // @require https://greasyfork.org/scripts/472956-userutils/code/UserUtils.js
   ```
   ```
   // @require https://openuserjs.org/src/libs/Sv443/UserUtils.js
   ```
-  (in order for your userscript not to break on a major library update, use the versioned URL at the top of the [GreasyFork page](https://greasyfork.org/scripts/472956-userutils))  
+  (in order for your userscript not to break on a major library update, instead use the versioned URL at the top of the [GreasyFork page](https://greasyfork.org/scripts/472956-userutils))  
     
   Then, access the functions on the global variable `UserUtils`:
   ```ts
@@ -107,10 +117,16 @@ View the documentation of previous major releases:
   const { clamp } = UserUtils;
   console.log(clamp(1, 5, 10)); // 5
   ```
+  If you're using TypeScript and it complains about the missing global variable `UserUtils`, install the library using the package manager of your choice and add the following inside a `.d.ts` file somewhere in your project:
+  ```ts
+  declare global {
+    const UserUtils: typeof import("@sv443-network/userutils");
+  }
+  ```
 
 <br><br>
 
-<!-- #MARKER Preamble -->
+<!-- #region Preamble -->
 ## Preamble:
 This library is written in TypeScript and contains builtin TypeScript declarations.  
   
@@ -123,19 +139,19 @@ Their documentation will contain a section marked by a warning emoji (⚠️) th
 
 <br><br>
 
-<!-- #MARKER License -->
+<!-- #region License -->
 ## License:
 This library is licensed under the MIT License.  
 See the [license file](./LICENSE.txt) for details.
 
 <br><br>
 
-<!-- #MARKER Features -->
+<!-- #region Features -->
 ## Features:
 
 <br>
 
-<!-- #SECTION DOM -->
+<!-- #region DOM -->
 ## DOM:
 
 ### SelectorObserver
@@ -435,10 +451,8 @@ document.addEventListener("DOMContentLoaded", () => {
   fooObserver.enable();
 });
 ```
-
 </details>
 
-
 <br>
 
 ### getUnsafeWindow()
@@ -466,7 +480,6 @@ const mouseEvent = new MouseEvent("mousemove", {
 
 document.body.dispatchEvent(mouseEvent);
 ```
-
 </details>
 
 <br>
@@ -494,7 +507,6 @@ newParent.href = "https://example.org/";
 
 addParent(element, newParent);
 ```
-
 </details>
 
 <br>
@@ -522,7 +534,6 @@ document.addEventListener("DOMContentLoaded", () => {
   `);
 });
 ```
-
 </details>
 
 <br>
@@ -554,7 +565,6 @@ preloadImages([
     console.error("Couldn't preload all images. Results:", results);
   });
 ```
-
 </details>
 
 <br>
@@ -581,7 +591,6 @@ document.querySelector("#my-button").addEventListener("click", () => {
   openInNewTab("https://example.org/", true);
 });
 ```
-
 </details>
 
 <br>
@@ -616,7 +625,6 @@ interceptEvent(document.body, "click", (event) => {
   return false; // allow all other click events through
 });
 ```
-
 </details>
 
 <br>
@@ -646,7 +654,6 @@ import { interceptWindowEvent } from "@sv443-network/userutils";
 // as no predicate is specified, all events will be discarded by default
 interceptWindowEvent("beforeunload");
 ```
-
 </details>
 
 <br>
@@ -671,7 +678,6 @@ const { horizontal, vertical } = isScrollable(element);
 console.log("Element has a horizontal scroll bar:", horizontal);
 console.log("Element has a vertical scroll bar:", vertical);
 ```
-
 </details>
 
 <br>
@@ -724,7 +730,6 @@ observeElementProp(myInput, "value", (oldValue, newValue) => {
   console.log("Value changed from", oldValue, "to", newValue);
 });
 ```
-
 </details>
 
 <br>
@@ -847,12 +852,42 @@ const allBelowExcl = getSiblingsFrame(refElement, Infinity, "bottom", false);
 // <div>5</div>             │ frame
 // <div>6</div>          ◄──┘
 ```
+</details>
+
+<br>
+
+### setInnerHtmlUnsafe()
+Usage:  
+```ts
+setInnerHtmlUnsafe(element: Element, html: string): Element
+```
+  
+Sets the innerHTML property of the provided element without any sanitation or validation.  
+Makes use of the [Trusted Types API](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) to trick the browser into thinking the HTML is safe.  
+Use this function if the page makes use of the CSP directive `require-trusted-types-for 'script'` and throws a "This document requires 'TrustedHTML' assignment" error on Chromium-based browsers.  
+If the browser doesn't support Trusted Types, this function will fall back to regular innerHTML assignment.  
+  
+⚠️ This function does not perform any sanitization, it only tricks the browser into thinking the HTML is safe and should thus be used with utmost caution, as it can easily cause XSS vulnerabilities!  
+A much better way of doing this is by using the [DOMPurify](https://github.com/cure53/DOMPurify#what-about-dompurify-and-trusted-types) library to create your own Trusted Types policy that *actually* sanitizes the HTML and prevents (most) XSS attack vectors.  
+You can also find more info [here.](https://web.dev/articles/trusted-types#library)  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { setInnerHtmlUnsafe } from "@sv443-network/userutils";
+
+const myElement = document.querySelector("#my-element");
+setInnerHtmlUnsafe(myElement, "<img src='https://picsum.photos/100/100' />");   // hardcoded value, so no XSS risk
 
+const myXssElement = document.querySelector("#my-xss-element");
+const userModifiableVariable = `<img onerror="alert('XSS!')" src="invalid" />`; // let's pretend this came from user input
+setInnerHtmlUnsafe(myXssElement, userModifiableVariable);                       // <- uses a user-modifiable variable, so big XSS risk!
+```
 </details>
 
 <br><br>
 
-<!-- #SECTION Math -->
+<!-- #region Math -->
 ## Math:
 
 ### clamp()
@@ -877,7 +912,6 @@ clamp(99999, 0, 10); // 10
 clamp(-99999, -Infinity, 0); // -99999
 clamp(99999, 0, Infinity);   // 99999
 ```
-
 </details>
 
 <br>
@@ -908,7 +942,6 @@ mapRange(5, 0, 10, 0, 50);  // 25
 // for example, if 4 files of a total of 13 were downloaded:
 mapRange(4, 0, 13, 0, 100); // 30.76923076923077
 ```
-
 </details>
 
 <br>
@@ -932,12 +965,11 @@ randRange(0, 10);  // 4
 randRange(10, 20); // 17
 randRange(10);     // 7
 ```
-
 </details>
 
 <br><br>
 
-<!-- #SECTION Misc -->
+<!-- #region Misc -->
 ## Misc:
 
 ### DataStore
@@ -1100,7 +1132,6 @@ async function init() {
 
 init();
 ```
-
 </details>
 
 <br>
@@ -1108,7 +1139,7 @@ init();
 ### DataStoreSerializer
 Usage:  
 ```ts
-new DataStoreSerializer(stores: DataStore[], options: DataStoreSerializerOptions)
+new DataStoreSerializer(stores: DataStore[], options?: DataStoreSerializerOptions)
 ```
 
 A class that manages serializing and deserializing (exporting and importing) one to infinite DataStore instances.  
@@ -1201,8 +1232,13 @@ const serializer = new DataStoreSerializer([fooStore, barStore], {
 });
 
 async function exportMyDataPls() {
+  // first, make sure the persistent data of the stores is loaded into their caches:
+  await fooStore.loadData();
+  await barStore.loadData();
+
+  // now serialize the data:
   const serializedData = await serializer.serialize();
-  // create file and download it:
+  // create a file and download it:
   const blob = new Blob([serializedData], { type: "application/json" });
   const url = URL.createObjectURL(blob);
   const a = document.createElement("a");
@@ -1211,7 +1247,7 @@ async function exportMyDataPls() {
   a.click();
   a.remove();
 
-  // This function exports an object like this:
+  // `serialize()` exports a stringified object that looks similar to this:
   // [
   //   {
   //     "id": "foo-data",
@@ -1246,7 +1282,241 @@ async function importMyDataPls() {
 ```
 </details>
 
-<br><br>
+<br>
+
+### Dialog
+Usage:  
+```ts
+new Dialog(options: DialogOptions)
+```  
+  
+A class that creates a customizable modal dialog with a title (optional), body and footer (optional).  
+There are tons of options for customization, like changing the close behavior, translating strings and more.  
+  
+The options object has the following properties:  
+| Property | Description |
+| :-- | :-- |
+| `id: string` | A unique internal identification string for this instance. If two Dialogs share the same ID, they will overwrite each other. |
+| `width: number` | The target and maximum width of the dialog in pixels. |
+| `height: number` | The target and maximum height of the dialog in pixels. |
+| `renderBody: () => HTMLElement \| Promise<HTMLElement>` | Called to render the body of the dialog. |
+| `renderHeader?: () => HTMLElement \| Promise<HTMLElement>` | (Optional) Called to render the header of the dialog. Leave undefined for a blank header. |
+| `renderFooter?: () => HTMLElement \| Promise<HTMLElement>` | (Optional) Called to render the footer of the dialog. Leave undefined for no footer. |
+| `closeOnBgClick?: boolean` | (Optional) Whether the dialog should close when the background is clicked. Defaults to `true`. |
+| `closeOnEscPress?: boolean` | (Optional) Whether the dialog should close when the escape key is pressed. Defaults to `true`. |
+| `destroyOnClose?: boolean` | (Optional) Whether the dialog should be destroyed when it's closed. Defaults to `false`. |
+| `unmountOnClose?: boolean` | (Optional) Whether the dialog should be unmounted when it's closed. Defaults to `true`. Superseded by `destroyOnClose`. |
+| `removeListenersOnDestroy?: boolean` | (Optional) Whether all listeners should be removed when the dialog is destroyed. Defaults to `true`. |
+| `small?: boolean` | (Optional) Whether the dialog should have a smaller overall appearance. Defaults to `false`. |
+| `verticalAlign?: "top" \| "center" \| "bottom"` | (Optional) Where to align or anchor the dialog vertically. Defaults to `"center"`. |
+| `strings?: Partial<typeof defaultStrings>` | (Optional) Strings used in the dialog (used for translations). Defaults to the default English strings (importable with the name `defaultStrings`). |
+| `dialogCss?: string` | (Optional) CSS to apply to the dialog. Defaults to the default (importable with the name `defaultDialogCss`). |
+  
+Methods:  
+`open(): Promise<void>`  
+Opens the dialog.  
+  
+`close(): void`  
+Closes the dialog.  
+  
+`mount(): Promise<void>`  
+Mounts the dialog to the DOM by calling the render functions provided in the options object.  
+Can be done before opening the dialog to avoid a delay.  
+  
+`unmount(): void`  
+Unmounts the dialog from the DOM.  
+  
+`remount(): Promise<void>`  
+Unmounts and mounts the dialog again.  
+The render functions in the options object will be called again.  
+May cause a flickering effect due to the rendering delay.  
+  
+`isOpen(): boolean`  
+Returns `true` if the dialog is open, else `false`.  
+  
+`isMounted(): boolean`  
+Returns `true` if the dialog is mounted, else `false`.  
+  
+`destroy(): void`  
+Destroys the dialog.  
+Removes all listeners and unmounts the dialog by default.  
+  
+`static getCurrentDialogId(): string`  
+Static method that returns the ID of the currently open dialog.  
+Needs to be called without creating an instance of the class.  
+  
+`static getOpenDialogs(): string[]`  
+Static method that returns an array of the IDs of all open dialogs.  
+Needs to be called without creating an instance of the class.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { Dialog } from "@sv443-network/userutils";
+
+const fooDialog = new Dialog({
+  id: "foo-dialog",
+  width: 400,
+  height: 300,
+  renderHeader() {
+    const header = document.createElement("div");
+    header.textContent = "This is the header";
+    return header;
+  },
+  renderBody() {
+    const body = document.createElement("div");
+    body.textContent = "This is the body";
+    return body;
+  },
+  renderFooter() {
+    const footer = document.createElement("div");
+    footer.textContent = "This is the footer";
+    return footer;
+  },
+  closeOnBgClick: true,
+  closeOnEscPress: true,
+  destroyOnClose: false,
+  unmountOnClose: true,
+  removeListenersOnDestroy: true,
+  small: false,
+  verticalAlign: "center",
+  strings: {
+    closeDialogTooltip: "Click to close",
+  },
+  dialogCss: getMyCustomDialogCss(),
+});
+
+fooDialog.on("close", () => {
+  console.log("Dialog closed");
+});
+
+fooDialog.open();
+```
+</details>
+
+<br>
+
+### NanoEmitter
+Usage:  
+```ts
+new NanoEmitter<TEventMap = EventsMap>(options?: NanoEmitterOptions): NanoEmitter<TEventMap>
+```  
+  
+A class that provides a minimalistic event emitter with a tiny footprint powered by [nanoevents.](https://npmjs.com/package/nanoevents)  
+The `TEventMap` generic is used to define the events that can be emitted and listened to.  
+  
+The main intention behind this class is to extend it in your own classes to provide a simple event system directly built into the class.  
+However in a functional environment you can also just create instances for use as standalone event emitters throughout your project.  
+  
+The options object has the following properties:
+| Property | Description |
+| :-- | :-- |
+| `publicEmit?: boolean` | (Optional) If set to true, allows emitting events through the public method `emit()` (`false` by default). |
+  
+Methods:  
+`on<K extends keyof TEventMap>(event: K, listener: TEventMap[K]): void`  
+Registers a listener function for the given event.  
+May be called multiple times for the same event.  
+  
+`once<K extends keyof TEventMap>(event: K, listener: TEventMap[K]): void`  
+Registers a listener function for the given event that will only be called once.
+  
+`emit<K extends keyof TEventMap>(event: K, ...args: Parameters<TEventMap[K]>): boolean`  
+Emits an event with the given arguments from outside the class instance if `publicEmit` is set to `true`.  
+If `publicEmit` is set to `true`, this method will return `true` if the event was emitted.  
+If it is set to `false`, it will always return `false` and you will need to use `this.events.emit()` from inside the class instead.  
+  
+`unsubscribeAll(): void`  
+Removes all listeners from all events.  
+  
+<br>
+  
+<details><summary><b>Object oriented example - click to view</b></summary>
+
+```ts
+import { NanoEmitter } from "@sv443-network/userutils";
+
+// map of events for strong typing - the functions always return void
+interface MyEventMap {
+  foo: (bar: string) => void;
+  baz: (qux: number) => void;
+}
+
+class MyClass extends NanoEmitter<MyEventMap> {
+  constructor() {
+    super({
+      // allow emitting events from outside the class
+      publicEmit: true,
+    });
+
+    this.once("baz", (qux) => {
+      console.log("baz event (inside, once):", qux);
+    });
+  }
+
+  public doStuff() {
+    this.emit("foo", "hello");
+    this.emit("baz", 42);
+    this.emit("foo", "world");
+    this.emit("baz", 69);
+  }
+}
+
+const myInstance = new MyClass();
+myInstance.doStuff();
+
+myInstance.on("foo", (bar) => {
+  console.log("foo event (outside):", bar);
+});
+
+myInstance.emit("baz", "hello from the outside");
+
+myInstance.unsubscribeAll();
+```
+</details>
+
+<br>
+
+<details><summary><b>Functional example - click to view</b></summary>
+
+```ts
+import { NanoEmitter } from "@sv443-network/userutils";
+
+// map of events for strong typing - the functions always return void
+interface MyEventMap {
+  foo: (bar: string) => void;
+  baz: (qux: number) => void;
+}
+
+const myEmitter = new NanoEmitter<MyEventMap>({
+  // allow emitting events from outside the class
+  publicEmit: true,
+});
+
+myEmitter.on("foo", (bar) => {
+  console.log("foo event:", bar);
+});
+
+myEmitter.once("baz", (qux) => {
+  console.log("baz event (once):", qux);
+});
+
+function doStuff() {
+  myEmitter.emit("foo", "hello");
+  myEmitter.emit("baz", 42);
+  myEmitter.emit("foo", "world");
+  myEmitter.emit("baz", 69);
+
+  myEmitter.emit("foo", "hello from the outside");
+
+  myEmitter.unsubscribeAll();
+}
+
+doStuff();
+```
+</details>
+
+<br>
 
 ### autoPlural()
 Usage:  
@@ -1272,7 +1542,6 @@ autoPlural("apple", [1, 2]); // "apples"
 const items = [1, 2, 3, 4, "foo", "bar"];
 console.log(`Found ${items.length} ${autoPlural("item", items)}`); // "Found 6 items"
 ```
-
 </details>
 
 <br>
@@ -1296,7 +1565,6 @@ async function run() {
   console.log("World");
 }
 ```
-
 </details>
 
 <br>
@@ -1342,7 +1610,6 @@ const myFunc = debounce((event) => {
 
 document.body.addEventListener("scroll", myFunc);
 ```
-
 </details>
 
 <br>
@@ -1377,7 +1644,6 @@ fetchAdvanced("https://jokeapi.dev/joke/Any?safe-mode", {
   console.error("Fetch error:", err);
 });
 ```
-
 </details>
 
 <br>
@@ -1405,7 +1671,6 @@ insertValues("Testing %1", { toString: () => "foo" });      // "Testing foo"
 const values = ["foo", "bar", "baz"];
 insertValues("Testing %1, %2, %3 and %4", ...values); // "Testing foo, bar and baz and %4"
 ```
-
 </details>
 
 <br>
@@ -1446,7 +1711,6 @@ const barDeflate = await compress("Hello, World!".repeat(20), "deflate");
 console.log(fooDeflate); // "eJzzSM3JyddRCM8vyklRBAAfngRq"
 console.log(barDeflate); // "eJzzSM3JyddRCM8vyklR9BiZHAAIEVg1"
 ```
-
 </details>
 
 <br>
@@ -1477,7 +1741,6 @@ const decompressed = await decompress(compressed, "gzip");
 
 console.log(decompressed); // "Hello, World!"
 ```
-
 </details>
 
 <br>
@@ -1544,12 +1807,11 @@ randomId(10, 2);  // "1010001101"       (length 10, radix 2)
 randomId(10, 10); // "0183428506"       (length 10, radix 10)
 randomId(10, 36); // "z46jfpa37r"       (length 10, radix 36)
 ```
-
 </details>
 
 <br><br>
 
-<!-- #SECTION Arrays -->
+<!-- #region Arrays -->
 ## Arrays:
 
 ### randomItem()
@@ -1569,7 +1831,6 @@ import { randomItem } from "@sv443-network/userutils";
 randomItem(["foo", "bar", "baz"]); // "bar"
 randomItem([ ]);                   // undefined
 ```
-
 </details>
 
 <br>
@@ -1596,7 +1857,6 @@ const [item, index] = randomItemIndex(["foo", "bar", "baz"]); // ["bar", 1]
 // or if you only want the index:
 const [, index] = randomItemIndex(["foo", "bar", "baz"]); // 1
 ```
-
 </details>
 
 <br>
@@ -1619,7 +1879,6 @@ const arr = ["foo", "bar", "baz"];
 takeRandomItem(arr); // "bar"
 console.log(arr);    // ["foo", "baz"]
 ```
-
 </details>
 
 <br>
@@ -1645,12 +1904,11 @@ console.log(randomizeArray(foo)); // [4, 5, 2, 1, 6, 3]
 
 console.log(foo); // [1, 2, 3, 4, 5, 6] - original array is not mutated
 ```
-
 </details>
 
 <br><br>
 
-<!-- #SECTION Translation -->
+<!-- #region Translation -->
 ## Translation:
 This is a very lightweight translation function that can be used to translate simple strings.  
 Pluralization is not supported but can be achieved manually by adding variations to the translations, identified by a different suffix. See the example section of [`tr.addLanguage()`](#traddlanguage) for an example on how this might be done.
@@ -1698,7 +1956,6 @@ tr.setLanguage("de");
 console.log(tr("welcome"));              // "Willkommen"
 console.log(tr("welcome_name", "John")); // "Willkommen, John"
 ```
-
 </details>
 
 <br>
@@ -1770,34 +2027,33 @@ tr.addLanguage("de-AT", {
 // example for custom pluralization:
 
 tr.addLanguage("en", {
-  "items_added-0": "Added %1 items to your cart",
-  "items_added-1": "Added %1 item to your cart",
-  "items_added-n": "Added all %1 items to your cart",
+  "cart_items_added-0": "No items were added to the cart",
+  "cart_items_added-1": "Added %1 item to the cart",
+  "cart_items_added-n": "Added %1 items to the cart",
 });
 
-/** Returns the custom pluralization identifier for the given number of items (or size of Array/NodeList) */
-function pl(num: number | unknown[] | NodeList) {
+/** Returns the translation key with a custom pluralization identifier added to it for the given number of items (or size of Array/NodeList or anything else with a `length` property) */
+function pl(key: string, num: number | Array<unknown> | NodeList | { length: number }) {
   if(typeof num !== "number")
     num = num.length;
 
   if(num === 0)
-    return "0";
+    return `${key}-0`;
   else if(num === 1)
-    return "1";
+    return `${key}-1`;
   else
-    return "n";
+    return `${key}-n`;
 };
 
 const items = [];
-tr(`items_added-${pl(items)}`, items.length); // "Added 0 items to your cart"
+console.log(tr(pl("cart_items_added", items), items.length)); // "No items were added to the cart"
 
 items.push("foo");
-tr(`items_added-${pl(items)}`, items.length); // "Added 1 item to your cart"
+console.log(tr(pl("cart_items_added", items), items.length)); // "Added 1 item to the cart"
 
 items.push("bar");
-tr(`items_added-${pl(items)}`, items.length); // "Added all 2 items to your cart"
+console.log(tr(pl("cart_items_added", items), items.length)); // "Added 2 items to the cart"
 ```
-
 </details>
 
 <br>
@@ -1826,7 +2082,101 @@ If no language has been set yet, it will return undefined.
 
 <br><br>
 
-<!-- #SECTION Utility types -->
+## Colors:
+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]
+```  
+  
+Converts a hex color string to an RGB color tuple array.  
+Accepts the formats `#RRGGBB` and `#RGB`, 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]
+```
+</details>
+
+<br>
+
+### rgbToHex()
+Usage:  
+```ts
+rgbToHex(red: number, green: number, blue: number, withHash?: boolean, upperCase?: boolean): string
+```  
+  
+Converts RGB 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).  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```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"
+```
+</details>
+
+<br>
+
+### lightenColor()
+Usage:  
+```ts
+lightenColor(color: string, percent: number): 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).  
+Throws an error if the color format is invalid or not supported.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { lightenColor } from "@sv443-network/userutils";
+
+lightenColor("#ff0000", 20);              // "#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)"
+```
+</details>
+
+<br>
+
+### darkenColor()
+Usage:  
+```ts
+darkenColor(color: string, percent: number): 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).  
+Throws an error if the color format is invalid or not supported.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { darkenColor } from "@sv443-network/userutils";
+
+darkenColor("#ff0000", 20);              // "#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)"
+```
+</details>
+
+<br><br>
+
+<!-- #region Utility types -->
 ## Utility types:
 UserUtils also offers some utility types that can be used in TypeScript projects.  
 They don't alter the runtime behavior of the code, but they can be used to make the code more readable and to prevent errors.
@@ -1862,7 +2212,6 @@ logSomething(fooObject); // "Log: hello world"
 
 logSomething(barObject); // Type error
 ```
-
 </details>
 
 <br>
@@ -1893,7 +2242,6 @@ function somethingElse(array: NonEmptyArray) {
 
 logFirstItem(["04abc", "69"]); // 4
 ```
-
 </details>
 
 <br>
@@ -1918,7 +2266,6 @@ function convertToNumber<T extends string>(str: NonEmptyString<T>) {
 convertToNumber("04abc"); // "4"
 convertToNumber("");      // type error: Argument of type 'string' is not assignable to parameter of type 'never'
 ```
-
 </details>
 
 <br>
@@ -1946,12 +2293,11 @@ foo("a"); // included in autocomplete, no type error
 foo("");  // *not* included in autocomplete, still no type error
 foo(1);   // type error: Argument of type '1' is not assignable to parameter of type 'LooseUnion<"a" | "b" | "c">'
 ```
-
 </details>
 
 <br><br><br><br>
 
-<!-- #MARKER Footer -->
+<!-- #region Footer -->
 <div style="text-align: center;" align="center">
 
 Made with ❤️ by [Sv443](https://github.com/Sv443)