feat(DatePicker): New DatePicker component by aresnik11 · Pull Request #3286 · Codecademy/gamut

aresnik11 · 2026-03-17T21:39:41Z

Overview

Adds DatePicker to Gamut: a locale-aware, accessible date (or date range) picker with segmented 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.
Calendar closes once a single date or date range is selected.

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).

Segmented inputs

Segmented entry (month / day / year) with locale-driven order and separators (Intl-based layout).
spinbutton pattern (role="spinbutton"), which matches Arrow Up/Down stepping and numeric constraints.
Live typing with blur normalization when input is invalid or partial.
Empty input clears the relevant selection (single or range bound).
Hidden input submits an ISO 8601 date-only value for forms (name / form supported).

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

Each input segment is a role="spinbutton" span (tabIndex={0} when enabled). Focus moves with Tab / Shift+Tab like normal focusable controls. **Arrow Left / Right ** moves focus within the segments. Arrow Up / Arrow Down steps the current segment up or down, clamped to min/max for that field. Month: 1–12. Day: 1–last day of month when month/year are known. Year: 1–9999; if empty, stepping uses sensible defaults (e.g. current year when stepping up from empty on year).
Alt + 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 shell uses role="group"; FormGroup associates the visible label with the first segment via htmlFor / id.
Visual focus: The shell uses :focus-within so the field still shows focus when any inner segment is focused.
Input segments use role="spinbutton", matching Arrow Up/Down stepping and numeric min/max.
Input segments include:
- aria-valuemin / aria-valuemax — match spin bounds (day max depends on month/year when known).
- aria-valuenow — when there is a numeric value; omitted when empty.
- aria-valuetext — display string (digits or placeholders like MM / DD / YYYY).
- aria-label — field name (month, day, year).
- aria-invalid — validation/error state.
- aria-disabled and tabIndex={-1} when disabled.
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:

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

PR Checklist

Related to designs: https://www.figma.com/design/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=127461-42132&m=dev
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.

Go to DatePicker
Play around with DatePicker and make sure all the functionality matches the description above
Do that something in dark mode
Check it with VO
Finish and do a celebratory dance

PR Links and Envs

Repository	PR Link
Monolith	Monolith PR
Mono	Mono PR

dreamwasp

i also had an issue opening the Calendar with the keyboard, but everything else looks + sounds good on VO.

i'd like to see some form integration tests (Gamut DatePicker / calendar in a form and assert submitted (or controlled) field data). i will prob look over this again tomorrow once i've let it percolate a little bit more ☕

dreamwasp · 2026-04-13T18:23:24Z

+                  // eslint-disable-next-line jsx-a11y/control-has-associated-label
+                  <td
+                    // fix this error
+                    // eslint-disable-next-line react/no-array-index-key, jsx-a11y/control-has-associated-label


curious about the a11y error here

dreamwasp · 2026-04-13T18:25:59Z

+import { MiniChevronLeftIcon } from '@codecademy/gamut-icons';
+import * as React from 'react';
+
+import { IconButton } from '../../Button';
+import { useResolvedLocale } from '../utils/locale';
+import { CalendarNavProps } from './types';
+import { getRelativeMonthLabels } from './utils/format';
+
+export const CalendarNavLastMonth: React.FC<CalendarNavProps> = ({
+  displayDate,
+  onDisplayDateChange,
+  onLastMonthClick,
+  locale,
+}) => {
+  const resolvedLocale = useResolvedLocale(locale);
+  const { lastMonth } = getRelativeMonthLabels(resolvedLocale);
+
+  const handleLastMonth = () => {
+    const lastMonth = new Date(
+      displayDate.getFullYear(),
+      displayDate.getMonth() - 1,
+      1
+    );
+    onDisplayDateChange?.(lastMonth);
+    onLastMonthClick?.();
+  };
+
+  return (
+    <IconButton
+      alignSelf="flex-start"
+      aria-label={lastMonth}
+      icon={MiniChevronLeftIcon}
+      size="small"
+      tip={lastMonth}
+      onClick={handleLastMonth}
+    />
+  );
+};


i feel like CalendarNavLastMonth + NextMonths could be one component + DRYED up

yeah ive been fussing with this a bunch. do you think the keyboard nav/tab order makes sense? its something like left arrow left calendar body right arrow. or should it be left arrow right arrow calendar. i was updating to make the calendar headers more attached to the calendar body in the reading order

codecademydev · 2026-04-13T19:20:36Z

📬 Published Alpha Packages:

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

github-actions · 2026-04-13T19:22:32Z

🚀 Styleguide deploy preview ready!

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

sh0ji

heads up that I only really reviewed the API, not the implementation. looks really good in general! but I did have quite a few questions and there are three things that could use refinement:

every prop needs a description and we should be very picky about those descriptions. prop descriptions are our most important docs since they can clarify usage, help in situations where naming is hard, and because they're our best just-in-time docs since they're visible during development thanks to IDE type hinting.
naming conventions: I'm of the opinion that callback props should always be named on${Event}, and that seems to be the case across Gamut. it's possible that some of the props I commented on aren't actually callback props, which would reinforce my first point (better descriptions).
the focus management API feels too big to me. happy to brainstorm ideas to solve it, but my instinct is to remove as much of it as possible and just handle it internally. it's also easier to add props later than it is to remove them after they're out.

sh0ji · 2026-04-13T19:43:14Z

+  /** Move focus from the input into the grid when the calendar is already open (e.g. ArrowDown). */
+  focusCalendarGrid: () => void;
+  /**
+   * Flips on each grid focus request so `CalendarBody` effects re-run when `focusTarget` is unchanged.
+   * Not a semantic true/false — only the change matters; pair with `gridFocusRequested`.
+   */
+  focusGridSignal: boolean;
+  /** When true, `CalendarBody` runs a one-shot move of DOM focus into the grid if it is not already there. */
+  gridFocusRequested: boolean;
+  /** Clears `gridFocusRequested` after focus has moved into the grid (or call when closing). */
+  clearGridFocusRequest: () => void;


these four props plus moveFocusIntoCalendar in OpenCalendarOptions is five props just for focus management, which feels like a huge API for something that I don't personally think developers want to spend that much time thinking about. how much of it do we need to expose to users?

i dont think any of this needs to be exposed to users

yeah this is the context props so we're handling all of this internally within DatePicker, this is what is within the context. i can move this type into a different file if thats clearer?

sh0ji · 2026-04-13T19:56:03Z

+  /** Which input is active (start/end focused); null = selection mode. */
+  activeRangePart: ActiveRangePart;
+  /** Set which input is active (e.g. when input receives focus). */
+  setActiveRangePart: (part: ActiveRangePart) => void;


I'm confused. "active" = focused? and "part" = the two different inputs (start/end)? the semantics and names of these props could use some refinement. and if these are part of the focus management API, I also wonder if there's just some better way to handle this?

yes this is for the logic when you specifically click on one of the inputs and then select a date in the calendar

lmk if you have a better naming suggestion or way to handle this

aresnik11 · 2026-04-13T21:04:24Z

heads up that I only really reviewed the API, not the implementation. looks really good in general! but I did have quite a few questions and there are three things that could use refinement:

every prop needs a description and we should be very picky about those descriptions. prop descriptions are our most important docs since they can clarify usage, help in situations where naming is hard, and because they're our best just-in-time docs since they're visible during development thanks to IDE type hinting.

naming conventions: I'm of the opinion that callback props should always be named on${Event}, and that seems to be the case across Gamut. it's possible that some of the props I commented on aren't actually callback props, which would reinforce my first point (better descriptions).

the focus management API feels too big to me. happy to brainstorm ideas to solve it, but my instinct is to remove as much of it as possible and just handle it internally. it's also easier to add props later than it is to remove them after they're out.

@sh0ji will update prop descriptions, naming conventions, and clean up what we're exporting (i think this will help with the focus management stuff too)

LinKCoding

I didn't review the docs fwiw -- but I did test the functionality (not including VO) and it worked well using mouse!

I think my review can be grouped into 3 things:

Clean-up around naming and comments (comments esp could be part of a later ticket)
Some RTL clean-up, albeit, you're blocked by current RTL fixes
Echoing Cass's point about using objects in function parameters/arguments

All in all, looking really good :)

LinKCoding · 2026-04-14T17:56:02Z

+  if (startDate && endDate) {
+    // if start date is end date and is clicked, clears everything
+    if (
+      startDate.getTime() === endDate.getTime() &&


purely stylistic, but you could also use isSameDay here

LinKCoding · 2026-04-14T18:36:25Z

+  delta: 1 | -1
+) => {
+  const { min, max } = getSegmentSpinBounds(field, segments);
+  let cur = parseSegmentNumericString(segments[field]);


maybe currentSegementVal to be more accurate?

LinKCoding · 2026-04-14T18:37:49Z

+  fieldOrder: DatePartKind[]
+): SegmentValues => {
+  let rest = digits;
+  const out: SegmentValues = { month: '', day: '', year: '' };


out => segmentDigits? something more descriptive?

LinKCoding · 2026-04-14T18:52:57Z

+                size={inputSize}
+              />
+              <Box alignSelf="center" mt={32}>
+                <MiniArrowRightIcon />


Note: could add a TODO comment for later, but this will need to adjust for RTL (waiting for the useElementDir hook in another PR)

LinKCoding · 2026-04-15T14:22:52Z

+  );
+
+  const setButtonRef = useCallback((date: Date, el: HTMLElement | null) => {
+    const k = new Date(


leftover robo naming? k => key? dateRef?

aresnik11 and others added 30 commits March 2, 2026 17:05

calendar phase 1

fd2fbce

add focus management

0ffb424

add input

b8a856d

datepicker

c096fe9

clean up

9346ac9

refactor datepicker

00a8584

clean up hooks

1946d73

update exports

39d0de0

add missing validation file

23f593d

clean up inputref

c1c9245

wip fix for typing date

9a8f70d

cleaning up

82854c8

update range logic

4f39ff9

range logic when specific input is focused

d194237

deselect logic

3bbeb01

fix lint

a6cbe80

fix story

a56426f

fix lint again

f79ce4a

update snapshot

e0ee942

fix lint

a417554

show 2 months on larger screens

cf4a438

style updates

d3f6fac

PR feedback

e615f9f

fix today in range color

a19fc7b

clean up context

9c30d34

update placeholder text to be locale based

b657556

update next/last month text to be locale based

1924433

capitalize

a83a99a

Merge branch 'main' into ajr-datepicker-styles

40a0c8b

translations

bfd8206

aresnik11 added 12 commits April 6, 2026 13:13

dedupe and format

dc273f3

version plan

43007af

fix sb import

aa6748d

tests round 1

cd040bb

CalendarBody tests

e086026

style updates

3b676f2

utils tests

878339f

segmentUtils tests

c87e08d

segment tests

e8fe147

fix segment refs

0394f4b

close on date select

1d7671a

fix focus & active range part

ed8e59c

aresnik11 marked this pull request as ready for review April 10, 2026 18:02

aresnik11 requested a review from a team as a code owner April 10, 2026 18:02

aresnik11 requested review from LinKCoding, dreamwasp and sh0ji April 10, 2026 18:03

aresnik11 added 2 commits April 10, 2026 14:45

move DatePicker to organism

6431e61

WIP mdx file

464b82a

sh0ji reviewed Apr 10, 2026

View reviewed changes

Comment thread packages/gamut/src/DatePicker/DatePickerInput/Segment/elements.tsx

sh0ji reviewed Apr 10, 2026

View reviewed changes

Comment thread packages/gamut/src/DatePicker/DatePickerInput/Segment/DatePickerInputSegment.tsx

dreamwasp reviewed Apr 13, 2026

View reviewed changes

aresnik11 added 3 commits April 13, 2026 15:09

quick actions

533625b

evan pr feedback

32ce0ff

dont render empty border in footer

e4b9092

sh0ji requested changes Apr 13, 2026

View reviewed changes

LinKCoding reviewed Apr 15, 2026

View reviewed changes

Conversation

aresnik11 commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Modes

Default UI vs composition

Segmented inputs

Calendar & layout

Selection behavior

Disabled dates

Footer

Keyboard & focus

Accessibility

Internationalization

Other

Things I know are missing/not completely working:

PR Checklist

Testing Instructions

PR Links and Envs

Uh oh!

Uh oh!

Uh oh!

dreamwasp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecademydev commented Apr 13, 2026

Uh oh!

github-actions bot commented Apr 13, 2026

Uh oh!

sh0ji left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aresnik11 commented Apr 13, 2026

Uh oh!

LinKCoding left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

aresnik11 commented Mar 17, 2026 •

edited

Loading