@oneluiz/dual-datepicker 3.5.0 → 3.6.0

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/built-in-presets.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Built-in Date Range Preset Plugins
+ *
+ * Version: 3.6.0
+ *
+ * Standard presets provided by the library.
+ * All presets use DateClock and DateAdapter for SSR-safety and timezone-safety.
+ *
+ * PRESETS INCLUDED:
+ * - TODAY, YESTERDAY
+ * - LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_60_DAYS, LAST_90_DAYS
+ * - THIS_WEEK, LAST_WEEK
+ * - THIS_MONTH, LAST_MONTH, MONTH_TO_DATE
+ * - THIS_QUARTER, LAST_QUARTER, QUARTER_TO_DATE
+ * - THIS_YEAR, LAST_YEAR, YEAR_TO_DATE
+ */
+import { RangePresetPlugin } from './range-preset.plugin';
+/**
+ * TODAY - Current day
+ */
+export declare const TODAY_PRESET: RangePresetPlugin;
+/**
+ * YESTERDAY - Previous day
+ */
+export declare const YESTERDAY_PRESET: RangePresetPlugin;
+/**
+ * LAST_7_DAYS - Last 7 days including today
+ */
+export declare const LAST_7_DAYS_PRESET: RangePresetPlugin;
+/**
+ * LAST_14_DAYS - Last 14 days including today
+ */
+export declare const LAST_14_DAYS_PRESET: RangePresetPlugin;
+/**
+ * LAST_30_DAYS - Last 30 days including today
+ */
+export declare const LAST_30_DAYS_PRESET: RangePresetPlugin;
+/**
+ * LAST_60_DAYS - Last 60 days including today
+ */
+export declare const LAST_60_DAYS_PRESET: RangePresetPlugin;
+/**
+ * LAST_90_DAYS - Last 90 days including today
+ */
+export declare const LAST_90_DAYS_PRESET: RangePresetPlugin;
+/**
+ * THIS_WEEK - Current week (Monday to Sunday)
+ */
+export declare const THIS_WEEK_PRESET: RangePresetPlugin;
+/**
+ * LAST_WEEK - Previous week (Monday to Sunday)
+ */
+export declare const LAST_WEEK_PRESET: RangePresetPlugin;
+/**
+ * THIS_MONTH - Current calendar month (1st to last day)
+ */
+export declare const THIS_MONTH_PRESET: RangePresetPlugin;
+/**
+ * LAST_MONTH - Previous calendar month
+ */
+export declare const LAST_MONTH_PRESET: RangePresetPlugin;
+/**
+ * MONTH_TO_DATE - From start of current month to today
+ */
+export declare const MONTH_TO_DATE_PRESET: RangePresetPlugin;
+/**
+ * THIS_QUARTER - Current quarter (Q1: Jan-Mar, Q2: Apr-Jun, Q3: Jul-Sep, Q4: Oct-Dec)
+ */
+export declare const THIS_QUARTER_PRESET: RangePresetPlugin;
+/**
+ * LAST_QUARTER - Previous quarter
+ */
+export declare const LAST_QUARTER_PRESET: RangePresetPlugin;
+/**
+ * QUARTER_TO_DATE - From start of current quarter to today
+ */
+export declare const QUARTER_TO_DATE_PRESET: RangePresetPlugin;
+/**
+ * THIS_YEAR - Current calendar year (Jan 1 to Dec 31)
+ */
+export declare const THIS_YEAR_PRESET: RangePresetPlugin;
+/**
+ * LAST_YEAR - Previous calendar year
+ */
+export declare const LAST_YEAR_PRESET: RangePresetPlugin;
+/**
+ * YEAR_TO_DATE - From start of current year to today
+ */
+export declare const YEAR_TO_DATE_PRESET: RangePresetPlugin;
+/**
+ * All built-in presets as an array
+ *
+ * Use this to register all built-in presets at once:
+ * ```typescript
+ * BUILT_IN_PRESETS.forEach(preset => registry.register(preset));
+ * ```
+ */
+export declare const BUILT_IN_PRESETS: RangePresetPlugin[];

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

@@ -1,7 +1,22 @@
 /**
  * Core headless date range logic
+ *
+ * v3.6.0: Plugin Architecture
+ * - RangePresetPlugin interface for extensible presets
+ * - PresetRegistry for plugin management
+ * - Built-in presets as plugins
+ * - Provider functions for custom presets
+ *
  * 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';
+export * from './range-preset.plugin';
+export * from './preset-registry';
+export * from './built-in-presets';
+export * from './preset-providers';