SugarCalendar
Interactive date picker
Month-grid date picker with keyboard navigation, min/max date constraints, locale-aware day names, and a fully-rendered ANSI view.
Install
composer require sugarcraft/sugar-calendarQuickstart
use SugarCraft\Calendar\DatePicker;
// Opens on January 2026. The cursor starts on the first cell of the 6×7 grid
// (a blank before Thursday the 1st); every step returns a new picker.
$picker = DatePicker::new(new \DateTimeImmutable('2026-01-15'))
->handleKey(DatePicker::KEY_DOWN) // one week down: Sunday the 4th
->SelectDate();
$picker->SelectedDate()->format('Y-m-d'); // '2026-01-04'
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')]; // ['4', '6']What's in the box
Month gridA 6×7 month view with localised day and month names, 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 cell, Enter and Esc drive range mode.Range selection
withRangeMode(true): the first Enter sets the start, the second the end (swapped if needed), a third starts over; Esc clears.TEA model
Model wraps the picker as a candy-core Model with an optional event store.Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Port of EthanEFung/bubble-datepicker (Go upstream)
API
| Class | Method | Description |
|---|---|---|
| DatePicker | static new(?DateTimeImmutable) / withToday(DateTimeImmutable) / 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 | View(int $width = 21, bool $showWeekNumbers = false) | Render the month grid |
| DatePicker | WithHeaderStyle() / WithTodayStyle() / WithSelectedStyle() / WithCursorStyle() / WithRangeStyle() | Styling (SGR strings) |
| Model | static new(?DateTimeImmutable, ?EventStoreInterface) / picker() | candy-core Model wrapping the picker |
