@ceed/ads 1.23.3 → 1.23.4

package/dist/components/feedback/Skeleton.md

@@ -0,0 +1,280 @@
+# Skeleton
+
+## Introduction
+
+The Skeleton component provides placeholder previews of content before data is loaded. It is based on Joy UI's Skeleton and helps reduce perceived loading time by showing an approximation of the page layout. Skeletons improve the user experience by preventing layout shifts and giving users a visual cue that content is on its way.
+
+```tsx
+<Skeleton
+  variant="rectangular"
+  width={200}
+  height={24}
+/>
+```
+
+| Field                        | Description | Default |
+| ---------------------------- | ----------- | ------- |
+| Controls resolved at runtime | —           | —       |
+
+## Usage
+
+```tsx
+import { Skeleton } from '@ceed/ads';
+
+function MyComponent() {
+  return <Skeleton variant="rectangular" width={200} height={24} />;
+}
+```
+
+## Variants
+
+Skeleton supports three variants: `rectangular`, `circular`, and `text`.
+
+- **rectangular**: Block-shaped placeholder for images, cards, and content areas.
+- **circular**: Round placeholder for avatars and icons.
+- **text**: Matches the height and spacing of text content at a given `level`.
+
+```tsx
+<>
+  <Skeleton variant="rectangular" width={200} height={24} />
+  <Skeleton variant="circular" width={48} height={48} />
+  <Skeleton variant="text" width={200} />
+</>
+```
+
+```tsx
+<Skeleton variant="rectangular" width={200} height={24} />
+<Skeleton variant="circular" width={48} height={48} />
+<Skeleton variant="text" width={200} />
+```
+
+## Animations
+
+Skeleton supports `wave` (default) and `pulse` animations. Set `animation={false}` to disable animation entirely.
+
+```tsx
+<Stack gap={3}>
+  <Box>
+    <Typography level="body-sm" sx={{
+      mb: 1
+    }}>
+    Wave (default)
+  </Typography>
+  <Skeleton animation="wave" variant="rectangular" width={200} height={24} />
+</Box>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 1
+  }}>
+  Pulse
+</Typography>
+<Skeleton animation="pulse" variant="rectangular" width={200} height={24} />
+</Box>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 1
+  }}>
+  No animation (false)
+</Typography>
+<Skeleton animation={false} variant="rectangular" width={200} height={24} />
+</Box>
+</Stack>
+```
+
+```tsx
+<Skeleton animation="wave" variant="rectangular" width={200} height={24} />
+<Skeleton animation="pulse" variant="rectangular" width={200} height={24} />
+<Skeleton animation={false} variant="rectangular" width={200} height={24} />
+```
+
+## Text Skeleton
+
+Use `variant="text"` with the `level` prop to match Typography sizing. This is useful for creating text content placeholders that accurately reflect the final layout.
+
+```tsx
+<Stack gap={1} sx={{
+  width: 300
+}}>
+<Skeleton variant="text" level="h3" />
+<Skeleton variant="text" level="body-md" />
+<Skeleton variant="text" level="body-md" />
+<Skeleton variant="text" level="body-md" width="80%" />
+</Stack>
+```
+
+```tsx
+<Skeleton variant="text" level="h3" />
+<Skeleton variant="text" level="body-md" />
+<Skeleton variant="text" level="body-md" />
+<Skeleton variant="text" level="body-md" width="80%" />
+```
+
+## Card Skeleton
+
+Compose multiple Skeleton elements to create placeholder layouts for complex components like cards.
+
+```tsx
+<Box sx={{
+  width: 300,
+  p: 2,
+  border: '1px solid',
+  borderColor: 'divider',
+  borderRadius: 'sm'
+}}>
+<Skeleton variant="rectangular" width="100%" height={140} sx={{
+  borderRadius: 'sm',
+  mb: 2
+}} />
+<Skeleton variant="text" level="title-md" sx={{
+  mb: 1
+}} />
+<Skeleton variant="text" level="body-sm" />
+<Skeleton variant="text" level="body-sm" width="60%" />
+<Stack direction="row" gap={1} sx={{
+  mt: 2
+}}>
+<Skeleton variant="rectangular" width={80} height={32} sx={{
+  borderRadius: 'sm'
+}} />
+<Skeleton variant="rectangular" width={80} height={32} sx={{
+  borderRadius: 'sm'
+}} />
+</Stack>
+</Box>
+```
+
+## Data Loading List
+
+Combine circular and text skeletons to represent list items during loading.
+
+```tsx
+<Stack gap={2} sx={{
+  width: 400
+}}>
+{[1, 2, 3].map(i => <Stack key={i} direction="row" gap={2} alignItems="center">
+<Skeleton variant="circular" width={40} height={40} />
+<Box sx={{
+  flex: 1
+}}>
+<Skeleton variant="text" level="title-sm" width="60%" />
+<Skeleton variant="text" level="body-xs" width="40%" />
+</Box>
+</Stack>)}
+</Stack>
+```
+
+## Inline Wrapping
+
+Wrap existing content with Skeleton to overlay it while loading. Set the `loading` prop to control visibility.
+
+```tsx
+<Typography level="body-md">
+  <Skeleton loading>
+    This text will be hidden behind a skeleton while loading.
+  </Skeleton>
+</Typography>
+```
+
+```tsx
+<Typography level="body-md">
+  <Skeleton loading>
+    This text will be hidden behind a skeleton while loading.
+  </Skeleton>
+</Typography>
+```
+
+## Common Use Cases
+
+### Page Content Loading
+
+```tsx
+function PageSkeleton() {
+  return (
+    <Stack gap={3}>
+      <Skeleton variant="text" level="h1" width="50%" />
+      <Skeleton variant="text" level="body-md" />
+      <Skeleton variant="text" level="body-md" />
+      <Skeleton variant="text" level="body-md" width="75%" />
+
+      <Skeleton variant="rectangular" width="100%" height={200} sx={{ borderRadius: 'sm' }} />
+
+      <Skeleton variant="text" level="body-md" />
+      <Skeleton variant="text" level="body-md" />
+    </Stack>
+  );
+}
+```
+
+### User List Loading
+
+```tsx
+function UserListSkeleton({ count = 5 }: { count?: number }) {
+  return (
+    <Stack gap={2}>
+      {Array.from({ length: count }).map((_, i) => (
+        <Stack key={i} direction="row" gap={2} alignItems="center">
+          <Skeleton variant="circular" width={40} height={40} />
+          <Box sx={{ flex: 1 }}>
+            <Skeleton variant="text" level="title-sm" width="40%" />
+            <Skeleton variant="text" level="body-xs" width="25%" />
+          </Box>
+        </Stack>
+      ))}
+    </Stack>
+  );
+}
+```
+
+### Conditional Rendering
+
+```tsx
+function UserProfile({ loading, user }: { loading: boolean; user?: User }) {
+  return (
+    <Stack direction="row" gap={2} alignItems="center">
+      {loading ? (
+        <Skeleton variant="circular" width={48} height={48} />
+      ) : (
+        <Avatar src={user?.avatar} />
+      )}
+      <Box>
+        <Typography level="title-md">
+          <Skeleton loading={loading}>{user?.name || 'Placeholder Name'}</Skeleton>
+        </Typography>
+        <Typography level="body-sm">
+          <Skeleton loading={loading}>{user?.email || 'email@example.com'}</Skeleton>
+        </Typography>
+      </Box>
+    </Stack>
+  );
+}
+```
+
+## Best Practices
+
+1. **Match the final layout**: Skeleton placeholders should closely approximate the size and position of the real content to prevent layout shifts.
+
+```tsx
+// ✅ Matches the actual content structure
+<Stack gap={1}>
+  <Skeleton variant="text" level="title-md" width="60%" />
+  <Skeleton variant="text" level="body-sm" />
+</Stack>
+
+// ❌ Generic rectangle that doesn't match
+<Skeleton variant="rectangular" width={300} height={100} />
+```
+
+2. **Use `variant="text"` with `level`**: When replacing Typography, use the text variant with the matching level to get accurate line heights.
+
+3. **Avoid over-skeletonizing**: Only skeleton the main content areas. Don't add skeletons for static elements like navigation or headers that are always present.
+
+4. **Use consistent animation**: Keep the same animation type (`wave` or `pulse`) across the entire application for a cohesive loading experience.
+
+5. **Set appropriate widths**: Vary skeleton widths (e.g., 60%, 80%, 100%) to mimic natural text line lengths rather than using uniform widths.
+
+## Accessibility
+
+- Skeleton elements are purely decorative. Screen readers should focus on the loading state announcement, not individual skeleton elements.
+- Use `aria-busy="true"` on the container element while content is loading.
+- Provide an `aria-label` or visually hidden text that describes the loading state (e.g., "Loading user profile").
+- Ensure the animation respects `prefers-reduced-motion` — Joy UI handles this automatically.

package/dist/components/feedback/llms.txt

@@ -3,8 +3,10 @@
 ## Documentation
 
 - [Alert](./Alert.md)
+- [CircularProgress](./CircularProgress.md)
 - [DialogFrame](./Dialog.md)
 - [Modal](./Modal.md)
+- [Skeleton](./Skeleton.md)
 
 ## Parent
 

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.