@heartlandone/vega 2.76.0 → 2.77.0

package/dist/collection/polyfill/libphonenumber/parse-phone-number.js

@@ -0,0 +1,127 @@
+import { PARSE_ERROR_NOT_A_NUMBER, PARSE_ERROR_INVALID_COUNTRY } from './types';
+import { META, getCountryCallingCode, detectCallingCode, getCountryByNationalNumber } from './metadata';
+import { PhoneNumber } from './phone-number';
+// ---------------------------------------------------------------------------
+// parseIncompletePhoneNumber
+// ---------------------------------------------------------------------------
+/**
+ * Strip everything except digits and a leading +.
+ *
+ * Mirrors the behavior of libphonenumber-js/core parseIncompletePhoneNumber.
+ *
+ * @param {string} text - The raw phone number input to sanitize.
+ * @returns {string} The sanitized string containing only digits and an optional leading +.
+ * @example parseIncompletePhoneNumber('(302) 333-4444')    // '3023334444'
+ * @example parseIncompletePhoneNumber('+1 (302) 333-4444') // '+13023334444'
+ */
+export function parseIncompletePhoneNumber(text) {
+  let result = '';
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (char === '+' && result.length === 0) {
+      result += '+';
+    }
+    else if (char >= '0' && char <= '9') {
+      result += char;
+    }
+  }
+  return result;
+}
+// ---------------------------------------------------------------------------
+// parsePhoneNumber
+// ---------------------------------------------------------------------------
+/**
+ * Parse a phone number string into a PhoneNumber instance.
+ *
+ * @param {string} text - The raw phone number string to parse.
+ * @param {VegaCountryCode | ParsePhoneNumberOptions} [optionsOrCountry] - A default country code or parsing options.
+ * @returns {PhoneNumber} The parsed PhoneNumber instance.
+ * @throws {Error} if the input cannot be parsed.
+ */
+export function parsePhoneNumber(text, optionsOrCountry) {
+  var _a;
+  const options = typeof optionsOrCountry === 'string' ? { defaultCountry: optionsOrCountry } : optionsOrCountry !== null && optionsOrCountry !== void 0 ? optionsOrCountry : {};
+  const { defaultCountry, extract = true } = options;
+  const cleaned = parseIncompletePhoneNumber(text);
+  if (!cleaned || cleaned === '+') {
+    throw new Error(PARSE_ERROR_NOT_A_NUMBER);
+  }
+  if (!extract) {
+    const stripped = text.replace(/[\s\-().+]/g, '');
+    if (!/^\d*$/.test(stripped)) {
+      throw new Error(PARSE_ERROR_NOT_A_NUMBER);
+    }
+  }
+  let callingCode = '';
+  let nationalNumber;
+  let country;
+  if (cleaned.startsWith('+')) {
+    const digits = cleaned.substring(1);
+    const detected = detectCallingCode(digits);
+    callingCode = (_a = detected.callingCode) !== null && _a !== void 0 ? _a : '';
+    if (!callingCode) {
+      throw new Error(PARSE_ERROR_INVALID_COUNTRY);
+    }
+    nationalNumber = digits.substring(callingCode.length);
+    // For NANPA (calling code '1'), strip the trunk prefix '1' if present.
+    // E.g. '+113405100000' → nationalNumber '3405100000' so VI can be detected.
+    if (callingCode === '1' && nationalNumber.length === 11 && nationalNumber.startsWith('1')) {
+      nationalNumber = nationalNumber.substring(1);
+    }
+    const possibleCountries = detected.countries;
+    if (possibleCountries && possibleCountries.length === 1) {
+      country = possibleCountries[0];
+    }
+    else if (possibleCountries && possibleCountries.length > 1) {
+      country = getCountryByNationalNumber(possibleCountries, nationalNumber);
+    }
+  }
+  else {
+    if (!defaultCountry) {
+      throw new Error(PARSE_ERROR_INVALID_COUNTRY);
+    }
+    callingCode = getCountryCallingCode(defaultCountry);
+    nationalNumber = cleaned;
+    // For NANPA countries (calling code '1'), the trunk prefix '1' may
+    // need to be stripped. E.g. '13405100000' → '3405100000' so that
+    // VI (leadingDigits 340) can be detected.
+    if (callingCode === '1' && nationalNumber.length === 11 && nationalNumber.startsWith('1')) {
+      nationalNumber = nationalNumber.substring(1);
+    }
+    // For countries sharing a calling code (e.g., NANPA), check if the
+    // national number actually belongs to a different country in the group.
+    const siblings = META.countryCallingCode[callingCode];
+    if (siblings && siblings.length > 1) {
+      const detected = getCountryByNationalNumber(siblings, nationalNumber);
+      country = detected !== null && detected !== void 0 ? detected : defaultCountry;
+    }
+    else {
+      country = defaultCountry;
+    }
+  }
+  // Extract the national number by stripping the national prefix, if applicable.
+  // Mirrors extractNationalNumber from the original library:
+  //  1. Match nationalPrefixForParsing against the beginning of nationalNumber.
+  //  2. If the original number already matches the validation pattern, keep it.
+  //  3. Otherwise, if the stripped version matches the validation pattern, use it.
+  if (country) {
+    const entry = META.countries[country];
+    if (entry) {
+      const prefixPattern = entry[7];
+      if (prefixPattern && typeof prefixPattern === 'string') {
+        const prefixMatch = nationalNumber.match(new RegExp('^(?:' + prefixPattern + ')'));
+        if (prefixMatch && prefixMatch[0].length > 0) {
+          const afterPrefix = nationalNumber.substring(prefixMatch[0].length);
+          const validPattern = entry[2];
+          const validRegex = new RegExp('^(?:' + validPattern + ')$');
+          const originalMatches = validRegex.test(nationalNumber);
+          const strippedMatches = afterPrefix.length > 0 && validRegex.test(afterPrefix);
+          if (!originalMatches && strippedMatches) {
+            nationalNumber = afterPrefix;
+          }
+        }
+      }
+    }
+  }
+  return new PhoneNumber(callingCode, nationalNumber, country);
+}

package/dist/collection/polyfill/libphonenumber/phone-number.js

@@ -0,0 +1,38 @@
+import { META } from './metadata';
+/**
+ * Represents a parsed phone number.
+ */
+export class PhoneNumber {
+  /**
+   * Creates a new PhoneNumber instance.
+   *
+   * @param {string} countryCallingCode - The country calling code for the phone number.
+   * @param {string} nationalNumber - The national portion of the phone number.
+   * @param {VegaCountryCode} country - The optional country code associated with the number.
+   */
+  constructor(countryCallingCode, nationalNumber, country) {
+    this.countryCallingCode = countryCallingCode;
+    this.nationalNumber = nationalNumber;
+    this.country = country;
+  }
+  /**
+   * Returns true if the national number matches the country's validation
+   * pattern and its length is among the expected possible lengths.
+   *
+   * @returns {boolean} Whether the phone number is valid.
+   */
+  isValid() {
+    if (!this.country)
+      return false;
+    const entry = META.countries[this.country];
+    if (!entry)
+      return false;
+    const validationPattern = entry[2];
+    const possibleLengths = entry[3];
+    if (!possibleLengths.includes(this.nationalNumber.length)) {
+      return false;
+    }
+    const regex = new RegExp('^(?:' + validationPattern + ')$');
+    return regex.test(this.nationalNumber);
+  }
+}

package/dist/collection/polyfill/libphonenumber/test/as-you-type.test.js

@@ -0,0 +1,309 @@
+import { AsYouType, formatIncompletePhoneNumber } from '../as-you-type';
+function internal(formatter) {
+  return formatter;
+}
+// ---------------------------------------------------------------------------
+// formatIncompletePhoneNumber
+// ---------------------------------------------------------------------------
+describe('formatIncompletePhoneNumber', () => {
+  it('should format a US number with country', () => {
+    expect(formatIncompletePhoneNumber('3023334444', 'US')).toBe('(302) 333-4444');
+  });
+  it('should format an international number without country', () => {
+    const result = formatIncompletePhoneNumber('+13023334444');
+    expect(result).toBe('+1 302 333 4444');
+  });
+  it('should return empty string for empty input', () => {
+    expect(formatIncompletePhoneNumber('')).toBe('');
+  });
+  it('should handle partial US number', () => {
+    expect(formatIncompletePhoneNumber('302333', 'US')).toBe('(302) 333');
+  });
+  it('should format a GB number', () => {
+    const result = formatIncompletePhoneNumber('7911123456', 'GB');
+    expect(result).toBeDefined();
+    expect(result.length).toBeGreaterThan(0);
+  });
+});
+// ---------------------------------------------------------------------------
+// AsYouType — basic usage
+// ---------------------------------------------------------------------------
+describe('AsYouType', () => {
+  describe('constructor', () => {
+    it('should accept a default country', () => {
+      const formatter = new AsYouType('US');
+      expect(formatter.country).toBe('US');
+    });
+    it('should work without a default country', () => {
+      const formatter = new AsYouType();
+      expect(formatter.country).toBeUndefined();
+    });
+  });
+  // -----------------------------------------------------------------------
+  // input() — US national mode
+  // -----------------------------------------------------------------------
+  describe('input (US national)', () => {
+    it('should progressively format a US number', () => {
+      const formatter = new AsYouType('US');
+      expect(formatter.input('3')).toBeDefined();
+      expect(formatter.input('0')).toBeDefined();
+      expect(formatter.input('2')).toBeDefined();
+      // After 6 more digits we should get full format
+      const result = formatter.input('3334444');
+      expect(result).toBe('(302) 333-4444');
+    });
+    it('should format a complete US number in one call', () => {
+      const formatter = new AsYouType('US');
+      expect(formatter.input('3023334444')).toBe('(302) 333-4444');
+    });
+    it('should handle digit-by-digit input', () => {
+      const formatter = new AsYouType('US');
+      let result = '';
+      for (const char of '3023334444') {
+        result = formatter.input(char);
+      }
+      expect(result).toBe('(302) 333-4444');
+    });
+  });
+  // -----------------------------------------------------------------------
+  // input() — international mode
+  // -----------------------------------------------------------------------
+  describe('input (international)', () => {
+    it('should format an international US number', () => {
+      const formatter = new AsYouType();
+      const result = formatter.input('+13023334444');
+      expect(result).toBe('+1 302 333 4444');
+    });
+    it('should detect calling code when +1 is entered', () => {
+      const formatter = new AsYouType();
+      formatter.input('+1302');
+      // NANPA has many countries; callingCode should be detected even if country is not
+      expect(internal(formatter)._callingCode).toBe('1');
+    });
+    it('should format an international GB number', () => {
+      const formatter = new AsYouType();
+      const result = formatter.input('+447911123456');
+      expect(result).toBeDefined();
+      expect(result).toContain('+44');
+    });
+    it('should return "+" when only + is entered', () => {
+      const formatter = new AsYouType();
+      expect(formatter.input('+')).toBe('+');
+    });
+    it('should format digits after calling code', () => {
+      const formatter = new AsYouType();
+      formatter.input('+1');
+      const result = formatter.input('3023334444');
+      expect(result).toBe('+1 302 333 4444');
+    });
+  });
+  // -----------------------------------------------------------------------
+  // input() — various countries
+  // -----------------------------------------------------------------------
+  describe('input (various countries)', () => {
+    it('should format a CN number nationally', () => {
+      const formatter = new AsYouType('CN');
+      const result = formatter.input('13812345678');
+      expect(result).toBeDefined();
+      expect(result.length).toBeGreaterThan(0);
+    });
+    it('should format a CN 10-digit number with 3-3-4 grouping', () => {
+      // Regression test: leading digits pattern 8(?:[1-358]|9[1-7]) must not
+      // eliminate the 3-3-4 format before MIN_LEADING_DIGITS_LENGTH digits
+      const formatter = new AsYouType('CN');
+      let result = '';
+      for (const char of '8934324345') {
+        result = formatter.input(char);
+      }
+      expect(result).toBe('893 432 4345');
+    });
+    it('should format a DE number nationally', () => {
+      const formatter = new AsYouType('DE');
+      const result = formatter.input('3012345678');
+      expect(result).toBeDefined();
+    });
+    it('should format an AU number', () => {
+      const formatter = new AsYouType('AU');
+      const result = formatter.input('0412345678');
+      expect(result).toBeDefined();
+    });
+  });
+  // -----------------------------------------------------------------------
+  // input() — non-digit characters
+  // -----------------------------------------------------------------------
+  describe('input (non-digit handling)', () => {
+    it('should ignore non-digit characters except leading +', () => {
+      const formatter = new AsYouType('US');
+      const result = formatter.input('(302) 333-4444');
+      expect(result).toBe('(302) 333-4444');
+    });
+    it('should ignore letters', () => {
+      const formatter = new AsYouType('US');
+      const result = formatter.input('3a0b2c3d3e3f4g4h4i4j');
+      expect(result).toBe('(302) 333-4444');
+    });
+  });
+  // -----------------------------------------------------------------------
+  // country getter
+  // -----------------------------------------------------------------------
+  describe('country', () => {
+    it('should return default country initially', () => {
+      const formatter = new AsYouType('GB');
+      expect(formatter.country).toBe('GB');
+    });
+    it('should detect country from international input', () => {
+      const formatter = new AsYouType();
+      formatter.input('+49');
+      expect(formatter.country).toBe('DE');
+    });
+    it('should detect NANPA country by leading digits', () => {
+      const formatter = new AsYouType();
+      formatter.input('+13405100000');
+      expect(formatter.country).toBe('VI');
+    });
+  });
+  // -----------------------------------------------------------------------
+  // Line-level coverage — each test targets a specific uncovered line
+  // -----------------------------------------------------------------------
+  describe('non-digit characters are skipped in input loop', () => {
+    it('should skip non-digit non-plus characters via continue', () => {
+      const formatter = new AsYouType('US');
+      // Characters '-' and ' ' are < '0' or > '9', hitting the continue.
+      // The result should only format the extracted digits, ignoring separators.
+      const result = formatter.input('3-0-2');
+      expect(result).toBeDefined();
+      // US formatting applies parentheses around the area code
+      expect(result).toBe('(302)');
+    });
+  });
+  describe('returns "+" when plus was entered but no digits follow', () => {
+    it('should return "+" when subsequent input has only non-digit chars', () => {
+      const formatter = new AsYouType();
+      expect(formatter.input('+')).toBe('+');
+      // Second call with only non-digit text: no digits added so result is still ''.
+      // Falls into if (!result) → _hasPlus is true, _allDigits.length === 0 → return '+'
+      // eslint-disable-next-line spellcheck/spell-checker
+      expect(formatter.input('abc')).toBe('+');
+    });
+  });
+  describe('re-initializes formats and resets when calling code changes for multi-country group', () => {
+    it('should re-init formats when calling code changes for a multi-country group', () => {
+      // Need: prevCallingCode !== detected.callingCode AND detected.countries.length > 1.
+      // Feed '+' then '4' (no calling code detected yet, prevCallingCode = undefined),
+      // then '4' → calling code '44' with multiple countries (GB, GG, JE, IM).
+      // undefined !== '44' → enters the if-block → initFormats + resetFormat (lines 177-178).
+      const formatter = new AsYouType();
+      formatter.input('+');
+      formatter.input('4');
+      const result = formatter.input('4');
+      expect(result).toBeDefined();
+      const final = formatter.input('7911123456');
+      expect(final).toContain('+44');
+    });
+  });
+  describe('chooseFormatAndApply breaks when re-encountering already chosen format', () => {
+    it('should break and reset when the chosen format is at the front of matching formats', () => {
+      const formatter = new AsYouType('US');
+      formatter.input('302');
+      // Set _chosenFormat to the first element in _matchingFormats so the
+      // for-loop immediately hits the break branch.
+      const matchingFormats = internal(formatter)._matchingFormats;
+      if (matchingFormats.length > 0) {
+        internal(formatter)._chosenFormat = matchingFormats[0];
+      }
+      const result = internal(formatter).chooseFormatAndApply();
+      // After the break the method calls resetFormat() and returns undefined
+      expect(result).toBeUndefined();
+    });
+  });
+  describe('chooseFormatAndApply skips altering format rules', () => {
+    it('should continue past formats whose replacement inserts extra characters', () => {
+      const formatter = new AsYouType('US');
+      formatter.input('302');
+      // Inject an altering format (replacement starts with '0') at the front
+      // of _matchingFormats so the continue branch is taken before reaching
+      // the real non-altering formats.
+      const alteringFormat = ['(\\d{3})(\\d{3})(\\d{4})', '0$1 $2-$3', ['[2-9]']];
+      internal(formatter)._matchingFormats.unshift(alteringFormat);
+      internal(formatter)._chosenFormat = undefined;
+      const result = internal(formatter).chooseFormatAndApply();
+      // The altering format is skipped, a real format is chosen instead
+      expect(result).toBeDefined();
+    });
+  });
+  describe('formatNextDigits returns undefined when no template exists', () => {
+    it('should return undefined from formatNextDigits when _populatedTemplate is falsy', () => {
+      const formatter = new AsYouType('US');
+      // Call the private method directly with no template set
+      const result = internal(formatter).formatNextDigits('5');
+      expect(result).toBeUndefined();
+    });
+  });
+  describe('populateTemplateFull returns undefined when template runs out of placeholders', () => {
+    it('should return undefined when digits exceed template placeholders', () => {
+      const formatter = new AsYouType('US');
+      // Call populateTemplateFull directly with more digits than placeholders
+      // Template has 7 placeholders; feed 10 digits to overflow them
+      const result = internal(formatter).populateTemplateFull(
+      // eslint-disable-next-line spellcheck/spell-checker
+      'xxx-xxxx', '1234567890');
+      expect(result).toBeUndefined();
+    });
+  });
+  describe('tryReExtractNationalPrefix returns early when metadata entry is falsy', () => {
+    it('should return early when country metadata entry does not exist', () => {
+      const formatter = new AsYouType('US');
+      // Set _country to a fake value so META.countries[_country] is undefined
+      internal(formatter)._country = 'ZZ';
+      // tryReExtractNationalPrefix should bail out at line 420: if (!entry) return
+      internal(formatter).tryReExtractNationalPrefix();
+      // No error thrown, method returned gracefully — _complexPrefix remains its initial value
+      expect(internal(formatter)._complexPrefix).toBe('');
+    });
+  });
+  describe('getFullOutput returns "+callingCode" when formattedNational is empty', () => {
+    it('should return just "+callingCode" via getFullOutput when formattedNational is falsy', () => {
+      const formatter = new AsYouType();
+      formatter.input('+1302');
+      // Call getFullOutput directly with empty string
+      const output = internal(formatter).getFullOutput('');
+      expect(output).toBe('+1');
+    });
+    it('should return "+callingCode" when entering only + and calling code digits', () => {
+      const formatter = new AsYouType();
+      const result = formatter.input('+1');
+      expect(result).toBe('+1');
+    });
+  });
+  describe('getNonFormattedOutput returns complexPrefix concatenated with nationalNumber', () => {
+    it('should return complexPrefix + nationalNumber when no format matches', () => {
+      const formatter = new AsYouType('CN');
+      // CN prefix pattern: (1(?:[12]\d|79)\d\d)|0
+      // '0' matches the '0' alternative. After prefix extraction, _complexPrefix = '0'
+      // and _nationalNumber = remaining digits.
+      // Feed enough digits to exhaust all format templates so getNonFormattedOutput is used.
+      const result = formatter.input('099999999999999999');
+      expect(result).toContain('0');
+      expect(result.length).toBeGreaterThan(1);
+    });
+    it('should include complexPrefix in output via direct method call', () => {
+      const formatter = new AsYouType('CN');
+      // Set internal state directly
+      internal(formatter)._complexPrefix = '0';
+      internal(formatter)._nationalNumber = '12345';
+      internal(formatter)._hasPlus = false;
+      const output = internal(formatter).getNonFormattedOutput();
+      expect(output).toBe('0 12345');
+    });
+  });
+  // -----------------------------------------------------------------------
+  // CN national prefix re-extraction
+  // -----------------------------------------------------------------------
+  describe('CN national prefix re-extraction', () => {
+    it('should handle CN digits with national prefix extraction', () => {
+      const formatter = new AsYouType('CN');
+      const result = formatter.input('123456789');
+      expect(result).toBeDefined();
+    });
+  });
+});

package/dist/collection/polyfill/libphonenumber/test/format-helpers.test.js

@@ -0,0 +1,192 @@
+/* eslint-disable spellcheck/spell-checker */
+import { isNonAlteringFormat, formatSuits, formatMatchesLeadingDigits, buildTemplate, cutAndStripNonPairedParens, applyInternationalSeparatorStyle, } from '../format-helpers';
+// ---------------------------------------------------------------------------
+// isNonAlteringFormat
+// ---------------------------------------------------------------------------
+describe('isNonAlteringFormat', () => {
+  it('should return true for standard group-only replacements', () => {
+    expect(isNonAlteringFormat('$1-$2-$3')).toBe(true);
+    expect(isNonAlteringFormat('($1) $2-$3')).toBe(true);
+    expect(isNonAlteringFormat('$1 $2 $3')).toBe(true);
+    expect(isNonAlteringFormat('$1.$2.$3')).toBe(true);
+  });
+  it('should return true for single group replacements', () => {
+    expect(isNonAlteringFormat('$1')).toBe(true);
+    expect(isNonAlteringFormat('($1)')).toBe(true);
+  });
+  it('should return false for replacements that insert extra characters', () => {
+    expect(isNonAlteringFormat('0$1 $2')).toBe(false);
+    expect(isNonAlteringFormat('8 $1')).toBe(false);
+  });
+  it('should return false for empty string', () => {
+    expect(isNonAlteringFormat('')).toBe(false);
+  });
+});
+// ---------------------------------------------------------------------------
+// formatSuits
+// ---------------------------------------------------------------------------
+describe('formatSuits', () => {
+  // Format with no nationalPrefixFormattingRule → no national prefix usage
+  const formatNoPrefix = ['(\\d{3})(\\d{4})', '$1-$2', ['[2-9]']];
+  // Format with a real national prefix rule (e.g., '0$1')
+  const formatWithPrefix = ['(\\d{3})(\\d{4})', '$1-$2', ['[2-9]'], '0$1'];
+  // Format with prefix rule but marked optional (index [4] truthy)
+  const formatOptionalPrefix = ['(\\d{3})(\\d{4})', '$1-$2', ['[2-9]'], '0$1', 1];
+  // Format whose rule is just '$1' (doesn't really prepend a prefix)
+  const formatPassthroughRule = ['(\\d{3})(\\d{4})', '$1-$2', ['[2-9]'], '$1'];
+  describe('when national prefix was entered', () => {
+    it('should return true for format with prefix rule', () => {
+      expect(formatSuits(formatWithPrefix, false, true)).toBe(true);
+    });
+    it('should return false for format without any prefix rule and not optional', () => {
+      expect(formatSuits(formatNoPrefix, false, true)).toBe(false);
+    });
+    it('should return true for format with optional prefix', () => {
+      expect(formatSuits(formatOptionalPrefix, false, true)).toBe(true);
+    });
+    it('should return true for passthrough prefix ($1)', () => {
+      // $1 means doesn't actually prepend, so formatUsesNationalPrefix is false,
+      // but it also doesn't have an optional marker → returns false
+      expect(formatSuits(formatPassthroughRule, false, true)).toBe(false);
+    });
+  });
+  describe('when no national prefix and not international', () => {
+    it('should return true for format without prefix', () => {
+      expect(formatSuits(formatNoPrefix, false, false)).toBe(true);
+    });
+    it('should return false for format with mandatory prefix', () => {
+      expect(formatSuits(formatWithPrefix, false, false)).toBe(false);
+    });
+    it('should return true for format with optional prefix', () => {
+      expect(formatSuits(formatOptionalPrefix, false, false)).toBe(true);
+    });
+  });
+  describe('when international mode', () => {
+    it('should return true for any format in international mode', () => {
+      expect(formatSuits(formatNoPrefix, true, false)).toBe(true);
+      expect(formatSuits(formatWithPrefix, true, false)).toBe(true);
+      expect(formatSuits(formatOptionalPrefix, true, false)).toBe(true);
+    });
+  });
+});
+// ---------------------------------------------------------------------------
+// formatMatchesLeadingDigits
+// ---------------------------------------------------------------------------
+describe('formatMatchesLeadingDigits', () => {
+  // Format with leading digits pattern '2[0-9]'
+  const formatRule = ['(\\d{3})(\\d{4})', '$1-$2', ['2[0-9]']];
+  // Format with no leading digits
+  const formatNoLeading = ['(\\d{3})(\\d{4})', '$1-$2', []];
+  it('should return true when no leading digits patterns exist', () => {
+    expect(formatMatchesLeadingDigits(formatNoLeading, '1234567', 0)).toBe(true);
+  });
+  it('should match when national number starts with matching digits', () => {
+    expect(formatMatchesLeadingDigits(formatRule, '2123456', 0)).toBe(true);
+  });
+  it('should not match when leading digits do not match', () => {
+    expect(formatMatchesLeadingDigits(formatRule, '3123456', 0)).toBe(false);
+  });
+  it('should return true for short numbers below MIN_LEADING_DIGITS_LENGTH', () => {
+    // Both '2' and '3' are 1-char inputs (below MIN_LEADING_DIGITS_LENGTH=3),
+    // so all formats are kept regardless of the leading-digits pattern.
+    expect(formatMatchesLeadingDigits(formatRule, '2', 0)).toBe(true);
+    expect(formatMatchesLeadingDigits(formatRule, '3', 0)).toBe(true);
+  });
+  it('should use the correct leading digits pattern based on index', () => {
+    const formatMulti = ['(\\d{3})(\\d{4})', '$1-$2', ['[2-9]', '2[0-3]']];
+    // At index 0, use first pattern '[2-9]' — 3 matches
+    expect(formatMatchesLeadingDigits(formatMulti, '312', 0)).toBe(true);
+    // At index 1, use second pattern '2[0-3]' — 3 doesn't match
+    expect(formatMatchesLeadingDigits(formatMulti, '312', 1)).toBe(false);
+  });
+});
+// ---------------------------------------------------------------------------
+// formatMatchesLeadingDigits — short-number early-return coverage
+// (With fewer than MIN_LEADING_DIGITS_LENGTH digits, all formats are kept.)
+// ---------------------------------------------------------------------------
+describe('formatMatchesLeadingDigits (short-number early return)', () => {
+  it('should return true for any 1-digit input regardless of pattern', () => {
+    const fmt = ['(\\d{3})(\\d{4})', '$1-$2', ['7[2-5]']];
+    expect(formatMatchesLeadingDigits(fmt, '9', 0)).toBe(true);
+    expect(formatMatchesLeadingDigits(fmt, '7', 0)).toBe(true);
+  });
+  it('should return true for any 2-digit input regardless of pattern', () => {
+    const fmt = ['(\\d{3})(\\d{4})', '$1-$2', ['25']];
+    expect(formatMatchesLeadingDigits(fmt, '25', 0)).toBe(true);
+    expect(formatMatchesLeadingDigits(fmt, '39', 0)).toBe(true);
+  });
+  it('should use regex for 3+ digit input', () => {
+    const fmt = ['(\\d{3})(\\d{4})', '$1-$2', ['7[2-5]']];
+    expect(formatMatchesLeadingDigits(fmt, '730', 0)).toBe(true);
+    expect(formatMatchesLeadingDigits(fmt, '910', 0)).toBe(false);
+  });
+});
+// ---------------------------------------------------------------------------
+// buildTemplate
+// ---------------------------------------------------------------------------
+describe('buildTemplate', () => {
+  it('should build a US-style template', () => {
+    // US format: (\\d{3})(\\d{3})(\\d{4}) → ($1) $2-$3
+    const formatRule = ['(\\d{3})(\\d{3})(\\d{4})', '($1) $2-$3', ['[2-9]']];
+    const template = buildTemplate(formatRule, 10);
+    expect(template).toBeDefined();
+    // Template should have placeholders like '(xxx) xxx-xxxx'
+    expect(template).toBe('(xxx) xxx-xxxx');
+  });
+  it('should return undefined when pattern cannot match', () => {
+    const formatRule = ['(impossible)', '$1', []];
+    const template = buildTemplate(formatRule, 5);
+    expect(template).toBeUndefined();
+  });
+  it('should return undefined when national number length exceeds pattern capacity', () => {
+    // Format only handles 7 digits
+    const formatRule = ['(\\d{3})(\\d{4})', '$1-$2', []];
+    const template = buildTemplate(formatRule, 15);
+    // The pattern can only match 7 digits
+    expect(template).toBeUndefined();
+  });
+  it('should use digit placeholder character x', () => {
+    const formatRule = ['(\\d{3})(\\d{4})', '$1-$2', []];
+    const template = buildTemplate(formatRule, 7);
+    expect(template).toBeDefined();
+    expect(template).toBe('xxx-xxxx');
+  });
+});
+// ---------------------------------------------------------------------------
+// cutAndStripNonPairedParens
+// ---------------------------------------------------------------------------
+describe('cutAndStripNonPairedParens', () => {
+  it('should cut the string at the given position', () => {
+    expect(cutAndStripNonPairedParens('(302) 333-xxxx', 9)).toBe('(302) 333');
+  });
+  it('should include closing paren if at cut position', () => {
+    // Position 4 is ')' — cutAndStripNonPairedParens advances past it
+    expect(cutAndStripNonPairedParens('(302) 333-xxxx', 4)).toBe('(302)');
+  });
+  it('should strip unpaired opening parens', () => {
+    expect(cutAndStripNonPairedParens('(302 333', 8)).toBe('302 333');
+  });
+  it('should keep paired parens', () => {
+    expect(cutAndStripNonPairedParens('(302) 333', 9)).toBe('(302) 333');
+  });
+});
+// ---------------------------------------------------------------------------
+// applyInternationalSeparatorStyle
+// ---------------------------------------------------------------------------
+describe('applyInternationalSeparatorStyle', () => {
+  it('should replace parens with nothing and dashes with spaces', () => {
+    expect(applyInternationalSeparatorStyle('(302) 333-4444')).toBe('302 333 4444');
+  });
+  it('should collapse multiple spaces', () => {
+    expect(applyInternationalSeparatorStyle('302  333  4444')).toBe('302 333 4444');
+  });
+  it('should trim leading and trailing whitespace', () => {
+    expect(applyInternationalSeparatorStyle(' 302 333 ')).toBe('302 333');
+  });
+  it('should handle empty string', () => {
+    expect(applyInternationalSeparatorStyle('')).toBe('');
+  });
+  it('should handle string with only parens/dashes', () => {
+    expect(applyInternationalSeparatorStyle('(-)(-)')).toBe('');
+  });
+});