# UVC.UIToolkit 컴포넌트 라이브러리

본 문서는 `Assets/Scripts/UVC/UIToolkit` 폴더의 UI Toolkit 컴포넌트 라이브러리에 대한 참조 가이드입니다.

---

## 1) 폴더 구조

```
Assets/Scripts/UVC/UIToolkit/
├── Button/                      # 버튼 컴포넌트
│   ├── UTKButton.cs            # 메인 버튼 (9가지 variant)
│   ├── UTKCheckBox.cs          # 체크박스
│   ├── UTKToggle.cs            # 토글 스위치
│   ├── UTKRadioButton.cs       # 라디오 버튼
│   └── UTKToggleButtonGroup.cs # 토글 버튼 그룹
├── Card/
│   └── UTKCard.cs              # 카드 컨테이너
├── Common/                      # 공통 유틸리티
│   ├── UTKCodeBlock.cs         # 코드 블록 표시
│   ├── UTKFoldout.cs           # 접이식 컨테이너
│   ├── UTKHelpBox.cs           # 도움말/정보 박스
│   ├── UTKImage.cs             # 이미지 로더 (내부/URL)
│   ├── UTKImageIcons.cs        # 이미지 아이콘 레지스트리
│   ├── UTKMaterialIcons.cs     # Material Symbols (4102개)
│   ├── UTKScrollView.cs        # 커스텀 스크롤 뷰
│   └── UTKTooltipManager.cs    # 툴팁 시스템
├── Dropdown/
│   ├── UTKDropdown.cs          # 일반 드롭다운
│   └── UTKEnumDropDown.cs      # Enum 전용 드롭다운
├── Input/                       # 입력 필드
│   ├── UTKBoundsField.cs       # Bounds 입력
│   ├── UTKDoubleField.cs       # Double 입력
│   ├── UTKFloatField.cs        # Float 입력
│   ├── UTKInputField.cs        # 텍스트 입력
│   ├── UTKIntegerField.cs      # Integer 입력
│   ├── UTKLongField.cs         # Long 입력
│   ├── UTKNumberStepper.cs     # 숫자 스테퍼 (+/-)
│   ├── UTKRectField.cs         # Rect 입력
│   ├── UTKVector2Field.cs      # Vector2 입력
│   ├── UTKVector3Field.cs      # Vector3 입력
│   └── UTKVector4Field.cs      # Vector4 입력
├── Label/
│   └── UTKLabel.cs             # 커스텀 레이블
├── List/                        # 리스트/트리 컴포넌트
│   ├── UTKAccordionList.cs     # 아코디언 리스트 (섹션+그리드)
│   ├── UTKAccordionListItemData.cs
│   ├── UTKComponentList.cs     # 컴포넌트 리스트
│   ├── UTKComponentListItemData.cs
│   ├── UTKImageList.cs         # 이미지 그리드 리스트
│   ├── UTKImageListItemData.cs
│   ├── UTKListView.cs          # 일반 리스트 뷰
│   ├── UTKMultiColumnListView.cs # 다중 컬럼 리스트
│   ├── UTKMultiColumnTreeView.cs # 다중 컬럼 트리
│   ├── UTKTreeListItemData.cs
│   └── UTKTreeView.cs          # 트리 뷰
├── Modal/                       # 모달/다이얼로그
│   ├── UTKAlert.cs             # 알림 다이얼로그
│   ├── UTKColorPicker.cs       # 색상 선택기
│   ├── UTKDatePicker.cs        # 날짜 선택기
│   ├── UTKModal.cs             # 기본 모달
│   ├── UTKModalBlocker.cs      # 모달 배경 블로커
│   ├── UTKNotification.cs      # 알림 토스트
│   ├── UTKPanel.cs             # 패널 컨테이너
│   └── UTKToast.cs             # 토스트 알림
├── Property/                    # 프로퍼티 에디터 시스템
│   ├── Core/                   #   핵심 인터페이스
│   │   ├── IUTKPropertyEntry.cs
│   │   ├── IUTKPropertyGroup.cs
│   │   ├── IUTKPropertyItem.cs
│   │   ├── UTKPropertyGroup.cs
│   │   ├── UTKPropertyType.cs
│   │   └── UTKPropertyValueChangedEventArgs.cs
│   ├── Data/                   #   데이터 타입
│   │   ├── UTKColorState.cs
│   │   └── UTKRangeValue.cs
│   ├── Items/                  #   프로퍼티 아이템 (16종)
│   │   ├── Base/UTKPropertyItemBase.cs
│   │   ├── UTKBoolPropertyItem.cs
│   │   ├── UTKColorPropertyItem.cs
│   │   ├── UTKColorStatePropertyItem.cs
│   │   ├── UTKDatePropertyItem.cs
│   │   ├── UTKDateRangePropertyItem.cs
│   │   ├── UTKDateTimePropertyItem.cs
│   │   ├── UTKDateTimeRangePropertyItem.cs
│   │   ├── UTKDropdownPropertyItem.cs
│   │   ├── UTKEnumPropertyItem.cs
│   │   ├── UTKFloatPropertyItem.cs
│   │   ├── UTKFloatRangePropertyItem.cs
│   │   ├── UTKIntPropertyItem.cs
│   │   ├── UTKIntRangePropertyItem.cs
│   │   ├── UTKRadioPropertyItem.cs
│   │   ├── UTKStringPropertyItem.cs
│   │   ├── UTKVector2PropertyItem.cs
│   │   └── UTKVector3PropertyItem.cs
│   ├── UTKPropertyList.cs      #   프로퍼티 리스트 컨테이너
│   └── UTKPropertyWindow.cs    #   프로퍼티 윈도우
├── Slider/
│   ├── UTKMinMaxSlider.cs      # 범위 슬라이더
│   ├── UTKProgressBar.cs       # 프로그레스 바
│   └── UTKSlider.cs            # 단일 슬라이더
├── Tab/
│   ├── UTKTab.cs               # 개별 탭
│   └── UTKTabView.cs           # 탭 컨테이너
├── Window/                      # 윈도우 컴포넌트
│   ├── UTKAccordionListWindow.cs
│   ├── UTKComponentListWindow.cs
│   ├── UTKComponentTabListWindow.cs
│   ├── UTKImageListWindow.cs
│   └── UTKTreeListWindow.cs
├── UTKStyleGuide.cs            # 스타일 상수 및 색상
└── UTKThemeManager.cs          # 테마 관리 (Light/Dark)
```

---

## 2) 핵심 시스템

### 테마 관리 (UTKThemeManager)

라이트/다크 테마 전환을 관리하는 싱글톤입니다.

```csharp
// 테마 등록 및 전환
UTKThemeManager.Instance.RegisterRoot(rootVisualElement);
UTKThemeManager.Instance.SetTheme(UTKTheme.Dark);
UTKThemeManager.Instance.ToggleTheme();

// 테마 변경 이벤트 구독
UTKThemeManager.OnThemeChanged += OnThemeChanged;

// 관리 USS 파일
// - UTKVariables.uss (CSS 변수)
// - UTKThemeDark.uss / UTKThemeLight.uss (테마별 스타일)
// - UTKComponents.uss (컴포넌트 공통 스타일)
```

### 스타일 가이드 (UTKStyleGuide)

색상, 간격, 폰트, 컴포넌트 크기 등의 상수를 정의합니다.

| 카테고리 | 설명 |
|----------|------|
| Base Colors | Base01~Base21 기본 색상 팔레트 |
| Accent Colors | Blue, Red, Green, Purple, Yellow, Orange, Gray, Seti |
| Semantic Colors | Text, Background, Border, Button, Calendar, State, Scrollbar |

### 아이콘 시스템

**1순위: Material Icons (UTKMaterialIcons)**
```csharp
// 폰트 로드
await UTKMaterialIcons.LoadFontAsync();

// 아이콘 적용
var icon = UTKMaterialIcons.GetIcon("settings");
UTKMaterialIcons.ApplyIconStyle(label, fontSize: 24);

// 버튼에 아이콘 설정
button.SetMaterialIcon(UTKMaterialIcons.Home);
```

**2순위: Image Icons (UTKImageIcons)**
```csharp
// 필요한 아이콘이 Material에 없는 경우에만 사용
var texture = UTKImageIcons.LoadTexture("path/to/icon");
button.SetImageIcon(UTKImageIcons.CustomIcon);
```

> **참고**: Material Icons는 4,102개의 아이콘을 제공하며, 폰트 기반으로 메모리 효율이 높습니다.

---

## 3) 주요 컴포넌트

### UTKButton

다양한 스타일과 크기를 지원하는 버튼 컴포넌트입니다.

**Variants:**
- Normal, Primary, Secondary, Ghost, Danger
- OutlineNormal, OutlinePrimary, OutlineDanger, Text

**Sizes:** Small, Medium, Large

```csharp
var button = new UTKButton("확인", UTKButton.Variant.Primary, UTKButton.Size.Medium);
button.SetMaterialIcon(UTKMaterialIcons.Check);
button.OnClicked += () => Debug.Log("Clicked!");

// UXML 사용
<utk:UTKButton text="확인"
               icon="check"
               variant="Primary"
               size="Medium"
               icon-only="false" />
```

### UTKAccordionList

섹션별 접기/펼치기가 가능한 아코디언 리스트입니다.

```csharp
var accordionList = new UTKAccordionList();
accordionList.SetData(sections); // List<UTKAccordionListItemData>
accordionList.Search("검색어");
accordionList.ExpandAll();
accordionList.CollapseAll();

// 이벤트
accordionList.OnItemClick += (item) => { };
accordionList.OnDragExitList += (item) => { };
accordionList.OnSectionToggled += (section, expanded) => { };
```

**특징:**
- TreeView 기반 가상화
- 검색 필터링
- 드래그 앤 드롭 지원
- 비동기 이미지 로딩 및 캐싱
- 그리드 레이아웃 (2열)

### UTKTreeView / UTKTreeListWindow

계층 구조 데이터를 트리 형태로 표시합니다.

```csharp
var treeView = new UTKTreeView();
treeView.SetData(rootItems); // List<UTKTreeListItemData>

// TreeListWindow 사용
var window = new UTKTreeListWindow();
window.SetData(items);
window.OnItemSelected += (item) => { };
```

### UTKModal / UTKColorPicker / UTKDatePicker

모달 다이얼로그 및 특수 선택기입니다.

```csharp
// 기본 모달
var modal = new UTKModal("제목");
modal.AddContent(contentElement);
modal.AddToFooter(confirmButton);
modal.Show();
modal.OnClosed += () => { };

// 색상 선택기
var colorPicker = new UTKColorPicker();
colorPicker.Color = Color.red;
colorPicker.OnColorChanged += (color) => { };

// 날짜 선택기
var datePicker = new UTKDatePicker();
datePicker.SelectedDate = DateTime.Now;
datePicker.OnDateSelected += (date) => { };
```

### UTKImage

내부 리소스 및 외부 URL에서 이미지를 로드합니다.

```csharp
var image = new UTKImage();

// Resources 로드
await image.LoadAsync("UIToolkit/Icons/sample");

// HTTP/HTTPS 로드
await image.LoadAsync("https://example.com/image.png");

// 이벤트
image.OnImageLoaded += (texture) => { };
image.OnImageFailed += (error) => { };

// 스케일 모드
image.ScaleMode = ScaleMode.ScaleToFit; // ScaleToFit, ScaleAndCrop, StretchToFill
```

---

## 4) 프로퍼티 에디터 시스템

Inspector 스타일의 프로퍼티 편집 시스템입니다.

### 아키텍처

```
IUTKPropertyEntry (기본 인터페이스)
├── IUTKPropertyItem<T>        # 개별 프로퍼티
│   ├── OnValueChanged event
│   ├── GetValue() / SetValue()
│   └── CreateUI() / BindUI() / UnbindUI()
└── IUTKPropertyGroup          # 프로퍼티 그룹
    ├── Items 컬렉션
    ├── AddItem() / RemoveItem()
    └── OnExpandedChanged event
```

### 프로퍼티 타입 (16종)

| 타입 | 클래스 | 설명 |
|------|--------|------|
| String | UTKStringPropertyItem | 텍스트 입력 |
| Int | UTKIntPropertyItem | 정수 (슬라이더 옵션) |
| Float | UTKFloatPropertyItem | 실수 (슬라이더 옵션) |
| Bool | UTKBoolPropertyItem | 토글 스위치 |
| Vector2 | UTKVector2PropertyItem | 2D 벡터 |
| Vector3 | UTKVector3PropertyItem | 3D 벡터 |
| Color | UTKColorPropertyItem | 색상 선택기 |
| Date | UTKDatePropertyItem | 날짜 선택 |
| DateTime | UTKDateTimePropertyItem | 날짜+시간 선택 |
| Enum | UTKEnumPropertyItem | Enum 드롭다운 |
| Dropdown | UTKDropdownPropertyItem | 문자열 드롭다운 |
| Radio | UTKRadioPropertyItem | 라디오 버튼 그룹 |
| IntRange | UTKIntRangePropertyItem | 정수 범위 (Min/Max) |
| FloatRange | UTKFloatRangePropertyItem | 실수 범위 |
| DateRange | UTKDateRangePropertyItem | 날짜 범위 |
| DateTimeRange | UTKDateTimeRangePropertyItem | 날짜+시간 범위 |
| ColorState | UTKColorStatePropertyItem | 색상+상태 (커스텀) |

### 사용 예시

```csharp
// 프로퍼티 윈도우 생성
var propertyWindow = new UTKPropertyWindow("설정");

// 그룹 생성
var generalGroup = new UTKPropertyGroup("일반 설정");

// 프로퍼티 아이템 추가
generalGroup.AddItem(new UTKStringPropertyItem("이름", "기본값"));
generalGroup.AddItem(new UTKIntPropertyItem("레벨", 1, minValue: 1, maxValue: 100));
generalGroup.AddItem(new UTKBoolPropertyItem("활성화", true));
generalGroup.AddItem(new UTKColorPropertyItem("색상", Color.white));

// 그룹을 윈도우에 추가
propertyWindow.PropertyList.AddGroup(generalGroup);

// 값 변경 이벤트
generalGroup.OnValueChanged += (sender, args) => {
    Debug.Log($"{args.PropertyName}: {args.OldValue} → {args.NewValue}");
};
```

**특징:**
- 디바운스 지원 (기본 300ms)
- 읽기 전용 모드
- 툴팁 지원
- IDisposable 패턴으로 메모리 관리

---

## 5) Window 컴포넌트

### UTKAccordionListWindow

아코디언 리스트를 포함한 윈도우입니다.

```csharp
var window = new UTKAccordionListWindow();
window.SetTitle("아이템 목록");
window.SetData(sections);
window.OnItemSelected += (item) => { };
```

### UTKComponentListWindow

컴포넌트 리스트 윈도우입니다.

```csharp
var window = new UTKComponentListWindow();
window.SetData(components);
window.OnComponentSelected += (component) => { };
```

### UTKTreeListWindow

트리 구조 데이터를 표시하는 윈도우입니다.

```csharp
var window = new UTKTreeListWindow();
window.SetData(treeItems);
window.OnItemSelected += (item) => { };
window.ExpandAll();
```

### UTKImageListWindow

이미지 그리드를 표시하는 윈도우입니다.

```csharp
var window = new UTKImageListWindow();
window.SetData(images);
window.OnImageSelected += (image) => { };
```

---

## 6) 입력 필드

### 기본 입력 필드

```csharp
// 정수 입력
var intField = new UTKIntegerField("수량");
intField.Value = 10;
intField.OnValueChanged += (value) => { };

// 실수 입력
var floatField = new UTKFloatField("크기");
floatField.Value = 1.5f;

// 벡터 입력
var vector3Field = new UTKVector3Field("위치");
vector3Field.Value = Vector3.zero;
```

### UTKNumberStepper

증가/감소 버튼이 있는 숫자 입력 필드입니다.

```csharp
var stepper = new UTKNumberStepper();
stepper.Value = 5;
stepper.Min = 0;
stepper.Max = 100;
stepper.Step = 1;
```

---

## 7) UXML 속성 규칙

Unity 6 소스 생성기 기반의 `[UxmlElement]`와 `[UxmlAttribute]`를 사용합니다.

```csharp
[UxmlElement]
public partial class UTKCustomComponent : VisualElement
{
    [UxmlAttribute("title")]
    public string Title { get; set; }

    [UxmlAttribute("is-enabled")]
    public bool IsEnabled { get; set; }

    [UxmlAttribute("border-width")]
    public int BorderWidth { get; set; }
}
```

**UXML 사용:**
```xml
<utk:UTKCustomComponent title="제목" is-enabled="true" border-width="2" />
```

**주의사항:**
- 클래스는 반드시 `partial`로 선언
- 속성명은 케밥 케이스(kebab-case) 소문자 사용
- 레거시 `UxmlFactory`/`UxmlTraits` 방식 사용 금지

---

## 8) 네이밍 규칙

| 항목 | 규칙 | 예시 |
|------|------|------|
| 클래스 | UTK 접두사 + PascalCase | `UTKButton`, `UTKAccordionList` |
| UXML 파일 | `{ComponentName}.uxml` | `UTKAccordionListWindow.uxml` |
| USS 파일 | `{ComponentName}Uss.uss` | `UTKAccordionListWindowUss.uss` |
| Public 멤버 | PascalCase | `OnClicked`, `Value` |
| Private 필드 | _camelCase | `_button`, `_labelCache` |
| 이벤트 | On 접두사 | `OnValueChanged`, `OnClicked` |

> **중요**: UXML과 USS 파일명을 다르게 지정해야 `Resources.Load<T>()` 충돌을 방지할 수 있습니다.

---

## 9) 메모리 관리 패턴

### 이벤트 구독/해제

```csharp
private EventCallback<ClickEvent>? _onClick;

void OnEnable()
{
    _onClick = OnButtonClick;
    _button?.RegisterCallback(_onClick);
    UTKThemeManager.OnThemeChanged += OnThemeChanged;
}

void OnDisable()
{
    _button?.UnregisterCallback(_onClick);
    UTKThemeManager.OnThemeChanged -= OnThemeChanged;
}
```

### IDisposable 패턴

```csharp
public void Dispose()
{
    UnregisterEvents();
    _cts?.Cancel();
    _cts?.Dispose();
    _cts = null;
}
```

### 체크리스트

- [ ] `RegisterCallback<T>` ↔ `UnregisterCallback<T>` 대칭 확인
- [ ] `UTKThemeManager.OnThemeChanged` 구독 해제
- [ ] `CancellationTokenSource` 정리 (`Cancel` → `Dispose`)
- [ ] 람다/클로저 캡처로 인한 누수 점검
- [ ] 이미지 캐시 정리 (해당 시)

---

## 10) 주요 API 요약

| 카테고리 | 클래스 | 주요 메서드 |
|----------|--------|-------------|
| **테마** | UTKThemeManager | `RegisterRoot`, `SetTheme`, `ToggleTheme` |
| **버튼** | UTKButton | `SetMaterialIcon`, `SetImageIcon`, `OnClicked` |
| **리스트** | UTKAccordionList | `SetData`, `Search`, `ExpandAll`, `OnItemClick` |
| **트리** | UTKTreeView | `SetData`, `ExpandAll`, `CollapseAll` |
| **프로퍼티** | UTKPropertyWindow | `LoadProperties`, `AddGroup`, `UpdatePropertyValue` |
| **모달** | UTKModal | `Show`, `Close`, `AddContent`, `AddToFooter` |
| **이미지** | UTKImage | `LoadAsync`, `SetTexture`, `ClearImage` |
| **입력** | UTK*Field | `Value`, `OnValueChanged` |

---

## 11) 참조 리소스

| 경로 | 설명 |
|------|------|
| `Assets/Resources/UIToolkit/Style/` | USS 스타일 파일 |
| `Assets/Resources/UIToolkit/Common/` | 공통 UXML 컴포넌트 |
| `Assets/Resources/UIToolkit/Window/` | 윈도우 UXML 템플릿 |
| `Assets/Resources/UIToolkit/Modal/` | 모달 UXML 템플릿 |
| `Assets/Resources/UIToolkit/List/` | 리스트 UXML 템플릿 |
| `Assets/Resources/UIToolkit/Property/` | 프로퍼티 UXML 템플릿 |