# Button

## Introduction

Button 컴포넌트는 사용자가 클릭하여 특정 작업을 수행할 수 있는 기본적인 UI 요소입니다. Joy UI의 Button을 기반으로 하며, Framer Motion 애니메이션 지원이 추가되었습니다. 폼 제출, 페이지 이동, 모달 열기/닫기, 데이터 처리 등 다양한 상호작용에 사용됩니다.

```tsx
<>
  {/* @ts-ignore */}
  <Button {...props} startDecorator={<Add />} />
  <IconButton {...props} aria-label="Add">
    <Add />
  </IconButton>
</>
```

| Field   | Description | Default   |
| ------- | ----------- | --------- |
| color   | —           | "primary" |
| size    | —           | "md"      |
| variant | —           | "solid"   |

## Usage

```tsx
import { Button } from '@ceed/ads';

function MyComponent() {
  return <Button onClick={() => console.log('클릭됨!')}>클릭하세요</Button>;
}
```

## Examples

### Basic Usage

가장 기본적인 버튼 사용법입니다.

```tsx
<>
  <Button {...props} />
  <Button {...props} disabled />
  <Button {...props} loading />
</>
```

### Disabled State

비활성 상태의 버튼입니다. 사용자가 클릭할 수 없으며 시각적으로도 비활성 상태임을 나타냅니다.

```tsx
<>
  <Button {...props} startDecorator={<Add />} variant="solid">
    Solid
  </Button>
  <Button {...props} startDecorator={<Add />} variant="soft">
    Soft
  </Button>
  <Button {...props} startDecorator={<Add />} variant="outlined">
    Outlined
  </Button>
  <Button {...props} startDecorator={<Add />} variant="plain">
    Plain
  </Button>
</>
```

### Loading State

로딩 중일 때 사용하는 버튼입니다. 비동기 작업 수행 중에 사용자에게 진행 상태를 알려줍니다.

```tsx
<Button
  children="Button"
  disabled={false}
  loading
  color="primary"
  size="md"
  variant="solid"
/>
```

## Customization

### Variants

버튼의 시각적 스타일을 다양하게 변경할 수 있습니다.

```tsx
<>
  <Button {...props} variant="solid">
    Solid
  </Button>
  <Button {...props} variant="soft">
    Soft
  </Button>
  <Button {...props} variant="outlined">
    Outlined
  </Button>
  <Button {...props} variant="plain">
    Plain
  </Button>
</>
```

- **solid**: 강조가 필요한 주요 액션 (기본값)
- **soft**: 부드러운 배경의 보조 액션
- **outlined**: 테두리만 있는 중요도가 낮은 액션
- **plain**: 텍스트만 있는 최소한의 스타일

### Sizes

버튼의 크기를 조절할 수 있습니다.

```tsx
<>
  <Button {...props} size="sm">
    Small
  </Button>
  <Button {...props} size="md">
    Medium
  </Button>
  <Button {...props} size="lg">
    Large
  </Button>
</>
```

- **sm**: 작은 크기 (제한된 공간에서 사용)
- **md**: 중간 크기 (기본값)
- **lg**: 큰 크기 (강조가 필요한 경우)

### Colors

다양한 색상 테마를 적용할 수 있습니다.

```tsx
<>
  <Button {...props} color="primary">
    Primary
  </Button>
  <Button {...props} color="neutral">
    Neutral
  </Button>
  <Button {...props} color="danger">
    Danger
  </Button>
  <Button {...props} color="success">
    Success
  </Button>
  <Button {...props} color="warning">
    Warning
  </Button>
</>
```

- **primary**: 주요 액션 (기본값)
- **neutral**: 중립적인 액션
- **success**: 성공/확인 액션
- **warning**: 주의가 필요한 액션
- **danger**: 위험한/삭제 액션

### Decorators

버튼에 아이콘이나 다른 요소를 추가할 수 있습니다.

```tsx
<>
  <Button {...props} startDecorator={<Add />}>
    Add to cart
  </Button>
  <Button {...props} endDecorator={<Add />} color="success">
    Go to checkout
  </Button>
</>
```

### Loading Indicator

로딩 표시기를 커스터마이징할 수 있습니다.

```tsx
<>
  <Button {...props} loading>
    Default
  </Button>
  <Button {...props} loading loadingIndicator="Loading…">
    Custom
  </Button>
</>
```

### Loading Position

로딩 표시기의 위치를 조절할 수 있습니다.

```tsx
<>
  <Button {...props} loading loadingPosition="start">
    Start
  </Button>
  <Button {...props} loading loadingPosition="end" endDecorator={<Add />}>
    End
  </Button>
</>
```

## Common Use Cases

### Form Submission

```tsx
<form onSubmit={handleSubmit}>
  <Stack spacing={2}>
    <Input placeholder="이름을 입력하세요" />
    <Input placeholder="이메일을 입력하세요" />

    <Stack direction="row" spacing={2} justifyContent="flex-end">
      <Button variant="outlined" type="button" onClick={handleCancel}>
        취소
      </Button>
      <Button type="submit" loading={isSubmitting}>
        {isSubmitting ? '저장 중...' : '저장'}
      </Button>
    </Stack>
  </Stack>
</form>
```

### Modal Actions

```tsx
<Modal open={open}>
  <ModalDialog>
    <ModalClose />
    <DialogTitle>삭제 확인</DialogTitle>
    <DialogContent>정말로 이 항목을 삭제하시겠습니까? 이 작업은 되돌릴 수 없습니다.</DialogContent>

    <DialogActions>
      <Button variant="outlined" onClick={handleClose}>
        취소
      </Button>
      <Button color="danger" onClick={handleDelete}>
        삭제
      </Button>
    </DialogActions>
  </ModalDialog>
</Modal>
```

### Action Buttons with Icons

```tsx
<Stack direction="row" spacing={2}>
  <Button startDecorator={<AddIcon />}>새로 만들기</Button>

  <Button variant="outlined" startDecorator={<DownloadIcon />} onClick={handleDownload}>
    다운로드
  </Button>

  <Button variant="soft" color="success" startDecorator={<ShareIcon />}>
    공유
  </Button>
</Stack>
```

### Async Operations

```tsx
function AsyncButton() {
  const [loading, setLoading] = useState(false);

  const handleAsyncAction = async () => {
    setLoading(true);
    try {
      await api.processData();
      // 성공 처리
    } catch (error) {
      // 에러 처리
    } finally {
      setLoading(false);
    }
  };

  return (
    <Button loading={loading} onClick={handleAsyncAction} startDecorator={<ProcessIcon />}>
      데이터 처리
    </Button>
  );
}
```

### Button Groups

```tsx
<Stack direction="row" spacing={1}>
  <Button variant="soft" size="sm">
    전체
  </Button>
  <Button variant="outlined" size="sm">
    진행중
  </Button>
  <Button variant="outlined" size="sm">
    완료
  </Button>
</Stack>
```

## Best Practices

1. **명확한 라벨**: 버튼의 기능을 명확하게 나타내는 텍스트를 사용하세요.

2. **적절한 변형 선택**:
   - 주요 액션: `solid`
   - 보조 액션: `outlined` 또는 `soft`
   - 최소한의 액션: `plain`

3. **색상 의미 일관성**:
   - 위험한 작업: `danger`
   - 성공/확인: `success`
   - 주의 필요: `warning`

4. **로딩 상태 표시**: 비동기 작업 시 사용자에게 피드백을 제공하세요.

5. **접근성**: 적절한 ARIA 라벨과 키보드 탐색을 지원하세요.

## Accessibility

- 키보드로 접근 가능 (Tab, Space, Enter)
- 스크린 리더 지원
- 적절한 색상 대비
- 비활성 상태에서 포커스 불가

Button은 사용자 인터페이스에서 가장 기본적이면서도 중요한 상호작용 요소입니다. 적절한 스타일과 상태 관리를 통해 직관적이고 접근 가능한 사용자 경험을 제공할 수 있습니다.
