@ceed/cds 1.28.0 → 1.29.0-next.1

package/dist/components/inputs/FilterableCheckboxGroup.md

@@ -2,14 +2,7 @@
 
 ## Introduction
 
-FilterableCheckboxGroup is a multi-select component that combines a search input with a scrollable list of checkboxes. It is designed for scenarios where users need to select multiple items from a potentially large dataset. The built-in search filter narrows down visible options in real time, and virtual scrolling ensures smooth performance even with hundreds of items.
-
-Key capabilities include a "Select all" toggle for bulk selection, automatic sorting (selected items first, then alphabetical), customizable list height, and built-in form integration via `label`, `helperText`, and `required` props. The component accepts options as either simple strings or `{ value, label }` objects.
-
-> **Form 구성 시 내장 prop 사용을 권장합니다**
->
-> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
-> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.
+FilterableCheckboxGroup 컴포넌트는 대량의 옵션 중에서 여러 항목을 선택할 수 있는 검색 가능한 체크박스 그룹입니다. 검색 필터링과 가상 스크롤링을 통해 많은 수의 옵션을 효율적으로 처리할 수 있으며, "Select all" 기능으로 일괄 선택이 가능합니다. 필터링, 다중 선택 폼, 설정 화면 등에서 유용하게 사용됩니다.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -34,7 +27,7 @@ Key capabilities include a "Select all" toggle for bulk selection, automatic sor
 ## Usage
 
 ```tsx
-import { FilterableCheckboxGroup } from '@ceed/cds';
+import { FilterableCheckboxGroup } from '@ceed/ads';
 
 function MyComponent() {
   const [selectedValues, setSelectedValues] = useState<string[]>([]);
@@ -57,9 +50,11 @@ function MyComponent() {
 }
 ```
 
-## Sizes
+## Examples
 
-Three sizes are available: `sm`, `md`, and `lg`. The size affects the search input, checkboxes, and overall spacing.
+### Sizes
+
+다양한 크기의 FilterableCheckboxGroup을 사용할 수 있습니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -69,11 +64,9 @@ Three sizes are available: `sm`, `md`, and `lg`. The size affects the search inp
 </Stack>
 ```
 
-## Label and Helper Text
-
 ### With Label
 
-Use the `label` prop to describe the purpose of the checkbox group.
+라벨을 추가할 수 있습니다.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -85,7 +78,7 @@ Use the `label` prop to describe the purpose of the checkbox group.
 
 ### With Helper Text
 
-Add a `helperText` prop to provide additional guidance below the component.
+도움말 텍스트를 추가할 수 있습니다.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -98,7 +91,7 @@ Add a `helperText` prop to provide additional guidance below the component.
 
 ### Required Field
 
-Set `required` to append a required indicator to the label.
+필수 입력 필드로 표시할 수 있습니다.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -110,9 +103,9 @@ Set `required` to append a required indicator to the label.
 />
 ```
 
-## Custom Max Height
+### Custom Max Height
 
-Control the visible height of the options list with the `maxHeight` prop (default: 300px). A smaller height is useful when screen space is limited.
+목록의 최대 높이를 커스터마이징할 수 있습니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -121,9 +114,9 @@ Control the visible height of the options list with the `maxHeight` prop (defaul
 </Stack>
 ```
 
-## Long List with Virtual Scrolling
+### Long List
 
-When the options list is large, the component uses virtual scrolling to render only the visible items. This keeps the UI performant regardless of the total number of options.
+많은 수의 옵션을 가상 스크롤링으로 효율적으로 표시합니다.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -136,9 +129,9 @@ When the options list is large, the component uses virtual scrolling to render o
 />
 ```
 
-## Empty State
+### No Options
 
-When no options are provided, the component displays an empty state. This is useful for dynamically loaded option lists that may start empty.
+옵션이 없을 때의 상태입니다.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -148,9 +141,9 @@ When no options are provided, the component displays an empty state. This is use
 />
 ```
 
-## Controlled Mode
+### Controlled
 
-Pass `value` and `onChange` to manage the selection state externally. This is the recommended approach when the component is part of a form or when the selected values need to be used by other parts of the UI.
+외부에서 값을 제어하는 예제입니다.
 
 ```tsx
 <Stack spacing={2}>
@@ -162,9 +155,9 @@ Pass `value` and `onChange` to manage the selection state externally. This is th
 </Stack>
 ```
 
-## Sorting Behavior
+### Sorting
 
-The component automatically sorts options on initial render: selected items appear first, followed by unselected items in alphabetical order. When new options are added dynamically, they are inserted in the correct sorted position.
+정렬 동작을 확인할 수 있는 예제입니다. 초기 렌더링 시 선택된 항목이 먼저 표시되고, 그 다음 알파벳 순으로 정렬됩니다.
 
 ```tsx
 <Stack spacing={2}>
@@ -197,122 +190,3 @@ The component automatically sorts options on initial render: selected items appe
 </Typography>
 </Stack>
 ```
-
-## Disabled State
-
-The component supports both full and partial disabling.
-
-- **Full disable**: Set `disabled` on the component to disable the search input, "Select all" toggle, and all checkboxes.
-- **Partial disable**: Set `disabled: true` on individual option objects to disable specific items while keeping the rest interactive.
-- **"Select all" behavior**: Disabled options are excluded from the "Select all" toggle. Their selected state is preserved regardless of bulk actions.
-
-```tsx
-<Stack spacing={3}>
-  <FilterableCheckboxGroup label="Entirely Disabled" placeholder="Search..." helperText="All inputs are disabled" options={defaultOptions.slice(0, 5)} disabled />
-  <FilterableCheckboxGroup label="Partially Disabled Options" placeholder="Search..." helperText="Some options are disabled" options={disabledOptions} />
-  <Stack spacing={2}>
-    <FilterableCheckboxGroup label="Controlled + Partially Disabled" placeholder="Search..." helperText="Disabled options (Banana, Date) maintain their selected state" options={disabledOptions} value={controlledValue} onChange={setControlledValue} />
-    <Typography level="body-sm">
-      Selected: {controlledValue.length > 0 ? controlledValue.join(', ') : 'None'}
-    </Typography>
-    <Typography level="body-sm" sx={{
-      color: 'text.secondary'
-    }}>
-    Try "Select all" - it will only affect enabled options (Apple, Cherry, Elderberry)
-  </Typography>
-</Stack>
-</Stack>
-```
-
-## Common Use Cases
-
-### Filter Panel
-
-Use FilterableCheckboxGroup in a sidebar or panel to let users filter a data table or list by multiple criteria.
-
-```tsx
-import { FilterableCheckboxGroup } from '@ceed/cds';
-
-function FilterPanel({ categories, onFilterChange }) {
-  const [selected, setSelected] = useState<string[]>([]);
-
-  const handleChange = (values: string[]) => {
-    setSelected(values);
-    onFilterChange(values);
-  };
-
-  return (
-    <FilterableCheckboxGroup
-      label="Categories"
-      placeholder="Search categories..."
-      options={categories}
-      value={selected}
-      onChange={handleChange}
-      maxHeight={200}
-    />
-  );
-}
-```
-
-### User Role Assignment
-
-Assign multiple roles to a user from a searchable list.
-
-```tsx
-<FilterableCheckboxGroup
-  label="Assign Roles"
-  placeholder="Search roles..."
-  helperText="Select all roles that apply to this user"
-  options={[
-    { value: 'admin', label: 'Administrator' },
-    { value: 'editor', label: 'Editor' },
-    { value: 'viewer', label: 'Viewer' },
-    { value: 'moderator', label: 'Moderator' },
-    { value: 'billing', label: 'Billing Manager' },
-  ]}
-  required
-  value={selectedRoles}
-  onChange={setSelectedRoles}
-/>
-```
-
-### Region / Country Selection
-
-When dealing with a large set of options like countries, the search filter and virtual scrolling work together for fast selection.
-
-```tsx
-<FilterableCheckboxGroup
-  label="Service Regions"
-  placeholder="Search countries..."
-  options={allCountries.map((c) => ({ value: c.code, label: c.name }))}
-  value={selectedCountries}
-  onChange={setSelectedCountries}
-/>
-```
-
-## Best Practices
-
-1. **Provide a meaningful placeholder.** The search input placeholder should hint at the type of content being filtered (e.g., "Search countries..." instead of a generic "Search...").
-
-```tsx
-// ✅ Specific and helpful
-<FilterableCheckboxGroup placeholder="Search countries..." />
-
-// ❌ Too generic
-<FilterableCheckboxGroup placeholder="Type here..." />
-```
-
-2. **Use `maxHeight` to fit the layout.** In tight spaces like sidebars or modals, set a smaller `maxHeight` to prevent the component from dominating the layout.
-
-3. **Prefer controlled mode for form integration.** Always pass `value` and `onChange` when the selected values participate in form submission or affect other UI state.
-
-4. **Leverage individual `disabled` for permissions.** When some options should be visible but not selectable (e.g., due to user permissions), disable them individually rather than hiding them. This communicates availability without surprising users.
-
-5. **Keep option labels concise.** Long labels will be truncated with an ellipsis. If detailed descriptions are needed, consider using a tooltip or a separate detail view.
-
-## Accessibility
-
-- The search input is labeled by the component's `label` prop, ensuring screen readers announce its purpose.
-- Each checkbox option uses a native `<input type="checkbox">` with an associated `<label>`, enabling click-on-label and proper screen reader announcements.
-- The "Select all" toggle clearly communicates its tri-state behavior (all, none, indeterminate) to assistive technologies.
-- Keyboard navigation is fully supported: Tab to move between the search input and the checkbox list, Space to toggle individual checkboxes, and standard arrow keys to navigate within the list.

package/dist/components/inputs/IconButton.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-IconButton is a compact, icon-only button component designed for actions where a visual symbol alone is sufficient to communicate meaning. It is ideal for toolbars, table row actions, card headers, navigation bars, and any context where space efficiency is critical.
-
-Because IconButton omits visible text, it relies entirely on the icon's clarity and supplementary accessibility attributes to convey its purpose. Always pair it with `aria-label` or a Tooltip to ensure all users can understand the button's function.
+IconButton 컴포넌트는 아이콘만으로 구성된 버튼입니다. 공간 효율적이며, 직관적인 액션을 제공하는 UI 요소로 주로 툴바, 헤더, 카드 등에서 사용됩니다. 텍스트 없이도 의미를 전달할 수 있는 명확한 아이콘과 함께 사용하세요.
 
 ```tsx
 <IconButton {...args} />
@@ -24,26 +22,56 @@ Because IconButton omits visible text, it relies entirely on the icon's clarity
 ```tsx
 import { IconButton } from '@ceed/cds';
 import AddIcon from '@mui/icons-material/Add';
-import DeleteIcon from '@mui/icons-material/Delete';
 
 function MyComponent() {
   return (
-    <div style={{ display: 'flex', gap: '0.5rem' }}>
-      <IconButton aria-label="Add item" onClick={handleAdd}>
+    <div>
+      <IconButton onClick={() => console.log('clicked')}>
         <AddIcon />
       </IconButton>
 
-      <IconButton color="danger" aria-label="Delete item" onClick={handleDelete}>
+      <IconButton color="danger" onClick={() => console.log('delete')}>
         <DeleteIcon />
       </IconButton>
+
+      <IconButton disabled>
+        <EditIcon />
+      </IconButton>
     </div>
   );
 }
 ```
 
-## Colors
+## Examples
+
+### Basic Usage
+
+기본적인 IconButton 사용법입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'center'
+}}>
+<IconButton>
+  <Add />
+</IconButton>
+<IconButton>
+  <Edit />
+</IconButton>
+<IconButton>
+  <Delete />
+</IconButton>
+<IconButton>
+  <Settings />
+</IconButton>
+</div>
+```
+
+### Colors
 
-IconButton supports five semantic colors: `primary` (default), `neutral`, `danger`, `success`, and `warning`. Choose a color that reflects the nature of the action.
+다양한 색상을 적용할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -69,9 +97,9 @@ IconButton supports five semantic colors: `primary` (default), `neutral`, `dange
 </div>
 ```
 
-## Variants
+### Variants
 
-Four visual variants are available: `solid` (filled background), `soft` (tinted background), `outlined` (border only), and `plain` (no background). Use `outlined` or `plain` for secondary actions, and `solid` for primary or high-emphasis actions.
+다양한 스타일 변형을 제공합니다.
 
 ```tsx
 <div style={{
@@ -94,9 +122,9 @@ Four visual variants are available: `solid` (filled background), `soft` (tinted
 </div>
 ```
 
-## Sizes
+### Sizes
 
-The `size` prop controls the button dimensions. Available sizes are `sm`, `md` (default), and `lg`. Ensure touch targets meet the minimum 44px recommended size for touch interfaces.
+크기를 조절할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -116,9 +144,9 @@ The `size` prop controls the button dimensions. Available sizes are `sm`, `md` (
 </div>
 ```
 
-## States
+### States
 
-IconButton supports multiple interactive states including normal, disabled, and loading. Use `disabled` to prevent interaction and `loading` to indicate an in-progress async operation.
+다양한 상태를 표현할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -174,9 +202,9 @@ IconButton supports multiple interactive states including normal, disabled, and
 </div>
 ```
 
-## With Badge
+### With Badge
 
-Combine IconButton with Badge to display notification counts, status indicators, or unread markers alongside the button.
+Badge와 함께 사용하여 알림 수나 상태를 표시할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -202,9 +230,9 @@ Combine IconButton with Badge to display notification counts, status indicators,
 </div>
 ```
 
-## With Tooltip
+### With Tooltip
 
-Wrap IconButton in a Tooltip to provide a text description on hover. This is especially important for icon-only buttons since the icon alone may not be self-explanatory for all users.
+Tooltip과 함께 사용하여 버튼의 기능을 설명할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -235,40 +263,9 @@ Wrap IconButton in a Tooltip to provide a text description on hover. This is esp
 </div>
 ```
 
-## Circular Variants
-
-IconButton renders as a circular shape by default, making it visually distinct from rectangular text buttons and well-suited for floating action buttons and compact action rows.
-
-```tsx
-<div style={{
-  display: 'flex',
-  gap: '2rem',
-  alignItems: 'center'
-}}>
-<div>
-  <h4>Default</h4>
-  <div style={{
-    display: 'flex',
-    gap: '1rem',
-    alignItems: 'center'
-  }}>
-  <IconButton>
-    <Add />
-  </IconButton>
-  <IconButton variant="outlined">
-    <Edit />
-  </IconButton>
-  <IconButton variant="soft">
-    <Delete />
-  </IconButton>
-</div>
-</div>
-</div>
-```
-
-## Action Buttons
+### Action Buttons
 
-A practical example of IconButton used for common CRUD operations with distinct colors signaling the nature of each action.
+실제 액션을 수행하는 버튼들의 예제입니다.
 
 ```tsx
 <div style={{
@@ -296,115 +293,69 @@ A practical example of IconButton used for common CRUD operations with distinct
 
 ## Common Use Cases
 
-### Table Row Actions
-
-```tsx
-import { IconButton, Tooltip } from '@ceed/cds';
-import EditIcon from '@mui/icons-material/Edit';
-import DeleteIcon from '@mui/icons-material/Delete';
-import VisibilityIcon from '@mui/icons-material/Visibility';
-
-function RowActions({ onView, onEdit, onDelete }) {
-  return (
-    <div style={{ display: 'flex', gap: '0.25rem' }}>
-      <Tooltip title="View details">
-        <IconButton size="sm" variant="plain" color="neutral" onClick={onView}>
-          <VisibilityIcon />
-        </IconButton>
-      </Tooltip>
-      <Tooltip title="Edit">
-        <IconButton size="sm" variant="plain" color="neutral" onClick={onEdit}>
-          <EditIcon />
-        </IconButton>
-      </Tooltip>
-      <Tooltip title="Delete">
-        <IconButton size="sm" variant="plain" color="danger" onClick={onDelete}>
-          <DeleteIcon />
-        </IconButton>
-      </Tooltip>
-    </div>
-  );
-}
-```
-
-### Dialog Close Button
+### Toolbar Actions
 
 ```tsx
-import CloseIcon from '@mui/icons-material/Close';
-
-<IconButton
-  variant="plain"
-  color="neutral"
-  size="sm"
-  aria-label="Close dialog"
-  onClick={onClose}
-  sx={{ position: 'absolute', top: 8, right: 8 }}
->
-  <CloseIcon />
-</IconButton>
+<div style={{ display: 'flex', gap: '0.5rem' }}>
+  <IconButton onClick={handleAdd} title="Add item">
+    <AddIcon />
+  </IconButton>
+  <IconButton onClick={handleEdit} color="neutral" title="Edit">
+    <EditIcon />
+  </IconButton>
+  <IconButton onClick={handleDelete} color="danger" title="Delete">
+    <DeleteIcon />
+  </IconButton>
+</div>
 ```
 
-### Navigation Back Button
+### Navigation
 
 ```tsx
-import ArrowBackIcon from '@mui/icons-material/ArrowBack';
-
-<IconButton
-  variant="outlined"
-  color="neutral"
-  aria-label="Go back"
-  onClick={() => router.back()}
->
+<IconButton onClick={() => router.back()} variant="outlined">
   <ArrowBackIcon />
 </IconButton>
 ```
 
-## Best Practices
-
-1. **Always provide an accessible label.** Since there is no visible text, use `aria-label` or wrap with a Tooltip to describe the action.
+### Settings & More Options
 
 ```tsx
-// ✅ Accessible icon button
-<IconButton aria-label="Delete item" color="danger">
-  <DeleteIcon />
+<IconButton onClick={handleSettings} color="neutral">
+  <SettingsIcon />
 </IconButton>
-
-// ❌ No accessible label
-<IconButton color="danger">
-  <DeleteIcon />
+<IconButton onClick={handleMoreOptions}>
+  <MoreVertIcon />
 </IconButton>
 ```
 
-2. **Use semantic colors to convey intent.** Match the color to the action's nature: `danger` for destructive actions, `success` for confirmations, `neutral` for general-purpose actions.
+### Social Actions
 
 ```tsx
-// ✅ Color matches the action
-<IconButton color="danger" aria-label="Delete">
-  <DeleteIcon />
+<IconButton onClick={handleLike} color="danger">
+  <FavoriteIcon />
 </IconButton>
-
-// ❌ Misleading color
-<IconButton color="success" aria-label="Delete">
-  <DeleteIcon />
+<IconButton onClick={handleShare} color="primary">
+  <ShareIcon />
 </IconButton>
 ```
 
-3. **Use the `loading` prop for async operations.** This prevents double-clicks and provides visual feedback during network requests or processing.
+## Best Practices
 
-```tsx
-// ✅ Shows loading spinner during async action
-<IconButton loading={isSaving} aria-label="Save" onClick={handleSave}>
-  <SaveIcon />
-</IconButton>
-```
+1. **명확한 아이콘**: 사용자가 쉽게 이해할 수 있는 명확하고 직관적인 아이콘을 사용하세요.
+
+2. **적절한 크기**: 터치 인터페이스를 고려하여 최소 44px 이상의 터치 영역을 확보하세요.
+
+3. **접근성**:
+   - `title` 속성이나 `aria-label`을 제공하여 스크린 리더 사용자를 위한 설명을 추가하세요.
+   - Tooltip과 함께 사용하여 기능을 명확히 설명하세요.
 
-4. **Prefer universally recognized icons.** Choose icons that are widely understood (e.g., trash can for delete, pencil for edit, plus for add). Avoid ambiguous symbols without a Tooltip.
+4. **일관된 스타일**: 같은 맥락에서는 일관된 variant와 색상을 사용하세요.
 
-5. **Maintain consistent sizing within the same context.** Use the same `size` and `variant` for all IconButtons in a toolbar or action group to keep the interface clean and predictable.
+5. **의미 있는 색상**:
+   - 빨간색(danger): 삭제, 취소 등의 위험한 액션
+   - 초록색(success): 저장, 승인 등의 긍정적인 액션
+   - 회색(neutral): 일반적인 액션
 
-## Accessibility
+6. **피드백 제공**: 클릭 시 명확한 피드백을 제공하여 사용자가 액션이 실행되었음을 알 수 있도록 하세요.
 
-- **`aria-label` is essential**: Every IconButton must have either an `aria-label`, `aria-labelledby`, or a wrapping Tooltip with `title` to provide a text alternative for screen readers.
-- **Keyboard interaction**: IconButton is focusable via `Tab` and can be activated with `Enter` or `Space`. Focus indicators are displayed by default.
-- **Disabled state**: When `disabled` is set, the button receives `aria-disabled="true"` and becomes non-interactive. It remains visible in the DOM for screen readers to announce.
-- **Touch targets**: Ensure the rendered button is at least 44x44 pixels for touch accessibility. The `sm` size may need additional padding in touch-heavy interfaces.
+7. **로딩 상태**: 비동기 작업 시 `loading` prop을 사용하여 사용자에게 진행 상황을 알려주세요.