Field

개요

Field는 폼 컨트롤(TextInput, Select 등)에 레이블·보조 텍스트·검증 메시지를 연결하는 컨테이너입니다.

자동 ID 연결 — Field.Root가 고유 fieldId, descriptionId, validationId를 생성하고 자식에 context로 전파
접근성 자동화 — Field.Label의 htmlFor, Field.Description·Field.Message의 id가 자동 설정
상태 전파 — status, disabled, readOnly가 context를 통해 하위 컴포넌트(TextInput 등)로 전달
4가지 status — none (기본), success, warning, error
$css prop — 모든 서브컴포넌트에서 rainbow-sprinkles 토큰 기반 스타일링
render prop — base-ui 기반 다형성 렌더링

접근성

WCAG 1.3.1 — Field.Label이 htmlFor로 입력 요소와 연결
WCAG 3.3.1 — Field.Message가 role="alert" 또는 aria-live로 오류 안내
WCAG 3.3.2 — Field.Description의 id가 입력 요소의 aria-describedby에 자동 연결
WCAG 1.4.3 — disabled/readOnly 상태는 시각적 색상과 aria 속성 모두 변경

Usage

기본 사용법

() => {
const [value, setValue] = React.useState('');
return (
  <Field.Root>
    <Field.Label>이름</Field.Label>
    <TextInput.Root>
      <TextInput.Input
        placeholder="이름을 입력하세요"
        value={value}
        onChange={e => setValue(e.target.value)}
      />
    </TextInput.Root>
    <Field.Description>실명을 입력해 주세요.</Field.Description>
  </Field.Root>
);
}

검증 상태

status에 따라 Field.Message의 색상과 아이콘이 변경됩니다.

() => {
const [value, setValue] = React.useState('');
const isError = value.length > 0 && value.length < 3;
return (
  <Field.Root status={isError ? 'error' : 'none'}>
    <Field.Label>닉네임</Field.Label>
    <TextInput.Root>
      <TextInput.Input
        placeholder="3자 이상 입력"
        value={value}
        onChange={e => setValue(e.target.value)}
      />
    </TextInput.Root>
    {isError && <Field.Message>닉네임은 3자 이상이어야 합니다.</Field.Message>}
  </Field.Root>
);
}

필수 항목

Field.Label의 required prop을 사용하면 레이블 뒤에 * 인디케이터가 표시됩니다.

<Field.Root>
<Field.Label required>이메일</Field.Label>
<TextInput.Root>
  <TextInput.Input type="email" placeholder="example@email.com" />
</TextInput.Root>
</Field.Root>

성공 상태

<Field.Root status="success">
<Field.Label>아이디</Field.Label>
<TextInput.Root>
  <TextInput.Input defaultValue="featuring_user" />
</TextInput.Root>
<Field.Message>사용 가능한 아이디입니다.</Field.Message>
</Field.Root>

경고 상태

<Field.Root status="warning">
<Field.Label>비밀번호</Field.Label>
<TextInput.Root>
  <TextInput.Input type="password" defaultValue="1234" />
</TextInput.Root>
<Field.Message>비밀번호가 너무 짧습니다.</Field.Message>
</Field.Root>

비활성 상태

<Field.Root disabled>
<Field.Label>사용자 ID</Field.Label>
<TextInput.Root>
  <TextInput.Input value="ft_user_001" readOnly />
</TextInput.Root>
<Field.Description>수정할 수 없는 항목입니다.</Field.Description>
</Field.Root>

읽기 전용

<Field.Root readOnly>
<Field.Label>가입일</Field.Label>
<TextInput.Root>
  <TextInput.Input value="2024-01-15" />
</TextInput.Root>
</Field.Root>

커스텀 레이아웃 (HStack)

$css로 레이아웃을 자유롭게 조정할 수 있습니다.

<HStack $css={{ gap: '$spacing-400', alignItems: 'flex-start' }}>
<Field.Root $css={{ flex: '1' }}>
  <Field.Label>성</Field.Label>
  <TextInput.Root>
    <TextInput.Input placeholder="홍" />
  </TextInput.Root>
</Field.Root>
<Field.Root $css={{ flex: '2' }}>
  <Field.Label>이름</Field.Label>
  <TextInput.Root>
    <TextInput.Input placeholder="길동" />
  </TextInput.Root>
</Field.Root>
</HStack>