calendar-react/README.md

# react-calendario

A modern, flexible, and highly customizable calendar component library for React with TypeScript support.

## Features

- 📅 **Multiple Views**: Year, Month, Week, and custom date ranges
- 🎨 **Highly Customizable**: Multiple header styles, sizes, and visual options
- 🔍 **Interactive**: Date selection, range picking, and click handlers
- 📱 **Responsive**: Works on all screen sizes
- 🎯 **TypeScript**: Full type safety and IntelliSense support
- 🎨 **Themeable**: Customizable colors and styles
- 📦 **Lightweight**: Minimal dependencies

## Installation

```bash
npm install react-calendario date-fns classnames
```

or

```bash
yarn add react-calendario date-fns classnames
```

## Quick Start

```tsx
import { Month } from 'react-calendario';

function App() {
  return (
    <Month
      date={new Date()}
      dayHeaderStyle="expanded"
      size="l"
    />
  );
}
```

## Components

### Year

Display a full year calendar with customizable month grid.

```tsx
import { Year } from 'react-calendario';

<Year
  year={2024}
  dayHeaderStyle="tiny"
  monthCutoff="truncate"
  size="m"
  fontProportion={100}
  magnify={true}
/>
```

### Month

Display a single month with various layout options.

```tsx
import { Month } from 'react-calendario';

<Month
  date={new Date()}
  dayHeaderStyle="expanded"
  direction="column"
  monthCutoff="dimmed"
  size="xl"
/>
```

### Week

Display a single week view.

```tsx
import { Week } from 'react-calendario';

<Week
  startDate={new Date()}
  headerStyle="compacted"
  referenceMonth={0}
  size="l"
/>
```

### DateRange

Display a custom date range with optional selection and interactivity.

```tsx
import { DateRange } from 'react-calendario';

<DateRange
  from={new Date(2024, 0, 15)}
  to={new Date(2024, 0, 22)}
  included={true}
  selected={true}
  headerStyle="tiny"
  size="l"
  onDateClick={(date) => console.log('Clicked:', date)}
  activeDates={[new Date(2024, 0, 17)]}
/>
```

## Props

### Common Props

All components share these common props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'xl' \| 'l' \| 'm' \| 's' \| 'xs' \| 'xxs'` | `'l'` | Day cell size |
| `fontProportion` | `number` | `100` | Font size percentage (10-100) |
| `magnify` | `boolean` | `false` | Enable magnify effect on selection |
| `weekendDays` | `number[]` | `[6, 0]` | Weekend day indices (0=Sunday) |

### Header Styles

| Style | Description |
|-------|-------------|
| `'expanded'` | Full day names (e.g., "Monday") |
| `'compacted'` | Three-letter abbreviations (e.g., "Mon") |
| `'tiny'` | Two-letter abbreviations (e.g., "Mo") |
| `'none'` | Numbers only |

### Size Options

- `'xxs'`: Extra extra small (20px height, 1:1.5 header:content ratio)
- `'xs'`: Extra small (24px height)
- `'s'`: Small (28px height)
- `'m'`: Medium (32px height)
- `'l'`: Large (36px height)
- `'xl'`: Extra large (48px height)

## Advanced Usage

### Date Range Selection

```tsx
import { useState } from 'react';
import { Year } from 'react-calendario';

function DateRangePicker() {
  const [dateRange, setDateRange] = useState({
    startDate: null,
    endDate: null,
    selecting: false,
    hoverDate: null,
    anchorDate: null
  });

  const handleDateSelect = (date) => {
    // Your range selection logic
  };

  return (
    <Year
      year={2024}
      dateRange={dateRange}
      onDateSelect={handleDateSelect}
      onDateHover={(date) => setDateRange(prev => ({ ...prev, hoverDate: date }))}
    />
  );
}
```

### Interactive Date Range with Active States

```tsx
import { DateRange } from 'react-calendario';

function InteractiveCalendar() {
  const [activeDates, setActiveDates] = useState([]);

  const handleDateClick = (date) => {
    setActiveDates(prev => {
      const exists = prev.some(d => d.getTime() === date.getTime());
      return exists 
        ? prev.filter(d => d.getTime() !== date.getTime())
        : [...prev, date];
    });
  };

  return (
    <DateRange
      from={new Date(2024, 0, 1)}
      to={new Date(2024, 0, 31)}
      onDateClick={handleDateClick}
      activeDates={activeDates}
    />
  );
}
```

## Styling

The components use CSS modules and CSS variables for theming. You can override the default styles by:

1. Using the built-in props for common customizations
2. Overriding CSS variables in your global styles
3. Applying custom CSS classes

### CSS Variables

```css
:root {
  --color-primary: #2196f3;
  --color-primary-dark: #1976d2;
  --color-selected: #e3f2fd;
  /* ... and more */
}
```

## TypeScript

Full TypeScript support with exported types:

```tsx
import type { 
  DateRange, 
  HeaderStyle, 
  DaySize,
  MonthCutoffType 
} from 'react-calendario';
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.