DatePicker

날짜 선택, 범위 선택, 월/연도 선택, 주간 선택, 빠른 단축 등을 내장한 올인원 날짜 입력 컴포넌트

개요

Cals DatePicker는 Foundation DatePicker를 래핑하여 CALS 제품의 날짜 입력 UI를 선언적으로 구현하는 컴포넌트입니다. 폼 레이블, 날짜 비활성화, 빠른 선택 단축, 검색 모드 등 CALS에서 자주 쓰이는 날짜 처리를 prop으로 제공합니다.

주요 특징

• ✅ 7가지 mode: single, range, month, year, month-range, year-range, week
• ✅ controlled / uncontrolled: value/onChange 또는 defaultValue로 값 관리
• ✅ 날짜 비활성화: disabledDate 콜백 + inactiveMode로 과거/미래 날짜 제한
• ✅ 빠른 선택: shortcuts 배열로 “오늘”, “이번 주” 등 단축 버튼 제공
• ✅ 검색 모드: isSearch + onSearch로 Enter 검색 지원
• ✅ FormItem 내장: label/required/description/error prop으로 폼 레이블 자동 래핑
• ✅ 라벨 도움말: labelTooltip으로 레이블 옆 도움말 아이콘 표시
• ✅ 가시성/포커스 제어: visible prop, ref.focus()/blur()/element
• ✅ 디자인 토큰: 조건부 토큰 오버라이드 (prop이 있을 때만 적용)

기본 사용

placeholder로 입력 전 안내 문구를 표시합니다.

<DatePicker placeholder="날짜를 선택하세요" />

기본값 설정

defaultValue로 초기 날짜를 설정합니다.

<DatePicker defaultValue={new Date(2026, 0, 15)} />

날짜 선택기 유형 (mode)

mode prop으로 선택 유형을 변경합니다. week 모드는 선택한 날짜가 속한 주의 월요일을 반환합니다.

<DatePicker mode="single" />   {/* 기본 */}
<DatePicker mode="range" />
<DatePicker mode="month" />
<DatePicker mode="year" />
<DatePicker mode="month-range" />
<DatePicker mode="year-range" />
<DatePicker mode="week" />     {/* 주간 → 월요일 반환 */}

크기

size prop으로 입력란 크기를 지정합니다. xs / sm / md / lg / xl을 지원합니다.

<DatePicker size="xs" />
<DatePicker size="sm" />
<DatePicker size="md" />
<DatePicker size="lg" />
<DatePicker size="xl" />

비활성화 / 읽기 전용

disabled, readOnly는 모두 비활성화된 외관으로 표시되며 날짜를 변경할 수 없습니다.

<DatePicker disabled defaultValue={new Date()} />
<DatePicker readOnly defaultValue={new Date()} />

레이블 / 필수 입력

label로 레이블을 표시하고, required로 필수 표시 기호(*)를 추가합니다.

<DatePicker label="시작일" placeholder="날짜 선택" />
<DatePicker label="마감일" required placeholder="필수 입력" />

레이블 위치

orientation=“horizontal”이면 레이블이 입력란 왼쪽에 배치됩니다.

<DatePicker label="시작일" orientation="horizontal" labelWidth={80} />

라벨 도움말

labelTooltip 지정 시 레이블 옆 아이콘에 마우스를 올리면 도움말이 표시됩니다.

<DatePicker label="보고일" labelTooltip="보고 기한을 선택하세요." />

선택 불가 날짜 (disabledDate)

disabledDate 콜백으로 특정 날짜의 선택을 차단합니다. true를 반환하면 해당 날짜 선택이 무시됩니다.

<DatePicker
  label="주말 제외"
  disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
/>

과거/미래 날짜 비활성 (inactiveMode)

inactiveMode로 오늘 기준 과거/미래 날짜 선택을 제한합니다. 원본 inactiveBfAf에 대응합니다.

<DatePicker inactiveMode="lt" />   {/* 오늘 이전 비활성 */}
<DatePicker inactiveMode="lte" />  {/* 오늘 포함 이전 비활성 */}
<DatePicker inactiveMode="gt" />   {/* 오늘 이후 비활성 */}
<DatePicker inactiveMode="gte" />  {/* 오늘 포함 이후 비활성 */}

빠른 선택 (shortcuts)

shortcuts 배열로 빠른 선택 버튼을 제공합니다. 원본 pickerOptions.shortcuts에 대응합니다.

const shortcuts = [
  { label: "오늘", value: today },
  { label: "내일", value: tomorrow },
  { label: "1주 후", value: nextWeek },
]
 
<DatePicker
  label="빠른 선택"
  shortcuts={shortcuts}
  value={value}
  onChange={(v) => setValue(v as Date)}
/>

범위 빠른 선택

range 모드에서도 shortcuts를 사용하여 기간을 빠르게 선택할 수 있습니다.

const shortcuts = [
  { label: "이번 주", value: { from: today, to: weekEnd } },
  { label: "이번 달", value: { from: today, to: monthEnd } },
]
 
<DatePicker mode="range" shortcuts={shortcuts} />

검색 폼 모드 (isSearch / onSearch)

isSearch=true에서 Enter 키 입력 시 onSearch가 호출됩니다.

<DatePicker isSearch onSearch={() => alert("검색 실행")} placeholder="날짜 선택 후 Enter" />

스타일 설정

backgroundColor, color, borderColor 등으로 디자인 토큰을 오버라이드합니다.

<DatePicker
  backgroundColor="#eef2ff"
  color="#1e3a8a"
  borderColor="#6366f1"
  defaultValue={new Date()}
/>

API Reference

Props

DatePickerShortcut

Events

Ref

접근성

권장 사항

• ✅ label 또는 aria-label로 입력란의 목적을 명확히 제공하세요.
• ✅ 필수 입력은 required로 설정하여 스크린 리더에 전달하세요.
• ❌ placeholder만으로 레이블을 대체하지 마세요. 값 입력 시 사라집니다.

관련 컴포넌트

• Foundation DatePicker: 기본 날짜 선택 컴포넌트
• FormItem: 폼 레이블 래퍼
• Cals Input: 텍스트 입력 컴포넌트