@sproutsocial/seeds-react-duration 1.0.0

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

@@ -0,0 +1,82 @@
+import testDuration from "./testDuration";
+
+describe("When using a negative value...", () => {
+  describe("... it renders properly", () => {
+    testDuration(-1, {}, { text: "0s" });
+    testDuration(
+      -1,
+      {
+        displayUnits: {
+          days: true,
+          hours: true,
+          minutes: true,
+          seconds: true,
+          milliseconds: true,
+        },
+      },
+      { text: "0ms" }
+    );
+    testDuration(
+      -1,
+      {
+        displayUnits: { days: true, hours: true, minutes: true, seconds: true },
+      },
+      { text: "0s" }
+    );
+    testDuration(
+      -1,
+      { displayUnits: { days: true, hours: true, minutes: true } },
+      { text: "0m" }
+    );
+    testDuration(
+      -1,
+      { displayUnits: { days: true, hours: true } },
+      { text: "0h" }
+    );
+    testDuration(-1, { displayUnits: { days: true } }, { text: "0d" });
+  });
+
+  describe("... should work with display long", () => {
+    testDuration(-1, { display: "long" }, { text: "0 seconds" });
+    testDuration(
+      -1,
+      {
+        display: "long",
+        displayUnits: {
+          days: true,
+          hours: true,
+          minutes: true,
+          seconds: true,
+          milliseconds: true,
+        },
+      },
+      { text: "0 milliseconds" }
+    );
+    testDuration(
+      -1,
+      {
+        display: "long",
+        displayUnits: { days: true, hours: true, minutes: true, seconds: true },
+      },
+      { text: "0 seconds" }
+    );
+    testDuration(
+      -1,
+      {
+        display: "long",
+        displayUnits: { days: true, hours: true, minutes: true },
+      },
+      { text: "0 minutes" }
+    );
+    testDuration(
+      -1,
+      { display: "long", displayUnits: { days: true, hours: true } },
+      { text: "0 hours" }
+    );
+    testDuration(
+      -1,
+      { display: "long", displayUnits: { days: true } },
+      { text: "0 days" }
+    );
+  });
+});

package/src/__tests__/features/testDuration.tsx

@@ -0,0 +1,37 @@
+/* eslint-env jest, node */
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import Duration, { formatDuration } from "../../Duration";
+
+jest.mock("../../constants.ts", () => ({
+  ...jest.requireActual("../../constants.ts"),
+  MEMO_CACHE_SIZE: 0,
+  COMPARE_OBJECTS: false,
+}));
+
+// @ts-ignore TS error later
+const testDuration = (milliseconds, options = {}, texts) => {
+  const { text: mainText, label: labelText, format: formatText } = texts;
+
+  test(`Should display ${milliseconds} as -> ${mainText}`, () => {
+    render(<Duration milliseconds={milliseconds} {...options} />);
+    const duration = screen.getByText(mainText);
+    expect(duration).toBeInTheDocument();
+    if (labelText) {
+      expect(screen.getByText(labelText)).toBeInTheDocument();
+    }
+
+    // formatDuration test
+    if (formatText) {
+      expect(
+        formatDuration({ milliseconds: milliseconds, ...options })
+      ).toEqual(formatText);
+    } else {
+      expect(
+        formatDuration({ milliseconds: milliseconds, ...options })
+      ).toEqual(mainText);
+    }
+  });
+};
+
+export default testDuration;

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

@@ -0,0 +1,260 @@
+import { getDurationMaxDisplayUnits } from "../../index";
+
+// full
+const millisecondsDuration = 123; // 123ms
+const secondsDuration = 12345; // 12s 345ms
+const minutesDuration = 1234567; // 20m 34s 567ms
+const hoursDuration = 12345678; // 3h 25m 45s 678ms
+const daysDuration = 123456789; // 1d 10h 17m 36s 789ms
+
+// partial
+const minutesPartialDuration = 1200567; // 20m 567ms
+const hoursPartialDuration = 10845000; // 3h 45s
+const daysPartialDuration = 87420789; // 1d 17m 789ms
+
+describe("When calling getDurationMaxDisplayUnits...", () => {
+  describe("... it returns the correct value ...", () => {
+    test.each([
+      // null
+      { milliseconds: null, maxDisplayUnits: 1, expected: {} },
+      // zero
+      { milliseconds: 0, maxDisplayUnits: 1, expected: {} },
+      // milliseconds
+      { milliseconds: millisecondsDuration, maxDisplayUnits: 0, expected: {} },
+      {
+        milliseconds: millisecondsDuration,
+        maxDisplayUnits: 1,
+        expected: { milliseconds: true },
+      },
+      {
+        milliseconds: millisecondsDuration,
+        maxDisplayUnits: 2,
+        expected: { milliseconds: true },
+      },
+      // seconds
+      { milliseconds: secondsDuration, maxDisplayUnits: 0, expected: {} },
+      {
+        milliseconds: secondsDuration,
+        maxDisplayUnits: 1,
+        expected: { seconds: true },
+      },
+      {
+        milliseconds: secondsDuration,
+        maxDisplayUnits: 2,
+        expected: { seconds: true, milliseconds: true },
+      },
+      {
+        milliseconds: secondsDuration,
+        maxDisplayUnits: 3,
+        expected: { seconds: true, milliseconds: true },
+      },
+      // minutes
+      { milliseconds: minutesDuration, maxDisplayUnits: 0, expected: {} },
+      {
+        milliseconds: minutesDuration,
+        maxDisplayUnits: 1,
+        expected: { minutes: true },
+      },
+      {
+        milliseconds: minutesDuration,
+        maxDisplayUnits: 2,
+        expected: { minutes: true, seconds: true },
+      },
+      {
+        milliseconds: minutesDuration,
+        maxDisplayUnits: 3,
+        expected: { minutes: true, seconds: true, milliseconds: true },
+      },
+      {
+        milliseconds: minutesDuration,
+        maxDisplayUnits: 4,
+        expected: { minutes: true, seconds: true, milliseconds: true },
+      },
+      // hours
+      { milliseconds: hoursDuration, maxDisplayUnits: 0, expected: {} },
+      {
+        milliseconds: hoursDuration,
+        maxDisplayUnits: 1,
+        expected: { hours: true },
+      },
+      {
+        milliseconds: hoursDuration,
+        maxDisplayUnits: 2,
+        expected: { hours: true, minutes: true },
+      },
+      {
+        milliseconds: hoursDuration,
+        maxDisplayUnits: 3,
+        expected: { hours: true, minutes: true, seconds: true },
+      },
+      {
+        milliseconds: hoursDuration,
+        maxDisplayUnits: 4,
+        expected: {
+          hours: true,
+          minutes: true,
+          seconds: true,
+          milliseconds: true,
+        },
+      },
+      {
+        milliseconds: hoursDuration,
+        maxDisplayUnits: 5,
+        expected: {
+          hours: true,
+          minutes: true,
+          seconds: true,
+          milliseconds: true,
+        },
+      },
+      // days
+      { milliseconds: daysDuration, maxDisplayUnits: 0, expected: {} },
+      {
+        milliseconds: daysDuration,
+        maxDisplayUnits: 1,
+        expected: { days: true },
+      },
+      {
+        milliseconds: daysDuration,
+        maxDisplayUnits: 2,
+        expected: { days: true, hours: true },
+      },
+      {
+        milliseconds: daysDuration,
+        maxDisplayUnits: 3,
+        expected: { days: true, hours: true, minutes: true },
+      },
+      {
+        milliseconds: daysDuration,
+        maxDisplayUnits: 4,
+        expected: { days: true, hours: true, minutes: true, seconds: true },
+      },
+      {
+        milliseconds: daysDuration,
+        maxDisplayUnits: 5,
+        expected: {
+          days: true,
+          hours: true,
+          minutes: true,
+          seconds: true,
+          milliseconds: true,
+        },
+      },
+      {
+        milliseconds: daysDuration,
+        maxDisplayUnits: 6,
+        expected: {
+          days: true,
+          hours: true,
+          minutes: true,
+          seconds: true,
+          milliseconds: true,
+        },
+      },
+      // partial minutes
+      {
+        milliseconds: minutesPartialDuration,
+        maxDisplayUnits: 0,
+        expected: {},
+      },
+      {
+        milliseconds: minutesPartialDuration,
+        maxDisplayUnits: 1,
+        expected: {
+          minutes: true,
+        },
+      },
+      {
+        milliseconds: minutesPartialDuration,
+        maxDisplayUnits: 2,
+        expected: {
+          minutes: true,
+          milliseconds: true,
+        },
+      },
+      {
+        milliseconds: minutesPartialDuration,
+        maxDisplayUnits: 3,
+        expected: {
+          minutes: true,
+          milliseconds: true,
+        },
+      },
+      // partial hours
+      {
+        milliseconds: hoursPartialDuration,
+        maxDisplayUnits: 0,
+        expected: {},
+      },
+      {
+        milliseconds: hoursPartialDuration,
+        maxDisplayUnits: 1,
+        expected: {
+          hours: true,
+        },
+      },
+      {
+        milliseconds: hoursPartialDuration,
+        maxDisplayUnits: 2,
+        expected: {
+          hours: true,
+          seconds: true,
+        },
+      },
+      {
+        milliseconds: hoursPartialDuration,
+        maxDisplayUnits: 3,
+        expected: {
+          hours: true,
+          seconds: true,
+        },
+      },
+      // partial days
+      {
+        milliseconds: daysPartialDuration,
+        maxDisplayUnits: 0,
+        expected: {},
+      },
+      {
+        milliseconds: daysPartialDuration,
+        maxDisplayUnits: 1,
+        expected: {
+          days: true,
+        },
+      },
+      {
+        milliseconds: daysPartialDuration,
+        maxDisplayUnits: 2,
+        expected: {
+          days: true,
+          minutes: true,
+        },
+      },
+      {
+        milliseconds: daysPartialDuration,
+        maxDisplayUnits: 3,
+        expected: {
+          days: true,
+          minutes: true,
+          milliseconds: true,
+        },
+      },
+      {
+        milliseconds: daysPartialDuration,
+        maxDisplayUnits: 4,
+        expected: {
+          days: true,
+          minutes: true,
+          milliseconds: true,
+        },
+      },
+    ])(
+      "given milliseconds: $milliseconds and maxDisplayUnits: $maxDisplayUnits",
+      ({ milliseconds, maxDisplayUnits, expected }) => {
+        expect(
+          getDurationMaxDisplayUnits({ milliseconds, maxDisplayUnits })
+        ).toEqual(expected);
+      }
+    );
+  });
+});

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

@@ -0,0 +1,82 @@
+import testDuration from "./testDuration";
+
+describe("When using a zero value...", () => {
+  describe("... it renders properly", () => {
+    testDuration(0.0, {}, { text: "0s" });
+    testDuration(
+      0.0,
+      {
+        displayUnits: {
+          days: true,
+          hours: true,
+          minutes: true,
+          seconds: true,
+          milliseconds: true,
+        },
+      },
+      { text: "0ms" }
+    );
+    testDuration(
+      0.0,
+      {
+        displayUnits: { days: true, hours: true, minutes: true, seconds: true },
+      },
+      { text: "0s" }
+    );
+    testDuration(
+      0.0,
+      { displayUnits: { days: true, hours: true, minutes: true } },
+      { text: "0m" }
+    );
+    testDuration(
+      0.0,
+      { displayUnits: { days: true, hours: true } },
+      { text: "0h" }
+    );
+    testDuration(0.0, { displayUnits: { days: true } }, { text: "0d" });
+  });
+
+  describe("... should work with display long", () => {
+    testDuration(0.0, { display: "long" }, { text: "0 seconds" });
+    testDuration(
+      0.0,
+      {
+        display: "long",
+        displayUnits: {
+          days: true,
+          hours: true,
+          minutes: true,
+          seconds: true,
+          milliseconds: true,
+        },
+      },
+      { text: "0 milliseconds" }
+    );
+    testDuration(
+      0.0,
+      {
+        display: "long",
+        displayUnits: { days: true, hours: true, minutes: true, seconds: true },
+      },
+      { text: "0 seconds" }
+    );
+    testDuration(
+      0.0,
+      {
+        display: "long",
+        displayUnits: { days: true, hours: true, minutes: true },
+      },
+      { text: "0 minutes" }
+    );
+    testDuration(
+      0.0,
+      { display: "long", displayUnits: { days: true, hours: true } },
+      { text: "0 hours" }
+    );
+    testDuration(
+      0.0,
+      { display: "long", displayUnits: { days: true } },
+      { text: "0 days" }
+    );
+  });
+});

package/src/constants.ts

@@ -0,0 +1,41 @@
+export const COMPARE_OBJECTS = true;
+export const MEMO_CACHE_SIZE = 10;
+
+export const UNITS = {
+  days: "days",
+  hours: "hours",
+  minutes: "minutes",
+  seconds: "seconds",
+  milliseconds: "milliseconds",
+};
+
+export const MILLISECONDS_IN = {
+  [UNITS.days]: 1 * 1000 * 60 * 60 * 24,
+  [UNITS.hours]: 1 * 1000 * 60 * 60,
+  [UNITS.minutes]: 1 * 1000 * 60,
+  [UNITS.seconds]: 1 * 1000,
+  [UNITS.milliseconds]: 1,
+};
+
+export const ORDERED_UNITS = [
+  UNITS.days,
+  UNITS.hours,
+  UNITS.minutes,
+  UNITS.seconds,
+  UNITS.milliseconds,
+];
+
+// Duration props defaults
+export const DEFAULT_DISPLAY = "narrow";
+export const DEFAULT_DISPLAY_UNITS = {
+  [UNITS.days]: true,
+  [UNITS.hours]: true,
+  [UNITS.minutes]: true,
+  [UNITS.seconds]: true,
+  [UNITS.milliseconds]: false,
+};
+
+export const DEFAULT_LOCALE = "en-US";
+export const DEFAULT_MILLISECONDS = null;
+
+export const EM_DASH = "—"; // shift + option + hyphen on a mac keyboard

package/src/index.ts

@@ -0,0 +1,12 @@
+import Duration, { formatDuration } from "./Duration";
+import {
+  getDurationMaxDisplayUnits,
+  type TypeGetDurationMaxDisplayUnitsProps,
+} from "./utils";
+
+export default Duration;
+export { Duration };
+export { formatDuration };
+export { getDurationMaxDisplayUnits };
+export type { TypeGetDurationMaxDisplayUnitsProps };
+export * from "./DurationTypes";

package/src/styles.ts

@@ -0,0 +1,6 @@
+import styled from "styled-components";
+import Text from "@sproutsocial/seeds-react-text";
+
+export const Container = styled(Text)`
+  font-variant-numeric: tabular-nums;
+`;

package/src/utils.ts

@@ -0,0 +1,89 @@
+import type {
+  TypeDurationDisplayUnits,
+  TypeDurationMilliseconds,
+} from "./DurationTypes";
+import { MILLISECONDS_IN, ORDERED_UNITS, UNITS } from "./constants";
+
+export const getLowestUnit = (displayUnits: TypeDurationDisplayUnits) =>
+  [...ORDERED_UNITS]
+    .reverse()
+    .find((unit) => displayUnits[unit as keyof TypeDurationDisplayUnits]) ||
+  UNITS.milliseconds;
+
+export const splitMillisecondsIntoUnits = (
+  milliseconds: number,
+  displayUnits: TypeDurationDisplayUnits
+): {
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+  milliseconds?: number;
+} => {
+  const lowestUnit = getLowestUnit(displayUnits);
+
+  // @ts-ignore TS error later
+  const remainder = milliseconds % MILLISECONDS_IN[lowestUnit];
+  // @ts-ignore TS error later
+  if (2 * remainder >= MILLISECONDS_IN[lowestUnit]) {
+    // if the remainder is large, add enough seconds to increse the lowest unit
+    // @ts-ignore TS error later
+    milliseconds += MILLISECONDS_IN[lowestUnit] - remainder;
+  }
+
+  const units = {};
+
+  ORDERED_UNITS.forEach((unit) => {
+    // @ts-ignore TS error later
+    if (displayUnits[unit]) {
+      // @ts-ignore TS error later
+      units[unit] = Math.floor(milliseconds / MILLISECONDS_IN[unit]);
+      // @ts-ignore TS error later
+      milliseconds -= units[unit] * MILLISECONDS_IN[unit];
+    }
+  });
+
+  return units;
+};
+
+export const isValidNumber = (value: unknown): boolean =>
+  typeof value === "number" && isFinite(value);
+
+export interface TypeGetDurationMaxDisplayUnitsProps {
+  milliseconds: TypeDurationMilliseconds;
+  maxDisplayUnits: number;
+}
+
+export const getDurationMaxDisplayUnits = ({
+  milliseconds,
+  maxDisplayUnits = ORDERED_UNITS.length,
+}: TypeGetDurationMaxDisplayUnitsProps): TypeDurationDisplayUnits => {
+  const displayUnits = {};
+
+  if (!isValidNumber(milliseconds)) {
+    return displayUnits;
+  }
+
+  for (const unit of ORDERED_UNITS) {
+    if (Object.keys(displayUnits).length >= maxDisplayUnits) {
+      break;
+    }
+
+    // @ts-expect-error - stupid typescript isn't smart enough to check the isValidNumber check above ¯\_(ツ)_/¯
+    const millisecondsByUnit = splitMillisecondsIntoUnits(milliseconds, {
+      days: true,
+      hours: true,
+      minutes: true,
+      seconds: true,
+      milliseconds: true,
+    });
+
+    // @ts-expect-error - stupid typescript isn't smart enough to check the isValidNumber check above ¯\_(ツ)_/¯
+    if (milliseconds > MILLISECONDS_IN[unit] && millisecondsByUnit[unit] > 0) {
+      // @ts-ignore TS error later
+      displayUnits[unit] = true;
+    }
+  }
+
+  return displayUnits;
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@sproutsocial/seeds-tsconfig/bundler/dom/library-monorepo",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "module": "esnext"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "coverage"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig((options) => ({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  clean: true,
+  legacyOutput: true,
+  dts: options.dts,
+  external: ["react"],
+  sourcemap: true,
+  metafile: options.metafile,
+}));