3.7 KiB
KBX v24 Component Interaction Contract
1. 목적
v23은 Screen Type과 Home/Shell의 구조를 고정했다. v24는 그 화면 안에서 사용자가 실제 입력·조회·검증·복구를 반복할 때 각 Component가 동일한 행동을 보이도록 runtime interaction contract를 고정한다.
2. Field State
공통 상태:
default
changed
warning
ai-suggested
error
readonly
disabled
우선순위:
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가 다음을 공통 처리한다.
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 경계
금지:
Vertical Slice
-> AG Grid ColumnState 저장
권장:
AG Grid state
↓ adapter
KbxGridColumnPreference
↓
Tenant/User/Screen/ScreenVersion Preference Store
KbxDataGrid는 preferenceChanged, preferenceReset을 emit하고 실제 영속화 정책은 Application Preference 계층이 담당한다.
5. Search Panel
v24부터 KbxSearchFieldType은 다음을 모두 지원한다.
text
date
date-range
select
lookup
checkbox
Reset은 무조건 null로 지우지 않고 Field의 defaultValue를 복원한다.
추가 UX:
- 상세조건 active count
- 마지막 조회조건 기억
- 저장 조건 진입점
- Checkbox 상세조건
Preference 영속화는 SearchPanel 내부 LocalStorage가 아니라 사용자 Preference 계층으로 연결한다.
6. Keyboard Manager
전역 단축키를 화면마다 window keydown으로 등록하지 않는다.
우선순위:
Editor
↓
Dialog
↓
Grid
↓
Page
↓
Application
보호:
F5
Ctrl+L
Ctrl+T
Ctrl+W
Ctrl+R
Scanner keyboard-wedge capture는 일반 shortcut과 다른 입력 lifecycle이므로 KbxBarcodeCapture 내부 capture listener를 허용한다.
7. Tabs
KbxTabs는 native Tab 이동만으로 끝나지 않는다.
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:
429
v24:
366
이번 수치를 새 baseline으로 고정하여 이후 변경은 366을 다시 넘을 수 없다.