Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(timestamp): add system_unix format + visible Copy tooltip on the copy button (#4717)

freddymeta8ad2cc19f7b2
diff --git a/.changeset/timestamp-unix-and-copy-tooltip.md b/.changeset/timestamp-unix-and-copy-tooltip.md
new file mode 100644
index 0000000000..c4ed7ecd0e
--- /dev/null
+++ b/.changeset/timestamp-unix-and-copy-tooltip.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Timestamp: two additions. (1) A new `system_unix` format renders the value as Unix time in whole seconds since the epoch (e.g. `1771520400`) — an absolute, zone-independent machine value, useful as a copyable `tooltipEntries` row alongside human-readable zones. It joins the `system_*` machine-readable family and, being absolute, ignores any tooltip time zone. (2) The copyable hover card's copy button now shows a visible `Copy` tooltip on hover/focus (flipping to `Copied` after a copy, in step with the icon), so the affordance is discoverable for sighted users; the full `Copy <value>` string remains the button's aria-label for assistive tech. Both additive — no change to existing formats or default rendering.
+
+@freddymeta
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 04d47bcdf3..5ee38041a8 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -927,6 +927,10 @@
"defaultMessage": "Copy {value}",
"description": "Aria label on a Timestamp copyable-hover-card row's copy button, in its default state. `value` is the formatted instant that row shows (e.g. `Copy February 19, 2026 at 5:00:00 PM UTC`). Imperative verb. Pairs with `timestamp.copied` (post-click state)."
},
+ "@astryx.timestamp.copy": {
+ "defaultMessage": "Copy",
+ "description": "Short label shown in the tooltip on a Timestamp copyable-hover-card row's copy button (hover/focus), in its default state. Imperative verb. Pairs with `timestamp.copied` (post-click state). The full `copyValue` string remains the button's aria-label for assistive tech."
+ },
"@astryx.timestamp.copied": {
"defaultMessage": "Copied",
"description": "Aria label on a Timestamp copy button for ~1.5s after a successful copy, and the text announced to a polite live region. Past-participle (\"has been copied\"); pairs with `timestamp.copyValue`."
diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjs
index b71882405a..f4c7772516 100644
--- a/packages/core/src/Timestamp/Timestamp.doc.mjs
+++ b/packages/core/src/Timestamp/Timestamp.doc.mjs
@@ -26,9 +26,9 @@ export const docs = {
},
{
name: 'format',
- type: "'relative' | 'relative_short' | 'auto' | 'date' | 'date_long' | 'date_weekday' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time'",
+ type: "'relative' | 'relative_short' | 'auto' | 'date' | 'date_long' | 'date_weekday' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time' | 'system_unix'",
description:
- "Display format. 'relative' shows '2 hours ago', 'relative_short' shows the same tiers abbreviated ('2h ago', '1d ago', '3mo ago') for compact surfaces, 'date' shows 'Mar 21, 2025', 'date_long' shows 'March 21, 2025', 'date_weekday' shows 'Wed, Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.",
+ "Display format. 'relative' shows '2 hours ago', 'relative_short' shows the same tiers abbreviated ('2h ago', '1d ago', '3mo ago') for compact surfaces, 'date' shows 'Mar 21, 2025', 'date_long' shows 'March 21, 2025', 'date_weekday' shows 'Wed, Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting ('system_unix' is the Unix time in whole seconds since the epoch, an absolute/zone-independent value), 'auto' switches from relative to date_time based on recency.",
default: "'auto'",
},
{
@@ -185,7 +185,7 @@ export const docsDense = {
},
propDescriptions: {
value: 'date/time as unix seconds or ISO string',
- format: "display mode: 'relative', 'auto', 'date', 'date_long', 'date_weekday', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time'",
+ format: "display mode: 'relative', 'auto', 'date', 'date_long', 'date_weekday', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time', 'system_unix'",
autoThreshold: 'seconds threshold for auto relative\u2192date_time switch',
hasTooltip: 'show copyable full-time hover card on hover (relative mode, or any format with tooltipEntries)',
tooltipEntries:
diff --git a/packages/core/src/Timestamp/Timestamp.test.tsx b/packages/core/src/Timestamp/Timestamp.test.tsx
index 33bb91dfb9..84a20eed50 100644
--- a/packages/core/src/Timestamp/Timestamp.test.tsx
+++ b/packages/core/src/Timestamp/Timestamp.test.tsx
@@ -343,6 +343,26 @@ describe('Timestamp', () => {
expect(el.textContent).toMatch(/\d{2}:\d{2}:\d{2}/);
});
+ it('renders system_unix format as whole epoch seconds (zone-independent)', () => {
+ // 2026-02-19T17:00:00Z is 1771520400 seconds since the epoch. The value is
+ // absolute, so it is the same regardless of the viewer's zone.
+ render(
+ <Timestamp
+ value="2026-02-19T17:00:00Z"
+ format="system_unix"
+ data-testid="ts"
+ />,
+ );
+ expect(screen.getByTestId('ts').textContent).toBe('1771520400');
+ });
+
+ it('renders system_unix from a Unix-seconds value input unchanged', () => {
+ render(
+ <Timestamp value={1771520400} format="system_unix" data-testid="ts" />,
+ );
+ expect(screen.getByTestId('ts').textContent).toBe('1771520400');
+ });
+
// --- Auto format ---
it('auto format uses relative for recent times', () => {
@@ -673,10 +693,14 @@ describe('Timestamp', () => {
/>,
);
// With no entries the hover surface is still the copyable card — one
- // surface, one styling — never the old read-only tooltip.
+ // surface, one styling — never the old read-only tooltip. (The copy
+ // button carries its own small "Copy" tooltip; that is not the hover
+ // surface, so exclude it.)
expect(
- screen.queryByRole('tooltip', {hidden: true}),
- ).not.toBeInTheDocument();
+ screen
+ .queryAllByRole('tooltip', {hidden: true})
+ .filter(el => !/^(Copy|Copied)$/.test(el.textContent?.trim() ?? '')),
+ ).toHaveLength(0);
const card = await screen.findByRole('dialog', {hidden: true});
// The default card is the named details card, exactly as the configured
// one is.
@@ -707,6 +731,31 @@ describe('Timestamp', () => {
).toBeInTheDocument();
});
});
+
+ it("shows a 'Copy' tooltip on the copy button, flipping to 'Copied' after a copy", async () => {
+ render(<Timestamp value={Date.now() / 1000 - 3600} format="relative" />);
+ const card = await screen.findByRole('dialog', {hidden: true});
+ const button = card.querySelector('button')!;
+ // The visible tooltip content defaults to the short imperative 'Copy'
+ // (the full "Copy <value>" string stays the button's aria-label).
+ await waitFor(() =>
+ expect(
+ screen.getByText('Copy', {
+ selector: '[role="tooltip"] *, [role="tooltip"]',
+ }),
+ ).toBeInTheDocument(),
+ );
+ fireEvent.click(button);
+ // After a successful copy the tooltip content flips to 'Copied' in step
+ // with the icon/aria-label.
+ await waitFor(() =>
+ expect(
+ screen.getByText('Copied', {
+ selector: '[role="tooltip"] *, [role="tooltip"]',
+ }),
+ ).toBeInTheDocument(),
+ );
+ });
});
// --- Multi-zone / multi-format copyable hover card (tooltipEntries) ---
@@ -748,10 +797,13 @@ describe('Timestamp', () => {
/>,
);
// Entries present — the surface is the interactive card, never the
- // lightweight read-only tooltip.
+ // lightweight read-only tooltip. (The copy button's own "Copy" tooltip
+ // is not the hover surface, so exclude it.)
expect(
- screen.queryByRole('tooltip', {hidden: true}),
- ).not.toBeInTheDocument();
+ screen
+ .queryAllByRole('tooltip', {hidden: true})
+ .filter(el => !/^(Copy|Copied)$/.test(el.textContent?.trim() ?? '')),
+ ).toHaveLength(0);
const card = await screen.findByRole('dialog', {hidden: true});
expect(card).toHaveAttribute('aria-label', 'Timestamp details');
});
@@ -925,7 +977,11 @@ describe('Timestamp', () => {
// hasTooltip stays the on/off switch: false suppresses the surface even
// when entries would otherwise upgrade it to the card.
expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
- expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
+ expect(
+ screen
+ .queryAllByRole('tooltip', {hidden: true})
+ .filter(el => !/^(Copy|Copied)$/.test(el.textContent?.trim() ?? '')),
+ ).toHaveLength(0);
expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
expect(
screen.getByTestId('ts').getAttribute('aria-describedby'),
diff --git a/packages/core/src/Timestamp/Timestamp.tsx b/packages/core/src/Timestamp/Timestamp.tsx
index 27c38688f0..cbcaf26a10 100644
--- a/packages/core/src/Timestamp/Timestamp.tsx
+++ b/packages/core/src/Timestamp/Timestamp.tsx
@@ -52,7 +52,8 @@ export type TimestampFormat =
| 'time'
| 'system_date'
| 'system_date_time'
- | 'system_time';
+ | 'system_time'
+ | 'system_unix';
export interface TimestampProps extends BaseProps<HTMLTimeElement> {
/** Ref forwarded to the root `<time>` element. */
@@ -74,6 +75,8 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
* - `'system_date'`: "2025-03-21"
* - `'system_date_time'`: "2025-03-21 14:51:53"
* - `'system_time'`: "14:51:53"
+ * - `'system_unix'`: "1742565113" — Unix time in whole seconds since the
+ * epoch. Absolute (zone-independent), so it ignores any tooltip time zone.
* @default 'auto'
*/
format?: TimestampFormat;
diff --git a/packages/core/src/Timestamp/TimestampHoverCard.tsx b/packages/core/src/Timestamp/TimestampHoverCard.tsx
index 7134b6645b..e387e83fc0 100644
--- a/packages/core/src/Timestamp/TimestampHoverCard.tsx
+++ b/packages/core/src/Timestamp/TimestampHoverCard.tsx
@@ -152,6 +152,12 @@ function CopyButton({value}: {value: string}) {
variant="ghost"
size="sm"
icon={<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')
diff --git a/packages/core/src/Timestamp/formatInstant.ts b/packages/core/src/Timestamp/formatInstant.ts
index c0392fce4f..4b9e2da419 100644
--- a/packages/core/src/Timestamp/formatInstant.ts
+++ b/packages/core/src/Timestamp/formatInstant.ts
@@ -213,5 +213,11 @@ export function formatInstant(
const w = getWallClock(date, timeZone);
return `${pad(w.hour)}:${pad(w.minute)}:${pad(w.second)}`;
}
+
+ case 'system_unix':
+ // 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));
}
}