sam-react-prod/claudedocs/guides/[FIX-2025-12-05] radix-ui-select-controlled-mode-bug.md

Radix UI Select Controlled Mode 버그 해결

작성일: 2025-12-05 문제 유형: UI 컴포넌트 버그 적용 범위: 모든 Dropdown/Select 필드

---

문제 현상

Edit 모드에서 Select/Dropdown 컴포넌트에 기존 값이 표시되지 않음

증상:

• API에서 데이터 정상 수신 (예: unit: 'M')
• formData에 값 정상 매핑 (예: 98_unit: 'M')
• resetForm 정상 호출
• DropdownField에 value prop 정상 전달 (rawValue: 'M')
• 하지만 UI에 선택된 값이 표시되지 않음!

---

원인

Radix UI Select의 Controlled Mode 버그

Select 컴포넌트가 빈 값('')으로 처음 마운트되면, 이후 value prop이 변경되어도 내부 상태가 업데이트되지 않는 문제

문제 코드:

<Select
  value={stringValue}  // 처음에 '' → 나중에 'M'으로 변경되어도 UI 반영 안됨
  onValueChange={onChange}
>

---

해결책

key prop으로 강제 리마운트

<Select
  key={`${fieldKey}-${stringValue}`}  // value 변경 시 컴포넌트 리마운트
  value={stringValue}
  onValueChange={onChange}
>

---

적용 파일

src/components/items/DynamicItemForm/fields/DropdownField.tsx

수정 전:

<Select
  value={stringValue}
  onValueChange={onChange}
  disabled={disabled || !hasOptions}
>

수정 후:

<Select
  key={`${fieldKey}-${stringValue}`}
  value={stringValue}
  onValueChange={onChange}
  disabled={disabled || !hasOptions}
>

---

적용 범위

이 수정은 DropdownField 컴포넌트를 사용하는 모든 품목 유형에 자동 적용됨:

• ✅ 소모품 (CS)
• ✅ 원자재 (RM)
• ✅ 부자재 (SM)
• ✅ 부품 (PT)
• ✅ 제품 (FG)

---

디버깅 가이드

Edit 모드에서 Select 값이 안 나올 때 체크리스트:

1. API 데이터 확인

[EditItem] ========== API 원본 데이터 ==========
unit: M        ← 값 있음 ✅
specification: null  ← 백엔드에서 안 줌 ❌

2. 필드 매핑 확인

[DynamicItemForm] fieldKeyMap: {unit: '98_unit', ...}
[DynamicItemForm] Mapped initialData: {98_unit: 'M', ...}

3. resetForm 확인

[useDynamicFormState] resetForm 호출됨: {98_unit: 'M', ...}

4. DropdownField 확인

[DropdownField] 단위 필드 디버깅:
  rawValue: 'M'           ← 값 있음 ✅
  valueInOptions: true    ← 옵션에 존재 ✅

모든 값이 정상인데 UI에 안 나오면 → key prop 문제!

---

관련 이슈

추가 발견 사항

API 응답에서 일부 필드가 누락될 수 있음:

• specification: null → DB에 값 없거나 API 응답에서 제외
• note: undefined → API 응답에 필드 자체가 없음
• remarks: null → DB에 값 없음

이런 경우 백엔드 API 수정 요청 필요

---

참고

• Radix UI Select 공식 문서에서는 이 동작을 버그로 인정하지 않음
• React의 controlled component 패턴에서 초기값 변경 시 발생하는 일반적인 문제
• key prop 패턴은 React 공식 권장 해결책