ngxsmk-datepicker 3.0.5 → 3.0.6

package/README.md

@@ -27,15 +27,15 @@
 
 ---
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**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.3` 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.3** on npm.
+> **Stable line**: v2.3.x includes side-by-side **`calendars`**, **natural language input**, searchable **timezone selection dropdown UI**, dynamic range presets, and warning range highlighting. Versions **2.0.10** and **2.0.11** were broken and have been **unpublished**; use **v2.1.1+** or current **v3.0.6** on npm.
 
 ---
 
@@ -343,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:**
 
@@ -353,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>
   `,
@@ -374,17 +386,18 @@ 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):** 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:
@@ -819,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
 
@@ -901,7 +915,7 @@ We welcome and appreciate contributions from the community! Whether it's reporti
 
 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.3** (Current Stable)
+### **v3.0.6** (Current Stable)
 
 - **npm**: Published tarballs include compiled `fesm2022/` output and type declarations.
 

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.

package/docs/COMPATIBILITY.md

@@ -1,57 +1,57 @@
-# Version Compatibility Matrix
+# Version Compatibility Matrix
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 This document provides comprehensive compatibility information for `ngxsmk-datepicker` across different Angular versions, Zone.js configurations, and SSR/CSR setups.
 
-## 📋 Angular Version Compatibility
+## ?? Angular Version Compatibility
 
 ### Compatibility Matrix
 
 | Angular Version | Status | Core Features | Signal Features | Signal Forms | SSR Support | Notes |
 |----------------|--------|--------------|----------------|--------------|-------------|-------|
-| **Angular 17** | ✅ Fully Supported | ✅ All | ✅ Signals, Computed | ❌ Not Available | ✅ Full | Minimum supported version |
-| **Angular 18** | ✅ Fully Supported | ✅ All | ✅ Signals, Computed, Effects | ❌ Not Available | ✅ Full | Enhanced signal support |
-| **Angular 19** | ✅ Fully Supported | ✅ All | ✅ Signals, Computed, Effects | ❌ Not Available | ✅ Full | Optimized performance |
-| **Angular 20** | ✅ Fully Supported | ✅ All | ✅ Signals, Computed, Effects | ❌ Not Available | ✅ Full | Fully supported |
-| **Angular 21** | ✅ Fully Supported | ✅ All | ✅ Signals, Computed, Effects | ✅ Signal Forms `[field]` | ✅ Full | **Officially released - Current development target**<br/>✅ Signal Forms (experimental)<br/>✅ Zoneless by default<br/>✅ Compatible with Vitest-based apps<br/>✅ Angular Aria compatible |
-| **Angular 22+** | 🔄 Future Support | ✅ All | ✅ Signals, Computed, Effects | ✅ Signal Forms `[field]` | ✅ Full | Peer dependency: `<24.0.0` |
+| **Angular 17** | ? Fully Supported | ? All | ? Signals, Computed | ? Not Available | ? Full | Minimum supported version |
+| **Angular 18** | ? Fully Supported | ? All | ? Signals, Computed, Effects | ? Not Available | ? Full | Enhanced signal support |
+| **Angular 19** | ? Fully Supported | ? All | ? Signals, Computed, Effects | ? Not Available | ? Full | Optimized performance |
+| **Angular 20** | ? Fully Supported | ? All | ? Signals, Computed, Effects | ? Not Available | ? Full | Fully supported |
+| **Angular 21** | ? Fully Supported | ? All | ? Signals, Computed, Effects | ? Signal Forms `[field]` | ? Full | **Officially released - Current development target**<br/>? Signal Forms (experimental)<br/>? Zoneless by default<br/>? Compatible with Vitest-based apps<br/>? Angular Aria compatible |
+| **Angular 22+** | ?? Future Support | ? All | ? Signals, Computed, Effects | ? Signal Forms `[field]` | ? Full | Peer dependency: `<24.0.0` |
 
 ### Feature Availability by Angular Version
 
 #### Core Features (Available in all versions)
-- ✅ Date selection (single, range, multiple)
-- ✅ Time selection
-- ✅ Calendar views (month, year, decade, timeline, time-slider)
-- ✅ Keyboard navigation
-- ✅ Touch gestures
-- ✅ RTL support
-- ✅ Timezone support
-- ✅ Custom formatting
-- ✅ Holiday provider integration
-- ✅ Custom hooks and extensions
-- ✅ Accessibility (ARIA, keyboard)
-- ✅ Theming (light/dark)
-- ✅ Translations/i18n
+- ? Date selection (single, range, multiple)
+- ? Time selection
+- ? Calendar views (month, year, decade, timeline, time-slider)
+- ? Keyboard navigation
+- ? Touch gestures
+- ? RTL support
+- ? Timezone support
+- ? Custom formatting
+- ? Holiday provider integration
+- ? Custom hooks and extensions
+- ? Accessibility (ARIA, keyboard)
+- ? Theming (light/dark)
+- ? Translations/i18n
 
 #### Signal Features (Angular 17+)
-- ✅ `signal()` - Reactive state management
-- ✅ `computed()` - Derived reactive values
-- ✅ `effect()` - Side effects (Angular 18+)
-- ✅ `inject()` - Dependency injection
+- ? `signal()` - Reactive state management
+- ? `computed()` - Derived reactive values
+- ? `effect()` - Side effects (Angular 18+)
+- ? `inject()` - Dependency injection
 
 #### Signal Forms (Angular 21+)
-- ✅ `[field]` input binding (experimental Angular 21 feature)
-- ✅ Automatic field synchronization
-- ✅ Reactive form field updates
-- ✅ Signal-based value management
-- ✅ Works with `form()`, `objectSchema()`, and `validators`
-- ✅ Compatible with `httpResource` and `linkedSignal` patterns
+- ? `[field]` input binding (experimental Angular 21 feature)
+- ? Automatic field synchronization
+- ? Reactive form field updates
+- ? Signal-based value management
+- ? Works with `form()`, `objectSchema()`, and `validators`
+- ? Compatible with `httpResource` and `linkedSignal` patterns
 
 #### Angular 21 New Features Compatibility
-- ✅ **Zoneless by Default**: Fully compatible with Angular 21 apps that don't include Zone.js
-- ✅ **Vitest Test Runner**: Library works in apps using Vitest-based setups
-- ✅ **Angular Aria**: Compatible with Angular Aria components; uses custom ARIA implementation for screen reader support
+- ? **Zoneless by Default**: Fully compatible with Angular 21 apps that don't include Zone.js
+- ? **Vitest Test Runner**: Library works in apps using Vitest-based setups
+- ? **Angular Aria**: Compatible with Angular Aria components; uses custom ARIA implementation for screen reader support
 
 ### Peer Dependencies
 
@@ -65,7 +65,7 @@ This document provides comprehensive compatibility information for `ngxsmk-datep
 
 **Zone.js**: Optional (declared in `peerDependenciesMeta`)
 
-## 🔄 Zone.js vs Zoneless Compatibility
+## ?? Zone.js vs Zoneless Compatibility
 
 ### Overview
 
@@ -75,12 +75,12 @@ This document provides comprehensive compatibility information for `ngxsmk-datep
 
 | Feature | With Zone.js | Without Zone.js | Notes |
 |---------|--------------|-----------------|-------|
-| **Change Detection** | ✅ Automatic | ✅ Manual (OnPush) | Component uses `OnPush` strategy |
-| **Form Integration** | ✅ Works | ✅ Works | Uses `ControlValueAccessor` |
-| **Event Handling** | ✅ Works | ✅ Works | Native event listeners |
-| **Signal Updates** | ✅ Works | ✅ Works | Signals trigger change detection |
-| **Reactive Forms** | ✅ Works | ✅ Works | FormControl integration |
-| **Signal Forms** | ✅ Works | ✅ Works | Angular 21+ signal forms |
+| **Change Detection** | ? Automatic | ? Manual (OnPush) | Component uses `OnPush` strategy |
+| **Form Integration** | ? Works | ? Works | Uses `ControlValueAccessor` |
+| **Event Handling** | ? Works | ? Works | Native event listeners |
+| **Signal Updates** | ? Works | ? Works | Signals trigger change detection |
+| **Reactive Forms** | ? Works | ? Works | FormControl integration |
+| **Signal Forms** | ? Works | ? Works | Angular 21+ signal forms |
 
 ### Zoneless Setup
 
@@ -89,7 +89,7 @@ The component uses **OnPush change detection strategy** and **signals** for reac
 ```typescript
 @Component({
   selector: 'ngxsmk-datepicker',
-  changeDetection: ChangeDetectionStrategy.OnPush, // ✅ Zoneless compatible
+  changeDetection: ChangeDetectionStrategy.OnPush, // ? Zoneless compatible
   // ...
 })
 ```
@@ -155,14 +155,14 @@ bootstrapApplication(AppComponent, {
 });
 ```
 
-### Migration Guide: Zone.js → Zoneless
+### Migration Guide: Zone.js ? Zoneless
 
 1. **Remove Zone.js dependency** (if desired)
 2. **Ensure OnPush strategy** (already used by component)
 3. **Use signals for state** (component already uses signals)
 4. **No code changes needed** - component is zoneless-ready
 
-## 🌐 SSR vs CSR Compatibility
+## ?? SSR vs CSR Compatibility
 
 ### Server-Side Rendering (SSR)
 
@@ -172,12 +172,12 @@ The component is **fully compatible** with Angular Universal and SSR.
 
 | Feature | SSR Support | Implementation |
 |---------|-------------|----------------|
-| **Platform Detection** | ✅ Safe | Uses `isPlatformBrowser()` and `PLATFORM_ID` |
-| **DOM Access** | ✅ Safe | Guarded with `isBrowser` checks |
-| **Event Listeners** | ✅ Safe | Only attached in browser |
-| **Date Formatting** | ✅ Safe | Uses `Intl` API (available in Node.js) |
-| **Local Storage** | ✅ Safe | Not used |
-| **Window/Document** | ✅ Safe | Guarded with platform checks |
+| **Platform Detection** | ? Safe | Uses `isPlatformBrowser()` and `PLATFORM_ID` |
+| **DOM Access** | ? Safe | Guarded with `isBrowser` checks |
+| **Event Listeners** | ? Safe | Only attached in browser |
+| **Date Formatting** | ? Safe | Uses `Intl` API (available in Node.js) |
+| **Local Storage** | ? Safe | Not used |
+| **Window/Document** | ? Safe | Guarded with platform checks |
 
 #### SSR Implementation Details
 
@@ -214,11 +214,11 @@ All features work identically in CSR mode. No special configuration needed.
 | Aspect | SSR | CSR | Notes |
 |--------|-----|-----|-------|
 | **Initial Render** | Server | Browser | Component renders on both |
-| **DOM Access** | ❌ Not Available | ✅ Available | Guarded with `isPlatformBrowser()` |
-| **Event Listeners** | ❌ Not Attached | ✅ Attached | Only in browser |
-| **Date Formatting** | ✅ Works | ✅ Works | Uses `Intl` API |
-| **Locale Detection** | ⚠️ Limited | ✅ Full | Server uses default, browser detects |
-| **Performance** | ✅ Fast Initial Load | ✅ Interactive | SSR improves SEO and initial load |
+| **DOM Access** | ? Not Available | ? Available | Guarded with `isPlatformBrowser()` |
+| **Event Listeners** | ? Not Attached | ? Attached | Only in browser |
+| **Date Formatting** | ? Works | ? Works | Uses `Intl` API |
+| **Locale Detection** | ?? Limited | ? Full | Server uses default, browser detects |
+| **Performance** | ? Fast Initial Load | ? Interactive | SSR improves SEO and initial load |
 
 ### SSR Setup Example
 
@@ -250,7 +250,7 @@ export class MyComponent {
 }
 ```
 
-## 🧩 Shadow DOM & Web Components Compatibility
+## ?? Shadow DOM & Web Components Compatibility
 
 `ngxsmk-datepicker` is fully compatible with **Shadow DOM encapsulation** (`ViewEncapsulation.ShadowDom`) and deployment as an **Angular Element (Custom Web Component)** inside other frameworks (React, Vue, etc.).
 
@@ -262,39 +262,39 @@ When components are loaded inside a Shadow root, the browser retargets event tar
 * Falls back to standard light DOM `.contains(target)` when composed paths are not supported by the environment.
 * Supported across both the primary Datepicker component and Custom Select dropdown components.
 
-## 🔧 Feature Compatibility Matrix
+## ?? Feature Compatibility Matrix
 
 ### By Angular Version
 
 | Feature | Angular 17 | Angular 18 | Angular 19 | Angular 20 | Angular 21+ |
 |---------|------------|-----------|------------|------------|-------------|
-| **Standalone Component** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Signals** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Shadow DOM Support** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Computed Signals** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Effects** | ⚠️ Limited | ✅ | ✅ | ✅ | ✅ |
-| **Signal Forms** | ❌ | ❌ | ❌ | ❌ | ✅ |
-| **ControlValueAccessor** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Reactive Forms** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **OnPush Strategy** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **SSR Support** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Zoneless Support** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Translations/i18n** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **Locale Registry** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Standalone Component** | ? | ? | ? | ? | ? |
+| **Signals** | ? | ? | ? | ? | ? |
+| **Shadow DOM Support** | ? | ? | ? | ? | ? |
+| **Computed Signals** | ? | ? | ? | ? | ? |
+| **Effects** | ?? Limited | ? | ? | ? | ? |
+| **Signal Forms** | ? | ? | ? | ? | ? |
+| **ControlValueAccessor** | ? | ? | ? | ? | ? |
+| **Reactive Forms** | ? | ? | ? | ? | ? |
+| **OnPush Strategy** | ? | ? | ? | ? | ? |
+| **SSR Support** | ? | ? | ? | ? | ? |
+| **Zoneless Support** | ? | ? | ? | ? | ? |
+| **Translations/i18n** | ? | ? | ? | ? | ? |
+| **Locale Registry** | ? | ? | ? | ? | ? |
 
 ### By Configuration
 
 | Configuration | Zone.js | Zoneless | SSR | CSR |
 |---------------|---------|----------|-----|-----|
-| **Change Detection** | ✅ Auto | ✅ Manual | ✅ Works | ✅ Works |
-| **Form Integration** | ✅ Works | ✅ Works | ✅ Works | ✅ Works |
-| **Event Handling** | ✅ Works | ✅ Works | ⚠️ Browser Only | ✅ Works |
-| **Signal Updates** | ✅ Works | ✅ Works | ✅ Works | ✅ Works |
-| **Date Formatting** | ✅ Works | ✅ Works | ✅ Works | ✅ Works |
-| **Keyboard Navigation** | ✅ Works | ✅ Works | ⚠️ Browser Only | ✅ Works |
-| **Touch Gestures** | ✅ Works | ✅ Works | ⚠️ Browser Only | ✅ Works |
+| **Change Detection** | ? Auto | ? Manual | ? Works | ? Works |
+| **Form Integration** | ? Works | ? Works | ? Works | ? Works |
+| **Event Handling** | ? Works | ? Works | ?? Browser Only | ? Works |
+| **Signal Updates** | ? Works | ? Works | ? Works | ? Works |
+| **Date Formatting** | ? Works | ? Works | ? Works | ? Works |
+| **Keyboard Navigation** | ? Works | ? Works | ?? Browser Only | ? Works |
+| **Touch Gestures** | ? Works | ? Works | ?? Browser Only | ? Works |
 
-## 📝 Migration Guides
+## ?? Migration Guides
 
 ### Upgrading from Angular 17 to 21
 
@@ -356,7 +356,7 @@ When components are loaded inside a Shadow root, the browser retargets event tar
 
 3. **No component changes needed** - component is SSR-safe
 
-## ⚠️ Known Limitations
+## ?? Known Limitations
 
 ### Angular 17
 - Effects support is limited (use signals/computed instead)
@@ -370,43 +370,43 @@ When components are loaded inside a Shadow root, the browser retargets event tar
 - Requires manual change detection (handled automatically by component)
 - Form integration works the same as with Zone.js
 
-## 🧪 Testing Compatibility
+## ?? Testing Compatibility
 
 The component is tested against:
-- ✅ Angular 17, 18, 19, 20, 21
-- ✅ With and without Zone.js
-- ✅ SSR and CSR modes
-- ✅ Various browser environments
-- ✅ **Vitest Compatible**: Works in Angular 21 applications using Vitest-based test setups
+- ? Angular 17, 18, 19, 20, 21
+- ? With and without Zone.js
+- ? SSR and CSR modes
+- ? Various browser environments
+- ? **Vitest Compatible**: Works in Angular 21 applications using Vitest-based test setups
   - Library tests use Karma/Jasmine, but the library itself is fully compatible with Vitest-based apps
   - No changes needed when using Vitest in your Angular 21 application
 
-## 🆕 Angular 21 New Features Support
+## ?? Angular 21 New Features Support
 
 ### Signal Forms (Experimental)
-- ✅ **Full Support**: `[field]` input binding for direct Signal Forms integration
-- ✅ **Automatic Sync**: Two-way binding with signal form fields
-- ✅ **Validation**: Respects field validation and disabled state
-- ✅ **Server Integration**: Works with `httpResource` and `linkedSignal` patterns
+- ? **Full Support**: `[field]` input binding for direct Signal Forms integration
+- ? **Automatic Sync**: Two-way binding with signal form fields
+- ? **Validation**: Respects field validation and disabled state
+- ? **Server Integration**: Works with `httpResource` and `linkedSignal` patterns
 
 ### Zoneless by Default
-- ✅ **Fully Compatible**: Works in Angular 21 apps without Zone.js
-- ✅ **OnPush Strategy**: Uses OnPush change detection for optimal performance
-- ✅ **Signal-Based**: Leverages signals for reactive updates
-- ✅ **No Changes Needed**: Existing code works without modification
+- ? **Fully Compatible**: Works in Angular 21 apps without Zone.js
+- ? **OnPush Strategy**: Uses OnPush change detection for optimal performance
+- ? **Signal-Based**: Leverages signals for reactive updates
+- ? **No Changes Needed**: Existing code works without modification
 
 ### Vitest Test Runner
-- ✅ **Compatible**: Library works in apps using Vitest-based setups
-- ✅ **No Migration Required**: Use the library as-is in Vitest-based projects
-- ✅ **Test Suite**: Library tests use Karma/Jasmine but library is Vitest-compatible
+- ? **Compatible**: Library works in apps using Vitest-based setups
+- ? **No Migration Required**: Use the library as-is in Vitest-based projects
+- ? **Test Suite**: Library tests use Karma/Jasmine but library is Vitest-compatible
 
 ### Angular Aria Compatibility
-- ✅ **ARIA Support**: Built-in ARIA attributes and screen reader support
-- ✅ **AriaLiveService**: Custom service for live region announcements
-- ✅ **Compatible**: Works alongside Angular Aria components
-- ✅ **Accessibility First**: All interactive elements have proper ARIA labels
+- ? **ARIA Support**: Built-in ARIA attributes and screen reader support
+- ? **AriaLiveService**: Custom service for live region announcements
+- ? **Compatible**: Works alongside Angular Aria components
+- ? **Accessibility First**: All interactive elements have proper ARIA labels
 
-## 📚 Additional Resources
+## ?? Additional Resources
 
 - [Angular Signals Documentation](https://angular.dev/guide/signals)
 - [Angular SSR Guide](https://angular.dev/guide/ssr)
@@ -415,7 +415,7 @@ The component is tested against:
 - [Vitest Documentation](https://vitest.dev/)
 - [Angular Aria Documentation](https://angular.dev/guide/accessibility/angular-aria)
 
-## 🔍 Version Detection
+## ?? Version Detection
 
 To check your Angular version:
 
@@ -429,7 +429,7 @@ To verify compatibility:
 npm list @angular/core @angular/common @angular/forms
 ```
 
-## 💡 Best Practices
+## ?? Best Practices
 
 1. **Use Signal Forms** (Angular 21+): Prefer `[field]` input for better integration
 2. **Enable SSR**: Improves SEO and initial load performance
@@ -437,7 +437,7 @@ npm list @angular/core @angular/common @angular/forms
 4. **Use OnPush**: Already enabled, ensures optimal change detection
 5. **Platform Checks**: Component handles SSR/CSR automatically
 
-## 🆘 Troubleshooting
+## ?? Troubleshooting
 
 ### Issue: Component not updating in zoneless app
 **Solution**: Component uses `markForCheck()` internally. Ensure you're using signals for reactive updates.
@@ -463,9 +463,9 @@ Recommended validation before tagging a release:
 | Lint | `npm run lint` | ESLint across workspace |
 | E2E (optional CI) | `npm run e2e` with `BASE_URL` pointing at served demo | Playwright; set `CI=1` and start demo separately in pipelines |
 
-**Angular minors**: Keep `@angular/*` on the same minor within the workspace (`package.json`). Bump peers in library `projects/ngxsmk-datepicker/package.json` when raising supported ceiling; update this doc’s matrix table and peer JSON block together.
+**Angular minors**: Keep `@angular/*` on the same minor within the workspace (`package.json`). Bump peers in library `projects/ngxsmk-datepicker/package.json` when raising supported ceiling; update this doc�s matrix table and peer JSON block together.
 
-**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).
+**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
+# Integration Guides
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 This document provides integration examples for using ngxsmk-datepicker with popular frameworks and libraries.
 
@@ -28,7 +28,7 @@ Do not pass a theme object to the `[theme]` input; use `ThemeBuilderService` for
 
 ## Accessibility
 
-The datepicker is built with **accessibility in mind**: keyboard navigation (arrows, Enter, Escape, T/Y/N/W, etc.), ARIA roles and labels on interactive elements, and live regions for screen reader announcements. For keyboard shortcuts and ARIA options see [API.md – Keyboard Support](API.md#keyboard-support) and the ARIA-related inputs in the API reference.
+The datepicker is built with **accessibility in mind**: keyboard navigation (arrows, Enter, Escape, T/Y/N/W, etc.), ARIA roles and labels on interactive elements, and live regions for screen reader announcements. For keyboard shortcuts and ARIA options see [API.md � Keyboard Support](API.md#keyboard-support) and the ARIA-related inputs in the API reference.
 
 ## Input sanitization and CSP
 
@@ -37,7 +37,7 @@ The datepicker is built with **accessibility in mind**: keyboard navigation (arr
 
 ## Angular Material
 
-The main `ngxsmk-datepicker` bundle does **not** import `@angular/material`, so non-Material apps are not forced to install it. If you use `mat-form-field`, install Material and add the directive as below.
+The main `ngxsmk-datepicker` bundle does **not** import `@angular/material`, so non-Material apps are not forced to install it. If you use `mat-form-field`, install Material and import from the optional **`ngxsmk-datepicker/material`** entry as below.
 
 ### Installation
 
@@ -47,33 +47,15 @@ npm install @angular/material @angular/cdk ngxsmk-datepicker
 
 ### Basic Integration (Standalone Components)
 
-**Recommended:** Use the **`ngxsmkMatFormFieldControl`** directive on the datepicker so `mat-form-field` finds it. Add this directive file to your project (e.g. `ngxsmk-mat-form-field.directive.ts`) so only Material apps pull in `@angular/material`:
+**Recommended:** Import the **`ngxsmkMatFormFieldControl`** directive from the optional `ngxsmk-datepicker/material` entry so only Material apps pull in `@angular/material`:
 
 ```typescript
-// ngxsmk-mat-form-field.directive.ts
-import { Directive, forwardRef } from '@angular/core';
-import { MatFormFieldControl } from '@angular/material/form-field';
 import { NgxsmkDatepickerComponent } from 'ngxsmk-datepicker';
-
-@Directive({
-  selector: 'ngxsmk-datepicker[ngxsmkMatFormFieldControl]',
-  standalone: true,
-  providers: [
-    { provide: MatFormFieldControl, useExisting: forwardRef(() => NgxsmkDatepickerComponent) },
-  ],
-})
-export class NgxsmkDatepickerMatFormFieldControlDirective {}
-```
-
-Then in your component:
-
-```typescript
-import { NgxsmkDatepickerComponent } from 'ngxsmk-datepicker';
-import { NgxsmkDatepickerMatFormFieldControlDirective } from './ngxsmk-mat-form-field.directive'; // your local file
+import { NgxsmkDatepickerMatFormFieldControlDirective } from 'ngxsmk-datepicker/material';
 import { MatFormFieldModule } from '@angular/material/form-field';
 
 @Component({
-  imports: [MatFormFieldModule, NgxsmkDatepickerComponent, NgxsmkDatepickerMatFormFieldControlDirective, ...],
+  imports: [MatFormFieldModule, NgxsmkDatepickerComponent, NgxsmkDatepickerMatFormFieldControlDirective],
   template: `
     <mat-form-field appearance="outline">
       <mat-label>Select Date</mat-label>
@@ -133,16 +115,16 @@ export class DatepickerComponent {
 }
 ```
 
-**If you see "mat-form-field must contain a MatFormFieldControl":** Add the **`ngxsmkMatFormFieldControl`** directive to the datepicker (Option A above). Do not use `MAT_FORM_FIELD` or pass the wrong token; the directive is the supported path.
+**If you see "mat-form-field must contain a MatFormFieldControl":** Add the **`ngxsmkMatFormFieldControl`** directive from `ngxsmk-datepicker/material` to the datepicker. Do not use `MAT_FORM_FIELD` or pass the wrong token; the directive is the supported path.
 
 ### Integration with Non-Standalone Components (NgModules)
 
-Add the same directive file (see snippet above) to your project, then import it in your NgModule:
+Import the Material entry in your NgModule:
 
 ```typescript
 import { NgModule } from '@angular/core';
 import { NgxsmkDatepickerComponent } from 'ngxsmk-datepicker';
-import { NgxsmkDatepickerMatFormFieldControlDirective } from './ngxsmk-mat-form-field.directive'; // your local file
+import { NgxsmkDatepickerMatFormFieldControlDirective } from 'ngxsmk-datepicker/material';
 import { MatFormFieldModule } from '@angular/material/form-field';
 import { MatInputModule } from '@angular/material/input';
 import { ReactiveFormsModule } from '@angular/forms';

package/docs/IONIC_INTEGRATION.md

@@ -1,6 +1,6 @@
 # Ionic Framework Integration Guide
 
-**Last updated:** August 22, 2026 - **Current stable:** v3.0.5
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 This guide provides step-by-step instructions for integrating `ngxsmk-datepicker` with modern **Ionic 7, 8, & 9+** and **Angular 17–21+** applications.