@astryxdesign/core 0.5.0 → 0.5.1-canary.f64186a

package/src/NumberInput/numberParser.docblock.test.ts

@@ -0,0 +1,234 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file numberParser.docblock.test.ts
+ * @input The rule paragraph in numberParser.ts, and the parser itself
+ * @output Nothing; fails when the two disagree
+ * @position Test-only; grades the prose in numberParser.ts against the code
+ *
+ * The file docblock of numberParser.ts states the rule the parser follows.
+ * A sentence like that rots silently — the code moves and the words stay —
+ * and the next person to change this file reads the words. So the paragraph
+ * is executable here: `predict` implements it, clause by clause, and every
+ * input is graded prose-against-parser.
+ *
+ * The one discipline that makes the number mean anything: `predict` may use
+ * ONLY what the paragraph says. Every branch below quotes the clause it
+ * implements, and those quotes are asserted verbatim against the source, so
+ * a paragraph that loses a clause fails here instead of drifting. If the
+ * parser grows a rule the words do not mention, this test goes red — that is
+ * the point, not a defect.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/NumberInput/numberParser.ts
+ */
+
+import {describe, it, expect} from 'vitest';
+import {parseLocaleNumber} from './numberParser';
+import SOURCE from './numberParser.ts?raw';
+
+/** The docblock as running prose: comment markers and line breaks removed. */
+const PROSE = SOURCE.replace(/^\s*\*\s?/gm, '').replace(/\s+/g, ' ');
+
+/** Every clause `predict` is allowed to know, quoted from the docblock. */
+const CLAUSES = {
+  'defer to the alphabet': 'SEPARATOR_CHARS below is a bounded alphabet',
+  'fold the space family': 'the whole space family folds to it under NFKC',
+  'refuse what no reading fits': 'text that no reading fits returns null',
+  'prefer the locale': 'Where both readings are well formed the locale',
+  'size every group':
+    "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.',
+  'fall back to the decimal point': 'keep the full stop as a decimal point',
+  'read three-digit groups anywhere':
+    'Groups of three fit every locale, so a separator repeated with ' +
+    'three-digit groups is grouping in all of them',
+  'need only one group-only occurrence':
+    'for a space or apostrophe, which no locale writes as a decimal point, ' +
+    'one occurrence is enough',
+} as const;
+
+/** The bounded alphabet the docblock defers to, read out of the source. */
+const ALPHABET: ReadonlySet<string> = new Set(
+  JSON.parse(
+    `"${/const SEPARATOR_CHARS = "([^"]*)"/.exec(SOURCE)?.[1] ?? ''}"`,
+  ),
+);
+
+const symbolsCache = new Map<string, ReturnType<typeof readSymbols>>();
+function readSymbols(locale: string) {
+  const parts = new Intl.NumberFormat(locale).formatToParts(12345.6);
+  const sizes = new Intl.NumberFormat(locale)
+    .formatToParts(11111111111)
+    .filter(p => p.type === 'integer')
+    .map(p => p.value.length);
+  const grouped = sizes.length > 1;
+  return {
+    group: (parts.find(p => p.type === 'group')?.value ?? ',').normalize(
+      'NFKC',
+    ),
+    decimal: parts.find(p => p.type === 'decimal')?.value ?? '.',
+    primary: grouped ? sizes[sizes.length - 1] : 3,
+    secondary: grouped ? sizes[sizes.length - 2] : 3,
+  };
+}
+function symbolsOf(locale: string) {
+  let s = symbolsCache.get(locale);
+  if (s === undefined) {
+    s = readSymbols(locale);
+    symbolsCache.set(locale, s);
+  }
+  return s;
+}
+
+/** CLAUSES['size every group'], with the sizes it is handed. */
+function groupsFit(chunks: string[], primary: number, secondary: number) {
+  return (
+    chunks[chunks.length - 1].length === primary &&
+    chunks[0].length <= secondary &&
+    chunks.slice(1, -1).every(chunk => chunk.length === secondary)
+  );
+}
+
+/** CLAUSES['need only one group-only occurrence']: "a space or apostrophe". */
+const isSpaceOrApostrophe = (char: string) => /^[\s'\u2019]$/.test(char);
+
+const SKIPPED = Symbol('outside the paragraph');
+
+/**
+ * The paragraph, as code. Digits with one separator character repeated
+ * between them is the shape it describes; anything else is not this
+ * paragraph's subject and is skipped rather than guessed at.
+ */
+function predict(input: string, locale: string): number | null | symbol {
+  // CLAUSES['fold the space family'].
+  const text = input.normalize('NFKC');
+  if (!/^\d/.test(text) || !/\d$/.test(text)) {
+    return SKIPPED;
+  }
+  const separators = [...new Set(text.replace(/\d/g, ''))];
+  if (separators.length !== 1) {
+    return SKIPPED;
+  }
+  const [separator] = separators;
+
+  // CLAUSES['defer to the alphabet'].
+  if (!ALPHABET.has(separator)) {
+    return null;
+  }
+
+  const chunks = text.split(separator);
+  const {group, decimal, primary, secondary} = symbolsOf(locale);
+
+  // CLAUSES['prefer the locale'] + CLAUSES['size every group']: of the two
+  // locale readings, grouping wins wherever it is well formed.
+  if (separator === group && groupsFit(chunks, primary, secondary)) {
+    return Number(chunks.join(''));
+  }
+  // The locale's other reading. A decimal point appears once.
+  if (separator === decimal && chunks.length === 2) {
+    return Number(`${chunks[0]}.${chunks[1]}`);
+  }
+  // CLAUSES['fall back to the decimal point'], for a full stop the locale
+  // could read neither way.
+  if (separator === '.' && chunks.length === 2) {
+    return Number(text);
+  }
+  // CLAUSES['read three-digit groups anywhere'], and CLAUSES['need only one
+  // group-only occurrence'] for how many occurrences it takes.
+  const enough = isSpaceOrApostrophe(separator) ? 1 : 2;
+  if (chunks.length - 1 >= enough && groupsFit(chunks, 3, 3)) {
+    return Number(chunks.join(''));
+  }
+  // CLAUSES['refuse what no reading fits'].
+  return null;
+}
+
+const LOCALES = ['en-US', 'de-DE', 'fr-FR', 'de-CH', 'en-IN', 'ar-SA'];
+
+/** The shapes the paragraph names, plus the seams around each clause. */
+const NAMED: [string, string][] = [
+  ['1.234', 'de-DE'],
+  ['1.2345', 'de-DE'],
+  ['1234.567', 'de-DE'],
+  ['12345.678', 'de-DE'],
+  ['12.345', 'de-DE'],
+  ['1.23', 'de-DE'],
+  ['1,234,567', 'en-US'],
+  ['1,234,567', 'de-DE'],
+  ['1.234.567', 'en-US'],
+  ['1234.567.890', 'de-DE'],
+  ['1 234', 'en-US'],
+  ['1\u00A0234', 'en-US'],
+  ['1 234 567', 'en-US'],
+  ['1234 567', 'fr-FR'],
+  ["1'234", 'de-CH'],
+  ["1'234", 'en-US'],
+  ['1\u2019234', 'de-CH'],
+  ['1,234', 'en-IN'],
+  ['12,34,567', 'en-IN'],
+  ['123,45,678', 'en-IN'],
+  ['1,2,345', 'en-IN'],
+  ['1\u066C234', 'ar-SA'],
+  ['1\u066B5', 'ar-SA'],
+  ['1\u00B7234\u00B7567', 'en-US'],
+  ['123-456-789', 'en-US'],
+];
+
+/** Every one-, two- and three-separator shape over short digit runs. */
+function* generated() {
+  const runs = ['1', '12', '123', '1234', '12345'];
+  for (const locale of LOCALES) {
+    for (const separator of ALPHABET) {
+      for (const a of runs) {
+        for (const b of runs) {
+          yield [`${a}${separator}${b}`, locale] as [string, string];
+          for (const c of runs) {
+            yield [`${a}${separator}${b}${separator}${c}`, locale] as [
+              string,
+              string,
+            ];
+            for (const d of runs) {
+              yield [
+                `${a}${separator}${b}${separator}${c}${separator}${d}`,
+                locale,
+              ] as [string, string];
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+describe('the numberParser docblock', () => {
+  it.each(Object.entries(CLAUSES))('still says: %s', (_name, quote) => {
+    expect(PROSE).toContain(quote);
+  });
+
+  it.each(NAMED)('reads %j in %s the way the parser does', (input, locale) => {
+    expect(predict(input, locale)).toBe(parseLocaleNumber(input, locale));
+  });
+
+  it('reads every generated shape the way the parser does', () => {
+    const disagreements: string[] = [];
+    let checked = 0;
+    for (const [input, locale] of generated()) {
+      const said = predict(input, locale);
+      if (said === SKIPPED) {
+        continue;
+      }
+      checked++;
+      const did = parseLocaleNumber(input, locale);
+      if (!Object.is(said, did)) {
+        disagreements.push(
+          `${JSON.stringify(input)} in ${locale}: docblock ${String(said)}, parser ${String(did)}`,
+        );
+      }
+    }
+    // The sweep is the evidence; a shrunken one silently proves nothing.
+    expect(checked).toBeGreaterThan(30000);
+    expect(disagreements.slice(0, 10)).toEqual([]);
+  });
+});

package/src/NumberInput/numberParser.test.ts

@@ -0,0 +1,222 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {formatEditableNumber, parseLocaleNumber} from './numberParser';
+
+const NBSP = '\u00A0';
+const NARROW_NBSP = '\u202F';
+const APOSTROPHE = '\u2019';
+const MIDDLE_DOT = '\u00B7';
+
+/**
+ * The contract, enumerated. A row is `[input, locale, expected]`, and `null`
+ * means the field stays visibly invalid rather than committing a guess.
+ */
+const CORPUS: [string, string, number | null][] = [
+  // Grouped — the case this exists for, and it holds in every locale because
+  // a repeated separator with three digits after it cannot be a decimal point.
+  ['1,234,234,234', 'en-US', 1234234234],
+  ['1,234,234,234', 'de-DE', 1234234234],
+  ['1,234,234,234', 'fr-FR', 1234234234],
+  ['1,234,234,234', 'ar-SA', 1234234234],
+  ['1.234.234.234', 'de-DE', 1234234234],
+  ['1.234.234.234', 'en-US', 1234234234],
+  [`1${NARROW_NBSP}234${NARROW_NBSP}234${NARROW_NBSP}234`, 'fr-FR', 1234234234],
+  [`1${NBSP}234${NBSP}234`, 'fr-FR', 1234234],
+  [`1${NBSP}234`, 'en-US', 1234],
+  [`1${APOSTROPHE}234${APOSTROPHE}234`, 'de-CH', 1234234],
+  ["1'234'234", 'de-CH', 1234234],
+  ['1,234', 'en-US', 1234],
+  ['1,234', 'de-DE', 1.234],
+
+  // Indian lakh grouping, derived from the locale's own group sizes.
+  ['12,34,567', 'en-IN', 1234567],
+  ['12,34,567', 'en-US', null],
+
+  // Ragged grouping is a typo, not a number: the last group is not three.
+  ['1,23,4', 'en-US', null],
+  ['1,2345', 'en-US', null],
+  ['12 34', 'en-US', null],
+
+  // One separator, one meaning per locale, and no meaning across them.
+  ['1,5', 'de-DE', 1.5],
+  ['1,5', 'en-US', null],
+  ['1.5', 'en-US', 1.5],
+
+  // The machine decimal point reads everywhere: a full stop the locale cannot
+  // read as grouping has one meaning left, and refusing it lost a number the
+  // person had typed. Where grouping IS well formed the locale still wins.
+  ['1.5', 'de-DE', 1.5],
+  ['1.5', 'fr-FR', 1.5],
+  ['1234.56', 'de-DE', 1234.56],
+  ['-3.25', 'fr-FR', -3.25],
+  ['0.5', 'de-DE', 0.5],
+  ['1.5e3', 'de-DE', 1500],
+  ['1.234', 'de-DE', 1234],
+  ['1.2345', 'de-DE', 1.2345],
+  // The same text in the other comma-decimal locale: fr-FR groups with a
+  // space, so a full stop has no grouping reading there and stays the point.
+  ['1.234', 'fr-FR', 1.234],
+
+  // Decimals and signs.
+  ['1,234.56', 'en-US', 1234.56],
+  ['1.234,56', 'de-DE', 1234.56],
+  ['1,234.56', 'de-DE', null],
+  ['-1,234.56', 'en-US', -1234.56],
+  ['+7', 'en-US', 7],
+  ['-7', 'en-US', -7],
+  ['7-', 'ar-SA', -7],
+  ['.5', 'en-US', 0.5],
+  ['5.', 'en-US', 5],
+  ['-', 'en-US', null],
+  ['', 'en-US', null],
+  ['   ', 'en-US', null],
+
+  // Spreadsheet cells arrive with their whitespace attached.
+  ['  42  ', 'en-US', 42],
+  ['\t1,234\n', 'en-US', 1234],
+  ['1,234\n5,678', 'en-US', null],
+
+  // Digit scripts, derived from \p{Nd} rather than enumerated.
+  ['١٢٣', 'ar-SA', 123],
+  ['۱۲۳', 'fa-IR', 123],
+  ['१२३', 'hi-IN', 123],
+  ['１２３', 'ja-JP', 123],
+  ['١,٢٣٤', 'en-US', 1234],
+  ['٣٫٥', 'ar-SA', 3.5],
+
+  // Currency decorates the number without changing its magnitude, so the
+  // symbol is dropped and the separators still decide. A number written for
+  // another locale still refuses.
+  ['$1,234.56', 'en-US', 1234.56],
+  ['£1,234', 'en-US', 1234],
+  ['1.234,56 €', 'de-DE', 1234.56],
+  ['1.234,56 €', 'en-US', null],
+  ['-$1,234', 'en-US', -1234],
+
+  // A unit suffix is not dropped: `B` and `k` carry magnitude, so guessing
+  // which trailing letters are inert is how a wrong number gets committed.
+  ['1,234 GB', 'en-US', null],
+  ['72°F', 'en-US', null],
+  ['1,234 kg', 'en-US', null],
+
+  // Accounting negatives.
+  ['(1,234)', 'en-US', -1234],
+  ['($1,234.50)', 'en-US', -1234.5],
+  ['(1,234', 'en-US', null],
+  // The parens already carry the sign; a second one reads two ways.
+  ['(-1,234)', 'en-US', null],
+  ['(+1,234)', 'en-US', null],
+
+  // Typographic minus signs.
+  ['\u22121234', 'en-US', -1234],
+  ['\u20131234', 'en-US', -1234],
+
+  // Exponents, including the shape a spreadsheet exports.
+  ['1.23E+09', 'en-US', 1230000000],
+  ['1.23e9', 'en-US', 1230000000],
+  ['1.5e-3', 'en-US', 0.0015],
+  ['1e', 'en-US', null],
+
+  // Invisible characters Excel and Sheets attach.
+  ['\uFEFF1,234', 'en-US', 1234],
+  ['1,234\u200B', 'en-US', 1234],
+  ['\u200E1,234', 'en-US', 1234],
+
+  // Junk.
+  ['NaN', 'en-US', null],
+  ['Infinity', 'en-US', null],
+  ['abc', 'en-US', null],
+  ['12abc', 'en-US', null],
+  ['1/2', 'en-US', null],
+  ['1 234 (approx)', 'en-US', null],
+  ['--5', 'en-US', null],
+  ['1..234', 'en-US', null],
+
+  // Only a character some locale writes between digits is a separator. None of
+  // these are numbers, and the last two were refused before only because their
+  // final group is the wrong length — luck, not a rule.
+  ['123-456-789', 'en-US', null],
+  ['1-800-555', 'en-US', null],
+  ['555-123-456', 'en-US', null],
+  ['1_234_567', 'en-US', null],
+  ['1/234/567', 'en-US', null],
+  ['1:234:567', 'en-US', null],
+  ['1*234*567', 'en-US', null],
+  ['800-555-1212', 'en-US', null],
+  ['2024-01-15', 'en-US', null],
+
+  // U+00B7 was in the alphabet as the Catalan middle dot. Catalan groups with
+  // a full stop, and no locale ICU resolves writes it between digits at all.
+  [`1${MIDDLE_DOT}234${MIDDLE_DOT}567`, 'en-US', null],
+  [`1${MIDDLE_DOT}234${MIDDLE_DOT}567`, 'ca-ES', null],
+
+  // The field has no percent semantics, so a percent sign is not dropped:
+  // committing 45 for `45%` is off by a factor of a hundred.
+  ['45%', 'en-US', null],
+  ['0.5%', 'en-US', null],
+  ['45 %', 'fr-FR', null],
+];
+
+describe('parseLocaleNumber', () => {
+  it.each(CORPUS)('parses %j in %s', (input, locale, expected) => {
+    expect(parseLocaleNumber(input, locale)).toBe(expected);
+  });
+
+  it('reads back the grouping every locale writes', () => {
+    for (const locale of [
+      'en-US',
+      'de-DE',
+      'fr-FR',
+      'de-CH',
+      'en-IN',
+      'ar-SA',
+    ]) {
+      const text = new Intl.NumberFormat(locale).format(1234234234);
+      expect(parseLocaleNumber(text, locale)).toBe(1234234234);
+    }
+  });
+});
+
+describe('formatEditableNumber', () => {
+  it.each([
+    [1.5, 'en-US', '1.5'],
+    [1.5, 'de-DE', '1,5'],
+    [-1234.56, 'fr-FR', '-1234,56'],
+    // Only the decimal separator is localized. The digits stay as `String`
+    // writes them, which is what the field shows at rest when no `formatValue`
+    // is given, so localizing them here would flip the script on focus.
+    [3.5, 'ar-SA', '3٫5'],
+    // No grouping: the text has to be editable, and a separator the person did
+    // not type is one they have to delete.
+    [1234234234, 'de-DE', '1234234234'],
+    [42, 'de-DE', '42'],
+    // What `String` writes for the extremes stays untouched but for the point.
+    [1e21, 'de-DE', '1e+21'],
+    [1.5e-7, 'de-DE', '1,5e-7'],
+  ])('shows %j in %s as %j', (value, locale, expected) => {
+    expect(formatEditableNumber(value, locale)).toBe(expected);
+  });
+
+  it('round trips through the parser in every locale', () => {
+    for (const locale of [
+      'en-US',
+      'de-DE',
+      'fr-FR',
+      'de-CH',
+      'en-IN',
+      'ar-SA',
+      'ja-JP',
+      'hi-IN',
+    ]) {
+      for (const value of [
+        0, 1, -1, 0.1, 1.5, -0.5, 1234.56, -1234567.125, 123456789,
+        3.141592653589793, 1e21, 1.5e-7, -9007199254740991,
+      ]) {
+        expect(
+          parseLocaleNumber(formatEditableNumber(value, locale), locale),
+        ).toBe(value);
+      }
+    }
+  });
+});