# FilterMenu

## Introduction

FilterMenu는 다양한 필터 타입을 지원하는 모달 형태의 필터 컴포넌트입니다. 여러 종류의 필터를 조합하여 복잡한 필터링 UI를 쉽게 구성할 수 있습니다.

```tsx
<FilterMenu {...args} defaultValues={values} onChange={newValues => {
  setValues(newValues);
  args.onChange!(newValues);
}} />
```

| Field                        | Description | Default |
| ---------------------------- | ----------- | ------- |
| Controls resolved at runtime | —           | —       |

## Usage

```tsx
import { FilterMenu } from '@ceed/ads';

function MyComponent() {
  const [filterValues, setFilterValues] = useState({});

  const filters = [
    {
      id: 'status',
      type: 'checkbox-group',
      label: 'Status',
      options: [
        { label: 'Active', value: 'active' },
        { label: 'Inactive', value: 'inactive' },
      ],
    },
    {
      id: 'priority',
      type: 'radio-group',
      label: 'Priority',
      options: [
        { label: 'High', value: 'high' },
        { label: 'Medium', value: 'medium' },
        { label: 'Low', value: 'low' },
      ],
    },
    {
      id: 'dateRange',
      type: 'date-range',
      label: 'Date Range',
      displayFormat: 'MM/DD/YYYY',
    },
  ];

  return <FilterMenu filters={filters} values={filterValues} onChange={setFilterValues} useReset />;
}
```

## Filter Types

FilterMenu는 다음과 같은 필터 타입을 지원합니다:

### Checkbox Group

다중 선택이 가능한 체크박스 그룹 필터입니다.

```tsx
{
  id: 'status',
  type: 'checkbox-group',
  label: 'Status',
  options: [
    { label: 'Active', value: 'active' },
    { label: 'Inactive', value: 'inactive' },
  ],
}
```

### Filterable Checkbox Group

검색 기능이 포함된 체크박스 그룹 필터입니다. 옵션이 많을 때 유용합니다.

```tsx
{
  id: 'categories',
  type: 'filterable-checkbox-group',
  label: 'Categories',
  options: [
    { label: 'Electronics', value: 'electronics' },
    { label: 'Clothing', value: 'clothing' },
    { label: 'Food', value: 'food' },
    { label: 'Books', value: 'books' },
  ],
  placeholder: 'Search categories...',
  maxHeight: 300,
}
```

### Radio Group

단일 선택이 가능한 라디오 버튼 그룹 필터입니다.

```tsx
{
  id: 'priority',
  type: 'radio-group',
  label: 'Priority',
  options: [
    { label: 'High', value: 'high' },
    { label: 'Medium', value: 'medium' },
    { label: 'Low', value: 'low' },
  ],
}
```

### Date Range

날짜 범위를 선택할 수 있는 필터입니다.

```tsx
{
  id: 'dateRange',
  type: 'date-range',
  label: 'Date Range',
  displayFormat: 'MM/DD/YYYY',
  inputReadOnly: true,
  hideClearButton: true,
}
```

### Currency Input

단일 통화 값을 입력할 수 있는 필터입니다.

```tsx
{
  id: 'amount',
  type: 'currency-input',
  label: 'Amount',
  currency: 'USD',
  useMinorUnit: true,
}
```

### Currency Range

통화 범위를 입력할 수 있는 필터입니다.

```tsx
{
  id: 'amountRange',
  type: 'currency-range',
  label: 'Amount Range',
  currency: 'USD',
  useMinorUnit: true,
}
```

### Percentage Input

단일 퍼센트 값을 입력할 수 있는 필터입니다.

```tsx
{
  id: 'percentage',
  type: 'percentage-input',
  label: 'Percentage',
  useMinorUnit: true,
  maxDecimalScale: 2,
  placeholder: 'Enter percentage',
}
```

### Percentage Range

퍼센트 범위를 입력할 수 있는 필터입니다.

```tsx
{
  id: 'percentageRange',
  type: 'percentage-range',
  label: 'Percentage Range',
  useMinorUnit: true,
  maxDecimalScale: 2,
}
```

### Autocomplete

자동완성을 지원하는 선택 필터입니다.

```tsx
{
  id: 'category',
  type: 'autocomplete',
  label: 'Category',
  options: ['Category 1', 'Category 2', 'Category 3'],
  placeholder: 'Select a category',
}
```

## Examples

### Controlled Mode

```tsx
<FilterMenu {...args} defaultValues={values} onChange={newValues => {
  setValues(newValues);
  args.onChange!(newValues);
}} />
```

### Uncontrolled Mode

```tsx
<FilterMenu />
```

## Best Practices

1. **필터 ID 관리**: 각 필터의 `id`는 고유해야 하며, 상태 관리의 키로 사용됩니다.

2. **타입 안전성**: TypeScript를 사용할 때 FilterItem 타입을 활용하여 타입 안전성을 보장하세요.

3. **Reset vs Clear**:
   - `useReset`: 여러 필터가 있을 때 모든 필터를 초기화
   - `useClear`: 단일 필터만 있을 때 해당 필터를 초기화

4. **상태 관리**: 제어 모드(`values` prop 사용) 또는 비제어 모드(`defaultValues` prop 사용) 중 하나를 선택하여 사용하세요.

5. **접근성**: 각 필터에는 적절한 `label`을 제공하여 접근성을 보장하세요.
