Add experimental React RelativeTime

[adierkens]

Closes #

Changelog

New

• ExperimentalRelativeTime is available from @primer/react/experimental for opt-in evaluation of the native React implementation.
• Internal users can enable primer_react_relative_time to evaluate the implementation through the established RelativeTime entry point.

Changed

• The stable RelativeTime component continues to render the existing <relative-time> custom element and retains its dependency, props, callback event contract, refs, and serialized formatting attributes by default.
• The experimental implementation is SSR-safe, renders a native <time>, and uses Intl APIs for formatting and live updates. It preserves its data-component and datetime contract; it intentionally does not reproduce legacy formatting attributes. If rollout diagnostics need DOM metadata, add a dedicated data-relative-time-* contract rather than reviving custom-element attributes.
• DataTable VRT masks both stable and experimental RelativeTime DOM shapes, so neither live timestamp output causes unrelated baseline churn.
• The changeset is now a minor release because the stable API and DOM output remain unchanged.

Removed

• None.

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

• Added coverage for the stable custom-element default, preserved nullable-date and formatting-attribute behavior, the flagged React implementation, unsupported legacy precision fallback, SSR output, formatting variants, live updates, callback payloads, and public experimental exports.
• The focused RelativeTime browser tests, export snapshot test, package type-check, full unit suite, lint, CSS lint, formatting, and build pass locally.
• The retriggered VRT run on ff7297694 showed 297 DataTable failures across 99 snapshots (three retries each). The stable default had reverted to <relative-time>, while the prior mask only targeted the experimental <time> shape. Commit fba412b2e masks both shapes; no baselines were regenerated.
• github-ui integration PR #28694 passed its relevant build, type-check, and package-test jobs with the stable path restored. Its unrelated VRT status gate remains separate from the component tests.

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

[changeset-bot]

🦋 Changeset detected

Latest commit: 5b7d457

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[primer-integration]

Integration test results from github/github-ui PR:

  CI Passed
  VRT Waiting
  Projects Running

[mattcosta7]

I think we need a fallback timezone for this, otherwise we'll have unsafe hydration when the server formats in UTC but the client render formats in locale timezone?

we probably need a path to making this configurable for the server pass too

[adierkens]

Are we already hitting that hydration mismatch today?

[mattcosta7]

Yep - we are. I updated the custom-element version with a fallback to a fixed UTC renderer - but that's not ideal

we should be able to avoid that a bit - since we don't need to wait for custom element hydration to show the updated value, but we do hit tz hydration mismatches today, as well as value replacement (light -> shadow swaps) causing shifts