sugarcraft/sugar-calendar

PHP port of EthanEFung/bubble-datepicker — interactive date picker component for terminal UIs. Supports month/year navigation, keyboard navigation, date selection with visual cursor, and customizable styling.

v0.2.0 2026-05-07 01:29 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Joe Huss

• date
• calendar
• datepicker
• bubble
• tui
• sugarcraft

README

SugarCalendar

PHP port of EthanEFung/bubble-datepicker — interactive date picker component for terminal UIs. Inspired by the jQuery Datepicker widget.

Features

• Month/year navigation — prev/next buttons, year select
• Keyboard navigation — arrow keys, Enter to select, Esc to close
• Date selection — select/clear a date, visual cursor
• Today highlight — show current date distinctly
• Selected date styling — clear visual indicator
• Pure renderer — outputs ANSI strings, no external TUI framework needed

Install

composer require sugarcraft/sugar-calendar

Quick Start

use SugarCraft\Calendar\Model;
use SugarCraft\Calendar\DatePicker;

$picker = DatePicker::new(new \DateTimeImmutable('2026-05-01'));
$picker = $picker->SelectDate();  // enter "select mode"

echo $picker->View();  // render calendar

Navigation

// Month navigation
$picker = $picker->GoToPreviousMonth();
$picker = $picker->GoToNextMonth();
$picker = $picker->GoToPreviousYear();
$picker = $picker->GoToNextYear();
$picker = $picker->GoToToday();

// Set arbitrary month
$picker = $picker->SetTime(new \DateTimeImmutable('2025-12-01'));

// Selection
$picker = $picker->SelectDate();   // confirm selection
$picker = $picker->ClearDate();    // clear selection

Keyboard Handling

Handle keyboard input by calling the appropriate move methods:

if ($key === 'left')  $picker = $picker->MoveCursorLeft();
if ($key === 'right') $picker = $picker->MoveCursorRight();
if ($key === 'up')    $picker = $picker->MoveCursorUp();
if ($key === 'down')  $picker = $picker->MoveCursorDown();
if ($key === 'enter') $picker = $picker->SelectDate();
if ($key === 'esc')   $picker = $picker->ClearDate();

License

MIT