Text

라벨, 마스크, 통화 서식, 검색 등을 내장한 올인원 단일 라인 텍스트 입력 컴포넌트

개요

Cals Text은 Foundation Input을 래핑하여 CALS 제품의 텍스트 입력 UI를 선언적으로 구현하는 컴포넌트입니다. 폼 라벨, 입력 마스크, 천 단위 구분, 통화 서식 등 CALS에서 자주 쓰이는 입력 처리를 prop으로 제공합니다.

주요 특징

• ✅ controlled / uncontrolled: value/onChange 또는 defaultValue로 값 관리
• ✅ 입력 마스크: mask 패턴(9/A/S/*)으로 입력 형식 제한, autoUnmask로 순수 값 전달
• ✅ 천 단위 구분: thousandSeparator로 표시 포맷, 값은 순수 숫자 유지
• ✅ 통화 서식: currency prop으로 통화 기호·소수 자릿수 적용
• ✅ 코드 표시명 변환: codeMap으로 코드 값을 표시명으로 변환
• ✅ FormItem 내장: label/required/description/error prop으로 폼 라벨 자동 래핑
• ✅ 라벨 도움말: labelTooltip으로 라벨 옆 도움말 아이콘 표시
• ✅ 검색 실행: isSearch + onSearch로 Enter 검색 지원
• ✅ 가시성/포커스 제어: visible prop, ref.focus()/blur()/element
• ✅ 디자인 토큰: 조건부 토큰 오버라이드 (prop이 있을 때만 적용)

기본 사용

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

<Text placeholder="입력하세요" />

기본값 설정

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

<Text defaultValue="기본값" />

크기

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

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

비활성화 / 읽기 전용

disabled는 조작할 수 없고, readOnly는 값을 바꿀 수 없습니다. readOnly는 disabled로 바뀌지 않고 읽기 전용 모양으로 표시되며 Tab 포커스를 받습니다.

<Text disabled defaultValue="비활성화" />
<Text readOnly defaultValue="읽기 전용" />

라벨 / 필수 입력

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

<Text label="이메일" placeholder="name@example.com" />
<Text label="이름" required placeholder="필수 입력" />

라벨 위치

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

<Text label="이름" orientation="horizontal" labelWidth={80} />

라벨 도움말

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

<Text label="비밀번호" labelTooltip="영문, 숫자 포함 8자 이상 입력하세요." />

글자 수 제한

maxLength로 최대 글자 수를 제한합니다. 초과 입력은 차단됩니다.

<Text maxLength={10} minLength={2} />

검색 실행

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

<Text isSearch onSearch={() => alert("검색 실행")} placeholder="검색어 입력 후 Enter" />

입력 마스크

mask 패턴으로 입력 형식을 제한합니다. 9는 숫자, A는 영문, S는 영숫자, *는 영숫자+한글이며 그 외 문자는 리터럴로 자동 삽입됩니다. autoUnmask=true이면 onChange로 마스크가 제거된 순수 값이 전달됩니다.

<Text mask="999-9999-9999" label="전화번호" />
<Text mask="999999-9999999" autoUnmask label="주민번호" />

천 단위 구분

thousandSeparator로 숫자에 천 단위 구분 기호(,)를 표시합니다. 저장되는 값은 구분 기호가 제거된 순수 숫자입니다.

<Text thousandSeparator defaultValue="1234567" label="금액" />

통화 서식

currency prop으로 통화 기호와 소수 자릿수를 지정합니다. blur 시 서식이 적용됩니다.

<Text currency={{ symbol: "$", decimal: 2 }} defaultValue="1234.5" />

코드 표시명 변환

codeMap에 매핑된 코드 값은 표시명으로 변환되어 보입니다. 매핑이 없으면 원래 값이 표시됩니다.

<Text codeMap={{ A: "승인", R: "반려" }} value="A" onChange={setValue} />

스타일 설정

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

<Text
  backgroundColor="#eef2ff"
  color="#1e3a8a"
  borderColor="#6366f1"
  defaultValue="스타일 오버라이드"
/>

API Reference

Props

Events

Ref

접근성

권장 사항

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

관련 컴포넌트

• Foundation Input: 기본 입력 컴포넌트
• FormItem: 폼 라벨 래퍼
• Cals Select: 드롭다운 선택 컴포넌트