@versini/ui-utilities 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -1,3 +1,43 @@
+/**
+ * Converts decimal degrees (DD) to degrees, minutes, and seconds (DMS) format.
+ *
+ * @param dd - The decimal degrees value to convert.
+ * @param lng - If true, treats the value as longitude (E/W); if false, as latitude (N/S).
+ * @returns An object containing the direction (dir), degrees (deg), minutes (min), and seconds (sec).
+ *
+ * @example
+ * convertDDToDMS(40.7128, false); // { dir: "N", deg: 40, min: 42, sec: 46.08 }
+ * convertDDToDMS(-74.006, true); // { dir: "W", deg: 74, min: 0, sec: 21.6 }
+ */
+export declare const convertDDToDMS: (dd: number, lng: boolean) => {
+    dir: string;
+    deg: number;
+    min: number;
+    sec: number;
+};
+
+/**
+ * Converts a latitude value from decimal degrees to a formatted DMS string.
+ *
+ * @param lat - The latitude in decimal degrees. Optional.
+ * @returns A formatted string like "40° 42' 46.08" N" or "N/A" if lat is undefined.
+ *
+ * @example
+ * convertLatitudeToDMS(40.7128); // "40° 42' 46.08" N"
+ * convertLatitudeToDMS(-33.8688); // "33° 52' 7.68" S"
+ * convertLatitudeToDMS(); // "N/A"
+ */
+export declare const convertLatitudeToDMS: (lat?: number) => string;
+
+/**
+ * Converts camelCase or PascalCase strings into human-readable, title-cased text
+ * by inserting spaces before uppercase characters and normalizing whitespace.
+ *
+ * @param input - The identifier-like string to humanize.
+ * @returns A title-cased, space-separated representation of the input.
+ */
+export declare const convertStringToHumanReadable: (input: string) => string;
+
 /**
  * Creates a debounced function that delays invoking the provided function until
  * after the specified wait time has elapsed since the last time the debounced
@@ -57,4 +97,54 @@ export declare const isProbablyTablet: () => boolean;
  */
 export declare const isPWAMode: () => boolean;
 
+/**
+ * A pre-configured Intl.NumberFormat instance for formatting numbers in English
+ * locale with no decimal places and no sign display.
+ *
+ * @example
+ * numberFormatter.format(1234567); // Returns "1,234,567"
+ * numberFormatter.format(-1234.56); // Returns "1,235"
+ * numberFormatter.format(0.789); // Returns "1"
+ */
+export declare const numberFormatter: Intl.NumberFormat;
+
+/**
+ * Encodes a string to Base64, properly handling Unicode characters by first
+ * converting to UTF-8 percent-encoding then to raw bytes.
+ *
+ * @param str - The string to obfuscate.
+ * @returns The Base64-encoded string.
+ *
+ * @example
+ * obfuscate("hello"); // Returns "aGVsbG8="
+ * obfuscate("héllo"); // Returns "aMOpbGxv" (handles Unicode)
+ */
+export declare const obfuscate: (str: string) => string;
+
+/**
+ * Function that adds an "s" to the end of a word if the count is 0 or greater
+ * than 1.
+ * @param word - The word to potentially pluralize.
+ * @param count - The count to determine if pluralization is needed.
+ * @returns The original word if count is 1, otherwise the pluralized word.
+ *
+ * @example
+ * Showing ${pluralize(`${count} chat`, count)} out of ${total}`;
+ *
+ */
+export declare const pluralize: (word: string, count: number) => string;
+
+/**
+ * Decodes a Base64-encoded string back to its original form, properly handling
+ * Unicode characters by converting from raw bytes to UTF-8 percent-encoding.
+ *
+ * @param str - The Base64-encoded string to decode.
+ * @returns The original decoded string.
+ *
+ * @example
+ * unObfuscate("aGVsbG8="); // Returns "hello"
+ * unObfuscate("aMOpbGxv"); // Returns "héllo" (handles Unicode)
+ */
+export declare const unObfuscate: (str: string) => string;
+
 export { }

package/dist/index.js

@@ -1,12 +1,12 @@
 /*!
-  @versini/ui-utilities v1.1.0
+  @versini/ui-utilities v1.3.0
   © 2025 gizmette.com
 */
 try {
   if (!window.__VERSINI_UI_UTILITIES__) {
     window.__VERSINI_UI_UTILITIES__ = {
-      version: "1.1.0",
-      buildTime: "12/19/2025 03:10 PM EST",
+      version: "1.3.0",
+      buildTime: "12/19/2025 08:08 PM EST",
       homepage: "https://www.npmjs.com/package/@versini/ui-utilities",
       license: "MIT",
     };
@@ -92,6 +92,121 @@ try {
  *
  */ /* c8 ignore start */ const isPWAMode = ()=>{
     return window.matchMedia("(display-mode: standalone)").matches || window.navigator.standalone === true;
-}; /* c8 ignore stop */ 
+};
+/* c8 ignore stop */ /**
+ * Function that adds an "s" to the end of a word if the count is 0 or greater
+ * than 1.
+ * @param word - The word to potentially pluralize.
+ * @param count - The count to determine if pluralization is needed.
+ * @returns The original word if count is 1, otherwise the pluralized word.
+ *
+ * @example
+ * Showing ${pluralize(`${count} chat`, count)} out of ${total}`;
+ *
+ */ const pluralize = (word, count)=>{
+    return count === 1 ? word : `${word}s`;
+};
+/**
+ * A pre-configured Intl.NumberFormat instance for formatting numbers in English
+ * locale with no decimal places and no sign display.
+ *
+ * @example
+ * numberFormatter.format(1234567); // Returns "1,234,567"
+ * numberFormatter.format(-1234.56); // Returns "1,235"
+ * numberFormatter.format(0.789); // Returns "1"
+ */ const numberFormatter = new Intl.NumberFormat("en", {
+    signDisplay: "never",
+    maximumFractionDigits: 0
+});
+/**
+ * Encodes a string to Base64, properly handling Unicode characters by first
+ * converting to UTF-8 percent-encoding then to raw bytes.
+ *
+ * @param str - The string to obfuscate.
+ * @returns The Base64-encoded string.
+ *
+ * @example
+ * obfuscate("hello"); // Returns "aGVsbG8="
+ * obfuscate("héllo"); // Returns "aMOpbGxv" (handles Unicode)
+ */ const obfuscate = (str)=>{
+    /**
+	 * First we use encodeURIComponent to get percent-encoded. UTF-8, then we
+	 * convert the percent encodings into raw bytes which can be fed into btoa.
+	 */ return window.btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function toSolidBytes(_match, p1) {
+        return String.fromCharCode(Number(`0x${p1}`));
+    }));
+};
+/**
+ * Decodes a Base64-encoded string back to its original form, properly handling
+ * Unicode characters by converting from raw bytes to UTF-8 percent-encoding.
+ *
+ * @param str - The Base64-encoded string to decode.
+ * @returns The original decoded string.
+ *
+ * @example
+ * unObfuscate("aGVsbG8="); // Returns "hello"
+ * unObfuscate("aMOpbGxv"); // Returns "héllo" (handles Unicode)
+ */ const unObfuscate = (str)=>{
+    /**
+	 * Going backwards: from bytestream, to percent-encoding, to original string.
+	 */ return decodeURIComponent(window.atob(str).split("").map(function(c) {
+        return `%${`00${c.charCodeAt(0).toString(16)}`.slice(-2)}`;
+    }).join(""));
+};
+/**
+ * Converts decimal degrees (DD) to degrees, minutes, and seconds (DMS) format.
+ *
+ * @param dd - The decimal degrees value to convert.
+ * @param lng - If true, treats the value as longitude (E/W); if false, as latitude (N/S).
+ * @returns An object containing the direction (dir), degrees (deg), minutes (min), and seconds (sec).
+ *
+ * @example
+ * convertDDToDMS(40.7128, false); // { dir: "N", deg: 40, min: 42, sec: 46.08 }
+ * convertDDToDMS(-74.006, true); // { dir: "W", deg: 74, min: 0, sec: 21.6 }
+ */ const convertDDToDMS = (dd, lng)=>{
+    const dir = dd < 0 ? lng ? "W" : "S" : lng ? "E" : "N";
+    const deg = 0 | Math.abs(dd);
+    const min = 0 | Math.abs(dd) * 60 % 60;
+    const sec = (0 | Math.abs(dd) * 60 % 1 * 6000) / 100;
+    return {
+        dir,
+        deg,
+        min,
+        sec
+    };
+};
+/**
+ * Converts a latitude value from decimal degrees to a formatted DMS string.
+ *
+ * @param lat - The latitude in decimal degrees. Optional.
+ * @returns A formatted string like "40° 42' 46.08" N" or "N/A" if lat is undefined.
+ *
+ * @example
+ * convertLatitudeToDMS(40.7128); // "40° 42' 46.08" N"
+ * convertLatitudeToDMS(-33.8688); // "33° 52' 7.68" S"
+ * convertLatitudeToDMS(); // "N/A"
+ */ const convertLatitudeToDMS = (lat)=>{
+    if (!lat && lat !== 0) {
+        return "N/A";
+    }
+    const latitude = convertDDToDMS(lat, false);
+    return `${latitude.deg}° ${latitude.min}' ${latitude.sec}" ${latitude.dir}`;
+};
+/**
+ * Converts camelCase or PascalCase strings into human-readable, title-cased text
+ * by inserting spaces before uppercase characters and normalizing whitespace.
+ *
+ * @param input - The identifier-like string to humanize.
+ * @returns A title-cased, space-separated representation of the input.
+ */ const convertStringToHumanReadable = (input)=>{
+    if (!input) {
+        return "";
+    }
+    const normalized = input.replace(/([A-Z])/g, " $1").replace(/\s+/g, " ").trim();
+    if (!normalized) {
+        return "";
+    }
+    return normalized.charAt(0).toUpperCase() + normalized.slice(1);
+};
 
-export { debounce, isPWAMode, isProbablyMobile, isProbablyTablet, isProbablyiPad, isProbablyiPhone };
+export { convertDDToDMS, convertLatitudeToDMS, convertStringToHumanReadable, debounce, isPWAMode, isProbablyMobile, isProbablyTablet, isProbablyiPad, isProbablyiPhone, numberFormatter, obfuscate, pluralize, unObfuscate };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@versini/ui-utilities",
-	"version": "1.1.0",
+	"version": "1.3.0",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
@@ -39,5 +39,5 @@
 	"sideEffects": [
 		"**/*.css"
 	],
-	"gitHead": "8c05a346766c79bba8ecbeb68c7adbb1e8c5e50c"
+	"gitHead": "3cd6b66a229c88f97e68f9de9cea8d4fabbb55ae"
 }