Components: Add `DateCalendar` and `DateRangeCalendar` components #70578

chihsuan · 2025-07-01T09:24:20Z

What?

This PR introduces new DateCalendar and DateRangeCalendar components built on the react-day-picker library, originally implemented by @ciampo, with the following changes to make it follow the Gutenberg guidelines/patterns:

Converted CSS modules to standard SCSS: styles.module.scss to style.scss
Updated class names from .calendar__* to .components-calendar__*
Moved Storybook and tests files from individual component folders to centralized stories/ and tests/ directory respectively
Fixed linting errors
Fixed unit tests (failed due to Node version differences in Intl API handling)

cc @oandregal @youknowriad

Why?

Current limitations: DatePicker (@wordpress/components) lacks date range support, while DateRange (Calypso) only handles ranges and requires moment.js.

Create a unified Calendar component that supports both single dates and date ranges, with flexible layout options.

How?

Testing Instructions

Start the storybook
Navigate to the DateCalendar and DateRangeCalendar stories

Testing Instructions for Keyboard

Screenshots or screencast

Screen.Recording.2025-07-01.at.17.20.17.mov

github-actions · 2025-07-01T09:24:29Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: chihsuan <chihsuan@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2025-07-01T09:24:53Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @chihsuan! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

- Introduced `DateCalendar` and `DateRangeCalendar` components for single date and date range selection, respectively. - Implemented localization support and accessibility features in both components. - Added styles and utility functions for calendar rendering and interaction. - Created tests for both components to ensure functionality and user experience. - Updated package dependencies to include `react-day-picker` and related libraries.

- Exported `DateCalendar`, `DateRangeCalendar`, and `TZDate` from the index file. - Updated styles in `calendar/style.scss` to remove unnecessary namespace prefixes. - Imported calendar styles in the main `style.scss`. - Changed story titles for `DateCalendar` and `DateRangeCalendar` to reflect the correct component hierarchy.

ciampo

Thank you, @chihsuan!

Before exporting the component from the package (thus making it a public API), I wonder if we should test the component in real-case scenario first — unless you're already using this component in WooCommerce?

(One small note — for ease of review, it would have been better to have an initial commit only containing the raw pasted code. It would have made it easier to distinguish the actual code changes added in Gutenberg compared to the original component.)

packages/components/src/calendar/date-calendar/test/index.tsx

packages/components/src/calendar/utils/use-controlled-value.ts

packages/components/src/calendar/style.scss

packages/components/src/calendar/test/date-range-calendar.tsx

packages/components/src/calendar/style.scss

ciampo · 2025-07-03T11:34:41Z

packages/components/src/calendar/utils/use-controlled-value.ts

+ * @param root0.onChange
+ * @param root0.value
+ */
+export function useControlledValue< T >( {


As a follow-up, we should try to re-use the existing useControlledValue hook in the package https://github.com/WordPress/gutenberg/blob/2dd93a3b957906412f6b4d8c547d8326f2ba8b78/packages/components/src/calendar/utils/use-controlled-value.ts

packages/components/src/calendar/test/date-calendar.tsx

packages/components/src/calendar/stories/date-calendar.story.tsx

packages/components/src/calendar/stories/date-range-calendar.story.tsx

ciampo · 2025-07-03T13:47:04Z

The styles also seem to be off compared to the original copy of the component:

original copy	this branch
Kapture.2025-07-03.at.15.41.31.mp4	Kapture.2025-07-03.at.15.42.43.mp4

missing focus styles for previous/next month buttons
wrong focus styles for the calendar days
missing background color for the dates selected in a range
wrong dashed border color when previewing the date selection

Likely, something broke either when refactoring classnames and selectors, or when refactoring colro variables.

Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>

- Updated parameter documentation for clarity by renaming `root0` to `props` and adjusting the parameter descriptions accordingly.

…tory.tsx Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>

- Replaced CSS custom properties with SCSS variables for better maintainability in `style.scss`. - Updated button and navigation dimensions, focus outlines, and background colors to utilize the new variable definitions.

chihsuan · 2025-07-04T04:00:15Z

The styles also seem to be off compared to the original copy of the component:

original copy this branch
Kapture.2025-07-03.at.15.41.31.mp4
Kapture.2025-07-03.at.15.42.43.mp4

missing focus styles for previous/next month buttons

wrong focus styles for the calendar days

missing background color for the dates selected in a range

wrong dashed border color when previewing the date selection

Likely, something broke either when refactoring classnames and selectors, or when refactoring colro variables.

Good catch! @ciampo Yes, color variables were not set correctly.

I've fixed it in cf6c3d5.

Screen.Recording.2025-07-04.at.11.58.19.mov

ciampo

As discussed in Slack, we're using this component in WooCommerce Analytics and don’t have any issues with it.

Cool, I guess we can leave the package exports, then!

I apologize for not clarifying this in the PR description. The initial commit does contain only the raw code without any modifications.

My bad, too — I checked, saw the scss file (instead of a CSS) and for some reason I assumed that wasn't the original component code. I must have gotten confused with the CSS modules setup we have in place in other repos 😅

Yes, color variables were not set correctly. I've fixed it

I confirm that styles look good now :)

packages/components/src/calendar/style.scss

packages/components/src/calendar/utils/use-controlled-value.ts

packages/components/src/calendar/utils/use-localization-props.ts

packages/components/src/calendar/stories/date-calendar.story.tsx

packages/components/src/calendar/stories/date-range-calendar.story.tsx

packages/components/src/calendar/style.scss

packages/components/src/calendar/test/date-calendar.tsx

packages/components/src/calendar/test/date-range-calendar.tsx

Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>

…r and date-range-calendar test files.

…tly instead of awaiting it - Adjusted all test cases in both `date-calendar.tsx` and `date-range-calendar.tsx` to reflect this change, improving test performance and readability.

- Updated the DateCalendar test to include a comment explaining the use of "Etc/GMT+2" for time zone, highlighting compatibility with Node v22.

- Updated the `today`, `tomorrow`, and `yesterday` variables in `date-calendar.tsx` and `date-range-calendar.tsx` tests to ensure they are consistently set to the start of the day. - Added a configuration to run tests in UTC timezone to avoid discrepancies based on system timezone.

- Changed the focus outline property in `style.scss` to utilize the CSS variable `--wp-admin-border-width-focus`, enhancing consistency and maintainability.

chihsuan · 2025-07-07T04:02:38Z

Thanks, @ciampo, I've made the suggested changes. 🙇‍♂️

ciampo

Thank you, @chihsuan , for the patience in addressing all of my feedback — code changes LGTM and both components test well in Storybook 🚀

Would you be able to explore/iterate on #70578 (comment) in a follow-up PR?

fabiankaegy · 2025-07-08T10:26:30Z

I added the "Needs Dev Note" Label because I think this is a great new component we should defiantly highlight when it ships in WordPress Core 👍 :)

chihsuan · 2025-07-09T02:28:36Z

Would you be able to explore/iterate on #70578 (comment) in a follow-up PR?

Yes, I can help with that. 🙂

ciampo · 2025-07-10T16:52:13Z

@fabiankaegy I'm removing the "needs dev note" label for now, as I think we want to be a bit more cautious with the way we introduce the component — in #70681 I'm changing it to be a private API. Happy to add the label back in case the component is made public, though!

chihsuan requested a review from ajitbohra as a code owner July 1, 2025 09:24

github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Jul 1, 2025

t-hamano added [Type] Enhancement A suggestion for improvement. [Package] Components /packages/components labels Jul 1, 2025

chihsuan requested review from juanmaguitar, fabiankaegy and ndiego as code owners July 1, 2025 09:41

ciampo requested review from mirka, ciampo and aduth July 1, 2025 10:43

chihsuan added 5 commits July 2, 2025 13:29

Move stories to stories directory

a774ab6

Fix linting errors

2dd93a3

Convert styles.module.scss to style.scss and fix linting errors

1652b10

Move stories and tests to stories and test directories

47d9abc

chihsuan force-pushed the add/calendar-component branch from 68ad983 to 4f507e3 Compare July 2, 2025 05:29

chihsuan added 5 commits July 2, 2025 13:56

Fix lint errors/warnings

57388c3

Fix tests

3a7e8d3

Add changelog

ab1423b

Update docs/manifest.json

275b4a8

chihsuan force-pushed the add/calendar-component branch from bdaeaf1 to 275b4a8 Compare July 2, 2025 05:56

ciampo reviewed Jul 3, 2025

View reviewed changes

packages/components/src/calendar/stories/date-calendar.story.tsx Outdated Show resolved Hide resolved

ciampo reviewed Jul 3, 2025

View reviewed changes

packages/components/src/calendar/stories/date-range-calendar.story.tsx Outdated Show resolved Hide resolved

chihsuan and others added 2 commits July 4, 2025 11:35

Update packages/components/src/calendar/stories/date-calendar.story.tsx

41e57ae

Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>

Refactor documentation in use-controlled-value.ts

be1c1f1

- Updated parameter documentation for clarity by renaming `root0` to `props` and adjusting the parameter descriptions accordingly.

chihsuan and others added 2 commits July 4, 2025 11:54

Update packages/components/src/calendar/stories/date-range-calendar.s…

4052bd0

…tory.tsx Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>

Fix calendar styles

cf6c3d5

- Replaced CSS custom properties with SCSS variables for better maintainability in `style.scss`. - Updated button and navigation dimensions, focus outlines, and background colors to utilize the new variable definitions.

chihsuan requested a review from ciampo July 4, 2025 04:02

Merge branch 'trunk' into add/calendar-component

3053be4

ciampo reviewed Jul 4, 2025

View reviewed changes

chihsuan and others added 11 commits July 7, 2025 11:01

Update packages/components/src/calendar/utils/use-controlled-value.ts

3f6edef

Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>

Update packages/components/src/calendar/utils/use-localization-props.ts

1fbc3b9

Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>

Remove unused import of '@testing-library/jest-dom' from date-calenda…

aa50f64

…r and date-range-calendar test files.

Move @storybook/react under "External dependencies"

d3ddf3c

Updated the setupUserEvent function to return the user event direc…

6ed7018

…tly instead of awaiting it - Adjusted all test cases in both `date-calendar.tsx` and `date-range-calendar.tsx` to reflect this change, improving test performance and readability.

Add note on time zone usage in DateCalendar test

a07fa05

- Updated the DateCalendar test to include a comment explaining the use of "Etc/GMT+2" for time zone, highlighting compatibility with Node v22.

Create variables for preview dates instead of reusing existing variables

8b89f22

Fix conflicts

4de50ac

Add note for tests

d12718a

Update calendar styles to use CSS variable for focus outline

5116112

- Changed the focus outline property in `style.scss` to utilize the CSS variable `--wp-admin-border-width-focus`, enhancing consistency and maintainability.

chihsuan requested a review from ciampo July 7, 2025 04:03

Move react-day-picker imports to the external dependencies

97db44f

ciampo approved these changes Jul 8, 2025

View reviewed changes

ciampo merged commit 6d20ad7 into WordPress:trunk Jul 8, 2025
63 checks passed

github-actions bot added this to the Gutenberg 21.2 milestone Jul 8, 2025

fabiankaegy added the Needs Dev Note Requires a developer note for a major WordPress release cycle label Jul 8, 2025

chihsuan mentioned this pull request Jul 9, 2025

Components: Reuse existing useControlledValue hook in Calendar components #70655

Merged

ciampo mentioned this pull request Jul 10, 2025

DateCalendar, DateRangeCalendar: move to private APIs #70681

Merged

ciampo removed the Needs Dev Note Requires a developer note for a major WordPress release cycle label Jul 10, 2025

Components: Add DateCalendar and DateRangeCalendar components #70578

Components: Add DateCalendar and DateRangeCalendar components #70578

Uh oh!

Conversation

chihsuan commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Uh oh!

github-actions bot commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 1, 2025

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ciampo Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ciampo commented Jul 3, 2025

Uh oh!

chihsuan commented Jul 4, 2025

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chihsuan commented Jul 7, 2025

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

fabiankaegy commented Jul 8, 2025

Uh oh!

chihsuan commented Jul 9, 2025

Uh oh!

ciampo commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Components: Add `DateCalendar` and `DateRangeCalendar` components #70578

Components: Add `DateCalendar` and `DateRangeCalendar` components #70578

chihsuan commented Jul 1, 2025 •

edited

Loading

github-actions bot commented Jul 1, 2025 •

edited

Loading

ciampo commented Jul 10, 2025 •

edited

Loading