Skip to content

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

TypeScript

feat(timestamp): add relative_short format (compact 5m/1h/2d/3mo ago) (#4673)

freddymeta416db07e57cb
diff --git a/.changeset/timestamp-relative-short.md b/.changeset/timestamp-relative-short.md
new file mode 100644
index 0000000000..75aaecf333
--- /dev/null
+++ b/.changeset/timestamp-relative-short.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Timestamp: add a `relative_short` format — the compact sibling of `relative`. It uses the same tier boundaries and present/clock-skew handling but renders abbreviated units for space-constrained surfaces (chat metadata, dense tables, chips): `now`, `30s ago`, `5m ago`, `2h ago`, `1d ago`, `3mo ago`, `2y ago`, and `in 5m` for future times. Months render as `mo` (not `m`) so they never collide with minutes; the short form is always numeric (no `yesterday` idiom). Like `relative`, it keeps the full absolute date as its accessible name and gets the hover tooltip and live updates. Additive — existing formats are unchanged.
+
+@freddymeta
diff --git a/apps/storybook/stories/Timestamp.stories.tsx b/apps/storybook/stories/Timestamp.stories.tsx
index 9f0c124de0..2f5844f39a 100644
--- a/apps/storybook/stories/Timestamp.stories.tsx
+++ b/apps/storybook/stories/Timestamp.stories.tsx
@@ -13,6 +13,7 @@ const meta: Meta<typeof Timestamp> = {
control: 'select',
options: [
'relative',
+ 'relative_short',
'auto',
'date',
'date_long',
@@ -117,6 +118,32 @@ export const RelativeFormat: Story = {
),
};
+export const RelativeShortFormat: Story = {
+ render: () => (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '8px',
+ alignItems: 'flex-start',
+ }}>
+ <Timestamp value={Date.now() / 1000 - 5} format="relative_short" />
+ <Timestamp value={Date.now() / 1000 - 120} format="relative_short" />
+ <Timestamp value={Date.now() / 1000 - 3600} format="relative_short" />
+ <Timestamp value={Date.now() / 1000 - 86400} format="relative_short" />
+ <Timestamp value={Date.now() / 1000 - 259200} format="relative_short" />
+ <Timestamp
+ value={Date.now() / 1000 - 90 * 86400}
+ format="relative_short"
+ />
+ <Timestamp
+ value={Date.now() / 1000 - 730 * 86400}
+ format="relative_short"
+ />
+ </div>
+ ),
+};
+
export const DateFormat: Story = {
args: {
value: '2026-02-19T17:00:00Z',
diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjs
index 9af6a15cdc..7b4c3f803a 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' | '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'",
description:
- "Display format. 'relative' shows '2 hours ago', '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, 'auto' switches from relative to date_time based on recency.",
default: "'auto'",
},
{
diff --git a/packages/core/src/Timestamp/Timestamp.test.tsx b/packages/core/src/Timestamp/Timestamp.test.tsx
index fb9002b8ce..3867c1b409 100644
--- a/packages/core/src/Timestamp/Timestamp.test.tsx
+++ b/packages/core/src/Timestamp/Timestamp.test.tsx
@@ -88,6 +88,137 @@ describe('Timestamp', () => {
expect(screen.getByText('yesterday')).toBeInTheDocument();
});
+ // --- relative_short format ---
+
+ describe('relative_short format', () => {
+ it('renders "now" for very recent times', () => {
+ render(
+ <Timestamp value={Date.now() / 1000 - 5} format="relative_short" />,
+ );
+ expect(screen.getByText('now')).toBeInTheDocument();
+ });
+
+ it('abbreviates each past tier (s/m/h/d/mo/y)', () => {
+ const {rerender} = render(
+ <Timestamp value={Date.now() / 1000 - 30} format="relative_short" />,
+ );
+ expect(screen.getByText('30s ago')).toBeInTheDocument();
+
+ rerender(
+ <Timestamp
+ value={Date.now() / 1000 - 5 * 60}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('5m ago')).toBeInTheDocument();
+
+ rerender(
+ <Timestamp
+ value={Date.now() / 1000 - 2 * 3600}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('2h ago')).toBeInTheDocument();
+
+ rerender(
+ <Timestamp
+ value={Date.now() / 1000 - 3 * 86400}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('3d ago')).toBeInTheDocument();
+
+ rerender(
+ <Timestamp
+ value={Date.now() / 1000 - 90 * 86400}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('3mo ago')).toBeInTheDocument();
+
+ rerender(
+ <Timestamp
+ value={Date.now() / 1000 - 730 * 86400}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('2y ago')).toBeInTheDocument();
+ });
+
+ it('uses "mo" for months so it never collides with "m" (minutes)', () => {
+ // 45 days → months tier. A bare "m" here would be indistinguishable from
+ // the minutes unit, so months must render as "mo".
+ render(
+ <Timestamp
+ value={Date.now() / 1000 - 45 * 86400}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('1mo ago')).toBeInTheDocument();
+ });
+
+ it('renders a single day as "1d ago" (no "yesterday" idiom in short form)', () => {
+ render(
+ <Timestamp
+ value={Date.now() / 1000 - 100000}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('1d ago')).toBeInTheDocument();
+ });
+
+ it('renders future times with the "in" prefix and abbreviated units', () => {
+ const {rerender} = render(
+ <Timestamp
+ value={Date.now() / 1000 + 5 * 60}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('in 5m')).toBeInTheDocument();
+
+ rerender(
+ <Timestamp
+ value={Date.now() / 1000 + 2 * 3600}
+ format="relative_short"
+ />,
+ );
+ expect(screen.getByText('in 2h')).toBeInTheDocument();
+ });
+
+ it('does not round a tier up past its own boundary', () => {
+ const {rerender} = render(
+ <Timestamp value={Date.now() / 1000 - 3599} format="relative_short" />,
+ );
+ expect(screen.getByText('59m ago')).toBeInTheDocument();
+
+ rerender(
+ <Timestamp value={Date.now() / 1000 - 86399} format="relative_short" />,
+ );
+ expect(screen.getByText('23h ago')).toBeInTheDocument();
+ });
+
+ it('treats a hair in the future as "now" (clock skew)', () => {
+ render(
+ <Timestamp value={Date.now() / 1000 + 2} format="relative_short" />,
+ );
+ expect(screen.getByText('now')).toBeInTheDocument();
+ });
+
+ it('keeps the full absolute date as the accessible name', () => {
+ render(
+ <Timestamp
+ value={Date.now() / 1000 - 2 * 3600}
+ format="relative_short"
+ />,
+ );
+ const el = screen.getByText('2h ago');
+ // Same a11y contract as the long relative form: the visible short label
+ // is backed by the full absolute date for screen readers.
+ expect(el).toHaveAttribute('aria-label');
+ expect(el.getAttribute('aria-label')).not.toBe('2h ago');
+ });
+ });
+
// --- Standard display formats ---
it('renders date format', () => {
diff --git a/packages/core/src/Timestamp/Timestamp.tsx b/packages/core/src/Timestamp/Timestamp.tsx
index e841416c22..d65f0783de 100644
--- a/packages/core/src/Timestamp/Timestamp.tsx
+++ b/packages/core/src/Timestamp/Timestamp.tsx
@@ -39,6 +39,7 @@ const LazyXDSTooltip = lazy(async () =>
export type TimestampFormat =
| 'relative'
+ | 'relative_short'
| 'auto'
| 'date'
| 'date_long'
@@ -57,6 +58,9 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
/**
* Display format.
* - `'relative'`: "2 hours ago", "yesterday", "now"
+ * - `'relative_short'`: "2h ago", "1d ago", "now" — the same tiers as
+ * `'relative'` with abbreviated units (s/m/h/d/mo/y), for compact,
+ * space-constrained surfaces
* - `'auto'`: Relative for recent times, `date_time` for older
* - `'date'`: "Mar 21, 2025"
* - `'date_long'`: "March 21, 2025"
@@ -298,6 +302,69 @@ function getRelativeTimeString(date: Date, now: Date): string {
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: Date, now: Date): string {
+ 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: number): number {
const absDiff = Math.abs(diffSeconds);
@@ -316,8 +383,22 @@ function getLiveInterval(diffSeconds: number): number {
/** Whether a format is non-relative (i.e. shows a fixed date/time). */
function isAbsoluteFormat(
format: TimestampFormat,
-): format is Exclude<TimestampFormat, 'relative' | 'auto'> {
- return format !== 'relative' && format !== 'auto';
+): format is Exclude<TimestampFormat, 'relative' | 'relative_short' | '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: TimestampFormat,
+): format is 'relative' | 'relative_short' {
+ return format === 'relative' || format === 'relative_short';
}
// =============================================================================
@@ -384,16 +465,18 @@ export function Timestamp({
? ''
: effectiveFormat === 'relative'
? getRelativeTimeString(date, now)
- : isAbsoluteFormat(effectiveFormat)
- ? formatInstant(date, effectiveFormat, {isTimezoneShown})
- : '';
+ : effectiveFormat === 'relative_short'
+ ? getRelativeTimeShortString(date, now)
+ : isAbsoluteFormat(effectiveFormat)
+ ? formatInstant(date, effectiveFormat, {isTimezoneShown})
+ : '';
// Full absolute text for tooltip and aria-label
const fullAbsoluteText = isValidDate ? formatInstant(date, 'full') : '';
// Live updates
useEffect(() => {
- if (!isLive || !isValidDate || effectiveFormat !== 'relative') {
+ if (!isLive || !isValidDate || !isRelativeFormat(effectiveFormat)) {
return;
}
@@ -428,7 +511,7 @@ export function Timestamp({
// 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);
+ hasTooltip && (isRelativeFormat(effectiveFormat) || entries !== undefined);
const timestampProps = mergeProps(
themeProps('timestamp', {format: effectiveFormat}),
@@ -447,7 +530,7 @@ export function Timestamp({
ref={mergeRefs(ref, timeRef)}
dateTime={isoString}
aria-label={
- effectiveFormat === 'relative' ? fullAbsoluteText : undefined
+ isRelativeFormat(effectiveFormat) ? fullAbsoluteText : undefined
}
// The absolute-time tooltip is anchored here with the default 'auto'
// focus trigger, which only activates on focusable anchors. A bare
diff --git a/packages/core/src/Timestamp/formatInstant.ts b/packages/core/src/Timestamp/formatInstant.ts
index 7e9c9a755c..c0392fce4f 100644
--- a/packages/core/src/Timestamp/formatInstant.ts
+++ b/packages/core/src/Timestamp/formatInstant.ts
@@ -41,12 +41,11 @@ 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';
+ Exclude<TimestampFormat, 'relative' | 'relative_short' | 'auto'> | 'full';
export interface FormatInstantOptions {
/**
diff --git a/packages/core/src/Timestamp/tooltipEntries.ts b/packages/core/src/Timestamp/tooltipEntries.ts
index df5549915a..4129830fa2 100644
--- a/packages/core/src/Timestamp/tooltipEntries.ts
+++ b/packages/core/src/Timestamp/tooltipEntries.ts
@@ -34,8 +34,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