ngxsmk-datepicker 3.0.5 → 3.0.6

package/docs/LOCALE-GUIDE.md

@@ -1,6 +1,6 @@
-# Locale Packs & i18n Contributor Guide
+# Locale Packs & i18n Contributor Guide
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 Guide for adding locale support and contributing translations to ngxsmk-datepicker.
 
@@ -185,7 +185,7 @@ Date formats vary by locale:
 - **US**: `MM/DD/YYYY` (e.g., 12/25/2025)
 - **Europe**: `DD/MM/YYYY` (e.g., 25/12/2025)
 - **ISO**: `YYYY-MM-DD` (e.g., 2025-12-25)
-- **Asia**: `YYYY年MM月DD日` (e.g., 2025年12月25日)
+- **Asia**: `YYYY?MM?DD?` (e.g., 2025?12?25?)
 
 The component uses `Intl.DateTimeFormat` which handles this automatically.
 

package/docs/PLUGIN-ARCHITECTURE.md

@@ -1,6 +1,6 @@
-# Plugin Architecture
+# Plugin Architecture
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 ngxsmk-datepicker features a powerful **plugin architecture** that allows you to extend and customize the component's behavior without modifying its core code. This architecture is built on a **hook-based system** that provides extension points throughout the component's lifecycle.
 
@@ -27,35 +27,35 @@ The plugin architecture in ngxsmk-datepicker is designed around the concept of *
 ### Key Concepts
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                    Datepicker Component                      │
-│                                                              │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │              Core Component Logic                     │  │
-│  │                                                       │  │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │  │
-│  │  │  Render  │  │ Validate │  │  Events  │          │  │
-│  │  │  Hooks   │  │  Hooks   │  │  Hooks   │          │  │
-│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘          │  │
-│  │       │             │             │                 │  │
-│  │       └─────────────┼─────────────┘                 │  │
-│  │                     │                               │  │
-│  │              ┌──────▼──────┐                        │  │
-│  │              │   Plugin    │                        │  │
-│  │              │   Registry  │                        │  │
-│  │              └──────┬──────┘                        │  │
-│  │                     │                               │  │
-│  └─────────────────────┼───────────────────────────────┘  │
-│                        │                                   │
-└────────────────────────┼───────────────────────────────────┘
-                         │
-                         │
-         ┌───────────────┼───────────────┐
-         │               │               │
-    ┌────▼────┐    ┌────▼────┐    ┌────▼────┐
-    │ Plugin  │    │ Plugin  │    │ Plugin  │
-    │    A    │    │    B    │    │    C    │
-    └─────────┘    └─────────┘    └─────────┘
++-------------------------------------------------------------+
+�                    Datepicker Component                      �
+�                                                              �
+�  +------------------------------------------------------+  �
+�  �              Core Component Logic                     �  �
+�  �                                                       �  �
+�  �  +----------+  +----------+  +----------+          �  �
+�  �  �  Render  �  � Validate �  �  Events  �          �  �
+�  �  �  Hooks   �  �  Hooks   �  �  Hooks   �          �  �
+�  �  +----------+  +----------+  +----------+          �  �
+�  �       �             �             �                 �  �
+�  �       +-------------+-------------+                 �  �
+�  �                     �                               �  �
+�  �              +------?------+                        �  �
+�  �              �   Plugin    �                        �  �
+�  �              �   Registry  �                        �  �
+�  �              +-------------+                        �  �
+�  �                     �                               �  �
+�  +---------------------+-------------------------------+  �
+�                        �                                   �
++------------------------+-----------------------------------+
+                         �
+                         �
+         +---------------+---------------+
+         �               �               �
+    +----?----+    +----?----+    +----?----+
+    � Plugin  �    � Plugin  �    � Plugin  �
+    �    A    �    �    B    �    �    C    �
+    +---------+    +---------+    +---------+
 ```
 
 ## Architecture Principles
@@ -65,12 +65,12 @@ The plugin architecture in ngxsmk-datepicker is designed around the concept of *
 Plugins extend functionality without modifying core code:
 
 ```typescript
-// ✅ Good: Plugin extends behavior
+// ? Good: Plugin extends behavior
 const myPlugin: DatepickerHooks = {
   validateDate: (date) => date.getDay() !== 0 // Disable Sundays
 };
 
-// ❌ Bad: Modifying core component (not possible, but conceptually wrong)
+// ? Bad: Modifying core component (not possible, but conceptually wrong)
 // Don't try to override internal methods
 ```
 
@@ -170,7 +170,7 @@ const stylingPlugin: DatepickerHooks = {
   
   getDayCellTooltip: (date, holidayLabel) => {
     if (holidayLabel) {
-      return `🎉 ${holidayLabel}`;
+      return `?? ${holidayLabel}`;
     }
     return `Date: ${date.toLocaleDateString()}`;
   }
@@ -309,7 +309,7 @@ const formattingPlugin: DatepickerHooks = {
     
     if (mode === 'range' && typeof value === 'object' && 'start' in value) {
       const range = value as { start: Date; end: Date };
-      return `${range.start.toLocaleDateString()} → ${range.end.toLocaleDateString()}`;
+      return `${range.start.toLocaleDateString()} ? ${range.end.toLocaleDateString()}`;
     }
     
     return ''; // Use default
@@ -529,20 +529,20 @@ Understanding when hooks are called helps you write effective plugins:
 ### 1. **Initialization Phase**
 
 ```
-Component Init → Calendar Generation → Hook: getDayCellClasses (for each date)
+Component Init ? Calendar Generation ? Hook: getDayCellClasses (for each date)
 ```
 
 ### 2. **User Interaction Phase**
 
 ```
 User Clicks Date
-  ↓
+  ?
 Hook: beforeDateSelect (can prevent selection)
-  ↓
+  ?
 Hook: validateDate (can prevent selection)
-  ↓
+  ?
 Date Selected (if allowed)
-  ↓
+  ?
 Hook: afterDateSelect
 ```
 
@@ -550,7 +550,7 @@ Hook: afterDateSelect
 
 ```
 Calendar Render
-  ↓
+  ?
 For each date:
   - Hook: getDayCellClasses
   - Hook: getDayCellTooltip
@@ -561,9 +561,9 @@ For each date:
 
 ```
 Key Press
-  ↓
+  ?
 Hook: handleShortcut (can handle custom shortcuts)
-  ↓
+  ?
 Default Shortcut Handling (if not handled)
 ```
 
@@ -571,9 +571,9 @@ Default Shortcut Handling (if not handled)
 
 ```
 Value Change
-  ↓
+  ?
 Hook: formatDisplayValue (for input display)
-  ↓
+  ?
 Display Updated
 ```
 
@@ -698,12 +698,12 @@ const validationPlugin = createValidationMiddleware(
 Each plugin should have a single responsibility:
 
 ```typescript
-// ✅ Good: Focused plugin
+// ? Good: Focused plugin
 const weekendBlocker: DatepickerHooks = {
   validateDate: (date) => date.getDay() !== 0 && date.getDay() !== 6
 };
 
-// ❌ Bad: Too many responsibilities
+// ? Bad: Too many responsibilities
 const megaPlugin: DatepickerHooks = {
   validateDate: (date) => { /* ... */ },
   getDayCellClasses: (date) => { /* ... */ },
@@ -718,14 +718,14 @@ const megaPlugin: DatepickerHooks = {
 Design plugins to be reusable across projects:
 
 ```typescript
-// ✅ Good: Configurable and reusable
+// ? Good: Configurable and reusable
 export function createBusinessDaysPlugin(config: BusinessDaysConfig): DatepickerHooks {
   return {
     validateDate: (date) => config.allowedDays.includes(date.getDay())
   };
 }
 
-// ❌ Bad: Hard-coded and not reusable
+// ? Bad: Hard-coded and not reusable
 const myBusinessDays: DatepickerHooks = {
   validateDate: (date) => [1, 2, 3, 4, 5].includes(date.getDay())
 };
@@ -736,7 +736,7 @@ const myBusinessDays: DatepickerHooks = {
 Keep hook functions lightweight:
 
 ```typescript
-// ✅ Good: Lightweight and memoized
+// ? Good: Lightweight and memoized
 const memoizedValidation = new Map<string, boolean>();
 
 const optimizedPlugin: DatepickerHooks = {
@@ -751,7 +751,7 @@ const optimizedPlugin: DatepickerHooks = {
   }
 };
 
-// ❌ Bad: Expensive operation on every call
+// ? Bad: Expensive operation on every call
 const slowPlugin: DatepickerHooks = {
   validateDate: (date) => {
     // Expensive API call on every validation
@@ -765,7 +765,7 @@ const slowPlugin: DatepickerHooks = {
 Use `getValidationError` for user-friendly messages:
 
 ```typescript
-// ✅ Good: Clear error messages
+// ? Good: Clear error messages
 const userFriendlyPlugin: DatepickerHooks = {
   validateDate: (date) => {
     const today = new Date();
@@ -917,12 +917,12 @@ export class BookingComponent {
 
 The plugin architecture in ngxsmk-datepicker provides:
 
-- ✅ **Non-invasive extension** - Extend without modifying core code
-- ✅ **Type safety** - Full TypeScript support
-- ✅ **Composability** - Combine multiple plugins
-- ✅ **Flexibility** - Optional and configurable
-- ✅ **Performance** - Lightweight hook system
-- ✅ **Maintainability** - Clear separation of concerns
+- ? **Non-invasive extension** - Extend without modifying core code
+- ? **Type safety** - Full TypeScript support
+- ? **Composability** - Combine multiple plugins
+- ? **Flexibility** - Optional and configurable
+- ? **Performance** - Lightweight hook system
+- ? **Maintainability** - Clear separation of concerns
 
 For more examples and detailed hook documentation, see [Extension Points Guide](./extension-points.md).
 

package/docs/SSR-EXAMPLE.md

@@ -1,6 +1,6 @@
-# Server-Side Rendering (SSR) Example
+# Server-Side Rendering (SSR) Example
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 Complete example demonstrating ngxsmk-datepicker with Angular Universal (SSR).
 
@@ -90,15 +90,15 @@ export class DatepickerDemoComponent {
 Always provide an explicit locale for SSR consistency:
 
 ```typescript
-// ❌ Bad - relies on browser API
+// ? Bad - relies on browser API
 locale = navigator.language;
 
-// ✅ Good - platform-checked
+// ? Good - platform-checked
 locale = isPlatformBrowser(this.platformId) 
   ? navigator.language || 'en-US'
   : 'en-US';
 
-// ✅ Better - use service or config
+// ? Better - use service or config
 locale = this.localeService.getLocale(); // Returns 'en-US' on server
 ```
 
@@ -107,7 +107,7 @@ locale = this.localeService.getLocale(); // Returns 'en-US' on server
 Dates work the same on server and client:
 
 ```typescript
-// ✅ Safe - Date works on both server and client
+// ? Safe - Date works on both server and client
 const today = new Date();
 const minDate = new Date(2025, 0, 1); // January 1, 2025
 ```
@@ -331,7 +331,7 @@ export class MyComponent implements AfterViewInit {
 **Solution**: Always provide explicit locale:
 
 ```typescript
-// ✅ Correct
+// ? Correct
 <ngxsmk-datepicker [locale]="'en-US'"></ngxsmk-datepicker>
 
 // Or use platform check
@@ -347,7 +347,7 @@ locale = isPlatformBrowser(this.platformId)
 **Solution**: Use consistent locale and timezone:
 
 ```typescript
-// ✅ Correct
+// ? Correct
 provideDatepickerConfig({
   locale: 'en-US',
   timezone: 'UTC' // Use UTC for consistency

package/docs/THEME-TOKENS.md

@@ -1,6 +1,6 @@
-# Theme Tokens & CSS Custom Properties
+# Theme Tokens & CSS Custom Properties
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 Complete reference for all CSS custom properties (CSS variables) available in ngxsmk-datepicker.
 

package/docs/TIMEZONE.md

@@ -1,6 +1,6 @@
-# Timezone Support
+# Timezone Support
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 ## Overview
 
@@ -147,7 +147,16 @@ const serverDate = new Date("2024-01-15T15:00:00Z");
 
 ## Optional Adapters (date-fns / Luxon)
 
-For advanced timezone operations, you may want to use specialized libraries:
+For advanced timezone operations, you may want to use specialized libraries. Built-in date adapters for the datepicker config live on the secondary entry:
+
+```typescript
+import { DateFnsAdapter, LuxonAdapter, DayjsAdapter } from 'ngxsmk-datepicker/adapters';
+import { provideDatepickerConfig } from 'ngxsmk-datepicker';
+
+provideDatepickerConfig({
+  dateAdapter: new LuxonAdapter(), // or DateFnsAdapter / DayjsAdapter
+});
+```
 
 ### date-fns-tz
 
@@ -218,10 +227,10 @@ export class MyComponent {
 **Solution**: Ensure you're setting the `timezone` property correctly:
 
 ```typescript
-// ✅ Correct
+// ? Correct
 <ngxsmk-datepicker [timezone]="'America/New_York'">
 
-// ❌ Incorrect (missing quotes)
+// ? Incorrect (missing quotes)
 <ngxsmk-datepicker [timezone]="America/New_York">
 ```
 
@@ -230,10 +239,10 @@ export class MyComponent {
 **Solution**: JavaScript Date objects are already UTC. Send them directly:
 
 ```typescript
-// ✅ Correct
+// ? Correct
 const utcString = date.toISOString(); // Send this to server
 
-// ❌ Incorrect (don't manually adjust)
+// ? Incorrect (don't manually adjust)
 const adjusted = new Date(date.getTime() - timezoneOffset); // Don't do this
 ```
 
@@ -242,10 +251,10 @@ const adjusted = new Date(date.getTime() - timezoneOffset); // Don't do this
 **Solution**: Create Date objects from ISO strings:
 
 ```typescript
-// ✅ Correct
+// ? Correct
 const date = new Date(serverResponse.dateString); // "2024-01-15T15:00:00Z"
 
-// ❌ Incorrect (may parse in wrong timezone)
+// ? Incorrect (may parse in wrong timezone)
 const date = new Date(serverResponse.dateString.replace('Z', '')); // Don't remove Z
 ```
 

package/docs/extension-points.md

@@ -1,10 +1,10 @@
-# Extension Points and Hooks
+# Extension Points and Hooks
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 ngxsmk-datepicker provides comprehensive extension points through the `hooks` input, allowing you to customize rendering, validation, keyboard shortcuts, formatting, and event handling.
 
-> **📚 For a complete understanding of the plugin architecture, see the [Plugin Architecture Guide](./PLUGIN-ARCHITECTURE.md)** which covers architecture principles, plugin patterns, lifecycle, and advanced use cases.
+> **?? For a complete understanding of the plugin architecture, see the [Plugin Architecture Guide](./PLUGIN-ARCHITECTURE.md)** which covers architecture principles, plugin patterns, lifecycle, and advanced use cases.
 
 ## Overview
 
@@ -248,7 +248,7 @@ myHooks: DatepickerHooks = {
     
     if (mode === 'range' && typeof value === 'object' && 'start' in value) {
       const range = value as { start: Date; end: Date };
-      return `${range.start.toLocaleDateString()} → ${range.end.toLocaleDateString()}`;
+      return `${range.start.toLocaleDateString()} ? ${range.end.toLocaleDateString()}`;
     }
     
     return ''; // Use default
@@ -373,7 +373,7 @@ The datepicker includes these built-in shortcuts:
 
 | Key | Action |
 |-----|--------|
-| `←` `→` `↑` `↓` | Navigate dates |
+| `?` `?` `?` `?` | Navigate dates |
 | `Page Up` | Previous month |
 | `Page Down` | Next month |
 | `Shift + Page Up` | Previous year |

package/docs/signal-forms.md

@@ -1,6 +1,6 @@
-# Signal Forms Integration
+# Signal Forms Integration
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 This guide covers using ngxsmk-datepicker with Angular 21+ Signal Forms API.
 
@@ -193,8 +193,8 @@ export class FormComponent {
 1. **Use `[field]` binding for automatic dirty tracking**: The datepicker uses the field's `setValue()` or `updateValue()` methods when available, which properly track dirty state in Angular Signal Forms.
 
 2. **Avoid mixing `[field]` with manual `(valueChange)` handlers**: If you use both `[field]` and `(valueChange)="dateField.set($event)"`, the manual handler bypasses the form API and may prevent dirty state tracking. Use one or the other:
-   - ✅ **Recommended**: Use only `[field]="myForm.dateField"` for automatic dirty tracking
-   - ⚠️ **Alternative**: Use `[value]` and `(valueChange)` with proper form API methods if you need manual control
+   - ? **Recommended**: Use only `[field]="myForm.dateField"` for automatic dirty tracking
+   - ?? **Alternative**: Use `[value]` and `(valueChange)` with proper form API methods if you need manual control
 
 3. **Manual binding pattern**: If you must use manual binding (e.g., for stability issues), ensure you update the form using the field's API methods:
    ```typescript
@@ -295,7 +295,7 @@ export class StableFormComponent {
 
 **Note:** The `$any($event)` cast may be needed if there's a type mismatch between `DatepickerValue` and your expected `Date` type.
 
-**⚠️ Warning**: Direct mutation (`this.myForm.value().myDate = newDate`) bypasses Angular's dirty tracking mechanism. Always prefer using `setValue()` or `updateValue()` when available.
+**?? Warning**: Direct mutation (`this.myForm.value().myDate = newDate`) bypasses Angular's dirty tracking mechanism. Always prefer using `setValue()` or `updateValue()` when available.
 
 ## Validation
 
@@ -569,13 +569,13 @@ If `form().dirty()` returns `false` after selecting a date:
 
 1. **Ensure you're using `[field]` binding**: The `[field]` input automatically uses the form's API methods to track dirty state.
    ```html
-   <!-- ✅ Correct - uses [field] binding -->
+   <!-- ? Correct - uses [field] binding -->
    <ngxsmk-datepicker [field]="myForm.dateField" mode="single"></ngxsmk-datepicker>
    ```
 
 2. **Avoid mixing `[field]` with manual `(valueChange)`**: Don't use both together, as the manual handler may bypass form tracking:
    ```html
-   <!-- ❌ Incorrect - manual handler bypasses form API -->
+   <!-- ? Incorrect - manual handler bypasses form API -->
    <ngxsmk-datepicker 
      [field]="myForm.dateField"
      (valueChange)="dateField.set($event)"
@@ -586,10 +586,10 @@ If `form().dirty()` returns `false` after selecting a date:
 3. **Use form API methods in manual handlers**: If you must use manual binding, use `setValue()` or `updateValue()`:
    ```typescript
    onDateChange(newDate: Date): void {
-     // ✅ Correct - uses form API
+     // ? Correct - uses form API
      this.myForm.dateField.setValue(newDate);
      
-     // ❌ Incorrect - bypasses dirty tracking
+     // ? Incorrect - bypasses dirty tracking
      // this.dateField.set(newDate);
    }
    ```

package/docs/signals.md

@@ -1,6 +1,6 @@
-# Signals Integration Guide
+# Signals Integration Guide
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 ngxsmk-datepicker is fully compatible with Angular Signals, providing seamless integration with both traditional reactive forms and modern signal-based patterns.
 

package/docs/ssr.md

@@ -1,6 +1,6 @@
-# Server-Side Rendering (SSR) Guide
+# Server-Side Rendering (SSR) Guide
 
-**Last updated:** July 29, 2026 - **Current stable:** v3.0.3
+**Last updated:** September 8, 2026 - **Current stable:** v3.0.6
 
 ngxsmk-datepicker is fully compatible with Angular Universal and server-side rendering. This guide covers SSR setup, best practices, and troubleshooting.
 
@@ -8,11 +8,11 @@ ngxsmk-datepicker is fully compatible with Angular Universal and server-side ren
 
 The datepicker is designed to work seamlessly in both server and browser environments:
 
-- ✅ All browser-only APIs are guarded with platform checks
-- ✅ No direct `window` or `document` access during initialization
-- ✅ Event listeners only attach in browser environment
-- ✅ Compatible with Angular Universal
-- ✅ Supports partial hydration
+- ? All browser-only APIs are guarded with platform checks
+- ? No direct `window` or `document` access during initialization
+- ? Event listeners only attach in browser environment
+- ? Compatible with Angular Universal
+- ? Supports partial hydration
 
 ## Basic SSR Setup
 
@@ -167,10 +167,10 @@ npm run serve:ssr
 **Solution**: Ensure date values are properly serialized/deserialized. Use `Date` objects, not strings, when possible:
 
 ```typescript
-// ❌ Bad - may cause issues
+// ? Bad - may cause issues
 date: "2024-01-15"
 
-// ✅ Good
+// ? Good
 date: new Date("2024-01-15")
 ```
 
@@ -231,8 +231,8 @@ Browser-only features are lazily initialized:
 
 The datepicker works with or without Zone.js:
 
-- ✅ Works with Zone.js (default)
-- ✅ Works without Zone.js (zoneless)
+- ? Works with Zone.js (default)
+- ? Works without Zone.js (zoneless)
 - Uses `ChangeDetectorRef.markForCheck()` for manual change detection
 - Compatible with Angular's zoneless mode