@keenthemes/ktui 1.0.28 → 1.1.0

package/src/components/datepicker/utils/__tests__/date-utils-timezone.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect } from 'vitest';
+import {
+	formatDateToLocalString,
+	normalizeDateToLocalMidnight,
+	isSameLocalDay,
+	parseLocalDate
+} from '../date-utils';
+
+describe('Date Utils - Timezone Handling', () => {
+	describe('formatDateToLocalString', () => {
+		it('should format date as YYYY-MM-DD using local timezone', () => {
+			const date = new Date(2024, 0, 15, 14, 30, 45); // Jan 15, 2024 2:30:45 PM
+			const formatted = formatDateToLocalString(date);
+			expect(formatted).toBe('2024-01-15');
+		});
+
+		it('should use local timezone components, not UTC', () => {
+			// Create a date that would shift if converted to UTC
+			// In PST (UTC-8), Jan 15 11:00 PM becomes Jan 16 7:00 AM UTC
+			const date = new Date(2024, 0, 15, 23, 0, 0); // Jan 15, 2024 11:00 PM local
+			const formatted = formatDateToLocalString(date);
+			// Should still be Jan 15 in local timezone, not shifted to Jan 16
+			expect(formatted).toBe('2024-01-15');
+		});
+
+		it('should pad single-digit months and days with zeros', () => {
+			const date = new Date(2024, 0, 5); // Jan 5, 2024
+			const formatted = formatDateToLocalString(date);
+			expect(formatted).toBe('2024-01-05');
+		});
+
+		it('should handle year boundaries correctly', () => {
+			const date1 = new Date(2023, 11, 31); // Dec 31, 2023
+			const date2 = new Date(2024, 0, 1); // Jan 1, 2024
+			expect(formatDateToLocalString(date1)).toBe('2023-12-31');
+			expect(formatDateToLocalString(date2)).toBe('2024-01-01');
+		});
+
+		it('should handle leap years correctly', () => {
+			const date = new Date(2024, 1, 29); // Feb 29, 2024 (leap year)
+			const formatted = formatDateToLocalString(date);
+			expect(formatted).toBe('2024-02-29');
+		});
+	});
+
+	describe('normalizeDateToLocalMidnight', () => {
+		it('should set time to local midnight (00:00:00)', () => {
+			const date = new Date(2024, 0, 15, 14, 30, 45, 123);
+			const normalized = normalizeDateToLocalMidnight(date);
+			expect(normalized.getHours()).toBe(0);
+			expect(normalized.getMinutes()).toBe(0);
+			expect(normalized.getSeconds()).toBe(0);
+			expect(normalized.getMilliseconds()).toBe(0);
+		});
+
+		it('should preserve date components (year, month, day)', () => {
+			const date = new Date(2024, 0, 15, 14, 30, 45);
+			const normalized = normalizeDateToLocalMidnight(date);
+			expect(normalized.getFullYear()).toBe(2024);
+			expect(normalized.getMonth()).toBe(0);
+			expect(normalized.getDate()).toBe(15);
+		});
+
+		it('should return a new Date object, not modify the original', () => {
+			const date = new Date(2024, 0, 15, 14, 30, 45);
+			const normalized = normalizeDateToLocalMidnight(date);
+			expect(normalized).not.toBe(date);
+			expect(date.getHours()).toBe(14); // Original unchanged
+			expect(normalized.getHours()).toBe(0); // New one normalized
+		});
+
+		it('should handle dates already at midnight', () => {
+			const date = new Date(2024, 0, 15, 0, 0, 0, 0);
+			const normalized = normalizeDateToLocalMidnight(date);
+			expect(normalized.getHours()).toBe(0);
+			expect(normalized.getDate()).toBe(15);
+		});
+	});
+
+	describe('isSameLocalDay', () => {
+		it('should return true for dates on the same calendar day', () => {
+			const date1 = new Date(2024, 0, 15, 10, 0, 0);
+			const date2 = new Date(2024, 0, 15, 20, 0, 0);
+			expect(isSameLocalDay(date1, date2)).toBe(true);
+		});
+
+		it('should return false for dates on different days', () => {
+			const date1 = new Date(2024, 0, 15, 10, 0, 0);
+			const date2 = new Date(2024, 0, 16, 10, 0, 0);
+			expect(isSameLocalDay(date1, date2)).toBe(false);
+		});
+
+		it('should return false for dates in different months', () => {
+			const date1 = new Date(2024, 0, 15, 10, 0, 0);
+			const date2 = new Date(2024, 1, 15, 10, 0, 0);
+			expect(isSameLocalDay(date1, date2)).toBe(false);
+		});
+
+		it('should return false for dates in different years', () => {
+			const date1 = new Date(2024, 0, 15, 10, 0, 0);
+			const date2 = new Date(2025, 0, 15, 10, 0, 0);
+			expect(isSameLocalDay(date1, date2)).toBe(false);
+		});
+
+		it('should ignore time components when comparing', () => {
+			const date1 = new Date(2024, 0, 15, 0, 0, 0, 0);
+			const date2 = new Date(2024, 0, 15, 23, 59, 59, 999);
+			expect(isSameLocalDay(date1, date2)).toBe(true);
+		});
+
+		it('should use local timezone for comparison', () => {
+			// Create dates that might differ in UTC but are same in local timezone
+			const date1 = new Date(2024, 0, 15, 23, 0, 0); // Jan 15 11 PM local
+			const date2 = new Date(2024, 0, 15, 0, 0, 0); // Jan 15 midnight local
+			expect(isSameLocalDay(date1, date2)).toBe(true);
+		});
+	});
+
+	describe('parseLocalDate', () => {
+		it('should parse YYYY-MM-DD string to local date at midnight', () => {
+			const parsed = parseLocalDate('2024-01-15');
+			expect(parsed.getFullYear()).toBe(2024);
+			expect(parsed.getMonth()).toBe(0); // January is 0
+			expect(parsed.getDate()).toBe(15);
+			expect(parsed.getHours()).toBe(0);
+			expect(parsed.getMinutes()).toBe(0);
+			expect(parsed.getSeconds()).toBe(0);
+		});
+
+		it('should create date in local timezone, not UTC', () => {
+			const parsed = parseLocalDate('2024-01-15');
+			// The date should represent Jan 15 at local midnight
+			// Not Jan 15 at UTC midnight (which could be different day in some timezones)
+			expect(parsed.getDate()).toBe(15);
+			expect(parsed.getMonth()).toBe(0);
+		});
+
+		it('should handle single-digit months and days', () => {
+			const parsed = parseLocalDate('2024-01-05');
+			expect(parsed.getMonth()).toBe(0);
+			expect(parsed.getDate()).toBe(5);
+		});
+
+		it('should handle year boundaries', () => {
+			const date1 = parseLocalDate('2023-12-31');
+			const date2 = parseLocalDate('2024-01-01');
+			expect(date1.getFullYear()).toBe(2023);
+			expect(date1.getMonth()).toBe(11);
+			expect(date1.getDate()).toBe(31);
+			expect(date2.getFullYear()).toBe(2024);
+			expect(date2.getMonth()).toBe(0);
+			expect(date2.getDate()).toBe(1);
+		});
+
+		it('should handle leap years', () => {
+			const parsed = parseLocalDate('2024-02-29');
+			expect(parsed.getFullYear()).toBe(2024);
+			expect(parsed.getMonth()).toBe(1);
+			expect(parsed.getDate()).toBe(29);
+		});
+
+		it('should round-trip correctly with formatDateToLocalString', () => {
+			const originalDate = new Date(2024, 0, 15, 14, 30, 45);
+			const formatted = formatDateToLocalString(originalDate);
+			const parsed = parseLocalDate(formatted);
+			expect(parsed.getFullYear()).toBe(originalDate.getFullYear());
+			expect(parsed.getMonth()).toBe(originalDate.getMonth());
+			expect(parsed.getDate()).toBe(originalDate.getDate());
+		});
+	});
+
+	describe('Timezone Consistency', () => {
+		it('should maintain date consistency across format and parse operations', () => {
+			const testDates = [
+				new Date(2024, 0, 1), // Jan 1
+				new Date(2024, 5, 15), // Jun 15
+				new Date(2024, 11, 31), // Dec 31
+				new Date(2024, 1, 29), // Feb 29 (leap year)
+			];
+
+			testDates.forEach(date => {
+				const formatted = formatDateToLocalString(date);
+				const parsed = parseLocalDate(formatted);
+				expect(parsed.getFullYear()).toBe(date.getFullYear());
+				expect(parsed.getMonth()).toBe(date.getMonth());
+				expect(parsed.getDate()).toBe(date.getDate());
+			});
+		});
+
+		it('should prevent date shifts from UTC conversion', () => {
+			// Create a date late in the day that could shift when converted to UTC
+			const lateEvening = new Date(2024, 0, 15, 23, 30, 0);
+			const formatted = formatDateToLocalString(lateEvening);
+
+			// Should remain Jan 15, not shift to Jan 16
+			expect(formatted).toBe('2024-01-15');
+
+			// Parse it back and verify it's still the same day
+			const parsed = parseLocalDate(formatted);
+			expect(parsed.getDate()).toBe(15);
+			expect(parsed.getMonth()).toBe(0);
+		});
+
+		it('should handle dates at midnight correctly', () => {
+			const midnight = new Date(2024, 0, 15, 0, 0, 0, 0);
+			const formatted = formatDateToLocalString(midnight);
+			expect(formatted).toBe('2024-01-15');
+
+			const parsed = parseLocalDate(formatted);
+			expect(parsed.getDate()).toBe(15);
+			expect(parsed.getHours()).toBe(0);
+		});
+	});
+});
+

package/src/components/datepicker/utils/date-formatters.ts

@@ -0,0 +1,85 @@
+/*
+ * date-formatters.ts - Date formatting and comparison utilities for KTDatepicker
+ * Provides pure utility functions for date formatting, comparison, and normalization.
+ */
+
+/**
+ * Formats a Date object according to the provided format string.
+ *
+ * Supported tokens:
+ *   yyyy - 4-digit year
+ *   yy   - 2-digit year
+ *   MM   - 2-digit month (01-12)
+ *   M    - 1/2-digit month (1-12)
+ *   dd   - 2-digit day (01-31)
+ *   d    - 1/2-digit day (1-31)
+ *   HH   - 2-digit hour (00-23)
+ *   H    - 1/2-digit hour (0-23)
+ *   mm   - 2-digit minute (00-59)
+ *   m    - 1/2-digit minute (0-59)
+ *   ss   - 2-digit second (00-59)
+ *   s    - 1/2-digit second (0-59)
+ *   a    - AM/PM indicator
+ *
+ * @param date Date object to format
+ * @param format Format string with tokens
+ * @returns Formatted date string, or empty string if date is invalid
+ *
+ * @example
+ * formatDate(new Date(2024, 0, 15), 'yyyy-MM-dd') // Returns "2024-01-15"
+ * formatDate(new Date(2024, 0, 15, 14, 30), 'HH:mm') // Returns "14:30"
+ */
+export function formatDate(date: Date, format: string): string {
+	if (!(date instanceof Date) || isNaN(date.getTime())) return '';
+	return format
+		.replace(/yyyy/g, date.getFullYear().toString())
+		.replace(/yy/g, date.getFullYear().toString().slice(-2))
+		.replace(/MM/g, String(date.getMonth() + 1).padStart(2, '0'))
+		.replace(/M(?![a-zA-Z])/g, String(date.getMonth() + 1))
+		.replace(/dd/g, String(date.getDate()).padStart(2, '0'))
+		.replace(/d(?![a-zA-Z])/g, String(date.getDate()))
+		.replace(/HH/g, String(date.getHours()).padStart(2, '0'))
+		.replace(/H(?![a-zA-Z])/g, String(date.getHours()))
+		.replace(/mm/g, String(date.getMinutes()).padStart(2, '0'))
+		.replace(/m(?![a-zA-Z])/g, String(date.getMinutes()))
+		.replace(/ss/g, String(date.getSeconds()).padStart(2, '0'))
+		.replace(/s(?![a-zA-Z])/g, String(date.getSeconds()))
+		.replace(/a/g, date.getHours() >= 12 ? 'PM' : 'AM');
+}
+
+/**
+ * Checks if two dates represent the same calendar day.
+ * Compares year, month, and day components, ignoring time.
+ *
+ * @param a First date to compare
+ * @param b Second date to compare
+ * @returns True if both dates represent the same day, false otherwise
+ *
+ * @example
+ * isSameDay(new Date(2024, 0, 15, 10, 30), new Date(2024, 0, 15, 14, 45)) // Returns true
+ * isSameDay(new Date(2024, 0, 15), new Date(2024, 0, 16)) // Returns false
+ */
+export function isSameDay(a: Date, b: Date): boolean {
+	return a.getFullYear() === b.getFullYear() &&
+		a.getMonth() === b.getMonth() &&
+		a.getDate() === b.getDate();
+}
+
+/**
+ * Normalizes a date to local midnight (00:00:00) in the local timezone.
+ * Useful for date-only comparisons where time components should be ignored.
+ *
+ * @param date Date object to normalize
+ * @returns New Date object set to local midnight (00:00:00)
+ *
+ * @example
+ * const date = new Date(2024, 0, 15, 14, 30, 45);
+ * const normalized = normalizeDateToMidnight(date);
+ * // normalized represents 2024-01-15 00:00:00 in local timezone
+ */
+export function normalizeDateToMidnight(date: Date): Date {
+	const normalized = new Date(date);
+	normalized.setHours(0, 0, 0, 0);
+	return normalized;
+}
+

package/src/components/datepicker/utils/date-utils.ts

@@ -0,0 +1,172 @@
+/*
+ * date-utils.ts - Shared date parsing/formatting utilities for KTDatepicker
+ * Exports parseDateFromFormat for use in datepicker and segmented input.
+ */
+
+/**
+ * Parses a date string according to a format string (supports yyyy, yy, MM, M, dd, d).
+ * @param str Date string
+ * @param format Format string
+ * @returns Date object or null if parsing fails
+ */
+export function parseDateFromFormat(str: string, format: string): Date | null {
+  if (!str || !format) return null;
+  // Supported tokens: yyyy, yy, MM, M, dd, d
+  const tokenRegex = /(yyyy|yy|MM|M|dd|d)/g;
+  const tokens: string[] = [];
+  let regexStr = '';
+  let lastIndex = 0;
+  let match;
+  while ((match = tokenRegex.exec(format)) !== null) {
+    // Add any literal text between tokens
+    if (match.index > lastIndex) {
+      regexStr += format.slice(lastIndex, match.index).replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+    }
+    tokens.push(match[0]);
+    switch (match[0]) {
+      case 'yyyy': regexStr += '(\\d{4})'; break;
+      case 'yy': regexStr += '(\\d{2})'; break;
+      case 'MM': regexStr += '(\\d{2})'; break;
+      case 'M': regexStr += '(\\d{1,2})'; break;
+      case 'dd': regexStr += '(\\d{2})'; break;
+      case 'd': regexStr += '(\\d{1,2})'; break;
+    }
+    lastIndex = match.index + match[0].length;
+  }
+  // Add any trailing literal text
+  if (lastIndex < format.length) {
+    regexStr += format.slice(lastIndex).replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+  }
+  const regex = new RegExp('^' + regexStr + '$');
+  const matchResult = regex.exec(str);
+  if (!matchResult) return null;
+  let year = 1970, month = 1, day = 1;
+  let matchIdx = 1;
+  for (const token of tokens) {
+    const val = matchResult[matchIdx++] || '';
+    switch (token) {
+      case 'yyyy': year = parseInt(val, 10); break;
+      case 'yy': year = 2000 + parseInt(val, 10); break;
+      case 'MM':
+      case 'M': month = parseInt(val, 10); break;
+      case 'dd':
+      case 'd': day = parseInt(val, 10); break;
+    }
+  }
+  return new Date(year, month - 1, day);
+}
+
+/**
+ * Extracts segment order from a format string for use in segmented input.
+ * @param format Format string (e.g., 'dd/MM/yyyy', 'yyyy-MM-dd')
+ * @returns Array of segment types in the order they appear in the format
+ */
+export function getSegmentOrderFromFormat(format: string): Array<'day' | 'month' | 'year'> {
+  if (!format) return ['month', 'day', 'year']; // Default fallback
+
+  const segments: Array<'day' | 'month' | 'year'> = [];
+  const tokenRegex = /(yyyy|yy|MM|M|dd|d)/g;
+  let match;
+
+  while ((match = tokenRegex.exec(format)) !== null) {
+    switch (match[0]) {
+      case 'yyyy':
+      case 'yy':
+        segments.push('year');
+        break;
+      case 'MM':
+      case 'M':
+        segments.push('month');
+        break;
+      case 'dd':
+      case 'd':
+        segments.push('day');
+        break;
+    }
+  }
+
+  // Remove duplicates while preserving order
+  const uniqueSegments = segments.filter((segment, index) => segments.indexOf(segment) === index);
+
+  // Ensure we have all required segments, add missing ones at the end
+  const requiredSegments: Array<'day' | 'month' | 'year'> = ['day', 'month', 'year'];
+  requiredSegments.forEach(segment => {
+    if (!uniqueSegments.includes(segment)) {
+      uniqueSegments.push(segment);
+    }
+  });
+
+  return uniqueSegments;
+}
+
+/**
+ * Formats a date to a local timezone string in YYYY-MM-DD format.
+ * Uses local timezone components to prevent date shifts from UTC conversion.
+ * @param date Date object to format
+ * @returns Date string in YYYY-MM-DD format using local timezone
+ */
+export function formatDateToLocalString(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Normalizes a date to local midnight (00:00:00) in the local timezone.
+ * Useful for date-only comparisons where time components should be ignored.
+ * @param date Date object to normalize
+ * @returns New Date object set to local midnight
+ */
+export function normalizeDateToLocalMidnight(date: Date): Date {
+  const normalized = new Date(date);
+  normalized.setHours(0, 0, 0, 0);
+  return normalized;
+}
+
+/**
+ * Checks if two dates represent the same calendar day in local timezone.
+ * Compares year, month, and day components, ignoring time.
+ * @param a First date
+ * @param b Second date
+ * @returns True if both dates represent the same day in local timezone
+ */
+export function isSameLocalDay(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate();
+}
+
+/**
+ * Parses a date string (YYYY-MM-DD format) into a Date object at local midnight.
+ * Creates a local timezone date to avoid timezone-related date shifts.
+ * @param dateStr Date string in YYYY-MM-DD format
+ * @returns Date object representing the date at local midnight
+ */
+export function parseLocalDate(dateStr: string): Date {
+  // Parse YYYY-MM-DD string and create local date at midnight
+  const [year, month, day] = dateStr.split('-').map(Number);
+  return new Date(year, month - 1, day, 0, 0, 0, 0);
+}
+
+/**
+ * Converts a date to a numeric key for O(1) date comparisons.
+ * Format: year * 10000 + month * 100 + day
+ * This enables efficient Set/Map lookups for date matching.
+ * @param date Date object to convert
+ * @returns Numeric key representing the date (e.g., 20241225 for Dec 25, 2024)
+ */
+export function getDateKey(date: Date): number {
+  return date.getFullYear() * 10000 + (date.getMonth() + 1) * 100 + date.getDate();
+}
+
+/**
+ * Checks if two dates have the same date key (same calendar day).
+ * Optimized version using numeric keys for O(1) comparison.
+ * @param a First date
+ * @param b Second date
+ * @returns True if both dates have the same date key
+ */
+export function isSameDayByKey(a: Date, b: Date): boolean {
+  return getDateKey(a) === getDateKey(b);
+}

package/src/components/datepicker/utils/index.ts

@@ -0,0 +1,8 @@
+/*
+ * utils/index.ts - Utility module exports
+ * Provides date and time utility functions for KTDatepicker
+ */
+
+export * from './date-utils';
+export * from './date-formatters';
+export * from './time-utils';

package/src/components/datepicker/utils/time-utils.ts

@@ -0,0 +1,221 @@
+/*
+ * time-utils.ts - Time utilities for KTDatepicker
+ * Provides time parsing, formatting, validation, and granularity handling.
+ * Follows HeroUI best practices for time picker functionality.
+ */
+
+import { TimeState } from '../config/types';
+
+/**
+ * Parse time string to TimeState object
+ * @param timeStr Time string in format 'HH:MM' or 'HH:MM:SS'
+ * @returns TimeState object or null if invalid
+ */
+export function parseTimeString(timeStr: string): TimeState | null {
+  if (!timeStr || typeof timeStr !== 'string') return null;
+
+  const timeRegex = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;
+  const match = timeStr.match(timeRegex);
+
+  if (!match) return null;
+
+  const hour = parseInt(match[1], 10);
+  const minute = parseInt(match[2], 10);
+  const second = match[3] ? parseInt(match[3], 10) : 0;
+
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59 || second < 0 || second > 59) {
+    return null;
+  }
+
+  return { hour, minute, second };
+}
+
+/**
+ * Format TimeState to string
+ * @param time TimeState object
+ * @param granularity Granularity level
+ * @param format Time format ('12h' or '24h')
+ * @returns Formatted time string
+ */
+export function formatTime(time: TimeState, granularity: 'second' | 'minute' | 'hour' = 'minute', format: '12h' | '24h' = '24h'): string {
+  if (!time) return '';
+
+  let { hour, minute, second } = time;
+  let ampm = '';
+
+  // Handle 12-hour format
+  if (format === '12h') {
+    ampm = hour >= 12 ? 'PM' : 'AM';
+    hour = hour % 12;
+    hour = hour === 0 ? 12 : hour;
+  }
+
+  // Format based on granularity
+  switch (granularity) {
+    case 'hour':
+      return format === '12h' ? `${hour} ${ampm}` : `${hour.toString().padStart(2, '0')}`;
+    case 'minute':
+      return format === '12h'
+        ? `${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')} ${ampm}`
+        : `${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}`;
+    case 'second':
+      return format === '12h'
+        ? `${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}:${second.toString().padStart(2, '0')} ${ampm}`
+        : `${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}:${second.toString().padStart(2, '0')}`;
+    default:
+      return format === '12h'
+        ? `${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')} ${ampm}`
+        : `${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}`;
+  }
+}
+
+/**
+ * Validate time against constraints
+ * @param time TimeState to validate
+ * @param minTime Minimum time constraint
+ * @param maxTime Maximum time constraint
+ * @returns Validation result
+ */
+export function validateTime(time: TimeState, minTime?: string, maxTime?: string): { isValid: boolean; error?: string } {
+  if (!time) {
+    return { isValid: false, error: 'Time is required' };
+  }
+
+  const { hour, minute, second } = time;
+
+  // Basic range validation
+  if (hour < 0 || hour > 23) {
+    return { isValid: false, error: 'Hour must be between 0 and 23' };
+  }
+  if (minute < 0 || minute > 59) {
+    return { isValid: false, error: 'Minute must be between 0 and 59' };
+  }
+  if (second < 0 || second > 59) {
+    return { isValid: false, error: 'Second must be between 0 and 59' };
+  }
+
+  // Min/Max time validation
+  if (minTime) {
+    const minTimeState = parseTimeString(minTime);
+    if (minTimeState && isTimeBefore(time, minTimeState)) {
+      return { isValid: false, error: `Time must be after ${minTime}` };
+    }
+  }
+
+  if (maxTime) {
+    const maxTimeState = parseTimeString(maxTime);
+    if (maxTimeState && isTimeAfter(time, maxTimeState)) {
+      return { isValid: false, error: `Time must be before ${maxTime}` };
+    }
+  }
+
+  return { isValid: true };
+}
+
+/**
+ * Check if time1 is before time2
+ * @param time1 First time
+ * @param time2 Second time
+ * @returns True if time1 is before time2
+ */
+export function isTimeBefore(time1: TimeState, time2: TimeState): boolean {
+  const totalSeconds1 = time1.hour * 3600 + time1.minute * 60 + time1.second;
+  const totalSeconds2 = time2.hour * 3600 + time2.minute * 60 + time2.second;
+  return totalSeconds1 < totalSeconds2;
+}
+
+/**
+ * Check if time1 is after time2
+ * @param time1 First time
+ * @param time2 Second time
+ * @returns True if time1 is after time2
+ */
+export function isTimeAfter(time1: TimeState, time2: TimeState): boolean {
+  const totalSeconds1 = time1.hour * 3600 + time1.minute * 60 + time1.second;
+  const totalSeconds2 = time2.hour * 3600 + time2.minute * 60 + time2.second;
+  return totalSeconds1 > totalSeconds2;
+}
+
+/**
+ * Get time segments based on granularity
+ * @param granularity Time granularity
+ * @returns Array of segment types
+ */
+export function getTimeSegments(granularity: 'second' | 'minute' | 'hour'): Array<'hour' | 'minute' | 'second' | 'ampm'> {
+  switch (granularity) {
+    case 'hour':
+      return ['hour'];
+    case 'minute':
+      return ['hour', 'minute'];
+    case 'second':
+      return ['hour', 'minute', 'second'];
+    default:
+      return ['hour', 'minute'];
+  }
+}
+
+/**
+ * Convert Date object to TimeState
+ * @param date Date object
+ * @returns TimeState object
+ */
+export function dateToTimeState(date: Date): TimeState {
+  return {
+    hour: date.getHours(),
+    minute: date.getMinutes(),
+    second: date.getSeconds()
+  };
+}
+
+/**
+ * Convert TimeState to Date object (using current date)
+ * @param time TimeState object
+ * @returns Date object with time applied
+ */
+export function timeStateToDate(time: TimeState): Date {
+  const date = new Date();
+  date.setHours(time.hour, time.minute, time.second, 0);
+  return date;
+}
+
+/**
+ * Apply time to existing date
+ * @param date Date object
+ * @param time TimeState object
+ * @returns New Date object with time applied
+ */
+export function applyTimeToDate(date: Date, time: TimeState): Date {
+  const newDate = new Date(date);
+  newDate.setHours(time.hour, time.minute, time.second, 0);
+  return newDate;
+}
+
+/**
+ * Get time step options based on granularity and step
+ * @param granularity Time granularity
+ * @param step Step increment in minutes
+ * @returns Array of available time values
+ */
+export function getTimeStepOptions(granularity: 'second' | 'minute' | 'hour', step: number = 1): number[] {
+  const options: number[] = [];
+
+  switch (granularity) {
+    case 'hour':
+      for (let i = 0; i < 24; i += Math.max(1, Math.floor(step / 60))) {
+        options.push(i);
+      }
+      break;
+    case 'minute':
+      for (let i = 0; i < 60; i += step) {
+        options.push(i);
+      }
+      break;
+    case 'second':
+      for (let i = 0; i < 60; i += Math.max(1, Math.floor(step * 60))) {
+        options.push(i);
+      }
+      break;
+  }
+
+  return options;
+}