@ceed/ads 1.25.1-next.3 → 1.27.0

package/dist/components/inputs/ButtonGroup.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-ButtonGroup 컴포넌트는 관련된 버튼들을 그룹화하여 하나의 통합된 인터페이스로 표시합니다. 버튼들을 논리적으로 묶어서 시각적 일관성을 제공하고, 공간을 효율적으로 사용할 수 있게 해줍니다. 툴바, 액션 버튼 세트, 토글 그룹 등에 주로 사용됩니다.
+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.
 
 ```tsx
 <ButtonGroup {...args}>
@@ -28,37 +30,17 @@ import { ButtonGroup, Button } from '@ceed/ads';
 function MyComponent() {
   return (
     <ButtonGroup>
-      <Button>첫번째</Button>
-      <Button>두번째</Button>
-      <Button>세번째</Button>
+      <Button>First</Button>
+      <Button>Second</Button>
+      <Button>Third</Button>
     </ButtonGroup>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Colors
 
-기본적인 ButtonGroup 사용법입니다.
-
-```tsx
-<div style={{
-  display: 'flex',
-  gap: '2rem',
-  flexDirection: 'column'
-}}>
-<ButtonGroup>
-  <Button>첫번째</Button>
-  <Button>두번째</Button>
-  <Button>세번째</Button>
-</ButtonGroup>
-</div>
-```
-
-### Colors
-
-다양한 색상을 적용할 수 있습니다.
+Apply a unified color theme to all buttons in the group using the `color` prop. Available colors are `primary`, `neutral`, `danger`, `success`, and `warning`.
 
 ```tsx
 <div style={{
@@ -98,9 +80,9 @@ function MyComponent() {
 </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={{
@@ -134,9 +116,9 @@ function MyComponent() {
 </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={{
@@ -165,9 +147,9 @@ function MyComponent() {
 </div>
 ```
 
-### Orientations
+## Orientations
 
-수평(horizontal) 또는 수직(vertical) 방향으로 배치할 수 있습니다.
+Buttons can be arranged horizontally (default) or vertically. Use `orientation="vertical"` for stacked layouts such as side panels or narrow containers.
 
 ```tsx
 <div style={{
@@ -195,9 +177,9 @@ function MyComponent() {
 </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={{
@@ -219,49 +201,9 @@ function MyComponent() {
 </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
+## States
 
-다양한 상태를 표현할 수 있습니다.
+ButtonGroup supports disabled states at the group level (affecting all children) or on individual buttons for mixed-state scenarios.
 
 ```tsx
 <div style={{
@@ -298,9 +240,9 @@ function MyComponent() {
 </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>
@@ -325,58 +267,125 @@ function MyComponent() {
 ### 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 />}>저장</Button>
-  <Button startDecorator={<UndoIcon />}>실행 취소</Button>
-  <Button startDecorator={<RedoIcon />}>다시 실행</Button>
+  <Button startDecorator={<SaveIcon />}>Save</Button>
+  <Button startDecorator={<UndoIcon />}>Undo</Button>
+  <Button startDecorator={<RedoIcon />}>Redo</Button>
 </ButtonGroup>
 ```
 
-### Text Formatting
+### View Switcher
 
 ```tsx
-<ButtonGroup size="sm" variant="soft">
-  <Button onClick={() => format('bold')}>B</Button>
-  <Button onClick={() => format('italic')}>I</Button>
-  <Button onClick={() => format('underline')}>U</Button>
+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>
 ```
 
-### View Controls
+### Pagination Controls
 
 ```tsx
-<ButtonGroup color="neutral">
-  <Button onClick={() => setView('list')}>목록</Button>
-  <Button onClick={() => setView('grid')}>격자</Button>
-  <Button onClick={() => setView('card')}>카드</Button>
+<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>
 ```
 
-### Pagination
+## Best Practices
+
+1. **Group only related actions together.** Each ButtonGroup should represent a logically connected set of operations.
 
 ```tsx
+// ✅ Related file operations grouped together
 <ButtonGroup variant="outlined">
-  <Button disabled={page === 1} onClick={() => setPage(page - 1)}>
-    이전
-  </Button>
-  <Button onClick={() => setPage(page + 1)}>
-    다음
-  </Button>
+  <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>
 </ButtonGroup>
 ```
 
-## Best Practices
+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>
 
-1. **관련성**: 논리적으로 관련된 버튼들만 그룹화하세요.
+// ❌ 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>
+```
 
-2. **일관성**: 그룹 내의 모든 버튼은 동일한 variant, size, color를 사용하는 것이 좋습니다.
+3. **Use consistent variant and color across the group.** Avoid overriding individual button styles unless implementing toggle selection.
 
-3. **적절한 개수**: 너무 많은 버튼을 한 그룹에 포함하지 마세요. 일반적으로 2-5개가 적당합니다.
+```tsx
+// ✅ Consistent styling via group props
+<ButtonGroup variant="outlined" color="neutral">
+  <Button>A</Button>
+  <Button>B</Button>
+</ButtonGroup>
+
+// ❌ Mixed styles with no semantic reason
+<ButtonGroup>
+  <Button variant="solid">A</Button>
+  <Button variant="outlined">B</Button>
+  <Button variant="plain">C</Button>
+</ButtonGroup>
+```
 
-4. **명확한 레이블**: 각 버튼의 기능을 명확하게 알 수 있는 레이블을 사용하세요.
+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.
 
-5. **접근성**: 키보드 탐색이 가능하도록 하고, 스크린 리더를 위한 적절한 레이블을 제공하세요.
+5. **Consider vertical orientation for narrow layouts.** On mobile or in sidebars, `orientation="vertical"` prevents horizontal overflow and improves usability.
 
-6. **상태 관리**: 토글 그룹으로 사용할 때는 현재 선택된 상태를 시각적으로 명확히 표시하세요.
+## Accessibility
 
-7. **반응형 디자인**: 작은 화면에서는 vertical orientation을 고려하거나 적절한 줄바꿈을 제공하세요.
+- **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.