ngxsmk-datepicker 3.0.3 → 3.0.4-beta.0

package/CHANGELOG.md

@@ -2,13 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** August 18, 2026 - **Current stable:** v3.0.4
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [3.0.4] - 2026-08-18
+
+### Added
+
+- **Built-in Angular Reactive Forms Validators**: Added type-safe Angular `ValidatorFn` utilities exported in the public API:
+  - `ngxsmkMinDateValidator(minDate)`: Validates single dates, ranges, and multiple date arrays against a minimum date.
+  - `ngxsmkMaxDateValidator(maxDate)`: Validates dates against a maximum date.
+  - `ngxsmkDateRangeValidator(options)`: Validates minimum/maximum range duration (`minDays`, `maxDays`) and complete range requirements (`requireBoth`).
+  - `ngxsmkBlockedDatesValidator(blocked)`: Validates that selected dates/ranges do not intersect blocked or blacklisted dates.
+- **Built-in Range Presets UI (`[showPresets]`)**: Added `[showPresets]` input signal to display standard presets (*Today*, *Yesterday*, *Last 7 Days*, *Last 30 Days*, *This Month*, *Last Month*) when in range mode.
+- **Datepicker Overlay Service**: Added and exported `DatepickerOverlayService` for automated viewport collision detection, auto-flipping, and responsive positioning.
+- **Accessibility & Reduced Motion**: Enhanced `@media (prefers-reduced-motion: reduce)` across all popovers, drawers, and overlay panels; added `role="grid"` and `role="gridcell"` attributes on Year/Decade views; added visible month span announcements for multi-calendar navigation.
+
+### Fixed
+
+- **Month & Year Select Sync on Clear (Issue #311)**: Fixed issue where clearing a date and re-opening the calendar or navigating months caused header dropdowns to desynchronize with the rendered days grid ([#311](https://github.com/NGXSMK/ngxsmk-datepicker/issues/311)).
+- **Performance Optimization**: Implemented precomputed timestamp `Set<number>` lookups ($O(1)$) for disabled dates and parsed ranges, eliminating per-cell string parsing overhead during calendar grid rendering.
+
 ## [3.0.3] - 2026-07-29
 
 ### Added

package/MIGRATION.md

@@ -2,11 +2,12 @@
 
 This document provides migration instructions for upgrading between major versions of ngxsmk-datepicker.
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** August 18, 2026 - **Current stable:** v3.0.4
 
 ## Table of Contents
 
-- [v2.4.0 → v3.0.3](#v240---v302)
+- [v3.0.3 → v3.0.4](#v303---v304)
+- [v2.4.0 → v3.0.3](#v240---v303)
 - [v2.2.15 → v2.3.1](#v2215---v231)
 - [v2.2.7 → v2.2.11](#v227---v228)
 - [v2.2.6 → v2.2.7](#v226---v227)
@@ -60,6 +61,17 @@ This document provides migration instructions for upgrading between major versio
 - [v1.8.0 → v1.9.0](#v180---v190)
 - [v1.7.0 → v1.8.0](#v170---v180)
 
+## v3.0.3 → v3.0.4
+
+### Changes
+
+All new functionality is backwards-compatible and opt-in:
+- **Built-in Reactive Forms Validators**: Added type-safe validators `ngxsmkMinDateValidator`, `ngxsmkMaxDateValidator`, `ngxsmkDateRangeValidator`, and `ngxsmkBlockedDatesValidator` in `@ngxsmk/datepicker` public API.
+- **Built-in Range Presets (`[showPresets]`)**: Standard preset ranges for range picker mode (*Today*, *Yesterday*, *Last 7 Days*, *Last 30 Days*, *This Month*, *Last Month*).
+- **Performance**: Precomputed lookup Set for disabled dates and parsed ranges, eliminating per-cell string parsing during calendar grid rendering.
+- **Accessibility**: Reduced-motion styles across all overlay/drawer surfaces, and ARIA grid attributes for year/decade views.
+- **Bug Fix**: Fixed Issue #311 (Month/year dropdowns desynchronize after clear).
+
 ## v2.4.0 → v3.0.3
 
 ### Changes

package/README.md

@@ -11,16 +11,18 @@
 ### _The Gold Standard for Premium Angular Calendar Selection_
 
 [![npm version](https://img.shields.io/npm/v/ngxsmk-datepicker.svg?style=flat-square&color=6d28d9)](https://www.npmjs.com/package/ngxsmk-datepicker)
+[![npm downloads](https://img.shields.io/npm/dm/ngxsmk-datepicker.svg?style=flat-square)](https://www.npmjs.com/package/ngxsmk-datepicker)
 [![CI](https://img.shields.io/github/actions/workflow/status/NGXSMK/ngxsmk-datepicker/ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/NGXSMK/ngxsmk-datepicker/actions/workflows/ci.yml)
 [![Angular](https://img.shields.io/badge/Angular-17%2B-DD0031.svg?style=flat-square&logo=angular)](https://angular.io/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/LICENSE)
+[![WhatsApp Channel](https://img.shields.io/badge/WhatsApp-Channel-25D366?style=flat-square&logo=whatsapp&logoColor=white)](https://whatsapp.com/channel/0029Vb8PWpz1XquUOnGPUM2p)
 [![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-toozuuu-orange?style=flat-square&logo=buy-me-a-coffee)](https://buymeacoffee.com/toozuuu)
 [![Bundle Size](https://img.shields.io/badge/bundle-~127KB-success.svg?style=flat-square)](https://bundlephobia.com/package/ngxsmk-datepicker)
 [![Zoneless](https://img.shields.io/badge/Zoneless-Ready-blueviolet.svg?style=flat-square)](https://angular.dev/guide/zoneless)
 
 **`npm i ngxsmk-datepicker`**
 
-[Live demo](https://ngxsmk.github.io/ngxsmk-datepicker/) • [StackBlitz (repo)](https://stackblitz.com/github/NGXSMK/ngxsmk-datepicker) • [API docs](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/projects/ngxsmk-datepicker/docs/API.md) • [Issues](https://github.com/NGXSMK/ngxsmk-datepicker/issues) • [Buy me a coffee](https://buymeacoffee.com/toozuuu)
+[Live demo](https://ngxsmk.github.io/ngxsmk-datepicker/) • [WhatsApp Channel](https://whatsapp.com/channel/0029Vb8PWpz1XquUOnGPUM2p) • [StackBlitz (repo)](https://stackblitz.com/github/NGXSMK/ngxsmk-datepicker) • [API docs](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/projects/ngxsmk-datepicker/docs/API.md) • [Issues](https://github.com/NGXSMK/ngxsmk-datepicker/issues) • [Buy me a coffee](https://buymeacoffee.com/toozuuu)
 
 *StackBlitz:* after it boots, run `npm install` then `npm start` in the terminal to serve the demo app (`demo-app`).
 
@@ -28,15 +30,15 @@
 
 ---
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** August 18, 2026 - **Current stable:** v3.0.4
 
 ### **Overview**
 
 **ngxsmk-datepicker** is a high-performance, enterprise-ready date and range picker engineered for the modern Angular ecosystem (v17+). Built from the ground up with **Angular Signals**, it delivers a seamless, zoneless-ready experience for both desktop and mobile (Ionic) applications.
 
-> **Stable Release**: `v3.0.3` is the current stable release with compiled `fesm2022` output and type declarations.
+> **Stable Release**: `v3.0.4` is the current stable release with compiled `fesm2022` output and type declarations.
 >
-> **Stable line**: v2.3.x includes side-by-side **`calendars`**, **natural language input**, searchable **timezone selection dropdown UI**, dynamic range presets, and warning range highlighting. Versions **2.0.10** and **2.0.11** were broken and have been **unpublished**; use **v2.1.1+** or current **v3.0.3** on npm.
+> **Stable line**: v2.3.x includes side-by-side **`calendars`**, **natural language input**, searchable **timezone selection dropdown UI**, dynamic range presets, and warning range highlighting. Versions **2.0.10** and **2.0.11** were broken and have been **unpublished**; use **v2.1.1+** or current **v3.0.4** on npm.
 
 ---
 
@@ -186,7 +188,7 @@ ng add ngxsmk-datepicker
 The `ng add` schematic installs the package, adds the `luxon` peer dependency if it is missing, and prints a getting-started snippet. Plain npm works too:
 
 ```bash
-npm install ngxsmk-datepicker@3.0.3
+npm install ngxsmk-datepicker@3.0.4
 ```
 
 ### Alternative installation
@@ -195,12 +197,12 @@ You can install without npm using any of these methods (peer dependencies must s
 
 | Method | Command |
 |--------|--------|
-| **Yarn** | `yarn add ngxsmk-datepicker@3.0.3` |
-| **pnpm** | `pnpm add ngxsmk-datepicker@3.0.3` |
-| **Bun** | `bun add ngxsmk-datepicker@3.0.3` |
-| **From Git** | `npm install github:NGXSMK/ngxsmk-datepicker#v3.0.3` (requires the repo to have built output or you build from source) |
+| **Yarn** | `yarn add ngxsmk-datepicker@3.0.4` |
+| **pnpm** | `pnpm add ngxsmk-datepicker@3.0.4` |
+| **Bun** | `bun add ngxsmk-datepicker@3.0.4` |
+| **From Git** | `npm install github:NGXSMK/ngxsmk-datepicker#v3.0.4` (requires the repo to have built output or you build from source) |
 | **Local path** | Build the library in the repo (`npx ng build ngxsmk-datepicker`), then `npm install /path/to/ngxsmk-datepicker/dist/ngxsmk-datepicker` |
-| **CDN (ESM)** | Use [unpkg](https://unpkg.com/ngxsmk-datepicker@3.0.3/) or [jsDelivr](https://cdn.jsdelivr.net/npm/ngxsmk-datepicker@3.0.3/) in your bundler or import map; peer dependencies (Angular, etc.) must be installed in your app. |
+| **CDN (ESM)** | Use [unpkg](https://unpkg.com/ngxsmk-datepicker@3.0.4/) or [jsDelivr](https://cdn.jsdelivr.net/npm/ngxsmk-datepicker@3.0.4/) in your bundler or import map; peer dependencies (Angular, etc.) must be installed in your app. |
 
 For all options and caveats, see [docs/INSTALLATION.md](docs/INSTALLATION.md).
 
@@ -540,6 +542,38 @@ By default, the datepicker input is `readonly` to prevent invalid date strings a
 2. **Custom Validation Logic:**
    If you prefer the readonly behavior, ensure your form submission handler explicitly checks `form.invalid` before proceeding, as the browser won't stop the submit button click.
 
+### **Built-in Reactive Forms Validators**
+
+`ngxsmk-datepicker` exports convenient, type-safe Angular `ValidatorFn` functions for standard form validation:
+
+```typescript
+import { FormControl, FormGroup } from '@angular/forms';
+import {
+  ngxsmkMinDateValidator,
+  ngxsmkMaxDateValidator,
+  ngxsmkDateRangeValidator,
+  ngxsmkBlockedDatesValidator
+} from 'ngxsmk-datepicker';
+
+const form = new FormGroup({
+  // Minimum date validator (Date, string, or dynamic factory)
+  arrivalDate: new FormControl(null, [ngxsmkMinDateValidator(new Date())]),
+
+  // Maximum date validator
+  departureDate: new FormControl(null, [ngxsmkMaxDateValidator(new Date(2026, 11, 31))]),
+
+  // Range validation: requires both dates, 2 to 14 days duration
+  tripRange: new FormControl(null, [
+    ngxsmkDateRangeValidator({ minDays: 2, maxDays: 14, requireBoth: true })
+  ]),
+
+  // Disallow weekends or specific blackout dates
+  bookingDate: new FormControl(null, [
+    ngxsmkBlockedDatesValidator((d: Date) => d.getDay() === 0 || d.getDay() === 6)
+  ]),
+});
+```
+
 ## **⚙️ API Reference**
 
 ### **Inputs**
@@ -550,7 +584,8 @@ By default, the datepicker input is `readonly` to prevent invalid date strings a
 | inline             | boolean \| 'always' \| 'auto' | false | Controls the display mode. `true` or `'always'` for inline, `'auto'` for responsive. |
 | locale             | string | navigator.language | Sets the locale for language and regional formatting (e.g., 'en-US', 'de-DE'). |
 | theme              | 'light' \| 'dark' | 'light' | The color theme. |
-| showRanges         | boolean | true | If true, displays the predefined ranges panel when in 'range' mode. |
+| showRanges         | boolean | true | If true, displays custom predefined ranges panel when in 'range' mode. |
+| showPresets        | boolean | false | If true, displays standard quick presets (*Today*, *Yesterday*, *Last 7 Days*, *This Month*, etc.). |
 | minDate            | DateInput | null | The earliest selectable date. |
 | maxDate            | DateInput | null | The latest selectable date. |
 | isInvalidDate      | (date: Date) => boolean | () => false | A function to programmatically disable specific dates. |
@@ -928,7 +963,7 @@ We welcome and appreciate contributions from the community! Whether it's reporti
 
 ## **📄 Changelog**
 
-**Recent:** Use **v3.0.3** on npm. The v2.3.x line adds side-by-side multi-calendar layouts, natural language typing, timezone selector UI dropdown, warning style selections, and strict TypeScript/AOT stability. Versions 2.0.10 and 2.0.11 are unpublished; use v2.1.1+ or **v3.0.3**.
+**Recent:** Use **v3.0.4** on npm. The v2.3.x line adds side-by-side multi-calendar layouts, natural language typing, timezone selector UI dropdown, warning style selections, and strict TypeScript/AOT stability. Versions 2.0.10 and 2.0.11 are unpublished; use v2.1.1+ or **v3.0.4**.
 
 For the full list of changes, see [CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md).
 
@@ -960,15 +995,20 @@ The hosted **[live demo](https://ngxsmk.github.io/ngxsmk-datepicker/)** build sh
 
 - 📧 Email: [sachindilshan040@gmail.com](mailto:sachindilshan040@gmail.com)
 - 🐙 GitHub: [@toozuuu](https://github.com/toozuuu)
+- 💬 WhatsApp Channel: [NGXSMK Channel](https://whatsapp.com/channel/0029Vb8PWpz1XquUOnGPUM2p)
 - 📦 NPM: [ngxsmk-datepicker](https://www.npmjs.com/package/ngxsmk-datepicker)
 - 🌐 Website: [sachindilshan.com](https://www.sachindilshan.com/)
 - 💼 LinkedIn: [sachindilshan](https://www.linkedin.com/in/sachindilshan/)
 
-## **⭐ Support**
+## **⭐ Community & Support**
+
+Stay connected and receive updates, release announcements, and tips via our official WhatsApp Channel:
+👉 **[Join WhatsApp Channel](https://whatsapp.com/channel/0029Vb8PWpz1XquUOnGPUM2p)**
 
 If you find this library helpful, please consider:
 
 - ⭐ **Starring** the repository
+- 💬 **Joining** our [WhatsApp Channel](https://whatsapp.com/channel/0029Vb8PWpz1XquUOnGPUM2p)
 - 🐛 **Reporting** bugs and issues
 - 💡 **Suggesting** new features
 - 🤝 **Contributing** code improvements