@datacomvn/lunar-date-picker/android/README.md

A powerful React Native lunar date picker with timezone support, lazy loading, and native performance built on Nitro Modules

# Android Implementation - Lunar Date Picker

This directory contains the Android implementation of the React Native Lunar Date Picker using Nitro Modules.

## Architecture

The Android implementation follows a similar architecture to the iOS version:

### Core Classes

#### `LunarDatePicker.kt`
Main entry point implementing `HybridLunarDatePickerSpec`. Handles validation and coordinates with the coordinator.

#### `LunarDatePickerCoordinator.kt`  
Manages the presentation flow and coordinates between different components.

#### `ConfigurationBuilder.kt`
Builds picker configurations from parameters and global settings.

#### `PickerPresenter.kt`
Handles the actual presentation of the date picker UI.

#### `DateConverter.kt`
Converts between JavaScript timestamps and Java Date objects.

### UI Components

#### `LunarDatePickerFragment.kt`
Main UI component - a DialogFragment that displays the date picker.

#### `CalendarAdapter.kt`
RecyclerView adapter for displaying the calendar grid with date cells.

### Supporting Classes

#### `PickerConfig.kt`
Data classes for holding configuration (colors, fonts, behavior).

#### `ColorUtils.kt`
Utility functions for color operations and hex conversion.

#### `LunarDatePickerException.kt`
Exception classes for error handling.

## Features

### Single Date Selection
- Tap to select a single date
- Visual feedback with selection highlighting

### Range Date Selection  
- Tap to select start date, tap again for end date
- Range highlighting between selected dates
- Smart ordering (earlier date becomes start automatically)

### Customizable Theming
- All colors configurable via hex values
- Support for day labels, lunar dates, weekends, etc.
- Background colors and selection states

### Localization Support
- Custom month names
- Custom weekday names
- Timezone configuration

### Date Constraints
- Minimum and maximum date boundaries
- Disabled state for invalid dates

### Lunar Date Display
- Placeholder implementation for lunar dates
- Extensible for real lunar calendar integration

## Integration Notes

### Dependencies Added
- `androidx.recyclerview:recyclerview` - For calendar grid
- `androidx.fragment:fragment-ktx` - For DialogFragment
- `kotlinx-coroutines-android` - For async operations

### Generated Files
The implementation uses generated Nitro Module files:
- `HybridLunarDatePickerSpec.kt` - Main interface
- `PresentParams.kt`, `ConfigParams.kt` - Parameter data classes
- `Range.kt`, `CustomStyle.kt`, etc. - Supporting data structures

### React Native Bridge
The coordinator attempts to get the current activity from React Native context for presentation.

## Usage

The Android implementation is automatically used when the JavaScript code calls:

```javascript
import { configure, pickDate } from 'react-native-lunar-date-picker';

// Configure globally
configure({
  themes: { ... },
  languages: { ... },
  yearRangeOffset: 100,
  timeZoneOffset: 7
});

// Present picker
pickDate({
  theme: 'default',
  language: 'en',
  title: 'Select Date',
  textCancel: 'Cancel',
  mode: 'single', // or 'range'
  onDone: (result) => {
    console.log('Selected:', result);
  }
});
```

## Lunar Date Integration

The current implementation includes a placeholder for lunar date conversion. To integrate real lunar calendar functionality:

1. Add a lunar calendar library dependency
2. Replace `generateLunarDate()` in `CalendarAdapter.kt`
3. Implement proper Gregorian to Lunar conversion
4. Add locale-specific lunar date formatting

## Future Enhancements

- Real lunar calendar integration
- Better lunar date display formatting
- Custom date validation rules
- Animation improvements
- Performance optimizations for large date ranges
- Accessibility improvements