ngx-datex 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Senguana Wisuma Emilio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# NgxDatex - Advanced Angular Date Range Picker
+
+[![npm version](https://badge.fury.io/js/ngx-datex.svg)](https://badge.fury.io/js/ngx-datex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A feature-rich, accessible date picker component for Angular applications. Built with modern Angular patterns including signals, standalone components, and CDK overlays.
+
+## ✨ Features
+
+- 📅 **Single Date & Date Range Selection** - Support for both single dates and date ranges
+- ⏰ **Time Picker Integration** - Optional time selection with 12/24 hour formats
+- 🎨 **Customizable Themes** - Built-in themes with full customization support
+- 🌍 **Internationalization** - Complete i18n support with multiple locales
+- � **Mobile Responsive** - Optimized for mobile devices with touch support
+- ♿ **Accessibility** - WCAG compliant with full keyboard navigation
+- 🔧 **Extensive Configuration** - Highly configurable with sensible defaults
+- � **Forms Integration** - Full Angular Forms support with ControlValueAccessor
+- 🚀 **Performance Optimized** - Built with Angular signals for optimal performance
+- 🎯 **TypeScript First** - Written in TypeScript with comprehensive type definitions
+
+## 🚀 Installation
+
+```bash
+npm install ngx-datex
+```
+
+## � Quick Start
+
+### 1. Import the Component
+
+```typescript
+import { NgxDatex } from 'ngx-datex';
+
+@Component({
+  selector: 'app-example',
+  imports: [NgxDatex], // For standalone components
+  template: ` <ngx-datex [(ngModel)]="selectedRange" [ranges]="predefinedRanges"> </ngx-datex> `,
+})
+export class ExampleComponent {
+  selectedRange: NgxDatexValue | null = null;
+
+  predefinedRanges = {
+    Today: [startOfDay(new Date()), endOfDay(new Date())],
+    'Last 7 Days': [startOfDay(subDays(new Date(), 6)), endOfDay(new Date())],
+    'Last 30 Days': [startOfDay(subDays(new Date(), 29)), endOfDay(new Date())],
+  };
+}
+```
+
+### 2. Basic Usage
+
+```html
+<!-- Simple date range picker -->
+<ngx-datex [(ngModel)]="dateRange" placeholder="Select date range"> </ngx-datex>
+
+<!-- Single date picker -->
+<ngx-datex [(ngModel)]="singleDate" [singleDatePicker]="true" placeholder="Select date">
+</ngx-datex>
+```
+
+## 🎛️ Configuration Options
+
+### Input Properties
+
+| Property           | Type                           | Default                | Description                                 |
+| ------------------ | ------------------------------ | ---------------------- | ------------------------------------------- |
+| `singleDatePicker` | `boolean`                      | `false`                | Enable single date selection mode           |
+| `timePicker`       | `boolean`                      | `false`                | Enable time selection                       |
+| `timePicker24Hour` | `boolean`                      | `true`                 | Use 24-hour format for time picker          |
+| `autoApply`        | `boolean`                      | `false`                | Auto-apply selection without confirm button |
+| `showDropdowns`    | `boolean`                      | `false`                | Show month/year dropdowns in header         |
+| `linkedCalendars`  | `boolean`                      | `true`                 | Link left and right calendar navigation     |
+| `ranges`           | `Record<string, [Date, Date]>` | `DEFAULT_RANGES`       | Predefined date ranges                      |
+| `minDate`          | `Date \| null`                 | `null`                 | Minimum selectable date                     |
+| `maxDate`          | `Date \| null`                 | `null`                 | Maximum selectable date                     |
+| `locale`           | `NgxDatexLocale`               | `SPANISH_LOCALE`       | Localization settings                       |
+| `theme`            | `NgxDatexTheme`                | `MATERIAL_LIGHT_THEME` | Theme configuration                         |
+
+### Output Events
+
+| Event         | Type                                       | Description                         |
+| ------------- | ------------------------------------------ | ----------------------------------- |
+| `dateChange`  | `NgxDatexValue \| null`                    | Emitted when date selection changes |
+| `rangeChange` | `{startDate: Date, endDate: Date \| null}` | Emitted when range changes          |
+| `openEvent`   | `void`                                     | Emitted when picker opens           |
+| `closeEvent`  | `void`                                     | Emitted when picker closes          |
+
+## 🎨 Theming
+
+### Using Built-in Themes
+
+```typescript
+import { MATERIAL_LIGHT_THEME } from 'ngx-datex';
+
+@Component({
+  template: ` <ngx-datex [theme]="materialTheme"></ngx-datex> `,
+})
+export class ThemedComponent {
+  materialTheme = MATERIAL_LIGHT_THEME;
+}
+```
+
+### Creating Custom Themes
+
+```typescript
+import { NgxDatexTheme } from 'ngx-datex';
+
+const customTheme: NgxDatexTheme = {
+  name: 'custom-dark',
+  colors: {
+    primary: '#bb86fc',
+    secondary: '#03dac6',
+    background: '#121212',
+    surface: '#1e1e1e',
+    text: '#ffffff',
+    // ... other colors
+  },
+  typography: {
+    fontFamily: 'Roboto, sans-serif',
+    fontSize: '14px',
+    fontWeight: '400',
+    lineHeight: '1.5',
+  },
+  // ... other theme properties
+};
+```
+
+## 🌍 Internationalization
+
+### Using Built-in Locales
+
+```typescript
+import { SPANISH_LOCALE } from 'ngx-datex';
+
+@Component({
+  template: ` <ngx-datex [locale]="spanishLocale"></ngx-datex> `,
+})
+export class LocalizedComponent {
+  spanishLocale = SPANISH_LOCALE;
+}
+```
+
+### Creating Custom Locales
+
+```typescript
+import { NgxDatexLocale } from 'ngx-datex';
+
+const frenchLocale: NgxDatexLocale = {
+  direction: 'ltr',
+  format: 'DD/MM/YYYY',
+  separator: ' - ',
+  applyLabel: 'Appliquer',
+  cancelLabel: 'Annuler',
+  daysOfWeek: ['Lu', 'Ma', 'Me', 'Je', 'Ve', 'Sa', 'Di'],
+  monthNames: [
+    'Janvier',
+    'Février',
+    'Mars',
+    'Avril',
+    'Mai',
+    'Juin',
+    'Juillet',
+    'Août',
+    'Septembre',
+    'Octobre',
+    'Novembre',
+    'Décembre',
+  ],
+  firstDay: 1,
+};
+```
+
+## 📱 Mobile Support
+
+The component automatically adapts to mobile devices with:
+
+- Touch-friendly interface
+- Optimized layout for small screens
+- Native-like date selection experience
+- Responsive design patterns
+
+## ♿ Accessibility
+
+NgxDatex is built with accessibility in mind:
+
+- Full keyboard navigation support
+- ARIA labels and descriptions
+- Screen reader compatibility
+- High contrast support
+- Focus management
+
+## 🔧 Advanced Usage
+
+### With Reactive Forms
+
+```typescript
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+
+@Component({
+  imports: [ReactiveFormsModule, NgxDatex],
+  template: `
+    <form [formGroup]="form">
+      <ngx-datex formControlName="dateRange"></ngx-datex>
+    </form>
+  `,
+})
+export class ReactiveFormComponent {
+  form = this.fb.group({
+    dateRange: new FormControl<NgxDatexValue | null>(null),
+  });
+}
+```
+
+### Custom Date Validation
+
+```typescript
+@Component({
+  template: `
+    <ngx-datex [isInvalidDate]="isWeekend" [minDate]="minDate" [maxDate]="maxDate"> </ngx-datex>
+  `,
+})
+export class ValidatedComponent {
+  minDate = new Date();
+  maxDate = addMonths(new Date(), 6);
+
+  isWeekend = (date: Date): boolean => {
+    const day = date.getDay();
+    return day === 0 || day === 6; // Disable weekends
+  };
+}
+```
+
+### Time Picker Configuration
+
+```typescript
+@Component({
+  template: `
+    <ngx-datex
+      [timePicker]="true"
+      [timePicker24Hour]="false"
+      [timePickerIncrement]="15"
+      [timePickerSeconds]="false"
+    >
+    </ngx-datex>
+  `,
+})
+export class TimePickerComponent {}
+```
+
+## 📚 API Reference
+
+### Types
+
+#### `NgxDatexValue`
+
+```typescript
+interface NgxDatexValue {
+  startDate: Date;
+  endDate: Date | null;
+  label?: string;
+}
+```
+
+#### `NgxDatexLocale`
+
+```typescript
+interface NgxDatexLocale {
+  direction?: 'ltr' | 'rtl';
+  format?: string;
+  separator?: string;
+  applyLabel?: string;
+  cancelLabel?: string;
+  daysOfWeek?: string[];
+  monthNames?: string[];
+  firstDay?: number;
+}
+```
+
+#### `NgxDatexTheme`
+
+```typescript
+interface NgxDatexTheme {
+  name: string;
+  colors: {
+    /* color definitions */
+  };
+  typography: {
+    /* typography settings */
+  };
+  spacing: {
+    /* spacing scale */
+  };
+  borderRadius: {
+    /* border radius values */
+  };
+  shadows: {
+    /* shadow definitions */
+  };
+}
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Inspired by the popular [daterangepicker](https://github.com/dangrossman/daterangepicker) library
+- Built with [Angular CDK](https://material.angular.io/cdk) for overlay management
+- Uses [@formkit/tempo](https://github.com/formkit/tempo) for reliable date operations
+
+## 📞 Support
+
+- 📖 [Documentation](https://ngx-datex.dev)
+- 🐛 [Issue Tracker](https://github.com/senguanasoft/ngx-datex/issues)
+- 💬 [Discussions](https://github.com/senguanasoft/ngx-datex/discussions)