// ---------------------------------------------------------------------------
// BT.Framework
// ArrayTitleAttribute.cs — 배열 요소별 인스펙터 라벨 커스터마이즈 속성
// ---------------------------------------------------------------------------
using System;
using UnityEngine;

namespace BurningTimes.Core.Attribute
{
    /// <summary>
    /// 배열·리스트의 각 요소를 인스펙터에서 표시할 때
    /// "Element N" 대신 지정 멤버의 값을 라벨로 사용하도록 지시한다.
    /// </summary>
    /// <remarks>
    /// <para>설계 문서 §5 Tier 1. 데이터 테이블·카드 리스트 등 요소 식별이 잦은 컬렉션을
    /// 인스펙터에서 빠르게 탐색할 수 있도록 한다.</para>
    /// <para>동작:</para>
    /// <list type="bullet">
    ///   <item><description>요소 타입 내부의 <see cref="MemberName"/> 필드 또는 프로퍼티를 읽어
    ///     <see cref="object.ToString"/> 결과를 라벨로 사용.</description></item>
    ///   <item><description>해당 멤버를 찾지 못하면 기본 "Element N" 라벨로 폴백.</description></item>
    ///   <item><description><see cref="Prefix"/>가 지정된 경우 접두어로 덧붙인다(예: "Card: Fireball").</description></item>
    /// </list>
    /// <para>실제 그리기는 Editor 스크립트 <c>ArrayTitleDrawer</c>에서 담당한다.</para>
    /// <para>사용 예:</para>
    /// <code>
    /// [SerializeField, ArrayTitle(nameof(CardEntry.DisplayName), "Card")]
    /// private List&lt;CardEntry&gt; _cards;
    /// </code>
    /// </remarks>
    [AttributeUsage(AttributeTargets.Field, AllowMultiple = false, Inherited = true)]
    public sealed class ArrayTitleAttribute : PropertyAttribute
    {
        /// <summary>요소 내부에서 라벨로 사용할 멤버 이름.</summary>
        public string MemberName { get; }

        /// <summary>라벨 접두어(옵션). 빈 문자열이면 접두어 없이 멤버 값만 표시.</summary>
        public string Prefix { get; }

        /// <summary>기본 생성자. 접두어 없이 멤버 값만 라벨로 사용한다.</summary>
        public ArrayTitleAttribute(string memberName)
        {
            MemberName = memberName;
            Prefix = string.Empty;
        }

        /// <summary>접두어와 함께 라벨을 구성한다. 표시 형식: "{Prefix}: {MemberValue}".</summary>
        public ArrayTitleAttribute(string memberName, string prefix)
        {
            MemberName = memberName;
            Prefix = prefix ?? string.Empty;
        }
    }
}
