@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/utils/dateTimeFormat.ts

@@ -0,0 +1,257 @@
+import { formatDistance, fromUnixTime, isToday as isTodayDateFns, isYesterday as isYesterdayDateFns } from 'date-fns';
+import { format } from 'date-fns-tz';
+
+export type TimeUnit = number | Date;
+
+export const safeFromUnixTime = (time?: TimeUnit): Date => {
+    let date = new Date();
+    try {
+        // return a valid date if the value is falsey
+        if (!time) {
+            return date;
+        }
+
+        // Check to see if time is a Date;
+        // @ts-expect-error - since time can be either a number or a date we will have a ts error checking this
+        if (typeof time.getMonth === 'function') {
+            return time as Date;
+        } else if (typeof time === 'number') {
+            date = fromUnixTime(time);
+
+            // in the case that the number is a JS style timestamp the date will be way in the future and so we should use new Date instead
+            if (date.getFullYear() > 10000) {
+                return new Date(time);
+            }
+        }
+
+        return date;
+    } catch (error) {
+        // eslint-disable-next-line no-console
+        console.log(error);
+    }
+    return date;
+};
+
+/**
+ * Formats the given timestamp into a string representation of month, day, year, and time.
+ *
+ * @param {number | Date} timestamp The timestamp to format, as a number or Date object.
+ * @param {boolean} [short=false] - Optional. If true, the date format will be abbreviated (e.g., "MMM d").
+ * @param {boolean} [timeZone="America/Denver"] - Optional. The time zone to use for the formatted date string.
+ * Otherwise, it will be in the long format (e.g., "MMMM d, yyyy, h:mm a zz").
+ * @returns {string} The formatted date string, e.g., "July 24, 2024, 3:38 PM MDT" for long format or "Jul 24" for short format.
+ *
+ * @example
+ * // Returns "July 24, 2024, 3:38 PM MDT"
+ * formatTimestamp(new Date(), { short: false, timeZone: 'America/Denver' });
+ */
+export const getMonthDayYearTime = (
+    timestamp: TimeUnit,
+    options: { short?: boolean; timeZone?: string } = {}
+): string => {
+    return format(safeFromUnixTime(timestamp), `${options.short ? 'MMM' : 'MMMM'} d, yyyy, h:mm a zz`, {
+        timeZone: options.timeZone,
+    });
+};
+
+/**
+ * Formats the given timestamp into a string representation of month, day, and year.
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @param {boolean} [options.short=false] - If true, the month format will be abbreviated (e.g., "MMM"). Otherwise, it will be in the long format (e.g., "MMMM").
+ * @returns {string} The formatted string representation of the timestamp in the format "MMM d, yyyy" or "MMMM d, yyyy".
+ *
+ * @example
+ * // Returns "July 24, 2024"
+ * getMonthDayYear(new Date(2024, 6, 24));
+ */
+
+export const getMonthDayYear = (timestamp: TimeUnit, options: { short?: boolean } = {}): string =>
+    format(safeFromUnixTime(timestamp), `${options.short ? 'MMM' : 'MMMM'} d, yyyy`);
+
+/**
+ * Formats the given timestamp into a string representation of day, month, and year.
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @param {boolean} [options.short=false] - If true, the month format will be abbreviated (e.g., "MMM"). Otherwise, it will be in the long format (e.g., "MMMM").
+ * @returns {string} The formatted string representation of the timestamp in the format "d MMM yyyy" or "d MMMM yyyy".
+ *
+ * @example
+ * // Returns "24 July 2024"
+ * getDayMonthYear(new Date(2024, 6, 24));
+ */
+
+export const getDayMonthYear = (timestamp: TimeUnit, options: { short?: boolean } = {}): string =>
+    format(safeFromUnixTime(timestamp), `d ${options.short ? 'MMM' : 'MMMM'} yyyy`);
+
+/**
+ * Formats the given timestamp into a string representation of day, month, year, and time.
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @param {boolean} [short=false] - Optional. If true, the date format will be abbreviated (e.g., "d MMM").
+ * @param {boolean} [timeZone="America/Denver"] - Optional. The time zone to use for the formatted date string.
+ * Otherwise, it will be in the long format (e.g., "dd MMMM, yyyy, h:mm a").
+ * @returns {string} The formatted string representation of the timestamp.
+ *
+ * @example
+ * // Returns "24 July, 2024, 3:38 PM"
+ * formatDateTime(new Date(), {short: false, timeZone: 'America/Denver'});
+ */
+export const getDayMonthYearTime = (
+    timestamp: TimeUnit,
+    options: { short?: boolean; timeZone?: string } = {}
+): string =>
+    format(safeFromUnixTime(timestamp), `${options.short ? 'd MMM' : 'dd MMMM'} yyyy, h:mm a zz`, {
+        timeZone: options.timeZone,
+    });
+
+/**
+ * Formats the given timestamp into a string representation of month and day.
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @returns {string} The formatted string representation of the timestamp in the format "MMMM d".
+ *
+ * @example
+ * // Returns "July 24"
+ * formatMonthDay(new Date());
+ */
+export const getMonthDay = (timestamp: TimeUnit): string => format(safeFromUnixTime(timestamp), 'MMMM dd');
+
+/**
+ * Formats the given timestamp into a string representation of month and day (abbreviated).
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @returns {string} The formatted string representation of the timestamp in the format "MMM d".
+ *
+ * @example
+ * // Returns "Jul 24"
+ * formatMonthDayAbbreviated(new Date());
+ *
+ */
+export const getMonthDayShort = (timestamp: TimeUnit): string => format(safeFromUnixTime(timestamp), 'MMM dd');
+
+/**
+ * Formats the given timestamp into a string representation of day and month (abbreviated).
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @returns {string} The formatted string representation of the timestamp in the format "dd MMM".
+ *
+ * @example
+ * // Returns "24 Jul"
+ * getDayMonthShort(new Date());
+ */
+export const getDayMonthShort = (timestamp: TimeUnit): string => format(safeFromUnixTime(timestamp), 'dd MMM');
+
+/**
+ * Formats the given timestamp into a string representation of day and month (abbreviated).
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @returns {string} The formatted string representation of the timestamp in the format "dd MMMM".
+ *
+ * @example
+ * // Returns "24 July"
+ * getDayMonthShort(new Date());
+ */
+export const getDayMonth = (timestamp: TimeUnit): string => format(safeFromUnixTime(timestamp), 'dd MMMM');
+
+/**
+ * Formats the given timestamp into a string representation of ISO date and time.
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @param {Object} [options={}] - Optional settings.
+ * @param {string} [options.timeZone] - The time zone to use for formatting. Defaults to the local time zone if not specified.
+ * @returns {string} The formatted string representation of the timestamp in the format "yyyy-MM-dd h:mm a zz".
+ *
+ * @example
+ * // Returns "2024-07-24 3:38 PM UTC" with specified time zone
+ * getISODateTime(new Date(), { timeZone: 'UTC' });
+ */
+export const getISODateTime = (timestamp: TimeUnit, options: { short?: boolean; timeZone?: string } = {}): string =>
+    options.short
+        ? format(safeFromUnixTime(timestamp), 'yyyy-MM-dd', { timeZone: options.timeZone })
+        : format(safeFromUnixTime(timestamp), 'yyyy-MM-dd h:mm a zz', { timeZone: options.timeZone });
+
+/**
+ * Formats the given timestamp into a string representation of time.
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @param {string} [options.timeZone] - The time zone to use for formatting. Defaults to the local time zone if not specified.
+ * @returns {string} The formatted string representation of the timestamp in the format "h:mm a zz".
+ *
+ * @example
+ * // Returns "3:38 PM UTC" with specified time zone
+ * getTime(new Date(), { timeZone: 'UTC' });
+ */
+export const getTime = (timestamp: TimeUnit, options: { timeZone?: string } = {}): string =>
+    format(safeFromUnixTime(timestamp), 'h:mm a zz', { timeZone: options.timeZone });
+
+/**
+ * Formats the given timestamp into a string representation of the date in 'MM/dd/yyyy' format.
+ *
+ * @param {number | Date} timestamp - The timestamp to format, as a number or Date object.
+ * @returns {string} The formatted string representation of the timestamp in 'MM/dd/yyyy' format.
+ *
+ * @example
+ * // Returns "07/24/2024"
+ * getSimpleDate(new Date(2024, 6, 24));
+ */
+
+export const getSimpleDate = (timestamp: TimeUnit): string => format(safeFromUnixTime(timestamp), 'MM/dd/yyyy');
+
+/**
+ * Calculates the time distance between a given timestamp and the current time.
+ * @param timestamp - The timestamp to calculate the distance from.
+ * @param short - Optional. If true, returns the short version of the time distance.
+ * @returns The time distance between the timestamp and the current time.
+ */
+export const formatTimeDistance = (timestamp: TimeUnit, options: { short?: boolean } = { short: false }) => {
+    const { short } = options;
+    const safeDate = safeFromUnixTime(timestamp);
+
+    const diff = new Date().getTime() - safeDate.getTime();
+
+    return formatDistance(safeFromUnixTime(timestamp), new Date(), {
+        addSuffix: Boolean(options.short),
+        locale: {
+            formatDistance: (token, count, options) => {
+                const isInTheFutureText = options?.comparison === 1 && !short ? 'In ' : '';
+                const inThePastText = options?.comparison === -1 && !short ? ' ago' : '';
+                let timeText = '';
+
+                if (token === 'lessThanXMinutes') {
+                    const seconds = Math.round(Math.abs(diff / 1000));
+                    timeText = short ? `${seconds}s` : seconds === 1 ? '1 second' : `${seconds} seconds`;
+                } else if (token === 'xMinutes') {
+                    timeText = short ? `${count}m` : count === 1 ? '1 minute' : `${count} minutes`;
+                } else if (token === 'aboutXHours') {
+                    timeText = short ? `${count}h` : count === 1 ? '1 hour' : `${count} hours`;
+                } else if (token === 'xDays' && count <= 7) {
+                    if (count === 7) {
+                        timeText = '1 week';
+                    } else {
+                        timeText = short ? `${count}d` : count === 1 ? '1 day' : `${count} days`;
+                    }
+                } else {
+                    return short ? getMonthDayShort(safeDate) : getMonthDayYear(safeDate);
+                }
+
+                return `${isInTheFutureText}${timeText}${inThePastText}`;
+            },
+        },
+    });
+};
+
+/**
+ * Determines whether the given timestamp represents a date that is today.
+ * @param timestamp - The timestamp to check.
+ * @returns A boolean indicating whether the timestamp represents a date that is today.
+ */
+
+export const isToday = (timestamp: TimeUnit): boolean => isTodayDateFns(safeFromUnixTime(timestamp));
+/**
+ * Determines whether the given timestamp represents a date that is yesterday.
+ *
+ * @param timestamp - The timestamp to check.
+ * @returns A boolean indicating whether the timestamp represents a date that is yesterday.
+ */
+export const isYesterday = (timestamp: TimeUnit): boolean => isYesterdayDateFns(safeFromUnixTime(timestamp));

package/src/utils/effectEventListener.ts

@@ -0,0 +1,11 @@
+export const effectEventListener = <T extends Window | Document, P extends Parameters<T['addEventListener']>>(
+    target: T,
+    event: P[0],
+    callback: P[1]
+) => {
+    target.addEventListener(event, callback);
+
+    return () => {
+        target.removeEventListener(event, callback);
+    };
+};

package/src/utils/formatFileSize.ts

@@ -0,0 +1,18 @@
+const FILE_SIZE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;
+
+export const formatFileSize = (bytes: number): string => {
+    if (bytes === 0) {
+        return '0 B';
+    }
+
+    const exp = Math.floor(Math.log(bytes) / Math.log(1024));
+    const clampedExp = Math.min(exp, FILE_SIZE_UNITS.length - 1);
+    const size = bytes / Math.pow(1024, clampedExp);
+    const unit = FILE_SIZE_UNITS[clampedExp];
+
+    // For numbers less than 10, show one decimal place
+    // For larger numbers, round to whole number
+    const formatted = size < 10 ? size.toFixed(1) : Math.round(size);
+
+    return `${formatted} ${unit}`;
+};

package/src/utils/isClientSide.ts

@@ -0,0 +1 @@
+export const isClientSide = typeof window !== 'undefined';

package/src/utils/keepTransition.ts

@@ -0,0 +1,15 @@
+declare const process:
+    | {
+          env?: {
+              KEEP_TRANSITION?: string;
+          };
+      }
+    | undefined;
+
+/**
+ * Test-only escape hatch, read at call time: Drawer specs set
+ * `process.env.KEEP_TRANSITION = 'true'` at runtime to opt back into CSS
+ * transitions. Unlike `nodeEnv` (a module-load-time read), a call-time read
+ * sees that mutation.
+ */
+export const keepTransition = () => (typeof process === 'undefined' ? undefined : process.env?.KEEP_TRANSITION);

package/src/utils/nodeEnv.ts

@@ -0,0 +1,9 @@
+declare const process:
+    | {
+          env?: {
+              NODE_ENV?: string;
+          };
+      }
+    | undefined;
+
+export const nodeEnv = typeof process === 'undefined' ? undefined : process.env?.NODE_ENV;

package/src/utils/smoothScrollTo.ts

@@ -0,0 +1,47 @@
+/**
+ * Easing function for smooth scroll animation
+ * Uses cubic easing in-out curve
+ * @param t - Progress value between 0 and 1
+ * @returns Eased progress value
+ */
+const easeInOutCubic = (t: number): number => {
+    return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+};
+
+/**
+ * Smoothly scrolls the window to a specific vertical position using requestAnimationFrame
+ * @param targetY - The target vertical scroll position in pixels
+ * @param duration - The duration of the scroll animation in milliseconds (defaults to 300ms)
+ *
+ * @example
+ * ```tsx
+ * // Scroll to 500px from the top over 300ms
+ * smoothScrollTo(500);
+ *
+ * // Scroll to top of an element with custom duration
+ * const element = document.getElementById('my-element');
+ * if (element) {
+ *   const targetY = element.getBoundingClientRect().top + window.scrollY;
+ *   smoothScrollTo(targetY, 500);
+ * }
+ * ```
+ */
+export const smoothScrollTo = (targetY: number, duration: number = 300): void => {
+    const startY = window.scrollY;
+    const distance = targetY - startY;
+    const startTime = performance.now();
+
+    const scroll = (currentTime: number) => {
+        const elapsed = currentTime - startTime;
+        const progress = Math.min(elapsed / duration, 1);
+        const easeProgress = easeInOutCubic(progress);
+
+        window.scrollTo(0, startY + distance * easeProgress);
+
+        if (progress < 1) {
+            requestAnimationFrame(scroll);
+        }
+    };
+
+    requestAnimationFrame(scroll);
+};

package/src/utils/utilityTypes.ts

@@ -0,0 +1,13 @@
+/**
+ * Allows for string replacement for typed string literals!
+ *
+ * Example: `Replace<'text' | 'toxt', 'xt', 'm'> -> 'tem' | 'tom'`
+ *
+ * @see https://stackoverflow.com/questions/71352751/string-replace-when-creating-string-literal-union-type-in-typescript
+ */
+export type Replace<
+    T extends string,
+    S extends string,
+    D extends string,
+    A extends string = '',
+> = T extends `${infer L}${S}${infer R}` ? Replace<R, S, D, `${A}${L}${D}`> : `${A}${T}`;