feat(Timestamp): show one instant across several time zones on hover (#4188)

[AKnassa]

What this does

Hovering a timestamp can now show the same moment in several time zones and formats at once, each on its own labelled line. Today it always shows exactly one line, in the reader's own zone.

<Timestamp
  value={savedAt}
  tooltipEntries={[
    {label: 'Local'},
    {timezoneID: 'UTC', label: 'UTC'},
  ]}
/>

One new prop. Each entry is one line: an optional timezoneID (omit it, or pass 'local', for the reader's own zone), an optional format, an optional label.

Why the shape is this shape

The issue says "needs API design", so this went through API Arbitration rather than my taste: four candidate APIs written independently, each given only its own docs to six naive authors who were asked for real product outcomes ("hovering should show the reader's zone and the incident's origin zone, clearly labelled"), then scored by three judges on different criteria.

Candidate	Naive authors served cleanly	Conventions	Evidence	Implementation
Entry array (shipped)	6/6, zero invented props	8	8.5	5.5
Orthogonal axes	5/6 (one silently wrong output)	6.5	7.5	7
Composition / render prop	6/6	4.5	7	8.5
Scalar minimal	4/6 (two produced broken code)	6	4	6.5

Two calls I made against the panel, so they're easy to challenge:

1. The implementation judge preferred a renderTooltip render prop. I didn't take it — renderTooltip is already taken in useTooltip.tsx:198 with a different contract, the issue's acceptance criteria ask for per-line labels as an API rather than delegated to each caller, and the bare-escape-hatch shape produced keyboard-unreachable tooltips in naive hands.
2. All three judges wanted exported formatting helpers grafted in. I cut them. The evidence for helpers was a different candidate failing because it exported nothing — not evidence this one needs them. Worth revisiting if ragged tooltips turn up in real use.

Nothing changes unless you opt in

Without the new prop, the tooltip content is the same single string it is today — no wrapper element, no markup change. An empty array counts as no configuration, so hasTooltip stays the only on/off switch.

One deliberate behaviour change worth your eyes: configuring entries also turns the tooltip on for absolute formats, which have never had one. Leaving that shut would let format silently suppress another prop's output, which the conventions wiki forbids. The cost is that those timestamps gain a tab stop and focus ring, exactly as relative ones already have — so a column of 500 of them gains 500 tab stops. Opt-in only, but it is a real tab-order change.

'full' (the long absolute style) lives only in the tooltip vocabulary and never touches TimestampFormat — so this has zero conflicting hunks with #4199, and the date_long / date_weekday you're adding there become valid tooltip formats for free. I confirmed the tripwire by simulating that change: adding a member to TimestampFormat fails the build (TS2366) in both the new switch and the existing formatTimestamp, rather than silently returning nothing.

Two things I need a call on

• The shape itself. The vocabulary (tooltipEntries, timezoneID, 'local', 'full') is my reading of your open questions, not your decision. Happy to reshape.
• The tab-order change described above.

Found while testing, not fixed here

parseValue misreads every pre-1970 millisecond timestamp: the heuristic value < 1e12 ? value * 1000 : value is applied to a signed number, so a negative millisecond value gets multiplied again. The moon landing (-14182940000) renders as the year 1520. It's pre-existing, unrelated to tooltips, and changes behaviour for every Timestamp consumer, so it wants its own PR — say the word and I'll open one.

Fixed in passing, because it sits on the prop next door: isTimezoneShown's JSDoc, .doc.mjs (en/zh/dense) and its showcase block all claimed it applied to system_date_time and system_time. It never has — formatTimestamp has no such branch, so the showcase was demonstrating a no-op.

How to check it

Storybook → Core/Timestamp → Tooltip — multiple time zones: local+UTC, three labelled zones, one zone in two formats, and a UTC-only audit log. Hover or tab to each.

Worth knowing: the tooltip is capped at 300px, so the long full style plus a label wraps. The docs steer multi-zone tooltips to date_time, which fits on one line.

Testing

93 Timestamp tests, up from 32 before this branch. All timezone- and locale-agnostic, because the repo pins TZ in neither vitest nor CI — a dev machine and a UTC runner have to agree, so exact assertions only use explicit-zone system_* output.

Covered: the date line (+14 / -11, 25 hours apart), 45-minute offsets, midnight rendering as 00 and not 24, both halves of a repeated DST hour, year and leap-day boundaries, empty and whitespace-padded zone ids, legacy link ids, casing, unknown ids degrading to the reader's zone instead of throwing, an unparseable value, auto resolving to an absolute format, and the aria-describedby wiring that is the only route to assistive tech on absolute formats.

Eleven mutations were run against the implementation; every one was caught by a test. Full suite 7472 pass / 0 fail (baseline on d762f825d was 7414 / 0 — no pre-existing failures to excuse). Core and Storybook typecheck clean, ESLint clean, changeset valid.

Closes #4188

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 23, 2026 3:32am

[github-actions]

PR Analysis Report

Modified Components

Timestamp

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	539	-
Complexity	N/A	Very High (62)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.7KB	0B

Accessibility Audit

Status: 1 accessibility violation(s) found — 1 serious.

Timestamp - 1 issue(s)

• 🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
  • Rule: color-contrast · Affects 1/14 stories · Learn more
  • WCAG: 1.4.3 (Level AA)

---

_{Generated by PR Enrichment workflow | View full report}