Skip to content

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

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

/**
 * @file Timestamp.test.tsx
 * @input Uses Timestamp, Testing Library, and mocked browser APIs
 * @output Regression coverage for formatting and the focusable details trigger
 * @position Colocated Timestamp behavior and accessibility tests
 */

import 'temporal-polyfill/full/global';
import {
  describe,
  it,
  expect,
  vi,
  beforeAll,
  beforeEach,
  afterAll,
  afterEach,
  onTestFinished,
} from 'vitest';
import {
  render,
  screen,
  act,
  waitFor,
  fireEvent,
  within,
} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Profiler} from 'react';
import {hydrateRoot, type Root} from 'react-dom/client';
import {renderToString} from 'react-dom/server';
import {Timestamp} from './Timestamp';
import {formatInstant} from './formatInstant';
import {formatTooltipLines} from './tooltipEntries';
import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
import {InternationalizationProvider} from '../i18n';
import type {CalendarSystem} from '../utils/calendarSystem';
import {withChineseTemporalAheadOfIntl} from '../__tests__/temporalAheadOfIntl';
import {__resetDevWarnings} from '../utils/devWarning';
import type {ComponentIconMap} from '../Icon/index';
import {defineTheme} from '../theme/defineTheme';
import {Theme} from '../theme/Theme';

let slotThemeCount = 0;

async function openTimestampHoverCard(): Promise<HTMLElement> {
  const timestamp = document.querySelector('time');
  if (timestamp == null) {
    throw new Error('Expected Timestamp to render a <time> element');
  }
  await userEvent.hover(timestamp);
  await waitFor(() => {
    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
  });

  return screen.getByRole('dialog', {hidden: true});
}

/** The long name of a zone at an instant, as Intl spells it in en-US. */
function longZoneName(timeZone?: string, at: Date = new Date()): string {
  return (
    new Intl.DateTimeFormat('en-US', {timeZoneName: 'long', timeZone})
      .formatToParts(at)
      .find(part => part.type === 'timeZoneName')?.value ?? ''
  );
}

describe('Timestamp', () => {
  // The hover card is loaded lazily (React.lazy + Suspense), so its chunk
  // resolves asynchronously the first time a card renders. Warm the module
  // cache once up front so findByRole('dialog') never races the cold import's
  // resolution against its default 1s timeout.
  beforeAll(async () => {
    await import('./TimestampHoverCard');
  });

  beforeEach(() => {
    vi.useFakeTimers();
    vi.setSystemTime(new Date('2026-03-25T12:00:00Z'));
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  it('renders a <time> element with ISO datetime attribute', () => {
    render(
      <Timestamp
        value="2026-03-25T10:00:00Z"
        format="date_time"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    expect(el.tagName).toBe('TIME');
    expect(el.getAttribute('datetime')).toBe('2026-03-25T10:00:00.000Z');
  });

  it('renders relative format for recent times', () => {
    const twoHoursAgo = Date.now() / 1000 - 7200;
    render(<Timestamp value={twoHoursAgo} format="relative" />);
    expect(screen.getByText('2 hours ago')).toBeInTheDocument();
  });

  it('does not round a tier up past its own boundary', () => {
    // Just under each threshold the count must stay within the tier, e.g.
    // 59.98 minutes is "59 minutes ago", never "60 minutes ago".
    const {rerender} = render(
      <Timestamp value={Date.now() / 1000 - 3599} format="relative" />,
    );
    expect(screen.getByText('59 minutes ago')).toBeInTheDocument();

    rerender(<Timestamp value={Date.now() / 1000 - 86399} format="relative" />);
    expect(screen.getByText('23 hours ago')).toBeInTheDocument();

    rerender(
      <Timestamp value={Date.now() / 1000 - 2591999} format="relative" />,
    );
    expect(screen.getByText('29 days ago')).toBeInTheDocument();

    // Same guarantee on the future side.
    rerender(<Timestamp value={Date.now() / 1000 + 3599} format="relative" />);
    expect(screen.getByText('in 59 minutes')).toBeInTheDocument();
  });

  it('renders "now" for very recent times', () => {
    const fiveSecondsAgo = Date.now() / 1000 - 5;
    render(<Timestamp value={fiveSecondsAgo} format="relative" />);
    expect(screen.getByText('now')).toBeInTheDocument();
  });

  it('renders "now" for the current instant (not a future phrase)', () => {
    // A value equal to "right now". Because the internal `now` baseline is
    // captured at render time, it can lag the value by a fraction of a second,
    // producing a tiny negative delta that must not be treated as the future.
    render(<Timestamp value={Date.now() / 1000} format="relative" />);
    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
    expect(screen.getByText('now')).toBeInTheDocument();
  });

  it('renders "now" for a value a hair in the future (clock skew)', () => {
    // Real-world clock / captured-now skew can make a current-ish value land a
    // fraction of a second in the future relative to the component's internal
    // `now`. This must read as the present ("now"), never "in a few
    // seconds". Regression test for the right-now -> future-phrase bug.
    const aHairInTheFuture = Date.now() / 1000 + 0.6;
    render(<Timestamp value={aHairInTheFuture} format="relative" />);
    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
    expect(screen.getByText('now')).toBeInTheDocument();
  });

  it('renders "yesterday" for times ~1 day ago', () => {
    const yesterday = Date.now() / 1000 - 100000;
    render(<Timestamp value={yesterday} format="relative" />);
    expect(screen.getByText('yesterday')).toBeInTheDocument();
  });

  // --- relative_short format ---

  describe('relative_short format', () => {
    it('renders "now" for very recent times', () => {
      render(
        <Timestamp value={Date.now() / 1000 - 5} format="relative_short" />,
      );
      expect(screen.getByText('now')).toBeInTheDocument();
    });

    it('abbreviates each past tier (s/m/h/d/mo/y)', () => {
      const {rerender} = render(
        <Timestamp value={Date.now() / 1000 - 30} format="relative_short" />,
      );
      expect(screen.getByText('30s ago')).toBeInTheDocument();

      rerender(
        <Timestamp
          value={Date.now() / 1000 - 5 * 60}
          format="relative_short"
        />,
      );
      expect(screen.getByText('5m ago')).toBeInTheDocument();

      rerender(
        <Timestamp
          value={Date.now() / 1000 - 2 * 3600}
          format="relative_short"
        />,
      );
      expect(screen.getByText('2h ago')).toBeInTheDocument();

      rerender(
        <Timestamp
          value={Date.now() / 1000 - 3 * 86400}
          format="relative_short"
        />,
      );
      expect(screen.getByText('3d ago')).toBeInTheDocument();

      rerender(
        <Timestamp
          value={Date.now() / 1000 - 90 * 86400}
          format="relative_short"
        />,
      );
      expect(screen.getByText('3mo ago')).toBeInTheDocument();

      rerender(
        <Timestamp
          value={Date.now() / 1000 - 730 * 86400}
          format="relative_short"
        />,
      );
      expect(screen.getByText('2y ago')).toBeInTheDocument();
    });

    it('uses "mo" for months so it never collides with "m" (minutes)', () => {
      // 45 days → months tier. A bare "m" here would be indistinguishable from
      // the minutes unit, so months must render as "mo".
      render(
        <Timestamp
          value={Date.now() / 1000 - 45 * 86400}
          format="relative_short"
        />,
      );
      expect(screen.getByText('1mo ago')).toBeInTheDocument();
    });

    it('renders a single day as "1d ago" (no "yesterday" idiom in short form)', () => {
      render(
        <Timestamp
          value={Date.now() / 1000 - 100000}
          format="relative_short"
        />,
      );
      expect(screen.getByText('1d ago')).toBeInTheDocument();
    });

    it('renders future times with the "in" prefix and abbreviated units', () => {
      const {rerender} = render(
        <Timestamp
          value={Date.now() / 1000 + 5 * 60}
          format="relative_short"
        />,
      );
      expect(screen.getByText('in 5m')).toBeInTheDocument();

      rerender(
        <Timestamp
          value={Date.now() / 1000 + 2 * 3600}
          format="relative_short"
        />,
      );
      expect(screen.getByText('in 2h')).toBeInTheDocument();
    });

    it('does not round a tier up past its own boundary', () => {
      const {rerender} = render(
        <Timestamp value={Date.now() / 1000 - 3599} format="relative_short" />,
      );
      expect(screen.getByText('59m ago')).toBeInTheDocument();

      rerender(
        <Timestamp value={Date.now() / 1000 - 86399} format="relative_short" />,
      );
      expect(screen.getByText('23h ago')).toBeInTheDocument();
    });

    it('treats a hair in the future as "now" (clock skew)', () => {
      render(
        <Timestamp value={Date.now() / 1000 + 2} format="relative_short" />,
      );
      expect(screen.getByText('now')).toBeInTheDocument();
    });

    it('keeps the full absolute date as the accessible name', () => {
      render(
        <Timestamp
          value={Date.now() / 1000 - 2 * 3600}
          format="relative_short"
        />,
      );
      const el = screen.getByText('2h ago');
      // Same a11y contract as the long relative form: the visible short label
      // is backed by the full absolute date for screen readers.
      expect(el).toHaveAttribute('aria-label');
      expect(el.getAttribute('aria-label')).not.toBe('2h ago');
    });
  });

  it.each([
    {format: 'relative' as const, style: 'long' as const},
    {format: 'relative_short' as const, style: 'narrow' as const},
    {format: 'auto' as const, style: 'long' as const},
  ])(
    'updates $format output when the provider locale changes',
    ({format, style}) => {
      const value = Date.now() / 1000 - 2 * 3600;
      const timestamp = (locale: string) => (
        <InternationalizationProvider locale={locale}>
          <Timestamp
            value={value}
            format={format}
            hasTooltip={false}
            data-testid="ts"
          />
        </InternationalizationProvider>
      );
      const expected = (locale: string) =>
        new Intl.RelativeTimeFormat(locale, {
          numeric: 'always',
          style,
        }).format(-2, 'hour');

      const {rerender} = render(timestamp('en-US'));
      expect(screen.getByTestId('ts')).toHaveTextContent(expected('en-US'));

      rerender(timestamp('fr-FR'));
      expect(screen.getByTestId('ts')).toHaveTextContent(expected('fr-FR'));
    },
  );

  it('localizes relative idioms from the provider locale', () => {
    const timestamp = (value: number) => (
      <InternationalizationProvider locale="fr-FR">
        <Timestamp
          value={value}
          format="relative"
          hasTooltip={false}
          data-testid="ts"
        />
      </InternationalizationProvider>
    );
    const formatter = new Intl.RelativeTimeFormat('fr-FR', {
      numeric: 'auto',
      style: 'long',
    });

    const {rerender} = render(timestamp(Date.now() / 1000 - 5));
    expect(screen.getByTestId('ts')).toHaveTextContent(
      formatter.format(0, 'second'),
    );

    rerender(timestamp(Date.now() / 1000 - 100000));
    expect(screen.getByTestId('ts')).toHaveTextContent(
      formatter.format(-1, 'day'),
    );
  });

  // --- Standard display formats ---

  it('updates absolute output when the provider locale changes', () => {
    const value = '2026-01-25T12:00:00Z';
    const timestamp = (locale: string) => (
      <InternationalizationProvider locale={locale}>
        <Timestamp
          value={value}
          format="date_long"
          hasTooltip={false}
          data-testid="ts"
        />
      </InternationalizationProvider>
    );

    const {rerender} = render(timestamp('en-US'));
    expect(screen.getByTestId('ts')).toHaveTextContent('January 25, 2026');

    rerender(timestamp('de-DE'));
    expect(screen.getByTestId('ts')).toHaveTextContent('25. Januar 2026');
  });

  it.each(['full', 'date', 'date_long', 'date_weekday', 'date_time'] as const)(
    'keeps Gregorian years for the %s format under a non-Gregorian locale',
    format => {
      const value = formatInstant(
        new Date('2026-08-22T12:00:00Z'),
        format,
        'th-TH',
        {timeZone: 'UTC'},
      );
      expect(value).toContain('2026');
      expect(value).not.toContain('2569');
    },
  );

  it('keeps Gregorian years in Timestamp output under a non-Gregorian locale', () => {
    render(
      <InternationalizationProvider locale="th-TH">
        <Timestamp
          value="2026-08-22T12:00:00Z"
          format="date_long"
          hasTooltip={false}
          data-testid="ts"
        />
      </InternationalizationProvider>,
    );

    expect(screen.getByTestId('ts')).toHaveTextContent('2026');
    expect(screen.getByTestId('ts')).not.toHaveTextContent('2569');
  });

  it('renders date format', () => {
    render(
      <Timestamp value="2026-02-19T17:00:00Z" format="date" data-testid="ts" />,
    );
    const el = screen.getByTestId('ts');
    expect(el.textContent).toContain('2026');
    // Should not contain time
    expect(el.textContent).not.toContain(':');
  });

  it('renders date_weekday format with a weekday prefix', () => {
    render(
      <Timestamp
        value="2026-02-19T17:00:00Z"
        format="date_weekday"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    // Includes the year and a leading weekday abbreviation, no time portion.
    expect(el.textContent).toContain('2026');
    expect(el.textContent).not.toContain(':');
    // en-US short weekday for 2026-02-19 is "Thu"; assert a weekday word is
    // present without over-fitting the exact locale punctuation.
    expect(el.textContent).toMatch(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/);
  });

  it('renders date_long format with a full month name', () => {
    render(
      <Timestamp
        value="2026-02-19T17:00:00Z"
        format="date_long"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    // Long-month shape: full month name, year, no time portion.
    expect(el.textContent).toContain('February');
    expect(el.textContent).toContain('2026');
    expect(el.textContent).not.toContain(':');
  });

  it('renders date_time format', () => {
    render(
      <Timestamp
        value="2026-02-19T17:00:00Z"
        format="date_time"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    expect(el.textContent).toContain('2026');
    // Should contain a colon for the time portion
    expect(el.textContent).toContain(':');
  });

  it('renders time format', () => {
    render(
      <Timestamp value="2026-02-19T17:00:00Z" format="time" data-testid="ts" />,
    );
    const el = screen.getByTestId('ts');
    // Should contain time but not year
    expect(el.textContent).toContain(':');
    expect(el.textContent).not.toContain('2026');
  });

  // --- System formats ---

  it('renders system_date format', () => {
    render(
      <Timestamp
        value="2026-02-19T17:00:00Z"
        format="system_date"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    expect(el.textContent).toMatch(/2026-02-\d{2}/);
  });

  it('renders system_date_time format', () => {
    render(
      <Timestamp
        value="2026-02-19T17:00:00Z"
        format="system_date_time"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    expect(el.textContent).toMatch(/2026-02-\d{2} \d{2}:\d{2}:\d{2}/);
  });

  it('renders system_time format', () => {
    render(
      <Timestamp
        value="2026-02-19T17:00:00Z"
        format="system_time"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    expect(el.textContent).toMatch(/\d{2}:\d{2}:\d{2}/);
  });

  it('renders unix_seconds format as whole epoch seconds (zone-independent)', () => {
    // 2026-02-19T17:00:00Z is 1771520400 seconds since the epoch. The value is
    // absolute, so it is the same regardless of the viewer's zone.
    render(
      <Timestamp
        value="2026-02-19T17:00:00Z"
        format="unix_seconds"
        data-testid="ts"
      />,
    );
    expect(screen.getByTestId('ts').textContent).toBe('1771520400');
  });

  it('renders unix_seconds from a Unix-seconds value input unchanged', () => {
    render(
      <Timestamp value={1771520400} format="unix_seconds" data-testid="ts" />,
    );
    expect(screen.getByTestId('ts').textContent).toBe('1771520400');
  });

  // --- Auto format ---

  it('auto format uses relative for recent times', () => {
    const oneHourAgo = Date.now() / 1000 - 3600;
    render(<Timestamp value={oneHourAgo} format="auto" />);
    expect(screen.getByText('1 hour ago')).toBeInTheDocument();
  });

  it('auto format uses date_time for old times', () => {
    const oldDate = '2026-01-01T12:00:00Z';
    render(<Timestamp value={oldDate} format="auto" data-testid="ts" />);
    const el = screen.getByTestId('ts');
    expect(el.textContent).toContain('2026');
    expect(el.textContent).not.toContain('ago');
  });

  // --- Accessibility ---

  it('sets aria-label with full absolute time in relative mode', () => {
    const oneHourAgo = Date.now() / 1000 - 3600;
    render(
      <Timestamp
        value={oneHourAgo}
        format="relative"
        hasTooltip={false}
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    expect(el.getAttribute('aria-label')).toBeTruthy();
    expect(el.getAttribute('aria-label')).toContain('2026');
  });

  it('does not set aria-label in non-relative mode', () => {
    render(
      <Timestamp
        value="2026-02-19T17:00:00Z"
        format="date_time"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    expect(el.getAttribute('aria-label')).toBeNull();
  });

  // Timezone abbreviations like "PST" or "GMT+2" are unexpanded abbreviations
  // to a screen-reader user (WCAG 3.1.4) — the AT-facing aria-label must spell
  // the timezone out in full, while visible text keeps the compact short form.
  it('uses the long timezone name in the aria-label (WCAG 3.1.4)', () => {
    const oneHourAgo = new Date(Date.now() - 3600 * 1000);
    render(
      <Timestamp
        value={oneHourAgo.getTime() / 1000}
        format="relative"
        hasTooltip={false}
        data-testid="ts"
      />,
    );

    const longTz =
      new Intl.DateTimeFormat('en', {timeZoneName: 'long'})
        .formatToParts(oneHourAgo)
        .find(p => p.type === 'timeZoneName')?.value ?? '';
    expect(longTz).not.toBe('');
    expect(screen.getByTestId('ts').getAttribute('aria-label')).toContain(
      longTz,
    );
  });

  it('keeps the short timezone form in visible text when isTimezoneShown', () => {
    const date = new Date('2026-03-25T10:00:00Z');
    render(
      <Timestamp
        value="2026-03-25T10:00:00Z"
        format="time"
        isTimezoneShown
        data-testid="ts"
      />,
    );

    const tzPart = (form: 'short' | 'long') =>
      new Intl.DateTimeFormat('en', {timeZoneName: form})
        .formatToParts(date)
        .find(p => p.type === 'timeZoneName')?.value ?? '';
    const text = screen.getByTestId('ts').textContent ?? '';
    expect(text).toContain(tzPart('short'));
    expect(text).not.toContain(tzPart('long'));
  });

  // --- Input handling ---

  it('accepts Unix timestamp in seconds', () => {
    render(<Timestamp value={1740000000} format="date" data-testid="ts" />);
    const el = screen.getByTestId('ts');
    expect(el.getAttribute('datetime')).toBeTruthy();
  });

  it('accepts ISO string', () => {
    render(
      <Timestamp
        value="2026-03-25T10:00:00Z"
        format="date_time"
        data-testid="ts"
      />,
    );
    const el = screen.getByTestId('ts');
    expect(el.getAttribute('datetime')).toBe('2026-03-25T10:00:00.000Z');
  });

  // --- Live updates ---

  it('live updates relative time', () => {
    const now = Date.now() / 1000;
    render(<Timestamp value={now - 5} format="relative" isLive />);
    expect(screen.getByText('now')).toBeInTheDocument();

    act(() => {
      vi.advanceTimersByTime(30_000);
    });
    expect(screen.getByText('35 seconds ago')).toBeInTheDocument();
  });

  // --- Ref ---

  it('forwards ref', () => {
    const ref = {current: null as HTMLTimeElement | null};
    render(
      <Timestamp ref={ref} value="2026-03-25T10:00:00Z" format="date_time" />,
    );
    expect(ref.current).toBeInstanceOf(HTMLTimeElement);
  });

  // --- Test ID ---

  it('spreads data-testid', () => {
    render(
      <Timestamp
        value="2026-03-25T10:00:00Z"
        format="date_time"
        data-testid="my-timestamp"
      />,
    );
    expect(screen.getByTestId('my-timestamp')).toBeInTheDocument();
  });

  // --- Future dates ---

  it('handles future dates in relative mode', () => {
    const oneHourFromNow = Date.now() / 1000 + 3600;
    render(<Timestamp value={oneHourFromNow} format="relative" />);
    expect(screen.getByText('in 1 hour')).toBeInTheDocument();
  });

  it('renders "now" for a value a few seconds in the future (clock skew)', () => {
    // Beyond the sub-second render lag but still within the skew tolerance: a
    // value ~20s ahead of our clock is almost always skew (the value's clock
    // running fast), not a genuine future event, so it should read as the
    // present rather than "in a few seconds".
    const twentySecondsFromNow = Date.now() / 1000 + 20;
    render(<Timestamp value={twentySecondsFromNow} format="relative" />);
    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
    expect(screen.getByText('now')).toBeInTheDocument();
  });

  it('renders a genuine near-future time beyond the skew tolerance with the native formatter', () => {
    // Past the skew window — this is a real upcoming time, not clock drift.
    const fortyFiveSecondsFromNow = Date.now() / 1000 + 45;
    render(
      <Timestamp
        value={fortyFiveSecondsFromNow}
        format="relative"
        hasTooltip={false}
      />,
    );
    expect(
      screen.getByText(
        new Intl.RelativeTimeFormat('en', {
          numeric: 'always',
          style: 'long',
        }).format(45, 'second'),
      ),
    ).toBeInTheDocument();
  });

  // --- Long-ago relative ---

  it('renders months ago for dates older than 30 days', () => {
    const threeMonthsAgo = Date.now() / 1000 - 90 * 86400;
    render(<Timestamp value={threeMonthsAgo} format="relative" />);
    expect(screen.getByText('3 months ago')).toBeInTheDocument();
  });

  it('renders years ago for dates older than 365 days', () => {
    const twoYearsAgo = Date.now() / 1000 - 730 * 86400;
    render(<Timestamp value={twoYearsAgo} format="relative" />);
    expect(screen.getByText('2 years ago')).toBeInTheDocument();
  });

  // --- Auto threshold ---

  it('respects custom autoThreshold', () => {
    const twoHoursAgo = Date.now() / 1000 - 7200;
    render(
      <Timestamp value={twoHoursAgo} format="auto" autoThreshold={3600} />,
    );
    const el = screen.getByRole('time');
    expect(el.textContent).not.toContain('ago');
  });

  // --- Invalid values ---

  it('renders nothing instead of crashing on an unparseable string value', () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    try {
      const {container} = render(
        <Timestamp value="not-a-date" data-testid="ts" />,
      );
      expect(container).toBeEmptyDOMElement();
      expect(warn).toHaveBeenCalledWith(
        expect.stringContaining('could not parse value'),
      );
    } finally {
      warn.mockRestore();
    }
  });

  it('renders nothing instead of crashing on a NaN value', () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    try {
      const {container} = render(<Timestamp value={NaN} data-testid="ts" />);
      expect(container).toBeEmptyDOMElement();
    } finally {
      warn.mockRestore();
    }
  });

  // --- Hover card keyboard reachability (WCAG 1.4.13 / 2.1.1) ---

  describe('hover card keyboard reachability', () => {
    const originalMatches = HTMLElement.prototype.matches;
    const originalShowPopover = HTMLElement.prototype.showPopover;
    const originalHidePopover = HTMLElement.prototype.hidePopover;

    beforeEach(() => {
      // The card content renders inline in a (mocked) popover; real timers let
      // RTL's findBy* and the async paths resolve (the outer beforeEach
      // installs fake timers, which would stall them).
      vi.useRealTimers();

      // Match HoverCard's Popover API mock so dismissal can observe which
      // layer is actually open, including the copy button's nested tooltip.
      const openPopovers = new WeakSet<HTMLElement>();
      HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
        openPopovers.add(this);
      });
      HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
        openPopovers.delete(this);
      });

      // jsdom does not derive :focus-visible from keyboard focus for a <time>
      // element; treat the focused element as focus-visible so the card's
      // keyboard-focus path can be exercised.
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      (HTMLElement.prototype as any).matches = function (
        selector: string,
      ): boolean {
        if (selector === ':popover-open') {
          return openPopovers.has(this);
        }
        if (selector === ':focus-visible') {
          return this === document.activeElement;
        }
        return originalMatches.call(this, selector);
      };
    });

    afterEach(() => {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      (HTMLElement.prototype as any).matches = originalMatches;
      HTMLElement.prototype.showPopover = originalShowPopover;
      HTMLElement.prototype.hidePopover = originalHidePopover;
    });

    it("keeps a caller's tabIndex while the hover card is attached (FR9)", async () => {
      render(
        <Timestamp
          value={Date.now() / 1000 - 3600}
          format="relative"
          tabIndex={-1}
          data-testid="ts"
        />,
      );
      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '-1');
      await openTimestampHoverCard();
      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '-1');
    });

    it('makes the <time> element focusable while the hover card is attached', () => {
      render(
        <Timestamp
          value={Date.now() / 1000 - 3600}
          format="relative"
          data-testid="ts"
        />,
      );
      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');
    });

    it.each([
      ['relative', {format: 'relative'}],
      ['relative_short', {format: 'relative_short'}],
      ['auto', {format: 'auto'}],
      ['configured absolute', {format: 'date_time', tooltipEntries: [{}]}],
    ] as const)(
      'names the %s details card from the tab stop only while it is open',
      async (_, props) => {
        render(
          <Timestamp
            value={Date.now() / 1000 - 3600}
            {...props}
            data-testid="ts"
          />,
        );
        const trigger = screen.getByTestId('ts');
        expect(trigger).toHaveAttribute('tabindex', '0');
        expect(trigger).not.toHaveAttribute('aria-controls');
        act(() => trigger.focus());
        const card = await screen.findByRole('dialog', {hidden: true});
        await waitFor(() => {
          expect(trigger).toHaveAttribute('aria-controls', card.id);
        });
        // The time role supports neither aria-haspopup nor aria-expanded, and
        // the time keeps its own role.
        expect(trigger).not.toHaveAttribute('aria-haspopup');
        expect(trigger).not.toHaveAttribute('aria-expanded');
        expect(trigger).not.toHaveAttribute('role');
        expect(trigger.closest('.astryx-timestamp')).not.toHaveAttribute(
          'aria-haspopup',
        );
      },
    );

    it('shows the hover card when the timestamp receives keyboard focus', async () => {
      const user = userEvent.setup();
      render(
        <Timestamp
          value={Date.now() / 1000 - 3600}
          format="relative"
          data-testid="ts"
        />,
      );
      const el = screen.getByTestId('ts');

      // The card carries the full absolute time in its visible form (short
      // timezone abbreviation) as its single default copyable row. The
      // aria-label spells the timezone out in full (WCAG 3.1.4), so the two
      // strings intentionally differ — compare the card against an
      // independently formatted short-form string after opening it.
      // Compare with normalized whitespace: Intl output can contain narrow
      // no-break spaces that jest-dom's matcher normalization would break on.
      const normalize = (s: string) => s.replace(/\s+/g, ' ');
      const datetime = new Date(el.getAttribute('datetime') ?? '');
      const expected = new Intl.DateTimeFormat('en', {
        year: 'numeric',
        month: 'long',
        day: 'numeric',
        hour: 'numeric',
        minute: '2-digit',
        second: '2-digit',
        timeZoneName: 'short',
      }).format(datetime);
      // Tab onto the timestamp — the only tab stop in the document.
      await user.tab();
      expect(el).toHaveFocus();
      await waitFor(() => {
        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
      });
      const card = screen.getByRole('dialog', {hidden: true});
      expect(normalize(card.textContent ?? '')).toContain(normalize(expected));
      expect(el).toHaveAttribute('aria-controls', card.id);
      expect(el).not.toHaveAttribute('aria-expanded');

      // Move into the card before dismissing it: focus must return to the
      // same semantic timestamp that exposed the popup relationship.
      const copy = screen.getByRole('button', {name: /^Copy /, hidden: true});
      act(() => copy.focus());
      expect(copy).toHaveFocus();
      // The copy button's own tooltip is the topmost layer on focus.
      if (screen.queryByRole('tooltip', {hidden: true})) {
        await user.keyboard('{Escape}');
      }
      await user.keyboard('{Escape}');
      await waitFor(() => {
        expect(el).not.toHaveAttribute('aria-controls');
      });
      expect(el).toHaveFocus();
      expect(el).not.toHaveAttribute('aria-haspopup');
    });

    it('keeps the ref, caller props, and text styling when a card is attached', async () => {
      const ref = {current: null as HTMLTimeElement | null};
      const onFocus = vi.fn();
      const {rerender} = render(
        <Timestamp
          ref={ref}
          value="2026-02-19T17:00:00Z"
          format="date_time"
          tooltipEntries={[{}]}
          aria-label="Published"
          aria-controls="related-content"
          id="published-at"
          data-source="cms"
          onFocus={onFocus}
          type="body"
          color="primary"
          weight="bold"
          className="custom-timestamp"
          style={{marginInlineStart: 12}}
          data-testid="ts"
        />,
      );
      const time = screen.getByTestId('ts');
      expect(ref.current).toBe(time);
      expect(time).toHaveAttribute('aria-label', 'Published');
      expect(time).toHaveAttribute('id', 'published-at');
      expect(time).toHaveAttribute('data-source', 'cms');
      const text = time.closest('.astryx-timestamp');
      expect(text).toHaveClass('astryx-text', 'custom-timestamp');
      expect(text).toHaveAttribute('data-type', 'body');
      expect(text).toHaveAttribute('data-color', 'primary');
      expect(text).toHaveStyle({marginInlineStart: '12px'});

      act(() => time.focus());
      const card = await screen.findByRole('dialog', {hidden: true});
      await waitFor(() => {
        expect(time).toHaveAttribute(
          'aria-controls',
          `related-content ${card.id}`,
        );
      });
      expect(onFocus).toHaveBeenCalledOnce();

      rerender(
        <Timestamp
          ref={ref}
          value="2026-02-19T17:00:00Z"
          format="date_time"
          tooltipEntries={[{}]}
          hasTooltip={false}
          aria-controls="related-content"
          data-testid="ts"
        />,
      );
      expect(ref.current).toBe(screen.getByTestId('ts'));
      expect(ref.current).not.toHaveAttribute('tabindex');
      expect(ref.current).not.toHaveAttribute('aria-haspopup');
      expect(ref.current).toHaveAttribute('aria-controls', 'related-content');
      expect(
        screen.queryByRole('dialog', {hidden: true}),
      ).not.toBeInTheDocument();
    });

    it('keeps a caller aria-controls changed while the card is open', async () => {
      const props = {
        value: '2026-02-19T17:00:00Z',
        format: 'date_time',
        tooltipEntries: [{}],
        'data-testid': 'ts',
      } as const;
      const {rerender} = render(<Timestamp {...props} aria-controls="first" />);
      const time = screen.getByTestId('ts');
      act(() => time.focus());
      const card = await screen.findByRole('dialog', {hidden: true});
      await waitFor(() => {
        expect(time).toHaveAttribute('aria-controls', `first ${card.id}`);
      });

      rerender(<Timestamp {...props} aria-controls="second" />);
      await waitFor(() => {
        expect(time).toHaveAttribute('aria-controls', `second ${card.id}`);
      });

      act(() => time.blur());
      await waitFor(() => {
        expect(time).toHaveAttribute('aria-controls', 'second');
      });
    });

    it('names no card after an open card is removed and a new one attaches', async () => {
      const view = (hasTooltip: boolean) => (
        <>
          <Timestamp
            value="2026-02-19T17:00:00Z"
            format="date_time"
            tooltipEntries={[{}]}
            hasTooltip={hasTooltip}
            data-testid="ts"
          />
          <button type="button">Elsewhere</button>
        </>
      );
      const {rerender} = render(view(true));
      const time = screen.getByTestId('ts');
      act(() => time.focus());
      const card = await screen.findByRole('dialog', {hidden: true});
      await waitFor(() => {
        expect(time).toHaveAttribute('aria-controls', card.id);
      });

      // The open card unmounts without a hide. Focus then moves on, and a new
      // card attaches closed.
      rerender(view(false));
      act(() => screen.getByRole('button', {name: 'Elsewhere'}).focus());
      rerender(view(true));
      await act(async () => {});
      expect(time).toHaveAttribute('tabindex', '0');
      expect(time).not.toHaveAttribute('aria-controls');
    });

    it('keeps the default hover-card row in the viewer zone with timezoneID set', async () => {
      const user = userEvent.setup();
      const originalTZ = process.env.TZ;
      process.env.TZ = 'UTC';
      try {
        render(
          <Timestamp
            value={new Date('2026-03-25T10:00:00Z').getTime() / 1000}
            format="relative"
            timezoneID="Asia/Tokyo"
            data-testid="ts"
          />,
        );
        const el = screen.getByTestId('ts');
        await user.tab();
        expect(el).toHaveFocus();
        await waitFor(() => {
          expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
        });
        const card = screen.getByRole('dialog', {hidden: true});
        // FR7: the default row reads the viewer's zone, not the pinned one.
        expect(card.textContent).toContain('10:00:00');
        expect(card.textContent).not.toContain('19:00:00');
      } finally {
        if (originalTZ === undefined) {
          delete process.env.TZ;
        } else {
          process.env.TZ = originalTZ;
        }
      }
    });

    it('does not add a tab stop when the hover card is disabled', () => {
      render(
        <Timestamp
          value={Date.now() / 1000 - 3600}
          format="relative"
          hasTooltip={false}
          data-testid="ts"
        />,
      );
      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
    });

    it('does not add a tab stop for absolute formats (no hover card)', () => {
      render(
        <Timestamp
          value="2026-02-19T17:00:00Z"
          format="date_time"
          data-testid="ts"
        />,
      );
      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
    });

    it('keeps the full absolute aria-label while the hover card is attached', () => {
      render(
        <Timestamp
          value={Date.now() / 1000 - 3600}
          format="relative"
          data-testid="ts"
        />,
      );
      const label = screen.getByTestId('ts').getAttribute('aria-label');
      expect(label).toBeTruthy();
      // The label is the full absolute string, not the relative text.
      expect(label).not.toContain('ago');
    });
  });

  // --- Default hover card (no tooltipEntries) ---

  describe('default hover card (no tooltipEntries)', () => {
    const originalShowPopover = HTMLElement.prototype.showPopover;
    const originalHidePopover = HTMLElement.prototype.hidePopover;

    beforeEach(() => {
      // The card content renders inline in a (mocked) popover; real timers let
      // RTL's findBy* and the async clipboard write resolve (the outer
      // beforeEach installs fake timers).
      vi.useRealTimers();
      HTMLElement.prototype.showPopover = vi.fn();
      HTMLElement.prototype.hidePopover = vi.fn();
      // jsdom does not implement the async Clipboard API.
      Object.defineProperty(navigator, 'clipboard', {
        value: {writeText: vi.fn().mockResolvedValue(undefined)},
        configurable: true,
      });
    });

    afterEach(() => {
      HTMLElement.prototype.showPopover = originalShowPopover;
      HTMLElement.prototype.hidePopover = originalHidePopover;
      __resetLiveRegionsForTest();
    });

    it('renders the unified copyable card with a single default absolute row', async () => {
      render(
        <Timestamp
          value={Date.now() / 1000 - 3600}
          format="relative"
          data-testid="ts"
        />,
      );
      // With no entries the hover surface is still the copyable card — one
      // surface, one styling — never the old read-only tooltip. (The copy
      // button carries its own small "Copy" tooltip; that is not the hover
      // surface, so exclude it.)
      expect(
        screen
          .queryAllByRole('tooltip', {hidden: true})
          .filter(el => !/^(Copy|Copied)$/.test(el.textContent?.trim() ?? '')),
      ).toHaveLength(0);
      const card = await openTimestampHoverCard();
      // The default card is the named details card, exactly as the configured
      // one is.
      expect(card).toHaveAttribute('aria-label', 'Timestamp details');
      // Exactly one row, carrying the full absolute time in its visible form
      // (short timezone abbreviation) with its own copy button. The
      // aria-label spells the timezone out in full (WCAG 3.1.4), so the two
      // strings intentionally differ — compare the row against an
      // independently formatted short-form string.
      // Without labels the card is still a description list: the value is
      // named by its long time-zone name, which is visually hidden.
      expect(card.querySelectorAll('dl > div > dd')).toHaveLength(1);
      expect(card.querySelector('dl > div > dt')?.textContent).toBe(
        longZoneName(),
      );
      expect(card.querySelectorAll('button')).toHaveLength(1);

      const normalize = (s: string) => s.replace(/\s+/g, ' ');
      const datetime = new Date(
        screen.getByTestId('ts').getAttribute('datetime') ?? '',
      );
      const expected = new Intl.DateTimeFormat('en', {
        year: 'numeric',
        month: 'long',
        day: 'numeric',
        hour: 'numeric',
        minute: '2-digit',
        second: '2-digit',
        timeZoneName: 'short',
      }).format(datetime);
      expect(normalize(card.textContent ?? '')).toContain(normalize(expected));
    });

    it("copies the default absolute row's value", async () => {
      render(<Timestamp value={Date.now() / 1000 - 3600} format="relative" />);
      const card = await openTimestampHoverCard();
      const rowValue = card.querySelector('dd > span')?.textContent ?? '';
      expect(rowValue).toBeTruthy();
      fireEvent.click(card.querySelector('button')!);
      expect(navigator.clipboard.writeText).toHaveBeenCalledWith(rowValue);
      // Let the async copy resolve and flip the button into its copied state
      // so the state update settles inside act().
      await waitFor(() => {
        expect(
          screen.getByRole('button', {name: 'Copied', hidden: true}),
        ).toBeInTheDocument();
      });
    });

    it("shows a 'Copy' tooltip on the copy button, flipping to 'Copied' after a copy", async () => {
      render(<Timestamp value={Date.now() / 1000 - 3600} format="relative" />);
      const card = await openTimestampHoverCard();
      const button = card.querySelector('button')!;
      // The visible tooltip content defaults to the short imperative 'Copy'
      // (the full "Copy <value>" string stays the button's aria-label).
      fireEvent.mouseEnter(button);
      await waitFor(() =>
        expect(
          screen.getByText('Copy', {
            selector: '[role="tooltip"] *, [role="tooltip"]',
          }),
        ).toBeInTheDocument(),
      );
      fireEvent.click(button);
      // After a successful copy the tooltip content flips to 'Copied' in step
      // with the icon/aria-label.
      await waitFor(() =>
        expect(
          screen.getByText('Copied', {
            selector: '[role="tooltip"] *, [role="tooltip"]',
          }),
        ).toBeInTheDocument(),
      );
    });

    describe('copy icon slot', () => {
      // Label each shared icon's artwork, so a test reads which name rendered.
      const icons = {
        copy: <span data-icon="copy" />,
        check: <span data-icon="check" />,
        clock: <span data-icon="clock" />,
        checkDouble: <span data-icon="checkDouble" />,
      };

      async function renderCard(componentIcons?: ComponentIconMap<never>) {
        const theme = defineTheme({
          name: `timestamp-copy-slot-${slotThemeCount++}`,
          icons,
          componentIcons,
        });
        render(
          <Theme theme={theme}>
            <Timestamp value={Date.now() / 1000 - 3600} format="relative" />
          </Theme>,
        );
        const card = await openTimestampHoverCard();
        return card.querySelector('button')!;
      }

      const glyph = (button: HTMLElement) =>
        button.querySelector('[data-icon]')?.getAttribute('data-icon') ?? null;

      async function copy(button: HTMLElement) {
        fireEvent.click(button);
        await waitFor(() => expect(button).toHaveAccessibleName('Copied'));
      }

      it('draws copy, then check while copied, when the theme maps nothing', async () => {
        const button = await renderCard();
        expect(glyph(button)).toBe('copy');
        await copy(button);
        expect(glyph(button)).toBe('check');
      });

      it('passes `copied` to a slot function and draws the name it returns', async () => {
        const slot = vi.fn(({copied}: {copied: boolean}) => ({
          icon: copied ? ('checkDouble' as const) : ('clock' as const),
        }));
        const button = await renderCard({'timestamp-copy': slot});

        expect(glyph(button)).toBe('clock');
        expect(slot).toHaveBeenLastCalledWith({copied: false});
        await copy(button);
        expect(glyph(button)).toBe('checkDouble');
        expect(slot).toHaveBeenLastCalledWith({copied: true});
      });

      it('hides only the glyph for null; the button keeps its name and copy action', async () => {
        const button = await renderCard({'timestamp-copy': null});

        expect(button.querySelector('.astryx-icon')).toBeNull();
        expect(button).toHaveClass('astryx-timestamp-copy-button');
        expect(button.getAttribute('aria-label')).toMatch(/^Copy /);
        await copy(button);
        expect(navigator.clipboard.writeText).toHaveBeenCalled();
      });

      it('changes only the icon size for a size request, not the button', async () => {
        const button = await renderCard({'timestamp-copy': {size: 'lg'}});

        expect(button.querySelector('.astryx-icon')).toHaveAttribute(
          'data-size',
          'lg',
        );
        expect(glyph(button)).toBe('copy');
        expect(button).toHaveAttribute('data-size', 'sm');
      });
    });
  });

  // --- Multi-zone / multi-format copyable hover card (tooltipEntries) ---

  describe('tooltipEntries copyable hover card', () => {
    // A fixed instant that lands on a different calendar day in Tokyo, so a
    // zone-blind implementation is visible in the output.
    const VALUE = '2026-02-19T17:00:00Z';

    const originalShowPopover = HTMLElement.prototype.showPopover;
    const originalHidePopover = HTMLElement.prototype.hidePopover;

    beforeEach(() => {
      // The card content renders inline in a (mocked) popover, so its rows are
      // in the DOM without opening it. Real timers so RTL's findBy* and the
      // async clipboard write resolve (the outer beforeEach installs fake ones).
      vi.useRealTimers();
      HTMLElement.prototype.showPopover = vi.fn();
      HTMLElement.prototype.hidePopover = vi.fn();
      // jsdom does not implement the async Clipboard API.
      Object.defineProperty(navigator, 'clipboard', {
        value: {writeText: vi.fn().mockResolvedValue(undefined)},
        configurable: true,
      });
    });

    afterEach(() => {
      HTMLElement.prototype.showPopover = originalShowPopover;
      HTMLElement.prototype.hidePopover = originalHidePopover;
      __resetLiveRegionsForTest();
    });

    it('presents configured entries as a named card, not a read-only tooltip', async () => {
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          tooltipEntries={[{label: 'Local'}, {timezoneID: 'UTC', label: 'UTC'}]}
        />,
      );
      // Entries present — the surface is the interactive card, never the
      // lightweight read-only tooltip. (The copy button's own "Copy" tooltip
      // is not the hover surface, so exclude it.)
      expect(
        screen
          .queryAllByRole('tooltip', {hidden: true})
          .filter(el => !/^(Copy|Copied)$/.test(el.textContent?.trim() ?? '')),
      ).toHaveLength(0);
      const card = await openTimestampHoverCard();
      expect(card).toHaveAttribute('aria-label', 'Timestamp details');
    });

    it('renders one row per configured entry, read-only by default', async () => {
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          tooltipEntries={[
            {label: 'Local'},
            {timezoneID: 'UTC', label: 'UTC'},
            {timezoneID: 'Asia/Tokyo', label: 'Tokyo'},
          ]}
        />,
      );
      const card = await openTimestampHoverCard();
      expect(card.querySelectorAll('dd')).toHaveLength(3);
      // Entries are read-only unless they opt in, so no copy buttons and no
      // trailing action column are rendered.
      expect(card.querySelectorAll('button')).toHaveLength(0);
      expect(card.textContent).toContain('Local');
      expect(card.textContent).toContain('UTC');
      expect(card.textContent).toContain('Tokyo');
    });

    it('renders a copy button only on rows that opt into isCopyable', async () => {
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          tooltipEntries={[
            {label: 'Local'},
            {timezoneID: 'UTC', label: 'UTC'},
            {
              timezoneID: 'UTC',
              format: 'system_date_time',
              label: 'ISO',
              isCopyable: true,
            },
          ]}
        />,
      );
      const card = await openTimestampHoverCard();
      // Three rows, but only the opted-in row carries a copy button.
      expect(card.querySelectorAll('dd')).toHaveLength(3);
      expect(card.querySelectorAll('button')).toHaveLength(1);
    });

    it('renders each entry in the time zone it names', async () => {
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          tooltipEntries={[
            {timezoneID: 'UTC', format: 'system_date_time', label: 'UTC'},
            {
              timezoneID: 'Asia/Tokyo',
              format: 'system_date_time',
              label: 'Tokyo',
            },
          ]}
        />,
      );
      const card = await openTimestampHoverCard();
      const values = Array.from(card.querySelectorAll('dd')).map(
        el => el.textContent,
      );
      // Machine formats are locale- and host-timezone-independent, so these
      // hold on any developer machine and on CI.
      expect(values).toEqual(['2026-02-19 17:00:00', '2026-02-20 02:00:00']);
    });

    it("copies an opted-in row's value and flips the button to the copied state", async () => {
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          tooltipEntries={[
            {
              label: 'ISO',
              format: 'system_date_time',
              timezoneID: 'UTC',
              isCopyable: true,
            },
          ]}
        />,
      );
      const card = await openTimestampHoverCard();
      const [rowValue] = Array.from(card.querySelectorAll('dd')).map(
        el => el.textContent ?? '',
      );
      const copyButton = card.querySelectorAll('button')[0];

      fireEvent.click(copyButton);
      expect(navigator.clipboard.writeText).toHaveBeenCalledWith(rowValue);

      // The button announces and flips its icon/label to the copied state.
      await waitFor(() => {
        expect(
          screen.getByRole('button', {name: 'Copied', hidden: true}),
        ).toBeInTheDocument();
      });
    });

    it('announces the copy to a polite live region through the i18n catalog', async () => {
      render(
        <InternationalizationProvider
          locale="fr"
          overrides={{fr: {'@astryx.timestamp.copied': 'Copié'}}}>
          <Timestamp
            value={VALUE}
            format="relative"
            tooltipEntries={[
              {timezoneID: 'UTC', label: 'UTC', isCopyable: true},
            ]}
          />
        </InternationalizationProvider>,
      );
      const card = await openTimestampHoverCard();
      fireEvent.click(card.querySelector('button')!);
      await waitFor(() => {
        expect(
          document.querySelector('[data-astryx-live-region="polite"]'),
        ).toHaveTextContent('Copié');
      });
    });

    it('shows the card for absolute formats once entries are configured', async () => {
      render(
        <Timestamp
          value={VALUE}
          format="date_time"
          tooltipEntries={[{timezoneID: 'UTC', label: 'UTC'}]}
          data-testid="ts"
        />,
      );
      // Without entries an absolute format has no hover surface at all;
      // configuring entries must not be silently ignored.
      const card = await openTimestampHoverCard();
      expect(card.textContent).toContain('UTC');
      // ...and the anchor becomes keyboard-reachable, as it is for relative.
      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');
    });

    it('treats an empty entry list exactly like no configuration', () => {
      render(
        <Timestamp
          value={VALUE}
          format="date_time"
          tooltipEntries={[]}
          data-testid="ts"
        />,
      );
      // An empty array is not a way to configure the card — with no lines to
      // show, an absolute format stays surface-less (no tab stop, no card).
      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
      expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
    });

    it('stays inert when hasTooltip is false even with entries configured', () => {
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          hasTooltip={false}
          tooltipEntries={[{timezoneID: 'UTC', label: 'UTC'}]}
          data-testid="ts"
        />,
      );
      // hasTooltip stays the on/off switch: false suppresses the surface even
      // when entries would otherwise upgrade it to the card.
      expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
      expect(
        screen
          .queryAllByRole('tooltip', {hidden: true})
          .filter(el => !/^(Copy|Copied)$/.test(el.textContent?.trim() ?? '')),
      ).toHaveLength(0);
      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
      expect(
        screen.getByTestId('ts').getAttribute('aria-describedby'),
      ).toBeNull();
    });

    it('leaves the accessible name unchanged when entries are configured', () => {
      const value = Date.now() / 1000 - 3600;
      const {unmount} = render(
        <Timestamp value={value} format="relative" data-testid="a" />,
      );
      const before = screen.getByTestId('a').getAttribute('aria-label');
      unmount();

      render(
        <Timestamp
          value={value}
          format="relative"
          tooltipEntries={[{timezoneID: 'UTC', label: 'UTC'}]}
          data-testid="b"
        />,
      );
      // The accessible name stays the canonical absolute time in the viewer's
      // own zone; the extra zones reach assistive tech through the card, not
      // by being stuffed into the name.
      expect(screen.getByTestId('b').getAttribute('aria-label')).toBe(before);
    });

    it('does not add an accessible name to absolute formats with entries', () => {
      render(
        <Timestamp
          value={VALUE}
          format="date_time"
          tooltipEntries={[{timezoneID: 'UTC'}]}
          data-testid="ts"
        />,
      );
      expect(screen.getByTestId('ts').getAttribute('aria-label')).toBeNull();
    });

    it('renders nothing for an unparseable value even with entries', () => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const {container} = render(
          <Timestamp
            value="not-a-date"
            tooltipEntries={[{timezoneID: 'UTC', label: 'UTC'}]}
          />,
        );
        // The invalid-value bail-out runs before any hover-surface work, so
        // there is no half-rendered card anchored to nothing.
        expect(container).toBeEmptyDOMElement();
      } finally {
        warn.mockRestore();
      }
    });

    it('shows configured entries when auto resolves to an absolute format', async () => {
      render(
        <Timestamp
          value={VALUE}
          format="auto"
          autoThreshold={0}
          tooltipEntries={[
            {timezoneID: 'UTC', format: 'system_date_time', label: 'UTC'},
          ]}
          data-testid="ts"
        />,
      );
      // autoThreshold={0} forces the absolute branch regardless of the clock.
      const card = await openTimestampHoverCard();
      expect(card.textContent).toContain('2026-02-19 17:00:00');
      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');
    });

    it('accepts a unix-seconds value alongside entries', async () => {
      render(
        <Timestamp
          value={Date.parse(VALUE) / 1000}
          format="relative"
          tooltipEntries={[
            {timezoneID: 'UTC', format: 'system_date_time', label: 'UTC'},
          ]}
        />,
      );
      const card = await openTimestampHoverCard();
      expect(card.textContent).toContain('2026-02-19 17:00:00');
    });

    it('pairs exactly one label cell with one value cell per entry', async () => {
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          tooltipEntries={[
            {timezoneID: 'UTC', label: 'UTC'},
            {timezoneID: 'Asia/Tokyo'},
            {timezoneID: 'Europe/London', label: 'London'},
          ]}
        />,
      );
      const card = await openTimestampHoverCard();
      // An unlabeled entry still emits its label cell, so the grid stays
      // aligned; its zone's long name, visually hidden, names its value.
      expect(card.querySelectorAll('dt')).toHaveLength(3);
      expect(card.querySelectorAll('dd')).toHaveLength(3);
      expect(card.querySelectorAll('dt')[1].textContent).toBe(
        longZoneName('Asia/Tokyo', new Date(VALUE)),
      );
    });

    it('keeps a copyable labelled card a valid description list', async () => {
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          tooltipEntries={[
            {timezoneID: 'UTC', label: 'UTC', isCopyable: true},
            {timezoneID: 'Asia/Tokyo', label: 'Tokyo'},
          ]}
        />,
      );
      const card = await openTimestampHoverCard();
      const list = card.querySelector('dl')!;
      // Each group holds only its dt and dd (WCAG 2.2 1.3.1); the copy
      // button sits inside the value.
      for (const group of Array.from(list.children)) {
        expect(group.tagName).toBe('DIV');
        expect(Array.from(group.children, el => el.tagName)).toEqual([
          'DT',
          'DD',
        ]);
      }
      expect(list.querySelectorAll('dd button')).toHaveLength(1);
    });

    it('gives the tab stop back when entries are removed', () => {
      const {rerender} = render(
        <Timestamp
          value={VALUE}
          format="date_time"
          tooltipEntries={[{timezoneID: 'UTC'}]}
          data-testid="ts"
        />,
      );
      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');

      rerender(<Timestamp value={VALUE} format="date_time" data-testid="ts" />);
      // The surface is driven purely by entry presence, so dropping the prop
      // must also drop the tab stop rather than stranding one.
      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
    });

    it('does not crash on an unknown time zone', async () => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        render(
          <Timestamp
            value={VALUE}
            format="relative"
            tooltipEntries={[
              {timezoneID: 'Not/AZone', format: 'system_date_time'},
              {timezoneID: 'UTC', format: 'system_date_time'},
            ]}
          />,
        );
        const card = await openTimestampHoverCard();
        const values = Array.from(card.querySelectorAll('dd')).map(
          el => el.textContent,
        );
        expect(values).toHaveLength(2);
        expect(values[1]).toBe('2026-02-19 17:00:00');
        expect(warn).toHaveBeenCalledWith(expect.stringContaining('Not/AZone'));
      } finally {
        warn.mockRestore();
      }
    });
  });

  describe('one formatter behind both surfaces', () => {
    // The rendered text and a tooltip line are two views of the same instant.
    // They are meant to come from one formatter parameterized by zone, not two
    // that happen to agree: a format added or reshaped on one surface and not
    // the other is a silent drift, invisible until someone compares them.
    // These assertions compare the two surfaces directly, so re-forking either
    // one fails here. Locale- and timezone-agnostic: nothing is pinned to a
    // literal, only the two paths to each other.
    const VALUE = '2026-02-19T17:00:00Z';

    const SHARED_FORMATS = [
      'date',
      'date_long',
      'date_weekday',
      'date_time',
      'time',
      'system_date',
      'system_date_time',
      'system_time',
    ] as const;

    it.each(SHARED_FORMATS)(
      'renders %s identically as text and as a zone-less tooltip line',
      format => {
        render(
          <Timestamp
            value={VALUE}
            format={format}
            hasTooltip={false}
            data-testid="ts"
          />,
        );
        const [line] = formatTooltipLines(new Date(VALUE), [{format}], 'en');
        expect(line.value).toBe(screen.getByTestId('ts').textContent);
      },
    );

    it('renders the full style as the aria-label and as a line, differing only in zone-name spelling', () => {
      // 'full' is the one member with no visible-text counterpart — it backs
      // the accessible name of a relative timestamp and the tooltip's default
      // line. The two must not drift apart on anything but the zone name: the
      // aria-label spells the zone out in full for assistive tech (WCAG 3.1.4),
      // the visible line keeps the abbreviation. Comparing them after swapping
      // the abbreviation for the spelled-out form keeps this a direct
      // surface-to-surface check, so re-forking either path still fails here.
      render(
        <Timestamp
          value={VALUE}
          format="relative"
          hasTooltip={false}
          data-testid="ts"
        />,
      );
      const date = new Date(VALUE);
      const tzPart = (form: 'short' | 'long') =>
        new Intl.DateTimeFormat('en', {timeZoneName: form})
          .formatToParts(date)
          .find(p => p.type === 'timeZoneName')?.value ?? '';
      const [line] = formatTooltipLines(date, [{format: 'full'}], 'en');
      expect(screen.getByTestId('ts').getAttribute('aria-label')).toBe(
        line.value.replace(tzPart('short'), tzPart('long')),
      );
    });
  });
});

describe('Timestamp pass-through props', () => {
  it('forwards pass-through props to the time element', () => {
    render(
      <Timestamp
        value="2024-01-15T10:30:00Z"
        format="date_time"
        aria-label="Published"
        id="published-at"
        data-source="cms"
        data-testid="stamp"
      />,
    );
    const time = screen.getByTestId('stamp');
    expect(time.tagName).toBe('TIME');
    expect(time).toHaveAttribute('aria-label', 'Published');
    expect(time).toHaveAttribute('id', 'published-at');
    expect(time).toHaveAttribute('data-source', 'cms');
  });

  it("keeps a caller's aria-label on a relative timestamp (FR5)", () => {
    render(
      <Timestamp
        value={Date.now()}
        format="relative"
        aria-label="Caller label"
        data-source="cms"
        data-testid="stamp"
      />,
    );
    const stamp = screen.getByTestId('stamp');
    expect({
      ariaLabel: stamp.getAttribute('aria-label'),
      dataSource: stamp.getAttribute('data-source'),
    }).toEqual({ariaLabel: 'Caller label', dataSource: 'cms'});
  });

  it('names a relative timestamp by the full date when the caller names nothing (FR5)', () => {
    render(
      <Timestamp
        value={Date.now()}
        format="relative"
        aria-label={undefined}
        data-testid="stamp"
      />,
    );
    expect(screen.getByTestId('stamp').getAttribute('aria-label')).toMatch(
      /\d{4}/,
    );
  });
});

/**
 * Counts `new Date()` calls with no argument (reads of the current time) made
 * while `run` executes.
 */
function countClockReads(run: () => void): number {
  const ActiveDate = globalThis.Date;
  let reads = 0;
  class CountingDate extends ActiveDate {
    constructor(...args: [] | [string | number | Date]) {
      if (args.length === 0) {
        reads += 1;
      }
      super(...(args as [string | number | Date]));
    }
  }
  globalThis.Date = CountingDate as DateConstructor;
  try {
    run();
  } finally {
    globalThis.Date = ActiveDate;
  }
  return reads;
}

describe('Timestamp server rendering', () => {
  beforeEach(() => {
    vi.useFakeTimers();
    vi.setSystemTime(new Date('2026-03-25T12:00:00Z'));
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  const originalTZ = process.env.TZ;

  afterEach(() => {
    if (originalTZ === undefined) {
      delete process.env.TZ;
    } else {
      process.env.TZ = originalTZ;
    }
  });

  it.each(['date', 'date_time', 'time', 'unix_seconds'] as const)(
    'never reads the current time for the absolute %s format',
    format => {
      const element = (
        <Timestamp value="2026-03-25T10:00:00Z" format={format} />
      );
      expect(countClockReads(() => renderToString(element))).toBe(0);
      expect(countClockReads(() => render(element))).toBe(0);
    },
  );

  it.each(['relative', 'relative_short', 'auto'] as const)(
    'renders the %s format as the full date and time in UTC on the server without reading the clock',
    format => {
      const value = '2026-03-25T10:00:00Z';
      let html = '';
      expect(
        countClockReads(() => {
          html = renderToString(<Timestamp value={value} format={format} />);
        }),
      ).toBe(0);
      const host = document.createElement('div');
      host.innerHTML = html;
      expect(host.textContent).toBe(
        formatInstant(new Date(value), 'date_time', 'en-US', {
          timeZone: 'UTC',
          isTimezoneShown: true,
        }),
      );
    },
  );

  it('never commits the UTC placeholder when a client Timestamp switches to a relative format', () => {
    const value = Date.now() / 1000 - 7200;
    const committed: string[] = [];
    function Spy({format}: {format: 'date' | 'relative'}) {
      return (
        <Profiler
          id="ts"
          onRender={() => {
            committed.push(document.querySelector('time')?.textContent ?? '');
          }}>
          <Timestamp value={value} format={format} hasTooltip={false} />
        </Profiler>
      );
    }
    const {rerender} = render(<Spy format="date" />);
    committed.length = 0;
    rerender(<Spy format="relative" />);
    expect(screen.getByText('2 hours ago')).toBeInTheDocument();
    expect(committed.some(text => text.includes('UTC'))).toBe(false);
  });

  describe('across time zones', () => {
    it('writes the same server markup whatever the server time zone', () => {
      const element = (
        <Timestamp value="2026-03-25T10:00:00Z" format="relative" />
      );
      process.env.TZ = 'UTC';
      const utc = renderToString(element);
      process.env.TZ = 'Asia/Tokyo';
      expect(renderToString(element)).toBe(utc);
    });

    it('hydrates server markup from another time zone without a mismatch', () => {
      const value = Date.now() / 1000 - 7200;
      const element = (
        <Timestamp value={value} format="relative" hasTooltip={false} />
      );
      process.env.TZ = 'UTC';
      const host = document.createElement('div');
      document.body.appendChild(host);
      host.innerHTML = renderToString(element);

      process.env.TZ = 'America/Los_Angeles';
      const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
      let root: Root | undefined;
      try {
        act(() => {
          root = hydrateRoot(host, element, {
            onRecoverableError: error => {
              throw error;
            },
          });
        });
        expect(host.textContent).toBe('2 hours ago');
        expect(errors).not.toHaveBeenCalled();
      } finally {
        errors.mockRestore();
        act(() => root?.unmount());
        host.remove();
      }
    });
  });

  it('hydrates the server markup without a mismatch, then shows the relative phrase', () => {
    const value = Date.now() / 1000 - 7200;
    const element = (
      <Timestamp value={value} format="relative" hasTooltip={false} />
    );
    const host = document.createElement('div');
    document.body.appendChild(host);
    host.innerHTML = renderToString(element);
    expect(host.textContent).not.toBe('2 hours ago');

    const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
    let root: Root | undefined;
    try {
      act(() => {
        root = hydrateRoot(host, element);
      });
      expect(host.textContent).toBe('2 hours ago');
      expect(errors).not.toHaveBeenCalled();
    } finally {
      errors.mockRestore();
      act(() => root?.unmount());
      host.remove();
    }
  });

  it('renders an explicit time zone identically whatever the host zone', () => {
    // Oct 15 in UTC, Oct 14 in Los Angeles: without the prop the host zone
    // decides which day renders.
    const element = (
      <Timestamp
        value={1665792474000}
        format="date"
        timezoneID="UTC"
        hasTooltip={false}
      />
    );
    process.env.TZ = 'UTC';
    const utc = renderToString(element);
    expect(utc).toContain('Oct 15, 2022');
    process.env.TZ = 'America/Los_Angeles';
    expect(renderToString(element)).toBe(utc);
    process.env.TZ = 'Asia/Tokyo';
    expect(renderToString(element)).toBe(utc);
  });

  it('shifts the reading into the named zone', () => {
    process.env.TZ = 'UTC';
    const {rerender} = render(
      <Timestamp
        value={1665792474000}
        format="date"
        timezoneID="America/Los_Angeles"
        hasTooltip={false}
      />,
    );
    expect(screen.getByText('Oct 14, 2022')).toBeInTheDocument();
    rerender(
      <Timestamp
        value={1665792474000}
        format="date"
        timezoneID="Asia/Tokyo"
        hasTooltip={false}
      />,
    );
    expect(screen.getByText('Oct 15, 2022')).toBeInTheDocument();
  });

  it('hydrates explicit-zone server markup from another host zone without a mismatch', () => {
    const element = (
      <Timestamp
        value={1665792474000}
        format="date_time"
        timezoneID="UTC"
        hasTooltip={false}
      />
    );
    process.env.TZ = 'UTC';
    const host = document.createElement('div');
    document.body.appendChild(host);
    host.innerHTML = renderToString(element);

    process.env.TZ = 'America/Los_Angeles';
    const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
    let root: Root | undefined;
    try {
      act(() => {
        root = hydrateRoot(host, element, {
          onRecoverableError: error => {
            throw error;
          },
        });
      });
      expect(host.textContent).toContain('Oct 15, 2022');
      expect(errors).not.toHaveBeenCalled();
    } finally {
      errors.mockRestore();
      act(() => root?.unmount());
      host.remove();
    }
  });

  it('keeps the UTC-labelled placeholder for a relative format with timezoneID', () => {
    // FR3/ORD1: while the clock is pending the server placeholder is UTC
    // with its label, whatever `timezoneID` pins.
    const element = (
      <Timestamp
        value={new Date('2026-03-25T10:00:00Z').getTime() / 1000}
        format="relative"
        timezoneID="America/Los_Angeles"
        hasTooltip={false}
      />
    );
    process.env.TZ = 'America/Los_Angeles';
    const html = renderToString(element);
    expect(html).toContain('UTC');
    expect(html).not.toContain('PDT');
  });

  it('ignores timezoneID in the relative accessible name', () => {
    const value = Date.now() / 1000 - 3600;
    const {rerender} = render(
      <Timestamp
        value={value}
        format="relative"
        hasTooltip={false}
        data-testid="ts"
      />,
    );
    const viewerLabel = screen.getByTestId('ts').getAttribute('aria-label');
    rerender(
      <Timestamp
        value={value}
        format="relative"
        timezoneID="Asia/Tokyo"
        hasTooltip={false}
        data-testid="ts"
      />,
    );
    expect(screen.getByTestId('ts').getAttribute('aria-label')).toBe(
      viewerLabel,
    );
  });

  it('falls back to the viewer zone on an unknown time zone', () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    try {
      process.env.TZ = 'UTC';
      render(
        <Timestamp
          value={1665792474000}
          format="date"
          timezoneID="Never/Whence"
          hasTooltip={false}
        />,
      );
      expect(screen.getByText('Oct 15, 2022')).toBeInTheDocument();
      expect(warn).toHaveBeenCalledWith(
        expect.stringContaining('Never/Whence'),
      );
    } finally {
      warn.mockRestore();
    }
  });
});

describe('Timestamp calendar systems', () => {
  const INSTANT = new Date('2026-10-30T12:00:00Z');
  const VALUE = INSTANT.toISOString();

  // Independent option bags: the date-bearing formats as Intl spells them.
  const DATE_OPTIONS = {
    full: {
      year: 'numeric',
      month: 'long',
      day: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
      second: '2-digit',
      timeZoneName: 'short',
    },
    date: {year: 'numeric', month: 'short', day: 'numeric'},
    date_long: {year: 'numeric', month: 'long', day: 'numeric'},
    date_weekday: {
      weekday: 'short',
      year: 'numeric',
      month: 'short',
      day: 'numeric',
    },
    date_time: {
      year: 'numeric',
      month: 'short',
      day: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    },
  } as const satisfies Record<string, Intl.DateTimeFormatOptions>;
  const DATE_FORMATS = Object.keys(
    DATE_OPTIONS,
  ) as (keyof typeof DATE_OPTIONS)[];
  const CALENDAR_LOCALES = [
    {calendar: 'persian', locale: 'en', year: '1405'},
    {calendar: 'persian', locale: 'fa', year: '۱۴۰۵'},
    {calendar: 'hebrew', locale: 'en', year: '5787'},
    {calendar: 'hebrew', locale: 'he', year: '5787'},
    {calendar: 'buddhist', locale: 'en', year: '2569'},
    {calendar: 'buddhist', locale: 'th', year: '2569'},
  ] as const;

  afterEach(() => {
    __resetDevWarnings();
    vi.restoreAllMocks();
  });

  describe.each(CALENDAR_LOCALES)(
    'formatInstant in $calendar under $locale',
    ({calendar, locale, year}) => {
      it.each(DATE_FORMATS)('writes %s in the calendar', format => {
        const value = formatInstant(INSTANT, format, locale, {
          timeZone: 'UTC',
          calendar,
        });
        expect(value).toBe(
          new Intl.DateTimeFormat(locale, {
            ...DATE_OPTIONS[format],
            timeZone: 'UTC',
            calendar,
          }).format(INSTANT),
        );
        expect(value).toContain(year);
        expect(value).not.toContain('2026');
      });

      it.each([
        'time',
        'system_date',
        'system_date_time',
        'system_time',
        'unix_seconds',
      ] as const)('keeps %s unchanged', format => {
        expect(
          formatInstant(INSTANT, format, locale, {timeZone: 'UTC', calendar}),
        ).toBe(formatInstant(INSTANT, format, locale, {timeZone: 'UTC'}));
      });
    },
  );

  it.each(DATE_FORMATS)('defaults %s to the Gregorian calendar', format => {
    expect(formatInstant(INSTANT, format, 'fa', {timeZone: 'UTC'})).toBe(
      formatInstant(INSTANT, format, 'fa', {
        timeZone: 'UTC',
        calendar: 'gregory',
      }),
    );
    expect(formatInstant(INSTANT, format, 'en', {timeZone: 'UTC'})).toContain(
      '2026',
    );
  });

  it('keeps the system formats Gregorian ISO in every calendar', () => {
    expect(
      formatInstant(INSTANT, 'system_date_time', 'fa', {
        timeZone: 'UTC',
        calendar: 'persian',
      }),
    ).toBe('2026-10-30 12:00:00');
  });

  function renderTimestamp(
    provider: {locale: string; calendar?: CalendarSystem},
    format: 'date_long' | 'date_time' | 'system_date' | 'relative',
  ) {
    return render(
      <InternationalizationProvider {...provider}>
        <Timestamp
          value={VALUE}
          format={format}
          hasTooltip={false}
          data-testid="ts"
        />
      </InternationalizationProvider>,
    );
  }

  it.each(CALENDAR_LOCALES)(
    'renders date_long in the provider calendar $calendar under $locale',
    ({calendar, locale, year}) => {
      renderTimestamp({locale, calendar}, 'date_long');
      const text = screen.getByTestId('ts').textContent;
      expect(text).toBe(
        formatInstant(INSTANT, 'date_long', locale, {calendar}),
      );
      expect(text).toContain(year);
    },
  );

  it('keeps the time of day of date_time in the provider calendar', () => {
    renderTimestamp({locale: 'en', calendar: 'persian'}, 'date_time');
    const text = screen.getByTestId('ts').textContent ?? '';
    expect(text).toBe(
      formatInstant(INSTANT, 'date_time', 'en', {calendar: 'persian'}),
    );
    expect(text).toContain('Aban');
    expect(text).toMatch(/\d:\d\d/);
  });

  it('keeps system_date Gregorian ISO under a provider calendar', () => {
    renderTimestamp({locale: 'fa', calendar: 'persian'}, 'system_date');
    expect(screen.getByTestId('ts').textContent).toBe(
      formatInstant(INSTANT, 'system_date', 'fa'),
    );
    expect(screen.getByTestId('ts').textContent).toMatch(/^\d{4}-\d{2}-\d{2}$/);
  });

  it('names relative output with the full date in the provider calendar', () => {
    vi.useFakeTimers();
    vi.setSystemTime(new Date(INSTANT.getTime() + 2 * 3600 * 1000));
    try {
      renderTimestamp({locale: 'en', calendar: 'hebrew'}, 'relative');
      const name = screen.getByTestId('ts').getAttribute('aria-label') ?? '';
      expect(name).toBe(
        formatInstant(INSTANT, 'full', 'en', {
          calendar: 'hebrew',
          timeZoneNameStyle: 'long',
        }),
      );
      expect(name).toContain('5787');
      expect(screen.getByTestId('ts').textContent).toBe('2 hours ago');
    } finally {
      vi.useRealTimers();
    }
  });

  it('keeps Gregorian dates for a -u-ca- keyword in the provider locale', () => {
    renderTimestamp({locale: 'th-TH-u-ca-buddhist'}, 'date_long');
    const ts = screen.getByTestId('ts');
    expect(ts).toHaveTextContent('2026');
    expect(ts).not.toHaveTextContent('2569');
  });

  it('keeps Gregorian dates when the locale names no calendar', () => {
    renderTimestamp({locale: 'fa-IR'}, 'date_long');
    expect(screen.getByTestId('ts').textContent).toBe(
      formatInstant(INSTANT, 'date_long', 'fa-IR'),
    );
  });

  it('writes tooltip rows in the provider calendar', async () => {
    await import('./TimestampHoverCard');
    const originalShowPopover = HTMLElement.prototype.showPopover;
    HTMLElement.prototype.showPopover = vi.fn();
    onTestFinished(() => {
      HTMLElement.prototype.showPopover = originalShowPopover;
    });
    render(
      <InternationalizationProvider locale="en" calendar="persian">
        <Timestamp
          value={VALUE}
          format="date"
          tooltipEntries={[
            {timezoneID: 'UTC', label: 'UTC'},
            {timezoneID: 'UTC', format: 'system_date_time', label: 'ISO'},
          ]}
          data-testid="ts"
        />
      </InternationalizationProvider>,
    );
    const card = await openTimestampHoverCard();
    expect(
      within(card).getByText(
        formatInstant(INSTANT, 'full', 'en', {
          timeZone: 'UTC',
          calendar: 'persian',
        }),
      ),
    ).toBeInTheDocument();
    expect(within(card).getByText('2026-10-30 12:00:00')).toBeInTheDocument();
  });

  describe('without Temporal', () => {
    const globals = globalThis as {Temporal?: unknown};
    let savedTemporal: unknown;

    beforeAll(() => {
      savedTemporal = globals.Temporal;
      delete globals.Temporal;
    });

    afterAll(() => {
      globals.Temporal = savedTemporal;
    });

    it('shows Gregorian dates for a calendar that needs Temporal', () => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      renderTimestamp({locale: 'en', calendar: 'persian'}, 'date_long');
      expect(screen.getByTestId('ts').textContent).toBe(
        formatInstant(INSTANT, 'date_long', 'en'),
      );
      expect(warn).toHaveBeenCalledWith(
        expect.stringContaining('needs a Temporal that supports it'),
      );
    });

    it('still shows the buddhist calendar, which needs no Temporal', () => {
      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
      renderTimestamp({locale: 'en', calendar: 'buddhist'}, 'date_long');
      expect(screen.getByTestId('ts')).toHaveTextContent('2569');
      expect(warn).not.toHaveBeenCalled();
    });
  });

  it.each(['date', 'date_long', 'date_weekday', 'date_time', 'full'] as const)(
    'writes %s in the `chinese` calendar on the day that Calendar shows',
    format => {
      const value = withChineseTemporalAheadOfIntl(() =>
        formatInstant(new Date('2027-02-06T12:00:00Z'), format, 'en', {
          timeZone: 'UTC',
          calendar: 'chinese',
        }),
      );
      // Intl alone names the 30th day of the Twelfth Month of 2026.
      expect(value).toMatch(/\b(Mo1|First Month) 1, 2027/);
    },
  );

  it.each(['date_time', 'full'] as const)(
    'writes %s in `iso8601` as in `gregory`',
    format => {
      expect(
        formatInstant(INSTANT, format, 'en', {
          timeZone: 'UTC',
          calendar: 'iso8601',
        }),
      ).toBe(formatInstant(INSTANT, format, 'en', {timeZone: 'UTC'}));
    },
  );

  it('hydrates a clock format rendered on a server without Temporal', () => {
    const value = Date.now() / 1000 - 7200;
    const element = (
      <InternationalizationProvider locale="en" calendar="persian">
        <Timestamp value={value} format="relative" hasTooltip={false} />
      </InternationalizationProvider>
    );
    const globals = globalThis as {Temporal?: unknown};
    const savedTemporal = globals.Temporal;
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const host = document.createElement('div');
    delete globals.Temporal;
    try {
      host.innerHTML = renderToString(element);
    } finally {
      globals.Temporal = savedTemporal;
    }
    document.body.appendChild(host);
    const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
    const recovered: unknown[] = [];
    let root: Root | undefined;
    try {
      act(() => {
        root = hydrateRoot(host, element, {
          onRecoverableError: error => recovered.push(error),
        });
      });
      expect(host.textContent).toBe('2 hours ago');
      expect(recovered).toEqual([]);
      expect(errors).not.toHaveBeenCalled();
    } finally {
      errors.mockRestore();
      warn.mockRestore();
      act(() => root?.unmount());
      host.remove();
    }
  });
});