@ceed/ads 1.25.1-next.3 → 1.27.0

package/dist/components/inputs/RadioList.md

@@ -0,0 +1,241 @@
+# RadioList
+
+## Introduction
+
+RadioList is a convenience component that renders a group of radio buttons from a data array. It wraps RadioGroup and Radio internally, providing a simpler API for the common pattern of rendering a list of options. Pass an array of `{ label, value }` items and the component handles the rest.
+
+```tsx
+<RadioList
+  items={defaultItems}
+  defaultValue="option1"
+/>
+```
+
+| Field       | Description | Default |
+| ----------- | ----------- | ------- |
+| size        | —           | —       |
+| color       | —           | —       |
+| orientation | —           | —       |
+| disabled    | —           | —       |
+
+## Usage
+
+```tsx
+import { RadioList } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <RadioList
+      items={[
+        { label: 'Small', value: 'sm' },
+        { label: 'Medium', value: 'md' },
+        { label: 'Large', value: 'lg' },
+      ]}
+      defaultValue="md"
+    />
+  );
+}
+```
+
+## Basic List
+
+A simple radio list with three options and a default selection.
+
+```tsx
+<RadioList items={[{
+  label: 'Small',
+  value: 'sm'
+}, {
+  label: 'Medium',
+  value: 'md'
+}, {
+  label: 'Large',
+  value: 'lg'
+}]} defaultValue="md" />
+```
+
+## Controlled
+
+Use `value` and `onChange` for controlled state management.
+
+```tsx
+<Stack gap={2}>
+  <Typography level="body-sm">Selected: {value}</Typography>
+  <RadioList items={defaultItems} value={value} onChange={e => setValue((e.target as HTMLInputElement).value)} />
+</Stack>
+```
+
+```tsx
+function ControlledExample() {
+  const [value, setValue] = React.useState('option1');
+  return (
+    <RadioList
+      items={items}
+      value={value}
+      onChange={(e) => setValue((e.target as HTMLInputElement).value)}
+    />
+  );
+}
+```
+
+## With Default Value
+
+Use `defaultValue` for uncontrolled usage with an initial selection.
+
+```tsx
+<RadioList items={defaultItems} defaultValue="option2" />
+```
+
+## Disabled
+
+Set `disabled` to prevent all radio buttons from being interacted with.
+
+```tsx
+<RadioList items={defaultItems} defaultValue="option1" disabled />
+```
+
+## Horizontal Layout
+
+Set `orientation="horizontal"` to display options in a row.
+
+```tsx
+<RadioList items={defaultItems} defaultValue="option1" orientation="horizontal" />
+```
+
+```tsx
+<RadioList
+  items={items}
+  defaultValue="option1"
+  orientation="horizontal"
+/>
+```
+
+## Sizes
+
+RadioList supports `sm`, `md` (default), and `lg` sizes. The size is applied to all radio buttons in the group.
+
+```tsx
+<Stack gap={3}>
+  <Box>
+    <Typography level="body-sm" sx={{
+      mb: 1
+    }}>Small</Typography>
+    <RadioList items={defaultItems} defaultValue="option1" size="sm" />
+  </Box>
+  <Box>
+    <Typography level="body-sm" sx={{
+      mb: 1
+    }}>Medium</Typography>
+    <RadioList items={defaultItems} defaultValue="option1" size="md" />
+  </Box>
+  <Box>
+    <Typography level="body-sm" sx={{
+      mb: 1
+    }}>Large</Typography>
+    <RadioList items={defaultItems} defaultValue="option1" size="lg" />
+  </Box>
+</Stack>
+```
+
+## Colors
+
+Five semantic colors are available via the `color` prop.
+
+```tsx
+<Stack gap={3}>
+  <RadioList items={defaultItems} defaultValue="option1" color="primary" />
+  <RadioList items={defaultItems} defaultValue="option1" color="neutral" />
+  <RadioList items={defaultItems} defaultValue="option1" color="danger" />
+  <RadioList items={defaultItems} defaultValue="option1" color="success" />
+  <RadioList items={defaultItems} defaultValue="option1" color="warning" />
+</Stack>
+```
+
+## Common Use Cases
+
+### Settings Selection
+
+```tsx
+function LanguageSetting() {
+  const [language, setLanguage] = React.useState('en');
+
+  return (
+    <FormControl>
+      <FormLabel>Language</FormLabel>
+      <RadioList
+        items={[
+          { label: 'English', value: 'en' },
+          { label: '한국어', value: 'ko' },
+          { label: '日本語', value: 'ja' },
+        ]}
+        value={language}
+        onChange={(e) => setLanguage((e.target as HTMLInputElement).value)}
+      />
+    </FormControl>
+  );
+}
+```
+
+### Survey Options
+
+```tsx
+function SatisfactionSurvey() {
+  return (
+    <FormControl>
+      <FormLabel>How satisfied are you?</FormLabel>
+      <RadioList
+        orientation="horizontal"
+        items={[
+          { label: 'Very Unsatisfied', value: '1' },
+          { label: 'Unsatisfied', value: '2' },
+          { label: 'Neutral', value: '3' },
+          { label: 'Satisfied', value: '4' },
+          { label: 'Very Satisfied', value: '5' },
+        ]}
+      />
+    </FormControl>
+  );
+}
+```
+
+### Dynamic Options from API
+
+```tsx
+function RoleSelector({ roles }: { roles: { id: string; name: string }[] }) {
+  return (
+    <RadioList
+      items={roles.map((role) => ({
+        label: role.name,
+        value: role.id,
+      }))}
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Use for mutually exclusive choices**: RadioList is for selecting exactly one option from a set. For multiple selections, use Checkbox or FilterableCheckboxGroup.
+
+```tsx
+// ✅ Mutually exclusive — only one role allowed
+<RadioList items={roles} />
+
+// ❌ Multiple selections needed — use Checkbox instead
+<RadioList items={permissions} />
+```
+
+2. **Provide a default value**: Pre-select the most common or recommended option to reduce user effort.
+
+3. **Keep labels concise**: Radio button labels should be short and scannable. Use descriptions elsewhere if more context is needed.
+
+4. **Limit visible options**: For more than 7 options, consider using a Select dropdown instead to save space.
+
+5. **Use horizontal layout sparingly**: Horizontal orientation works well for 2–4 short options. For longer lists, vertical is more readable.
+
+## Accessibility
+
+- RadioList renders a `<RadioGroup>` with `role="radiogroup"`, and each option is a `<Radio>` with `role="radio"`.
+- Keyboard navigation: Arrow keys move between options, Space selects the focused option.
+- Wrap in a FormControl with FormLabel to provide an accessible group label.
+- The `disabled` prop sets `aria-disabled` on all radio buttons in the group.

package/dist/components/inputs/RadioTileGroup.md

@@ -1,6 +1,15 @@
 # RadioTileGroup
 
-RadioTileGroup 컴포넌트는 타일 형태의 라디오 옵션을 표시하는 컴포넌트입니다. 각 옵션이 타일 형태로 나타나며, 사용자가 선택할 수 있습니다.
+## Introduction
+
+RadioTileGroup is a selection component that displays radio options as visually distinct tiles. Unlike a standard radio button list, each option occupies a tile card, making selections more prominent and scannable. This is especially useful for choices that benefit from visual emphasis, such as plan selection, category picking, or preference surveys.
+
+The component supports flexible layouts (horizontal, grid, vertical), icons via `startDecorator`, three sizes, and built-in form integration with `label`, `helperText`, `error`, and `required` props. It works in both controlled and uncontrolled modes.
+
+> **Form 구성 시 내장 prop 사용을 권장합니다**
+>
+> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
+> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.
 
 ```tsx
 <RadioTileGroup
@@ -28,18 +37,36 @@ RadioTileGroup 컴포넌트는 타일 형태의 라디오 옵션을 표시하는
 | error        | —           | —             |
 | required     | —           | —             |
 
-## 기본형
-
-RadioTileGroup의 기본 형태입니다. 필수 속성 값으로 `options`를 받으며, 각 옵션은 `value`와 `label`을 포함해야 합니다.
+## Usage
 
 ```tsx
-<RadioTileGroup
-  options={simpleOptions}
-  useIndicator
-/>
+import { RadioTileGroup } from '@ceed/ads';
+
+function MyComponent() {
+  const [value, setValue] = useState('');
+
+  const options = [
+    { value: 'option1', label: 'Option 1' },
+    { value: 'option2', label: 'Option 2' },
+    { value: 'option3', label: 'Option 3' },
+  ];
+
+  return (
+    <RadioTileGroup
+      label="Choose an option"
+      helperText="Select one of the options below"
+      options={options}
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      useIndicator
+    />
+  );
+}
 ```
 
-`label`과 `helperText`를 함께 사용하면 아래와 같은 모습입니다.
+## Label and Helper Text
+
+Use the `label` and `helperText` props to add descriptive text above and below the tile group. The `required` prop appends a required indicator to the label.
 
 ```tsx
 <RadioTileGroup
@@ -50,10 +77,6 @@ RadioTileGroup의 기본 형태입니다. 필수 속성 값으로 `options`를
 />
 ```
 
-## 필수 값 표시
-
-`required` 속성을 사용하여 필수 입력 필드임을 표시할 수 있습니다.
-
 ```tsx
 <RadioTileGroup
   options={simpleOptions}
@@ -64,11 +87,11 @@ RadioTileGroup의 기본 형태입니다. 필수 속성 값으로 `options`를
 />
 ```
 
-## 레이아웃 옵션
+## Layout Options
 
 ### Flex
 
-`flex` 속성을 활성화하면 RadioTileGroup이 사용 가능한 공간을 균등하게 채웁니다.
+Enable the `flex` prop to make tiles stretch and fill all available horizontal space equally.
 
 ```tsx
 <RadioTileGroup
@@ -80,7 +103,7 @@ RadioTileGroup의 기본 형태입니다. 필수 속성 값으로 `options`를
 
 ### Columns
 
-`columns` 속성을 사용하여 타일을 특정 열 수로 배치할 수 있습니다.
+Use the `columns` prop to arrange tiles in a specific number of columns using a grid layout.
 
 ```tsx
 <RadioTileGroup
@@ -90,9 +113,9 @@ RadioTileGroup의 기본 형태입니다. 필수 속성 값으로 `options`를
 />
 ```
 
-### Flex와 Columns 함께 사용
+### Flex with Columns
 
-`flex`와 `columns` 속성을 함께 사용하여 타일이 균등하게 공간을 채우면서 특정 열 수로 배치할 수 있습니다.
+Combine `flex` and `columns` to create a grid where each tile stretches to fill its column width evenly.
 
 ```tsx
 <Box sx={{
@@ -108,9 +131,9 @@ Flex with Columns
 </Box>
 ```
 
-### 수직 레이아웃
+### Vertical Layout
 
-`columns: 1`로 설정하면 타일이 수직으로 쌓이는 레이아웃을 만들 수 있습니다.
+Set `columns={1}` to stack tiles vertically. This layout is well-suited for list-style selections like pricing plans or step-by-step options.
 
 ```tsx
 <Box sx={{
@@ -126,9 +149,9 @@ Vertical Layout (columns: 1)
 </Box>
 ```
 
-## 정렬 옵션
+## Text Alignment
 
-`textAlign` 속성을 사용하여 타일 내부의 콘텐츠 정렬 방식을 설정할 수 있습니다. 기본값은 `center`이며, `start`로 설정하면 텍스트가 왼쪽으로 정렬됩니다.
+The `textAlign` prop controls the alignment of content inside each tile. The default is `center`. Set it to `start` for left-aligned content.
 
 ```tsx
 <Box sx={{
@@ -157,9 +180,9 @@ Vertical Layout (columns: 1)
 </Box>
 ```
 
-## Size
+## Sizes
 
-RadioTileGroup은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`. 기본값은 `sm`입니다.
+RadioTileGroup supports three sizes: `sm` (default), `md`, and `lg`. Choose the size that best fits the density of your layout.
 
 ```tsx
 <Box sx={{
@@ -196,9 +219,9 @@ RadioTileGroup은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`. 기본
 </Box>
 ```
 
-## 아이콘 사용
+## Icons
 
-각 옵션에 `startDecorator` 속성을 사용하여 아이콘을 추가할 수 있습니다.
+Add icons to tiles using the `startDecorator` property on each option. Icons help users visually distinguish between choices at a glance.
 
 ```tsx
 <RadioTileGroup
@@ -219,11 +242,11 @@ RadioTileGroup은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`. 기본
 />
 ```
 
-## 상태 관리
+## State Management
 
-### Controlled Component
+### Controlled
 
-RadioTileGroup은 상태 관리를 위한 제어 컴포넌트(Controlled Component)로 사용할 수 있습니다.
+Pass `value` and `onChange` to fully control the selected state from the parent component. This is recommended when the selection participates in form state or triggers side effects.
 
 ```tsx
 <Box sx={{
@@ -239,9 +262,9 @@ Selected value: {selectedValue}
 </Box>
 ```
 
-### Uncontrolled Component
+### Uncontrolled
 
-또한 비제어 컴포넌트(Uncontrolled Component)로도 사용 가능합니다.
+Use `defaultValue` to set an initial selection without managing state externally. The component tracks its own selection internally.
 
 ```tsx
 <Box sx={{
@@ -274,11 +297,11 @@ Uncontrolled Example (without Indicator)
 </Box>
 ```
 
-## 비활성화 상태
+## Disabled State
 
-### 전체 비활성화
+### Fully Disabled
 
-`disabled` 속성을 사용하여 모든 옵션을 비활성화할 수 있습니다.
+Set the `disabled` prop on the group to disable all tiles.
 
 ```tsx
 <RadioTileGroup
@@ -287,9 +310,9 @@ Uncontrolled Example (without Indicator)
 />
 ```
 
-### 개별 옵션 비활성화
+### Individual Disabled
 
-각 옵션별로 `disabled` 속성을 설정하여 특정 옵션만 비활성화할 수 있습니다.
+Set `disabled: true` on specific option objects to disable only those tiles while keeping the rest interactive.
 
 ```tsx
 <RadioTileGroup
@@ -307,11 +330,9 @@ Uncontrolled Example (without Indicator)
 />
 ```
 
-## 상태 표시
-
-### 오류 상태
+## Error State
 
-`error` 속성을 사용하여 오류 상태를 표시할 수 있습니다.
+Use the `error` prop to indicate validation errors. Pair it with `helperText` to communicate the issue to the user.
 
 ```tsx
 <RadioTileGroup
@@ -323,9 +344,9 @@ Uncontrolled Example (without Indicator)
 />
 ```
 
-### 필수 값 검증 예제
+### Form Validation Example
 
-`required` 속성과 함께 오류 상태를 활용하여 필수 값 검증을 할 수 있습니다. 아래는 폼 제출 시 유효성 검사를 포함한 예제입니다.
+Combine `required`, `error`, and `helperText` to build a complete form validation flow. The example below validates that the user has made a selection before submitting.
 
 ```tsx
 <Stack spacing={2} sx={{
@@ -342,11 +363,32 @@ Uncontrolled Example (without Indicator)
 </Stack>
 ```
 
-## 활용 사례
+## Common Use Cases
+
+### Shipping Method Selection
 
-### 배송 방법 선택
+Display delivery options with icons so users can choose intuitively.
 
-RadioTileGroup은 배송 방법을 시각적으로 선택할 수 있는 인터페이스로 활용할 수 있습니다. 각 타일에 아이콘과 함께 배송 방법 정보를 표시하여 사용자가 직관적으로 선택할 수 있도록 합니다.
+```tsx
+import { RadioTileGroup } from '@ceed/ads';
+import HomeIcon from '@mui/icons-material/Home';
+import LocalShippingIcon from '@mui/icons-material/LocalShipping';
+import BusinessIcon from '@mui/icons-material/Business';
+
+<RadioTileGroup
+  label="Shipping Method"
+  helperText="Delivery fees may vary by method."
+  options={[
+    { value: 'standard', label: 'Standard', startDecorator: <HomeIcon /> },
+    { value: 'express', label: 'Express', startDecorator: <LocalShippingIcon /> },
+    { value: 'business', label: 'Business', startDecorator: <BusinessIcon /> },
+  ]}
+  value={selected}
+  onChange={(e) => setSelected(e.target.value)}
+  size="md"
+  useIndicator
+/>
+```
 
 ```tsx
 <Box sx={{
@@ -369,9 +411,25 @@ RadioTileGroup은 배송 방법을 시각적으로 선택할 수 있는 인터
 </Box>
 ```
 
-### 설문조사
+### Survey / Preference Selection
 
-설문조사나 선호도 조사에서 다양한 선택지를 제공하는 데 활용할 수 있습니다. 각 타일에 선택지를 시각적으로 표현하여 사용자가 직관적으로 응답할 수 있도록 합니다.
+Present survey options with icons in a multi-column grid for a clear, scannable layout.
+
+```tsx
+<RadioTileGroup
+  label="What type of exercise do you prefer?"
+  options={[
+    { value: 'cardio', label: 'Cardio', startDecorator: <DirectionsRunIcon /> },
+    { value: 'strength', label: 'Strength', startDecorator: <FitnessCenterIcon /> },
+    { value: 'flexibility', label: 'Flexibility', startDecorator: <SelfImprovementIcon /> },
+    { value: 'balance', label: 'Balance', startDecorator: <BalanceIcon /> },
+  ]}
+  columns={2}
+  size="md"
+  value={selected}
+  onChange={(e) => setSelected(e.target.value)}
+/>
+```
 
 ```tsx
 <Box sx={{
@@ -398,21 +456,52 @@ RadioTileGroup은 배송 방법을 시각적으로 선택할 수 있는 인터
 </Box>
 ```
 
-### 폼 검증과 함께 사용
+### Pricing Plan Picker
 
-폼 검증 기능과 함께 사용하여 사용자가 필수 항목을 선택했는지 확인할 수 있습니다.
+Use a vertical layout with `columns={1}` for plan or tier selection.
 
 ```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
+  label="Subscription Plan"
+  helperText="Select your preferred plan"
+  options={[
+    { value: 'basic', label: 'Basic Plan', startDecorator: <AttachMoneyIcon /> },
+    { value: 'pro', label: 'Pro Plan', startDecorator: <AttachMoneyIcon /> },
+    { value: 'premium', label: 'Premium Plan', startDecorator: <StarIcon /> },
+  ]}
+  columns={1}
+  size="md"
+  useIndicator
+  value={selected}
+  onChange={(e) => setSelected(e.target.value)}
+/>
+```
+
+## Best Practices
+
+1. **Use built-in form props instead of external labels.** The component's `label`, `helperText`, `required`, and `error` props ensure consistent layout and accessibility. Avoid wrapping with separate Typography elements.
+
+```tsx
+// ✅ Recommended
+<RadioTileGroup label="Select option" helperText="Required field" required />
+
+// ❌ Avoid
+<Typography>Select option</Typography>
+<RadioTileGroup options={options} />
+<Typography color="danger">Required field</Typography>
 ```
+
+2. **Choose the right layout for the number of options.** Use the default horizontal flow for 2-4 options. Use `columns` for 5+ options. Use `columns={1}` when each option has long labels or descriptions.
+
+3. **Prefer controlled mode in forms.** When RadioTileGroup is part of a form with validation or submission logic, use `value` and `onChange` for predictable state management.
+
+4. **Add icons only when they aid comprehension.** Icons via `startDecorator` are helpful for visually distinct categories (e.g., shipping methods). Avoid decorating every option if icons do not add meaning.
+
+5. **Always provide an error message.** When `error` is true, update `helperText` to explain the validation issue so users know how to fix it.
+
+## Accessibility
+
+- RadioTileGroup renders a `<fieldset>` with a `<legend>` derived from the `label` prop, providing proper grouping for screen readers.
+- Each tile is backed by a native `<input type="radio">`, ensuring full keyboard navigation (arrow keys to move between options, Space/Enter to select).
+- The `disabled` prop correctly applies `aria-disabled` semantics to prevent interaction while keeping elements discoverable by assistive technologies.
+- When `error` is set, pair it with descriptive `helperText` so that screen readers can announce the validation message via `aria-describedby`.