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.mdnew file mode 100644index 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.++@freddymetadiff --git a/apps/storybook/stories/Timestamp.stories.tsx b/apps/storybook/stories/Timestamp.stories.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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-labelconst fullAbsoluteText = isValidDate ? formatInstant(date, 'full') : '';// Live updatesuseEffect(() => {- 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 barediff --git a/packages/core/src/Timestamp/formatInstant.ts b/packages/core/src/Timestamp/formatInstant.tsindex 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.tsindex 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