# ButtonGroup

## Introduction

ButtonGroup 컴포넌트는 관련된 버튼들을 그룹화하여 하나의 통합된 인터페이스로 표시합니다. 버튼들을 논리적으로 묶어서 시각적 일관성을 제공하고, 공간을 효율적으로 사용할 수 있게 해줍니다. 툴바, 액션 버튼 세트, 토글 그룹 등에 주로 사용됩니다.

```tsx
<ButtonGroup {...args}>
  <Button>첫번째</Button>
  <Button>두번째</Button>
  <Button>세번째</Button>
</ButtonGroup>
```

| Field       | Description | Default      |
| ----------- | ----------- | ------------ |
| color       | 버튼 그룹 색상    | "primary"    |
| variant     | 버튼 스타일 변형   | "solid"      |
| size        | 버튼 크기       | "md"         |
| orientation | 방향          | "horizontal" |
| disabled    | 비활성화 상태     | false        |

## Usage

```tsx
import { ButtonGroup, Button } from '@ceed/cds';

function MyComponent() {
  return (
    <ButtonGroup>
      <Button>첫번째</Button>
      <Button>두번째</Button>
      <Button>세번째</Button>
    </ButtonGroup>
  );
}
```

## Examples

### Basic Usage

기본적인 ButtonGroup 사용법입니다.

```tsx
<div style={{
  display: 'flex',
  gap: '2rem',
  flexDirection: 'column'
}}>
<ButtonGroup>
  <Button>첫번째</Button>
  <Button>두번째</Button>
  <Button>세번째</Button>
</ButtonGroup>
</div>
```

### Colors

다양한 색상을 적용할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexDirection: 'column'
}}>
<ButtonGroup color="primary">
  <Button>Primary</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup color="neutral">
  <Button>Neutral</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup color="danger">
  <Button>Danger</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup color="success">
  <Button>Success</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup color="warning">
  <Button>Warning</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>
</div>
```

### Variants

다양한 스타일 변형을 제공합니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexDirection: 'column'
}}>
<ButtonGroup variant="solid">
  <Button>Solid</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup variant="soft">
  <Button>Soft</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup variant="outlined">
  <Button>Outlined</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup variant="plain">
  <Button>Plain</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>
</div>
```

### Sizes

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

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexDirection: 'column',
  alignItems: 'flex-start'
}}>
<ButtonGroup size="sm">
  <Button>Small</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup size="md">
  <Button>Medium</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>

<ButtonGroup size="lg">
  <Button>Large</Button>
  <Button>Button</Button>
  <Button>Group</Button>
</ButtonGroup>
</div>
```

### Orientations

수평(horizontal) 또는 수직(vertical) 방향으로 배치할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '2rem',
  alignItems: 'flex-start'
}}>
<div>
  <h4>Horizontal</h4>
  <ButtonGroup orientation="horizontal">
    <Button>첫번째</Button>
    <Button>두번째</Button>
    <Button>세번째</Button>
  </ButtonGroup>
</div>

<div>
  <h4>Vertical</h4>
  <ButtonGroup orientation="vertical">
    <Button>첫번째</Button>
    <Button>두번째</Button>
    <Button>세번째</Button>
  </ButtonGroup>
</div>
</div>
```

### With Icons

아이콘과 함께 사용할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '2rem',
  flexDirection: 'column'
}}>
<ButtonGroup>
  <Button startDecorator={<Add />}>추가</Button>
  <Button startDecorator={<Edit />}>편집</Button>
  <Button startDecorator={<Delete />}>삭제</Button>
</ButtonGroup>

<ButtonGroup variant="outlined">
  <Button startDecorator={<Save />} />
  <Button startDecorator={<Share />} />
  <Button startDecorator={<Edit />} />
</ButtonGroup>
</div>
```

### Action Groups

실제 사용 사례별 액션 그룹들입니다.

```tsx
<div style={{
  display: 'flex',
  gap: '2rem',
  flexDirection: 'column'
}}>
<div>
  <h4>File Actions</h4>
  <ButtonGroup variant="outlined">
    <Button onClick={() => alert('Save')}>저장</Button>
    <Button onClick={() => alert('Save As')}>다른 이름으로 저장</Button>
    <Button onClick={() => alert('Export')}>내보내기</Button>
  </ButtonGroup>
</div>

<div>
  <h4>Text Formatting</h4>
  <ButtonGroup size="sm" variant="soft">
    <Button>B</Button>
    <Button>I</Button>
    <Button>U</Button>
    <Button>S</Button>
  </ButtonGroup>
</div>

<div>
  <h4>View Options</h4>
  <ButtonGroup color="neutral" variant="outlined">
    <Button>목록</Button>
    <Button>격자</Button>
    <Button>타일</Button>
  </ButtonGroup>
</div>
</div>
```

### States

다양한 상태를 표현할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '2rem',
  flexDirection: 'column'
}}>
<div>
  <h4>Normal</h4>
  <ButtonGroup>
    <Button>첫번째</Button>
    <Button>두번째</Button>
    <Button>세번째</Button>
  </ButtonGroup>
</div>

<div>
  <h4>Disabled</h4>
  <ButtonGroup disabled>
    <Button>첫번째</Button>
    <Button>두번째</Button>
    <Button>세번째</Button>
  </ButtonGroup>
</div>

<div>
  <h4>Mixed States</h4>
  <ButtonGroup>
    <Button>활성</Button>
    <Button disabled>비활성</Button>
    <Button>활성</Button>
  </ButtonGroup>
</div>
</div>
```

### Toggle Group

선택 상태를 토글할 수 있는 버튼 그룹입니다.

```tsx
<div>
  <h4>Toggle Group (Alignment)</h4>
  <ButtonGroup variant="outlined">
    <Button variant={selected === 'left' ? 'solid' : 'outlined'} onClick={() => setSelected('left')}>
      왼쪽 정렬
    </Button>
    <Button variant={selected === 'center' ? 'solid' : 'outlined'} onClick={() => setSelected('center')}>
      가운데 정렬
    </Button>
    <Button variant={selected === 'right' ? 'solid' : 'outlined'} onClick={() => setSelected('right')}>
      오른쪽 정렬
    </Button>
  </ButtonGroup>
  <p>선택된 정렬: {selected}</p>
</div>
```

## Common Use Cases

### Toolbar Actions

```tsx
<ButtonGroup variant="outlined">
  <Button startDecorator={<SaveIcon />}>저장</Button>
  <Button startDecorator={<UndoIcon />}>실행 취소</Button>
  <Button startDecorator={<RedoIcon />}>다시 실행</Button>
</ButtonGroup>
```

### Text Formatting

```tsx
<ButtonGroup size="sm" variant="soft">
  <Button onClick={() => format('bold')}>B</Button>
  <Button onClick={() => format('italic')}>I</Button>
  <Button onClick={() => format('underline')}>U</Button>
</ButtonGroup>
```

### View Controls

```tsx
<ButtonGroup color="neutral">
  <Button onClick={() => setView('list')}>목록</Button>
  <Button onClick={() => setView('grid')}>격자</Button>
  <Button onClick={() => setView('card')}>카드</Button>
</ButtonGroup>
```

### Pagination

```tsx
<ButtonGroup variant="outlined">
  <Button disabled={page === 1} onClick={() => setPage(page - 1)}>
    이전
  </Button>
  <Button onClick={() => setPage(page + 1)}>다음</Button>
</ButtonGroup>
```

## Best Practices

1. **관련성**: 논리적으로 관련된 버튼들만 그룹화하세요.

2. **일관성**: 그룹 내의 모든 버튼은 동일한 variant, size, color를 사용하는 것이 좋습니다.

3. **적절한 개수**: 너무 많은 버튼을 한 그룹에 포함하지 마세요. 일반적으로 2-5개가 적당합니다.

4. **명확한 레이블**: 각 버튼의 기능을 명확하게 알 수 있는 레이블을 사용하세요.

5. **접근성**: 키보드 탐색이 가능하도록 하고, 스크린 리더를 위한 적절한 레이블을 제공하세요.

6. **상태 관리**: 토글 그룹으로 사용할 때는 현재 선택된 상태를 시각적으로 명확히 표시하세요.

7. **반응형 디자인**: 작은 화면에서는 vertical orientation을 고려하거나 적절한 줄바꿈을 제공하세요.
