# Text Field Input
URL: /lynx/components/text-field-input
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/text-field-input.mdx

한 줄 텍스트를 입력받고 Field의 레이블·설명·오류 상태와 조합하는 컴포넌트입니다.

Lynx Engine 최소 버전: 3.6
사용 XElement: <input>

사용 가능 버전: @seed-design/lynx-react@0.4.0, @seed-design/lynx-css@0.7.0

## Preview

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { Field, TextField, VStack, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <VStack className="text-field-input-preview" gap="x4">
        <Field.Root className="text-field-input-preview__content">
          <Field.Header>
            <Field.Label>제목</Field.Label>
          </Field.Header>
          <TextField.Root>
            <TextField.Input
              accessibility-label="제목"
              maxlength={100}
              placeholder="제목을 입력해 주세요"
            />
          </TextField.Root>
          <Field.Footer>
            <Field.Description>한 줄로 제목을 입력해 주세요.</Field.Description>
          </Field.Footer>
        </Field.Root>
      </VStack>
    </page>
  );
}

root.render(<Root />);
```

## Installation

- npm: npx @seed-design/cli add ui:text-field
- pnpm: pnpm dlx @seed-design/cli add ui:text-field
- yarn: yarn dlx @seed-design/cli add ui:text-field
- bun: bun x @seed-design/cli add ui:text-field

## Props

### `TextField`

### `TextFieldInput`

## Examples

### Listening to Value Changes

`TextField.Root`에 `value`와 `onValueChange`를 전달하면 입력값을 직접 관리할 수 있습니다. Lynx native 입력에는 `value` attribute가 없으므로 컴포넌트가 `setValue` UI method로 값을 동기화합니다.

```tsx
import "./styles";

import { root, useState } from "@lynx-js/react";
import { TextField, VStack, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [value, setValue] = useState("");
  const [changeCount, setChangeCount] = useState(0);

  function handleValueChange(nextValue: string) {
    "background only";

    setValue(nextValue);
    setChangeCount((previous) => previous + 1);
  }

  return (
    <page className={seedClassName}>
      <VStack className="text-field-input-preview" gap="x4">
        <VStack className="text-field-input-preview__content" gap="x3">
          <TextField.Root value={value} onValueChange={handleValueChange}>
            <TextField.Input
              accessibility-label="닉네임"
              maxlength={20}
              placeholder="닉네임을 입력해 주세요"
            />
          </TextField.Root>
          <text className="text-field-input-preview__status">
            입력값: {JSON.stringify(value)}, 변경 횟수: {JSON.stringify(changeCount)}
          </text>
        </VStack>
      </VStack>
    </page>
  );
}

root.render(<Root />);
```

### State

`Field.Root`의 `disabled`, `readOnly`, `invalid` 상태는 내부 `TextField.Root`와 `TextField.Input`에 전달됩니다.

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { Field, TextField, VStack, useSeedClassName } from "@seed-design/lynx-react";

function StateField({
  defaultValue,
  label,
  ...stateProps
}: Field.RootProps & { defaultValue?: string; label: string }) {
  return (
    <Field.Root {...stateProps}>
      <Field.Header>
        <Field.Label>{label}</Field.Label>
      </Field.Header>
      <TextField.Root defaultValue={defaultValue}>
        <TextField.Input accessibility-label={label} maxlength={100} placeholder="내용 입력" />
      </TextField.Root>
      {stateProps.invalid ? (
        <Field.Footer>
          <Field.ErrorMessage>입력 내용을 확인해 주세요.</Field.ErrorMessage>
        </Field.Footer>
      ) : null}
    </Field.Root>
  );
}

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <VStack className="text-field-input-preview" gap="x4">
        <VStack className="text-field-input-preview__content" gap="spacingY.componentDefault">
          <StateField label="Enabled" />
          <StateField disabled label="Disabled" />
          <StateField defaultValue="수정할 수 없는 값" label="Read only" readOnly />
          <StateField invalid label="Invalid" />
        </VStack>
      </VStack>
    </page>
  );
}

root.render(<Root />);
```

### Prefix and Suffix

`TextField.PrefixText`와 `TextField.SuffixText`를 입력 앞뒤에 조합할 수 있습니다.

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { Field, TextField, VStack, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <VStack className="text-field-input-preview" gap="x4">
        <VStack className="text-field-input-preview__content" gap="spacingY.componentDefault">
          <Field.Root>
            <Field.Header>
              <Field.Label>프로필 주소</Field.Label>
            </Field.Header>
            <TextField.Root>
              <TextField.PrefixText>https://</TextField.PrefixText>
              <TextField.Input
                accessibility-label="프로필 주소"
                maxlength={100}
                placeholder="example.com"
              />
            </TextField.Root>
          </Field.Root>
          <Field.Root>
            <Field.Header>
              <Field.Label>나이</Field.Label>
            </Field.Header>
            <TextField.Root>
              <TextField.PrefixText>만</TextField.PrefixText>
              <TextField.Input
                accessibility-label="나이"
                maxlength={3}
                placeholder="20"
                type="number"
              />
              <TextField.SuffixText>세</TextField.SuffixText>
            </TextField.Root>
          </Field.Root>
        </VStack>
      </VStack>
    </page>
  );
}

root.render(<Root />);
```

### Composing with Field

`Field`와 조합하면 레이블, 설명, 필수 표시, 오류 메시지를 함께 제공합니다. Lynx에는 HTML `label for` 연결이 없으므로 native 입력에는 `accessibility-label`을 직접 지정합니다.

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { Field, TextField, VStack, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <VStack className="text-field-input-preview" gap="x4">
        <VStack className="text-field-input-preview__content" gap="spacingY.componentDefault">
          <Field.Root required>
            <Field.Header>
              <Field.Label weight="bold">
                이름
                <Field.RequiredIndicator />
              </Field.Label>
            </Field.Header>
            <TextField.Root required>
              <TextField.Input accessibility-label="이름" maxlength={30} placeholder="이름 입력" />
            </TextField.Root>
            <Field.Footer>
              <Field.Description>실명을 입력해 주세요.</Field.Description>
            </Field.Footer>
          </Field.Root>
          <Field.Root invalid>
            <Field.Header>
              <Field.Label>사용자 이름</Field.Label>
            </Field.Header>
            <TextField.Root defaultValue="이미 사용 중" invalid>
              <TextField.Input accessibility-label="사용자 이름" maxlength={20} />
            </TextField.Root>
            <Field.Footer>
              <Field.ErrorMessage>다른 사용자 이름을 입력해 주세요.</Field.ErrorMessage>
            </Field.Footer>
          </Field.Root>
        </VStack>
      </VStack>
    </page>
  );
}

root.render(<Root />);
```

### Grapheme Limit

이모지·조합 문자를 사용자에게 보이는 한 글자로 계산하려면 snippet의 `maxGraphemeCount`와 `onValueChange`를 사용합니다.

```tsx
import { useState } from "@lynx-js/react";
import { TextField, TextFieldInput } from "@/components/ui/text-field";

export function LimitedTitleField() {
  const [value, setValue] = useState("");

  return (
    <TextField
      label="제목"
      value={value}
      maxGraphemeCount={40}
      onValueChange={({ slicedValue }) => setValue(slicedValue)}
    >
      <TextFieldInput accessibility-label="제목" />
    </TextField>
  );
}
```

### Keyboard avoidance

`KeyboardAvoidingScrollView` 안에 배치하면 `TextFieldInput`이 focus될 때 자동으로 등록되어 키보드에 가려지지 않는 위치로 스크롤됩니다.

```tsx
import { KeyboardAvoidingScrollView } from "@seed-design/lynx-react";
import { TextField, TextFieldInput } from "@/components/ui/text-field";

export function Form() {
  return (
    <KeyboardAvoidingScrollView>
      <TextField label="제목">
        <TextFieldInput accessibility-label="제목" />
      </TextField>
    </KeyboardAvoidingScrollView>
  );
}
```

## Web Version Differences

- 편집 가능한 상태에서는 HTML `<input>` 대신 Lynx native `<input>` element를 렌더링합니다.
- `readOnly` 상태에서는 native focus·selection·잘라내기 메뉴를 제거하기 위해 `<text>` element로 렌더링합니다. 이 상태의 ref는 `<text>`를 가리키며 input 전용 UI method와 이벤트는 사용할 수 없습니다.
- `onChange` 대신 snippet `TextField`의 `onValueChange`를 사용합니다. 원문과 grapheme 단위로 자른 값을 함께 제공합니다.
- native `bindinput`은 `TextFieldInput`에 추가로 전달할 수 있습니다.
- `Field.Label`과 입력의 DOM id 연결이 없으므로 `accessibility-label`을 입력에 직접 제공합니다.
- 포커스 시 키보드가 나타나도록 `show-soft-input-on-focus`의 기본값은 `true`입니다. `undefined`가 native attribute로 전달되지 않도록 컴포넌트가 이 기본값을 명시적으로 적용합니다. 커스텀 키보드를 사용하는 경우에는 `false`로 재정의할 수 있습니다.
- `android-set-soft-input-mode`의 기본값은 `"unspecified"`입니다. Android에서 `undefined`가 native attribute로 전달되면 오류가 발생할 수 있어 컴포넌트가 이 기본값을 명시적으로 적용합니다.
- `android-set-soft-input-mode`는 입력 요소가 포함된 host window 전역에 영향을 줍니다. 기본값인 `"unspecified"`도 기존 Activity 설정을 그대로 보존하는 값이 아니라 시스템 판단 모드로 다시 설정합니다. `KeyboardAvoidingScrollView`가 키보드 회피를 전담하는 화면에서는 별도 pan/resize를 막기 위해 `"nothing"`으로 재정의합니다. 같은 window에 있는 입력 요소에는 가능한 한 같은 값을 사용합니다.
- `size="responsive"`는 CSS viewport breakpoint가 없는 Lynx에서 지원하지 않습니다. `large` 또는 `medium`을 명시합니다.

## Unsupported Lynx Features

- HTML form submit, browser validation, `aria-describedby` id 연결은 지원하지 않습니다.