feat: RFC calendar rewrite (CalendarPreview)

[Shreyag02]

Proposes replacing Calendar, DatePicker, and RangePicker with a single subcomposed root that owns date and popover state explicitly and exposes every surface as a dot-notation part.

Description

Adds docs/rfcs/005-calendar-preview.md. Docs only — no component code in this PR.

The calendar family is the only part of Apsara that never adopted the composition contract. The RFC argues every recurring bug is downstream of that, and proposes CalendarPreview: one export, dot-notation parts, value/onValueChange + open/onOpenChange, react-day-picker isolated behind one file.

Problem today	Proposed fix
Popover open state is private, so dismissal can't be handed to Base UI — 185 lines of bespoke popover machinery	open/onOpenChange on the root; use-picker-popover.ts deleted
captionLayout='dropdown' reverted — month/year nav can't be the default inside a picker	.Nav is ours, a sibling of the grid; RDP never mounts a Select, so nav is default-on
slotProps bags, children-as-function, onErrorChange — idioms found nowhere else in the library	Parts + render + Field composition; zero slotProps
RDP's prop union forces mode/selected/required to be overridden after the consumer spread	RDP behind .Grid only; ...props spread-last becomes satisfiable
dayjs.extend() in four modules, import-order dependent — the cause of a past P0	Single date-adapter.ts; failure class becomes impossible
Disabling one range input gates the whole picker	lock="from" / lock="to"

Findings turned up while writing it, each cited to file and line in the RFC:

Where	Finding
date-picker.tsx	Unguarded effect loops on an inline defaultMonth; its three siblings were hardened, this one missed
range-picker.tsx	RangePickerProps not exported and in no barrel — consumers can't type a wrapper, yet the docs render its type table
props.ts	Types slotProps.calendar as the full CalendarProps, including four props the real type excludes
CHANGELOG.md	Claims a DataView filterProps.calendar slot that was never built
filter-chip.tsx	Shallow slotProps.input merge silently drops a consumer's container class; CSS reaches into Input's hashed classes
package.json	RDP is two majors behind — but the v10 diff shows the mode/required union is unchanged, so upgrading ≠ fixing this
lockfile	date-fns already ships unconditionally via RDP and Base UI; dayjs is a second date implementation we pay for twice
Base UI 1.6/1.7	No date component, but internals/temporal* adapters exist — date-adapter.ts is shaped to that surface

Breaking, no shim: the new component ships alongside, the old family is removed one release later. The migration map is mechanical and codemod-able. Seven open items for review — the quarter/half-year value shape needs a decision before implementation, since it shapes the type union.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactor (no functional changes, no bug fixes just code improvements)
• Chore (changes to the build process or auxiliary tools and libraries such as documentation generation)
• Style (changes that do not affect the meaning of the code (white-space, formatting, etc))
• Test (adding missing tests or correcting existing tests)
• Improvement (Improvements to existing code)
• Other (please specify)

Docs-only PR; the change it proposes is breaking, noted so the label isn't a surprise later.

How Has This Been Tested?

No code, so nothing to run. The RFC's claims were verified instead:

Claim	How
All file/line citations	Checked against the branch point
Dependency versions	npm registry + pnpm-lock.yaml
RDP v10 union unchanged	Diffed the 9.6.7 and 10.0.1 tarballs — selection types, UI values, classNames keys, components overrides, removed props
Base UI has no date component	Enumerated its exports at 1.6.0 and 1.7.0

Note: the citations predate the latest styling commit on main, so some calendar.module.css line numbers may have drifted. Worth a re-check before merge.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas — every claim cited to file and line
• I have made corresponding changes to the documentation (.mdx files) — this PR is the doc; component .mdx lands with the implementation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works — N/A, no code; acceptance criteria are in the RFC's Testing section

Screenshots (if appropriate):

N/A — no visual change.

Related Issues

Prior art	#819 — the coordinated overhaul this RFC argues was necessary but not sufficient
Lands with the rewrite	FilterChip rewrite, DataView filterProps.calendar slot, filter-operations → date-adapter.ts
Independent, not prerequisites	@base-ui/react → ~1.7.0, react-day-picker → ~10.0.1

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
apsara	Ready	Preview	Aug 24, 2026 9:29am

[coderabbitai]

Warning

Review limit reached

Next included review available in 54 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a885093e-bbd4-43e3-a79e-9fc8bdf63672

📥 Commits

Reviewing files that changed from the base of the PR and between 8ab14c9 and 8c1388a.

📒 Files selected for processing (1)

• docs/rfcs/005-calendar-preview.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

pnpm add https://pkg.pr.new/@raystack/apsara@890

commit: 8c1388a

[rohanchkrabrty]

@Shreyag02 can you make the RFC a bit more concise? Currently it feels bloated and hard to understand.