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.mdindex 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` — ahyphenated ID pasted into a quantity field became a number. Only thecharacters 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 — anaccounting 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.mdindex 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.jsindex 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.mjsindex 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 implementationdiff --git a/packages/core/src/NumberInput/numberParser.docblock.test.ts b/packages/core/src/NumberInput/numberParser.docblock.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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;+}