Field
레이블, 컨트롤, 설명, 네이티브 유효성, 오류를 접근 가능하게 구성해요.
핵심 속성
TRField는 Base UI Field의 전체 구조를 감싸요. Label, Description, 표시 중인 Error는 Control에 자동으로 연결돼요. Root의 name과 disabled는 Control의 같은 prop보다 우선해요.
| Part | 역할 |
|---|---|
Root | 이름, 사용 가능 상태, 유효성 검사 시점, dirty/touched/filled/focused 상태 |
Label | 접근 가능한 이름과 클릭하면 포커스되는 대상 |
Control | 네이티브 입력 값, 이벤트, 유효성, 폼 데이터, 초기화 |
Description | aria-describedby에 포함되는 상시 안내 |
Error | 네이티브 유효성이나 외부 상태에 따른 복구 메시지 |
Validity | 값, 오류, 네이티브 ValidityState를 읽는 render prop |
Item | 컬렉션의 checkbox/radio와 label/description 배치 |
값을 포커스 가능한 상태로 제출해야 하면 Control의 readOnly를 사용해요. 사용할 수 없고 폼 데이터에서도 제외해야 하면 Root의 disabled를 사용해요. 표준 파트를 조합할 때는 aria-labelledby나 aria-describedby를 직접 추가하지 않아요.
설치
pnpm add @tinyrack/ui긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
스타일
@import '@tinyrack/ui/components/field.css';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
가져오기
import { TRField } from '@tinyrack/ui/components/field';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
플레이그라운드
미리보기 안에서 입력하면 상호작용이 소유하는 값이 바뀌어요. Playground 컨트롤에서는 required, invalid, read-only, disabled, size를 전환할 수 있으며 Reset은 컨트롤과 미리보기 값을 초기값으로 되돌려요.
사용법
예시
크기 고유 링크
주변 컨트롤과 콘텐츠 밀도에 맞는 크기를 선택해요.
사용 가능 여부와 유효성 상태 고유 링크
복구 안내에는 invalid를, 폼 데이터에서 값을 제외하려면 disabled를, 포커스와 제출 값을 유지하려면 readOnly를 사용해요.
제출, 복구, 초기화 고유 링크
네이티브 이메일 유효성이 알맞은 오류를 선택하고 Reset이 입력값과 피드백을 복원해요.
컬렉션 항목과 네이티브 유효성 고유 링크
Item은 옵션과 설명을 배치하고 Validity는 검증 규칙을 중복하지 않고 현재 상태를 보여줘요.
API
TRField.Root
| Prop | 타입 / default | 용도 |
|---|---|---|
name | string | field 이름을 지정하며 Control.name보다 우선 |
disabled | boolean / false | control을 비활성화하고 모든 part에 data-disabled 부여 |
invalid, dirty, touched | boolean | 외부에서 관리하는 field state |
validate | sync/async validator | error, error 배열 또는 null 반환 |
validationMode | 'onSubmit' | 'onBlur' | 'onChange' / 'onSubmit' | validation 시점 |
validationDebounceTime | number / 0 | onChange validation debounce(ms) |
actionsRef | RefObject<TRFieldRootActions> | validate() 노출 |
Control은 네이티브 input props, value / defaultValue, onValueChange(value, details)를 받아요. 크기는 Root가 아니라 control에 지정해요. Control은 uiSize?: 'md' | 'lg'(기본값 md)를 받고 다른 Tinyrack control도 같은 prop을 쓰기 때문에, Root 안에 있든 단독으로 쓰든 규칙이 하나예요. Label.nativeLabel={false}는 render가 label이 아닌 host를 사용할 때 지정해요. Error.match는 true 또는 valueMissing 같은 ValidityState key를 받고, Item.disabled는 단일 옵션을 비활성화해요. Validity는 validity, value, initialValue, error, errors를 제공해요.
모든 host 파트는 ref, 네이티브 attribute/event, 함수형 className / style, Base UI render를 보존해요. namespace, named part 7개, 각 props/state type, TRFieldRootActions, TRFieldValidityData, Control change-event type을 모두 개별 export해요. CSS는 opt-in이에요.