#nullable enable
using System;
using System.Collections.Generic;
using System.Linq;
using UnityEngine;
using UnityEngine.UIElements;
using static UVC.UIToolkit.UTKStyleGuide;

namespace UVC.UIToolkit
{
    /// <summary>
    /// 계층적 트리 구조를 표시하는 커스텀 UI Toolkit 컴포넌트입니다.
    ///
    /// <para><b>개요:</b></para>
    /// <para>
    /// UTKTreeListWindow는 Unity UI Toolkit의 TreeView를 래핑하여 검색, 가시성 토글,
    /// 닫기 기능 등을 제공하는 재사용 가능한 컴포넌트입니다.
    /// UXML 파일(UTKTreeListWindow.uxml, UTKTreeListItem.uxml)과 함께 사용됩니다.
    /// </para>
    ///
    /// <para><b>주요 기능:</b></para>
    /// <list type="bullet">
    ///   <item>계층적 트리 구조 표시 (펼치기/접기 지원)</item>
    ///   <item>실시간 검색 필터링</item>
    ///   <item>항목별 가시성(눈 아이콘) 토글</item>
    ///   <item>다중 선택 지원</item>
    ///   <item>삭제 기능 (Delete/Backspace 키)</item>
    /// </list>
    ///
    /// <para><b>UXML 사용 예시:</b></para>
    /// <code><![CDATA[
    /// <!-- UXML 파일에서 UTKTreeListWindow 사용 -->
    /// <ui:UXML xmlns:utk="UVC.UIToolkit">
    ///     <utk:UTKTreeListWindow name="tree-list-window" />
    /// </ui:UXML>
    /// ]]></code>
    ///
    /// <para><b>C# 사용 예시:</b></para>
    /// <code><![CDATA[
    /// // 1. 윈도우 참조 획득
    /// var treeWindow = root.Q<UTKTreeListWindow>("tree-list-window");
    ///
    /// // 2. 윈도우 제목 및 닫기 버튼 설정
    /// treeWindow.Title = "씬 계층구조";
    /// treeWindow.ShowCloseButton = true;
    ///
    /// // 3. 데이터 구성 - 계층적 트리 구조
    /// var data = new List<UTKTreeListItemData>
    /// {
    ///     new UTKTreeListItemData
    ///     {
    ///         name = "루트 오브젝트",
    ///         isExpanded = true,
    ///         IsVisible = true,
    ///         children = new List<UTKTreeListItemData>
    ///         {
    ///             new UTKTreeListItemData
    ///             {
    ///                 name = "자식 오브젝트 1",
    ///                 IsVisible = true
    ///             },
    ///             new UTKTreeListItemData
    ///             {
    ///                 name = "자식 오브젝트 2",
    ///                 IsVisible = false,
    ///                 children = new List<UTKTreeListItemData>
    ///                 {
    ///                     new UTKTreeListItemData { name = "손자 오브젝트" }
    ///                 }
    ///             }
    ///         }
    ///     }
    /// };
    /// treeWindow.SetData(data);
    ///
    /// // 4. 선택 변경 이벤트 구독 (선택 및 해제 모두)
    /// treeWindow.OnSelectionChanged += (selectedItems) =>
    /// {
    ///     Debug.Log($"선택된 아이템 수: {selectedItems.Count}");
    ///     foreach (var item in selectedItems)
    ///     {
    ///         Debug.Log($"선택: {item.name}");
    ///     }
    /// };
    ///
    /// // 5. 가시성 변경 이벤트 (눈 아이콘 클릭)
    /// treeWindow.OnVisibilityChanged += (item) =>
    /// {
    ///     Debug.Log($"{item.name} 가시성: {item.IsVisible}");
    ///     // 3D 씬에서 해당 오브젝트 활성화/비활성화
    ///     var gameObject = FindGameObjectByName(item.name);
    ///     if (gameObject != null)
    ///     {
    ///         gameObject.SetActive(item.IsVisible);
    ///     }
    /// };
    ///
    /// // 6. 삭제 이벤트 (Delete/Backspace 키)
    /// treeWindow.EnabledDeleteItem = true;
    /// treeWindow.OnItemDeleted += (item) =>
    /// {
    ///     Debug.Log($"삭제 요청: {item.name}");
    ///     // 데이터에서 제거 후 UI 갱신
    ///     RemoveFromData(item);
    ///     treeWindow.Rebuild();
    /// };
    ///
    /// // 7. 윈도우 닫힘 이벤트
    /// treeWindow.OnClosed += () =>
    /// {
    ///     Debug.Log("윈도우가 닫혔습니다.");
    /// };
    ///
    /// // 8. 검색 실행
    /// treeWindow.ApplySearch("자식");
    /// // 검색어는 SearchQuery 속성으로 확인 가능
    /// string currentQuery = treeWindow.SearchQuery;
    ///
    /// // 9. 프로그래밍 방식 선택
    /// treeWindow.SelectByItemId(itemId);
    ///
    /// // 10. 전체 펼치기/접기
    /// treeWindow.ExpandAll();
    /// treeWindow.CollapseAll();
    ///
    /// // 11. TreeView 갱신 (데이터 변경 후)
    /// treeWindow.Rebuild();
    ///
    /// // 12. 윈도우 표시/숨김
    /// treeWindow.Show();
    /// treeWindow.Hide();
    ///
    /// // 13. 리소스 해제 (OnDestroy에서 호출)
    /// treeWindow.Dispose();
    /// ]]></code>
    ///
    /// <para><b>관련 리소스:</b></para>
    /// <list type="bullet">
    ///   <item>Resources/UIToolkit/Window/UTKTreeListWindow.uxml - 메인 레이아웃</item>
    ///   <item>Resources/UIToolkit/List/UTKTreeListItem.uxml - 개별 항목 템플릿</item>
    /// </list>
    ///
    /// <para><b>선택 해제 방지:</b></para>
    /// <para>
    /// 빈 영역 클릭 시 선택이 해제되지 않도록 하려면 EventSystem의 InputSystemUIInputModule 컴포넌트에서
    /// <c>Deselect On Background Click</c> 옵션을 해제해야 합니다.
    /// </para>
    /// </summary>
    [UxmlElement]
    public partial class UTKTreeListWindow : VisualElement, IDisposable
    {
        #region IDisposable
        private bool _disposed = false;
        #endregion
        #region 상수 (Constants)
        /// <summary>메인 UXML 파일 경로 (Resources 폴더 기준)</summary>
        private const string UXML_PATH = "UIToolkit/Window/UTKTreeListWindow";

        /// <summary>USS 파일 경로 (Resources 폴더 기준)</summary>
        private const string USS_PATH = "UIToolkit/Window/UTKTreeListWindowUss";
        #endregion

        #region UI 컴포넌트 참조 (UI Component References)
        /// <summary>검색어 입력 필드</summary>
        private TextField? _searchField;

        /// <summary>Unity UI Toolkit의 TreeView 컴포넌트</summary>
        private TreeView? _treeView;

        /// <summary>트리 리스트 닫기 버튼 (UTKButton)</summary>
        private UTKButton? _closeButton;

        /// <summary>검색어 지우기 버튼 (UTKButton)</summary>
        private UTKButton? _clearButton;

        /// <summary>윈도우 제목 라벨</summary>
        private Label? _titleLabel;
        #endregion

        #region 내부 데이터 (Internal Data)
        

        /// <summary>
        /// 원본 루트 데이터입니다.
        /// 검색 필터 해제 시 원래 데이터로 복원하는 데 사용됩니다.
        /// </summary>
        private List<UTKTreeListItemData> _originalRoots = new();

        /// <summary>
        /// TreeView에 바인딩되는 데이터 소스입니다.
        /// TreeViewItemData는 Unity의 TreeView가 요구하는 래퍼 타입입니다.
        /// </summary>
        private List<TreeViewItemData<UTKTreeListItemData>>? _rootData;

        /// <summary>
        /// 항목 ID 자동 생성을 위한 시드 값입니다.
        /// SetData() 호출 시 id가 0인 항목에 순차적으로 ID를 할당합니다.
        /// </summary>
        private int _idSeed = 1;

        /// <summary>
        /// 이전에 선택된 항목들입니다.
        /// 선택 해제 이벤트 발송에 사용됩니다.
        /// </summary>
        private List<UTKTreeListItemData> _previouslySelectedItems = new();

        /// <summary>
        /// 선택 이벤트 발송을 일시적으로 억제하는 플래그입니다.
        /// 프로그래밍 방식으로 선택 시 이벤트를 발송하지 않으려면 true로 설정합니다.
        /// </summary>
        private bool _suppressSelectionEvent = false;

        /// <summary>
        /// 펼침/접힘 이벤트 처리를 일시적으로 억제하는 플래그입니다.
        /// ExpandByData() 실행 중 이벤트로 인한 데이터 덮어쓰기를 방지합니다.
        /// </summary>
        private bool _suppressExpandEvent = false;
        #endregion

        #region 공개 속성 (Public Properties)
        /// <summary>
        /// 항목 삭제 기능 활성화 여부입니다.
        /// true일 때만 Delete/Backspace 키로 항목 삭제 이벤트가 발생합니다.
        /// 기본값은 true입니다.
        /// </summary>
        public bool EnabledDeleteItem { get; set; } = true;

        /// <summary>윈도우 제목</summary>
        public string Title
        {
            get => _titleLabel?.text ?? string.Empty;
            set { if (_titleLabel != null) _titleLabel.text = value; }
        }

        /// <summary>닫기 버튼 표시 여부</summary>
        public bool ShowCloseButton
        {
            get => _closeButton?.style.display == DisplayStyle.Flex;
            set { if (_closeButton != null) _closeButton.style.display = value ? DisplayStyle.Flex : DisplayStyle.None; }
        }
        #endregion

        #region 외부 이벤트 (Public Events)

        /// <summary>
        /// 메인/검색 리스트에서 항목이 선택될 때 발생합니다.
        /// </summary>
        public Action<List<UTKTreeListItemData>>? OnItemSelected;

        /// <summary>
        /// 메인/검색 리스트에서 항목이 선택 해제될 때 발생합니다.
        /// </summary>
        public Action<List<UTKTreeListItemData>>? OnItemDeselected;
        /// <summary>
        /// 항목의 가시성(눈 아이콘)이 변경될 때 발생합니다.
        /// 3D 모델의 GameObject 활성화/비활성화에 연동합니다.
        /// </summary>
        public event Action<UTKTreeListItemData, bool>? OnItemVisibilityChanged;

        /// <summary>
        /// 메인/검색 리스트에서 항목이 삭제될 때 발생합니다 (Delete 키).
        /// </summary>
        public Action<UTKTreeListItemData>? OnItemDeleted;

        /// <summary>
        /// 메인/검색 리스트에서 항목이 더블클릭될 때 발생합니다.
        /// </summary>
        public Action<UTKTreeListItemData>? OnItemDoubleClicked;

        /// <summary>
        /// 트리 리스트가 닫힐 때(숨겨질 때) 발생합니다.
        /// 닫기 버튼 클릭 시 트리거됩니다.
        /// </summary>
        public event Action? OnClosed;
        #endregion

        #region 생성자 (Constructor)
        /// <summary>
        /// TreeListWindow 컴포넌트를 초기화합니다.
        /// UXML 템플릿을 로드하고 내부 컴포넌트를 설정합니다.
        /// </summary>
        public UTKTreeListWindow()
        {
            // 1. 메인 UXML 로드 및 복제
            // CloneTree(this)로 UXML 내용이 이 클래스의 자식으로 추가됨
            var visualTree = Resources.Load<VisualTreeAsset>(UXML_PATH);
            if (visualTree == null)
            {
                Debug.LogError($"[TreeMenu] UXML not found at: {UXML_PATH}");
                return;
            }
            visualTree!.CloneTree(this);

            // 2. 테마 적용
            UTKThemeManager.Instance.ApplyThemeToElement(this);

            // USS 로드 (테마 변수 스타일시트 이후에 로드되어야 변수가 해석됨)
            var uss = Resources.Load<StyleSheet>(USS_PATH);
            if (uss != null)
            {
                styleSheets.Add(uss);
            }

            // 3. 자식 요소 참조 획득 (UXML의 name 속성으로 찾음)
            _searchField = this.Q<TextField>("search-field");
            _treeView = this.Q<TreeView>("main-tree-view");
            _titleLabel = this.Q<Label>("title");
            _closeButton = this.Q<UTKButton>("close-btn");
            _clearButton = this.Q<UTKButton>("clear-btn");

            // 4. 닫기 버튼 아이콘 설정
            if (_closeButton != null)
            {
                _closeButton.SetMaterialIcon(UTKMaterialIcons.Close, 16);
            }

            // 5. Clear 버튼 아이콘 설정
            if (_clearButton != null)
            {
                _clearButton.SetMaterialIcon(UTKMaterialIcons.Close, 12);
            }

            // 6. 이벤트 연결 및 로직 초기화
            InitializeLogic();
        }
        #endregion

        #region 초기화 (Initialization)
        /// <summary>
        /// 내부 로직과 이벤트 핸들러를 초기화합니다.
        /// </summary>
        private void InitializeLogic()
        {
            // 검색창 이벤트: Enter 키를 눌렀을 때 또는 포커스를 잃었을 때 필터링 실행
            if (_searchField != null)
            {
                _searchField.RegisterCallback<KeyDownEvent>(OnSearchFieldKeyDown);
                _searchField.RegisterCallback<FocusOutEvent>(OnSearchFieldFocusOut);
            }

            // TreeView 설정
            // makeItem: 새 항목 UI 생성 시 호출
            // bindItem: 데이터를 UI에 바인딩할 때 호출
            // selectionChanged: 선택 변경 시 호출
            if (_treeView != null)
            {
                _treeView.bindItem = BindTreeItem;
                _treeView.selectionChanged += OnTreeViewSelectionChanged;
                _treeView.itemsChosen += OnTreeViewItemsChosen;
                _treeView.itemExpandedChanged += OnTreeViewItemExpandedChanged;
                _treeView.RegisterCallback<KeyDownEvent>(OnTreeViewKeyDown);
            }

            // 닫기 버튼: 트리 리스트를 숨기고 이벤트 발생
            if (_closeButton != null)
            {
                _closeButton.OnClicked += OnCloseButtonClicked;
            }

            // 검색어 지우기 버튼
            if(_clearButton != null)
            {
                _clearButton.style.display = DisplayStyle.None; // 초기에는 숨김
                _clearButton.OnClicked += OnClearButtonClicked;
            }

            // 스크롤바 hover/active 색상 설정
            SetupScrollerDraggerColors();
        }

        /// <summary>
        /// 스크롤바 드래거의 hover/active 색상을 설정합니다.
        /// USS로는 드래거에 직접 hover/active 상태를 적용할 수 없어 코드로 구현합니다.
        /// </summary>
        private void SetupScrollerDraggerColors()
        {
            if (_treeView == null) return;

            // TreeView가 렌더링된 후에 스크롤러 설정
            _treeView.RegisterCallback<GeometryChangedEvent>(OnTreeViewGeometryChanged);
        }

        // USS 변수 정의 (customStyle에서 읽기 위한 키)
        private static readonly CustomStyleProperty<Color> s_DraggerNormalColor = new("--scroller-dragger-normal");
        private static readonly CustomStyleProperty<Color> s_DraggerHoverColor = new("--scroller-dragger-hover");
        private static readonly CustomStyleProperty<Color> s_DraggerActiveColor = new("--scroller-dragger-active");
        private static readonly CustomStyleProperty<Color> s_TrackerNormalColor = new("--scroller-tracker-normal");
        private static readonly CustomStyleProperty<Color> s_TrackerHoverColor = new("--scroller-tracker-hover");

        /// <summary>
        /// TreeView 렌더링 완료 후 스크롤러 색상을 설정합니다.
        /// </summary>
        private void OnTreeViewGeometryChanged(GeometryChangedEvent evt)
        {
            if (_treeView == null) return;

            // 한 번만 실행
            _treeView.UnregisterCallback<GeometryChangedEvent>(OnTreeViewGeometryChanged);

            // USS 변수에서 색상 읽기 (실패 시 UTKStyleGuide 기본값 사용)
            Color normalColor = ScrollbarDraggerNormal;
            Color hoverColor = ScrollbarDraggerHover;
            Color activeColor = ScrollbarDraggerActive;
            Color trackerNormalColor = ScrollbarTrackerNormal;
            Color trackerHoverColor = ScrollbarTrackerHover;

            if (_treeView.customStyle.TryGetValue(s_DraggerNormalColor, out Color n)) normalColor = n;
            if (_treeView.customStyle.TryGetValue(s_DraggerHoverColor, out Color h)) hoverColor = h;
            if (_treeView.customStyle.TryGetValue(s_DraggerActiveColor, out Color a)) activeColor = a;
            if (_treeView.customStyle.TryGetValue(s_TrackerNormalColor, out Color tn)) trackerNormalColor = tn;
            if (_treeView.customStyle.TryGetValue(s_TrackerHoverColor, out Color th)) trackerHoverColor = th;

            // TreeView 내부의 ScrollView 찾기
            var scrollView = _treeView.Q<ScrollView>();
            if (scrollView == null) return;

            // 수직 스크롤바
            var verticalScroller = scrollView.verticalScroller;
            if (verticalScroller != null)
            {
                SetupDraggerEvents(verticalScroller, normalColor, hoverColor, activeColor, trackerNormalColor, trackerHoverColor);
            }

            // 수평 스크롤바
            var horizontalScroller = scrollView.horizontalScroller;
            if (horizontalScroller != null)
            {
                SetupDraggerEvents(horizontalScroller, normalColor, hoverColor, activeColor, trackerNormalColor, trackerHoverColor);
            }
        }

        /// <summary>
        /// 개별 스크롤러에 드래거 색상 이벤트를 설정합니다.
        /// </summary>
        private void SetupDraggerEvents(Scroller scroller, Color normalColor, Color hoverColor, Color activeColor, Color trackerNormalColor, Color trackerHoverColor)
        {
            var dragger = scroller.Q(className: "unity-base-slider__dragger");
            var tracker = scroller.Q(className: "unity-base-slider__tracker");
            if (dragger == null) return;

            // 드래거에 직접 이벤트 등록
            dragger.RegisterCallback<MouseEnterEvent>(evt =>
            {
                dragger.style.backgroundColor = hoverColor;
            });

            dragger.RegisterCallback<MouseLeaveEvent>(evt =>
            {
                dragger.style.backgroundColor = normalColor;
            });

            dragger.RegisterCallback<MouseDownEvent>(evt =>
            {
                dragger.style.backgroundColor = activeColor;
            });

            dragger.RegisterCallback<MouseUpEvent>(evt =>
            {
                dragger.style.backgroundColor = hoverColor;
            });

            // 트래커(배경) 마우스 오버 시 색상 변경
            if (tracker != null)
            {
                tracker.RegisterCallback<MouseEnterEvent>(evt =>
                {
                    tracker.style.backgroundColor = trackerHoverColor;
                });

                tracker.RegisterCallback<MouseLeaveEvent>(evt =>
                {
                    tracker.style.backgroundColor = trackerNormalColor;
                });
            }
        }
        #endregion

        #region 공개 메서드 (Public Methods)
        /// <summary>
        /// 트리 리스트를 화면에 표시합니다.
        /// </summary>
        public void Show()
        {
            this.style.display = DisplayStyle.Flex;
        }

        /// <summary>
        /// 트리 데이터를 설정합니다.
        /// UTKTreeListItemData 리스트를 받아 TreeView에 바인딩합니다.
        /// </summary>
        /// <param name="roots">루트 항목들의 리스트 (계층 구조의 최상위 항목들)</param>
        public void SetData(List<UTKTreeListItemData> roots)
        {
            // 원본 데이터 저장 (필터 복원용)
            _originalRoots = roots ?? new List<UTKTreeListItemData>();

            // ID 시드 초기화
            _idSeed = 1;

            // 순환 참조 감지를 위한 방문 집합
            var visited = new HashSet<UTKTreeListItemData>();

            // TreeView 형식으로 데이터 변환
            _rootData = ConvertToTreeViewData(_originalRoots, visited, 0);

            // TreeView에 데이터 설정
            _treeView!.SetRootItems<UTKTreeListItemData>(_rootData);

            // UI 갱신 및 데이터의 isExpanded에 따라 항목 펼치기
            _treeView!.Rebuild();
            ExpandByData(_originalRoots);
        }

        /// <summary>
        /// 지정된 ID의 항목을 프로그래밍 방식으로 선택합니다.
        /// </summary>
        /// <param name="itemId">선택할 항목의 ID</param>
        public void SelectByItemId(int itemId)
        {
            _treeView?.SetSelection(new List<int> { itemId });
        }

        /// <summary>
        /// 지정된 이름 목록에 해당하는 항목만 표시하고 나머지는 숨깁니다.
        /// </summary>
        /// <param name="items">표시할 항목들의 이름 목록</param>
        /// <param name="depth">검색 깊이 (1=1뎁스 자식만, 2=2뎁스까지, 0이하=전체)</param>
        public void ShowItems(List<string> items, int depth = 1)
        {
            if (_originalRoots == null || _originalRoots.Count == 0) return;

            var visibleNames = new HashSet<string>(items ?? new List<string>());

            foreach (var root in _originalRoots)
            {
                SetVisibilityByNames(root, visibleNames, depth, 0);
            }

            // UI 갱신
            _treeView?.RefreshItems();
        }

        /// <summary>
        /// 루트 레벨에 새 항목을 추가합니다.
        /// ID가 0이면 자동으로 할당됩니다.
        /// </summary>
        /// <param name="data">추가할 항목 데이터</param>
        public void AddItem(UTKTreeListItemData data)
        {
            if (data == null) return;

            // ID가 없으면 자동 할당
            if (data.id == 0) data.id = _idSeed++;

            // 원본 데이터에 추가
            _originalRoots.Add(data);

            // _rootData가 null이면 초기화
            _rootData ??= new List<TreeViewItemData<UTKTreeListItemData>>();

            // TreeViewItemData 래퍼 생성 및 추가
            var childData = data.children != null && data.children.Count > 0
                ? ConvertToTreeViewData(data.children, new HashSet<UTKTreeListItemData>(), 1)
                : null;
            var treeItem = new TreeViewItemData<UTKTreeListItemData>(data.id, data, childData);
            _rootData.Add(treeItem);

            // TreeView 갱신
            _treeView?.SetRootItems(_rootData);
            _treeView?.Rebuild();
            if (_treeView != null && _treeView.autoExpand) ExpandByData(_originalRoots);
        }

        /// <summary>
        /// 지정된 부모 항목의 자식으로 새 항목을 추가합니다.
        /// </summary>
        /// <param name="parent">부모 항목 (null이면 루트에 추가)</param>
        /// <param name="data">추가할 항목 데이터</param>
        public void AddItem(UTKTreeListItemData? parent, UTKTreeListItemData data)
        {
            if (data == null) return;

            // 부모가 없으면 루트에 추가
            if (parent == null)
            {
                AddItem(data);
                return;
            }

            // ID가 없으면 자동 할당
            if (data.id == 0) data.id = _idSeed++;

            // 부모의 children 리스트에 추가
            parent.children ??= new List<UTKTreeListItemData>();
            parent.children.Add(data);

            // TreeView 데이터 재구성 및 갱신
            RefreshTreeViewData();
        }

        /// <summary>
        /// 트리에서 항목을 완전히 삭제합니다 (데이터 + 뷰 + 선택 상태).
        /// 자식 항목이 있는 경우 함께 삭제됩니다.
        /// </summary>
        /// <param name="data">삭제할 항목 데이터</param>
        public void DeleteItem(UTKTreeListItemData data)
        {
            if (data == null) return;

            bool removed = false;

            // 루트 레벨에서 삭제 시도
            if (_originalRoots.Remove(data))
            {
                removed = true;
            }
            else
            {
                // 루트에 없으면 자식에서 재귀적으로 검색하여 삭제
                foreach (var root in _originalRoots)
                {
                    if (RemoveFromChildren(root, data))
                    {
                        removed = true;
                        break;
                    }
                }
            }

            if (removed)
            {
                // 선택 상태에서 삭제된 항목 및 자식들 제거
                RemoveFromSelection(data);

                // TreeView 데이터 재구성 및 갱신
                RefreshTreeViewData();
            }
        }

        /// <summary>
        /// 항목의 이름을 변경하고 UI를 갱신합니다.
        /// </summary>
        /// <param name="data">변경할 항목 데이터</param>
        /// <param name="newName">새 이름</param>
        public void SetItemName(UTKTreeListItemData data, string newName)
        {
            if (data == null || string.IsNullOrEmpty(newName)) return;

            data.name = newName;

            // UI 갱신 (해당 항목의 레이블 업데이트)
            _treeView?.RefreshItems();
        }

        /// <summary>
        /// 이름으로 항목을 찾아 선택합니다.
        /// 검색 모드 중이면 검색을 취소하고 원본 데이터에서 선택합니다.
        /// SelectionType에 따라 단일 선택이면 기존 선택을 대체하고, 다중 선택이면 기존 선택에 추가합니다.
        /// </summary>
        /// <param name="name">선택할 항목의 이름</param>
        /// <param name="notify">선택 이벤트 발송 여부 (false면 OnItemSelected/OnItemDeselected 이벤트 억제)</param>
        public void SelectItem(string name, bool notify = true)
        {
            if (string.IsNullOrEmpty(name) || _treeView == null) return;

            // SelectionType.None인 경우 선택 불가
            if (_treeView.selectionType == SelectionType.None) return;

            // 검색 중이면 검색 취소
            if (_searchField != null && !string.IsNullOrEmpty(_searchField.value))
            {
                _searchField.value = string.Empty;
                OnSearch(string.Empty);
            }

            // 이름으로 항목 찾기
            var item = FindItemByName(name);
            if (item == null) return;

            // 이미 선택되어 있으면 무시
            if (_previouslySelectedItems.Contains(item)) return;

            List<int> newSelection;

            // SelectionType에 따라 선택 방식 결정
            if (_treeView.selectionType == SelectionType.Multiple)
            {
                // 다중 선택: 기존 선택에 추가
                newSelection = _previouslySelectedItems.Select(i => i.id).ToList();
                newSelection.Add(item.id);
            }
            else
            {
                // 단일 선택: 기존 선택 대체
                newSelection = new List<int> { item.id };
            }

            // 이벤트 억제 플래그 설정
            _suppressSelectionEvent = !notify;
            try
            {
                _treeView.SetSelection(newSelection);
            }
            finally
            {
                _suppressSelectionEvent = false;
            }
        }

        /// <summary>
        /// 이름으로 항목을 찾아 선택을 해제합니다.
        /// 단일 선택 모드에서는 모든 선택이 해제되고, 다중 선택 모드에서는 해당 항목만 제외됩니다.
        /// </summary>
        /// <param name="name">선택 해제할 항목의 이름</param>
        /// <param name="notify">선택 해제 이벤트 발송 여부 (false면 OnItemDeselected 이벤트 억제)</param>
        public void DeselectItem(string name, bool notify = true)
        {
            if (string.IsNullOrEmpty(name) || _treeView == null) return;

            // SelectionType.None인 경우 선택 해제 불필요
            if (_treeView.selectionType == SelectionType.None) return;

            var item = FindItemByName(name);
            if (item == null) return;

            // 현재 선택되어 있지 않으면 무시
            if (!_previouslySelectedItems.Contains(item)) return;

            List<int> newSelection;

            // SelectionType에 따라 선택 해제 방식 결정
            if (_treeView.selectionType == SelectionType.Multiple)
            {
                // 다중 선택: 해당 항목만 제외
                newSelection = _previouslySelectedItems
                    .Where(i => i.id != item.id)
                    .Select(i => i.id)
                    .ToList();
            }
            else
            {
                // 단일 선택: 전체 선택 해제
                newSelection = new List<int>();
            }

            // 이벤트 억제 플래그 설정
            _suppressSelectionEvent = !notify;
            try
            {
                _treeView.SetSelection(newSelection);
            }
            finally
            {
                _suppressSelectionEvent = false;
            }
        }

        /// <summary>
        /// 모든 항목의 선택을 해제합니다.
        /// </summary>
        public void ClearSelection()
        {
            _treeView?.ClearSelection();
        }


        /// <summary>
        /// 원본 데이터를 기반으로 TreeView 데이터를 재구성하고 UI를 갱신합니다.
        /// </summary>
        private void RefreshTreeViewData()
        {
            var visited = new HashSet<UTKTreeListItemData>();
            _rootData = ConvertToTreeViewData(_originalRoots, visited, 0);
            _treeView?.SetRootItems(_rootData);
            _treeView?.Rebuild();
            if (_treeView != null && _treeView.autoExpand) ExpandByData(_originalRoots);
        }

        /// <summary>
        /// 부모 노드의 자식들에서 대상 항목을 재귀적으로 찾아 삭제합니다.
        /// </summary>
        /// <param name="parent">부모 노드</param>
        /// <param name="target">삭제할 대상 항목</param>
        /// <returns>삭제 성공 여부</returns>
        private bool RemoveFromChildren(UTKTreeListItemData parent, UTKTreeListItemData target)
        {
            if (parent.children == null || parent.children.Count == 0) return false;

            // 직접 자식에서 삭제 시도
            if (parent.children.Remove(target))
            {
                return true;
            }

            // 하위 자식들에서 재귀적으로 검색
            foreach (var child in parent.children)
            {
                if (RemoveFromChildren(child, target))
                {
                    return true;
                }
            }

            return false;
        }

        /// <summary>
        /// 이름으로 항목을 재귀적으로 검색합니다.
        /// </summary>
        /// <param name="name">찾을 항목의 이름</param>
        /// <returns>찾은 항목 또는 null</returns>
        private UTKTreeListItemData? FindItemByName(string name)
        {
            foreach (var root in _originalRoots)
            {
                var found = FindItemByNameRecursive(root, name);
                if (found != null) return found;
            }
            return null;
        }

        /// <summary>
        /// 삭제된 항목과 그 자식들을 선택 상태에서 제거합니다.
        /// _previouslySelectedItems와 TreeView의 선택 상태 모두에서 제거합니다.
        /// </summary>
        /// <param name="data">삭제된 항목</param>
        private void RemoveFromSelection(UTKTreeListItemData data)
        {
            // 삭제할 항목과 모든 자식들의 ID 수집
            var idsToRemove = new HashSet<int>();
            CollectItemIds(data, idsToRemove);

            // _previouslySelectedItems에서 제거
            _previouslySelectedItems.RemoveAll(item => idsToRemove.Contains(item.id));

            // TreeView 선택 상태에서 제거
            if (_treeView != null)
            {
                var currentSelection = _treeView.selectedIndices.ToList();
                var newSelection = new List<int>();

                foreach (var index in currentSelection)
                {
                    var selectedItem = _treeView.GetItemDataForIndex<UTKTreeListItemData>(index);
                    if (selectedItem != null && !idsToRemove.Contains(selectedItem.id))
                    {
                        newSelection.Add(selectedItem.id);
                    }
                }

                if (currentSelection.Count != newSelection.Count)
                {
                    _treeView.SetSelection(newSelection);
                }
            }
        }

        /// <summary>
        /// 항목과 모든 자식들의 ID를 재귀적으로 수집합니다.
        /// </summary>
        /// <param name="node">수집 시작 노드</param>
        /// <param name="ids">ID를 저장할 HashSet</param>
        private void CollectItemIds(UTKTreeListItemData node, HashSet<int> ids)
        {
            ids.Add(node.id);

            if (node.children != null)
            {
                foreach (var child in node.children)
                {
                    CollectItemIds(child, ids);
                }
            }
        }

        /// <summary>
        /// 노드와 그 자식들에서 이름으로 항목을 재귀적으로 검색합니다.
        /// </summary>
        /// <param name="node">검색 시작 노드</param>
        /// <param name="name">찾을 항목의 이름</param>
        /// <returns>찾은 항목 또는 null</returns>
        private UTKTreeListItemData? FindItemByNameRecursive(UTKTreeListItemData node, string name)
        {
            if (node.name == name) return node;

            if (node.children != null)
            {
                foreach (var child in node.children)
                {
                    var found = FindItemByNameRecursive(child, name);
                    if (found != null) return found;
                }
            }

            return null;
        }

        /// <summary>
        /// 재귀적으로 항목의 가시성을 이름 목록에 따라 설정합니다.
        /// </summary>
        /// <param name="node">현재 노드</param>
        /// <param name="visibleNames">표시할 이름 목록</param>
        /// <param name="maxDepth">최대 검색 깊이 (0이하=무제한)</param>
        /// <param name="currentDepth">현재 깊이</param>
        private void SetVisibilityByNames(UTKTreeListItemData node, HashSet<string> visibleNames, int maxDepth, int currentDepth)
        {
            if (node == null) return;

            // maxDepth <= 0 이면 전체 검색, 아니면 깊이 제한 체크
            bool isWithinDepth = maxDepth <= 0 || currentDepth < maxDepth;

            if (isWithinDepth)
            {
                // 이름이 목록에 있으면 visible, 없으면 hidden
                node.IsVisible = visibleNames.Contains(node.name);

                // 가시성 변경 이벤트 발송
                OnItemVisibilityChanged?.Invoke(node, node.IsVisible);
            }

            // 자식들도 재귀적으로 처리
            if (node.children != null)
            {
                foreach (var child in node.children)
                {
                    SetVisibilityByNames(child, visibleNames, maxDepth, currentDepth + 1);
                }
            }
        }
        #endregion

        #region 확장/축소 처리 (Expand/Collapse Handling)
        /// <summary>
        /// TreeView의 항목 확장/축소 이벤트를 처리합니다.
        /// 데이터의 isExpanded 값을 동기화합니다.
        /// </summary>
        /// <param name="evt">확장 변경 이벤트 인자</param>
        private void OnTreeViewItemExpandedChanged(TreeViewExpansionChangedArgs evt)
        {
            // ExpandByData() 실행 중에는 이벤트 무시 (데이터 덮어쓰기 방지)
            if (_suppressExpandEvent) return;

            var item = _treeView?.GetItemDataForId<UTKTreeListItemData>(evt.id);
            if (item != null)
            {
                item.isExpanded = evt.isExpanded;
            }
        }

        /// <summary>
        /// 데이터의 isExpanded 속성에 따라 항목을 펼치거나 접습니다.
        /// </summary>
        /// <param name="items">처리할 항목 리스트</param>
        private void ExpandByData(List<UTKTreeListItemData> items)
        {
            if (_treeView == null || items == null) return;

            // 이벤트 억제 시작 (재귀 호출 고려하여 최상위에서만 설정)
            bool wasSupressed = _suppressExpandEvent;
            _suppressExpandEvent = true;

            try
            {
                ExpandByDataInternal(items);
            }
            finally
            {
                _suppressExpandEvent = wasSupressed;
            }
        }

        /// <summary>
        /// ExpandByData의 내부 재귀 구현입니다.
        /// </summary>
        private void ExpandByDataInternal(List<UTKTreeListItemData> items)
        {
            foreach (var item in items)
            {
                if (item.children != null && item.children.Count > 0)
                {
                    if (item.isExpanded)
                        _treeView!.ExpandItem(item.id);
                    else
                        _treeView!.CollapseItem(item.id);

                    ExpandByDataInternal(item.children);
                }
            }
        }
        #endregion

        #region 선택 처리 (Selection Handling)
        /// <summary>
        /// TreeView의 선택 변경 이벤트를 처리합니다.
        /// SelectionType에 따라 TreeView가 자동으로 선택 항목 수를 제한합니다:
        /// - None: 선택 불가 (selectedItems 항상 비어있음)
        /// - Single: 최대 1개 선택
        /// - Multiple: 여러 개 선택 가능
        /// </summary>
        /// <param name="selectedItems">선택된 항목들</param>
        private void OnTreeViewSelectionChanged(IEnumerable<object> selectedItems)
        {
            // SelectionType.None인 경우 선택 변경 무시
            if (_treeView?.selectionType == SelectionType.None) return;

            // 현재 선택된 항목들 (TreeView가 selectionType에 따라 이미 필터링함)
            var currentItems = selectedItems.OfType<UTKTreeListItemData>().ToList();

            // 선택 해제된 항목들 찾기 (이전에는 있었지만 현재는 없는 항목)
            var deselectedItems = _previouslySelectedItems
                .Where(prev => !currentItems.Contains(prev))
                .ToList();

            // 새로 선택된 항목들 찾기 (이전에는 없었지만 현재는 있는 항목)
            var newlySelectedItems = currentItems
                .Where(curr => !_previouslySelectedItems.Contains(curr))
                .ToList();

            // 선택 해제 상태 업데이트
            foreach (var item in deselectedItems)
            {
                item.isSelected = false;
            }

            // 선택 상태 업데이트
            foreach (var item in newlySelectedItems)
            {
                item.isSelected = true;
            }

            // 이벤트 억제 플래그가 false일 때만 이벤트 발송
            if (!_suppressSelectionEvent)
            {
                if (deselectedItems.Count > 0)
                {
                    OnItemDeselected?.Invoke(deselectedItems);
                }

                if (newlySelectedItems.Count > 0)
                {
                    OnItemSelected?.Invoke(newlySelectedItems);
                }
            }

            // 현재 선택 상태 저장
            _previouslySelectedItems = currentItems;
        }

        /// <summary>
        /// TreeView에서 항목이 더블클릭되거나 Enter 키로 선택될 때 호출됩니다.
        /// </summary>
        /// <param name="chosenItems">선택된 항목들</param>
        private void OnTreeViewItemsChosen(IEnumerable<object> chosenItems)
        {
            var item = chosenItems.FirstOrDefault() as UTKTreeListItemData;
            if (item != null)
            {
                OnItemDoubleClicked?.Invoke(item);
            }
        }

        /// <summary>
        /// TreeView에서 키보드 입력 이벤트를 처리합니다.
        /// Delete 키 입력 시 선택된 항목 삭제 이벤트를 발송합니다.
        /// </summary>
        /// <param name="evt">키 입력 이벤트</param>
        private void OnTreeViewKeyDown(KeyDownEvent evt)
        {
            // EnabledDeleteItem이 false이면 삭제 키 무시
            if (!EnabledDeleteItem) return;

            if (evt.keyCode == KeyCode.Delete || evt.keyCode == KeyCode.Backspace)
            {
                if (_previouslySelectedItems.Count > 0)
                {
                    // 선택된 항목들 각각에 대해 삭제 이벤트 발송
                    foreach (var item in _previouslySelectedItems)
                    {
                        OnItemDeleted?.Invoke(item);
                    }
                    evt.StopPropagation();
                }
            }
        }
        #endregion

        #region 데이터 변환 (Data Conversion)
        /// <summary>
        /// UTKTreeListItemData 리스트를 TreeView가 요구하는 TreeViewItemData 형식으로 변환합니다.
        /// 재귀적으로 자식 항목도 변환하며, 순환 참조를 감지합니다.
        /// </summary>
        /// <param name="items">변환할 항목 리스트</param>
        /// <param name="visited">순환 참조 감지용 방문 집합</param>
        /// <param name="depth">현재 깊이 (디버깅용)</param>
        /// <returns>TreeViewItemData 래퍼 리스트</returns>
        private List<TreeViewItemData<UTKTreeListItemData>> ConvertToTreeViewData(List<UTKTreeListItemData> items, HashSet<UTKTreeListItemData> visited, int depth)
        {
            var list = new List<TreeViewItemData<UTKTreeListItemData>>(items.Count);
            foreach (var item in items)
            {
                if (item == null) continue;

                // 순환 참조 체크: 이미 방문한 항목이면 자식 무시
                if (!visited.Add(item))
                {
                    Debug.LogWarning($"[TreeList] Cycle detected at item '{item.name}' → children 무시");
                    item.children = null;
                }

                // ID가 없으면 자동 할당
                if (item.id == 0) item.id = _idSeed++;

                // 자식 항목 재귀 변환
                List<TreeViewItemData<UTKTreeListItemData>>? childData = null;
                if (item.children != null && item.children.Count > 0)
                    childData = ConvertToTreeViewData(item.children, visited, depth + 1);

                // TreeViewItemData 래퍼 생성
                var treeItem = new TreeViewItemData<UTKTreeListItemData>(item.id, item, childData);
                list.Add(treeItem);
            }
            return list;
        }
        #endregion

        #region TreeView 항목 바인딩 (TreeView Item Creation/Binding)
        
        /// <summary>
        /// 데이터를 UI 요소에 바인딩합니다.
        /// TreeView의 bindItem 콜백으로 사용됩니다.
        /// 스크롤 시 재사용되는 항목에 새 데이터를 연결합니다.
        /// </summary>
        /// <param name="element">바인딩할 UI 요소</param>
        /// <param name="index">TreeView 내부 인덱스</param>
        private void BindTreeItem(VisualElement element, int index)
        {
            // 인덱스로 데이터 획득
            var item = _treeView.GetItemDataForIndex<UTKTreeListItemData>(index);
            if (item == null) return;

            // 0. 자식이 없는 항목의 토글(화살표) 영역 너비 제거
            // element는 TemplateContainer이고, Toggle은 부모(unity-tree-view__item)의 자식
            var treeViewItem = element.parent.parent;
            var toggle = treeViewItem?.Q<Toggle>("unity-tree-view__item-toggle");
            if (toggle != null)
            {
                bool hasChildren = item.children != null && item.children.Count > 0;
                toggle.style.width = hasChildren ? StyleKeyword.Auto : 0;
            }

            // 1. 항목 이름 레이블 설정
            var label = element.Q<Label>("item-label");
            if (label != null) label.text = item.name;

            // 2. 가시성 아이콘 버튼 설정
            var toggleBtn = element.Q<Button>("visibility-btn");
            if (toggleBtn != null) UpdateVisibilityIcon(toggleBtn, item.IsVisible);

            // 3. 가시성 버튼 클릭 이벤트 연결
            // 주의: bindItem은 스크롤 시 재호출되므로 기존 이벤트 제거 후 재등록
            if (toggleBtn.userData is Action oldAction) toggleBtn.clicked -= oldAction;
            System.Action clickAction = () =>
            {
                // 가시성 상태 토글
                item.IsVisible = !item.IsVisible;
                UpdateVisibilityIcon(toggleBtn, item.IsVisible);

                // 자식들에게 동일 상태 전파
                SetChildrenVisibility(item, item.IsVisible);

                // 화면에 보이는 자식 아이콘도 갱신
                _treeView.RefreshItems();

                // 외부에 이벤트 발송 (3D 모델 가시성 동기화)
                OnItemVisibilityChanged?.Invoke(item, item.IsVisible);
            };
            toggleBtn.userData = clickAction;
            toggleBtn.clicked += clickAction;
        }
        #endregion

        #region 가시성 처리 (Visibility Handling)
        /// <summary>
        /// 자식 항목들의 가시성을 재귀적으로 동기화합니다.
        /// 부모의 가시성이 변경되면 모든 하위 항목에 동일하게 적용됩니다.
        /// </summary>
        /// <param name="node">현재 노드</param>
        /// <param name="isVisible">설정할 가시성 상태</param>
        private void SetChildrenVisibility(UTKTreeListItemData node, bool isVisible)
        {
            if (node.children == null || node.children.Count == 0) return;
            foreach (var child in node.children)
            {
                if (child == null) continue;
                child.IsVisible = isVisible;
                // 재귀적으로 하위 자식에도 적용
                SetChildrenVisibility(child, isVisible);
            }
        }

        /// <summary>
        /// 가시성 버튼의 아이콘 스타일을 업데이트합니다.
        /// USS 클래스를 토글하여 아이콘 변경을 처리합니다.
        /// </summary>
        /// <param name="btn">가시성 토글 버튼</param>
        /// <param name="isVisible">현재 가시성 상태</param>
        private void UpdateVisibilityIcon(Button btn, bool isVisible)
        {
            if (isVisible)
            {
                btn.RemoveFromClassList("visibility-off");
                btn.AddToClassList("visibility-on");
            }
            else
            {
                btn.RemoveFromClassList("visibility-on");
                btn.AddToClassList("visibility-off");
            }
        }
        #endregion

        #region 버튼 이벤트 핸들러 (Button Event Handlers)
        /// <summary>
        /// 닫기 버튼 클릭 이벤트를 처리합니다.
        /// </summary>
        private void OnCloseButtonClicked()
        {
            this.style.display = DisplayStyle.None;
            OnClosed?.Invoke();
        }

        /// <summary>
        /// Clear 버튼 클릭 이벤트를 처리합니다.
        /// </summary>
        private void OnClearButtonClicked()
        {
            if (_searchField != null && _searchField.value.Length > 0)
            {
                _searchField.value = string.Empty;
                OnSearch(string.Empty);
            }
            if (_clearButton != null)
            {
                _clearButton.style.display = DisplayStyle.None;
            }
        }
        #endregion

        #region 검색 기능 (Search Functionality)
        /// <summary>
        /// 검색 필드에서 Enter 키를 눌렀을 때 검색을 실행합니다.
        /// </summary>
        /// <param name="evt">키 입력 이벤트</param>
        private void OnSearchFieldKeyDown(KeyDownEvent evt)
        {
            if (evt.keyCode == KeyCode.Return || evt.keyCode == KeyCode.KeypadEnter)
            {
                OnSearch(_searchField?.value ?? string.Empty);
                evt.StopPropagation();
            }
        }

        /// <summary>
        /// 검색 필드가 포커스를 잃었을 때 검색을 실행합니다.
        /// </summary>
        /// <param name="evt">포커스 아웃 이벤트</param>
        private void OnSearchFieldFocusOut(FocusOutEvent evt)
        {
            OnSearch(_searchField?.value ?? string.Empty);
        }

        /// <summary>
        /// 검색어에 따라 트리를 필터링합니다.
        /// 검색어가 비어있으면 원본 데이터로 복원됩니다.
        /// </summary>
        /// <param name="query">검색어</param>
        private void OnSearch(string query)
        {
            // Clear 버튼 가시성 토글
            if (_clearButton != null)
            {
                _clearButton.style.display = string.IsNullOrEmpty(query) ? DisplayStyle.None : DisplayStyle.Flex;
            }

            // 검색어가 없으면 원본 데이터 복원
            if (string.IsNullOrEmpty(query))
            {
                _treeView.SetRootItems<UTKTreeListItemData>(_rootData);
                _treeView.Rebuild();
                ExpandByData(_originalRoots);
                return;
            }

            // 대소문자 무시 검색
            string qLower = query.Trim().ToLowerInvariant();
            var filteredWrappers = FilterTree(qLower);

            // 필터링된 결과로 TreeView 갱신
            _treeView.SetRootItems<UTKTreeListItemData>(filteredWrappers);
            _treeView.Rebuild();

            // 검색 결과 모두 펼치기
            ExpandAll(filteredWrappers);
        }

        /// <summary>
        /// 모든 루트 항목에 대해 필터링을 수행합니다.
        /// </summary>
        /// <param name="qLower">소문자로 변환된 검색어</param>
        /// <returns>필터링된 TreeViewItemData 리스트</returns>
        private List<TreeViewItemData<UTKTreeListItemData>> FilterTree(string qLower)
        {
            var result = new List<TreeViewItemData<UTKTreeListItemData>>();
            foreach (var root in _originalRoots)
            {
                TreeViewItemData<UTKTreeListItemData>? filtered = FilterNode(root, qLower);
                if (filtered != null) result.Add(filtered.Value);
            }
            return result;
        }

        /// <summary>
        /// 단일 노드를 필터링합니다.
        /// 자신 또는 자식이 검색어와 매치되면 결과에 포함됩니다.
        /// </summary>
        /// <param name="node">필터링할 노드</param>
        /// <param name="qLower">소문자로 변환된 검색어</param>
        /// <returns>매치된 경우 TreeViewItemData, 아니면 null</returns>
        private TreeViewItemData<UTKTreeListItemData>? FilterNode(UTKTreeListItemData node, string qLower)
        {
            // 자기 자신이 매치되는지 확인
            bool selfMatch = NodeMatches(node, qLower);
            List<TreeViewItemData<UTKTreeListItemData>>? childFiltered = null;

            // 자식들도 재귀적으로 필터링
            if (node.children != null && node.children.Count > 0)
            {
                foreach (var child in node.children)
                {
                    TreeViewItemData<UTKTreeListItemData>? f = FilterNode(child, qLower);
                    if (f != null)
                    {
                        childFiltered ??= new List<TreeViewItemData<UTKTreeListItemData>>();
                        childFiltered.Add(f.Value);
                    }
                }
            }

            // 자신이 매치되거나 매치된 자식이 있으면 포함
            if (selfMatch || (childFiltered != null && childFiltered.Count > 0))
            {
                return new TreeViewItemData<UTKTreeListItemData>(node.id, node, childFiltered);
            }
            return null;
        }

        /// <summary>
        /// 노드가 검색어와 매치되는지 확인합니다.
        /// name, option, ExternalKey 필드를 검색 대상으로 합니다.
        /// </summary>
        /// <param name="item">검사할 항목</param>
        /// <param name="qLower">소문자로 변환된 검색어</param>
        /// <returns>매치 여부</returns>
        private bool NodeMatches(UTKTreeListItemData item, string qLower)
        {
            if (item.name != null && item.name.ToLowerInvariant().Contains(qLower)) return true;
            if (!string.IsNullOrEmpty(item.option) && item.option.ToLowerInvariant().Contains(qLower)) return true;
            if (!string.IsNullOrEmpty(item.ExternalKey) && item.ExternalKey.ToLowerInvariant().Contains(qLower)) return true;
            return false;
        }

        /// <summary>
        /// 필터링된 결과의 모든 항목을 펼칩니다.
        /// </summary>
        /// <param name="roots">펼칠 루트 항목들</param>
        private void ExpandAll(List<TreeViewItemData<UTKTreeListItemData>> roots)
        {
            foreach (var r in roots)
                ExpandRecursive(r);
        }

        /// <summary>
        /// 노드와 그 자식들을 재귀적으로 펼칩니다.
        /// </summary>
        /// <param name="wrapper">펼칠 TreeViewItemData</param>
        private void ExpandRecursive(TreeViewItemData<UTKTreeListItemData> wrapper)
        {
            _treeView.ExpandItem(wrapper.id);
            if (wrapper.children != null)
            {
                foreach (var c in wrapper.children)
                    ExpandRecursive(c);
            }
        }
        #endregion

        #region IDisposable
        /// <summary>
        /// 리소스를 해제하고 이벤트 핸들러를 정리합니다.
        /// </summary>
        public void Dispose()
        {
            if (_disposed) return;
            _disposed = true;

            // 검색 필드 이벤트 해제
            if (_searchField != null)
            {
                _searchField.UnregisterCallback<KeyDownEvent>(OnSearchFieldKeyDown);
                _searchField.UnregisterCallback<FocusOutEvent>(OnSearchFieldFocusOut);
            }

            // TreeView 이벤트 핸들러 해제
            if (_treeView != null)
            {
                _treeView.selectionChanged -= OnTreeViewSelectionChanged;
                _treeView.itemsChosen -= OnTreeViewItemsChosen;
                _treeView.itemExpandedChanged -= OnTreeViewItemExpandedChanged;
                _treeView.UnregisterCallback<KeyDownEvent>(OnTreeViewKeyDown);
                _treeView.bindItem = null;
                _treeView.makeItem = null;
            }

            // 닫기 버튼 이벤트 해제 및 정리
            if (_closeButton != null)
            {
                _closeButton.OnClicked -= OnCloseButtonClicked;
                _closeButton.Dispose();
            }

            // Clear 버튼 이벤트 해제 및 정리
            if (_clearButton != null)
            {
                _clearButton.OnClicked -= OnClearButtonClicked;
                _clearButton.Dispose();
            }

            // 외부 이벤트 구독자 정리
            OnItemVisibilityChanged = null;
            OnClosed = null;
            OnItemSelected = null;
            OnItemDeselected = null;
            OnItemDeleted = null;
            OnItemDoubleClicked = null;

            // 데이터 정리
            _originalRoots.Clear();
            _rootData?.Clear();
            _rootData = null;
            _previouslySelectedItems.Clear();

            // ID 시드 초기화
            _idSeed = 1;

            // UI 참조 정리
            _searchField = null;
            _treeView = null;
            _titleLabel = null;
            _closeButton = null;
            _clearButton = null;
        }
        #endregion
    }
}