ngxsmk-datepicker 2.3.1 → 2.4.0

package/docs/extension-points.md

@@ -1,419 +1,419 @@
-# Extension Points and Hooks
-
-**Last updated:** June 3, 2026 - **Current stable:** v2.3.1
-
-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.
-
-## Overview
-
-The `hooks` input accepts a `DatepickerHooks` object that implements various hook interfaces:
-
-- **DayCellRenderHook**: Customize day cell rendering
-- **ValidationHook**: Custom validation and range rules
-- **KeyboardShortcutHook**: Custom keyboard shortcuts
-- **DateFormatHook**: Custom date formatting
-- **EventHook**: Event lifecycle hooks
-
-## Basic Usage
-
-```typescript
-import { Component } from '@angular/core';
-import { NgxsmkDatepickerComponent, DatepickerHooks } from 'ngxsmk-datepicker';
-
-@Component({
-  selector: 'app-custom',
-  standalone: true,
-  imports: [NgxsmkDatepickerComponent],
-  template: `
-    <ngxsmk-datepicker
-      [hooks]="myHooks"
-      mode="single">
-    </ngxsmk-datepicker>
-  `
-})
-export class CustomComponent {
-  myHooks: DatepickerHooks = {
-    // Implement hook methods here
-  };
-}
-```
-
-## Day Cell Rendering Hooks
-
-### Custom CSS Classes
-
-Add custom CSS classes to day cells:
-
-```typescript
-myHooks: DatepickerHooks = {
-  getDayCellClasses: (date, isSelected, isDisabled, isToday, isHoliday) => {
-    const classes: string[] = [];
-    
-    // Add custom class for weekends
-    if (date.getDay() === 0 || date.getDay() === 6) {
-      classes.push('weekend-day');
-    }
-    
-    // Add custom class for first of month
-    if (date.getDate() === 1) {
-      classes.push('first-of-month');
-    }
-    
-    return classes;
-  }
-};
-```
-
-### Custom Tooltips
-
-Customize tooltip text for day cells:
-
-```typescript
-myHooks: DatepickerHooks = {
-  getDayCellTooltip: (date, holidayLabel) => {
-    if (holidayLabel) {
-      return `Holiday: ${holidayLabel}`;
-    }
-    
-    // Add custom tooltip for specific dates
-    if (date.getDate() === 15) {
-      return 'Mid-month special';
-    }
-    
-    return null; // Use default
-  }
-};
-```
-
-### Custom Day Number Formatting
-
-Format the day number display:
-
-```typescript
-myHooks: DatepickerHooks = {
-  formatDayNumber: (date) => {
-    // Add suffix (1st, 2nd, 3rd, etc.)
-    const day = date.getDate();
-    const suffix = day === 1 || day === 21 || day === 31 ? 'st' :
-                   day === 2 || day === 22 ? 'nd' :
-                   day === 3 || day === 23 ? 'rd' : 'th';
-    return `${day}${suffix}`;
-  }
-};
-```
-
-## Validation Hooks
-
-### Custom Date Validation
-
-Add custom validation logic:
-
-```typescript
-myHooks: DatepickerHooks = {
-  validateDate: (date, currentValue, mode) => {
-    // Prevent selecting dates in the past
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-    if (date < today) {
-      return false;
-    }
-    
-    // Prevent selecting more than 5 dates in multiple mode
-    if (mode === 'multiple' && Array.isArray(currentValue)) {
-      if (currentValue.length >= 5) {
-        return false;
-      }
-    }
-    
-    return true;
-  }
-};
-```
-
-### Custom Range Validation
-
-Validate date ranges:
-
-```typescript
-myHooks: DatepickerHooks = {
-  validateRange: (startDate, endDate) => {
-    // Ensure range is at least 3 days
-    const diffTime = endDate.getTime() - startDate.getTime();
-    const diffDays = diffTime / (1000 * 60 * 60 * 24);
-    
-    if (diffDays < 3) {
-      return false; // Range too short
-    }
-    
-    // Ensure range is not more than 30 days
-    if (diffDays > 30) {
-      return false; // Range too long
-    }
-    
-    return true;
-  },
-  
-  getValidationError: (date) => {
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-    if (date < today) {
-      return 'Cannot select past dates';
-    }
-    return null;
-  }
-};
-```
-
-## Keyboard Shortcuts
-
-### Custom Keyboard Shortcuts
-
-Add custom keyboard shortcuts:
-
-```typescript
-myHooks: DatepickerHooks = {
-  handleShortcut: (event, context) => {
-    // Custom shortcut: Ctrl+1 for first day of month
-    if (event.ctrlKey && event.key === '1') {
-      const firstDay = new Date(context.currentDate);
-      firstDay.setDate(1);
-      // Navigate to first day
-      return true; // Handled
-    }
-    
-    // Custom shortcut: Ctrl+L for last day of month
-    if (event.ctrlKey && event.key === 'l') {
-      const lastDay = new Date(context.currentDate);
-      lastDay.setMonth(lastDay.getMonth() + 1, 0);
-      // Navigate to last day
-      return true; // Handled
-    }
-    
-    return false; // Not handled, use default
-  }
-};
-```
-
-### Using customShortcuts Input
-
-Alternatively, use the `customShortcuts` input for simpler shortcuts:
-
-```typescript
-import { KeyboardShortcutContext } from 'ngxsmk-datepicker';
-
-@Component({
-  // ...
-})
-export class MyComponent {
-  shortcuts = {
-    'Ctrl+1': (context: KeyboardShortcutContext) => {
-      // Handle Ctrl+1
-      return true;
-    },
-    'Ctrl+L': (context: KeyboardShortcutContext) => {
-      // Handle Ctrl+L
-      return true;
-    }
-  };
-}
-```
-
-```html
-<ngxsmk-datepicker
-  [customShortcuts]="shortcuts"
-  mode="single">
-</ngxsmk-datepicker>
-```
-
-## Date Formatting Hooks
-
-### Custom Display Value Formatting
-
-Format the input display value:
-
-```typescript
-myHooks: DatepickerHooks = {
-  formatDisplayValue: (value, mode) => {
-    if (mode === 'single' && value instanceof Date) {
-      // Custom format: "Monday, January 15, 2024"
-      return value.toLocaleDateString('en-US', {
-        weekday: 'long',
-        year: 'numeric',
-        month: 'long',
-        day: 'numeric'
-      });
-    }
-    
-    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 ''; // Use default
-  },
-  
-  formatAriaLabel: (date) => {
-    // Custom aria-label format
-    return `Select ${date.toLocaleDateString('en-US', {
-      weekday: 'long',
-      month: 'long',
-      day: 'numeric',
-      year: 'numeric'
-    })}`;
-  }
-};
-```
-
-## Event Hooks
-
-### Lifecycle Events
-
-Hook into date selection lifecycle:
-
-```typescript
-myHooks: DatepickerHooks = {
-  beforeDateSelect: (date, currentValue) => {
-    // Called before date is selected
-    // Return false to prevent selection
-    console.log('About to select:', date);
-    
-    // Example: Prevent selection on weekends
-    const day = date.getDay();
-    if (day === 0 || day === 6) {
-      return false; // Prevent selection
-    }
-    
-    return true; // Allow selection
-  },
-  
-  afterDateSelect: (date, newValue) => {
-    // Called after date is selected
-    console.log('Date selected:', date);
-    console.log('New value:', newValue);
-    
-    // Perform side effects (API calls, analytics, etc.)
-  },
-  
-  onCalendarOpen: () => {
-    console.log('Calendar opened');
-    // Track analytics, etc.
-  },
-  
-  onCalendarClose: () => {
-    console.log('Calendar closed');
-    // Cleanup, etc.
-  }
-};
-```
-
-## Complete Example
-
-```typescript
-import { Component } from '@angular/core';
-import { NgxsmkDatepickerComponent, DatepickerHooks } from 'ngxsmk-datepicker';
-
-@Component({
-  selector: 'app-advanced',
-  standalone: true,
-  imports: [NgxsmkDatepickerComponent],
-  template: `
-    <ngxsmk-datepicker
-      [hooks]="advancedHooks"
-      [customShortcuts]="shortcuts"
-      mode="range">
-    </ngxsmk-datepicker>
-  `
-})
-export class AdvancedComponent {
-  advancedHooks: DatepickerHooks = {
-    // Custom classes
-    getDayCellClasses: (date, isSelected, isDisabled, isToday, isHoliday) => {
-      const classes: string[] = [];
-      if (date.getDay() === 0 || date.getDay() === 6) {
-        classes.push('weekend');
-      }
-      return classes;
-    },
-    
-    // Custom validation
-    validateRange: (start, end) => {
-      const days = (end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24);
-      return days >= 3 && days <= 30;
-    },
-    
-    // Custom formatting
-    formatDisplayValue: (value, mode) => {
-      if (mode === 'range' && typeof value === 'object' && 'start' in value) {
-        const r = value as { start: Date; end: Date };
-        return `${r.start.toLocaleDateString()} - ${r.end.toLocaleDateString()}`;
-      }
-      return '';
-    },
-    
-    // Event hooks
-    beforeDateSelect: (date) => {
-      return date.getDay() !== 0 && date.getDay() !== 6; // No weekends
-    }
-  };
-  
-  shortcuts = {
-    'Ctrl+Home': (context) => {
-      // Navigate to today
-      return true;
-    }
-  };
-}
-```
-
-## Built-in Keyboard Shortcuts
-
-The datepicker includes these built-in shortcuts:
-
-| Key | Action |
-|-----|--------|
-| `←` `→` `↑` `↓` | Navigate dates |
-| `Page Up` | Previous month |
-| `Page Down` | Next month |
-| `Shift + Page Up` | Previous year |
-| `Shift + Page Down` | Next year |
-| `Home` | First day of month |
-| `End` | Last day of month |
-| `Enter` / `Space` | Select focused date |
-| `Escape` | Close calendar |
-| `T` | Select today |
-| `Y` | Select yesterday |
-| `N` | Select tomorrow |
-| `W` | Select next week |
-
-Disable shortcuts:
-```html
-<ngxsmk-datepicker
-  [enableKeyboardShortcuts]="false"
-  mode="single">
-</ngxsmk-datepicker>
-```
-
-## Best Practices
-
-1. **Performance**: Keep hook functions lightweight and memoize expensive operations
-2. **Accessibility**: Ensure custom formatting maintains accessibility
-3. **Validation**: Provide clear error messages via `getValidationError`
-4. **Consistency**: Use consistent formatting across all hooks
-5. **Testing**: Test hooks thoroughly, especially validation logic
-
-## Type Safety
-
-All hooks are fully typed with TypeScript interfaces. Use the exported types for better IDE support:
-
-```typescript
-import { 
-  DatepickerHooks,
-  KeyboardShortcutContext,
-  KeyboardShortcutHelp
-} from 'ngxsmk-datepicker';
-```
-
-
-
+# Extension Points and Hooks
+
+**Last updated:** July 2, 2026 - **Current stable:** v2.4.0
+
+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.
+
+## Overview
+
+The `hooks` input accepts a `DatepickerHooks` object that implements various hook interfaces:
+
+- **DayCellRenderHook**: Customize day cell rendering
+- **ValidationHook**: Custom validation and range rules
+- **KeyboardShortcutHook**: Custom keyboard shortcuts
+- **DateFormatHook**: Custom date formatting
+- **EventHook**: Event lifecycle hooks
+
+## Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import { NgxsmkDatepickerComponent, DatepickerHooks } from 'ngxsmk-datepicker';
+
+@Component({
+  selector: 'app-custom',
+  standalone: true,
+  imports: [NgxsmkDatepickerComponent],
+  template: `
+    <ngxsmk-datepicker
+      [hooks]="myHooks"
+      mode="single">
+    </ngxsmk-datepicker>
+  `
+})
+export class CustomComponent {
+  myHooks: DatepickerHooks = {
+    // Implement hook methods here
+  };
+}
+```
+
+## Day Cell Rendering Hooks
+
+### Custom CSS Classes
+
+Add custom CSS classes to day cells:
+
+```typescript
+myHooks: DatepickerHooks = {
+  getDayCellClasses: (date, isSelected, isDisabled, isToday, isHoliday) => {
+    const classes: string[] = [];
+    
+    // Add custom class for weekends
+    if (date.getDay() === 0 || date.getDay() === 6) {
+      classes.push('weekend-day');
+    }
+    
+    // Add custom class for first of month
+    if (date.getDate() === 1) {
+      classes.push('first-of-month');
+    }
+    
+    return classes;
+  }
+};
+```
+
+### Custom Tooltips
+
+Customize tooltip text for day cells:
+
+```typescript
+myHooks: DatepickerHooks = {
+  getDayCellTooltip: (date, holidayLabel) => {
+    if (holidayLabel) {
+      return `Holiday: ${holidayLabel}`;
+    }
+    
+    // Add custom tooltip for specific dates
+    if (date.getDate() === 15) {
+      return 'Mid-month special';
+    }
+    
+    return null; // Use default
+  }
+};
+```
+
+### Custom Day Number Formatting
+
+Format the day number display:
+
+```typescript
+myHooks: DatepickerHooks = {
+  formatDayNumber: (date) => {
+    // Add suffix (1st, 2nd, 3rd, etc.)
+    const day = date.getDate();
+    const suffix = day === 1 || day === 21 || day === 31 ? 'st' :
+                   day === 2 || day === 22 ? 'nd' :
+                   day === 3 || day === 23 ? 'rd' : 'th';
+    return `${day}${suffix}`;
+  }
+};
+```
+
+## Validation Hooks
+
+### Custom Date Validation
+
+Add custom validation logic:
+
+```typescript
+myHooks: DatepickerHooks = {
+  validateDate: (date, currentValue, mode) => {
+    // Prevent selecting dates in the past
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    if (date < today) {
+      return false;
+    }
+    
+    // Prevent selecting more than 5 dates in multiple mode
+    if (mode === 'multiple' && Array.isArray(currentValue)) {
+      if (currentValue.length >= 5) {
+        return false;
+      }
+    }
+    
+    return true;
+  }
+};
+```
+
+### Custom Range Validation
+
+Validate date ranges:
+
+```typescript
+myHooks: DatepickerHooks = {
+  validateRange: (startDate, endDate) => {
+    // Ensure range is at least 3 days
+    const diffTime = endDate.getTime() - startDate.getTime();
+    const diffDays = diffTime / (1000 * 60 * 60 * 24);
+    
+    if (diffDays < 3) {
+      return false; // Range too short
+    }
+    
+    // Ensure range is not more than 30 days
+    if (diffDays > 30) {
+      return false; // Range too long
+    }
+    
+    return true;
+  },
+  
+  getValidationError: (date) => {
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    if (date < today) {
+      return 'Cannot select past dates';
+    }
+    return null;
+  }
+};
+```
+
+## Keyboard Shortcuts
+
+### Custom Keyboard Shortcuts
+
+Add custom keyboard shortcuts:
+
+```typescript
+myHooks: DatepickerHooks = {
+  handleShortcut: (event, context) => {
+    // Custom shortcut: Ctrl+1 for first day of month
+    if (event.ctrlKey && event.key === '1') {
+      const firstDay = new Date(context.currentDate);
+      firstDay.setDate(1);
+      // Navigate to first day
+      return true; // Handled
+    }
+    
+    // Custom shortcut: Ctrl+L for last day of month
+    if (event.ctrlKey && event.key === 'l') {
+      const lastDay = new Date(context.currentDate);
+      lastDay.setMonth(lastDay.getMonth() + 1, 0);
+      // Navigate to last day
+      return true; // Handled
+    }
+    
+    return false; // Not handled, use default
+  }
+};
+```
+
+### Using customShortcuts Input
+
+Alternatively, use the `customShortcuts` input for simpler shortcuts:
+
+```typescript
+import { KeyboardShortcutContext } from 'ngxsmk-datepicker';
+
+@Component({
+  // ...
+})
+export class MyComponent {
+  shortcuts = {
+    'Ctrl+1': (context: KeyboardShortcutContext) => {
+      // Handle Ctrl+1
+      return true;
+    },
+    'Ctrl+L': (context: KeyboardShortcutContext) => {
+      // Handle Ctrl+L
+      return true;
+    }
+  };
+}
+```
+
+```html
+<ngxsmk-datepicker
+  [customShortcuts]="shortcuts"
+  mode="single">
+</ngxsmk-datepicker>
+```
+
+## Date Formatting Hooks
+
+### Custom Display Value Formatting
+
+Format the input display value:
+
+```typescript
+myHooks: DatepickerHooks = {
+  formatDisplayValue: (value, mode) => {
+    if (mode === 'single' && value instanceof Date) {
+      // Custom format: "Monday, January 15, 2024"
+      return value.toLocaleDateString('en-US', {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric'
+      });
+    }
+    
+    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 ''; // Use default
+  },
+  
+  formatAriaLabel: (date) => {
+    // Custom aria-label format
+    return `Select ${date.toLocaleDateString('en-US', {
+      weekday: 'long',
+      month: 'long',
+      day: 'numeric',
+      year: 'numeric'
+    })}`;
+  }
+};
+```
+
+## Event Hooks
+
+### Lifecycle Events
+
+Hook into date selection lifecycle:
+
+```typescript
+myHooks: DatepickerHooks = {
+  beforeDateSelect: (date, currentValue) => {
+    // Called before date is selected
+    // Return false to prevent selection
+    console.log('About to select:', date);
+    
+    // Example: Prevent selection on weekends
+    const day = date.getDay();
+    if (day === 0 || day === 6) {
+      return false; // Prevent selection
+    }
+    
+    return true; // Allow selection
+  },
+  
+  afterDateSelect: (date, newValue) => {
+    // Called after date is selected
+    console.log('Date selected:', date);
+    console.log('New value:', newValue);
+    
+    // Perform side effects (API calls, analytics, etc.)
+  },
+  
+  onCalendarOpen: () => {
+    console.log('Calendar opened');
+    // Track analytics, etc.
+  },
+  
+  onCalendarClose: () => {
+    console.log('Calendar closed');
+    // Cleanup, etc.
+  }
+};
+```
+
+## Complete Example
+
+```typescript
+import { Component } from '@angular/core';
+import { NgxsmkDatepickerComponent, DatepickerHooks } from 'ngxsmk-datepicker';
+
+@Component({
+  selector: 'app-advanced',
+  standalone: true,
+  imports: [NgxsmkDatepickerComponent],
+  template: `
+    <ngxsmk-datepicker
+      [hooks]="advancedHooks"
+      [customShortcuts]="shortcuts"
+      mode="range">
+    </ngxsmk-datepicker>
+  `
+})
+export class AdvancedComponent {
+  advancedHooks: DatepickerHooks = {
+    // Custom classes
+    getDayCellClasses: (date, isSelected, isDisabled, isToday, isHoliday) => {
+      const classes: string[] = [];
+      if (date.getDay() === 0 || date.getDay() === 6) {
+        classes.push('weekend');
+      }
+      return classes;
+    },
+    
+    // Custom validation
+    validateRange: (start, end) => {
+      const days = (end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24);
+      return days >= 3 && days <= 30;
+    },
+    
+    // Custom formatting
+    formatDisplayValue: (value, mode) => {
+      if (mode === 'range' && typeof value === 'object' && 'start' in value) {
+        const r = value as { start: Date; end: Date };
+        return `${r.start.toLocaleDateString()} - ${r.end.toLocaleDateString()}`;
+      }
+      return '';
+    },
+    
+    // Event hooks
+    beforeDateSelect: (date) => {
+      return date.getDay() !== 0 && date.getDay() !== 6; // No weekends
+    }
+  };
+  
+  shortcuts = {
+    'Ctrl+Home': (context) => {
+      // Navigate to today
+      return true;
+    }
+  };
+}
+```
+
+## Built-in Keyboard Shortcuts
+
+The datepicker includes these built-in shortcuts:
+
+| Key | Action |
+|-----|--------|
+| `←` `→` `↑` `↓` | Navigate dates |
+| `Page Up` | Previous month |
+| `Page Down` | Next month |
+| `Shift + Page Up` | Previous year |
+| `Shift + Page Down` | Next year |
+| `Home` | First day of month |
+| `End` | Last day of month |
+| `Enter` / `Space` | Select focused date |
+| `Escape` | Close calendar |
+| `T` | Select today |
+| `Y` | Select yesterday |
+| `N` | Select tomorrow |
+| `W` | Select next week |
+
+Disable shortcuts:
+```html
+<ngxsmk-datepicker
+  [enableKeyboardShortcuts]="false"
+  mode="single">
+</ngxsmk-datepicker>
+```
+
+## Best Practices
+
+1. **Performance**: Keep hook functions lightweight and memoize expensive operations
+2. **Accessibility**: Ensure custom formatting maintains accessibility
+3. **Validation**: Provide clear error messages via `getValidationError`
+4. **Consistency**: Use consistent formatting across all hooks
+5. **Testing**: Test hooks thoroughly, especially validation logic
+
+## Type Safety
+
+All hooks are fully typed with TypeScript interfaces. Use the exported types for better IDE support:
+
+```typescript
+import { 
+  DatepickerHooks,
+  KeyboardShortcutContext,
+  KeyboardShortcutHelp
+} from 'ngxsmk-datepicker';
+```
+
+
+