@oneluiz/dual-datepicker 3.5.0 → 3.5.1

package/README.md

@@ -2,7 +2,8 @@
 
 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.0**: [**Headless Architecture**](HEADLESS.md) - Use date range state WITHOUT the UI component. Perfect for SSR, services, and global dashboard filters! 🎯
+> **🆕 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)
@@ -21,6 +22,25 @@ 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**:
@@ -44,7 +64,7 @@ http.get(`/api/sales?start=${range.start}&end=${range.end}`);
 - 🎯 Service-layer filtering
 - 📈 Analytics and BI tools
 
-**[📖 Read the Headless Architecture Guide →](HEADLESS.md)**
+**[📖 Read the Headless Architecture Guide →](docs/HEADLESS.md)**
 
 ---
 
@@ -245,7 +265,35 @@ export class DashboardComponent {
 - ✅ Perfect for services and guards
 - ✅ Testable and deterministic
 
-**[📖 Full Headless Architecture Guide →](HEADLESS.md)** | **[💻 Code Examples →](HEADLESS_EXAMPLES.ts)**
+#### 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)**
 
 ---
 

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

@@ -14,6 +14,10 @@ export interface DateRangeConfig {
     defaultEndTime?: string;
 }
 export declare class DualDateRangeStore {
+    private presetEngine;
+    private clock;
+    private adapter;
+    constructor();
     private config;
     private _startDate;
     private _endDate;
@@ -72,6 +76,11 @@ export declare class DualDateRangeStore {
     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;
     /**

package/core/index.d.ts

@@ -5,3 +5,7 @@
 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';

package/core/native-date-adapter.d.ts

@@ -0,0 +1,152 @@
+import { DateAdapter } from './date-adapter';
+import * as i0 from "@angular/core";
+export declare class NativeDateAdapter implements DateAdapter {
+    /**
+     * Normalize date to start of day (00:00:00.000) in local timezone
+     *
+     * This is the foundation of timezone-safe operations.
+     * All other methods use normalized dates for comparisons.
+     */
+    normalize(date: Date): Date;
+    /**
+     * Check if two dates are the same calendar day
+     *
+     * Implementation: Compare YYYY-MM-DD components directly
+     * Avoids timezone issues from valueOf() comparisons
+     */
+    isSameDay(a: Date, b: Date): boolean;
+    /**
+     * Check if date A is before date B (calendar day level)
+     *
+     * Implementation: Compare normalized dates using valueOf()
+     */
+    isBeforeDay(a: Date, b: Date): boolean;
+    /**
+     * Check if date A is after date B (calendar day level)
+     *
+     * Implementation: Compare normalized dates using valueOf()
+     */
+    isAfterDay(a: Date, b: Date): boolean;
+    /**
+     * Add days to a date
+     *
+     * Implementation: Use setDate() which handles month rollover automatically
+     *
+     * Example:
+     * Jan 31 + 3 days → Feb 3 ✅
+     * Feb 28 + 1 day → Mar 1 ✅ (non-leap year)
+     */
+    addDays(date: Date, days: number): Date;
+    /**
+     * Add months to a date
+     *
+     * CRITICAL: Handles month overflow correctly
+     *
+     * Algorithm:
+     * 1. Add months using setMonth()
+     * 2. If day-of-month changed (overflow), set to last day of target month
+     *
+     * Examples:
+     * - Jan 31 + 1 month → Feb 28 (or Feb 29 in leap year) ✅
+     * - Jan 31 + 2 months → Mar 31 ✅
+     * - Mar 31 + 1 month → Apr 30 ✅
+     * - Dec 31 + 1 month → Jan 31 (next year) ✅
+     */
+    addMonths(date: Date, months: number): Date;
+    /**
+     * Get start of day (00:00:00.000)
+     *
+     * Alias for normalize() with explicit intent
+     */
+    startOfDay(date: Date): Date;
+    /**
+     * Get end of day (23:59:59.999)
+     *
+     * Useful for inclusive range queries
+     */
+    endOfDay(date: Date): Date;
+    /**
+     * Get first day of month (00:00:00.000)
+     */
+    startOfMonth(date: Date): Date;
+    /**
+     * Get last day of month (23:59:59.999)
+     *
+     * Algorithm: Go to 1st of next month, subtract 1 day
+     */
+    endOfMonth(date: Date): Date;
+    /**
+     * Get year (4-digit)
+     */
+    getYear(date: Date): number;
+    /**
+     * Get month (0-11)
+     */
+    getMonth(date: Date): number;
+    /**
+     * Get day of month (1-31)
+     */
+    getDate(date: Date): number;
+    /**
+     * Get day of week (0-6, Sunday=0)
+     */
+    getDay(date: Date): number;
+    /**
+     * Convert Date to ISO date string (YYYY-MM-DD)
+     *
+     * CRITICAL: DO NOT use toISOString() - it converts to UTC!
+     *
+     * Manual construction ensures local timezone is preserved:
+     *
+     * Example problem with toISOString():
+     * ```
+     * // Local timezone: GMT-6 (CST)
+     * const date = new Date('2026-02-21T23:00:00'); // 11 PM Feb 21 local
+     *
+     * // WRONG ❌
+     * date.toISOString().split('T')[0]
+     * // Returns "2026-02-22" (converted to UTC = Feb 22 05:00 AM)
+     *
+     * // CORRECT ✅
+     * toISODate(date)
+     * // Returns "2026-02-21" (local date preserved)
+     * ```
+     *
+     * Implementation: Build YYYY-MM-DD manually from local date components
+     */
+    toISODate(date: Date): string;
+    /**
+     * Parse ISO date string (YYYY-MM-DD) to Date
+     *
+     * CRITICAL: DO NOT use new Date(isoString) - may parse as UTC!
+     *
+     * Example problem with Date constructor:
+     * ```
+     * // Local timezone: GMT-6 (CST)
+     *
+     * // WRONG ❌
+     * new Date('2026-02-21')
+     * // Parsed as UTC: 2026-02-21T00:00:00Z
+     * // In local timezone: Feb 20, 2026 6:00 PM (previous day!)
+     *
+     * // CORRECT ✅
+     * parseISODate('2026-02-21')
+     * // Returns: 2026-02-21T00:00:00 local time
+     * ```
+     *
+     * Implementation: Parse components and construct Date in local timezone
+     */
+    parseISODate(isoDate: string): Date | null;
+    /**
+     * Get week start day for locale
+     *
+     * Default: Sunday (0) for most locales
+     * Monday (1) for Europe, ISO 8601
+     *
+     * Implementation: Simple locale detection
+     * For advanced needs, use Intl.Locale or external library
+     */
+    getWeekStart(locale?: string): 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NativeDateAdapter, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NativeDateAdapter>;
+}