Date picker

Problem Context

• The user is selecting one exact date for an appointment, booking, deadline, publication, reminder, or recent/future event.
• The day of week, closeness to today, or nearby availability affects the user's choice.
• Some dates are unavailable because of weekends, holidays, service windows, min and max dates, or capacity rules.
• Users may prefer either pointer selection from the grid or keyboard entry in the text field.
• The service must synchronize visible local format with a backend-safe canonical date.

Selection Rules

• Choose date picker for single-date scheduling when calendar position, weekday, or availability changes the decision.
• Use date input for birthdays, document dates, and other exact remembered dates that users can type faster than they can navigate.
• Use select when there are only a few meaningful date choices, such as three appointment slots or four reporting periods.
• Use text input when approximate wording is acceptable, such as early July or around the end of the month.
• Do not use a calendar picker when the implementation cannot support keyboard navigation, visible labels, typed entry, and focus return.
• Default the open month near the relevant booking window, not always today.
• Show unavailable dates in the grid and explain the rule that makes them unavailable.
• Keep manual date typing available with a persistent format hint.
• Validate typed and picked values against the same min date, max date, and availability rules.
• Avoid automatic form submission when the user selects a day.

Required States

• Closed labelled text field with visible date-format hint and calendar button.
• Open calendar menu with month and year heading, weekday row, previous and next controls, and active focus.
• Today state that is visually distinct from selected date.
• Selected date state synchronized with the text field.
• Unavailable date state for weekends, holidays, outside-window days, or capacity limits.
• Typed valid date state that updates the same canonical value as a grid selection.
• Typed invalid format state that explains the expected date format.
• Out-of-window error state for dates before the minimum or after the maximum.
• Month-navigation state that preserves selection and announces the new month.
• Submitted state showing the canonical YYYY-MM-DD value.

Interaction Contract

• Opening the calendar moves focus to the current, selected, or first available date without losing the labelled input context.
• Previous and next month controls update the grid, heading, available dates, and live status together.
• Clicking or pressing Enter on an available day writes the visible field value and canonical date while leaving the form unsubmitted.
• Unavailable days are skipped or blocked and expose a clear reason such as Weekend unavailable.
• Typing a date in the field is parsed on blur or submit against the same rules as a picked date.
• Escape or a close action returns focus to the input or calendar button without clearing a valid selection.
• Submit validates required value, date format, real calendar date, booking window, and availability before storing the date.

Implementation Checklist

• Define the date purpose, allowed range, unavailable-day rules, local display format, canonical storage format, default open month, and whether manual typing is required.
• Build the labelled input, persistent format hint, calendar button, menu, month heading, weekday headings, previous and next month controls, and day buttons with semantic names.
• Represent selected, today, focused, unavailable, out-of-month, open, closed, empty, invalid, and submitted states in design and code.
• Parse typed values flexibly enough for the locale and validate them with the same service rules used by calendar clicks.
• Keep focus order, arrow-key movement, Page Up and Page Down month movement, Home and End week movement, Escape close, and Tab escape behavior testable.
• Announce month changes, selected dates, disabled restrictions, and validation errors to assistive technology.
• Test keyboard-only operation, screen readers, zoom, small viewports, forced colors, localization, server-returned errors, min and max dates, and unavailable dates.

Common Generated-UI Mistakes

• Using a calendar picker for a date of birth or other remembered historic date.
• Removing manual date typing and forcing pointer-only calendar selection.
• Showing only disabled colors without text explaining why a date cannot be selected.
• Letting unavailable dates be selected and failing late on submit.
• Auto-submitting the form when a day receives focus or selection.
• Opening every picker on today even when the valid booking window starts months later.
• Dropping focus after a month change or date selection.
• Using locale-specific date formatting in the field while storing ambiguous slash dates on the backend.

Critique Questions

• Does the user need weekday or availability context, or would manual date input be faster?
• What month should open first for this task's real booking window?
• Which dates are unavailable and how will the interface explain each restriction?
• Can users type the date, choose it with a pointer, and choose it with the keyboard?
• What happens to focus after opening, navigating months, selecting, closing, and submitting?
• How does the displayed date format map to canonical storage and localization?