@hkdigital/lib-core 0.3.1

package/dist/util/bases/base58.js

@@ -0,0 +1,262 @@
+/**
+ * base-58.js
+ *
+ * @description
+ * This file contains code for working with base 58 encoding
+ *
+ * @example
+ *
+ *   import { base58fromNumber } from "./base-58.js";
+ *
+ *   console.log( base58fromNumber( 1234513245 ) ) // base 58 encoded string
+ */
+
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../expect';
+
+/* ------------------------------------------------------------------ Exports */
+
+// Base 58 helper functions
+//
+// Inspired by
+//   https://github.com/jimeh/node-base58/blob/master/src/base58.js
+//
+// @note
+//   Two different commonly used alphabets exist
+//
+//   Bitcoin, IPFS (respects default sort order):
+//     123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+//
+//   Short URLs for Flickr
+//     123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ
+//
+// @see https://en.wikipedia.org/wiki/StdBase58Helper
+//
+
+export const ALPHABET_BASE_58 =
+  '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+//export
+const BASE_SIZE = BigInt(ALPHABET_BASE_58.length);
+
+// Create a lookup table to fetch character index
+
+export const ALPHABET_BASE_58_MAP =
+  new Map( [...ALPHABET_BASE_58].map( ( char, index ) => [ char, index ] ) );
+
+/**
+ * Convert a number to a base 58 encoded string
+ *
+ * @param {number|BigInt} num - Number to encode
+ *
+ * @returns {string} string encoded using base 58
+ */
+export function base58fromNumber( num )
+{
+  let str = '';
+
+  if( typeof num !== 'bigint' )
+  {
+    if( Number.isNaN( num ) ||
+        num < 0 ||
+        num > Number.MAX_SAFE_INTEGER ||
+        Math.floor( num ) !== num )
+    {
+      throw new Error(
+        'Invalid parameter [num], expected not negative safe integer');
+    }
+
+    num = BigInt(num);
+  }
+
+  while( num >= BASE_SIZE )
+  {
+    const mod = Number(num % BASE_SIZE);
+
+    str = ALPHABET_BASE_58[ mod ] + str;
+
+    // num = Math.floor( num / BASE_SIZE );
+    //
+    num = num / BASE_SIZE; // BigInts are integers, automatically rounded down
+  }
+
+  return ALPHABET_BASE_58[ Number(num) ] + str;
+}
+
+/**
+ * Returns true if the specified string only contains base 58 characters
+ *
+ * @param {string} str [description]
+ *
+ * @returns {boolean} true if the string only contains base 58 characters
+ */
+export function isBase58( str )
+{
+  expect.string( str );
+
+  for( let j = 0, n = str.length; j < n; j = j + 1 )
+  {
+    const char = str.charAt(j);
+    if( !ALPHABET_BASE_58_MAP.has( char ) )
+    {
+      return false;
+    }
+  } // end for
+
+  return true;
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Convert a string encoded as base 58 to a number (BigInt)
+ *
+ * @param {string} str - String to decode
+ *
+ * @param {number} [exceptionValue]
+ *   If specified, the exceptionValue will be returned instead of
+ *   throwing an exception
+ *
+ * @returns {number} decoded decimal numerical representation
+ */
+export function base58toNumber( str, exceptionValue )
+{
+  expect.string( str, 'Missing or invalid parameter [str]' );
+
+  let num = BigInt(0);
+
+  const n = str.length;
+  const n_1 = n - 1;
+
+  for( let j = 0; j < n; j = j + 1 )
+  {
+    const char = str.charAt(j);
+    const value = ALPHABET_BASE_58_MAP.get( char );
+
+    if( value === undefined )
+    {
+      if( 1 === arguments.length )
+      {
+        throw new Error(
+          `Invalid character [${char}] found in string (expected base58`);
+      }
+      else {
+        return exceptionValue;
+      }
+    }
+
+    num = num + BigInt(value) * BigInt(58) ** BigInt( n_1 - j );
+
+    // console.log("num", num );
+
+  } // end for
+
+  return num;
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Convert a base58 encoded string to an Uint8Array (bytes)
+ * - A base58 encoded string actually represents a (potentially very big)
+ *   number. This method converts that number into a bytes representation
+ * - A byte can hold 256 values, a base58 character only 58, so there will be
+ *   less bytes needed to encode the value of the base58 encoded string
+ *
+ * @param {string} str - String to convert
+ *
+ * @returns {Uint8Array} bytes that represent the base58 encoded string value
+ */
+export function base58toBytes( str )
+{
+  const num = base58toNumber( str );
+
+  let numBase16 = num.toString(16);
+
+  if( 1 === numBase16.length % 2 )
+  {
+    //
+    // String contains inpair number of characters -> prefix a "0"
+    //
+    numBase16 = '0' + numBase16;
+  }
+
+  const n = numBase16.length;
+
+  const out = new Uint8Array( numBase16.length >> 1 );
+
+  for( let j = n - 1; j > 0; j = j - 2 )
+  {
+    const low16 = parseInt( numBase16[ j ], 16 );
+    const high16 = parseInt( numBase16[ j - 1 ], 16 );
+
+  //   // const low16 = (j < n_1) ? parseInt(numBase16[ j + 1 ], 10) : 0;
+
+  //   const low16 = (j < n_1) ? parseInt( numBase16[ j + 1 ], 16 ) : 0;
+
+    const value256 = (high16 << 4) + low16;
+
+    out[ j >> 1 ] = value256;
+
+    // console.log(
+    //   {
+    //     numBase16,
+    //     n,
+    //     j,
+    //     high16,
+    //     low16,
+    //     value256,
+    //     out
+    //   } );
+
+  } // end for
+
+  return out;
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Convert a base58 encoded string to a (base256) byte string
+ *
+ * @param {string} str
+ *
+ * @returns {string} byte string
+ */
+export function base58toByteString( str )
+{
+  return new TextDecoder().decode( base58toBytes( str ) );
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Convert bytes to number
+ *
+ * @param {Uint8Array} bytes
+ *
+ * @returns {BigInt} numeric value
+ */
+export function bytesToNumber( bytes )
+{
+  let sum = BigInt(0);
+
+  // console.log( "check", bytes.length );
+
+  for( let j = 0, n = bytes.length; j < n; j = j + 1 )
+  {
+    const base = BigInt(256) ** BigInt( n - 1 - j );
+    const value = bytes[ j ];
+
+    // console.log(
+    //   {
+    //     base,
+    //     value
+    //   } );
+
+    sum = sum + base * BigInt( value );
+  }
+
+  return sum;
+}

package/dist/util/bases/index.d.ts

@@ -0,0 +1 @@
+export * from "./base58.js";

package/dist/util/bases/index.js

@@ -0,0 +1 @@
+export * from './base58.js';

package/dist/util/compare/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Check if the values of two variables should be considered the same
+ *
+ * @param  {any} value1 - First value for comparison
+ * @param  {any} value2 - Second value for comparison
+ *
+ * @return {boolean} true if the two values can be considered the same
+ */
+export function equals(value1: any, value2: any, _pendingComparisons: any): boolean;
+/**
+ * Returns true if x is greater than y
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ */
+export function isGreaterThan(x: any, y: any): boolean;
+/**
+ * Returns true if x is less than y
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ */
+export function isLessThan(x: any, y: any): boolean;
+/**
+ * Compare function that can be used for sorting smallest values first
+ * - undefined values are placed at the ...???FIXME???... of the sorted array
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ *
+ * @returns {number} 0 = keep original order,
+ *                   1 = sort x after y,
+ *                  -1 = sort x before y
+ */
+export function smallestFirst(x: any, y: any): number;
+/**
+ * Compare function that can be used for sorting largest values first
+ * - undefined values are placed at the ...???FIXME???... of the sorted array
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ *
+ * @returns {number} 0 = keep original order,
+ *                   1 = sort x after y,
+ *                  -1 = sort x before y
+ */
+export function largestFirst(x: any, y: any): number;
+/**
+ * Comparator that can be used for sorting using an object path
+ *
+ * @param {function} compareFn - Function to use to compare the values
+ *
+ * @param {any} a - First value
+ * @param {any} b - Second value
+ *
+ * @param {string|string[]} path - Object path
+ */
+export function compareUsingPath(compareFn: Function, a: any, b: any, path: string | string[]): any;
+/**
+ * Comparator that can be used for sorting using an object key
+ *
+ * @param {function} compareFn - Function to use to compare the values
+ * @param {string|string[]} path - Object path
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ */
+export function compareUsingKey(compareFn: Function, key: any, a: any, b: any): any;

package/dist/util/compare/index.js

@@ -0,0 +1,247 @@
+/* ------------------------------------------------------------------ Imports */
+
+import { objectGet } from '../object/index.js';
+
+/* ------------------------------------------------------------------ Exports */
+
+/**
+ * Check if the values of two variables should be considered the same
+ *
+ * @param  {any} value1 - First value for comparison
+ * @param  {any} value2 - Second value for comparison
+ *
+ * @return {boolean} true if the two values can be considered the same
+ */
+export function equals(value1, value2, _pendingComparisons) {
+	// -- Basic sameness comparisons
+
+	if (typeof value1 !== typeof value2) {
+		// Not the same [type]
+		return false;
+	}
+
+	if (!(value1 instanceof Object) && value1 !== value2) {
+		// [Not an object] and [not the same value]
+		return false;
+	}
+
+	if (value1 === value2) {
+		// [same value or same object reference]
+		return true;
+	}
+
+	if (value1 === null || value2 === null) {
+		// [one of the values is null, the other an object]
+		return false;
+	}
+
+	// -- Check if variables are already being compared
+
+	if (!_pendingComparisons) {
+		_pendingComparisons = { value1: [], value2: [] };
+	} else {
+		const values1 = _pendingComparisons.value1;
+		const values2 = _pendingComparisons.value2;
+
+		if (values1.length > 0) {
+			const foundIndex = values1.indexOf(value1);
+
+			if (-1 !== foundIndex && values2[foundIndex] === value2) {
+				// Objects comparison in progress (it's safe to return true),
+				// since equals will fail on other place if objects differ
+				return true;
+			}
+		}
+	}
+
+	// -- Compare special objects
+
+	switch (value1.constructor) {
+		// Implement other special objects here.
+
+		case RegExp:
+			if (value1.toString() === value2.toString()) {
+				return true;
+			}
+			return false;
+
+		case Date:
+			if (value1.getTime() === value2.getTime()) {
+				return true;
+			}
+			return false;
+	}
+
+	// -- Check if both objects have the same properties
+
+	for (const prop in value1) {
+		if (undefined === value2[prop] && undefined !== value1[prop]) {
+			// (defined) property found in value1 that is undefined in value2
+			return false;
+		}
+	}
+
+	for (const prop in value2) {
+		if (undefined === value1[prop] && undefined !== value2[prop]) {
+			// (defined) property found in value2 that is undefined in value1
+			return false;
+		}
+	}
+
+	// -- Check each property for sameness
+
+	_pendingComparisons.value1.push(value1);
+	_pendingComparisons.value2.push(value2);
+
+	for (const prop in value1) {
+		if (false === equals(value1[prop], value2[prop], _pendingComparisons)) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Returns true if x is greater than y
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ */
+export function isGreaterThan(x, y) {
+	if (typeof x === 'undefined') {
+		if (typeof y === 'undefined') {
+			return false;
+		}
+
+		return true;
+	}
+
+	if (typeof y === 'undefined') {
+		return false;
+	}
+
+	return x > y;
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Returns true if x is less than y
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ */
+export function isLessThan(x, y) {
+	if (typeof x === 'undefined') {
+		if (typeof y === 'undefined') {
+			return false;
+		}
+
+		return false;
+	}
+
+	if (typeof y === 'undefined') {
+		return true;
+	}
+
+	return x < y;
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Compare function that can be used for sorting smallest values first
+ * - undefined values are placed at the ...???FIXME???... of the sorted array
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ *
+ * @returns {number} 0 = keep original order,
+ *                   1 = sort x after y,
+ *                  -1 = sort x before y
+ */
+export function smallestFirst(x, y) {
+	if (x === undefined) {
+		if (y === undefined) {
+			return 0;
+		}
+
+		return 1;
+	}
+
+	if (y === undefined) {
+		return -1;
+	}
+
+	return x < y ? -1 : x > y ? 1 : 0;
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Compare function that can be used for sorting largest values first
+ * - undefined values are placed at the ...???FIXME???... of the sorted array
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ *
+ * @returns {number} 0 = keep original order,
+ *                   1 = sort x after y,
+ *                  -1 = sort x before y
+ */
+export function largestFirst(x, y) {
+	if (x === undefined) {
+		if (y === undefined) {
+			return 0;
+		}
+
+		return 1;
+	}
+
+	if (y === undefined) {
+		return -1;
+	}
+
+	return x < y ? 1 : x > y ? -1 : 0;
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Comparator that can be used for sorting using an object path
+ *
+ * @param {function} compareFn - Function to use to compare the values
+ *
+ * @param {any} a - First value
+ * @param {any} b - Second value
+ *
+ * @param {string|string[]} path - Object path
+ */
+export function compareUsingPath(compareFn, a, b, path) {
+	// @note assume a and b are objects
+
+	const valueA = objectGet(a, path);
+	const valueB = objectGet(b, path);
+
+	return compareFn(valueA, valueB);
+}
+
+// ---------------------------------------------------------------------- Method
+
+/**
+ * Comparator that can be used for sorting using an object key
+ *
+ * @param {function} compareFn - Function to use to compare the values
+ * @param {string|string[]} path - Object path
+ *
+ * @param {any} x - First value
+ * @param {any} y - Second value
+ */
+export function compareUsingKey(compareFn, key, a, b) {
+	// @note assume a and b are objects
+
+	return compareFn(a[key], b[key]);
+}

package/dist/util/css/css-vars.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Normalizes a CSS variable name to ensure it has the -- prefix
+ *
+ * @param {string} varName - The CSS variable name
+ * @returns {string} Normalized variable name with -- prefix
+ */
+export function normalizeCssVarName(varName: string): string;
+/**
+ * Extract a CSS variable value from document root
+ *
+ * @param {string} varName - CSS variable name without '--'
+ * @param {boolean} [useCache=false]
+ *
+ * @returns {any} Parsed value or default
+ */
+export function getRootCssVar(varName: string, useCache?: boolean): any;
+/**
+ * Sets a CSS variable in :root to a new value
+ *
+ * @param {string} varName - The CSS variable name (with or without --)
+ * @param {string|number} value - The new value to set
+ * @returns {boolean} True if successful, false otherwise
+ */
+export function setRootCssVar(varName: string, value: string | number): boolean;

package/dist/util/css/css-vars.js

@@ -0,0 +1,83 @@
+let cssVarCache = {};
+
+/**
+ * Normalizes a CSS variable name to ensure it has the -- prefix
+ *
+ * @param {string} varName - The CSS variable name
+ * @returns {string} Normalized variable name with -- prefix
+ */
+export function normalizeCssVarName(varName) {
+  if (typeof varName !== 'string') {
+    throw new Error('Variable name must be a string');
+  }
+  return varName.startsWith('--') ? varName : `--${varName}`;
+}
+
+/**
+ * Extract a CSS variable value from document root
+ *
+ * @param {string} varName - CSS variable name without '--'
+ * @param {boolean} [useCache=false]
+ *
+ * @returns {any} Parsed value or default
+ */
+export function getRootCssVar(varName, useCache = false) {
+  if (cssVarCache[varName] !== undefined && useCache) {
+    return cssVarCache[varName];
+  }
+
+  // Get computed style from document root
+  const rootStyle = getComputedStyle(document.documentElement);
+  const declaration = rootStyle.getPropertyValue(`--${varName}`).trim();
+
+  if (!declaration) {
+    return null;
+  }
+
+  let result;
+
+  // Try to parse as number
+  if (!isNaN(parseFloat(declaration))) {
+    result = parseFloat(declaration);
+  } else {
+    // Return string value
+    result = declaration;
+  }
+
+  // Cache the result
+  cssVarCache[varName] = result;
+  return result;
+}
+
+/**
+ * Sets a CSS variable in :root to a new value
+ *
+ * @param {string} varName - The CSS variable name (with or without --)
+ * @param {string|number} value - The new value to set
+ * @returns {boolean} True if successful, false otherwise
+ */
+export function setRootCssVar(varName, value) {
+  try {
+    if (varName === undefined || varName === null) {
+      throw new Error('Variable name cannot be null or undefined');
+    }
+
+    if (value === undefined || value === null) {
+      throw new Error('Value cannot be null or undefined');
+    }
+
+    const normalizedName = normalizeCssVarName(varName);
+
+    // Convert to string if numeric
+    const formattedValue = typeof value === 'number' ? `${value}` : value;
+
+    document.documentElement.style.setProperty(normalizedName, formattedValue);
+
+    delete cssVarCache[varName];
+
+    return true;
+  } catch (error) {
+    console.error(`Error setting CSS variable ${varName}:`, error);
+    return false;
+  }
+}

package/dist/util/css/index.d.ts

@@ -0,0 +1 @@
+export * from "./css-vars.js";

package/dist/util/css/index.js

@@ -0,0 +1 @@
+export * from './css-vars.js';

package/dist/util/design-system/components/states.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generates state classes from an object of state variables
+ *
+ * @param {Object.<string, boolean>} stateObject
+ *   Object with state names as keys and boolean values
+ *
+ * @returns {string} Space-separated string of state classes
+ *
+ * @example
+ * // Returns "state-selected state-error"
+ * toStateClasses({ selected: true, loading: false, error: true });
+ */
+export function toStateClasses(stateObject: {
+    [x: string]: boolean;
+}): string;