base-ui [temporal] New `Calendar` component

Part of #1709

Step 1: Extract a minimal version of the Calendar component from the X repo

In this PR

Adapters

~The adapters expose a unified set of methods in order to support several date libraries. The MUI X Date and Time Pickers currently support 8 adapters (Day.js, Luxon, Moment, Date Fns v3+v4, Date Fns v2, Moment Jalaali, Moment Hijri and Date Fns Jalali). One of the main goal of this PR should be to decide if we want to keep this abstraction.~

Decided to hide the adapter initially and use the date-fns adapter internally.

[x] Import the adapter internals
[x] Remove the properties only used by the field components (to keep the PR "light")
[x] Improve some methods (create a adapter.now() method to avoid polymorphism on adapter.date())
[x] Remove most unused formats and give more explicit names to the remaining ones (to know if they have leading zeros or not)
[x] Import and update the Luxon adapter
[x] Migrate the adapter tests

Manager / validation

The manager expose methods to interact with the value regarless of its type (date, time, date time, date range, time range and date time range). This allow to do stuff like validate the value, set the timezone on a value, compare two values etc... It allows to share a lot of code between the Calendar and the Range Calendar (see useSharedCalendarRoot). On the field components, it will allow to have almost all the code agnostic of the value type and to create very light wrappers for each value type.

[x] Import the manager internals
[x] Remove the properties the the calendar doesn't use (to keep the PR "light")
[x] Import and update the date manager
[x] Import the validation internals
[x] Import and update the date validation
[x] Rework the date validation API (remove disableFuture and disablePast, replace shouldDisableDate with a isDateUnavailable that is not part of the validation per say like on React Aria)
[x] Add tests

Calendar component

[x] Migrate my PoC from the MUI X repo without the month view, the year view and the range calendar parts
[x] Use the new store/selector introduced for the Select
[x] Create a first version of the doc page with a CSS Module example
[x] Create a few experiments
[x] Implement a11y keyboard navigation
- [ ] Refine keyboard shortcut navigation with checks for disabled days
- [x] Fix issues with typing for DOM updates/syncs (onKeyDown)
[ ] Add example of lazy loading inside of days
[ ] Add Tailwind examples
[ ] Add tests (not sure how deep I'll go :laughing: )
[x] Update to use the new eventDetails structure
[x] Add transitions to month navigation

May 27 '25 14:05 flaviendelangle

Deploy Preview for base-ui ready!

Name	Link
Latest commit	744b4ee20d447107450e06c80730ce123e5d7fe4
Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/691dcab359ca260008d0d6d3
Deploy Preview	https://deploy-preview-1973--base-ui.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

May 27 '25 14:05 netlify[bot]

vite-css-base-ui-example

pnpm add https://pkg.pr.new/mui/base-ui/@base-ui-components/react@1973

pnpm add https://pkg.pr.new/mui/base-ui/@base-ui-components/utils@1973

commit: f4b65de

May 28 '25 11:05 pkg-pr-new[bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui-components/react	🔺+17KB^(+5.44%)	🔺+4.81KB^(+4.83%)

Details of bundle changes

Generated by :no_entry_sign: dangerJS against f3c2aa59bb5cd600e163588b02392b8d8f5750ce

May 30 '25 07:05 mui-bot

I'm wondering if a template-based API (not fully composable, so instead of forcing users to render each week and day, they'd only specify a template and we will be responsible for rendering) wouldn't be a better choice here.

I suppose (feel free to correct me, though) that in most (if not all) cases, users will simply map weeks and days arrays to DayGridRow and DayGridCell. Having a DayTemplate and WeekTemplate could simplify the required JSX.

Jun 04 '25 10:06 michaldudak

@michaldudak could you give me a basic JSX example of what it could look like?

Jun 04 '25 10:06 flaviendelangle

Something along these lines:

<Calendar.DayGridBody className={styles.DayGridBody}>
  <Calendar.DayGridRowTemplate>
    { (week, props) => <div {...props} className={styles.DayGridRow} /> }
  </Calendar.DayGridRowTemplate>

  <Calendar.DayGridCellTemplate>
    { (day, props) => <div {...props} className={styles.DayGridCell}><Calendar.DayButton className={styles.DayButton} /></div> }
  </Calendar.DayGridCellTemplate>     
</Calendar.DayGridBody>

(alternatively, with a render prop instead of children)

EDIT: I just realized this could be problematic with SSR, as templates would have to register themselves in their parent. We could work around this by looking for them with React.children.

Jun 04 '25 12:06 michaldudak

I have mixed feelings with the shortcuts on the DX here. Is the few lines of JSX removed worth the new concept that people will have to learn? That's always the question I guess.

In your example, how would people style the other nodes? (mostly GridHeader, GridHeaderBody and GridHeaderCell?) In my example, I think I'm adding CSS to every single DOM node. Or how they would pass other props like event handlers? (probably more niche for sure).

I do agree with you that for bigger component, the fully composable approach becomes quite verbose. And that, for the Calendar, almost all app will have similar JSX if they use a fully composable approach. I do think the fully composable approach has value and I wouldn't remove it (because it is the most flexible one). But I'm interested to see how we could come up with a alternative and complementary DX. React Aria has a short version:

  <CalendarGrid>
    {(date) => <CalendarCell date={date} />}
  </CalendarGrid>

But it only works because they ship CSS by default. We could do the same and expose a classes prop to allow people to style the nodes, but it's not super "Base UI".

Jun 04 '25 15:06 flaviendelangle

Another point, I decided to let the user map the cells, to be super flexible, but we could of course discuss replacing:

  <Calendar.DayGridRow value={week}>
    {({ days }) =>
      days.map((day) => (
        <Calendar.DayGridCell value={day}>
          <Calendar.DayButton />
        </Calendar.DayGridCell>
      ))
    }
  </Calendar.DayGridRow>

With:

  <Calendar.DayGridRow value={week}>
    {({ day }) =>
      <Calendar.DayGridCell value={day}>
        <Calendar.DayButton />
      </Calendar.DayGridCell>
    }
  </Calendar.DayGridRow>

It's what React Aria does on their Date Field component You loose the ability to skip some days, add stuff between the days etc... (which I don't have a valid use case for, but I can't guarantee nobody wants to do it), but you have a shorter DX. (same the the header cell and the grid row)

Jun 04 '25 15:06 flaviendelangle

@flaviendelangle Thanks for this, excited to see it! I had a quick first look over it.

Chiming in on the recent feedback

I'm wondering if a template-based API (not fully composable, so instead of forcing users to render each week and day, they'd only specify a template and we will be responsible for rendering) wouldn't be a better choice here. Is the few lines of JSX removed worth the new concept that people will have to learn?

I don't personally feel much pain in the JSX. On the contrary, I'm actually quite surprised at how terse it is. If there are new concepts to learn, or potential issues with SSR, or styling limitations, or content limitations, I'd opt for the usual normal compound pattern. If there are none of those limitations, it's worth considering.

I decided to let the user map the cells, to be super flexible, but we could of course discuss replacing:

This seems more promising to me. I prefer it without the map. If we can't think of a valid use case we'd be restricting, it seems we should do this?

Some questions/suggestions of my own:

In June, why are dates 6–10 missing? Can I control that somehow?
Can you add isDateUnavailable and timezone to .Root in the demo please? Just so I can see the syntax.
What is the thinking behind exposing <Calendar.KeyboardNavigation> as a component, rather than just always enabling keyboard navigation and not having a component for it?
Drop "Day" and just call it Calendar.Grid?
What is the purpose of the nativeButton prop and what's its use case?
Rather than <Calendar.SetVisibleMonth target="previous|next", what do you think about Calendar.Previous and Calendar.Next? Or Calendar.PreviousMonth and Calendar.NextMonth or Calendar.SetPrevious and Calendar.SetNext. I think something like this might be more inline with the conventions we set in our NumberField component.
Do we have some mechanism to set the beginning of the week? Some people consider it Sunday, others Monday.
How will animation work? Do we need to add the data-starting-style and data-ending-style attrs?
How could we animate it vertically, so the next/previous buttons are up/down arrow icons, and the next month slides up from the bottom, and the previous month slides down from the top?
What is the purpose of the {({ weeks }) => map? I was expecting to just see the days map, since I don't see any mention of weeks in the calendar demo.

Btw, lmk whenever you want some styling feedback. I assumed it's too early for that, so didn't bother.

Jun 05 '25 00:06 colmtuite

Feedback

Bug?: I'm assuming focus isn't meant to revert back to the beginning after navigating to a new month and selecting a day

https://github.com/user-attachments/assets/9c057afa-d9ed-4409-a8b4-1f7c02b9c13b

What's the purpose of Calendar.KeyboardNavigation? Shouldn't this be implicit inside the Root part?

VoiceOver doesn't announce the new month when navigating down continually (past the last/first date) once it loops. The buttons also don't have an aria-label and say the icon name.

Jun 05 '25 04:06 atomiks

This seems more promising to me. I prefer it without the map. If we can't think of a valid use case we'd be restricting, it seems we should do this?

I will remove the map so that we can discuss this version :+1:

In June, why are dates 6–10 missing? Can I control that somehow?

I will check why

Can you add isDateUnavailable and timezone to .Root in the demo please? Just so I can see the syntax.

Sure

What is the thinking behind exposing <Calendar.KeyboardNavigation> as a component, rather than just always enabling keyboard navigation and not having a component for it?

What's the purpose of Calendar.KeyboardNavigation? Shouldn't this be implicit inside the Root part?

It did the split recently looking at #1963, but I'm very unsure My reasoning was to have a smaller bundle size when you don't need keyboard navigaton, but I struggle to find a use case where it doesn't make sense to have it...

What is the purpose of the nativeButton prop and what's its use case?

I just re-used what other components are doing when using useButton I think it's to support SSR correctly.

Rather than <Calendar.SetVisibleMonth target="previous|next", what do you think about Calendar.Previous and Calendar.Next? Or Calendar.PreviousMonth and Calendar.NextMonth or Calendar.SetPrevious and Calendar.SetNext. I think something like this might be more inline with the conventions we set in our NumberField component.

No big technical challenge here. If we are fine having 6 components it's good for me. I just think having a shortcut way of going to the previous and next without date manipulation is nice. But not strong preference on the exact DX.

Do we have some mechanism to set the beginning of the week? Some people consider it Sunday, others Monday.

We let the date library handle that. I need to document it, you can find the MUI X doc here

How will animation work? Do we need to add the data-starting-style and data-ending-style attrs?

I did not explore that at all yet. Do you think it's needed on the initial PR or can it be kept for a follow up?

How could we animate it vertically, so the next/previous buttons are up/down arrow icons, and the next month slides up from the bottom, and the previous month slides down from the top?

For me the current version make no assumption on the rendering layout to we could animate vertically. But I would need to explore and add experiments.

What is the purpose of the {({ weeks }) => map? I was expecting to just see the days map, since I don't see any mention of weeks in the calendar demo.

Not sure to understand this one. Do you mean you expected a single map in ·Calendar.DayGridBody that would render the days without having one row per week?

Bug?: I'm assuming focus isn't meant to revert back to the beginning after navigating to a new month and selecting a day

Clearly bug EDIT: Should be fixed now

VoiceOver doesn't announce the new month when navigating down continually (past the last/first date) once it loops. The buttons also don't have an aria-label and say the icon name.

The accessibility is probably far from perfect for now. I will add aria-label on the buttons. For the new month, not sure how to achieve that.