Skip to content

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

TypeScript

fix(NumberInput): drop U+00B7 from the separator alphabet, and say what the parser actually does (#5468)

Cindy Zhang299077f204c8
diff --git a/.changeset/number-input-bounded-separators.md b/.changeset/number-input-bounded-separators.md
index c554602e10..ec4f1169ad 100644
--- a/.changeset/number-input-bounded-separators.md
+++ b/.changeset/number-input-bounded-separators.md
@@ -20,6 +20,9 @@ in de-DE is 1234, not 1.234.
committed 123456789, and so did `1_234_567`, `1/234/567` and `1:234:567` — a
hyphenated ID pasted into a quantity field became a number. Only the
characters some locale actually writes between digits are separators now.
+That bounds the characters, not the shapes: a full stop is a real separator in
+its own right, so `192.168.100.200` still commits 192168100200, exactly as it
+did before.
Also: `(-1,234)` and `(+1,234)` each flipped their own sign and now refuse — an
accounting paren already says negative, so a sign inside it reads two ways.
diff --git a/internal/eslint-plugin-astryx/README.md b/internal/eslint-plugin-astryx/README.md
index 4130c84d74..d65adc21ea 100644
--- a/internal/eslint-plugin-astryx/README.md
+++ b/internal/eslint-plugin-astryx/README.md
@@ -78,6 +78,7 @@ Named test oracles:
- `packages/core/src/Calendar/Calendar.test.tsx`
- `packages/core/src/NumberInput/NumberInput.test.tsx`
- `packages/core/src/NumberInput/numberParser.test.ts`
+- `packages/core/src/NumberInput/numberParser.docblock.test.ts`
- `packages/core/src/Table/plugins/tree/useTableTreeState.test.tsx`
- `packages/core/src/Timestamp/tooltipEntries.test.ts`
- `packages/core/src/PowerSearch/formatFilterValue.test.ts`
diff --git a/internal/eslint-plugin-astryx/no-raw-intl-locale.js b/internal/eslint-plugin-astryx/no-raw-intl-locale.js
index 646bacd7bd..aec523a874 100644
--- a/internal/eslint-plugin-astryx/no-raw-intl-locale.js
+++ b/internal/eslint-plugin-astryx/no-raw-intl-locale.js
@@ -123,6 +123,10 @@ const APPROVED_TEST_ORACLE_FILES = [
'packages/core/src/Calendar/Calendar.test.tsx',
'packages/core/src/NumberInput/NumberInput.test.tsx',
'packages/core/src/NumberInput/numberParser.test.ts',
+ // The docblock grader's oracle: it re-derives the locale's separators and
+ // group sizes from Intl so the prose is checked against something other
+ // than the helper it grades.
+ 'packages/core/src/NumberInput/numberParser.docblock.test.ts',
'packages/core/src/Table/plugins/tree/useTableTreeState.test.tsx',
'packages/core/src/Timestamp/tooltipEntries.test.ts',
'packages/core/src/PowerSearch/formatFilterValue.test.ts',
diff --git a/internal/eslint-plugin-astryx/no-raw-intl-locale.test.mjs b/internal/eslint-plugin-astryx/no-raw-intl-locale.test.mjs
index 5574e2a5e4..fd7a21aced 100644
--- a/internal/eslint-plugin-astryx/no-raw-intl-locale.test.mjs
+++ b/internal/eslint-plugin-astryx/no-raw-intl-locale.test.mjs
@@ -37,6 +37,8 @@ const NUMBER_PARSER_INFRA_FILE =
'packages/core/src/NumberInput/numberParser.ts';
const NUMBER_PARSER_TEST_ORACLE_FILE =
'packages/core/src/NumberInput/numberParser.test.ts';
+const NUMBER_PARSER_DOCBLOCK_ORACLE_FILE =
+ 'packages/core/src/NumberInput/numberParser.docblock.test.ts';
const CHARTS_INFRA_FILE = 'packages/charts/src/formatters.ts';
const TIMESTAMP_TEST_ORACLE_FILE = 'packages/core/src/Timestamp/Timestamp.test.tsx';
const CALENDAR_TEST_ORACLE_FILE = 'packages/core/src/Calendar/Calendar.test.tsx';
@@ -147,6 +149,10 @@ tester.run('no-raw-intl-locale', rule, {
code: `new Intl.NumberFormat('de-DE').format(1234234234);`,
filename: NUMBER_PARSER_TEST_ORACLE_FILE,
},
+ {
+ code: `new Intl.NumberFormat(locale).formatToParts(11111111111);`,
+ filename: NUMBER_PARSER_DOCBLOCK_ORACLE_FILE,
+ },
// -- A named test-oracle file may also construct raw Intl with a
// non-navigator locale argument, exactly like an infra implementation
diff --git a/packages/core/src/NumberInput/numberParser.docblock.test.ts b/packages/core/src/NumberInput/numberParser.docblock.test.ts
new file mode 100644
index 0000000000..1da35ffae1
--- /dev/null
+++ b/packages/core/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([]);
+ });
+});
diff --git a/packages/core/src/NumberInput/numberParser.test.ts b/packages/core/src/NumberInput/numberParser.test.ts
index 5ae93046c6..32ec52be5f 100644
--- a/packages/core/src/NumberInput/numberParser.test.ts
+++ b/packages/core/src/NumberInput/numberParser.test.ts
@@ -6,6 +6,7 @@ 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`
@@ -53,6 +54,9 @@ const CORPUS: [string, string, number | null][] = [
['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],
@@ -142,6 +146,11 @@ const CORPUS: [string, string, number | 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],
@@ -174,6 +183,9 @@ describe('formatEditableNumber', () => {
[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.
diff --git a/packages/core/src/NumberInput/numberParser.ts b/packages/core/src/NumberInput/numberParser.ts
index 2d87fa4cf8..978c56cf80 100644
--- a/packages/core/src/NumberInput/numberParser.ts
+++ b/packages/core/src/NumberInput/numberParser.ts
@@ -9,9 +9,21 @@
* 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 anything
- * that could mean two different numbers returns null so the field stays
- * visibly invalid instead of committing a guess.
+ * 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
@@ -20,6 +32,7 @@
* 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';
@@ -81,15 +94,19 @@ const INVISIBLES = /[\u200B-\u200D\u200E\u200F\u061C\u2066-\u2069\uFEFF]/g;
const MINUS_SIGNS = '\u2212\u2012\u2013-';
/**
- * Every character a locale writes between digits: comma, full stop, space
- * (the whole space family folds to it under NFKC), the Swiss apostrophes, the
- * Catalan middle dot, and the Arabic decimal and thousands separators.
+ * 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.
+ * 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\u00B7\u066B\u066C";
+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+)$/;
@@ -198,7 +215,7 @@ function readUnder(
* beats the decimal-point reading.
*/
function isGroupOnlySeparator(separator: string): boolean {
- return /^[\s'\u2019\u00B7]$/.test(separator);
+ return /^[\s'\u2019]$/.test(separator);
}
function toPlainNumber(
diff --git a/packages/core/src/raw-import.d.ts b/packages/core/src/raw-import.d.ts
new file mode 100644
index 0000000000..e69c56ec68
--- /dev/null
+++ b/packages/core/src/raw-import.d.ts
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Ambient module declaration for Vite's `?raw` imports.
+ *
+ * numberParser.docblock.test.ts reads its own subject's source as text, to
+ * check the prose in it against the parser's behaviour. Vite serves that with
+ * the `?raw` query; without this declaration TypeScript fails with TS2307.
+ */
+
+declare module '*?raw' {
+ const content: string;
+ export default content;
+}