@carbon/ibm-products/lib/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.
 */

'use strict';

var _rollupPluginBabelHelpers = require('../../_virtual/_rollupPluginBabelHelpers.js');
var React = require('react');
var index = require('../../_virtual/index.js');
var cx = require('classnames');
var devtools = require('../../global/js/utils/devtools.js');
var getSupportedLocale = require('../../global/js/utils/getSupportedLocale.js');
var settings = require('../../settings.js');
var icons = require('@carbon/react/icons');
var react = require('@carbon/react');
var BigNumbersSkeleton = require('./BigNumbersSkeleton.js');
var constants = require('./constants.js');
var TooltipTrigger = require('../TooltipTrigger/TooltipTrigger.js');

var _Information;
const blockClass = `${settings.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.
 */
exports.BigNumbers = /*#__PURE__*/React.forwardRef((_ref, ref) => {
  let {
    // The component props, in alphabetical order (for consistency).
    className,
    forceShowTotal = false,
    fractionDigits = 1,
    iconButton,
    loading = false,
    label,
    locale = constants.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.getSupportedLocale(locale, constants.DefaultLocale);
  const truncatedValue = constants.formatValue(supportedLocale, value, fractionDigits, truncate) ?? constants.Characters.Dash;
  const truncatedTotal = constants.formatValue(supportedLocale, total, fractionDigits, truncate) ?? 'Unknown';
  const shouldDisplayDenominator = forceShowTotal || !percentage && total && value && total > value && truncatedValue !== truncatedTotal;
  if (loading) {
    return /*#__PURE__*/React.createElement(BigNumbersSkeleton.BigNumbersSkeleton, _rollupPluginBabelHelpers.extends({}, rest, {
      ref: ref,
      className: className,
      size: size
    }, devtools.getDevtoolsProps(componentName)));
  }
  return /*#__PURE__*/React.createElement("div", _rollupPluginBabelHelpers.extends({}, rest, {
    className: cx(blockClass, bigNumbersClasses, className),
    ref: ref
  }, devtools.getDevtoolsProps(componentName)), /*#__PURE__*/React.createElement("span", {
    className: `${blockClass}__row`
  }, /*#__PURE__*/React.createElement("h4", {
    className: `${blockClass}__label`
  }, label), tooltipDescription && /*#__PURE__*/React.createElement(react.Tooltip, {
    description: tooltipDescription,
    align: "right",
    className: `${blockClass}__info`
  }, /*#__PURE__*/React.createElement(TooltipTrigger.TooltipTrigger, {
    className: `${blockClass}__tooltip-trigger`
  }, _Information || (_Information = /*#__PURE__*/React.createElement(icons.Information, {
    size: 16
  }))))), /*#__PURE__*/React.createElement("span", {
    className: `${blockClass}__row`,
    role: "math"
  }, trending && /*#__PURE__*/React.createElement(icons.ArrowUp, {
    className: `${blockClass}__trend`,
    size: constants.getIconSize(size)
  }), /*#__PURE__*/React.createElement("span", {
    className: `${blockClass}__value`
  }, percentage ? /*#__PURE__*/React.createElement("div", {
    className: `${blockClass}__percentage`
  }, truncatedValue, /*#__PURE__*/React.createElement("span", {
    className: `${blockClass}__percentage-mark`
  }, "%")) : truncatedValue), shouldDisplayDenominator && /*#__PURE__*/React.createElement("span", {
    className: `${blockClass}__total`
  }, /*#__PURE__*/React.createElement("span", null, `${constants.Characters.Slash}${truncatedTotal}`)), /*#__PURE__*/React.createElement("span", {
    className: `${blockClass}__icon-button`
  }, iconButton)));
});

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

// The display name of the component, used by React. Note that displayName
// is used in preference to relying on function.name.
exports.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.
exports.BigNumbers.propTypes = {
  /**
   * Provide an optional class to be applied to the containing node.
   */
  className: index.default.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: index.default.bool,
  /**
   * Specifies the number of fraction digits when truncating `value` and `total`.
   */
  fractionDigits: index.default.number,
  /**
   * Displays an icon button next to `value`.
   */
  iconButton: index.default.node,
  /**
   * Text label above the `value`.
   */
  label: index.default.string.isRequired,
  /**
   * When `true`, will show the loading state.
   */
  loading: index.default.bool,
  /**
   * Determines how `value` and `total` will be formatted.
   */
  locale: index.default.string,
  /**
   * Appends a percent sign (_%_) after `value` and hides `total`.
   */
  percentage: index.default.bool,
  /**
   *
   */
  size: index.default.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: index.default.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: index.default.number,
  /**
   * When `true`, will render a "trending up" icon.
   */
  trending: index.default.bool,
  /**
   * Abbreviates the number when `true`. E.g. from _1,000_ to _1K_.
   */
  truncate: index.default.bool,
  /**
   * The primary value to display (or the "numerator" of a fraction).
   */
  value: index.default.number
};