RFC: DayPicker with Temporal

[gpbl]

1. Summary

This RFC proposes that DayPicker v11 remains date-fns-based by default, while introducing a new optional Temporal implementation under a dedicated subpath:

• Default import path remains unchanged and date-fns-based:
  • import { DayPicker } from "react-day-picker"
• New optional Temporal path:
  • import { DayPicker } from "react-day-picker/temporal"

The Temporal path is designed as a day-first API:

1. Public date values are Temporal.PlainDate.
2. Zone-aware today is derived as Temporal.PlainDate via Temporal.Now.plainDateISO(resolvedTimeZone).
3. The timeZone prop controls zone-sensitive behavior such as deriving today and formatting/labels.

This offers Temporal adoption without forcing a breaking engine migration for existing users.

2. Motivation

We want to support two valid user needs at the same time:

1. Stability for current users who rely on Date + date-fns behavior and ecosystem.
2. A first-class Temporal option for users who want immutable, explicit date primitives now.

Replacing the default engine in v11 increases migration risk across selection behavior, timezone handling, locale expectations, and userland utilities. A dedicated /temporal path reduces that risk while allowing full Temporal implementation to mature in production.

A day picker primarily operates on calendar days, not instants. Making Temporal.PlainDate the public type keeps selection and matcher logic stable, avoids time-of-day drift, and aligns with DayPicker's existing mental model. Time zone still matters for "what day is today" and localized output, so zone handling remains explicit but internal.

3. Goals

1. Keep default DayPicker behavior (react-day-picker) backward-compatible and date-fns-based.
2. Ship a production-ready Temporal DayPicker at react-day-picker/temporal.
3. Preserve accessibility and keyboard behavior parity between default and temporal paths.
4. Keep package exports tree-shakeable so non-temporal users do not pay temporal bundle/runtime costs.
5. Define explicit timezone semantics for Temporal path, including deterministic today behavior.
6. Define a path to evaluate whether Temporal should become default in a future major.

4. Non-Goals

1. Do not rewrite the default DayPicker to Temporal in v11.
2. Do not remove date-fns, date-fns-jalali, or @date-fns/tz from default runtime path in v11.
3. Do not introduce implicit behavior changes in existing react-day-picker imports.
4. Do not force Temporal polyfill installation for users who do not import /temporal.
5. Do not require date-time/instant types in the public /temporal API.

5. Locked Decisions

1. react-day-picker (default path) remains date-fns-based in v11.
2. A new react-day-picker/temporal subpath is introduced.
3. Temporal runtime requirements apply only to the /temporal path.
4. Temporal implementation is fully Temporal-native internally (no date-fns dependency in that subpath).
5. Public date-bearing contracts in /temporal use Temporal.PlainDate.
6. Zone-aware defaults (for example today) are derived with Temporal.Now.plainDateISO(resolvedTimeZone) and stored as Temporal.PlainDate.
7. Existing specialized calendar paths (/persian, /buddhist, /ethiopic, /hebrew) remain unchanged for v11 scope unless explicitly extended later.

6. Public API Design

6.1 Default Path (Unchanged)

import { DayPicker } from "react-day-picker";

• Keeps existing Date-based props/events.
• Keeps existing date-fns locale and formatter expectations.

6.2 Temporal Path (New)

import { DayPicker } from "react-day-picker/temporal";

Temporal path uses Temporal.PlainDate as the public value type for day-bearing fields.

type TemporalDay = Temporal.PlainDate;

type TemporalDateRange = {
  from: Temporal.PlainDate | undefined;
  to: Temporal.PlainDate | undefined;
};

type TemporalOnSelectHandler<T> = (
  selected: T,
  triggerDate: Temporal.PlainDate,
  modifiers: Modifiers,
  e: React.MouseEvent | React.KeyboardEvent,
) => void;

6.3 Time Zone Contract in /temporal

timeZone remains a supported prop in the Temporal path, but it does not change the public selected-value type.

1. Selected values, range endpoints, and matcher date values are still Temporal.PlainDate.
2. timeZone affects zone-sensitive defaults and presentation, not the shape of selected values.
3. If today is not passed, DayPicker derives it from the configured zone:
   • Temporal.Now.plainDateISO(resolvedTimeZone)
4. today can be overridden via today?: Temporal.PlainDate.
5. When timeZone changes, derived today and dependent month calculations must update.

6.4 Naming and Exports

The /temporal entry point exports its own DayPicker and related types:

• DayPicker (Temporal variant)
• DayPickerProps (Temporal variant)
• Temporal-specific type aliases such as TemporalDateRange and TemporalMatcher

No API surface changes are required in default path exports.

7. Runtime and Dependency Model

7.1 Default Path

• Uses current runtime/dependencies.
• No Temporal requirement.

7.2 Temporal Path

• Requires native Temporal or @js-temporal/polyfill.
• If unavailable, throws a clear runtime error with setup instructions.

Suggested error guidance:

1. Install @js-temporal/polyfill.
2. Initialize polyfill in app bootstrap before rendering.
3. Ensure SSR/client runtime parity.

7.3 Packaging

• Keep subpath exports explicit in package.json ("./temporal").
• Ensure /temporal code is isolated to avoid affecting default bundle size.
• Preserve ESM/CJS parity for the new subpath.

8. Internal Architecture

8.1 Shared UI Core with Pluggable Date Backend

Refactor toward a shared rendering and interaction core with separate date backends:

1. Existing Date/date-fns backend for default path.
2. New Temporal backend for /temporal.

This avoids duplicating components while isolating date logic differences.

8.2 Temporal Backend Rules

1. Canonical date model is Temporal.PlainDate.
2. Selection, matcher, and navigation math operate on Temporal.PlainDate.
3. Zone-aware defaults are derived directly as Temporal.PlainDate with Temporal.Now.plainDateISO(resolvedTimeZone).
4. Formatter and label helpers consume Temporal.PlainDate plus locale/timezone metadata.
5. No date-fns imports in temporal-specific modules.

8.3 "Today" Modifier Semantics in Temporal Path

today is treated as a date-only value in the same model as all other day cells.

1. Default: compute today from resolved timeZone using Temporal.Now.plainDateISO(resolvedTimeZone).
2. Comparison: day.equals(today) (date equality only).
3. If today prop is provided, it is authoritative.
4. timeZone changes recompute derived today and refresh modifiers.
5. Optional enhancement: schedule a re-render at next midnight in the resolved timeZone so long-lived mounted calendars roll over automatically.

8.4 Accessibility and Interaction Contract

Both backends must preserve:

1. Keyboard navigation behavior.
2. Screen-reader labels and roles.
3. Focus movement semantics.
4. Selection state transitions.

9. Implementation Plan

Concretely, the code changes should be implemented as the following explicit work items:

1. Add temporal subpath exports in package metadata.
   Update package.json exports so ./temporal has ESM, CJS, and type declarations, matching the existing packaging pattern used by the main entry point and calendar subpaths.

2. Create a dedicated Temporal public entry point.
   Add src/temporal/index.ts (and corresponding build outputs) to export the Temporal DayPicker component and Temporal-specific types without changing src/index.ts behavior.

3. Define Temporal-specific public type contracts.
   Introduce new type modules (for example src/types/props-temporal.ts, src/types/shared-temporal.ts, and matcher/range type files) where date-bearing fields are based on Temporal.PlainDate instead of Date, including today?: Temporal.PlainDate and timeZone?: string.

4. Extract backend-agnostic UI logic from current core modules.
   Refactor shared rendering and interaction flow from src/DayPicker.tsx, src/useCalendar.ts, and src/useSelection.ts into reusable modules that can be wired to either the existing date-fns backend or the new Temporal backend.

5. Implement the Temporal date backend under src/temporal/.
   Add Temporal-native utilities for date arithmetic, month/week boundaries, comparison/equality, interval traversal, selection math, and matcher evaluation using Temporal.PlainDate.

6. Implement timezone context helpers for Temporal path.
   Add internal helpers to:

   • resolve effective time zone (prop or runtime default)
   • derive today as PlainDate from zone-aware "now"
   • handle zone changes deterministically
   • optionally support midnight rollover re-render in selected zone

7. Implement Temporal formatting and localization adapters.
   Add formatter/label helpers in src/temporal/ that consume Temporal.PlainDate and use Intl APIs (and locale metadata) to provide parity with existing captions, weekday labels, and accessible strings.

8. Add a runtime guard for Temporal availability.
   Create src/temporal/getTemporal.ts (or equivalent) to resolve globalThis.Temporal and throw a deterministic, user-facing error when neither native Temporal nor @js-temporal/polyfill is available.

9. Keep default path behavior unchanged by strict isolation.
   Ensure the react-day-picker default import path continues to use current date-fns code paths, and verify no temporal-only code is pulled into the default bundle via accidental shared imports.

10. Add a dedicated Temporal test matrix.
    Add tests under src/temporal/**/*.test.tsx for Temporal-only behavior, and add parity tests that compare user-visible behavior between default and temporal paths for selection, navigation, modifiers, and accessibility labels.

11. Update examples and documentation for the new import path.
    Add focused docs and examples showing import { DayPicker } from "react-day-picker/temporal", required runtime/polyfill setup, and migration patterns from Date-based state to Temporal.PlainDate.

Phase A: Export and Scaffolding

1. Add ./temporal subpath exports.
2. Create temporal types and props contracts.
3. Add runtime guard for Temporal availability.

Phase B: Temporal Date Backend

1. Implement PlainDate arithmetic and comparison utilities.
2. Implement matcher logic with Temporal.PlainDate.
3. Implement navigation and selection hooks for temporal values.

Phase C: Time Zone and "Today"

1. Implement timeZone resolution and zone-aware today derivation.
2. Wire today modifier comparisons with PlainDate equality.
3. Handle runtime timeZone changes and optional midnight rollover behavior.

Phase D: UI Integration

1. Reuse current UI components where possible.
2. Wire temporal backend into shared rendering flow.
3. Ensure no regressions in modifier rendering and event handling.

Phase E: Testing and Docs

1. Add parity tests between default and temporal paths for behavior.
2. Add temporal-specific tests for type and runtime guarantees.
3. Add docs for /temporal usage, polyfill setup, and timezone semantics.

Phase F: Release and Validation

1. Release v11 with default path unchanged + new /temporal.
2. Track adoption and defect trends.
3. Use data to inform whether Temporal becomes default in a later major.

10. Testing Strategy

Mandatory coverage for both paths:

1. Selection modes:

   • single, multiple, range
   • required/min/max constraints

2. Navigation:

   • month/year navigation
   • week starts and ISO behavior

3. Modifiers:

   • disabled/hidden/custom matcher behavior

4. Accessibility:

   • ARIA labels
   • keyboard flow
   • focus behavior

5. Localization:

   • caption formatting
   • weekday labels
   • numeral rendering where relevant

6. Temporal-only:

   • runtime guard behavior
   • polyfill path validation
   • PlainDate matcher and range correctness
   • today modifier correctness in selected timeZone
   • behavior when timeZone changes at runtime
   • optional midnight rollover behavior (if implemented)

11. Acceptance Criteria

1. react-day-picker import path remains behaviorally compatible for existing Date-based users.
2. react-day-picker/temporal is production-usable with Temporal-native types.
3. Temporal public API uses Temporal.PlainDate for date-bearing values.
4. today modifier in /temporal reflects the resolved timeZone.
5. Temporal path does not add required runtime cost to default path.
6. Accessibility parity is validated across both paths.
7. Tests, typecheck, lint, and docs build pass.
8. Documentation includes clear migration and setup instructions for temporal users.

12. Risks and Mitigations

1. Dual-backend maintenance complexity:

   • Mitigation: shared UI core + strict backend interface boundaries.

2. API confusion between paths:

   • Mitigation: clear docs and explicit type names by entry point.

3. Confusion about timezone with PlainDate:

   • Mitigation: document that timeZone controls today derivation and formatting, while selected values remain PlainDate.

4. Polyfill setup issues:

   • Mitigation: deterministic runtime errors and copy-pasteable setup examples.

5. Behavioral drift between paths:

   • Mitigation: parity-focused test matrix and shared acceptance scenarios.

13. Migration Guidance

For existing users

No change required. Keep using:

import { DayPicker } from "react-day-picker";

For Temporal adopters

Switch to:

import { DayPicker } from "react-day-picker/temporal";

Then migrate date-bearing state and handlers from Date to Temporal.PlainDate.

If your app persists instants, convert at your app boundary:

1. From instant to picker value: convert the instant in your app time zone, then map to a Temporal.PlainDate.
2. From picker value to instant: combine PlainDate with app time zone and chosen wall-clock time at your app boundary.

14. Release Notes Guidance

v11 release notes should state:

1. Default DayPicker remains date-fns-based.
2. New optional Temporal implementation is available at /temporal.
3. Temporal runtime or polyfill is required only when importing /temporal.
4. Temporal path uses Temporal.PlainDate public values; timezone is used for today and formatting semantics.
5. Existing Date-based apps do not need immediate migration.

15. Open Follow-Ups

1. Should specialized calendar paths also gain temporal variants (/persian/temporal, etc.)?
2. Should a Date <-> Temporal helper package be published for user migration convenience?
3. Should midnight rollover be enabled by default in /temporal or kept opt-in?
4. What adoption/quality thresholds trigger an RFC to make Temporal the default path?

[Sparticuz]

Time zone issues disappear altogether when using PlainDate, so none of the tz handling needs to be ported over.

Temporal-polyfill seems to be more popular right now. (It's what I used). But it isn't 100% spec compliant because some temporal operations require BigInt support and only the @js-temporal one has that. (Though I'm not sure which operations and if they are needed for PlainDate.)

https://npmtrends.com/@js-temporal/polyfill-vs-temporal-polyfill

Edit: Also, Typescript 6 will include the types for Temporal (microsoft/TypeScript#62628)

[gpbl]

Thanks @Sparticuz, I’m getting familiar with the Temporal API, so your feedback is really helpful.

I’m still struggling a bit with PlainDate vs. ZonedDateTime. I’ve been bitten by the buggy Date implementation, and I’m not fully sure which one makes more sense in the context of our calendar. Would a timezone still be involved here? How would that interact with PlainDate?

[Sparticuz]

If daypicker is going to stay ONLY dates, and not have a time element, PlainDate is so much simpler. Since there is no time element in PlainDate, there is no need for time zones at all. You click on Feb 10, 2026, and the value for PlainDate.toString() is 2026-02-10 regardless of the time zone the user is in.

ZonedDateTime is more similar to Date, with time zones, so it would require a time element. In which case, toString() would be something similar to 2026-02-10T00:00:00-05:00[America/New_York].

IMO, PlainDate is what should be used in this package.

What's more, is that a PlainDate can easily be extended to add time information, so a user can take the output of daypicker, and then add a time element with .toZonedDateTime({plainTime: "10:00:00", timeZone: "America/New_York"}) and then the user will have a ZonedDateTime. It makes it much easier to add a time picker to daypicker

[andystalick]

Is there ever a use-case where we don't care about the date boundaries? Knowing TZ is key to understanding which side of the date-line we are on, as well as understanding daylight-savings-time application.

Maybe translating to PlainDate at the boundary is the right move, but handling TZ seems like key functionality to me.

Regardless, looking forward to this advancing, thanks to all for the work so far!

[gpbl]

Good point, @andystalick. While a calendar always has the same dates falling on the same weekdays, in DayPicker we also rely on today’s date, which is one case that can vary between time zones. I now think that ZonedDateTime would be a better choice.

[Sparticuz]

I admit, I’m not sure of everything that react-day-picker does behind the scenes, but Temporal.Now.plaindateiso() gives ‘today’ for the user’s current time zone.