feat(NumberInput): add support locale format validation (#20520)

* feat(NumberInput): add support locale format validation

* chore: updated locale formatting validation check

* chore: updated locale formatting validation same as Manage

* chore: updated code logic

* dummy commit

* chore: updated validation

* dummy commit

* chore: added warntext which was removed unintentionally

Author: abpaul1993

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -7321,6 +7321,9 @@ Map {
         ],
         "type": "oneOf",
       },
+      "validate": {
+        "type": "func",
+      },
       "value": {
         "args": [
           [

packages/react/src/components/NumberInput/NumberInput.stories.js

@@ -8,6 +8,7 @@
 import React, { useState } from 'react';
 import { NumberInput } from './';
 import NumberInputSkeleton from './NumberInput.Skeleton';
+import { validateNumberSeparators } from './NumberInput';
 import Button from '../Button';
 import { AILabel, AILabelContent, AILabelActions } from '../AILabel';
 import { IconButton } from '../IconButton';
@@ -250,6 +251,55 @@ WithTypeOfTextControlled.argTypes = {
   ...sharedArgTypes,
 };
 
+export const WithTypeOfCustomValidation = (args) => {
+  const locale = useDocumentLang();
+  const [value, setValue] = useState(NaN);
+
+  return (
+    <>
+      <NumberInput
+        id="default-number-input"
+        type="text"
+        inputMode="decimal"
+        label="NumberInput label"
+        helperText="Optional helper text."
+        validate={validateNumberSeparators}
+        {...args}
+        locale={locale}
+        value={value}
+        allowEmpty
+        onChange={(event, state) => {
+          setValue(state.value);
+        }}
+      />
+      <button
+        type="button"
+        onClick={() => {
+          setValue(1000);
+        }}>
+        set to 1000
+      </button>
+    </>
+  );
+};
+WithTypeOfCustomValidation.args = {
+  step: 1,
+  disabled: false,
+  invalid: false,
+  invalidText: `Number is not valid. Must be between ${reusableProps.min} and ${reusableProps.max}`,
+  helperText: 'Optional helper text.',
+  warn: false,
+  warnText:
+    'Warning message that is really long can wrap to more lines but should not be excessively long.',
+  size: 'md',
+  type: 'text',
+};
+WithTypeOfCustomValidation.argTypes = {
+  locale: { control: { type: 'text' } },
+  formatOptions: { control: { type: 'object' } },
+  ...sharedArgTypes,
+};
+
 export const Skeleton = () => {
   return <NumberInputSkeleton />;
 };

packages/react/src/components/NumberInput/NumberInput.tsx

@@ -67,6 +67,26 @@ type ExcludedAttributes =
 export interface NumberInputProps
   extends Omit<React.InputHTMLAttributes<HTMLInputElement>, ExcludedAttributes>,
     TranslateWithId<TranslationKey> {
+  /**
+   * Optional validation function that is called with the input value and locale.
+   * This is called before other validations, giving consumers the ability
+   * to short-circuit or extend validation without replacing built-in rules
+   * @example
+   * // Using the built-in separator validation
+   * <NumberInput validate={validateNumberSeparators} />
+   *
+   * // Combining with custom validation
+   * <NumberInput
+   *   validate={(value, locale) => {
+   *     return validateNumberSeparators(value, locale) && customValidation(value)
+   *   }}
+   * />
+   * - Return `false` to immediately fail validation.
+   * - Return `true` to pass this validation, but still run other checks (min, max, required, etc.).
+   * - Return `undefined` to defer entirely to built-in validation logic.
+   *
+   */
+  validate?: (value: string, locale: string) => boolean | undefined;
   /**
    * `true` to allow empty string.
    */
@@ -277,6 +297,78 @@ export interface NumberInputProps
   warnText?: ReactNode;
 }
 
+const getSeparators = (locale: string) => {
+  const numberWithGroupAndDecimal = 1234567.89;
+
+  const formatted = new Intl.NumberFormat(locale).format(
+    numberWithGroupAndDecimal
+  );
+
+  // Extract separators using regex
+  const match = formatted.match(/(\D+)\d{3}(\D+)\d{2}$/);
+
+  if (match) {
+    const groupSeparator = match[1];
+    const decimalSeparator = match[2];
+    return { groupSeparator, decimalSeparator };
+  } else {
+    return { groupSeparator: null, decimalSeparator: null };
+  }
+};
+
+export const validateNumberSeparators = (
+  input: string,
+  locale: string
+): boolean => {
+  // allow empty string
+  if (input === '' || Number.isNaN(input)) {
+    return true;
+  }
+  const { groupSeparator, decimalSeparator } = getSeparators(locale);
+
+  if (!decimalSeparator) {
+    return !isNaN(Number(input));
+  }
+
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  let group = '';
+  if (groupSeparator) {
+    if (groupSeparator.trim() === '') {
+      group = '[\\u00A0\\u202F\\s]'; // handle NBSP, narrow NBSP, space
+    } else {
+      group = esc(groupSeparator);
+    }
+  }
+
+  const decimal = esc(decimalSeparator);
+
+  // Regex for:
+  // - integers (with/without grouping)
+  // - optional decimal with 0+ digits after separator
+  const regex = new RegExp(
+    `^-?\\d{1,3}(${group}\\d{3})*(${decimal}\\d*)?$|^-?\\d+(${decimal}\\d*)?$`
+  );
+
+  if (!regex.test(input)) {
+    return false;
+  }
+
+  // Normalize
+  let normalized = input;
+  if (groupSeparator) {
+    if (groupSeparator.trim() === '') {
+      normalized = normalized?.replace(/[\u00A0\u202F\s]/g, '');
+    } else {
+      normalized = normalized?.split(groupSeparator).join('');
+    }
+  }
+
+  normalized = normalized?.replace(decimalSeparator, '.');
+
+  return !isNaN(Number(normalized));
+};
+
 // eslint-disable-next-line react/display-name -- https://github.com/carbon-design-system/carbon/issues/20071
 const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
   (props: NumberInputProps, forwardRef) => {
@@ -312,6 +404,7 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
       translateWithId: t = (id) => defaultTranslations[id],
       type = 'number',
       defaultValue = type === 'number' ? 0 : NaN,
+      validate,
       warn = false,
       warnText = '',
       stepStartValue = 0,
@@ -367,7 +460,6 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
      * Only used when type="text"
      */
     const [previousNumberValue, setPreviousNumberValue] = useState(numberValue);
-
     /**
      * The current text value of the input.
      * Only used when type=text
@@ -418,9 +510,11 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
     const isInputValid = getInputValidity({
       allowEmpty,
       invalid,
-      value: type === 'number' ? value : numberValue,
+      value: validate ? inputValue : type === 'number' ? value : numberValue,
       max,
       min,
+      validate,
+      locale,
     });
     const normalizedProps = normalize({
       id,
@@ -492,7 +586,6 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
         const _value =
           allowEmpty && event.target.value === '' ? '' : event.target.value;
 
-        // When isControlled, setNumberValue will not update numberValue in useControllableState.
         setNumberValue(numberParser.parse(_value));
         setInputValue(_value);
         // The onChange prop isn't called here because it will be called on blur
@@ -559,7 +652,7 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
           getDecimalPlaces(currentValue),
           getDecimalPlaces(step)
         );
-        const floatValue = parseFloat(rawValue.toFixed(precision));
+        const floatValue = parseFloat(Number(rawValue).toFixed(precision));
         const newValue = clamp(floatValue, min ?? -Infinity, max ?? Infinity);
 
         const state = {
@@ -693,15 +786,17 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
                   const formattedValue = isNaN(_numberValue)
                     ? ''
                     : format(_numberValue);
-                  setInputValue(formattedValue);
-
+                  const rawValue = e.target.value;
+                  // Validate raw input
+                  const isValid = validate ? validate(rawValue, locale) : true;
+                  setInputValue(isValid ? formattedValue : rawValue);
                   // Calling format() can alter the number (such as rounding it)
                   // causing the _numberValue to mismatch the formatted value in
                   // the input. To avoid this, formattedValue is re-parsed.
                   const parsedFormattedNewValue =
                     numberParser.parse(formattedValue);
 
-                  if (onChange) {
+                  if (onChange && isValid) {
                     const state = {
                       value: parsedFormattedNewValue,
                       direction:
@@ -1013,6 +1108,18 @@ NumberInput.propTypes = {
    * Provide the text that is displayed when the control is in warning state
    */
   warnText: PropTypes.node,
+
+  /**
+   * Optional validation function that is called with the input value and locale.
+   *
+   * - Return `false` to immediately fail validation.
+   * - Return `true` to pass this validation, but still run other checks (min, max, required, etc.).
+   * - Return `undefined` to defer entirely to built-in validation logic.
+   *
+   * This is called before other validations, giving consumers the ability
+   * to short-circuit or extend validation without replacing built-in rules.
+   */
+  validate: PropTypes.func,
 };
 
 interface LabelProps {
@@ -1073,9 +1180,27 @@ const HelperText = ({ disabled, description, id }: HelperTextProps) => {
  * @param {number} config.value
  * @param {number} config.max
  * @param {number} config.min
+ * @param {Function} config.validate
+ * @param {string} config.locale
  * @returns {boolean}
  */
-function getInputValidity({ allowEmpty, invalid, value, max, min }) {
+function getInputValidity({
+  allowEmpty,
+  invalid,
+  value,
+  max,
+  min,
+  validate,
+  locale,
+}) {
+  if (typeof validate === 'function') {
+    const result = validate(value, locale);
+    if (result === false) {
+      return false; // immediate invalid
+    }
+    // If true or undefined, continue to further validations
+  }
+
   if (invalid) {
     return false;
   }

packages/react/src/components/NumberInput/__tests__/NumberInput-test.js

@@ -11,6 +11,7 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import React, { useState } from 'react';
 import { NumberInput } from '../NumberInput';
+import { validateNumberSeparators } from '../NumberInput';
 import { AILabel } from '../../AILabel';
 
 function translateWithId(id) {
@@ -1470,6 +1471,46 @@ describe('NumberInput', () => {
         await userEvent.click(screen.getByLabelText('increment'));
         expect(input).toHaveValue('20%');
       });
+      it('should throw an error if group seperator is in wrong position', async () => {
+        render(
+          <NumberInput
+            type="text"
+            label="NumberInput label"
+            id="number-input"
+            value=""
+            step={1}
+            validate={validateNumberSeparators}
+            translateWithId={translateWithId}
+            invalidText="test-invalid-text"
+          />
+        );
+        const input = screen.getByLabelText('NumberInput label');
+        await userEvent.type(input, '1,1');
+        await userEvent.tab();
+        expect(screen.getByText('test-invalid-text')).toBeInTheDocument();
+        expect(screen.getByRole('textbox')).toHaveAttribute('data-invalid');
+      });
+
+      it('should throw an error if group seperator is in wrong position for given locale', async () => {
+        render(
+          <NumberInput
+            type="text"
+            label="NumberInput label"
+            id="number-input"
+            locale="DE"
+            value=""
+            step={1}
+            validate={validateNumberSeparators}
+            translateWithId={translateWithId}
+            invalidText="test-invalid-text"
+          />
+        );
+        const input = screen.getByLabelText('NumberInput label');
+        await userEvent.type(input, '1.1');
+        await userEvent.tab();
+        expect(screen.getByText('test-invalid-text')).toBeInTheDocument();
+        expect(screen.getByRole('textbox')).toHaveAttribute('data-invalid');
+      });
     });
   });
 });