ngxsmk-datepicker 3.0.5-beta.0 → 3.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +77 -124
  2. package/package.json +1 -1
  3. package/types/ngxsmk-datepicker.d.ts +1 -1
  4. package/CHANGELOG.md +0 -1366
  5. package/LICENSE +0 -21
  6. package/MIGRATION.md +0 -1842
package/README.md CHANGED
@@ -12,7 +12,6 @@
12
12
 
13
13
  [![npm version](https://img.shields.io/npm/v/ngxsmk-datepicker.svg?style=flat-square&color=6d28d9)](https://www.npmjs.com/package/ngxsmk-datepicker)
14
14
  [![npm downloads](https://img.shields.io/npm/dm/ngxsmk-datepicker.svg?style=flat-square)](https://www.npmjs.com/package/ngxsmk-datepicker)
15
- [![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)
16
15
  [![Angular](https://img.shields.io/badge/Angular-17%2B-DD0031.svg?style=flat-square&logo=angular)](https://angular.io/)
17
16
  [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/LICENSE)
18
17
  [![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 @@
22
21
 
23
22
  **`npm i ngxsmk-datepicker`**
24
23
 
25
- [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)
26
-
27
- *StackBlitz:* after it boots, run `npm install` then `npm start` in the terminal to serve the demo app (`demo-app`).
24
+ [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)
28
25
 
29
26
  </div>
30
27
 
31
28
  ---
32
29
 
33
- **Last updated:** August 22, 2026 - **Current stable:** v3.0.5
30
+ **Last updated:** July 29, 2026 - **Current stable:** v3.0.3
34
31
 
35
32
  ### **Overview**
36
33
 
37
34
  **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.
38
35
 
39
- > **Stable Release**: `v3.0.5` is the current stable release with compiled `fesm2022` output and type declarations.
36
+ > **Stable Release**: `v3.0.3` is the current stable release with compiled `fesm2022` output and type declarations.
40
37
  >
41
- > **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.
38
+ > **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.
42
39
 
43
40
  ---
44
41
 
@@ -46,16 +43,14 @@
46
43
 
47
44
  1. [📷 Screenshots](#-screenshots)
48
45
  2. [✨ Features](#-features)
49
- 3. [🤔 Why this library?](#why-this-library)
50
- 4. [🌐 Discoverability](#-discoverability)
51
- 5. [📋 Compatibility](#-compatibility)
52
- 6. [🌍 Localization (i18n)](#-localization-i18n)
53
- 7. [📦 Installation](#-installation)
54
- 8. [🚀 Quick start / usage](#usage)
55
- 9. [🔌 Framework Integration](#-framework-integration)
56
- 10. [⚙️ API Reference](#-api-reference)
57
- 11. [🎨 Theming](#-theming)
58
- 12. [⌨️ Keyboard Navigation](#-keyboard-navigation)
46
+ 3. [📋 Compatibility](#-compatibility)
47
+ 4. [🌍 Localization (i18n)](#-localization-i18n)
48
+ 5. [📦 Installation](#-installation)
49
+ 6. [🚀 Quick Start](#-quick-start)
50
+ 7. [🔌 Framework Integration](#-framework-integration)
51
+ 8. [⚙️ API Reference](#-api-reference)
52
+ 9. [🎨 Theming](#-theming)
53
+ 10. [⌨️ Keyboard Navigation](#-keyboard-navigation)
59
54
 
60
55
  ---
61
56
 
@@ -74,7 +69,7 @@
74
69
  - 💎 **Signal-Driven Engine**: Hyper-reactive state management using Angular Signals.
75
70
  - 🌓 **Native Dark Mode**: Beautifully crafted themes for light and dark environments.
76
71
  - 📱 **Mobile-First UX**: Native mobile picker integration with touch gestures and haptic feedback.
77
- - 🧩 **Minimal footprint**: Standalone component; **Luxon** is the only date peer beyond Angular (no full UI suite required).
72
+ - 🧩 **Zero Dependencies**: Lightweight standalone component with no external bloat.
78
73
  - ⚡ **Performance++**: Lazy-loaded calendar months, memoized calculations, and tree-shakable architecture.
79
74
 
80
75
  ### **Advanced Functionality**
@@ -83,17 +78,30 @@
83
78
  - 🗓️ **Adjacent Month Days (`showOtherMonths`)**: Display trailing and leading days from adjacent months in the calendar grid.
84
79
  - 📐 **Responsive Control (`[responsive]`)**: Disable viewport max-width responsive overrides for fixed-width container embedding (#299).
85
80
  - 🌐 **8-Language i18n**: Full localization for `en`, `de`, `es`, `sv`, `ko`, `zh`, `ja`, and `fr`.
86
- - 🔢 **ISO Week Numbers**: Optional week-number column via `[showWeekNumbers]`.
87
- - ⌨️ **Guided Input Masking**: `[inputMask]` auto-inserts separators as users type (e.g. `12` → `12/`).
88
- - 🌍 **Secondary Calendars**: Annotate day cells with Hijri, Jalali, Hebrew, Buddhist, or Japanese dates via `[secondaryCalendar]`.
89
- - 🏨 **Availability Calendars**: Per-day prices, indicator dots, and classes via `[dayMetadata]`; server-driven blocked dates via `[asyncDateFilter]`.
90
- - 🎛️ **Custom Action Bars**: `[calendarHeaderTemplate]` / `[calendarFooterTemplate]` slots with `clear()`/`close()` actions.
91
81
  - 🛠️ **Plugin Architecture**: Extend functionality via hooks for rendering, validation, and shortcuts.
92
- - 🤖 **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).
93
82
  - 🧪 **Signal Forms Native**: Direct integration with Angular 21's new Signal Forms API.
94
83
  - 🚀 **Zoneless Ready**: Optimized for the future of Angular—works perfectly without zone.js.
95
84
  - ♿ **Full Accessibility**: WAI-ARIA compliant with extensive keyboard navigation support.
96
85
 
86
+ ## **⚖️ Why ngxsmk-datepicker? (Comparison)**
87
+
88
+ | Capability | **ngxsmk-datepicker** | @angular/material | ngx-bootstrap | ng-pick-datetime |
89
+ | --- | :---: | :---: | :---: | :---: |
90
+ | Standalone / no NgModule | ✅ | ✅ | ⚠️ | ❌ |
91
+ | Signals & Zoneless-ready | ✅ | ⚠️ | ❌ | ❌ |
92
+ | SSR / Angular Universal | ✅ | ✅ | ⚠️ | ❌ |
93
+ | Date **range** picker | ✅ | ✅ | ✅ | ✅ |
94
+ | Multiple / week / month / quarter / year modes | ✅ | ❌ | ❌ | ❌ |
95
+ | Time & timezone-aware selection | ✅ | ❌ | ⚠️ | ✅ |
96
+ | Natural-language input ("next friday") | ✅ | ❌ | ❌ | ❌ |
97
+ | Dual-range **comparison** highlight | ✅ | ❌ | ❌ | ❌ |
98
+ | Built-in i18n (8 languages) + RTL | ✅ | ⚠️ | ⚠️ | ⚠️ |
99
+ | React / Vue / Web-Component wrappers | ✅ | ❌ | ❌ | ❌ |
100
+ | Zero peer-dep bloat (only Luxon) | ✅ | ⚠️ | ⚠️ | ⚠️ |
101
+ | Actively maintained (Angular 17–21+) | ✅ | ✅ | ⚠️ | ❌ |
102
+
103
+ <sub>✅ first-class · ⚠️ partial / extra
104
+
97
105
  ## Why this library?
98
106
 
99
107
  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
112
120
  | **Google Calendar Sync & Multi-Calendars** | ✅ Built-in | ❌ Requires custom code | ❌ Not supported |
113
121
  | **SSR / Hydration Safety** | ✅ 100% Guarded (`DOCUMENT`) | ⚠️ Requires CDK SSR overlays | ❌ Window access errors |
114
122
 
115
- 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.
116
-
117
- ## **🌐 Discoverability**
118
-
119
- **Maintainers (GitHub):** consider repository **Topics** such as: `angular`, `datepicker`, `date-range-picker`, `luxon`, `standalone-components`, `i18n`, `angular-universal`, `ionic`, `accessibility`.
120
-
121
- **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.
122
-
123
- **Security:** report sensitive issues per [SECURITY.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/SECURITY.md), not via public issues.
123
+ 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>
124
124
 
125
125
  ## **📋 Compatibility**
126
126
 
@@ -180,36 +180,21 @@ Features marked as experimental may change:
180
180
 
181
181
  For details, see [CONTRIBUTING.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CONTRIBUTING.md#deprecation-policy).
182
182
 
183
- ## **📦 Installation**
183
+ ## **🚀 Installation**
184
184
 
185
- ```bash
186
- ng add ngxsmk-datepicker
187
- ```
188
-
189
- 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:
185
+ Install the package using npm:
190
186
 
191
187
  ```bash
192
- npm install ngxsmk-datepicker@3.0.5
188
+ npm install ngxsmk-datepicker@latest
193
189
  ```
194
190
 
195
191
  ### Alternative installation
196
192
 
197
- You can install without npm using any of these methods (peer dependencies must still be installed in your app):
198
-
199
- | Method | Command |
200
- |--------|--------|
201
- | **Yarn** | `yarn add ngxsmk-datepicker@3.0.5` |
202
- | **pnpm** | `pnpm add ngxsmk-datepicker@3.0.5` |
203
- | **Bun** | `bun add ngxsmk-datepicker@3.0.5` |
204
- | **From Git** | `npm install github:NGXSMK/ngxsmk-datepicker#v3.0.5` (requires the repo to have built output or you build from source) |
205
- | **Local path** | Build the library in the repo (`npx ng build ngxsmk-datepicker`), then `npm install /path/to/ngxsmk-datepicker/dist/ngxsmk-datepicker` |
206
- | **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. |
207
-
208
- For all options and caveats, see [docs/INSTALLATION.md](docs/INSTALLATION.md).
193
+ 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.
209
194
 
210
195
  ## **Usage**
211
196
 
212
- ngxsmk-datepicker is a standalone component, so you can import it directly into your component or module.
197
+ 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>`).
213
198
 
214
199
  ### Signal Forms (Angular 21)
215
200
 
@@ -279,7 +264,7 @@ For detailed Signal Forms integration including dirty state tracking, see the [S
279
264
 
280
265
  #### **1. Import the Component**
281
266
 
282
- 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).
267
+ In your component file (e.g., app.component.ts), import NgxsmkDatepickerComponent.
283
268
 
284
269
  import { Component } from '@angular/core';
285
270
  import { NgxsmkDatepickerComponent, DateRange, HolidayProvider } from 'ngxsmk-datepicker';
@@ -309,8 +294,6 @@ All public exports (component, utilities, types, services) come from the main pa
309
294
  }
310
295
  }
311
296
 
312
- **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>`).
313
-
314
297
  #### **2. Add it to Your Template**
315
298
 
316
299
  Use the `<ngxsmk-datepicker>` selector in your HTML template.
@@ -391,7 +374,7 @@ export class MaterialFormComponent {
391
374
  }
392
375
  ```
393
376
 
394
- **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.
377
+ **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.
395
378
 
396
379
  **With Date Range:**
397
380
 
@@ -410,9 +393,6 @@ For best integration with Ionic, import the integration styles in your global CS
410
393
  @import "ngxsmk-datepicker/styles/ionic-integration.css";
411
394
  ```
412
395
 
413
- **Automatic Theming:**
414
- 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.
415
-
416
396
  Works seamlessly with Ionic form components and follows Ionic design patterns:
417
397
 
418
398
  ```typescript
@@ -543,38 +523,6 @@ By default, the datepicker input is `readonly` to prevent invalid date strings a
543
523
  2. **Custom Validation Logic:**
544
524
  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.
545
525
 
546
- ### **Built-in Reactive Forms Validators**
547
-
548
- `ngxsmk-datepicker` exports convenient, type-safe Angular `ValidatorFn` functions for standard form validation:
549
-
550
- ```typescript
551
- import { FormControl, FormGroup } from '@angular/forms';
552
- import {
553
- ngxsmkMinDateValidator,
554
- ngxsmkMaxDateValidator,
555
- ngxsmkDateRangeValidator,
556
- ngxsmkBlockedDatesValidator
557
- } from 'ngxsmk-datepicker';
558
-
559
- const form = new FormGroup({
560
- // Minimum date validator (Date, string, or dynamic factory)
561
- arrivalDate: new FormControl(null, [ngxsmkMinDateValidator(new Date())]),
562
-
563
- // Maximum date validator
564
- departureDate: new FormControl(null, [ngxsmkMaxDateValidator(new Date(2026, 11, 31))]),
565
-
566
- // Range validation: requires both dates, 2 to 14 days duration
567
- tripRange: new FormControl(null, [
568
- ngxsmkDateRangeValidator({ minDays: 2, maxDays: 14, requireBoth: true })
569
- ]),
570
-
571
- // Disallow weekends or specific blackout dates
572
- bookingDate: new FormControl(null, [
573
- ngxsmkBlockedDatesValidator((d: Date) => d.getDay() === 0 || d.getDay() === 6)
574
- ]),
575
- });
576
- ```
577
-
578
526
  ## **⚙️ API Reference**
579
527
 
580
528
  ### **Inputs**
@@ -585,8 +533,7 @@ const form = new FormGroup({
585
533
  | inline | boolean \| 'always' \| 'auto' | false | Controls the display mode. `true` or `'always'` for inline, `'auto'` for responsive. |
586
534
  | locale | string | navigator.language | Sets the locale for language and regional formatting (e.g., 'en-US', 'de-DE'). |
587
535
  | theme | 'light' \| 'dark' | 'light' | The color theme. |
588
- | showRanges | boolean | true | If true, displays custom predefined ranges panel when in 'range' mode. |
589
- | showPresets | boolean | false | If true, displays standard quick presets (*Today*, *Yesterday*, *Last 7 Days*, *This Month*, etc.). |
536
+ | showRanges | boolean | true | If true, displays the predefined ranges panel when in 'range' mode. |
590
537
  | minDate | DateInput | null | The earliest selectable date. |
591
538
  | maxDate | DateInput | null | The latest selectable date. |
592
539
  | isInvalidDate | (date: Date) => boolean | () => false | A function to programmatically disable specific dates. |
@@ -615,17 +562,10 @@ const form = new FormGroup({
615
562
  | enableGoogleCalendar| boolean | false | Enable seamless Google Calendar integration and sync. |
616
563
  | googleClientId | string \| null | null | Google API OAuth 2.0 Web Client ID for authentication. |
617
564
  | calendars | number | 1 | Multi-calendar display layout (supports 1, 2, or 3 side-by-side calendars). |
565
+ | 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. |
618
566
  | rangePresetFactory | (today: Date) => DatePreset[] | null | Callback function supplying dynamic rolling range presets. |
619
567
  | showTimezoneSelector | boolean | false | Enables searchable IANA timezone selection dropdown UI. |
620
568
  | enableNaturalLanguage | boolean | false | Enables manual relative keyboard typing input (e.g. "today", "in 3 days"). |
621
- | showWeekNumbers | boolean | false | Shows an ISO 8601 week-number column on the left of the day grid. |
622
- | weekNumberLabel | string | 'Wk' | Header label for the week-number column (e.g. "KW", "S"). |
623
- | 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`. |
624
- | 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. |
625
- | 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). |
626
- | 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. |
627
- | calendarHeaderTemplate | TemplateRef | null | Custom content at the top of the popover/inline calendar. Context: `let-actions` → `{ clear(), close() }`. |
628
- | calendarFooterTemplate | TemplateRef | null | Replaces the default Clear/Close footer with custom actions. Context: `let-actions` → `{ clear(), close() }`. |
629
569
 
630
570
  ### **Outputs**
631
571
 
@@ -637,8 +577,6 @@ const form = new FormGroup({
637
577
  | invalidRange | { start: Date; end: Date; disabledDatesInside: Date[] } | Emitted when selected date range contains disabled dates. |
638
578
  | naturalLanguageResolved | Date \| { start: Date; end: Date } | Emitted when user types relative natural language date input. |
639
579
  | timezoneChange | string | Emitted when timezone selection is changed. |
640
- | asyncDateFilterLoading | boolean | Emits true while an `asyncDateFilter` request is in flight, false when it settles. |
641
- | asyncDateFilterError | unknown | Emitted when `asyncDateFilter` rejects; the previous disabled set is kept. |
642
580
 
643
581
  ## **🎨 Theming**
644
582
 
@@ -706,14 +644,14 @@ The `locale` input controls all internationalization. It automatically formats m
706
644
 
707
645
  ngxsmk-datepicker v2.4.0+ now features **full localization synchronization** for:
708
646
 
709
- - �� English (`en`)
710
- - �� German (`de`)
711
- - �� French (`fr`)
712
- - �� Spanish (`es`)
647
+ - 🇺🇸 English (`en`)
648
+ - 🇩🇪 German (`de`)
649
+ - 🇫🇷 French (`fr`)
650
+ - 🇪🇸 Spanish (`es`)
713
651
  - 🇸🇪 Swedish (`sv`)
714
- - �� Korean (`ko`)
715
- - �� Chinese (`zh`)
716
- - �� Japanese (`ja`)
652
+ - 🇰🇷 Korean (`ko`)
653
+ - 🇨🇳 Chinese (`zh`)
654
+ - 🇯🇵 Japanese (`ja`)
717
655
 
718
656
  ### **Usage Example**
719
657
 
@@ -778,7 +716,7 @@ const myHooks: DatepickerHooks = {
778
716
  <ngxsmk-datepicker [hooks]="myHooks" [customShortcuts]="shortcuts" mode="single"> </ngxsmk-datepicker>
779
717
  ```
780
718
 
781
- 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.
719
+ All date cells are keyboard accessible with proper ARIA attributes for screen readers.
782
720
 
783
721
  See [Extension Points Guide](./projects/ngxsmk-datepicker/docs/extension-points.md) for detailed customization options.
784
722
 
@@ -803,14 +741,11 @@ This library has been optimized for maximum performance:
803
741
  - ✅ **Date Validation**: Fixed "Today" unselectable bug by normalizing `minDate` boundary checks.
804
742
  - ✅ **Keyboard Shortcuts**: Updated "Today" selection shortcut to use timezone-aware calculation.
805
743
  - ✅ **Validation messages**: User-facing i18n strings for invalid date, min/max; `validationError` output and on-screen error display
806
- - ✅ **Change Detection**: Fixed OnPush change detection issues with proper `markForCheck()` triggers
807
- - ✅ **Date Comparison**: Fixed null safety issues in date range comparisons
808
- - ✅ **Memory Leaks**: Added cache size limits to prevent memory leaks
809
- - ✅ **Type Safety**: Improved TypeScript types and null safety checks
810
- - ✅ **Mobile UX**: Enhanced mobile interactions and touch feedback
811
- - ✅ **Performance**: Optimized template bindings with memoized functions
812
- - ✅ **Accessibility**: Better focus states and keyboard navigation
813
- - ✅ **Build System**: Improved build configuration and optimization
744
+ - ✅ **Calendar loading state**: Visual spinner + text and screen-reader announcement while calendar opens/generates
745
+ - ✅ **Demo theme**: Light/dark theme toggle and system preference now correctly switch the demo UI
746
+ - ✅ **Installation options**: Full install guide (npm, Yarn, pnpm, Bun, Git, CDN, etc.) and demo page updates
747
+ - ✅ **Accessibility**: Loading state announced via live region; validation errors exposed for a11y
748
+ - ✅ **Type Safety**: New translation keys and strictly typed inputs/outputs
814
749
 
815
750
  ### **Performance Enhancements:**
816
751
 
@@ -964,9 +899,15 @@ We welcome and appreciate contributions from the community! Whether it's reporti
964
899
 
965
900
  ## **📄 Changelog**
966
901
 
967
- **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**.
902
+ For a full list of changes, please refer to the [CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md) file.
903
+
904
+ ### **v3.0.3** (Current Stable)
905
+
906
+ - **npm**: Published tarballs include compiled `fesm2022/` output and type declarations.
968
907
 
969
- For the full list of changes, see [CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md).
908
+ ### **Earlier Versions**
909
+
910
+ For older version details, please refer to the [full CHANGELOG.md](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/CHANGELOG.md).
970
911
 
971
912
  ## **🎨 Theming with TokiForge**
972
913
 
@@ -974,6 +915,11 @@ Looking for a powerful theming solution for your Angular application? Check out
974
915
 
975
916
  ### Why TokiForge?
976
917
 
918
+ - ✅ **Framework-agnostic** — Works with Angular, React, Vue, Svelte, and vanilla JS
919
+ - ✅ **Runtime theme switching** — Change themes dynamically without rebuilds
920
+ - ✅ **Type-safe** — Full TypeScript support for design tokens
921
+ - ✅ **Lightweight** — <3 KB gzipped runtime footprint
922
+ - ✅ **CSS custom properties** — Zero JS overhead in static mode
977
923
  - ✅ **SSR compatible** — Works seamlessly with Angular Universal
978
924
 
979
925
  Perfect for managing design tokens, creating theme systems, and implementing dark mode in your Angular applications!
@@ -986,9 +932,16 @@ Perfect for managing design tokens, creating theme systems, and implementing dar
986
932
 
987
933
  MIT License - see [LICENSE](https://github.com/NGXSMK/ngxsmk-datepicker/blob/main/LICENSE) file for details.
988
934
 
989
- ## **🔍 SEO (demo site)**
935
+ ## **🔍 SEO & Discoverability**
936
+
937
+ This library is optimized for search engine visibility, AI search engines, and global developer discovery:
990
938
 
991
- 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.
939
+ - **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
940
+ - **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
941
+ - **Multi-language Support**: i18n support and hreflang meta tags for 15+ global languages and regional locales
942
+ - **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
943
+ - **Documentation**: Complete API documentation with live interactive code examples
944
+ - **Performance**: Optimized bundle size (~127KB) for fast initial page load and high Lighthouse SEO scores
992
945
 
993
946
  ## **👨‍💻 Author**
994
947
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ngxsmk-datepicker",
3
- "version": "3.0.5-beta.0",
3
+ "version": "3.0.5",
4
4
  "description": "Lightweight, accessible date and range picker for Angular 17+. Standalone component, Signals, SSR and zoneless-ready, Luxon-based i18n and timezones.",
5
5
  "author": {
6
6
  "name": "Sachin Dilshan",
package/types/ngxsmk-datepicker.d.ts CHANGED
@@ -541,7 +541,7 @@ declare class NgxsmkDatepickerContentComponent {
541
541
  event: TouchEvent;
542
542
  day: Date | null;
543
543
  }>;
544
- viewModeChange: EventEmitter<"year" | "decade" | "month" | "timeline" | "time-slider">;
544
+ viewModeChange: EventEmitter<"year" | "month" | "decade" | "timeline" | "time-slider">;
545
545
  changeYear: EventEmitter<number>;
546
546
  yearClick: EventEmitter<number>;
547
547
  changeDecade: EventEmitter<number>;