ngxsmk-datepicker 3.0.5-beta.0 → 3.0.6

package/README.md

@@ -12,7 +12,6 @@
 
 [![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)
@@ -22,23 +21,21 @@
 
 **`npm i ngxsmk-datepicker`**
 
-[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`).
+[Explore Live Demo](https://ngxsmk.github.io/ngxsmk-datepicker/) • [WhatsApp Channel](https://whatsapp.com/channel/0029Vb8PWpz1XquUOnGPUM2p) • [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:** August 22, 2026 - **Current stable:** v3.0.5
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 ### **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.5` is the current stable release with compiled `fesm2022` output and type declarations.
+> **Stable Release**: `v3.0.6` 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.5** 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.6** on npm.
 
 ---
 
@@ -46,16 +43,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)
 
 ---
 
@@ -74,7 +69,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**
@@ -83,17 +78,30 @@
 - 🗓️ **Adjacent Month Days (`showOtherMonths`)**: Display trailing and leading days from adjacent months in the calendar grid.
 - 📐 **Responsive Control (`[responsive]`)**: Disable viewport max-width responsive overrides for fixed-width container embedding (#299).
 - 🌐 **8-Language i18n**: Full localization for `en`, `de`, `es`, `sv`, `ko`, `zh`, `ja`, and `fr`.
-- 🔢 **ISO Week Numbers**: Optional week-number column via `[showWeekNumbers]`.
-- ⌨️ **Guided Input Masking**: `[inputMask]` auto-inserts separators as users type (e.g. `12` → `12/`).
-- 🌍 **Secondary Calendars**: Annotate day cells with Hijri, Jalali, Hebrew, Buddhist, or Japanese dates via `[secondaryCalendar]`.
-- 🏨 **Availability Calendars**: Per-day prices, indicator dots, and classes via `[dayMetadata]`; server-driven blocked dates via `[asyncDateFilter]`.
-- 🎛️ **Custom Action Bars**: `[calendarHeaderTemplate]` / `[calendarFooterTemplate]` slots with `clear()`/`close()` actions.
 - 🛠️ **Plugin Architecture**: Extend functionality via hooks for rendering, validation, and shortcuts.
-- 🤖 **Model Context Protocol (MCP) & AI Assistant**: Standalone MCP server (`@ngxsmk/datepicker-mcp`) with date intelligence tools, plus embedded UI AI prompt bar (`[enableAi]`). See [MCP Integration Guide](docs/MCP_INTEGRATION.md).
 - 🧪 **Signal Forms Native**: Direct integration with Angular 21's new Signal Forms API.
 - 🚀 **Zoneless Ready**: Optimized for the future of Angular—works perfectly without zone.js.
 - ♿ **Full Accessibility**: WAI-ARIA compliant with extensive keyboard navigation support.
 
+## **⚖️ Why ngxsmk-datepicker? (Comparison)**
+
+| Capability | **ngxsmk-datepicker** | @angular/material | ngx-bootstrap | ng-pick-datetime |
+| --- | :---: | :---: | :---: | :---: |
+| Standalone / no NgModule | ✅ | ✅ | ⚠️ | ❌ |
+| Signals & Zoneless-ready | ✅ | ⚠️ | ❌ | ❌ |
+| SSR / Angular Universal | ✅ | ✅ | ⚠️ | ❌ |
+| Date **range** picker | ✅ | ✅ | ✅ | ✅ |
+| Multiple / week / month / quarter / year modes | ✅ | ❌ | ❌ | ❌ |
+| Time & timezone-aware selection | ✅ | ❌ | ⚠️ | ✅ |
+| Natural-language input ("next friday") | ✅ | ❌ | ❌ | ❌ |
+| Dual-range **comparison** highlight | ✅ | ❌ | ❌ | ❌ |
+| Built-in i18n (8 languages) + RTL | ✅ | ⚠️ | ⚠️ | ⚠️ |
+| React / Vue / Web-Component wrappers | ✅ | ❌ | ❌ | ❌ |
+| Zero peer-dep bloat (only Luxon) | ✅ | ⚠️ | ⚠️ | ⚠️ |
+| Actively maintained (Angular 17–21+) | ✅ | ✅ | ⚠️ | ❌ |
+
+<sub>✅ first-class · ⚠️ partial / extra
+
 ## Why this library?
 
 Use **ngxsmk-datepicker** when you want an enterprise-grade **date / range picker** with strong **mobile**, **i18n**, **timezone**, **Ionic**, and **SSR** support on **Angular 17–22+**, without adopting a heavy Material UI stack or legacy Day.js dependencies.
@@ -112,15 +120,7 @@ Use **ngxsmk-datepicker** when you want an enterprise-grade **date / range picke
 | **Google Calendar Sync & Multi-Calendars** | ✅ Built-in | ❌ Requires custom code | ❌ Not supported |
 | **SSR / Hydration Safety** | ✅ 100% Guarded (`DOCUMENT`) | ⚠️ Requires CDK SSR overlays | ❌ Window access errors |
 
-This is **not** a heavy UI framework; it is a **standalone datepicker** engineered for maximum performance, accessibility, and theming flexibility. 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.
+This is **not** a heavy UI framework; it is a **standalone datepicker** engineered for maximum performance, accessibility, and theming flexibility. 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.</sub>
 
 ## **📋 Compatibility**
 
@@ -180,36 +180,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**
 
-```bash
-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:
+Install the package using npm:
 
 ```bash
-npm install ngxsmk-datepicker@3.0.5
+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@3.0.5` |
-| **pnpm** | `pnpm add ngxsmk-datepicker@3.0.5` |
-| **Bun** | `bun add ngxsmk-datepicker@3.0.5` |
-| **From Git** | `npm install github:NGXSMK/ngxsmk-datepicker#v3.0.5` (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.5/) or [jsDelivr](https://cdn.jsdelivr.net/npm/ngxsmk-datepicker@3.0.5/) 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)
 
@@ -279,7 +264,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';
@@ -309,8 +294,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.
@@ -360,7 +343,7 @@ class MyHolidayProvider implements HolidayProvider {
 
 ### **Angular Material Form Fields**
 
-Integrate with Angular Material's form field components for a seamless Material Design experience. Works with both standalone and non-standalone components:
+Integrate with Angular Material's form field components for a seamless Material Design experience. Import the optional **`ngxsmk-datepicker/material`** entry (keeps `@angular/material` out of the main bundle):
 
 **Standalone Components:**
 
@@ -370,16 +353,28 @@ import { FormControl, FormGroup, ReactiveFormsModule } from "@angular/forms";
 import { MatFormFieldModule } from "@angular/material/form-field";
 import { MatInputModule } from "@angular/material/input";
 import { NgxsmkDatepickerComponent } from "ngxsmk-datepicker";
+import { NgxsmkDatepickerMatFormFieldControlDirective } from "ngxsmk-datepicker/material";
 
 @Component({
   selector: "app-material-form",
   standalone: true,
-  imports: [ReactiveFormsModule, MatFormFieldModule, MatInputModule, NgxsmkDatepickerComponent],
+  imports: [
+    ReactiveFormsModule,
+    MatFormFieldModule,
+    MatInputModule,
+    NgxsmkDatepickerComponent,
+    NgxsmkDatepickerMatFormFieldControlDirective,
+  ],
   template: `
     <form [formGroup]="myForm">
       <mat-form-field appearance="outline">
         <mat-label>Select Date</mat-label>
-        <ngxsmk-datepicker mode="single" formControlName="date" placeholder="Choose a date"> </ngxsmk-datepicker>
+        <ngxsmk-datepicker
+          ngxsmkMatFormFieldControl
+          mode="single"
+          formControlName="date"
+          placeholder="Choose a date"
+        ></ngxsmk-datepicker>
       </mat-form-field>
     </form>
   `,
@@ -391,17 +386,18 @@ 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):** Import `NgxsmkDatepickerMatFormFieldControlDirective` from `ngxsmk-datepicker/material` into your module `imports` (with `NgxsmkDatepickerComponent`, `MatFormFieldModule`, etc.) and put `ngxsmkMatFormFieldControl` on the datepicker. See [INTEGRATION.md § Angular Material](docs/INTEGRATION.md#angular-material).
 
 **With Date Range:**
 
 ```html
 <mat-form-field appearance="fill">
   <mat-label>Date Range</mat-label>
-  <ngxsmk-datepicker mode="range" [showTime]="true" formControlName="dateRange"> </ngxsmk-datepicker>
+  <ngxsmk-datepicker ngxsmkMatFormFieldControl mode="range" [showTime]="true" formControlName="dateRange"></ngxsmk-datepicker>
 </mat-form-field>
 ```
 
+**Optional date adapters** (date-fns / Day.js / Luxon) live on a separate entry: `import { DateFnsAdapter } from 'ngxsmk-datepicker/adapters'`.
 ### **Ionic Components**
 
 For best integration with Ionic, import the integration styles in your global CSS/SCSS file:
@@ -410,9 +406,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
@@ -543,38 +536,6 @@ 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**
@@ -585,8 +546,7 @@ const form = new FormGroup({
 | 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 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.). |
+| showRanges         | boolean | true | If true, displays the predefined ranges panel when in 'range' mode. |
 | 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. |
@@ -615,17 +575,10 @@ const form = new FormGroup({
 | 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). |
+| changeActiveMonthOnSelection | boolean | true | If false, selecting a date won't shift the visible month(s) — useful in multi-calendar mode to keep both calendars fixed when picking a date from the second/third one. |
 | 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"). |
-| showWeekNumbers    | boolean | false | Shows an ISO 8601 week-number column on the left of the day grid. |
-| weekNumberLabel    | string | 'Wk' | Header label for the week-number column (e.g. "KW", "S"). |
-| inputMask          | boolean \| string | false | Guided input masking while typing: `true` uses `displayFormat` (or MM/DD/YYYY); a string (e.g. `'DD.MM.YYYY'`) sets an explicit pattern. Requires `allowTyping`. |
-| asyncDateFilter    | (start: Date, end: Date) => Promise<DateInput[]> | null | Server-driven disabled dates: called with the visible range on every navigation; resolved dates are disabled. Stale responses are discarded. |
-| secondaryCalendar  | 'islamic' \| 'persian' \| 'hebrew' \| 'buddhist' \| 'japanese' | null | Annotates each day cell with its date in a second calendar system (rendered via Intl; the grid stays Gregorian). |
-| dayMetadata        | (date: Date) => DayMetadata | null | Per-day decorations without templates: label under the day number (e.g. a price), indicator dot color, extra CSS classes, tooltip. |
-| calendarHeaderTemplate | TemplateRef | null | Custom content at the top of the popover/inline calendar. Context: `let-actions` → `{ clear(), close() }`. |
-| calendarFooterTemplate | TemplateRef | null | Replaces the default Clear/Close footer with custom actions. Context: `let-actions` → `{ clear(), close() }`. |
 
 ### **Outputs**
 
@@ -637,8 +590,6 @@ const form = new FormGroup({
 | 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. |
-| asyncDateFilterLoading | boolean | Emits true while an `asyncDateFilter` request is in flight, false when it settles. |
-| asyncDateFilterError | unknown | Emitted when `asyncDateFilter` rejects; the previous disabled set is kept. |
 
 ## **🎨 Theming**
 
@@ -706,14 +657,14 @@ The `locale` input controls all internationalization. It automatically formats m
 
 ngxsmk-datepicker v2.4.0+ 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**
 
@@ -778,7 +729,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.
 
@@ -803,14 +754,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:**
 
@@ -884,7 +832,8 @@ npm run build:analyze
 
 **Build Output:**
 
-- Main bundle: `dist/ngxsmk-datepicker/fesm2022/ngxsmk-datepicker.mjs` (~127KB)
+- Main bundle: `dist/ngxsmk-datepicker/fesm2022/ngxsmk-datepicker.mjs` (~127KB gzipped / published target; raw FESM is larger)
+- Optional: `ngxsmk-datepicker-adapters.mjs`, `ngxsmk-datepicker-material.mjs` (secondary entries)
 - Type definitions: `dist/ngxsmk-datepicker/index.d.ts`
 - Source maps: Automatically removed from production builds
 
@@ -964,9 +913,15 @@ We welcome and appreciate contributions from the community! Whether it's reporti
 
 ## **📄 Changelog**
 
-**Recent:** Use **v3.0.5** 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.5**.
+For a full list of changes, please refer to the [CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md) file.
+
+### **v3.0.6** (Current Stable)
+
+- **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**
 
@@ -974,6 +929,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!
@@ -986,9 +946,16 @@ 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, AI search engines, and global developer discovery:
 
-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-22+, Signals, Zoneless Angular, TypeScript, Signal Forms, Timezone Dropdown, Secondary Calendars (Hijri, Jalali), SSR Compatible, Ionic DatePicker
+- **Global & European SEO**: Optimized for worldwide developer discovery across North America, Europe (Germany, France, UK, Spain, Sweden, Netherlands, Poland), Asia (Japan, South Korea, China), and Latin America
+- **Multi-language Support**: i18n support and hreflang meta tags for 15+ global languages and regional locales
+- **Social & Community Visibility**: Rich Open Graph metadata, Twitter Cards, JSON-LD structured data (SoftwareApplication & Organization schema), and official [WhatsApp Channel](https://whatsapp.com/channel/0029Vb8PWpz1XquUOnGPUM2p) updates
+- **Documentation**: Complete API documentation with live interactive code examples
+- **Performance**: Optimized bundle size (~127KB) for fast initial page load and high Lighthouse SEO scores
 
 ## **👨‍💻 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**: 3.0.3+ (includes unreleased `main` additions) | **Last updated**: July 24, 2026
+**Version**: 3.0.6 | **Last updated**: September 8, 2026
 
 ## Stable vs experimental
 
@@ -84,7 +84,7 @@ import { NgxsmkDatepickerComponent } from 'ngxsmk-datepicker';
 | `hooks` | `DatepickerHooks \| null` | `null` | Stable | Extension points for customization | `[hooks]="customHooks"` |
 | `enableKeyboardShortcuts` | `boolean` | `true` | Stable | Enable/disable keyboard shortcuts. Press '?' for help. | `[enableKeyboardShortcuts]="false"` |
 | `customShortcuts` | `{ [key: string]: (context: KeyboardShortcutContext) => boolean } \| null` | `null` | Stable | Custom keyboard shortcuts map | `[customShortcuts]="myShortcuts"` |
-| `autoApplyClose` | `boolean` | `false` | Stable | Auto-close calendar after selection | `[autoApplyClose]="true"` |
+| `autoApplyClose` | `boolean` | `false` | Stable | Opt-in auto-close after a complete selection. Forced off when `showTime` / `timeOnly` / inline. | `[autoApplyClose]="true"` |
 | `clearLabel` | `string` | `'Clear'` | Stable | Custom label for clear button | `clearLabel="Reset"` |
 | `closeLabel` | `string` | `'Close'` | Stable | Custom label for close button | `closeLabel="Done"` |
 | `prevMonthAriaLabel` | `string` | `'Previous month'` | Stable | ARIA label for previous month button | `prevMonthAriaLabel="Go to previous month"` |
@@ -2343,6 +2343,34 @@ interface DatepickerClasses {
 
 ## Exported Utilities
 
+### Constraints Snapshot
+
+**Status**: Stable (v3.0.6+)
+
+Allowed-day truth for min/max, disabled dates/ranges, holidays, async disabled sets, and `isInvalidDate`. The Host rebuilds an immutable snapshot when constraint inputs change; forms validators map `ConstraintDenial` codes to public error keys. See `docs/adr/0001-hybrid-constraints-snapshot.md` and root `CONTEXT.md`.
+
+```typescript
+import {
+  Constraints,
+  buildConstraints,
+  EMPTY_CONSTRAINTS_SOURCES,
+  type ConstraintsSources,
+  type ConstraintsSnapshot,
+  type DayVerdict,
+  type ConstraintDenial,
+} from 'ngxsmk-datepicker';
+
+const snap = Constraints.build({
+  ...EMPTY_CONSTRAINTS_SOURCES,
+  minDate: new Date(2026, 0, 1),
+  maxDate: new Date(2026, 11, 31),
+  disabledDates: ['2026-01-15'],
+});
+
+snap.isAllowed(new Date(2026, 0, 15)); // false
+snap.evaluate(new Date(2026, 0, 15)); // { allowed: false, denial: { code: 'disabledDate', ... } }
+```
+
 ### Date Utilities
 
 **Status**: Stable
@@ -2363,6 +2391,24 @@ export function getDaysInMonth(year: number, month: number): number;
 export function getFirstDayOfMonth(year: number, month: number): number;
 ```
 
+## Secondary entry points
+
+Optional packages stay out of the main FESM:
+
+| Import path | Contents | Notes |
+|-------------|----------|--------|
+| `ngxsmk-datepicker` | Component, validators, Constraints, utils, config | Main bundle |
+| `ngxsmk-datepicker/adapters` | `DateFnsAdapter`, `DayjsAdapter`, `LuxonAdapter` | Install the matching peer library |
+| `ngxsmk-datepicker/material` | `NgxsmkDatepickerMatFormFieldControlDirective`, `provideMaterialFormFieldControl` | Requires `@angular/material` + `@angular/cdk` |
+| `ngxsmk-datepicker/styles/*` | CSS assets | Styles only |
+
+```typescript
+import { DateFnsAdapter } from 'ngxsmk-datepicker/adapters';
+import { NgxsmkDatepickerMatFormFieldControlDirective } from 'ngxsmk-datepicker/material';
+```
+
+`NativeDateAdapter` / `DateAdapter` remain on the main entry.
+
 ## Virtual scrolling
 
 Year and decade views use the internal `calculateVirtualScroll` utility and visible-index signals so that only visible items are rendered when year ranges are large (e.g. 100+ years). The main calendar grid uses lazy month rendering via `_visibleCalendarIndicesSignal`. For very large ranges, consider limiting `yearRange` for optimal performance.