@ceed/ads 1.25.1-next.3 → 1.26.0

package/dist/components/inputs/FilterMenu.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-FilterMenu는 다양한 필터 타입을 지원하는 모달 형태의 필터 컴포넌트입니다. 여러 종류의 필터를 조합하여 복잡한 필터링 UI를 쉽게 구성할 수 있습니다.
+FilterMenu is a comprehensive filtering component that supports multiple filter types within a single dropdown panel. It enables users to apply, combine, and reset various filters -- including checkboxes, radio buttons, date ranges, currency inputs, percentage inputs, and autocomplete fields -- through a consistent, organized interface.
+
+FilterMenu is ideal for data-heavy admin interfaces such as tables, lists, and dashboards where users need to narrow down results based on multiple criteria. It supports both controlled and uncontrolled state management, allowing flexible integration with different state architectures.
 
 ```tsx
 <FilterMenu {...args} defaultValues={values} onChange={newValues => {
@@ -57,11 +59,11 @@ function MyComponent() {
 
 ## Filter Types
 
-FilterMenu는 다음과 같은 필터 타입을 지원합니다:
+FilterMenu supports the following filter types. Each type is configured through the `filters` array prop.
 
 ### Checkbox Group
 
-다중 선택이 가능한 체크박스 그룹 필터입니다.
+Multi-select filter with checkboxes. The selected values are stored as an array.
 
 ```tsx
 {
@@ -77,7 +79,7 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Filterable Checkbox Group
 
-검색 기능이 포함된 체크박스 그룹 필터입니다. 옵션이 많을 때 유용합니다.
+A searchable checkbox group for long option lists. Includes a text input to filter visible options.
 
 ```tsx
 {
@@ -87,7 +89,6 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
   options: [
     { label: 'Electronics', value: 'electronics' },
     { label: 'Clothing', value: 'clothing' },
-    { label: 'Food', value: 'food' },
     { label: 'Books', value: 'books' },
   ],
   placeholder: 'Search categories...',
@@ -97,7 +98,7 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Radio Group
 
-단일 선택이 가능한 라디오 버튼 그룹 필터입니다.
+Single-select filter with radio buttons. The selected value is stored as a single string.
 
 ```tsx
 {
@@ -114,7 +115,7 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Date Range
 
-날짜 범위를 선택할 수 있는 필터입니다.
+A date range picker filter. The value is stored as a two-element array of date strings.
 
 ```tsx
 {
@@ -129,7 +130,7 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Currency Input
 
-단일 통화 값을 입력할 수 있는 필터입니다.
+A single currency value input field.
 
 ```tsx
 {
@@ -143,7 +144,7 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Currency Range
 
-통화 범위를 입력할 수 있는 필터입니다.
+A currency range filter with min and max inputs.
 
 ```tsx
 {
@@ -157,7 +158,7 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Percentage Input
 
-단일 퍼센트 값을 입력할 수 있는 필터입니다.
+A single percentage value input field.
 
 ```tsx
 {
@@ -172,7 +173,7 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Percentage Range
 
-퍼센트 범위를 입력할 수 있는 필터입니다.
+A percentage range filter with min and max inputs.
 
 ```tsx
 {
@@ -186,7 +187,7 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Autocomplete
 
-자동완성을 지원하는 선택 필터입니다.
+A searchable single-select filter with autocomplete support.
 
 ```tsx
 {
@@ -202,6 +203,8 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Controlled Mode
 
+In controlled mode, you manage the filter state externally using `values` (or `defaultValues` with an `onChange` handler).
+
 ```tsx
 <FilterMenu {...args} defaultValues={values} onChange={newValues => {
   setValues(newValues);
@@ -211,20 +214,167 @@ FilterMenu는 다음과 같은 필터 타입을 지원합니다:
 
 ### Uncontrolled Mode
 
+In uncontrolled mode, FilterMenu manages its own internal state. This is useful when you only need the final filter values on submission.
+
 ```tsx
 <FilterMenu />
 ```
 
+## Common Use Cases
+
+### Table Filters
+
+```tsx
+function DataTable() {
+  const [filters, setFilters] = useState({});
+  const { data } = useQuery(['items', filters], () => fetchItems(filters));
+
+  return (
+    <Box>
+      <FilterMenu
+        filters={[
+          {
+            id: 'status',
+            type: 'checkbox-group',
+            label: 'Status',
+            options: [
+              { label: 'Active', value: 'active' },
+              { label: 'Pending', value: 'pending' },
+              { label: 'Archived', value: 'archived' },
+            ],
+          },
+          {
+            id: 'dateRange',
+            type: 'date-range',
+            label: 'Created Date',
+            displayFormat: 'MM/DD/YYYY',
+          },
+          {
+            id: 'amount',
+            type: 'currency-range',
+            label: 'Amount',
+            currency: 'USD',
+          },
+        ]}
+        defaultValues={filters}
+        onChange={setFilters}
+        useReset
+      />
+      <Table data={data} />
+    </Box>
+  );
+}
+```
+
+### Dashboard Filters
+
+```tsx
+function DashboardFilters({ onFilterChange }) {
+  return (
+    <FilterMenu
+      filters={[
+        {
+          id: 'region',
+          type: 'filterable-checkbox-group',
+          label: 'Region',
+          options: regions.map((r) => ({ label: r.name, value: r.id })),
+          placeholder: 'Search regions...',
+          maxHeight: 200,
+        },
+        {
+          id: 'period',
+          type: 'radio-group',
+          label: 'Time Period',
+          options: [
+            { label: 'Last 7 days', value: '7d' },
+            { label: 'Last 30 days', value: '30d' },
+            { label: 'Last 90 days', value: '90d' },
+            { label: 'Custom', value: 'custom' },
+          ],
+        },
+      ]}
+      onChange={onFilterChange}
+      useReset
+    />
+  );
+}
+```
+
+### Invoice Filters
+
+```tsx
+function InvoiceFilters({ onFilterChange }) {
+  return (
+    <FilterMenu
+      filters={[
+        {
+          id: 'status',
+          type: 'checkbox-group',
+          label: 'Invoice Status',
+          options: [
+            { label: 'Paid', value: 'paid' },
+            { label: 'Pending', value: 'pending' },
+            { label: 'Overdue', value: 'overdue' },
+          ],
+        },
+        {
+          id: 'amount',
+          type: 'currency-range',
+          label: 'Amount Range',
+          currency: 'USD',
+          useMinorUnit: true,
+        },
+        {
+          id: 'date',
+          type: 'date-range',
+          label: 'Invoice Date',
+          displayFormat: 'MM/DD/YYYY',
+        },
+      ]}
+      onChange={onFilterChange}
+      useReset
+    />
+  );
+}
+```
+
 ## Best Practices
 
-1. **필터 ID 관리**: 각 필터의 `id`는 고유해야 하며, 상태 관리의 키로 사용됩니다.
+1. **Use unique filter IDs**: Each filter's `id` must be unique since it serves as the key for state management.
+
+```tsx
+// ✅ Good: Unique IDs
+filters={[
+  { id: 'status', type: 'checkbox-group', ... },
+  { id: 'priority', type: 'radio-group', ... },
+]}
+
+// ❌ Bad: Duplicate IDs cause state conflicts
+filters={[
+  { id: 'filter1', type: 'checkbox-group', ... },
+  { id: 'filter1', type: 'radio-group', ... },
+]}
+```
+
+2. **Choose the right reset strategy**: Use `useReset` when the FilterMenu contains multiple filters that users may want to clear all at once. Use `useClear` for single-filter scenarios.
+
+3. **Provide descriptive labels**: Each filter should have a clear `label` that tells users what they are filtering. Avoid generic names like "Filter 1".
+
+```tsx
+// ✅ Good: Descriptive labels
+{ id: 'invoiceStatus', type: 'checkbox-group', label: 'Invoice Status', ... }
+
+// ❌ Bad: Vague labels
+{ id: 'filter1', type: 'checkbox-group', label: 'Options', ... }
+```
 
-2. **타입 안전성**: TypeScript를 사용할 때 FilterItem 타입을 활용하여 타입 안전성을 보장하세요.
+4. **Use filterable checkbox groups for long lists**: When an option list exceeds 8-10 items, switch from `checkbox-group` to `filterable-checkbox-group` so users can search rather than scroll.
 
-3. **Reset vs Clear**:
-   - `useReset`: 여러 필터가 있을 때 모든 필터를 초기화
-   - `useClear`: 단일 필터만 있을 때 해당 필터를 초기화
+5. **Prefer controlled mode for complex state**: When filter values need to be synced with URL parameters, API requests, or other UI elements, use the controlled pattern with `values` and `onChange`.
 
-4. **상태 관리**: 제어 모드(`values` prop 사용) 또는 비제어 모드(`defaultValues` prop 사용) 중 하나를 선택하여 사용하세요.
+## Accessibility
 
-5. **접근성**: 각 필터에는 적절한 `label`을 제공하여 접근성을 보장하세요.
+- Each filter section is labeled with its `label` prop, providing clear context for screen readers.
+- Checkbox and radio groups follow standard form control patterns with proper labeling.
+- The reset button is keyboard-accessible and clearly labeled, allowing users to quickly clear all filters.
+- Use the `placeholder` prop on filterable checkbox groups and autocomplete filters to provide instructional text for assistive technology users.

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
@@ -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}>
@@ -191,13 +198,13 @@ function MyComponent() {
 </Stack>
 ```
 
-### Disabled
+## Disabled State
 
-컴포넌트 전체 또는 특정 옵션을 비활성화할 수 있습니다.
+The component supports both full and partial disabling.
 
-- **컴포넌트 전체 비활성화**: `disabled` prop을 사용하여 검색 input, "Select all", 모든 옵션을 비활성화합니다.
-- **특정 옵션 비활성화**: 옵션 객체의 `disabled` 속성을 사용하여 개별 옵션을 비활성화합니다.
-- **"Select all" 동작**: 비활성화된 옵션은 "Select all"의 영향을 받지 않으며, 선택 상태가 유지됩니다.
+- **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}>
@@ -216,3 +223,96 @@ function MyComponent() {
 </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/ads';
+
+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.