@ceed/cds 1.24.1-next.3 → 1.25.0

package/dist/components/inputs/FilterableCheckboxGroup.md

@@ -2,7 +2,14 @@
 
 ## Introduction
 
-FilterableCheckboxGroup 컴포넌트는 대량의 옵션 중에서 여러 항목을 선택할 수 있는 검색 가능한 체크박스 그룹입니다. 검색 필터링과 가상 스크롤링을 통해 많은 수의 옵션을 효율적으로 처리할 수 있으며, "Select all" 기능으로 일괄 선택이 가능합니다. 필터링, 다중 선택 폼, 설정 화면 등에서 유용하게 사용됩니다.
+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을 사용하세요.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -27,7 +34,7 @@ FilterableCheckboxGroup 컴포넌트는 대량의 옵션 중에서 여러 항목
 ## Usage
 
 ```tsx
-import { FilterableCheckboxGroup } from '@ceed/ads';
+import { FilterableCheckboxGroup } from '@ceed/cds';
 
 function MyComponent() {
   const [selectedValues, setSelectedValues] = useState<string[]>([]);
@@ -50,11 +57,9 @@ function MyComponent() {
 }
 ```
 
-## Examples
+## Sizes
 
-### Sizes
-
-다양한 크기의 FilterableCheckboxGroup을 사용할 수 있습니다.
+Three sizes are available: `sm`, `md`, and `lg`. The size affects the search input, checkboxes, and overall spacing.
 
 ```tsx
 <Stack spacing={3}>
@@ -64,9 +69,11 @@ function MyComponent() {
 </Stack>
 ```
 
+## Label and Helper Text
+
 ### With Label
 
-라벨을 추가할 수 있습니다.
+Use the `label` prop to describe the purpose of the checkbox group.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -78,7 +85,7 @@ function MyComponent() {
 
 ### With Helper Text
 
-도움말 텍스트를 추가할 수 있습니다.
+Add a `helperText` prop to provide additional guidance below the component.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -91,7 +98,7 @@ function MyComponent() {
 
 ### Required Field
 
-필수 입력 필드로 표시할 수 있습니다.
+Set `required` to append a required indicator to the label.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -103,9 +110,9 @@ function MyComponent() {
 />
 ```
 
-### 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}>
@@ -114,9 +121,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### Long List
+## Long List with Virtual Scrolling
 
-많은 수의 옵션을 가상 스크롤링으로 효율적으로 표시합니다.
+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
@@ -129,9 +136,9 @@ function MyComponent() {
 />
 ```
 
-### No Options
+## Empty State
 
-옵션이 없을 때의 상태입니다.
+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
@@ -141,9 +148,9 @@ function MyComponent() {
 />
 ```
 
-### Controlled
+## Controlled Mode
 
-외부에서 값을 제어하는 예제입니다.
+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}>
@@ -155,9 +162,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### Sorting
+## Sorting Behavior
 
-정렬 동작을 확인할 수 있는 예제입니다. 초기 렌더링 시 선택된 항목이 먼저 표시되고, 그 다음 알파벳 순으로 정렬됩니다.
+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}>
@@ -190,3 +197,122 @@ function MyComponent() {
 </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/FormControl.md

@@ -0,0 +1,361 @@
+# FormControl
+
+## Introduction
+
+FormControl is a wrapper component that provides context to form elements such as Input, Textarea, Select, and more. It manages shared states like `error`, `disabled`, `required`, and `size`, passing them down to its children automatically. Use it with FormLabel and FormHelperText to build accessible, consistent form fields.
+
+```tsx
+<FormControl {...args}>
+  <FormLabel>Label</FormLabel>
+  <Input placeholder="Enter text…" />
+  <FormHelperText>This is helper text.</FormHelperText>
+</FormControl>
+```
+
+| Field       | Description | Default |
+| ----------- | ----------- | ------- |
+| size        | —           | —       |
+| error       | —           | —       |
+| disabled    | —           | —       |
+| required    | —           | —       |
+| orientation | —           | —       |
+
+## Usage
+
+```tsx
+import { FormControl, FormLabel, FormHelperText, Input } from '@ceed/cds';
+
+function MyForm() {
+  return (
+    <FormControl>
+      <FormLabel>Username</FormLabel>
+      <Input placeholder="Enter username" />
+      <FormHelperText>Choose a unique username.</FormHelperText>
+    </FormControl>
+  );
+}
+```
+
+## With Input
+
+The most common pattern — wrapping an Input with a label and helper text.
+
+```tsx
+<FormControl>
+  <FormLabel>Username</FormLabel>
+  <Input placeholder="Enter username" />
+  <FormHelperText>Choose a unique username.</FormHelperText>
+</FormControl>
+```
+
+## With Textarea
+
+FormControl works equally well with Textarea components.
+
+```tsx
+<FormControl>
+  <FormLabel>Description</FormLabel>
+  <Textarea placeholder="Enter description…" minRows={3} />
+  <FormHelperText>Provide a detailed description.</FormHelperText>
+</FormControl>
+```
+
+## With Select
+
+Use FormControl with Select for dropdown fields.
+
+```tsx
+<FormControl>
+  <FormLabel>Role</FormLabel>
+  <Select placeholder="Select a role" options={roleOptions} />
+  <FormHelperText>Select the user role.</FormHelperText>
+</FormControl>
+```
+
+## Error State
+
+Set `error` on FormControl to propagate the error state to all child components. FormHelperText automatically changes color to indicate the error.
+
+```tsx
+<FormControl error>
+  <FormLabel>Email</FormLabel>
+  <Input placeholder="email@example.com" defaultValue="invalid-email" />
+  <FormHelperText>Please enter a valid email address.</FormHelperText>
+</FormControl>
+```
+
+```tsx
+<FormControl error>
+  <FormLabel>Email</FormLabel>
+  <Input placeholder="email@example.com" value="invalid-email" />
+  <FormHelperText>Please enter a valid email address.</FormHelperText>
+</FormControl>
+```
+
+## Disabled State
+
+Set `disabled` to disable all child form elements at once.
+
+```tsx
+<FormControl disabled>
+  <FormLabel>Name</FormLabel>
+  <Input placeholder="Enter name" defaultValue="John Doe" />
+  <FormHelperText>This field is disabled.</FormHelperText>
+</FormControl>
+```
+
+```tsx
+<FormControl disabled>
+  <FormLabel>Name</FormLabel>
+  <Input placeholder="Enter name" value="John Doe" />
+  <FormHelperText>This field is disabled.</FormHelperText>
+</FormControl>
+```
+
+## Required Field
+
+Set `required` to add an asterisk (\*) to the label and mark the field as required.
+
+```tsx
+<FormControl required>
+  <FormLabel>Full Name</FormLabel>
+  <Input placeholder="Enter your full name" />
+  <FormHelperText>This field is required.</FormHelperText>
+</FormControl>
+```
+
+```tsx
+<FormControl required>
+  <FormLabel>Full Name</FormLabel>
+  <Input placeholder="Enter your full name" />
+</FormControl>
+```
+
+## Sizes
+
+FormControl supports `sm`, `md`, and `lg` sizes. The size is inherited by child components.
+
+```tsx
+<Stack gap={3}>
+  <FormControl size="sm">
+    <FormLabel>Small</FormLabel>
+    <Input placeholder="Small input" />
+  </FormControl>
+  <FormControl size="md">
+    <FormLabel>Medium</FormLabel>
+    <Input placeholder="Medium input" />
+  </FormControl>
+  <FormControl size="lg">
+    <FormLabel>Large</FormLabel>
+    <Input placeholder="Large input" />
+  </FormControl>
+</Stack>
+```
+
+## Horizontal Layout
+
+Use `orientation="horizontal"` for inline form controls, such as Switch or Checkbox toggles.
+
+```tsx
+<FormControl orientation="horizontal" sx={{
+  gap: 2
+}}>
+<FormLabel>Subscribe</FormLabel>
+<Switch />
+</FormControl>
+```
+
+```tsx
+<FormControl orientation="horizontal" sx={{ gap: 2 }}>
+  <FormLabel>Subscribe</FormLabel>
+  <Switch />
+</FormControl>
+```
+
+## Form Example
+
+A complete form demonstrating FormControl with multiple input types.
+
+```tsx
+<Stack gap={2} sx={{
+  maxWidth: 400
+}}>
+<FormControl required>
+  <FormLabel>Name</FormLabel>
+  <Input placeholder="Enter your name" />
+</FormControl>
+<FormControl required>
+  <FormLabel>Email</FormLabel>
+  <Input type="email" placeholder="email@example.com" />
+  <FormHelperText>We will never share your email.</FormHelperText>
+</FormControl>
+<FormControl>
+  <FormLabel>Role</FormLabel>
+  <Select placeholder="Select a role" options={roleOptions} />
+</FormControl>
+<FormControl>
+  <FormLabel>Bio</FormLabel>
+  <Textarea placeholder="Tell us about yourself…" minRows={3} />
+  <FormHelperText>Maximum 500 characters.</FormHelperText>
+</FormControl>
+</Stack>
+```
+
+## FormLabel
+
+FormLabel renders a `<label>` element associated with its sibling input. It automatically displays an asterisk when the parent FormControl has `required` set.
+
+```tsx
+<FormControl required>
+  <FormLabel>Email</FormLabel>
+  <Input />
+</FormControl>
+```
+
+## FormHelperText
+
+FormHelperText provides supplementary guidance below the input. It automatically switches to the error color when the parent FormControl has `error` set.
+
+```tsx
+<FormControl error>
+  <FormLabel>Password</FormLabel>
+  <Input type="password" />
+  <FormHelperText>Password must be at least 8 characters.</FormHelperText>
+</FormControl>
+```
+
+## Common Use Cases
+
+### Registration Form
+
+```tsx
+function RegistrationForm() {
+  const [errors, setErrors] = React.useState({});
+
+  return (
+    <Stack gap={2} component="form">
+      <FormControl required error={!!errors.name}>
+        <FormLabel>Name</FormLabel>
+        <Input placeholder="Enter your name" />
+        {errors.name && <FormHelperText>{errors.name}</FormHelperText>}
+      </FormControl>
+
+      <FormControl required error={!!errors.email}>
+        <FormLabel>Email</FormLabel>
+        <Input type="email" placeholder="email@example.com" />
+        {errors.email && <FormHelperText>{errors.email}</FormHelperText>}
+      </FormControl>
+
+      <FormControl required error={!!errors.password}>
+        <FormLabel>Password</FormLabel>
+        <Input type="password" placeholder="Enter password" />
+        <FormHelperText>{errors.password || 'Must be at least 8 characters.'}</FormHelperText>
+      </FormControl>
+
+      <FormControl orientation="horizontal">
+        <Checkbox label="I agree to the terms and conditions" />
+      </FormControl>
+    </Stack>
+  );
+}
+```
+
+### Settings Form with Mixed Controls
+
+```tsx
+function SettingsForm() {
+  return (
+    <Stack gap={2}>
+      <FormControl orientation="horizontal" sx={{ justifyContent: 'space-between' }}>
+        <FormLabel>Email notifications</FormLabel>
+        <Switch />
+      </FormControl>
+
+      <FormControl>
+        <FormLabel>Language</FormLabel>
+        <Select
+          defaultValue="en"
+          options={[
+            { value: 'en', label: 'English' },
+            { value: 'ko', label: 'Korean' },
+          ]}
+        />
+      </FormControl>
+
+      <FormControl>
+        <FormLabel>Notes</FormLabel>
+        <Textarea minRows={3} placeholder="Additional notes…" />
+        <FormHelperText>Optional</FormHelperText>
+      </FormControl>
+    </Stack>
+  );
+}
+```
+
+> **Tip: Use built-in form props instead**
+>
+> Input, Select, Textarea, DatePicker 등 Input 계열 컴포넌트는 `label`, `helperText` prop을 자체적으로 지원합니다.
+> 간단한 form 필드에는 각 컴포넌트의 내장 prop을 사용하는 것이 더 간결합니다.
+>
+> ```tsx
+> // ✅ Simpler: built-in props
+> <Input label="Username" helperText="Choose a unique username." />
+>
+> // ⬆️ Equivalent to:
+> <FormControl>
+>   <FormLabel>Username</FormLabel>
+>   <Input placeholder="Enter username" />
+>   <FormHelperText>Choose a unique username.</FormHelperText>
+> </FormControl>
+> ```
+>
+> FormControl is most useful when you need to compose multiple elements, share state across siblings, or use horizontal orientation.
+
+## Best Practices
+
+1. **Always pair with FormLabel**: Every form field should have a label for accessibility. Use FormLabel inside FormControl.
+
+```tsx
+// ✅ Accessible — label is associated with input
+<FormControl>
+  <FormLabel>Email</FormLabel>
+  <Input />
+</FormControl>
+
+// ❌ No label — screen readers cannot identify the input
+<FormControl>
+  <Input placeholder="Email" />
+</FormControl>
+```
+
+2. **Use `error` prop on FormControl, not children**: Set error state on FormControl so all children react consistently.
+
+```tsx
+// ✅ Error propagated from FormControl
+<FormControl error>
+  <FormLabel>Email</FormLabel>
+  <Input />
+  <FormHelperText>Invalid email</FormHelperText>
+</FormControl>
+
+// ❌ Inconsistent — only Input shows error
+<FormControl>
+  <FormLabel>Email</FormLabel>
+  <Input error />
+  <FormHelperText>Invalid email</FormHelperText>
+</FormControl>
+```
+
+3. **Use consistent sizing**: Set `size` on FormControl to ensure all children (label, input, helper text) are proportionally sized.
+
+4. **Mark required fields**: Use the `required` prop to automatically add visual indicators and `aria-required` attributes.
+
+5. **Provide helpful error messages**: When using the error state, always include a FormHelperText explaining what went wrong and how to fix it.
+
+## Accessibility
+
+- FormControl automatically associates FormLabel with the input using `htmlFor` and `id`.
+- The `required` prop adds `aria-required="true"` to the input and an asterisk to the label.
+- The `error` prop adds `aria-invalid="true"` to the input.
+- FormHelperText is linked to the input via `aria-describedby` so screen readers announce it.
+- Use the `disabled` prop on FormControl to set `aria-disabled` on child elements.