# 국가 선택기 (Nation Selector)

국가 코드를 선택할 수 있는 컴포넌트들입니다. CMCTB_CD 테이블에서 CD_CLF='LE0010' 조건으로 국가 정보를 조회합니다.

## 컴포넌트 구조

- `nation-service.ts`: 국가 데이터 조회 서버 액션
- `nation-selector.tsx`: 기본 국가 선택기 (트리거 버튼 포함)
- `nation-single-selector.tsx`: 단일 선택 다이얼로그
- `nation-multi-selector.tsx`: 다중 선택 다이얼로그

## 데이터 구조

```typescript
interface NationCode {
  CD: string        // 2글자 국가코드 (예: KR)
  CD2: string       // 3글자 국가코드 (예: KOR)
  CD3: string       // 3글자 숫자 국가코드 (예: 410)
  CDNM: string      // 한국어 국가명 (예: 대한민국)
  GRP_DSC: string   // 영문 국가명 (예: Korea, Republic of)
}
```

## 사용 예제

### 1. 기본 국가 선택기

```tsx
import { useState } from 'react'
import { NationSelector, NationCode } from '@/components/common/selectors/nation'

function MyComponent() {
  const [selectedNation, setSelectedNation] = useState<NationCode>()

  return (
    <NationSelector
      selectedNation={selectedNation}
      onNationSelect={setSelectedNation}
      placeholder="국가를 선택하세요"
    />
  )
}
```

### 2. 단일 선택 다이얼로그

```tsx
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { NationSingleSelector, NationCode } from '@/components/common/selectors/nation'

function MyComponent() {
  const [open, setOpen] = useState(false)
  const [selectedNation, setSelectedNation] = useState<NationCode>()

  return (
    <>
      <Button onClick={() => setOpen(true)}>
        국가 선택
      </Button>
      
      <NationSingleSelector
        open={open}
        onOpenChange={setOpen}
        selectedNation={selectedNation}
        onNationSelect={setSelectedNation}
        title="국가 선택"
        description="하나의 국가를 선택하세요"
        showConfirmButtons={true}
        onConfirm={(nation) => {
          console.log('선택된 국가:', nation)
        }}
        onCancel={() => {
          console.log('선택 취소됨')
        }}
      />
    </>
  )
}
```

### 3. 다중 선택 다이얼로그

```tsx
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { NationMultiSelector, NationCode } from '@/components/common/selectors/nation'

function MyComponent() {
  const [open, setOpen] = useState(false)
  const [selectedNations, setSelectedNations] = useState<NationCode[]>([])

  return (
    <>
      <Button onClick={() => setOpen(true)}>
        국가 다중 선택 ({selectedNations.length}개 선택됨)
      </Button>
      
      <NationMultiSelector
        open={open}
        onOpenChange={setOpen}
        selectedNations={selectedNations}
        onNationsSelect={setSelectedNations}
        title="국가 다중 선택"
        description="여러 국가를 선택하세요"
        maxSelection={5} // 최대 5개까지 선택 가능
        onConfirm={(nations) => {
          console.log('선택된 국가들:', nations)
        }}
        onCancel={() => {
          console.log('선택 취소됨')
        }}
      />
    </>
  )
}
```

### 4. 서버 액션 직접 사용

```tsx
import { getNationCodes, getNationCodeByCode } from '@/components/common/selectors/nation'

// 모든 국가 조회
const result = await getNationCodes()
if (result.success) {
  console.log('국가 목록:', result.data)
}

// 검색 조건으로 조회
const searchResult = await getNationCodes({
  searchTerm: '한국',
  limit: 50
})

// 특정 국가 코드로 조회
const korea = await getNationCodeByCode('KR')
console.log('대한민국:', korea)
```

## Props 옵션

### NationSelector

- `selectedNation?: NationCode` - 선택된 국가
- `onNationSelect: (nation: NationCode) => void` - 국가 선택 콜백
- `disabled?: boolean` - 비활성화 여부
- `placeholder?: string` - 플레이스홀더 텍스트
- `className?: string` - 추가 CSS 클래스
- `searchOptions?: Partial<NationSearchOptions>` - 검색 옵션

### NationSingleSelector

- `open: boolean` - 다이얼로그 열림 상태
- `onOpenChange: (open: boolean) => void` - 다이얼로그 상태 변경 콜백
- `selectedNation?: NationCode` - 선택된 국가
- `onNationSelect: (nation: NationCode) => void` - 국가 선택 콜백
- `onConfirm?: (nation: NationCode | undefined) => void` - 확인 버튼 콜백
- `onCancel?: () => void` - 취소 버튼 콜백
- `title?: string` - 다이얼로그 제목
- `description?: string` - 다이얼로그 설명
- `showConfirmButtons?: boolean` - 확인/취소 버튼 표시 여부

### NationMultiSelector

- `open: boolean` - 다이얼로그 열림 상태
- `onOpenChange: (open: boolean) => void` - 다이얼로그 상태 변경 콜백
- `selectedNations?: NationCode[]` - 선택된 국가들
- `onNationsSelect: (nations: NationCode[]) => void` - 국가들 선택 콜백
- `onConfirm?: (nations: NationCode[]) => void` - 확인 버튼 콜백
- `onCancel?: () => void` - 취소 버튼 콜백
- `title?: string` - 다이얼로그 제목
- `description?: string` - 다이얼로그 설명
- `maxSelection?: number` - 최대 선택 가능 개수

## 특징

- **검색 기능**: 국가코드, 국가명으로 실시간 검색
- **페이지네이션**: 대량의 데이터를 페이지별로 표시
- **디바운스**: 검색 성능 최적화
- **다국어 지원**: 한국어명과 영문명 모두 표시
- **접근성**: 키보드 네비게이션 및 스크린 리더 지원
- **반응형**: 다양한 화면 크기에 대응