@astryxdesign/core 0.2.0 → 0.3.0-canary.5f9896c

package/dist/Timestamp/Timestamp.js

@@ -13,22 +13,22 @@
  * - /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, Fragment } from 'react';
+import { lazy, Suspense, useEffect, useRef, useState } 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 { useTranslator } from "../i18n/index.js";
 import { themeProps } from "../utils/themeProps.js";
-import "../theme/tokens.stylex.js";
-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
-})));
+import { jsx as _jsx } from "react/jsx-runtime";
+// Load the overlay lazily so a card-less Timestamp — the default — never
+// bundles HoverCard or the copy affordance's Icon/IconButton. Mirrors the code
+// split the read-only Tooltip path used before it.
+const LazyTimestampHoverCard = /*#__PURE__*/lazy(async () => import("./TimestampHoverCard.js"));
 
 // =============================================================================
 // Types
@@ -139,6 +139,67 @@ function getRelativeTimeString(date, now) {
   return `${years} ${years === 1 ? 'year' : 'years'} ago`;
 }
 
+/**
+ * The compact sibling of `getRelativeTimeString`: the same tier boundaries and
+ * present/future-skew handling, rendered with abbreviated units for
+ * space-constrained surfaces (chat metadata, dense tables, chips).
+ *
+ * Units follow the common compact convention (and the Microsoft Style Guide):
+ * `s` seconds, `m` minutes, `h` hours, `d` days, `mo` months, `y` years.
+ * Months use `mo` — not `m` — because `m` already means minutes; a bare `m`
+ * for months would be ambiguous. The value is always numeric (no "yesterday"
+ * idiom, which belongs to the long form) so the short form stays predictable
+ * and easy to scan. The `ago` / `in` affixes are kept so direction stays
+ * unambiguous at a glance.
+ */
+function getRelativeTimeShortString(date, now) {
+  const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
+
+  // Present clamp — identical to the long form (see getRelativeTimeString).
+  if (Math.abs(diffSeconds) < 10) {
+    return 'now';
+  }
+  if (diffSeconds < 0) {
+    // Future dates.
+    const absDiff = Math.abs(diffSeconds);
+    if (absDiff <= FUTURE_SKEW_TOLERANCE) {
+      return 'now';
+    }
+    if (absDiff < MINUTE) {
+      return `in ${absDiff}s`;
+    }
+    if (absDiff < HOUR) {
+      return `in ${Math.floor(absDiff / MINUTE)}m`;
+    }
+    if (absDiff < DAY) {
+      return `in ${Math.floor(absDiff / HOUR)}h`;
+    }
+    if (absDiff < MONTH) {
+      return `in ${Math.floor(absDiff / DAY)}d`;
+    }
+    if (absDiff < YEAR) {
+      return `in ${Math.floor(absDiff / MONTH)}mo`;
+    }
+    return `in ${Math.floor(absDiff / YEAR)}y`;
+  }
+  if (diffSeconds < MINUTE) {
+    return `${diffSeconds}s ago`;
+  }
+  if (diffSeconds < HOUR) {
+    return `${Math.floor(diffSeconds / MINUTE)}m ago`;
+  }
+  if (diffSeconds < DAY) {
+    return `${Math.floor(diffSeconds / HOUR)}h ago`;
+  }
+  if (diffSeconds < MONTH) {
+    return `${Math.floor(diffSeconds / DAY)}d ago`;
+  }
+  if (diffSeconds < YEAR) {
+    return `${Math.floor(diffSeconds / MONTH)}mo ago`;
+  }
+  return `${Math.floor(diffSeconds / YEAR)}y ago`;
+}
+
 /** Returns the interval (in ms) at which a relative timestamp should update. */
 function getLiveInterval(diffSeconds) {
   const absDiff = Math.abs(diffSeconds);
@@ -156,7 +217,17 @@ function getLiveInterval(diffSeconds) {
 
 /** Whether a format is non-relative (i.e. shows a fixed date/time). */
 function isAbsoluteFormat(format) {
-  return format !== 'relative' && format !== 'auto';
+  return format !== 'relative' && format !== 'relative_short' && format !== 'auto';
+}
+
+/**
+ * Whether a format renders a relative phrase ("2 hours ago" / "2h ago") rather
+ * than a fixed instant. Both the long and short relative forms share the same
+ * treatment: they get the accessible full-date name, the hover tooltip, and
+ * live updates.
+ */
+function isRelativeFormat(format) {
+  return format === 'relative' || format === 'relative_short';
 }
 
 // =============================================================================
@@ -168,8 +239,8 @@ function isAbsoluteFormat(format) {
  *
  * Renders a semantic `<time>` element with an ISO 8601 `datetime` attribute,
  * styled via Text. Supports relative ("2 hours ago"), multiple absolute
- * formats, and auto formatting. Optionally shows a tooltip with the full
- * absolute time and can update live.
+ * formats, and auto formatting. Optionally shows a hover card with the full
+ * absolute time (copyable) and can update live.
  *
  * @example
  * ```
@@ -197,6 +268,7 @@ export function Timestamp({
   ref,
   'data-testid': testId
 }) {
+  const t = useTranslator();
   const timeRef = useRef(null);
   const [now, setNow] = useState(() => new Date());
   const date = parseValue(value);
@@ -213,7 +285,7 @@ export function Timestamp({
 
   // 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, {
+  const displayText = !isValidDate ? '' : effectiveFormat === 'relative' ? getRelativeTimeString(date, now) : effectiveFormat === 'relative_short' ? getRelativeTimeShortString(date, now) : isAbsoluteFormat(effectiveFormat) ? formatInstant(date, effectiveFormat, {
     isTimezoneShown
   }) : '';
 
@@ -222,7 +294,7 @@ export function Timestamp({
 
   // Live updates
   useEffect(() => {
-    if (!isLive || !isValidDate || effectiveFormat !== 'relative') {
+    if (!isLive || !isValidDate || !isRelativeFormat(effectiveFormat)) {
       return;
     }
     const interval = getLiveInterval(diffSeconds);
@@ -242,11 +314,20 @@ export function Timestamp({
   // 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);
+  // Absolute formats have never carried a hover surface. 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 && (isRelativeFormat(effectiveFormat) || entries !== undefined);
+
+  // The rows the hover card renders: the configured entries, or the single
+  // default absolute line shown when none are set. Either way the surface is
+  // the same copyable card — the default line is a one-row card carrying the
+  // full absolute time, itself copyable, just like a configured entry.
+  const lines = entries === undefined ? [{
+    value: fullAbsoluteText,
+    isCopyable: true
+  }] : formatTooltipLines(date, entries);
   const timestampProps = mergeProps(themeProps('timestamp', {
     format: effectiveFormat
   }), {
@@ -263,61 +344,43 @@ export function Timestamp({
     children: /*#__PURE__*/_jsx("time", {
       ref: mergeRefs(ref, timeRef),
       dateTime: isoString,
-      "aria-label": effectiveFormat === 'relative' ? fullAbsoluteText : undefined
-      // The absolute-time tooltip is anchored here with the default 'auto'
-      // focus trigger, which only activates on focusable anchors. A bare
-      // <time> is not focusable, so without a tab stop sighted keyboard
-      // users could never reveal the tooltip (WCAG 1.4.13 / 2.1.1). Only
-      // add the tab stop while a tooltip is actually attached — no
-      // gratuitous tab stops otherwise.
+      "aria-label": isRelativeFormat(effectiveFormat) ? fullAbsoluteText : undefined
+      // The hover card is anchored here with focusTrigger="always", which
+      // attaches focus listeners but does not itself make the anchor
+      // focusable. A bare <time> is not focusable, so without a tab stop
+      // sighted keyboard users could never reveal the card (WCAG 1.4.13 /
+      // 2.1.1). Add the tab stop only while a card is actually attached — no
+      // gratuitous tab stops otherwise. The card carries its own
+      // dashed-underline hover indication as the affordance, so the anchor
+      // needs no separate focus outline.
       ,
       tabIndex: showTooltip ? 0 : undefined,
       "data-testid": testId,
       ...{
-        0: {
-          className: "xt0psk2 xjb2p0i x1j61x8r x1qlqyl8 x15bjb6t x1heor9g x1pd3egz"
-        },
-        1: {
-          className: "xt0psk2 xjb2p0i x1j61x8r x1qlqyl8 x15bjb6t x1heor9g x1pd3egz x17nn4n9 x1wfwxd8 x7s97pk"
-        }
-      }[!!showTooltip << 0],
+        className: "xt0psk2 xjb2p0i x1j61x8r x1qlqyl8 x15bjb6t x1heor9g x1pd3egz"
+      },
       children: displayText
     })
   });
   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: tooltipContent,
-          placement: "above"
-        })
-      })]
+    // One surface for every timestamp that shows one: the copyable hover card,
+    // loaded lazily so the default card-less path never bundles it. Each line
+    // becomes a labelled row with its own copy button. With no configured
+    // entries this is a single row carrying the full absolute time, itself
+    // copyable — so hovering a relative timestamp reveals the full time and
+    // lets the reader copy it. Opens on hover and on keyboard focus (the
+    // <time> tab stop above), with the dashed-underline affordance signalling
+    // it is interactive.
+    //
+    // While the chunk loads the bare <time> stays visible (the Suspense
+    // fallback), so nothing disappears — the card simply attaches once ready.
+    return /*#__PURE__*/_jsx(Suspense, {
+      fallback: timeElement,
+      children: /*#__PURE__*/_jsx(LazyTimestampHoverCard, {
+        lines: lines,
+        label: t('@astryx.timestamp.detailsLabel'),
+        children: timeElement
+      })
     });
   }
   return timeElement;

package/dist/Timestamp/TimestampHoverCard.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file TimestampHoverCard.tsx
+ * @input Uses React, HoverCard, IconButton, Icon, formatted lines
+ * @output Default-exports the lazily-loaded copyable hover card for Timestamp
+ * @position Split out of Timestamp so the overlay (HoverCard) and the copy
+ *   affordance's Icon/IconButton load only when a card is actually shown — the
+ *   default, card-less Timestamp never bundles this chunk.
+ *
+ * Layout: a semantic `<dl>` laid out as a grid. Labelled cards use three
+ *   columns — label, value, and a trailing action column for copy buttons —
+ *   so the buttons align down a single column no matter how wide each value
+ *   is. The action column is only added when at least one row is copyable, so
+ *   a fully read-only card carries no dangling gutter. Label-less cards drop
+ *   the label column and stack to whatever columns remain.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timestamp/Timestamp.tsx (the lazy() + Suspense wrapper)
+ * - /packages/core/src/Timestamp/Timestamp.doc.mjs (theming.targets)
+ * - /packages/core/src/Timestamp/Timestamp.test.tsx
+ */
+import type { ReactNode } from 'react';
+import type { TimestampTooltipLine } from './tooltipEntries';
+export interface TimestampHoverCardProps {
+    /** The rows to render, each a labelled instant, optionally copyable. */
+    lines: ReadonlyArray<TimestampTooltipLine>;
+    /** Accessible name for the card. */
+    label: string;
+    /** The anchor the card is attached to (the `<time>` element). */
+    children: ReactNode;
+}
+/**
+ * The copyable hover card for Timestamp. Renders a semantic `<dl>` as a grid:
+ * an optional label column, the value, and — when any row is copyable — a
+ * trailing action column carrying that row's copy button, so buttons align
+ * down one column. With a single default line this is a one-row card carrying
+ * the full absolute time, copyable. Opens on hover and on keyboard focus (the
+ * anchor's tab stop), with a dashed-underline affordance signalling it is
+ * interactive.
+ */
+declare function TimestampHoverCard({ lines, label, children, }: TimestampHoverCardProps): ReactNode;
+declare namespace TimestampHoverCard {
+    var displayName: string;
+}
+export default TimestampHoverCard;
+//# sourceMappingURL=TimestampHoverCard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TimestampHoverCard.d.ts","sourceRoot":"","sources":["../../src/Timestamp/TimestampHoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAerC,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,kBAAkB,CAAC;AAoK3D,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,KAAK,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAC3C,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,QAAQ,EAAE,SAAS,CAAC;CACrB;AAkBD;;;;;;;;GAQG;AACH,iBAAwB,kBAAkB,CAAC,EACzC,KAAK,EACL,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,SAAS,CAsCrC;kBA1CuB,kBAAkB;;;eAAlB,kBAAkB"}

package/dist/Timestamp/TimestampHoverCard.js

@@ -0,0 +1,228 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TimestampHoverCard.tsx
+ * @input Uses React, HoverCard, IconButton, Icon, formatted lines
+ * @output Default-exports the lazily-loaded copyable hover card for Timestamp
+ * @position Split out of Timestamp so the overlay (HoverCard) and the copy
+ *   affordance's Icon/IconButton load only when a card is actually shown — the
+ *   default, card-less Timestamp never bundles this chunk.
+ *
+ * Layout: a semantic `<dl>` laid out as a grid. Labelled cards use three
+ *   columns — label, value, and a trailing action column for copy buttons —
+ *   so the buttons align down a single column no matter how wide each value
+ *   is. The action column is only added when at least one row is copyable, so
+ *   a fully read-only card carries no dangling gutter. Label-less cards drop
+ *   the label column and stack to whatever columns remain.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timestamp/Timestamp.tsx (the lazy() + Suspense wrapper)
+ * - /packages/core/src/Timestamp/Timestamp.doc.mjs (theming.targets)
+ * - /packages/core/src/Timestamp/Timestamp.test.tsx
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { HoverCard } from "../HoverCard/index.js";
+import { IconButton } from "../IconButton/index.js";
+import { Icon } from "../Icon/index.js";
+import { useAnnounce } from "../hooks/useAnnounce.js";
+import { useTranslator } from "../i18n/index.js";
+import { themeProps } from "../utils/themeProps.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, spacingVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const styles = {
+  dl: {
+    k1xSpc: "xrvj5dj",
+    kGNEyG: "x6s0dn4",
+    k1C7PZ: "xty4p9g",
+    khm7nJ: "x1x7z4sm",
+    kogj98: "x1ghz6dp",
+    kmVPX3: "x1717udv",
+    $$css: true
+  }
+};
+
+// Grid templates, selected per-card by which columns are present.
+// - hasAnyLabel + hasAnyCopyable → label | value | action
+// - hasAnyLabel only             → label | value
+// - hasAnyCopyable only          → value | action
+// - neither                      → value
+const gridTemplates = {
+  labelValueAction: {
+    kumcoG: "x1g3yg12",
+    $$css: true
+  },
+  labelValue: {
+    kumcoG: "x1pmbctz",
+    $$css: true
+  },
+  valueAction: {
+    kumcoG: "x52fmzj",
+    $$css: true
+  },
+  value: {
+    kumcoG: "x1y6fwsi",
+    $$css: true
+  }
+};
+
+/** How long the copied checkmark stays before reverting to the copy icon. */
+const COPY_FEEDBACK_MS = 1500;
+
+/**
+ * The per-row copy affordance: a compact ghost `IconButton` that writes the
+ * row's value to the clipboard, flips `copy` → `check` for a moment, and
+ * announces the copy to a polite live region (a swapped aria-label alone
+ * isn't reliably announced). A clipboard rejection is a silent no-op.
+ *
+ * Kept as its own component so its state/timer/effect only exist for rows that
+ * actually opt into copying — read-only rows render no button and carry none
+ * of this machinery.
+ */
+function CopyButton({
+  value
+}) {
+  const t = useTranslator();
+  const announce = useAnnounce();
+  const [copied, setCopied] = useState(false);
+  const resetTimerRef = useRef(null);
+  useEffect(() => {
+    return () => {
+      if (resetTimerRef.current != null) {
+        clearTimeout(resetTimerRef.current);
+      }
+    };
+  }, []);
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(value);
+      setCopied(true);
+      announce(t('@astryx.timestamp.copied'));
+      // Restart the reset timer on every copy so a rapid re-copy isn't
+      // reverted early by the previous click's timer.
+      if (resetTimerRef.current != null) {
+        clearTimeout(resetTimerRef.current);
+      }
+      resetTimerRef.current = setTimeout(() => {
+        resetTimerRef.current = null;
+        setCopied(false);
+      }, COPY_FEEDBACK_MS);
+    } catch {
+      // Clipboard failures leave the copied state unchanged.
+    }
+  }, [value, announce, t]);
+  return /*#__PURE__*/_jsx(IconButton, {
+    variant: "ghost",
+    size: "sm",
+    icon: /*#__PURE__*/_jsx(Icon, {
+      icon: copied ? 'check' : 'copy',
+      size: "sm",
+      color: "inherit"
+    })
+    // Visible hover/focus hint via Button's built-in tooltip: 'Copy',
+    // flipping to 'Copied' after a successful copy in step with the icon.
+    // The full 'Copy <value>' string stays the aria-label for assistive tech.
+    ,
+    tooltip: t(copied ? '@astryx.timestamp.copied' : '@astryx.timestamp.copy'),
+    label: copied ? t('@astryx.timestamp.copied') : t('@astryx.timestamp.copyValue', {
+      value
+    }),
+    onClick: () => {
+      void handleCopy();
+    },
+    ...themeProps('timestamp-copy-button')
+  });
+}
+
+/**
+ * One row of the hover card: an optional label, the formatted instant, and —
+ * when the card reserves an action column — a trailing action cell holding the
+ * copy button (for a copyable row) or nothing (for a read-only row, so the
+ * columns stay aligned). Pure presentation: the copy state lives in
+ * {@link CopyButton}, which only copyable rows render.
+ */
+function EntryRow({
+  line,
+  hasLabelColumn,
+  hasActionColumn
+}) {
+  return /*#__PURE__*/_jsxs("div", {
+    ...{
+      className: "xjp7ctv"
+    },
+    children: [hasLabelColumn && /*#__PURE__*/_jsx("dt", {
+      ...{
+        className: "xv1l7n4 x141an7d x1ltkj2j x1sodnla x1ghz6dp x1717udv xuxw1ft"
+      },
+      children: line.label ?? ''
+    }), /*#__PURE__*/_jsx("dd", {
+      ...{
+        className: "x1tgivj0 xjm74w1 xw6l6zx x1sodnla x1ghz6dp x1717udv xuxw1ft"
+      },
+      children: line.value
+    }), hasActionColumn && /*#__PURE__*/_jsx("div", {
+      ...{
+        className: "x78zum5 x13a6bvl x6s0dn4"
+      },
+      children: line.isCopyable && /*#__PURE__*/_jsx(CopyButton, {
+        value: line.value
+      })
+    })]
+  });
+}
+function gridTemplateFor(hasLabelColumn, hasActionColumn) {
+  if (hasLabelColumn && hasActionColumn) {
+    return gridTemplates.labelValueAction;
+  }
+  if (hasLabelColumn) {
+    return gridTemplates.labelValue;
+  }
+  if (hasActionColumn) {
+    return gridTemplates.valueAction;
+  }
+  return gridTemplates.value;
+}
+
+/**
+ * The copyable hover card for Timestamp. Renders a semantic `<dl>` as a grid:
+ * an optional label column, the value, and — when any row is copyable — a
+ * trailing action column carrying that row's copy button, so buttons align
+ * down one column. With a single default line this is a one-row card carrying
+ * the full absolute time, copyable. Opens on hover and on keyboard focus (the
+ * anchor's tab stop), with a dashed-underline affordance signalling it is
+ * interactive.
+ */
+export default function TimestampHoverCard({
+  lines,
+  label,
+  children
+}) {
+  // A label column is only reserved when some row is labelled; otherwise the
+  // value sits flush at the card's leading edge. An action column is only
+  // reserved when some row is copyable (option B), so a fully read-only card
+  // has no trailing gutter.
+  const hasLabelColumn = lines.some(line => line.label != null && line.label !== '');
+  const hasActionColumn = lines.some(line => line.isCopyable);
+  const cardContent = /*#__PURE__*/_jsx("dl", {
+    ...stylex.props(styles.dl, gridTemplateFor(hasLabelColumn, hasActionColumn)),
+    children: lines.map((line, index) => /*#__PURE__*/_jsx(EntryRow
+    // eslint-disable-next-line @eslint-react/no-array-index-key -- rows are fixed positional slots and two entries may legitimately be identical
+    , {
+      line: line,
+      hasLabelColumn: hasLabelColumn,
+      hasActionColumn: hasActionColumn
+    }, index))
+  });
+  return /*#__PURE__*/_jsx(HoverCard, {
+    content: cardContent,
+    placement: "above",
+    focusTrigger: "always",
+    hasHoverIndication: true,
+    label: label,
+    children: children
+  });
+}
+TimestampHoverCard.displayName = 'TimestampHoverCard';

package/dist/Timestamp/formatInstant.d.ts

@@ -4,10 +4,10 @@ import type { TimestampFormat } from './Timestamp';
  * 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.
+ * `'relative'`, `'relative_short'`, 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 type InstantFormat = Exclude<TimestampFormat, 'relative' | 'relative_short' | 'auto'> | 'full';
 export interface FormatInstantOptions {
     /**
      * IANA time zone identifier. Omit for the viewer's own zone — which is what

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

@@ -1 +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"}
+{"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,GACvB,OAAO,CAAC,eAAe,EAAE,UAAU,GAAG,gBAAgB,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;AAE5E,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,CAgER"}

package/dist/Timestamp/formatInstant.js

@@ -40,8 +40,8 @@ import { SHARED_DATE_FORMAT_OPTIONS, getTimeZoneParts } from "../utils/plainDate
  * 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.
+ * `'relative'`, `'relative_short'`, and `'auto'` are excluded: a relative
+ * phrase names no instant, so a zone could not change what it says.
  */
 
 // =============================================================================
@@ -173,5 +173,10 @@ export function formatInstant(date, format, {
         const w = getWallClock(date, timeZone);
         return `${pad(w.hour)}:${pad(w.minute)}:${pad(w.second)}`;
       }
+    case 'unix_seconds':
+      // Unix time in whole seconds since the epoch. The epoch is an absolute
+      // instant, so this is zone-independent — `timeZone` is intentionally
+      // ignored (a wall-clock zone can't change how many seconds have elapsed).
+      return String(Math.floor(date.getTime() / 1000));
   }
 }

package/dist/Timestamp/tooltipEntries.d.ts

@@ -4,8 +4,9 @@ import type { InstantFormat } from './formatInstant';
  *
  * 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.
+ * UTC"). `'relative'`, `'relative_short'`, 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
@@ -40,11 +41,25 @@ export interface TimestampTooltipEntry {
      * Supplied already translated; Timestamp never invents or localizes labels.
      */
     label?: string;
+    /**
+     * Whether this row shows a copy-to-clipboard button, rendered in a dedicated
+     * trailing action column so the buttons line up across rows regardless of
+     * each value's width. The action column is only reserved when at least one
+     * row is copyable, so a fully read-only card has no trailing gutter.
+     *
+     * Defaults to `false` — rows are read-only unless opted in. Set `true` for a
+     * row whose value is worth pasting elsewhere, such as a machine-readable
+     * `system_date_time` value shown beside human-readable zones that only need
+     * to be read.
+     * @default false
+     */
+    isCopyable?: boolean;
 }
 /** A rendered tooltip line. */
 export interface TimestampTooltipLine {
     label?: string;
     value: string;
+    isCopyable: boolean;
 }
 /**
  * Renders one tooltip line per entry, in the order given.

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

@@ -1 +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"}
+{"version":3,"file":"tooltipEntries.d.ts","sourceRoot":"","sources":["../../src/Timestamp/tooltipEntries.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAMnD;;;;;;;;;;;;;;;GAeG;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;IACf;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,+BAA+B;AAC/B,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;CACrB;AAqGD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,aAAa,CAAC,qBAAqB,CAAC,GAC5C,aAAa,CAAC,oBAAoB,CAAC,CAqBrC"}

package/dist/Timestamp/tooltipEntries.js

@@ -33,8 +33,9 @@ import { formatInstant } from "./formatInstant.js";
  *
  * 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.
+ * UTC"). `'relative'`, `'relative_short'`, 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
@@ -154,6 +155,7 @@ export function formatTooltipLines(date, entries) {
       ...(entry.label === undefined ? {} : {
         label: entry.label
       }),
+      isCopyable: entry.isCopyable ?? false,
       value: formatInstant(date, format, {
         timeZone,
         isTimezoneShown: shouldShowZoneName(format, hasMultipleZones, timeZone !== undefined)