namespace AcDream.UI.Abstractions;

/// <summary>
/// A UI panel — chat window, inventory, vitals HUD, character sheet, etc.
/// Panels are backend-agnostic: they only call into <see cref="IPanelRenderer"/>
/// primitives, never reach through to a specific UI library (Hexa.NET.ImGui
/// in Phase D.2a, a custom retail-look toolkit in Phase D.2b).
///
/// <para>
/// Hard rule: <b>no <c>using Hexa.NET.ImGui</c> inside a panel file</b>. If a
/// widget needs a feature the abstraction doesn't expose, extend
/// <see cref="IPanelRenderer"/>; do not import the backend. See
/// <c>docs/plans/2026-04-24-ui-framework.md</c>.
/// </para>
/// </summary>
public interface IPanel
{
    /// <summary>Stable, globally-unique identifier. Convention: <c>acdream.{name}</c>.</summary>
    string Id { get; }

    /// <summary>Human-readable window title shown in the chrome of the panel.</summary>
    string Title { get; }

    /// <summary>
    /// Whether the panel is currently visible. Backends read this per frame;
    /// panels may mutate it in response to their own close-button handling.
    /// </summary>
    bool IsVisible { get; set; }

    /// <summary>
    /// Draw the panel for one frame. Called by <see cref="IPanelHost.RenderAll"/>
    /// on the render thread once ImGui's (or the future custom backend's)
    /// frame has begun. Panels issue drawing calls through <paramref name="renderer"/>
    /// and publish user-intent actions through <paramref name="ctx"/>.<see cref="PanelContext.Commands"/>.
    /// </summary>
    void Render(PanelContext ctx, IPanelRenderer renderer);
}