ngxsmk-datepicker 2.2.15 → 2.3.0-beta.0

package/CHANGELOG.md

@@ -2,14 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.14
+**Last updated:** May 19, 2026 - **Current stable:** v2.3.0
 
 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.2.14] - 2026-05-19
+## [2.3.0] - 2026-05-19
 
 ### Added
 
@@ -25,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Unnecessary Type Assertions Cleanup**: Cleaned up dozens of redundant type assertions (e.g. `as keyof DatepickerTranslations`, `as HTMLElement`, `as DatepickerValue`, `as EventListenerOptions`) to fully align with standard Angular strict compiler guidelines and eliminate all IDE compiler warnings.
 - **Spec Styling Overhaul**: Refactored the test suite to move the `createMockEvent` helper to the top-level outer scope and transitioned elements cleanup to the modern `insideNode.remove()` native DOM standard.
 
-## [2.2.13] - 2026-05-06
+## [2.3.0] - 2026-05-06
 
 ### Fixed
 
@@ -51,7 +51,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- **npm package**: The `2.2.12` tarball on the registry omitted `fesm2022/` and `types/` (only docs, styles, and package metadata). **Use `ngxsmk-datepicker@2.2.11` until `2.2.13` or later** with a full ng-packagr build ([#230](https://github.com/NGXSMK/ngxsmk-datepicker/issues/230)).
+- **npm package**: The `2.2.12` tarball on the registry omitted `fesm2022/` and `types/` (only docs, styles, and package metadata). **Use `ngxsmk-datepicker@2.2.11` until `2.3.0` or later** with a full ng-packagr build ([#230](https://github.com/NGXSMK/ngxsmk-datepicker/issues/230)).
 
 ## [2.2.11] - 2026-03-24
 

package/MIGRATION.md

@@ -2,7 +2,7 @@
 
 This document provides migration instructions for upgrading between major versions of ngxsmk-datepicker.
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.14
+**Last updated:** May 19, 2026 - **Current stable:** v2.3.0
 
 ## Table of Contents
 
@@ -60,10 +60,10 @@ This document provides migration instructions for upgrading between major versio
 
 ## 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.2.13`** (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.0`** (or newer) once published ([#230](https://github.com/NGXSMK/ngxsmk-datepicker/issues/230)).
 
 ```bash
-npm install ngxsmk-datepicker@2.2.13
+npm install ngxsmk-datepicker@2.3.0
 ```
 
 ## v2.2.7 → v2.2.11
@@ -77,7 +77,7 @@ npm install ngxsmk-datepicker@2.2.13
 No breaking changes.
 
 ```bash
-npm install ngxsmk-datepicker@2.2.13
+npm install ngxsmk-datepicker@2.3.0
 ```
 
 ## v2.2.6 → v2.2.7
@@ -92,7 +92,7 @@ npm install ngxsmk-datepicker@2.2.13
 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.2.13
+npm install ngxsmk-datepicker@2.3.0
 ```
 
 ## v2.2.3 → v2.2.6

package/README.md

@@ -11,6 +11,7 @@
 ### _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)
@@ -19,21 +20,23 @@
 
 **`npm i ngxsmk-datepicker`**
 
-[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)
+[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`).
 
 </div>
 
 ---
 
-**Last updated:** May 19, 2026 - **Current stable:** v2.2.15
+**Last updated:** May 19, 2026 - **Current stable:** v2.3.0
 
 ### **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.2.15` is the current stable release with compiled `fesm2022` output and type declarations.
+> **Stable Release**: `v2.3.0` is the current stable release with compiled `fesm2022` output and type declarations.
 >
-> **Stable line**: v2.2.x includes **`allowSameDay`**, **IANA timezone** support, validation fixes, and strict TypeScript improvements. Versions **2.0.10** and **2.0.11** were **unpublished**; use **v2.1.1+** or **v2.2.15** on npm.
+> **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.
 
 ---
 
@@ -41,14 +44,16 @@
 
 1. [📷 Screenshots](#-screenshots)
 2. [✨ Features](#-features)
-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)
+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)
 
 ---
 
@@ -67,7 +72,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.
-- 🧩 **Zero Dependencies**: Lightweight standalone component with no external bloat.
+- 🧩 **Minimal footprint**: Standalone component; **Luxon** is the only date peer beyond Angular (no full UI suite required).
 - ⚡ **Performance++**: Lazy-loaded calendar months, memoized calculations, and tree-shakable architecture.
 
 ### **Advanced Functionality**
@@ -79,6 +84,27 @@
 - 🚀 **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).
@@ -137,21 +163,30 @@ Features marked as experimental may change:
 
 For details, see [CONTRIBUTING.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CONTRIBUTING.md#deprecation-policy).
 
-## **🚀 Installation**
-
-Install the package using npm:
+## **📦 Installation**
 
 ```bash
-npm install ngxsmk-datepicker@latest
+npm install ngxsmk-datepicker@2.3.0
 ```
 
 ### Alternative installation
 
-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.
+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).
 
 ## **Usage**
 
-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>`).
+ngxsmk-datepicker is a standalone component, so you can import it directly into your component or module.
 
 ### Signal Forms (Angular 21)
 
@@ -221,7 +256,7 @@ For detailed Signal Forms integration including dirty state tracking, see the [S
 
 #### **1. Import the Component**
 
-In your component file (e.g., app.component.ts), import NgxsmkDatepickerComponent.
+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).
 
     import { Component } from '@angular/core';
     import { NgxsmkDatepickerComponent, DateRange, HolidayProvider } from 'ngxsmk-datepicker';
@@ -251,6 +286,8 @@ In your component file (e.g., app.component.ts), import NgxsmkDatepickerComponen
       }
     }
 
+**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.
@@ -331,7 +368,7 @@ export class MaterialFormComponent {
 }
 ```
 
-**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.
+**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.
 
 **With Date Range:**
 
@@ -350,6 +387,9 @@ 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
@@ -593,14 +633,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**
 
@@ -665,7 +705,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.
+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.
 
 See [Extension Points Guide](./projects/ngxsmk-datepicker/docs/extension-points.md) for detailed customization options.
 
@@ -690,11 +730,14 @@ 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
-- ✅ **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
+- ✅ **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
 
 ### **Performance Enhancements:**
 
@@ -848,13 +891,9 @@ We welcome and appreciate contributions from the community! Whether it's reporti
 
 ## **📄 Changelog**
 
-For a full list of changes, please refer to the [CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md) file.
-
-### **v2.2.15** (Current Stable)`r`n`r`n- **npm**: Published tarballs include compiled `fesm2022/` output and type declarations.
+**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**.
 
-### **Earlier Versions**
-
-For older version details, please refer to the [full CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md).
+For the full list of changes, see [CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md).
 
 ## **🎨 Theming with TokiForge**
 
@@ -862,11 +901,6 @@ 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!
@@ -879,19 +913,9 @@ 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 & Discoverability**
-
-This library is optimized for search engine visibility, especially for European markets:
+## **🔍 SEO (demo site)**
 
-- **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
+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.
 
 ## **👨‍💻 Author**