# Input Button

입력처럼 보이지만 실제로는 버튼입니다. 값을 고르는 일이 다른 화면에서 일어날 때 씁니다.

> 원본: `03_ASSET_GUIDE/catalog/input-button.js` · CSS: `03_ASSET_GUIDE/styles/elements/input-button.css`
> kind `element` · category `action-input` · status `stable` · specSource **없음** · **`hidden: true`**

> [!WARNING]
> **원본 문서가 미완성입니다**
> - 원본은 카탈로그에서 숨겨져 있습니다(`meta.hidden: true`).
> - `meta.specSource` 가 지정되어 있지 않습니다. 아래 수치는 실측(`measured`)·계산(`derived`) 근거가 표시되지 않은 값입니다
>   (원본 registry `spec-source-missing`).
> - Specification 이 미완성입니다. `### Props` · `### Design Tokens` · `### Markup` 소제목과 Accessibility 절이 없습니다
>   (원본 registry `specification-incomplete`). Props 표와 Markup 은 소제목 없이 Specification 바로 아래에 있어 registry 가 읽지 못합니다.
>
> 이 문서는 원본에 있는 내용만 옮기고, 원본에 없는 절은 **(원본 없음)** 으로 표시합니다.
> 구현이 정한 내용은 **구현 기준(원본 없음)** 으로 따로 표시합니다.

---

## 1. 구성

**Value** 와 오른쪽 **Caret** 이 필수 구성입니다. Caret 은 다른 화면으로 이어진다는 표시이므로 생략하지 않습니다.

```
┌──────────────────────────────────┐
│ [📅]  2026년 8월 19일          ›  │
└──────────────────────────────────┘
 ①  ②        ③                  ④
```

| # | 요소 | 필수 | 클래스 | 설명 |
|---|---|---|---|---|
| ① | Container | 필수 | `atom-input-button` | `<button type="button">`. 입력처럼 테두리·배경을 그립니다. |
| ② | Prefix Icon | 선택 | `atom-input-button__prefix` | 값 앞에 놓이는 20px 아이콘. |
| ③ | Value | 필수 | `atom-input-button__value` | 고른 값, 또는 값이 없을 때의 안내 문구. |
| ④ | Caret | 필수 | `atom-input-button__caret` | 오른쪽 화살표(`chevron-right`). 다른 화면으로 이어진다는 표시. |

> [!NOTE]
> **직접 입력하는 값에는 Input Button 을 쓰지 않습니다**
> 키보드로 값을 직접 적을 수 있다면 [Text Input](./text-input.md) 을, 그 자리에서 목록이 펼쳐진다면 [Select](./select.md) 를 쓰세요. Input Button 은 **화면이 바뀔 때만** 씁니다.

---

## 2. 종류 / 크기

### Variant

`outline` 이 기본입니다. 폼 안에 입력 칸이 여러 개 쌓여 테두리가 복잡해 보일 때 `weak` 를, 리스트 행 자체가 이미 구분선을 가지고 있을 때 `ghost` 를 씁니다.

### Size

높이는 컨트롤 공통 토큰입니다 — `medium` 은 `--atom-control-h`(48px), `small` · `large` 는 40 · 56px 이고 [Text Input](./text-input.md) · [Select](./select.md) · [Date Input](./date-input.md) · [Time Input](./time-input.md) 이 같은 값을 씁니다. 같은 `size` 를 주면 한 줄에 나란히 놓아도 어긋나지 않습니다.

테두리와 포커스 링도 같은 토큰입니다 — `--atom-control-border`(1px `--atom-border-default`), `:focus-visible` 에서 `--atom-control-border-focus`(2px `--atom-primary-600`). 모서리만 `--atom-radius-r3`(12px)로 Input 의 `r2`(8px)보다 한 단계 큽니다.

### Field 와 함께

라벨과 도움말이 필요하면 [Field](./field.md) 로 감쌉니다. Field 는 컨트롤 종류를 가리지 않습니다.

### 클래스 계약

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

| Prop | 값 | 클래스 |
|---|---|---|
| `size` | `small` · `medium` · `large` | `--size_small` · — · `--size_large` |
| `variant` | `outline` · `weak` · `ghost` | — · `--variant_weak` · `--variant_ghost` |
| (값 없음) | `value` 가 비어 있음 | `--empty` |

상태 선택자: `--empty` · `[data-invalid]` · `[disabled]` · `:hover` · `:focus-visible`

---

## 3. 상태

값이 없는 `empty` 상태에서는 Value 가 플레이스홀더 색으로 흐려집니다. 값이 채워지면 본문 색이 됩니다.

원본 데모의 상태는 `empty` · `filled` · `invalid` · `disabled` 네 가지입니다. 원본에는 상태 표가 없어, 아래 표현·선택자는 CSS 에서 읽은 것입니다(**구현 기준(원본 없음)**).

| State | 표현 (CSS) | 선택자 |
|---|---|---|
| `empty` | Value 를 `--atom-fg-neutral-subtle` 로 | `--empty` |
| `filled` | Value 본문 색 | — |
| `hover` | 배경 `--atom-bg-neutral-weak` (`weak` 는 `filter: brightness(0.96)`) | `:hover:not([disabled])` |
| `focus` | 2px `--atom-primary-600` 안쪽 링 | `:focus-visible` |
| `invalid` | 2px 오류 색 테두리 | `[data-invalid]` |
| `disabled` | `opacity: 0.4`, 커서 `not-allowed`, 배경 `--atom-bg-layer` | `[disabled]` |

---

## 4. Props

원본 Specification 바로 아래의 표입니다(`### Props` 소제목 없음).

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `value` | `ReactNode` | | | 선택된 값입니다. 없으면 placeholder 가 보입니다. |
| `placeholder` | `string` | | | 값이 없을 때 보여줄 안내 문구입니다. |
| `size` | `"small" \| "medium" \| "large"` | `"medium"` | | 높이와 폰트 크기를 결정합니다. |
| `variant` | `"outline" \| "weak" \| "ghost"` | `"outline"` | | 배경과 테두리 처리를 결정합니다. |
| `prefixIcon` | `ReactNode` | | | 값 앞에 놓이는 아이콘입니다. |
| `invalid` | `boolean` | `false` | | 테두리를 오류 색으로 바꿉니다. |
| `disabled` | `boolean` | `false` | | 누를 수 없게 만듭니다. |
| `onClick` | `() => void` | | ● | 값을 고르는 화면을 여는 핸들러입니다. |

**구현 기준(원본 없음):**

| 항목 | 구현 |
|---|---|
| 요소 | `<button>` 의 나머지 HTML 속성을 그대로 받습니다(`id` · `aria-*` · `name` …). `type` 기본값은 `"button"`. |
| `ref` | `<button>` 요소를 가리킵니다. |
| `onClick` 타입 | `MouseEventHandler<HTMLButtonElement>` (`() => void` 도 그대로 넘길 수 있습니다). |
| 빈 값 판정 | `value` 가 `undefined` · `null` · `false` · `""` 이면 `--empty` 를 붙이고 `placeholder` 를 보입니다. |
| `size` | 지정하지 않으면 [Field](./field.md) 의 `size` 를 따르고, Field 밖이면 `"medium"` 입니다. |
| Field 연결 | Field 안에서는 `id`, `aria-labelledby`("Field 라벨 + 현재 값"), `aria-describedby`, `invalid` · `disabled` 를 Field 에서 받습니다. |

### Parts (compound)

| Part | 요소 | 설명 |
|---|---|---|
| `InputButton` | `<button type="button" class="atom-input-button">` | Container. 위 Props 를 받습니다. |
| (Prefix) | `prefixIcon` 요소에 `atom-input-button__prefix` 를 합칩니다 | `aria-hidden`. |
| (Value) | `<span class="atom-input-button__value">` | `value` 또는 `placeholder`. |
| (Caret) | `<svg class="atom-input-button__caret">` (`ChevronRightIcon`) | `aria-hidden`. |

---

## 5. Component tokens

> [!WARNING]
> **(원본 없음)** 원본에 Design Tokens 표가 없습니다. 아래는 `input-button.css` 에서 읽은 값이며
> **구현 기준(원본 없음)** 입니다. specSource 도 없으므로 확정 스펙으로 쓰지 마세요.

| 대상 | 속성 | Token | Value |
|---|---|---|---|
| Container | gap | `{space.x3}` | 12px |
| Container | padding-inline | `{space.x4}` | 16px |
| Container (`ghost`) | padding-inline | — | 0 |
| Container | height | `{control.h}` | 48px |
| Container (`small` · `large`) | height | `{control.h-small}` · `{control.h-large}` | 40 · 56px |
| Container | radius | `{radius.r3}` | 12px |
| Container (`small`) | radius | `{radius.r2}` | 8px |
| Container | background | `{color.bg.layer}` | |
| Container | border | `{control.border}` | `{color.border.default}` 1px inset |
| Container | color | `{color.fg.neutral}` | 15px (`small` 14px · `large` 16px) |
| `weak` | background | `{color.bg.neutral-weak}` | 테두리 없음 |
| `ghost` | background | — | `transparent`, 테두리 없음 |
| hover | background | `{color.bg.neutral-weak}` | |
| focus | ring | `{control.border-focus}` | `{color.primary.600}` 2px inset |
| invalid | border | `{control.border-invalid}` | `{color.fg.critical}` 2px inset |
| Prefix | color | `{color.fg.neutral-muted}` | 20px |
| Value (비었을 때) | color | `{color.fg.neutral-subtle}` | |
| Caret | color | `{color.fg.neutral-subtle}` | 18px (`small` 16px) |
| transition | duration | `{duration.fast}` | 120ms |

```json
{
  "input-button": {
    "$description": "구현 기준(원본 없음) — input-button.css 에서 읽은 값. 원본 Design Tokens 표 없음, specSource 없음",
    "gap":            { "$type": "dimension", "$value": "{space.x3}" },
    "padding-inline": { "$type": "dimension", "$value": "{space.x4}" },
    "height": {
      "$type": "dimension",
      "default": { "$value": "{control.h}" },
      "small":   { "$value": "{control.h-small}" },
      "large":   { "$value": "{control.h-large}" }
    },
    "radius": {
      "$type": "dimension",
      "default": { "$value": "{radius.r3}" },
      "small":   { "$value": "{radius.r2}" }
    },
    "bg":       { "$type": "color", "$value": "{color.bg.layer}" },
    "bg-hover": { "$type": "color", "$value": "{color.bg.neutral-weak}" },
    "weak-bg":  { "$type": "color", "$value": "{color.bg.neutral-weak}" },
    "border": {
      "$type": "shadow",
      "default": { "$value": "{control.border}" },
      "focus":   { "$value": "{control.border-focus}" },
      "invalid": { "$value": "{control.border-invalid}" }
    },
    "color":       { "$type": "color", "$value": "{color.fg.neutral}" },
    "prefix":      { "$type": "color", "$value": "{color.fg.neutral-muted}" },
    "value-empty": { "$type": "color", "$value": "{color.fg.neutral-subtle}" },
    "caret":       { "$type": "color", "$value": "{color.fg.neutral-subtle}" },
    "transition":  { "$type": "duration", "$value": "{duration.fast}" }
  }
}
```

---

## 6. 접근성

> [!WARNING]
> **(원본 없음)** 원본에 Accessibility 절이 없습니다. 아래는 원본 CSS·Markup 과 구현이 따르는
> **구현 기준(원본 없음)** 입니다.

- **요소** — 원본 Markup 대로 `<button type="button">` 입니다. `Tab` 으로 포커스, `Enter` · `Space` 로 `onClick` 이 실행됩니다.
- **포커스 표시** — CSS 의 `:focus-visible` 이 `--atom-control-border-focus` 안쪽 링으로 `base.css` 의 공통 링을 대신합니다.
- **이름** — Field 안에서는 `aria-labelledby` 로 "Field 라벨 + 현재 값(또는 안내 문구)" 을 함께 읽힙니다. Field 밖에서는 Value 텍스트가 이름이 되므로, 무엇을 고르는 칸인지 알 수 있도록 라벨을 붙입니다.
- **아이콘** — Prefix Icon 과 Caret 은 `aria-hidden="true"` 입니다.
- **비활성** — `disabled` 속성을 씁니다(CSS 선택자 `[disabled]`). 포커스를 받지 못합니다.
- **오류** — `invalid` 는 `data-invalid` 로 테두리 색만 바꿉니다. 오류 문구는 Field 의 `aria-describedby` 로 연결됩니다.
  (`aria-invalid` 는 button 역할이 지원하지 않는 속성이라 붙이지 않습니다.)

---

## 7. 사용 가이드

### 고른 값을 그대로 보여주기

선택이 끝나면 고른 값을 버튼 안에 표시합니다. 라벨만 남아 있으면 다시 눌러야 값을 확인할 수 있습니다.

- ✅ **Do** 고르기 전에는 안내를, 고른 뒤에는 값을 보여줍니다.
- ❌ **Don't** 값을 고른 뒤에도 라벨만 남겨두지 않습니다.

### Caret 방향으로 목적지를 알리기

오른쪽 화살표는 '화면이 바뀐다', 아래 화살표는 '이 자리에서 펼쳐진다' 는 뜻입니다. 방향은 실제 동작과 일치시킵니다.

- ✅ **Do** 다음 화면으로 이동하므로 오른쪽 화살표를 씁니다.
- ❌ **Don't** 화면이 바뀌는데 아래 화살표를 쓰지 않습니다.

### 언제 쓰나

| 값을 고르는 방식 | 쓸 컴포넌트 |
|---|---|
| 키보드로 직접 입력 | [Text Input](./text-input.md) |
| 같은 자리에서 목록이 펼쳐짐 | [Select](./select.md) |
| 바텀시트가 올라옴 | **Input Button** |
| 전체 화면(지도, 주소 검색)으로 이동 | **Input Button** |
| 달력이 열림 | **Input Button** + [Date Picker](./date-picker.md) |

### 관련 컴포넌트

- [Text Input & Textarea](./text-input.md) — 직접 타이핑하는 입력.
- [Select](./select.md) — 같은 자리에서 목록이 펼쳐지는 선택.
- [Field](./field.md) — 라벨과 오류 메시지를 붙이는 래퍼.

---

## 8. 예시

```tsx
<InputButton
  prefixIcon={<CalendarIcon />}
  value={date}
  placeholder="날짜를 선택해주세요"
  onClick={openDatePicker}
/>

<InputButton variant="ghost" value="역삼동" onClick={openRegionSheet} />
```

```html
<button class="atom-input-button" type="button">
  <svg class="atom-input-button__prefix" aria-hidden="true">
    <use href="#atom-i-calendar" />
  </svg>
  <span class="atom-input-button__value">2026년 8월 19일</span>
  <svg class="atom-input-button__caret" aria-hidden="true">
    <use href="#atom-i-chevron-right" />
  </svg>
</button>
```