Number

숫자 입력과 증감 버튼을 제공하는 CALS 전용 숫자 입력 컴포넌트

개요

Cals Number는 Foundation Number를 래핑하여 CALS 제품의 숫자 입력 UI를 선언적으로 구현하는 컴포넌트입니다. 폼 레이블, min/max 범위 제한, step 증감 단위, 스타일 토큰 오버라이드 등을 prop으로 제공합니다.

주요 특징

• ✅ controlled / uncontrolled: value/onValueChange 또는 defaultValue로 값 관리
• ✅ 범위 제한: min/max prop으로 입력 범위 설정
• ✅ 증감 단위: step prop으로 버튼 클릭 시 증감량 설정
• ✅ FormItem 내장: label/required/description/error prop으로 폼 레이블 자동 래핑
• ✅ 라벨 도움말: labelTooltip으로 레이블 옆 도움말 아이콘 표시
• ✅ 가시성/포커스 제어: visible prop, ref.focus()/blur()/element
• ✅ 디자인 토큰: 조건부 토큰 오버라이드 (prop이 있을 때만 적용)

기본 사용

증감 버튼(-, +)과 숫자 입력 필드를 렌더링합니다.

<Number defaultValue={0} />

기본값 설정

defaultValue로 초기값을 지정합니다.

<Number defaultValue={42} />

크기

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

<Number size="xs" defaultValue={10} />
<Number size="sm" defaultValue={10} />
<Number size="md" defaultValue={10} />
<Number size="lg" defaultValue={10} />
<Number size="xl" defaultValue={10} />

범위 제한 (Min / Max)

min과 max로 입력 가능한 범위를 제한합니다. 범위를 벗어나면 자동으로 보정됩니다.

<Number min={0} max={100} defaultValue={50} />

증감 단위 (Step)

step으로 버튼 클릭 시 증감량을 설정합니다.

<Number step={5} defaultValue={0} />

상태

읽기 전용

readOnly 시 값은 표시되지만 수정할 수 없습니다.

<Number readOnly value={99} />

비활성화

disabled 시 시각적으로 비활성화 표시됩니다.

<Number disabled defaultValue={10} />

레이블

label prop으로 폼 레이블을 표시합니다. orientation으로 배치 방향을 설정합니다.

<Number label="수량" defaultValue={1} />
<Number label="수량" orientation="horizontal" labelWidth={80} defaultValue={1} />

필수 입력

required prop으로 필수 표시를 추가합니다.

<Number label="수량" required defaultValue={0} />

레이블 도움말

labelTooltip으로 레이블 옆 도움말 아이콘을 표시합니다.

<Number label="수량" labelTooltip="최소 1개 이상 주문하세요." defaultValue={1} />

스타일 오버라이드

backgroundColor, color, borderColor 등의 props로 디자인 토큰을 오버라이드할 수 있습니다.

<Number backgroundColor="#eef2ff" color="#1e3a8a" borderColor="#6366f1" defaultValue={42} />

API Reference

Props

Events

Ref API

기본 사용법

import { Number } from "@vortex/ui-cals"
 
<Number defaultValue={0} />
<Number min={0} max={100} step={5} defaultValue={50} />
<Number label="수량" required />

접근성

키보드 지원

• Arrow Up/Down: 값 증가/감소
• Page Up/Down: step * 10 단위 증감
• Home/End: min/max로 이동

권장 사항

• ✅ label prop으로 레이블을 제공하여 입력 필드의 목적을 명시하세요
• ✅ min/max를 설정하여 유효 범위를 사용자에게 알려주세요
• ❌ placeholder만으로 레이블을 대체하지 마세요

관련 컴포넌트

• Input: 단일 라인 텍스트 입력 컴포넌트