ngxsmk-datepicker 2.3.0-beta.0 → 2.3.1

package/CHANGELOG.md

@@ -2,23 +2,29 @@
 
 All notable changes to this project will be documented in this file.
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.3.0
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 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]
 
-## [2.3.0] - 2026-05-19
+## [2.3.1] - 2026-06-03
 
 ### Added
 
+- **Natural Language Input**: Integrated a lightweight, zero-dependency parser engine that resolves text expressions like "today", "tomorrow", relative day/week offsets, and quarter descriptors. Features a dynamic preview suggestion tooltip beneath the input field.
+- **Multi-Calendar View**: Supported side-by-side calendar renders via `[calendars]="2"` or `[calendars]="3"` inputs, with seamless range highlights extending across all month boundaries.
+- **Dynamic Presets Factory**: Introduced the `[rangePresetFactory]` callback input allowing developers to supply dynamic rolling ranges (e.g., fiscal quarters or rolling business-day windows).
+- **Invalid Range Warning**: Highlights ranges with a warning style if a disabled date falls inside the selected range, emitting details via the `(invalidRange)` output.
+- **Timezone Selector UI**: Added a searchable timezone dropdown via `[showTimezoneSelector]="true"` input, with timezone change values emitted via the `(timezoneChange)` output.
 - **Shadow DOM Compatibility (Issue #268)**: Added full, native support for running inside Angular Shadow DOM containers (`ViewEncapsulation.ShadowDom`) and Custom Web Components.
   - Interaction listeners now query and utilize `event.composedPath()` to correctly identify clicked targets originating inside the component shadow boundary, preventing calendar dropdowns and header custom selects from closing prematurely due to event target retargeting.
   - Added new comprehensive Shadow DOM unit test suite (`shadow-dom-compatibility.spec.ts`).
 
 ### Changed
 
+- **AOT & AoT Compilation Boundaries**: Refactored internal component signals (`_isCalendarOpen`, `_currentMonthSignal`, and `_currentYearSignal`) to `protected` access modifiers to prevent strict production AoT compilation errors.
 - **Code Quality & Cognitive Complexity Reductions**:
   - Flattened highly nested condition structures in `CustomSelectComponent.onDocumentTouchStart()`, reducing cognitive complexity to well below the limit of 15.
   - Decomposed monolithic date check inside `NgxsmkDatepickerComponent.containsNode()` into private helper functions (`containsNodeViaComposedPath`, `containsNodeViaDOM`), drastically improving maintainability and reducing complexity down to 2.

package/MIGRATION.md

@@ -2,10 +2,11 @@
 
 This document provides migration instructions for upgrading between major versions of ngxsmk-datepicker.
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.3.0
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 ## Table of Contents
 
+- [v2.2.15 → v2.3.1](#v2215---v231)
 - [v2.2.7 → v2.2.11](#v227---v228)
 - [v2.2.6 → v2.2.7](#v226---v227)
 - [v2.2.3 → v2.2.6](#v223---v226)
@@ -58,12 +59,30 @@ 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)
 
+## v2.2.15 → v2.3.1
+
+### Changes
+
+- **Natural Language Input**: Standard text inputs can now resolve relative expressions (e.g. "today", "tomorrow", relative day/week/month/year offsets, quarter descriptors). Controlled via `[enableNaturalLanguage]` and emits via `(naturalLanguageResolved)`.
+- **Multi-Calendar Layouts**: Support for showing 2 or 3 calendars side-by-side via `[calendars]`.
+- **Dynamic Presets**: Supply a custom preset callback via `[rangePresetFactory]`.
+- **Timezone Selection**: Searchable timezone selection dropdown via `[showTimezoneSelector]`.
+- **Range Warnings**: Emits `(invalidRange)` if a range contains disabled dates.
+
+### Migration Steps
+
+No breaking changes. Upgrade with:
+
+```bash
+npm install ngxsmk-datepicker@2.3.1
+```
+
 ## npm: skip v2.2.12
 
-The **`2.2.12`** package on the registry is missing **`fesm2022/`** and **`types/`**. Stay on **`2.2.11`** or upgrade to **`2.3.0`** (or newer) once published ([#230](https://github.com/NGXSMK/ngxsmk-datepicker/issues/230)).
+The **`2.2.12`** package on the registry is missing **`fesm2022/`** and **`types/`**. Stay on **`2.2.11`** or upgrade to **`2.3.1`** (or newer) once published ([#230](https://github.com/NGXSMK/ngxsmk-datepicker/issues/230)).
 
 ```bash
-npm install ngxsmk-datepicker@2.3.0
+npm install ngxsmk-datepicker@2.3.1
 ```
 
 ## v2.2.7 → v2.2.11
@@ -77,7 +96,7 @@ npm install ngxsmk-datepicker@2.3.0
 No breaking changes.
 
 ```bash
-npm install ngxsmk-datepicker@2.3.0
+npm install ngxsmk-datepicker@2.3.1
 ```
 
 ## v2.2.6 → v2.2.7
@@ -92,7 +111,7 @@ npm install ngxsmk-datepicker@2.3.0
 No breaking changes. Use **2.2.11** on npm (the `2.2.7` npm package was incomplete; 2.2.11 matches the intended 2.2.7 release).
 
 ```bash
-npm install ngxsmk-datepicker@2.3.0
+npm install ngxsmk-datepicker@2.3.1
 ```
 
 ## v2.2.3 → v2.2.6

package/README.md

@@ -11,7 +11,6 @@
 ### _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)
-[![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)
 [![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)
@@ -20,23 +19,21 @@
 
 **`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)
-
-*StackBlitz:* after it boots, run `npm install` then `npm start` in the terminal to serve the demo app (`demo-app`).
+[Explore Live Demo](https://ngxsmk.github.io/ngxsmk-datepicker/) • [Buy me a coffee](https://buymeacoffee.com/toozuuu) • [API Documentation](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/projects/ngxsmk-datepicker/docs/API.md) • [Submit Issue](https://github.com/NGXSMK/ngxsmk-datepicker/issues)
 
 </div>
 
 ---
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.3.0
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 ### **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**: `v2.3.0` is the current stable release with compiled `fesm2022` output and type declarations.
+> **Stable Release**: `v2.3.1` is the current stable release with compiled `fesm2022` output and type declarations.
 >
-> **Stable line**: v2.2.x includes range-mode **`allowSameDay`**, **IANA timezone** support, validation fixes, and strict TypeScript improvements. Versions **2.0.10** and **2.0.11** were broken and have been **unpublished**; use **v2.1.1+** or current **v2.3.0** 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 **v2.3.1** on npm.
 
 ---
 
@@ -44,16 +41,14 @@
 
 1. [📷 Screenshots](#-screenshots)
 2. [✨ Features](#-features)
-3. [🤔 Why this library?](#why-this-library)
-4. [🌐 Discoverability](#-discoverability)
-5. [📋 Compatibility](#-compatibility)
-6. [🌍 Localization (i18n)](#-localization-i18n)
-7. [📦 Installation](#-installation)
-8. [🚀 Quick start / usage](#usage)
-9. [🔌 Framework Integration](#-framework-integration)
-10. [⚙️ API Reference](#-api-reference)
-11. [🎨 Theming](#-theming)
-12. [⌨️ Keyboard Navigation](#-keyboard-navigation)
+3. [📋 Compatibility](#-compatibility)
+4. [🌍 Localization (i18n)](#-localization-i18n)
+5. [📦 Installation](#-installation)
+6. [🚀 Quick Start](#-quick-start)
+7. [🔌 Framework Integration](#-framework-integration)
+8. [⚙️ API Reference](#-api-reference)
+9. [🎨 Theming](#-theming)
+10. [⌨️ Keyboard Navigation](#-keyboard-navigation)
 
 ---
 
@@ -72,7 +67,7 @@
 - 💎 **Signal-Driven Engine**: Hyper-reactive state management using Angular Signals.
 - 🌓 **Native Dark Mode**: Beautifully crafted themes for light and dark environments.
 - 📱 **Mobile-First UX**: Native mobile picker integration with touch gestures and haptic feedback.
-- 🧩 **Minimal footprint**: Standalone component; **Luxon** is the only date peer beyond Angular (no full UI suite required).
+- 🧩 **Zero Dependencies**: Lightweight standalone component with no external bloat.
 - ⚡ **Performance++**: Lazy-loaded calendar months, memoized calculations, and tree-shakable architecture.
 
 ### **Advanced Functionality**
@@ -84,27 +79,6 @@
 - 🚀 **Zoneless Ready**: Optimized for the future of Angular—works perfectly without zone.js.
 - ♿ **Full Accessibility**: WAI-ARIA compliant with extensive keyboard navigation support.
 
-## Why this library?
-
-Use **ngxsmk-datepicker** when you want a focused **date / range picker** with strong **mobile**, **i18n**, **timezone**, and **SSR** story on **Angular 17+**, without adopting a full Material UI stack. It is a **standalone** component with **Luxon** as the single date peer (plus Angular).
-
-| | ngxsmk-datepicker | Angular Material datepicker |
-| --- | --- | --- |
-| **Fit** | Picker-first; optional Material/CDK peers for overlays only | Part of Material; best when you already use Material forms & CDK |
-| **Peer deps** | Angular + **Luxon** | **@angular/material** + **@angular/cdk** |
-| **Forms** | Template-driven, Reactive Forms, Signals; **Signal Forms** (`[field]`) on Angular 21+ | Reactive + template-driven; integrates with Material form field |
-| **Stack** | Tree-shakable package aimed at picker scenarios | Broader design system and bundle footprint |
-
-This is **not** a drop-in replacement for every Material datepicker API; choose based on whether you need **Material’s form-field ecosystem** or a **standalone picker** you can theme and ship with **zoneless** / **SSR** setups. See the [live demo](https://ngxsmk.github.io/ngxsmk-datepicker/) and [COMPATIBILITY](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/projects/ngxsmk-datepicker/docs/COMPATIBILITY.md) for details.
-
-## **🌐 Discoverability**
-
-**Maintainers (GitHub):** consider repository **Topics** such as: `angular`, `datepicker`, `date-range-picker`, `luxon`, `standalone-components`, `i18n`, `angular-universal`, `ionic`, `accessibility`.
-
-**Community:** if this project helped you, stars and accurate comparisons in blog posts or issue threads help others find it. Curated lists (for example **awesome-angular**-style repos) usually accept small PRs that add a one-line link and follow their contribution rules—check each list’s guidelines before opening a PR.
-
-**Security:** report sensitive issues per [SECURITY.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/SECURITY.md), not via public issues.
-
 ## **📋 Compatibility**
 
 For detailed compatibility information, see [COMPATIBILITY.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/projects/ngxsmk-datepicker/docs/COMPATIBILITY.md).
@@ -163,30 +137,21 @@ Features marked as experimental may change:
 
 For details, see [CONTRIBUTING.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CONTRIBUTING.md#deprecation-policy).
 
-## **📦 Installation**
+## **🚀 Installation**
+
+Install the package using npm:
 
 ```bash
-npm install ngxsmk-datepicker@2.3.0
+npm install ngxsmk-datepicker@latest
 ```
 
 ### Alternative installation
 
-You can install without npm using any of these methods (peer dependencies must still be installed in your app):
-
-| Method | Command |
-|--------|--------|
-| **Yarn** | `yarn add ngxsmk-datepicker@2.3.0` |
-| **pnpm** | `pnpm add ngxsmk-datepicker@2.3.0` |
-| **Bun** | `bun add ngxsmk-datepicker@2.3.0` |
-| **From Git** | `npm install github:NGXSMK/ngxsmk-datepicker#v2.3.0` (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@2.3.0/) or [jsDelivr](https://cdn.jsdelivr.net/npm/ngxsmk-datepicker@2.3.0/) 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).
+You can install without npm using Yarn, pnpm, Bun, from Git, a local path, or via CDN (ESM). Peer dependencies must still be installed in your app. For all options and caveats, see [INSTALLATION.md](../../docs/INSTALLATION.md) in the repo root.
 
 ## **Usage**
 
-ngxsmk-datepicker is a standalone component, so you can import it directly into your component or module.
+ngxsmk-datepicker is a standalone component, so you can import it directly into your component or module. If you see **NG1010** (`'imports' must be an array... Value could not be determined statically`) when using the Angular compiler plugin or in strict AOT builds, use `NgxsmkDatepickerModule` in your `imports` array instead of `NgxsmkDatepickerComponent` (same template: `<ngxsmk-datepicker>`).
 
 ### Signal Forms (Angular 21)
 
@@ -256,7 +221,7 @@ For detailed Signal Forms integration including dirty state tracking, see the [S
 
 #### **1. Import the Component**
 
-All public exports (component, utilities, types, services) come from the main package entry: `'ngxsmk-datepicker'` (there is no separate `/utils` subpath). In your component file (e.g., app.component.ts), import the component (or the module—see troubleshooting below).
+In your component file (e.g., app.component.ts), import NgxsmkDatepickerComponent.
 
     import { Component } from '@angular/core';
     import { NgxsmkDatepickerComponent, DateRange, HolidayProvider } from 'ngxsmk-datepicker';
@@ -286,8 +251,6 @@ All public exports (component, utilities, types, services) come from the main pa
       }
     }
 
-**If you see NG1010** (`'imports' must be an array... Value could not be determined statically`) when using the Angular compiler plugin or in strict AOT builds, use the wrapper module instead: `import { NgxsmkDatepickerModule } from 'ngxsmk-datepicker'` and set `imports: [NgxsmkDatepickerModule]`. The template stays the same (`<ngxsmk-datepicker>`).
-
 #### **2. Add it to Your Template**
 
 Use the `<ngxsmk-datepicker>` selector in your HTML template.
@@ -368,7 +331,7 @@ export class MaterialFormComponent {
 }
 ```
 
-**Non-Standalone (NgModules):** Add the directive file from [INTEGRATION.md § Angular Material](projects/ngxsmk-datepicker/docs/INTEGRATION.md#angular-material), then add it to your module `imports` (with `NgxsmkDatepickerComponent`, `MatFormFieldModule`, etc.) and use `ngxsmkMatFormFieldControl` on the datepicker in templates.
+**Non-Standalone (NgModules):** Add the directive file from [INTEGRATION.md § Angular Material](docs/INTEGRATION.md#angular-material), then add it to your module `imports` (with `NgxsmkDatepickerComponent`, `MatFormFieldModule`, etc.) and use `ngxsmkMatFormFieldControl` on the datepicker in templates.
 
 **With Date Range:**
 
@@ -387,9 +350,6 @@ For best integration with Ionic, import the integration styles in your global CS
 @import "ngxsmk-datepicker/styles/ionic-integration.css";
 ```
 
-**Automatic Theming:**
-The datepicker automatically detects and uses Ionic CSS variables (e.g., `--ion-color-primary`, `--ion-background-color`) so it matches your app's theme out of the box without extra configuration.
-
 Works seamlessly with Ionic form components and follows Ionic design patterns:
 
 ```typescript
@@ -558,6 +518,10 @@ By default, the datepicker input is `readonly` to prevent invalid date strings a
 | classes            | object | undefined | Tailwind-friendly class overrides (wrapper, input, popover, etc.). |
 | enableGoogleCalendar| boolean | false | Enable seamless Google Calendar integration and sync. |
 | googleClientId     | string \| null | null | Google API OAuth 2.0 Web Client ID for authentication. |
+| calendars          | number | 1 | Multi-calendar display layout (supports 1, 2, or 3 side-by-side calendars). |
+| rangePresetFactory | (today: Date) => DatePreset[] | null | Callback function supplying dynamic rolling range presets. |
+| showTimezoneSelector | boolean | false | Enables searchable IANA timezone selection dropdown UI. |
+| enableNaturalLanguage | boolean | false | Enables manual relative keyboard typing input (e.g. "today", "in 3 days"). |
 
 ### **Outputs**
 
@@ -566,6 +530,9 @@ By default, the datepicker input is `readonly` to prevent invalid date strings a
 | valueChange | DatepickerValue                 | Emits the newly selected date, range, or array of dates.      |
 | action      | { type: string; payload?: any } | Emits various events like `dateSelected`, `timeChanged`, etc. |
 | googleSyncClick | void                          | Emitted when the user clicks the Google Calendar sync button. |
+| invalidRange | { start: Date; end: Date; disabledDatesInside: Date[] } | Emitted when selected date range contains disabled dates. |
+| naturalLanguageResolved | Date \| { start: Date; end: Date } | Emitted when user types relative natural language date input. |
+| timezoneChange | string | Emitted when timezone selection is changed. |
 
 ## **🎨 Theming**
 
@@ -633,14 +600,14 @@ The `locale` input controls all internationalization. It automatically formats m
 
 ngxsmk-datepicker v2.2.x now features **full localization synchronization** for:
 
-- �� English (`en`)
-- �� German (`de`)
-- �� French (`fr`)
-- �� Spanish (`es`)
+- 🇺🇸 English (`en`)
+- 🇩🇪 German (`de`)
+- 🇫🇷 French (`fr`)
+- 🇪🇸 Spanish (`es`)
 - 🇸🇪 Swedish (`sv`)
-- �� Korean (`ko`)
-- �� Chinese (`zh`)
-- �� Japanese (`ja`)
+- 🇰🇷 Korean (`ko`)
+- 🇨🇳 Chinese (`zh`)
+- 🇯🇵 Japanese (`ja`)
 
 ### **Usage Example**
 
@@ -705,7 +672,7 @@ const myHooks: DatepickerHooks = {
 <ngxsmk-datepicker [hooks]="myHooks" [customShortcuts]="shortcuts" mode="single"> </ngxsmk-datepicker>
 ```
 
-All date cells are keyboard accessible with proper ARIA attributes for screen readers. The component is built with **accessibility in mind**: keyboard navigation, ARIA roles and labels, and live regions for announcements. For details see [API.md – Keyboard Support](projects/ngxsmk-datepicker/docs/API.md#keyboard-support) and the ARIA-related inputs (e.g. `closeAriaLabel`, `clearAriaLabel`) in the API reference.
+All date cells are keyboard accessible with proper ARIA attributes for screen readers.
 
 See [Extension Points Guide](./projects/ngxsmk-datepicker/docs/extension-points.md) for detailed customization options.
 
@@ -730,14 +697,11 @@ This library has been optimized for maximum performance:
 - ✅ **Date Validation**: Fixed "Today" unselectable bug by normalizing `minDate` boundary checks.
 - ✅ **Keyboard Shortcuts**: Updated "Today" selection shortcut to use timezone-aware calculation.
 - ✅ **Validation messages**: User-facing i18n strings for invalid date, min/max; `validationError` output and on-screen error display
-- ✅ **Change Detection**: Fixed OnPush change detection issues with proper `markForCheck()` triggers
-- ✅ **Date Comparison**: Fixed null safety issues in date range comparisons
-- ✅ **Memory Leaks**: Added cache size limits to prevent memory leaks
-- ✅ **Type Safety**: Improved TypeScript types and null safety checks
-- ✅ **Mobile UX**: Enhanced mobile interactions and touch feedback
-- ✅ **Performance**: Optimized template bindings with memoized functions
-- ✅ **Accessibility**: Better focus states and keyboard navigation
-- ✅ **Build System**: Improved build configuration and optimization
+- ✅ **Calendar loading state**: Visual spinner + text and screen-reader announcement while calendar opens/generates
+- ✅ **Demo theme**: Light/dark theme toggle and system preference now correctly switch the demo UI
+- ✅ **Installation options**: Full install guide (npm, Yarn, pnpm, Bun, Git, CDN, etc.) and demo page updates
+- ✅ **Accessibility**: Loading state announced via live region; validation errors exposed for a11y
+- ✅ **Type Safety**: New translation keys and strictly typed inputs/outputs
 
 ### **Performance Enhancements:**
 
@@ -891,9 +855,13 @@ We welcome and appreciate contributions from the community! Whether it's reporti
 
 ## **📄 Changelog**
 
-**Recent:** Use **v2.3.0** on npm. The v2.2.x line adds `allowSameDay` range mode, IANA timezone support, TypeScript strictness, appendToBody/popover fixes, and CSS cleanup. Versions 2.0.10 and 2.0.11 are unpublished; use v2.1.1+ or **v2.3.0**.
+For a full list of changes, please refer to the [CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md) file.
+
+### **v2.3.1** (Current Stable)`r`n`r`n- **npm**: Published tarballs include compiled `fesm2022/` output and type declarations.
 
-For the full list of changes, see [CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md).
+### **Earlier Versions**
+
+For older version details, please refer to the [full CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md).
 
 ## **🎨 Theming with TokiForge**
 
@@ -901,6 +869,11 @@ Looking for a powerful theming solution for your Angular application? Check out
 
 ### Why TokiForge?
 
+- ✅ **Framework-agnostic** — Works with Angular, React, Vue, Svelte, and vanilla JS
+- ✅ **Runtime theme switching** — Change themes dynamically without rebuilds
+- ✅ **Type-safe** — Full TypeScript support for design tokens
+- ✅ **Lightweight** — <3 KB gzipped runtime footprint
+- ✅ **CSS custom properties** — Zero JS overhead in static mode
 - ✅ **SSR compatible** — Works seamlessly with Angular Universal
 
 Perfect for managing design tokens, creating theme systems, and implementing dark mode in your Angular applications!
@@ -913,9 +886,19 @@ Perfect for managing design tokens, creating theme systems, and implementing dar
 
 MIT License - see [LICENSE](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/LICENSE) file for details.
 
-## **🔍 SEO (demo site)**
+## **🔍 SEO & Discoverability**
+
+This library is optimized for search engine visibility, especially for European markets:
 
-The hosted **[live demo](https://ngxsmk.github.io/ngxsmk-datepicker/)** build ships with meta tags (Open Graph, Twitter cards, `hreflang`, structured data) and locale-aware content for broader discovery. For **GitHub/npm** visibility—topics, awesome lists, StackBlitz, and security reporting—see [**Discoverability**](#-discoverability) near the top of this README.
+- **Keywords**: Angular datepicker, date range picker, calendar component, Angular 17-21, TypeScript, Signal Forms, SSR compatible
+- **European SEO**: Optimized for Germany, France, Spain, Italy, Netherlands, Poland, Portugal, Sweden, Norway, Finland, Denmark, Belgium, Switzerland, Austria, and United Kingdom
+- **Multi-language Support**: hreflang tags for 15+ European languages and locales
+- **European Geo-targeting**: Geo tags and structured data optimized for European Union countries
+- **Meta Tags**: Comprehensive Open Graph and Twitter Card support with European locale alternates
+- **Structured Data**: JSON-LD schema markup with European audience targeting and area served information
+- **Documentation**: Complete API documentation with examples
+- **Performance**: Optimized bundle size (~127KB) for fast loading
+- **European Localization**: Full i18n support for European date formats, week start days, and regional preferences
 
 ## **👨‍💻 Author**
 

package/docs/API.md

@@ -2,7 +2,7 @@
 
 This document describes the stable public API of ngxsmk-datepicker with comprehensive real-world examples. APIs marked as **stable** are guaranteed to remain backward-compatible within the same major version. APIs marked as **experimental** may change in future releases.
 
-**Version**: 2.2.15+ | **Last updated**: March 21, 2026
+**Version**: 2.3.1+ | **Last updated**: June 3, 2026
 
 ## Stable vs experimental
 
@@ -102,6 +102,10 @@ import { NgxsmkDatepickerComponent } from 'ngxsmk-datepicker';
 | `enableHapticFeedback` | `boolean` | `false` | Stable | Trigger haptic feedback on supported devices when selecting/clearing. | `[enableHapticFeedback]="true"` |
 | `enablePullToRefresh` | `boolean` | `false` | Experimental | Reserve for future pull-to-refresh on mobile. | — |
 | `enableVoiceInput` | `boolean` | `false` | Experimental | Reserve for future voice input. | — |
+| `calendars` | `number` | `1` | Stable | Multi-calendar display layout (1, 2, or 3 months side-by-side) | `[calendars]="2"` |
+| `rangePresetFactory` | `(today: Date) => DatePreset[]` | `null` | Stable | Callback function supplying dynamic range presets | `[rangePresetFactory]="myPresetFactory"` |
+| `showTimezoneSelector` | `boolean` | `false` | Stable | Enables searchable timezone selection dropdown UI | `[showTimezoneSelector]="true"` |
+| `enableNaturalLanguage` | `boolean` | `false` | Stable | Enables relative natural language input parsing (e.g. "today", "tomorrow") | `[enableNaturalLanguage]="true"` |
 
 ##### Outputs
 
@@ -111,6 +115,9 @@ import { NgxsmkDatepickerComponent } from 'ngxsmk-datepicker';
 | `action` | `EventEmitter<{ type: string; payload?: any }>` | Stable | Emitted on user actions (dateSelected, timeChanged, etc.) | `(action)="handleAction($event)"` |
 | `googleSyncClick` | `EventEmitter<void>` | Stable | Emitted when the user clicks the Google Calendar sync button. | `(googleSyncClick)="onSyncClick()"` |
 | `validationError` | `EventEmitter<{ code: string; message: string }>` | Stable | Emitted when validation fails (e.g. invalid typed date, date before min, after max). Message is translated. | `(validationError)="onValidationError($event)"` |
+| `invalidRange` | `EventEmitter<{ start: Date; end: Date; disabledDatesInside: Date[] }>` | Stable | Emitted when selected date range contains disabled dates | `(invalidRange)="onInvalidRange($event)"` |
+| `naturalLanguageResolved` | `EventEmitter<Date \| { start: Date; end: Date }>` | Stable | Emitted when natural language input is parsed successfully | `(naturalLanguageResolved)="onResolved($event)"` |
+| `timezoneChange` | `EventEmitter<string>` | Stable | Emitted when timezone is changed via selector UI | `(timezoneChange)="onTimezoneChange($event)"` |
 
 #### Methods
 

package/docs/COMPATIBILITY.md

@@ -1,6 +1,6 @@
 # Version Compatibility Matrix
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 This document provides comprehensive compatibility information for `ngxsmk-datepicker` across different Angular versions, Zone.js configurations, and SSR/CSR setups.
 
@@ -468,3 +468,4 @@ Recommended validation before tagging a release:
 **Ionic/Capacitor sample**: The `examples/ionic-test-app` project may require `npm install --legacy-peer-deps` when Ionic’s peers lag Angular—see [examples/ionic-test-app/README.md](../../../examples/ionic-test-app/README.md).
 
 
+

package/docs/INTEGRATION.md

@@ -1,6 +1,6 @@
 # Integration Guides
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 This document provides integration examples for using ngxsmk-datepicker with popular frameworks and libraries.
 
@@ -700,3 +700,4 @@ See the demo app **Integrations** page for a full "Datepicker in a modal" exampl
 - [Locale Guide](./LOCALE-GUIDE.md)
 
 
+

package/docs/IONIC_INTEGRATION.md

@@ -1,6 +1,6 @@
 # Ionic Framework Integration Guide
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 This guide provides step-by-step instructions for integrating ngxsmk-datepicker with Ionic Angular applications.
 
@@ -225,3 +225,4 @@ export class DatepickerPage {
 - [Capacitor Keyboard Plugin](https://capacitorjs.com/docs/apis/keyboard)
 
 
+

package/docs/IONIC_TESTING.md

@@ -1,6 +1,6 @@
 # Ionic Integration Testing Guide
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 This document provides comprehensive testing instructions for verifying ngxsmk-datepicker compatibility with Ionic Framework.
 
@@ -145,3 +145,4 @@ jobs:
 4. **Report issues** with detailed information
 
 
+

package/docs/LOCALE-GUIDE.md

@@ -1,6 +1,6 @@
 # Locale Packs & i18n Contributor Guide
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 Guide for adding locale support and contributing translations to ngxsmk-datepicker.
 
@@ -297,3 +297,4 @@ If you encounter issues with a specific locale or want to contribute improvement
 **Thank you for contributing to ngxsmk-datepicker's internationalization!**
 
 
+

package/docs/PLUGIN-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Plugin Architecture
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 ngxsmk-datepicker features a powerful **plugin architecture** that allows you to extend and customize the component's behavior without modifying its core code. This architecture is built on a **hook-based system** that provides extension points throughout the component's lifecycle.
 
@@ -927,3 +927,4 @@ The plugin architecture in ngxsmk-datepicker provides:
 For more examples and detailed hook documentation, see [Extension Points Guide](./extension-points.md).
 
 
+

package/docs/SEO.md

@@ -1,6 +1,6 @@
 # SEO Optimization Guide
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 This document outlines the SEO optimizations implemented for ngxsmk-datepicker to improve search engine visibility and discoverability.
 
@@ -211,3 +211,4 @@ ngxsmk-datepicker has been optimized for search engines with comprehensive meta
 - [Web.dev SEO Guide](https://web.dev/learn/seo/)
 
 
+

package/docs/SSR-EXAMPLE.md

@@ -1,6 +1,6 @@
 # Server-Side Rendering (SSR) Example
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 Complete example demonstrating ngxsmk-datepicker with Angular Universal (SSR).
 
@@ -424,3 +424,4 @@ test('datepicker works after SSR hydration', async ({ page }) => {
 - [Platform Detection](https://angular.io/api/common/isPlatformBrowser)
 
 
+

package/docs/THEME-TOKENS.md

@@ -1,6 +1,6 @@
 # Theme Tokens & CSS Custom Properties
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 Complete reference for all CSS custom properties (CSS variables) available in ngxsmk-datepicker.
 
@@ -321,3 +321,4 @@ CSS custom properties are supported in all modern browsers:
 For older browsers, consider using a CSS custom properties polyfill or provide fallback values.
 
 
+

package/docs/TIMEZONE.md

@@ -1,6 +1,6 @@
 # Timezone Support
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 ## Overview
 
@@ -258,6 +258,19 @@ const date = new Date(serverResponse.dateString.replace('Z', '')); // Don't remo
 - **Description**: IANA timezone name for date formatting
 - **Example**: `'America/New_York'`, `'UTC'`, `'Europe/London'`
 
+### Input: `showTimezoneSelector`
+
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Enables a searchable timezone selection dropdown UI in the datepicker header.
+- **Example**: `[showTimezoneSelector]="true"`
+
+### Output: `timezoneChange`
+
+- **Type**: `EventEmitter<string>`
+- **Description**: Emitted when the user changes the active timezone via the selector UI.
+- **Example**: `(timezoneChange)="onTimezoneChange($event)"`
+
 ### Utility Functions
 
 The library exports timezone utility functions:

package/docs/extension-points.md

@@ -1,6 +1,6 @@
 # Extension Points and Hooks
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 ngxsmk-datepicker provides comprehensive extension points through the `hooks` input, allowing you to customize rendering, validation, keyboard shortcuts, formatting, and event handling.
 
@@ -416,3 +416,4 @@ import {
 ```
 
 
+

package/docs/signal-forms.md

@@ -1,6 +1,6 @@
 # Signal Forms Integration
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 This guide covers using ngxsmk-datepicker with Angular 21+ Signal Forms API.
 
@@ -597,3 +597,4 @@ If `form().dirty()` returns `false` after selecting a date:
 4. **Check dev console warnings**: In development mode, the datepicker logs warnings if it falls back to direct signal mutation, which may not track dirty state correctly.
 
 
+

package/docs/signals.md

@@ -1,6 +1,6 @@
 # Signals Integration Guide
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 ngxsmk-datepicker is fully compatible with Angular Signals, providing seamless integration with both traditional reactive forms and modern signal-based patterns.
 
@@ -263,3 +263,4 @@ dateSignal = signal<DatepickerValue>(null);
 The datepicker supports both patterns simultaneously, so you can migrate gradually.
 
 
+

package/docs/ssr.md

@@ -1,6 +1,6 @@
 # Server-Side Rendering (SSR) Guide
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
 
 ngxsmk-datepicker is fully compatible with Angular Universal and server-side rendering. This guide covers SSR setup, best practices, and troubleshooting.
 
@@ -302,3 +302,4 @@ export class SSRExampleComponent {
 - [Platform Detection](https://angular.dev/api/common/isPlatformBrowser)
 
 
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngxsmk-datepicker",
-  "version": "2.3.0-beta.0",
+  "version": "2.3.1",
   "description": "Lightweight, accessible date and range picker for Angular 17+. Standalone component, Signals, SSR and zoneless-ready, Luxon-based i18n and timezones.",
   "author": {
     "name": "Sachin Dilshan",