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 intent is to offer Temporal adoption without forcing a breaking engine migration for all 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.

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 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. 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. 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 primary public value type.

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 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. Timezone-sensitive operations use Temporal APIs explicitly.
3. Formatter and label helpers consume PlainDate and locale metadata.
4. No date-fns imports in temporal-specific modules.

8.3 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.

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 so /temporal has no runtime dependency on date-fns.

6. 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.

7. 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.

8. 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.

9. 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.

10. 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 date arithmetic and comparison utilities using Temporal.
2. Implement matcher logic with Temporal.PlainDate.
3. Implement navigation and selection hooks for temporal values.

Phase C: 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 D: 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 and polyfill setup.

Phase E: 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

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 path does not add required runtime cost to default path.
4. Accessibility parity is validated across both paths.
5. Tests, typecheck, lint, and docs build pass.
6. 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. Polyfill setup issues:

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

4. 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.

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. 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. 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