@oneluiz/dual-datepicker 3.9.2 → 4.0.0

package/core/calendar-grid/range-highlighter.types.d.ts

@@ -1,182 +0,0 @@
-/**
- * Range Highlighter Types
- *
- * Type definitions for calendar cell decorations with range highlighting.
- * Used by RangeHighlighter to cache decorated grids and avoid recomputations.
- *
- * @module core/calendar-grid/range-highlighter.types
- * @version 3.8.0
- */
-import { CalendarCell, CalendarGrid } from './calendar-grid.types';
-/**
- * Calendar cell with range highlight decorations
- *
- * Extends base CalendarCell with computed properties for:
- * - Start/end markers (selected range boundaries)
- * - Range membership (cell within selected range)
- * - Hover preview (temporary range during mouse hover)
- * - Disabled state (constraints, custom predicates)
- */
-export interface DecoratedCell extends CalendarCell {
-    /**
-     * True if this cell is the selected start date
-     */
-    isSelectedStart: boolean;
-    /**
-     * True if this cell is the selected end date
-     */
-    isSelectedEnd: boolean;
-    /**
-     * True if this cell is within the selected range (inclusive)
-     */
-    isInRange: boolean;
-    /**
-     * True if this cell is within the hover preview range
-     */
-    isInHoverRange: boolean;
-    /**
-     * True if this cell is disabled (via constraints or custom logic)
-     */
-    isDisabled: boolean;
-}
-/**
- * Calendar grid with decorated cells
- *
- * Contains:
- * - base: Original CalendarGrid (from CalendarGridCache)
- * - weeks: 2D array of decorated cells (6 × 7)
- * - cells: Flat array of decorated cells (42 cells)
- */
-export interface DecoratedGrid {
-    /**
-     * Base grid structure (memoized by CalendarGridCache)
-     */
-    base: CalendarGrid;
-    /**
-     * Decorated cells organized as weeks (6 weeks × 7 days)
-     */
-    weeks: DecoratedCell[][];
-    /**
-     * Decorated cells as flat array (42 cells for layout stability)
-     */
-    cells: DecoratedCell[];
-}
-/**
- * Parameters for range decoration
- *
- * All dates must be Date objects (pre-parsed by component).
- * Cache key is built from ISO dates (via DateAdapter.toISODate).
- *
- * Constraints:
- * - start/end: Selected range boundaries (null if not selected)
- * - minDate/maxDate: Hard constraints (optional, for future use)
- * - hoverDate: Current hover date (null if not hovering)
- * - disabledDates: Array of disabled dates OR function predicate
- */
-export interface RangeDecorationParams {
-    /**
-     * Selected start date (null if not selected yet)
-     */
-    start: Date | null;
-    /**
-     * Selected end date (null if not selected yet)
-     */
-    end: Date | null;
-    /**
-     * Minimum allowed date (optional, for future constraint support)
-     * All dates before this will be disabled.
-     */
-    minDate?: Date | null;
-    /**
-     * Maximum allowed date (optional, for future constraint support)
-     * All dates after this will be disabled.
-     */
-    maxDate?: Date | null;
-    /**
-     * Current hover date (null if not hovering)
-     * Used to calculate hover preview range.
-     */
-    hoverDate?: string | null;
-    /**
-     * Disabled dates specification
-     *
-     * Can be one of:
-     * - Array of Date objects to disable (exact matches)
-     * - Function predicate (date) => boolean
-     * - undefined/null (no dates disabled)
-     *
-     * NOTE: Functions cannot be cached reliably (no stable key).
-     * If using function, cache will be bypassed for isDisabled computation.
-     */
-    disabledDates?: Date[] | ((date: Date) => boolean) | null;
-    /**
-     * Multi-range mode flag (affects hover range behavior)
-     * Default: false
-     */
-    multiRange?: boolean;
-    /**
-     * Currently selecting start date (affects hover preview)
-     * Default: false
-     */
-    selectingStartDate?: boolean;
-}
-/**
- * Cache key for decorated grid
- *
- * Built from:
- * - monthKey: `${year}-${month}-${weekStart}-${locale}`
- * - startISO, endISO: ISO dates or 'null'
- * - minISO, maxISO: ISO dates or 'null' (optional)
- * - hoverISO: ISO date or 'null'
- * - disabledSignature: Hash of disabled dates (or 'none' / 'function')
- *
- * Example:
- * "2026-1-0-|2026-01-15|2026-01-25|null|null|2026-01-20|2026-01-10,2026-01-11"
- *
- * Segment breakdown:
- * 1. 2026-1-0- (month: Jan 2026, weekStart: Sunday, no locale)
- * 2. 2026-01-15 (start date)
- * 3. 2026-01-25 (end date)
- * 4. null (no minDate)
- * 5. null (no maxDate)
- * 6. 2026-01-20 (hovering over Jan 20)
- * 7. 2026-01-10,2026-01-11 (disabled dates: Jan 10 & 11)
- */
-export interface DecoratedGridCacheKey {
-    /**
-     * Combined month key (from base grid)
-     */
-    monthKey: string;
-    /**
-     * Start date ISO (YYYY-MM-DD) or 'null'
-     */
-    startISO: string;
-    /**
-     * End date ISO (YYYY-MM-DD) or 'null'
-     */
-    endISO: string;
-    /**
-     * Min date ISO (YYYY-MM-DD) or 'null'
-     */
-    minISO: string;
-    /**
-     * Max date ISO (YYYY-MM-DD) or 'null'
-     */
-    maxISO: string;
-    /**
-     * Hover date ISO (YYYY-MM-DD) or 'null'
-     */
-    hoverISO: string;
-    /**
-     * Disabled dates signature
-     *
-     * - 'none': No dates disabled
-     * - 'function': Using predicate function (not cacheable)
-     * - sorted ISO string: "2026-01-10,2026-01-11,..." (for array)
-     */
-    disabledSignature: string;
-    /**
-     * Full cache key (concatenation of all segments)
-     */
-    full: string;
-}

package/core/calendar-grid/virtual-weeks.logic.d.ts

@@ -1,116 +0,0 @@
-/**
- * Virtual Weeks Logic (Pure Functions)
- *
- * Pure computation layer for windowed week rendering.
- * No side effects, fully testable with node:test.
- *
- * @module core/calendar-grid/virtual-weeks.logic
- * @version 3.9.0
- */
-import { VirtualWeekWindow } from './virtual-weeks.types';
-/**
- * Get visible weeks from total weeks array
- *
- * Pure function: Given weeks array and window config, returns visible slice.
- *
- * @param weeks Total weeks array (usually 6 weeks)
- * @param startIndex Start index of visible window (0-based)
- * @param windowSize How many weeks to show
- * @returns Visible weeks slice
- *
- * @example
- * ```typescript
- * const allWeeks = [week0, week1, week2, week3, week4, week5]; // 6 weeks
- * const visible = getVisibleWeeks(allWeeks, 0, 3);
- * // Returns [week0, week1, week2]
- *
- * const visible2 = getVisibleWeeks(allWeeks, 3, 3);
- * // Returns [week3, week4, week5]
- * ```
- */
-export declare function getVisibleWeeks<T>(weeks: T[], startIndex: number, windowSize: number): T[];
-/**
- * Clamp week start index to valid range
- *
- * Ensures startIndex is within bounds [0, totalWeeks - windowSize].
- * Prevents scrolling beyond available weeks.
- *
- * @param startIndex Desired start index
- * @param totalWeeks Total weeks available
- * @param windowSize Window size
- * @returns Clamped start index
- *
- * @example
- * ```typescript
- * clampWeekStart(0, 6, 3); // 0 (valid)
- * clampWeekStart(3, 6, 3); // 3 (valid, shows weeks 3-5)
- * clampWeekStart(4, 6, 3); // 3 (clamped, can't show beyond week 5)
- * clampWeekStart(-1, 6, 3); // 0 (clamped, can't go negative)
- * ```
- */
-export declare function clampWeekStart(startIndex: number, totalWeeks: number, windowSize: number): number;
-/**
- * Navigate week window (scroll up/down)
- *
- * Returns new start index after navigation.
- * Handles clamping automatically.
- *
- * @param currentStart Current start index
- * @param direction Navigation direction (+1 = down/later, -1 = up/earlier)
- * @param totalWeeks Total weeks available
- * @param windowSize Window size
- * @returns New start index after navigation
- *
- * @example
- * ```typescript
- * // Start at week 0, navigate down
- * navigateWeekWindow(0, 1, 6, 3); // Returns 1 (now showing weeks 1-3)
- *
- * // At week 3 (last valid position), navigate down
- * navigateWeekWindow(3, 1, 6, 3); // Returns 3 (can't go further)
- *
- * // At week 1, navigate up
- * navigateWeekWindow(1, -1, 6, 3); // Returns 0 (now showing weeks 0-2)
- * ```
- */
-export declare function navigateWeekWindow(currentStart: number, direction: number, totalWeeks: number, windowSize: number): number;
-/**
- * Get virtual week window state
- *
- * Computes full window state including navigation capabilities.
- *
- * @param startIndex Current start index
- * @param totalWeeks Total weeks available
- * @param windowSize Window size
- * @returns Complete window state
- *
- * @example
- * ```typescript
- * const state = getVirtualWeekWindow(0, 6, 3);
- * // {
- * //   startIndex: 0,
- * //   windowSize: 3,
- * //   totalWeeks: 6,
- * //   canNavigateUp: false,    // Already at top
- * //   canNavigateDown: true    // Can scroll down
- * // }
- *
- * const state2 = getVirtualWeekWindow(3, 6, 3);
- * // {
- * //   startIndex: 3,
- * //   windowSize: 3,
- * //   totalWeeks: 6,
- * //   canNavigateUp: true,     // Can scroll up
- * //   canNavigateDown: false   // Already at bottom
- * // }
- * ```
- */
-export declare function getVirtualWeekWindow(startIndex: number, totalWeeks: number, windowSize: number): VirtualWeekWindow;
-/**
- * Check if virtual weeks mode is enabled
- *
- * @param windowSize Window size from config (undefined = disabled)
- * @param totalWeeks Total weeks available
- * @returns True if windowing should be applied
- */
-export declare function isVirtualWeeksEnabled(windowSize: number | undefined, totalWeeks: number): boolean;

package/core/calendar-grid/virtual-weeks.types.d.ts

@@ -1,71 +0,0 @@
-/**
- * Virtual Weeks Types
- *
- * Type definitions for windowed week rendering (virtual scrolling).
- * Reduces DOM nodes by rendering only visible weeks instead of full month.
- *
- * @module core/calendar-grid/virtual-weeks.types
- * @version 3.9.0
- */
-/**
- * Virtual weeks configuration
- *
- * Controls how many weeks to render at once (windowed rendering).
- * Reduces DOM complexity for better mobile performance.
- *
- * Example:
- * ```typescript
- * <ngx-dual-datepicker
- *   [virtualWeeks]="{ windowSize: 3 }"
- * </ngx-dual-datepicker>
- * ```
- *
- * With windowSize=3:
- * - Renders only 3 weeks at a time (21 cells vs 42 cells)
- * - User can navigate between week windows
- * - ~50% reduction in DOM nodes per calendar
- * - ~50% reduction in reflow/repaint cost
- */
-export interface VirtualWeeksConfig {
-    /**
-     * Number of weeks to render at once
-     *
-     * Default: undefined (render all 6 weeks - backward compatible)
-     *
-     * Recommended values:
-     * - 3: Good balance (21 cells)
-     * - 4: More context (28 cells)
-     * - 2: Minimal (14 cells, may feel cramped)
-     */
-    windowSize: number;
-}
-/**
- * Virtual week window state
- *
- * Tracks which weeks are currently visible in the window.
- * Managed by component signals.
- */
-export interface VirtualWeekWindow {
-    /**
-     * Start index of visible week range (0-based)
-     *
-     * Range: [0, totalWeeks - windowSize]
-     */
-    startIndex: number;
-    /**
-     * Window size (how many weeks visible)
-     */
-    windowSize: number;
-    /**
-     * Total weeks available in month (usually 6, sometimes 5)
-     */
-    totalWeeks: number;
-    /**
-     * Whether user can scroll/navigate up (to earlier weeks)
-     */
-    canNavigateUp: boolean;
-    /**
-     * Whether user can scroll/navigate down (to later weeks)
-     */
-    canNavigateDown: boolean;
-}

package/core/date-adapter.d.ts

@@ -1,298 +0,0 @@
-/**
- * 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>;