# @samirkoirala/bs-calendar-react

A comprehensive React and React Native library for **Bikram Sambat (Nepali calendar)** with built-in holidays support. Fully cross-platform compatible.

[![npm version](https://badge.fury.io/js/@samirkoirala%2Fbs-calendar-react.svg)](https://badge.fury.io/js/@samirkoirala%2Fbs-calendar-react)
[![React Native](https://img.shields.io/badge/React%20Native-Compatible-brightgreen.svg)](https://reactnative.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

## ✨ Features

- 🗓️ **Accurate BS to AD conversion** and vice versa
- 🎉 **Built-in Nepali holidays** with complete data
- 📅 **Calendar grid generation** with month navigation
- 🕐 **Cross-platform timezone handling** (Asia/Kathmandu)
- ⚛️ **React hook** for seamless integration
- 📱 **Full React Native support** (iOS, Android, Web, Windows, macOS)
- 📱 **TypeScript support** with complete type definitions
- 🚀 **Lightweight and performant**

## 🌏 Platform Support

✅ **React**: Web applications  
✅ **React Native**: iOS, Android, Web, Windows, macOS  
✅ **Cross-platform**: Works seamlessly everywhere  
✅ **TypeScript**: Full type definitions included  

## 📦 Installation

```bash
npm install @samirkoirala/bs-calendar-react
# or
yarn add @samirkoirala/bs-calendar-react
```

## 🚀 Quick Start

### React/Web Usage

```typescript
import React from 'react';
import { useCalendar } from '@samirkoirala/bs-calendar-react';

function CalendarComponent() {
  const { 
    today, 
    monthsWithHolidays, 
    currentBikYear, 
    currentBikMonth 
  } = useCalendar({});

  return (
    <div>
      <h2>Today: {today.date}</h2>
      <h3>BS Date: {currentBikYear}-{currentBikMonth}</h3>
      
      {monthsWithHolidays.map((day, index) => (
        <div key={index} className={day.holiday?.length ? 'holiday' : ''}>
          <span>Day {day.day}</span>
          {day.holiday?.map(h => <span key={h}>{h}</span>)}
        </div>
      ))}
    </div>
  );
}
```

### React Native Usage

```typescript
import React from 'react';
import { View, Text, ScrollView } from 'react-native';
import { useCalendar } from '@samirkoirala/bs-calendar-react';

export default function CalendarScreen() {
  const { today, monthsWithHolidays } = useCalendar({});

  return (
    <ScrollView style={{ flex: 1, padding: 16 }}>
      <Text style={{ fontSize: 24, fontWeight: 'bold' }}>
        Nepali Calendar
      </Text>
      <Text style={{ fontSize: 18 }}>Today: {today.date}</Text>

      {monthsWithHolidays.map((day, index) => (
        <View key={index} style={{ 
          padding: 8, 
          backgroundColor: day.holiday?.length ? '#ffebee' : 'white' 
        }}>
          <Text>Day {day.day}</Text>
          {day.holiday?.length > 0 && (
            <Text style={{ color: '#d32f2f' }}>
              {day.holiday.join(', ')}
            </Text>
          )}
        </View>
      ))}
    </ScrollView>
  );
}
```

## 📚 API Reference

### `useCalendar(options)`

Main React hook for calendar functionality.

```typescript
interface Props {
  year?: number;   // Bikram Sambat year
  month?: number;  // Bikram Sambat month (1-12)
}

const {
  today,              // Today's date info
  monthsWithHolidays, // Calendar days with holidays
  currentBikYear,     // Current BS year
  currentBikMonth,    // Current BS month
  currentBikDay,      // Current BS day
  getThisMonths,      // Function to get current month days
} = useCalendar({ year: 2081, month: 3 });
```

### Utility Functions

```typescript
import { 
  getCurrentDate,
  daysInMonth,
  bikramSambat 
} from '@samirkoirala/bs-calendar-react';

// Get current BS date
const today = getCurrentDate();
// { year: 2082, month: 3, day: 27 }

// Get days in a specific month
const days = daysInMonth(2082, 3); // 32 days (Asadh can have 32 days!)

// Direct converter access
const bsDate = bikramSambat.toBik('2025-07-11');
const adDate = bikramSambat.toGreg(2082, 3, 27);
```

## 🌟 Unique Features

### Bikram Sambat Calendar Specifics

- **Variable month lengths**: BS months can have 29-32 days
- **32-day months**: Months like Asadh (असार), Jestha (जेठ) can have 32 days
- **Accurate holidays**: Complete Nepali holiday calendar included

### Month Names & Numbers

| Month | English | Nepali | Typical Days |
|-------|---------|--------|--------------|
| 1 | Baisakh | बैशाख | 30-31 |
| 2 | Jestha | जेठ | 31-32 |
| 3 | Asadh | असार | 31-32 |
| 4 | Shrawan | श्रावण | 31-32 |
| 5 | Bhadra | भदौ | 31 |
| 6 | Ashwin | आश्विन | 30-31 |
| 7 | Kartik | कार्तिक | 29-30 |
| 8 | Mangsir | मंसिर | 29-30 |
| 9 | Poush | पुष | 29-30 |
| 10 | Magh | माघ | 29-30 |
| 11 | Falgun | फाल्गुण | 29-30 |
| 12 | Chaitra | चैत्र | 30-31 |

## 📱 React Native Documentation

For detailed React Native usage, examples, and platform-specific guides:
- [React Native Usage Guide](./REACT_NATIVE.md)
- [Example App Setup](./EXAMPLE_APP.md)

## 🔧 Advanced Usage

### Month Navigation

```typescript
const [year, setYear] = useState(2081);
const [month, setMonth] = useState(3);

const { monthsWithHolidays } = useCalendar({ year, month });

const nextMonth = () => {
  if (month < 12) setMonth(month + 1);
  else { setYear(year + 1); setMonth(1); }
};
```

### Holiday Filtering

```typescript
const { monthsWithHolidays } = useCalendar({});
const holidays = monthsWithHolidays.filter(day => day.holiday?.length > 0);
```

## 🎯 TypeScript Support

Full TypeScript definitions included:

```typescript
interface IMonthDayWithHoliday {
  date: string;        // YYYY-MM-DD format
  month: number;       // Month number (1-12)
  day: number;         // Day number
  bs_date: string;     // Bikram Sambat date string
  holiday: string[];   // Array of holiday names
}
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## 📄 License

ISC License - see LICENSE file for details.

## 🙏 Credits

- **Author**: Pradip Chapagain
- **Bikram Sambat Converter**: Based on accurate BS calendar algorithms
- **Holiday Data**: Official Nepal holiday calendar

---

Made with ❤️ for the Nepali developer community