# react-calendario

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

## 🆕 Version 1.4.0 Features

- 📅 **Today in Any State**: Define custom colors for today's date in any state (default, active, rangeStart, etc.)
- ✏️ **Header Text Transform**: Custom function to transform day name display (e.g., `dayName => dayName.slice(0, 2)`)
- 🌍 **International Locale Support**: Full internationalization with 50+ languages via date-fns
- 🎨 **Three-Dimensional Color Schemes**: Control colors by week split (weekday/weekend), relative (today/anyday), and state
- 🎯 **Enhanced Weekend Support**: Distinct colors for weekends in all selection states

📖 **[View the complete Usage Guide](./USAGE_GUIDE.md)** for detailed examples of the new features!

## 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
- 🌍 **i18n Support**: Locale-aware with date-fns locales
- 🎨 **Advanced Theming**: Comprehensive color customization system
- 📦 **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';
import 'react-calendario/dist/react-calendario.css';

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

### With Locale and Custom Colors (v1.1.0+)

```tsx
import { Year } from 'react-calendario';
import { fr } from 'date-fns/locale';

const colorScheme = [
  { 
    type: 'weekday', 
    state: 'default',
    colors: { 
      header: { backgroundColor: '#2c3e50', color: '#ffffff' },
      content: { backgroundColor: '#ffffff', color: '#2c3e50' }
    }
  },
  { 
    type: 'weekend', 
    state: 'default',
    colors: {
      header: { backgroundColor: '#95a5a6', color: '#ffffff' },
      content: { backgroundColor: '#ecf0f1', color: '#34495e' }
    }
  }
  // ... more states
];

<Year
  year={2025}
  locale={fr}  // French locale
  colorScheme={colorScheme}  // Custom colors
/>
```

## 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}
    />
  );
}
```

## Customization

### 1. Built-in Props

The easiest way to customize the calendar is through props:

```tsx
<Month
  date={new Date()}
  dayHeaderStyle="tiny"      // Header style
  size="xl"                  // Cell size
  fontProportion={80}        // Font size (10-100)
  monthCutoff="dimmed"       // How to show other month's days
  weekendDays={[0, 6]}       // Which days are weekends
  magnify={true}             // Magnify effect on selection
/>
```

### 2. Theming with CSS

The library uses CSS modules with predictable class names (prefixed with `rc_`). While the internal Sass variables don't support CSS custom properties due to color manipulation functions, you can still customize the appearance through CSS overrides:

```css
/* Override component styles */
.rc_Day__Container {
  background: var(--my-bg-color, white);
  color: var(--my-text-color, #2c2c2c);
  border-color: var(--my-border-color, #f0f0f0);
}

.rc_Day__Header {
  background: var(--my-header-bg, #2c2c2c);
  color: var(--my-header-text, white);
}

/* Custom theme example */
[data-theme="dark"] {
  --my-bg-color: #1a1a1a;
  --my-text-color: #ffffff;
  --my-border-color: #333333;
  --my-header-bg: #2a2a2a;
  --my-header-text: #ffffff;
}

/* Selected state */
.rc_Day__Container--selected {
  background: var(--my-selected-bg, #e3f2fd) !important;
}

/* Hover state */
.rc_Day__Container--interactive:hover {
  background: var(--my-hover-bg, #f5f5f5);
}
```

### 3. Custom Styling

The components use CSS modules with predictable class names:

```css
/* Target specific components */
.rc_Month__Container {
  /* Custom month container styles */
}

.rc_Day__Container {
  /* Custom day styles */
}

.rc_Day__Container--selected {
  /* Custom selected day styles */
}

.rc_Day__Container--active {
  /* Custom active day styles */
}

/* Custom weekend styling */
.rc_Day__Container--greyed {
  opacity: 0.5;
}
```

### 4. Size Customization

Create custom sizes beyond the built-in options:

```css
/* Custom size classes */
.rc_Day--custom .rc_Day__Header {
  height: 64px;
  font-size: 1.2rem;
}

.rc_Day--custom .rc_Day__Content {
  height: 128px; /* 2x header height */
}
```

Then use it:
```tsx
<Month size="custom" />
```

### 5. Complete Theme Example

```css
/* Purple theme */
:root {
  --rc-primary: #7c3aed;
  --rc-primary-dark: #6d28d9;
  --rc-selected: #ede9fe;
  --rc-selected-hover: #ddd6fe;
  --rc-text: #1f2937;
  --rc-hover: #f3f4f6;
}

/* Rounded corners */
.rc_Day__Container {
  border-radius: 12px;
  overflow: hidden;
}

/* Spacing between days */
.rc_Week__Container {
  gap: 4px;
}

/* Custom header style */
.rc_Day__Header {
  text-transform: uppercase;
  letter-spacing: 0.05em;
  font-weight: 600;
}
```

### 6. Advanced Customization

For complete control, you can:

1. **Import SCSS variables** (if using Sass):
```scss
@use 'react-calendario/styles/variables' as rc;

.custom-calendar {
  padding: rc.$week-wrapper-padding;
}
```

2. **Override specific component styles**:
```css
/* Remove borders */
.rc_Day__Container {
  border: none;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

/* Custom hover effect */
.rc_Day__Container--interactive:hover {
  transform: scale(1.05);
  transition: transform 0.2s;
}
```

3. **Customize date number rendering**:
```css
/* Circle style for dates */
.rc_DayNumber__Container {
  background: #f0f0f0;
  border-radius: 50%;
  width: 32px;
  height: 32px;
  margin: auto;
}
```

## 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.