@sproutsocial/seeds-react-duration 1.0.0

package/src/Duration.stories.tsx

@@ -0,0 +1,82 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Duration from "./Duration";
+
+const localeOptions = [
+  "English (en-US)",
+  "Spanish (es-LA)",
+  "French (fr-FR)",
+  "Italian (it-IT)",
+  "Portuguese (pt-BR)",
+];
+
+const localeMapping = {
+  "English (en-US)": "en-US",
+  "Spanish (es-LA)": "es-LA",
+  "French (fr-FR)": "fr-FR",
+  "Italian (it-IT)": "it-IT",
+  "Portuguese (pt-BR)": "pt-BR",
+};
+
+const displayOptions = ["Long", "Narrow"];
+
+const displayMapping = {
+  Long: "long",
+  Narrow: "narrow",
+};
+
+const meta: Meta<typeof Duration> = {
+  title: "Components/Duration",
+  component: Duration,
+  argTypes: {
+    locale: {
+      control: "select",
+      options: localeOptions,
+      mapping: localeMapping,
+    },
+    display: {
+      control: "select",
+      options: displayOptions,
+      mapping: displayMapping,
+    },
+  },
+  args: {
+    milliseconds: 123456789,
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Duration>;
+
+export const Default: Story = {
+  args: {
+    milliseconds: 123456789,
+  },
+};
+
+export const Invalid: Story = {
+  args: {
+    milliseconds: null,
+  },
+};
+
+export const DisplayLong: Story = {
+  args: {
+    display: "long",
+  },
+};
+
+export const Negative: Story = {
+  args: {
+    milliseconds: -123456789,
+  },
+};
+
+export const DisplayUnits: Story = {
+  args: {
+    displayUnits: {
+      hours: true,
+      minutes: true,
+    },
+  },
+};

package/src/Duration.tsx

@@ -0,0 +1,151 @@
+import * as React from "react";
+// @ts-expect-error lru-memoize is not typed
+import memoize from "lru-memoize";
+import { EM_DASH } from "./constants";
+import { VisuallyHidden } from "@sproutsocial/seeds-react-visually-hidden";
+
+import {
+  COMPARE_OBJECTS,
+  DEFAULT_DISPLAY,
+  DEFAULT_DISPLAY_UNITS,
+  DEFAULT_LOCALE,
+  DEFAULT_MILLISECONDS,
+  MEMO_CACHE_SIZE,
+  ORDERED_UNITS,
+  UNITS,
+} from "./constants";
+import { Container } from "./styles";
+import type {
+  TypeDurationProps,
+  TypeDurationLocale,
+  TypeDurationDisplay,
+  TypeDurationDisplayUnits,
+} from "./DurationTypes";
+import {
+  isValidNumber,
+  getLowestUnit,
+  splitMillisecondsIntoUnits,
+} from "./utils";
+
+const _createDurationFormatter = (
+  locale: TypeDurationLocale,
+  unitDisplay: TypeDurationDisplay,
+  displayUnits: TypeDurationDisplayUnits
+) => {
+  const timeUnitFormatter = (
+    locale: TypeDurationProps["locale"],
+    unit: string,
+    unitDisplay: TypeDurationProps["display"]
+  ) => Intl.NumberFormat(locale, { style: "unit", unit, unitDisplay }).format;
+
+  const formatterByUnit = {
+    [UNITS.days]: timeUnitFormatter(locale, "day", unitDisplay),
+    [UNITS.hours]: timeUnitFormatter(locale, "hour", unitDisplay),
+    [UNITS.minutes]: timeUnitFormatter(locale, "minute", unitDisplay),
+    [UNITS.seconds]: timeUnitFormatter(locale, "second", unitDisplay),
+    [UNITS.milliseconds]: timeUnitFormatter(locale, "millisecond", unitDisplay),
+  };
+
+  const formatList = new Intl.ListFormat(locale, {
+    style: "narrow",
+    type: "unit",
+  });
+
+  return (value: number) => {
+    const lowestUnit = getLowestUnit(displayUnits);
+
+    // if the value is zero or negative, we just want to return 0 for the lowest unit (ex "0 minutes")
+    if (value <= 0) {
+      // @ts-ignore TS error later
+      return formatterByUnit[lowestUnit](0);
+    }
+
+    const millisecondsByUnit = splitMillisecondsIntoUnits(value, displayUnits);
+    const list: string[] = [];
+
+    ORDERED_UNITS.forEach((unit) => {
+      if (unit in millisecondsByUnit) {
+        // @ts-ignore TS error later
+        const unitValue = millisecondsByUnit[unit];
+
+        // we want to add to the list if one of two conditions are met:
+        // 1) the unit has a value greater than 0 OR
+        // 2) the unit has value 0 AND the unit is the lowest unit AND the list is already empty
+        if (
+          unitValue !== 0 ||
+          (unitValue === 0 && unit === lowestUnit && list.length === 0)
+        ) {
+          // @ts-ignore TS error later
+          list.push(formatterByUnit[unit](millisecondsByUnit[unit]));
+        }
+      }
+    });
+
+    return formatList.format(list);
+  };
+};
+
+// Memoize to reduce the energy of creating new instances of Intl.NumberFormat
+const memoizer = memoize(MEMO_CACHE_SIZE, COMPARE_OBJECTS);
+const createDurationFormatter = memoizer(_createDurationFormatter);
+
+const getDuration = ({
+  returnType,
+  props,
+}: {
+  returnType: "string" | "component";
+  props: TypeDurationProps;
+}): string | React.ReactNode => {
+  const {
+    display = DEFAULT_DISPLAY,
+    displayUnits = DEFAULT_DISPLAY_UNITS,
+    invalidMillisecondsLabel,
+    locale = DEFAULT_LOCALE,
+    milliseconds = DEFAULT_MILLISECONDS,
+    qa,
+  } = props;
+  const isReturnTypeString = returnType === "string";
+
+  if (!isValidNumber(milliseconds)) {
+    return isReturnTypeString ? (
+      EM_DASH
+    ) : (
+      <>
+        {invalidMillisecondsLabel ? (
+          // Give screen readers something useful to read off + hide the em dash
+          <VisuallyHidden>{invalidMillisecondsLabel}</VisuallyHidden>
+        ) : null}
+        <Container aria-hidden {...qa}>
+          {EM_DASH}
+        </Container>
+      </>
+    );
+  }
+
+  const validatedDisplayUnits =
+    Object.keys(displayUnits).length === 0
+      ? DEFAULT_DISPLAY_UNITS
+      : displayUnits;
+
+  const fullText = createDurationFormatter(
+    locale,
+    display,
+    validatedDisplayUnits
+  )(milliseconds);
+
+  return isReturnTypeString ? (
+    fullText
+  ) : (
+    <Container {...qa}>{fullText}</Container>
+  );
+};
+
+export const formatDuration = (props: TypeDurationProps): string => {
+  return getDuration({ returnType: "string", props }) as string;
+};
+
+const Duration = (props: TypeDurationProps) => {
+  return getDuration({ returnType: "component", props });
+};
+
+export default Duration;

package/src/DurationTypes.ts

@@ -0,0 +1,34 @@
+import type { TypeTextProps } from "@sproutsocial/seeds-react-text";
+
+export type TypeDurationMilliseconds = number | null;
+
+export type TypeDurationLocale = Intl.LocalesArgument;
+
+export type TypeDurationDisplay = "long" | "narrow";
+
+export interface TypeDurationDisplayUnits {
+  days?: boolean;
+  hours?: boolean;
+  minutes?: boolean;
+  seconds?: boolean;
+  milliseconds?: boolean;
+}
+
+export interface TypeDurationProps extends Omit<TypeTextProps, "children"> {
+  /** The milliseconds to be formatted */
+  milliseconds: TypeDurationMilliseconds;
+
+  /** Locale to format. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument */
+  locale?: TypeDurationLocale;
+
+  /** The style of the formatted duration */
+  display?: TypeDurationDisplay;
+
+  /** The units of the duration to render */
+  displayUnits?: TypeDurationDisplayUnits;
+
+  /** Text to be read off by screen readers for invalid values (i.e., any value rendered as '—' (em dash)) */
+  invalidMillisecondsLabel?: string;
+
+  qa?: object;
+}

package/src/__tests__/Duration.typetest.tsx

@@ -0,0 +1,29 @@
+import * as React from "react";
+import Duration from "../Duration";
+
+const defaultProps = {
+  color: "text.headline",
+  milliseconds: 12345,
+};
+
+export const DurationTypeTest = () => (
+  <>
+    <Duration {...defaultProps} />
+    <Duration
+      {...defaultProps}
+      milliseconds={100}
+      fontWeight="semibold"
+      fontSize={500}
+    />
+    <Duration {...defaultProps} milliseconds={100} color="teal.500" />
+    <Duration {...defaultProps} milliseconds={100} locale="it-IT" />
+    <Duration {...defaultProps} milliseconds={123.4} display="narrow" />
+    <Duration
+      {...defaultProps}
+      milliseconds={null}
+      invalidMillisecondsLabel="Not available"
+    />
+    {/* @ts-expect-error - test that invalid display is rejected */}
+    <Duration {...defaultProps} display="short" />
+  </>
+);

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

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

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

@@ -0,0 +1,116 @@
+import testDuration from "./testDuration";
+
+describe("When using the default props...", () => {
+  describe("... it renders properly", () => {
+    testDuration(1, {}, { text: "0s" });
+    testDuration(2, {}, { text: "0s" });
+    testDuration(1000, {}, { text: "1s" });
+    testDuration(2000, {}, { text: "2s" });
+    testDuration(1001, {}, { text: "1s" });
+    testDuration(2002, {}, { text: "2s" });
+    testDuration(60000, {}, { text: "1m" });
+    testDuration(120000, {}, { text: "2m" });
+    testDuration(61000, {}, { text: "1m 1s" });
+    testDuration(122000, {}, { text: "2m 2s" });
+    testDuration(60001, {}, { text: "1m" });
+    testDuration(120002, {}, { text: "2m" });
+    testDuration(61001, {}, { text: "1m 1s" });
+    testDuration(
+      122002,
+      {},
+      {
+        text: "2m 2s",
+      }
+    );
+    testDuration(3600000, {}, { text: "1h" });
+    testDuration(7200000, {}, { text: "2h" });
+    testDuration(3660000, {}, { text: "1h 1m" });
+    testDuration(7320000, {}, { text: "2h 2m" });
+    testDuration(3601000, {}, { text: "1h 1s" });
+    testDuration(7202000, {}, { text: "2h 2s" });
+    testDuration(3600001, {}, { text: "1h" });
+    testDuration(7200002, {}, { text: "2h" });
+    testDuration(3661000, {}, { text: "1h 1m 1s" });
+    testDuration(7322000, {}, { text: "2h 2m 2s" });
+    testDuration(3601001, {}, { text: "1h 1s" });
+    testDuration(
+      7202002,
+      {},
+      {
+        text: "2h 2s",
+      }
+    );
+    testDuration(3660001, {}, { text: "1h 1m" });
+    testDuration(
+      7320002,
+      {},
+      {
+        text: "2h 2m",
+      }
+    );
+    testDuration(3661001, {}, { text: "1h 1m 1s" });
+    testDuration(7322002, {}, { text: "2h 2m 2s" });
+    testDuration(86400000, {}, { text: "1d" });
+    testDuration(172800000, {}, { text: "2d" });
+    testDuration(90000000, {}, { text: "1d 1h" });
+    testDuration(180000000, {}, { text: "2d 2h" });
+    testDuration(86460000, {}, { text: "1d 1m" });
+    testDuration(172920000, {}, { text: "2d 2m" });
+    testDuration(86401000, {}, { text: "1d 1s" });
+    testDuration(172802000, {}, { text: "2d 2s" });
+    testDuration(86400001, {}, { text: "1d" });
+    testDuration(172800002, {}, { text: "2d" });
+    testDuration(90060000, {}, { text: "1d 1h 1m" });
+    testDuration(180120000, {}, { text: "2d 2h 2m" });
+    testDuration(90001000, {}, { text: "1d 1h 1s" });
+    testDuration(180002000, {}, { text: "2d 2h 2s" });
+    testDuration(90000001, {}, { text: "1d 1h" });
+    testDuration(180000002, {}, { text: "2d 2h" });
+    testDuration(86461000, {}, { text: "1d 1m 1s" });
+    testDuration(172922000, {}, { text: "2d 2m 2s" });
+    testDuration(86460001, {}, { text: "1d 1m" });
+    testDuration(
+      172920002,
+      {},
+      {
+        text: "2d 2m",
+      }
+    );
+    testDuration(86401001, {}, { text: "1d 1s" });
+    testDuration(
+      172802002,
+      {},
+      {
+        text: "2d 2s",
+      }
+    );
+    testDuration(90061000, {}, { text: "1d 1h 1m 1s" });
+    testDuration(
+      180122000,
+      {},
+      {
+        text: "2d 2h 2m 2s",
+      }
+    );
+    testDuration(86461001, {}, { text: "1d 1m 1s" });
+    testDuration(172922002, {}, { text: "2d 2m 2s" });
+    testDuration(
+      90001001,
+      {},
+      {
+        text: "1d 1h 1s",
+      }
+    );
+    testDuration(180002002, {}, { text: "2d 2h 2s" });
+    testDuration(
+      90060001,
+      {},
+      {
+        text: "1d 1h 1m",
+      }
+    );
+    testDuration(180120002, {}, { text: "2d 2h 2m" });
+    testDuration(90061001, {}, { text: "1d 1h 1m 1s" });
+    testDuration(180122002, {}, { text: "2d 2h 2m 2s" });
+  });
+});

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

@@ -0,0 +1,102 @@
+import testDuration from "./testDuration";
+
+const options = { display: "long" };
+
+describe("When setting display long...", () => {
+  describe("... it renders properly", () => {
+    testDuration(1, options, { text: "0 seconds" });
+    testDuration(2, options, { text: "0 seconds" });
+    testDuration(1000, options, { text: "1 second" });
+    testDuration(2000, options, { text: "2 seconds" });
+    testDuration(1001, options, { text: "1 second" });
+    testDuration(2002, options, { text: "2 seconds" });
+    testDuration(60000, options, { text: "1 minute" });
+    testDuration(120000, options, { text: "2 minutes" });
+    testDuration(61000, options, { text: "1 minute 1 second" });
+    testDuration(122000, options, { text: "2 minutes 2 seconds" });
+    testDuration(60001, options, { text: "1 minute" });
+    testDuration(120002, options, { text: "2 minutes" });
+    testDuration(61001, options, { text: "1 minute 1 second" });
+    testDuration(122002, options, {
+      text: "2 minutes 2 seconds",
+    });
+    testDuration(3600000, options, { text: "1 hour" });
+    testDuration(7200000, options, { text: "2 hours" });
+    testDuration(3660000, options, { text: "1 hour 1 minute" });
+    testDuration(7320000, options, { text: "2 hours 2 minutes" });
+    testDuration(3601000, options, { text: "1 hour 1 second" });
+    testDuration(7202000, options, { text: "2 hours 2 seconds" });
+    testDuration(3600001, options, { text: "1 hour" });
+    testDuration(7200002, options, { text: "2 hours" });
+    testDuration(3661000, options, { text: "1 hour 1 minute 1 second" });
+    testDuration(7322000, options, { text: "2 hours 2 minutes 2 seconds" });
+    testDuration(3601001, options, { text: "1 hour 1 second" });
+    testDuration(7202002, options, {
+      text: "2 hours 2 seconds",
+    });
+    testDuration(3660001, options, { text: "1 hour 1 minute" });
+    testDuration(7320002, options, {
+      text: "2 hours 2 minutes",
+    });
+    testDuration(3661001, options, {
+      text: "1 hour 1 minute 1 second",
+    });
+    testDuration(7322002, options, {
+      text: "2 hours 2 minutes 2 seconds",
+    });
+    testDuration(86400000, options, { text: "1 day" });
+    testDuration(172800000, options, { text: "2 days" });
+    testDuration(90000000, options, { text: "1 day 1 hour" });
+    testDuration(180000000, options, { text: "2 days 2 hours" });
+    testDuration(86460000, options, { text: "1 day 1 minute" });
+    testDuration(172920000, options, { text: "2 days 2 minutes" });
+    testDuration(86401000, options, { text: "1 day 1 second" });
+    testDuration(172802000, options, { text: "2 days 2 seconds" });
+    testDuration(86400001, options, { text: "1 day" });
+    testDuration(172800002, options, { text: "2 days" });
+    testDuration(90060000, options, { text: "1 day 1 hour 1 minute" });
+    testDuration(180120000, options, { text: "2 days 2 hours 2 minutes" });
+    testDuration(90001000, options, { text: "1 day 1 hour 1 second" });
+    testDuration(180002000, options, { text: "2 days 2 hours 2 seconds" });
+    testDuration(90000001, options, { text: "1 day 1 hour" });
+    testDuration(180000002, options, { text: "2 days 2 hours" });
+    testDuration(86461000, options, { text: "1 day 1 minute 1 second" });
+    testDuration(172922000, options, { text: "2 days 2 minutes 2 seconds" });
+    testDuration(86460001, options, { text: "1 day 1 minute" });
+    testDuration(172920002, options, {
+      text: "2 days 2 minutes",
+    });
+    testDuration(86401001, options, { text: "1 day 1 second" });
+    testDuration(172802002, options, {
+      text: "2 days 2 seconds",
+    });
+    testDuration(90061000, options, { text: "1 day 1 hour 1 minute 1 second" });
+    testDuration(180122000, options, {
+      text: "2 days 2 hours 2 minutes 2 seconds",
+    });
+    testDuration(86461001, options, {
+      text: "1 day 1 minute 1 second",
+    });
+    testDuration(172922002, options, {
+      text: "2 days 2 minutes 2 seconds",
+    });
+    testDuration(90001001, options, {
+      text: "1 day 1 hour 1 second",
+    });
+    testDuration(180002002, options, {
+      text: "2 days 2 hours 2 seconds",
+    });
+    testDuration(90060001, options, {
+      text: "1 day 1 hour 1 minute",
+    });
+    testDuration(180120002, options, {
+      text: "2 days 2 hours 2 minutes",
+    });
+    testDuration(90061001, options, {
+      text: "1 day 1 hour 1 minute 1 second",
+    });
+    testDuration(180122002, options, {
+      text: "2 days 2 hours 2 minutes 2 seconds",
+    });
+  });
+});