DatePicker

캘린더 팝업으로 날짜를 선택하는 기본 컴포넌트

개요

Foundation DatePicker는 Button + Popover + Calendar을 조합한 날짜 선택 컴포넌트입니다. 단일 날짜 선택을 위한 기본 빌딩 블록으로, iCignal 레이어에서 FormItem 통합, 키보드 입력, 범위 선택 등 확장 기능을 제공합니다.

주요 특징

• ✅ 캘린더 팝업: Popover 기반 날짜 선택
• ✅ 캘린더 아이콘: 트리거 버튼에 아이콘 표시
• ✅ 월/연도 드롭다운: captionLayout=“dropdown” 기본 적용
• ✅ 날짜 포맷: yyyy-MM-dd 형식으로 표시
• ✅ 접근성: Button 기반 키보드 네비게이션
• ✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본 날짜 선택

버튼을 클릭하면 캘린더 팝업이 열리고, 날짜를 선택하면 입력 필드에 반영됩니다.

const [date, setDate] = useState<Date | undefined>()
 
<DatePicker value={date} onChange={setDate} width={200} />

기본값 설정

value에 초기 Date 객체를 전달하여 기본 날짜를 설정합니다.

<DatePicker value={new Date()} onChange={setDate} width={200} />

비활성 상태

disabled를 설정하면 버튼이 비활성화되어 캘린더를 열 수 없습니다.

<DatePicker disabled width={200} />

Calendar 기간 선택

Calendar 컴포넌트를 직접 사용하여 기간(range) 선택이 가능합니다.

const [range, setRange] = useState<DateRange | undefined>()
 
<Calendar
  mode="range"
  selected={range}
  onSelect={setRange}
  numberOfMonths={2}
/>

Calendar 월/연도 드롭다운

captionLayout="dropdown"으로 월과 연도를 드롭다운으로 빠르게 전환할 수 있습니다. DatePicker에는 기본 적용되어 있습니다.

<Calendar mode="single" captionLayout="dropdown" />

API Reference

DatePicker Props

Events

기본 사용법

import { DatePicker, Calendar } from "@vortex/ui-foundation"
 
// 단일 날짜 선택
<DatePicker value={date} onChange={setDate} width={200} />
 
// Calendar 직접 사용
<Calendar mode="single" captionLayout="dropdown" />
<Calendar mode="range" numberOfMonths={2} />

접근성

ARIA 속성

• Button 기반으로 role="button" 자동 적용
• Popover에 포커스 트랩 지원

키보드 네비게이션

• Enter/Space: 캘린더 팝업 열기/닫기
• Arrow Keys: 캘린더 내 날짜 이동
• Tab: 포커스 이동

권장 사항

• ✅ 폼 필드에서 사용 시 iCignal DatePicker 권장 (label, error, required 지원)
• ✅ 키보드 직접 입력이 필요하면 iCignal DatePicker 사용
• ❌ Foundation DatePicker를 label 없이 단독 사용 지양

관련 컴포넌트

• Calendar: 캘린더 컴포넌트
• Button: 버튼 컴포넌트
• DatePicker (iCignal): FormItem 통합 DatePicker