@ceed/ads 1.30.0 → 1.31.0

package/dist/components/feedback/Modal.md

@@ -86,9 +86,7 @@ function DetailModal({ open, onClose }) {
 > **Note**: Connect the same handler to both `Modal`'s `onClose` and `ModalFrame`'s `onClose`.
 > `Modal` handles backdrop click and ESC key, while `ModalFrame` handles the X button click.
 
-## Examples
-
-### Basic Modal
+## Basic Modal
 
 The basic modal with a simple Sheet for custom layouts.
 
@@ -121,7 +119,7 @@ The basic modal with a simple Sheet for custom layouts.
 </>
 ```
 
-### Modal Dialog
+## Modal Dialog
 
 Use ModalDialog for structured dialogs with title, content, and actions.
 
@@ -156,7 +154,7 @@ Use ModalDialog for structured dialogs with title, content, and actions.
 </>
 ```
 
-### Variants
+## Modal Dialog Variants
 
 Modal dialogs support different visual variants.
 
@@ -220,7 +218,7 @@ Modal dialogs support different visual variants.
 </>
 ```
 
-### Alert Dialog
+## Alert Dialog
 
 For critical confirmations that require explicit user decision.
 
@@ -250,7 +248,7 @@ For critical confirmations that require explicit user decision.
 </>
 ```
 
-### Layouts
+## Modal Layouts
 
 #### Fullscreen Layout
 
@@ -274,7 +272,7 @@ For complex content that requires maximum screen space.
 </>
 ```
 
-### Nested Modals
+## Nested Modals
 
 Modals can be stacked on top of each other when necessary.
 
@@ -304,7 +302,7 @@ Modals can be stacked on top of each other when necessary.
 </>
 ```
 
-### ModalFrame
+## ModalFrame Examples
 
 ModalFrame is a convenience component that automatically provides a title, close button, and content area.
 
@@ -482,9 +480,7 @@ ModalFrame can be used without a Modal wrapper for embedding dialog-style layout
 - **Non-critical information**: Success messages or tips should use Toast or inline feedback
 - **Mobile navigation**: Consider using full-page transitions instead on mobile devices
 
-## Common Use Cases
-
-### Confirmation Dialog
+## Confirmation Dialog
 
 Confirm destructive or significant actions before executing them.
 
@@ -515,7 +511,7 @@ function DeleteConfirmation({ item, onDelete, onCancel }) {
 }
 ```
 
-### Form Modal
+## Form Modal
 
 Capture user input in a focused dialog.
 
@@ -563,7 +559,7 @@ function CreateProjectModal({ open, onClose, onCreate }) {
 }
 ```
 
-### Information Modal
+## Information Modal
 
 Display detailed information that requires user acknowledgment.
 
@@ -593,7 +589,7 @@ function TermsModal({ open, onAccept, onDecline }) {
 }
 ```
 
-### Image Preview Modal
+## Image Preview Modal
 
 Display images or media in a focused overlay.
 
@@ -610,7 +606,7 @@ function ImagePreviewModal({ image, open, onClose }) {
 }
 ```
 
-### Loading Modal
+## Loading Modal
 
 Block user interaction during async operations.
 

package/dist/components/feedback/Skeleton.md

@@ -183,9 +183,7 @@ Wrap existing content with Skeleton to overlay it while loading. Set the `loadin
 </Typography>
 ```
 
-## Common Use Cases
-
-### Page Content Loading
+## Page Content Loading
 
 ```tsx
 function PageSkeleton() {
@@ -205,7 +203,7 @@ function PageSkeleton() {
 }
 ```
 
-### User List Loading
+## User List Loading
 
 ```tsx
 function UserListSkeleton({ count = 5 }: { count?: number }) {
@@ -225,7 +223,7 @@ function UserListSkeleton({ count = 5 }: { count?: number }) {
 }
 ```
 
-### Conditional Rendering
+## Conditional Rendering
 
 ```tsx
 function UserProfile({ loading, user }: { loading: boolean; user?: User }) {
@@ -249,6 +247,23 @@ function UserProfile({ loading, user }: { loading: boolean; user?: User }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop        | Type                                                             | Default     | Description                                    |
+| ----------- | ---------------------------------------------------------------- | ----------- | ---------------------------------------------- |
+| `variant`   | `'rectangular' \| 'circular' \| 'text' \| 'overlay' \| 'inline'` | `'overlay'` | Skeleton shape                                 |
+| `animation` | `'pulse' \| 'wave' \| false`                                     | `'pulse'`   | Animation type                                 |
+| `width`     | `number \| string`                                               | -           | Skeleton width                                 |
+| `height`    | `number \| string`                                               | -           | Skeleton height                                |
+| `level`     | Typography level                                                 | -           | Matches text height for `text` variant         |
+| `loading`   | `boolean`                                                        | `true`      | When false, shows children instead of skeleton |
+| `children`  | `ReactNode`                                                      | -           | Content to show when not loading               |
+| `sx`        | `SxProps`                                                        | -           | Custom styles                                  |
+
+> **Note**: Skeleton also accepts all Joy UI Skeleton props.
+
 ## Best Practices
 
 1. **Match the final layout**: Skeleton placeholders should closely approximate the size and position of the real content to prevent layout shifts.

package/dist/components/inputs/Autocomplete.md

@@ -423,9 +423,7 @@ These boolean props fine-tune interaction behavior. Toggle them in the Controls
 - **Numeric ranges**: Use Slider or NumberInput
 - **Date selection**: Use DatePicker
 
-## Common Use Cases
-
-### Country Selector
+## Country Selector
 
 ```tsx
 function CountrySelector({ value, onChange }) {
@@ -452,7 +450,7 @@ function CountrySelector({ value, onChange }) {
 }
 ```
 
-### User Search
+## User Search
 
 ```tsx
 function UserSearch({ onSelect }) {
@@ -500,7 +498,7 @@ function UserSearch({ onSelect }) {
 }
 ```
 
-### Product Search with Categories
+## Product Search with Categories
 
 ```tsx
 function ProductSearch({ products, onSelect }) {
@@ -531,7 +529,7 @@ function ProductSearch({ products, onSelect }) {
 }
 ```
 
-### Address Autocomplete
+## Address Autocomplete
 
 ```tsx
 function AddressAutocomplete({ onAddressSelect }) {
@@ -576,7 +574,7 @@ function AddressAutocomplete({ onAddressSelect }) {
 }
 ```
 
-### Tag Selection (Multiple)
+## Tag Selection (Multiple)
 
 ```tsx
 function TagSelector({ availableTags, selectedTags, onChange }) {
@@ -608,7 +606,7 @@ function TagSelector({ availableTags, selectedTags, onChange }) {
 }
 ```
 
-### Grouped Options
+## Grouped Options
 
 ```tsx
 function CategorySelector() {
@@ -634,7 +632,7 @@ function CategorySelector() {
 }
 ```
 
-### With Secondary Text
+## With Secondary Text
 
 ```tsx
 function ContactSelector() {
@@ -649,7 +647,7 @@ function ContactSelector() {
 }
 ```
 
-### Lazy Loading Options
+## Lazy Loading Options
 
 ```tsx
 function LazyAutocomplete({ fetchOptions }) {

package/dist/components/inputs/Button.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Button 컴포넌트는 사용자가 클릭하여 특정 작업을 수행할 수 있는 기본적인 UI 요소입니다. Joy UI의 Button을 기반으로 하며, Framer Motion 애니메이션 지원이 추가되었습니다. 폼 제출, 페이지 이동, 모달 열기/닫기, 데이터 처리 등 다양한 상호작용에 사용됩니다.
+Button is the primary interactive element for triggering actions. Built on Joy UI's Button with Framer Motion animation support, it provides multiple visual variants, sizes, colors, loading states, and decorator slots. Use buttons for form submissions, navigation triggers, modal actions, and data operations.
 
 ```tsx
 <>
@@ -26,15 +26,13 @@ Button 컴포넌트는 사용자가 클릭하여 특정 작업을 수행할 수
 import { Button } from '@ceed/ads';
 
 function MyComponent() {
-  return <Button onClick={() => console.log('클릭됨!')}>클릭하세요</Button>;
+  return <Button onClick={() => console.log('Clicked!')}>Click me</Button>;
 }
 ```
 
-## Examples
+## Basic Usage
 
-### Basic Usage
-
-가장 기본적인 버튼 사용법입니다.
+The most basic button usage.
 
 ```tsx
 <>
@@ -44,9 +42,9 @@ function MyComponent() {
 </>
 ```
 
-### Disabled State
+## Disabled Button
 
-비활성 상태의 버튼입니다. 사용자가 클릭할 수 없으며 시각적으로도 비활성 상태임을 나타냅니다.
+A disabled button cannot be clicked and is visually dimmed.
 
 ```tsx
 <>
@@ -65,9 +63,9 @@ function MyComponent() {
 </>
 ```
 
-### Loading State
+## Button Loading State
 
-로딩 중일 때 사용하는 버튼입니다. 비동기 작업 수행 중에 사용자에게 진행 상태를 알려줍니다.
+Shows a loading indicator during async operations. The button is automatically disabled while loading.
 
 ```tsx
 <Button
@@ -80,11 +78,9 @@ function MyComponent() {
 />
 ```
 
-## Customization
-
-### Variants
+## Variants
 
-버튼의 시각적 스타일을 다양하게 변경할 수 있습니다.
+Four visual styles are available to indicate action importance.
 
 ```tsx
 <>
@@ -103,14 +99,14 @@ function MyComponent() {
 </>
 ```
 
-- **solid**: 강조가 필요한 주요 액션 (기본값)
-- **soft**: 부드러운 배경의 보조 액션
-- **outlined**: 테두리만 있는 중요도가 낮은 액션
-- **plain**: 텍스트만 있는 최소한의 스타일
+- **solid**: High-emphasis primary actions (default)
+- **soft**: Medium-emphasis secondary actions with a subtle background
+- **outlined**: Low-emphasis actions with a border
+- **plain**: Minimal actions with text only
 
-### Sizes
+## Sizes
 
-버튼의 크기를 조절할 수 있습니다.
+Three sizes are available: `sm`, `md` (default), and `lg`.
 
 ```tsx
 <>
@@ -126,13 +122,9 @@ function MyComponent() {
 </>
 ```
 
-- **sm**: 작은 크기 (제한된 공간에서 사용)
-- **md**: 중간 크기 (기본값)
-- **lg**: 큰 크기 (강조가 필요한 경우)
-
-### Colors
+## Colors
 
-다양한 색상 테마를 적용할 수 있습니다.
+Apply semantic colors to communicate intent.
 
 ```tsx
 <>
@@ -154,15 +146,15 @@ function MyComponent() {
 </>
 ```
 
-- **primary**: 주요 액션 (기본값)
-- **neutral**: 중립적인 액션
-- **success**: 성공/확인 액션
-- **warning**: 주의가 필요한 액션
-- **danger**: 위험한/삭제 액션
+- **primary**: Main actions (default)
+- **neutral**: Neutral actions
+- **success**: Confirmation or positive actions
+- **warning**: Caution-required actions
+- **danger**: Destructive or irreversible actions
 
-### Decorators
+## Button Decorators
 
-버튼에 아이콘이나 다른 요소를 추가할 수 있습니다.
+Add icons or other elements before or after the button text using `startDecorator` and `endDecorator`.
 
 ```tsx
 <>
@@ -175,9 +167,9 @@ function MyComponent() {
 </>
 ```
 
-### Loading Indicator
+## Loading Indicator Customization
 
-로딩 표시기를 커스터마이징할 수 있습니다.
+Customize the loading spinner with the `loadingIndicator` prop.
 
 ```tsx
 <>
@@ -190,9 +182,9 @@ function MyComponent() {
 </>
 ```
 
-### Loading Position
+## Loading Position
 
-로딩 표시기의 위치를 조절할 수 있습니다.
+Control where the loading indicator appears with `loadingPosition`.
 
 ```tsx
 <>
@@ -205,66 +197,64 @@ function MyComponent() {
 </>
 ```
 
-## Common Use Cases
-
-### Form Submission
+## Button in Form Submission
 
 ```tsx
 <form onSubmit={handleSubmit}>
   <Stack spacing={2}>
-    <Input placeholder="이름을 입력하세요" />
-    <Input placeholder="이메일을 입력하세요" />
+    <Input placeholder="Enter your name" />
+    <Input placeholder="Enter your email" />
 
     <Stack direction="row" spacing={2} justifyContent="flex-end">
       <Button variant="outlined" type="button" onClick={handleCancel}>
-        취소
+        Cancel
       </Button>
       <Button type="submit" loading={isSubmitting}>
-        {isSubmitting ? '저장 중...' : '저장'}
+        {isSubmitting ? 'Saving...' : 'Save'}
       </Button>
     </Stack>
   </Stack>
 </form>
 ```
 
-### Modal Actions
+## Button in Modal Actions
 
 ```tsx
 <Modal open={open}>
   <ModalDialog>
     <ModalClose />
-    <DialogTitle>삭제 확인</DialogTitle>
-    <DialogContent>정말로 이 항목을 삭제하시겠습니까? 이 작업은 되돌릴 수 없습니다.</DialogContent>
+    <DialogTitle>Confirm Deletion</DialogTitle>
+    <DialogContent>Are you sure you want to delete this item? This action cannot be undone.</DialogContent>
 
     <DialogActions>
       <Button variant="outlined" onClick={handleClose}>
-        취소
+        Cancel
       </Button>
       <Button color="danger" onClick={handleDelete}>
-        삭제
+        Delete
       </Button>
     </DialogActions>
   </ModalDialog>
 </Modal>
 ```
 
-### Action Buttons with Icons
+## Action Buttons with Icons
 
 ```tsx
 <Stack direction="row" spacing={2}>
-  <Button startDecorator={<AddIcon />}>새로 만들기</Button>
+  <Button startDecorator={<AddIcon />}>Create New</Button>
 
   <Button variant="outlined" startDecorator={<DownloadIcon />} onClick={handleDownload}>
-    다운로드
+    Download
   </Button>
 
   <Button variant="soft" color="success" startDecorator={<ShareIcon />}>
-    공유
+    Share
   </Button>
 </Stack>
 ```
 
-### Async Operations
+## Async Operation Button
 
 ```tsx
 function AsyncButton() {
@@ -274,9 +264,6 @@ function AsyncButton() {
     setLoading(true);
     try {
       await api.processData();
-      // 성공 처리
-    } catch (error) {
-      // 에러 처리
     } finally {
       setLoading(false);
     }
@@ -284,51 +271,84 @@ function AsyncButton() {
 
   return (
     <Button loading={loading} onClick={handleAsyncAction} startDecorator={<ProcessIcon />}>
-      데이터 처리
+      Process Data
     </Button>
   );
 }
 ```
 
-### Button Groups
+## Props and Customization
+
+### Key Props
+
+| Prop               | Type                                                           | Default                | Description                                                       |
+| ------------------ | -------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------- |
+| `children`         | `ReactNode`                                                    | -                      | Button content (text, icons, etc.)                                |
+| `variant`          | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'solid'`              | Visual style                                                      |
+| `size`             | `'sm' \| 'md' \| 'lg'`                                         | `'md'`                 | Button size                                                       |
+| `color`            | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'primary'`            | Color scheme                                                      |
+| `disabled`         | `boolean`                                                      | `false`                | Disables the button                                               |
+| `loading`          | `boolean`                                                      | `false`                | Shows a loading indicator and disables the button                 |
+| `loadingIndicator` | `ReactNode`                                                    | `<CircularProgress />` | Custom loading indicator element                                  |
+| `loadingPosition`  | `'start' \| 'end'`                                             | `'start'`              | Where the loading indicator appears                               |
+| `startDecorator`   | `ReactNode`                                                    | -                      | Content rendered before the button text                           |
+| `endDecorator`     | `ReactNode`                                                    | -                      | Content rendered after the button text                            |
+| `fullWidth`        | `boolean`                                                      | `false`                | Stretches the button to fill its container width                  |
+| `component`        | `ElementType`                                                  | `'button'`             | Root element type (polymorphic — can render as `a`, `Link`, etc.) |
+| `type`             | `'button' \| 'submit' \| 'reset'`                              | `'button'`             | HTML button type attribute                                        |
+| `onClick`          | `(event: MouseEvent) => void`                                  | -                      | Click event handler                                               |
+| `sx`               | `SxProps`                                                      | -                      | Custom styles using the MUI system                                |
+
+> **Note**: Button also accepts all Joy UI Button props and Framer Motion props.
+
+## Polymorphic Button
+
+Button supports the `component` prop to render as a different element:
 
 ```tsx
-<Stack direction="row" spacing={1}>
-  <Button variant="soft" size="sm">
-    전체
-  </Button>
-  <Button variant="outlined" size="sm">
-    진행중
-  </Button>
-  <Button variant="outlined" size="sm">
-    완료
-  </Button>
-</Stack>
+// Render as an anchor tag
+<Button component="a" href="/dashboard">Go to Dashboard</Button>
+
+// Render as a React Router Link
+<Button component={Link} to="/settings">Settings</Button>
 ```
 
 ## Best Practices
 
-1. **명확한 라벨**: 버튼의 기능을 명확하게 나타내는 텍스트를 사용하세요.
+1. **Choose the right variant for the action hierarchy**:
+   - Primary action: `solid`
+   - Secondary action: `outlined` or `soft`
+   - Tertiary/minimal action: `plain`
 
-2. **적절한 변형 선택**:
-   - 주요 액션: `solid`
-   - 보조 액션: `outlined` 또는 `soft`
-   - 최소한의 액션: `plain`
+2. **Use consistent color semantics**:
+   - Destructive actions: `danger`
+   - Confirmations: `success`
+   - Caution: `warning`
 
-3. **색상 의미 일관성**:
-   - 위험한 작업: `danger`
-   - 성공/확인: `success`
-   - 주의 필요: `warning`
+3. **Use clear, specific labels.** The button text should describe exactly what happens when clicked.
 
-4. **로딩 상태 표시**: 비동기 작업 시 사용자에게 피드백을 제공하세요.
+```tsx
+// ✅ Good
+<Button color="danger">Delete Account</Button>
 
-5. **접근성**: 적절한 ARIA 라벨과 키보드 탐색을 지원하세요.
+// ❌ Bad
+<Button color="danger">OK</Button>
+```
 
-## Accessibility
+4. **Show loading state during async operations** to provide user feedback.
 
-- 키보드로 접근 가능 (Tab, Space, Enter)
-- 스크린 리더 지원
-- 적절한 색상 대비
-- 비활성 상태에서 포커스 불가
+```tsx
+<Button loading={isSubmitting} type="submit">
+  Save Changes
+</Button>
+```
+
+5. **Limit the number of primary buttons** in a view. Typically one `solid` primary button per section.
+
+## Accessibility
 
-Button은 사용자 인터페이스에서 가장 기본적이면서도 중요한 상호작용 요소입니다. 적절한 스타일과 상태 관리를 통해 직관적이고 접근 가능한 사용자 경험을 제공할 수 있습니다.
+- **Keyboard accessible**: Tab to focus, Space or Enter to activate.
+- **Screen reader support**: Button text is announced as the accessible name.
+- **Disabled state**: When `disabled`, the button is removed from the tab order.
+- **Loading state**: When `loading`, the button is announced as disabled. Consider adding `aria-label` to describe the loading context if the loading indicator replaces the text.
+- **Color contrast**: All color/variant combinations meet WCAG AA contrast ratios.

package/dist/components/inputs/ButtonGroup.md

@@ -262,9 +262,7 @@ By dynamically switching the `variant` prop on individual buttons based on selec
 </div>
 ```
 
-## Common Use Cases
-
-### Toolbar Actions
+## Toolbar Actions
 
 ```tsx
 import { ButtonGroup, Button } from '@ceed/ads';
@@ -279,7 +277,7 @@ import RedoIcon from '@mui/icons-material/Redo';
 </ButtonGroup>
 ```
 
-### View Switcher
+## View Switcher
 
 ```tsx
 const [view, setView] = useState('list');
@@ -306,7 +304,7 @@ const [view, setView] = useState('list');
 </ButtonGroup>
 ```
 
-### Pagination Controls
+## Pagination Controls
 
 ```tsx
 <ButtonGroup variant="outlined" size="sm">
@@ -383,6 +381,23 @@ const [view, setView] = useState('list');
 
 5. **Consider vertical orientation for narrow layouts.** On mobile or in sidebars, `orientation="vertical"` prevents horizontal overflow and improves usability.
 
+## Props and Customization
+
+### Key Props
+
+| Prop          | Type                                                           | Default        | Description                         |
+| ------------- | -------------------------------------------------------------- | -------------- | ----------------------------------- |
+| `children`    | `ReactNode`                                                    | -              | Button elements inside the group    |
+| `variant`     | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'outlined'`   | Visual style applied to all buttons |
+| `size`        | `'sm' \| 'md' \| 'lg'`                                         | `'md'`         | Size applied to all buttons         |
+| `color`       | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`    | Color applied to all buttons        |
+| `disabled`    | `boolean`                                                      | `false`        | Disables all buttons in the group   |
+| `orientation` | `'horizontal' \| 'vertical'`                                   | `'horizontal'` | Layout direction                    |
+| `spacing`     | `number \| string`                                             | `0`            | Gap between buttons                 |
+| `sx`          | `SxProps`                                                      | -              | Custom styles using the MUI system  |
+
+> **Note**: ButtonGroup accepts all Joy UI ButtonGroup props.
+
 ## Accessibility
 
 - **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`.