@astryxdesign/core 0.5.0-canary.b0a09a6 → 0.5.0-canary.b79f0db

package/dist/NumberInput/numberParser.d.ts

@@ -7,9 +7,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
@@ -18,6 +30,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';
 /**

package/dist/NumberInput/numberParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"numberParser.d.ts","sourceRoot":"","sources":["../../src/NumberInput/numberParser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,SAAS,CAAC;AA6OpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CA8Ef;AAaD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3E"}
+{"version":3,"file":"numberParser.d.ts","sourceRoot":"","sources":["../../src/NumberInput/numberParser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,SAAS,CAAC;AAiPpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CA8Ef;AAaD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3E"}

package/dist/NumberInput/numberParser.js

@@ -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
  */
 
 const symbolsByLocale = new Map();
@@ -64,15 +77,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+)$/;
@@ -167,7 +184,7 @@ function readUnder(core, group, decimal, primaryGroupSize, secondaryGroupSize, m
  * beats the decimal-point reading.
  */
 function isGroupOnlySeparator(separator) {
-  return /^[\s'\u2019\u00B7]$/.test(separator);
+  return /^[\s'\u2019]$/.test(separator);
 }
 function toPlainNumber(core, locale) {
   if (!NUMBER_BODY.test(core)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.5.0-canary.b0a09a6",
+  "version": "0.5.0-canary.b79f0db",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -661,7 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.5.0-canary.b0a09a6",
+    "@astryxdesign/cli": "0.5.0-canary.b79f0db",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

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

@@ -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.

package/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(

package/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;
+}