@ceed/cds 1.29.0 → 1.30.0

package/dist/components/layout/Box.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Box는 가장 기본적이고 중요한 레이아웃 컴포넌트입니다. 다른 컴포넌트들을 감싸는 범용 컨테이너 역할을 하며, CSS-in-JS를 통해 스타일을 직접 적용할 수 있습니다. Framer Motion이 내장되어 있어 애니메이션 효과도 쉽게 추가할 수 있습니다. 모든 HTML 요소로 변환 가능한 다형성(polymorphic) 컴포넌트이기도 합니다.
+Box is the most fundamental and essential layout component. It acts as a general-purpose container that wraps other components, and you can apply styles directly through CSS-in-JS. It also includes built-in Framer Motion support, making it easy to add animations. It is also a polymorphic component that can render as any HTML element.
 
 ```tsx
 <Box {...args} sx={{
@@ -48,7 +48,7 @@ function MyComponent() {
 
 ### Basic Usage
 
-가장 기본적인 Box 사용법입니다.
+The most basic way to use Box.
 
 ```tsx
 <div style={{
@@ -86,7 +86,7 @@ function MyComponent() {
 
 ### Colors
 
-다양한 배경색을 적용할 수 있습니다.
+You can apply various background colors.
 
 ```tsx
 <div style={{
@@ -138,7 +138,7 @@ function MyComponent() {
 
 ### Spacing
 
-패딩과 마진을 조절할 수 있습니다.
+You can adjust padding and margin.
 
 ```tsx
 <div style={{
@@ -215,7 +215,7 @@ function MyComponent() {
 
 ### Border Radius
 
-모서리 둥글기를 다양하게 설정할 수 있습니다.
+You can configure different corner radius values.
 
 ```tsx
 <div style={{
@@ -299,7 +299,7 @@ function MyComponent() {
 
 ### Shadows
 
-그림자 효과를 추가할 수 있습니다.
+You can add shadow effects.
 
 ```tsx
 <div style={{
@@ -390,7 +390,7 @@ function MyComponent() {
 
 ### Flex Layouts
 
-Flexbox를 사용한 레이아웃을 쉽게 만들 수 있습니다.
+You can easily build layouts using Flexbox.
 
 ```tsx
 <div style={{
@@ -499,7 +499,7 @@ Flexbox를 사용한 레이아웃을 쉽게 만들 수 있습니다.
 
 ### Responsive Layout
 
-반응형 레이아웃을 구현할 수 있습니다.
+You can create responsive layouts.
 
 ```tsx
 <div style={{
@@ -551,7 +551,7 @@ Flexbox를 사용한 레이아웃을 쉽게 만들 수 있습니다.
 
 ### Polymorphic Components
 
-component prop을 사용하여 다양한 HTML 요소로 렌더링할 수 있습니다.
+You can render it as different HTML elements using the `component` prop.
 
 ```tsx
 <div style={{
@@ -603,7 +603,7 @@ component prop을 사용하여 다양한 HTML 요소로 렌더링할 수 있습
 
 ### Motion Animations
 
-내장된 Framer Motion을 사용한 애니메이션 효과입니다.
+Animation effects using built-in Framer Motion.
 
 ```tsx
 <div style={{
@@ -655,7 +655,7 @@ component prop을 사용하여 다양한 HTML 요소로 렌더링할 수 있습
 
 ### Complex Layouts
 
-Box를 조합하여 복잡한 레이아웃을 만들 수 있습니다.
+You can combine Box components to build complex layouts.
 
 ```tsx
 <div style={{
@@ -790,17 +790,16 @@ Box를 조합하여 복잡한 레이아웃을 만들 수 있습니다.
 
 ### SX Prop
 
-Box의 가장 강력한 기능은 `sx` prop입니다. 이를 통해 CSS 스타일을 객체 형태로 직접 적용할 수 있습니다.
+The most powerful feature of Box is the `sx` prop. It allows you to apply CSS styles directly as an object.
 
 ```tsx
 <Box
   sx={{
-    p: 2, // padding: 16px
-    m: { xs: 1, md: 2 }, // 반응형 마진
-    bgcolor: 'primary.50', // 테마 색상
-    borderRadius: 'md', // 테마 border-radius
-    '&:hover': {
-      // hover 상태
+    p: 2,                    // padding: 16px
+    m: { xs: 1, md: 2 },     // responsive margin
+    bgcolor: 'primary.50',   // theme color
+    borderRadius: 'md',      // theme border-radius
+    '&:hover': {            // hover state
       bgcolor: 'primary.100',
     },
   }}
@@ -811,7 +810,7 @@ Box의 가장 강력한 기능은 `sx` prop입니다. 이를 통해 CSS 스타
 
 ### Responsive Design
 
-객체 구문을 사용해 브레이크포인트별 스타일을 지정할 수 있습니다.
+You can define styles per breakpoint using object syntax.
 
 ```tsx
 <Box
@@ -827,7 +826,7 @@ Box의 가장 강력한 기능은 `sx` prop입니다. 이를 통해 CSS 스타
 
 ### Theme Integration
 
-디자인 시스템의 토큰을 직접 사용할 수 있습니다.
+You can use design system tokens directly.
 
 ```tsx
 <Box
@@ -844,7 +843,7 @@ Box의 가장 강력한 기능은 `sx` prop입니다. 이를 통해 CSS 스타
 
 ### Framer Motion
 
-애니메이션 props를 직접 사용할 수 있습니다.
+You can use animation props directly.
 
 ```tsx
 <Box
@@ -908,7 +907,7 @@ Box의 가장 강력한 기능은 `sx` prop입니다. 이를 통해 CSS 스타
     gap: 2,
   }}
 >
-  {items.map((item) => (
+  {items.map(item => (
     <Box key={item.id} sx={{ p: 2, bgcolor: 'background.surface' }}>
       {item.content}
     </Box>
@@ -948,34 +947,46 @@ Box의 가장 강력한 기능은 `sx` prop입니다. 이를 통해 CSS 스타
 </Box>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop        | Type          | Default | Description                        |
+| ----------- | ------------- | ------- | ---------------------------------- |
+| `children`  | `ReactNode`   | -       | Content inside the box             |
+| `component` | `ElementType` | `'div'` | Root element type                  |
+| `sx`        | `SxProps`     | -       | Custom styles using the MUI system |
+
+Box is a general-purpose container that renders as a `<div>` by default. It accepts all standard HTML attributes and Joy UI's `sx` prop for responsive styling.
+
 ## Best Practices
 
-1. **의미 있는 HTML 요소 사용**: `component` prop을 활용해 의미론적으로 올바른 HTML 요소를 선택하세요.
+1. **Use meaningful HTML elements**: Use the `component` prop to choose semantically appropriate HTML elements.
 
-2. **테마 토큰 활용**: 하드코딩된 값 대신 테마의 spacing, color, border-radius 등을 사용하세요.
+2. **Use theme tokens**: Use theme spacing, color, border-radius, and similar values instead of hardcoded values.
 
-3. **반응형 고려**: 다양한 화면 크기에서 잘 동작하도록 반응형 값을 사용하세요.
+3. **Design responsively**: Use responsive values so the component works well across different screen sizes.
 
-4. **성능 최적화**:
-   - 인라인 객체 생성을 피하고 가능하면 객체를 메모화하세요
-   - 복잡한 애니메이션은 필요할 때만 사용하세요
+4. **Optimize performance**:
+   - Avoid creating inline objects repeatedly, and memoize them when possible
+   - Use complex animations only when necessary
 
-5. **접근성**:
-   - 적절한 semantic HTML 요소를 선택하세요
-   - 필요시 ARIA 속성을 추가하세요
-   - 충분한 색상 대비를 유지하세요
+5. **Consider accessibility**:
+   - Choose appropriate semantic HTML elements
+   - Add ARIA attributes when needed
+   - Maintain sufficient color contrast
 
-6. **재사용성**:
-   - 자주 사용하는 스타일 조합은 별도 컴포넌트로 분리하세요
-   - 공통 스타일은 테마에 정의하세요
+6. **Promote reusability**:
+   - Extract frequently used style combinations into separate components
+   - Define shared styles in the theme
 
-7. **일관성**:
-   - 팀 내에서 일관된 spacing과 naming convention을 사용하세요
-   - 디자인 시스템의 가이드라인을 따르세요
+7. **Maintain consistency**:
+   - Use consistent spacing and naming conventions across the team
+   - Follow the design system guidelines
 
 ## Spacing Scale
 
-Box에서 사용할 수 있는 spacing 값들:
+Spacing values available in Box:
 
 - `0.5` = 4px
 - `1` = 8px
@@ -988,11 +999,11 @@ Box에서 사용할 수 있는 spacing 값들:
 
 ## Color Tokens
 
-주요 색상 토큰들:
+Primary color tokens:
 
 - **Background**: `background.body`, `background.surface`, `background.level1`
 - **Primary**: `primary.50`, `primary.100`, `primary.500`, `primary.main`
 - **Neutral**: `neutral.50`, `neutral.100`, `neutral.500`, `neutral.main`
 - **Text**: `text.primary`, `text.secondary`, `text.tertiary`
 
-Box는 ADS의 모든 레이아웃과 스타일링의 기초가 되는 컴포넌트입니다. 강력한 sx prop과 내장된 애니메이션 기능을 활용해 다양한 UI 요구사항을 충족할 수 있습니다.
+Box is the foundational component for all layout and styling in ADS. Its powerful `sx` prop and built-in animation support make it flexible enough to satisfy a wide range of UI requirements.

package/dist/components/layout/Grid.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Grid 컴포넌트는 CSS Grid를 기반으로 한 강력한 레이아웃 시스템입니다. 12열 그리드 시스템을 사용하여 반응형 레이아웃을 쉽게 구현할 수 있으며, 다양한 브레이크포인트에서 다른 레이아웃을 적용할 수 있습니다. 복잡한 대시보드, 제품 카탈로그, 카드 레이아웃 등 다양한 용도로 활용할 수 있습니다.
+The Grid component is a powerful layout system built on CSS Grid. It uses a 12-column grid system, making it easy to create responsive layouts and apply different layouts at different breakpoints. It is well suited for complex dashboards, product catalogs, card layouts, and more.
 
 ```tsx
 <Grid container spacing={args.spacing}>
@@ -57,7 +57,7 @@ function MyComponent() {
 
 ### Basic Usage
 
-12열 그리드 시스템의 기본 사용법입니다.
+The basic usage of the 12-column grid system.
 
 ```tsx
 <div style={{
@@ -89,7 +89,7 @@ function MyComponent() {
 
 ### Responsive Grid
 
-다양한 화면 크기에서 다른 레이아웃을 적용하는 반응형 그리드입니다.
+A responsive grid that applies different layouts across different screen sizes.
 
 ```tsx
 <div>
@@ -137,7 +137,7 @@ function MyComponent() {
 
 ### Different Spacing
 
-다양한 간격을 적용한 그리드 레이아웃입니다.
+Grid layouts with different spacing values.
 
 ```tsx
 <div style={{
@@ -201,7 +201,7 @@ function MyComponent() {
 
 ### Nested Grid
 
-그리드 안에 또 다른 그리드를 중첩하여 사용할 수 있습니다.
+You can nest one grid inside another.
 
 ```tsx
 <div>
@@ -265,7 +265,7 @@ function MyComponent() {
 
 ### Auto Layout
 
-자동 레이아웃을 사용한 그리드입니다.
+A grid using auto layout.
 
 ```tsx
 <div style={{
@@ -309,7 +309,7 @@ function MyComponent() {
 
 ### Complex Layouts
 
-실제 사용 사례를 보여주는 복잡한 레이아웃 예제입니다.
+Complex layout examples based on real use cases.
 
 ```tsx
 <div style={{
@@ -435,7 +435,7 @@ function MyComponent() {
 
 ### Breakpoint Demo
 
-각 브레이크포인트에서 어떻게 동작하는지 보여주는 예제입니다.
+An example showing how Grid behaves at each breakpoint.
 
 ```tsx
 <div>
@@ -491,61 +491,49 @@ function MyComponent() {
 
 ## Grid System
 
-### 12열 시스템
+### 12-Column System
 
-Grid는 12열 시스템을 기반으로 합니다. 각 아이템은 1-12열을 차지할 수 있습니다.
+Grid is based on a 12-column system. Each item can span 1 to 12 columns.
 
 ```tsx
 <Grid container spacing={2}>
-  <Grid item xs={12}>
-    전체 너비 (12/12)
-  </Grid>
-  <Grid item xs={6}>
-    절반 너비 (6/12)
-  </Grid>
-  <Grid item xs={6}>
-    절반 너비 (6/12)
-  </Grid>
-  <Grid item xs={4}>
-    3분의 1 너비 (4/12)
-  </Grid>
-  <Grid item xs={4}>
-    3분의 1 너비 (4/12)
-  </Grid>
-  <Grid item xs={4}>
-    3분의 1 너비 (4/12)
-  </Grid>
+  <Grid item xs={12}>전체 너비 (12/12)</Grid>
+  <Grid item xs={6}>절반 너비 (6/12)</Grid>
+  <Grid item xs={6}>절반 너비 (6/12)</Grid>
+  <Grid item xs={4}>3분의 1 너비 (4/12)</Grid>
+  <Grid item xs={4}>3분의 1 너비 (4/12)</Grid>
+  <Grid item xs={4}>3분의 1 너비 (4/12)</Grid>
 </Grid>
 ```
 
 ### Container & Item
 
-- `container`: Grid 컨테이너를 만들 때 사용
-- `item`: Grid 아이템을 만들 때 사용
-- 한 컴포넌트가 동시에 container와 item이 될 수 있습니다 (중첩 그리드)
+- `container`: Used to create a Grid container
+- `item`: Used to create a Grid item
+- A single component can be both a `container` and an `item` at the same time (nested grid)
 
 ## Breakpoints
 
-Grid는 다음 브레이크포인트를 지원합니다:
+Grid supports the following breakpoints:
 
-| 브레이크포인트 | 크기      | 설명                |
-| ------- | ------- | ----------------- |
-| `xs`    | 0px+    | 모바일 (세로)          |
-| `sm`    | 600px+  | 모바일 (가로) / 작은 태블릿 |
-| `md`    | 900px+  | 태블릿               |
-| `lg`    | 1200px+ | 데스크톱              |
-| `xl`    | 1536px+ | 큰 데스크톱            |
+| Breakpoint | Size    | Description                       |
+| ---------- | ------- | --------------------------------- |
+| `xs`       | 0px+    | Mobile (portrait)                 |
+| `sm`       | 600px+  | Mobile (landscape) / small tablet |
+| `md`       | 900px+  | Tablet                            |
+| `lg`       | 1200px+ | Desktop                           |
+| `xl`       | 1536px+ | Large desktop                     |
 
-### 반응형 사용법
+### Responsive Usage
 
 ```tsx
 <Grid container spacing={2}>
   <Grid item xs={12} sm={6} md={4} lg={3}>
     {/*
-      xs: 100% (12/12) - 모바일에서 전체 너비
-      sm: 50% (6/12)   - 작은 화면에서 절반 너비
-      md: 33% (4/12)   - 태블릿에서 3분의 1 너비
-      lg: 25% (3/12)   - 데스크톱에서 4분의 1 너비
+      xs: 100% (12/12) - full width on mobile
+      sm: 50% (6/12)   - half width on small screens
+      md: 33% (4/12)   - one-third width on tablets
+      lg: 25% (3/12)   - one-quarter width on desktop
     */}
     반응형 아이템
   </Grid>
@@ -554,21 +542,21 @@ Grid는 다음 브레이크포인트를 지원합니다:
 
 ## Spacing
 
-`spacing` prop을 사용하여 그리드 아이템 간의 간격을 조절할 수 있습니다.
+You can control the spacing between grid items using the `spacing` prop.
 
-| 값   | 크기   | 설명          |
-| --- | ---- | ----------- |
-| `0` | 0px  | 간격 없음       |
-| `1` | 8px  | 아주 작은 간격    |
-| `2` | 16px | 작은 간격 (기본값) |
-| `3` | 24px | 중간 간격       |
-| `4` | 32px | 큰 간격        |
-| `5` | 40px | 아주 큰 간격     |
-| `6` | 48px | 최대 간격       |
+| Value | Size | Description             |
+| ----- | ---- | ----------------------- |
+| `0`   | 0px  | No spacing              |
+| `1`   | 8px  | Very small spacing      |
+| `2`   | 16px | Small spacing (default) |
+| `3`   | 24px | Medium spacing          |
+| `4`   | 32px | Large spacing           |
+| `5`   | 40px | Very large spacing      |
+| `6`   | 48px | Maximum spacing         |
 
 ## Auto Layout
 
-열 수를 명시하지 않고 자동으로 배치되도록 할 수 있습니다:
+You can let items size and position automatically without explicitly defining the column count:
 
 ```tsx
 <Grid container spacing={2}>
@@ -664,9 +652,7 @@ Grid는 다음 브레이크포인트를 지원합니다:
   </Grid>
 
   <Grid item xs={12}>
-    <Button type="submit" fullWidth>
-      Submit
-    </Button>
+    <Button type="submit" fullWidth>Submit</Button>
   </Grid>
 </Grid>
 ```
@@ -680,7 +666,7 @@ Grid는 다음 브레이크포인트를 지원합니다:
       <Box
         sx={{
           position: 'relative',
-          paddingTop: '100%', // 1:1 비율 유지
+          paddingTop: '100%', // maintain a 1:1 ratio
           overflow: 'hidden',
           borderRadius: 'sm',
         }}
@@ -705,38 +691,58 @@ Grid는 다음 브레이크포인트를 지원합니다:
 
 ## Best Practices
 
-1. **의미 있는 구조**: Grid를 사용할 때 HTML의 의미구조를 고려하여 적절한 요소를 선택하세요.
+1. **Use meaningful structure**: Choose appropriate elements while considering semantic HTML structure when using Grid.
+
+2. **Design responsively first**: Start with mobile layouts and scale up to larger screens.
+
+3. **Keep spacing consistent**: Use consistent spacing values across the project.
+
+4. **Optimize performance**:
+   - Avoid unnecessarily deep nesting
+   - Consider virtualization when rendering many items
+
+5. **Consider accessibility**:
+   - Use appropriate semantic tags
+   - Arrange content so keyboard navigation remains logical
 
-2. **반응형 우선 설계**: 모바일부터 시작하여 큰 화면으로 확장하는 방식으로 설계하세요.
+6. **Prioritize content**: Let the grid adapt to the content instead of forcing content into the grid.
 
-3. **일관된 간격**: 프로젝트 전반에서 일관된 spacing 값을 사용하세요.
+7. **Debug effectively**: Apply background colors to Grid items during development to inspect the layout more easily.
 
-4. **성능 최적화**:
-   - 불필요하게 깊은 중첩은 피하세요
-   - 많은 아이템이 있을 때는 가상화를 고려하세요
+## Props and Customization
 
-5. **접근성**:
-   - 적절한 시맨틱 태그를 사용하세요
-   - 키보드 탐색이 논리적으로 이뤄지도록 배치하세요
+### Key Props
 
-6. **콘텐츠 우선**: 그리드가 콘텐츠를 억지로 맞추는 것이 아니라 콘텐츠에 맞춰 조정되도록 하세요.
+| Prop        | Type                                                     | Default | Description                          |
+| ----------- | -------------------------------------------------------- | ------- | ------------------------------------ |
+| `children`  | `ReactNode`                                              | -       | Grid children (items)                |
+| `container` | `boolean`                                                | `false` | Sets the element as a grid container |
+| `xs`        | `number \| 'auto' \| boolean`                            | -       | Column span at xs breakpoint         |
+| `sm`        | `number \| 'auto' \| boolean`                            | -       | Column span at sm breakpoint         |
+| `md`        | `number \| 'auto' \| boolean`                            | -       | Column span at md breakpoint         |
+| `lg`        | `number \| 'auto' \| boolean`                            | -       | Column span at lg breakpoint         |
+| `xl`        | `number \| 'auto' \| boolean`                            | -       | Column span at xl breakpoint         |
+| `spacing`   | `number \| string`                                       | `0`     | Gap between grid items               |
+| `direction` | `'row' \| 'row-reverse' \| 'column' \| 'column-reverse'` | `'row'` | Flex direction                       |
+| `columns`   | `number`                                                 | `12`    | Total number of columns              |
+| `sx`        | `SxProps`                                                | -       | Custom styles                        |
 
-7. **디버깅**: 개발 중에는 Grid 아이템에 배경색을 적용해 레이아웃을 쉽게 확인하세요.
+> **Note**: Grid accepts all Joy UI Grid (MUI) props.
 
 ## Troubleshooting
 
-### 흔한 문제들
+### Common Issues
 
-1. **아이템이 예상과 다르게 배치됨**
-   - 12를 넘지 않도록 열 수를 확인하세요
-   - container와 item props가 올바르게 설정되었는지 확인하세요
+1. **Items are positioned differently than expected**
+   - Check that the total column count does not exceed 12
+   - Make sure the `container` and `item` props are set correctly
 
-2. **간격이 적용되지 않음**
-   - container에 spacing prop이 설정되었는지 확인하세요
-   - 자식 요소들이 Grid item으로 감싸져 있는지 확인하세요
+2. **Spacing is not applied**
+   - Verify that the `spacing` prop is set on the container
+   - Verify that child elements are wrapped in Grid items
 
-3. **반응형이 동작하지 않음**
-   - 브레이크포인트 값이 올바른지 확인하세요
-   - 각 브레이크포인트에서 의도한 합계가 12 이하인지 확인하세요
+3. **Responsive behavior is not working**
+   - Check that the breakpoint values are correct
+   - Make sure the intended total at each breakpoint is 12 or less
 
-Grid는 복잡한 레이아웃을 구현하는 강력한 도구입니다. 반응형 디자인과 일관된 간격을 통해 사용자 경험을 향상시킬 수 있습니다.
+Grid is a powerful tool for building complex layouts. Responsive design and consistent spacing help improve the overall user experience.