# RadioTileGroup

RadioTileGroup 컴포넌트는 타일 형태의 라디오 옵션을 표시하는 컴포넌트입니다. 각 옵션이 타일 형태로 나타나며, 사용자가 선택할 수 있습니다.

> 💡 **Form 구성 시 내장 prop 사용을 권장합니다**
>
> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.

```tsx
<RadioTileGroup
  options={simpleOptions}
  useIndicator
/>
```

| Field        | Description | Default       |
| ------------ | ----------- | ------------- |
| options      | —           | simpleOptions |
| value        | —           | —             |
| defaultValue | —           | —             |
| onChange     | —           | —             |
| name         | —           | —             |
| disabled     | —           | —             |
| className    | —           | —             |
| useIndicator | —           | —             |
| textAlign    | —           | —             |
| size         | —           | —             |
| flex         | —           | —             |
| columns      | —           | —             |
| label        | —           | —             |
| helperText   | —           | —             |
| error        | —           | —             |
| required     | —           | —             |

## 기본형

RadioTileGroup의 기본 형태입니다. 필수 속성 값으로 `options`를 받으며, 각 옵션은 `value`와 `label`을 포함해야 합니다.

```tsx
<RadioTileGroup
  options={simpleOptions}
  useIndicator
/>
```

`label`과 `helperText`를 함께 사용하면 아래와 같은 모습입니다.

```tsx
<RadioTileGroup
  options={simpleOptions}
  useIndicator
  label="Select an option"
  helperText="This is helper text for the RadioTileGroup"
/>
```

## 필수 값 표시

`required` 속성을 사용하여 필수 입력 필드임을 표시할 수 있습니다.

```tsx
<RadioTileGroup
  options={simpleOptions}
  useIndicator
  label="Select an option"
  helperText="This field is required"
  required
/>
```

## 레이아웃 옵션

### Flex

`flex` 속성을 활성화하면 RadioTileGroup이 사용 가능한 공간을 균등하게 채웁니다.

```tsx
<RadioTileGroup
  options={simpleOptions}
  useIndicator
  flex
/>
```

### Columns

`columns` 속성을 사용하여 타일을 특정 열 수로 배치할 수 있습니다.

```tsx
<RadioTileGroup
  options={simpleOptions}
  useIndicator
  columns={2}
/>
```

### Flex와 Columns 함께 사용

`flex`와 `columns` 속성을 함께 사용하여 타일이 균등하게 공간을 채우면서 특정 열 수로 배치할 수 있습니다.

```tsx
<Box sx={{
  width: '100%',
  maxWidth: 700
}}>
<Typography level="body-md" sx={{
  mb: 2
}}>
Flex with Columns
</Typography>
<RadioTileGroup options={optionsWithIcons} onChange={handleChange} value={selectedValue} flex={true} columns={3} size="md" useIndicator={true} label="Flex with Columns Example" helperText="Items stretch to fill available space and are arranged in 3 columns" />
</Box>
```

### 수직 레이아웃

`columns: 1`로 설정하면 타일이 수직으로 쌓이는 레이아웃을 만들 수 있습니다.

```tsx
<Box sx={{
  width: '100%',
  maxWidth: 400
}}>
<Typography level="body-md" sx={{
  mb: 2
}}>
Vertical Layout (columns: 1)
</Typography>
<RadioTileGroup options={pricingOptions} onChange={handleChange} value={selectedValue} columns={1} size="md" useIndicator={true} label="Subscription Plans" helperText="Select your preferred subscription plan" />
</Box>
```

## 정렬 옵션

`textAlign` 속성을 사용하여 타일 내부의 콘텐츠 정렬 방식을 설정할 수 있습니다. 기본값은 `center`이며, `start`로 설정하면 텍스트가 왼쪽으로 정렬됩니다.

```tsx
<Box sx={{
  display: 'flex',
  flexDirection: 'column',
  gap: 4,
  width: '100%',
  maxWidth: 700
}}>
<Box>
  <Typography level="body-md" sx={{
    mb: 2
  }}>
  Center Alignment (default)
</Typography>
<RadioTileGroup options={simpleOptions} textAlign="center" useIndicator={true} />
</Box>
<Box>
  <Typography level="body-md" sx={{
    mb: 2
  }}>
  Start Alignment
</Typography>
<RadioTileGroup options={simpleOptions} textAlign="start" useIndicator={true} />
</Box>
</Box>
```

## Size

RadioTileGroup은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`. 기본값은 `sm`입니다.

```tsx
<Box sx={{
  display: 'flex',
  flexDirection: 'column',
  gap: 4,
  width: '100%',
  maxWidth: 700
}}>
<Box>
  <Typography level="body-md" sx={{
    mb: 2
  }}>
  Size: sm (default)
</Typography>
<RadioTileGroup options={simpleOptions} size="sm" useIndicator={true} />
</Box>
<Box>
  <Typography level="body-md" sx={{
    mb: 2
  }}>
  Size: md
</Typography>
<RadioTileGroup options={simpleOptions} size="md" useIndicator={true} />
</Box>
<Box>
  <Typography level="body-md" sx={{
    mb: 2
  }}>
  Size: lg
</Typography>
<RadioTileGroup options={simpleOptions} size="lg" useIndicator={true} />
</Box>
</Box>
```

## 아이콘 사용

각 옵션에 `startDecorator` 속성을 사용하여 아이콘을 추가할 수 있습니다.

```tsx
<RadioTileGroup
  options={[{
  value: 'home',
  label: 'Home',
  startDecorator: <HomeIcon fontSize="large" />
}, {
  value: 'office',
  label: 'Office',
  startDecorator: <BusinessIcon fontSize="large" />
}, {
  value: 'shipping',
  label: 'Shipping',
  startDecorator: <LocalShippingIcon fontSize="large" />
}]}
  useIndicator
/>
```

## 상태 관리

### Controlled Component

RadioTileGroup은 상태 관리를 위한 제어 컴포넌트(Controlled Component)로 사용할 수 있습니다.

```tsx
<Box sx={{
  width: '100%',
  maxWidth: 500
}}>
<Typography level="body-md" sx={{
  mb: 1
}}>
Selected value: {selectedValue}
</Typography>
<RadioTileGroup options={simpleOptions} value={selectedValue} onChange={handleChange} />
</Box>
```

### Uncontrolled Component

또한 비제어 컴포넌트(Uncontrolled Component)로도 사용 가능합니다.

```tsx
<Box sx={{
  display: 'flex',
  flexDirection: 'column',
  gap: 4
}}>
<Box sx={{
  width: '100%',
  maxWidth: 500
}}>
<Typography level="body-md" sx={{
  mb: 2
}}>
Uncontrolled Example (with Indicator)
</Typography>
<RadioTileGroup options={simpleOptions} defaultValue="option2" useIndicator={true} onChange={event => console.log(`Selected value: ${event.target.value}`)} />
</Box>
<Box sx={{
  width: '100%',
  maxWidth: 500
}}>
<Typography level="body-md" sx={{
  mb: 2
}}>
Uncontrolled Example (without Indicator)
</Typography>
<RadioTileGroup options={simpleOptions} defaultValue="option3" useIndicator={false} onChange={event => console.log(`Selected value: ${event.target.value}`)} />
</Box>
</Box>
```

## 비활성화 상태

### 전체 비활성화

`disabled` 속성을 사용하여 모든 옵션을 비활성화할 수 있습니다.

```tsx
<RadioTileGroup
  options={simpleOptions}
  disabled
/>
```

### 개별 옵션 비활성화

각 옵션별로 `disabled` 속성을 설정하여 특정 옵션만 비활성화할 수 있습니다.

```tsx
<RadioTileGroup
  options={[{
  value: 'option1',
  label: 'Option 1'
}, {
  value: 'option2',
  label: 'Option 2',
  disabled: true
}, {
  value: 'option3',
  label: 'Option 3'
}]}
/>
```

## 상태 표시

### 오류 상태

`error` 속성을 사용하여 오류 상태를 표시할 수 있습니다.

```tsx
<RadioTileGroup
  options={simpleOptions}
  useIndicator
  label="Select an option"
  helperText="Please select a valid option"
  error
/>
```

### 필수 값 검증 예제

`required` 속성과 함께 오류 상태를 활용하여 필수 값 검증을 할 수 있습니다. 아래는 폼 제출 시 유효성 검사를 포함한 예제입니다.

```tsx
<Stack spacing={2} sx={{
  width: '100%',
  maxWidth: 500
}}>
<RadioTileGroup options={simpleOptions} value={selectedValue} onChange={handleChange} label="Choose your preferred option" helperText={error ? 'Please select an option' : 'This selection is required'} error={error} useIndicator={true} required={true} />
<Box sx={{
  display: 'flex',
  justifyContent: 'flex-end'
}}>
<Button onClick={handleSubmit}>Submit</Button>
</Box>
</Stack>
```

## 활용 사례

### 배송 방법 선택

RadioTileGroup은 배송 방법을 시각적으로 선택할 수 있는 인터페이스로 활용할 수 있습니다. 각 타일에 아이콘과 함께 배송 방법 정보를 표시하여 사용자가 직관적으로 선택할 수 있도록 합니다.

```tsx
<Box sx={{
  width: '100%',
  maxWidth: 700
}}>
<RadioTileGroup label="배송 방법 선택" helperText="배송 방법에 따라 배송비가 달라질 수 있습니다." options={[{
  value: 'standard',
  label: '일반 배송',
  startDecorator: <HomeIcon />
}, {
  value: 'express',
  label: '빠른 배송',
  startDecorator: <LocalShippingIcon />
}, {
  value: 'business',
  label: '기업 배송',
  startDecorator: <BusinessIcon />
}]} onChange={handleChange} value={selectedValue} size="md" useIndicator={true} />
</Box>
```

### 설문조사

설문조사나 선호도 조사에서 다양한 선택지를 제공하는 데 활용할 수 있습니다. 각 타일에 선택지를 시각적으로 표현하여 사용자가 직관적으로 응답할 수 있도록 합니다.

```tsx
<Box sx={{
  width: '100%',
  maxWidth: 700
}}>
<RadioTileGroup label="선호하는 운동 유형을 선택해주세요" options={[{
  value: 'cardio',
  label: '유산소 운동',
  startDecorator: <DirectionsRunIcon />
}, {
  value: 'strength',
  label: '근력 운동',
  startDecorator: <FitnessCenterIcon />
}, {
  value: 'flexibility',
  label: '유연성 운동',
  startDecorator: <SelfImprovementIcon />
}, {
  value: 'balance',
  label: '균형 운동',
  startDecorator: <BalanceIcon />
}]} onChange={handleChange} value={selectedValue} columns={2} size="md" />
</Box>
```

### 폼 검증과 함께 사용

폼 검증 기능과 함께 사용하여 사용자가 필수 항목을 선택했는지 확인할 수 있습니다.

```tsx
<Stack spacing={2} sx={{
  width: '100%',
  maxWidth: 500
}}>
<RadioTileGroup options={simpleOptions} value={selectedValue} onChange={handleChange} label="Choose your preferred option" helperText={error ? 'Please select an option' : 'This selection is required'} error={error} useIndicator={true} required={true} />
<Box sx={{
  display: 'flex',
  justifyContent: 'flex-end'
}}>
<Button onClick={handleSubmit}>Submit</Button>
</Box>
</Stack>
```
