@oneluiz/dual-datepicker 3.6.0 → 3.9.0

package/core/calendar-grid/calendar-grid.cache.d.ts

@@ -0,0 +1,39 @@
+import { CalendarGridFactory } from './calendar-grid.factory';
+import { CalendarGrid } from './calendar-grid.types';
+import * as i0 from "@angular/core";
+export declare class CalendarGridCache {
+    private factory;
+    private cache;
+    private readonly maxSize;
+    constructor(factory: CalendarGridFactory);
+    /**
+     * Get or create a calendar grid
+     *
+     * @param monthDate - Any date within the target month
+     * @param weekStart - First day of week (0 = Sunday, 1 = Monday, etc.)
+     * @param locale - Locale identifier (optional)
+     * @returns CalendarGrid - cached or newly created
+     */
+    get(monthDate: Date, weekStart?: number, locale?: string): CalendarGrid;
+    /**
+     * Build cache key from month parameters
+     *
+     * Format: "year-month-weekStart-locale"
+     * Example: "2026-1-0-en" (Feb 2026, Sunday start, English)
+     */
+    private buildKey;
+    /**
+     * Clear entire cache (for testing or manual reset)
+     */
+    clear(): void;
+    /**
+     * Get cache size (for debugging/testing)
+     */
+    size(): number;
+    /**
+     * Check if a specific month is cached
+     */
+    has(monthDate: Date, weekStart?: number, locale?: string): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarGridCache, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CalendarGridCache>;
+}

package/core/calendar-grid/calendar-grid.factory.d.ts

@@ -0,0 +1,26 @@
+import { DateAdapter } from '../date-adapter';
+import { CalendarGrid } from './calendar-grid.types';
+import * as i0 from "@angular/core";
+export declare class CalendarGridFactory {
+    private adapter;
+    constructor(adapter: DateAdapter);
+    /**
+     * Create a calendar grid for a given month
+     *
+     * @param monthDate - Any date within the target month (will be normalized to start of month)
+     * @param weekStart - First day of week (0 = Sunday, 1 = Monday, etc.)
+     * @param locale - Locale identifier (optional, for future use)
+     * @returns CalendarGrid - 6 weeks x 7 days grid
+     */
+    createGrid(monthDate: Date, weekStart?: number, locale?: string): CalendarGrid;
+    /**
+     * Calculate offset (number of padding days from previous month)
+     *
+     * @param firstDayOfWeek - Day of week for first day of month (0-6)
+     * @param weekStart - Desired week start (0-6)
+     * @returns Number of padding days needed
+     */
+    private calculateOffset;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarGridFactory, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CalendarGridFactory>;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Calendar Grid Types
+ *
+ * Defines the structure for memoized calendar month grids.
+ * Separates base grid structure (cacheable) from decorations (dynamic).
+ */
+/**
+ * A single calendar cell representing one day
+ */
+export interface CalendarCell {
+    /** Date object (normalized to start of day) */
+    date: Date;
+    /** Whether this day belongs to the current rendered month */
+    inCurrentMonth: boolean;
+    /** ISO string 'YYYY-MM-DD' (timezone-safe via DateAdapter) */
+    iso: string;
+    /** Day of month (1-31) */
+    day: number;
+    /** Month (0-11, JavaScript convention) */
+    month: number;
+    /** Full year */
+    year: number;
+    /** Day of week (0 = Sunday, 6 = Saturday) */
+    dayOfWeek: number;
+}
+/**
+ * A calendar grid representing one month
+ *
+ * Grid is always 6 weeks x 7 days (42 cells) for layout stability.
+ * Includes padding days from previous/next month.
+ */
+export interface CalendarGrid {
+    /** Month identifier */
+    month: {
+        /** Year */
+        year: number;
+        /** Month 0-11 */
+        month: number;
+    };
+    /** Week start day (0 = Sunday, 1 = Monday, etc.) */
+    weekStart: number;
+    /** Locale (for future i18n, optional) */
+    locale?: string;
+    /** 6 weeks x 7 days matrix */
+    weeks: CalendarCell[][];
+    /** Flat array of all cells (convenience accessor) */
+    cells: CalendarCell[];
+}
+/**
+ * Cache key for calendar grids
+ */
+export interface CalendarGridCacheKey {
+    year: number;
+    month: number;
+    weekStart: number;
+    locale?: string;
+}

package/core/calendar-grid/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Calendar Grid Module
+ *
+ * Performance-optimized calendar month grid generation with memoization.
+ *
+ * v3.7.0: Grid Structure Cache
+ * - CalendarGridFactory for deterministic 42-cell grids
+ * - CalendarGridCache with LRU (24 months)
+ *
+ * v3.8.0: Range Highlight Cache
+ * - RangeHighlighter for decoration logic
+ * - RangeHighlighterCache with LRU (48 grids)
+ * - Separates grid structure from decorations
+ *
+ * v3.9.0: Virtual Weeks (Windowed Rendering)
+ * - Virtual-weeks logic for reduced DOM complexity
+ * - Render only visible weeks (configurable window)
+ * - ~50% reduction in DOM nodes with windowSize=3
+ *
+ * Usage:
+ * ```typescript
+ * constructor(
+ *   private gridCache: CalendarGridCache,
+ *   private highlighterCache: RangeHighlighterCache
+ * ) {}
+ *
+ * const grid = this.gridCache.get(monthDate, weekStart);
+ * const decorated = this.highlighterCache.get(grid, {
+ *   start, end, hoverDate, disabledDates
+ * });
+ *
+ * // Optional: Windowed rendering (v3.9.0+)
+ * const windowSize = 3; // Render only 3 weeks
+ * const visibleWeeks = getVisibleWeeks(
+ *   decorated.weeks,
+ *   weekStartIndex,
+ *   windowSize
+ * );
+ * // decorated.cells[0].iso => '2026-02-01'
+ * // decorated.cells[0].isInRange => true
+ * ```
+ */
+export * from './calendar-grid.types';
+export * from './calendar-grid.factory';
+export * from './calendar-grid.cache';
+export * from './range-highlighter.types';
+export * from './range-highlighter';
+export * from './range-highlighter.cache';
+export * from './virtual-weeks.types';
+export * from './virtual-weeks.logic';

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

@@ -0,0 +1,105 @@
+import { DateAdapter } from '../date-adapter';
+import { CalendarGrid } from './calendar-grid.types';
+import { DecoratedGrid, RangeDecorationParams } from './range-highlighter.types';
+import { RangeHighlighter } from './range-highlighter';
+import * as i0 from "@angular/core";
+/**
+ * Range Highlighter Cache
+ *
+ * Memoizes decorated grids to avoid recomputing decorations.
+ *
+ * Cache strategy:
+ * - LRU eviction (Map preserves insertion order)
+ * - Max 48 entries (~1-2 years of decorated grids)
+ * - Key: month + start + end + hover + disabled signature
+ *
+ * Performance:
+ * - Cache hit: ~0.1ms (object lookup)
+ * - Cache miss: ~1ms (decoration + store)
+ * - Hit rate: Expected >80% in typical usage
+ *
+ * Memory:
+ * - ~15KB per decorated grid
+ * - Max 48 grids = ~720KB
+ * - Auto-eviction prevents leaks
+ *
+ * Edge cases handled:
+ * - Function predicates: Not cacheable (recompute every time)
+ * - Large disabled arrays: Sorted + joined for stable key
+ * - Hover changes: Separate cache entries
+ * - Multi-range mode: Included in key
+ *
+ * Usage:
+ * ```typescript
+ * const grid = calendarGridCache.get(monthDate, 0);
+ * const decorated = rangeHighlighterCache.get(grid, {
+ *   start: startDate,
+ *   end: endDate,
+ *   hoverDate: '2026-01-20',
+ *   disabledDates: [...]
+ * });
+ * // Same params = same object reference (===)
+ * ```
+ */
+export declare class RangeHighlighterCache {
+    private highlighter;
+    private adapter;
+    private cache;
+    private maxSize;
+    constructor(highlighter: RangeHighlighter, adapter: DateAdapter);
+    /**
+     * Get decorated grid (cached or computed)
+     *
+     * If cache hit: Returns existing DecoratedGrid (same object reference)
+     * If cache miss: Computes decorations, stores in cache, returns new grid
+     *
+     * @param grid Base calendar grid (from CalendarGridCache)
+     * @param params Decoration parameters
+     * @returns Decorated grid with range highlights
+     */
+    get(grid: CalendarGrid, params: RangeDecorationParams): DecoratedGrid;
+    /**
+     * Build cache key from grid and params
+     *
+     * Key structure:
+     * `${monthKey}|${startISO}|${endISO}|${minISO}|${maxISO}|${hoverISO}|${disabledSig}`
+     *
+     * Example:
+     * "2026-1-0-|2026-01-15|2026-01-25|null|null|2026-01-20|2026-01-10,2026-01-11"
+     *
+     * @param grid Base calendar grid
+     * @param params Decoration parameters
+     * @returns Cache key components
+     */
+    private buildKey;
+    /**
+     * Build signature for disabled dates
+     *
+     * Strategies:
+     * - null/undefined: 'none'
+     * - Function: 'function' (not cacheable)
+     * - Array: Sorted ISO dates joined with commas
+     *
+     * @param disabledDates Disabled dates specification
+     * @returns Signature string for cache key
+     */
+    private buildDisabledSignature;
+    /**
+     * Clear all cached grids
+     */
+    clear(): void;
+    /**
+     * Get current cache size
+     */
+    size(): number;
+    /**
+     * Check if key is cached
+     *
+     * @param grid Base calendar grid
+     * @param params Decoration parameters
+     * @returns True if this grid+params is cached
+     */
+    has(grid: CalendarGrid, params: RangeDecorationParams): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RangeHighlighterCache, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RangeHighlighterCache>;
+}

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

@@ -0,0 +1,85 @@
+import { DateAdapter } from '../date-adapter';
+import { CalendarGrid } from './calendar-grid.types';
+import { DecoratedGrid, RangeDecorationParams } from './range-highlighter.types';
+import * as i0 from "@angular/core";
+/**
+ * Range Highlighter
+ *
+ * Applies decorations to calendar grids:
+ * - isSelectedStart, isSelectedEnd (range boundaries)
+ * - isInRange (cells within selected range)
+ * - isInHoverRange (hover preview)
+ * - isDisabled (constraints, custom predicates)
+ *
+ * Design:
+ * - Pure functions (same input = same output)
+ * - Uses DateAdapter for all date operations (SSR-safe)
+ * - No side effects, no state
+ * - Fast (~1ms for 42 cells on mobile)
+ *
+ * Usage:
+ * ```typescript
+ * const grid = calendarGridCache.get(monthDate, 0);
+ * const decorated = rangeHighlighter.decorate(grid, {
+ *   start: startDate,
+ *   end: endDate,
+ *   hoverDate: '2026-01-20',
+ *   disabledDates: [...]
+ * });
+ * ```
+ */
+export declare class RangeHighlighter {
+    private adapter;
+    constructor(adapter: DateAdapter);
+    /**
+     * Decorate calendar grid with range highlights
+     *
+     * @param grid Base calendar grid (from CalendarGridCache)
+     * @param params Decoration parameters (start, end, hover, disabled, etc.)
+     * @returns Decorated grid with computed properties
+     */
+    decorate(grid: CalendarGrid, params: RangeDecorationParams): DecoratedGrid;
+    /**
+     * Check if cell is within selected range
+     *
+     * @param cellISO Cell date (ISO format)
+     * @param startISO Start date (ISO or null)
+     * @param endISO End date (ISO or null)
+     * @returns True if cell is in range [start, end] (inclusive)
+     */
+    private isInRange;
+    /**
+     * Check if cell is within hover preview range
+     *
+     * @param cellISO Cell date (ISO format)
+     * @param hoverRange Hover range boundaries (or null)
+     * @returns True if cell is in hover range
+     */
+    private isInHoverRange;
+    /**
+     * Check if cell is disabled
+     *
+     * @param date Cell date object
+     * @param minISO Minimum allowed date (ISO or null)
+     * @param maxISO Maximum allowed date (ISO or null)
+     * @param disabledDates Disabled dates (array, function, or null)
+     * @returns True if cell is disabled
+     */
+    private isDisabled;
+    /**
+     * Compute hover preview range
+     *
+     * When user hovers over a date (and not selecting start):
+     * - Show preview range from start to hover
+     * - Range is always [min, max] where min <= max
+     *
+     * @param startISO Current start date (ISO or null)
+     * @param hoverISO Hovered date (ISO or null)
+     * @param selectingStart True if selecting start date (hover disabled)
+     * @param multiRange True if in multi-range mode
+     * @returns Hover range boundaries or null
+     */
+    private computeHoverRange;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RangeHighlighter, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RangeHighlighter>;
+}

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

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

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