@ceed/cds 1.29.0 → 1.30.0

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

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-Badge 컴포넌트는 다른 UI 요소 위에 작은 카운트, 상태, 또는 레이블을 표시하는 데 사용됩니다. 주로 알림 수, 상태 표시기, 또는 새로운 콘텐츠를 나타내는 데 활용됩니다.
+Badge is a small visual indicator that overlays another UI element to display a count, status, or label. It is commonly used to show unread notification counts, online/offline status indicators, and "NEW" labels on menu items or navigation elements. The Badge wraps a child component (such as an icon button or avatar) and positions itself in the top-right corner by default.
+
+Badge supports multiple colors, variants, and sizes for flexible visual customization. It also provides utility features like a `max` prop for truncating large numbers (e.g., "99+"), a `showZero` prop for controlling zero-count visibility, and a dot-only mode when no `badgeContent` is provided.
 
 ```tsx
 <Badge {...args}>
@@ -26,7 +28,7 @@ Badge 컴포넌트는 다른 UI 요소 위에 작은 카운트, 상태, 또는
 
 ```tsx
 import { Badge, IconButton } from '@ceed/cds';
-import { NotificationsIcon } from '@mui/icons-material';
+import NotificationsIcon from '@mui/icons-material/Notifications';
 
 function MyComponent() {
   return (
@@ -39,11 +41,9 @@ function MyComponent() {
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Basic
 
-기본적인 Badge 사용법입니다.
+Basic Badge usage showing numeric counts, max overflow, and text content.
 
 ```tsx
 <div style={{
@@ -70,9 +70,9 @@ function MyComponent() {
 </div>
 ```
 
-### Colors
+## Colors
 
-다양한 색상을 적용할 수 있습니다.
+Apply semantic colors to convey the badge's meaning: `primary` for general counts, `danger` for urgent notifications, `success` for online status, and `warning` for attention items.
 
 ```tsx
 <div style={{
@@ -111,9 +111,9 @@ function MyComponent() {
 </div>
 ```
 
-### Variants
+## Variants
 
-다양한 스타일 변형을 제공합니다.
+Four style variants are available: `solid` (filled), `soft` (subtle background), `outlined` (border only), and `plain` (minimal).
 
 ```tsx
 <div style={{
@@ -146,9 +146,9 @@ function MyComponent() {
 </div>
 ```
 
-### Sizes
+## Sizes
 
-크기를 조절할 수 있습니다.
+Three sizes -- `sm`, `md`, and `lg` -- allow the badge to scale proportionally with its wrapped element.
 
 ```tsx
 <div style={{
@@ -176,9 +176,9 @@ function MyComponent() {
 </div>
 ```
 
-### With Avatar
+## With Avatar
 
-아바타와 함께 사용할 수 있습니다.
+Badge pairs naturally with Avatar to indicate user status (e.g., notification count or online indicator).
 
 ```tsx
 <div style={{
@@ -195,9 +195,9 @@ function MyComponent() {
 </div>
 ```
 
-### Dot Badge
+## Dot Badge
 
-내용 없이 점으로만 표시할 수 있습니다.
+When no `badgeContent` is provided, Badge renders as a small dot. This is useful for simple presence or status indicators without a specific count.
 
 ```tsx
 <div style={{
@@ -216,9 +216,9 @@ function MyComponent() {
 </div>
 ```
 
-### Max Count
+## Max Count
 
-최대 카운트를 설정하여 숫자가 넘을 때 '+' 표시를 할 수 있습니다.
+Use the `max` prop to cap the displayed number. When `badgeContent` exceeds `max`, it renders as "max+" (e.g., "99+").
 
 ```tsx
 <div style={{
@@ -245,9 +245,9 @@ function MyComponent() {
 </div>
 ```
 
-### Show Zero
+## Show Zero
 
-기본적으로 0일 때는 숨겨지지만, showZero 옵션으로 표시할 수 있습니다.
+By default, Badge hides when `badgeContent` is `0`. Use the `showZero` prop to force it to remain visible.
 
 ```tsx
 <div style={{
@@ -276,40 +276,92 @@ function MyComponent() {
 
 ## Common Use Cases
 
-### Notification Count
+### Notification Bell
 
 ```tsx
-<Badge badgeContent={unreadCount} color="danger">
-  <IconButton>
-    <NotificationsIcon />
-  </IconButton>
-</Badge>
+import { Badge, IconButton } from '@ceed/cds';
+import NotificationsIcon from '@mui/icons-material/Notifications';
+
+function NotificationBell({ unreadCount }) {
+  return (
+    <Badge badgeContent={unreadCount} max={99} color="danger">
+      <IconButton aria-label={`${unreadCount} unread notifications`}>
+        <NotificationsIcon />
+      </IconButton>
+    </Badge>
+  );
+}
 ```
 
-### Status Indicator
+### Online Status on Avatar
 
 ```tsx
-<Badge color="success" variant="solid">
-  <Avatar src="/user-avatar.jpg" />
-</Badge>
+import { Badge, Avatar } from '@ceed/cds';
+
+function UserAvatar({ name, avatarUrl, isOnline }) {
+  return (
+    <Badge
+      color={isOnline ? 'success' : 'neutral'}
+      variant="solid"
+      anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+    >
+      <Avatar src={avatarUrl} alt={name} />
+    </Badge>
+  );
+}
 ```
 
-### New Items
+### New Feature Label
 
 ```tsx
-<Badge badgeContent="NEW" color="warning">
-  <Button>메뉴</Button>
-</Badge>
+import { Badge, Button } from '@ceed/cds';
+
+function FeatureButton() {
+  return (
+    <Badge badgeContent="NEW" color="warning" size="sm">
+      <Button variant="outlined">Analytics</Button>
+    </Badge>
+  );
+}
 ```
 
 ## Best Practices
 
-1. **의미 있는 색상**: 색상은 의미를 가지도록 사용하세요 (빨간색은 중요한 알림, 초록색은 성공 상태 등).
+- **Use semantic colors consistently.** Reserve `danger` for urgent notifications, `success` for positive status (e.g., online), `warning` for attention-needed items, and `primary` for neutral counts.
+  - ✔ `color="danger"` for unread message count
+  - ✘ `color="primary"` for critical alert count
+
+- **Set a `max` value for numeric badges.** Avoid displaying very large numbers like "1,247" in a tiny badge. Use `max={99}` or `max={999}` to keep the badge compact and readable.
+
+- **Keep badge content short.** Badges work best with numbers (1-3 digits) or very short text ("NEW", "HOT"). Long text will overflow and look broken.
+
+- **Use dot badges for binary states.** When the specific count does not matter (e.g., "has unread items" vs. "12 unread items"), use a dot badge by omitting `badgeContent`.
+
+- **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
 
-2. **적절한 콘텐츠**: 너무 긴 텍스트는 피하고, 숫자나 짧은 텍스트를 사용하세요.
+| 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                                    |
 
-3. **대비**: Badge의 색상이 배경과 충분한 대비를 가지도록 하세요.
+> **Note**: Badge also accepts all Joy UI Badge props.
 
-4. **접근성**: 시각적 정보만으로 의존하지 않고, 스크린 리더를 위한 적절한 레이블을 제공하세요.
+## Accessibility
 
-5. **일관성**: 애플리케이션 전체에서 Badge 사용 패턴을 일관되게 유지하세요.
+- Badge automatically applies `aria-label` or equivalent attributes so screen readers can announce the badge content alongside the wrapped element.
+- When using Badge on an IconButton, always provide an `aria-label` on the IconButton that includes the badge context (e.g., `aria-label="5 unread notifications"`).
+- Avoid relying solely on color to convey badge meaning. Pair colored badges with icons, text, or positional context so color-blind users can also interpret the status.
+- Dot badges (without `badgeContent`) should have an accessible label on the parent element that describes the status (e.g., "User is online").

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

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Chip 컴포넌트는 입력, 속성, 액션을 컴팩트하게 표현하는 UI 요소입니다. 태그, 필터, 연락처, 카테고리 등을 나타내는 데 주로 사용됩니다. 텍스트, 아이콘, 아바타와 함께 사용할 수 있으며, 클릭하거나 삭제할 수 있는 인터랙티브한 기능을 제공합니다.
+The Chip component is a compact UI element used to represent inputs, attributes, and actions. It is commonly used for tags, filters, contacts, categories, and similar items. It can be used with text, icons, or avatars, and provides interactive behaviors such as clicking or deleting.
 
 ```tsx
 <Chip {...args} />
@@ -28,7 +28,10 @@ function MyComponent() {
       <Chip clickable onClick={() => console.log('clicked')}>
         Clickable Chip
       </Chip>
-      <Chip endDecorator={<CloseIcon />} onClick={() => console.log('delete')}>
+      <Chip
+        endDecorator={<CloseIcon />}
+        onClick={() => console.log('delete')}
+      >
         Deletable Chip
       </Chip>
     </div>
@@ -40,7 +43,7 @@ function MyComponent() {
 
 ### Basic Usage
 
-기본적인 Chip 사용법입니다.
+Basic Chip usage.
 
 ```tsx
 <div style={{
@@ -56,7 +59,7 @@ function MyComponent() {
 
 ### Colors
 
-다양한 색상을 적용할 수 있습니다.
+You can apply various colors.
 
 ```tsx
 <div style={{
@@ -74,7 +77,7 @@ function MyComponent() {
 
 ### Variants
 
-다양한 스타일 변형을 제공합니다.
+Provides a variety of style variants.
 
 ```tsx
 <div style={{
@@ -91,7 +94,7 @@ function MyComponent() {
 
 ### Sizes
 
-크기를 조절할 수 있습니다.
+You can adjust the size.
 
 ```tsx
 <div style={{
@@ -108,7 +111,7 @@ function MyComponent() {
 
 ### With Icons
 
-아이콘과 함께 사용할 수 있습니다.
+Can be used with icons.
 
 ```tsx
 <div style={{
@@ -126,7 +129,7 @@ function MyComponent() {
 
 ### With Avatar
 
-아바타와 함께 사용하여 사용자를 나타낼 수 있습니다.
+Can be used with an avatar to represent a user.
 
 ```tsx
 <div style={{
@@ -141,7 +144,7 @@ function MyComponent() {
 
 ### Deletable
 
-삭제 기능을 가진 Chip입니다. 클릭하면 목록에서 제거됩니다.
+A Chip with delete functionality. Clicking it removes it from the list.
 
 ```tsx
 <div style={{
@@ -157,7 +160,7 @@ function MyComponent() {
 
 ### Clickable
 
-클릭 가능한 Chip으로 필터나 탭으로 사용할 수 있습니다.
+A clickable Chip that can be used as a filter or tab.
 
 ```tsx
 <div style={{
@@ -177,7 +180,7 @@ function MyComponent() {
 
 ### Clickable Actions
 
-클릭하여 다양한 액션을 수행할 수 있습니다.
+Can trigger various actions when clicked.
 
 ```tsx
 <div style={{
@@ -197,7 +200,7 @@ function MyComponent() {
 
 ### States
 
-다양한 상태를 표현할 수 있습니다.
+Can represent various states.
 
 ```tsx
 <div style={{
@@ -262,7 +265,11 @@ function MyComponent() {
 ### Filter Controls
 
 ```tsx
-<Chip clickable variant={isActive ? 'solid' : 'outlined'} onClick={() => setFilter('all')}>
+<Chip
+  clickable
+  variant={isActive ? 'solid' : 'outlined'}
+  onClick={() => setFilter('all')}
+>
   All Items
 </Chip>
 ```
@@ -270,21 +277,43 @@ function MyComponent() {
 ### Contact Pills
 
 ```tsx
-<Chip startDecorator={<Avatar size="sm" />} endDecorator={<CloseIcon />} onDelete={() => removeContact(id)}>
+<Chip
+  startDecorator={<Avatar size="sm" />}
+  endDecorator={<CloseIcon />}
+  onDelete={() => removeContact(id)}
+>
   John Doe
 </Chip>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                           | Default     | Description                            |
+| ---------------- | -------------------------------------------------------------- | ----------- | -------------------------------------- |
+| `children`       | `ReactNode`                                                    | -           | Chip content (text, icons)             |
+| `variant`        | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'soft'`    | Visual style                           |
+| `size`           | `'sm' \| 'md' \| 'lg'`                                         | `'md'`      | Chip size                              |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'` | Color scheme                           |
+| `disabled`       | `boolean`                                                      | `false`     | Disables the chip                      |
+| `onClick`        | `(event: MouseEvent) => void`                                  | -           | Click handler (makes chip interactive) |
+| `startDecorator` | `ReactNode`                                                    | -           | Content before the chip text           |
+| `endDecorator`   | `ReactNode`                                                    | -           | Content after the chip text            |
+| `sx`             | `SxProps`                                                      | -           | Custom styles using the MUI system     |
+
+> **Note**: Chip also accepts all Joy UI Chip props and Framer Motion props.
+
 ## Best Practices
 
-1. **적절한 크기**: 콘텐츠에 맞는 적절한 크기를 선택하세요. 긴 텍스트는 피하고 간결하게 표현하세요.
+1. **Use appropriate sizes**: Choose sizes that fit the content. Keep text concise.
 
-2. **일관된 스타일**: 같은 맥락에서는 일관된 variant와 color를 사용하세요.
+2. **Be consistent**: Use the same variant and color within the same context.
 
-3. **명확한 액션**: clickable이나 deletable 기능을 사용할 때는 사용자에게 명확한 피드백을 제공하세요.
+3. **Clear actions**: When using clickable or deletable behavior, provide clear feedback to the user.
 
-4. **접근성**: 키보드 탐색이 가능하도록 하고, 스크린 리더를 위한 적절한 레이블을 제공하세요.
+4. **Accessibility**: Support keyboard navigation and provide appropriate labels for screen readers.
 
-5. **적절한 간격**: 여러 Chip을 나열할 때는 적절한 간격을 두어 가독성을 높이세요.
+5. **Appropriate spacing**: Use proper spacing when listing multiple Chips to improve readability.
 
-6. **색상 의미**: 색상은 의미를 가지도록 사용하세요 (성공은 초록색, 경고는 주황색 등).
+6. **Semantic color usage**: Use colors with clear meaning, such as green for success and orange for warnings.

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

@@ -1726,6 +1726,99 @@ This is inspector: {selectedRowId}
 </Stack>
 ```
 
+## Props and Customization
+
+### DataTableProps
+
+| Prop                            | Type                                                                | Default                 | Description                                           |
+| ------------------------------- | ------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------- |
+| `rows`                          | `T[]`                                                               | (required)              | Array of row data objects                             |
+| `columns`                       | `ColumnDef<T, ID>[]`                                                | (required)              | Column definitions array                              |
+| `getId`                         | `(row: T) => ID`                                                    | -                       | Custom row identifier function (defaults to `row.id`) |
+| `checkboxSelection`             | `boolean`                                                           | `false`                 | Enables checkbox selection column                     |
+| `selectionModel`                | `ID[]`                                                              | -                       | Controlled selection state                            |
+| `onSelectionModelChange`        | `(model: ID[], isTotalSelected?: boolean) => void`                  | -                       | Callback when selection changes                       |
+| `isRowSelectable`               | `(params: { row, id }) => boolean`                                  | -                       | Determines if a row can be selected                   |
+| `disableSelectionOnClick`       | `boolean`                                                           | `false`                 | Prevents selection when clicking a row                |
+| `isTotalSelected`               | `boolean`                                                           | `false`                 | Represents total selection state in server pagination |
+| `editMode`                      | `boolean`                                                           | `false`                 | Enables inline cell editing                           |
+| `pagination`                    | `boolean`                                                           | `false`                 | Enables pagination                                    |
+| `paginationMode`                | `'client' \| 'server'`                                              | `'client'`              | Client-side or server-side pagination                 |
+| `paginationModel`               | `{ page: number; pageSize: number }`                                | -                       | Controlled pagination state                           |
+| `onPaginationModelChange`       | `(model: { page, pageSize }) => void`                               | -                       | Callback when page or page size changes               |
+| `rowCount`                      | `number`                                                            | -                       | Total row count (required for server pagination)      |
+| `sortModel`                     | `SortModel<T>[]`                                                    | -                       | Controlled sort state                                 |
+| `sortOrder`                     | `('asc' \| 'desc' \| null)[]`                                       | `['asc', 'desc', null]` | Allowed sort directions cycle                         |
+| `onSortModelChange`             | `(model: SortModel<T>[]) => void`                                   | -                       | Callback when sort changes                            |
+| `pinnedColumns`                 | `{ left?: string[]; right?: string[] }`                             | -                       | Pin columns to left/right edges                       |
+| `columnGroupingModel`           | `ColumnGroupingModel`                                               | -                       | Column header grouping configuration                  |
+| `columnVisibilityModel`         | `Record<string, boolean>`                                           | -                       | Controlled column visibility (false = hidden)         |
+| `onColumnVisibilityModelChange` | `(model: Record<string, boolean>) => void`                          | -                       | Callback when visibility changes                      |
+| `loading`                       | `boolean`                                                           | `false`                 | Shows loading overlay                                 |
+| `hoverRow`                      | `boolean`                                                           | `false`                 | Highlights rows on hover                              |
+| `stickyHeader`                  | `boolean`                                                           | `false`                 | Fixes the header when scrolling                       |
+| `stripe`                        | `'even' \| 'odd'`                                                   | -                       | Applies striped row background                        |
+| `noWrap`                        | `boolean`                                                           | `false`                 | Prevents cell text wrapping                           |
+| `onRowClick`                    | `(params: { row, rowId }, event) => void`                           | -                       | Callback when a row is clicked                        |
+| `slots`                         | `{ checkbox?, toolbar?, footer?, loadingOverlay?, noRowsOverlay? }` | -                       | Custom component slots                                |
+| `slotProps`                     | `{ checkbox?, toolbar?, background?, noRowsOverlay? }`              | -                       | Props passed to slot components                       |
+| `apiRef`                        | `React.RefObject<DataTableApi>`                                     | -                       | Imperative API reference                              |
+| `initialState`                  | `{ sorting?, columns? }`                                            | -                       | Initial state for uncontrolled sort/visibility        |
+
+### ColumnDef Union Type
+
+All column types extend `BaseColumnDef` with shared properties:
+
+| Prop              | Type                                                                                                            | Default    | Description                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------ |
+| `field`           | `keyof T`                                                                                                       | (required) | Row data field to display                        |
+| `headerName`      | `string`                                                                                                        | -          | Column header text                               |
+| `type`            | `'text' \| 'number' \| 'currency' \| 'date' \| 'select' \| 'autocomplete' \| 'longText' \| 'link' \| 'actions'` | `'text'`   | Column type (determines edit UI)                 |
+| `width`           | `string`                                                                                                        | -          | Column width (e.g., `'200px'`, `'30%'`)          |
+| `minWidth`        | `string`                                                                                                        | -          | Minimum column width                             |
+| `maxWidth`        | `string`                                                                                                        | -          | Maximum column width                             |
+| `resizable`       | `boolean`                                                                                                       | `false`    | Enables column resizing by dragging              |
+| `sortable`        | `boolean`                                                                                                       | `true`     | Enables sorting for this column                  |
+| `sortComparator`  | `(params: { rowA, rowB }) => number`                                                                            | -          | Custom sort logic                                |
+| `sortOrder`       | `('asc' \| 'desc' \| null)[]`                                                                                   | -          | Column-specific sort direction cycle             |
+| `required`        | `boolean`                                                                                                       | `false`    | Shows required indicator (\*) in header          |
+| `headerLineClamp` | `1 \| 2`                                                                                                        | `1`        | Max header text lines before truncation          |
+| `description`     | `string`                                                                                                        | -          | Tooltip text for the column header               |
+| `cellClassName`   | `string \| ((params: { row, value }) => string)`                                                                | -          | Dynamic cell CSS class                           |
+| `headerClassName` | `string \| ((params) => string)`                                                                                | -          | Dynamic header CSS class                         |
+| `renderCell`      | `(params: { row, value, rowIndex, colIndex, id }) => ReactNode`                                                 | -          | Custom cell renderer                             |
+| `renderEditCell`  | `(params) => ReactNode`                                                                                         | -          | Custom edit cell renderer                        |
+| `isCellEditable`  | `boolean \| ((params: { row, value, id }) => boolean)`                                                          | `true`     | Whether a cell is editable                       |
+| `componentProps`  | `object \| ((params: { row, id }) => object)`                                                                   | -          | Props passed to the column type's edit component |
+| `onCellEditStart` | `(params: { row, originalRow, value }) => void`                                                                 | -          | Callback when cell editing begins                |
+| `onCellEditStop`  | `(params: { row, originalRow, value }) => void`                                                                 | -          | Callback when cell editing ends                  |
+
+### ActionsColumnDef
+
+For action columns, use `type: 'actions'` with `getActions`:
+
+```tsx
+{
+  field: 'actions',
+  type: 'actions',
+  getActions: ({ row, id }) => [
+    <Button key="edit" size="sm">Edit</Button>,
+    <IconMenuButton key="more" items={[...]} />,
+  ],
+}
+```
+
+### DataTableApi
+
+```tsx
+interface DataTableApi {
+  getRowIndexRelativeToVisibleRows(rowId: string): number;
+  setCellFocus(rowId: string): void;
+}
+```
+
+> **Note**: DataTable also accepts all Joy UI Table props (e.g., `borderAxis`, `size`, `sx`).
+
 ## Constraints and Considerations
 
 ### Required Conditions

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

@@ -114,6 +114,18 @@ function MetricCard() {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop        | Type                                                           | Default     | Description                           |
+| ----------- | -------------------------------------------------------------- | ----------- | ------------------------------------- |
+| `message`   | `string`                                                       | (required)  | Tooltip message text                  |
+| `placement` | `TooltipPlacement`                                             | `'top'`     | Tooltip position relative to the icon |
+| `color`     | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'` | Icon color                            |
+| `size`      | `'sm' \| 'md' \| 'lg'`                                         | `'md'`      | Icon size                             |
+| `sx`        | `SxProps`                                                      | -           | Custom styles                         |
+
 ## Best Practices
 
 - **Keep messages concise.** Tooltip messages should be 1-2 sentences that quickly answer "what does this mean?" Avoid paragraphs of text.