Changelog

All notable changes to this project are documented here

🚀

Current Version

v4.0.2 - Released November 23, 2024

Version 4.0.2 - November 23, 2024

Fixed

Firefox Compatibility - Fixed 'TouchEvent is not defined' error in DragHandlers - changed from instanceof TouchEvent to 'touches' in event check

Added

Exported Grouped Option Types - Added exports for TimepickerOptions, ClockOptions, UIOptions, LabelsOptions, BehaviorOptions, CallbacksOptions to support type-safe option composition
onUpdate Event Emissions - Added missing onUpdate event emissions in EventManager and ClockManager for real-time value synchronization

Firefox Fix Details

// Before (causing error on Firefox)
if (event instanceof TouchEvent) { // ❌ TouchEvent not defined
  const touch = event.touches[0];
}

// After (cross-browser compatible)
if ('touches' in event) { // ✅ Works everywhere
  const touch = event.touches[0];
}

Version 4.0.1 - November 21, 2024

Fixed

TypeScript Callback Types - All callback functions now have proper generic types instead of unknown
Type-safe Event Payloads - onConfirm, onOpen, onUpdate, and other callbacks now correctly infer event data types
Improved IntelliSense - Full autocomplete for event data properties without requiring manual type annotations

Before (4.0.0)

// Callbacks had unknown types
callbacks: {
  onConfirm: (data) => {
    // data: unknown - no autocomplete ❌
    console.log(data.hour); // TypeScript error
  }
}

After (4.0.1)

// Callbacks are now properly typed
callbacks: {
  onConfirm: (data) => {
    // data: ConfirmEventData - full autocomplete ✅
    console.log(data.hour); // string | undefined
    console.log(data.minutes); // string | undefined
    console.log(data.type); // string | undefined
  }
}

Version 4.0.0 - November 21, 2024

⚠️ BREAKING CHANGES - Migration Required

All CSS class names and CSS variable names have been renamed:

// CSS Class Names (ALL classes changed)
- .timepicker-ui-*
+ .tp-ui-*

Examples:
- .timepicker-ui-wrapper       → .tp-ui-wrapper
- .timepicker-ui-modal         → .tp-ui-modal
- .timepicker-ui-clock-face    → .tp-ui-clock-face
- .timepicker-ui-hour          → .tp-ui-hour
- .timepicker-ui-minutes       → .tp-ui-minutes
- .timepicker-ui-am            → .tp-ui-am
- .timepicker-ui-pm            → .tp-ui-pm
- .timepicker-ui-ok-btn        → .tp-ui-ok-btn
- .timepicker-ui-cancel-btn    → .tp-ui-cancel-btn

// CSS Variables (ALL variables changed)
- --timepicker-*
+ --tp-*

Examples:
- --timepicker-bg              → --tp-bg
- --timepicker-primary         → --tp-primary
- --timepicker-text            → --tp-text
- --timepicker-surface         → --tp-surface
- --timepicker-border          → --tp-border
- --timepicker-shadow          → --tp-shadow
- --timepicker-border-radius   → --tp-border-radius
- --timepicker-font-family     → --tp-font-family

// Options Structure (GROUPED)
// v3.x (flat - DEPRECATED):
-{
-  clockType: '24h',
-  theme: 'dark',
-  animation: true,
-  amLabel: 'AM',
-  onConfirm: (data) => {}
-}

// v4.0.0 (grouped - NEW):
+{
+  clock: {
+    type: '24h'
+  },
+  ui: {
+    theme: 'dark',
+    animation: true
+  },
+  labels: {
+    am: 'AM'
+  },
+  callbacks: {
+    onConfirm: (data) => {}
+  }
+}

// Migration Steps:
1. Find & replace all CSS class names in your stylesheets
2. Find & replace all CSS variable names in your custom themes
3. Reorganize options into groups: clock, ui, labels, behavior, callbacks
4. Update clockType → clock.type, theme → ui.theme, onConfirm → callbacks.onConfirm
5. Test all customizations and themes thoroughly

Important: The NPM package name remains timepicker-ui. Only CSS classes and variables changed.

Changed (Breaking)

CSS Class Renaming - All .timepicker-ui-* classes renamed to .tp-ui-*
CSS Variable Renaming - All --timepicker-* variables renamed to --tp-*
Options Structure Reorganization - Options now grouped into: clock, ui, labels, behavior, callbacks
Legacy DOM Events Removed - timepicker:* custom events completely removed - use EventEmitter API or callbacks
setTheme() Method Removed - Programmatic theming removed - use CSS classes with CSS variables instead

Added

EventEmitter API with Callback Bridge - All 9 callback options automatically bridge to EventEmitter with on(), off(), once() methods
SSR-Safe Architecture - All modules can be imported in Node.js (Next.js, Nuxt, Remix, Astro compatible)
Composition-Based Architecture - Pure composition with CoreState, Managers, Lifecycle - no inheritance, fully testable
Auto-Focus Improvements - Modal auto-focuses on open, minutes auto-focus with autoSwitchToMinutes
TypeScript Enhancements - No any types, fully typed event payloads, grouped options types, stricter type safety

Changed

Architecture Refactored - Composition-only pattern - removed all extends, pure dependency injection
Bundle Size Reduced - 80 KB → 63.3 KB ESM (-20.9%)
Theme Count - 11 → 10 themes (removed theme-custom from production)
Event System Unified - Single source of truth - callbacks bridge to EventEmitter automatically
Options API Restructured - 40+ flat options → 5 logical groups

Removed

Legacy DOM Events - timepicker:open, timepicker:confirm, timepicker:cancel, etc. - use picker.on() instead
setTheme() Method - Programmatic theme setting removed - use CSS classes instead
theme-custom - Removed from production bundle - users create custom themes via CSS variables

Fixed

Focus Trap Auto-Focus - Modal wrapper auto-focuses on open (no Tab press needed)
Auto-Switch Focus - Minute input receives focus when autoSwitchToMinutes enabled
SSR Compatibility - No DOM globals during initialization - safe for server rendering
currentTime Parsing - Simplified time parsing for better reliability
Dynamic Updates - Fixed React useEffect patterns to prevent infinite loops

Benefits

Shorter class names - Reduced HTML size and improved readability
Smaller bundle - -20.9% bundle size reduction (80 KB → 63.3 KB)
Better DX - Cleaner API with grouped options and EventEmitter
SSR Compatible - Works seamlessly with Next.js, Nuxt, Remix, Astro
Type Safety - No any types, fully typed events and options

Version 3.2.0 - November 14, 2025

Added

Material Design 3 Ripple Effect - Interactive ripple animations on buttons and inputs
M3 Color System - Complete color token implementation with CSS variables
M2 Legacy Theme - Material Design 2 theme (theme: 'm2')
Mobile Clock Face Toggle - Expand/collapse clock face with smooth animations
Desktop to Mobile Switching - Dynamic view switching via enableSwitchIcon
Local SVG Icon Assets - Built-in keyboard.svg and schedule.svg icons
New ClockSystem Architecture - Three-layer Engine → Controller → Renderer with RAF batching

Changed

Theme Naming (Breaking) - Renamed 'm3' → 'm3-green'
Option Naming (Breaking) - Renamed 'switchToMinutesAfterSelectHour' → 'autoSwitchToMinutes'
ConfigManager Refactoring - Split into 4 modules (87% code reduction)
Code Quality - KISS/DRY optimization - longest method 225→18 lines (-92%)

Fixed

Clock face state bugs - Fixed mobile ↔ desktop switching issues
Animation performance - Removed will-change causing resize lag
Angle Jump Bug - Fixed Math.atan2() parameter order
Disabled minutes styling - Visual state now reflects configuration
24h positioning - Fixed inner/outer circle dimensions
24h click overlap - Reduced threshold and element size
ClockFace disappears early - Destroy after modal animation completes
Landscape layout - Fixed expansion direction and class system
Desktop init bug - Removed incorrect .mobile class
autoSwitchToMinutes regression - Fixed feature after ClockSystem refactor

Performance

60fps transitions - Multi-phase RAF scheduling
ClockSystem gains - Rendering 15ms→3ms, Drag 8ms→2ms, -25% code size

Migration Guide

Breaking Changes:

// Theme rename
- theme: 'm3'
+ theme: 'm3-green'

// Option rename  
- switchToMinutesAfterSelectHour: true
+ autoSwitchToMinutes: true

Previous Versions

Version 3.1.2

Nov 7, 2025

• Fixed CSS variable issues with var(--timepicker-text)
• Resolved input color styling problems

Version 3.1.1

Nov 7, 2025

• Virtual DOM caching - 25% performance improvement
• RAF batching for smoother animations
• Input sanitization for XSS protection

Version 3.1.0

Nov 7, 2025

• EventEmitter API - on(), once(), off()
• Deprecated DOM events - migrate to EventEmitter

📖

Full Changelog

View the complete changelog with all versions on GitHub