All 42 libraries

SugarDatepicker

Interactive month-grid date picker

inspired by EthanEFung/bubble-datepicker datepickercalendarinput

SugarDatepicker code coverage

Month-grid date picker with keyboard navigation, min/max date constraints, localized day and month names (17 locales), and a fully-rendered ANSI view.

Install

composer require sugarcraft/sugar-datepicker

Quickstart

use SugarCraft\DatePicker\DatePicker;

// Opens on January 2026 with the cursor aimed at the seed date, 2026-01-15
// (a cursor on an empty cell falls back to the first valid day); every step
// returns a new picker.
$picker = DatePicker::new(new \DateTimeImmutable('2026-01-15'))
    ->handleKey(DatePicker::KEY_DOWN)   // one row down: Thursday the 22nd
    ->selectDate();                      // selects the date under the cursor

$picker->selectedDate()->format('Y-m-d');   // '2026-01-22'
echo $picker->view();                       // month grid, today and cursor highlighted

// Range mode: Enter sets the start, a second Enter the end
$range = DatePicker::new(new \DateTimeImmutable('2026-01-15'))
    ->withRangeMode(true)
    ->handleKey(DatePicker::KEY_DOWN)->handleKey(DatePicker::KEY_ENTER)
    ->handleKey(DatePicker::KEY_RIGHT)->handleKey(DatePicker::KEY_RIGHT)
    ->handleKey(DatePicker::KEY_ENTER);
[$range->rangeStart()->format('j'), $range->rangeEnd()->format('j')];   // ['22', '24']

What's in the box

Month gridA 6×7 month view with localized day and month names (17 locales), weeks starting Sunday (firstDayOfWeek is not configurable), today and the cursor highlighted, and optional ISO week numbers.
Keyboard navhandleKey() takes the KEY_* constants: arrows move the cursor, Home/End jump to the first/last selectable day of the viewed month (bounds consulted), PgUp/PgDn step one month, Enter selects (single mode) or sets the range start/end, Esc/Escape clears.
Range selectionwithRangeMode(true): the first Enter sets the start, the second the end (swapped if needed), a third starts over; Esc clears.
Date boundswithMinDate()/withMaxDate() clamp navigation to the allowed months and refuse out-of-range selection; withoutMinDate()/withoutMaxDate() lift a bound.
Host-owned color policyThe widget emits raw SGR unconditionally; NO_COLOR stripping, attribute-only monochrome re-styling, and contrast alternates are documented host-side seams (README: Accessibility and terminal fallbacks).
SugarCraft modelModel wraps the picker as a sugar-core Model with an optional event store recording all eight published wire transitions (cursor_moved, month_changed, range_started, range_restarted, range_cleared, date_selected, date_cleared, selection_refused); the payload contract is in the README's Events section.

Source & demos

Try the quickstart →

API

ClassMethodDescription
DatePickerstatic new(?DateTimeImmutable) / withToday(DateTimeImmutable) / withClockToday() / setTime(DateTimeImmutable)Create a picker on a month; pin "today"; jump to a date
DatePickergoToPreviousMonth() / goToNextMonth() / goToPreviousYear() / goToNextYear() / goToToday()Navigate the viewed month
DatePickermoveCursorLeft/Right/Up/Down() / handleKey(string $key)Move the cursor
DatePickerselectDate() / clearDate() / toggleSelection() / selectedDate() / isSelecting()Single-date selection
DatePickerwithRangeMode(bool) / rangeStart() / rangeEnd() / isRangeMode()Range selection
DatePickerwithMinDate(DateTimeImmutable) / withMaxDate(DateTimeImmutable) / withoutMinDate() / withoutMaxDate() / minDate() / maxDate() / inBounds() / withRange(?DateTimeImmutable, ?DateTimeImmutable)Min/max date constraints (clamped navigation, refused selection)
DatePickerwithoutToday() / withClockToday() / todayHidden()Hide the today marker outright, resume wall-clock following, read the state
DatePickerview(?int $width = null, ?bool $showWeekNumbers = null) / renderWidth(?int, ?bool)Render the month grid
DatePickerwithHeaderStyle() / withDayNameStyle() / withTodayStyle() / withSelectedStyle() / withSelectedTodayStyle() / withCursorStyle() / withRangeStyle()Styling (SGR strings)
DatePickermoveToDate(DateTimeImmutable) / dateAtCursor() / cursorIndex() / viewMonth() / viewYear()Aim and read the cursor
Modelstatic new(?DateTimeImmutable, ?EventStoreInterface) / withPicker(callable|DatePicker) / update($msg) / view() / picker()sugar-core Model wrapping the picker; the argless view() contract render honors the picker's withWidth()/withShowWeekNumbers() state — picker()->view($width, $showWeekNumbers) overrides per call
DatePickerhitTest(int $col, int $row, ?bool $showWeekNumbers = null)Mouse seam: character coordinate of a rendered view to the date under it, or null (blanks, chrome, padding) — never throws
DateRangepublic readonly $start / $end / withStart() / withEnd() / contains() / durationInDays(?$now) / isComplete()Immutable start/end value object behind range mode
EventStore__construct(?\Closure $clock = null) / record($type, $payload) / release() / hasEvents() / count()Bounded transition ring (MAX_EVENTS 1000); optional clock seam for deterministic tests
EventStoreInterfacerecord() / release() / hasEvents() / count()The contract Model consumes
Navigationstatic gridIndexToDate(int $gridIndex, int $month, int $year)Raw grid index → date; throws when month is outside 1–12 or year is below 1

Demos.

VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.

May to June 2026

May → June 2026

Month-grid date picker with cursor and selected day; the recording walks all four sections of examples/basic.php (May and June views, a July selection, a direct-API December cursor move).
Min / max constraints

Min / max constraints

Same picker bounded between two dates.