@oneluiz/dual-datepicker 3.5.1 → 3.9.0

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