using System;
using System.Threading;
using System.Threading.Tasks;

namespace BaseGames.UI
{
    /// <summary>
    /// 统一 UI 导航栈服务。所有面板（主菜单子面板 + 游戏内面板）经此压栈/出栈，
    /// 由它统一保证：只有栈顶可交互、下层被屏蔽出导航图、ESC 逐层回退、出栈恢复焦点。
    ///
    /// <para>设计要点：</para>
    /// <list type="bullet">
    /// <item>单一取消入口：导航器是 EVT_UICancelPressed 的唯一消费者，ESC 只关栈顶一层。</item>
    /// <item>场景作用域：面板可能位于会被卸载的关卡 / 主菜单场景，导航器订阅 sceneUnloaded
    ///       清理随场景销毁的栈层，每次操作对已销毁面板兜底。</item>
    /// <item>非面板的"底层上下文"（如主菜单按钮组、游戏内 HUD）不入栈，由各自上下文
    ///       订阅 <see cref="StackChanged"/> / 读 <see cref="Depth"/> 自行屏蔽。</item>
    /// </list>
    /// </summary>
    public interface IUINavigator
    {
        /// <summary>当前栈顶面板；空栈为 null。</summary>
        UIPanelBase Top { get; }

        /// <summary>栈深度（已打开的面板层数）。</summary>
        int Depth { get; }

        /// <summary>栈结构变化（任何 Push / Pop / 场景清理）后触发，供底层上下文屏蔽自身。</summary>
        event Action StackChanged;

        /// <summary>压栈打开面板。<paramref name="mode"/> 为空时用面板自身 <see cref="UIPanelBase.DefaultMode"/>。</summary>
        void Push(UIPanelBase panel, PushMode? mode = null);

        /// <summary>关闭栈顶并恢复下层（若有）。空栈无操作。</summary>
        void Pop();

        /// <summary>清空整个栈（逐层关闭）。</summary>
        void PopToRoot();

        /// <summary>
        /// 压栈打开结果面板并等待玩家给出结果（确认 / 选择）。
        /// 面板被出栈（含 ESC 取消）、被销毁或 <paramref name="ct"/> 取消时，
        /// 以面板的取消默认值兜底完成，绝不悬挂 await。
        /// </summary>
        Task<T> PushForResultAsync<T>(UIResultPanel<T> panel, CancellationToken ct = default);
    }
}