@carbon/ibm-products/es/components/BigNumbers/BigNumbers.js

Carbon for IBM Products

/**
 * Copyright IBM Corp. 2020, 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 { extends as _extends } from '../../_virtual/_rollupPluginBabelHelpers.js';
import React__default, { forwardRef } from 'react';
import PropTypes from '../../_virtual/index.js';
import cx from 'classnames';
import { getDevtoolsProps } from '../../global/js/utils/devtools.js';
import { getSupportedLocale } from '../../global/js/utils/getSupportedLocale.js';
import { pkg } from '../../settings.js';
import { Information, ArrowUp } from '@carbon/react/icons';
import { Tooltip } from '@carbon/react';
import { BigNumbersSkeleton } from './BigNumbersSkeleton.js';
import { DefaultLocale, formatValue, Characters, getIconSize } from './constants.js';
import { TooltipTrigger } from '../TooltipTrigger/TooltipTrigger.js';

var _Information;
const blockClass = `${pkg.prefix}--big-numbers`;
const componentName = 'BigNumbers';

// NOTE: the component SCSS is not imported here: it is rolled up separately.

/**
 * BigNumbers is used to display large values in a small area. The display of
 * values can be the value itself, or grouped in a `numerator/denominator` fashion.
 * Control over the total fraction decimals displayed as well as how the
 * values/totals are displayed are done via a locale prop. Other optional props
 * allow control over size, truncation, if the value is a percentage, the addition
 * of a button as well as tool tip functionality.
 * The default locale is English (`en-US`) if one is not provided or if the provided one is not supported.
 */
let BigNumbers = /*#__PURE__*/forwardRef((_ref, ref) => {
  let {
    // The component props, in alphabetical order (for consistency).
    className,
    forceShowTotal = false,
    fractionDigits = 1,
    iconButton,
    loading = false,
    label,
    locale = DefaultLocale,
    percentage = false,
    size = 'default',
    tooltipDescription,
    total,
    trending = false,
    truncate = true,
    value,
    // Collect any other property values passed in.
    ...rest
  } = _ref;
  const bigNumbersClasses = cx(className, {
    [`${blockClass}--lg`]: size === 'lg',
    [`${blockClass}--xl`]: size === 'xl'
  });
  const supportedLocale = getSupportedLocale(locale, DefaultLocale);
  const truncatedValue = formatValue(supportedLocale, value, fractionDigits, truncate) ?? Characters.Dash;
  const truncatedTotal = formatValue(supportedLocale, total, fractionDigits, truncate) ?? 'Unknown';
  const shouldDisplayDenominator = forceShowTotal || !percentage && total && value && total > value && truncatedValue !== truncatedTotal;
  if (loading) {
    return /*#__PURE__*/React__default.createElement(BigNumbersSkeleton, _extends({}, rest, {
      ref: ref,
      className: className,
      size: size
    }, getDevtoolsProps(componentName)));
  }
  return /*#__PURE__*/React__default.createElement("div", _extends({}, rest, {
    className: cx(blockClass, bigNumbersClasses, className),
    ref: ref
  }, getDevtoolsProps(componentName)), /*#__PURE__*/React__default.createElement("span", {
    className: `${blockClass}__row`
  }, /*#__PURE__*/React__default.createElement("h4", {
    className: `${blockClass}__label`
  }, label), tooltipDescription && /*#__PURE__*/React__default.createElement(Tooltip, {
    description: tooltipDescription,
    align: "right",
    className: `${blockClass}__info`
  }, /*#__PURE__*/React__default.createElement(TooltipTrigger, {
    className: `${blockClass}__tooltip-trigger`
  }, _Information || (_Information = /*#__PURE__*/React__default.createElement(Information, {
    size: 16
  }))))), /*#__PURE__*/React__default.createElement("span", {
    className: `${blockClass}__row`,
    role: "math"
  }, trending && /*#__PURE__*/React__default.createElement(ArrowUp, {
    className: `${blockClass}__trend`,
    size: getIconSize(size)
  }), /*#__PURE__*/React__default.createElement("span", {
    className: `${blockClass}__value`
  }, percentage ? /*#__PURE__*/React__default.createElement("div", {
    className: `${blockClass}__percentage`
  }, truncatedValue, /*#__PURE__*/React__default.createElement("span", {
    className: `${blockClass}__percentage-mark`
  }, "%")) : truncatedValue), shouldDisplayDenominator && /*#__PURE__*/React__default.createElement("span", {
    className: `${blockClass}__total`
  }, /*#__PURE__*/React__default.createElement("span", null, `${Characters.Slash}${truncatedTotal}`)), /*#__PURE__*/React__default.createElement("span", {
    className: `${blockClass}__icon-button`
  }, iconButton)));
});

// Return a placeholder if not released and not enabled by feature flag
BigNumbers = pkg.checkComponentEnabled(BigNumbers, componentName);

// The display name of the component, used by React. Note that displayName
// is used in preference to relying on function.name.
BigNumbers.displayName = componentName;

// The types and DocGen commentary for the component props,
// in alphabetical order (for consistency).
// See https://www.npmjs.com/package/prop-types#usage.
BigNumbers.propTypes = {
  /**
   * Provide an optional class to be applied to the containing node.
   */
  className: PropTypes.string,
  /**
   * The default behavior will hide `total` if `undefined` or is the same as `value`.
   *
   * Set to `true` to ignore the default behavior and show the `total`.
   */
  forceShowTotal: PropTypes.bool,
  /**
   * Specifies the number of fraction digits when truncating `value` and `total`.
   */
  fractionDigits: PropTypes.number,
  /**
   * Displays an icon button next to `value`.
   */
  iconButton: PropTypes.node,
  /**
   * Text label above the `value`.
   */
  label: PropTypes.string.isRequired,
  /**
   * When `true`, will show the loading state.
   */
  loading: PropTypes.bool,
  /**
   * Determines how `value` and `total` will be formatted.
   */
  locale: PropTypes.string,
  /**
   * Appends a percent sign (_%_) after `value` and hides `total`.
   */
  percentage: PropTypes.bool,
  /**
   *
   */
  size: PropTypes.oneOf(['default', 'lg', 'xl']),
  /**
   * When applied, an information icon will be rendered next to the
   * `label` and the description will be applied to its tooltip.
   */
  tooltipDescription: PropTypes.string,
  /**
   * The number that will appear after the slash (i.e. the "denominator" of a fraction).
   *
   * This number will not be rendered if it's the same as `value` or
   * `percentage` is true. See also the **forceShowTotal** prop.
   */
  total: PropTypes.number,
  /**
   * When `true`, will render a "trending up" icon.
   */
  trending: PropTypes.bool,
  /**
   * Abbreviates the number when `true`. E.g. from _1,000_ to _1K_.
   */
  truncate: PropTypes.bool,
  /**
   * The primary value to display (or the "numerator" of a fraction).
   */
  value: PropTypes.number
};

export { BigNumbers };