Here is how your PR affects size of JS and CSS bundles shipped to the user's browser:

Sections (~1150 bytes added 📈 [gzipped])

name                             parsed_size           gzip_size
reader                              +39410 B  (+1.1%)     +491 B  (+0.1%)
patterns                            +39410 B  (+2.0%)     +491 B  (+0.1%)
subscribers                         +39375 B  (+3.7%)     +488 B  (+0.2%)
staging-site                        +39375 B  (+3.1%)     +488 B  (+0.1%)
sites-dashboard                     +39375 B  (+3.8%)     +488 B  (+0.2%)
site-settings                       +39375 B  (+2.7%)     +488 B  (+0.1%)
site-purchases                      +39375 B  (+1.8%)     +488 B  (+0.1%)
site-performance                    +39375 B  (+2.9%)     +488 B  (+0.1%)
site-monitoring                     +39375 B  (+3.4%)     +488 B  (+0.1%)
purchases                           +39375 B  (+1.6%)     +488 B  (+0.1%)
plans                               +39375 B  (+1.9%)     +488 B  (+0.1%)
overview                            +39375 B  (+1.5%)     +488 B  (+0.1%)
jetpack-cloud-plugin-management     +39375 B  (+2.1%)     +488 B  (+0.1%)
hosting                             +39375 B  (+2.3%)     +488 B  (+0.1%)
github-deployments                  +39375 B  (+3.3%)     +488 B  (+0.1%)
domains                             +39375 B  (+1.5%)     +488 B  (+0.1%)
a8c-for-agencies-woopayments        +39375 B  (+4.6%)     +488 B  (+0.2%)
a8c-for-agencies-team               +39375 B  (+4.7%)     +488 B  (+0.2%)
a8c-for-agencies-referrals          +39375 B  (+4.3%)     +488 B  (+0.2%)
a8c-for-agencies-plugins            +39375 B  (+2.3%)     +488 B  (+0.1%)
a8c-for-agencies-overview           +39375 B  (+3.6%)     +488 B  (+0.2%)
a8c-for-agencies-migrations         +39375 B  (+4.6%)     +488 B  (+0.2%)
a8c-for-agencies-client             +39375 B  (+1.8%)     +488 B  (+0.1%)
site-logs                           +39373 B  (+3.3%)     +491 B  (+0.1%)
plugins                             +39373 B  (+1.4%)     +754 B  (+0.1%)
a8c-for-agencies-sites              +39373 B  (+1.6%)     +878 B  (+0.1%)

Async-loaded Components (~491 bytes added 📈 [gzipped])

name                                                                         parsed_size           gzip_size
async-load-design-wordpress-components-gallery                                  +39410 B  (+5.7%)     +491 B  (+0.3%)
async-load-comment-block-editor                                                 +39410 B  (+1.5%)     +491 B  (+0.1%)
async-load-automattic-global-styles-src-components-global-styles-variations     +39410 B  (+2.2%)     +491 B  (+0.1%)

Legend

Generated by performance advisor bot at iscalypsofastyet.com.

This PR modifies the release build for the following Calypso Apps:

For info about this notification, see here: PCYsg-OT6-p2

• help-center
• notifications
• odyssey-stats
• wpcom-block-editor

To test WordPress.com changes, run install-plugin.sh $pluginSlug try/calendar-react-day-picker on your sandbox.

@jameskoster @verofasulo @mirka @retrofox Could you take a look and share some early feedback? This is a prototype but, if we agree on the approach, I'm going to iterate on it and refine it.

Update:

• I re-wrote the styles (instead importing the original styles and partially overriding them, we're now supplying all the styles first-party) and added a few tweaks (like day button hover colors)
• I added first-party types, which involved deciding which of the many react-day-picker props should be forwarded/exposed to our consumers;
• I removed localization from the component, since it would impose the choice of tech stack on the consumer when providing translations data. Consumers of the component will be able to localize it via the locale (used for formatting dates and other calendar preferences such as starting day of the week), labels (used for strings), and dir (used to change visual styles and keyboard interaction for RTL languages)

Next up, I'm going to take a look at controlled vs uncontrolled. react-day-picker only works in controlled mode, and I'm going to try to understand how feasible it is to add support for uncontrolled mode on our end.

In any case, I've added some TODO items in the PR description.

I'm following the linear project and just saw this PR. I thought I'd share the following, though I suppose you're already aware of this.

The "date filter" is one of the features we'd like to have in DataViews (see original conversation). One of the key features would be providing presets ("one day", "past week", etc.). Is this something the new Calendar component will support? or would it be up to consumers to implement?

For reference, in the Site Logs screen, we've reused the existing DateControl (it's also in use in the stats screen, but the component doesn't have a story):

Logs	Stats

One of the key features would be providing presets ("one day", "past week", etc.). Is this something the new Calendar component will support? or would it be up to consumers to implement?

Hey @oandregal ! Yes, we're aware of this need, and we already discussed it on Gutenberg (link). These components are focused on displaying only the Calendar UI and handling the user interaction. We deliberately decided to exclude:

• any features that overlap with a datetime input
• any UI external to the calendar itself (such as presets)

In short — we expect the consumers of the component to handle the presets. I added a "With Presets" Storybook examples to both DateCalendar and DateRangeCalendar which should help with the dataviews case.

Sidenote: happy to help with building that filter dialog, especially when it comes to choosing the componentry and adopting the correct semantics!

Update:

• added support for controlled / uncontrolled use (specific to selected, defaultSelected and onSelect props);
• added more Storybook examples (including one about localizing the component, very much needed after it was decided to entirely delegate localization to consumers of the components);
• added an initial implementation for range previews on mouse hover;

The PR is now ready for a preliminary review, with the goal of flagging any missing requirements, any visual tweaks, and discuss the API approach.

I'd like to highlight a few aspects to receive feedback on.

Code, API design and general functionality (cc @Automattic/team-calypso @retrofox @kangzj @miguelpeixe @dkoo @oandregal )

• Keeping two separate components (DateCalendar and DateRangeCalendar)
• The general choice of props exposed (I kept the same names as react-day-picker, but decided to write first-party types for better control and more fitting JSDocs);
• The footer and autoFocus props — do we think they're useful, or should we omit them initially?
• Clamping numberOfMonths between 1 and 3;
• I haven't exposed any modifiers-related props in the component's public APIs. We could use them at a later point to implement features like the events prop from the DatePicker component from @wordpress/components — either by implementing the feature internally, or by exposing the props and allow consumers to implement their own modifiers;
• general a11y (like the default role="application" or the default aria-labels)
• hooking to Calypso variables (as I'm currently using some temporary, local variables that emulate guenberg vars) (cc @mirka @jameskoster )

Design & visual styles (@jameskoster @verofasulo ):

• Notice how the calendars break on multiple rows when they don't fit on one row. There isn't much we can do about it, as we expect the consumer of the component to resize its container appropriately.
• Are we ok with the general look of calendar days? (resting state / hover / focus / selected / selected range / preview start and end);
• Are we ok with not having any hover styles on the starting and ending range dates?
• Notice how the focus ring around each day overlaps the neighbouring days — this may not look as good when the neighbouring day is today's date, or the start/end day of a selected range (see screenshots below)

I've started to look into adding a datetime filter to DataViews at #103136 It should serve to test the new calendar component developed in this PR as well.

Generally the design is in a decent spot. I think we might need a different treatment for marking today though; currently it disappears when it's part of a selection.

I'm going to work on all the different states in Figma. I don't think design needs to hold up the PR.

Thank you so much for working on this, @ciampo !

Not sure if it's still in progress, but I can't see this logic implemented in the video above: "Clicking outside the range updates the start/end date accordingly. Clicking within a range deselects as well."

Or maybe it is, and I couldn't get it from the video.

we might need a different treatment for marking today though; currently it disappears when it's part of a selection.

@jameskoster, can't we just keep the outline persistent? Like in the MUI calendar:

@veronica.fasulo I should have been more specific, it disappears when it's the first or last date in a range.

Not sure if it's still in progress, but I can't see this logic implemented in the video above: "Clicking outside the range updates the start/end date accordingly. Clicking within a range deselects as well."

By using react-day-picker we are also inheriting the date range selection / deselection behaviour. I personally don't mind their logic, but if we think it's a blocker I can try to work a new behaviour out (although it will take time and add complexity to the code).

I don't think design needs to hold up the PR.

Agree, I don't see any large changes needed — more like small tweaks.

I'll wait for technical feedback before moving forward.

Thank you for taking a look, @kangzj !

Could we please make timeZone a explicit param, which would be useful for Jetpack Stats because all the stats is in the timezone of the site right now?

I don't think handling time zones is relevant since the component only handles dates (and no time) — although I may be missing something.

Plus what's the size implication of adapting the component?

react-day-picker is 17.4Kb minified + zipped, although ~70% of that comes from date-fns, which we would have used directly if we went for a first-party implementation. Also, we're not using the bundled styles, but we're providing our own styles.

Beyond that, though, building a well-functioning, feature-full and accessible Calendar component first-hand would require a big effort, and I'm not sure about what the potential savings in terms of bundle size would be.
We believe that delegating to third party is a better compromise — any inefficiencies in bundle size are compensated by how quickly we were able to put a complex and high-quality component together.

I don't think handling time zones is relevant since the component only handles dates (and no time) — although I may be missing something.

AFAIK, we need to highlight today in the timezone of the site, which otherwise would be incorrect for some pps especially those ones who have a site set to a different timezone as their browser. For example, I'm in +12 zone, and when I look at stats for FG, it always lags 12 hours.

This gets trickier when the Calendar accepts Date objects 🤔

react-day-picker is 17.4Kb minified + zipped, although ~70% of that comes from date-fns, which we would have used directly if we went for a first-party implementation. Also, we're not using the bundled styles, but we're providing our own styles.

Not bad at all. Thanks!

I know this is still a draft but maybe we should put the stories in packages/components path:

AFAIK, we need to highlight today in the timezone of the site, which otherwise would be incorrect for some pps especially those ones who have a site set to a different timezone as their browser. For example, I'm in +12 zone, and when I look at stats for FG, it always lags 12 hours.
This gets trickier when the Calendar accepts Date objects 🤔

I assume that the "today" date would always works as expected, given that it's calculated on the client — new Date() should respect the local datetime settings, right? I expect any logic that needs to coordinate time (and time + date) to be external to these Calendar components as they only deal with dates (and not with time).

I know this is still a draft but maybe we should put the stories in packages/components path:

Absolutely, I'll ensure that the Storybook examples' path is right before merging.

I assume that the "today" date would always works as expected, given that it's calculated on the client — new Date() should respect the local datetime settings, right?

Like I shared in this comment, Jetpack Stats is always in the timezone of the site, regardless of the browser timezone. It means, today would be in site timezone as well. We only allow selection of past dates + today, so if site timezone and browser timezone don't match, then users could have problems selecting dates. For example, if my browser is +12, and site is UTC, when it's 8am, 12 May, my today would be 12 May, and the today for the site is still 11 May.

(I passed 'UTC' as timeZone in the example above and my local timezone is +12)

I understand this might not be super intuitive to users and this is definitely a point to improve; however, it would cover a case where multiple users access the same data set, their data would match.

Jetpack Stats is always in the timezone of the site, regardless of the browser timezone. It means, today would be in site timezone as well. We only allow selection of past dates + today, so if site timezone and browser timezone don't match, then users could have problems selecting dates. For example, if my browser is +12, and site is UTC, when it's 8am, 12 May, my today would be 12 May, and the today for the site is still 11 May.

@kangzj Thank you for sharing a more detailed example.

I tried exposing the experimental timeZone prop, and added a quick Storybook example:

https://github.com/Automattic/wp-calypso/blob/9b1cc7d27fcdeed49a74082b2f0697873482df47/packages/components/src/calendar-react-day-picker/date-calendar.stories.tsx/#L58-L70

Could you take a look and let me know if it fulfils your needs?

Things to keep in mind for more context:

• the onSelect callback will be called with the Date, but I'm not sure about retaining the time zone information
• the official react-day-picker docs suggest using TZDate from date-fns, so we may have to do that

(@mirka , FYI react-day-picker lists date-fns and date-fns/tz as dependencies anyway)

Could you take a look and let me know if it fulfils your needs?

LGTM! Thanks for doing that 👍

@garymurray I understand this component is still a necessity for the Woo Analytics project (as per pfKYZu-2M1-p2) - could we get some feedback from the team to ensure it covers all needs? Thanks!

@garymurray I understand this component is still a necessity for the Woo Analytics project (as per pfKYZu-2M1-p2) - could we get some feedback from the team to ensure it covers all needs? Thanks!

Yup, thanks for the reminder @tyxla :)

Now that the general implementation feels stable enough both in terms of design, functionality and APIs, I'm going to merge this PR, and continue to iterate in follow-ups.

Planned follow-ups:

• remove old WIP calendar prototype, and refactor folder naming and structure;
• convert to CSS modules;
• add unit tests
• add README and any additional best practices docs
• add a more detailed Storybook example resembling the date filtering dialog (ie. with date inputs and presets inside a dialog)
• potentially refine the code for range selection preview, enabling it when min, max and excludeDates props are used.

This Pull Request is now available for translation here: https://translate.wordpress.com/deliverables/17503189

Some locales (Hebrew) have been temporarily machine-translated due to translator availability. All other translations are usually ready within a few days. Untranslated and machine-translated strings will be sent for translation next Monday and are expected to be completed by the following Friday.

Hi @ciampo, could you please edit the description of this PR and add a screenshot for our translators? Ideally it'd include all of the following strings:

• Date calendar
• Date range calendar
• Go to the Next Month
• Go to the Previous Month
• %s, selected

Thank you in advance!

Great work with this one @ciampo, happy to see it land 🚀

Coming late to this, apologies! Last year sometime, Jetpack design and VIP design did some work on establishing a date-time picker component for our charts/analytics products. Posting an image of this below.

Figma File Link

Timelines were short and MVP scope limitations meant that each team ended up building their own thing. Nevertheless, if we're thinking about doing another round with this component, there's a couple of things to note from that collab that might be relevant here.

1. We were both looking at an upper left side location for the input, thus locating presets on the right side of the flyout made more sense.
2. After a design review with the design council, we agreed to go for a progressive disclosure approach, i.e. Presets only flyout at first, with the calendar view appearing only once the "custom range" preset was selected. Obviously if a custom range was currently showing, the calendar view would be open already when the flyout appears.
3. For the component to be useful for VIP, it needed to include time. The timezone was to default to UTC and state this somewhere in the component, because this is the VIP standard for looking at server data (which our charts are normally doing - Jetpack didn't require time). Alternatively, the timezone could be selected by the user, but I'm not sure this adds value (or just complexity).
4. The time (hour and minute) was also needed to be shown in the date-picker input once a custom range was selected. This complicated things somewhat, for VIP at least. The view below is what we ended up implementing in VIP.
   
5. VIP has fairly strict A11y requirements and while researching this component collaboration, I don't think we found even one example that claimed to be fully accessible. The reason was mostly due to the nesting of numerous fields/buttons and inputs, as well as the complex interaction that's needed to define a custom range. Adding time into the equation makes this even more difficult.
   Below you can see what was eventually implemented. I wasn't directly involved in the project, so I'm not 100% on where A11y compliance ended up.
   

Hey @donaghokeeffe , thank you for sharing more details!

The components from this PR focus on proving a calendar UI for date picking in a Calendar interface — ie. the part highlighted in green:

While components take timezone into account to "localize" date picking (for example, right now it's Friday in Italy, but soon in New Zealand will be Saturday), they don't provide UI for time picking.

At the same time, the components accept full date objects, meaning that you should be able to build extra UI for time picking and integrate it with the Calendar UI, as in the screenshot above.

I plan on working on a comprehensive Storybook example for a very similar use case.