@oneluiz/dual-datepicker 3.1.1 → 3.3.0

package/README.md

@@ -3,6 +3,7 @@
 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)
+[![npm provenance](https://img.shields.io/badge/provenance-available-brightgreen)](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)
 
@@ -10,20 +11,958 @@ A lightweight, zero-dependency date range picker for Angular 17+. Built with sta
 npm install @oneluiz/dual-datepicker
 ```
 
-> ## ⚠️ **BREAKING CHANGES in v3.0.0**
->
-> - **All DateRange properties renamed to English**: `fechaInicio` → `startDate`, `fechaFin` → `endDate`, `rangoTexto` → `rangeText`
-> - **Deprecated `daysAgo` removed**: Use `getValue: () => PresetRange` pattern or `CommonPresets` instead
-> - **All component methods renamed to English**: `limpiar()` → `clear()`, etc.
-> 
-> **📖 See [MIGRATION_V3.md](MIGRATION_V3.md) for complete migration guide**
->
-> To stay on v2.x: `npm install @oneluiz/dual-datepicker@2.7.0`
-
 ## 🎯 [Live Demo](https://oneluiz.github.io/ng-dual-datepicker/)
 
 **[Check out the interactive examples →](https://oneluiz.github.io/ng-dual-datepicker/)**
 
+---
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Why Choose This Library?](#-why-choose-this-library)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+  - [Basic Usage](#basic-usage)
+  - [Reactive Forms](#with-reactive-forms)
+  - [Angular Signals](#with-angular-signals)
+- [Advanced Features](#-advanced-features)
+  - [Multi-Range Selection](#multi-range-support)
+  - [Disabled Dates](#disabled-dates)
+  - [Display Format](#display-format)
+  - [Apply/Confirm Button](#applyconfirm-button)
+  - [Hover Range Preview](#hover-range-preview)
+  - [Custom Presets](#custom-presets)
+  - [Date Adapter System](#date-adapter-system)
+  - [Keyboard Navigation](#keyboard-navigation)
+- [Customization](#-customization)
+  - [Theming System](#theming-system)
+  - [Styling Options](#styling-options)
+  - [Localization (i18n)](#localization-i18n)
+- [API Reference](#-api-reference)
+  - [Inputs](#inputs)
+  - [Outputs](#outputs)
+  - [Methods](#public-methods)
+  - [Types](#types)
+- [Examples](#-usage-examples)
+- [Accessibility](#-accessibility)
+- [Requirements](#-requirements)
+- [License & Support](#-license--support)
+
+---
+
+## ✨ Features
+
+- 🪶 **Zero Dependencies** – No external libraries required
+- 🎯 **Standalone Component** – No NgModule imports needed
+- ⚡ **Angular Signals** – Modern reactive state management
+- 🔄 **Reactive Forms** – Full ControlValueAccessor implementation
+- 🔥 **Multi-Range Support** – Select multiple date ranges (Material CAN'T do this!)
+- 🚫 **Disabled Dates** – Block weekends, holidays, or custom logic
+- 🎨 **Display Format** – Customize date display (DD/MM/YYYY, MM/DD/YYYY, etc.)
+- ✅ **Apply/Confirm Button** – Require confirmation before emitting (perfect for dashboards)
+- � **Theming System** – Built-in themes for Bootstrap, Bulma, Foundation, Tailwind, + Custom
+- �🎨 **Fully Customizable** – Every color, padding, border configurable
+- 📦 **Lightweight** – ~60 KB gzipped total bundle
+- 🚀 **Performance** – OnPush change detection + trackBy optimization
+- ♿ **Accessible** – Full keyboard navigation, ARIA labels, WCAG 2.1 AA compliant
+- 🌍 **i18n Ready** – Customizable month/day names
+- 📱 **Responsive** – Works on desktop and mobile
+- 🔌 **Date Adapters** – Use DayJS, date-fns, Luxon, or custom libraries
+
+---
+
+## 🤔 Why Choose This Library?
+
+| 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 |
+| **Multi-Range Support** | ✅ Yes | ❌ Not available |
+| **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) |
+
+### When to 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
+- Need Angular Signals support now
+- Need multi-range selection
+- 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
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @oneluiz/dual-datepicker
+```
+
+**Requirements:** Angular 17.0.0 or higher
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import { DualDatepickerComponent, DateRange } from '@oneluiz/dual-datepicker';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [DualDatepickerComponent],
+  template: `
+    <ngx-dual-datepicker
+      (dateRangeChange)="onRangeChange($event)">
+    </ngx-dual-datepicker>
+  `
+})
+export class AppComponent {
+  onRangeChange(range: DateRange) {
+    console.log('Start:', range.startDate);
+    console.log('End:', range.endDate);
+  }
+}
+```
+
+### With Reactive Forms
+
+```typescript
+import { FormControl } from '@angular/forms';
+import { DateRange } from '@oneluiz/dual-datepicker';
+
+dateRange = new FormControl<DateRange | null>(null);
+```
+
+```html
+<ngx-dual-datepicker [formControl]="dateRange"></ngx-dual-datepicker>
+```
+
+### With Angular Signals
+
+```typescript
+import { signal } from '@angular/core';
+
+dateRange = signal<DateRange | null>(null);
+```
+
+```html
+<ngx-dual-datepicker
+  [(ngModel)]="dateRange()"
+  (dateRangeChange)="dateRange.set($event)">
+</ngx-dual-datepicker>
+```
+
+---
+
+## 🎯 Advanced Features
+
+### Multi-Range Support
+
+**🔥 Material CAN'T do this!** Select multiple date ranges in a single picker - perfect for booking systems, blackout periods, and complex scheduling.
+
+```typescript
+import { Component } from '@angular/core';
+import { MultiDateRange } from '@oneluiz/dual-datepicker';
+
+@Component({
+  template: `
+    <ngx-dual-datepicker
+      [multiRange]="true"
+      (multiDateRangeChange)="onMultiRangeChange($event)">
+    </ngx-dual-datepicker>
+
+    @if (selectedRanges && selectedRanges.ranges.length > 0) {
+      <div class="selected-ranges">
+        <h3>Selected Ranges ({{ selectedRanges.ranges.length }})</h3>
+        @for (range of selectedRanges.ranges; track $index) {
+          <div class="range-item">
+            {{ range.startDate }} → {{ range.endDate }}
+          </div>
+        }
+      </div>
+    }
+  `
+})
+export class MultiRangeExample {
+  selectedRanges: MultiDateRange | null = null;
+
+  onMultiRangeChange(ranges: MultiDateRange) {
+    this.selectedRanges = ranges;
+    console.log('Selected ranges:', ranges.ranges);
+  }
+}
+```
+
+**Perfect Use Cases:**
+- 🏨 Hotel booking systems
+- 📅 Event blackout periods
+- 🔧 Maintenance windows
+- 📊 Availability calendars
+- 👷 Shift scheduling
+
+### Disabled Dates
+
+**Block specific dates or apply custom logic to disable dates.** Perfect for booking systems, business day selection, and holiday management.
+
+#### Option 1: Disable Specific Dates (Array)
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  template: `
+    <ngx-dual-datepicker
+      [disabledDates]="holidays"
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+  `
+})
+export class DisabledDatesExample {
+  holidays: Date[] = [
+    new Date(2026, 0, 1),   // New Year
+    new Date(2026, 11, 25), // Christmas
+  ];
+
+  onDateRangeChange(range: DateRange) {
+    console.log('Selected range:', range);
+  }
+}
+```
+
+#### Option 2: Disable with Function (Weekends + Holidays)
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  template: `
+    <ngx-dual-datepicker
+      [disabledDates]="isDateDisabled"
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+  `
+})
+export class BusinessDaysExample {
+  holidays: Date[] = [
+    new Date(2026, 0, 1),   // New Year
+    new Date(2026, 11, 25), // Christmas
+  ];
+
+  // Disable weekends and holidays
+  isDateDisabled = (date: Date): boolean => {
+    const day = date.getDay();
+    
+    // Disable weekends (0 = Sunday, 6 = Saturday)
+    if (day === 0 || day === 6) {
+      return true;
+    }
+    
+    // Check if date is a holiday
+    return this.holidays.some(holiday => 
+      holiday.getFullYear() === date.getFullYear() &&
+      holiday.getMonth() === date.getMonth() &&
+      holiday.getDate() === date.getDate()
+    );
+  };
+
+  onDateRangeChange(range: DateRange) {
+    console.log('Selected range:', range);
+  }
+}
+```
+
+**Perfect Use Cases:**
+- 🏢 Business day selection (no weekends)
+- 📅 Booking systems (unavailable dates)
+- 🎉 Holiday management
+- 🚫 Blackout dates for reservations
+- 📆 Appointment scheduling
+
+**Features:**
+- ✅ Two modes: Array or Function
+- ✅ Visual styling (strikethrough, grayed out)
+- ✅ Cannot be selected via mouse or keyboard
+- ✅ Flexible custom logic support
+
+### Display Format
+
+**Customize how dates appear in the input field.** Use flexible format tokens to match regional preferences and localization needs.
+
+#### Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  template: `
+    <!-- Default: "D MMM" (1 Jan, 15 Feb) -->
+    <ngx-dual-datepicker
+      displayFormat="D MMM"
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+
+    <!-- European: "DD/MM/YYYY" (01/01/2026, 15/02/2026) -->
+    <ngx-dual-datepicker
+      displayFormat="DD/MM/YYYY"
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+
+    <!-- US: "MM/DD/YYYY" (01/01/2026, 02/15/2026) -->
+    <ngx-dual-datepicker
+      displayFormat="MM/DD/YYYY"
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+
+    <!-- ISO: "YYYY-MM-DD" (2026-01-01, 2026-02-15) -->
+    <ngx-dual-datepicker
+      displayFormat="YYYY-MM-DD"
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+
+    <!-- Long: "MMM DD, YYYY" (Jan 01, 2026) -->
+    <ngx-dual-datepicker
+      displayFormat="MMM DD, YYYY"
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+  `
+})
+export class DisplayFormatExample {
+  onDateRangeChange(range: DateRange) {
+    console.log('Selected range:', range);
+  }
+}
+```
+
+#### Available Format Tokens
+
+| Token | Output | Description |
+|-------|--------|-------------|
+| `YYYY` | 2026 | Full year (4 digits) |
+| `YY` | 26 | 2-digit year |
+| `MMMM` | January | Full month name |
+| `MMM` | Jan | Short month name (3 letters) |
+| `MM` | 01-12 | 2-digit month (zero-padded) |
+| `M` | 1-12 | Month number (no padding) |
+| `DD` | 01-31 | 2-digit day (zero-padded) |
+| `D` | 1-31 | Day number (no padding) |
+
+#### Custom Format Examples
+
+```typescript
+// Mix and match tokens with any separators
+displayFormat="D/M/YY"          // 1/2/26
+displayFormat="DD-MM-YYYY"      // 01-02-2026
+displayFormat="MMMM D, YYYY"    // January 1, 2026
+displayFormat="D. MMMM YYYY"    // 1. January 2026
+displayFormat="YY.MM.DD"        // 26.01.01
+```
+
+**Perfect Use Cases:**
+- 🌍 Localization (match regional formats)
+- 🇪🇺 European format (DD/MM/YYYY)
+- 🇺🇸 US format (MM/DD/YYYY)
+- 💻 ISO format (YYYY-MM-DD for APIs)
+- 📱 Mobile-friendly short formats
+- 📄 Long formats for reports
+
+**Features:**
+- ✅ Flexible token system
+- ✅ Any separator (/, -, space, comma, dot)
+- ✅ Mix and match freely
+- ✅ Works with locale month names
+- ✅ No external dependencies
+
+### Apply/Confirm Button
+
+**Require explicit confirmation before emitting changes.** Perfect for dashboards and enterprise applications where recalculating data or making API calls is expensive.
+
+#### How It Works
+
+```typescript
+import { Component } from '@angular/core';
+import { DateRange } from '@oneluiz/dual-datepicker';
+
+@Component({
+  template: `
+    <ngx-dual-datepicker
+      [requireApply]="true"
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+
+    @if (selectedRange) {
+      <div class="data-display">
+        <!-- Expensive data loaded only after Apply -->
+        <app-dashboard-data [range]="selectedRange"></app-dashboard-data>
+      </div>
+    }
+  `
+})
+export class DashboardExample {
+  selectedRange: DateRange | null = null;
+
+  onDateRangeChange(range: DateRange) {
+    this.selectedRange = range;
+    // This only fires AFTER user clicks Apply button
+    // Prevents unnecessary API calls during date selection
+    this.loadExpensiveData(range.startDate, range.endDate);
+  }
+
+  loadExpensiveData(start: string, end: string) {
+    // API call, database query, heavy calculation, etc.
+    this.apiService.fetchDashboardData(start, end).subscribe(...);
+  }
+}
+```
+
+#### User Flow
+
+1. **User selects dates** - Clicks start and end dates in calendar
+2. **Pending state** - Selection highlighted as "pending" (not confirmed)
+3. **No events yet** - `dateRangeChange` is NOT emitted
+4. **Apply** - User clicks "Apply" button → dates confirmed, event emitted
+5. **Cancel** - Or clicks "Cancel" button → pending selection discarded
+
+#### Visual Behavior
+
+- Selected dates show in calendar with pending styling
+- Apply button enabled when both dates selected
+- Cancel button enabled when there are pending changes
+- Apply button triggers event emission and closes picker
+- Cancel clears pending selection and keeps current dates
+
+**Perfect Use Cases:**
+- 📊 Dashboards that load data on date change  
+- 📈 Reports with expensive calculations/aggregations
+- 🔍 Analytics with API calls to fetch metrics
+- 💰 Financial systems with complex data processing
+- 📉 BI tools with heavy database queries
+- 🧮 Any scenario where immediate updates are costly
+
+**Key Benefits:**
+- ✅ Prevent unwanted API calls during selection
+- ✅ User control - explicit confirmation required
+- ✅ Professional enterprise UX pattern
+- ✅ Reduces server load and improves performance
+- ✅ Works with all other features (presets, formats, etc.)
+
+**Comparison with Immediate Mode:**
+
+| Behavior | Immediate Mode | Apply Mode |
+|----------|---------------|------------|
+| Event emission | On each date click | Only on Apply click |
+| API calls | Multiple (start + end) | Single (only Apply) |
+| User control | Automatic | Explicit confirmation |
+| Best for | Simple forms | Dashboards, reports |
+
+### Hover Range Preview
+
+**Automatic visual feedback while selecting dates.** Provides instant visual preview of the date range when hovering over dates before clicking to confirm.
+
+#### How It Works
+
+```typescript
+import { Component } from '@angular/core';
+import { DateRange } from '@oneluiz/dual-datepicker';
+
+@Component({
+  template: `
+    <ngx-dual-datepicker
+      (dateRangeChange)="onDateRangeChange($event)">
+    </ngx-dual-datepicker>
+  `
+})
+export class SimpleExample {
+  selectedRange: DateRange | null = null;
+
+  onDateRangeChange(range: DateRange) {
+    this.selectedRange = range;
+    console.log('Range selected:', range);
+  }
+}
+```
+
+#### User Flow
+
+1. **Select start date** - User clicks on any date
+2. **Hover over dates** - Move mouse over other dates
+3. **Visual preview** - See potential range highlighted instantly
+4. **Select end date** - Click to confirm the range
+
+#### Visual Styling
+
+- **Light purple background** (#e0e7ff) for preview range
+- **Purple dashed border** (#6366f1) around preview dates
+- **70% opacity** - subtle, non-intrusive preview
+- **Clear distinction** from confirmed selected range
+
+**Key Benefits:**
+- ✅ Better UX - visual preview before confirming selection
+- ✅ Instant feedback - see range immediately on mouse hover
+- ✅ Intuitive interaction - natural mouse behavior
+- ✅ Zero configuration - automatic, always enabled
+- ✅ Professional feel - premium date picker experience
+
+**Works With All Modes:**
+- ✅ Single range mode
+- ✅ Multi-range mode  
+- ✅ requireApply mode
+- ✅ All presets, formats, and disabled dates
+
+**No Configuration Needed:**  
+Hover preview is automatically enabled and works seamlessly with all other features. Just use the datepicker normally!
+
+### Custom Presets
+
+**Power feature for dashboards, reporting, ERP, and BI systems!**
+
+#### Using Pre-built Presets
+
+```typescript
+import { CommonPresets } from '@oneluiz/dual-datepicker';
+
+// Dashboard presets
+presets = CommonPresets.dashboard;
+// → Last 7, 15, 30, 60, 90 days + last 6 months
+
+// Reporting presets
+presets = CommonPresets.reporting;
+// → Today, This week, Last week, This month, Last month, This quarter
+
+// Financial/ERP presets
+presets = CommonPresets.financial;
+// → Month to date, Quarter to date, Year to date
+
+// Analytics presets
+presets = CommonPresets.analytics;
+// → Last 7/14/30/60/90/180/365 days
+```
+
+#### Creating Custom Presets
+
+```typescript
+import { PresetConfig, getToday, getThisMonth, getLastMonth } from '@oneluiz/dual-datepicker';
+
+customPresets: PresetConfig[] = [
+  { label: 'Today', getValue: getToday },
+  { label: 'This Month', getValue: getThisMonth },
+  { label: 'Last Month', getValue: getLastMonth },
+  { 
+    label: 'Custom Logic', 
+    getValue: () => {
+      // Your custom date calculation
+      const today = new Date();
+      const start = new Date(today.getFullYear(), today.getMonth(), 1);
+      return {
+        start: formatDate(start),
+        end: formatDate(today)
+      };
+    }
+  }
+];
+```
+
+```html
+<ngx-dual-datepicker [presets]="customPresets"></ngx-dual-datepicker>
+```
+
+**Why This Is Powerful:**
+- ✅ Perfect for dashboards: "Last 7 days", "Month to date"
+- ✅ Perfect for reporting: "This quarter", "Last quarter"
+- ✅ Perfect for financial systems: "Quarter to date", "Year to date"
+- ✅ Perfect for analytics: Consistent date ranges for BI tools
+
+### Date Adapter System
+
+Use custom date libraries (DayJS, date-fns, Luxon) instead of native JavaScript `Date` objects.
+
+#### Example: date-fns Adapter
+
+```typescript
+import { Injectable } from '@angular/core';
+import { DateAdapter } from '@oneluiz/dual-datepicker';
+import { parse, format, addDays, isValid } from 'date-fns';
+
+@Injectable()
+export class DateFnsAdapter extends DateAdapter<Date> {
+  parse(value: any): Date | null {
+    if (!value) return null;
+    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);
+  }
+
+  // ... implement other required methods
+}
+```
+
+#### Providing the Adapter
+
+```typescript
+import { DATE_ADAPTER } from '@oneluiz/dual-datepicker';
+
+@Component({
+  providers: [
+    { provide: DATE_ADAPTER, useClass: DateFnsAdapter }
+  ]
+})
+export class AppComponent {}
+```
+
+**Benefits:**
+- ✅ Zero vendor lock-in
+- ✅ Use same date library across your app
+- ✅ Adapt to custom backend formats
+- ✅ Full TypeScript support
+
+### Keyboard Navigation
+
+**Full keyboard control** for accessibility (WCAG 2.1 AA compliant):
+
+| Key(s) | Action |
+|--------|--------|
+| `←` / `→` | Navigate between days |
+| `↑` / `↓` | Navigate by weeks |
+| `Enter` / `Space` | Select focused day |
+| `Escape` | Close datepicker |
+| `Home` / `End` | Jump to first/last day |
+| `PageUp` / `PageDown` | Navigate months |
+| `Shift + PageUp/Down` | Navigate years |
+| `Tab` | Navigate between input, presets, and calendar |
+
+```html
+<!-- Enabled by default -->
+<ngx-dual-datepicker></ngx-dual-datepicker>
+
+<!-- Disable if needed -->
+<ngx-dual-datepicker [enableKeyboardNavigation]="false"></ngx-dual-datepicker>
+```
+
+---
+
+## 🎨 Customization
+
+### Theming System
+
+The datepicker now supports 6 built-in themes: `default`, `bootstrap`, `bulma`, `foundation`, `tailwind`, and `custom`.
+
+```typescript
+<ngx-dual-datepicker theme="bootstrap"></ngx-dual-datepicker>
+```
+
+```scss
+// In your styles.scss
+@import '@oneluiz/dual-datepicker/themes/bootstrap';
+```
+
+**Available Themes:**
+- `default` - Original styling (no import needed)
+- `bootstrap` - Bootstrap 5 compatible styling
+- `bulma` - Bulma CSS compatible styling
+- `foundation` - Foundation CSS compatible styling
+- `tailwind` - Tailwind CSS compatible styling
+- `custom` - CSS variables-based customization
+
+**📚 For detailed theming documentation, see [THEMING.md](./THEMING.md)**
+
+### Styling Options
+
+```html
+<ngx-dual-datepicker
+  inputBackgroundColor="#ffffff"
+  inputTextColor="#495057"
+  inputBorderColor="#ced4da"
+  inputBorderColorHover="#80bdff"
+  inputBorderColorFocus="#0d6efd"
+  inputPadding="0.375rem 0.75rem">
+</ngx-dual-datepicker>
+```
+
+#### Pre-styled Examples
+
+**Bootstrap Style:**
+```html
+<ngx-dual-datepicker
+  inputBackgroundColor="#ffffff"
+  inputBorderColor="#ced4da"
+  inputBorderColorFocus="#80bdff">
+</ngx-dual-datepicker>
+```
+
+**GitHub Style:**
+```html
+<ngx-dual-datepicker
+  inputBackgroundColor="#f3f4f6"
+  inputBorderColor="transparent"
+  inputBorderColorHover="#d1d5db">
+</ngx-dual-datepicker>
+```
+
+### Localization (i18n)
+
+```typescript
+import { LocaleConfig } from '@oneluiz/dual-datepicker';
+
+spanishLocale: LocaleConfig = {
+  monthNames: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio',
+               'Julio', 'Agosto', 'Septiembre', 'Octubre', 'Noviembre', 'Diciembre'],
+  monthNamesShort: ['Ene', 'Feb', 'Mar', 'Abr', 'May', 'Jun',
+                    'Jul', 'Ago', 'Sep', 'Oct', 'Nov', 'Dic'],
+  dayNames: ['Domingo', 'Lunes', 'Martes', 'Miércoles', 'Jueves', 'Viernes', 'Sábado'],
+  dayNamesShort: ['Dom', 'Lun', 'Mar', 'Mié', 'Jue', 'Vie', 'Sáb']
+};
+```
+
+```html
+<ngx-dual-datepicker [locale]="spanishLocale"></ngx-dual-datepicker>
+```
+
+---
+
+## 📖 API Reference
+
+### Inputs
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `ngModel` | `DateRange \| null` | `null` | Two-way binding for selected date range |
+| `placeholder` | `string` | `'Select date range'` | Input placeholder text |
+| `presets` | `PresetConfig[]` | `[]` | Array of preset configurations |
+| `showPresets` | `boolean` | `true` | Show/hide the presets sidebar |
+| `showClearButton` | `boolean` | `false` | Show/hide the Clear button |
+| `closeOnSelection` | `boolean` | `false` | Close picker when both dates selected |
+| `closeOnPresetSelection` | `boolean` | `false` | Close picker when preset clicked |
+| `closeOnClickOutside` | `boolean` | `true` | Close picker when clicking outside |
+| `multiRange` | `boolean` | `false` | Enable multi-range selection mode |
+| `disabledDates` | `Date[] \| ((date: Date) => boolean)` | `undefined` | Array of dates or function to disable specific dates |
+| `displayFormat` | `string` | `'D MMM'` | Format for displaying dates in input (tokens: YYYY, YY, MMMM, MMM, MM, M, DD, D) |
+| `requireApply` | `boolean` | `false` | Require Apply button confirmation before emitting changes |
+| `enableKeyboardNavigation` | `boolean` | `true` | Enable keyboard navigation |
+| `inputBackgroundColor` | `string` | `'#fff'` | Input background color |
+| `inputTextColor` | `string` | `'#495057'` | Input text color |
+| `inputBorderColor` | `string` | `'#ced4da'` | Input border color |
+| `inputBorderColorHover` | `string` | `'#9ca3af'` | Input border color on hover |
+| `inputBorderColorFocus` | `string` | `'#80bdff'` | Input border color on focus |
+| `inputPadding` | `string` | `'0.375rem 0.75rem'` | Input padding |
+| `locale` | `LocaleConfig` | English defaults | Custom month/day names for i18n |
+
+### Outputs
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `dateRangeChange` | `EventEmitter<DateRange>` | Emitted when date range changes |
+| `dateRangeSelected` | `EventEmitter<DateRange>` | Emitted when both dates are selected |
+| `multiDateRangeChange` | `EventEmitter<MultiDateRange>` | Emitted in multi-range mode |
+| `multiDateRangeSelected` | `EventEmitter<MultiDateRange>` | Emitted when multi-range selection is complete |
+
+### Public Methods
+
+```typescript
+import { Component, ViewChild } from '@angular/core';
+import { DualDatepickerComponent } from '@oneluiz/dual-datepicker';
+
+@Component({
+  template: `
+    <ngx-dual-datepicker #datepicker></ngx-dual-datepicker>
+    <button (click)="clearSelection()">Clear</button>
+  `
+})
+export class MyComponent {
+  @ViewChild('datepicker') datepicker!: DualDatepickerComponent;
+
+  clearSelection() {
+    this.datepicker.clear();
+  }
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `clear()` | Clears current selection and resets component |
+
+### Types
+
+```typescript
+interface DateRange {
+  startDate: string;   // ISO format: 'YYYY-MM-DD'
+  endDate: string;     // ISO format: 'YYYY-MM-DD'
+  rangeText: string;   // Display text: 'DD Mon - DD Mon'
+}
+
+interface MultiDateRange {
+  ranges: DateRange[];  // Array of selected date ranges
+}
+
+interface PresetRange {
+  start: string;  // ISO format: 'YYYY-MM-DD'
+  end: string;    // ISO format: 'YYYY-MM-DD'
+}
+
+interface PresetConfig {
+  label: string;
+  getValue: () => PresetRange;
+}
+
+interface LocaleConfig {
+  monthNames?: string[];         // Full month names (12 items)
+  monthNamesShort?: string[];    // Short month names (12 items)
+  dayNames?: string[];           // Full day names (7 items, starting Sunday)
+  dayNamesShort?: string[];      // Short day names (7 items, starting Sunday)
+}
+```
+
+---
+
+## 💡 Usage Examples
+
+### With Events
+
+```typescript
+@Component({
+  template: `
+    <ngx-dual-datepicker
+      (dateRangeSelected)="onDateRangeSelected($event)">
+    </ngx-dual-datepicker>
+    
+    @if (selectedRange) {
+      <div>Selected: {{ selectedRange.rangeText }}</div>
+    }
+  `
+})
+export class ExampleComponent {
+  selectedRange: DateRange | null = null;
+
+  onDateRangeSelected(range: DateRange) {
+    this.selectedRange = range;
+    // Both dates selected - fetch data
+    this.fetchData(range.startDate, range.endDate);
+  }
+
+  fetchData(start: string, end: string) {
+    // Dates are in 'YYYY-MM-DD' format
+  }
+}
+```
+
+### With Angular Signals
+
+```typescript
+import { Component, signal, computed } from '@angular/core';
+
+@Component({
+  template: `
+    <ngx-dual-datepicker
+      (dateRangeChange)="onDateChange($event)">
+    </ngx-dual-datepicker>
+    
+    @if (isRangeSelected()) {
+      <div>
+        <p>{{ rangeText() }}</p>
+        <p>Days: {{ daysDifference() }}</p>
+      </div>
+    }
+  `
+})
+export class SignalsExample {
+  startDate = signal('');
+  endDate = signal('');
+  
+  isRangeSelected = computed(() => 
+    this.startDate() !== '' && this.endDate() !== ''
+  );
+  
+  rangeText = computed(() => 
+    `${this.startDate()} to ${this.endDate()}`
+  );
+  
+  daysDifference = computed(() => {
+    if (!this.isRangeSelected()) return 0;
+    const start = new Date(this.startDate());
+    const end = new Date(this.endDate());
+    return Math.ceil((end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24));
+  });
+
+  onDateChange(range: DateRange) {
+    this.startDate.set(range.startDate);
+    this.endDate.set(range.endDate);
+  }
+}
+```
+
+### With Complete Customization
+
+```html
+<ngx-dual-datepicker
+  placeholder="Pick your dates"
+  [presets]="customPresets"
+  [showClearButton]="true"
+  [closeOnSelection]="true"
+  [locale]="spanishLocale"
+  inputBackgroundColor="#fef3c7"
+  inputTextColor="#92400e"
+  inputBorderColor="#fbbf24"
+  inputBorderColorFocus="#d97706"
+  inputPadding="12px 16px"
+  (dateRangeSelected)="onDateRangeSelected($event)">
+</ngx-dual-datepicker>
+```
+
+---
+
+## ♿ Accessibility
+
+**WCAG 2.1 Level AA Compliant**
+
+- ✅ Full keyboard navigation
+- ✅ Screen reader support with ARIA labels
+- ✅ Semantic HTML with proper `role` attributes
+- ✅ Focus management with visual indicators
+- ✅ High contrast support
+
+---
+
+## 🛠️ Requirements
+
+- **Angular:** 17.0.0 or higher
+- **TypeScript:** 5.0+ (recommended)
+
+---
+
+## 📄 License & Support
+
+**License:** MIT © Luis Cortes
+
+**Issues:** [Report bugs](https://github.com/oneluiz/ng-dual-datepicker/issues)
+
+**Star this project:** If you find it useful, please ⭐ the [GitHub repository](https://github.com/oneluiz/ng-dual-datepicker)!
+
+---
+
+Made with ❤️ by [Luis Cortes](https://github.com/oneluiz)
+**
+
 ## Why ng-dual-datepicker?
 
 | Feature | ng-dual-datepicker | Angular Material DateRangePicker |