Skip to content

Expose the compact absolute-time preset in RelativeTime #8802

Open

Description

@tay1orjones

Goal and dependency

Expose the custom element's compact preset through:

<RelativeTime date={timestamp} absoluteFormat="compact" />

Upstream issue: github/relative-time-element#404 in github/relative-time-element
("Add an opt-in compact absolute-time preset").

Keep this PR in draft while the upstream implementation and package release are pending.
Use the upstream implementation for all formatting. Do not duplicate it in React.

Independent assignment and upstream lookup

You own only the primer/react work in this issue.
There is no orchestrator and no shared conversation with the element or Rails agents.
This issue contains the required wrapper contract; it does not require the private parent or meeting notes.
Do not assign other issues, start sibling agent sessions, change another repository, or wait for agent messages.
The Rails wrapper is not a dependency.

  1. Read the upstream issue body and comments using the supplied public issue URL.
  2. Read its linked implementation PR, including the description, relevant discussion, current diff, and declarations.
  3. If no PR URL is supplied, inspect the issue's linked PRs or search github/relative-time-element for its exact issue reference.
  4. Confirm the candidate PR references that issue and implements the requested API. Do not select by a similar title alone.
  5. Record the chosen PR URL and exact head commit SHA. Read its build/pack handoff and inspect the source at that SHA.
  6. Compare the implementation with the contract below before writing wrapper-specific changes.

A linked issue or PR is evidence, not proof that the feature is implemented or released.
If the issue and implementation disagree, report the difference in your own draft PR.
Do not silently change the contract or implement a second formatter to compensate.
If there are multiple plausible PRs, an inaccessible source, or no usable implementation, use the blocked path below.

Contract

absoluteFormat="compact" changes presentation only when the element already selects absolute output.
It does not force absolute output or change thresholds or user preferences.

Today uses a localized date/time connector and 12-hour time.
Japanese, Chinese, and unsafe connector patterns fall back to localized today plus time.
Other days show a localized short month, numeric day, and year.
Compact visible text omits the time zone, and non-today dates omit the time.
The effective locale and time zone still apply.
Today follows a calendar day in that time zone, not a rolling 24-hour window.
The year is present even for dates within the current year.
The 12-hour rule applies only to compact visible time, not full titles or existing output.
The element owns calendar-boundary updates, including future dates becoming today.

The preset overrides prefix, formatStyle, and individual date/time display fields while compact output is active.
It does not change mode selection or the full timestamp detail.
Preserve datetime, custom titles, and noTitle.
Omitting the prop preserves the existing behavior.
Support both date and datetime inputs, and prop changes/removal after rendering.
Relative/duration output stays unchanged; micro uses compact only when its existing rules select absolute output.

Work

  • Check packages/react/src/RelativeTime/RelativeTime.tsx and packages/react/src/utils/create-component.ts.
    The wrapper uses @lit-labs/react, with props derived from the element type.
    Use the upstream typed property and verify actual forwarding; do not introduce a parallel formatter or unsafe type casts.
  • Add the prop description to packages/react/src/RelativeTime/RelativeTime.docs.json, or its current authoritative replacement.
    Document precedence there. A separate design document is unnecessary.
  • Add a focused feature story showing compact today and a non-today date.
    Include a non-compact comparison and existing absolute-output selection.
    Reuse established story patterns and restore any document-level preference after the example.
  • Extend RelativeTime.test.tsx and the existing browser coverage as needed.
    Keep the UTC server fallback and explicit children behavior.
  • Add the release note or changeset required by repository guidance.

Suggested public prop description:

Controls presentation when absolute output is selected. compact shows localized today with
12-hour time, or a date with its year. 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. Omitting the prop preserves existing behavior.

Unpublished dependency

The dependency is in packages/react/package.json; its lockfile is the root package-lock.json.
Before merge, both must use the actual element release containing this feature.

For this draft, record the upstream issue URL, PR URL, tested commit SHA, and pending release bump in the PR body.
^5.4.0 is an anticipated minimum, not a confirmed release.
Do not commit an unavailable version or invent lockfile metadata.
If a release already exists when you start, verify that it contains the implementation and is available through the configured registry.
Use that actual release and regenerate the lockfile rather than retaining a provisional plan.

Build and pack the upstream PR, then temporarily use that package for integration and type checks.
Build before npm pack; the upstream package does not build itself through a pack hook.
Keep temporary local dependency paths and tarballs out of the committed diff.
Use the configured dependency registry.
If the upstream build is inaccessible, report the blocker rather than faking the implementation.

Keep the committed released dependency until the actual release is available.
State which ordinary CI checks remain blocked by that dependency.
Do not add type shims, weaken types, or mock the new behavior to make them pass.
Replacing the dependency and regenerating the lockfile is a before-merge follow-up, not part of the agent's stop point.

If upstream is not ready or accessible

Complete the wrapper work supported by the contract, such as documentation, stories, and meaningful test cases.
Open a clearly marked partial draft PR for that work, with the upstream issue link.
Keep acceptance checks that require the actual element build unchecked.
State whether the blocker is a missing PR, ambiguous implementation, unavailable source, failed upstream build,
or unpublished dependency. Distinguish that from a defect in the wrapper.

Include the exact input needed to resume: a confirmed upstream PR URL and usable commit,
or the published version containing the feature.
Do not invent a URL, claim integration was verified, fake the API, or wait indefinitely.
No automatic restart or cross-agent notification is assumed.
If you cannot open a PR, report that limitation in this assignment's final result.

Acceptance checks

  • absoluteFormat="compact" type-checks against the upstream package and reaches the live element.
  • date and datetime inputs retain their behavior with the new prop.
  • A browser example renders compact today and a non-today date using the real upstream implementation.
  • Prop changes and removal update or restore the element's output.
  • Preference off with relative output remains relative; the prop does not force absolute output.
  • Existing children, noTitle, and full timestamp detail remain intact.
  • Existing server fallback and hydration checks also cover the compact prop without new hydration errors.
  • The public prop description explains precedence, 12-hour time, and omitted-prop behavior.
  • The draft PR links the upstream issue and confirmed implementation PR, records the tested SHA, and states remaining release blockers.

Use the existing test, type-check, build, and story tooling.
Test live element behavior, not only the presence of a prop or attribute.
Leave the full localization and calendar-boundary matrix in the upstream suite.

Deliverable and stop point

Open one draft PR containing the wrapper integration, documentation, examples, and tests.
Link the upstream issue and implementation PR in its body and record the upstream build used for testing.
Identify what works, what remains blocked, and the precise before-merge dependency update.
Recheck the upstream PR once before handoff; if its head moved, report the tested SHA and assess whether the change affects compatibility.
Keep it in draft; do not merge, publish, wait for a release, or change application consumers.
The assignment stops at your draft PR, or an explicitly reported partial draft under the blocked path.
Do not update a parent tracker, wait for the Rails PR, or claim the whole workstream is complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions