@oneluiz/dual-datepicker 2.4.0 → 2.6.0

package/README.md

@@ -1,30 +1,84 @@
-# @oneluiz/dual-datepicker
+# ng-dual-datepicker
 
-A beautiful, customizable dual-calendar date range picker for Angular 17+. Built as a standalone component with full TypeScript support.
+A lightweight, zero-dependency date range picker for Angular 17+. Built with standalone components, Reactive Forms, and Angular Signals. No Angular Material required.
 
 [![npm version](https://img.shields.io/npm/v/@oneluiz/dual-datepicker)](https://www.npmjs.com/package/@oneluiz/dual-datepicker)
 ![license](https://img.shields.io/npm/l/@oneluiz/dual-datepicker)
 ![Angular](https://img.shields.io/badge/Angular-17%2B-red)
 
+```bash
+npm install @oneluiz/dual-datepicker
+```
+
 ## 🎯 [Live Demo](https://oneluiz.github.io/ng-dual-datepicker/)
 
 **[Check out the interactive examples →](https://oneluiz.github.io/ng-dual-datepicker/)**
 
-## ✨ Features
-
-- 📅 **Dual Calendar Display** - Side-by-side month view for easy range selection
-- 🎨 **Fully Customizable** - Color scheme, padding, and styling
-- ⚡ **Preset Ranges** - Configurable quick-select options
-- 🧹 **Clear Button** - Built-in button to reset selection
-- 🎯 **Standalone Component** - No module imports required
-- 🚀 **Zero Dependencies** - No Bootstrap or other CSS frameworks required
-- 🌍 **i18n Support** - Customizable month and day names for any language
-- 📱 **Responsive Design** - Works on desktop and mobile
-- 🌐 **TypeScript** - Full type safety
-- ♿ **Accessible** - Keyboard navigation and ARIA labels
-- 🎭 **Flexible Behavior** - Control when the picker closes
-- 🔄 **Reactive Forms Support** - Full ControlValueAccessor implementation
-- ⚡ **Angular Signals** - Modern reactive state management
+## Why ng-dual-datepicker?
+
+| Feature | ng-dual-datepicker | Angular Material DateRangePicker |
+|---------|-------------------|----------------------------------|
+| **Bundle Size** | ~60 KB gzipped | ~300+ KB (with dependencies) |
+| **Dependencies** | Zero | Requires @angular/material, @angular/cdk |
+| **Standalone** | ✅ Native | ⚠️ Requires module setup |
+| **Signals Support** | ✅ Built-in | ❌ Not yet |
+| **Customization** | Full styling control | Theme-constrained |
+| **Learning Curve** | Minimal | Requires Material knowledge |
+| **Change Detection** | OnPush optimized | Default |
+| **Setup Time** | < 1 minute | ~10+ minutes (theming, modules) |
+
+## ✨ Key Features
+
+- 🪶 **Zero Dependencies** – No external libraries required
+- 🎯 **Standalone Component** – No NgModule imports needed
+- ⚡ **Angular Signals** – Modern reactive state management
+- 🔄 **Reactive Forms** – Full ControlValueAccessor implementation
+- 🎨 **Fully Customizable** – Every color, padding, border configurable
+- 📦 **Lightweight** – ~60 KB gzipped total bundle
+- 🚀 **Performance** – OnPush change detection + trackBy optimization
+- ♿ **Accessible** – ARIA labels, semantic HTML, keyboard navigation (in progress)
+- 🌍 **i18n Ready** – Customizable month/day names
+- 📱 **Responsive** – Works on desktop and mobile
+
+## 🤔 When Should I Use This?
+
+**Use ng-dual-datepicker if you:**
+- Don't want to install Angular Material just for a date picker
+- Need precise control over styling and behavior
+- Want minimal bundle size impact
+- Prefer standalone components over NgModules
+- Need Angular Signals support now
+- Are building a custom design system
+
+**Use Angular Material DateRangePicker if you:**
+- Already use Angular Material throughout your app
+- Need Material Design compliance
+- Want a battle-tested enterprise solution with extensive ecosystem support
+
+## ⚡ Performance
+
+```typescript
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush, // ✅ Optimized
+  standalone: true                                   // ✅ No module overhead
+})
+```
+
+- **OnPush change detection** – Minimal re-renders
+- **trackBy functions** – Efficient list rendering
+- **No external CSS** – No runtime stylesheet downloads
+- **Tree-shakeable** – Only import what you use
+
+## ♿ Accessibility (A11y)
+
+**Current Status:**
+- ✅ **Screen reader support** - ARIA labels included for all interactive elements
+- ✅ **Semantic HTML** - Proper HTML structure
+- 🚧 **Full keyboard navigation** - In active development (see [Roadmap](#-roadmap))
+  - Mouse/touch interaction: ✅ Fully supported
+  - Keyboard navigation: 🚧 In progress
+
+> **Note:** Full keyboard navigation support is planned and will be included in a future release. This includes arrow key navigation, Enter/Space selection, and Escape to close.
 
 ## 📦 Installation
 
@@ -34,7 +88,7 @@ npm install @oneluiz/dual-datepicker
 
 ## 🚀 Quick Start
 
-### 1. Import the Component
+### Basic Usage
 
 ```typescript
 import { Component } from '@angular/core';
@@ -46,104 +100,58 @@ import { DualDatepickerComponent, DateRange } from '@oneluiz/dual-datepicker';
   imports: [DualDatepickerComponent],
   template: `
     <ngx-dual-datepicker
-      [(ngModel)]="dateRange"
-      placeholder="Select date range">
+      (dateRangeChange)="onRangeChange($event)">
     </ngx-dual-datepicker>
   `
 })
 export class AppComponent {
-  dateRange: DateRange = { start: null, end: null };
+  onRangeChange(range: DateRange) {
+    console.log('Start:', range.fechaInicio);
+    console.log('End:', range.fechaFin);
+  }
 }
 ```
 
-### 2. Use with Forms
+### With Reactive Forms
 
 ```typescript
-import { Component } from '@angular/core';
-import { FormsModule } from '@angular/forms';
-import { DualDatepickerComponent } from '@oneluiz/dual-datepicker';
+import { FormControl } from '@angular/forms';
+import { DateRange } from '@oneluiz/dual-datepicker';
 
-@Component({
-  selector: 'app-example',
-  standalone: true,
-  imports: [FormsModule, DualDatepickerComponent],
-  template: `
-    <ngx-dual-datepicker
-      [fechaInicio]="fechaInicio"
-      [fechaFin]="fechaFin"
-      [presets]="customPresets"
-      (dateRangeChange)="onDateChange($event)">
-    </ngx-dual-datepicker>
-  `
-})
-export class ExampleComponent {
-  fechaInicio = '';
-  fechaFin = '';
-  
-  customPresets = [
-    { label: 'Last 7 days', daysAgo: 7 },
-    { label: 'Last 30 days', daysAgo: 30 },
-    { label: 'Last 90 days', daysAgo: 90 }
-  ];
+dateRange = new FormControl<DateRange | null>(null);
+```
 
-  onDateChange(range: DateRange) {
-    console.log('Date range selected:', range);
-    this.fechaInicio = range.fechaInicio;
-    this.fechaFin = range.fechaFin;
-  }
-}
+```html
+<ngx-dual-datepicker [formControl]="dateRange"></ngx-dual-datepicker>
 ```
 
-### 3. Use with Reactive Forms ✨ New!
+### With Angular Signals
 
 ```typescript
-import { Component, OnInit } from '@angular/core';
-import { FormBuilder, FormGroup, ReactiveFormsModule } from '@angular/forms';
-import { DualDatepickerComponent, DateRange } from '@oneluiz/dual-datepicker';
+import { signal } from '@angular/core';
 
-@Component({
-  selector: 'app-reactive-form',
-  standalone: true,
-  imports: [ReactiveFormsModule, DualDatepickerComponent],
-  template: `
-    <form [formGroup]="form" (ngSubmit)="onSubmit()">
-      <label>Select Date Range:</label>
-      <ngx-dual-datepicker
-        formControlName="dateRange"
-        placeholder="Choose dates"
-        [showClearButton]="true">
-      </ngx-dual-datepicker>
-      
-      <button type="submit" [disabled]="!form.valid">Submit</button>
-      
-      @if (form.value.dateRange) {
-        <div>
-          Selected: {{ form.value.dateRange.fechaInicio }} to {{ form.value.dateRange.fechaFin }}
-        </div>
-      }
-    </form>
-  `
-})
-export class ReactiveFormComponent implements OnInit {
-  form!: FormGroup;
+dateRange = signal<DateRange | null>(null);
+```
 
-  constructor(private fb: FormBuilder) {}
+```html
+<ngx-dual-datepicker
+  [(ngModel)]="dateRange()"
+  (dateRangeChange)="dateRange.set($event)">
+</ngx-dual-datepicker>
+```
 
-  ngOnInit() {
-    this.form = this.fb.group({
-      dateRange: [null] // Will receive DateRange object
-    });
-    
-    // Listen to changes
-    this.form.get('dateRange')?.valueChanges.subscribe(value => {
-      console.log('Date range changed:', value);
-    });
-  }
+### Custom Styling
 
-  onSubmit() {
-    const dateRange: DateRange = this.form.value.dateRange;
-    console.log('Form submitted:', dateRange);
-  }
+```html
+<ngx-dual-datepicker
+  inputBackgroundColor="#1a1a2e"
+  inputTextColor="#eee"
+  inputBorderColor="#4a5568"
+  inputBorderColorFocus="#3182ce">
+</ngx-dual-datepicker>
+```
+
+## 📚 Advanced Usage
 }
 ```
 
@@ -203,6 +211,221 @@ export class SignalsExampleComponent {
 }
 ```
 
+## 🔌 Date Adapter System
+
+The library supports custom date adapters, allowing you to use different date libraries (DayJS, date-fns, Luxon) or custom backend models instead of native JavaScript `Date` objects.
+
+### Using Native Date (Default)
+
+By default, the component uses `NativeDateAdapter` which works with JavaScript `Date` objects:
+
+```typescript
+import { DualDatepickerComponent } from '@oneluiz/dual-datepicker';
+
+@Component({
+  standalone: true,
+  imports: [DualDatepickerComponent],
+  template: `<ngx-dual-datepicker></ngx-dual-datepicker>`
+})
+export class AppComponent {}
+```
+
+### Creating a Custom Adapter
+
+Example using **date-fns**:
+
+```typescript
+import { Injectable } from '@angular/core';
+import { DateAdapter } from '@oneluiz/dual-datepicker';
+import { 
+  parse, format, addDays, addMonths, 
+  getYear, getMonth, getDate, getDay,
+  isSameDay, isBefore, isAfter, isWithinInterval,
+  isValid 
+} from 'date-fns';
+
+@Injectable()
+export class DateFnsAdapter extends DateAdapter<Date> {
+  parse(value: any): Date | null {
+    if (!value) return null;
+    if (value instanceof Date) return value;
+    
+    const parsed = parse(value, 'yyyy-MM-dd', new Date());
+    return isValid(parsed) ? parsed : null;
+  }
+
+  format(date: Date, formatStr: string = 'yyyy-MM-dd'): string {
+    return format(date, formatStr);
+  }
+
+  addDays(date: Date, days: number): Date {
+    return addDays(date, days);
+  }
+
+  addMonths(date: Date, months: number): Date {
+    return addMonths(date, months);
+  }
+
+  getYear(date: Date): number {
+    return getYear(date);
+  }
+
+  getMonth(date: Date): number {
+    return getMonth(date);
+  }
+
+  getDate(date: Date): number {
+    return getDate(date);
+  }
+
+  getDay(date: Date): number {
+    return getDay(date);
+  }
+
+  createDate(year: number, month: number, day: number): Date {
+    return new Date(year, month, day);
+  }
+
+  today(): Date {
+    return new Date();
+  }
+
+  isSameDay(a: Date | null, b: Date | null): boolean {
+    if (!a || !b) return false;
+    return isSameDay(a, b);
+  }
+
+  isBefore(a: Date | null, b: Date | null): boolean {
+    if (!a || !b) return false;
+    return isBefore(a, b);
+  }
+
+  isAfter(a: Date | null, b: Date | null): boolean {
+    if (!a || !b) return false;
+    return isAfter(a, b);
+  }
+
+  isBetween(date: Date | null, start: Date | null, end: Date | null): boolean {
+    if (!date || !start || !end) return false;
+    return isWithinInterval(date, { start, end });
+  }
+
+  clone(date: Date): Date {
+    return new Date(date);
+  }
+
+  isValid(date: any): boolean {
+    return isValid(date);
+  }
+}
+```
+
+### Providing Custom Adapter
+
+```typescript
+import { Component } from '@angular/core';
+import { DualDatepickerComponent, DATE_ADAPTER } from '@oneluiz/dual-datepicker';
+import { DateFnsAdapter } from './date-fns-adapter';
+
+@Component({
+  standalone: true,
+  imports: [DualDatepickerComponent],
+  providers: [
+    { provide: DATE_ADAPTER, useClass: DateFnsAdapter }
+  ],
+  template: `<ngx-dual-datepicker></ngx-dual-datepicker>`
+})
+export class AppComponent {}
+```
+
+### Example: DayJS Adapter
+
+```typescript
+import { Injectable } from '@angular/core';
+import { DateAdapter } from '@oneluiz/dual-datepicker';
+import dayjs, { Dayjs } from 'dayjs';
+
+@Injectable()
+export class DayJSAdapter extends DateAdapter<Dayjs> {
+  parse(value: any): Dayjs | null {
+    if (!value) return null;
+    const parsed = dayjs(value);
+    return parsed.isValid() ? parsed : null;
+  }
+
+  format(date: Dayjs, format: string = 'YYYY-MM-DD'): string {
+    return date.format(format);
+  }
+
+  addDays(date: Dayjs, days: number): Dayjs {
+    return date.add(days, 'day');
+  }
+
+  addMonths(date: Dayjs, months: number): Dayjs {
+    return date.add(months, 'month');
+  }
+
+  getYear(date: Dayjs): number {
+    return date.year();
+  }
+
+  getMonth(date: Dayjs): number {
+    return date.month();
+  }
+
+  getDate(date: Dayjs): number {
+    return date.date();
+  }
+
+  getDay(date: Dayjs): number {
+    return date.day();
+  }
+
+  createDate(year: number, month: number, day: number): Dayjs {
+    return dayjs().year(year).month(month).date(day);
+  }
+
+  today(): Dayjs {
+    return dayjs();
+  }
+
+  isSameDay(a: Dayjs | null, b: Dayjs | null): boolean {
+    if (!a || !b) return false;
+    return a.isSame(b, 'day');
+  }
+
+  isBefore(a: Dayjs | null, b: Dayjs | null): boolean {
+    if (!a || !b) return false;
+    return a.isBefore(b);
+  }
+
+  isAfter(a: Dayjs | null, b: Dayjs | null): boolean {
+    if (!a || !b) return false;
+    return a.isAfter(b);
+  }
+
+  isBetween(date: Dayjs | null, start: Dayjs | null, end: Dayjs | null): boolean {
+    if (!date || !start || !end) return false;
+    return date.isAfter(start) && date.isBefore(end) || date.isSame(start) || date.isSame(end);
+  }
+
+  clone(date: Dayjs): Dayjs {
+    return date.clone();
+  }
+
+  isValid(date: any): boolean {
+    return dayjs.isDayjs(date) && date.isValid();
+  }
+}
+```
+
+### Benefits of Date Adapters
+
+- ✅ **Zero vendor lock-in** - Use any date library you prefer
+- ✅ **Consistency** - Use the same date library across your entire app
+- ✅ **Custom backend models** - Adapt to your API's date format
+- ✅ **Type safety** - Full TypeScript support with generics
+
 ## 🎨 Customization
 
 ### Custom Colors (Bootstrap Style)
@@ -233,7 +456,11 @@ export class SignalsExampleComponent {
 </ngx-dual-datepicker>
 ```
 
-### Custom Presets
+### ⚡ Custom Presets (Power Feature)
+
+**This is where our library shines!** Unlike Angular Material, we offer an incredibly flexible preset system perfect for dashboards, reporting, POS, BI apps, and ERP systems.
+
+#### Simple Pattern (Backward Compatible)
 
 ```typescript
 customPresets: PresetConfig[] = [
@@ -244,6 +471,132 @@ customPresets: PresetConfig[] = [
 ];
 ```
 
+#### **NEW v2.6.0** - Flexible Pattern with `getValue()` 🔥
+
+The real power comes with the `getValue()` pattern. Define **any custom logic** you need:
+
+```typescript
+import { PresetConfig } from '@oneluiz/dual-datepicker';
+
+customPresets: PresetConfig[] = [
+  { 
+    label: 'Today', 
+    getValue: () => {
+      const today = new Date();
+      return {
+        start: formatDate(today),
+        end: formatDate(today)
+      };
+    }
+  },
+  { 
+    label: 'This Month', 
+    getValue: () => {
+      const today = new Date();
+      const start = new Date(today.getFullYear(), today.getMonth(), 1);
+      const end = new Date(today.getFullYear(), today.getMonth() + 1, 0);
+      return {
+        start: formatDate(start),
+        end: formatDate(end)
+      };
+    }
+  },
+  { 
+    label: 'Last Month', 
+    getValue: () => {
+      const today = new Date();
+      const start = new Date(today.getFullYear(), today.getMonth() - 1, 1);
+      const end = new Date(today.getFullYear(), today.getMonth(), 0);
+      return {
+        start: formatDate(start),
+        end: formatDate(end)
+      };
+    }
+  },
+  { 
+    label: 'Quarter to Date', 
+    getValue: () => {
+      const today = new Date();
+      const currentMonth = today.getMonth();
+      const quarterStartMonth = Math.floor(currentMonth / 3) * 3;
+      const start = new Date(today.getFullYear(), quarterStartMonth, 1);
+      return {
+        start: formatDate(start),
+        end: formatDate(today)
+      };
+    }
+  }
+];
+```
+
+#### **Even Better** - Use Pre-built Utilities 🚀
+
+We provide **ready-to-use preset utilities** for common scenarios:
+
+```typescript
+import { CommonPresets } from '@oneluiz/dual-datepicker';
+
+// Dashboard presets
+presets = CommonPresets.dashboard;
+// → Today, Yesterday, Last 7 days, Last 30 days, This month, Last month
+
+// Reporting presets
+presets = CommonPresets.reporting;
+// → Today, This week, Last week, This month, Last month, This quarter, Last quarter
+
+// Financial/ERP presets
+presets = CommonPresets.financial;
+// → Month to date, Quarter to date, Year to date, Last month, Last quarter, Last year
+
+// Analytics/BI presets
+presets = CommonPresets.analytics;
+// → Last 7/14/30/60/90/180/365 days
+
+// Simple presets
+presets = CommonPresets.simple;
+// → Today, Last 7 days, Last 30 days, This year
+```
+
+#### Create Your Own Utilities
+
+Import individual utilities and mix them:
+
+```typescript
+import { 
+  getToday, 
+  getThisMonth, 
+  getLastMonth, 
+  getQuarterToDate,
+  getYearToDate,
+  PresetConfig 
+} from '@oneluiz/dual-datepicker';
+
+customPresets: PresetConfig[] = [
+  { label: 'Today', getValue: getToday },
+  { label: 'This Month', getValue: getThisMonth },
+  { label: 'Last Month', getValue: getLastMonth },
+  { label: 'Quarter to Date', getValue: getQuarterToDate },
+  { label: 'Year to Date', getValue: getYearToDate },
+  { 
+    label: 'Custom Logic', 
+    getValue: () => {
+      // Your custom date calculation
+      return { start: '2026-01-01', end: '2026-12-31' };
+    }
+  }
+];
+```
+
+#### Why This Is Powerful
+
+✅ **Perfect for Dashboards** - "Last 7 days", "Month to date", "Quarter to date"  
+✅ **Perfect for Reporting** - "This week", "Last week", "This quarter"  
+✅ **Perfect for Financial Systems** - "Quarter to date", "Year to date", "Fiscal year"  
+✅ **Perfect for Analytics** - Consistent date ranges for BI tools  
+✅ **Perfect for ERP** - Custom business logic and fiscal calendars  
+
+**Angular Material doesn't offer this level of flexibility!** 🎯
+
 ```html
 <ngx-dual-datepicker
   [(ngModel)]="dateRange"
@@ -311,14 +664,23 @@ export class MyComponent {
 ### Types
 
 ```typescript
-infechaInicio: string;  // ISO date format: 'YYYY-MM-DD'
+interface DateRange {
+  fechaInicio: string;  // ISO date format: 'YYYY-MM-DD'
   fechaFin: string;     // ISO date format: 'YYYY-MM-DD'
   rangoTexto: string;   // Display text: 'DD Mon - DD Mon'
 }
 
+interface PresetRange {
+  start: string;  // ISO date format: 'YYYY-MM-DD'
+  end: string;    // ISO date format: 'YYYY-MM-DD'
+}
+
 interface PresetConfig {
   label: string;
-  daysAgo: number;
+  /** @deprecated Use getValue() instead for more flexibility */
+  daysAgo?: number;
+  /** NEW v2.6.0 - Function that returns date range with custom logic */
+  getValue?: () => PresetRange;
 }
 
 interface LocaleConfig {
@@ -327,7 +689,6 @@ interface LocaleConfig {
   dayNames?: string[];           // Full day names (7 items, starting Sunday)
   dayNamesShort?: string[];      // Short day names (7 items, starting Sunday)
   firstDayOfWeek?: number;       // 0 = Sunday, 1 = Monday, etc. (not yet implemented)
-  daysAgo: number;
 }
 ```
 
@@ -455,6 +816,25 @@ export class ExampleComponent {
 - Angular 19.0.0 or higher
 - Angular 20.0.0 or higher
 
+## 🗺️ Roadmap
+
+Recently shipped:
+
+**v2.6.0:**
+- ✅ **Flexible Preset System** - `getValue()` pattern for custom date logic (This month, Last month, Quarter to date, etc.)
+- ✅ **Pre-built Preset Utilities** - CommonPresets for Dashboard, Reporting, Financial, Analytics
+- ✅ **Real Differentiator** - Perfect for ERP, BI, POS, and Reporting systems
+
+**v2.5.0:**
+- ✅ **Date Adapter System** - Support for DayJS, date-fns, Luxon, and custom date libraries
+
+Planned features and improvements:
+
+- ⬜ **Complete keyboard navigation** - Arrow keys, Enter/Space, Tab, Escape
+- ⬜ **Full accessibility audit** - WCAG 2.1 AA compliance
+- ⬜ **Multi-range support** - Select multiple date ranges
+- ⬜ **Theming system** - Pre-built theme presets
+
 ## 📄 License
 
 MIT © Luis Cortes