@ceed/cds 1.29.0 → 1.30.0

package/dist/components/layout/Stack.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Stack 컴포넌트는 자식 요소들을 하나의 차원(수직 또는 수평)에서 일정한 간격으로 배치하는 레이아웃 컴포넌트입니다. Flexbox를 기반으로 하여 간단하고 직관적인 API로 복잡한 레이아웃을 쉽게 구현할 수 있습니다. 내비게이션 바, 폼 레이아웃, 카드 내부 구조 등 다양한 UI 패턴에서 활용됩니다.
+The Stack component is a layout component that arranges child elements in one dimension, either vertically or horizontally, with consistent spacing. Built on Flexbox, it provides a simple and intuitive API for creating complex layouts with ease. It is useful across many UI patterns, including navigation bars, form layouts, and card internals.
 
 ```tsx
 <Stack {...args}>
@@ -39,7 +39,7 @@ function MyComponent() {
 
 ### Basic Usage
 
-세로(column)와 가로(row) 배치의 기본 사용법입니다.
+The basic usage for vertical (`column`) and horizontal (`row`) layouts.
 
 ```tsx
 <div style={{
@@ -77,7 +77,7 @@ function MyComponent() {
 
 ### Directions
 
-다양한 배치 방향을 사용할 수 있습니다.
+You can use different layout directions.
 
 ```tsx
 <div style={{
@@ -146,7 +146,7 @@ function MyComponent() {
 
 ### Different Spacing
 
-다양한 간격을 적용할 수 있습니다.
+You can apply different spacing values.
 
 ```tsx
 <div style={{
@@ -210,7 +210,7 @@ function MyComponent() {
 
 ### Alignment
 
-요소들의 정렬을 다양하게 조절할 수 있습니다.
+You can control element alignment in different ways.
 
 ```tsx
 <div style={{
@@ -279,7 +279,7 @@ function MyComponent() {
 
 ### Responsive Direction
 
-화면 크기에 따라 배치 방향을 변경할 수 있습니다.
+You can change the layout direction based on screen size.
 
 ```tsx
 <div>
@@ -337,7 +337,7 @@ function MyComponent() {
 
 ### Nested Stacks
 
-Stack을 중첩하여 더 복잡한 레이아웃을 만들 수 있습니다.
+You can nest Stack components to build more complex layouts.
 
 ```tsx
 <div>
@@ -395,7 +395,7 @@ Stack을 중첩하여 더 복잡한 레이아웃을 만들 수 있습니다.
 
 ### Real World Examples
 
-실제 사용 사례를 보여주는 예제들입니다.
+Examples that demonstrate real-world use cases.
 
 ```tsx
 <div style={{
@@ -640,7 +640,7 @@ Stack을 중첩하여 더 복잡한 레이아웃을 만들 수 있습니다.
 
 ### direction
 
-요소들의 배치 방향을 설정합니다.
+Sets the layout direction of the elements.
 
 ```tsx
 <Stack direction="row">가로 배치</Stack>
@@ -648,7 +648,7 @@ Stack을 중첩하여 더 복잡한 레이아웃을 만들 수 있습니다.
 <Stack direction="row-reverse">가로 역순</Stack>
 <Stack direction="column-reverse">세로 역순</Stack>
 
-// 반응형 방향
+// responsive direction
 <Stack direction={{ xs: 'column', sm: 'row' }}>
   반응형 배치
 </Stack>
@@ -656,26 +656,26 @@ Stack을 중첩하여 더 복잡한 레이아웃을 만들 수 있습니다.
 
 ### spacing
 
-요소들 간의 간격을 설정합니다.
+Sets the spacing between elements.
 
-| 값     | 크기   | 설명          |
-| ----- | ---- | ----------- |
-| `0`   | 0px  | 간격 없음       |
-| `0.5` | 4px  | 아주 작은 간격    |
-| `1`   | 8px  | 작은 간격       |
-| `1.5` | 12px | 작은-중간 간격    |
-| `2`   | 16px | 중간 간격 (기본값) |
-| `3`   | 24px | 큰 간격        |
-| `4`   | 32px | 아주 큰 간격     |
-| `5`   | 40px | 매우 큰 간격     |
-| `6`   | 48px | 최대 간격       |
+| Value | Size | Description              |
+| ----- | ---- | ------------------------ |
+| `0`   | 0px  | No spacing               |
+| `0.5` | 4px  | Very small spacing       |
+| `1`   | 8px  | Small spacing            |
+| `1.5` | 12px | Small-to-medium spacing  |
+| `2`   | 16px | Medium spacing (default) |
+| `3`   | 24px | Large spacing            |
+| `4`   | 32px | Very large spacing       |
+| `5`   | 40px | Extra large spacing      |
+| `6`   | 48px | Maximum spacing          |
 
 ```tsx
 <Stack spacing={2}>기본 간격</Stack>
 <Stack spacing={0}>간격 없음</Stack>
 <Stack spacing={4}>큰 간격</Stack>
 
-// 반응형 간격
+// responsive spacing
 <Stack spacing={{ xs: 1, sm: 2, md: 3 }}>
   반응형 간격
 </Stack>
@@ -683,7 +683,7 @@ Stack을 중첩하여 더 복잡한 레이아웃을 만들 수 있습니다.
 
 ### alignItems
 
-교차축(cross axis) 정렬을 설정합니다.
+Sets alignment along the cross axis.
 
 ```tsx
 <Stack alignItems="center">중앙 정렬</Stack>
@@ -695,7 +695,7 @@ Stack을 중첩하여 더 복잡한 레이아웃을 만들 수 있습니다.
 
 ### justifyContent
 
-주축(main axis) 정렬을 설정합니다.
+Sets alignment along the main axis.
 
 ```tsx
 <Stack justifyContent="center">중앙 정렬</Stack>
@@ -707,7 +707,7 @@ Stack을 중첩하여 더 복잡한 레이아웃을 만들 수 있습니다.
 
 ## Responsive Behavior
 
-Stack은 모든 props에서 반응형 값을 지원합니다:
+Stack supports responsive values for all props:
 
 ```tsx
 <Stack
@@ -715,7 +715,7 @@ Stack은 모든 props에서 반응형 값을 지원합니다:
   spacing={{ xs: 1, sm: 2, md: 3 }}
   alignItems={{ xs: 'stretch', md: 'center' }}
 >
-  {/* 화면 크기별로 다른 레이아웃 */}
+  {/* different layouts for different screen sizes */}
 </Stack>
 ```
 
@@ -724,7 +724,12 @@ Stack은 모든 props에서 반응형 값을 지원합니다:
 ### Navigation Bar
 
 ```tsx
-<Stack direction="row" justifyContent="space-between" alignItems="center" sx={{ p: 2 }}>
+<Stack
+  direction="row"
+  justifyContent="space-between"
+  alignItems="center"
+  sx={{ p: 2 }}
+>
   <Typography level="title-lg">Logo</Typography>
   <Stack direction="row" spacing={2}>
     <Button variant="plain">Home</Button>
@@ -776,21 +781,17 @@ Stack은 모든 props에서 반응형 값을 지원합니다:
         <Chip variant="soft">New</Chip>
       </Stack>
 
-      <Typography level="body-md">Product description goes here...</Typography>
+      <Typography level="body-md">
+        Product description goes here...
+      </Typography>
 
       <Stack direction="row" spacing={1}>
-        <Chip size="sm" variant="outlined">
-          Tag 1
-        </Chip>
-        <Chip size="sm" variant="outlined">
-          Tag 2
-        </Chip>
+        <Chip size="sm" variant="outlined">Tag 1</Chip>
+        <Chip size="sm" variant="outlined">Tag 2</Chip>
       </Stack>
 
       <Stack direction="row" justifyContent="space-between" alignItems="center">
-        <Typography level="title-lg" color="primary">
-          $99.99
-        </Typography>
+        <Typography level="title-lg" color="primary">$99.99</Typography>
         <Button>Add to Cart</Button>
       </Stack>
     </Stack>
@@ -812,7 +813,9 @@ Stack은 모든 props에서 반응형 값을 지원합니다:
     </Stack>
   </Stack>
 
-  <Typography level="body-md">Passionate about creating great user experiences...</Typography>
+  <Typography level="body-md">
+    Passionate about creating great user experiences...
+  </Typography>
 
   <Stack direction="row" spacing={1}>
     <Chip variant="soft">React</Chip>
@@ -821,9 +824,7 @@ Stack은 모든 props에서 반응형 값을 지원합니다:
   </Stack>
 
   <Stack direction="row" spacing={2}>
-    <Button variant="outlined" fullWidth>
-      Follow
-    </Button>
+    <Button variant="outlined" fullWidth>Follow</Button>
     <Button fullWidth>Message</Button>
   </Stack>
 </Stack>
@@ -884,53 +885,72 @@ Stack은 모든 props에서 반응형 값을 지원합니다:
 
 ## Best Practices
 
-1. **적절한 간격**: 콘텐츠의 계층구조에 맞는 적절한 spacing을 선택하세요.
+1. **Choose appropriate spacing**: Use spacing values that match the content hierarchy.
 
-2. **반응형 고려**: 다양한 화면 크기에서 잘 작동하도록 반응형 props를 활용하세요.
+2. **Design responsively**: Use responsive props so layouts work well across different screen sizes.
 
-3. **의미있는 정렬**: alignItems와 justifyContent를 사용해 의미있는 정렬을 적용하세요.
+3. **Use meaningful alignment**: Use `alignItems` and `justifyContent` to create intentional alignment.
 
-4. **중첩 최소화**: 과도한 중첩은 피하고, 필요한 경우에만 Stack을 중첩하세요.
+4. **Minimize nesting**: Avoid excessive nesting and only nest Stack when it is actually needed.
 
-5. **성능 고려**: 많은 아이템이 있는 경우 가상화를 고려하세요.
+5. **Consider performance**: Use virtualization when rendering many items.
 
-6. **접근성**:
-   - 논리적인 탭 순서가 되도록 요소를 배치하세요
-   - 적절한 시맨틱 태그와 함께 사용하세요
+6. **Consider accessibility**:
+   - Arrange elements to preserve a logical tab order
+   - Use appropriate semantic tags alongside Stack
 
-7. **일관성**: 프로젝트 전반에서 일관된 spacing 값을 사용하세요.
+7. **Maintain consistency**: Use consistent spacing values across the project.
 
 ## When to Use Stack vs Other Layout Components
 
 ### Stack vs Flexbox (Box)
 
-- **Stack**: 단순한 1차원 레이아웃, 일정한 간격이 필요한 경우
-- **Box with flex**: 복잡한 flexbox 속성이 필요한 경우
+- **Stack**: For simple one-dimensional layouts with consistent spacing
+- **Box with flex**: For cases that need more complex Flexbox behavior
 
 ### Stack vs Grid
 
-- **Stack**: 1차원 레이아웃 (세로 또는 가로)
-- **Grid**: 2차원 레이아웃 (행과 열)
+- **Stack**: One-dimensional layouts (vertical or horizontal)
+- **Grid**: Two-dimensional layouts (rows and columns)
 
 ### Stack vs Space (if available)
 
-- **Stack**: 컨테이너와 간격을 함께 제공
-- **Space**: 간격만 제공 (자식들 사이에)
+- **Stack**: Provides both a container and spacing
+- **Space**: Provides spacing only (between children)
+
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                     | Default    | Description                               |
+| ---------------- | -------------------------------------------------------- | ---------- | ----------------------------------------- |
+| `children`       | `ReactNode`                                              | -          | Stack children                            |
+| `direction`      | `'row' \| 'row-reverse' \| 'column' \| 'column-reverse'` | `'column'` | Flex direction                            |
+| `spacing`        | `number \| string`                                       | `0`        | Gap between children                      |
+| `alignItems`     | `string`                                                 | -          | CSS align-items                           |
+| `justifyContent` | `string`                                                 | -          | CSS justify-content                       |
+| `flexWrap`       | `'nowrap' \| 'wrap' \| 'wrap-reverse'`                   | `'nowrap'` | Flex wrapping behavior                    |
+| `divider`        | `ReactNode`                                              | -          | Element inserted between each child       |
+| `component`      | `ElementType`                                            | `'div'`    | Root element type                         |
+| `useFlexGap`     | `boolean`                                                | `false`    | Use CSS gap instead of margin for spacing |
+| `sx`             | `SxProps`                                                | -          | Custom styles                             |
+
+> **Note**: Stack accepts all Joy UI Stack props.
 
 ## Troubleshooting
 
-### 흔한 문제들
+### Common Issues
 
-1. **간격이 적용되지 않음**
-   - 자식 요소들이 직접적인 자식인지 확인하세요
-   - Fragment나 다른 래퍼가 방해하지 않는지 확인하세요
+1. **Spacing is not applied**
+   - Make sure the elements are direct children
+   - Check whether a Fragment or another wrapper is interfering
 
-2. **정렬이 예상과 다름**
-   - direction에 따라 주축과 교차축이 바뀐다는 점을 기억하세요
-   - alignItems와 justifyContent의 차이를 이해하세요
+2. **Alignment is different from what you expected**
+   - Remember that the main axis and cross axis change based on `direction`
+   - Understand the difference between `alignItems` and `justifyContent`
 
-3. **반응형이 동작하지 않음**
-   - 객체 문법 `{ xs: 'column', md: 'row' }`가 올바른지 확인하세요
-   - 브레이크포인트 값이 올바른지 확인하세요
+3. **Responsive behavior is not working**
+   - Check that object syntax like `{ xs: 'column', md: 'row' }` is correct
+   - Verify that the breakpoint values are correct
 
-Stack은 직관적이고 강력한 레이아웃 도구입니다. 간단한 API로 복잡한 레이아웃을 쉽게 구현할 수 있어 많은 UI 패턴에서 활용됩니다.
+Stack is an intuitive and powerful layout tool. Its simple API makes complex layouts easy to build, so it fits a wide range of UI patterns.

package/dist/components/navigation/Breadcrumbs.md

@@ -67,6 +67,14 @@ function MyComponent() {
 
 ## Features
 
+### Basic Breadcrumbs
+
+A simple breadcrumb trail with a few levels of hierarchy. The last item uses `type: 'text'` to indicate the current page.
+
+```
+<Canvas of={Breadcrumbs.BasicExample} />
+```
+
 ### Sizes
 
 Breadcrumbs are available in three sizes -- `sm`, `md`, and `lg` -- allowing you to match the surrounding layout density.
@@ -83,39 +91,16 @@ Breadcrumbs are available in three sizes -- `sm`, `md`, and `lg` -- allowing you
 
 The separator character between items can be customized via the `separator` prop. Common choices include `/`, `>`, and `-`.
 
-```tsx
-<Breadcrumbs
-  crumbs={[{
-  label: 'Home',
-  type: 'link',
-  linkHref: '/'
-}, {
-  label: 'Catalog',
-  type: 'link',
-  linkHref: '/'
-}, {
-  label: 'Category',
-  type: 'link',
-  linkHref: '/'
-}, {
-  label: 'Subcategory',
-  type: 'link',
-  linkHref: '/'
-}, {
-  label: 'Product',
-  type: 'link',
-  linkHref: '/'
-}, {
-  label: 'Product Detail',
-  type: 'link',
-  linkHref: '/'
-}, {
-  label: 'Owner',
-  type: 'text'
-}]}
-  collapsed
-  separator="-"
-/>
+```
+<Canvas of={Breadcrumbs.CustomSeparator} />
+```
+
+### Collapsed Breadcrumbs
+
+When paths are deep, the component automatically collapses middle items behind an ellipsis. You can control how many items appear at the start and end using `startCrumbCount` and `endCrumbCount`.
+
+```
+<Canvas of={Breadcrumbs.CollapsedVariants} />
 ```
 
 ### Expanded View
@@ -170,42 +155,55 @@ The component handles the edge case of a single breadcrumb item gracefully.
 />
 ```
 
+### With Icons
+
+Breadcrumb items can include icons alongside their labels.
+
+```
+<Canvas of={Breadcrumbs.WithIcons} />
+```
+
 ## Common Use Cases
 
-### Service Detail Page
+### Admin Dashboard Navigation
 
 ```tsx
-function ServiceDetailPage({ service, category }) {
+function UserDetailPage({ user }) {
   const crumbs = [
-    { label: 'Home', type: 'link', linkHref: '/' },
-    { label: 'Services', type: 'link', linkHref: '/services' },
-    { label: category.name, type: 'link', linkHref: `/services/${category.slug}` },
-    { label: service.name, type: 'text' },
+    { label: 'Dashboard', type: 'link', linkHref: '/admin' },
+    { label: 'Users', type: 'link', linkHref: '/admin/users' },
+    { label: user.name, type: 'text' },
   ];
 
   return (
     <Box>
       <Breadcrumbs crumbs={crumbs} />
-      <ServiceDetails service={service} />
+      <UserProfile user={user} />
     </Box>
   );
 }
 ```
 
-### Account Settings
+### E-commerce Product Page
 
 ```tsx
-function AccountSettingsPage() {
+function ProductPage({ product, category, subcategory }) {
   const crumbs = [
     { label: 'Home', type: 'link', linkHref: '/' },
-    { label: 'Account', type: 'link', linkHref: '/account' },
-    { label: 'Settings', type: 'text' },
+    { label: 'Shop', type: 'link', linkHref: '/shop' },
+    { label: category.name, type: 'link', linkHref: `/shop/${category.slug}` },
+    {
+      label: subcategory.name,
+      type: 'link',
+      linkHref: `/shop/${category.slug}/${subcategory.slug}`,
+    },
+    { label: product.name, type: 'text' },
   ];
 
   return (
     <Box>
-      <Breadcrumbs crumbs={crumbs} size="sm" />
-      <SettingsForm />
+      <Breadcrumbs crumbs={crumbs} collapsed={true} startCrumbCount={1} endCrumbCount={2} />
+      <ProductDetails product={product} />
     </Box>
   );
 }
@@ -231,6 +229,19 @@ function DynamicBreadcrumbs() {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop              | Type                                                             | Default                          | Description                                          |
+| ----------------- | ---------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------- |
+| `crumbs`          | `{ type: 'text' \| 'link'; label: string; linkHref?: string }[]` | (required)                       | Breadcrumb items                                     |
+| `collapsed`       | `boolean`                                                        | `true`                           | Whether long crumb lists are collapsed with ellipsis |
+| `startCrumbCount` | `number`                                                         | `1`                              | Number of crumbs shown at the start when collapsed   |
+| `endCrumbCount`   | `number`                                                         | `3`                              | Number of crumbs shown at the end when collapsed     |
+| `slots`           | `{ link?: ElementType }`                                         | -                                | Custom component for link crumbs                     |
+| `slotProps`       | `{ link?: { color?: string } }`                                  | `{ link: { color: 'neutral' } }` | Props passed to slot components                      |
+
 ## Best Practices
 
 - **Always start with a root item.** Begin the trail with "Home" or an equivalent top-level link so users can always navigate back to the starting point.

package/dist/components/navigation/Drawer.md

@@ -161,6 +161,23 @@ function FormDrawer({ open, onClose, onSubmit }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop       | Type                                                           | Default                          | Description                                                                |                                                                                |
+| ---------- | -------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `children` | `ReactNode`                                                    | -                                | Content rendered inside the drawer panel                                   |                                                                                |
+| `open`     | `boolean`                                                      | `false`                          | Controls whether the drawer is visible                                     |                                                                                |
+| `onClose`  | \`(event: React.SyntheticEvent                                 | Event, reason: string) => void\` | -                                                                          | Called when the drawer requests to close, such as backdrop click or Escape key |
+| `anchor`   | `'left' \| 'right' \| 'top' \| 'bottom'`                       | `'left'`                         | Edge of the screen from which the drawer slides in                         |                                                                                |
+| `size`     | `'sm' \| 'md' \| 'lg'`                                         | `'md'`                           | Preset drawer size used to control width or height depending on the anchor |                                                                                |
+| `variant`  | `'plain' \| 'soft' \| 'outlined' \| 'solid'`                   | `'plain'`                        | Visual style inherited from Joy UI Drawer                                  |                                                                                |
+| `color`    | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`                      | Color scheme inherited from Joy UI Drawer                                  |                                                                                |
+| `sx`       | `SxProps`                                                      | -                                | Custom styles using the MUI system                                         |                                                                                |
+
+> **Note**: Drawer also accepts Joy UI `DrawerProps` and Framer Motion props because the component is a thin wrapper around Joy UI Drawer with motion support.
+
 ## Best Practices
 
 1. **Choose the right size**: Use `sm` (360px) for simple navigation, `md` (600px) for moderate content, and `lg` (900px) for complex detail views or forms.

package/dist/components/navigation/Dropdown.md

@@ -583,6 +583,19 @@ const [open, setOpen] = useState(false);
 </Button>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                             | Default | Description                          |
+| -------------- | -------------------------------- | ------- | ------------------------------------ |
+| `children`     | `ReactNode`                      | -       | Dropdown content (MenuButton + Menu) |
+| `open`         | `boolean`                        | -       | Controlled open state                |
+| `defaultOpen`  | `boolean`                        | `false` | Initial open state (uncontrolled)    |
+| `onOpenChange` | `(event, open: boolean) => void` | -       | Callback when open state changes     |
+
+> **Note**: Dropdown accepts all Joy UI Dropdown props. It is a state management wrapper — style props go on Menu and MenuButton.
+
 ## Best Practices
 
 - **Use the right abstraction level.** If you only need a simple list of text items, prefer `MenuButton` or `IconMenuButton` standalone components. Use `Dropdown` + `Menu` when you need dividers, custom headers, or mixed content inside the menu.

package/dist/components/navigation/IconMenuButton.md

@@ -225,6 +225,23 @@ function EditorToolbar({ onAction }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop                   | Type                                                                   | Default     | Description                                  |
+| ---------------------- | ---------------------------------------------------------------------- | ----------- | -------------------------------------------- |
+| `icon`                 | `ReactNode`                                                            | (required)  | Icon element to render in the trigger button |
+| `items`                | `{ text: string; component?: ElementType; componentProps?: object }[]` | -           | Menu items                                   |
+| `size`                 | `'sm' \| 'md' \| 'lg'`                                                 | `'md'`      | Button size                                  |
+| `color`                | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'`         | `'neutral'` | Button color                                 |
+| `variant`              | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                           | `'plain'`   | Button visual style                          |
+| `disabled`             | `boolean`                                                              | `false`     | Disables the button                          |
+| `loading`              | `boolean`                                                              | `false`     | Shows loading indicator                      |
+| `placement`            | `Placement`                                                            | `'bottom'`  | Menu position                                |
+| `buttonComponent`      | `ElementType`                                                          | -           | Custom trigger element                       |
+| `buttonComponentProps` | `object`                                                               | -           | Props passed to custom trigger               |
+
 ## Best Practices
 
 - **Always provide `aria-label`.** Since IconMenuButton has no visible text, screen readers rely entirely on the `aria-label` to announce the button's purpose. Include context when possible.