@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/Timestamp/Timestamp.tsx

@@ -13,10 +13,10 @@
  * - /packages/core/src/Timestamp/Timestamp.test.tsx
  * - /packages/core/src/Timestamp/index.ts
  * - /apps/storybook/stories/Timestamp.stories.tsx
- * - /packages/cli/templates/blocks/components/Timestamp/ (showcase blocks)
+ * - /packages/cli/assets/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>

package/src/Timestamp/formatInstant.ts

@@ -0,0 +1,218 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file formatInstant.ts
+ * @input A Date, one absolute format name, and an optional time zone
+ * @output That instant rendered as a string
+ * @position Leaf shared by Timestamp's visible text and each of its tooltip
+ *   lines; owns every absolute format Timestamp can produce
+ *
+ * Timestamp renders the same instant on two surfaces — the visible text and,
+ * on hover, one line per configured time zone. They differ only in which zone
+ * they name and whether they carry a zone abbreviation, so they are one
+ * formatter parameterized by zone rather than two switches that have to be
+ * kept in step by hand. Adding a member to `TimestampFormat` now fails to
+ * compile in exactly one place.
+ *
+ * Each caller keeps its own policy for the zone abbreviation: the visible text
+ * takes it straight from the `isTimezoneShown` prop, a tooltip line derives it
+ * from how many zones are on screen (see tooltipEntries.ts). Only the
+ * rendering is shared, not the decision.
+ *
+ * Omitting `timeZone` means the viewer's own zone. That path hands `Intl` no
+ * `timeZone` and keeps `system_*` on plain `Date` getters, so it produces
+ * exactly what it produced before this module existed.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timestamp/Timestamp.tsx
+ * - /packages/core/src/Timestamp/tooltipEntries.ts
+ * - /packages/core/src/Timestamp/Timestamp.test.tsx
+ */
+
+import {SHARED_DATE_FORMAT_OPTIONS, getTimeZoneParts} from '../utils/plainDate';
+import type {TimestampFormat} from './Timestamp';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Every format that names a fixed instant, plus `'full'` — the long absolute
+ * style ("February 19, 2026 at 5:00:00 PM UTC") that backs a relative
+ * timestamp's accessible name and the tooltip's default line.
+ *
+ * `'relative'` and `'auto'` are excluded: a relative phrase names no instant,
+ * so a zone could not change what it says.
+ */
+export type InstantFormat =
+  | Exclude<TimestampFormat, 'relative' | 'auto'>
+  | 'full';
+
+export interface FormatInstantOptions {
+  /**
+   * IANA time zone identifier. Omit for the viewer's own zone — which is what
+   * `Intl` already does with no `timeZone`, so the omitted path never
+   * constructs an explicit-zone formatter and cannot drift from the host
+   * default.
+   *
+   * Must already be one the platform accepts. An identifier `Intl` does not
+   * recognize throws a `RangeError` from its constructor, before any
+   * formatting happens; deciding what to do about that belongs to whoever
+   * took the identifier from a consumer, not here (tooltipEntries resolves
+   * and warns in `resolveTimezoneID`, then passes only what survived).
+   */
+  timeZone?: string;
+  /**
+   * Whether to append the zone abbreviation. Honoured by `date_time` and
+   * `time` only: `'full'` always carries one because that is the style, and
+   * the `system_*` shapes never do — a trailing "PST" would break anything
+   * parsing them, which is why `isTimezoneShown` has never applied to them.
+   * @default false
+   */
+  isTimezoneShown?: boolean;
+}
+
+// =============================================================================
+// Option bags
+// =============================================================================
+
+/** The long absolute style, with seconds and a zone name. */
+const FULL_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric',
+  hour: 'numeric',
+  minute: '2-digit',
+  second: '2-digit',
+  timeZoneName: 'short',
+};
+
+/** The time-of-day part, shared by `time` and `date_time`. */
+const TIME_OPTIONS: Intl.DateTimeFormatOptions = {
+  hour: 'numeric',
+  minute: '2-digit',
+};
+
+/**
+ * The date part here is spelled out rather than taken from
+ * `SHARED_DATE_FORMAT_OPTIONS.date`. That bag is shared with DateInput, and
+ * pointing `date_time` at it would mean a change made for date-only fields
+ * silently reshaped every date-and-time reading too. The two agree today; they
+ * are not the same decision.
+ */
+const DATE_TIME_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: 'numeric',
+  month: 'short',
+  day: 'numeric',
+  ...TIME_OPTIONS,
+};
+
+// =============================================================================
+// Formatting
+// =============================================================================
+
+function pad(n: number): string {
+  return String(n).padStart(2, '0');
+}
+
+/** The fields a `system_*` string is assembled from. */
+interface WallClock {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/**
+ * Wall-clock fields for an instant: in the named zone, or — with no zone —
+ * the viewer's own, read straight off the `Date`. The zone-less branch
+ * deliberately stays on plain getters so the default rendering never gains a
+ * dependency on `Intl` zone data it did not have before.
+ *
+ * The explicit return type is load-bearing: it is what forces the two branches
+ * to keep producing the same shape.
+ */
+function getWallClock(date: Date, timeZone: string | undefined): WallClock {
+  return timeZone === undefined
+    ? {
+        year: date.getFullYear(),
+        month: date.getMonth() + 1,
+        day: date.getDate(),
+        hour: date.getHours(),
+        minute: date.getMinutes(),
+        second: date.getSeconds(),
+      }
+    : getTimeZoneParts(date.getTime(), timeZone);
+}
+
+/**
+ * Renders one instant in one absolute format.
+ *
+ * Pure: the same arguments always produce the same string for a given host
+ * locale (and, when no `timeZone` is given, host zone).
+ */
+export function formatInstant(
+  date: Date,
+  format: InstantFormat,
+  {timeZone, isTimezoneShown = false}: FormatInstantOptions = {},
+): string {
+  const zone = timeZone === undefined ? {} : {timeZone};
+  const zoneName = isTimezoneShown ? {timeZoneName: 'short' as const} : {};
+
+  switch (format) {
+    case 'full':
+      return new Intl.DateTimeFormat(undefined, {
+        ...FULL_OPTIONS,
+        ...zone,
+      }).format(date);
+
+    case 'date':
+      return new Intl.DateTimeFormat(undefined, {
+        ...SHARED_DATE_FORMAT_OPTIONS.date,
+        ...zone,
+      }).format(date);
+
+    case 'date_long':
+      return new Intl.DateTimeFormat(undefined, {
+        ...SHARED_DATE_FORMAT_OPTIONS.date_long,
+        ...zone,
+      }).format(date);
+
+    case 'date_weekday':
+      return new Intl.DateTimeFormat(undefined, {
+        ...SHARED_DATE_FORMAT_OPTIONS.date_weekday,
+        ...zone,
+      }).format(date);
+
+    case 'date_time':
+      return new Intl.DateTimeFormat(undefined, {
+        ...DATE_TIME_OPTIONS,
+        ...zoneName,
+        ...zone,
+      }).format(date);
+
+    case 'time':
+      return new Intl.DateTimeFormat(undefined, {
+        ...TIME_OPTIONS,
+        ...zoneName,
+        ...zone,
+      }).format(date);
+
+    case 'system_date': {
+      const w = getWallClock(date, timeZone);
+      return `${w.year}-${pad(w.month)}-${pad(w.day)}`;
+    }
+
+    case 'system_date_time': {
+      const w = getWallClock(date, timeZone);
+      return `${w.year}-${pad(w.month)}-${pad(w.day)} ${pad(w.hour)}:${pad(w.minute)}:${pad(w.second)}`;
+    }
+
+    case 'system_time': {
+      const w = getWallClock(date, timeZone);
+      return `${pad(w.hour)}:${pad(w.minute)}:${pad(w.second)}`;
+    }
+  }
+}

package/src/Timestamp/index.ts

@@ -13,3 +13,7 @@
 
 export {Timestamp} from './Timestamp';
 export type {TimestampProps, TimestampFormat} from './Timestamp';
+export type {
+  TimestampTooltipEntry,
+  TimestampTooltipFormat,
+} from './tooltipEntries';