# ProgressRing

진행률을 둥근 고리로 보여 준다. `ProgressRing`은 작은 고정 고리, `AnimatedRing`은 나타날 때 0%에서 값까지 채워지는 큰 고리다.

- 분류: 데이터 표시
- 가져오기: `import { ProgressRing, AnimatedRing } from '@/ui/charts'`
- 코드 위치: `apps/mobile/src/ui/charts.tsx:12` (Mordy 저장소 60df633)
- 웹 페이지: https://developers.moring.co/tds/components/progress-ring

## 미리보기

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

## 언제 쓰는가

### 쓴다
- 과목 목록처럼 작은 곳에서 진도를 숫자와 함께 보일 때 `ProgressRing`을 쓴다.
- 문제 풀이 결과, 시험 목표처럼 화면의 주인공이 되는 값에는 `AnimatedRing`을 쓰고, 가운데에 숫자나 글자를 `children`으로 넣는다.

### 쓰지 않는다
- 값이 없는데 0%로 보이지 않는다. `ProgressRing`에 `null`을 넘기면 "기록 없음"과 "–"로 표시한다.
- 한 화면에 고리를 여러 개 큰 크기로 놓지 않는다. 주인공 하나만 크게 쓴다.
- 여러 부분으로 나뉜 값은 `DonutChart`를 쓴다.

## 종류

| 이름 | 설명 |
| --- | --- |
| ProgressRing | 고정 고리. 가운데 글자는 퍼센트(또는 `label`). |
| AnimatedRing | 900ms 동안 0에서 값까지 채워진다(150ms 뒤 시작). 가운데는 `children`. |

## 크기

| 이름 | 값 | 설명 |
| --- | --- | --- |
| ProgressRing | 지름 52, 선 5 | 글자 크기는 지름의 0.24. |
| AnimatedRing | 지름 140, 선 12 |  |

## 상태

| 상태 | 모습과 동작 |
| --- | --- |
| 값 있음 | `primary` 호가 `track` 고리 위에 그려진다. 끝은 둥글다. |
| 값 없음 | `null`이면 호가 없고 "–"를 보인다. |

## 사용 방법

### ProgressRing

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

<ProgressRing value={accuracy} />   {/* 0~1, 없으면 null */}
```

### AnimatedRing

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

<AnimatedRing value={score / 100}>
  <AppText variant="metric">{score}%</AppText>
</AnimatedRing>
```

### 속성(props)

#### ProgressRing

| 이름 | 타입 | 기본값 | 필수 | 설명 |
| --- | --- | --- | --- | --- |
| `value` | `number \| null` | — | 필수 | 진행률(0~1). 없으면 `null`. |
| `size` | `number` | `52` | 선택 | 지름(px). 기본 52. |
| `stroke` | `number` | `5` | 선택 | 선 두께(px). 기본 5. |
| `tint` | `string` | `color.primary` | 선택 | 호의 색. 기본 `color.primary`. |
| `track` | `string` | `color.track` | 선택 | 바탕 고리 색. 기본 `color.track`. |
| `label` | `string` | — | 선택 | 가운데 글자. 없으면 퍼센트. |
| `labelSize` | `number` | — | 선택 | 가운데 글자 크기. |
| `labelColor` | `string` | `color.text` | 선택 | 가운데 글자 색. 기본 `color.text`. |

#### AnimatedRing

| 이름 | 타입 | 기본값 | 필수 | 설명 |
| --- | --- | --- | --- | --- |
| `value` | `number` | — | 필수 | 진행률(0~1). |
| `size` | `number` | `140` | 선택 | 지름(px). 기본 140. |
| `stroke` | `number` | `12` | 선택 | 선 두께(px). 기본 12. |
| `tint` | `string` | `color.primary` | 선택 | 호의 색. |
| `track` | `string` | `color.track` | 선택 | 바탕 고리 색. |
| `delay` | `number` | `150` | 선택 | 채우기 시작 전 기다리는 시간(ms). 기본 150. |
| `children` | `ReactNode` | — | 선택 | 고리 가운데에 놓을 요소. |

## 치수와 토큰

| 항목 | 값 |
| --- | --- |
| 호 | 시작은 12시 방향, 시계 방향, 끝이 둥글다(`round`) |
| 색 | 호 `primary`, 바탕 `track` |
| 움직임 | `AnimatedRing` 900ms, out 곡선, 150ms 지연 |

## 접근성

- `ProgressRing`의 이름은 퍼센트(또는 `label`)이고 값이 없으면 "기록 없음"이다.
- 가운데 숫자를 함께 보인다. 호의 길이만으로 값을 전달하지 않는다.

## 잘한 예와 잘못한 예

- 잘한 예: 가운데에 숫자를 함께 쓴다.
- 잘못한 예: 숫자 없이 고리만 있으면 정확한 값을 알 수 없다.

## 함께 보는 컴포넌트

- [DonutChart](https://developers.moring.co/tds/components/donut-chart.md): 전체를 여러 부분으로 나눠 보여 주는 도넛 차트다. 부분 사이에 3의 틈이 있다. 시험 계획의 익힘/학습 중/시작 전 비율에 쓴다.
- [ProgressBar](https://developers.moring.co/tds/components/progress-bar.md): 진행률을 가로 막대로 보여 준다. 채운 부분은 기본으로 서비스 주색 그라데이션이다.
- [SegmentedProgress](https://developers.moring.co/tds/components/segmented-progress.md): 문제 하나에 칸 하나씩, 푼 문제만큼 칸이 채워지는 진행 막대다. 퀴즈 맨 위에 쓴다.