TimeSelect

시/분 컬럼 기반 팝오버로 시간을 선택하는 입력 컴포넌트

개요

Cals TimeSelect는 Foundation TimePicker를 래핑하여 CALS 제품의 시간 입력 UI를 선언적으로 구현하는 컴포넌트입니다. 폼 레이블, 시간 간격, 12시간 형식, 범위 제한 등 CALS에서 자주 쓰이는 시간 처리를 prop으로 제공합니다.

주요 특징

• ✅ 시/분/초 선택: 팝오버 기반 컬럼 UI로 시간 선택
• ✅ controlled / uncontrolled: value/onChange 또는 defaultValue로 값 관리
• ✅ 시간 간격: interval prop으로 분 단위 간격 설정
• ✅ 12시간 형식: use12Hour로 AM/PM 표시 전환
• ✅ 시간 범위 제한: startTime/endTime으로 선택 가능 범위 설정
• ✅ FormItem 내장: label/required/description/error prop으로 폼 레이블 자동 래핑
• ✅ 라벨 도움말: labelTooltip으로 레이블 옆 도움말 아이콘 표시
• ✅ 가시성/포커스 제어: visible prop, ref.focus()/blur()/element
• ✅ 디자인 토큰: 조건부 토큰 오버라이드 (prop이 있을 때만 적용)

기본 사용

기본 상태의 시간 선택 컴포넌트입니다. 팝오버를 열어 시/분을 선택합니다.

<TimeSelect />

기본값 설정

defaultValue로 초기 시간을 설정합니다.

<TimeSelect defaultValue={new Date(2026, 0, 1, 9, 30)} />

시간 간격 (interval)

interval prop으로 분 단위 간격을 설정합니다. 기본값은 1분입니다.

<TimeSelect interval={15} label="15분 간격" />
<TimeSelect interval={30} label="30분 간격" />

12시간 형식 (use12Hour)

use12Hour=true이면 AM/PM 표시 형식을 사용합니다.

<TimeSelect use12Hour label="12시간 형식" />

초 표시 (showSeconds)

showSeconds=true이면 초 단위 선택도 가능합니다.

<TimeSelect showSeconds label="초 포함" />

시간 범위 제한 (startTime / endTime)

startTime/endTime으로 선택 가능한 시간 범위를 제한합니다. 범위 밖 시간 선택 시 onChange가 호출되지 않습니다.

<TimeSelect startTime="09:00" endTime="18:00" label="업무 시간" />

크기

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

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

비활성화 / 읽기 전용

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

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

레이블 / 필수 입력

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

<TimeSelect label="시작 시간" />
<TimeSelect label="마감 시간" required />

레이블 위치

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

<TimeSelect label="시작 시간" orientation="horizontal" labelWidth={80} />

라벨 도움말

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

<TimeSelect label="회의 시간" labelTooltip="회의 시작 시간을 선택하세요." />

Controlled 패턴

value/onChange로 외부에서 시간 상태를 제어합니다.

const [value, setValue] = useState<Date | undefined>()
 
<TimeSelect value={value} onChange={setValue} label="시간 선택" />

스타일 설정

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

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

API Reference

Props

Events

Ref

접근성

권장 사항

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

관련 컴포넌트

• Foundation TimePicker: 기본 시간 선택 컴포넌트
• Cals DatePicker: 날짜 선택 컴포넌트
• FormItem: 폼 레이블 래퍼