# 📅 달력 위젯 구현 계획

## 개요

대시보드에 추가할 수 있는 달력 위젯을 구현합니다. 사용자가 날짜를 확인하고 일정을 관리할 수 있는 인터랙티브한 달력 기능을 제공합니다.

## 주요 기능

### 1. 달력 뷰 타입

- **월간 뷰**: 한 달 전체를 보여주는 기본 뷰
- **주간 뷰**: 일주일을 세로로 보여주는 뷰
- **일간 뷰**: 하루의 시간대별 일정 뷰

### 2. 달력 설정

- **시작 요일**: 월요일 시작 / 일요일 시작 선택
- **주말 강조**: 주말 색상 다르게 표시
- **오늘 날짜 강조**: 오늘 날짜 하이라이트
- **공휴일 표시**: 한국 공휴일 표시 (선택 사항)

### 3. 테마 및 스타일

- **Light 테마**: 밝은 배경
- **Dark 테마**: 어두운 배경
- **사용자 지정**: 커스텀 색상 선택

### 4. 일정 기능 (향후 확장)

- 간단한 메모 추가
- 일정 표시 (외부 연동)

## 구현 단계

### ✅ Step 1: 타입 정의

- [x] `CalendarConfig` 인터페이스 정의
- [x] `types.ts`에 달력 설정 타입 추가
- [x] 요소 타입에 'calendar' subtype 추가

### ✅ Step 2: 기본 달력 컴포넌트

- [x] `CalendarWidget.tsx` - 메인 위젯 컴포넌트
- [x] `MonthView.tsx` - 월간 달력 뷰
- [x] 날짜 계산 유틸리티 함수 (`calendarUtils.ts`)
- [ ] `WeekView.tsx` - 주간 달력 뷰 (향후 추가)

### ✅ Step 3: 달력 네비게이션

- [x] 이전/다음 월 이동 버튼
- [x] 오늘로 돌아가기 버튼
- [ ] 월/연도 선택 드롭다운 (향후 추가)

### ✅ Step 4: 설정 UI

- [x] `CalendarSettings.tsx` - Popover 내장 설정 컴포넌트
- [x] 뷰 타입 선택 (월간 - 현재 구현)
- [x] 시작 요일 설정
- [x] 테마 선택 (light/dark/custom)
- [x] 표시 옵션 (주말 강조, 공휴일, 오늘 강조)

### ✅ Step 5: 스타일링

- [x] 달력 그리드 레이아웃
- [x] 날짜 셀 디자인
- [x] 오늘 날짜 하이라이트
- [x] 주말/평일 구분
- [x] 반응형 디자인 (크기별 최적화)

### ✅ Step 6: 통합

- [x] `DashboardSidebar`에 달력 위젯 추가
- [x] `CanvasElement`에서 달력 위젯 렌더링
- [x] `DashboardDesigner`에 기본값 설정

### ✅ Step 7: 공휴일 데이터

- [x] 한국 공휴일 데이터 정의
- [x] 공휴일 표시 기능
- [x] 공휴일 이름 툴팁

### ✅ Step 8: 테스트 및 최적화

- [ ] 다양한 크기에서 테스트 (사용자 테스트 필요)
- [x] 날짜 계산 로직 검증
- [ ] 성능 최적화 (필요시)
- [ ] 접근성 개선 (필요시)

## 기술 스택

### UI 컴포넌트

- **shadcn/ui**: Button, Select, Switch, Popover, Card
- **lucide-react**: Settings, ChevronLeft, ChevronRight, Calendar

### 날짜 처리

- **JavaScript Date API**: 기본 날짜 계산
- **Intl.DateTimeFormat**: 날짜 형식화
- 외부 라이브러리 없이 순수 구현

### 스타일링

- **Tailwind CSS**: 반응형 그리드 레이아웃
- **CSS Grid**: 달력 레이아웃

## 컴포넌트 구조

```
widgets/
├── CalendarWidget.tsx       # 메인 위젯 (설정 버튼 포함)
├── CalendarSettings.tsx     # 설정 UI (Popover 내부)
├── MonthView.tsx           # 월간 뷰
├── WeekView.tsx            # 주간 뷰 (선택)
├── DayView.tsx             # 일간 뷰 (선택)
└── calendarUtils.ts        # 날짜 계산 유틸리티
```

## 데이터 구조

```typescript
interface CalendarConfig {
  view: "month" | "week" | "day"; // 뷰 타입
  startWeekOn: "monday" | "sunday"; // 주 시작 요일
  highlightWeekends: boolean; // 주말 강조
  highlightToday: boolean; // 오늘 강조
  showHolidays: boolean; // 공휴일 표시
  theme: "light" | "dark" | "custom"; // 테마
  customColor?: string; // 사용자 지정 색상
  showWeekNumbers?: boolean; // 주차 표시 (선택)
}
```

## UI/UX 고려사항

### 반응형 디자인

- **2x2**: 미니 달력 (월간 뷰만, 날짜만 표시)
- **3x3**: 기본 달력 (월간 뷰, 요일 헤더 포함)
- **4x4 이상**: 풀 달력 (모든 기능, 일정 표시 가능)

### 인터랙션

- 날짜 클릭 시 해당 날짜 정보 표시 (선택)
- 드래그로 월 변경 (선택)
- 키보드 네비게이션 지원

### 접근성

- 날짜 셀에 적절한 aria-label
- 키보드 네비게이션 지원
- 스크린 리더 호환

## 공휴일 데이터 구조

```typescript
interface Holiday {
  date: string; // 'MM-DD' 형식
  name: string; // 공휴일 이름
  isRecurring: boolean; // 매년 반복 여부
}

// 2025년 한국 공휴일 예시
const KOREAN_HOLIDAYS: Holiday[] = [
  { date: "01-01", name: "신정", isRecurring: true },
  { date: "01-28", name: "설날 연휴", isRecurring: false },
  { date: "01-29", name: "설날", isRecurring: false },
  { date: "01-30", name: "설날 연휴", isRecurring: false },
  { date: "03-01", name: "삼일절", isRecurring: true },
  { date: "05-05", name: "어린이날", isRecurring: true },
  { date: "06-06", name: "현충일", isRecurring: true },
  { date: "08-15", name: "광복절", isRecurring: true },
  { date: "10-03", name: "개천절", isRecurring: true },
  { date: "10-09", name: "한글날", isRecurring: true },
  { date: "12-25", name: "크리스마스", isRecurring: true },
];
```

## 향후 확장 기능

### Phase 2 (선택)

- [ ] 일정 추가/수정/삭제
- [ ] 반복 일정 설정
- [ ] 카테고리별 색상 구분
- [ ] 다른 달력 서비스 연동 (Google Calendar, Outlook 등)
- [ ] 일정 알림 기능
- [ ] 드래그 앤 드롭으로 일정 이동

### Phase 3 (선택)

- [ ] 여러 달력 레이어 지원
- [ ] 일정 검색 기능
- [ ] 월별 통계 (일정 개수 등)
- [ ] CSV/iCal 내보내기

## 참고사항

### 장점

- 순수 JavaScript로 구현 (외부 의존성 최소화)
- shadcn/ui 컴포넌트 활용으로 일관된 디자인
- 시계 위젯과 동일한 패턴 (내장 설정 UI)

### 주의사항

- 날짜 계산 로직 정확성 검증 필요
- 윤년 처리
- 타임존 고려 (필요시)
- 다양한 크기에서의 가독성

## 완료 기준

- [x] 월간 뷰 달력이 정확하게 표시됨
- [x] 이전/다음 월 네비게이션이 작동함
- [x] 오늘 날짜가 하이라이트됨
- [x] 주말이 다른 색상으로 표시됨
- [x] 공휴일이 표시되고 이름이 보임
- [x] 설정 UI에서 모든 옵션을 변경할 수 있음
- [x] 테마 변경이 즉시 반영됨
- [x] 2x2 크기에서도 깔끔하게 표시됨
- [x] 4x4 크기에서 모든 기능이 정상 작동함

---

## 구현 시작

이제 단계별로 구현을 시작합니다!