EnglewoodLAB/Assets/Scripts/UVC/UIToolkit/List/UTKTreeView.cs

#nullable enable
using System;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UIElements;

namespace UVC.UIToolkit
{
    /// <summary>
    /// 트리 뷰 컴포넌트.
    /// Unity TreeView를 래핑하여 커스텀 스타일을 적용합니다.
    /// 계층적(부모-자식) 구조의 데이터를 접기/펼치기로 표시합니다.
    /// </summary>
    /// <remarks>
    /// <para><b>TreeView(트리 뷰)란?</b></para>
    /// <para>
    /// TreeView는 계층 구조(부모-자식 관계)를 가진 데이터를 표시하는 UI 컴포넌트입니다.
    /// 폴더 구조, 조직도, 메뉴 계층, 게임 오브젝트 계층 등을 표현할 때 사용합니다.
    /// 각 노드는 펼치거나 접을 수 있어 복잡한 구조를 효율적으로 탐색할 수 있습니다.
    /// </para>
    ///
    /// <para><b>ListView vs TreeView:</b></para>
    /// <list type="bullet">
    /// <item><description><c>ListView</c> - 단순 목록 (1차원 데이터)</description></item>
    /// <item><description><c>TreeView</c> - 계층 구조 (부모-자식, 중첩 가능)</description></item>
    /// </list>
    ///
    /// <para><b>TreeViewItemData 구조:</b></para>
    /// <code>
    /// TreeViewItemData<T>(int id, T data, List<TreeViewItemData<T>> children)
    /// - id: 고유 식별자 (필수, 중복 불가)
    /// - data: 노드에 저장할 데이터
    /// - children: 자식 노드 목록 (없으면 리프 노드)
    /// </code>
    ///
    /// <para><b>필수 설정:</b></para>
    /// <list type="number">
    /// <item><description><c>SetRootItems()</c> - 루트 노드 설정</description></item>
    /// <item><description><c>makeItem</c> - 항목 VisualElement 생성 함수</description></item>
    /// <item><description><c>bindItem</c> - 데이터를 요소에 바인딩하는 함수</description></item>
    /// </list>
    ///
    /// <para><b>주요 메서드:</b></para>
    /// <list type="bullet">
    /// <item><description><c>SetRootItems()</c> - 전체 트리 데이터 설정</description></item>
    /// <item><description><c>GetItemDataForIndex<T>(index)</c> - 인덱스로 데이터 조회</description></item>
    /// <item><description><c>ExpandItem(id)</c> - 특정 노드 펼치기</description></item>
    /// <item><description><c>CollapseItem(id)</c> - 특정 노드 접기</description></item>
    /// <item><description><c>ExpandAll()</c> - 모든 노드 펼치기</description></item>
    /// <item><description><c>CollapseAll()</c> - 모든 노드 접기</description></item>
    /// </list>
    ///
    /// <para><b>실제 활용 예시:</b></para>
    /// <list type="bullet">
    /// <item><description>파일 탐색기 - 폴더/파일 계층 구조</description></item>
    /// <item><description>Unity Hierarchy - 게임 오브젝트 계층</description></item>
    /// <item><description>조직도 - 부서/팀/직원 구조</description></item>
    /// <item><description>메뉴 시스템 - 다단계 메뉴</description></item>
    /// <item><description>카테고리 - 대분류/중분류/소분류</description></item>
    /// </list>
    /// </remarks>
    /// <example>
    /// <para><b>C# 코드에서 사용:</b></para>
    /// <code>
    /// // 트리 뷰 생성
    /// var treeView = new UTKTreeView();
    /// treeView.fixedItemHeight = 24;
    ///
    /// // 계층 데이터 구성
    /// var rootItems = new List<TreeViewItemData<string>>
    /// {
    ///     new TreeViewItemData<string>(0, "프로젝트", new List<TreeViewItemData<string>>
    ///     {
    ///         new TreeViewItemData<string>(1, "Assets", new List<TreeViewItemData<string>>
    ///         {
    ///             new TreeViewItemData<string>(2, "Scripts"),
    ///             new TreeViewItemData<string>(3, "Prefabs"),
    ///             new TreeViewItemData<string>(4, "Materials")
    ///         }),
    ///         new TreeViewItemData<string>(5, "Packages")
    ///     }),
    ///     new TreeViewItemData<string>(6, "Settings")
    /// };
    ///
    /// treeView.SetRootItems(rootItems);
    ///
    /// // 항목 생성 함수
    /// treeView.makeItem = () => new Label();
    ///
    /// // 데이터 바인딩 함수
    /// treeView.bindItem = (element, index) => {
    ///     var data = treeView.GetItemDataForIndex<string>(index);
    ///     (element as Label).text = data;
    /// };
    ///
    /// // 선택 이벤트
    /// treeView.OnItemSelected += (index) => {
    ///     var selectedData = treeView.GetItemDataForIndex<string>(index);
    ///     Debug.Log($"선택됨: {selectedData}");
    /// };
    ///
    /// // 더블클릭 이벤트 (폴더 열기 등)
    /// treeView.OnItemDoubleClicked += (index) => {
    ///     var data = treeView.GetItemDataForIndex<string>(index);
    ///     OpenFolder(data);
    /// };
    ///
    /// // 특정 노드 펼치기
    /// treeView.ExpandItem(0);  // ID 0인 노드 펼치기
    ///
    /// // 모든 노드 펼치기
    /// treeView.ExpandAll();
    /// </code>
    /// <para><b>UXML에서 사용:</b></para>
    /// <code>
    /// <!-- 기본 트리 뷰 -->
    /// <utk:UTKTreeView fixed-item-height="24" />
    ///
    /// <!-- 다중 선택 가능 -->
    /// <utk:UTKTreeView selection-type="Multiple" />
    /// </code>
    /// </example>
    [UxmlElement]
    public partial class UTKTreeView : TreeView, IDisposable
    {
        #region Constants
        private const string USS_PATH = "UIToolkit/List/UTKTreeView";
        #endregion

        #region Fields
        private bool _disposed;
        #endregion

        #region Events
        /// <summary>아이템 선택 이벤트</summary>
        public event Action<int>? OnItemSelected;
        /// <summary>아이템 더블클릭 이벤트</summary>
        public event Action<int>? OnItemDoubleClicked;
        #endregion

        #region Constructor
        public UTKTreeView() : base()
        {
            UTKThemeManager.Instance.ApplyThemeToElement(this);

            var uss = Resources.Load<StyleSheet>(USS_PATH);
            if (uss != null)
            {
                styleSheets.Add(uss);
            }

            SetupStyles();
            SetupEvents();
            SubscribeToThemeChanges();
        }
        #endregion

        #region Setup
        private void SetupStyles()
        {
            AddToClassList("utk-treeview");
        }

        private void SetupEvents()
        {
            selectionChanged += OnSelectionChanged;
            itemsChosen += OnItemsChosen;
        }

        private void SubscribeToThemeChanges()
        {
            UTKThemeManager.Instance.OnThemeChanged += OnThemeChanged;
            RegisterCallback<AttachToPanelEvent>(OnAttachToPanelForTheme);
            RegisterCallback<DetachFromPanelEvent>(OnDetachFromPanelForTheme);
        }

        private void OnAttachToPanelForTheme(AttachToPanelEvent evt)
        {
            UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
            UTKThemeManager.Instance.OnThemeChanged += OnThemeChanged;
            UTKThemeManager.Instance.ApplyThemeToElement(this);
        }

        private void OnDetachFromPanelForTheme(DetachFromPanelEvent evt)
        {
            UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
        }

        private void OnThemeChanged(UTKTheme theme)
        {
            UTKThemeManager.Instance.ApplyThemeToElement(this);
        }
        #endregion

        #region Event Handlers
        private void OnSelectionChanged(IEnumerable<object> items)
        {
            OnItemSelected?.Invoke(selectedIndex);
        }

        private void OnItemsChosen(IEnumerable<object> items)
        {
            OnItemDoubleClicked?.Invoke(selectedIndex);
        }
        #endregion

        #region IDisposable
        public void Dispose()
        {
            if (_disposed) return;
            _disposed = true;

            selectionChanged -= OnSelectionChanged;
            itemsChosen -= OnItemsChosen;
            UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
            UnregisterCallback<AttachToPanelEvent>(OnAttachToPanelForTheme);
            UnregisterCallback<DetachFromPanelEvent>(OnDetachFromPanelForTheme);
            OnItemSelected = null;
            OnItemDoubleClicked = null;
        }
        #endregion
    }
}