# Progress Circle
URL: /lynx/components/progress-circle
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/progress-circle.mdx

작업이 진행 중임을 알리거나 작업 시간을 시각적으로 나타내는 데 사용됩니다.

Lynx Engine 최소 버전: 3.6

사용 가능 버전: @seed-design/lynx-react@0.1.0, @seed-design/lynx-css@0.1.0

## Preview

```tsx
import "./styles";

import { ProgressCircle } from "@/components/ui/progress-circle";

import { useSeedClassName } from "@seed-design/lynx-react";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-progress-circle-root`}>
      <view className="progress-circle-preview">
        <ProgressCircle tone="neutral" size="40" />
      </view>
    </view>
  );
}
```

## Installation

- npm: npx @seed-design/cli add ui:progress-circle
- pnpm: pnpm dlx @seed-design/cli add ui:progress-circle
- yarn: yarn dlx @seed-design/cli add ui:progress-circle
- bun: bun x @seed-design/cli add ui:progress-circle

## Props

`ProgressCircle`은 기본적으로 접근성 요소로 노출되며 `accessibility-role-description="progressbar"`를 전달합니다. `minValue`, `maxValue`, `value`를 모두 지정하면 세 값을 `accessibility-value`로 전달하고, `value`를 생략하면 `indeterminate`를 전달합니다.

스크린 리더가 읽을 문구를 바꾸려면 `accessibility-value`를 직접 지정하세요. 필요한 경우 `accessibility-role-description`과 `accessibility-element`도 같은 방식으로 덮어쓸 수 있습니다.

```tsx
<ProgressCircle
  minValue={0}
  maxValue={100}
  value={40}
  accessibility-label="파일 업로드"
  accessibility-value="40% 완료"
/>
```

## Examples

### Neutral

```tsx
import "./styles";

import { ProgressCircle } from "@/components/ui/progress-circle";

import { useSeedClassName } from "@seed-design/lynx-react";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-progress-circle-root`}>
      <view className="progress-circle-preview">
        <ProgressCircle tone="neutral" />
      </view>
    </view>
  );
}
```

### Brand

```tsx
import "./styles";

import { ProgressCircle } from "@/components/ui/progress-circle";

import { useSeedClassName } from "@seed-design/lynx-react";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-progress-circle-root`}>
      <view className="progress-circle-preview">
        <ProgressCircle tone="brand" />
      </view>
    </view>
  );
}
```

### Static White

`staticWhite`는 어두운 배경 위에서 사용합니다.

```tsx
import "./styles";

import { ProgressCircle } from "@/components/ui/progress-circle";

import { useSeedClassName } from "@seed-design/lynx-react";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view
      className={`${seedClassName} progress-circle-preview--dark docs-lynx-progress-circle-root`}
    >
      <view className="progress-circle-preview">
        <ProgressCircle tone="staticWhite" />
      </view>
    </view>
  );
}
```

### Size=40

```tsx
import "./styles";

import { ProgressCircle } from "@/components/ui/progress-circle";

import { useSeedClassName } from "@seed-design/lynx-react";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-progress-circle-root`}>
      <view className="progress-circle-preview">
        <ProgressCircle size="40" />
      </view>
    </view>
  );
}
```

### Size=24

```tsx
import "./styles";

import { ProgressCircle } from "@/components/ui/progress-circle";

import { useSeedClassName } from "@seed-design/lynx-react";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-progress-circle-root`}>
      <view className="progress-circle-preview">
        <ProgressCircle size="24" />
      </view>
    </view>
  );
}
```

### Determinate

`minValue`, `maxValue`, `value`를 모두 지정하면 정해진 진행률을 표시합니다.

```tsx
import "./styles";

import { ProgressCircle } from "@/components/ui/progress-circle";

import { useSeedClassName } from "@seed-design/lynx-react";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-progress-circle-root`}>
      <view className="progress-circle-preview">
        <ProgressCircle minValue={0} maxValue={100} value={40} />
      </view>
    </view>
  );
}
```

### Indeterminate

`value`를 생략하면 완료 시점을 알 수 없는 작업의 진행 상태를 표시합니다.

```tsx
import "./styles";

import { ProgressCircle } from "@/components/ui/progress-circle";

import { useSeedClassName } from "@seed-design/lynx-react";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-progress-circle-root`}>
      <view className="progress-circle-preview">
        <ProgressCircle />
      </view>
    </view>
  );
}
```

## 웹 버전과의 차이

Lynx 버전은 플랫폼 제약으로 인해 웹(`@seed-design/react`) 버전과 내부 구현이 다릅니다. Registry에서 제공하는 단일 `ProgressCircle` API와 공개 variant, 진행률 API는 같습니다.

|                     | 웹 (React)                                                                                 | Lynx                                                                  |
| ------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Registry API**    | 단일 `ProgressCircle` 컴포넌트                                                                  | 단일 `ProgressCircle` 컴포넌트                                              |
| **저수준 package API** | `Root`, `Track`, `Range` 조합                                                               | `Root`, `Range` 조합                                                    |
| **렌더링**             | SVG `<circle>`과 `stroke-dasharray`                                                        | CSS `clip-path` 기반 pie sector                                         |
| **애니메이션**           | CSS `@keyframes`와 `animation`                                                             | Main thread `requestAnimationFrame`과 `setStyleProperty`               |
| **Determinate 전환**  | CSS `transition`                                                                          | Main thread `requestAnimationFrame` 기반 easing 애니메이션                   |
| **Track**           | `<ProgressCircle.Track />` SVG circle                                                     | Root의 CSS `background`와 `clip-path`로 렌더링하며 별도 Track 컴포넌트 없음           |
| **접근성**             | `role="progressbar"`와 `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext` | `accessibility-role-description="progressbar"`와 `accessibility-value` |

<Callout type="warn">
  Lynx에서는 `clip-path`가 애니메이션 속성이 아니어서 매 프레임 path 문자열을 만듭니다. Indeterminate 인스턴스를 한 화면에 많이 렌더링하면 성능이 저하될 수 있습니다.
</Callout>