calendar-react/USAGE_GUIDE.md

# Calendar Component Usage Guide

## ✏️ Header Text Transform (v1.2.0+)

Customize how day names are displayed with a transform function:

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

// Example 1: Two-letter abbreviations
<Month
  date={new Date()}
  headerStyle="compacted"  // Shows "MON", "TUE", etc.
  headerTextTransform={(dayName) => dayName.slice(0, 2)}  // Returns "MO", "TU", etc.
/>

// Example 2: Custom mapping
const customDayNames = (dayName: string) => {
  const map: Record<string, string> = {
    'MON': 'Mo', 'TUE': 'Tu', 'WED': 'We',
    'THU': 'Th', 'FRI': 'Fr', 'SAT': 'Sa', 'SUN': 'Su'
  };
  return map[dayName] || dayName;
};

<Month
  date={new Date()}
  headerStyle="compacted"
  headerTextTransform={customDayNames}
/>

// Example 3: Lowercase
<Month
  date={new Date()}
  headerStyle="tiny"
  headerTextTransform={(dayName) => dayName.toLowerCase()}
/>
```

The `headerTextTransform` function:
- Receives the day name after `headerStyle` processing
- Can return any string for display
- Works with all components: Year, Month, Week, DateRange, Day

## 🎨 Custom Color Schemes

### Basic Active Colors (Simple)
For highlighting specific dates with custom colors:

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

const activeColors: ActiveColors = {
  headerBg: '#D4EDDA',
  headerColor: '#155724',
  contentBg: '#28A745',
  contentColor: '#FFFFFF'
};

<Year 
  year={2025}
  activeDates={[new Date(2025, 0, 1), new Date(2025, 11, 25)]}
  activeColors={activeColors}
/>
```

### Comprehensive Color Scheme (Advanced)
Full control over colors for every state and day type:

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

const colorScheme: ColorScheme = [
  // Today's date colors for different states
  { 
    weekSplit: 'weekday', 
    relative: 'today',
    state: 'default',  // Today when it's a normal weekday
    colors: { 
      header: { backgroundColor: '#ffd700', color: '#000000' },
      content: { backgroundColor: '#fff9e6', color: '#000000' }
    }
  },
  { 
    weekSplit: 'weekday', 
    relative: 'today',
    state: 'active',  // Today when it's active/clicked
    colors: { 
      header: { backgroundColor: '#ffed4e', color: '#000000' },
      content: { backgroundColor: '#fff59d', color: '#000000' }
    }
  },
  { 
    weekSplit: 'weekday', 
    relative: 'today',
    state: 'rangeStart',  // Today when it starts a range
    colors: { 
      header: { backgroundColor: '#ffc107', color: '#000000' },
      content: { backgroundColor: '#ffeb3b', color: '#000000' }
    }
  },
  // Regular weekday colors (anyday is default when relative is omitted)
  { 
    weekSplit: 'weekday', 
    state: 'default',  // Normal weekday
    colors: { 
      header: { backgroundColor: '#2c3e50', color: '#ffffff' },
      content: { backgroundColor: '#ffffff', color: '#2c3e50' }
    }
  },
  { 
    weekSplit: 'weekday', 
    state: 'rangeStart',  // First day of selected range
    colors: {
      header: { backgroundColor: '#2980b9', color: '#ffffff' },
      content: { backgroundColor: '#3498db', color: '#ffffff' }
    }
  },
  { 
    weekSplit: 'weekday', 
    state: 'rangeMid',  // Middle days of selected range
    colors: {
      header: { backgroundColor: '#5dade2', color: '#ffffff' },
      content: { backgroundColor: '#aed6f1', color: '#1a5490' }
    }
  },
  
  // Weekend colors
  { 
    weekSplit: 'weekend', 
    state: 'default',  // Normal weekend
    colors: {
      header: { backgroundColor: '#7f8c8d', color: '#ffffff' },
      content: { backgroundColor: '#ecf0f1', color: '#34495e' }
    }
  },
  { 
    weekSplit: 'weekend', 
    state: 'rangeStart',  // Weekend that starts a range
    colors: {
      header: { backgroundColor: '#2980b9', color: '#ffffff' },
      content: { backgroundColor: '#3498db', color: '#ffffff' }
    }
  },
  // ... more states
];

<Year 
  year={2025}
  colorScheme={colorScheme}
/>
```

#### Color Scheme Dimensions:

**Week Split** (`weekSplit`):
- `weekday` - Monday through Friday
- `weekend` - Saturday and Sunday (or custom weekend days)

**Relative** (`relative`, optional):
- `today` - Today's date (automatically detected)
- `anyday` - Any other date (default when omitted)

**State** (`state`):
- `default` - Normal day appearance
- `selecting` - Day is being hovered during selection
- `rangeStart` - First day of a range
- `rangeEnd` - Last day of a range  
- `rangeMid` - Middle days of a selected range
- `active` - Special highlighted days (holidays, events)

#### Backwards Compatibility:
- `type` is still supported but deprecated (use `weekSplit` instead)

## 🌍 Locale Support

### Basic Usage
```tsx
import { Year } from 'react-calendario';
import { fr, de, ja, es } from 'date-fns/locale';

// French
<Year year={2025} locale={fr} />

// German
<Year year={2025} locale={de} />

// Japanese
<Year year={2025} locale={ja} />

// Spanish
<Year year={2025} locale={es} />
```

### What Gets Localized:
- Month names (January → Janvier → Januar → 一月)
- Day headers based on style:
  - `expanded`: Full names (MONDAY → LUNDI → MONTAG)
  - `compacted`: 3-letter (MON → LUN → MO)
  - `tiny`: Single letter (M → L → M)
- Date formats in tooltips and labels

### Available Locales:
All date-fns locales are supported. Common ones include:
- `enUS` - English (US) - Default
- `es` - Spanish
- `fr` - French
- `de` - German
- `it` - Italian
- `pt` - Portuguese
- `ja` - Japanese
- `ko` - Korean
- `zhCN` - Chinese (Simplified)
- `ru` - Russian
- `ar` - Arabic
- `nl` - Dutch
- `pl` - Polish
- `tr` - Turkish
- `sv` - Swedish
- `nb` - Norwegian

## 🎯 Combined Example

Using both features together:

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

const frenchHolidayScheme: ColorScheme = [
  // Regular days with French aesthetic
  { 
    type: 'weekday', 
    state: 'default',
    colors: { 
      header: { backgroundColor: '#002395', color: '#ffffff' },  // French blue
      content: { backgroundColor: '#ffffff', color: '#002395' }
    }
  },
  // Weekends in subtle gray
  { 
    type: 'weekend', 
    state: 'default',
    colors: {
      header: { backgroundColor: '#95a5a6', color: '#ffffff' },
      content: { backgroundColor: '#ecf0f1', color: '#34495e' }
    }
  },
  // French holidays in red
  { 
    type: 'weekday', 
    state: 'active',
    colors: {
      header: { backgroundColor: '#ed2939', color: '#ffffff' },  // French red
      content: { backgroundColor: '#c0392b', color: '#ffffff' }
    }
  },
  { 
    type: 'weekend', 
    state: 'active',
    colors: {
      header: { backgroundColor: '#c0392b', color: '#ffffff' },
      content: { backgroundColor: '#ed2939', color: '#ffffff' }
    }
  }
];

const frenchHolidays = [
  new Date(2025, 0, 1),   // Jour de l'An
  new Date(2025, 4, 1),   // Fête du Travail
  new Date(2025, 6, 14),  // Fête Nationale
  new Date(2025, 11, 25)  // Noël
];

<Year 
  year={2025}
  locale={fr}
  colorScheme={frenchHolidayScheme}
  activeDates={frenchHolidays}
  dayHeaderStyle="compacted"
/>
```

## 📝 Tips

1. **Color Scheme Fallbacks**: You don't need to define every state. The system intelligently falls back:
   - Weekend states → Weekday states of same type
   - Missing states → Default state
   - Weekend default → Weekday default

2. **Performance**: ColorScheme is more efficient than inline styles for large calendars

3. **Accessibility**: Ensure sufficient color contrast between background and text colors

4. **Locale + Colors**: Combine locale with themed colors for culturally appropriate calendars

5. **Weekend Customization**: Weekend days are automatically detected and styled differently, including when they're part of a selected range