XRLib/Assets/Scripts/UVC/UIToolkit/CLAUDE.md

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 입력
│   ├── UTKIntStepper.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      #   프로퍼티 리스트 컨테이너
│   └── UTKPropertyListWindow.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)

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

// 테마 등록 및 전환
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)

// 폰트 로드
await UTKMaterialIcons.LoadFontAsync();

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

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

2순위: Image Icons (UTKImageIcons)

// 필요한 아이콘이 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

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

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

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

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

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

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

UTKModal / UTKColorPicker / UTKDatePicker

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

// 기본 모달
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에서 이미지를 로드합니다.

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	색상+상태 (커스텀)

사용 예시

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

// 그룹 생성
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

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

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

UTKComponentListWindow

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

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

UTKTreeListWindow

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

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

UTKImageListWindow

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

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

---

6) 입력 필드

기본 입력 필드

// 정수 입력
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;

UTKIntStepper

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

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

---

7) UXML 속성 규칙

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

[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 사용:

<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) 메모리 관리 패턴

이벤트 구독/해제

private EventCallback<ClickEvent>? _onClick;

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

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

IDisposable 패턴

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
프로퍼티	UTKPropertyListWindow	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 템플릿