@samirkoirala/bs-calendar-react/REACT_NATIVE.md

A comprehensive React and React Native library for Bikram Sambat (Nepali) calendar with holidays support. Cross-platform compatible.

# React Native Usage Guide

This package is fully compatible with React Native and provides the same functionality as the React version.

## Installation

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

## React Native Compatibility

✅ **Works on all platforms:**
- iOS
- Android
- Web (React Native Web)
- Windows (React Native Windows)
- macOS (React Native macOS)

## Key Features for React Native

- **Cross-platform date handling**: No reliance on browser-specific APIs
- **Timezone awareness**: Properly handles Nepal timezone (+5:45 GMT) across all platforms
- **Performance optimized**: Lightweight and efficient for mobile apps
- **TypeScript support**: Full type definitions included

## Basic Usage

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

export const CalendarScreen = () => {
  const { 
    today, 
    monthsWithHolidays, 
    currentBikYear, 
    currentBikMonth 
  } = useCalendar({});

  return (
    <ScrollView style={{ flex: 1, padding: 16 }}>
      <Text style={{ fontSize: 24, fontWeight: 'bold' }}>
        Nepali Calendar
      </Text>
      
      <Text style={{ fontSize: 18, marginVertical: 10 }}>
        Today: {today.date}
      </Text>
      
      <Text style={{ fontSize: 16, marginBottom: 20 }}>
        Bikram Sambat: {currentBikYear}-{currentBikMonth}
      </Text>

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

## Advanced Usage

### Navigation Between Months

```typescript
import React, { useState } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { useCalendar } from 'bs-calendar-react';

export const NavigableCalendar = () => {
  const [selectedYear, setSelectedYear] = useState(2081);
  const [selectedMonth, setSelectedMonth] = useState(3);

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

  const goToPreviousMonth = () => {
    if (selectedMonth > 1) {
      setSelectedMonth(selectedMonth - 1);
    } else {
      setSelectedYear(selectedYear - 1);
      setSelectedMonth(12);
    }
  };

  const goToNextMonth = () => {
    if (selectedMonth < 12) {
      setSelectedMonth(selectedMonth + 1);
    } else {
      setSelectedYear(selectedYear + 1);
      setSelectedMonth(1);
    }
  };

  return (
    <View style={{ flex: 1, padding: 16 }}>
      <View style={{ 
        flexDirection: 'row', 
        justifyContent: 'space-between', 
        alignItems: 'center',
        marginBottom: 20
      }}>
        <TouchableOpacity 
          onPress={goToPreviousMonth}
          style={{ padding: 10, backgroundColor: '#e3f2fd', borderRadius: 5 }}
        >
          <Text>← Previous</Text>
        </TouchableOpacity>
        
        <Text style={{ fontSize: 18, fontWeight: 'bold' }}>
          {selectedYear} - Month {selectedMonth}
        </Text>
        
        <TouchableOpacity 
          onPress={goToNextMonth}
          style={{ padding: 10, backgroundColor: '#e3f2fd', borderRadius: 5 }}
        >
          <Text>Next →</Text>
        </TouchableOpacity>
      </View>

      {/* Calendar grid component */}
      <CalendarGrid days={monthsWithHolidays} />
    </View>
  );
};
```

### Calendar Grid Component

```typescript
import React from 'react';
import { View, Text, Dimensions } from 'react-native';
import { IMonthDayWithHoliday } from 'bs-calendar-react';

const { width } = Dimensions.get('window');
const dayWidth = (width - 32) / 7; // 7 days per week, 16px padding on each side

interface CalendarGridProps {
  days: IMonthDayWithHoliday[];
}

export const CalendarGrid: React.FC<CalendarGridProps> = ({ days }) => {
  const weeks = [];
  for (let i = 0; i < days.length; i += 7) {
    weeks.push(days.slice(i, i + 7));
  }

  return (
    <View>
      {/* Header with day names */}
      <View style={{ flexDirection: 'row', marginBottom: 10 }}>
        {['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].map(day => (
          <View key={day} style={{ width: dayWidth, alignItems: 'center' }}>
            <Text style={{ fontWeight: 'bold', fontSize: 12 }}>{day}</Text>
          </View>
        ))}
      </View>

      {/* Calendar weeks */}
      {weeks.map((week, weekIndex) => (
        <View key={weekIndex} style={{ flexDirection: 'row', marginBottom: 5 }}>
          {week.map((day, dayIndex) => (
            <View
              key={dayIndex}
              style={{
                width: dayWidth,
                height: 40,
                justifyContent: 'center',
                alignItems: 'center',
                backgroundColor: day.holiday?.length > 0 ? '#ffcdd2' : 'transparent',
                borderRadius: 5,
                margin: 1
              }}
            >
              <Text style={{ 
                fontSize: 14,
                color: day.holiday?.length > 0 ? '#d32f2f' : '#333'
              }}>
                {day.day}
              </Text>
            </View>
          ))}
        </View>
      ))}
    </View>
  );
};
```

## Unique Features of Bikram Sambat Calendar

- **Variable month lengths**: Unlike Gregorian calendar, BS months can have 29-32 days
- **32-day months**: Some months like Asadh (असार), Jestha (जेठ), and Shrawan (श्रावण) can have 32 days in certain years
- **Month order**: 1=Baisakh, 2=Jestha, 3=Asadh, 4=Shrawan, 5=Bhadra, 6=Ashwin, 7=Kartik, 8=Mangsir, 9=Poush, 10=Magh, 11=Falgun, 12=Chaitra

## Platform-Specific Considerations

### iOS
- Works seamlessly with iOS date handling
- Supports dark mode automatically
- Proper accessibility support

### Android
- Compatible with all Android versions supported by React Native
- Handles different screen densities properly
- Works with Android's date/time preferences

### Performance Tips

1. **Memoization**: Use `React.memo` for calendar components that don't change frequently
2. **Lazy loading**: Only load holiday data when needed
3. **Virtual scrolling**: For large calendar views, consider using FlatList

```typescript
import React, { memo } from 'react';

export const CalendarDay = memo(({ day }: { day: IMonthDayWithHoliday }) => {
  return (
    <View style={styles.dayContainer}>
      <Text>{day.day}</Text>
      {day.holiday?.map(holiday => (
        <Text key={holiday} style={styles.holiday}>{holiday}</Text>
      ))}
    </View>
  );
});
```

## Troubleshooting

### Common Issues

1. **Date not updating properly**: Make sure you're using the latest version and not caching old date values
2. **Timezone issues**: The package handles Nepal timezone automatically, no manual adjustment needed
3. **Performance on large lists**: Use FlatList for calendar views with many months

### Metro Configuration

If you encounter issues with ES modules, add this to your `metro.config.js`:

```javascript
module.exports = {
  resolver: {
    assetExts: ['bin', 'txt', 'jpg', 'png', 'json'],
  },
  transformer: {
    assetRegistryPath: 'react-native/Libraries/Image/AssetRegistry',
  },
};
```

## Support

- **React Native Version**: 0.60+
- **React Version**: 17+
- **TypeScript**: Full support included
- **Platforms**: iOS, Android, Web, Windows, macOS

For issues or feature requests, please visit the GitHub repository.