@rabex-kit/rabex-ui 0.2.45 → 0.2.46

package/dist/rabex-ui.cjs.development.js

@@ -381,73 +381,189 @@ function useOnScreen(ref, options) {
   return isIntersecting;
 }
 
+// ============================================================================
+// CONSTANTS & TYPE DEFINITIONS
+// ============================================================================
+/**
+ * Persian/Farsi numerals mapping to English numerals
+ * Used for localization and number format conversion
+ */
 var persianNumber = ['۰', '۱', '۲', '۳', '۴', '۵', '۶', '۷', '۸', '۹'];
+/**
+ * Standard English numerals
+ * Target format for all numeric operations
+ */
 var englishNumber = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'];
+/**
+ * Valid decimal and thousand separator characters
+ * Allows both period and comma based on locale preferences
+ */
 var charachter = ['.', ','];
+// ============================================================================
+// CORE UTILITY FUNCTIONS - SCIENTIFIC NOTATION SAFE
+// ============================================================================
+/**
+ * CONVERT SCIENTIFIC NOTATION TO DECIMAL STRING
+ *
+ * Purpose: Prevents scientific notation (1e-8) by converting to decimal format (0.00000001)
+ *
+ * @param num - Input number in any format (number, string, scientific notation)
+ * @returns Decimal string representation or undefined if invalid
+ *
+ * Key Features:
+ * - Handles very large numbers using BigInt
+ * - Handles very small numbers with proper decimal places
+ * - Returns undefined for invalid inputs (NaN, null, undefined)
+ * - Uses toFixed(20) to ensure adequate precision
+ * - Removes trailing zeros for clean output
+ *
+ * Examples:
+ * convertScientific(1e-8) → "0.00000001"
+ * convertScientific(1e8) → "100000000"
+ * convertScientific("abc") → undefined
+ */
+var convertScientific = function convertScientific(num) {
+  // Handle null, undefined, or empty string inputs
+  if (num === null || num === undefined || num === '') {
+    return undefined;
+  }
+  // Convert input to number for validation and processing
+  var numValue = Number(num);
+  // Validate that the result is a finite number
+  if (isNaN(numValue) || !isFinite(numValue)) {
+    return undefined;
+  }
+  // Handle exact zero case
+  if (numValue === 0) return '0';
+  // Handle very large integers using BigInt to avoid precision loss
+  // Numbers >= 1e15 may lose precision in JavaScript's Number type
+  if (Math.abs(numValue) >= 1e15 && Number.isInteger(numValue)) {
+    return BigInt(Math.round(numValue)).toString();
+  }
+  // Handle very small numbers that would round to zero
+  if (Math.abs(numValue) < 1e-15) {
+    return '0';
+  }
+  // Convert to fixed decimal notation with high precision
+  // Then remove trailing zeros for clean output
+  return numValue.toFixed(20).replace(/\.?0+$/, '');
+};
+/**
+ * SAFE NUMBER CONVERSION
+ *
+ * Purpose: Wrapper around convertScientific that always returns a valid string
+ *
+ * @param num - Input number in any format
+ * @returns Decimal string representation (defaults to '0' if conversion fails)
+ *
+ * This is the primary function used throughout the library to ensure
+ * all number inputs are converted to safe decimal strings before processing
+ */
+var safeNumber = function safeNumber(num) {
+  return convertScientific(num) || '0';
+};
+// ============================================================================
+// FORMATTING & DISPLAY FUNCTIONS
+// ============================================================================
+/**
+ * NUMBER SUFFIX FORMATTER (K, M, B, T)
+ *
+ * Purpose: Converts large numbers to human-readable format with suffixes
+ *
+ * @param num - Input number to format
+ * @param options - Formatting options (precision, rounding method, allowed suffixes)
+ * @returns Formatted string with appropriate suffix
+ *
+ * Key Features:
+ * - Uses bigDecimal for all calculations to avoid scientific notation
+ * - Supports custom precision and rounding methods
+ * - Configurable suffix types (K=thousands, M=millions, B=billions, T=trillions)
+ * - Falls back to original number if no suffix applies
+ *
+ * Examples:
+ * suffix(1000, {precision: 1}) → "1K"
+ * suffix(1500000, {precision: 2, round: 'roundUp'}) → "1.5M"
+ * suffix(2.5e9) → "2.5B"
+ *
+ * Scientific Notation Prevention:
+ * - Uses string-based thresholds instead of numeric literals
+ * - BigDecimal comparison instead of JavaScript's Math.abs()
+ * - BigDecimal division instead of standard division operator
+ */
 function suffix(num, options) {
-  var _ref = options || {},
-    _ref$precision = _ref.precision,
-    precision = _ref$precision === void 0 ? 3 : _ref$precision,
-    _ref$round = _ref.round,
-    round = _ref$round === void 0 ? 'roundDown' : _ref$round,
-    _ref$suffix = _ref.suffix,
-    suffix = _ref$suffix === void 0 ? ['B', 'T'] : _ref$suffix;
+  if (options === void 0) {
+    options = {};
+  }
+  var _options = options,
+    _options$precision = _options.precision,
+    precision = _options$precision === void 0 ? 3 : _options$precision,
+    _options$round = _options.round,
+    round = _options$round === void 0 ? 'roundDown' : _options$round,
+    _options$suffix = _options.suffix,
+    suffix = _options$suffix === void 0 ? ['B', 'T'] : _options$suffix;
+  // Define thresholds as strings to avoid floating point precision issues
   var map = [{
     suffix: 'T',
-    threshold: 1e12
+    threshold: '1000000000000'
   }, {
     suffix: 'B',
-    threshold: 1e9
+    threshold: '1000000000'
   }, {
     suffix: 'M',
-    threshold: 1e6
+    threshold: '1000000'
   }, {
     suffix: 'K',
-    threshold: 1e3
+    threshold: '1000'
   }, {
     suffix: '$',
-    threshold: 1
+    threshold: '1'
   }];
+  // Convert input to safe decimal string
+  var numStr = safeNumber(num);
+  // Find appropriate suffix using bigDecimal comparison
   var found = map.find(function (x) {
-    return Math.abs(Number(num)) >= x.threshold && _includes([].concat(suffix, ['$']), x.suffix);
+    var comparison = bigDecimal.compareTo(bigDecimal.abs(numStr), x.threshold);
+    return comparison >= 0 && _includes([].concat(suffix, ['$']), x.suffix);
   });
+  // Reference to enhanced rounding functions
   var func = {
-    roundDown: _roundDown,
-    roundUp: _roundUp
+    roundDown: enhancedRoundDown,
+    roundUp: enhancedRoundUp
   };
   if (found) {
-    var formatted = func[round](Number(num) / found.threshold, precision) + (found.suffix === '$' ? '' : found.suffix);
+    // Use bigDecimal division to maintain precision
+    var divided = bigDecimal.divide(numStr, found.threshold, precision + 2);
+    var formatted = func[round](parseFloat(divided), precision) + (found.suffix === '$' ? '' : found.suffix);
     return formatted;
   }
-  return num.toString();
+  // Return original number if no suffix applies
+  return numStr;
 }
-var divide = function divide(num1, num2, precision) {
-  if (Number(num1) === 0) console.log('can not divide by zero! - (arguments[0])');
-  if (Number(num2) === 0) console.log('can not divide by zero! - (arguments[1])');
-  var number1 = Number(num1) || 1;
-  var number2 = Number(num2) || 1;
-  return bigDecimal.divide(number1, number2, precision);
-};
-var _toEn = function toEn(num) {
-  var find = [].concat(persianNumber, ['٫']);
-  var replace = [].concat(englishNumber, ['.']);
-  var replaceString = num;
-  var regex;
-  for (var i = 0; i < find.length; i++) {
-    regex = new RegExp(find[i], 'g');
-    replaceString = replaceString.replace(regex, replace[i]);
-  }
-  return replaceString;
-};
-var _isValid = function isValid(num) {
-  var numbers = typeof num === 'number' ? num.toString() : num;
-  if (numbers.length === 0) return true;
-  var allowCharachter = [].concat(persianNumber, englishNumber, charachter);
-  if (_includes(allowCharachter, numbers.slice(-1))) {
-    return true;
-  }
-  return false;
-};
+/**
+ * THOUSAND SEPARATOR FORMATTER
+ *
+ * Purpose: Adds thousand separators to numbers for improved readability
+ *
+ * @param num - Input number to format
+ * @param separator - Character to use as separator (default: comma)
+ * @param separateBy - Number of digits between separators (default: 3)
+ * @returns Formatted string with separators
+ *
+ * Key Features:
+ * - Preserves decimal places
+ * - Configurable separator character and grouping
+ * - Handles both number and string inputs
+ * - Uses safeNumber conversion to avoid scientific notation
+ *
+ * Examples:
+ * delimiter(1000) → "1,000"
+ * delimiter(1234567.89) → "1,234,567.89"
+ * delimiter(1000, '.', 3) → "1.000"
+ *
+ * Scientific Notation Prevention:
+ * - Uses safeNumber() instead of toString() for number inputs
+ * - Ensures consistent decimal format before processing
+ */
 var _delimiter = function delimiter(num, separator, separateBy) {
   if (separator === void 0) {
     separator = ',';
@@ -455,75 +571,582 @@ var _delimiter = function delimiter(num, separator, separateBy) {
   if (separateBy === void 0) {
     separateBy = 3;
   }
-  var numbers = typeof num === 'number' ? num.toString() : num;
+  // Convert number inputs to safe decimal string, keep strings as-is
+  var numbers = typeof num === 'number' ? safeNumber(num) : num;
   if (numbers) {
+    // Split into integer and decimal parts
     var parts = numbers.split('.');
+    // Create regex pattern for inserting separators
     var regex = new RegExp("(\\d)(?=(\\d{" + separateBy + "})+(?!\\d))", 'g');
+    // Apply separators to integer part, removing any existing separators first
     parts[0] = _replace(parts[0].split(',').join(''), regex, "$1" + separator);
+    // Rejoin integer and decimal parts
     return parts.join('.');
   }
   return num;
 };
+/**
+ * REMOVE THOUSAND SEPARATORS
+ *
+ * Purpose: Removes thousand separators and returns clean decimal string
+ *
+ * @param num - Input string with separators
+ * @param separator - Separator character to remove (default: comma)
+ * @returns Clean decimal string without separators
+ *
+ * Key Features:
+ * - Returns string instead of number to prevent scientific notation
+ * - Uses safeNumber conversion for validation
+ * - Preserves original precision
+ *
+ * Examples:
+ * removeDelimiter("1,234,567") → "1234567"
+ * removeDelimiter("1.234.567", ".") → "1234567"
+ *
+ * Scientific Notation Prevention:
+ * - Returns string type instead of number
+ * - Uses safeNumber() for final validation
+ */
 var _removeDelimiter = function removeDelimiter(num, separator) {
   if (separator === void 0) {
     separator = ',';
   }
+  // Remove all instances of the separator character
   var cleanedNumber = num.split(separator).join('');
-  return parseFloat(cleanedNumber);
+  // Return as safe decimal string instead of number to avoid scientific notation
+  return safeNumber(cleanedNumber);
+};
+// ============================================================================
+// MATHEMATICAL OPERATIONS - HIGH PRECISION
+// ============================================================================
+/**
+ * SAFE DIVISION WITH PRECISION
+ *
+ * Purpose: Performs division using bigDecimal to maintain precision
+ *
+ * @param num1 - Dividend (number being divided)
+ * @param num2 - Divisor (number dividing by)
+ * @param precision - Number of decimal places in result
+ * @returns Division result as decimal string
+ *
+ * Key Features:
+ * - Zero division protection with console warnings
+ * - Direct bigDecimal operations (no Number conversion)
+ * - Configurable precision
+ * - Returns '0' for invalid operations
+ *
+ * Examples:
+ * divide("10", "3", 4) → "3.3333"
+ * divide(1e-8, 2, 10) → "0.000000005"
+ *
+ * Scientific Notation Prevention:
+ * - Uses safeNumber() conversion before bigDecimal operations
+ * - No intermediate Number() conversions
+ * - BigDecimal maintains precision throughout calculation
+ */
+var _divide = function divide(num1, num2, precision) {
+  if (precision === void 0) {
+    precision = 10;
+  }
+  // Convert inputs to safe decimal strings
+  var safeNum1 = safeNumber(num1);
+  var safeNum2 = safeNumber(num2);
+  // Check for division by zero in first operand
+  if (safeNum1 === '0') {
+    console.log('can not divide by zero! - (arguments[0])');
+    return '0';
+  }
+  // Check for division by zero in second operand
+  if (safeNum2 === '0') {
+    console.log('can not divide by zero! - (arguments[1])');
+    return '0';
+  }
+  // Perform division using bigDecimal for precision
+  return bigDecimal.divide(safeNum1, safeNum2, precision);
 };
+// ============================================================================
+// ROUNDING FUNCTIONS - SCIENTIFIC NOTATION SAFE
+// ============================================================================
+/**
+ * ENHANCED ROUND UP FUNCTION
+ *
+ * Purpose: Rounds number up to specified decimal places using bigDecimal
+ *
+ * @param val - Number to round up
+ * @param dec - Number of decimal places
+ * @returns Rounded up value as formatted string
+ *
+ * Key Features:
+ * - Uses bigDecimal for all intermediate calculations
+ * - Handles zero decimal places (integer rounding)
+ * - Creates multipliers as strings to avoid precision loss
+ * - Formats output to remove unnecessary trailing zeros
+ *
+ * Algorithm:
+ * 1. Convert input to safe decimal string
+ * 2. For integer rounding, use bigDecimal.ceil directly
+ * 3. For decimal rounding, multiply by 10^dec, ceil, then divide back
+ * 4. Format result with proper decimal places
+ *
+ * Examples:
+ * enhancedRoundUp(3.14159, 2) → "3.15"
+ * enhancedRoundUp(1.1, 0) → "2"
+ * enhancedRoundUp(1e-8, 8) → "0.00000001"
+ *
+ * Scientific Notation Prevention:
+ * - No Number() conversions in calculations
+ * - String-based multiplier creation
+ * - BigDecimal operations maintain precision
+ */
+var enhancedRoundUp = function enhancedRoundUp(val, dec) {
+  // Convert input to safe decimal string
+  var valStr = safeNumber(val);
+  // Handle integer rounding (no decimal places)
+  if (dec === 0) {
+    return bigDecimal.ceil(valStr).toString();
+  }
+  // Create multiplier as string: "1000" for dec=3, "100" for dec=2, etc.
+  var multiplier = '1' + '0'.repeat(dec);
+  // Multiply by power of 10 to shift decimal places
+  var multiplied = bigDecimal.multiply(valStr, multiplier);
+  // Apply ceiling function to get round-up behavior
+  var ceiled = bigDecimal.ceil(multiplied);
+  // Divide back to restore original decimal places
+  var result = bigDecimal.divide(ceiled, multiplier, dec);
+  // Format with fixed decimal places and remove trailing zeros
+  var formatted = parseFloat(result).toFixed(dec);
+  return formatted.replace(/^([\d,]+)$|^([\d,]+)\.0*$|^([\d,]+\.[0-9]*?)0*$/, '$1$2$3');
+};
+/**
+ * ENHANCED ROUND DOWN FUNCTION
+ *
+ * Purpose: Rounds number down to specified decimal places using bigDecimal
+ *
+ * @param val - Number to round down
+ * @param dec - Number of decimal places
+ * @returns Rounded down value as formatted string
+ *
+ * Key Features:
+ * - Identical to enhancedRoundUp but uses floor instead of ceil
+ * - Same precision-safe algorithm and string-based operations
+ *
+ * Algorithm:
+ * 1. Convert input to safe decimal string
+ * 2. For integer rounding, use bigDecimal.floor directly
+ * 3. For decimal rounding, multiply by 10^dec, floor, then divide back
+ * 4. Format result with proper decimal places
+ *
+ * Examples:
+ * enhancedRoundDown(3.14159, 2) → "3.14"
+ * enhancedRoundDown(1.9, 0) → "1"
+ * enhancedRoundDown(1e-8, 8) → "0.00000001"
+ */
+var enhancedRoundDown = function enhancedRoundDown(val, dec) {
+  // Convert input to safe decimal string
+  var valStr = safeNumber(val);
+  // Handle integer rounding (no decimal places)
+  if (dec === 0) {
+    return bigDecimal.floor(valStr).toString();
+  }
+  // Create multiplier as string: "1000" for dec=3, "100" for dec=2, etc.
+  var multiplier = '1' + '0'.repeat(dec);
+  // Multiply by power of 10 to shift decimal places
+  var multiplied = bigDecimal.multiply(valStr, multiplier);
+  // Apply floor function to get round-down behavior
+  var floored = bigDecimal.floor(multiplied);
+  // Divide back to restore original decimal places
+  var result = bigDecimal.divide(floored, multiplier, dec);
+  // Format with fixed decimal places and remove trailing zeros
+  var formatted = parseFloat(result).toFixed(dec);
+  return formatted.replace(/^([\d,]+)$|^([\d,]+)\.0*$|^([\d,]+\.[0-9]*?)0*$/, '$1$2$3');
+};
+/**
+ * BACKWARD COMPATIBLE ROUND UP
+ *
+ * Purpose: Wrapper function maintaining original API while using enhanced implementation
+ */
 var _roundUp = function roundUp(val, dec) {
-  var decimal = dec === 0 ? 0 : +("1" + new Array(dec + 1).join('0'));
-  var result = decimal === 0 ? Math.ceil(val) : Math.ceil(+bigDecimal.multiply(val, decimal)) / decimal;
-  return result ? result.toFixed(dec).replace(/^([\d,]+)$|^([\d,]+)\.0*$|^([\d,]+\.[0-9]*?)0*$/, '$1$2$3') : '0';
+  return enhancedRoundUp(val, dec);
 };
+/**
+ * BACKWARD COMPATIBLE ROUND DOWN
+ *
+ * Purpose: Wrapper function maintaining original API while using enhanced implementation
+ */
 var _roundDown = function roundDown(val, dec) {
-  var decimal = dec === 0 ? 0 : +("1" + new Array(dec + 1).join('0'));
-  var result = decimal === 0 ? Math.floor(val) : Math.floor(+bigDecimal.multiply(val, decimal)) / decimal;
-  return result ? result.toFixed(dec).replace(/^([\d,]+)$|^([\d,]+)\.0*$|^([\d,]+\.[0-9]*?)0*$/, '$1$2$3') : '0';
+  return enhancedRoundDown(val, dec);
 };
+// ============================================================================
+// VALIDATION & CONVERSION FUNCTIONS
+// ============================================================================
+/**
+ * PERSIAN TO ENGLISH NUMERAL CONVERTER
+ *
+ * Purpose: Converts Persian/Farsi numerals to English numerals
+ *
+ * @param num - Input string containing Persian numerals
+ * @returns String with English numerals
+ *
+ * Key Features:
+ * - Handles all Persian numeral characters (۰-۹)
+ * - Converts Persian decimal separator (٫) to period (.)
+ * - Uses regex replacement for efficient conversion
+ * - Pure string manipulation, no scientific notation risk
+ *
+ * Examples:
+ * toEn("۱۲۳۴") → "1234"
+ * toEn("۱۲٫۳۴") → "12.34"
+ *
+ * Algorithm:
+ * 1. Create mapping arrays for Persian to English characters
+ * 2. Iterate through each character mapping
+ * 3. Use regex to replace all instances globally
+ * 4. Return converted string
+ */
+var _toEn = function toEn(num) {
+  // Characters to find (Persian numerals + Persian decimal separator)
+  var find = [].concat(persianNumber, ['٫']);
+  // Replacement characters (English numerals + period)
+  var replace = [].concat(englishNumber, ['.']);
+  var replaceString = num;
+  var regex;
+  // Replace each Persian character with its English equivalent
+  for (var i = 0; i < find.length; i++) {
+    regex = new RegExp(find[i], 'g'); // Global replacement
+    replaceString = replaceString.replace(regex, replace[i]);
+  }
+  return replaceString;
+};
+/**
+ * INPUT CHARACTER VALIDATOR
+ *
+ * Purpose: Validates if input contains only allowed numeric characters
+ *
+ * @param num - Input to validate (number or string)
+ * @returns Boolean indicating if input is valid
+ *
+ * Key Features:
+ * - Allows Persian numerals, English numerals, periods, and commas
+ * - Handles both number and string inputs
+ * - Checks only the last character for incremental validation
+ * - Returns true for empty strings (allows clearing input)
+ *
+ * Use Cases:
+ * - Real-time input validation in forms
+ * - Preventing invalid character entry
+ * - Supporting multiple numeral systems
+ *
+ * Examples:
+ * isValid("123") → true
+ * isValid("۱۲۳") → true
+ * isValid("12.34") → true
+ * isValid("12abc") → false
+ */
+var _isValid = function isValid(num) {
+  // Convert number to string if needed
+  var numbers = typeof num === 'number' ? num.toString() : num;
+  // Allow empty input (user clearing the field)
+  if (numbers.length === 0) return true;
+  // Define all allowed characters
+  var allowCharachter = [].concat(persianNumber, englishNumber, charachter);
+  // Check if the last character is allowed (for incremental validation)
+  if (_includes(allowCharachter, numbers.slice(-1))) {
+    return true;
+  }
+  return false;
+};
+/**
+ * DECIMAL PLACES VALIDATOR
+ *
+ * Purpose: Validates if decimal places don't exceed specified limit
+ *
+ * @param val - Input string to validate
+ * @param dec - Maximum allowed decimal places
+ * @returns Boolean indicating if decimal places are within limit
+ *
+ * Key Features:
+ * - Handles strings without decimal points (always valid)
+ * - Counts decimal places after the decimal point
+ * - Used for form validation and precision control
+ *
+ * Examples:
+ * isDecimalValid("12.34", 2) → true
+ * isDecimalValid("12.345", 2) → false
+ * isDecimalValid("12", 2) → true
+ *
+ * Algorithm:
+ * 1. Convert input to string
+ * 2. Check if decimal point exists
+ * 3. If exists, count characters after decimal point
+ * 4. Compare against maximum allowed
+ */
 var _isDecimalValid = function isDecimalValid(val, dec) {
   var stringVal = val.toString();
-  return stringVal.indexOf('.') >= 0 ? !(stringVal.split('.')[1].length > dec) : true;
+  // If no decimal point, any number of allowed decimals is valid
+  return stringVal.indexOf('.') >= 0 ? !(stringVal.split('.')[1].length > dec) // Check decimal places
+  : true; // No decimal point = valid
+};
+// ============================================================================
+// ENHANCED MATHEMATICAL OPERATIONS SUITE
+// ============================================================================
+/**
+ * SAFE MATHEMATICAL OPERATIONS OBJECT
+ *
+ * Purpose: Provides a complete suite of mathematical operations using bigDecimal
+ *
+ * Key Features:
+ * - All operations use safeNumber() conversion
+ * - Returns string results to prevent scientific notation
+ * - Consistent API across all operations
+ * - High precision calculations
+ *
+ * Available Operations:
+ * - add: Addition with precision
+ * - subtract: Subtraction with precision
+ * - multiply: Multiplication with precision
+ * - divide: Division with configurable precision
+ *
+ * Usage:
+ * safeMath.add(1e-8, 2e-8) → "0.00000003"
+ * safeMath.multiply("1.5", "2.3") → "3.45"
+ */
+var safeMath = {
+  /**
+   * SAFE ADDITION
+   * @param num1 - First addend
+   * @param num2 - Second addend
+   * @returns Sum as decimal string
+   */
+  add: function add(num1, num2) {
+    return bigDecimal.add(safeNumber(num1), safeNumber(num2));
+  },
+  /**
+   * SAFE SUBTRACTION
+   * @param num1 - Minuend (number to subtract from)
+   * @param num2 - Subtrahend (number to subtract)
+   * @returns Difference as decimal string
+   */
+  subtract: function subtract(num1, num2) {
+    return bigDecimal.subtract(safeNumber(num1), safeNumber(num2));
+  },
+  /**
+   * SAFE MULTIPLICATION
+   * @param num1 - First factor
+   * @param num2 - Second factor
+   * @returns Product as decimal string
+   */
+  multiply: function multiply(num1, num2) {
+    return bigDecimal.multiply(safeNumber(num1), safeNumber(num2));
+  },
+  /**
+   * SAFE DIVISION
+   * @param num1 - Dividend
+   * @param num2 - Divisor
+   * @param precision - Decimal places in result (default: 10)
+   * @returns Quotient as decimal string
+   */
+  divide: function divide(num1, num2, precision) {
+    if (precision === void 0) {
+      precision = 10;
+    }
+    return _divide(num1, num2, precision);
+  }
 };
+// ============================================================================
+// MAIN EXPORT OBJECT - COMPLETE API
+// ============================================================================
+/**
+ * COMPREHENSIVE NUMBER UTILITIES EXPORT
+ *
+ * This object provides the complete API for all number operations, formatting,
+ * validation, and mathematical calculations. All functions are designed to
+ * prevent scientific notation and maintain high precision.
+ *
+ * Categories:
+ * 1. Formatting: delimiter, removeDelimiter, suffix
+ * 2. Rounding: roundUp, roundDown
+ * 3. Validation: isValid, isDecimalValid
+ * 4. Conversion: toEn, convertScientific, safeNumber
+ * 5. Mathematics: All bigDecimal operations + safeMath suite
+ * 6. Utilities: Direct access to bigDecimal library
+ */
 var numberUtils = {
+  // ============================================================================
+  // FORMATTING & DISPLAY FUNCTIONS
+  // ============================================================================
+  /**
+   * Add thousand separators to numbers
+   * Usage: delimiter(1234567) → "1,234,567"
+   */
   delimiter: function delimiter(num, separator, separateBy) {
     return _delimiter(num, separator, separateBy);
   },
+  /**
+   * Remove thousand separators from formatted strings
+   * Usage: removeDelimiter("1,234,567") → "1234567"
+   */
   removeDelimiter: function removeDelimiter(num, separator) {
     if (separator === void 0) {
       separator = ',';
     }
     return _removeDelimiter(num, separator);
   },
+  /**
+   * Format large numbers with K/M/B/T suffixes
+   * Usage: suffix(1000000) → "1M"
+   */
+  suffix: suffix,
+  // ============================================================================
+  // ROUNDING FUNCTIONS
+  // ============================================================================
+  /**
+   * Round number down to specified decimal places
+   * Usage: roundDown(3.14159, 2) → "3.14"
+   */
   roundDown: function roundDown(val, dec) {
     return _roundDown(val, dec);
   },
+  /**
+   * Round number up to specified decimal places
+   * Usage: roundUp(3.14159, 2) → "3.15"
+   */
   roundUp: function roundUp(val, dec) {
     return _roundUp(val, dec);
   },
+  // ============================================================================
+  // VALIDATION FUNCTIONS
+  // ============================================================================
+  /**
+   * Validate if decimal places are within specified limit
+   * Usage: isDecimalValid("12.34", 2) → true
+   */
   isDecimalValid: function isDecimalValid(val, dec) {
     return _isDecimalValid(val, dec);
   },
+  /**
+   * Validate if input contains only valid numeric characters
+   * Usage: isValid("123.45") → true
+   */
   isValid: function isValid(val) {
     return _isValid(val);
   },
+  // ============================================================================
+  // CONVERSION & UTILITY FUNCTIONS
+  // ============================================================================
+  /**
+   * Convert Persian numerals to English numerals
+   * Usage: toEn("۱۲۳") → "123"
+   */
   toEn: function toEn(val) {
     return _toEn(val);
   },
-  suffix: suffix,
+  /**
+   * Convert scientific notation to decimal string
+   * Usage: convertScientific(1e-8) → "0.00000001"
+   */
+  convertScientific: convertScientific,
+  /**
+   * Safe number conversion with fallback to "0"
+   * Usage: safeNumber(1e-8) → "0.00000001"
+   */
+  safeNumber: safeNumber,
+  // ============================================================================
+  // ENHANCED MATHEMATICAL OPERATIONS
+  // ============================================================================
+  /**
+   * Complete suite of safe mathematical operations
+   * All operations prevent scientific notation and maintain precision
+   */
+  safeMath: safeMath,
+  /**
+   * Direct access to bigDecimal library for advanced operations
+   */
   bigDecimal: bigDecimal,
-  modulus: bigDecimal.modulus,
-  divide: divide,
-  multiply: bigDecimal.multiply,
-  subtract: bigDecimal.subtract,
-  add: bigDecimal.add,
-  negate: bigDecimal.negate,
-  compareTo: bigDecimal.compareTo,
-  ceil: bigDecimal.ceil,
-  floor: bigDecimal.floor,
-  abs: bigDecimal.abs,
-  round: bigDecimal.round,
-  getPrettyValue: bigDecimal.getPrettyValue
+  // ============================================================================
+  // INDIVIDUAL MATHEMATICAL OPERATIONS (Enhanced with safeNumber)
+  // ============================================================================
+  /**
+   * Modulus operation with precision
+   * Usage: modulus(10, 3) → remainder as string
+   */
+  modulus: function modulus(num1, num2) {
+    return bigDecimal.modulus(safeNumber(num1), safeNumber(num2));
+  },
+  /**
+   * Division with configurable precision
+   * Usage: divide(10, 3, 4) → "3.3333"
+   */
+  divide: _divide,
+  /**
+   * Multiplication with precision
+   * Usage: multiply(1.5, 2.3) → "3.45"
+   */
+  multiply: function multiply(num1, num2) {
+    return bigDecimal.multiply(safeNumber(num1), safeNumber(num2));
+  },
+  /**
+   * Subtraction with precision
+   * Usage: subtract(10, 3.5) → "6.5"
+   */
+  subtract: function subtract(num1, num2) {
+    return bigDecimal.subtract(safeNumber(num1), safeNumber(num2));
+  },
+  /**
+   * Addition with precision
+   * Usage: add(1.1, 2.2) → "3.3"
+   */
+  add: function add(num1, num2) {
+    return bigDecimal.add(safeNumber(num1), safeNumber(num2));
+  },
+  /**
+   * Number negation
+   * Usage: negate(5) → "-5"
+   */
+  negate: function negate(num) {
+    return bigDecimal.negate(safeNumber(num));
+  },
+  /**
+   * Number comparison (-1: less, 0: equal, 1: greater)
+   * Usage: compareTo(5, 3) → 1
+   */
+  compareTo: function compareTo(num1, num2) {
+    return bigDecimal.compareTo(safeNumber(num1), safeNumber(num2));
+  },
+  /**
+   * Ceiling function (round up to nearest integer)
+   * Usage: ceil(3.14) → "4"
+   */
+  ceil: function ceil(num) {
+    return bigDecimal.ceil(safeNumber(num));
+  },
+  /**
+   * Floor function (round down to nearest integer)
+   * Usage: floor(3.14) → "3"
+   */
+  floor: function floor(num) {
+    return bigDecimal.floor(safeNumber(num));
+  },
+  /**
+   * Absolute value
+   * Usage: abs(-5) → "5"
+   */
+  abs: function abs(num) {
+    return bigDecimal.abs(safeNumber(num));
+  },
+  /**
+   * Round to specified precision
+   * Usage: round(3.14159, 2) → "3.14"
+   */
+  round: function round(num, precision) {
+    return bigDecimal.round(safeNumber(num), precision);
+  },
+  /**
+   * Format number with pretty printing (thousands separators)
+   * Usage: getPrettyValue(1234567, 2, ",") → "1,234,567.00"
+   */
+  getPrettyValue: function getPrettyValue(num, precision, separator) {
+    return bigDecimal.getPrettyValue(safeNumber(num), precision, separator);
+  }
 };
 
 var handleSearch = function handleSearch(list, value) {