jmkcoder
Calendar & Time Controller
A flexible calendar and time picker API supporting both calendar and time selection integrations for any JavaScript framework or library.
Latest Release (v0.2.3): Added comprehensive Time Controller with full time picker functionality alongside the existing Calendar Controller.
Features
Calendar Controller
- Multiple view modes (day, month, and year views)
- Date selection (single date and date range)
- Year range navigation for efficient date picking
- Disabled weekdays - Disable specific days of the week across all calendar views
- Date constraints (min/max dates, disabled specific dates)
- Internationalization support with locale-specific date formats
- Flexible configuration options
- Service-oriented architecture
- Framework agnostic
Time Controller ✨ NEW
- Time selection (single time and time range)
- 12/24 hour format support
- Precision control (hours, minutes, seconds, milliseconds)
- Time navigation with keyboard support
- Time constraints and validation
- Accessibility features with focus management
- Locale-aware time formatting
- Reactive state bindings
- Complete service-oriented architecture
Usage
Calendar Controller
import { CalendarController } from '@uplink-protocol/calendar-controller';
// Create a new calendar controller
const calendar = CalendarController({
firstDayOfWeek: 1, // Monday
dateFormat: 'MM/DD/YYYY',
initialSelectedDate: new Date(),
disabledDaysOfWeek: [0, 6] // Disable weekends
});
// Use the calendar API for date selection
calendar.methods.selectDate(2025, 4, 15);
// Work with different view modes
const days = calendar.bindings.calendarDays.get(); // Day view
const months = calendar.bindings.calendarMonths.get(); // Month view
const years = calendar.bindings.calendarYears.get(); // Year view
// Navigate between view modes
calendar.methods.selectMonth(3, 2025); // Select April 2025 in month view
calendar.methods.selectYear(2026); // Select 2026 in year view
// Navigate year ranges
calendar.methods.nextYearRange(); // Move to next decade
calendar.methods.prevYearRange(); // Move to previous decade
// Manage disabled weekdays dynamically
calendar.methods.setDisabledDaysOfWeek([0, 6]); // Disable weekends
calendar.methods.addDisabledDayOfWeek(1); // Also disable Monday
calendar.methods.removeDisabledDayOfWeek(0); // Re-enable SundayTime Controller ✨ NEW
import { TimeController } from '@uplink-protocol/calendar-controller';
// Create a new time controller
const timeController = TimeController({
use12HourFormat: true,
showSeconds: true,
locale: 'en-US',
minuteStep: 15
});
// Select a time
timeController.selectTime(9, 30, 0); // 9:30:00 AM
// Get reactive bindings
const selectedTime = timeController.bindings.selectedTime.get();
const formattedTime = timeController.methods.getFormattedTime();
// Navigate time
timeController.goToNextHour();
timeController.goToPreviousMinute();
// Time range selection
timeController.setRangeSelectionMode(true);
timeController.selectTime(9, 0); // Start time
timeController.selectTime(17, 30); // End time
// Time constraints
timeController.setMinTime(new Date(2024, 0, 1, 9, 0)); // 9:00 AM
timeController.setMaxTime(new Date(2024, 0, 1, 17, 0)); // 5:00 PM
timeController.setDisabledHours([12, 13]); // Lunch break
const disabledDays = calendar.methods.getDisabledDaysOfWeek(); // Get current disabled daysDisabled Weekdays
Disable specific days of the week across all calendar views:
// Disable weekends for business applications
const businessCalendar = CalendarController({
disabledDaysOfWeek: [0, 6] // 0 = Sunday, 6 = Saturday
});
// Disable specific business days
const customSchedule = CalendarController({
disabledDaysOfWeek: [1, 3] // Monday and Wednesday
});
// Dynamic management
businessCalendar.methods.setDisabledDaysOfWeek([0, 5, 6]); // Weekends + Friday
businessCalendar.methods.addDisabledDayOfWeek(1); // Add Monday
businessCalendar.methods.removeDisabledDayOfWeek(5); // Remove FridayUI Integration
The examples provided showcase integration with:
- Tailwind CSS - For responsive, utility-first styling
- Font Awesome - For beautiful, scalable icons
Tailwind CSS Setup
<!-- Include Tailwind CSS -->
<script src="https://cdn.tailwindcss.com"></script>
<script>
tailwind.config = {
theme: {
extend: {
colors: {
primary: '#007bff',
'primary-light': '#e6f2ff'
}
}
}
}
</script>Font Awesome Setup
<!-- Include Font Awesome -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css">Architecture
This controller uses a service-oriented architecture where all the core functionality is delegated to specialized services:
- CalendarService - Handles basic calendar operations like getting month names
- DateSelectionService - Manages date selection logic
- DateValidationService - Validates dates against constraints
- DateFormattingService - Handles date formatting operations
- ViewStateService - Manages UI state and bindings
- EventManagerService - Manages event emission
- NavigationService - Handles calendar navigation operations
- ConstraintsService - Manages date constraints
- CalendarGeneratorService - Generates calendar days
- ConfigurationService - Manages calendar configuration options
Configuration Options
The following configuration options can be provided when creating a new calendar controller:
| Option | Type | Default | Description |
|---|---|---|---|
minDate |
Date | null | Minimum selectable date |
maxDate |
Date | null | Maximum selectable date |
disabledDates |
Date[] | [] | Array of specific dates to disable |
initialSelectedDate |
Date | null | Pre-selected date when calendar loads |
firstDayOfWeek |
number | 0 | First day of week (0 = Sunday, 1 = Monday, etc.) |
dateFormat |
string | null | Date format string (e.g., 'MM/DD/YYYY') |
hideOtherMonthDays |
boolean | false | When true, hides days from previous and next months in the current month view |
Example with hideOtherMonthDays
// Create a calendar that hides days from other months
const calendar = CalendarController({
firstDayOfWeek: 1,
dateFormat: 'MM/DD/YYYY',
hideOtherMonthDays: true // Only show days from the current month
});Internationalization
The calendar supports internationalization with the following features:
- Localized Month Names: Month names are displayed according to the selected locale
- Localized Weekday Names: Weekday names are displayed according to the selected locale
- Locale-based Date Formatting: Dates can be formatted according to the locale conventions
- RTL Support: Right-to-left languages are supported via the browser's localization
Configuration
// Internationalization options
const calendar = CalendarController({
// Set locale (any valid BCP 47 language tag)
locale: 'ja-JP', // Japanese
// Optional date format options (Intl.DateTimeFormat options)
dateFormatOptions: {
year: 'numeric',
month: 'long',
day: 'numeric',
weekday: 'short'
}
});Changing Locale Dynamically
// Change locale at runtime
calendar.methods.setLocale('ar-EG'); // Arabic (Egypt)
// Update date format options
calendar.methods.setDateFormatOptions({
year: 'numeric',
month: 'short',
day: '2-digit'
});Example
See the full example of internationalization usage in the i18n example.
Examples
The package includes comprehensive examples demonstrating various features and use cases:
- Basic Calendar - Simple calendar implementation
- Date Picker - Full-featured date picker with modern styling
- Disabled Weekdays - Business rules and weekday restrictions
- Internationalization - Multi-language support
- Multi-view Calendar - Day, month, and year views
- Comprehensive Demo - Advanced features showcase
Running Examples
All examples work directly in the browser without build tools:
# Clone the repository
git clone https://github.com/jmkcoder/uplink-protocol-calendar.git
cd uplink-protocol-calendar
# Open any example in your browser
# e.g., open examples/date-picker/index.htmlDocumentation
Comprehensive Guides
- Calendar Controller Usage Guide - Complete calendar implementation guide
- Time Controller Guide - Complete time picker implementation guide ✨ NEW
- Technical Architecture - Service-oriented architecture details
- TypeScript Usage - TypeScript integration guide
- Internationalization Guide - Multi-language support
- Features Guide - Advanced features and examples
API Reference
- API Documentation - Complete API reference with examples
- Calendar Controller API - Calendar controller methods
- Time Controller API - Time controller methods ✨ NEW
v0.2.3 Improvements
- Added comprehensive Time Controller with full time picker functionality
- Complete service-oriented architecture for time operations
- Full TypeScript support with comprehensive type definitions
- 24 comprehensive tests ensuring reliability
- Reactive bindings for real-time UI updates
- Accessibility features with focus management