Repository navigation
Description
Assignment boundary
This is one independently assigned implementation task in github/relative-time-element.
This issue contains the contract; no private parent or meeting access is required.
Primer React and Primer ViewComponents will have separate assignments that consume this API.
You do not need those assignments or their issue numbers to complete this work.
Work only on the custom element. Do not assign other issues, start sibling agent sessions,
or open wrapper PRs. Do not wait for messages from another agent.
Make the implementation and handoff readable from your own PR.
Goal
Add a compact presentation for absolute timestamps in width-constrained components.
Keep the formatting in this element so wrappers do not implement separate versions.
Expose absolute-format="compact" and a typed absoluteFormat property.
Use an enum-shaped API, not a Boolean.
Omitted, empty, and unrecognized attribute values retain the existing presentation.
Behavior
Apply the preset only after the existing logic selects absolute output.
It must cover the user preference, threshold transitions, and explicit format="datetime".
Do not change preference handling, thresholds, or mode selection.
| Resolved output | Timestamp | Compact presentation |
|---|---|---|
| Absolute | Today in the effective display time zone | Localized "today at" plus a 12-hour time, such as today at 3:04 PM |
| Absolute | Any other calendar day, past or future | Localized abbreviated month, numeric day, and numeric year, such as Nov 2, 2026 |
| Relative or duration | Any | Existing output, unchanged |
Always include the year on non-today dates, even within the current year.
The English date uses an unpadded day and a four-digit year.
Preserve localized date order and digits.
Do not include a time zone in compact visible text.
Do not include a time on non-today dates.
Use the effective display time zone for both the calendar-day comparison and the time.
"Today" is a calendar day, not the preceding 24 hours.
Use hourCycle: 'h12' for compact visible time.
Do not inherit a 24-hour preference for this preset yet.
Leave hour-cycle behavior unchanged for non-compact output and full titles.
The preset overrides prefix, format-style, and individual display fields:
second, minute, hour, weekday, day, month, year, and time-zone-name.
It does not override lang, time-zone, datetime, or mode-selection controls.
Apply these overrides only when rendering compact absolute text.
Keep the machine-readable datetime and existing full-title generation.
Preserve custom titles and no-title.
Do not add a title when callers suppress it.
Do not redesign access to full timestamp detail in this change.
Localized "today at"
Use Intl.RelativeTimeFormat(locale, {numeric: 'auto'}) for the localized word for today.
Use Intl.DateTimeFormat(...).formatToParts() to obtain the locale's date/time connector.
Start with dateStyle: 'long', timeStyle: 'short', the effective time zone, and hourCycle: 'h12'.
Format the visible time separately with numeric hours and two-digit minutes.
Support as many structurally safe patterns as possible, rather than only an English phrase.
Identify the date/time boundary from typed parts, including dayPeriod.
Do not select an arbitrary literal or split a rendered string on spaces.
Preserve locale ordering, punctuation, and directional characters.
Use the no-connector fallback for Japanese and Chinese locale families, including regional variants.
Use the same fallback whenever the separator is unsafe or ambiguous.
Korean patterns can include a day suffix such as 일 ; do not append it to the word for today.
The fallback is localized today plus localized time, with no guessed English connector.
This is deliberate best-effort localization, not a promise of universal grammatical correctness.
Do not add a translation service or handwritten translation catalog.
Implementation starting points
src/relative-time-element.ts:update(),#resolveFormat(),#shouldDisplayUserPreferredAbsoluteTime(),
#getUserPreferredAbsoluteTimeFormat(), and#getDateTimeFormat().#isToday(),getUnitFactor(), and the shared date observer: reuse the existing calendar/time-zone machinery.observedAttributesand the property accessors: support setting, changing, and removing the preset after connection.src/intl-cache.ts: reuse the existing formatter cache where appropriate.test/relative-time.js: extend the existing absolute-preference and timer cases.README.mdand the existing API comments: document the preset and its precedence.
Use one compact formatter for both absolute-output paths.
Do not add a second timer system.
Keep future compact dates observed so they can become today, including across a year boundary.
Audit near-midnight scheduling for recent timestamps as well as older timestamps.
Keep the exported declarations and generated custom-element metadata consistent with the new API.
Obey the repository's conventions for generated files.
Acceptance checks
- With an
en-USlocale and fixed clock, today showstoday at 3:04 PM; another day showsNov 2, 2026. - Preference on
<html>and preference on<body>each select compact absolute output. - Threshold-based absolute output and explicit datetime output use the same compact formatter.
- Relative output,
duration, andelapsedretain their existing behavior. -
microretains its existing relative/duration output, but uses compact text when existing rules select absolute output. - Omitted, empty, invalid, and removed preset values retain or restore the existing output.
- Compact today uses 12-hour time even when
hour-cycle="h23"is inherited or set directly. - Compact text ignores conflicting display fields and prefixes without changing non-compact text or title behavior.
- Calendar-day checks use the effective time zone when it differs from UTC and the browser zone.
- A today value becomes a date at midnight without a reload, including when the timestamp is less than an hour old.
- A future date becomes today at the correct midnight, including across New Year.
- Daylight-saving transitions use calendar boundaries rather than a fixed 24-hour timeout.
- Connector cases cover
en-US,en-GB, German, French, and Spanish. - Fallback cases cover Japanese, Chinese, and a suffix-attached or ambiguous pattern such as Korean.
- Runtime preset changes update visible text; existing datetime/title opt-outs and invalid-date fallbacks remain intact.
Use the repository's existing browser tests and fixed-clock patterns.
Run its build, lint, and relevant tests.
Check the generated declarations, not just string output.
Deliverable and stop point
Open one PR with the implementation, tests, and documentation.
Reference this element issue in the PR body so downstream agents can find the implementation.
Include a short downstream handoff in that same body:
- The PR URL and the tested commit SHA.
- The final attribute/property spelling, accepted values, and omission/removal behavior.
- The 12-hour compact-time rule, connector/fallback behavior, and preserved title behavior.
- The commands needed to build, pack, and temporarily install this commit in a wrapper checkout.
- Where the built JavaScript, declarations, and generated API metadata are found in the packed package.
- Any known blocker or difference from this issue's contract.
Build before packing. Do not require a published release or a hosted tarball for this handoff.
Do not change the agreed contract silently; identify a conflict and leave the affected acceptance checks open.
If you cannot finish the implementation, identify the incomplete work in a draft PR rather than claiming completion.
Do not publish a release or choose a final package version.
Do not merge the PR, change wrappers, or modify application consumers in this issue.
The assignment stops at your open implementation PR and its handoff.
Do not update a parent tracker or wait for the other two PRs.
Activity