# KBX v24 Component Interaction Contract

## 1. 목적

v23은 Screen Type과 Home/Shell의 구조를 고정했다. v24는 그 화면 안에서 사용자가 실제 입력·조회·검증·복구를 반복할 때 각 Component가 동일한 행동을 보이도록 **runtime interaction contract**를 고정한다.

## 2. Field State

공통 상태:

```text
default
changed
warning
ai-suggested
error
readonly
disabled
```

우선순위:

```text
Error
  > Warning
  > Changed / AI Suggested
  > Default
```

Readonly와 Disabled는 상태 의미가 다르다. Readonly는 업무값을 확인·복사하는 상태이고 Disabled는 현재 업무조건에서 상호작용 자체가 허용되지 않는 상태다.

적용 Component:

- KbxInput / KbxTextField
- KbxNumberField / KbxMoneyField / KbxQuantityField
- KbxDateField / KbxDateRange
- KbxSelect
- KbxLookup
- KbxCheckbox / KbxRadio
- KbxTextarea
- KbxBarcodeField

AI Suggested는 확정값으로 보이지 않도록 별도 semantic state를 사용하며, Error/Warning이 발생하면 AI 상태보다 검증 결과를 우선한다.

## 3. Async State

`KbxDataState`가 다음을 공통 처리한다.

```text
Loading
Empty
Error
Recovery Action
```

첫 조회 Loading은 결과 대신 상태를 표시한다. 기존 데이터가 있는 재조회는 데이터를 지우지 않고 `재조회 중...`을 보조적으로 표시한다.

Error는 해결이 필요한 상태이므로 사라지는 Toast만 사용하지 않는다.

## 4. Grid Runtime

`KbxDataGrid`는 AG Grid wrapper가 아니라 업무 Grid contract다.

v24 보강:

- Loading / Empty / Error
- 기존 데이터 유지 재조회
- Changed Cell
- Invalid Cell + message tooltip
- Selection count
- Cell error count
- CSV export
- Summary count/sum/custom
- F2 Lookup
- Enter editing navigation
- Column resize/move/pin/sort preference emit

### Preference 경계

금지:

```text
Vertical Slice
  -> AG Grid ColumnState 저장
```

권장:

```text
AG Grid state
   ↓ adapter
KbxGridColumnPreference
   ↓
Tenant/User/Screen/ScreenVersion Preference Store
```

`KbxDataGrid`는 `preferenceChanged`, `preferenceReset`을 emit하고 실제 영속화 정책은 Application Preference 계층이 담당한다.

## 5. Search Panel

v24부터 `KbxSearchFieldType`은 다음을 모두 지원한다.

```text
text
date
date-range
select
lookup
checkbox
```

Reset은 무조건 null로 지우지 않고 Field의 `defaultValue`를 복원한다.

추가 UX:

- 상세조건 active count
- 마지막 조회조건 기억
- 저장 조건 진입점
- Checkbox 상세조건

Preference 영속화는 SearchPanel 내부 LocalStorage가 아니라 사용자 Preference 계층으로 연결한다.

## 6. Keyboard Manager

전역 단축키를 화면마다 window keydown으로 등록하지 않는다.

우선순위:

```text
Editor
 ↓
Dialog
 ↓
Grid
 ↓
Page
 ↓
Application
```

보호:

```text
F5
Ctrl+L
Ctrl+T
Ctrl+W
Ctrl+R
```

Scanner keyboard-wedge capture는 일반 shortcut과 다른 입력 lifecycle이므로 `KbxBarcodeCapture` 내부 capture listener를 허용한다.

## 7. Tabs

`KbxTabs`는 native Tab 이동만으로 끝나지 않는다.

```text
ArrowLeft
ArrowRight
Home
End
```

으로 활성 Tab과 focus를 같이 이동한다. `aria-controls`, `tabpanel`, roving tabindex를 유지한다.

## 8. Component Catalog

Catalog는 Component 이름 목록이 아니라 독립 재현 환경이다.

v24에서 실제 화면으로 재현하는 상태:

- Changed
- Warning
- AI Suggested
- Loading
- Empty
- Error
- Search + checkbox/remember
- Grid changed/error/summary/personalization/export
- Tabs keyboard

## 9. 기술부채 Ratchet

v23 최종 design debt literal count:

```text
429
```

v24:

```text
366
```

이번 수치를 새 baseline으로 고정하여 이후 변경은 366을 다시 넘을 수 없다.
