@oneluiz/dual-datepicker 3.4.0 → 3.5.1

package/README.md

@@ -2,6 +2,9 @@
 
 A lightweight, zero-dependency date range picker for Angular 17+. Built with standalone components, Reactive Forms, and Angular Signals. No Angular Material required.
 
+> **🆕 NEW in v3.5.1**: [**Timezone-Safe Date Adapter**](docs/TIMEZONE_ADAPTER.md) - Fixes enterprise-critical timezone bugs in ERP, BI, POS, and invoicing systems 🛡️  
+> **🆕 NEW in v3.5.0**: [**Headless Architecture**](docs/HEADLESS.md) - Use date range state WITHOUT the UI component. Perfect for SSR, services, and global dashboard filters! 🎯
+
 [![npm version](https://img.shields.io/npm/v/@oneluiz/dual-datepicker)](https://www.npmjs.com/package/@oneluiz/dual-datepicker)
 [![npm provenance](https://img.shields.io/badge/provenance-available-brightgreen)](https://www.npmjs.com/package/@oneluiz/dual-datepicker)
 ![license](https://img.shields.io/npm/l/@oneluiz/dual-datepicker)
@@ -17,6 +20,54 @@ npm install @oneluiz/dual-datepicker
 
 ---
 
+## 🌟 What's New
+
+### Timezone-Safe Date Adapter (v3.5.1)
+
+**Fixed**: Enterprise timezone bugs that caused date ranges to shift by ±1 day.
+
+```typescript
+// ✅ No more timezone shift bugs!
+const store = inject(DualDateRangeStore);
+store.applyPreset('THIS_MONTH');
+const range = store.range(); // { start: "2024-03-01", end: "2024-03-31" }
+// Always correct, even across timezones and DST transitions
+
+// ✅ Optional: Use your preferred date library
+providers: [
+  { provide: DATE_ADAPTER, useClass: LuxonDateAdapter }
+]
+```
+
+**[📖 Read the Timezone Adapter Guide →](docs/TIMEZONE_ADAPTER.md)**
+
+### Headless Architecture (v3.5.0)
+
+Use date range logic **without the UI component**:
+
+```typescript
+// Inject the store anywhere - no UI needed!
+const rangeStore = inject(DualDateRangeStore);
+
+// Apply preset
+rangeStore.applyPreset('THIS_MONTH');
+
+// Use in API calls
+const range = rangeStore.range();
+http.get(`/api/sales?start=${range.start}&end=${range.end}`);
+```
+
+**Perfect for:**
+- 📊 Dashboard filters (control multiple charts)
+- 🏢 SSR applications
+- 🔄 Global state management
+- 🎯 Service-layer filtering
+- 📈 Analytics and BI tools
+
+**[📖 Read the Headless Architecture Guide →](docs/HEADLESS.md)**
+
+---
+
 ## 📋 Table of Contents
 
 - [Features](#-features)
@@ -26,6 +77,7 @@ npm install @oneluiz/dual-datepicker
   - [Basic Usage](#basic-usage)
   - [Reactive Forms](#with-reactive-forms)
   - [Angular Signals](#with-angular-signals)
+  - [Headless Usage](#headless-usage-new) ⭐ NEW
 - [Advanced Features](#-advanced-features)
   - [Multi-Range Selection](#multi-range-support)
   - [Disabled Dates](#disabled-dates)
@@ -169,6 +221,80 @@ dateRange = signal<DateRange | null>(null);
 </ngx-dual-datepicker>
 ```
 
+### Headless Usage (NEW) ⭐
+
+**Use date range state WITHOUT the UI component** - perfect for SSR, services, and global filters!
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { DualDateRangeStore } from '@oneluiz/dual-datepicker';
+import { HttpClient } from '@angular/common/http';
+
+@Component({
+  template: `
+    <div class="dashboard">
+      <button (click)="setPreset('TODAY')">Today</button>
+      <button (click)="setPreset('THIS_MONTH')">This Month</button>
+      <p>{{ rangeText() }}</p>
+    </div>
+  `
+})
+export class DashboardComponent {
+  private rangeStore = inject(DualDateRangeStore);
+  private http = inject(HttpClient);
+  
+  // Expose signals for template
+  rangeText = this.rangeStore.rangeText;
+  
+  setPreset(key: string) {
+    this.rangeStore.applyPreset(key);
+    
+    // Use in API call
+    const range = this.rangeStore.range();
+    this.http.get(`/api/sales`, { 
+      params: { start: range.start, end: range.end } 
+    }).subscribe(data => console.log(data));
+  }
+}
+```
+
+**Benefits:**
+- ✅ No UI component needed
+- ✅ SSR-compatible
+- ✅ Global state management
+- ✅ Perfect for services and guards
+- ✅ Testable and deterministic
+
+#### SSR-Safe Clock Injection
+
+Presets like "Last 7 Days" now use **clock injection** for SSR hydration consistency:
+
+```typescript
+// Server (SSR)
+import { DATE_CLOCK } from '@oneluiz/dual-datepicker';
+
+const requestTime = new Date();
+
+renderApplication(AppComponent, {
+  providers: [
+    { provide: DATE_CLOCK, useValue: { now: () => requestTime } }
+  ]
+});
+```
+
+```typescript
+// Client (Browser)
+bootstrapApplication(AppComponent, {
+  providers: [
+    { provide: DATE_CLOCK, useValue: { now: () => new Date(getServerTime()) } }
+  ]
+});
+```
+
+**Result**: Server and client resolve identical presets ✅ No hydration mismatch!
+
+**[📖 Full Headless Architecture Guide →](HEADLESS.md)** | **[💻 Code Examples →](HEADLESS_EXAMPLES.ts)** | **[🚀 SSR Clock Injection Guide →](SSR_CLOCK_INJECTION.md)**
+
 ---
 
 ## 🎯 Advanced Features
@@ -1998,6 +2124,12 @@ export class ExampleComponent {
 
 Recently shipped:
 
+**v3.4.0:**
+- ✅ **Time Picker** - Select precise datetime ranges with 12h/24h format
+- ✅ **Configurable Minute Steps** - Choose 1, 5, 15, or 30-minute intervals
+- ✅ **Default Times** - Set default start/end times
+- ✅ **Full Theme Support** - Works seamlessly with all built-in themes
+
 **v3.3.0:**
 - ✅ **Theming System** - Pre-built themes for Bootstrap, Bulma, Foundation, Tailwind CSS, and Custom
 - ✅ **CSS Variables Support** - 13 customizable variables for branding
@@ -2025,9 +2157,10 @@ Recently shipped:
 
 Planned features:
 
-- ⬜ **Time Picker** - Select date + time ranges
 - ⬜ **Mobile Optimizations** - Enhanced touch gestures and responsive layout
 - ⬜ **Range Shortcuts** - Quick selection buttons (Today, This Week, etc.)
+- ⬜ **Time Constraints** - Min/max time validation and business hours
+- ⬜ **Multi-range + Time Picker** - Combined support for multiple datetime ranges
 
 ## 📄 License
 

package/core/date-adapter.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Date Adapter Abstraction for Timezone-Safe Date Operations
+ *
+ * Problem:
+ * Using Date natively in calendar/range logic causes enterprise bugs:
+ * - Date ranges shift by 1 day due to timezone/DST
+ * - Server (UTC) vs Client (local timezone) discrepancies
+ * - Inconsistent reporting in BI/ERP/invoicing/hotel systems
+ *
+ * Solution:
+ * All date calculations go through an adapter layer.
+ * This allows:
+ * - Timezone-safe operations by default (NativeDateAdapter normalizes to day boundaries)
+ * - Optional integration with Luxon/DayJS/date-fns for advanced timezone handling
+ * - Consistent behavior across SSR and client
+ * - Migration path to timezone-aware libraries without breaking changes
+ *
+ * Architecture:
+ * ```
+ * DualDateRangeStore
+ *     ↓ uses
+ * DateAdapter ← Inject via DATE_ADAPTER token
+ *     ↓ implements
+ * NativeDateAdapter (default, zero deps)
+ * LuxonDateAdapter (optional, full timezone support)
+ * DayJSDateAdapter (optional, lightweight)
+ * ```
+ *
+ * Usage:
+ * ```typescript
+ * // Default (NativeDateAdapter)
+ * bootstrapApplication(AppComponent);
+ *
+ * // Advanced (Luxon with timezone)
+ * import { LuxonDateAdapter } from '@oneluiz/dual-datepicker/luxon';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     { provide: DATE_ADAPTER, useClass: LuxonDateAdapter }
+ *   ]
+ * });
+ * ```
+ */
+import { InjectionToken } from '@angular/core';
+/**
+ * Date adapter interface for all calendar/range operations
+ *
+ * All methods operate on "calendar day" level, ignoring time components.
+ * Implementations must ensure timezone-safe behavior.
+ *
+ * Implementations:
+ * - NativeDateAdapter: Default, zero dependencies, uses Date with normalization
+ * - LuxonDateAdapter: Optional, full timezone support with Luxon
+ * - DayJSDateAdapter: Optional, lightweight timezone support
+ * - Custom: Implement for your specific backend/timezone requirements
+ */
+export interface DateAdapter {
+    /**
+     * Normalize date to start of day (00:00:00.000)
+     *
+     * Critical for timezone-safe comparisons.
+     *
+     * Example:
+     * ```typescript
+     * const date = new Date('2026-02-21T15:30:00');
+     * const normalized = adapter.normalize(date);
+     * // → 2026-02-21T00:00:00.000 (in local timezone)
+     * ```
+     *
+     * @param date - Date to normalize
+     * @returns Date with time set to 00:00:00.000
+     */
+    normalize(date: Date): Date;
+    /**
+     * Check if two dates represent the same calendar day
+     *
+     * Ignores time component. Timezone-safe.
+     *
+     * Example:
+     * ```typescript
+     * const a = new Date('2026-02-21T23:59:59');
+     * const b = new Date('2026-02-21T00:00:01');
+     * adapter.isSameDay(a, b); // → true
+     * ```
+     */
+    isSameDay(a: Date, b: Date): boolean;
+    /**
+     * Check if date A is before date B (calendar day level)
+     *
+     * Example:
+     * ```typescript
+     * adapter.isBeforeDay(new Date('2026-02-20'), new Date('2026-02-21')); // → true
+     * adapter.isBeforeDay(new Date('2026-02-21'), new Date('2026-02-21')); // → false
+     * ```
+     */
+    isBeforeDay(a: Date, b: Date): boolean;
+    /**
+     * Check if date A is after date B (calendar day level)
+     *
+     * Example:
+     * ```typescript
+     * adapter.isAfterDay(new Date('2026-02-22'), new Date('2026-02-21')); // → true
+     * adapter.isAfterDay(new Date('2026-02-21'), new Date('2026-02-21')); // → false
+     * ```
+     */
+    isAfterDay(a: Date, b: Date): boolean;
+    /**
+     * Add days to a date
+     *
+     * Must handle DST transitions correctly.
+     *
+     * Example:
+     * ```typescript
+     * const date = new Date('2026-02-21');
+     * const future = adapter.addDays(date, 7);
+     * // → 2026-02-28
+     * ```
+     */
+    addDays(date: Date, days: number): Date;
+    /**
+     * Add months to a date
+     *
+     * Must handle month overflow (e.g., Jan 31 + 1 month → Feb 28).
+     *
+     * Example:
+     * ```typescript
+     * const date = new Date('2026-01-31');
+     * const next = adapter.addMonths(date, 1);
+     * // → 2026-02-28 (not March 3rd)
+     * ```
+     */
+    addMonths(date: Date, months: number): Date;
+    /**
+     * Get start of day (00:00:00.000)
+     *
+     * Similar to normalize() but explicit intent.
+     */
+    startOfDay(date: Date): Date;
+    /**
+     * Get end of day (23:59:59.999)
+     *
+     * Useful for range queries that need to include entire day.
+     *
+     * Example:
+     * ```typescript
+     * const date = new Date('2026-02-21');
+     * const end = adapter.endOfDay(date);
+     * // → 2026-02-21T23:59:59.999
+     * ```
+     */
+    endOfDay(date: Date): Date;
+    /**
+     * Get first day of month (00:00:00.000)
+     *
+     * Example:
+     * ```typescript
+     * const date = new Date('2026-02-21');
+     * const start = adapter.startOfMonth(date);
+     * // → 2026-02-01T00:00:00.000
+     * ```
+     */
+    startOfMonth(date: Date): Date;
+    /**
+     * Get last day of month (23:59:59.999)
+     *
+     * Example:
+     * ```typescript
+     * const date = new Date('2026-02-21');
+     * const end = adapter.endOfMonth(date);
+     * // → 2026-02-28T23:59:59.999
+     * ```
+     */
+    endOfMonth(date: Date): Date;
+    /**
+     * Get year (4-digit)
+     *
+     * Example:
+     * ```typescript
+     * adapter.getYear(new Date('2026-02-21')); // → 2026
+     * ```
+     */
+    getYear(date: Date): number;
+    /**
+     * Get month (0-11, where 0 = January)
+     *
+     * Example:
+     * ```typescript
+     * adapter.getMonth(new Date('2026-02-21')); // → 1 (February)
+     * ```
+     */
+    getMonth(date: Date): number;
+    /**
+     * Get day of month (1-31)
+     *
+     * Example:
+     * ```typescript
+     * adapter.getDate(new Date('2026-02-21')); // → 21
+     * ```
+     */
+    getDate(date: Date): number;
+    /**
+     * Get day of week (0-6, where 0 = Sunday)
+     *
+     * Example:
+     * ```typescript
+     * adapter.getDay(new Date('2026-02-21')); // → 6 (Saturday)
+     * ```
+     */
+    getDay(date: Date): number;
+    /**
+     * Convert Date to ISO date string (YYYY-MM-DD)
+     *
+     * CRITICAL: Must be timezone-safe!
+     * DO NOT use date.toISOString() as it converts to UTC.
+     *
+     * Example:
+     * ```typescript
+     * // Local timezone GMT-6 (CST)
+     * const date = new Date('2026-02-21T23:00:00'); // 11 PM CST
+     *
+     * // ❌ WRONG: date.toISOString().split('T')[0]
+     * // Returns "2026-02-22" (shifted to UTC!)
+     *
+     * // ✅ CORRECT: adapter.toISODate(date)
+     * // Returns "2026-02-21" (local date preserved)
+     * ```
+     *
+     * @param date - Date to format (or null)
+     * @returns ISO date string in YYYY-MM-DD format (local timezone), empty string if null
+     */
+    toISODate(date: Date | null): string;
+    /**
+     * Parse ISO date string (YYYY-MM-DD) to Date
+     *
+     * CRITICAL: Must be timezone-safe!
+     * DO NOT use new Date(isoString) as it may parse as UTC.
+     *
+     * Example:
+     * ```typescript
+     * // ❌ WRONG: new Date('2026-02-21')
+     * // May parse as UTC midnight, which is previous day in some timezones
+     *
+     * // ✅ CORRECT: adapter.parseISODate('2026-02-21')
+     * // Returns Date representing 2026-02-21 00:00:00 in local timezone
+     * ```
+     *
+     * @param isoDate - ISO date string (YYYY-MM-DD) or null
+     * @returns Date object or null if invalid
+     */
+    parseISODate(isoDate: string | null): Date | null;
+    /**
+     * Get week start day for locale
+     *
+     * 0 = Sunday, 1 = Monday, etc.
+     *
+     * Example:
+     * ```typescript
+     * adapter.getWeekStart('en-US'); // → 0 (Sunday)
+     * adapter.getWeekStart('en-GB'); // → 1 (Monday)
+     * ```
+     *
+     * @param locale - Locale string (e.g., 'en-US', 'es-ES')
+     * @returns Day number (0-6)
+     */
+    getWeekStart(locale?: string): 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}
+/**
+ * Injection token for DateAdapter
+ *
+ * Default: NativeDateAdapter (zero dependencies)
+ *
+ * Override for advanced timezone handling:
+ *
+ * ```typescript
+ * // Luxon with timezone
+ * import { LuxonDateAdapter } from '@oneluiz/dual-datepicker/luxon';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     {
+ *       provide: DATE_ADAPTER,
+ *       useClass: LuxonDateAdapter
+ *     }
+ *   ]
+ * });
+ * ```
+ *
+ * Custom implementation:
+ *
+ * ```typescript
+ * class CustomDateAdapter implements DateAdapter {
+ *   // Your implementation for backend-specific date handling
+ * }
+ *
+ * provide(DATE_ADAPTER, { useClass: CustomDateAdapter });
+ * ```
+ */
+export declare const DATE_ADAPTER: InjectionToken<DateAdapter>;

package/core/date-clock.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Date Clock Abstraction for SSR-Safe Date Resolution
+ *
+ * Problem:
+ * Presets like "Last 7 Days" or "This Month" use new Date() which causes:
+ * - SSR hydration mismatch
+ * - Server renders "2026-02-14", client renders "2026-02-15"
+ * - Different filters in dashboards
+ * - Different queries in ERP/BI
+ * - Cache inconsistency
+ *
+ * Solution:
+ * Inject a DateClock to control time deterministically:
+ *
+ * Server (SSR):
+ * provide(DATE_CLOCK, {
+ *   useValue: { now: () => new Date('2026-02-21T00:00:00Z') }
+ * })
+ *
+ * Client (Browser):
+ * Uses SystemClock by default (new Date())
+ *
+ * Testing:
+ * provide(DATE_CLOCK, {
+ *   useValue: { now: () => new Date('2026-01-15T10:30:00Z') }
+ * })
+ *
+ * Architecture:
+ * - PresetEngine receives DateClock via DI
+ * - All preset calculations use clock.now() instead of new Date()
+ * - Deterministic: Same clock.now() → Same preset result
+ * - SSR-compatible: Server and client resolve identical ranges
+ */
+import { InjectionToken } from '@angular/core';
+/**
+ * Clock abstraction for deterministic date resolution
+ *
+ * Use cases:
+ * - SSR: Ensure server and client generate identical presets
+ * - Testing: Control time for predictable test results
+ * - Replay: Reproduce exact user state from past sessions
+ * - Demo: Freeze time for reproducible demos
+ */
+export interface DateClock {
+    /**
+     * Get current date/time
+     *
+     * Default implementation returns new Date()
+     * Override for SSR, testing, or time-travel scenarios
+     */
+    now(): Date;
+}
+/**
+ * Injection token for DateClock
+ *
+ * Usage:
+ * ```typescript
+ * // Default (uses SystemClock)
+ * bootstrapApplication(AppComponent);
+ *
+ * // SSR Override
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     {
+ *       provide: DATE_CLOCK,
+ *       useValue: { now: () => new Date('2026-02-21T00:00:00Z') }
+ *     }
+ *   ]
+ * });
+ *
+ * // Testing Override
+ * TestBed.configureTestingModule({
+ *   providers: [
+ *     {
+ *       provide: DATE_CLOCK,
+ *       useValue: { now: () => new Date('2026-01-15T12:00:00Z') }
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export declare const DATE_CLOCK: InjectionToken<DateClock>;

package/core/dual-date-range.store.d.ts

@@ -0,0 +1,113 @@
+import * as i0 from "@angular/core";
+export interface DateRangeState {
+    start: string;
+    end: string;
+    startTime?: string;
+    endTime?: string;
+}
+export interface DateRangeConfig {
+    minDate?: Date;
+    maxDate?: Date;
+    disabledDates?: Date[] | ((date: Date) => boolean);
+    enableTimePicker?: boolean;
+    defaultStartTime?: string;
+    defaultEndTime?: string;
+}
+export declare class DualDateRangeStore {
+    private presetEngine;
+    private clock;
+    private adapter;
+    constructor();
+    private config;
+    private _startDate;
+    private _endDate;
+    private _leftMonth;
+    private _rightMonth;
+    private _selectingStart;
+    private _startTime;
+    private _endTime;
+    private _pendingStart;
+    private _pendingEnd;
+    private _hasPendingChanges;
+    readonly startDate: import("@angular/core").Signal<Date>;
+    readonly endDate: import("@angular/core").Signal<Date>;
+    readonly leftMonth: import("@angular/core").Signal<Date>;
+    readonly rightMonth: import("@angular/core").Signal<Date>;
+    readonly selectingStart: import("@angular/core").Signal<boolean>;
+    readonly startTime: import("@angular/core").Signal<string>;
+    readonly endTime: import("@angular/core").Signal<string>;
+    readonly hasPendingChanges: import("@angular/core").Signal<boolean>;
+    readonly range: import("@angular/core").Signal<DateRangeState>;
+    readonly isValid: import("@angular/core").Signal<boolean>;
+    readonly rangeText: import("@angular/core").Signal<string>;
+    /**
+     * Configure the store
+     */
+    configure(config: Partial<DateRangeConfig>): void;
+    /**
+     * Set start date (with validation)
+     */
+    setStart(date: Date | string | null): void;
+    /**
+     * Set end date (with validation)
+     */
+    setEnd(date: Date | string | null): void;
+    /**
+     * Set complete range at once
+     */
+    setRange(start: Date | string | null, end: Date | string | null): void;
+    /**
+     * Set pending selection (for requireApply mode)
+     */
+    setPendingStart(date: Date | string | null): void;
+    setPendingEnd(date: Date | string | null): void;
+    /**
+     * Apply pending changes
+     */
+    applyPending(): void;
+    /**
+     * Cancel pending changes
+     */
+    cancelPending(): void;
+    private clearPending;
+    /**
+     * Reset to empty state
+     */
+    reset(): void;
+    /**
+     * Apply a preset by key
+     *
+     * SSR-Safe: Uses injected DateClock for deterministic resolution
+     *
+     * @param presetKey - Preset identifier (e.g., 'TODAY', 'LAST_7_DAYS')
+     * @param now - Optional date override (defaults to clock.now())
+     */
+    applyPreset(presetKey: string, now?: Date): void;
+    /**
+     * Navigate left calendar month
+     */
+    setLeftMonth(date: Date): void;
+    /**
+     * Navigate right calendar month
+     */
+    setRightMonth(date: Date): void;
+    /**
+     * Set time values
+     */
+    setStartTime(time: string): void;
+    setEndTime(time: string): void;
+    /**
+     * Get current state as snapshot
+     */
+    getSnapshot(): DateRangeState;
+    /**
+     * Load state from snapshot
+     */
+    loadSnapshot(snapshot: DateRangeState): void;
+    private parseDate;
+    private getNextMonth;
+    private getPreviousMonth;
+    private formatDateShort;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DualDateRangeStore, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DualDateRangeStore>;
+}

package/core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Core headless date range logic
+ * Import from here for clean barrel exports
+ */
+export * from './dual-date-range.store';
+export * from './preset.engine';
+export * from './range.validator';
+export * from './date-clock';
+export * from './system-clock';
+export * from './date-adapter';
+export * from './native-date-adapter';