XRLib/Assets/Scripts/UVC/UIToolkit/Common/UTKHelpBox.cs

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

namespace UVC.UIToolkit
{
    /// <summary>
    /// 도움말 박스 컴포넌트.
    /// Unity HelpBox를 래핑하여 커스텀 스타일을 적용합니다.
    /// 정보, 경고, 오류 메시지를 아이콘과 함께 표시합니다.
    /// </summary>
    /// <remarks>
    /// <para><b>HelpBox(도움말 박스)란?</b></para>
    /// <para>
    /// HelpBox는 사용자에게 중요한 정보, 경고, 오류 메시지를 눈에 띄게 표시하는 컴포넌트입니다.
    /// 메시지 유형에 따라 아이콘과 배경색이 달라져 시각적으로 구분됩니다.
    /// Unity Inspector에서 볼 수 있는 노란색/빨간색 경고 박스와 같은 역할입니다.
    /// </para>
    ///
    /// <para><b>메시지 유형 (HelpBoxMessageType):</b></para>
    /// <list type="bullet">
    /// <item><description><c>None</c> - 아이콘 없이 텍스트만 표시</description></item>
    /// <item><description><c>Info</c> - 정보 아이콘 (파란색) - 일반 안내 메시지</description></item>
    /// <item><description><c>Warning</c> - 경고 아이콘 (노란색) - 주의 필요한 사항</description></item>
    /// <item><description><c>Error</c> - 오류 아이콘 (빨간색) - 에러, 문제 상황</description></item>
    /// </list>
    ///
    /// <para><b>HelpBox vs Alert 차이:</b></para>
    /// <list type="bullet">
    /// <item><description><c>HelpBox</c> - 화면에 고정 표시, 닫기 불가, 인라인 메시지</description></item>
    /// <item><description><c>Alert</c> - 모달 팝업, 버튼으로 닫기, 사용자 확인 필요</description></item>
    /// </list>
    ///
    /// <para><b>실제 활용 예시:</b></para>
    /// <list type="bullet">
    /// <item><description>폼 유효성 검사 - 입력 오류 메시지</description></item>
    /// <item><description>설정 페이지 - "이 설정은 재시작 후 적용됩니다" 안내</description></item>
    /// <item><description>에디터 - "필수 필드가 비어 있습니다" 경고</description></item>
    /// <item><description>튜토리얼 - 사용법 힌트 표시</description></item>
    /// </list>
    /// </remarks>
    /// <example>
    /// <para><b>C# 코드에서 사용:</b></para>
    /// <code>
    /// // 정보 메시지
    /// var infoBox = new UTKHelpBox()
    /// {
    ///     Message = "이 기능은 베타 버전입니다.",
    ///     messageType = HelpBoxMessageType.Info
    /// };
    /// 
    /// // 경고 메시지
    /// var warningBox = new UTKHelpBox()
    /// {
    ///     Message = "주의: 되돌릴 수 없습니다.",
    ///     messageType = HelpBoxMessageType.Warning
    /// };
    /// 
    /// // 오류 메시지
    /// var errorBox = new UTKHelpBox()
    /// {
    ///     Message = "오류: 파일을 찾을 수 없습니다.",
    ///     messageType = HelpBoxMessageType.Error
    /// };
    /// </code>
    /// <para><b>UXML에서 사용:</b></para>
    /// <code>
    /// <ui:UXML xmlns:utk="UVC.UIToolkit">
    ///     <!-- 정보 -->
    ///     <utk:UTKHelpBox text="정보 메시지입니다." message-type="Info" />
    ///     
    ///     <!-- 경고 -->
    ///     <utk:UTKHelpBox text="경고 메시지입니다." message-type="Warning" />
    ///     
    ///     <!-- 오류 -->
    ///     <utk:UTKHelpBox text="오류 메시지입니다." message-type="Error" />
    /// </ui:UXML>
    /// </code>
    /// </example>
    [UxmlElement]
    public partial class UTKHelpBox : HelpBox, IDisposable
    {
        #region Constants
        private const string USS_PATH = "UIToolkit/Common/UTKHelpBox";
        #endregion

        #region Fields
        private bool _disposed;
        #endregion

        #region Properties
        /// <summary>메시지 텍스트</summary>
        [UxmlAttribute("text")]
        public string Message
        {
            get => text;
            set => text = value;
        }

        /// <summary>메시지 타입</summary>
        [UxmlAttribute("message-type")]
        public new HelpBoxMessageType MessageType
        {
            get => base.messageType;
            set
            {
                base.messageType = value;
                UpdateMessageTypeClass();
            }
        }
        #endregion

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

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

            SetupStyles();
            SubscribeToThemeChanges();
        }

        public UTKHelpBox(string message, HelpBoxMessageType type = HelpBoxMessageType.Info) : this()
        {
            Message = message;
            MessageType = type;
        }
        #endregion

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

        private void UpdateMessageTypeClass()
        {
            RemoveFromClassList("utk-helpbox--info");
            RemoveFromClassList("utk-helpbox--warning");
            RemoveFromClassList("utk-helpbox--error");
            RemoveFromClassList("utk-helpbox--none");

            var typeClass = messageType switch
            {
                HelpBoxMessageType.Warning => "utk-helpbox--warning",
                HelpBoxMessageType.Error => "utk-helpbox--error",
                HelpBoxMessageType.None => "utk-helpbox--none",
                _ => "utk-helpbox--info"
            };
            AddToClassList(typeClass);
        }

        private void SubscribeToThemeChanges()
        {
            UTKThemeManager.Instance.OnThemeChanged += OnThemeChanged;
            RegisterCallback<DetachFromPanelEvent>(_ =>
            {
                UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
            });
        }

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

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

            UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
        }
        #endregion
    }
}