# CalendarHeat

한 달 달력에서 날마다 공부한 시간을 색의 진하기(5단계)로 보여 주는 차트다.

- 분류: 차트
- 가져오기: `import { CalendarHeat } from '@/ui/charts'`
- 코드 위치: `apps/mobile/src/ui/charts.tsx:372` (Mordy 저장소 60df633)
- 웹 페이지: https://developers.moring.co/tds/components/calendar-heat

## 미리보기

실제 컴포넌트를 그린 화면은 https://developers.moring.co/tds/components/calendar-heat 에서 볼 수 있다. 서비스 색 선택기로 Mordy, Morit 색을 바꿔 볼 수 있다.

## 언제 쓰는가

### 쓴다
- "이번 달" 학습 기록처럼 날마다 공부한 정도를 한눈에 볼 때 쓴다.
- 칸을 누르면 그 날의 자세한 기록을 보여 준다(`onSelect`).
- 5단계 범례를 반드시 함께 쓴다.

### 쓰지 않는다
- 한 달을 넘는 기간에는 쓰지 않는다. 시작은 일요일, 달 하나 기준이다.
- 색만으로 값을 알리지 않는다. 눌렀을 때 시간을 글자로 보여 준다.

## 종류

종류가 없다.

## 크기

| 이름 | 값 | 설명 |
| --- | --- | --- |
| 기본 | 칸 최대 40, 칸 사이 8 | 폭이 좁으면 칸이 줄어든다. 7열. |

## 상태

| 상태 | 모습과 동작 |
| --- | --- |
| 5단계 | 학습 없음(`track`), 1~30분(`primary` 22%), 30분~1시간(45%), 1~2시간(72%), 2시간 이상(100%). |
| 미래 | 점선 테두리(`line`)의 빈 칸. 누를 수 없다. |
| 선택 | 2px `text` 테두리. |

## 사용 방법

### 기본

```tsx
import { CalendarHeat } from '@/ui/charts';

<CalendarHeat days={month.days} today={today} selected={sel} onSelect={setSel} />
```

### 속성(props)

| 이름 | 타입 | 기본값 | 필수 | 설명 |
| --- | --- | --- | --- | --- |
| `days` | `{ date: string; seconds: number; answered: number }[]` | — | 필수 | 그 달의 날짜 목록. 각 항목 `{ date: "YYYY-MM-DD", seconds, answered }`. 첫 날의 요일로 앞 빈 칸을 정한다. |
| `today` | `string` | — | 필수 | 오늘 날짜. 이후 날짜는 미래 칸이 된다. |
| `selected` | `string \| null` | — | 필수 | 선택된 날짜(없으면 `null`). |
| `onSelect` | `(date: string) => void` | — | 필수 | 칸을 눌렀을 때 날짜와 함께 호출된다. |

## 치수와 토큰

| 항목 | 값 |
| --- | --- |
| 칸 | 최대 40 정사각형, 모서리 = 크기 × 0.26, 사이 8 |
| 단계 기준 | 0초, 1800초 미만, 3600초 미만, 7200초 미만, 7200초 이상 |
| 요일 줄 | 일월화수목금토, `small`, `textSecondary` |

## 접근성

- 각 칸은 `button`이고 이름은 "{일}일, {단계 글자}"("12일, 30분~1시간")다. 미래 칸은 "아직 오지 않은 날".
- 5단계 범례를 글자로 함께 쓴다.

## 잘한 예와 잘못한 예

- 잘한 예: 범례(5단계 이름)를 함께 쓴다.
- 잘못한 예: 범례 없이 색만 있으면 무엇을 뜻하는지 알 수 없다.

## 함께 보는 컴포넌트

- [HourBars](https://developers.moring.co/tds/components/hour-bars.md): 값 축이 있는 막대 차트다. 학습 시간(시간·분)이나 푼 문제 수를 날짜별로 보여 주고, 고른 막대 위에 말풍선이 뜬다.
- [WeekStrip](https://developers.moring.co/tds/components/week-strip.md): 월요일부터 일요일까지 7일을 한 줄로 보여 주는 주간 표시다. 공부한 날에는 점이 찍힌다.
- [Calendar](https://developers.moring.co/tds/components/date-calendar.md): 한 달 달력에서 여러 날짜를 고르는 컴포넌트다. 시험 날짜를 고를 때 쓴다.