calendar-react/README.md

# Minimal Calendar Component

A flexible and customizable calendar component built with React, TypeScript, and styled-components.

## Features

- 📅 Year, month, and week views
- 🎨 Multiple header styles (expanded, compacted, tiny, none)
- 🎯 Customizable month cutoff behavior
- 🎭 Weekend highlighting
- 📱 Fully responsive design
- 🔧 TypeScript support
- 💅 Styled with styled-components

## Installation

```bash
npm install date-fns styled-components
```

## Basic Usage

```tsx
import { Year } from './components/calendar/Year';

function App() {
  return (
    <Year 
      year={2024}
      dayHeaderStyle="tiny"
      weekendDays={[6, 0]} // Saturday and Sunday
    />
  );
}
```

## Advanced Usage

### With Date Selection

```tsx
import { useState } from 'react';
import { Year } from './components/calendar/Year';

function App() {
  const [selectedDate, setSelectedDate] = useState<Date | undefined>();

  return (
    <Year 
      year={2024}
      dayHeaderStyle="expanded"
      monthCutoff="truncate"
      weekendDays={[6, 0]}
      selectedDate={selectedDate}
      onDateSelect={setSelectedDate}
    />
  );
}
```

### With Controls

```tsx
import { useState } from 'react';
import { Year } from './components/calendar/Year';
import { Controls } from './components/calendar/Controls';
import { HeaderStyle, MonthCutoffType } from './types/calendar';

function App() {
  const [headerStyle, setHeaderStyle] = useState<HeaderStyle>('tiny');
  const [monthCutoff, setMonthCutoff] = useState<MonthCutoffType>('truncate');

  return (
    <>
      <Controls
        headerStyle={headerStyle}
        monthCutoff={monthCutoff}
        onHeaderStyleChange={setHeaderStyle}
        onMonthCutoffChange={setMonthCutoff}
      />
      <Year 
        year={2024}
        dayHeaderStyle={headerStyle}
        monthCutoff={monthCutoff}
        weekendDays={[6, 0]}
      />
    </>
  );
}
```

## Component Props

### Year Component

| Prop | Type | Description |
|------|------|-------------|
| year | number | The year to display |
| dayHeaderStyle | 'expanded' \| 'compacted' \| 'tiny' \| 'none' | Style of day headers |
| monthDayOfWeekHeaderStyle | HeaderStyle (optional) | Style of month day headers |
| monthCutoff | 'dimmed' \| 'truncate' \| undefined | How to handle days from other months |
| weekendDays | number[] | Array of day indices to mark as weekends (0-6) |
| selectedDate | Date (optional) | Currently selected date |
| rangeStart | Date (optional) | Start date for range selection |
| rangeEnd | Date (optional) | End date for range selection |
| onDateSelect | (date: Date) => void (optional) | Date selection callback |
| compact | boolean (optional) | Use compact layout |

### Controls Component

| Prop | Type | Description |
|------|------|-------------|
| headerStyle | HeaderStyle | Current header style |
| monthCutoff | MonthCutoffType | Current month cutoff type |
| onHeaderStyleChange | (type: HeaderStyle) => void | Header style change handler |
| onMonthCutoffChange | (type: MonthCutoffType) => void | Month cutoff change handler |

## Styling

The calendar uses styled-components for styling. You can customize the appearance by:

1. Using the built-in props
2. Extending the styled components
3. Wrapping components with custom styled containers

Example of custom styling:

```tsx
import styled from 'styled-components';
import { Year } from './components/calendar/Year';

const CustomCalendarContainer = styled.div`
  padding: 2rem;
  background: #fafafa;
  
  // Custom styles for the calendar
  .month-title {
    color: #1a73e8;
  }
`;

function App() {
  return (
    <CustomCalendarContainer>
      <Year 
        year={2024}
        dayHeaderStyle="tiny"
      />
    </CustomCalendarContainer>
  );
}
```

## Header Styles

- **expanded**: Full day names (e.g., "MONDAY")
- **compacted**: Three-letter day names (e.g., "MON")
- **tiny**: Single letter day names (e.g., "M")
- **none**: No day headers, only numbers

## Month Cutoff Options

- **dimmed**: Show days from other months with reduced opacity
- **truncate**: Hide days from other months
- **undefined**: Show all days normally

## Browser Support

The calendar component supports all modern browsers:

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## License

MIT