From 2f6d0bb9b622857eba912cde34683d9a934965ae Mon Sep 17 00:00:00 2001
From: tay1orjones <3360588+tay1orjones@users.noreply.github.com>
Date: Thu, 19 Nov 2026 20:55:29 +0000
Subject: [PATCH 1/3] Initial plan
From 6e60293fbeda80197785d64cb7ed5affa7e9e059 Mon Sep 17 00:00:00 2001
From: tay1orjones <3360588+tay1orjones@users.noreply.github.com>
Date: Thu, 19 Nov 2026 21:11:34 +0000
Subject: [PATCH 2/3] feat(RelativeTime): expose the compact absolute-time
preset
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
---
.changeset/relative-time-compact-absolute.md | 5 +
.../src/RelativeTime/RelativeTime.docs.json | 9 +
.../RelativeTime.features.stories.tsx | 22 +++
.../src/RelativeTime/RelativeTime.test.tsx | 161 ++++++++++++++----
.../react/src/RelativeTime/RelativeTime.tsx | 10 +-
5 files changed, 172 insertions(+), 35 deletions(-)
create mode 100644 .changeset/relative-time-compact-absolute.md
diff --git a/.changeset/relative-time-compact-absolute.md b/.changeset/relative-time-compact-absolute.md
new file mode 100644
index 00000000000..f1d4ff53c11
--- /dev/null
+++ b/.changeset/relative-time-compact-absolute.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+RelativeTime: Add `absoluteFormat="compact"` to shorten absolute timestamps without changing when they appear.
diff --git a/packages/react/src/RelativeTime/RelativeTime.docs.json b/packages/react/src/RelativeTime/RelativeTime.docs.json
index 3e373c44e11..c961e6be602 100644
--- a/packages/react/src/RelativeTime/RelativeTime.docs.json
+++ b/packages/react/src/RelativeTime/RelativeTime.docs.json
@@ -15,6 +15,9 @@
},
{
"id": "components-relativetime-features--count-down-timer"
+ },
+ {
+ "id": "components-relativetime-features--compact-absolute-format"
}
],
"importPath": "@primer/react",
@@ -38,6 +41,12 @@
"defaultValue": "'auto'",
"description": "The format with which to display the time"
},
+ {
+ "name": "absoluteFormat",
+ "type": "'compact'",
+ "defaultValue": "undefined",
+ "description": "Controls presentation when absolute output is selected. `compact` shows localized today with 12-hour time, or a localized date with its year and no time. It omits the visible time zone and overrides `prefix`, `formatStyle`, and individual date/time display fields. Locale and display time zone still apply. It does not force absolute output or change the full timestamp title. Omitting the prop preserves existing behavior."
+ },
{
"name": "tense",
"type": "'auto' | 'past' | 'future'",
diff --git a/packages/react/src/RelativeTime/RelativeTime.features.stories.tsx b/packages/react/src/RelativeTime/RelativeTime.features.stories.tsx
index c9ecb5a24e4..948414dc533 100644
--- a/packages/react/src/RelativeTime/RelativeTime.features.stories.tsx
+++ b/packages/react/src/RelativeTime/RelativeTime.features.stories.tsx
@@ -149,4 +149,26 @@ export const CountDownTimer: StoryFn = args => {
CountDownTimer.args = {date: new Date('2038-01-19T03:14:08Z'), format: 'elapsed', day: '', month: ''}
CountDownTimer.argTypes = {date: {control: false}, format: {control: false}}
+export const CompactAbsoluteFormat: StoryFn = () => {
+ const today = new Date()
+
+ return (
+
+ - Compact today
+ -
+
+
+ - Compact on another day
+ -
+
+
+ - Standard absolute time today
+ -
+
+
+
+ )
+}
+CompactAbsoluteFormat.parameters = {controls: {disable: true}}
+
export default meta
diff --git a/packages/react/src/RelativeTime/RelativeTime.test.tsx b/packages/react/src/RelativeTime/RelativeTime.test.tsx
index b13bafaf65c..91ca6f1c8c6 100644
--- a/packages/react/src/RelativeTime/RelativeTime.test.tsx
+++ b/packages/react/src/RelativeTime/RelativeTime.test.tsx
@@ -1,6 +1,6 @@
import {hydrateRoot, type Root} from 'react-dom/client'
import {renderToString} from 'react-dom/server'
-import {describe, expect, it, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
import RelativeTime from '.'
import {act, render} from '@testing-library/react'
import {implementsClassName} from '../utils/testing'
@@ -31,47 +31,54 @@ describe('RelativeTime', () => {
expect(container.textContent).toEqual('Mar 7, 2024')
})
- it('renders children if passed', () => {
+ it.each([undefined, 'compact'] as const)('renders children if passed (absoluteFormat: %s)', absoluteFormat => {
const date = new Date('2024-03-07T12:22:48.123Z')
- const {container} = render(server rendered date)
+ const {container} = render(
+
+ server rendered date
+ ,
+ )
expect(container.textContent).toEqual('server rendered date')
})
- it('hydrates the fallback without errors when server and client time zones differ', async () => {
- const date = new Date('2024-03-07T00:30:00.000Z')
- const relativeTime =
- const toLocaleDateStringSpy = vi.spyOn(Date.prototype, 'toLocaleDateString').mockReturnValue('Mar 7, 2024')
- const container = document.createElement('div')
- container.innerHTML = renderToString(relativeTime)
- document.body.appendChild(container)
+ it.each([undefined, 'compact'] as const)(
+ 'hydrates the fallback without errors when server and client time zones differ (absoluteFormat: %s)',
+ async absoluteFormat => {
+ const date = new Date('2024-03-07T00:30:00.000Z')
+ const relativeTime =
+ const toLocaleDateStringSpy = vi.spyOn(Date.prototype, 'toLocaleDateString').mockReturnValue('Mar 7, 2024')
+ const container = document.createElement('div')
+ container.innerHTML = renderToString(relativeTime)
+ document.body.appendChild(container)
- toLocaleDateStringSpy.mockImplementation((_locales, options) =>
- options?.timeZone === 'UTC' ? 'Mar 7, 2024' : 'Mar 6, 2024',
- )
+ toLocaleDateStringSpy.mockImplementation((_locales, options) =>
+ options?.timeZone === 'UTC' ? 'Mar 7, 2024' : 'Mar 6, 2024',
+ )
- const recoverableErrors: unknown[] = []
- const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
- let root: Root | undefined
+ const recoverableErrors: unknown[] = []
+ const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+ let root: Root | undefined
- try {
- expect(container.firstChild).toHaveTextContent('Mar 7, 2024')
+ try {
+ expect(container.firstChild).toHaveTextContent('Mar 7, 2024')
- await act(async () => {
- root = hydrateRoot(container, relativeTime, {
- onRecoverableError: error => recoverableErrors.push(error),
+ await act(async () => {
+ root = hydrateRoot(container, relativeTime, {
+ onRecoverableError: error => recoverableErrors.push(error),
+ })
})
- })
-
- expect(recoverableErrors).toEqual([])
- expect(consoleErrorSpy).not.toHaveBeenCalled()
- expect(container.firstChild).toHaveTextContent('Mar 7, 2024')
- } finally {
- toLocaleDateStringSpy.mockRestore()
- consoleErrorSpy.mockRestore()
- await act(async () => root?.unmount())
- container.remove()
- }
- })
+
+ expect(recoverableErrors).toEqual([])
+ expect(consoleErrorSpy).not.toHaveBeenCalled()
+ expect(container.firstChild).toHaveTextContent('Mar 7, 2024')
+ } finally {
+ toLocaleDateStringSpy.mockRestore()
+ consoleErrorSpy.mockRestore()
+ await act(async () => root?.unmount())
+ container.remove()
+ }
+ },
+ )
it('does not render no-title attribute by default', () => {
const date = new Date('2024-03-07T12:22:48.123Z')
@@ -84,4 +91,92 @@ describe('RelativeTime', () => {
const {container} = render()
expect(container.firstChild).toHaveAttribute('no-title')
})
+
+ describe('compact absolute output', () => {
+ const date = new Date('2026-11-03T15:04:00.000Z')
+
+ beforeEach(() => {
+ vi.useFakeTimers({toFake: ['Date']})
+ vi.setSystemTime(new Date('2026-11-03T16:04:00.000Z'))
+ })
+
+ afterEach(() => {
+ vi.useRealTimers()
+ })
+
+ it('updates and restores absolute text without changing the datetime or full title', async () => {
+ const props = {
+ date,
+ format: 'datetime',
+ lang: 'en-US',
+ 'time-zone': 'UTC',
+ 'hour-cycle': 'h23',
+ prefix: 'Uploaded:',
+ hour: 'numeric',
+ minute: '2-digit',
+ timeZoneName: 'short',
+ } as const
+ const {container, rerender} = render()
+ const element = container.querySelector('relative-time')
+ const displayedText = () => element?.shadowRoot?.textContent
+
+ await expect.poll(displayedText).toContain('Uploaded:')
+ const standardText = displayedText()
+ const fullTitle = element?.getAttribute('title')
+ expect(fullTitle).toContain('15:04 UTC')
+
+ rerender()
+ await expect.poll(displayedText).toBe('today at 3:04 PM')
+ expect(element).toHaveAttribute('datetime', date.toISOString())
+ expect(element).toHaveAttribute('title', fullTitle)
+
+ rerender()
+ await expect.poll(displayedText).toBe(standardText)
+ })
+
+ it.each([
+ {name: 'a custom title', title: 'Uploaded earlier', noTitle: false},
+ {name: 'noTitle', title: undefined, noTitle: true},
+ ])('renders a compact non-today datetime with $name when absolute time is preferred', async ({title, noTitle}) => {
+ const datetime = '2026-11-02T15:04:00.000Z'
+ const preference = 'data-prefers-absolute-time'
+ const previousPreference = document.body.getAttribute(preference)
+ document.body.setAttribute(preference, 'true')
+
+ try {
+ const {container} = render(
+ ,
+ )
+ const element = container.querySelector('relative-time')
+
+ await expect.poll(() => element?.shadowRoot?.textContent).toBe('Nov 2, 2026')
+ expect(element).toHaveAttribute('datetime', datetime)
+ expect(element?.getAttribute('title')).toBe(title ?? null)
+ } finally {
+ if (previousPreference === null) document.body.removeAttribute(preference)
+ else document.body.setAttribute(preference, previousPreference)
+ }
+ })
+
+ it.each([
+ {format: 'relative', text: '1 hour ago'},
+ {format: 'duration', text: '1 hour'},
+ {format: 'micro', text: '1h'},
+ ] as const)('does not force absolute output in $format mode', async ({format, text}) => {
+ const {container} = render(
+ ,
+ )
+ const element = container.querySelector('relative-time')
+
+ await expect.poll(() => element?.shadowRoot?.textContent).toBe(text)
+ })
+ })
})
diff --git a/packages/react/src/RelativeTime/RelativeTime.tsx b/packages/react/src/RelativeTime/RelativeTime.tsx
index d1b55856835..e9762e70167 100644
--- a/packages/react/src/RelativeTime/RelativeTime.tsx
+++ b/packages/react/src/RelativeTime/RelativeTime.tsx
@@ -10,10 +10,16 @@ const localeOptions: Intl.DateTimeFormatOptions = {
year: 'numeric',
timeZone: 'UTC',
} satisfies Intl.DateTimeFormatOptions
-function RelativeTime({date, datetime, children, noTitle, ...props}: RelativeTimeProps) {
+function RelativeTime({date, datetime, children, noTitle, absoluteFormat, ...props}: RelativeTimeProps) {
if (datetime) date = new Date(datetime)
return (
-
+
{children || date?.toLocaleDateString('en', localeOptions) || ''}
)
From 29aa400bb852147f96fc90c92335a678442dde89 Mon Sep 17 00:00:00 2001
From: tay1orjones <3360588+tay1orjones@users.noreply.github.com>
Date: Fri, 20 Nov 2026 18:38:08 +0000
Subject: [PATCH 3/3] chore(deps): require @github/relative-time-element 5.4.0
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
---
package-lock.json | 6 +++---
packages/react/package.json | 2 +-
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/package-lock.json b/package-lock.json
index 035bd35fb98..8169b13a410 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -4648,8 +4648,8 @@
"license": "MIT"
},
"node_modules/@github/relative-time-element": {
- "version": "5.0.0",
- "integrity": "sha512-L/2r0DNR/rMbmHWcsdmhtOiy2gESoGOhItNFD4zJ3nZfHl79Dx3N18Vfx/pYr2lruMOdk1cJZb4wEumm+Dxm1w==",
+ "version": "5.4.0",
+ "integrity": "sha512-OKlo1xuHo6UxaeB1Oxy9aH2oLnMT8NBa03yabkZ0FZIIkcSnztxfrTdtx3bhWgjhQbPdJnuRvY64fx+oBGfkyA==",
"license": "MIT"
},
"node_modules/@hono/node-server": {
@@ -31172,7 +31172,7 @@
"license": "MIT",
"dependencies": {
"@github/mini-throttle": "^2.1.1",
- "@github/relative-time-element": "^5.0.0",
+ "@github/relative-time-element": "^5.4.0",
"@lit-labs/react": "1.2.1",
"@oddbird/popover-polyfill": "^0.7.3",
"@primer/behaviors": "^1.10.3",
diff --git a/packages/react/package.json b/packages/react/package.json
index 5f94d88229f..ef65196310b 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -74,7 +74,7 @@
},
"dependencies": {
"@github/mini-throttle": "^2.1.1",
- "@github/relative-time-element": "^5.0.0",
+ "@github/relative-time-element": "^5.4.0",
"@lit-labs/react": "1.2.1",
"@oddbird/popover-polyfill": "^0.7.3",
"@primer/behaviors": "^1.10.3",