@carbon/react 1.83.0 → 1.84.0-rc.0

package/es/components/NumberInput/NumberFormatPropTypes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright IBM Corp. 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import PropTypes from 'prop-types';
+export declare const NumberFormatOptionsPropType: PropTypes.Requireable<PropTypes.InferProps<{
+    localeMatcher: PropTypes.Requireable<string>;
+    style: PropTypes.Requireable<string>;
+    currency: PropTypes.Requireable<string>;
+    currencyDisplay: PropTypes.Requireable<string>;
+    currencySign: PropTypes.Requireable<string>;
+    unit: PropTypes.Requireable<string>;
+    unitDisplay: PropTypes.Requireable<string>;
+    notation: PropTypes.Requireable<string>;
+    compactDisplay: PropTypes.Requireable<string>;
+    signDisplay: PropTypes.Requireable<string>;
+    minimumIntegerDigits: PropTypes.Requireable<number>;
+    minimumFractionDigits: PropTypes.Requireable<number>;
+    maximumFractionDigits: PropTypes.Requireable<number>;
+    minimumSignificantDigits: PropTypes.Requireable<number>;
+    maximumSignificantDigits: PropTypes.Requireable<number>;
+    useGrouping: PropTypes.Requireable<NonNullable<string | boolean | null | undefined>>;
+    numberingSystem: PropTypes.Requireable<string>;
+    roundingIncrement: PropTypes.Requireable<number>;
+    roundingMode: PropTypes.Requireable<string>;
+    trailingZeroDisplay: PropTypes.Requireable<string>;
+}>>;

package/es/components/NumberInput/NumberFormatPropTypes.js

@@ -0,0 +1,40 @@
+/**
+ * Copyright IBM Corp. 2016, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import PropTypes from 'prop-types';
+
+const NumberFormatOptionsPropType = PropTypes.shape({
+  // Locale Options
+  localeMatcher: PropTypes.oneOf(['best fit', 'lookup']),
+  // Style Options
+  style: PropTypes.oneOf(['decimal', 'currency', 'percent', 'unit']),
+  currency: PropTypes.string,
+  // e.g., 'USD'
+  currencyDisplay: PropTypes.oneOf(['symbol', 'narrowSymbol', 'code', 'name']),
+  currencySign: PropTypes.oneOf(['standard', 'accounting']),
+  unit: PropTypes.string,
+  // e.g., 'liter', 'mile-per-hour'
+  unitDisplay: PropTypes.oneOf(['short', 'narrow', 'long']),
+  notation: PropTypes.oneOf(['standard', 'scientific', 'engineering', 'compact']),
+  compactDisplay: PropTypes.oneOf(['short', 'long']),
+  signDisplay: PropTypes.oneOf(['auto', 'never', 'always', 'exceptZero']),
+  // Digit Options
+  minimumIntegerDigits: PropTypes.number,
+  minimumFractionDigits: PropTypes.number,
+  maximumFractionDigits: PropTypes.number,
+  minimumSignificantDigits: PropTypes.number,
+  maximumSignificantDigits: PropTypes.number,
+  useGrouping: PropTypes.oneOfType([PropTypes.bool, PropTypes.oneOf(['always', 'auto', 'min2'])]),
+  // Misc/Other Options
+  numberingSystem: PropTypes.string,
+  // e.g., 'latn', 'arab'
+  roundingIncrement: PropTypes.number,
+  roundingMode: PropTypes.oneOf(['ceil', 'floor', 'expand', 'trunc', 'halfCeil', 'halfFloor', 'halfExpand', 'halfTrunc', 'halfEven']),
+  trailingZeroDisplay: PropTypes.oneOf(['auto', 'stripIfInteger'])
+});
+
+export { NumberFormatOptionsPropType };

package/es/components/NumberInput/NumberInput.Skeleton.js

@@ -11,13 +11,12 @@ import React from 'react';
 import cx from 'classnames';
 import { usePrefix } from '../../internal/usePrefix.js';
 
-function NumberInputSkeleton(_ref) {
-  let {
-    hideLabel,
-    className,
-    size = 'md',
-    ...rest
-  } = _ref;
+function NumberInputSkeleton({
+  hideLabel,
+  className,
+  size = 'md',
+  ...rest
+}) {
   const prefix = usePrefix();
   return /*#__PURE__*/React.createElement("div", _extends({
     className: cx(`${prefix}--form-item`, className)

package/es/components/NumberInput/NumberInput.d.ts

@@ -6,6 +6,7 @@
  */
 import React, { ReactNode } from 'react';
 import { TranslateWithId } from '../../types/common';
+import { type NumberFormatOptions } from '@carbon/utilities';
 export declare const translationIds: {
     readonly 'increment.number': "increment.number";
     readonly 'decrement.number': "decrement.number";
@@ -25,7 +26,8 @@ export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInp
      */
     className?: string;
     /**
-     * **Experimental**: Provide a `decorator` component to be rendered inside the `TextInput` component
+     * **Experimental**: Provide a `decorator` component to be rendered inside the
+     * `TextInput` component
      */
     decorator?: ReactNode;
     /**
@@ -40,6 +42,13 @@ export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInp
      * Specify if the control should be disabled, or not
      */
     disabled?: boolean;
+    /**
+     * **Experimental:** Specify Intl.NumberFormat options applied to internal
+     * number parsing and formatting. Use with `type="text"`, has no effect when
+     * `type="number"`.
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
+     */
+    formatOptions?: NumberFormatOptions;
     /**
      * Provide text that is used alongside the control label for additional help
      */
@@ -60,6 +69,12 @@ export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInp
      * Specify a custom `id` for the input
      */
     id: string;
+    /**
+     * Instruct the browser which keyboard to display on mobile devices. Note that
+     * standard numeric keyboards vary across devices and operating systems.
+     * @see https://css-tricks.com/everything-you-ever-wanted-to-know-about-inputmode/
+     */
+    inputMode?: React.HTMLAttributes<HTMLInputElement>['inputMode'];
     /**
      * Specify if the currently value is invalid.
      */
@@ -77,9 +92,16 @@ export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInp
      * `true` to use the light version.
      *
      * @deprecated The `light` prop for `NumberInput` is no longer needed and has
-     *     been deprecated in v11 in favor of the new `Layer` component. It will be moved in the next major release.
+     * been deprecated in v11 in favor of the new `Layer` component. It will be
+     * removed in the next major release.
      */
     light?: boolean;
+    /**
+     * **Experimental:** Specify a [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt)
+     * language code for parsing and formatting. Use with `type="text"`, has no
+     * effect when `type="number"`.
+     */
+    locale?: string;
     /**
      * The maximum value.
      */
@@ -91,9 +113,12 @@ export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInp
     /**
      * Provide an optional handler that is called when the internal state of
      * NumberInput changes. This handler is called with event and state info.
+     * When type="number", this is called on every change of the input.
+     * When type="text", this is only called on blur after the number has been
+     * parsed and formatted.
      * `(event, { value, direction }) => void`
      */
-    onChange?: (event: React.MouseEvent<HTMLButtonElement>, state: {
+    onChange?: (event: React.MouseEvent<HTMLButtonElement> | React.FocusEvent<HTMLInputElement> | React.KeyboardEvent<HTMLInputElement>, state: {
         value: number | string;
         direction: string;
     }) => void;
@@ -108,6 +133,11 @@ export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInp
      * Provide an optional function to be called when a key is pressed in the number input
      */
     onKeyUp?: React.KeyboardEventHandler<HTMLInputElement>;
+    /**
+     * When type="text", provide an optional pattern to restrict user input. Has
+     * no effect when type="number".
+     */
+    pattern?: string;
     /**
      * Specify if the component should be read-only
      */
@@ -125,6 +155,12 @@ export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInp
      * Specify how much the values should increase/decrease upon clicking on up/down button
      */
     step?: number;
+    /**
+     * **Experimental**: Specify if the input should be of type text or number.
+     * Use type="text" with `locale`, `formatOptions`, and guide user input with
+     * `pattern` and `inputMode`.
+     */
+    type?: 'number' | 'text';
     /**
      * Specify the value of the input
      */

package/es/components/NumberInput/NumberInput.js

@@ -9,7 +9,7 @@ import { extends as _extends } from '../../_virtual/_rollupPluginBabelHelpers.js
 import { Subtract, Add } from '@carbon/icons-react';
 import cx from 'classnames';
 import PropTypes from 'prop-types';
-import React, { useContext, useState, useRef, useEffect } from 'react';
+import React, { useContext, useState, useMemo, useCallback, useRef, useEffect } from 'react';
 import { useMergedRefs } from '../../internal/useMergedRefs.js';
 import { useNormalizedInputProps } from '../../internal/useNormalizedInputProps.js';
 import { usePrefix } from '../../internal/usePrefix.js';
@@ -18,6 +18,11 @@ import '../FluidForm/FluidForm.js';
 import { FormContext } from '../FluidForm/FormContext.js';
 import '../Text/index.js';
 import { clamp } from '../../internal/clamp.js';
+import { useControllableState } from '../../internal/useControllableState.js';
+import { NumberParser, NumberFormatter } from '@carbon/utilities';
+import { ArrowUp, ArrowDown } from '../../internal/keyboard/keys.js';
+import { match } from '../../internal/keyboard/match.js';
+import { NumberFormatOptionsPropType } from './NumberFormatPropTypes.js';
 import { Text } from '../Text/Text.js';
 
 var _Subtract, _Add;
@@ -42,25 +47,30 @@ const NumberInput = /*#__PURE__*/React.forwardRef(function NumberInput(props, fo
     disabled = false,
     disableWheel: disableWheelProp = false,
     defaultValue = 0,
+    formatOptions,
     helperText = '',
     hideLabel = false,
     hideSteppers,
     iconDescription,
     id,
-    label,
+    inputMode,
     invalid = false,
     invalidText,
+    label,
     light,
+    locale = 'en-US',
     max,
     min,
     onChange,
     onClick,
     onKeyUp,
+    pattern = '[0-9]*',
     readOnly,
     size = 'md',
     slug,
     step = 1,
     translateWithId: t = id => defaultTranslations[id],
+    type = 'number',
     warn = false,
     warnText = '',
     value: controlledValue,
@@ -71,6 +81,10 @@ const NumberInput = /*#__PURE__*/React.forwardRef(function NumberInput(props, fo
     isFluid
   } = useContext(FormContext);
   const [isFocused, setIsFocused] = useState(false);
+
+  /**
+   * The input value, only used when type=number
+   */
   const [value, setValue] = useState(() => {
     if (controlledValue !== undefined) {
       return controlledValue;
@@ -84,6 +98,30 @@ const NumberInput = /*#__PURE__*/React.forwardRef(function NumberInput(props, fo
     return 0;
   });
   const [prevControlledValue, setPrevControlledValue] = useState(controlledValue);
+  const numberParser = useMemo(() => new NumberParser(locale, formatOptions), [locale, formatOptions]);
+  /**
+   * The currently parsed number value.
+   * Only used when type=text
+   * Updated based on the `value` as the user types.
+   */
+  const [numberValue, setNumberValue, isControlled] = useControllableState({
+    name: 'NumberInput',
+    defaultValue: typeof defaultValue === 'string' ? numberParser.parse(defaultValue) : defaultValue,
+    value: typeof controlledValue === 'string' ? numberParser.parse(controlledValue) : controlledValue
+  });
+
+  /**
+   * The current text value of the input.
+   * Only used when type=text
+   * Updated as the user types and formatted on blur.
+   */
+  const [inputValue, setInputValue] = React.useState(() => isNaN(numberValue) ? '' : new NumberFormatter(locale, formatOptions).format(numberValue));
+  const numberingSystem = useMemo(() => numberParser.getNumberingSystem(inputValue), [numberParser, inputValue]);
+  const numberFormatter = useMemo(() => new NumberFormatter(locale, {
+    ...formatOptions,
+    numberingSystem
+  }), [locale, formatOptions, numberingSystem]);
+  const format = useCallback(value => isNaN(value) || value === null ? '' : numberFormatter.format(value), [numberFormatter]);
   const inputRef = useRef(null);
   const ref = useMergedRefs([forwardRef, inputRef]);
   const numberInputClasses = cx({
@@ -98,7 +136,7 @@ const NumberInput = /*#__PURE__*/React.forwardRef(function NumberInput(props, fo
   const isInputValid = getInputValidity({
     allowEmpty,
     invalid,
-    value,
+    value: type === 'number' ? value : numberValue,
     max,
     min
   });
@@ -140,13 +178,24 @@ const NumberInput = /*#__PURE__*/React.forwardRef(function NumberInput(props, fo
     if (disabled) {
       return;
     }
-    const state = {
-      value: allowEmpty && event.target.value === '' ? '' : Number(event.target.value),
-      direction: value < event.target.value ? 'up' : 'down'
-    };
-    setValue(state.value);
-    if (onChange) {
-      onChange(event, state);
+    if (type === 'number') {
+      const state = {
+        value: allowEmpty && event.target.value === '' ? '' : Number(event.target.value),
+        direction: value < event.target.value ? 'up' : 'down'
+      };
+      setValue(state.value);
+      if (onChange) {
+        onChange(event, state);
+      }
+      return;
+    }
+    if (type === 'text') {
+      const _value = allowEmpty && event.target.value === '' ? '' : event.target.value;
+      setNumberValue(numberParser.parse(_value));
+      setInputValue(_value);
+      // The onChange prop isn't called here because it will be called on blur
+      // or on click of a stepper, after the number is parsed and formatted
+      // according to the locale.
     }
   }
   const handleFocus = evt => {
@@ -168,21 +217,44 @@ const NumberInput = /*#__PURE__*/React.forwardRef(function NumberInput(props, fo
     const parts = num.toString().split('.');
     return parts[1] ? parts[1].length : 0;
   };
-  const handleStepperClick = (event, direction) => {
+  const handleStep = (event, direction) => {
     if (inputRef.current) {
-      const currentValue = Number(inputRef.current.value);
+      const currentValue = type === 'number' ? Number(inputRef.current.value) : numberParser.parse(inputRef.current.value);
       const rawValue = direction === 'up' ? currentValue + step : currentValue - step;
       const precision = Math.max(getDecimalPlaces(currentValue), getDecimalPlaces(step));
       const floatValue = parseFloat(rawValue.toFixed(precision));
       const newValue = clamp(floatValue, min ?? -Infinity, max ?? Infinity);
-      const state = {
-        value: allowEmpty && inputRef.current.value === '' && step === 0 ? '' : newValue,
-        direction
-      };
-      setValue(state.value);
+      let state;
+      if (type === 'number') {
+        state = {
+          value: allowEmpty && inputRef.current.value === '' && step === 0 ? '' : newValue,
+          direction
+        };
+        setValue(state.value);
+      }
+      if (type === 'text') {
+        const formattedNewValue = format(newValue);
+        state = {
+          value: allowEmpty && inputRef.current.value === '' && step === 0 ? '' : formattedNewValue,
+          direction
+        };
+
+        // newValue does not need to be parsed because it is derived from
+        // currentValue, which is parsed at the beginning of this function
+        setNumberValue(newValue);
+        setInputValue(formattedNewValue);
+      }
       if (onChange) {
         onChange(event, state);
       }
+      return state;
+    }
+  };
+  const handleStepperClick = (event, direction) => {
+    if (inputRef.current) {
+      const {
+        state
+      } = handleStep(event, direction);
       if (onClick) {
         onClick(event, state);
       }
@@ -234,6 +306,15 @@ const NumberInput = /*#__PURE__*/React.forwardRef(function NumberInput(props, fo
     onClick: onClick,
     onChange: handleOnChange,
     onKeyUp: onKeyUp,
+    onKeyDown: e => {
+      if (type === 'text') {
+        match(e, ArrowUp) && handleStep(e, 'up');
+        match(e, ArrowDown) && handleStep(e, 'down');
+      }
+      if (rest?.onKeyDown) {
+        rest?.onKeyDown(e);
+      }
+    },
     onFocus: e => {
       if (disableWheelProp) {
         e.target.addEventListener('wheel', disableWheel);
@@ -246,15 +327,32 @@ const NumberInput = /*#__PURE__*/React.forwardRef(function NumberInput(props, fo
       if (disableWheelProp) {
         e.target.removeEventListener('wheel', disableWheel);
       }
+      if (type === 'text') {
+        // When isControlled, the current inputValue needs re-parsed
+        // because the consumer's onChange hasn't been called yet and
+        // the `numberValue` we have in state is the (stale) value
+        // they've passed in.
+        const _numberValue = isControlled ? numberParser.parse(inputValue) : numberValue;
+        const formattedValue = isNaN(_numberValue) ? '' : format(_numberValue);
+        setInputValue(formattedValue);
+        if (onChange) {
+          const state = {
+            value: formattedValue,
+            direction: value < e.target.value ? 'up' : 'down'
+          };
+          onChange(e, state);
+        }
+      }
       if (rest.onBlur) {
         rest.onBlur(e);
       }
     },
-    pattern: "[0-9]*",
+    pattern: pattern,
+    inputMode: inputMode,
     readOnly: readOnly,
     step: step,
-    type: "number",
-    value: value
+    type: type,
+    value: type === 'number' ? value : inputValue
   })), slug ? normalizedDecorator : decorator ? /*#__PURE__*/React.createElement("div", {
     className: `${prefix}--number__input-inner-wrapper--decorator`
   }, normalizedDecorator) : '', Icon ? /*#__PURE__*/React.createElement(Icon, {
@@ -311,13 +409,20 @@ NumberInput.propTypes = {
    */
   defaultValue: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
   /**
-   * Specify if the wheel functionality for the input should be disabled, or not
+   * Specify if the wheel functionality for the input should be disabled, or no t
    */
   disableWheel: PropTypes.bool,
   /**
    * Specify if the control should be disabled, or not
    */
   disabled: PropTypes.bool,
+  /**
+   * **Experimental:** Specify Intl.NumberFormat options applied to internal
+   * number parsing and formatting. Use with `type="text"`, has no effect when
+   * `type="number"`.
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
+   */
+  formatOptions: NumberFormatOptionsPropType,
   /**
    * Provide text that is used alongside the control label for additional help
    */
@@ -338,6 +443,12 @@ NumberInput.propTypes = {
    * Specify a custom `id` for the input
    */
   id: PropTypes.string.isRequired,
+  /**
+   * Instruct the browser which keyboard to display on mobile devices. Note that
+   * standard numeric keyboards vary across devices and operating systems.
+   * @see https://css-tricks.com/everything-you-ever-wanted-to-know-about-inputmode/
+   */
+  inputMode: PropTypes.oneOf(['none', 'text', 'tel', 'url', 'email', 'numeric', 'decimal', 'search']),
   /**
    * Specify if the currently value is invalid.
    */
@@ -355,6 +466,12 @@ NumberInput.propTypes = {
    * `true` to use the light version.
    */
   light: deprecate(PropTypes.bool, 'The `light` prop for `NumberInput` is no longer needed and has ' + 'been deprecated in v11 in favor of the new `Layer` component. It will be moved in the next major release.'),
+  /**
+   * **Experimental:** Specify a [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt)
+   * language code for parsing and formatting. Use with `type="text"`, has no
+   * effect when `type="number"`.
+   */
+  locale: PropTypes.string,
   /**
    * The maximum value.
    */
@@ -366,6 +483,9 @@ NumberInput.propTypes = {
   /**
    * Provide an optional handler that is called when the internal state of
    * NumberInput changes. This handler is called with event and state info.
+   * When type="number", this is called on every change of the input.
+   * When type="text", this is only called on blur after the number has been
+   * parsed and formatted.
    * `(event, { value, direction }) => void`
    */
   onChange: PropTypes.func,
@@ -377,6 +497,11 @@ NumberInput.propTypes = {
    * Provide an optional function to be called when a key is pressed in the number input
    */
   onKeyUp: PropTypes.func,
+  /**
+   * When type="text", provide an optional pattern to restrict user input. Has
+   * no effect when type="number".
+   */
+  pattern: PropTypes.string,
   /**
    * Specify if the component should be read-only
    */
@@ -386,17 +511,25 @@ NumberInput.propTypes = {
    */
   size: PropTypes.oneOf(['sm', 'md', 'lg']),
   /**
-   * **Experimental**: Provide a `Slug` component to be rendered inside the `NumberInput` component
+   * **Experimental**: Provide a `Slug` component to be rendered inside the
+   * `NumberInput` component
    */
   slug: deprecate(PropTypes.node, 'The `slug` prop for `NumberInput` is no longer needed and has ' + 'been deprecated in v11 in favor of the new `decorator` prop. It will be moved in the next major release.'),
   /**
-   * Specify how much the values should increase/decrease upon clicking on up/down button
+   * Specify how much the values should increase/decrease upon clicking on
+   * up/down button
    */
   step: PropTypes.number,
   /**
    * Provide custom text for the component for each translation id
    */
   translateWithId: PropTypes.func,
+  /**
+   * **Experimental**: Specify if the input should be of type text or number.
+   * Use type="text" with `locale`, `formatOptions`, and guide user input with
+   * `pattern` and `inputMode`.
+   */
+  type: PropTypes.oneOf(['number', 'text']),
   /**
    * Specify the value of the input
    */
@@ -410,13 +543,12 @@ NumberInput.propTypes = {
    */
   warnText: PropTypes.node
 };
-const Label = _ref => {
-  let {
-    disabled,
-    id,
-    hideLabel,
-    label
-  } = _ref;
+const Label = ({
+  disabled,
+  id,
+  hideLabel,
+  label
+}) => {
   const prefix = usePrefix();
   const className = cx({
     [`${prefix}--label`]: true,
@@ -438,12 +570,11 @@ Label.propTypes = {
   id: PropTypes.string,
   label: PropTypes.node
 };
-function HelperText(_ref2) {
-  let {
-    disabled,
-    description,
-    id
-  } = _ref2;
+function HelperText({
+  disabled,
+  description,
+  id
+}) {
   const prefix = usePrefix();
   const className = cx(`${prefix}--form__helper-text`, {
     [`${prefix}--form__helper-text--disabled`]: disabled
@@ -476,14 +607,13 @@ HelperText.propTypes = {
  * @param {number} config.min
  * @returns {boolean}
  */
-function getInputValidity(_ref3) {
-  let {
-    allowEmpty,
-    invalid,
-    value,
-    max,
-    min
-  } = _ref3;
+function getInputValidity({
+  allowEmpty,
+  invalid,
+  value,
+  max,
+  min
+}) {
   if (invalid) {
     return false;
   }

package/es/components/OrderedList/OrderedList.js

@@ -11,14 +11,13 @@ import React from 'react';
 import cx from 'classnames';
 import { usePrefix } from '../../internal/usePrefix.js';
 
-function OrderedList(_ref) {
-  let {
-    className,
-    nested = false,
-    native = false,
-    isExpressive = false,
-    ...other
-  } = _ref;
+function OrderedList({
+  className,
+  nested = false,
+  native = false,
+  isExpressive = false,
+  ...other
+}) {
   const prefix = usePrefix();
   const classNames = cx({
     [`${prefix}--list--ordered`]: !native,

package/es/components/OverflowMenu/OverflowMenu.d.ts

@@ -106,7 +106,7 @@ export interface OverflowMenuProps {
      */
     selectorPrimaryFocus?: string;
     /**
-     * Specify the size of the OverflowMenu. Currently supports either `sm`, 'md' (default) or 'lg` as an option.
+     * Specify the size of the OverflowMenu. Currently supports either `sm`, `md` (default) or `lg` as an option.
      */
     size?: 'sm' | 'md' | 'lg';
     /**