@oneluiz/dual-datepicker 3.5.0 → 3.6.0

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>;
+}

package/core/preset-providers.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Provider Functions for Built-in Presets
+ *
+ * Version: 3.6.0
+ *
+ * Automatic registration of built-in date range presets.
+ * These providers ensure backward compatibility by auto-registering
+ * all standard presets (TODAY, LAST_7_DAYS, THIS_MONTH, etc.)
+ *
+ * USAGE IN LIBRARY (Internal):
+ * Built-in presets are registered automatically via Angular providers.
+ * Library consumers don't need to do anything.
+ *
+ * USAGE IN APP (Custom Presets):
+ * ```typescript
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     // ... other providers
+ *     provideCustomPresets([
+ *       {
+ *         key: 'THIS_FISCAL_QUARTER',
+ *         resolve: (clock, adapter) => {
+ *           const now = clock.now();
+ *           // ... fiscal logic
+ *           return { start, end };
+ *         }
+ *       }
+ *     ])
+ *   ]
+ * };
+ * ```
+ */
+import { EnvironmentProviders } from '@angular/core';
+import { RangePresetPlugin } from './range-preset.plugin';
+/**
+ * Provide built-in date range presets
+ *
+ * This provider is automatically included in the library's root providers.
+ * Library consumers don't need to add this manually.
+ *
+ * @returns EnvironmentProviders for built-in presets
+ *
+ * @internal
+ */
+export declare function provideBuiltInPresets(): EnvironmentProviders;
+/**
+ * Provide custom date range presets
+ *
+ * Use this to register your own industry-specific presets:
+ * - Fiscal presets
+ * - Hotel/hospitality presets
+ * - Logistics presets
+ * - Custom business logic
+ *
+ * @param presets - Array of custom RangePresetPlugin implementations
+ * @returns EnvironmentProviders for custom presets
+ *
+ * @example
+ * ```typescript
+ * // Fiscal presets
+ * const FISCAL_PRESETS: RangePresetPlugin[] = [
+ *   {
+ *     key: 'THIS_FISCAL_QUARTER',
+ *     resolve: (clock, adapter) => {
+ *       const now = clock.now();
+ *       const month = adapter.getMonth(now);
+ *
+ *       // Fiscal year starts April (month 3)
+ *       const fiscalMonth = (month + 9) % 12;
+ *       const quarterStart = Math.floor(fiscalMonth / 3) * 3;
+ *       const calendarMonth = (quarterStart - 9 + 12) % 12;
+ *
+ *       const year = adapter.getYear(now);
+ *       const fiscalYear = month < 3 ? year - 1 : year;
+ *
+ *       const start = new Date(fiscalYear, calendarMonth, 1);
+ *       const end = new Date(fiscalYear, calendarMonth + 3, 0);
+ *
+ *       return {
+ *         start: adapter.normalize(start),
+ *         end: adapter.normalize(end)
+ *       };
+ *     }
+ *   },
+ *   {
+ *     key: 'FISCAL_YEAR_TO_DATE',
+ *     resolve: (clock, adapter) => {
+ *       const now = clock.now();
+ *       const month = adapter.getMonth(now);
+ *       const year = adapter.getYear(now);
+ *
+ *       // Fiscal year starts April 1
+ *       const fiscalYearStart = month >= 3
+ *         ? new Date(year, 3, 1)
+ *         : new Date(year - 1, 3, 1);
+ *
+ *       return {
+ *         start: adapter.normalize(fiscalYearStart),
+ *         end: adapter.normalize(now)
+ *       };
+ *     }
+ *   }
+ * ];
+ *
+ * // In app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideCustomPresets(FISCAL_PRESETS)
+ *   ]
+ * };
+ *
+ * // Use in components
+ * store.applyPreset('THIS_FISCAL_QUARTER');
+ * store.applyPreset('FISCAL_YEAR_TO_DATE');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Hotel presets
+ * const HOTEL_PRESETS: RangePresetPlugin[] = [
+ *   {
+ *     key: 'CHECK_IN_WEEK',
+ *     resolve: (clock, adapter) => {
+ *       const now = clock.now();
+ *       const dayOfWeek = adapter.getDayOfWeek(now);
+ *
+ *       // Check-in week: Friday to Friday
+ *       const daysToNextFriday = dayOfWeek <= 5
+ *         ? 5 - dayOfWeek
+ *         : 7 - dayOfWeek + 5;
+ *
+ *       const nextFriday = adapter.addDays(now, daysToNextFriday);
+ *       const followingFriday = adapter.addDays(nextFriday, 7);
+ *
+ *       return { start: nextFriday, end: followingFriday };
+ *     }
+ *   },
+ *   {
+ *     key: 'NEXT_30_NIGHTS',
+ *     resolve: (clock, adapter) => {
+ *       const now = clock.now();
+ *       const tomorrow = adapter.addDays(now, 1);
+ *       const end = adapter.addDays(tomorrow, 30);
+ *       return { start: tomorrow, end };
+ *     }
+ *   }
+ * ];
+ *
+ * providers: [provideCustomPresets(HOTEL_PRESETS)]
+ * ```
+ */
+export declare function provideCustomPresets(presets: RangePresetPlugin[]): EnvironmentProviders;
+/**
+ * Provide preset package
+ *
+ * Convenience function for external preset packages.
+ *
+ * @param packageName - Name of the preset package (for logging)
+ * @param presets - Array of presets from the package
+ * @returns EnvironmentProviders
+ *
+ * @example
+ * ```typescript
+ * // @acme/fiscal-presets package
+ * export function provideFiscalPresets(): EnvironmentProviders {
+ *   return providePresetPackage('@acme/fiscal-presets', FISCAL_PRESETS);
+ * }
+ *
+ * // In app
+ * import { provideFiscalPresets } from '@acme/fiscal-presets';
+ *
+ * providers: [provideFiscalPresets()]
+ * ```
+ */
+export declare function providePresetPackage(packageName: string, presets: RangePresetPlugin[]): EnvironmentProviders;

package/core/preset-registry.d.ts

@@ -0,0 +1,181 @@
+import { RangePresetPlugin } from './range-preset.plugin';
+import * as i0 from "@angular/core";
+/**
+ * Preset Registry Service
+ *
+ * Manages registration and retrieval of date range preset plugins.
+ *
+ * DESIGN:
+ * - Uses Map for O(1) lookups
+ * - Immutable getAll() returns copy
+ * - Supports plugin override (last registration wins)
+ * - Validates plugins before registration
+ */
+export declare class PresetRegistry {
+    /**
+     * Internal map of registered presets
+     * Key: preset key (e.g., 'TODAY', 'LAST_7_DAYS')
+     * Value: RangePresetPlugin instance
+     */
+    private readonly presets;
+    /**
+     * Register a date range preset plugin
+     *
+     * If a preset with the same key already exists, it will be overridden.
+     * This is useful for:
+     * - Testing (override built-in presets with mocks)
+     * - Customization (replace default behavior)
+     * - Hot-reload scenarios
+     *
+     * @param plugin - The preset plugin to register
+     * @throws Error if plugin is invalid (missing key or resolve function)
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   key: 'LAST_BUSINESS_WEEK',
+     *   resolve: (clock, adapter) => {
+     *     const now = clock.now();
+     *     const dayOfWeek = adapter.getDayOfWeek(now);
+     *
+     *     // Go back to last Friday
+     *     const daysToLastFriday = dayOfWeek === 0 ? 2 : (dayOfWeek + 2) % 7;
+     *     const lastFriday = adapter.addDays(now, -daysToLastFriday);
+     *
+     *     // Business week: Monday to Friday
+     *     const monday = adapter.addDays(lastFriday, -4);
+     *
+     *     return { start: monday, end: lastFriday };
+     *   }
+     * });
+     * ```
+     */
+    register(plugin: RangePresetPlugin): void;
+    /**
+     * Register multiple preset plugins at once
+     *
+     * Convenience method for bulk registration.
+     * Useful when importing preset packages.
+     *
+     * @param plugins - Array of preset plugins to register
+     *
+     * @example
+     * ```typescript
+     * import { FISCAL_PRESETS } from '@acme/fiscal-presets';
+     *
+     * registry.registerAll(FISCAL_PRESETS);
+     * ```
+     */
+    registerAll(plugins: RangePresetPlugin[]): void;
+    /**
+     * Get a preset plugin by key
+     *
+     * @param key - Preset key (case-insensitive, e.g., 'today' or 'TODAY')
+     * @returns The preset plugin or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const preset = registry.get('LAST_7_DAYS');
+     * if (preset) {
+     *   const range = preset.resolve(clock, adapter);
+     *   console.log('Range:', range);
+     * }
+     * ```
+     */
+    get(key: string): RangePresetPlugin | undefined;
+    /**
+     * Check if a preset exists in the registry
+     *
+     * @param key - Preset key (case-insensitive)
+     * @returns true if preset exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (registry.has('THIS_FISCAL_QUARTER')) {
+     *   store.applyPreset('THIS_FISCAL_QUARTER');
+     * } else {
+     *   console.error('Fiscal quarter preset not registered');
+     * }
+     * ```
+     */
+    has(key: string): boolean;
+    /**
+     * Get all registered preset plugins
+     *
+     * Returns a NEW array (immutable) to prevent external modification.
+     *
+     * @returns Array of all registered preset plugins
+     *
+     * @example
+     * ```typescript
+     * const allPresets = registry.getAll();
+     * console.log('Available presets:');
+     * allPresets.forEach(preset => {
+     *   console.log(`- ${preset.key}`);
+     * });
+     * ```
+     */
+    getAll(): RangePresetPlugin[];
+    /**
+     * Get all preset keys
+     *
+     * Convenience method to list available preset identifiers.
+     *
+     * @returns Array of preset keys (uppercase)
+     *
+     * @example
+     * ```typescript
+     * const keys = registry.getAllKeys();
+     * // ['TODAY', 'YESTERDAY', 'LAST_7_DAYS', 'THIS_MONTH', ...]
+     * ```
+     */
+    getAllKeys(): string[];
+    /**
+     * Get count of registered presets
+     *
+     * @returns Number of registered presets
+     *
+     * @example
+     * ```typescript
+     * console.log(`${registry.count()} presets available`);
+     * ```
+     */
+    count(): number;
+    /**
+     * Unregister a preset plugin
+     *
+     * Useful for:
+     * - Testing cleanup
+     * - Dynamic preset management
+     * - Removing deprecated presets
+     *
+     * @param key - Preset key to remove (case-insensitive)
+     * @returns true if preset was removed, false if it didn't exist
+     *
+     * @example
+     * ```typescript
+     * registry.unregister('MY_TEMPORARY_PRESET');
+     * ```
+     */
+    unregister(key: string): boolean;
+    /**
+     * Clear all registered presets
+     *
+     * ⚠️ USE WITH CAUTION: This removes ALL presets including built-ins.
+     *
+     * Useful for:
+     * - Test teardown
+     * - Complete re-initialization scenarios
+     *
+     * @example
+     * ```typescript
+     * // In test cleanup
+     * afterEach(() => {
+     *   registry.clear();
+     * });
+     * ```
+     */
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PresetRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PresetRegistry>;
+}

package/core/preset.engine.d.ts

@@ -1,7 +1,7 @@
+import * as i0 from "@angular/core";
 /**
- * Headless Preset Engine
- * Pure functions that resolve date ranges WITHOUT render dependency
- * Perfect for SSR, global state, dashboard filters
+ * @deprecated Use RangePresetPlugin from './range-preset.plugin' instead
+ * Kept for backward compatibility
  */
 export interface RangePreset {
     /**
@@ -18,37 +18,107 @@ export interface PresetRange {
     end: string;
 }
 /**
- * Registry of built-in presets
- * Can be extended by consumers
+ * Preset Engine - Plugin-Driven Architecture
+ *
+ * ARCHITECTURE (v3.6.0):
+ * - NO longer contains presets internally
+ * - Uses PresetRegistry for plugin management
+ * - Injects DateClock for SSR-safe time
+ * - Injects DateAdapter for timezone-safe operations
+ * - Follows Open/Closed Principle
+ *
+ * BACKWARD COMPATIBILITY:
+ * - Old API unchanged: resolve(), register(), getPresetKeys()
+ * - Built-in presets auto-registered via provider
+ * - Existing code continues to work
+ *
+ * EXTENSIBILITY:
+ * ```typescript
+ * // Register custom preset via registry
+ * const registry = inject(PresetRegistry);
+ * registry.register({
+ *   key: 'MY_PRESET',
+ *   resolve: (clock, adapter) => {
+ *     const now = clock.now();
+ *     return { start: now, end: now };
+ *   }
+ * });
+ *
+ * // Use via engine
+ * const engine = inject(PresetEngine);
+ * const range = engine.resolve('MY_PRESET');
+ * ```
  */
 export declare class PresetEngine {
-    private presets;
+    private clock;
+    private adapter;
+    private registry;
     constructor();
     /**
      * Register a custom preset
+     *
+     * @deprecated Use PresetRegistry.register() directly for new code
+     * Kept for backward compatibility
+     *
+     * @param key - Preset key (e.g., 'MY_CUSTOM_PRESET')
+     * @param preset - Legacy RangePreset object
      */
     register(key: string, preset: RangePreset): void;
     /**
      * Resolve a preset to date range
+     *
+     * Plugin Architecture:
+     * 1. Looks up plugin in PresetRegistry
+     * 2. Calls plugin.resolve(clock, adapter)
+     * 3. Returns ISO date range
+     *
+     * SSR Note: Uses injected DateClock for deterministic resolution
+     * Timezone Note: Uses injected DateAdapter for consistent operations
+     *
+     * @param key - Preset key (e.g., 'TODAY', 'LAST_7_DAYS')
+     * @param now - Optional override for current date (defaults to clock.now())
+     * @returns ISO date range or null if preset not found
      */
     resolve(key: string, now?: Date): PresetRange | null;
     /**
      * Get all available preset keys
+     *
+     * Delegates to PresetRegistry
+     *
+     * @returns Array of registered preset keys
      */
     getPresetKeys(): string[];
     /**
-     * Register all built-in presets
+     * Check if a preset exists
+     *
+     * @param key - Preset key to check
+     * @returns true if preset is registered
      */
-    private registerBuiltInPresets;
+    hasPreset(key: string): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PresetEngine, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PresetEngine>;
 }
 /**
  * Create a custom preset from a function
+ *
+ * @deprecated Use RangePresetPlugin interface instead
+ * Kept for backward compatibility
  */
 export declare function createPreset(resolver: (now: Date) => {
     start: Date;
     end: Date;
 }): RangePreset;
 /**
- * Singleton preset engine instance
+ * @deprecated Use dependency injection instead:
+ * ```typescript
+ * private engine = inject(PresetEngine);
+ * ```
+ *
+ * Singleton preset engine instance for backward compatibility
+ *
+ * WARNING: This singleton uses SystemClock directly and is NOT SSR-safe.
+ * For SSR applications, inject PresetEngine and override DATE_CLOCK token.
+ *
+ * This export will be removed in v4.0.0
  */
 export declare const presetEngine: PresetEngine;