Calendar

<Calendar
  value={date}
  onValueChange={setDate}
  month={month}
  onMonthChange={setMonth}
/>

Paging through months is not choosing a day. A calendar that jumped back to the chosen month every time you looked at the next one would be unusable, and one that chose a day because you paged past it would be worse. So there are two pieces of state, and either can be controlled without the other.

Uncontrolled, the month starts on the chosen day's — or on this one.

Never five for a short month. A grid that changed height between March and April would move everything under it twice a year, and the calendar would jump as you paged through it.

Days from the months either side fill the ends. They are muted and still choosable: a calendar that refused the 1st of next month would be refusing a date you can see. What makes a day inert is minValue / maxValue, not which month it belongs to.

Intl.Locale's week info answers it properly where it exists — Saturday-first locales are real, and a hand-kept list of Monday-first languages has never included them. Most React Native engines do not have it, so a list of Monday-first languages is the fallback rather than the source.

firstDayOfWeek={1} overrides both. locale names the months and the weekdays, and defaults to the device's.

<Calendar.Grid>
  {date => (
    <Calendar.Day key={date.getTime()} date={date}>
      <Text>{date.getDate()}</Text>
    </Calendar.Day>
  )}
</Calendar.Grid>

Calendar.Grid takes a function, and it is the one place in this library that does. Forty-two cells are generated from a month rather than written, so there is nothing for a caller to compose against: asChild merges into one element, and a slot list cannot enumerate a month.

A day is a date plus the calendar around it. Calendar.Day reads everything else off its date — chosen, outside the month, out of bounds, today — which is what makes the function above two lines rather than a wiring exercise. It is also what AgendaCalendar builds its event dots on.

<Calendar minValue={new Date()} maxValue={addMonths(new Date(), 3)} />

Days outside them are muted and inert, and the chevrons go dead: a step that would land on a month with no selectable day in it has nothing to show, and a chevron that stays lit while it stops working is the worst of the three options.

Bounds are compared by day, not by instant. A maxValue written as new Date() carries the current time, and an instant comparison would refuse the rest of today.

Today carries a small dot tucked just under its number — the soft accent on a plain day, and the chosen day's own contrast colour when today is the chosen day. It is positioned absolutely so the number does not shift down the day the dot appears.

The arithmetic is utils/dates.ts, and it is tested: startOfDay, isSameDay, isSameMonth, addDays, addMonths, startOfWeek, isWithinBounds, monthGrid, weekGrid, weekdayNames, monthLabel, monthNames, firstDayOfWeekFor.

Two of those exist because the obvious version is wrong:

• addMonths clamps to the end of the target month. new Date(2026, 0, 31) plus a month is the 31st of February, which Date rolls forward to the 3rd of March — so a calendar stepping from January to February would land on March.
• addDays goes through the day-of-month, not through milliseconds. A day is not always 86 400 seconds, and adding that many across a daylight-saving boundary lands an hour into the day before.

Calendar.YearPicker and Calendar.MonthPicker are the legacy dialog's month-year button rebuilt in composition. Each mounts instead of the weekdays and the grid, not over them — a drum of years behind a drum of days would read as two things at once — and the walk is legacy's: the title opens the years, a year opens the months of that year, a month lands back on the days.

view is the third piece of state, controlled the way value and month are. The pickers step it themselves; the caller owns it so the title can be the switch:

const [view, setView] = useState<CalendarView>('grid')

<Calendar value={date} onValueChange={setDate} view={view} onViewChange={setView}>
  <Calendar.Header>
    <Calendar.PreviousButton accessibilityLabel="Mois précédent" />
    <PressableFeedback onPress={() => setView(v => (v === 'grid' ? 'year' : 'grid'))}>
      <Calendar.Title />
    </PressableFeedback>
    <Calendar.NextButton accessibilityLabel="Mois suivant" />
  </Calendar.Header>
  {view === 'year' ? (
    <Calendar.YearPicker />
  ) : view === 'month' ? (
    <Calendar.MonthPicker />
  ) : (
    <>
      <Calendar.Weekdays />
      <Calendar.Grid />
    </>
  )}
</Calendar>

The year and the month on screen each wear the chosen day's disc, and the year list opens on the year it was on. Pressing a year keeps the month of the year it was showing, and pressing a month keeps the year — a header that said "septembre 2026" has not become a switch to January. A year or a month that lies entirely outside the bounds is dead rather than merely inert.

The caller reads view to choose which of the three to render, so in practice it holds the state — as above, or from a child on useCalendar(). The pickers only ever step it.

useCalendar() is exported (R10) and carries the resolved styles, the month on screen, the chosen day, the locale, the panel (view / setView), and the moves: select, goToMonth, canGoToMonth, goToYear and goToMonthInYear. Enough for a "Today" button of your own, or a title on useCalendar().setView — the pickers the built-in ones serve run on nothing else. Outside a <Calendar> it throws by name.