@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/NumberInput/NumberInput.tsx

@@ -9,6 +9,8 @@
  * @position Core implementation; consumed by index.ts, tested by NumberInput.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/NumberInput/numberParser.ts (locale-aware parsing)
+ * - /packages/core/src/NumberInput/numberInputCommit.ts (draft commit policy)
  * - /packages/core/src/NumberInput/NumberInput.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/NumberInput/NumberInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/NumberInput/index.ts (exports if types change)
@@ -213,7 +215,9 @@ import {isImeKeyEvent, mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
+import {useTranslator, useLocale} from '../i18n';
+import {formatEditableNumber} from './numberParser';
+import {parseNumberInput, resolveNumberInputCommit} from './numberInputCommit';
 
 interface NumberInputPropsBase extends Omit<
   BaseProps,
@@ -348,10 +352,12 @@ interface NumberInputPropsBase extends Omit<
   autoComplete?: string;
   /**
    * The minimum value allowed.
+   * A smaller entry commits at this value on blur or Enter.
    */
   min?: number | null;
   /**
    * The maximum value allowed.
+   * A larger entry commits at this value on blur or Enter.
    */
   max?: number | null;
   /**
@@ -425,46 +431,6 @@ type NumberInputPropsClearable = NumberInputPropsBase & {
 export type NumberInputProps =
   NumberInputPropsNonClearable | NumberInputPropsClearable;
 
-/**
- * Parse and validate a string input as a number.
- * Returns null if the input is not a valid number or fails validation.
- */
-function parseNumberInput(
-  input: string,
-  options: {
-    min?: number | null;
-    max?: number | null;
-    isIntegerOnly?: boolean;
-  },
-): number | null {
-  const trimmed = input.trim();
-  if (trimmed === '' || trimmed === '-') {
-    return null;
-  }
-
-  const num = Number(trimmed);
-  if (!Number.isFinite(num)) {
-    return null;
-  }
-
-  // Check integer constraint
-  if (options.isIntegerOnly && !Number.isInteger(num)) {
-    return null;
-  }
-
-  // Check min constraint
-  if (options.min != null && num < options.min) {
-    return null;
-  }
-
-  // Check max constraint
-  if (options.max != null && num > options.max) {
-    return null;
-  }
-
-  return num;
-}
-
 type StepDirection = -1 | 1;
 
 function getDecimalPlaces(value: number): number {
@@ -549,7 +515,8 @@ function getSteppedValue({
 
 /**
  * A number input component for collecting numeric user input.
- * Only calls onChange when the entered value passes validation.
+ * Commits text edits on blur or Enter and only calls onChange when the whole
+ * draft passes validation.
  *
  * @example
  * ```
@@ -599,6 +566,7 @@ export function NumberInput({
   ...rest
 }: NumberInputProps) {
   const t = useTranslator();
+  const locale = useLocale();
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const size = useSize(sizeProp, 'md');
   const id = useId();
@@ -653,6 +621,11 @@ export function NumberInput({
     inputGroup,
   );
 
+  const parseInput = useCallback(
+    (text: string) => parseNumberInput(text, {min, max, isIntegerOnly, locale}),
+    [isIntegerOnly, locale, max, min],
+  );
+
   const formattedValue = useMemo(() => {
     if (value == null) {
       return '';
@@ -669,36 +642,29 @@ export function NumberInput({
     if (value == null) {
       return '';
     }
-    return isFocused ? String(value) : formattedValue;
-  }, [formattedValue, isFocused, pendingInput, value]);
+    return isFocused ? formatEditableNumber(value, locale) : formattedValue;
+  }, [formattedValue, isFocused, locale, pendingInput, value]);
 
   // Check if current pending input is valid (for styling purposes)
   const isInputValid = useMemo(() => {
     if (pendingInput === null || !pendingInput.trim()) {
       return true;
     }
-    return parseNumberInput(pendingInput, {min, max, isIntegerOnly}) !== null;
-  }, [pendingInput, min, max, isIntegerOnly]);
+    return parseInput(pendingInput) !== null;
+  }, [pendingInput, parseInput]);
 
-  // Handle input text change - update immediately if valid
+  // Keep the whole text edit as a draft until an explicit commit boundary.
   const handleInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
       // Value can't change while showing a disabled message (the field is
       // read-only and non-native-disabled), but guard the handler too so the
-      // pending value and onChange never fire.
+      // pending value never changes.
       if (isDisabled || isReadOnly) {
         return;
       }
-      const newValue = e.target.value;
-      setPendingInput(newValue);
-
-      // If the input is valid, update immediately
-      const parsed = parseNumberInput(newValue, {min, max, isIntegerOnly});
-      if (parsed !== null && parsed !== value) {
-        onChange(parsed);
-      }
+      setPendingInput(e.target.value);
     },
-    [value, onChange, min, max, isIntegerOnly, isDisabled, isReadOnly],
+    [isDisabled, isReadOnly],
   );
 
   // Handle focus
@@ -710,34 +676,45 @@ export function NumberInput({
     [onFocus],
   );
 
-  // Handle blur - validate and clear pending input
-  const handleBlur = useCallback(
-    (e: FocusEvent<HTMLInputElement>) => {
-      if (pendingInput !== null) {
-        if (hasClear && pendingInput.trim() === '') {
-          // Keyboard clearing honors the clearable contract: an emptied
-          // input commits null instead of silently reverting on blur.
-          if (value != null) {
-            onChange(null);
-          }
-        } else {
-          const parsed = parseNumberInput(pendingInput, {
-            min,
-            max,
-            isIntegerOnly,
-          });
-          if (parsed !== null && parsed !== value) {
-            onChange(parsed);
-          }
+  const commitPendingInput = useCallback(
+    (trigger: 'blur' | 'Enter') => {
+      if (pendingInput === null) {
+        return;
+      }
+
+      const decision = resolveNumberInputCommit(pendingInput, {
+        min,
+        max,
+        isIntegerOnly,
+        locale,
+        hasClear: !!hasClear,
+      });
+      if (
+        trigger === 'blur' ||
+        (decision.type === 'commit' && decision.didClamp)
+      ) {
+        setPendingInput(null);
+      }
+
+      if (decision.type === 'clear') {
+        if (hasClear && value != null) {
+          onChange(null);
         }
+      } else if (decision.type === 'commit' && decision.value !== value) {
+        onChange(decision.value);
       }
+    },
+    [hasClear, isIntegerOnly, locale, max, min, onChange, pendingInput, value],
+  );
 
-      // Clear pending input - display will revert to formatted value
-      setPendingInput(null);
+  // Blur ends the edit and displays the resulting committed value.
+  const handleBlur = useCallback(
+    (e: FocusEvent<HTMLInputElement>) => {
+      commitPendingInput('blur');
       setIsFocused(false);
       onBlur?.(e);
     },
-    [pendingInput, value, onChange, min, max, isIntegerOnly, onBlur, hasClear],
+    [commitPendingInput, onBlur],
   );
 
   const valueForStepping = useMemo(() => {
@@ -747,10 +724,8 @@ export function NumberInput({
     if (pendingInput.trim() === '') {
       return null;
     }
-    return (
-      parseNumberInput(pendingInput, {min, max, isIntegerOnly}) ?? value ?? null
-    );
-  }, [isIntegerOnly, max, min, pendingInput, value]);
+    return parseInput(pendingInput) ?? value ?? null;
+  }, [parseInput, pendingInput, value]);
 
   const getNextValue = useCallback(
     (direction: StepDirection) =>
@@ -806,41 +781,12 @@ export function NumberInput({
         return;
       }
       if (e.key === 'Enter') {
-        // Validate and commit on Enter
-        if (pendingInput !== null) {
-          if (hasClear && pendingInput.trim() === '') {
-            // Same clearable contract as blur: Enter on an emptied input
-            // commits null instead of reverting.
-            if (value != null) {
-              onChange(null);
-            }
-          } else {
-            const parsed = parseNumberInput(pendingInput, {
-              min,
-              max,
-              isIntegerOnly,
-            });
-            if (parsed !== null && parsed !== value) {
-              onChange(parsed);
-            }
-          }
-        }
+        commitPendingInput('Enter');
         onEnter?.();
       }
       onKeyDown?.(e);
     },
-    [
-      pendingInput,
-      value,
-      onChange,
-      min,
-      max,
-      isIntegerOnly,
-      onEnter,
-      onKeyDown,
-      hasClear,
-      stepValue,
-    ],
+    [commitPendingInput, onEnter, onKeyDown, stepValue],
   );
 
   // React's delegated wheel listener can be passive, so use a native,
@@ -963,6 +909,8 @@ export function NumberInput({
         data-autofocus={hasAutoFocus || undefined}
         aria-valuemin={min ?? undefined}
         aria-valuemax={max ?? undefined}
+        // The ARIA value and hidden form input expose the committed value;
+        // pendingInput is still an uncommitted edit and may be invalid.
         aria-valuenow={value ?? undefined}
         aria-valuetext={
           value == null || !formatValue ? undefined : formattedValue

package/src/NumberInput/numberInputCommit.test.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file numberInputCommit.test.ts
+ * @input Uses Vitest and the NumberInput draft commit policy
+ * @output Focused tests for commit, clear, clamp, and revert decisions
+ * @position Testing; validates numberInputCommit.ts independently of React
+ */
+
+import {describe, expect, it} from 'vitest';
+import {parseNumberInput, resolveNumberInputCommit} from './numberInputCommit';
+
+describe('parseNumberInput', () => {
+  it('validates the complete localized draft', () => {
+    expect(parseNumberInput('1.234.567', {locale: 'de-DE'})).toBe(1234567);
+    expect(parseNumberInput('1·234·567', {locale: 'de-DE'})).toBeNull();
+  });
+});
+
+describe('resolveNumberInputCommit', () => {
+  it('commits one valid localized draft', () => {
+    expect(
+      resolveNumberInputCommit('1.234.567', {
+        locale: 'de-DE',
+        hasClear: false,
+      }),
+    ).toEqual({
+      type: 'commit',
+      value: 1234567,
+      didClamp: false,
+    });
+  });
+
+  it('reverts the whole draft when parsing fails', () => {
+    expect(
+      resolveNumberInputCommit('1·234·567', {
+        locale: 'en-US',
+        hasClear: false,
+      }),
+    ).toEqual({type: 'revert'});
+  });
+
+  it('clamps an out-of-range draft and requests normalization', () => {
+    expect(
+      resolveNumberInputCommit('100', {
+        min: 1,
+        max: 2,
+        isIntegerOnly: true,
+        hasClear: false,
+      }),
+    ).toEqual({type: 'commit', value: 2, didClamp: true});
+  });
+
+  it('distinguishes a clearable empty draft from a revert', () => {
+    expect(resolveNumberInputCommit('', {hasClear: true})).toEqual({
+      type: 'clear',
+    });
+    expect(resolveNumberInputCommit('', {hasClear: false})).toEqual({
+      type: 'revert',
+    });
+  });
+
+  it('reverts when no value can satisfy the bounds', () => {
+    expect(
+      resolveNumberInputCommit('10', {
+        min: 5,
+        max: 2,
+        hasClear: false,
+      }),
+    ).toEqual({type: 'revert'});
+  });
+});

package/src/NumberInput/numberInputCommit.ts

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file numberInputCommit.ts
+ * @input A NumberInput draft and the field's validation constraints
+ * @output A single commit, clear, or revert decision for the whole draft
+ * @position Shared internal draft validation and commit policy for NumberInput and its live consumers
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/NumberInput/NumberInput.tsx
+ * - /packages/core/src/NumberInput/numberInputCommit.test.ts
+ * - /packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
+ * - /packages/core/src/PowerSearch/PowerSearchValueEditor.tsx
+ */
+
+import type {Locale} from '../i18n';
+import {parseLocaleNumber} from './numberParser';
+
+interface NumberInputValidationOptions {
+  min?: number | null;
+  max?: number | null;
+  isIntegerOnly?: boolean;
+  locale?: Locale;
+}
+
+export type NumberInputCommitDecision =
+  | {type: 'commit'; value: number; didClamp: boolean}
+  | {type: 'clear'}
+  | {type: 'revert'};
+
+function parseNumericInput(
+  input: string,
+  options: Pick<NumberInputValidationOptions, 'isIntegerOnly' | 'locale'>,
+): number | null {
+  const trimmed = input.trim();
+  if (trimmed === '') {
+    return null;
+  }
+
+  const value = parseLocaleNumber(trimmed, options.locale);
+  if (value == null || !Number.isFinite(value)) {
+    return null;
+  }
+  if (options.isIntegerOnly && !Number.isInteger(value)) {
+    return null;
+  }
+  return value;
+}
+
+export function parseNumberInput(
+  input: string,
+  options: NumberInputValidationOptions,
+): number | null {
+  const value = parseNumericInput(input, options);
+  if (value === null) {
+    return null;
+  }
+  if (options.min != null && value < options.min) {
+    return null;
+  }
+  if (options.max != null && value > options.max) {
+    return null;
+  }
+  return value;
+}
+
+export function resolveNumberInputCommit(
+  input: string,
+  options: NumberInputValidationOptions & {hasClear: boolean},
+): NumberInputCommitDecision {
+  if (input.trim() === '') {
+    return options.hasClear ? {type: 'clear'} : {type: 'revert'};
+  }
+
+  const value = parseNumericInput(input, options);
+  if (value === null) {
+    return {type: 'revert'};
+  }
+
+  const min =
+    options.min == null
+      ? null
+      : options.isIntegerOnly
+        ? Math.ceil(options.min)
+        : options.min;
+  const max =
+    options.max == null
+      ? null
+      : options.isIntegerOnly
+        ? Math.floor(options.max)
+        : options.max;
+  if (min != null && max != null && min > max) {
+    return {type: 'revert'};
+  }
+
+  const committedValue =
+    min != null && value < min ? min : max != null && value > max ? max : value;
+  return {
+    type: 'commit',
+    value: committedValue,
+    didClamp: committedValue !== value,
+  };
+}

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([]);
+  });
+});