@sv443-network/userutils 7.2.1 → 7.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @sv443-network/userutils
 
+## 7.3.0
+
+### Minor Changes
+
+- 7e8e147: - Added `tr.forLang()` to get the translation for a specified language code
+  - Added `tr.getTranslations()` to return the translations object for the given or currently active language
+
+## 7.2.2
+
+### Patch Changes
+
+- a171b0d: Fix color functions not being exported 🥴
+
 ## 7.2.1
 
 ### Patch Changes

package/README.md

@@ -4,7 +4,7 @@
 ## UserUtils
 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. Supports ESM and CJS imports via a bundler and UMD / global declaration via `@require`.  
+Contains builtin TypeScript declarations. Supports ESM and CJS imports via a bundler and global declaration via `@require`  
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
 
 <br>
@@ -63,9 +63,11 @@ 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.forLang()`](#trforlang) - specify a language besides the currently set one for the translation
     - [`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.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
@@ -1960,6 +1962,39 @@ console.log(tr("welcome_name", "John")); // "Willkommen, John"
 
 <br>
 
+### tr.forLang()
+Usage:  
+```ts
+tr.forLang(language: string, key: string, ...values: Stringifiable[]): string
+```  
+  
+Returns the translation of the passed key in the specified language. Otherwise behaves exactly like [`tr()`](#tr)  
+This function does not change the currently active language set by [`tr.setLanguage()`](#trsetlanguage)  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { tr } from "@sv443-network/userutils";
+
+tr.addLanguage("en", {
+  "welcome_name": "Welcome, %1",
+});
+
+tr.addLanguage("de", {
+  "welcome_name": "Willkommen, %1",
+});
+
+// the language is set to "en"
+tr.setLanguage("en");
+
+console.log(tr("welcome_name", "John"));               // "Welcome"
+// the language doesn't need to be changed:
+console.log(tr.forLang("de", "welcome_name", "John")); // "Willkommen, John"
+```
+</details>
+
+<br>
+
 ### tr.addLanguage()
 Usage:  
 ```ts
@@ -2080,6 +2115,37 @@ tr.getLanguage(): string | undefined
 Returns the currently active language set by [`tr.setLanguage()`](#trsetlanguage)  
 If no language has been set yet, it will return undefined.
 
+<br>
+
+### tr.getTranslations()
+Usage:  
+```ts
+tr.getTranslations(language?: string): Record<string, string> | undefined
+```  
+  
+Returns the translations of the specified language.  
+If no language is specified, it will return the translations of the currently active language set by [`tr.setLanguage()`](#trsetlanguage)  
+If no translations are found, it will return undefined.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { tr } from "@sv443-network/userutils";
+
+tr.addLanguage("en", {
+  "welcome": "Welcome",
+});
+
+console.log(tr.getTranslations());     // undefined
+tr.setLanguage("en");
+console.log(tr.getTranslations());     // { "welcome": "Welcome" }
+
+console.log(tr.getTranslations("en")); // { "welcome": "Welcome" }
+
+console.log(tr.getTranslations("de")); // undefined
+```
+</details>
+
 <br><br>
 
 ## Colors:

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.2.1
+// @version      7.3.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -128,6 +128,55 @@ var UserUtils = (function (exports) {
     return retArray;
   }
 
+  // lib/colors.ts
+  function hexToRgb(hex) {
+    hex = hex.trim();
+    const bigint = parseInt(hex.startsWith("#") ? hex.slice(1) : 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)];
+  }
+  function rgbToHex(red, green, blue, 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)}`;
+  }
+  function lightenColor(color, percent) {
+    return darkenColor(color, percent * -1);
+  }
+  function darkenColor(color, percent) {
+    var _a;
+    color = color.trim();
+    const darkenRgb = (r2, g2, b2, percent2) => {
+      r2 = Math.max(0, Math.min(255, r2 - r2 * percent2 / 100));
+      g2 = Math.max(0, Math.min(255, g2 - g2 * percent2 / 100));
+      b2 = Math.max(0, Math.min(255, b2 - b2 * percent2 / 100));
+      return [r2, g2, b2];
+    };
+    let r, g, b, a;
+    const isHexCol = color.match(/^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/);
+    if (isHexCol)
+      [r, g, b] = 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
+        throw new Error("Invalid RGB/RGBA color format");
+    } 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);
+    else if (color.startsWith("rgba"))
+      return `rgba(${r}, ${g}, ${b}, ${a})`;
+    else if (color.startsWith("rgb"))
+      return `rgb(${r}, ${g}, ${b})`;
+    else
+      throw new Error("Unsupported color format");
+  }
+
   // lib/dom.ts
   function getUnsafeWindow() {
     try {
@@ -1343,18 +1392,22 @@ Has: ${checksum}`);
   // lib/translation.ts
   var trans = {};
   var curLang;
-  function tr(key, ...args) {
+  var trLang = (language, key, ...args) => {
     var _a;
-    if (!curLang)
+    if (!language)
       return key;
-    const trText = (_a = trans[curLang]) == null ? void 0 : _a[key];
+    const trText = (_a = trans[language]) == null ? void 0 : _a[key];
     if (!trText)
       return key;
     if (args.length > 0 && trText.match(/%\d/)) {
       return insertValues(trText, ...args);
     }
     return trText;
+  };
+  function tr(key, ...args) {
+    return trLang(curLang, key, ...args);
   }
+  tr.forLang = trLang;
   tr.addLanguage = (language, translations) => {
     trans[language] = translations;
   };
@@ -1364,6 +1417,9 @@ Has: ${checksum}`);
   tr.getLanguage = () => {
     return curLang;
   };
+  tr.getTranslations = (language) => {
+    return trans[language != null ? language : curLang];
+  };
 
   exports.DataStore = DataStore;
   exports.DataStoreSerializer = DataStoreSerializer;
@@ -1376,6 +1432,7 @@ Has: ${checksum}`);
   exports.clamp = clamp;
   exports.compress = compress;
   exports.computeHash = computeHash;
+  exports.darkenColor = darkenColor;
   exports.debounce = debounce;
   exports.decompress = decompress;
   exports.defaultDialogCss = defaultDialogCss;
@@ -1383,10 +1440,12 @@ Has: ${checksum}`);
   exports.fetchAdvanced = fetchAdvanced;
   exports.getSiblingsFrame = getSiblingsFrame;
   exports.getUnsafeWindow = getUnsafeWindow;
+  exports.hexToRgb = hexToRgb;
   exports.insertValues = insertValues;
   exports.interceptEvent = interceptEvent;
   exports.interceptWindowEvent = interceptWindowEvent;
   exports.isScrollable = isScrollable;
+  exports.lightenColor = lightenColor;
   exports.mapRange = mapRange;
   exports.observeElementProp = observeElementProp;
   exports.openDialogs = openDialogs;
@@ -1398,6 +1457,7 @@ Has: ${checksum}`);
   exports.randomItem = randomItem;
   exports.randomItemIndex = randomItemIndex;
   exports.randomizeArray = randomizeArray;
+  exports.rgbToHex = rgbToHex;
   exports.setInnerHtmlUnsafe = setInnerHtmlUnsafe;
   exports.takeRandomItem = takeRandomItem;
   exports.tr = tr;

package/dist/index.js

@@ -108,6 +108,55 @@ function randomizeArray(array) {
   return retArray;
 }
 
+// lib/colors.ts
+function hexToRgb(hex) {
+  hex = hex.trim();
+  const bigint = parseInt(hex.startsWith("#") ? hex.slice(1) : 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)];
+}
+function rgbToHex(red, green, blue, 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)}`;
+}
+function lightenColor(color, percent) {
+  return darkenColor(color, percent * -1);
+}
+function darkenColor(color, percent) {
+  var _a;
+  color = color.trim();
+  const darkenRgb = (r2, g2, b2, percent2) => {
+    r2 = Math.max(0, Math.min(255, r2 - r2 * percent2 / 100));
+    g2 = Math.max(0, Math.min(255, g2 - g2 * percent2 / 100));
+    b2 = Math.max(0, Math.min(255, b2 - b2 * percent2 / 100));
+    return [r2, g2, b2];
+  };
+  let r, g, b, a;
+  const isHexCol = color.match(/^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/);
+  if (isHexCol)
+    [r, g, b] = 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
+      throw new Error("Invalid RGB/RGBA color format");
+  } 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);
+  else if (color.startsWith("rgba"))
+    return `rgba(${r}, ${g}, ${b}, ${a})`;
+  else if (color.startsWith("rgb"))
+    return `rgb(${r}, ${g}, ${b})`;
+  else
+    throw new Error("Unsupported color format");
+}
+
 // lib/dom.ts
 function getUnsafeWindow() {
   try {
@@ -1303,18 +1352,22 @@ var SelectorObserver = class {
 // lib/translation.ts
 var trans = {};
 var curLang;
-function tr(key, ...args) {
+var trLang = (language, key, ...args) => {
   var _a;
-  if (!curLang)
+  if (!language)
     return key;
-  const trText = (_a = trans[curLang]) == null ? void 0 : _a[key];
+  const trText = (_a = trans[language]) == null ? void 0 : _a[key];
   if (!trText)
     return key;
   if (args.length > 0 && trText.match(/%\d/)) {
     return insertValues(trText, ...args);
   }
   return trText;
+};
+function tr(key, ...args) {
+  return trLang(curLang, key, ...args);
 }
+tr.forLang = trLang;
 tr.addLanguage = (language, translations) => {
   trans[language] = translations;
 };
@@ -1324,5 +1377,8 @@ tr.setLanguage = (language) => {
 tr.getLanguage = () => {
   return curLang;
 };
+tr.getTranslations = (language) => {
+  return trans[language != null ? language : curLang];
+};
 
-export { DataStore, DataStoreSerializer, Dialog, NanoEmitter, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, computeHash, currentDialogId, debounce, decompress, defaultDialogCss, defaultStrings, fetchAdvanced, getSiblingsFrame, getUnsafeWindow, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, observeElementProp, openDialogs, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, setInnerHtmlUnsafe, takeRandomItem, tr };
+export { DataStore, DataStoreSerializer, Dialog, NanoEmitter, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, computeHash, currentDialogId, darkenColor, debounce, decompress, defaultDialogCss, defaultStrings, fetchAdvanced, getSiblingsFrame, getUnsafeWindow, hexToRgb, insertValues, interceptEvent, interceptWindowEvent, isScrollable, lightenColor, mapRange, observeElementProp, openDialogs, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, rgbToHex, setInnerHtmlUnsafe, takeRandomItem, tr };

package/dist/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./array.js";
+export * from "./colors.js";
 export * from "./crypto.js";
 export * from "./DataStore.js";
 export * from "./DataStoreSerializer.js";

package/dist/lib/translation.d.ts

@@ -1,7 +1,8 @@
 import type { Stringifiable } from "./types.js";
 /**
  * Returns the translated text for the specified key in the current language set by {@linkcode tr.setLanguage()}
- * If the key is not found in the previously registered translation, the key itself is returned.
+ * Use {@linkcode tr.forLang()} to get the translation for a specific language instead of the currently set one.
+ * If the key is not found in the currently set language, the key itself is returned.
  *
  * ⚠️ Remember to register a language with {@linkcode tr.addLanguage()} and set it as active with {@linkcode tr.setLanguage()} before using this function, otherwise it will always return the key itself.
  * @param key Key of the translation to return
@@ -9,8 +10,10 @@ import type { Stringifiable } from "./types.js";
  */
 declare function tr(key: string, ...args: Stringifiable[]): string;
 declare namespace tr {
+    var forLang: (language: string, key: string, ...args: Stringifiable[]) => string;
     var addLanguage: (language: string, translations: Record<string, string>) => void;
     var setLanguage: (language: string) => void;
     var getLanguage: () => string;
+    var getTranslations: (language?: string | undefined) => Record<string, string> | undefined;
 }
 export { tr };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "7.2.1",
+  "version": "7.3.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",