Calendar (WIP)
Gregorian date selection, localized weekdays and explicit caption composition.
Ordinary demos on this page explicitly use Shadcn Rhea, with matching examples. This does not change public compatibility defaults or imply complete browser, native-host or visual acceptance. Neutral Surface/Text atoms retain their own public semantics; the consumer composition supplies the family presentation theme.
Calendar is a Gregorian control with single (default), multiple and range selection modes. value uses YYYY-MM-DD; the canonical visible month uses YYYY-MM. Selection and month can each be controlled. A successful requestMonth means a proposal was emitted, not that the owner accepted it. Refused or pending cross-month keyboard navigation keeps the current valid Tab entry; accepted navigation materializes and focuses only after canonical month changes and current availability is checked. Focus is not stolen back from an external control.
Range and multiple selection
Section titled “Range and multiple selection”| Mode | Controlled / initial selection | Request callback |
|---|---|---|
single | value / defaultValue: YYYY-MM-DD string | onValueChange({ value }) |
multiple | values / defaultValues: date array | onValuesChange({ values }) |
range | range / defaultRange: { from?, to? } | onRangeChange({ range }) |
Multiple selection toggles each activated day. Arrays are deduplicated, sorted by civil date and copied on input and output. minSelected defaults to 0; maxSelected is unbounded when omitted. Adding a day can build up from empty toward the minimum; removing a day must leave at least the minimum. Explicit requestValues replacements validate the complete array against both count limits. Range selection starts with { from }; a second activation completes an inclusive { from, to }, ordering reversed endpoints. Activating a day after completion starts a new range. {} clears a range. A same-day range is complete when minNights=0 (the default). minNights and maxNights constrain the civil-day interval between endpoints; they do not count selected cells. Omitted maxima are unbounded. Limits must be nonnegative integers.
min, max and Root unavailable apply to every selected date. A completed range crossing an unavailable date is rejected and retains its anchor. Put whole-date restrictions on Root unavailable; local Day disabled only disables that authored control. Root disabled and readOnly reject selection requests. Changing eligibility never silently rewrites an owner’s current selection.
requestValue(date) activates a date in the current mode. requestValues(dates) and requestRange(range) replace the corresponding selection only in that mode. A true result means a request was emitted; controlled rendering changes only after the matching owner prop is accepted. getValues() and getRange() return copies. default* inputs initialize once, and switching modes preserves each mode’s separate selection. Root also exposes mode, selectedCount and rangeComplete.
Day exposes rangeStart, rangeEnd, rangeMiddle and rangePending alongside selected. A pending anchor has start/pending; a one-day complete range has start/end; interior days have middle. Every date in a complete range is selected. The family recipes distinguish endpoints from middle segments, and Grid projects aria-multiselectable for range and multiple modes. Keyboard navigation is unchanged; Enter or Space activates the focused date.
Composition and clock ownership
Section titled “Composition and clock ownership”The ten atoms are Root, Caption, Heading, Previous, Next, Grid, Weekdays, Weekday, Row and Day. Compose seven Weekday atoms with offsets 0–6 inside Weekdays, then optionally retain six indexed Rows (index 0–5) of Day atoms with offsets 0–41 as capacity. By default the canonical month displays the minimum complete 4, 5 or 6 weeks; Root fixedWeeks=true explicitly reserves six. Root exposes weekCount; indexed unused Rows and unused offset Days expose hidden and are hidden/disabled off the focus path. Unindexed rows and explicit dates remain application-authored. Weekday labels and date order follow Root weekStartsOn (0 = Sunday) and locale; full localized civil dates name the grid cells. direction="rtl" mirrors Left/Right navigation, leaving Up/Down and week boundaries unchanged. Navigation controls accept a11yLabel for icon-only accessible naming.
The host supplies today as a civil-date string. Base never reads a clock or timezone: no today means no current-date marker. Today and selected are independent, including unavailable dates; today projects aria-current="date". Initial month priority is explicit month, explicit defaultMonth, the active mode’s selected date (single value, earliest multiple value, or range start), supplied today, then deterministic 1970-01. Later clock updates do not silently navigate. unavailable is a string array; invalid inputs retain their prior valid value/default. Root disabled combines with local Day/Previous/Next disabled policy; readOnly blocks selection while allowing browsing.
Explicit month/year caption composition
Section titled “Explicit month/year caption composition”The demo uses real family Select controls and bindCalendarCaption(source, {month, year}) through public Calendar month/disabled state and requestMonth. Caption itself is only a semantic group. Month and year selectors are application composition, not an internal Calendar Select dependency. The helper always restores canonical control values after rejection or pending acceptance, subscribes to later commits, and exposes dispose() for teardown. The demo owns an explicit year option list (not a Calendar limit), local-clock today, midnight/visibility refresh and complete controlled prop records. The Month and Year triggers pass stable names through the public Select accessibleLabel prop; Select Value independently displays the current month or year. The demo does not write Adapter-owned ARIA attributes. Computed accessible names, name stability after selection, keyboard interaction and focus return still require current-source browser evidence; screen-reader acceptance remains separate.
The Shadcn demo restores the upstream example’s current-year-minus-100 through current-year list (101 options), without truncating it to disguise collection cost. Other families retain an explicitly application-chosen ±10-year sample. Caption month labels use the host’s Intl short-month format by default; createCalendarDemo(family, {captionLocale}) can choose that host boundary separately from English weekday labels. The user’s Chinese month / English weekday example can therefore be composed explicitly. Our family Select popup is not the official page’s native-select popup and is not claimed to match native platform pixels.
The page selects Rhea’s 32px date/navigation cells (h-8 w-8) and p-3 layout at a 16px root font, from the Rhea style source. The separate base-nova registry, observed on 2026-10-10, retains its 28px/p-2 compatibility recipe. Neither recipe is enlarged merely to match a screenshot. Actual focus and selection remain independent Base facts; this is not complete react-day-picker compatibility or native visual acceptance.
The Rhea month/year selectors use the supported default appearance and small size, with the complete public Select Content, Surface, Viewport and ItemText composition. The public parts own popup paint and scrolling, while preserving all 101 year options.
Verification boundary
Section titled “Verification boundary”This remains WIP. Calendar behavior has focused actual-host tests including WC, React, Vue and Vue2; public Props/Exposes/AsHook domains are checked independently. The current CLI collector misses some legitimate inherited Calendar/nested Button state tokens, so stateful generated CSS and browser visual fidelity are not accepted. Compiler interpretation is a separate owner’s responsibility, not a reason to constrain valid Prototype semantics. Native GPUI/Qt, compiled and packed parity, exact-commit browser evidence and independent acceptance remain open.
Calendar is workspace source. There is no public proto-ui add target. Passing value selects controlled mode. An omitted today means no today marker.
| Prop | Type | Default |
|---|---|---|
mode | 'single' 'multiple' 'range' | single |
value | string | undefined |
values | readonly string[] | undefined |
defaultValues | readonly string[] | [] |
range | CalendarRange | undefined |
defaultRange | CalendarRange | {} |
minSelected / minNights | number | 0 |
maxSelected / maxNights | number | undefined |
defaultValue | string | '' |
min | string | '' |
max | string | '' |
unavailable | readonly string[] | [] |
disabled | boolean | false |
readOnly | boolean | false |
weekStartsOn | number | 0 |
fixedWeeks | boolean | false |
a11yLabel | string | Calendar |
today | string | '' |
locale | string | en-US |
These props belong to Root.