@ceed/cds 1.29.0 → 1.30.0

package/dist/Overview.md

@@ -1,11 +1,11 @@
 # CDS (Customer Design System)
 
-CDS는 Customer Design System의 약자로, 유려한 UI를 중심으로 두는 시스템으로 개발되었습니다. 이 시스템은 사용자 친화적인 경험을 제공하고, 개발 및 디자인 프로세스를 효율화하기 위해 제작되었습니다.
+CDS stands for Customer Design System, and it was developed as a system centered around polished UI. It was created to provide a user-friendly experience and streamline development and design processes.
 
-이 디자인시스템은 [JoyUI](https://mui.com/joy-ui/getting-started/)를 기반으로 하므로 대부분 [JoyUI](https://mui.com/joy-ui/getting-started/)의 문서를 참고할 수 있지만, 일부 컴포넌트는 추상화 레이어가 추가되어 인터페이스가 다를 수 있습니다.
+This design system is built on [JoyUI](https://mui.com/joy-ui/getting-started/), so you can refer to the [JoyUI](https://mui.com/joy-ui/getting-started/) documentation for most cases, although some components may have different interfaces due to added abstraction layers.
 
-데이터 중심보다는 시각적이고 직관적인 UI를 목적으로 이름이 지어졌으며 주로 고객이 사용하는 UI에 적용됩니다.
+It is named for UIs that prioritize visual and intuitive experiences over data-centric interfaces, and it is mainly applied to customer-facing UI.
 
-## 문서 및 가이드
+## Documentation and Guides
 
-CDS에 대한 자세한 내용은 [Design System 문서](https://ecubelabs.atlassian.net/wiki/spaces/HP/pages/3256123430/Design+System)를 참조하세요.
+For more information about CDS, refer to the [Design System documentation](https://ecubelabs.atlassian.net/wiki/spaces/HP/pages/3256123430/Design+System).

package/dist/components/Calendar/utils/index.d.ts

@@ -3,6 +3,7 @@ export declare const getYearName: (date: Date, locale: string) => string;
 export declare const getMonthName: (date: Date, locale: string, options?: {
     hideYear?: boolean;
 }) => string;
+export declare const getShortMonthName: (date: Date, locale: string) => string;
 export declare const getMonthNameFromIndex: (index: number, locale: string) => string;
 /**
  * 일~토 / Sun ~ Sat 같은 요일 이름을 가져옵니다.

package/dist/components/DatePicker/DatePicker.d.ts

@@ -36,6 +36,10 @@ interface BaseDatePickerProps {
      * Input 에 표시되는 값의 포맷을 지정한다.
      */
     displayFormat?: string;
+    /**
+     * 월 이름 표시에 사용할 locale (예: 'en-US', 'ko-KR'). MMM/MMMM 토큰 사용 시 적용된다.
+     */
+    locale?: string;
     inputReadOnly?: boolean;
     hideClearButton?: boolean;
     /**

package/dist/components/DateRangePicker/DateRangePicker.d.ts

@@ -36,6 +36,10 @@ interface BaseDateRangePickerProps {
      * Input 에 표시되는 값의 포맷을 지정한다.
      */
     displayFormat?: string;
+    /**
+     * 월 이름 표시에 사용할 locale (예: 'en-US', 'ko-KR'). MMM/MMMM 토큰 사용 시 적용된다.
+     */
+    locale?: string;
     inputReadOnly?: boolean;
     hideClearButton?: boolean;
     /**

package/dist/components/MonthRangePicker/MonthRangePicker.d.ts

@@ -20,6 +20,14 @@ interface BaseMonthRangePickerProps {
     disableFuture?: boolean;
     disablePast?: boolean;
     format?: string;
+    /**
+     * Input 에 표시되는 값의 포맷을 지정한다.
+     */
+    displayFormat?: string;
+    /**
+     * 월 이름 표시에 사용할 locale (예: 'en-US', 'ko-KR'). MMM/MMMM 토큰 사용 시 적용된다.
+     */
+    locale?: string;
 }
 export type MonthRangePickerProps = BaseMonthRangePickerProps & Omit<React.ComponentProps<typeof Input>, 'onChange' | 'value' | 'defaultValue'>;
 declare const MonthRangePicker: React.ForwardRefExoticComponent<Omit<MonthRangePickerProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/data-display/Avatar.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Avatar 컴포넌트는 사용자의 프로필 이미지, 이니셜 또는 아이콘을 표시하는 컴포넌트입니다. Joy UI의 Avatar를 기반으로 하며, 다양한 크기, 색상, 변형을 지원합니다. 사용자 인터페이스에서 개인을 시각적으로 나타내거나 그룹, 브랜드를 표현하는 데 사용됩니다.
+The Avatar component displays a user's profile image, initials, or icon. It is based on Joy UI Avatar and supports various sizes, colors, and variants. It is used to visually represent individuals, groups, or brands in a user interface.
 
 ```tsx
 <Avatar alt="User avatar" />
@@ -25,13 +25,13 @@ import { Avatar } from '@ceed/cds';
 function MyComponent() {
   return (
     <div>
-      {/* 이미지가 있는 아바타 */}
+      {/* Avatar with an image */}
       <Avatar src="/path/to/image.jpg" alt="사용자 이름" />
 
-      {/* 이니셜 아바타 */}
+      {/* Initials avatar */}
       <Avatar>김철수</Avatar>
 
-      {/* 단일 문자 아바타 */}
+      {/* Single-character avatar */}
       <Avatar>김</Avatar>
     </div>
   );
@@ -42,7 +42,7 @@ function MyComponent() {
 
 ### Basic Usage
 
-가장 기본적인 Avatar 사용법입니다.
+The most basic Avatar usage.
 
 ```tsx
 <Avatar alt="User avatar" />
@@ -50,7 +50,7 @@ function MyComponent() {
 
 ### With Image
 
-이미지를 사용한 아바타입니다.
+An avatar that uses an image.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -60,7 +60,7 @@ function MyComponent() {
 
 ### With Text
 
-텍스트나 이니셜을 사용한 아바타입니다.
+An avatar that uses text or initials.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -72,7 +72,7 @@ function MyComponent() {
 
 ### Variants
 
-다양한 시각적 스타일을 적용할 수 있습니다.
+You can apply various visual styles.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -80,14 +80,14 @@ function MyComponent() {
 </Stack>
 ```
 
-- **solid**: 배경색이 채워진 스타일
-- **soft**: 부드러운 배경색 스타일
-- **outlined**: 테두리만 있는 스타일
-- **plain**: 최소한의 스타일
+- **solid**: A style with a filled background color
+- **soft**: A style with a soft background color
+- **outlined**: A style with only a border
+- **plain**: A minimal style
 
 ### Sizes
 
-다양한 크기의 아바타를 사용할 수 있습니다.
+You can use avatars in various sizes.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -97,14 +97,14 @@ function MyComponent() {
 </Stack>
 ```
 
-- **xs**: 매우 작은 크기 (16px)
-- **sm**: 작은 크기 (24px)
-- **md**: 중간 크기 (32px, 기본값)
-- **lg**: 큰 크기 (40px)
+- **xs**: Extra small size (16px)
+- **sm**: Small size (24px)
+- **md**: Medium size (32px, default)
+- **lg**: Large size (40px)
 
 ### Colors
 
-다양한 색상 테마를 적용할 수 있습니다.
+You can apply various color themes.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -112,15 +112,15 @@ function MyComponent() {
 </Stack>
 ```
 
-- **primary**: 주요 브랜드 색상
-- **neutral**: 중립적인 회색톤
-- **danger**: 경고나 오류를 나타내는 빨간색
-- **success**: 성공을 나타내는 녹색
-- **warning**: 주의를 나타내는 주황색
+- **primary**: Primary brand color
+- **neutral**: Neutral gray tone
+- **danger**: Red for warnings or errors
+- **success**: Green for success
+- **warning**: Orange for caution
 
 ### All Combinations
 
-모든 변형, 크기, 색상 조합을 확인할 수 있습니다.
+You can review all variant, size, and color combinations.
 
 ```tsx
 <Stack gap={8}>
@@ -150,11 +150,15 @@ function MyComponent() {
 
 ### User Profile
 
-사용자 프로필에서 아바타를 사용하는 경우입니다.
+An example of using an avatar in a user profile.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
-  <Avatar src="/user-profile.jpg" alt="김철수" size="lg" />
+  <Avatar
+    src="/user-profile.jpg"
+    alt="김철수"
+    size="lg"
+  />
   <Stack>
     <Typography level="title-md">김철수</Typography>
     <Typography level="body-sm" color="neutral">
@@ -166,7 +170,7 @@ function MyComponent() {
 
 ### Navigation Bar
 
-네비게이션 바에서 현재 사용자를 표시할 때 사용합니다.
+Used to display the current user in a navigation bar.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center" sx={{ ml: 'auto' }}>
@@ -182,7 +186,7 @@ function MyComponent() {
 
 ### Comment System
 
-댓글이나 피드에서 사용자를 나타낼 때 사용합니다.
+Used to represent a user in comments or feeds.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -196,14 +200,16 @@ function MyComponent() {
         2시간 전
       </Typography>
     </Stack>
-    <Typography level="body-md">이것은 사용자의 댓글 내용입니다.</Typography>
+    <Typography level="body-md">
+      이것은 사용자의 댓글 내용입니다.
+    </Typography>
   </Stack>
 </Stack>
 ```
 
 ### Team Members
 
-팀 구성원 목록을 표시할 때 사용합니다.
+Used to display a list of team members.
 
 ```tsx
 <Stack spacing={3}>
@@ -211,7 +217,13 @@ function MyComponent() {
 
   {teamMembers.map((member) => (
     <Stack key={member.id} direction="row" spacing={2} alignItems="center">
-      <Avatar src={member.avatar} alt={member.name} size="md" variant="soft" color="primary">
+      <Avatar
+        src={member.avatar}
+        alt={member.name}
+        size="md"
+        variant="soft"
+        color="primary"
+      >
         {member.name.charAt(0)}
       </Avatar>
       <Stack flex={1}>
@@ -230,19 +242,13 @@ function MyComponent() {
 
 ### Avatar Groups
 
-여러 사용자를 그룹으로 표시할 때 사용합니다.
+Used to display multiple users as a group.
 
 ```tsx
 <Stack direction="row" spacing={-1}>
-  <Avatar size="sm" variant="solid" color="primary">
-    김
-  </Avatar>
-  <Avatar size="sm" variant="solid" color="success">
-    이
-  </Avatar>
-  <Avatar size="sm" variant="solid" color="warning">
-    박
-  </Avatar>
+  <Avatar size="sm" variant="solid" color="primary">김</Avatar>
+  <Avatar size="sm" variant="solid" color="success">이</Avatar>
+  <Avatar size="sm" variant="solid" color="warning">박</Avatar>
   <Avatar size="sm" variant="outlined" color="neutral">
     <Typography level="body-xs">+3</Typography>
   </Avatar>
@@ -251,7 +257,7 @@ function MyComponent() {
 
 ### Status Indicators
 
-사용자 상태를 함께 표시할 때 사용합니다.
+Used to display user status alongside the avatar.
 
 ```tsx
 <Box sx={{ position: 'relative', display: 'inline-block' }}>
@@ -274,7 +280,7 @@ function MyComponent() {
 
 ### Empty State
 
-데이터가 없을 때 플레이스홀더로 사용합니다.
+Used as a placeholder when no data is available.
 
 ```tsx
 <Stack alignItems="center" spacing={2}>
@@ -292,7 +298,7 @@ function MyComponent() {
 
 ### List Items
 
-리스트 아이템에서 사용자나 항목을 표현할 때 사용합니다.
+Used to represent users or items in list items.
 
 ```tsx
 <List>
@@ -318,72 +324,107 @@ function MyComponent() {
 
 ### Fallback Behavior
 
-이미지 로드가 실패했을 때 자동으로 이니셜이나 아이콘으로 대체됩니다.
+If image loading fails, it automatically falls back to initials or an icon.
 
 ```tsx
-<Avatar src="/broken-image-url.jpg" alt="김철수" color="primary" variant="soft">
+<Avatar
+  src="/broken-image-url.jpg"
+  alt="김철수"
+  color="primary"
+  variant="soft"
+>
   김
 </Avatar>
 ```
 
 ### Loading States
 
-이미지 로딩 중에는 children이 표시되다가 이미지 로드 완료 후 이미지로 전환됩니다.
+While the image is loading, `children` are shown first, then the image is displayed once loading completes.
 
 ```tsx
-<Avatar src="/slow-loading-image.jpg" alt="사용자" color="neutral" variant="soft">
+<Avatar
+  src="/slow-loading-image.jpg"
+  alt="사용자"
+  color="neutral"
+  variant="soft"
+>
   <PersonIcon />
 </Avatar>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop         | Type                                                           | Default         | Description                                     |
+| ------------ | -------------------------------------------------------------- | --------------- | ----------------------------------------------- |
+| `src`        | `string`                                                       | -               | Image URL for the avatar                        |
+| `alt`        | `string`                                                       | -               | Alt text for the avatar image                   |
+| `children`   | `ReactNode`                                                    | -               | Fallback content (text, icon) when no image     |
+| `getInitial` | `(name: string) => string`                                     | First character | Custom function to extract initials from a name |
+| `size`       | `'sm' \| 'md' \| 'lg'`                                         | `'md'`          | Avatar size                                     |
+| `variant`    | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'soft'`        | Visual style                                    |
+| `color`      | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`     | Color scheme                                    |
+| `sx`         | `SxProps`                                                      | -               | Custom styles using the MUI system              |
+
+> **Note**: Avatar also accepts all Joy UI Avatar props and Framer Motion props.
+
 ## Accessibility
 
-Avatar 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
+Avatar provides the following accessibility features:
 
 ### Image Alt Text
 
-이미지 아바타의 경우 적절한 alt 텍스트를 제공해야 합니다.
+For image avatars, provide appropriate alt text.
 
 ```tsx
-<Avatar src="/user-profile.jpg" alt="김철수의 프로필 사진" />
+<Avatar
+  src="/user-profile.jpg"
+  alt="김철수의 프로필 사진"
+/>
 ```
 
 ### Semantic Meaning
 
-아바타가 단순히 장식적 목적이 아닌 의미를 가질 때는 적절한 역할을 제공하세요.
+If the avatar carries meaning rather than serving a purely decorative purpose, provide an appropriate role.
 
 ```tsx
-<Avatar src="/user-avatar.jpg" alt="현재 사용자" role="img" aria-label="현재 로그인한 사용자의 프로필 이미지" />
+<Avatar
+  src="/user-avatar.jpg"
+  alt="현재 사용자"
+  role="img"
+  aria-label="현재 로그인한 사용자의 프로필 이미지"
+/>
 ```
 
 ### Color Contrast
 
-텍스트 아바타의 경우 충분한 색상 대비를 유지하세요.
+For text avatars, maintain sufficient color contrast.
 
 ```tsx
-// 좋은 대비를 제공하는 색상 조합
+// Color combinations that provide good contrast
 <Avatar variant="solid" color="primary">김</Avatar>
 <Avatar variant="soft" color="neutral">이</Avatar>
 ```
 
 ## Best Practices
 
-1. **적절한 크기 선택**: 사용 맥락에 맞는 적절한 크기를 선택하세요.
+1. **Choose an appropriate size**: Select a size that fits the usage context.
 
 ```tsx
-// ✅ 적절한 크기 사용
-<Avatar size="sm">김</Avatar>  // 리스트 아이템에서
-<Avatar size="lg">김</Avatar>  // 프로필 페이지에서
+// ✅ Appropriate size usage
+<Avatar size="sm">김</Avatar>  // In a list item
+<Avatar size="lg">김</Avatar>  // On a profile page
 
-// ❌ 부적절한 크기 사용
-<Avatar size="lg">김</Avatar>  // 네비게이션 바에서 (너무 큼)
+// ❌ Inappropriate size usage
+<Avatar size="lg">김</Avatar>  // In a navigation bar (too large)
 ```
 
-2. **일관된 스타일**: 같은 컨텍스트에서는 일관된 변형과 색상을 사용하세요.
+2. **Consistent styling**: Use consistent variants and colors within the same context.
 
-3. **이미지 최적화**: 아바타 이미지는 적절한 크기로 최적화하여 사용하세요.
+3. **Optimize images**: Use avatar images optimized to an appropriate size.
 
-4. **폴백 제공**: 이미지가 없거나 로드 실패 시를 대비해 적절한 폴백을 제공하세요.
+4. **Provide a fallback**: Prepare an appropriate fallback for missing or failed image loads.
 
 ```tsx
 <Avatar src={user.avatar} alt={user.name} color="primary" variant="soft">
@@ -391,14 +432,14 @@ Avatar 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
 </Avatar>
 ```
 
-5. **의미적 사용**: 아바타가 누구를 나타내는지 명확하게 식별할 수 있어야 합니다.
+5. **Meaningful usage**: It should be clear whom the avatar represents.
 
 ## Performance Considerations
 
-1. **이미지 최적화**: 아바타 이미지는 작은 크기로 최적화하여 로딩 속도를 향상시키세요.
+1. **Image optimization**: Optimize avatar images to a small size to improve loading speed.
 
-2. **Lazy Loading**: 많은 아바타가 있는 페이지에서는 지연 로딩을 고려하세요.
+2. **Lazy Loading**: Consider lazy loading on pages with many avatars.
 
-3. **캐싱**: 자주 사용되는 아바타 이미지는 적절히 캐싱하세요.
+3. **Caching**: Cache frequently used avatar images appropriately.
 
-Avatar는 사용자 인터페이스에서 개인을 시각적으로 나타내는 중요한 컴포넌트입니다. 적절한 크기, 색상, 변형을 선택하여 일관되고 접근 가능한 사용자 경험을 제공할 수 있습니다.
+Avatar is an important component for visually representing people in a user interface. By choosing the right size, color, and variant, you can provide a consistent and accessible user experience.