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

package/dist/Timestamp/Timestamp.js

@@ -15,16 +15,17 @@
  * - /apps/storybook/stories/Timestamp.stories.tsx
  * - /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/index.js";
 import { mergeProps, mergeRefs } from "../utils/index.js";
 import { useDevWarning } from "../hooks/useDevWarning.js";
 import { themeProps } from "../utils/themeProps.js";
 import "../theme/tokens.stylex.js";
-import { colorVars } from "../theme/tokens.stylex.js";
-import { SHARED_DATE_FORMAT_OPTIONS } from "../utils/plainDate.js";
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { colorVars, spacingVars } from "../theme/tokens.stylex.js";
+import { formatInstant } from "./formatInstant.js";
+import { formatTooltipLines } from "./tooltipEntries.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const LazyXDSTooltip = /*#__PURE__*/lazy(async () => import('../Tooltip/Tooltip').then(mod => ({
   default: mod.Tooltip
 })));
@@ -137,73 +138,6 @@ function getRelativeTimeString(date, now) {
   const years = Math.floor(diffSeconds / YEAR);
   return `${years} ${years === 1 ? 'year' : 'years'} ago`;
 }
-function pad(n) {
-  return String(n).padStart(2, '0');
-}
-function formatTimestamp(date, format, isTimezoneShown) {
-  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) {
-  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) {
@@ -250,6 +184,7 @@ export function Timestamp({
   format = 'auto',
   autoThreshold = DEFAULT_AUTO_THRESHOLD,
   hasTooltip = true,
+  tooltipEntries,
   isTimezoneShown = false,
   isLive = false,
   type = 'supporting',
@@ -276,11 +211,14 @@ export function Timestamp({
   const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
   const effectiveFormat = format === 'auto' ? Math.abs(diffSeconds) <= autoThreshold ? 'relative' : 'date_time' : format;
 
-  // Format the display text
-  const displayText = !isValidDate ? '' : effectiveFormat === 'relative' ? getRelativeTimeString(date, now) : isAbsoluteFormat(effectiveFormat) ? formatTimestamp(date, effectiveFormat, isTimezoneShown) : '';
+  // 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) ? 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(() => {
@@ -299,7 +237,16 @@ export function Timestamp({
   if (!isValidDate) {
     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
   }), {
@@ -338,12 +285,36 @@ 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 : /*#__PURE__*/_jsx("dl", {
+      ...{
+        className: "xrvj5dj x1pmbctz x1tw44j4 x10im51j xrxpjvj"
+      },
+      children: formatTooltipLines(date, entries).map((line, index) =>
+      /*#__PURE__*/
+      // eslint-disable-next-line @eslint-react/no-array-index-key -- tooltip lines are fixed positional slots and two entries may legitimately be identical
+      _jsxs(Fragment, {
+        children: [/*#__PURE__*/_jsx("dt", {
+          ...{
+            className: "x10im51j xrxpjvj xyri2b xepvkrk"
+          },
+          children: line.label ?? ''
+        }), /*#__PURE__*/_jsx("dd", {
+          ...{
+            className: "x10im51j xrxpjvj"
+          },
+          children: line.value
+        })]
+      }, index))
+    });
     return /*#__PURE__*/_jsxs(_Fragment, {
       children: [timeElement, /*#__PURE__*/_jsx(Suspense, {
         fallback: null,
         children: /*#__PURE__*/_jsx(LazyXDSTooltip, {
           anchorRef: timeRef,
-          content: fullAbsoluteText,
+          content: tooltipContent,
           placement: "above"
         })
       })]

package/dist/Timestamp/formatInstant.d.ts

@@ -0,0 +1,41 @@
+import type { TimestampFormat } from './Timestamp';
+/**
+ * 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;
+}
+/**
+ * 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 declare function formatInstant(date: Date, format: InstantFormat, { timeZone, isTimezoneShown }?: FormatInstantOptions): string;
+//# sourceMappingURL=formatInstant.d.ts.map

package/dist/Timestamp/formatInstant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatInstant.d.ts","sourceRoot":"","sources":["../../src/Timestamp/formatInstant.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAMjD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACrB,OAAO,CAAC,eAAe,EAAE,UAAU,GAAG,MAAM,CAAC,GAC7C,MAAM,CAAC;AAEX,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA6ED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,aAAa,EACrB,EAAC,QAAQ,EAAE,eAAuB,EAAC,GAAE,oBAAyB,GAC7D,MAAM,CA0DR"}

package/dist/Timestamp/formatInstant.js

@@ -0,0 +1,177 @@
+// 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.js";
+
+// =============================================================================
+// 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.
+ */
+
+// =============================================================================
+// Option bags
+// =============================================================================
+
+/** The long absolute style, with seconds and a zone name. */
+const FULL_OPTIONS = {
+  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 = {
+  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 = {
+  year: 'numeric',
+  month: 'short',
+  day: 'numeric',
+  ...TIME_OPTIONS
+};
+
+// =============================================================================
+// Formatting
+// =============================================================================
+
+function pad(n) {
+  return String(n).padStart(2, '0');
+}
+
+/** The fields a `system_*` string is assembled from. */
+
+/**
+ * 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, timeZone) {
+  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, format, {
+  timeZone,
+  isTimezoneShown = false
+} = {}) {
+  const zone = timeZone === undefined ? {} : {
+    timeZone
+  };
+  const zoneName = isTimezoneShown ? {
+    timeZoneName: 'short'
+  } : {};
+  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/dist/Timestamp/index.d.ts

@@ -8,4 +8,5 @@
  */
 export { Timestamp } from './Timestamp';
 export type { TimestampProps, TimestampFormat } from './Timestamp';
+export type { TimestampTooltipEntry, TimestampTooltipFormat, } from './tooltipEntries';
 //# sourceMappingURL=index.d.ts.map

package/dist/Timestamp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Timestamp/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,YAAY,EAAC,cAAc,EAAE,eAAe,EAAC,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Timestamp/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,YAAY,EAAC,cAAc,EAAE,eAAe,EAAC,MAAM,aAAa,CAAC;AACjE,YAAY,EACV,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC"}

package/dist/Timestamp/tooltipEntries.d.ts

@@ -0,0 +1,56 @@
+import type { InstantFormat } from './formatInstant';
+/**
+ * Formats available to a tooltip line.
+ *
+ * Every `TimestampFormat` that names a fixed instant, plus `'full'` — the long
+ * absolute style the tooltip has always shown ("February 19, 2026 at 5:00:00 PM
+ * UTC"). `'relative'` and `'auto'` are excluded: a relative phrase ignores any
+ * zone, which would make `timezoneID` silently inert on that line.
+ *
+ * `'full'` lives only in this vocabulary, never in `TimestampFormat` — nothing
+ * asked for it as a visible display format, and keeping it out means new
+ * members added to `TimestampFormat` become valid tooltip formats for free.
+ *
+ * The public spelling of {@link InstantFormat}: consumers reading Timestamp's
+ * props should not have to know the name of its internal formatter.
+ */
+export type TimestampTooltipFormat = InstantFormat;
+/** One line of the Timestamp tooltip. */
+export interface TimestampTooltipEntry {
+    /**
+     * IANA time zone identifier, e.g. `'UTC'`, `'America/Los_Angeles'`.
+     * Omit it — or pass `'local'` — for the viewer's own zone.
+     *
+     * Prefer region identifiers. Fixed-offset abbreviations such as `'EST'` are
+     * accepted by the platform but never observe daylight saving, so they read
+     * an hour wrong for half the year — `'America/New_York'` is what people
+     * usually mean by "Eastern".
+     *
+     * An identifier the platform does not recognize falls back to the viewer's
+     * zone with a console warning rather than throwing.
+     */
+    timezoneID?: string;
+    /**
+     * How this line renders the instant.
+     * @default 'full'
+     */
+    format?: TimestampTooltipFormat;
+    /**
+     * Text shown beside the time, e.g. `'Local'`, `'UTC'`, `'Pacific'`.
+     * Supplied already translated; Timestamp never invents or localizes labels.
+     */
+    label?: string;
+}
+/** A rendered tooltip line. */
+export interface TimestampTooltipLine {
+    label?: string;
+    value: string;
+}
+/**
+ * Renders one tooltip line per entry, in the order given.
+ *
+ * Pure: the same `date` and `entries` always produce the same lines for a given
+ * host zone and locale.
+ */
+export declare function formatTooltipLines(date: Date, entries: ReadonlyArray<TimestampTooltipEntry>): ReadonlyArray<TimestampTooltipLine>;
+//# sourceMappingURL=tooltipEntries.d.ts.map

package/dist/Timestamp/tooltipEntries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltipEntries.d.ts","sourceRoot":"","sources":["../../src/Timestamp/tooltipEntries.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAMnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEnD,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+BAA+B;AAC/B,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAqGD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,aAAa,CAAC,qBAAqB,CAAC,GAC5C,aAAa,CAAC,oBAAoB,CAAC,CAoBrC"}

package/dist/Timestamp/tooltipEntries.js

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file tooltipEntries.ts
+ * @input A Date and the consumer's tooltip entry list
+ * @output Pure formatting of one tooltip line per entry, plus the entry types
+ * @position Leaf module; owns which zone each tooltip line names and whether
+ *   it needs a zone abbreviation, then defers to formatInstant to render it
+ *
+ * This module holds only the decisions a tooltip makes that the visible text
+ * does not: resolving `timezoneID` (including the `'local'` alias and the
+ * fallback for an unknown identifier), and deciding which lines need a zone
+ * abbreviation to be told apart. The formatting itself is formatInstant's,
+ * shared with the rendered text, so the two surfaces cannot drift.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timestamp/Timestamp.tsx
+ * - /packages/core/src/Timestamp/formatInstant.ts
+ * - /packages/core/src/Timestamp/tooltipEntries.test.ts
+ * - /packages/core/src/Timestamp/Timestamp.doc.mjs
+ * - /packages/core/src/Timestamp/index.ts
+ */
+
+import { devWarn } from "../utils/devWarning.js";
+import { formatInstant } from "./formatInstant.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Formats available to a tooltip line.
+ *
+ * Every `TimestampFormat` that names a fixed instant, plus `'full'` — the long
+ * absolute style the tooltip has always shown ("February 19, 2026 at 5:00:00 PM
+ * UTC"). `'relative'` and `'auto'` are excluded: a relative phrase ignores any
+ * zone, which would make `timezoneID` silently inert on that line.
+ *
+ * `'full'` lives only in this vocabulary, never in `TimestampFormat` — nothing
+ * asked for it as a visible display format, and keeping it out means new
+ * members added to `TimestampFormat` become valid tooltip formats for free.
+ *
+ * The public spelling of {@link InstantFormat}: consumers reading Timestamp's
+ * props should not have to know the name of its internal formatter.
+ */
+
+/** One line of the Timestamp tooltip. */
+
+/** A rendered tooltip line. */
+
+// =============================================================================
+// Zone resolution
+// =============================================================================
+
+/** Spelling that means "the viewer's own zone" without naming it. */
+const LOCAL_ZONE_ALIAS = 'local';
+
+/**
+ * Zone identifiers already reported as unknown.
+ *
+ * Resolution runs once per entry on every render, so without this a single
+ * typo on a live timestamp would emit the same warning every tick, forever.
+ * One report per bad identifier is enough to act on.
+ */
+const warnedTimezoneIDs = new Set();
+
+/**
+ * Resolves an entry's zone to something safe to hand to `Intl`.
+ *
+ * Returns `undefined` for the viewer's own zone, which is also what `Intl`
+ * treats as "use the host zone" — so the local path never constructs a
+ * formatter with an explicit `timeZone` and cannot drift from today's output.
+ */
+function resolveTimezoneID(timezoneID) {
+  if (timezoneID === undefined || timezoneID.toLowerCase() === LOCAL_ZONE_ALIAS) {
+    return undefined;
+  }
+
+  // An unrecognized identifier makes every Intl.DateTimeFormat constructor
+  // throw a RangeError. Rendering a timestamp must never take down the tree —
+  // degrade to the viewer's zone and say so, mirroring how an unparseable
+  // `value` is handled in Timestamp.tsx.
+  try {
+    new Intl.DateTimeFormat(undefined, {
+      timeZone: timezoneID
+    });
+  } catch {
+    if (!warnedTimezoneIDs.has(timezoneID)) {
+      warnedTimezoneIDs.add(timezoneID);
+      devWarn('Timestamp', `unknown time zone ${JSON.stringify(timezoneID)} in tooltipEntries. Falling back to the viewer's time zone.`);
+    }
+    return undefined;
+  }
+  return timezoneID;
+}
+
+/**
+ * A stable key for "which zone did the consumer ask for", used to decide
+ * whether the tooltip needs zone abbreviations to disambiguate its lines.
+ *
+ * Deliberately keyed on the *requested* zone, not on the resolved offset: a
+ * consumer who asks for two zones gets both labelled even when the viewer
+ * happens to be sitting in one of them, so the rendering does not change shape
+ * depending on where the reader is. That also keeps this testable under any
+ * machine timezone.
+ */
+function zoneKey(resolved) {
+  return resolved === undefined ? LOCAL_ZONE_ALIAS : resolved.toLowerCase();
+}
+
+// =============================================================================
+// Zone marking
+// =============================================================================
+
+/**
+ * Whether a format should carry a zone abbreviation.
+ *
+ * `'full'` always has one (that is the style). `system_*` never does — those
+ * are machine shapes and a trailing "PST" would break anything parsing them,
+ * which is also why `isTimezoneShown` has never applied to them.
+ *
+ * The two human formats that can carry one do so when either the reader has
+ * to tell several lines apart, or the line shows a zone the consumer named
+ * explicitly. That second case matters even for a lone entry: the tooltip is
+ * the `<time>` element's `aria-describedby`, and that element's accessible
+ * name is the absolute time in the *viewer's* zone — so an unmarked foreign
+ * time is announced directly after a local one with nothing to distinguish
+ * them. A line the consumer did not steer stays unmarked, matching how the
+ * visible text reads with `isTimezoneShown` off.
+ */
+function shouldShowZoneName(format, hasMultipleZones, isNamedZone) {
+  if (format === 'full') {
+    return true;
+  }
+  if (format === 'date_time' || format === 'time') {
+    return hasMultipleZones || isNamedZone;
+  }
+  return false;
+}
+
+/**
+ * Renders one tooltip line per entry, in the order given.
+ *
+ * Pure: the same `date` and `entries` always produce the same lines for a given
+ * host zone and locale.
+ */
+export function formatTooltipLines(date, entries) {
+  const resolved = entries.map(entry => resolveTimezoneID(entry.timezoneID));
+  const hasMultipleZones = new Set(resolved.map(zoneKey)).size > 1;
+  return entries.map((entry, index) => {
+    const format = entry.format ?? 'full';
+    const timeZone = resolved[index];
+    return {
+      ...(entry.label === undefined ? {} : {
+        label: entry.label
+      }),
+      value: formatInstant(date, format, {
+        timeZone,
+        isTimezoneShown: shouldShowZoneName(format, hasMultipleZones, timeZone !== undefined)
+      })
+    };
+  });
+}

package/dist/Token/Token.d.ts

@@ -1,7 +1,7 @@
 /**
  * @file Token.tsx
  * @input Uses React, ReactNode, StyleXStyles
- * @output Exports Token component, TokenProps, TokenColor types
+ * @output Exports Token component, TokenProps, TokenColor, TokenColorMap types
  * @position Core implementation; consumed by index.ts, tested by Token.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -14,9 +14,36 @@
 import type { ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
 /**
- * Available color variants for the token.
+ * Extensible color map for Token.
+ *
+ * Theme packages can add custom colors via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Token' {
+ *   interface TokenColorMap {
+ *     brand: true;
+ *   }
+ * }
+ * ```
+ */
+export interface TokenColorMap {
+    default: true;
+    red: true;
+    orange: true;
+    yellow: true;
+    green: true;
+    teal: true;
+    cyan: true;
+    blue: true;
+    purple: true;
+    pink: true;
+    gray: true;
+}
+/**
+ * Token color type derived from TokenColorMap.
+ * Extensible via module augmentation of TokenColorMap.
  */
-export type TokenColor = 'default' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'cyan' | 'blue' | 'purple' | 'pink' | 'gray';
+export type TokenColor = keyof TokenColorMap;
 export type TokenSize = 'sm' | 'md' | 'lg';
 export interface TokenProps extends BaseProps<HTMLElement> {
     /** Ref forwarded to the root element */