@astryxdesign/core 0.1.9-canary.d2d84f8 → 0.1.9-canary.e00a241

package/src/Timestamp/Timestamp.test.tsx

@@ -4,6 +4,7 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Timestamp} from './Timestamp';
+import {formatTooltipLines} from './tooltipEntries';
 
 describe('Timestamp', () => {
   beforeEach(() => {
@@ -487,4 +488,374 @@ describe('Timestamp', () => {
       expect(label).not.toContain('ago');
     });
   });
+
+  // --- Multi-zone / multi-format tooltip entries ---
+
+  describe('tooltipEntries', () => {
+    // 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 tooltip is lazy-loaded; real timers let the dynamic import and
+      // RTL's findBy* resolve (the outer beforeEach installs fake timers).
+      vi.useRealTimers();
+      HTMLElement.prototype.showPopover = vi.fn();
+      HTMLElement.prototype.hidePopover = vi.fn();
+    });
+
+    afterEach(() => {
+      HTMLElement.prototype.showPopover = originalShowPopover;
+      HTMLElement.prototype.hidePopover = originalHidePopover;
+    });
+
+    it('leaves the default tooltip as a single unwrapped line', async () => {
+      render(
+        <Timestamp
+          value={Date.now() / 1000 - 3600}
+          format="relative"
+          data-testid="ts"
+        />,
+      );
+      const layer = await screen.findByRole('tooltip', {hidden: true});
+      // No entries configured — the tooltip content stays the bare string it
+      // has always been, with no list wrapper introduced around it.
+      expect(layer.querySelector('dl')).toBeNull();
+
+      const normalize = (s: string) => s.replace(/\s+/g, ' ');
+      expect(normalize(layer.textContent ?? '')).toContain(
+        normalize(screen.getByTestId('ts').getAttribute('aria-label') ?? '\0'),
+      );
+    });
+
+    it('renders one tooltip line per configured entry', async () => {
+      render(
+        <Timestamp
+          value={VALUE}
+          format="relative"
+          tooltipEntries={[
+            {label: 'Local'},
+            {timezoneID: 'UTC', label: 'UTC'},
+            {timezoneID: 'Asia/Tokyo', label: 'Tokyo'},
+          ]}
+        />,
+      );
+      const layer = await screen.findByRole('tooltip', {hidden: true});
+      expect(layer.querySelectorAll('dd')).toHaveLength(3);
+      expect(layer.textContent).toContain('Local');
+      expect(layer.textContent).toContain('UTC');
+      expect(layer.textContent).toContain('Tokyo');
+    });
+
+    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 layer = await screen.findByRole('tooltip', {hidden: true});
+      const values = Array.from(layer.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('shows a tooltip 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 tooltip at all; configuring
+      // entries must not be silently ignored.
+      const layer = await screen.findByRole('tooltip', {hidden: true});
+      expect(layer.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"
+        />,
+      );
+      // `hasTooltip` stays the only on/off switch — an empty array is not a
+      // second way to spell "off", and it must not widen the gate either.
+      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
+    });
+
+    it('still honors hasTooltip={false} when entries are configured', () => {
+      render(
+        <Timestamp
+          value={VALUE}
+          format="date_time"
+          hasTooltip={false}
+          tooltipEntries={[{timezoneID: 'UTC'}]}
+          data-testid="ts"
+        />,
+      );
+      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
+    });
+
+    it('leaves the accessible name unchanged when entries are configured', async () => {
+      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 tooltip's
+      // aria-describedby, 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 tooltip work, so there is
+        // no half-rendered tooltip 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 layer = await screen.findByRole('tooltip', {hidden: true});
+      expect(layer.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 layer = await screen.findByRole('tooltip', {hidden: true});
+      expect(layer.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 layer = await screen.findByRole('tooltip', {hidden: true});
+      // An unlabeled entry still emits its label cell, so the two-column grid
+      // stays aligned and the <dl> stays valid markup.
+      expect(layer.querySelectorAll('dt')).toHaveLength(3);
+      expect(layer.querySelectorAll('dd')).toHaveLength(3);
+      expect(layer.querySelectorAll('dt')[1].textContent).toBe('');
+    });
+
+    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 widened gate 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('describes an absolute-format timestamp with its tooltip', async () => {
+      render(
+        <Timestamp
+          value={VALUE}
+          format="date_time"
+          tooltipEntries={[{timezoneID: 'UTC', label: 'UTC'}]}
+          data-testid="ts"
+        />,
+      );
+      const layer = await screen.findByRole('tooltip', {hidden: true});
+      const el = screen.getByTestId('ts');
+      // An absolute format carries no aria-label, so aria-describedby is the
+      // only route the configured zones have to assistive tech.
+      expect(el.getAttribute('aria-label')).toBeNull();
+      await waitFor(() => {
+        expect(el.getAttribute('aria-describedby')).toBe(layer.id);
+      });
+      expect(layer.id).toBeTruthy();
+    });
+
+    it('leaves no tooltip and no description when hasTooltip is false', () => {
+      render(
+        <Timestamp
+          value={VALUE}
+          format="relative"
+          hasTooltip={false}
+          tooltipEntries={[{timezoneID: 'UTC', label: 'UTC'}]}
+          data-testid="ts"
+        />,
+      );
+      expect(
+        screen.queryByRole('tooltip', {hidden: true}),
+      ).not.toBeInTheDocument();
+      // No orphaned reference pointing at a tooltip that was never rendered.
+      expect(
+        screen.getByTestId('ts').getAttribute('aria-describedby'),
+      ).toBeNull();
+    });
+
+    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 layer = await screen.findByRole('tooltip', {hidden: true});
+        const values = Array.from(layer.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}]);
+        expect(line.value).toBe(screen.getByTestId('ts').textContent);
+      },
+    );
+
+    it('renders the full style identically as the aria-label and as a line', () => {
+      // '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. Those two must not drift apart either.
+      render(
+        <Timestamp
+          value={VALUE}
+          format="relative"
+          hasTooltip={false}
+          data-testid="ts"
+        />,
+      );
+      const [line] = formatTooltipLines(new Date(VALUE), [{format: 'full'}]);
+      expect(line.value).toBe(
+        screen.getByTestId('ts').getAttribute('aria-label'),
+      );
+    });
+  });
 });

package/src/Timestamp/Timestamp.tsx

@@ -16,7 +16,7 @@
  * - /packages/cli/templates/blocks/components/Timestamp/ (showcase blocks)
  */
 
-import {useEffect, useRef, useState, lazy, Suspense} from 'react';
+import {useEffect, useRef, useState, lazy, Suspense, Fragment} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Text} from '../Text';
 import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
@@ -24,8 +24,10 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
-import {colorVars} from '../theme/tokens.stylex';
-import {SHARED_DATE_FORMAT_OPTIONS} from '../utils/plainDate';
+import {colorVars, spacingVars} from '../theme/tokens.stylex';
+import {formatInstant} from './formatInstant';
+import {formatTooltipLines} from './tooltipEntries';
+import type {TimestampTooltipEntry} from './tooltipEntries';
 
 const LazyXDSTooltip = lazy(async () =>
   import('../Tooltip/Tooltip').then(mod => ({default: mod.Tooltip})),
@@ -78,8 +80,35 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
    */
   hasTooltip?: boolean;
   /**
-   * Whether to append the timezone abbreviation after the timestamp.
-   * Applies to date_time, time, system_date_time, and system_time formats.
+   * Lines to show in the hover tooltip, so one instant can be read in several
+   * time zones and/or formats at once. Each entry is one line, rendered in the
+   * order given, with an optional label.
+   *
+   * Configuring entries also attaches the tooltip to absolute formats, which
+   * otherwise have no tooltip at all. `hasTooltip={false}` still suppresses it,
+   * and an empty array is treated as no configuration.
+   *
+   * @default undefined — a single line with the full absolute time in the
+   *   viewer's own time zone
+   * @example
+   * ```
+   * <Timestamp
+   *   value={savedAt}
+   *   tooltipEntries={[
+   *     {label: 'Your time'},
+   *     {timezoneID: 'UTC', label: 'UTC'},
+   *   ]}
+   * />
+   * ```
+   */
+  tooltipEntries?: ReadonlyArray<TimestampTooltipEntry>;
+  /**
+   * Whether to append the timezone abbreviation after the timestamp text.
+   * Applies to the date_time and time formats. The system_* formats stay
+   * machine-readable and never carry a timezone abbreviation.
+   *
+   * Affects the visible text only — use `tooltipEntries` to control the
+   * tooltip's time zones.
    * @default false
    */
   isTimezoneShown?: boolean;
@@ -137,6 +166,31 @@ const styles = stylex.create({
       ':focus-visible': '2px',
     },
   },
+  // Label/value pairs for a multi-entry tooltip. The label column is sized to
+  // its content, so when no entry carries a label it collapses to zero width
+  // and the values sit exactly where a plain list of lines would.
+  tooltipLines: {
+    display: 'grid',
+    gridTemplateColumns: 'auto 1fr',
+    rowGap: spacingVars['--spacing-0-5'],
+    marginBlock: 0,
+    marginInline: 0,
+  },
+  tooltipLabel: {
+    marginBlock: 0,
+    marginInline: 0,
+    // Only a label that actually has text earns the gutter, keeping the
+    // unlabeled case flush.
+    paddingInlineEnd: {
+      default: 0,
+      ':not(:empty)': spacingVars['--spacing-2'],
+    },
+  },
+  tooltipValue: {
+    marginBlock: 0,
+    // <dd> carries a 40px inline start margin from the UA stylesheet.
+    marginInline: 0,
+  },
 });
 
 // =============================================================================
@@ -244,89 +298,6 @@ function getRelativeTimeString(date: Date, now: Date): string {
   return `${years} ${years === 1 ? 'year' : 'years'} ago`;
 }
 
-function pad(n: number): string {
-  return String(n).padStart(2, '0');
-}
-
-function formatTimestamp(
-  date: Date,
-  format: Exclude<TimestampFormat, 'relative' | 'auto'>,
-  isTimezoneShown: boolean,
-): string {
-  switch (format) {
-    case 'date':
-      return new Intl.DateTimeFormat(
-        undefined,
-        SHARED_DATE_FORMAT_OPTIONS.date,
-      ).format(date);
-
-    case 'date_long':
-      return new Intl.DateTimeFormat(
-        undefined,
-        SHARED_DATE_FORMAT_OPTIONS.date_long,
-      ).format(date);
-
-    case 'date_weekday':
-      return new Intl.DateTimeFormat(
-        undefined,
-        SHARED_DATE_FORMAT_OPTIONS.date_weekday,
-      ).format(date);
-
-    case 'date_time':
-      return new Intl.DateTimeFormat(undefined, {
-        year: 'numeric',
-        month: 'short',
-        day: 'numeric',
-        hour: 'numeric',
-        minute: '2-digit',
-        ...(isTimezoneShown ? {timeZoneName: 'short'} : {}),
-      }).format(date);
-
-    case 'time':
-      return new Intl.DateTimeFormat(undefined, {
-        hour: 'numeric',
-        minute: '2-digit',
-        ...(isTimezoneShown ? {timeZoneName: 'short'} : {}),
-      }).format(date);
-
-    case 'system_date': {
-      const y = date.getFullYear();
-      const m = pad(date.getMonth() + 1);
-      const d = pad(date.getDate());
-      return `${y}-${m}-${d}`;
-    }
-
-    case 'system_date_time': {
-      const y = date.getFullYear();
-      const m = pad(date.getMonth() + 1);
-      const d = pad(date.getDate());
-      const h = pad(date.getHours());
-      const min = pad(date.getMinutes());
-      const s = pad(date.getSeconds());
-      return `${y}-${m}-${d} ${h}:${min}:${s}`;
-    }
-
-    case 'system_time': {
-      const h = pad(date.getHours());
-      const min = pad(date.getMinutes());
-      const s = pad(date.getSeconds());
-      return `${h}:${min}:${s}`;
-    }
-  }
-}
-
-function getFullAbsoluteString(date: Date): string {
-  return new Intl.DateTimeFormat(undefined, {
-    year: 'numeric',
-    month: 'long',
-    day: 'numeric',
-    hour: 'numeric',
-    minute: '2-digit',
-    second: '2-digit',
-    timeZoneName: 'short',
-  }).format(date);
-}
-
 /** Returns the interval (in ms) at which a relative timestamp should update. */
 function getLiveInterval(diffSeconds: number): number {
   const absDiff = Math.abs(diffSeconds);
@@ -374,6 +345,7 @@ export function Timestamp({
   format = 'auto',
   autoThreshold = DEFAULT_AUTO_THRESHOLD,
   hasTooltip = true,
+  tooltipEntries,
   isTimezoneShown = false,
   isLive = false,
   type = 'supporting',
@@ -406,17 +378,18 @@ export function Timestamp({
         : 'date_time'
       : format;
 
-  // Format the display text
+  // Format the display text. No time zone is passed: the visible text always
+  // reads in the viewer's own zone, and only the tooltip names others.
   const displayText = !isValidDate
     ? ''
     : effectiveFormat === 'relative'
       ? getRelativeTimeString(date, now)
       : isAbsoluteFormat(effectiveFormat)
-        ? formatTimestamp(date, effectiveFormat, isTimezoneShown)
+        ? formatInstant(date, effectiveFormat, {isTimezoneShown})
         : '';
 
   // Full absolute text for tooltip and aria-label
-  const fullAbsoluteText = isValidDate ? getFullAbsoluteString(date) : '';
+  const fullAbsoluteText = isValidDate ? formatInstant(date, 'full') : '';
 
   // Live updates
   useEffect(() => {
@@ -443,7 +416,19 @@ export function Timestamp({
     return null;
   }
 
-  const showTooltip = hasTooltip && effectiveFormat === 'relative';
+  // An empty array is not a second way to spell "off" — `hasTooltip` stays the
+  // only on/off axis — so normalize it away before anything reads it.
+  const entries =
+    tooltipEntries !== undefined && tooltipEntries.length > 0
+      ? tooltipEntries
+      : undefined;
+
+  // Absolute formats have never carried a tooltip. Leaving that gate closed
+  // when a consumer has explicitly configured tooltip lines would let `format`
+  // silently suppress another prop's output, so entry presence opens it too.
+  // With no entries this reduces to the original condition exactly.
+  const showTooltip =
+    hasTooltip && (effectiveFormat === 'relative' || entries !== undefined);
 
   const timestampProps = mergeProps(
     themeProps('timestamp', {format: effectiveFormat}),
@@ -479,13 +464,31 @@ export function Timestamp({
   );
 
   if (showTooltip) {
+    // Built inside the branch so a timestamp without a tooltip allocates none
+    // of it. With no entries the content stays the bare string it has always
+    // been — no wrapper element is introduced around the default line.
+    const tooltipContent =
+      entries === undefined ? (
+        fullAbsoluteText
+      ) : (
+        <dl {...stylex.props(styles.tooltipLines)}>
+          {formatTooltipLines(date, entries).map((line, index) => (
+            // eslint-disable-next-line @eslint-react/no-array-index-key -- tooltip lines are fixed positional slots and two entries may legitimately be identical
+            <Fragment key={index}>
+              <dt {...stylex.props(styles.tooltipLabel)}>{line.label ?? ''}</dt>
+              <dd {...stylex.props(styles.tooltipValue)}>{line.value}</dd>
+            </Fragment>
+          ))}
+        </dl>
+      );
+
     return (
       <>
         {timeElement}
         <Suspense fallback={null}>
           <LazyXDSTooltip
             anchorRef={timeRef}
-            content={fullAbsoluteText}
+            content={tooltipContent}
             placement="above"
           />
         </Suspense>