@ceed/cds 1.22.3 → 1.22.5

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/cds';
 function MyComponent() {
   return (
     <ButtonGroup>
-      <Button>첫번째</Button>
-      <Button>두번째</Button>
-      <Button>세번째</Button>
+      <Button>First</Button>
+      <Button>Second</Button>
+      <Button>Third</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
+## 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
+## States
 
-실제 사용 사례별 액션 그룹들입니다.
-
-```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={{
@@ -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,56 +267,125 @@ function MyComponent() {
 ### Toolbar Actions
 
 ```tsx
+import { ButtonGroup, Button } from '@ceed/cds';
+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.
 
-1. **관련성**: 논리적으로 관련된 버튼들만 그룹화하세요.
+```tsx
+// ✅ Concise group
+<ButtonGroup>
+  <Button>Bold</Button>
+  <Button>Italic</Button>
+  <Button>Underline</Button>
+</ButtonGroup>
 
-2. **일관성**: 그룹 내의 모든 버튼은 동일한 variant, size, color를 사용하는 것이 좋습니다.
+// ❌ 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>
+```
+
+3. **Use consistent variant and color across the group.** Avoid overriding individual button styles unless implementing toggle selection.
+
+```tsx
+// ✅ Consistent styling via group props
+<ButtonGroup variant="outlined" color="neutral">
+  <Button>A</Button>
+  <Button>B</Button>
+</ButtonGroup>
 
-3. **적절한 개수**: 너무 많은 버튼을 한 그룹에 포함하지 마세요. 일반적으로 2-5개가 적당합니다.
+// ❌ 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.

package/dist/components/inputs/CurrencyInput.md

@@ -2,10 +2,11 @@
 
 ## Introduction
 
-> 💡 **Form 구성 시 내장 prop 사용을 권장합니다**
+CurrencyInput is a specialized numeric input for entering monetary values. It automatically formats numbers with the appropriate currency symbol, thousand separators, and decimal places based on the selected currency (USD or KRW). It supports features like maximum value validation, minor unit conversion, and controlled/uncontrolled modes.
+
+> **Tip: Use built-in form props**
 >
-> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
-> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.
+> This component supports `label` and `helperText` props directly. Use these instead of wrapping with FormControl + FormLabel + FormHelperText for simpler forms.
 
 ```tsx
 <CurrencyInput
@@ -30,8 +31,42 @@
 | useMinorUnit | —           | —                |
 | onChange     | —           | —                |
 
+## Usage
+
+```tsx
+import { CurrencyInput } from '@ceed/cds';
+
+function MyComponent() {
+  const [amount, setAmount] = React.useState(0);
+
+  return (
+    <CurrencyInput
+      label="Price"
+      currency="USD"
+      value={amount}
+      onChange={(e) => setAmount(e.target.value)}
+    />
+  );
+}
+```
+
+## Currency Formats
+
+### USD (Default)
+
+US Dollar format with `$` symbol, comma thousand separators, and 2 decimal places.
+
+```tsx
+<CurrencyInput
+  name="currency-input"
+  defaultValue={1000}
+/>
+```
+
 ### KRW
 
+Korean Won format with `₩` symbol, comma thousand separators, and no decimal places.
+
 ```tsx
 <CurrencyInput
   name="currency-input"
@@ -40,7 +75,13 @@
 />
 ```
 
-### Sizes
+```tsx
+<CurrencyInput currency="KRW" value={50000} />
+```
+
+## Sizes
+
+CurrencyInput supports three sizes: `sm`, `md` (default), and `lg`.
 
 ```tsx
 <Stack gap={2}>
@@ -50,7 +91,9 @@
 </Stack>
 ```
 
-### WithLabel
+## Form Features
+
+### With Label
 
 ```tsx
 <CurrencyInput
@@ -60,7 +103,11 @@
 />
 ```
 
-### WithHelperText
+```tsx
+<CurrencyInput label="Total Amount" />
+```
+
+### With Helper Text
 
 ```tsx
 <CurrencyInput
@@ -71,7 +118,11 @@
 />
 ```
 
-### Error
+```tsx
+<CurrencyInput label="Price" helperText="Enter the item price in USD." />
+```
+
+### Error State
 
 ```tsx
 <CurrencyInput
@@ -83,7 +134,13 @@
 />
 ```
 
-### PriceLimitError
+```tsx
+<CurrencyInput label="Amount" error helperText="Amount is required." />
+```
+
+## Price Limit
+
+Set the `max` prop to enforce a maximum value. When the entered value exceeds the limit, the input automatically displays an error state with a formatted limit message.
 
 ```tsx
 <CurrencyInput
@@ -94,3 +151,119 @@
   max={1000000}
 />
 ```
+
+```tsx
+<CurrencyInput
+  currency="USD"
+  max={1000000}
+  value={10000000}
+/>
+```
+
+## Minor Unit Mode
+
+When `useMinorUnit` is true, the component converts between display values and minor units (e.g., cents for USD). This is useful when your API stores amounts in the smallest currency unit.
+
+```tsx
+// Display shows "$10.00", but onChange returns 1000 (cents)
+<CurrencyInput currency="USD" useMinorUnit value={1000} />
+
+// Display shows "₩10,000", onChange returns 10000 (no conversion for KRW)
+<CurrencyInput currency="KRW" useMinorUnit value={10000} />
+```
+
+## Common Use Cases
+
+### Product Price Editor
+
+```tsx
+function ProductPriceEditor() {
+  const [priceUSD, setPriceUSD] = React.useState(0);
+  const [priceKRW, setPriceKRW] = React.useState(0);
+
+  return (
+    <Stack gap={2}>
+      <CurrencyInput
+        label="USD Price"
+        currency="USD"
+        value={priceUSD}
+        onChange={(e) => setPriceUSD(e.target.value)}
+        max={99999.99}
+      />
+      <CurrencyInput
+        label="KRW Price"
+        currency="KRW"
+        value={priceKRW}
+        onChange={(e) => setPriceKRW(e.target.value)}
+        max={99999999}
+      />
+    </Stack>
+  );
+}
+```
+
+### Invoice Line Item
+
+```tsx
+function InvoiceLineItem({ item, onChange }) {
+  return (
+    <Stack direction="row" gap={2} alignItems="flex-end">
+      <Input label="Description" value={item.description} />
+      <CurrencyInput
+        label="Unit Price"
+        currency="USD"
+        value={item.unitPrice}
+        onChange={(e) => onChange({ ...item, unitPrice: e.target.value })}
+      />
+      <Input label="Qty" type="number" value={item.quantity} sx={{ width: 80 }} />
+    </Stack>
+  );
+}
+```
+
+### Budget Limit Input
+
+```tsx
+function BudgetSetting() {
+  const [budget, setBudget] = React.useState(50000);
+
+  return (
+    <CurrencyInput
+      label="Monthly Budget"
+      helperText="Set the maximum monthly spending limit."
+      currency="USD"
+      value={budget}
+      onChange={(e) => setBudget(e.target.value)}
+      max={1000000}
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Choose the right currency**: Always set the `currency` prop explicitly. USD uses 2 decimal places while KRW uses none.
+
+```tsx
+// ✅ Explicit currency
+<CurrencyInput currency="USD" />
+<CurrencyInput currency="KRW" />
+
+// ❌ Relying on default — may confuse users expecting KRW
+<CurrencyInput />
+```
+
+2. **Set max limits**: Use `max` to prevent unreasonable values. The component displays a helpful error message when the limit is exceeded.
+
+3. **Use `useMinorUnit` for API integration**: When your backend stores amounts in minor units (cents, etc.), enable `useMinorUnit` to avoid manual conversion.
+
+4. **Use built-in label and helperText**: Prefer the component's own `label` and `helperText` props over wrapping with FormControl.
+
+5. **Handle negative values carefully**: CurrencyInput supports negative values. If negatives are not valid for your use case, validate in `onChange`.
+
+## Accessibility
+
+- The input has `role="textbox"` with proper labeling via the `label` prop.
+- Error states are communicated via `aria-invalid` and associated error messages.
+- The currency symbol serves as a visual indicator; ensure labels also mention the currency for screen readers.
+- Keyboard input is fully supported — users can type numbers, and formatting is applied automatically.