feat: CalendarPreview date picker composition

[Shreyag02]

Summary

PR 3 of 7 in the RFC 005 stack, on top of #895.

Adds the date picker — which is not an export. It's three parts composed, and the composition lives in the docs.

<CalendarPreview value={date} onValueChange={setDate}>
  <CalendarPreview.Trigger>
    <CalendarPreview.Input />
  </CalendarPreview.Trigger>
  <CalendarPreview.Content>
    <CalendarPreview.Days />
  </CalendarPreview.Content>
</CalendarPreview>

In	.Trigger, .Content, .Input, root open / defaultOpen / onOpenChange
Not in	Range (PR 4), scale switcher + period views (PR 5)
Deleted	Nothing — use-picker-popover.ts goes when the old family does

Changes

Part	Notes
.Trigger	Anchors the popover, owns opening. Renders the value or placeholder when childless. Never a button — it wraps a control
.Content	Apsara Popover.Content. Takes its props; flips on collision
.Input	Apsara Input. Parses via parseScaleInput, displays via formatValue, reports onValidityChange

• Root gains open / defaultOpen / onOpenChange, forwarding Base UI's typed details — not a re-declared { reason?: string }.
• Typing emits nothing. Enter, blur, and the blur an outside click causes commit. No Apply button, no commit prop.
• Coarser scales (May 2027, Q4 2026) parse but are refused until PR 5, rather than committing a day nobody typed.
• minDate / maxDate join the context so .Input can separate out-of-bounds from unavailable.
• Docs: Basic, Disabled, Disabled dates, Without calendar icon, With Field, Custom trigger. No-icon is trailingIcon={null} — composition, not a prop.

Technical Details

The RFC's mechanism doesn't exist. It assumed focus-to-open would arrive as a Base UI trigger option:

Checked	Result
openOn* in Base UI 1.7.0	openOnHover, openOnInputClick, openOnArrowKeyDown — no openOnFocus
Popover.Trigger wiring	useClick + hover only
useFocus	exists, unexported floating-ui-react internals

So it's a handler — but one, on .Trigger, reporting Base UI's own trigger-focus. .Input never touches open state.

jsdom passed; real input didn't. Driving Chrome over CDP with trusted events (no new dependency — Node 24 ships a global WebSocket):

Case	Synthetic	Real trusted input
Click input	pass	trigger-focus → trigger-press closes → trigger-focus reopens
Escape	pass	closes, then instantly reopens — Base UI returns focus to the trigger

That's the race this rewrite exists to kill, and the jsdom-shaped false negative the RFC warns about.

Two guards, both floating-ui's own rules from useFocus:

Guard	Tracks	Why
Skip focus-open during a pointer press	the pointer	useClick is already going to open it
Skip the focus after an escapeKey / triggerPress close	last close reason	that focus is Base UI handing the trigger back, not the user asking again

Neither mirrors open state. Neither touches dismissal.

Nothing here dismisses anything.

$ grep -rn "addEventListener|mouseup|mousedown|outsideClick" components/calendar-preview/
NONE

Outside press, escape and focus-out are all Popover.Root's — no document listener, no swallowed trigger-press close, no open-state mirror. Those three are what made use-picker-popover.ts 185 lines.

Test Plan

• Manual testing completed
• Build and type checking passes

Real browser, trusted input — the EXIT criterion:

#	Case	Result
1	Click opens	single trigger-press, no flicker
2	Escape closes	no reopen
3	Tab focus opens	single trigger-focus
4	Outside press closes	via focus-out
5	Enter commits	Thu May 20 2027
6	Outside-click commits	Tue Feb 01 2028
7	Selects mounted	0

Check	Result
New picker.test.tsx	29 passed
calendar-preview/ total	385 passed
Full package suite	3092 passed, 1 skipped (skip predates this stack)
biome check / tsc --noEmit	clean
build:apsara / docs build	both green

Covered — focus opens with one event and no re-close; commit on Enter / blur / outside click, each asserted separately; nothing emitted while typing; partial input stays visible; all three day formats; coarser scale refused; clear on empty; formatValue display; every onValidityChange reason plus no re-fire on consecutive invalid keystrokes; disabled and readOnly; controlled open; trigger renders no button; zero Selects open or closed.

Review notes

Thing	Why
Context grew by minDate / maxDate	.Input must distinguish the two invalid reasons; the existing predicate folds them
One as never on the trigger ref	Base UI types it Ref<HTMLButtonElement> & Ref<HTMLElement> — an intersection no single ref satisfies. Ours is always a div

SQL Safety (if your PR touches *_repository.go or goqu.*)

Not applicable — TypeScript and CSS only. No Go files, no database access.

[vercel]

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

Project	Deployment	Actions	Updated
apsara	Ready	Preview	Sep 5, 2026 9:20am UTC

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 6d6b604a-e1c3-4c44-afb0-0a1e3d0bf4da

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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@896

commit: bcc77ec