Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
12.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file numberParser.ts
 * @input Text a person typed or pasted, plus the resolved BCP 47 locale
 * @output Exports parseLocaleNumber and formatEditableNumber
 * @position Internal to NumberInput; not part of the public surface
 *
 * People paste numbers out of spreadsheets, and a spreadsheet writes them
 * grouped, signed, and decorated. This reads those back. Everything locale
 * specific — the grouping and decimal separators, the group sizes, the digit
 * script — is derived from Intl and Unicode rather than a table, and text that
 * no reading fits returns null so the field stays visibly invalid instead of
 * committing a guess. Where both readings are well formed the locale's wins,
 * the way utils/dateParser.ts settles an ambiguous date by locale preference.
 * Grouping is well formed only when every group fits the locale's own sizes:
 * the last exactly the primary size, each inner one exactly the secondary, the
 * first no longer than that. So de-DE `1.234` is 1234, while `1.2345` (last
 * group too long) and `1234.567` (too much ahead of it) keep the full stop as
 * a decimal point. Groups of three fit every locale, so a separator repeated
 * with three-digit groups is grouping in all of them and `1,234,567` reads the
 * same everywhere; for a space or apostrophe, which no locale writes as a
 * decimal point, one occurrence is enough, so en-US `1 234` is 1234.
 *
 * That paragraph is executable: numberParser.docblock.test.ts implements it as
 * code, quote by quote, and fails when the parser and the words disagree.
 *
 * Which characters may separate digits at all is the one thing that is NOT
 * read off the input: SEPARATOR_CHARS below is a bounded alphabet, the same
 * shape utils/dateParser.ts uses for its `[-/.]` date separators.
 *
 * Digit-script folding is shared with utils/timeFormat.ts through
 * utils/unicodeDigits.ts.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/NumberInput/NumberInput.tsx
 * - /packages/core/src/NumberInput/numberParser.test.ts
 * - /packages/core/src/NumberInput/numberParser.docblock.test.ts
 */

import type {Locale} from '../i18n';
import {INVISIBLE_CHARS, toAsciiDigits} from '../utils/unicodeDigits';

interface LocaleNumberSymbols {
  group: string;
  decimal: string;
  /** Digits in the rightmost group — 3 nearly everywhere, 3 in en-IN too. */
  primaryGroupSize: number;
  /** Digits in every group left of it — 2 in en-IN's lakh grouping. */
  secondaryGroupSize: number;
}

const symbolsByLocale = new Map<string, LocaleNumberSymbols>();

function getLocaleNumberSymbols(locale: Locale | undefined) {
  const key = locale ?? '';
  let symbols = symbolsByLocale.get(key);
  if (symbols === undefined) {
    let format: Intl.NumberFormat;
    try {
      format = new Intl.NumberFormat(locale);
    } catch {
      format = new Intl.NumberFormat('en');
    }
    const parts = format.formatToParts(12345.6);
    // A probe long enough to expose a second grouping size where one exists.
    const groupSizes = format
      .formatToParts(11111111111)
      .filter(part => part.type === 'integer')
      .map(part => part.value.length);
    const hasGrouping = groupSizes.length > 1;
    symbols = {
      // Normalized so the space-family separators compare equal to the plain
      // space that input text is normalized to.
      group: (parts.find(p => p.type === 'group')?.value ?? ',').normalize(
        'NFKC',
      ),
      decimal: parts.find(p => p.type === 'decimal')?.value ?? '.',
      primaryGroupSize: hasGrouping ? groupSizes[groupSizes.length - 1] : 3,
      secondaryGroupSize: hasGrouping ? groupSizes[groupSizes.length - 2] : 3,
    };
    symbolsByLocale.set(key, symbols);
  }
  return symbols;
}

// Built at runtime rather than written as a literal: see
// utils/unicodeDigits.ts (Babel's property-escape transform).
const CURRENCY = new RegExp('\\p{Sc}', 'u');
// Hyphen last: inside the character class this builds, a leading one would
// open a range.
const MINUS_SIGNS = '\u2212\u2012\u2013-';

/**
 * Every character a locale writes between digits. Sweeping every language ICU
 * resolves, in every region, yields seven: comma, full stop, apostrophe,
 * space (the whole space family folds to it under NFKC), the Arabic decimal
 * and thousands separators, and U+060C — which only nqo writes, and which
 * this alphabet leaves out. U+2019 is here in its place: no locale writes it,
 * but the corpus pins it as the Swiss spelling.
 *
 * The alphabet is bounded on purpose. Read the candidates off the input
 * instead and any repeated character is grouping, so a hyphenated ID commits
 * as a number. It bounds characters and not shapes: a full stop is a real
 * separator, so `192.168.100.200` is four well-formed groups.
 */
const SEPARATOR_CHARS = ",.' \u2019\u066B\u066C";
const NUMBER_BODY = new RegExp(`^[0-9${SEPARATOR_CHARS}]+$`);
/** No grouping and at most one full stop: the format `Number()` reads. */
const MACHINE_NUMBER = /^(?:\d+\.?\d*|\.\d+)$/;

/**
 * Reduce a digits-and-separators string to a plain machine number under one
 * candidate reading, or null when it is not well formed under that reading.
 * `minGroups` is how many grouping separators the reading has to see before it
 * believes the separator is grouping at all.
 */
function readUnder(
  core: string,
  group: string,
  decimal: string,
  primaryGroupSize: number,
  secondaryGroupSize: number,
  minGroups: number,
): string | null {
  let intText = core;
  let fracText: string | null = null;

  if (decimal !== '' && core.includes(decimal)) {
    const at = core.indexOf(decimal);
    if (core.includes(decimal, at + decimal.length)) {
      return null;
    }
    intText = core.slice(0, at);
    fracText = core.slice(at + decimal.length);
    if (!/^\d*$/.test(fracText)) {
      return null;
    }
  }

  let digits: string;
  if (group !== '' && intText.includes(group)) {
    const chunks = intText.split(group);
    if (
      chunks.length - 1 < minGroups ||
      !chunks.every(chunk => /^\d+$/.test(chunk))
    ) {
      return null;
    }
    const first = chunks[0];
    const last = chunks[chunks.length - 1];
    if (last.length !== primaryGroupSize || first.length > secondaryGroupSize) {
      return null;
    }
    for (let i = 1; i < chunks.length - 1; i++) {
      if (chunks[i].length !== secondaryGroupSize) {
        return null;
      }
    }
    digits = chunks.join('');
  } else {
    if (!/^\d*$/.test(intText)) {
      return null;
    }
    digits = intText;
  }

  if (digits === '' && (fracText == null || fracText === '')) {
    return null;
  }
  return fracText == null ? digits : `${digits}.${fracText}`;
}

/**
 * A separator that no locale uses as a decimal point, so one well-formed group
 * of it is already unambiguous. Everything else needs two before grouping
 * beats the decimal-point reading.
 */
function isGroupOnlySeparator(separator: string): boolean {
  return /^[\s'\u2019]$/.test(separator);
}

function toPlainNumber(
  core: string,
  locale: Locale | undefined,
): string | null {
  if (!NUMBER_BODY.test(core)) {
    return null;
  }

  const {group, decimal, primaryGroupSize, secondaryGroupSize} =
    getLocaleNumberSymbols(locale);
  const inLocale = readUnder(
    core,
    group,
    decimal,
    primaryGroupSize,
    secondaryGroupSize,
    1,
  );
  if (inLocale != null) {
    return inLocale;
  }

  // The machine format, which is what the field read before this parser
  // existed. It comes after the locale rather than before it — dateParser.ts
  // can put ISO first because `2026-01-25` has no second reading, while
  // `1.234` in de-DE has one and grouping is the reading a German means. What
  // reaches here is a full stop the locale could NOT read, so it is not
  // well-formed grouping either, and exactly one reading is left.
  if (MACHINE_NUMBER.test(core)) {
    return core;
  }

  // A repeated separator with three digits after each occurrence can only be
  // grouping — a decimal point appears once — so that shape reads the same in
  // every locale, which is what lets a `1,234,234,234` pasted out of a
  // spreadsheet land in a de-DE app.
  const separators = [...new Set(core.replace(/\d/g, ''))];
  if (separators.length === 0 || separators.length > 2) {
    return null;
  }
  for (const candidate of separators) {
    const occurrences = core.split(candidate).length - 1;
    const minGroups = isGroupOnlySeparator(candidate) ? 1 : 2;
    if (occurrences < minGroups) {
      continue;
    }
    const other = separators.find(s => s !== candidate) ?? '';
    if (other !== '' && core.split(other).length - 1 !== 1) {
      continue;
    }
    const read = readUnder(core, candidate, other, 3, 3, minGroups);
    if (read != null) {
      return read;
    }
  }
  return null;
}

/**
 * Read a number out of text the way a person in `locale` writes one: their
 * grouping and decimal separators, their group sizes, their digit script, an
 * optional currency symbol, and the shapes a spreadsheet pastes.
 *
 * Returns null rather than a guess. Grouping is validated, so en-US `1,23` —
 * a comma that is neither a decimal point nor a well-formed group — is not
 * silently read as 123, and neither is a number written for another locale.
 * Only the characters some locale writes between digits count as separators,
 * so `123-456-789` is not a number at all.
 *
 * @example
 * ```
 * parseLocaleNumber('1,234,234,234', 'en-US')  // 1234234234
 * parseLocaleNumber('1,234,234,234', 'de-DE')  // 1234234234
 * parseLocaleNumber('1,5', 'de-DE')            // 1.5
 * parseLocaleNumber('1.5', 'de-DE')            // 1.5
 * parseLocaleNumber('1,5', 'en-US')            // null
 * parseLocaleNumber('123-456-789', 'en-US')    // null
 * ```
 */
export function parseLocaleNumber(
  text: string,
  locale?: Locale,
): number | null {
  const normalized = toAsciiDigits(
    text.normalize('NFKC').replace(INVISIBLE_CHARS, ''),
  );
  if (normalized == null) {
    return null;
  }

  let rest = normalized.trim();
  let sign = 1;

  // Accounting negatives: spreadsheets write -1234 as (1,234).
  const accounting = /^\((.*)\)$/s.exec(rest);
  if (accounting) {
    sign = -1;
    rest = accounting[1].trim();
  }

  rest = stripCurrency(rest);

  // The sign lands on either end — RTL locales trail it, and Intl writes
  // U+2212 where a keyboard writes a hyphen.
  let hasWrittenSign = false;
  const leadingSign = new RegExp(`^([+${MINUS_SIGNS}])\\s*`).exec(rest);
  if (leadingSign) {
    hasWrittenSign = true;
    sign = leadingSign[1] === '+' ? sign : -sign;
    rest = rest.slice(leadingSign[0].length);
  } else {
    const trailingSign = new RegExp(`\\s*([+${MINUS_SIGNS}])$`).exec(rest);
    if (trailingSign) {
      hasWrittenSign = true;
      sign = trailingSign[1] === '+' ? sign : -sign;
      rest = rest.slice(0, rest.length - trailingSign[0].length);
    }
  }

  // The parens already say negative, so a sign inside them contradicts or
  // doubles it: `(-1,234)` is -1234 to one reader and +1234 to another.
  if (accounting && hasWrittenSign) {
    return null;
  }

  rest = stripCurrency(rest);

  let exponent = 0;
  const exponentMatch = /\s*[eE]\s*([+-]?\d+)$/.exec(rest);
  if (exponentMatch) {
    exponent = Number(exponentMatch[1]);
    rest = rest.slice(0, rest.length - exponentMatch[0].length);
  }

  const core = rest.trim();
  if (core === '') {
    return null;
  }

  const plain = toPlainNumber(core, locale);
  if (plain == null) {
    return null;
  }

  const magnitude = Number(plain);
  if (!Number.isFinite(magnitude)) {
    return null;
  }

  const scaled =
    exponent === 0
      ? magnitude
      : // 1.23 * 1e3 is 1229.9999999999998 in binary floating point, and a
        // field that commits that instead of 1230 has not round-tripped.
        Number((magnitude * 10 ** exponent).toPrecision(15));
  if (!Number.isFinite(scaled)) {
    return null;
  }
  const result = sign * scaled;
  return Object.is(result, -0) ? 0 : result;
}

function stripCurrency(text: string): string {
  let out = text.trim();
  if (CURRENCY.test(out.charAt(0))) {
    out = out.slice(1).trim();
  }
  if (CURRENCY.test(out.charAt(out.length - 1))) {
    out = out.slice(0, -1).trim();
  }
  return out;
}

/**
 * The text shown while the field is focused: the plain machine number in the
 * locale's decimal separator, so what a person sees mid-edit is what the
 * parser reads back on blur.
 */
export function formatEditableNumber(value: number, locale?: Locale): string {
  const {decimal} = getLocaleNumberSymbols(locale);
  const raw = String(value);
  return decimal === '.' ? raw : raw.replace('.', decimal);
}