feat(DatePicker): New DatePicker component

[aresnik11]

Overview

Adds DatePicker to Gamut: a locale-aware, accessible date (or date range) picker with text inputs, a popover calendar, keyboard support, and optional composition via context.

Modes

• Single date — selectedDate / setSelectedDate.
• Date range — startDate, endDate, setStartDate, setEndDate; optional startLabel / endLabel.

Default UI vs composition

• Default — text input(s) + calendar in a popover under the input.
• Custom — pass children for layout only; compose DatePickerInput and DatePickerCalendar (calendar requires DatePicker context).

Text input

• Locale-aware formatting and default placeholder from the locale date pattern.
• Live typing with blur normalization when input is invalid or partial.
• Empty input clears the relevant selection (single or range bound).

Calendar & layout

• Responsive — two adjacent months from the xs breakpoint up; one month on smaller viewports.
• Month navigation with nav adjusted for two-month view.
• Week starts from Intl.Locale#getWeekInfo() (polyfill when needed), optional weekStartsOn on DatePickerCalendar.

Selection behavior

• Single — select a day; same day again clears.
• Range — selection by focused field (start vs end), or full-range behavior when neither field is focused; rules for clearing bounds, extending range, and avoiding ranges that include disabled dates follow https://www.figma.com/make/8hUgRziVeW0LzplwtQRyiu/Date-range-picker-v2?p=f&t=K2AAbiaWeAcJdEXR-0.

Disabled dates

• disabledDates — unselectable days; integrated into range validation.

Footer

• Today — select today and align visible month(s).
• Clear — range mode; clears range; disabled when empty.

Keyboard & focus

• ArrowDown from input opens calendar and moves focus into the grid (or focuses grid if already open).
• Open via click keeps focus on the input (pointer-friendly / WCAG-oriented).
• Grid — arrows (day/week), Home / End (row), PageUp / PageDown (month; Shift for year), Enter / Space to select, Escape closes and returns focus to input.
• Two-month — horizontal arrows can move between visible months appropriately.

Accessibility

• Calendar role="dialog" with configurable aria-label.
• Input role="combobox" with aria-expanded, aria-controls, aria-haspopup, aria-autocomplete="none".
• Grid tied to month heading and per-day accessible names.

Internationalization

• locale usesIntl.LocalesArgument, defaults to runtime locale but ability to override via locale prop
• translations for clear button, field labels, and dialog label. default values in English but ability to override via translations prop
• weekStartsOn uses Intl.Locale#getWeekInfo() (polyfill when needed) but ability to override via weekStartsOn prop
• Calendar month/year, weekday table headers, placeholder date format (MM/DD/YYYY), date cell aria labels, are automatically localized to the locale via Intl.DateTimeFormat
• Last month/next month tip text and today button text are automatically localized to the locale via Intl.RelativeTimeFormat

Other

• inputSize passes through to Input size in the default layout.

Things I know are missing/not completely working:

• segmented input
• calendar is supposed to close after selecting a date(s)
• tests
• calendar quick actions

PR Checklist

• Related to designs:
• Related to JIRA ticket: GMT-1520
• I have run this code to verify it works
• This PR includes unit tests for the code change
• This PR includes testing instructions tests for the code change
• The alpha package of this PR is passing end-to-end tests in all relevant Codecademy repositories

Testing Instructions

Don't make me tap the sign.

1. Go to story X
2. Do something
3. Do that something in dark mode
4. Check it with VO
5. Finish and do a celebratory dance

PR Links and Envs

Repository	PR Link
Monolith	Monolith PR
Mono	Mono PR

[aresnik11]

@sh0ji re focus ring transition: this is our default gamut focus ring. do you want me to override it for this case or can i cut a separate ticket to update the focus ring opacity transition across the board?

[dreamwasp]

have a couple comments but looking good overall!

[dreamwasp]

could you get the robot to add tests for these longer util functions

[aresnik11]

yeah im going to tackle tests separately and everything will have tests

[dreamwasp]

idk if you want to get nitty gritty w/ it, but comment here

[codecademydev]

📬 Published Alpha Packages:

Package	Version	npm	Diff
@codecademy/gamut	68.2.3-alpha.02a91b.0	npm	diff
@codecademy/gamut-icons	9.57.3-alpha.02a91b.0	npm	diff
@codecademy/gamut-illustrations	0.58.10-alpha.02a91b.0	npm	diff
@codecademy/gamut-kit	0.6.593-alpha.02a91b.0	npm	diff
@codecademy/gamut-patterns	0.10.29-alpha.02a91b.0	npm	diff
@codecademy/gamut-styles	17.13.2-alpha.02a91b.0	npm	diff
@codecademy/gamut-tests	5.3.4-alpha.02a91b.0	npm	diff
@codecademy/variance	0.26.2-alpha.02a91b.0	npm	diff
eslint-plugin-gamut	2.4.4-alpha.02a91b.0	npm	diff

[github-actions]

🚀 Styleguide deploy preview ready!

Preview URL: https://69d3ee242142547e479a95d5--gamut-preview.netlify.app
Deploy Logs: https://app.netlify.com/projects/gamut-preview/deploys/69d3ee242142547e479a95d5