An open source design system that's fully customizable and agent ready
TypeScript
// 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();
}
});
});