ethio-calendar-converter-angular/README.md

Ethiopian Calendar Converter for Angular applications

# Ethio Calendar Converter

A modern Angular package for converting between Ethiopian and Gregorian calendars with a built-in UI component.

## Features
- 🔄 Two-way conversion between Ethiopian and Gregorian calendars
- 📅 Handles Ethiopian calendar's unique 13-month system
- ✨ Modern UI with Tailwind CSS
- 🎯 Built specifically for Angular 17+
- 📱 Responsive design
- 🔍 Built-in validation
- 📦 Easy to install and use

## Installation

1. Install the package and its peer dependencies:

npm install ethio-calendar-converter 

2. Add Tailwind CSS to your project:
```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init
```

3. Configure Tailwind CSS (`tailwind.config.js`):
```javascript
module.exports = {
  content: [
    "./src/**/*.{html,ts}",
    "./node_modules/ethio-calendar-converter/**/*.{html,ts}"
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

## Usage Examples

### 1. Basic Component Usage

```typescript
// app.component.ts
import { Component } from '@angular/core';
import { EthiopianCalendarModule } from 'ethio-calendar-converter';
import { EthiopianDate, GregorianDate } from 'ethio-calendar-converter';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [EthiopianCalendarModule],
  template: `
    <ethiopian-calendar
      (ethiopianDateChange)="onEthiopianDateChange($event)"
      (gregorianDateChange)="onGregorianDateChange($event)">
    </ethiopian-calendar>
  `
})
export class AppComponent {
  onEthiopianDateChange(date: EthiopianDate) {
    console.log('Ethiopian Date:', date);
  }

  onGregorianDateChange(date: GregorianDate) {
    console.log('Gregorian Date:', date);
  }
}
```

### 2. Advanced Component Usage with Custom Styling

```typescript
// calendar-page.component.ts
import { Component } from '@angular/core';
import { EthiopianCalendarModule } from 'ethio-calendar-converter';
import { EthiopianDate, GregorianDate } from 'ethio-calendar-converter';

@Component({
  selector: 'app-calendar-page',
  standalone: true,
  imports: [EthiopianCalendarModule],
  template: `
    <div class="max-w-4xl mx-auto p-6">
      <h1 class="text-3xl font-bold mb-8">Calendar Converter</h1>
      
      <div class="bg-white shadow-lg rounded-lg p-6">
        <ethiopian-calendar
          (ethiopianDateChange)="onEthiopianDateChange($event)"
          (gregorianDateChange)="onGregorianDateChange($event)">
        </ethiopian-calendar>

        <!-- Conversion History -->
        <div class="mt-8">
          <h2 class="text-xl font-semibold mb-4">Conversion History</h2>
          <div class="space-y-2">
            <div *ngFor="let conversion of conversionHistory" 
                 class="p-3 bg-gray-50 rounded">
              {{ conversion }}
            </div>
          </div>
        </div>
      </div>
    </div>
  `
})
export class CalendarPageComponent {
  conversionHistory: string[] = [];

  onEthiopianDateChange(date: EthiopianDate) {
    this.conversionHistory.unshift(
      `Ethiopian: ${date.year}-${date.month}-${date.day}`
    );
  }

  onGregorianDateChange(date: GregorianDate) {
    this.conversionHistory.unshift(
      `Gregorian: ${date.year}-${date.month}-${date.day}`
    );
  }
}
```

### 3. Using the Service Directly

```typescript
// date-converter.service.ts
import { Injectable } from '@angular/core';
import { EthiopianCalendarService } from 'ethio-calendar-converter';

@Injectable({
  providedIn: 'root'
})
export class DateConverterService {
  constructor(private ethiopianCalendar: EthiopianCalendarService) {}

  convertToGregorian(year: number, month: number, day: number) {
    const ethiopianDate = { year, month, day };
    try {
      const gregorianDate = this.ethiopianCalendar.toGregorian(ethiopianDate);
      return this.ethiopianCalendar.formatDate(gregorianDate, false);
    } catch (error) {
      console.error('Conversion error:', error);
      return null;
    }
  }

  convertToEthiopian(year: number, month: number, day: number) {
    const gregorianDate = { year, month, day };
    try {
      const ethiopianDate = this.ethiopianCalendar.toEthiopian(gregorianDate);
      return this.ethiopianCalendar.formatDate(ethiopianDate);
    } catch (error) {
      console.error('Conversion error:', error);
      return null;
    }
  }
}
```

### 4. Form Integration Example

```typescript
// date-form.component.ts
import { Component } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';
import { EthiopianCalendarService } from 'ethio-calendar-converter';

@Component({
  selector: 'app-date-form',
  template: `
    <form [formGroup]="dateForm" (ngSubmit)="onSubmit()" class="space-y-4">
      <div class="grid grid-cols-3 gap-4">
        <input type="number" formControlName="year" placeholder="Year"
               class="p-2 border rounded">
        <input type="number" formControlName="month" placeholder="Month"
               class="p-2 border rounded">
        <input type="number" formControlName="day" placeholder="Day"
               class="p-2 border rounded">
      </div>
      
      <button type="submit" 
              class="px-4 py-2 bg-blue-500 text-white rounded">
        Convert
      </button>

      <div *ngIf="result" class="mt-4 p-4 bg-gray-100 rounded">
        {{ result }}
      </div>
    </form>
  `
})
export class DateFormComponent {
  dateForm: FormGroup;
  result: string = '';

  constructor(
    private fb: FormBuilder,
    private ethiopianCalendar: EthiopianCalendarService
  ) {
    this.dateForm = this.fb.group({
      year: ['', [Validators.required, Validators.min(1)]],
      month: ['', [Validators.required, Validators.min(1), Validators.max(13)]],
      day: ['', [Validators.required, Validators.min(1), Validators.max(31)]]
    });
  }

  onSubmit() {
    if (this.dateForm.valid) {
      const { year, month, day } = this.dateForm.value;
      const ethiopianDate = { year, month, day };
      
      try {
        const gregorianDate = this.ethiopianCalendar.toGregorian(ethiopianDate);
        this.result = `Converted to: ${gregorianDate.year}-${gregorianDate.month}-${gregorianDate.day}`;
      } catch (error) {
        this.result = 'Invalid date';
      }
    }
  }
}
```

## API Reference

### Interfaces

```typescript
interface EthiopianDate {
  year: number;  // Ethiopian year
  month: number; // 1-13 (Pagume is 13th month)
  day: number;   // 1-30 (1-5/6 for Pagume)
}

interface GregorianDate {
  year: number;  // Gregorian year
  month: number; // 1-12
  day: number;   // 1-31
}
```

### Service Methods

```typescript
class EthiopianCalendarService {
  toGregorian(ethiopianDate: EthiopianDate): GregorianDate
  toEthiopian(gregorianDate: GregorianDate): EthiopianDate
  formatDate(date: EthiopianDate | GregorianDate, isEthiopian?: boolean): string
}
```

## Common Conversion Examples

```typescript
// Ethiopian to Gregorian
2015-04-25 (Ethiopian) → 2022-03-25 (Gregorian)
2016-01-01 (Ethiopian) → 2023-09-11 (Gregorian)
2015-13-05 (Ethiopian) → 2023-09-10 (Gregorian)

// Gregorian to Ethiopian
2022-03-25 (Gregorian) → 2015-04-25 (Ethiopian)
2023-09-11 (Gregorian) → 2016-01-01 (Ethiopian)
2023-09-10 (Gregorian) → 2015-13-05 (Ethiopian)
```

## Error Handling

The service throws errors for invalid dates:
- Invalid month numbers (Ethiopian: 1-13, Gregorian: 1-12)
- Invalid day numbers
- Invalid Pagume days (5 or 6 depending on leap year)

## License

MIT

## Author

Alex Weldu