SugarDatepicker
Interactive month-grid date picker
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 nav
handleKey() 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 selection
withRangeMode(true): the first Enter sets the start, the second the end (swapped if needed), a third starts over; Esc clears.Date bounds
withMinDate()/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 model
Model 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
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by EthanEFung/bubble-datepicker (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| DatePicker | static new(?DateTimeImmutable) / withToday(DateTimeImmutable) / withClockToday() / setTime(DateTimeImmutable) | Create a picker on a month; pin "today"; jump to a date |
| DatePicker | goToPreviousMonth() / goToNextMonth() / goToPreviousYear() / goToNextYear() / goToToday() | Navigate the viewed month |
| DatePicker | moveCursorLeft/Right/Up/Down() / handleKey(string $key) | Move the cursor |
| DatePicker | selectDate() / clearDate() / toggleSelection() / selectedDate() / isSelecting() | Single-date selection |
| DatePicker | withRangeMode(bool) / rangeStart() / rangeEnd() / isRangeMode() | Range selection |
| DatePicker | withMinDate(DateTimeImmutable) / withMaxDate(DateTimeImmutable) / withoutMinDate() / withoutMaxDate() / minDate() / maxDate() / inBounds() / withRange(?DateTimeImmutable, ?DateTimeImmutable) | Min/max date constraints (clamped navigation, refused selection) |
| DatePicker | withoutToday() / withClockToday() / todayHidden() | Hide the today marker outright, resume wall-clock following, read the state |
| DatePicker | view(?int $width = null, ?bool $showWeekNumbers = null) / renderWidth(?int, ?bool) | Render the month grid |
| DatePicker | withHeaderStyle() / withDayNameStyle() / withTodayStyle() / withSelectedStyle() / withSelectedTodayStyle() / withCursorStyle() / withRangeStyle() | Styling (SGR strings) |
| DatePicker | moveToDate(DateTimeImmutable) / dateAtCursor() / cursorIndex() / viewMonth() / viewYear() | Aim and read the cursor |
| Model | static 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 |
| DatePicker | hitTest(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 |
| DateRange | public 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 |
| EventStoreInterface | record() / release() / hasEvents() / count() | The contract Model consumes |
| Navigation | static 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 → 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).