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

여러 줄의 긴 텍스트를 입력받고 자동으로 높이를 조절하는 컴포넌트입니다.

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

사용 가능 버전: @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 { useSeedClassName, VStack } from "@seed-design/lynx-react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

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

  return (
    <page className={seedClassName}>
      <VStack width="full" height="full" align="center" justify="center">
        <VStack width="full" maxWidth="480px" gap="x3">
          <TextField
            label="소개"
            description="내용이 늘어나면 입력 영역의 높이도 자동으로 늘어납니다."
            defaultValue={"동네에서 함께할 이웃을 찾고 있어요.\n관심사를 자유롭게 적어 주세요."}
          >
            <TextFieldTextarea accessibility-label="소개" placeholder="소개를 입력해 주세요" />
          </TextField>
        </VStack>
      </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`

### `TextFieldTextarea`

## Usage

Snippet의 `TextField`가 label, description, required indicator와 여러 줄 입력 영역을 조합합니다. Lynx에는 HTML `label for` 연결이 없으므로 native 입력에는 `accessibility-label`을 함께 지정합니다.

```tsx
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

export function IntroductionField() {
  return (
    <TextField label="소개">
      <TextFieldTextarea accessibility-label="소개" placeholder="소개를 입력해 주세요" />
    </TextField>
  );
}
```

### Controlled value

`value`와 `onValueChange`를 전달하면 controlled mode로 동작합니다. Lynx native textarea에는 `value` attribute가 없으므로 컴포넌트가 `setValue` UI method로 값을 동기화합니다.

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

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

  return (
    <TextField value={value} onValueChange={({ value }) => setValue(value)}>
      <TextFieldTextarea accessibility-label="소개" />
    </TextField>
  );
}
```

### Autoresizing

`TextFieldTextarea`는 기본적으로 Lynx native textarea의 측정 기능을 사용해 내용에 맞춰 높이가 늘어납니다. iOS에서는 크기 측정용 래퍼가 최소 높이와 세로 여백을 맡고, Android에서는 native textarea가 직접 맡습니다. 실제 영역의 높이가 달라지면 `KeyboardAvoidingScrollView`의 회피 위치를 다시 계산합니다. 고정 높이가 필요하면 `autoresize={false}`와 명시적인 `height`를 함께 사용합니다.

Android에서는 SEED typography의 줄 높이를 맞추기 위해 `line-spacing="3.2px"`를 기본 적용합니다. `line-spacing`을 명시하면 모든 플랫폼에서 해당 값이 우선하며, Android의 기본 보정은 `line-spacing={0}`으로 해제할 수 있습니다. `fontSize`나 `lineHeight`를 직접 변경한다면 이에 맞는 `line-spacing`도 함께 지정해야 합니다.

```tsx
<TextField label="소개">
  <TextFieldTextarea accessibility-label="소개" placeholder="소개를 입력해 주세요" />
</TextField>
```

### Grapheme limit

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

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

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

  return (
    <TextField
      label="소개"
      value={value}
      maxGraphemeCount={80}
      onValueChange={({ slicedValue }) => setValue(slicedValue)}
    >
      <TextFieldTextarea accessibility-label="소개" />
    </TextField>
  );
}
```

### Keyboard avoidance

`KeyboardAvoidingScrollView` 안에 배치하면 `TextFieldTextarea`가 focus될 때 자동으로 등록됩니다. autoresize로 레이아웃이 바뀌면 활성 입력 위치를 다시 계산합니다.

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

export function Form() {
  return (
    <KeyboardAvoidingScrollView>
      <TextField label="내용">
        <TextFieldTextarea accessibility-label="내용" />
      </TextField>
    </KeyboardAvoidingScrollView>
  );
}
```

## Examples

### State

#### Enabled

기본 상태와 오류 상태를 `Field`의 label, description, error message와 함께 구성합니다.

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { useSeedClassName, VStack } from "@seed-design/lynx-react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

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

  return (
    <page className={seedClassName}>
      <VStack width="full" height="full" align="center" justify="center">
        <VStack width="full" maxWidth="480px" gap="x5">
          <TextField label="소개" description="자신을 소개해 주세요.">
            <TextFieldTextarea accessibility-label="소개" placeholder="소개를 입력해 주세요" />
          </TextField>
          <TextField
            label="문의 내용"
            invalid
            errorMessage="문의 내용을 10자 이상 입력해 주세요."
            defaultValue="짧은 문의"
          >
            <TextFieldTextarea accessibility-label="문의 내용" />
          </TextField>
        </VStack>
      </VStack>
    </page>
  );
}

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

#### Disabled

`disabled`는 입력과 이를 감싸는 `Field`의 상태를 함께 비활성화합니다.

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { useSeedClassName, VStack } from "@seed-design/lynx-react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

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

  return (
    <page className={seedClassName}>
      <VStack width="full" height="full" align="center" justify="center">
        <VStack width="full" maxWidth="480px" gap="x5">
          <TextField
            label="소개"
            description="현재 수정할 수 없는 항목입니다."
            disabled
            defaultValue="동네 생활을 좋아해요."
          >
            <TextFieldTextarea accessibility-label="소개" />
          </TextField>
          <TextField
            label="문의 내용"
            disabled
            invalid
            errorMessage="입력 내용을 확인해 주세요."
            defaultValue="확인이 필요한 내용"
          >
            <TextFieldTextarea accessibility-label="문의 내용" />
          </TextField>
        </VStack>
      </VStack>
    </page>
  );
}

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

#### Read Only

`readOnly`는 값을 편집할 수 없는 텍스트로 표시합니다. 비활성 상태와 달리 내용을 읽는 용도로 사용합니다.

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { useSeedClassName, VStack } from "@seed-design/lynx-react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

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

  return (
    <page className={seedClassName}>
      <VStack width="full" height="full" align="center" justify="center">
        <VStack width="full" maxWidth="480px" gap="x5">
          <TextField
            label="소개"
            description="내용을 읽을 수 있지만 수정할 수 없습니다."
            readOnly
            defaultValue={"동네에서 함께 산책할 이웃을 찾고 있어요.\n주말 오후에 주로 산책해요."}
          >
            <TextFieldTextarea accessibility-label="소개" />
          </TextField>
          <TextField label="메모" readOnly>
            <TextFieldTextarea accessibility-label="메모" placeholder="작성된 메모가 없습니다" />
          </TextField>
        </VStack>
      </VStack>
    </page>
  );
}

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

### Grapheme Count

`maxGraphemeCount`를 지정하면 현재 글자 수와 최대 글자 수를 표시합니다. 이모지와 조합 문자는 화면에 보이는 grapheme 단위로 계산합니다.

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { useSeedClassName, VStack } from "@seed-design/lynx-react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

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

  return (
    <page className={seedClassName}>
      <VStack width="full" height="full" align="center" justify="center">
        <VStack width="full" maxWidth="480px" gap="x3">
          <TextField
            label="한 줄 소개"
            description="이모지와 조합 문자를 화면에 보이는 한 글자로 계산합니다."
            maxGraphemeCount={40}
            defaultValue="산책과 커피를 좋아해요 ☕️"
          >
            <TextFieldTextarea
              accessibility-label="한 줄 소개"
              placeholder="자신을 소개해 주세요"
            />
          </TextField>
        </VStack>
      </VStack>
    </page>
  );
}

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

## Web Version Differences

- 편집 가능한 상태에서는 HTML `<textarea>` 대신 Lynx native `<textarea>` element를 렌더링합니다.
- `readOnly` 상태에서는 native focus·selection·잘라내기 메뉴를 제거하기 위해 `<text>` element로 렌더링합니다. 이 상태의 ref는 `<text>`를 가리키며 textarea 전용 UI method와 이벤트는 사용할 수 없습니다.
- `onChange` 대신 snippet `TextField`의 `onValueChange`를 사용합니다. 원문과 grapheme 단위로 자른 값을 함께 제공합니다.
- native `bindinput`은 `TextFieldTextarea`에 추가로 전달할 수 있습니다.
- `Field.Label`과 입력의 DOM id 연결이 없으므로 `accessibility-label`을 입력에 직접 제공합니다.
- autoresize는 DOM `scrollHeight` 대신 native intrinsic height를 사용합니다. iOS에서는 크기 측정용 래퍼가 세로 여백과 최소 높이를 소유해 첫 입력 시 native content size에 여백이 중복되지 않게 합니다. Android에서는 native textarea가 세로 여백과 최소 높이를 직접 소유합니다.
- Android에서는 CSS `line-height`가 native textarea에 적용되지 않아 `line-spacing="3.2px"`를 기본 적용합니다. 명시적인 `line-spacing` 값이 이 기본값보다 우선합니다.
- controlled textarea도 native 입력 이벤트를 그대로 유지하고, 외부에서 값이 달라진 경우에만 `setValue`로 동기화합니다. 입력마다 `readonly`를 토글하지 않아 줄 추가 시 native scroll offset과 높이 측정이 초기화되지 않습니다.
- 포커스 시 키보드가 나타나도록 `show-soft-input-on-focus`의 기본값은 `true`입니다. `undefined`가 native attribute로 전달되지 않도록 컴포넌트가 이 기본값을 명시적으로 적용합니다. 커스텀 키보드를 사용하는 경우에는 `false`로 재정의할 수 있습니다.
- Android의 fullscreen extract input은 기본적으로 비활성화합니다. 필요한 경우 `android-fullscreen-mode={true}`를 명시합니다.
- `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 연결은 지원하지 않습니다.
- 큰 textarea에서 현재 caret 위치만 기준으로 키보드를 회피하는 기능은 지원하지 않습니다. 현재는 Field·TextField·native 입력 영역 중 안전 영역에 맞는 가장 큰 영역을 선택합니다.