From 98e86ada15b2a867374188c79f78f5578018a911 Mon Sep 17 00:00:00 2001 From: joonhoekim <26rote@gmail.com> Date: Fri, 7 Nov 2025 09:40:41 +0900 Subject: (김준회) 공통 컴포넌트 이해를 위한 문서 추가 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/common/selectors/nation/README.md | 183 +++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 components/common/selectors/nation/README.md (limited to 'components/common/selectors/nation') 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() + + return ( + + ) +} +``` + +### 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() + + return ( + <> + + + { + 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([]) + + return ( + <> + + + { + 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` - 검색 옵션 + +### 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` - 최대 선택 가능 개수 + +## 특징 + +- **검색 기능**: 국가코드, 국가명으로 실시간 검색 +- **페이지네이션**: 대량의 데이터를 페이지별로 표시 +- **디바운스**: 검색 성능 최적화 +- **다국어 지원**: 한국어명과 영문명 모두 표시 +- **접근성**: 키보드 네비게이션 및 스크린 리더 지원 +- **반응형**: 다양한 화면 크기에 대응 -- cgit v1.2.3