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: 63d5e4e

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]

nit early feedback:

creating Intl.DateTimeFormat (and related objects) objects can actually be quite expensive in some cases - safari especially).

If we can build these once and cache/reuse them between instances rather than creating a new one for every instance it can save a good bit of client thead time.

Particularly in cases where many of these render at once on a page (list views) this saves a lot of overhead.

https://github.com/js-temporal/temporal-polyfill/blob/main/CHANGELOG.md#044

Intl.DateTimeFormat instances can be expensive to create. For performance-sensitive code where the same calendar and time zone are used repeatedly for formatting, we recommend creating and reusing an Intl.DateTimeFormat instance with the desired timeZone and calendar options, and then formatting using the value of Temporal.ZonedDateTime.prototype.epochMilliseconds. Intl.DateTimeFormat instances may also require a lot of RAM, so indefinitely caching large numbers of them is not recommended for memory-constrained environments.

[mattcosta7]

I pushed some similar changes to relative-time-element for that too github/relative-time-element#364