(김준회) 공통 컴포넌트 이해를 위한 문서 추가

1 files changed, 183 insertions, 0 deletions

diff --git a/components/common/selectors/nation/README.md b/components/common/selectors/nation/README.md
new file mode 100644
index 00000000..f16c3a2f
--- /dev/null
+++ b/components/common/selectors/nation/README.md
@@ -0,0 +1,183 @@
+# 국가 선택기 (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` - 최대 선택 가능 개수
+
+## 특징
+
+- **검색 기능**: 국가코드, 국가명으로 실시간 검색
+- **페이지네이션**: 대량의 데이터를 페이지별로 표시
+- **디바운스**: 검색 성능 최적화
+- **다국어 지원**: 한국어명과 영문명 모두 표시
+- **접근성**: 키보드 네비게이션 및 스크린 리더 지원
+- **반응형**: 다양한 화면 크기에 대응