Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
6.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file Timer.tsx
 * @input Uses an optional start time, standardized format, Timestamp typography, BaseProps, and React ref
 * @output Exports Timer, TimerProps, and TimerFormat with non-rendering elapsed-time updates
 * @position Core content primitive for elapsed duration in active operations
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /docs/specs/components/Timer/Timer.spec.md
 * - /packages/core/src/Timer/Timer.doc.mjs
 * - /packages/core/src/Timer/Timer.test.tsx
 * - /packages/core/src/Timer/index.ts
 * - /apps/storybook/stories/Timer.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Timer/
 */

import {useEffect, useRef, useState} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {Text} from '../Text';
import type {TextColor, TextSize, TextType, TextWeight} from '../theme/types';
import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';

const ONE_SECOND_MS = 1000;
const ONE_MINUTE_MS = 60 * ONE_SECOND_MS;
const ONE_HOUR_SECONDS = 60 * 60;
const MAX_TIMEOUT_MS = 2_147_483_647;

const styles = stylex.create({
  time: {
    color: 'inherit',
    display: 'inline',
    fontFamily: 'inherit',
    fontSize: 'inherit',
    fontStyle: 'normal',
    fontVariantNumeric: 'tabular-nums',
    fontWeight: 'inherit',
    lineHeight: 'inherit',
  },
});

export type TimerFormat = 'elapsed' | 'clock';

type TimerPresentation = {
  dateTime: string;
  text: string;
};

function pad(value: number): string {
  return String(value).padStart(2, '0');
}

function resolveFormat(format: TimerFormat): TimerFormat {
  return format === 'clock' ? 'clock' : 'elapsed';
}

function getElapsedMilliseconds(now: number, startTime: number): number {
  return Math.max(0, now - startTime);
}

function getPresentation(
  elapsedMilliseconds: number,
  format: TimerFormat,
): TimerPresentation {
  const elapsedSeconds = Math.floor(elapsedMilliseconds / ONE_SECOND_MS);

  if (format === 'clock') {
    const hours = Math.floor(elapsedSeconds / ONE_HOUR_SECONDS);
    const minutes = Math.floor((elapsedSeconds % ONE_HOUR_SECONDS) / 60);
    const seconds = elapsedSeconds % 60;
    return {
      dateTime: `PT${elapsedSeconds}S`,
      text:
        hours > 0
          ? `${String(hours)}:${pad(minutes)}:${pad(seconds)}`
          : `${String(minutes)}:${pad(seconds)}`,
    };
  }

  if (elapsedSeconds < 60) {
    return {
      dateTime: `PT${elapsedSeconds}S`,
      text: `${String(elapsedSeconds)}s`,
    };
  }

  const totalMinutes = Math.floor(elapsedSeconds / 60);
  if (totalMinutes < 60) {
    return {
      dateTime: `PT${elapsedSeconds}S`,
      text: `${String(totalMinutes)}m ${pad(elapsedSeconds % 60)}s`,
    };
  }

  const representedSeconds = totalMinutes * 60;
  return {
    dateTime: `PT${representedSeconds}S`,
    text: `${String(Math.floor(totalMinutes / 60))}h ${pad(totalMinutes % 60)}m`,
  };
}

function getMillisecondsUntilNextChange(
  now: number,
  startTime: number,
  elapsedMilliseconds: number,
  format: TimerFormat,
): number {
  if (now < startTime) {
    return Math.min(startTime - now + ONE_SECOND_MS, MAX_TIMEOUT_MS);
  }

  const precision =
    format === 'elapsed' &&
    elapsedMilliseconds >= ONE_HOUR_SECONDS * ONE_SECOND_MS
      ? ONE_MINUTE_MS
      : ONE_SECOND_MS;
  return precision - (elapsedMilliseconds % precision);
}

export interface TimerProps extends Omit<
  BaseProps<HTMLTimeElement>,
  'dateTime'
> {
  /** Ref forwarded to the rendered `<time>` element. */
  ref?: React.Ref<HTMLTimeElement>;
  /**
   * Unix time in milliseconds when the measured operation began. Omit it to
   * start counting from this Timer's mount.
   */
  startTime?: number;
  /**
   * Standard duration representation.
   * @default 'elapsed'
   */
  format?: TimerFormat;
  /**
   * Semantic text type. Matches Timestamp typography behavior.
   * @default 'supporting'
   */
  type?: TextType;
  /** Explicit font size override. Overrides the size from `type`. */
  size?: TextSize;
  /**
   * Text color.
   * @default 'secondary'
   */
  color?: TextColor;
  /** Font weight override. */
  weight?: TextWeight;
}

/**
 * Displays a standardized elapsed duration without scheduling React tick renders.
 *
 * Timer writes changing text and its ISO 8601 duration directly to the owned
 * `<time>` node. Use `elapsed` for compact duration text or `clock` for a
 * stopwatch-like reading.
 *
 * @example
 * ```
 * <Timer />
 * <Timer format="clock" />
 * ```
 */
export function Timer({
  startTime,
  format = 'elapsed',
  type = 'supporting',
  size,
  color = 'secondary',
  weight,
  ref,
  xstyle,
  className,
  style,
  ...rest
}: TimerProps) {
  const [mountTime] = useState(() => Date.now());
  const timerRef = useRef<HTMLTimeElement>(null);
  const mergedRef = useMergedRefs(ref, timerRef);
  const resolvedFormat = resolveFormat(format);
  const initialPresentation = getPresentation(0, resolvedFormat);

  // Syncs the elapsed-time text with a timer.
  useEffect(() => {
    const resolvedStartTime =
      startTime !== undefined && Number.isFinite(startTime)
        ? startTime
        : mountTime;
    let timeoutID: ReturnType<typeof setTimeout> | undefined;
    let previousDateTime: string | undefined;
    let previousText: string | undefined;

    const tick = () => {
      const now = Date.now();
      const elapsedMilliseconds = getElapsedMilliseconds(
        now,
        resolvedStartTime,
      );
      const presentation = getPresentation(elapsedMilliseconds, resolvedFormat);
      const node = timerRef.current;

      if (node != null) {
        if (presentation.text !== previousText) {
          node.textContent = presentation.text;
          previousText = presentation.text;
        }
        if (presentation.dateTime !== previousDateTime) {
          node.dateTime = presentation.dateTime;
          previousDateTime = presentation.dateTime;
        }
      }

      timeoutID = setTimeout(
        tick,
        getMillisecondsUntilNextChange(
          now,
          resolvedStartTime,
          elapsedMilliseconds,
          resolvedFormat,
        ),
      );
    };

    tick();
    return () => {
      if (timeoutID !== undefined) {
        clearTimeout(timeoutID);
      }
    };
  }, [mountTime, resolvedFormat, startTime]);

  const timerProps = mergeProps(themeProps('timer'), {className, style});

  return (
    <Text
      type={type}
      size={size}
      color={color}
      weight={weight}
      xstyle={xstyle}
      {...timerProps}>
      <time
        {...rest}
        ref={mergedRef}
        dateTime="PT0S"
        {...stylex.props(styles.time)}>
        {initialPresentation.text}
      </time>
    </Text>
  );
}

Timer.displayName = 'Timer';