@ceed/ads 1.29.0 → 1.30.0-next.1

package/dist/components/inputs/ButtonGroup.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-ButtonGroup is a layout component that visually and semantically groups related buttons into a single cohesive unit. It automatically handles border merging, spacing, and consistent styling across all child buttons, making it ideal for toolbars, action sets, and segmented controls.
-
-By applying shared props like `color`, `variant`, `size`, and `orientation` at the group level, you ensure visual consistency without having to repeat props on every individual button. ButtonGroup is built on top of Joy UI's ButtonGroup and inherits all of its capabilities.
+ButtonGroup 컴포넌트는 관련된 버튼들을 그룹화하여 하나의 통합된 인터페이스로 표시합니다. 버튼들을 논리적으로 묶어서 시각적 일관성을 제공하고, 공간을 효율적으로 사용할 수 있게 해줍니다. 툴바, 액션 버튼 세트, 토글 그룹 등에 주로 사용됩니다.
 
 ```tsx
 <ButtonGroup {...args}>
@@ -30,17 +28,37 @@ import { ButtonGroup, Button } from '@ceed/ads';
 function MyComponent() {
   return (
     <ButtonGroup>
-      <Button>First</Button>
-      <Button>Second</Button>
-      <Button>Third</Button>
+      <Button>첫번째</Button>
+      <Button>두번째</Button>
+      <Button>세번째</Button>
     </ButtonGroup>
   );
 }
 ```
 
-## Colors
+## Examples
+
+### Basic Usage
 
-Apply a unified color theme to all buttons in the group using the `color` prop. Available colors are `primary`, `neutral`, `danger`, `success`, and `warning`.
+기본적인 ButtonGroup 사용법입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem',
+  flexDirection: 'column'
+}}>
+<ButtonGroup>
+  <Button>첫번째</Button>
+  <Button>두번째</Button>
+  <Button>세번째</Button>
+</ButtonGroup>
+</div>
+```
+
+### Colors
+
+다양한 색상을 적용할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -80,9 +98,9 @@ Apply a unified color theme to all buttons in the group using the `color` prop.
 </div>
 ```
 
-## Variants
+### Variants
 
-ButtonGroup supports four visual variants: `solid`, `soft`, `outlined`, and `plain`. The variant prop propagates to all child buttons, ensuring a consistent look.
+다양한 스타일 변형을 제공합니다.
 
 ```tsx
 <div style={{
@@ -116,9 +134,9 @@ ButtonGroup supports four visual variants: `solid`, `soft`, `outlined`, and `pla
 </div>
 ```
 
-## Sizes
+### Sizes
 
-Control the size of all buttons in the group with the `size` prop. Available sizes are `sm`, `md` (default), and `lg`.
+크기를 조절할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -147,9 +165,9 @@ Control the size of all buttons in the group with the `size` prop. Available siz
 </div>
 ```
 
-## Orientations
+### Orientations
 
-Buttons can be arranged horizontally (default) or vertically. Use `orientation="vertical"` for stacked layouts such as side panels or narrow containers.
+수평(horizontal) 또는 수직(vertical) 방향으로 배치할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -177,9 +195,9 @@ Buttons can be arranged horizontally (default) or vertically. Use `orientation="
 </div>
 ```
 
-## With Icons
+### With Icons
 
-Combine text labels with icons using the `startDecorator` prop on individual buttons for a richer, more descriptive interface.
+아이콘과 함께 사용할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -201,9 +219,49 @@ Combine text labels with icons using the `startDecorator` prop on individual but
 </div>
 ```
 
-## States
+### 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
 
-ButtonGroup supports disabled states at the group level (affecting all children) or on individual buttons for mixed-state scenarios.
+다양한 상태를 표현할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -240,9 +298,9 @@ ButtonGroup supports disabled states at the group level (affecting all children)
 </div>
 ```
 
-## Toggle Group
+### Toggle Group
 
-By dynamically switching the `variant` prop on individual buttons based on selection state, you can create a segmented toggle control for exclusive selection patterns.
+선택 상태를 토글할 수 있는 버튼 그룹입니다.
 
 ```tsx
 <div>
@@ -267,125 +325,58 @@ By dynamically switching the `variant` prop on individual buttons based on selec
 ### Toolbar Actions
 
 ```tsx
-import { ButtonGroup, Button } from '@ceed/ads';
-import SaveIcon from '@mui/icons-material/Save';
-import UndoIcon from '@mui/icons-material/Undo';
-import RedoIcon from '@mui/icons-material/Redo';
-
 <ButtonGroup variant="outlined">
-  <Button startDecorator={<SaveIcon />}>Save</Button>
-  <Button startDecorator={<UndoIcon />}>Undo</Button>
-  <Button startDecorator={<RedoIcon />}>Redo</Button>
+  <Button startDecorator={<SaveIcon />}>저장</Button>
+  <Button startDecorator={<UndoIcon />}>실행 취소</Button>
+  <Button startDecorator={<RedoIcon />}>다시 실행</Button>
 </ButtonGroup>
 ```
 
-### View Switcher
+### Text Formatting
 
 ```tsx
-const [view, setView] = useState('list');
-
-<ButtonGroup variant="outlined" color="neutral">
-  <Button
-    variant={view === 'list' ? 'solid' : 'outlined'}
-    onClick={() => setView('list')}
-  >
-    List
-  </Button>
-  <Button
-    variant={view === 'grid' ? 'solid' : 'outlined'}
-    onClick={() => setView('grid')}
-  >
-    Grid
-  </Button>
-  <Button
-    variant={view === 'card' ? 'solid' : 'outlined'}
-    onClick={() => setView('card')}
-  >
-    Card
-  </Button>
+<ButtonGroup size="sm" variant="soft">
+  <Button onClick={() => format('bold')}>B</Button>
+  <Button onClick={() => format('italic')}>I</Button>
+  <Button onClick={() => format('underline')}>U</Button>
 </ButtonGroup>
 ```
 
-### Pagination Controls
+### View Controls
 
 ```tsx
-<ButtonGroup variant="outlined" size="sm">
-  <Button disabled={page === 1} onClick={() => setPage(page - 1)}>
-    Previous
-  </Button>
-  <Button disabled>{page}</Button>
-  <Button onClick={() => setPage(page + 1)}>
-    Next
-  </Button>
+<ButtonGroup color="neutral">
+  <Button onClick={() => setView('list')}>목록</Button>
+  <Button onClick={() => setView('grid')}>격자</Button>
+  <Button onClick={() => setView('card')}>카드</Button>
 </ButtonGroup>
 ```
 
-## Best Practices
-
-1. **Group only related actions together.** Each ButtonGroup should represent a logically connected set of operations.
+### Pagination
 
 ```tsx
-// ✅ Related file operations grouped together
 <ButtonGroup variant="outlined">
-  <Button>Save</Button>
-  <Button>Save As</Button>
-  <Button>Export</Button>
-</ButtonGroup>
-
-// ❌ Unrelated actions mixed in one group
-<ButtonGroup>
-  <Button>Save</Button>
-  <Button>Delete Account</Button>
-  <Button>Help</Button>
+  <Button disabled={page === 1} onClick={() => setPage(page - 1)}>
+    이전
+  </Button>
+  <Button onClick={() => setPage(page + 1)}>
+    다음
+  </Button>
 </ButtonGroup>
 ```
 
-2. **Keep the button count between 2 and 5.** Too many buttons reduce clarity and overwhelm users.
-
-```tsx
-// ✅ Concise group
-<ButtonGroup>
-  <Button>Bold</Button>
-  <Button>Italic</Button>
-  <Button>Underline</Button>
-</ButtonGroup>
-
-// ❌ Too many options in a single group
-<ButtonGroup>
-  <Button>Bold</Button>
-  <Button>Italic</Button>
-  <Button>Underline</Button>
-  <Button>Strikethrough</Button>
-  <Button>Superscript</Button>
-  <Button>Subscript</Button>
-  <Button>Code</Button>
-</ButtonGroup>
-```
+## Best Practices
 
-3. **Use consistent variant and color across the group.** Avoid overriding individual button styles unless implementing toggle selection.
+1. **관련성**: 논리적으로 관련된 버튼들만 그룹화하세요.
 
-```tsx
-// ✅ Consistent styling via group props
-<ButtonGroup variant="outlined" color="neutral">
-  <Button>A</Button>
-  <Button>B</Button>
-</ButtonGroup>
+2. **일관성**: 그룹 내의 모든 버튼은 동일한 variant, size, color를 사용하는 것이 좋습니다.
 
-// ❌ Mixed styles with no semantic reason
-<ButtonGroup>
-  <Button variant="solid">A</Button>
-  <Button variant="outlined">B</Button>
-  <Button variant="plain">C</Button>
-</ButtonGroup>
-```
+3. **적절한 개수**: 너무 많은 버튼을 한 그룹에 포함하지 마세요. 일반적으로 2-5개가 적당합니다.
 
-4. **Clearly indicate the active state in toggle groups.** Use a distinct variant (e.g., `solid` vs `outlined`) so users can immediately see which option is selected.
+4. **명확한 레이블**: 각 버튼의 기능을 명확하게 알 수 있는 레이블을 사용하세요.
 
-5. **Consider vertical orientation for narrow layouts.** On mobile or in sidebars, `orientation="vertical"` prevents horizontal overflow and improves usability.
+5. **접근성**: 키보드 탐색이 가능하도록 하고, 스크린 리더를 위한 적절한 레이블을 제공하세요.
 
-## Accessibility
+6. **상태 관리**: 토글 그룹으로 사용할 때는 현재 선택된 상태를 시각적으로 명확히 표시하세요.
 
-- **Keyboard navigation**: All buttons within the group are focusable and navigable using the `Tab` key. Each button is a standard focusable element that responds to `Enter` and `Space`.
-- **ARIA grouping**: Wrap the ButtonGroup in a container with `role="group"` and an `aria-label` when the group represents a distinct set of controls (e.g., text formatting toolbar).
-- **Disabled state**: When the entire group is disabled, all child buttons receive `aria-disabled="true"` automatically, preventing interaction and communicating the state to assistive technologies.
-- **Toggle groups**: When using ButtonGroup as a toggle, consider adding `aria-pressed` to each button to communicate the selection state to screen readers.
+7. **반응형 디자인**: 작은 화면에서는 vertical orientation을 고려하거나 적절한 줄바꿈을 제공하세요.