Skip to content

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

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

'use client';

/**
 * @file Timestamp.tsx
 * @input Uses React, Text, lazy TimestampHoverCard, provider locale and
 *   calendar, and Timestamp formatters
 * @output Exports Timestamp component and related types
 * @position Core implementation; a stable time node anchors lazily attached details
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Timestamp/formatRelativeTime.ts
 * - /packages/core/src/Timestamp/Timestamp.doc.mjs
 * - /packages/core/src/Timestamp/Timestamp.test.tsx
 * - /packages/core/src/Timestamp/index.ts
 * - /apps/storybook/stories/Timestamp.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Timestamp/ (showcase blocks)
 */

import {
  lazy,
  Suspense,
  useEffect,
  useRef,
  useState,
  useSyncExternalStore,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {Text} from '../Text';
import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
import {mergeProps} from '../utils';
import {useDevWarning} from '../hooks/useDevWarning';
import {useLocale} from '../i18n/useLocale';
import {useCalendarSystem} from '../i18n/useCalendarSystem';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import {
  ROLELESS_TRIGGER,
  labelledTriggerAttributes,
} from '../HoverCard/popupTrigger';
import {formatInstant, formatZoneName} from './formatInstant';
import {formatRelativeTime} from './formatRelativeTime';
import {formatTooltipLines, resolveTimezoneID} from './tooltipEntries';
import type {
  TimestampTooltipEntry,
  TimestampTooltipLine,
} from './tooltipEntries';

import {useMergedRefs} from '../hooks/useMergedRefs';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Timestamp/Timestamp.generated';

registerEnglishFallback(english);
// Load the overlay lazily so a card-less Timestamp — the default — never
// bundles HoverCard or the copy affordance's Icon/IconButton. Mirrors the code
// split the read-only Tooltip path used before it.
const LazyTimestampHoverCard = lazy(async () => import('./TimestampHoverCard'));

// =============================================================================
// Types
// =============================================================================

export type TimestampFormat =
  | 'relative'
  | 'relative_short'
  | 'auto'
  | 'date'
  | 'date_long'
  | 'date_weekday'
  | 'date_time'
  | 'time'
  | 'system_date'
  | 'system_date_time'
  | 'system_time'
  | 'unix_seconds';

export interface TimestampProps extends BaseProps<HTMLTimeElement> {
  /** Ref forwarded to the root `<time>` element. */
  ref?: React.Ref<HTMLTimeElement>;
  /** The date/time to display. Accepts Unix timestamps (seconds) or ISO 8601 strings. */
  value: string | number;
  /**
   * Display format.
   * - `'relative'`: "2 hours ago", "yesterday", "now"
   * - `'relative_short'`: "2h ago", "1d ago", "now" in English — the
   *   locale's native narrow relative-time pattern, for compact,
   *   space-constrained surfaces
   * - `'auto'`: Relative for recent times, `date_time` for older
   * - `'date'`: "Mar 21, 2025"
   * - `'date_long'`: "March 21, 2025"
   * - `'date_weekday'`: "Wed, Mar 21, 2025"
   * - `'date_time'`: "Mar 21, 2025, 2:51 PM"
   * - `'time'`: "2:51 PM"
   * - `'system_date'`: "2025-03-21"
   * - `'system_date_time'`: "2025-03-21 14:51:53"
   * - `'system_time'`: "14:51:53"
   * - `'unix_seconds'`: "1742565113" — Unix time in whole seconds since the
   *   epoch. Absolute (zone-independent), so it ignores any tooltip time zone.
   * @default 'auto'
   */
  format?: TimestampFormat;
  /**
   * IANA time zone the absolute formats render in, such as `'UTC'` or
   * `'America/Los_Angeles'`. Omit (or pass `'local'`) for the viewer's own
   * zone. An explicit zone renders identically on the server and the client,
   * so it is the way to show an absolute time without a hydration mismatch;
   * without it the server markup depends on the server's zone. Relative
   * formats name no instant, so their visible text ignores it. Configured
   * `tooltipEntries` rows still follow it. An unknown identifier warns once
   * in development and falls back to the viewer's zone.
   */
  timezoneID?: string;
  /**
   * Threshold in seconds for 'auto' format to switch from relative to date_time.
   * @default 604800 (7 days)
   */
  autoThreshold?: number;
  /**
   * Whether to show a card with the full date/time on hover or keyboard focus. The card
   * is copyable — its default single row carries the full absolute time — and
   * `tooltipEntries` customizes its rows.
   * @default true
   */
  hasTooltip?: boolean;
  /**
   * Lines to show on hover, so one instant can be read — and optionally
   * copied — in several time zones and/or formats at once. Each entry is one
   * line, rendered in the order given, with an optional label.
   *
   * Rows are read-only unless they set `isCopyable` (default `false`). A
   * copyable row shows a copy button in a dedicated trailing action column so
   * the buttons align across rows; that column is only present when some row
   * is copyable. With no entries the card shows a single default row with the
   * full absolute time in the viewer's own zone, which is copyable.
   *
   * An entry without its own `timezoneID` follows the Timestamp's
   * `timezoneID` when set, else the viewer's zone; `'local'` always means
   * the viewer's zone.
   *
   * Configuring entries also attaches the surface to absolute formats, which
   * otherwise have no hover card at all. `hasTooltip={false}` still suppresses
   * it, and an empty array is treated as no configuration.
   *
   * @default undefined — a single default row with the full absolute time in
   *   the viewer's own time zone
   * @example
   * ```
   * <Timestamp
   *   value={savedAt}
   *   tooltipEntries={[
   *     {label: 'Your time'},
   *     {timezoneID: 'UTC', label: 'UTC'},
   *     {timezoneID: 'UTC', format: 'system_date_time', label: 'ISO', isCopyable: true},
   *   ]}
   * />
   * ```
   */
  tooltipEntries?: ReadonlyArray<TimestampTooltipEntry>;
  /**
   * Whether to append the timezone abbreviation after the timestamp text.
   * Applies to the date_time and time formats. The system_* formats stay
   * machine-readable and never carry a timezone abbreviation.
   *
   * Affects the visible text only — use `tooltipEntries` to control the
   * tooltip's time zones.
   * @default false
   */
  isTimezoneShown?: boolean;
  /**
   * Whether the relative time should update live.
   * @default false
   */
  isLive?: boolean;
  /**
   * Semantic text type. Determines size, weight, and line-height from theme.
   * @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;
  /** Test ID for testing frameworks. */
  'data-testid'?: string;
}

// =============================================================================
// Styles
// =============================================================================

const styles = stylex.create({
  time: {
    display: 'inline',
    fontFamily: 'inherit',
    fontStyle: 'normal',
    // Reset <time> element defaults
    fontSize: 'inherit',
    lineHeight: 'inherit',
    color: 'inherit',
    fontWeight: 'inherit',
  },
});

// =============================================================================
// Formatting utilities
// =============================================================================

const MINUTE = 60;
const HOUR = 3600;
const DAY = 86400;

/** Default auto threshold: 7 days in seconds */
const DEFAULT_AUTO_THRESHOLD = 7 * DAY;

function parseValue(value: string | number): Date {
  if (typeof value === 'number') {
    // Heuristic: if the number is less than 1e12, treat as seconds; otherwise ms.
    // Unix timestamps in seconds are < 1e12 until ~2286.
    return new Date(value < 1e12 ? value * 1000 : value);
  }
  return new Date(value);
}

/** Returns the interval (in ms) at which a relative timestamp should update. */
function getLiveInterval(diffSeconds: number): number {
  const absDiff = Math.abs(diffSeconds);
  if (absDiff < MINUTE) {
    return 1000;
  } // every second
  if (absDiff < HOUR) {
    return 30_000;
  } // every 30s
  if (absDiff < DAY) {
    return 60_000;
  } // every minute
  return 300_000; // every 5 minutes
}

// Whether this render may read the current time. Server renders (including
// static prerenders) and the hydration pass read `false`, so the markup never
// depends on when it was rendered; client renders read `true`.
const subscribeToNothing = () => () => {};
const canReadClockOnClient = () => true;
const canReadClockOnServer = () => false;

/** Whether a format is non-relative (i.e. shows a fixed date/time). */
function isAbsoluteFormat(
  format: TimestampFormat,
): format is Exclude<TimestampFormat, 'relative' | 'relative_short' | 'auto'> {
  return (
    format !== 'relative' && format !== 'relative_short' && format !== 'auto'
  );
}

/**
 * Whether a format renders a relative phrase ("2 hours ago" / "2h ago") rather
 * than a fixed instant. Both the long and short relative forms share the same
 * treatment: they get the accessible full-date name, the hover tooltip, and
 * live updates.
 */
function isRelativeFormat(
  format: TimestampFormat,
): format is 'relative' | 'relative_short' {
  return format === 'relative' || format === 'relative_short';
}

// =============================================================================
// Component
// =============================================================================

/**
 * Displays a formatted timestamp as human-readable text.
 *
 * Renders a semantic `<time>` element with an ISO 8601 `datetime` attribute,
 * styled via Text. Supports relative ("2 hours ago"), multiple absolute
 * formats, and auto formatting. Optionally shows a hover card with the full
 * absolute time (copyable) and can update live.
 *
 * @example
 * ```
 * <Timestamp value="2026-02-19T17:00:00Z" />
 * <Timestamp value={1740000000} format="date" />
 * <Timestamp value={date} format="auto" isLive />
 * <Timestamp value={event.timestamp} format="system_date_time" />
 * ```
 */
export function Timestamp({
  value,
  format = 'auto',
  timezoneID: timezoneIDProp,
  autoThreshold = DEFAULT_AUTO_THRESHOLD,
  hasTooltip = true,
  tooltipEntries,
  isTimezoneShown = false,
  isLive = false,
  type = 'supporting',
  size,
  color = 'secondary',
  weight,
  xstyle,
  className,
  style,
  ref,
  'data-testid': testId,
  ...rest
}: TimestampProps) {
  const t = useComponentTranslator();
  const locale = useLocale();
  const calendar = useCalendarSystem(undefined, 'Timestamp');
  const timeRef = useRef<HTMLTimeElement>(null);
  const mergedTimeRef = useMergedRefs(ref, timeRef);
  // Only relative and auto formats depend on the current time. Absolute
  // formats never read the clock, so they render identically on the server,
  // in a static prerender, and on the client. A clock-dependent format reads
  // it on the client only: server renders and the hydration pass show the
  // full date and time in UTC, and the client switches to the relative phrase
  // right after hydration.
  const needsClock = !isAbsoluteFormat(format);
  const canReadClock = useSyncExternalStore(
    subscribeToNothing,
    canReadClockOnClient,
    canReadClockOnServer,
  );
  // The open card's id, which the card reports as it shows and hides.
  const [openCardId, setOpenCardId] = useState<string | null>(null);
  const [now, setNow] = useState<Date | null>(() =>
    needsClock && canReadClock ? new Date() : null,
  );
  // Read the clock during render once it may be read: after hydration (the
  // store re-renders with its client value) and when `format` switches from
  // an absolute value to a clock-dependent one, so the placeholder never
  // commits on the client.
  if (needsClock && canReadClock && now === null) {
    // eslint-disable-next-line @eslint-react/purity -- seeds clock state once, like the initializer; never runs on the server or while hydrating
    setNow(new Date());
  }

  const date = parseValue(value);
  // An unparseable value (a malformed date string, or a NaN timestamp from
  // missing data) yields an Invalid Date, and formatting one throws "Invalid
  // time value" — crashing the whole tree. Compute nothing from it here and
  // bail out below (after the hooks) instead.
  const isValidDate = !Number.isNaN(date.getTime());
  const isoString = isValidDate ? date.toISOString() : '';

  // Determine effective format. Until the clock is read, a clock-dependent
  // format renders as the full date and time.
  const isClockPending = needsClock && now === null;
  const diffSeconds =
    now === null ? 0 : Math.round((now.getTime() - date.getTime()) / 1000);
  const effectiveFormat: TimestampFormat = isClockPending
    ? 'date_time'
    : format === 'auto'
      ? Math.abs(diffSeconds) <= autoThreshold
        ? 'relative'
        : 'date_time'
      : format;

  // Absolute text uses `timezoneID`, else the viewer's zone. A named zone makes
  // the text the same on the server and the client. It does not reach the UTC
  // placeholder, the default card row or the relative name.
  const timezoneID = resolveTimezoneID(timezoneIDProp, 'timezoneID');
  const displayText = !isValidDate
    ? ''
    : effectiveFormat === 'relative'
      ? formatRelativeTime(date, now ?? date, locale, 'long')
      : effectiveFormat === 'relative_short'
        ? formatRelativeTime(date, now ?? date, locale, 'narrow')
        : isAbsoluteFormat(effectiveFormat)
          ? formatInstant(
              date,
              effectiveFormat,
              locale,
              // The pre-hydration placeholder is Gregorian and in UTC, with its zone,
              // whatever `timezoneID` pins. The server and the client then write the
              // same text, with or without Temporal.
              isClockPending
                ? {timeZone: 'UTC', isTimezoneShown: true}
                : {timeZone: timezoneID, isTimezoneShown, calendar},
            )
          : '';

  // Full absolute text for the tooltip (visible — keeps the compact timezone
  // abbreviation) and for the AT-facing aria-label, which spells the timezone
  // out in full: abbreviations like "PST" or "GMT+2" are unexpanded
  // abbreviations to a screen-reader user (WCAG 3.1.4). Both stay in the
  // viewer's zone: the default hover-card row and the relative accessible name.
  const fullAbsoluteText = isValidDate
    ? formatInstant(date, 'full', locale, {timeZone: undefined, calendar})
    : '';
  const ariaLabelText = isValidDate
    ? formatInstant(date, 'full', locale, {
        timeZone: undefined,
        timeZoneNameStyle: 'long',
        calendar,
      })
    : '';

  // Syncs the relative time with an interval timer while the timestamp is live.
  useEffect(() => {
    if (!isLive || !isValidDate || !isRelativeFormat(effectiveFormat)) {
      return;
    }

    const interval = getLiveInterval(diffSeconds);
    const timer = setInterval(() => {
      setNow(new Date());
    }, interval);

    return () => clearInterval(timer);
  }, [isLive, isValidDate, effectiveFormat, diffSeconds]);

  useDevWarning(
    'Timestamp',
    `could not parse value ${JSON.stringify(value)} as a date. Rendering nothing.`,
    !isValidDate,
  );

  // An empty array is not a second way to spell "off" — `hasTooltip` stays the
  // only on/off axis — so normalize it away before anything reads it.
  const entries =
    tooltipEntries !== undefined && tooltipEntries.length > 0
      ? tooltipEntries
      : undefined;

  // Absolute formats have never carried a hover surface. Leaving that gate
  // closed when a consumer has explicitly configured tooltip lines would let
  // `format` silently suppress another prop's output, so entry presence opens
  // it too. With no entries this reduces to the original condition exactly.
  const showTooltip =
    isValidDate &&
    hasTooltip &&
    (isRelativeFormat(effectiveFormat) || entries !== undefined);

  // A card that unmounts while open never reports its hide. Without a card,
  // forget its id, so the time names no element that is gone.
  if (!showTooltip && openCardId !== null) {
    setOpenCardId(null);
  }

  // Placed after all hooks so the hook order stays stable across renders.
  if (!isValidDate) {
    return null;
  }

  // The rows the hover card renders: the configured entries, or the single
  // default absolute line shown when none are set. Either way the surface is
  // the same copyable card — the default line is a one-row card carrying the
  // full absolute time, itself copyable, just like a configured entry.
  const lines: ReadonlyArray<TimestampTooltipLine> =
    entries === undefined
      ? [
          {
            value: fullAbsoluteText,
            zoneName: isValidDate ? formatZoneName(date, locale) : '',
            isCopyable: true,
          },
        ]
      : formatTooltipLines(date, entries, locale, calendar, timezoneID);

  const timestampProps = mergeProps(
    themeProps('timestamp', {format: effectiveFormat}),
    {className, style},
  );

  const timeElement = (
    <time
      ref={mergedTimeRef}
      dateTime={isoString}
      data-testid={testId}
      {...stylex.props(styles.time)}
      {...rest}
      // `ariaLabelText` is '' only for an invalid date, which bails out
      // before rendering — but keep the guard local: an empty aria-label
      // must be omitted entirely (not rendered as aria-label="") so AT
      // falls back to reading the visible <time> content.
      // A caller's own name wins.
      {...(isRelativeFormat(effectiveFormat) &&
      ariaLabelText !== '' &&
      rest['aria-label'] == null
        ? {'aria-label': ariaLabelText}
        : {})}
      // A bare <time> cannot take focus. Add the tab stop only while a card
      // is attached, so keyboard users can open it. A caller's tabIndex wins.
      {...(showTooltip && rest.tabIndex == null ? {tabIndex: 0} : {})}
      // The time names the open card after a caller's own ids. The time role
      // supports neither aria-haspopup nor aria-expanded.
      {...(showTooltip
        ? labelledTriggerAttributes(
            ROLELESS_TRIGGER,
            {controls: rest['aria-controls']},
            {id: openCardId, isOpen: openCardId != null},
          )
        : null)}>
      {displayText}
    </time>
  );

  // Keep the focusable node outside Suspense. Attaching the lazy overlay must
  // not replace a timestamp the reader focused while its chunk was loading.
  return (
    <>
      <Text
        type={type}
        size={size}
        color={color}
        weight={weight}
        xstyle={xstyle}
        {...timestampProps}>
        {timeElement}
      </Text>
      {showTooltip && (
        <Suspense fallback={null}>
          <LazyTimestampHoverCard
            lines={lines}
            label={t('@astryx.timestamp.detailsLabel')}
            triggerRef={timeRef}
            onCardOpenChange={setOpenCardId}
          />
        </Suspense>
      )}
    </>
  );
}

Timestamp.displayName = 'Timestamp';