@sproutsocial/seeds-react-numeral 1.0.0

package/src/Numeral.stories.tsx

@@ -0,0 +1,169 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Numeral from "./Numeral";
+
+const localeOptions = [
+  "United States (en-US)",
+  "English (en)",
+  "Arabic (ar-EG)",
+  "Brazil (pt-BR)",
+  "India (en-IN)",
+  "French (fr-FR)",
+  "Spain (es-ES)",
+  "Mexico (es-MX)",
+  "Germany (de-DE)",
+  "German (de)",
+  "Japan (ja-JP)",
+  "Japanese (ja)",
+];
+
+const localeMapping = {
+  "United States (en-US)": "en-US",
+  "English (en)": "en",
+  "Arabic (ar-EG)": "ar-EG",
+  "Brazil (pt-BR)": "pt-BR",
+  "India (en-IN)": "en-IN",
+  "French (fr-FR)": "fr-FR",
+  "Spain (es-ES)": "es-ES",
+  "Mexico (es-MX)": "es-MX",
+  "Germany (de-DE)": "de-DE",
+  "German (de)": "de",
+  "Japan (ja-JP)": "ja-JP",
+  "Japanese (ja)": "ja",
+};
+
+const currencyOptions = [
+  "Egyptian £",
+  "European €",
+  "Indian ₹",
+  "Japanese ¥",
+  "USA $",
+];
+
+const currencyMapping = {
+  "Egyptian £": "EGP",
+  "European €": "EUR",
+  "Indian ₹": "INR",
+  "Japanese ¥": "JPY",
+  "USA $": "USD",
+};
+
+const formatOptions = ["decimal", "currency", "percent"];
+
+const formatMapping = {
+  decimal: "decimal",
+  currency: "currency",
+  percent: "percent",
+};
+
+const abbreviateOptions = [
+  "true",
+  "false",
+  " 500",
+  "1_000",
+  "10_000",
+  "100_000",
+];
+
+const abbreviateMapping = {
+  true: true,
+  false: false,
+  " 500": 500,
+  "1_000": 1000,
+  "10_000": 10000,
+  "100_000": 100000,
+};
+
+const precisionOptions = ["0", "1", "2", "3", "6", "none"];
+
+const precisionMapping = {
+  "0": 0,
+  "1": 1,
+  "2": 2,
+  "3": 3,
+  "6": 6,
+  none: "none",
+};
+
+const meta: Meta<typeof Numeral> = {
+  title: "Components/Numeral",
+  component: Numeral,
+  argTypes: {
+    locale: {
+      control: "select",
+      options: localeOptions,
+      mapping: localeMapping,
+    },
+    format: {
+      control: "select",
+      options: formatOptions,
+      mapping: formatMapping,
+    },
+    currency: {
+      control: "select",
+      options: currencyOptions,
+      mapping: currencyMapping,
+    },
+    abbreviate: {
+      control: "select",
+      options: abbreviateOptions,
+      mapping: abbreviateMapping,
+    },
+    precision: {
+      control: "select",
+      options: precisionOptions,
+      mapping: precisionMapping,
+    },
+  },
+  args: {
+    color: "text.headline",
+    number: 12.89,
+    invalidNumberLabel: "Not available",
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Numeral>;
+
+export const Default: Story = {};
+
+export const Total: Story = {
+  args: {
+    number: 100,
+    fontWeight: "semibold",
+    fontSize: 500,
+  },
+};
+
+export const Trend: Story = {
+  args: {
+    number: 100,
+    color: "teal.500",
+  },
+};
+
+export const NoPrecision: Story = {
+  args: {
+    number: 123.45678,
+    precision: "none",
+  },
+};
+
+export const CurrencyPrecision: Story = {
+  args: {
+    number: 123.4,
+    format: "currency",
+  },
+};
+
+export const Invalid: Story = {
+  args: {
+    number: null,
+  },
+};
+
+export const AbbreviatedNegative: Story = {
+  args: {
+    number: -123456.789,
+    abbreviate: true,
+  },
+};

package/src/Numeral.tsx

@@ -0,0 +1,208 @@
+import * as React from "react";
+// @ts-expect-error lru-memoize is not typed
+import memoize from "lru-memoize";
+import { EM_DASH } from "./constants";
+import Tooltip from "@sproutsocial/seeds-react-tooltip";
+import type { TypeTextProps } from "@sproutsocial/seeds-react-text";
+import { VisuallyHidden } from "@sproutsocial/seeds-react-visually-hidden";
+
+import {
+  DEFAULT_THRESHOLD,
+  MEMO_CACHE_SIZE,
+  COMPARE_OBJECTS,
+  MAX_PRECISION,
+  ABBREV_PRECISION,
+  DefaultPrecisions,
+} from "./constants";
+import { AbbrContainer, Container } from "./styles";
+import type { EnumNumeralFormat, TypeNumeralProps } from "./NumeralTypes";
+
+interface TypeFormatOptions {
+  locale: string;
+  format: EnumNumeralFormat;
+  currency: string;
+  min: number;
+  max: number;
+}
+
+interface TypeFormatters {
+  standard: Intl.NumberFormat;
+  abbreviated: Intl.NumberFormat;
+}
+
+interface TypeArgs {
+  value: number;
+  canAbbreviate: boolean;
+  invalidNumberLabel?: string;
+  ariaLabel?: string;
+  options: TypeFormatOptions;
+  qa: object | null | undefined;
+  rest: Omit<TypeTextProps, "children">;
+}
+
+const _getNumberFormatters = (options: TypeFormatOptions): TypeFormatters => {
+  const { locale, format, currency, min, max } = options;
+  const compactPrecision = min === max ? min : ABBREV_PRECISION;
+
+  const _currency = format === "currency" ? currency : undefined;
+
+  const standard: Intl.NumberFormatOptions = {
+    style: format,
+    minimumFractionDigits: min,
+    maximumFractionDigits: max,
+    currency: _currency,
+  };
+  const compact: Intl.NumberFormatOptions = {
+    style: format,
+    minimumFractionDigits: compactPrecision,
+    maximumFractionDigits: compactPrecision,
+    currency: _currency,
+    notation: "compact",
+  };
+  // Safari 14.1 is currently throwing errors when trying to use the compact
+  // options of NumberFormat
+  // https://community.atlassian.com/t5/Trello-questions/Trello-stuck-at-loading-after-Safari-14-1-update-on-macOS-Mojave/qaq-p/1675577#M45687
+  let abbreviated;
+
+  try {
+    abbreviated = new Intl.NumberFormat(locale, compact);
+  } catch (error) {
+    abbreviated = new Intl.NumberFormat(locale, standard);
+  }
+
+  return {
+    standard: new Intl.NumberFormat(locale, standard),
+    abbreviated,
+  };
+};
+
+// Memoize to reduce the energy of creating new instances of Intl.NumberFormat
+const memoizer = memoize(MEMO_CACHE_SIZE, COMPARE_OBJECTS);
+const getNumberFormatters = memoizer(_getNumberFormatters);
+
+const getThreshold = (abbreviate: boolean | number): number => {
+  if (typeof abbreviate === "number")
+    return Math.max(1000, Math.abs(abbreviate));
+  if (abbreviate) return DEFAULT_THRESHOLD;
+  return Infinity;
+};
+
+const getMinMaxPrecision = (
+  precision: TypeNumeralProps["precision"],
+  format: EnumNumeralFormat
+): [number, number] => {
+  if (typeof precision === "number") return [precision, precision];
+  if (precision === "none") return [0, MAX_PRECISION];
+  return DefaultPrecisions[format];
+};
+
+const isValidNumber = (value: unknown): boolean => {
+  return typeof value === "number" && isFinite(value);
+};
+
+const normalizeArgs = (props: TypeNumeralProps): TypeArgs => {
+  const {
+    number,
+    locale = "us-EN",
+    format = props.currency ? "currency" : "decimal",
+    currency = "USD",
+    abbreviate = true,
+    invalidNumberLabel,
+    precision,
+    qa,
+    ...rest
+  } = props;
+  const threshold = getThreshold(abbreviate);
+  const [min, max] = getMinMaxPrecision(precision, format);
+
+  const _number = number || 0;
+
+  const value = _number * (format === "percent" ? 0.01 : 1);
+  const canAbbreviate = Math.abs(_number) >= threshold;
+  const options = {
+    locale,
+    format,
+    currency,
+    min,
+    max,
+  };
+
+  return {
+    value,
+    canAbbreviate,
+    invalidNumberLabel,
+    options,
+    qa,
+    rest,
+  };
+};
+
+const getNumeral = ({
+  returnType,
+  props,
+}: {
+  returnType: "string" | "component";
+  props: TypeNumeralProps;
+}): string | React.ReactNode => {
+  const isReturnTypeString = returnType === "string";
+  const { value, canAbbreviate, invalidNumberLabel, options, qa, rest } =
+    normalizeArgs(props);
+
+  if (!isValidNumber(props.number)) {
+    return isReturnTypeString ? (
+      EM_DASH
+    ) : (
+      <>
+        {invalidNumberLabel && (
+          // Give screen readers something useful to read off + hide the em dash
+          <VisuallyHidden>{invalidNumberLabel}</VisuallyHidden>
+        )}
+        <Container aria-hidden {...qa}>
+          {EM_DASH}
+        </Container>
+      </>
+    );
+  }
+
+  const formatters = getNumberFormatters(options);
+  const fullText = formatters.standard.format(value);
+
+  if (canAbbreviate) {
+    const abbreviatedText = formatters.abbreviated.format(value);
+
+    // The following are used to debug the skipped tests which are misbehaving!!!
+    // console.log({ fullText, abbreviatedText });
+    // console.log({ abbreviated: formatters.abbreviated.resolvedOptions() });
+    // The following check is necessary because each locale may have differing thresholds
+    // for which abbreviation begins.
+    if (abbreviatedText !== fullText) {
+      return isReturnTypeString ? (
+        abbreviatedText
+      ) : (
+        <Tooltip content={fullText}>
+          <AbbrContainer {...qa} {...rest}>
+            {abbreviatedText}
+          </AbbrContainer>
+        </Tooltip>
+      );
+    }
+  }
+
+  return isReturnTypeString ? (
+    fullText
+  ) : (
+    <Container {...qa} {...rest}>
+      {fullText}
+    </Container>
+  );
+};
+
+export const formatNumeral = (props: TypeNumeralProps): string => {
+  return getNumeral({ returnType: "string", props }) as string;
+};
+
+const Numeral = (props: TypeNumeralProps) => {
+  return getNumeral({ returnType: "component", props });
+};
+
+export default Numeral;

package/src/NumeralTypes.ts

@@ -0,0 +1,27 @@
+import type { TypeTextProps } from "@sproutsocial/seeds-react-text";
+
+export type EnumNumeralFormat = "decimal" | "currency" | "percent";
+
+export interface TypeNumeralProps extends Omit<TypeTextProps, "children"> {
+  /** The number to be formatted */
+  number?: number | null | undefined;
+
+  /** Locale to format. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument */
+  locale?: string;
+
+  /* The number formatting style to use */
+  format?: EnumNumeralFormat;
+
+  /** The currency format to use when formatting currency */
+  currency?: string;
+
+  /** A boolean determining whether or not the number should be abbreviated, or a number representing the abbreviation threshold  */
+  abbreviate?: boolean | number;
+
+  /** Text to be read off by screen readers for invalid values (i.e., any value rendered as '—' (em dash)) */
+  invalidNumberLabel?: string;
+
+  /** Override the default decimal precision (2 for decimals/currency, 1 for percentages), or "none" allowing unrestricted precision. */
+  precision?: number | "none";
+  qa?: object;
+}

package/src/__tests__/Numeral.typetest.tsx

@@ -0,0 +1,32 @@
+import * as React from "react";
+import Numeral from "../Numeral";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function NumeralTypes() {
+  const defaultProps = {
+    color: "text.headline",
+    number: 12.89,
+  };
+
+  return (
+    <>
+      <Numeral {...defaultProps} />
+      <Numeral
+        {...defaultProps}
+        number={100}
+        fontWeight="semibold"
+        fontSize={500}
+      />
+      <Numeral {...defaultProps} number={100} color="teal.500" />
+      <Numeral {...defaultProps} number={100} precision="none" />
+      <Numeral {...defaultProps} number={123.4} format="currency" />
+      <Numeral
+        {...defaultProps}
+        number={null}
+        invalidNumberLabel="Not available"
+      />
+      {/* @ts-expect-error - test that invalid precision is rejected */}
+      <Numeral {...defaultProps} precision="invalid" />
+    </>
+  );
+}

package/src/__tests__/features/A11y.test.tsx

@@ -0,0 +1,11 @@
+import React from "react";
+import { render } from "@sproutsocial/seeds-react-testing-library";
+import Numeral from "../../Numeral";
+
+describe("When rendering...", () => {
+  it("should handle A11y", async () => {
+    const { container, runA11yCheck } = render(<Numeral />);
+    expect(container).toBeTruthy();
+    await runA11yCheck();
+  });
+});

package/src/__tests__/features/abbreviate.test.ts

@@ -0,0 +1,215 @@
+import testNumeral from "./testNumeral";
+
+describe("When setting abbreviate false...", () => {
+  describe("... it never abbreviates the text", () => {
+    const options = {
+      abbreviate: false,
+    };
+    // positive values
+    testNumeral(1, options, {
+      text: "1",
+    });
+    testNumeral(12, options, {
+      text: "12",
+    });
+    testNumeral(0.23, options, {
+      text: "0.23",
+    });
+    testNumeral(1234, options, {
+      text: "1,234",
+    });
+    testNumeral(12345, options, {
+      text: "12,345",
+    });
+    testNumeral(123456.789, options, {
+      text: "123,456.79",
+    });
+    testNumeral(1225000000000, options, {
+      text: "1,225,000,000,000",
+    });
+    // negative values
+    testNumeral(-1, options, {
+      text: "-1",
+    });
+    testNumeral(-12, options, {
+      text: "-12",
+    });
+    testNumeral(-0.23, options, {
+      text: "-0.23",
+    });
+    testNumeral(-1234, options, {
+      text: "-1,234",
+    });
+    testNumeral(-12345, options, {
+      text: "-12,345",
+    });
+    testNumeral(-123456.789, options, {
+      text: "-123,456.79",
+    });
+    testNumeral(-1225000000000, options, {
+      text: "-1,225,000,000,000",
+    });
+  });
+});
+
+describe("When abbreviate throws an error", () => {
+  describe("... it never abbreviates the text", () => {
+    const OriginalNumberFormat = Intl.NumberFormat;
+    beforeEach(() => {
+      class CustomNumberFormat {
+        constructor(locale: string, standard?: Intl.NumberFormatOptions) {
+          if (standard?.notation === "compact") {
+            throw new Error("safari bug can not use compact");
+          }
+
+          return new OriginalNumberFormat(locale, standard);
+        }
+      }
+      // @ts-expect-error - types mismatch
+      Intl["NumberFormat"] = CustomNumberFormat;
+    });
+
+    afterEach(() => {
+      Intl["NumberFormat"] = OriginalNumberFormat;
+    });
+    const options = {
+      abbreviate: true,
+    };
+    // positive values
+    testNumeral(1, options, {
+      text: "1",
+    });
+    testNumeral(12, options, {
+      text: "12",
+    });
+    testNumeral(0.23, options, {
+      text: "0.23",
+    });
+    testNumeral(1234, options, {
+      text: "1,234",
+    });
+    testNumeral(12345, options, {
+      text: "12,345",
+    });
+    testNumeral(123456.789, options, {
+      text: "123,456.79",
+    });
+    testNumeral(1225000000000, options, {
+      text: "1,225,000,000,000",
+    });
+    // negative values
+    testNumeral(-1, options, {
+      text: "-1",
+    });
+    testNumeral(-12, options, {
+      text: "-12",
+    });
+    testNumeral(-0.23, options, {
+      text: "-0.23",
+    });
+    testNumeral(-1234, options, {
+      text: "-1,234",
+    });
+    testNumeral(-12345, options, {
+      text: "-12,345",
+    });
+    testNumeral(-123456.789, options, {
+      text: "-123,456.79",
+    });
+    testNumeral(-1225000000000, options, {
+      text: "-1,225,000,000,000",
+    });
+  });
+});
+
+describe("When setting abbreviate to a threshold...", () => {
+  describe("... it doesn't abbreviate if under the threshold", () => {
+    // positive values
+    const positiveOptions = {
+      abbreviate: 2000,
+    };
+    testNumeral(1999, positiveOptions, {
+      text: "1,999",
+    });
+    testNumeral(2000, positiveOptions, {
+      text: "2.00K",
+      tip: "2,000",
+    });
+    testNumeral(2011, positiveOptions, {
+      text: "2.01K",
+      tip: "2,011",
+    });
+    // negative values
+    const negativeOptions = {
+      abbreviate: -2000,
+    };
+    testNumeral(-1999, negativeOptions, {
+      text: "-1,999",
+    });
+    testNumeral(-2000, negativeOptions, {
+      text: "-2.00K",
+      tip: "-2,000",
+    });
+    testNumeral(-2011, negativeOptions, {
+      text: "-2.01K",
+      tip: "-2,011",
+    });
+  });
+
+  describe("... or if too small to abbreviate", () => {
+    // positive values
+    const positiveOptions = {
+      abbreviate: 500,
+    };
+    testNumeral(999, positiveOptions, {
+      text: "999",
+    });
+    testNumeral(1000, positiveOptions, {
+      text: "1.00K",
+      tip: "1,000",
+    });
+    // negative values
+    const negativeOptions = {
+      abbreviate: -500,
+    };
+    testNumeral(-999, negativeOptions, {
+      text: "-999",
+    });
+    testNumeral(-1000, negativeOptions, {
+      text: "-1.00K",
+      tip: "-1,000",
+    });
+  });
+
+  describe("... it abbreviates if greater or equal to the threshold", () => {
+    const options = {
+      abbreviate: true,
+    };
+    // positive values
+    testNumeral(12345, options, {
+      text: "12.35K",
+      tip: "12,345",
+    });
+    testNumeral(123456.789, options, {
+      text: "123.46K",
+      tip: "123,456.79",
+    });
+    testNumeral(1225000000000, options, {
+      text: "1.23T",
+      tip: "1,225,000,000,000",
+    });
+    // negative values
+    testNumeral(-12345, options, {
+      text: "-12.35K",
+      tip: "-12,345",
+    });
+    testNumeral(-123456.789, options, {
+      text: "-123.46K",
+      tip: "-123,456.79",
+    });
+    testNumeral(-1225000000000, options, {
+      text: "-1.23T",
+      tip: "-1,225,000,000,000",
+    });
+  });
+});