@ceed/ads 1.29.1 → 1.30.1

package/dist/Overview.md

@@ -1,11 +1,11 @@
 # ADS (Admin Design System)
 
-ADS는 Admin Design System의 약자로, 컴포넌트 기반의 UI 디자인 시스템입니다. 이 시스템은 일관된 사용자 경험을 제공하고, 개발 및 디자인 프로세스를 효율화하기 위해 제작되었습니다.
+ADS stands for Admin Design System, a component-based UI design system. It was created to provide a consistent user 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 intended for data-centric administrative dashboards and applications, and it can be applied not only to internal services but also to customer-facing UIs.
 
-## 문서 및 가이드
+## Documentation and Guides
 
-ADS에 대한 자세한 내용은 [Design System 문서](https://ecubelabs.atlassian.net/wiki/spaces/HP/pages/3256123430/Design+System)를 참조하세요.
+For more information about ADS, refer to the [Design System documentation](https://ecubelabs.atlassian.net/wiki/spaces/HP/pages/3256123430/Design+System).

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

@@ -1,5 +1,11 @@
 import React from 'react';
 import Input from '../Input';
+export interface DatePickerPreset {
+    /** 프리셋 버튼에 표시할 라벨 */
+    label: string;
+    /** 컴포넌트의 format에 맞는 날짜 문자열 (예: "2026/04/03") */
+    value: string;
+}
 interface BaseDatePickerProps {
     /**
      * props.format 의 형식을 따라야 한다.
@@ -39,6 +45,10 @@ interface BaseDatePickerProps {
      * @returns If `true` the date will be disabled
      */
     shouldDisableDate?: (date: string) => boolean;
+    /**
+     * 달력 옆에 표시할 프리셋 목록. 각 항목의 value는 format prop의 형식을 따라야 한다.
+     */
+    presets?: DatePickerPreset[];
 }
 export type DatePickerProps = BaseDatePickerProps & Omit<React.ComponentProps<typeof Input>, 'onChange' | 'value' | 'defaultValue'>;
 declare const DatePicker: React.ForwardRefExoticComponent<Omit<DatePickerProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

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

@@ -1,5 +1,11 @@
 import React from 'react';
 import Input from '../Input';
+export interface DateRangePickerPreset {
+    /** 프리셋 버튼에 표시할 라벨 */
+    label: string;
+    /** 컴포넌트의 format에 맞는 날짜 범위 문자열 (예: "2026/03/31 - 2026/04/03") */
+    value: string;
+}
 interface BaseDateRangePickerProps {
     /**
      * props.format 의 형식을 따라야 한다.
@@ -32,6 +38,10 @@ interface BaseDateRangePickerProps {
     displayFormat?: string;
     inputReadOnly?: boolean;
     hideClearButton?: boolean;
+    /**
+     * 달력 옆에 표시할 프리셋 목록. 각 항목의 value는 format prop의 형식을 따라야 한다.
+     */
+    presets?: DateRangePickerPreset[];
 }
 export type DateRangePickerProps = BaseDateRangePickerProps & Omit<React.ComponentProps<typeof Input>, 'onChange' | 'value' | 'defaultValue'>;
 declare const DateRangePicker: React.ForwardRefExoticComponent<Omit<DateRangePickerProps, "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,32 +25,30 @@ import { Avatar } from '@ceed/ads';
 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>
   );
 }
 ```
 
-## Examples
+## Avatar Basic Usage
 
-### Basic Usage
-
-가장 기본적인 Avatar 사용법입니다.
+The most basic Avatar usage.
 
 ```tsx
 <Avatar alt="User avatar" />
 ```
 
-### With Image
+## Avatar With Image
 
-이미지를 사용한 아바타입니다.
+An avatar that uses an image.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -58,9 +56,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### With Text
+## Avatar With Text
 
-텍스트나 이니셜을 사용한 아바타입니다.
+An avatar that uses text or initials.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -68,11 +66,9 @@ function MyComponent() {
 </Stack>
 ```
 
-## Customization
-
-### Variants
+## Avatar Variants
 
-다양한 시각적 스타일을 적용할 수 있습니다.
+You can apply various visual styles.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -80,14 +76,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
+## Avatar Sizes
 
-다양한 크기의 아바타를 사용할 수 있습니다.
+You can use avatars in various sizes.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -97,14 +93,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
+## Avatar Colors
 
-다양한 색상 테마를 적용할 수 있습니다.
+You can apply various color themes.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -112,15 +108,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
+## Avatar All Combinations
 
-모든 변형, 크기, 색상 조합을 확인할 수 있습니다.
+You can review all variant, size, and color combinations.
 
 ```tsx
 <Stack gap={8}>
@@ -146,11 +142,9 @@ function MyComponent() {
 </Stack>
 ```
 
-## Common Use Cases
+## Avatar User Profile
 
-### User Profile
-
-사용자 프로필에서 아바타를 사용하는 경우입니다.
+An example of using an avatar in a user profile.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -168,9 +162,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### Navigation Bar
+## Avatar Navigation Bar
 
-네비게이션 바에서 현재 사용자를 표시할 때 사용합니다.
+Used to display the current user in a navigation bar.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center" sx={{ ml: 'auto' }}>
@@ -184,9 +178,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### Comment System
+## Avatar Comment System
 
-댓글이나 피드에서 사용자를 나타낼 때 사용합니다.
+Used to represent a user in comments or feeds.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -207,9 +201,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### Team Members
+## Avatar Team Members
 
-팀 구성원 목록을 표시할 때 사용합니다.
+Used to display a list of team members.
 
 ```tsx
 <Stack spacing={3}>
@@ -240,9 +234,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### Avatar Groups
+## Avatar Groups
 
-여러 사용자를 그룹으로 표시할 때 사용합니다.
+Used to display multiple users as a group.
 
 ```tsx
 <Stack direction="row" spacing={-1}>
@@ -255,9 +249,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### Status Indicators
+## Avatar Status Indicators
 
-사용자 상태를 함께 표시할 때 사용합니다.
+Used to display user status alongside the avatar.
 
 ```tsx
 <Box sx={{ position: 'relative', display: 'inline-block' }}>
@@ -278,9 +272,9 @@ function MyComponent() {
 </Box>
 ```
 
-### Empty State
+## Avatar Empty State
 
-데이터가 없을 때 플레이스홀더로 사용합니다.
+Used as a placeholder when no data is available.
 
 ```tsx
 <Stack alignItems="center" spacing={2}>
@@ -296,9 +290,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### List Items
+## Avatar List Items
 
-리스트 아이템에서 사용자나 항목을 표현할 때 사용합니다.
+Used to represent users or items in list items.
 
 ```tsx
 <List>
@@ -324,7 +318,7 @@ function MyComponent() {
 
 ### Fallback Behavior
 
-이미지 로드가 실패했을 때 자동으로 이니셜이나 아이콘으로 대체됩니다.
+If image loading fails, it automatically falls back to initials or an icon.
 
 ```tsx
 <Avatar
@@ -339,7 +333,7 @@ function MyComponent() {
 
 ### Loading States
 
-이미지 로딩 중에는 children이 표시되다가 이미지 로드 완료 후 이미지로 전환됩니다.
+While the image is loading, `children` are shown first, then the image is displayed once loading completes.
 
 ```tsx
 <Avatar
@@ -352,13 +346,30 @@ function MyComponent() {
 </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
@@ -369,7 +380,7 @@ Avatar 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
 
 ### Semantic Meaning
 
-아바타가 단순히 장식적 목적이 아닌 의미를 가질 때는 적절한 역할을 제공하세요.
+If the avatar carries meaning rather than serving a purely decorative purpose, provide an appropriate role.
 
 ```tsx
 <Avatar
@@ -382,32 +393,32 @@ Avatar 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
 
 ### 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">
@@ -415,14 +426,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.

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

@@ -274,9 +274,7 @@ By default, Badge hides when `badgeContent` is `0`. Use the `showZero` prop to f
 </div>
 ```
 
-## Common Use Cases
-
-### Notification Bell
+## Badge Notification Bell
 
 ```tsx
 import { Badge, IconButton } from '@ceed/ads';
@@ -293,7 +291,7 @@ function NotificationBell({ unreadCount }) {
 }
 ```
 
-### Online Status on Avatar
+## Badge Online Status on Avatar
 
 ```tsx
 import { Badge, Avatar } from '@ceed/ads';
@@ -311,7 +309,7 @@ function UserAvatar({ name, avatarUrl, isOnline }) {
 }
 ```
 
-### New Feature Label
+## Badge New Feature Label
 
 ```tsx
 import { Badge, Button } from '@ceed/ads';
@@ -339,6 +337,26 @@ function FeatureButton() {
 
 - **Do not badge everything.** Only add badges to elements where the count or status information is genuinely useful. Overuse diminishes their attention-grabbing effect.
 
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                                                             | Default                                    | Description                                                           |
+| -------------- | ---------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| `badgeContent` | `ReactNode`                                                      | -                                          | Content displayed inside the badge (number, text). Omit for dot badge |
+| `children`     | `ReactNode`                                                      | -                                          | The element the badge is attached to                                  |
+| `color`        | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'`   | `'danger'`                                 | Badge color                                                           |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                           | `'md'`                                     | Badge size                                                            |
+| `variant`      | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                     | `'solid'`                                  | Visual style                                                          |
+| `max`          | `number`                                                         | `99`                                       | Maximum value before showing "N+"                                     |
+| `invisible`    | `boolean`                                                        | `false`                                    | Hides the badge                                                       |
+| `showZero`     | `boolean`                                                        | `false`                                    | Shows badge when value is 0                                           |
+| `anchorOrigin` | `{ vertical: 'top' \| 'bottom'; horizontal: 'left' \| 'right' }` | `{ vertical: 'top', horizontal: 'right' }` | Badge position                                                        |
+| `badgeInset`   | `string`                                                         | -                                          | Custom inset for badge positioning                                    |
+| `sx`           | `SxProps`                                                        | -                                          | Custom styles using the MUI system                                    |
+
+> **Note**: Badge also accepts all Joy UI Badge props.
+
 ## Accessibility
 
 - Badge automatically applies `aria-label` or equivalent attributes so screen readers can announce the badge content alongside the wrapped element.