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

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

namespace UVC.UIToolkit
{
    /// <summary>
    /// 트리 구조 리스트의 항목 데이터를 위한 추상 기본 클래스입니다.
    ///
    /// <para><b>개요:</b></para>
    /// <para>
    /// UTKComponentListItemDataBase는 카테고리(UTKComponentListCategoryData)와
    /// 일반 항목(UTKComponentListItemData)의 공통 속성을 정의합니다.
    /// UTKComponentListWindow(UI)에서 사용됩니다.
    /// </para>
    ///
    /// <para><b>상속 구조:</b></para>
    /// <list type="bullet">
    ///   <item>UTKComponentListCategoryData - 카테고리용 (자식 항목을 가짐)</item>
    ///   <item>UTKComponentListItemData - 일반 항목용 (리프 노드)</item>
    /// </list>
    /// </summary>
    public abstract class UTKComponentListItemDataBase : IDisposable
    {
        /// <summary>
        /// 항목의 고유 식별자입니다.
        /// TreeView에서 항목을 구분하고 선택하는 데 사용됩니다.
        /// 일반적으로 UTKComponentList.SetData() 호출 시 자동으로 할당됩니다.
        /// </summary>
        public int id = 0;

        /// <summary>
        /// 항목의 표시 이름입니다.
        /// UI의 TreeView에서 사용자에게 보여지는 텍스트입니다.
        /// </summary>
        public string name = string.Empty;

        /// <summary>
        /// 트리뷰에서 해당 항목이 펼쳐져 있는지 여부입니다.
        /// true: 자식 항목들이 표시됨 / false: 자식 항목들이 숨겨짐
        /// </summary>
        public bool isExpanded = true;

        /// <summary>
        /// 해당 항목이 현재 선택되어 있는지 여부입니다.
        /// 선택 상태가 변경되면 UTKComponentList.OnSelectionChanged 이벤트가 발생합니다.
        /// </summary>
        public bool isSelected = false;

        /// <summary>
        /// 해당 항목(및 연결된 3D 오브젝트)의 가시성 상태입니다.
        /// UI의 눈 아이콘 버튼으로 토글되며,
        /// 변경 시 UTKComponentListWindow.OnVisibilityChanged 이벤트를 통해
        /// 3D 모델의 GameObject.SetActive()가 호출됩니다.
        /// </summary>
        public bool IsVisible = true;

        /// <summary>
        /// 검색 결과를 감싸는 임시 그룹 항목인지 여부입니다.
        /// true인 경우 setting-btn이 숨겨지고 클릭되지 않습니다.
        /// 검색 시 자동 생성되며, 검색 해제 시 제거됩니다.
        /// </summary>
        public bool isSearchResultGroup = false;

        /// <summary>
        /// 부모 항목에 대한 참조입니다.
        /// 루트 항목의 경우 null입니다.
        /// Add() 메서드로 자식을 추가하면 자동으로 설정됩니다.
        /// </summary>
        public UTKComponentListItemDataBase? parent;

        /// <summary>
        /// 자식 항목들의 리스트입니다.
        /// 카테고리 항목에서만 사용됩니다. 일반 항목에서는 빈 리스트입니다.
        /// </summary>
        public abstract List<UTKComponentListItemDataBase> children { get; }

        /// <summary>
        /// 이 항목이 카테고리인지 여부를 반환합니다.
        /// </summary>
        public abstract bool IsCategory { get; }

        /// <summary>
        /// 리소스를 해제합니다.
        /// </summary>
        public virtual void Dispose()
        {
            parent = null;
        }
    }

    /// <summary>
    /// 카테고리(그룹) 항목을 나타내는 클래스입니다.
    /// 자식 항목들을 가질 수 있습니다.
    ///
    /// <para><b>사용 예시:</b></para>
    /// <code>
    /// // 카테고리 생성
    /// var category = new UTKComponentListCategoryData { name = "카테고리1" };
    ///
    /// // 일반 항목 추가
    /// var item1 = new UTKComponentListItemData { name = "항목1", option = "옵션1" };
    /// var item2 = new UTKComponentListItemData { name = "항목2", option = "옵션2" };
    /// category.Add(item1);
    /// category.Add(item2);
    /// </code>
    /// </summary>
    public class UTKComponentListCategoryData : UTKComponentListItemDataBase
    {
        /// <summary>
        /// 자식 항목들의 리스트입니다.
        /// </summary>
        private List<UTKComponentListItemDataBase> _children = new List<UTKComponentListItemDataBase>();

        /// <summary>
        /// 자식 항목들의 리스트를 반환합니다.
        /// </summary>
        public override List<UTKComponentListItemDataBase> children => _children;

        /// <summary>
        /// 이 항목이 카테고리임을 나타냅니다.
        /// </summary>
        public override bool IsCategory => true;

        /// <summary>
        /// 자식 항목을 추가합니다.
        /// 추가되는 자식의 parent 속성이 자동으로 현재 항목으로 설정됩니다.
        /// </summary>
        /// <param name="child">추가할 자식 항목</param>
        public void Add(UTKComponentListItemDataBase child)
        {
            child.parent = this;
            _children.Add(child);
        }

        /// <summary>
        /// 자식 항목을 제거합니다.
        /// </summary>
        /// <param name="child">제거할 자식 항목</param>
        /// <returns>제거 성공 여부</returns>
        public bool Remove(UTKComponentListItemDataBase child)
        {
            if (_children.Remove(child))
            {
                child.parent = null;
                return true;
            }
            return false;
        }

        /// <summary>
        /// 모든 자식 항목을 제거합니다.
        /// </summary>
        public void Clear()
        {
            foreach (var child in _children)
            {
                child.parent = null;
            }
            _children.Clear();
        }

        /// <summary>
        /// 리소스를 해제합니다.
        /// </summary>
        public override void Dispose()
        {
            Clear();
            base.Dispose();
        }
    }

    /// <summary>
    /// 일반 항목(리프 노드)을 나타내는 클래스입니다.
    /// 자식 항목을 가지지 않습니다.
    ///
    /// <para><b>사용 예시:</b></para>
    /// <code>
    /// var item = new UTKComponentListItemData
    /// {
    ///     name = "항목 이름",
    ///     option = "추가 옵션",
    ///     ExternalKey = "외부 연동 키"
    /// };
    /// </code>
    /// </summary>
    public class UTKComponentListItemData : UTKComponentListItemDataBase
    {
        /// <summary>
        /// 추가 옵션 또는 설명 텍스트입니다.
        /// 검색 필터링 시 name과 함께 검색 대상이 됩니다.
        /// </summary>
        public string option = string.Empty;

        /// <summary>
        /// 외부 시스템(예: 간트 차트)과의 연동을 위한 외부 키입니다.
        /// 검색 필터링 시 검색 대상에 포함됩니다.
        /// 모델과 차트 간의 동기화에 사용될 수 있습니다.
        /// </summary>
        public string ExternalKey = string.Empty;

        /// <summary>
        /// 임의의 데이터를 항목에 연결하기 위한 태그입니다.
        /// 예: Transform, GameObject 등 외부 객체 참조에 사용됩니다.
        /// </summary>
        public object? Tag = null;

        /// <summary>
        /// 일반 항목은 자식을 가지지 않으므로 빈 리스트를 반환합니다.
        /// </summary>
        private static readonly List<UTKComponentListItemDataBase> _emptyChildren = new List<UTKComponentListItemDataBase>();

        /// <summary>
        /// 자식 항목들의 리스트를 반환합니다. 항상 빈 리스트입니다.
        /// </summary>
        public override List<UTKComponentListItemDataBase> children => _emptyChildren;

        /// <summary>
        /// 이 항목이 카테고리가 아님을 나타냅니다.
        /// </summary>
        public override bool IsCategory => false;
    }
}