# Text Input & Textarea

키보드로 값을 직접 입력하는 컴포넌트입니다. 한 줄과 여러 줄이 같은 박스를 공유합니다.

> 원본: `03_ASSET_GUIDE/catalog/text-input.js` · CSS: `03_ASSET_GUIDE/styles/elements/text-input.css`
> kind `element` · category `action-input` · status `stable` · specSource `measured`
> sub-asset: [Textarea](#textarea) (`--textarea`)

> [!NOTE]
> **Input 과 [Textarea](#textarea) 는 한 컴포넌트입니다**
> 저장소에서는 `text-input` 하나이고, 카탈로그 이름도 "Text Input & Textarea" 입니다.
> 테두리·상태·크기 규칙이 완전히 같고 다른 것은 높이와 `<input>` / `<textarea>` 뿐이라
> `--textarea` 라는 하나의 modifier 로 처리합니다.
> 문서만 두 개로 나눈 것이며, 여러 줄 입력은 [Textarea](#textarea) 를 보세요.

---

## 1. 구성

테두리를 그리는 **Container** 와, 그 안에서 실제 입력을 받는 **Control** 로 나뉩니다.
Control 은 테두리를 갖지 않으므로 Prefix · Suffix 를 자유롭게 붙일 수 있습니다.

```
┌──────────────────────────────────┐
│ ₩  120,000                 (×) 원 │
└──────────────────────────────────┘
 ①  ②     ③                   ⑤  ④
```

| # | 요소 | 필수 | 클래스 | 설명 |
|---|---|---|---|---|
| ① | Container | 필수 | `atom-text-input` | 테두리·배경·높이를 그립니다. 상태 클래스가 여기에 붙습니다. |
| ② | Prefix | 선택 | `atom-text-input__prefix` | 입력 앞에 고정되는 아이콘이나 단위. 텍스트 14px, 아이콘 18px. |
| ③ | Control | 필수 | `atom-text-input__control` | 실제 `<input>` / `<textarea>`. 테두리 없이 Container 안을 채웁니다. |
| ④ | Suffix | 선택 | `atom-text-input__suffix` | 입력 뒤에 고정되는 아이콘이나 단위. |
| ⑤ | Clear | `clearable` 일 때 | `atom-text-input__clear` | 값을 지우는 20×20px 원형 버튼. |
| — | Placeholder · Caret | 데모 전용 | `atom-text-input__placeholder` · `atom-text-input__caret` | 포커스 없이 플레이스홀더·커서를 보여주는 정적 대역. 실제 사용에서는 렌더하지 않습니다. |

---

## 2. 종류 / 크기

### Shape

입력값의 길이가 예측 가능하고 한 줄이면 `textInput`, 사용자가 문장을 쓰게 될 자리라면
`textarea` 를 씁니다.

### Size

`medium` 이 기본입니다. 같은 폼 안의 [Select](./select.md) 와 높이를 맞추세요.

| Size | 최소 높이 | 패딩 | 모서리 | 폰트 |
|---|---|---|---|---|
| `small` | 40px | 8px 12px | 8px | 14px |
| `medium` | 48px | 12px 16px | 8px | 15px |
| `large` | 56px | 12px 20px | 12px | 16px |

### Prefix · Suffix

단위나 통화 기호처럼 고정된 부분은 Prefix · Suffix 로 박스 안에 붙입니다.

Prefix · Suffix 텍스트는 14px `--atom-fg-neutral-muted`, 아이콘은 18×18px 입니다.

### Variant

폼 안에서는 테두리가 있는 `outline`, 헤더의 검색 바처럼 입력임이 맥락으로 이미 분명한
자리에서는 `weak` 를 씁니다.

`weak` 는 테두리를 없애고 `--atom-bg-neutral-weak` 배경으로 입력 영역을 표시합니다.

### Clear 버튼

값이 있고 포커스가 들어와 있을 때만 노출합니다. 20×20px 원형 버튼에 12px 아이콘입니다.
빈 칸에서는 지울 값이 없으므로 노출하지 않습니다.

### 실제 input 과 함께

실제 포커스는 `:focus-within` 규칙이 표시합니다. `--focused` 클래스는 데모용입니다.

### Field 와 함께

라벨·도움말·글자 수는 [Form Field](./field.md) 로 감싸서 붙입니다.

### 클래스 계약

`styles/elements/text-input.css` 헤더와 원본 `registry.json` `css.blocks` 기준입니다. 클래스가 없는 값(—)은 기본 스타일 그대로입니다.

| Prop | 값 | 클래스 |
|---|---|---|
| `shape` | `textInput` · `textarea` | — · `--textarea` |
| `size` | `small` · `medium` · `large` | `--size_small` · — · `--size_large` |
| `variant` | `outline` · `weak` | — · `--variant_weak` |
| `invalid` | `true` | `--invalid` |
| `readOnly` | `true` | `--readonly` |
| `disabled` | `true` | `--disabled` + Control 의 `[disabled]` |
| (포커스) | Control 에 포커스 | `--focused` (+ `:focus-within`) |

상태 선택자: `--focused` · `:focus-within` · `--invalid` · `--readonly` · `--disabled` · `:has(.atom-text-input__control[disabled])` · `:hover`

> Text Input 은 상태를 속성이 아니라 **클래스**로 표현하는 예외입니다([README](./README.md#클래스-이름-규칙)).
> `--disabled` 는 CSS 에 정의되어 있지만 헤더 주석에는 빠져 있습니다(원본 registry `css-defined-not-declared`).

---

## 3. 상태

테두리 두께와 색으로 상태를 전달합니다.

| State | 테두리 | 언제 |
|---|---|---|
| `default` | 1px `--atom-border-default` | 값이 없거나 포커스가 없을 때 |
| `hover` | 1px `--atom-fg-neutral-subtle` | 마우스가 올라갔을 때 |
| `focused` | 2px `--atom-primary-600` | 커서가 들어와 있을 때 |
| `invalid` | 2px `--atom-fg-critical` | 검증에 실패했을 때 |
| `readonly` | 없음 · `--atom-bg-neutral-weak` 배경 | 값은 보여주되 수정은 막을 때 |
| `disabled` | 없음 · 회색 배경 · `opacity: 0.45` | 선행 조건이 충족되지 않았을 때 |

`focused` 는 `.atom-text-input--focused` 클래스와 `:focus-within` 두 경로로 모두 걸립니다.
데모에서는 클래스로 상태를 고정할 수 있고, 실제 사용에서는 `:focus-within` 이 자동으로 따라갑니다.

> [!NOTE]
> `readonly` 와 `disabled` 는 다릅니다. `readonly` 는 값을 읽고 복사할 수 있고 폼 제출에
> 포함되지만, `disabled` 는 둘 다 아닙니다.

---

## 4. Props

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `shape` | `"textInput" \| "textarea"` | `"textInput"` | | 한 줄 · 여러 줄 중 어느 것으로 렌더할지 결정합니다. |
| `size` | `"small" \| "medium" \| "large"` | `"medium"` | | 높이와 폰트 크기를 결정합니다. |
| `variant` | `"outline" \| "weak"` | `"outline"` | | 테두리와 배경 처리를 결정합니다. |
| `prefix` | `ReactNode` | | | 입력 앞에 고정되는 아이콘이나 단위입니다. |
| `suffix` | `ReactNode` | | | 입력 뒤에 고정되는 아이콘이나 단위입니다. |
| `clearable` | `boolean` | `false` | | 값이 있을 때 Clear 버튼을 노출합니다. |
| `invalid` | `boolean` | `false` | | 테두리를 오류 색으로 바꿉니다. |
| `readOnly` | `boolean` | `false` | | 값은 읽을 수 있고 수정만 막습니다. |
| `disabled` | `boolean` | `false` | | 읽기와 제출 모두 막습니다. |
| `rows` | `number` | `3` | | `textarea` 일 때의 기본 줄 수입니다. |

구현 메모:

- `className` · `style` 은 Container 에, 그 밖의 HTML 속성(`id` · `placeholder` · `type` · `inputMode` · `value` · `defaultValue` · `onChange` · `maxLength` …)과 `ref` 는 Control(`<input>` / `<textarea>`) 에 붙습니다.
- `size` 를 지정하지 않으면 [Field](./field.md) 의 `size` 를 따르고, Field 밖이면 `"medium"` 입니다.
- Clear 를 누르면 Control 값을 비우고 `onChange` 를 부른 뒤 Control 에 포커스를 돌려줍니다(controlled · uncontrolled 모두).

### Parts (compound)

Text Input 은 단일 컴포넌트입니다. Prefix · Suffix 는 원본 Props 대로 `prefix` · `suffix` 로 받습니다.

| Part | 요소 | 설명 |
|---|---|---|
| `TextInput` | `<div class="atom-text-input">` + `<input>` / `<textarea class="atom-text-input__control">` | Container 와 Control. 위 Props 를 받습니다. |
| (Prefix · Suffix) | `<span class="atom-text-input__prefix">` · `__suffix` | `prefix` · `suffix` 가 있을 때. |
| (Clear) | `<button type="button" class="atom-text-input__clear" aria-label="지우기">` | `clearable` 이고 값·포커스가 있을 때. |

---

## 5. Component tokens

| 대상 | 속성 | Token | Value |
|---|---|---|---|
| Container | gap | `{space.x2}` | 8px |
| Container | padding | `{space.x3}` `{space.x4}` | 12px 16px |
| Container (`small`) | padding | `{space.x2}` `{space.x3}` | 8px 12px |
| Container (`large`) | padding-inline | `{space.x5}` | 20px |
| Container | radius | `{radius.r2}` | 8px |
| Container (`large`) | radius | `{radius.r3}` | 12px |
| Container | background | `{color.bg.layer}` | |
| Container | min-height | `{control.h}` | 48px |
| Container (`small` · `large`) | min-height | `{control.h-small}` · `{control.h-large}` | 40 · 56px |
| Container | border | `{control.border}` | `{color.border.default}` 1px inset |
| `weak` | background | `{color.bg.neutral-weak}` | 테두리 없음 |
| Control | color | `{color.fg.neutral}` | |
| Placeholder | color | `{color.fg.neutral-subtle}` | |
| Prefix · Suffix | color | `{color.fg.neutral-muted}` | 14px, 아이콘 18px |
| Clear | background · color | `{color.bg.neutral-weak}` · `{color.fg.neutral-muted}` | 20px 원, 아이콘 12px |
| Clear | radius | `{radius.full}` | 9999px |
| hover | border | `{control.border-hover}` | `{color.fg.neutral-subtle}` 1px inset |
| focused | border | `{control.border-focus}` | `{color.primary.600}` 2px inset |
| invalid | border | `{control.border-invalid}` | `{color.fg.critical}` 2px inset |
| readonly · disabled | background | `{color.bg.neutral-weak}` | |
| Caret | animation | `atom-text-input-blink` | `1.1s steps(1) infinite` |
| transition | duration | `{duration.fast}` | 120ms |

최소 높이와 테두리는 `--atom-control-*` 토큰입니다. Select · Date Input · Time Input 등
필드에 조합되는 컨트롤이 같은 값을 공유합니다. 폰트(14 · 15 · 16px)와 행간 1.45 는
토큰이 아닙니다.

```json
{
  "text-input": {
    "gap": { "$type": "dimension", "$value": "{space.x2}" },
    "padding": {
      "$type": "dimension",
      "default": { "block": { "$value": "{space.x3}" }, "inline": { "$value": "{space.x4}" } },
      "small":   { "block": { "$value": "{space.x2}" }, "inline": { "$value": "{space.x3}" } },
      "large":   { "inline": { "$value": "{space.x5}" } }
    },
    "radius": {
      "$type": "dimension",
      "default": { "$value": "{radius.r2}" },
      "large":   { "$value": "{radius.r3}" }
    },
    "min-height": {
      "$type": "dimension",
      "default": { "$value": "{control.h}" },
      "small":   { "$value": "{control.h-small}" },
      "large":   { "$value": "{control.h-large}" }
    },
    "bg": { "$type": "color", "$value": "{color.bg.layer}" },
    "border": {
      "$type": "shadow",
      "default": { "$value": "{control.border}" },
      "hover":   { "$value": "{control.border-hover}" },
      "focused": { "$value": "{control.border-focus}" },
      "invalid": { "$value": "{control.border-invalid}" }
    },
    "weak-bg":        { "$type": "color", "$value": "{color.bg.neutral-weak}" },
    "control-color":  { "$type": "color", "$value": "{color.fg.neutral}" },
    "placeholder":    { "$type": "color", "$value": "{color.fg.neutral-subtle}" },
    "affix":          { "$type": "color", "$value": "{color.fg.neutral-muted}" },
    "clear": {
      "bg":     { "$type": "color", "$value": "{color.bg.neutral-weak}" },
      "fg":     { "$type": "color", "$value": "{color.fg.neutral-muted}" },
      "radius": { "$type": "dimension", "$value": "{radius.full}" }
    },
    "readonly-bg":  { "$type": "color", "$value": "{color.bg.neutral-weak}" },
    "transition":   { "$type": "duration", "$value": "{duration.fast}" }
  }
}
```

---

## 6. 접근성

- **라벨은 필수** — 라벨 없는 입력은 무엇을 넣는 칸인지 알 수 없고 스크린리더가 읽을 것이
  없습니다. [Form Field](./field.md) 로 감싸는 것이 기본이고, 시각적
  라벨을 둘 수 없는 예외적 경우에만 `aria-label` 을 직접 붙입니다.
- **키보드** — `Tab` 으로 들어오면 기존 값이 전체 선택됩니다. 그 밖의 조작은 브라우저
  기본 동작입니다.
- **`aria-invalid`** — `--invalid` 클래스는 색만 바꿉니다. 스크린리더에 알리려면
  `aria-invalid="true"` 를, 오류 문구 연결에는 `aria-describedby` 를 함께 지정합니다.
- **오류 안내** — 오류 메시지가 나타날 때 스크린리더가 읽도록 하려면 그 영역을
  `role="alert"` 또는 `aria-live="polite"` 로 두어야 합니다. ATOM 은 이 배선을 아직
  컴포넌트에 담고 있지 않으므로 사용하는 쪽에서 처리해야 합니다.
- **Clear 버튼** — 아이콘만 있으므로 `aria-label="지우기"` 가 필요합니다.
  `<button type="button">` 으로 만들어 `Enter` 로 눌리게 합니다.
- **Prefix · Suffix** — 값의 일부가 아니라 장식이라면 `aria-hidden="true"` 를 붙입니다.
  단위처럼 의미가 있으면 라벨에 포함시키는 편이 낫습니다 ("금액 (원)").
- **대비** — 기본 테두리 `--atom-border-default` 는 흰 배경 대비 **1.36:1** 로
  WCAG 1.4.11 의 3:1 에 미달합니다. 포커스 시 `--atom-primary-600`(8.43:1)으로 바뀌므로
  포커스 표시는 문제없습니다. [Color](../foundation/color.md) 참조.
- **플레이스홀더 대비** — `--atom-fg-neutral-subtle` 은 흰 배경 대비 **2.57:1** 입니다.
  따라서 읽어야 하는 정보는 플레이스홀더에 담지 않습니다.
- **터치 영역** — `small`(40px)은 권장 최소 44px 에 4px 못 미칩니다. 모바일 폼에는
  `medium`(48px) 이상을 씁니다.
- **강제 색상 모드** — 테두리를 `inset box-shadow` 로 그리므로 Windows 고대비 모드에서
  입력 칸의 경계가 사라집니다.

> 구현: `invalid` (또는 Field 의 invalid) 이면 Control 에 `aria-invalid="true"` 를, Field 안에서는 `id` · `aria-describedby` · `required` · `disabled` 를 Field 에서 받아 Control 에 붙입니다.

---

## 7. 사용 가이드

### 입력 종류에 맞는 키보드

모바일에서 `type` 과 `inputmode` 를 지정하면 알맞은 키보드가 올라와 숫자 입력이
빨라집니다.

- ✅ **Do** 숫자 입력에는 숫자 키패드를 띄웁니다.
- ❌ **Don't** 모든 칸을 `type="text"` 로 두지 않습니다.

| 입력값 | `type` | `inputmode` |
|---|---|---|
| 휴대폰 번호 | `tel` | `numeric` |
| 가격 · 수량 | `text` | `numeric` |
| 이메일 | `email` | `email` |
| 검색어 | `search` | — |
| URL | `url` | `url` |

### 문장을 받는 칸은 Textarea 로

한 줄 입력에 긴 글을 적으면 앞부분이 스크롤되어 가려지므로 쓴 내용을 검토하기 어렵습니다.

- ✅ **Do** 여러 줄이 예상되는 칸은 [Textarea](#textarea) 로 둡니다.
- ❌ **Don't** 긴 글을 한 줄 입력으로 받지 않습니다.

### 형식이 정해진 값은 칸을 쪼개지 않습니다

전화번호나 주민등록번호를 세 칸으로 나누면 칸을 이동하며 입력해야 하고, 붙여넣기가
동작하지 않습니다. 한 칸으로 받고 입력에 맞춰 포맷을 자동 적용하세요.

- ✅ **Do** 한 칸에서 `010-1234-5678` 로 자동 포맷합니다.
- ❌ **Don't** 전화번호를 3분할 입력으로 만들지 않습니다.

### 플레이스홀더는 형식 예시

- 라벨을 반복하지 않습니다. 예: `이름` 라벨 아래 `이름` 플레이스홀더.
- 형식이 헷갈리는 값에는 예시를 보여줍니다. `예: 1994-03-21`
- 필수 정보를 플레이스홀더에만 담지 않습니다. 플레이스홀더는 입력을 시작하면 사라지고,
  자동 완성으로 값이 채워지면 표시되지 않습니다.

- ✅ **Do** 라벨은 [Label](./field.md#label) 에 두고, 플레이스홀더는 형식 예시로 씁니다.
- ❌ **Don't** 라벨을 없애고 플레이스홀더만 남기지 않습니다.

### 가로로 두 칸을 나란히 놓을 때

라벨과 입력값이 짧을 때만 2열로 배치하고, 칸 사이 간격을 충분히 둡니다. 간격이 좁으면 옆
칸을 잘못 누르기 쉽습니다.

- ✅ **Do** 시·도 / 우편번호처럼 짧은 값만 2열로 둡니다.
- ⚠️ **Caution** 2열 사이 간격은 최소 `--atom-x4`(16px) 를 둡니다.
- ❌ **Don't** 긴 주소 입력을 2열로 쪼개지 않습니다.

### 다른 요소와 한 줄에 놓을 때

검색 줄 · 툴바처럼 Input 을 다른 요소와 한 줄에 놓으면, 높이가 한 픽셀만 달라도 줄이
어긋나 보입니다. 상자가 있는 요소는 높이를 맞추고, 상자가 없는 요소는 가운데에 둡니다.

| 요소 | 맞추는 방법 |
|---|---|
| Input · [Select](./select.md) · [Button](./button.md) | **같은 높이.** 셋 모두에 같은 `size` 를 줍니다 |
| [Checkbox](./checkbox.md) · [Radio](./radio.md) · [Switch](./switch.md) · 텍스트 · 단위 · [Badge](./badge.md) · 아이콘 | **세로 가운데 정렬.** 옆 상자의 높이 안에서 가운데에 둡니다 |

- ✅ **Do** 한 줄의 Input · Select · Button 은 높이가 같고, 나머지는 그 가운데에 섭니다.
- ❌ **Don't** `size` 를 섞거나 위쪽 정렬로 두지 않습니다.

> [!WARNING]
> **Button 은 같은 `size` 여도 1–2px 낮습니다**
> Input · Select 는 `--atom-control-h` 계열(40 · 48 · 56px)을 쓰지만 Button 은 고정
> 높이(38 · 47 · 54px)라, 그냥 나란히 두면 어긋납니다. 한 줄을
> [Field](./field.md#control) 의 `__control` 슬롯으로 묶으세요. 슬롯이
> Button 높이를 행에 맞추고, Icon Button 을 정사각형으로, Checkbox 를 가운데로 둡니다.

#### 버튼은 아이콘 먼저, 모호하면 짧은 텍스트

Input 옆 버튼은 뜻이 바로 읽히는 **아이콘 버튼**(`--layout_icon-only`)이 기본입니다.
아이콘만으로 무엇을 하는지 짐작하기 어려우면 **간결한 텍스트 버튼**으로 만듭니다.

| 동작 | 버튼 | 이유 |
|---|---|---|
| 검색 · 찾기 | 돋보기 아이콘 | 누구나 같은 뜻으로 읽습니다 |
| 지우기 | × 아이콘 | 〃 |
| 날짜 선택 | 달력 아이콘 | 〃 |
| 중복 확인 · 인증 · 적용 · 발송 | `중복 확인` 같은 짧은 텍스트 | 맞는 아이콘이 없거나, 있어도 뜻이 여럿입니다 |

- ✅ **Do** 검색은 돋보기 아이콘, 중복 확인은 `중복 확인` 텍스트로 둡니다.
- ❌ **Don't** 아이콘이면 충분한 곳에 긴 문장을 쓰거나, 뜻이 모호한 아이콘을 쓰지 않습니다.

- 텍스트는 동사 하나 또는 `명사 + 동사` 두 단어까지 씁니다. `~하기` 는 붙이지 않습니다.
- 아이콘 버튼에는 `aria-label` 로 동작 이름을 반드시 붙여, 스크린 리더에서 텍스트 버튼과
  같은 이름으로 읽히게 합니다.

### 관련 컴포넌트

- [Field](./field.md) — 라벨·도움말·글자 수를 붙일 때.
- [Select](./select.md) — 정해진 목록에서 고를 때.

---

## 8. 예시

```tsx
<TextInput prefix="₩" suffix="원" inputMode="numeric" placeholder="0" aria-label="금액" />

<TextInput prefix={<SearchGlassIcon />} variant="weak" type="search" clearable placeholder="검색" aria-label="검색" />

<TextInput type="email" invalid aria-describedby="email-error" />
```

```html
<div class="atom-text-input">
  <span class="atom-text-input__prefix">₩</span>
  <input class="atom-text-input__control" type="text" inputmode="numeric"
         placeholder="0" aria-label="금액" />
  <span class="atom-text-input__suffix">원</span>
</div>
```

```html
<!-- 오류 상태 — Form Field 로 감싸 메시지를 연결합니다 -->
<div class="atom-text-input atom-text-input--invalid">
  <input class="atom-text-input__control" type="email"
         aria-invalid="true" aria-describedby="email-error" />
</div>
```

---

## Textarea

여러 줄 문장을 입력받는 컴포넌트.

> [!NOTE]
> **독립된 컴포넌트가 아닙니다**
> Textarea 는 [Input](#text-input--textarea) 과 같은 CSS 파일 안의 `--textarea` modifier 입니다.
> 테두리·상태·크기·Prefix/Suffix 규칙이 전부 같고, 다른 것은 **높이와 정렬** 두 가지뿐입니다.
> 이 문서는 그 차이만 다루고, 공통 규칙은 [Input](#text-input--textarea) 을 참고하세요.
> `spec_source` 가 `derived` 인 것은 Textarea 전용 수치가 CSS 에 세 줄뿐이기 때문입니다.

### 구성

Input 과 같이 테두리를 그리는 **Container** 와 그 안의 **Control** 로 나뉩니다. 단 Container 의
`align-items` 가 `center` 에서 `flex-start` 로 바뀝니다. 여러 줄일 때 Prefix 와 Clear
버튼을 **첫 줄에 맞추기** 위해서입니다.

### 종류 / 크기

#### Shape

`--textarea` modifier 하나로 전환됩니다. 사용자가 문장을 쓰게 될 자리라면 Textarea,
값의 길이가 예측 가능하고 한 줄이면 [Input](#text-input--textarea) 입니다.

#### 높이

| 대상 | 값 |
|---|---|
| Container 최소 높이 | 92px |
| Control 최소 높이 | 66px |
| Input(`medium`) 최소 높이 | 48px |

92px 는 15px 폰트에 행간 1.45(약 22px)를 기준으로 **약 3줄** 분량입니다.
Input 과 높이가 달라야 긴 글을 쓰는 칸으로 인식됩니다.

> [!WARNING]
> **`size` 와 `--textarea` 를 함께 쓰면 높이가 어긋납니다**
> `--textarea` 는 `min-height: 92px` 를 고정으로 씁니다. `--size_small`(40px)이나
> `--size_large`(56px)를 함께 걸어도, CSS 에서 `--textarea` 규칙이 사이즈 규칙보다 뒤에
> 있어 92px 가 적용됩니다. 사이즈별 Textarea 높이는 정의되어 있지 않습니다.

#### 리사이즈

Control 에 `resize: none` 이 걸려 있어 **사용자가 크기를 조절할 수 없습니다.**
브라우저 기본 리사이즈 핸들이 나타나지 않습니다.

| 방식 | 현재 상태 |
|---|---|
| 사용자 드래그 리사이즈 | 꺼져 있음 (`resize: none`) |
| 내용에 따른 자동 확장 | 구현되어 있지 않음 |
| 고정 높이 + 내부 스크롤 | 현재 동작 |

높이를 넘어가는 내용은 Control 안에서 스크롤됩니다.

> [!NOTE]
> **자동 확장은 아직 없습니다**
> 입력 길이에 따라 높이가 늘어나는 동작은 CSS 만으로 만들 수 없어 스크립트가 필요합니다.
> 도입한다면 **최대 높이를 반드시 함께 정하고**, 그 이상은 내부 스크롤로 넘겨야 합니다.
> 최대 높이가 없으면 긴 글에서 제출 버튼이 화면 밖으로 밀려납니다.

#### State · Variant · Prefix · Suffix

[Input](#text-input--textarea) 과 완전히 같습니다. `hover` · `focused` · `invalid` · `readonly` ·
`disabled`, `outline` / `weak` variant 모두 같은 규칙으로 동작합니다.

#### Field 와 함께

글자 수 카운터는 Textarea 가 아니라 [Form Field](./field.md) 의
`__counter` 가 담당합니다.

### Props

[Input](#text-input--textarea) 과 같은 props 를 쓰고, `shape="textarea"` 로 전환합니다.

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `shape` | `"textInput" \| "textarea"` | `"textInput"` | | `"textarea"` 로 지정하면 여러 줄이 됩니다. |
| `rows` | `number` | `3` | | 기본 줄 수입니다. |
| `variant` | `"outline" \| "weak"` | `"outline"` | | 테두리와 배경 처리를 결정합니다. |
| `invalid` | `boolean` | `false` | | 테두리를 오류 색으로 바꿉니다. |
| `readOnly` | `boolean` | `false` | | 값은 읽을 수 있고 수정만 막습니다. |
| `disabled` | `boolean` | `false` | | 읽기와 제출 모두 막습니다. |
| `maxLength` | `number` | | | 입력 가능한 최대 글자 수입니다. |

`size` 는 받되 높이에는 영향을 주지 않습니다 (위 경고 참조). 폰트 크기만 바뀝니다.

구현: 별도 `Textarea` 컴포넌트는 없습니다. `<TextInput shape="textarea" />` 가 `<textarea class="atom-text-input__control">` 를 렌더합니다.

### Component tokens

Textarea 전용으로 추가되는 값은 아래 세 줄뿐입니다. 나머지는 [Input](#5-component-tokens) 과 같습니다.

| 대상 | 속성 | 값 |
|---|---|---|
| `.atom-text-input--textarea` | `min-height` | `92px` |
| `.atom-text-input--textarea` | `align-items` | `flex-start` |
| `.atom-text-input--textarea .atom-text-input__control` | `min-height` | `66px` |

세 값 모두 토큰이 아닙니다. `--atom-x` 스케일에 92 · 66 이 없기 때문입니다
([Spacing](../foundation/spacing.md) 의 결번 참조).

### 접근성

- **라벨은 필수** — [Input](#text-input--textarea) 과 같습니다.
  [Form Field](./field.md) 로 감싸는 것이 기본입니다.
- **키보드** — `Tab` 으로 들어오면 기존 값이 전체 선택됩니다. `Enter` 는 줄바꿈이고
  폼을 제출하지 않습니다. `Tab` 은 다음 요소로 이동합니다. 탭 문자를 입력받게 하면 키보드
  사용자가 Textarea 를 빠져나갈 수 없으므로 탭 문자는 넣지 않습니다.
- **글자 수 카운터** — 값이 바뀔 때마다 스크린리더가 숫자를 읽으면 방해가 됩니다.
  카운터에는 `aria-live` 를 걸지 않고, 제한에 가까워질 때만 알리거나
  `aria-describedby` 로 "200자까지" 라는 정적 안내를 연결하는 편이 낫습니다.
- **`maxlength`** — 브라우저는 초과 입력을 알림 없이 잘라냅니다. 붙여넣은 긴 글이 잘려도
  알기 어려우므로 카운터를 함께 노출합니다.
- **`resize: none`** — 사용자가 칸을 넓힐 수 없으므로, 확대 상태나 좁은 화면에서 내용이
  보이는 범위가 제한됩니다. 최소 높이를 넉넉히 두는 것이 이 제약을 보완합니다.
- **대비 · 강제 색상 모드** — [Input](#text-input--textarea) 과 같습니다.

### 사용 가이드

#### Input 으로 오인되지 않을 높이를 둡니다

Textarea 가 Input 과 높이가 비슷하면 한 줄 입력으로 오인됩니다. 최소 3줄 분량의 높이를
둡니다.

- ✅ **Do** 최소 높이 92px(약 3줄)를 유지합니다.
- ❌ **Don't** Input 높이(48px)에 가깝게 줄이지 않습니다.

#### 기대하는 답변 길이만큼 보여줍니다

높이는 기대하는 답변 분량을 나타냅니다. 한 문장을 받을 칸에 10줄 높이를 두거나, 긴 후기를
받을 칸에 3줄만 두지 않습니다.

- ✅ **Do** 기대 분량에 맞춰 높이를 정합니다.
- ❌ **Don't** 모든 Textarea 를 같은 높이로 두지 않습니다.

#### 글자 수 제한이 있을 때만 카운터를

제한이 없으면 카운터를 두지 않습니다. 제한이 있으면 반드시 보여줍니다. 제한을 모르고
입력하면 내용이 잘릴 수 있습니다.

- ✅ **Do** `maxlength` 가 있으면 Field 의 카운터를 함께 켭니다.
- ❌ **Don't** 제한이 없는 칸에 글자 수를 세지 않습니다.

#### 줄바꿈이 제출이 되지 않게

Textarea 안에서 `Enter` 는 줄바꿈입니다. 채팅 입력처럼 `Enter` 로 전송해야 한다면
`Shift + Enter` 로 줄바꿈할 수 있음을 반드시 안내합니다.

- ✅ **Do** 전송 단축키를 쓰면 힌트를 함께 노출합니다.
- ❌ **Don't** 안내 없이 `Enter` 를 제출로 가로채지 않습니다.

#### 한국어 문장은 단어 단위로 줄바꿈

Container 자체에는 `word-break` 규칙이 없습니다. 긴 한국어 문장이 들어가는 자리라면
`.atom-break-keep` 을 함께 씁니다.
[Typography](../foundation/typography.md) 의 줄바꿈 규칙을 참고하세요.

### 예시

```tsx
<TextInput
  shape="textarea"
  rows={3}
  maxLength={200}
  placeholder="예: 처리가 빨라서 좋았어요"
  aria-label="후기"
/>
```

```html
<div class="atom-text-input atom-text-input--textarea">
  <textarea
    class="atom-text-input__control atom-break-keep"
    rows="3"
    maxlength="200"
    placeholder="예: 처리가 빨라서 좋았어요"
    aria-label="후기"
  ></textarea>
</div>
```

```html
<!-- Field 로 감싸 카운터를 붙입니다 -->
<div class="atom-field">
  <div class="atom-field__header">
    <label class="atom-field__label" for="review">후기</label>
  </div>
  <div class="atom-field__control">
    <div class="atom-text-input atom-text-input--textarea">
      <textarea class="atom-text-input__control" id="review" maxlength="200"></textarea>
    </div>
  </div>
  <div class="atom-field__footer">
    <span class="atom-field__description">200자까지 쓸 수 있어요</span>
    <span class="atom-field__counter">0/200</span>
  </div>
</div>
```