(*---------------------------------------------------------------------------
  Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
  SPDX-License-Identifier: MIT
 ---------------------------------------------------------------------------*)

(** Floating warning panel UI.

    This module creates and manages a draggable, floating panel that displays
    validation warnings. The panel supports:
    - Grouping by severity (errors first)
    - Click-to-navigate to problematic elements
    - Collapse/expand functionality
    - Light/dark themes *)

open Htmlrw_js_types


(** {1 Panel Management} *)

(** The warning panel. *)
type t

(** Create and display a warning panel.

    The panel is appended to [document.body] and positioned according
    to the configuration.

    @param config Panel configuration.
    @param result Validation result to display. *)
val create : config:panel_config -> result -> t

(** Update the panel with new validation results.

    Use this to re-validate and refresh the panel without destroying it. *)
val update : t -> result -> unit

(** Show the panel if hidden. *)
val show : t -> unit

(** Hide the panel (but keep it in the DOM). *)
val hide : t -> unit

(** Remove the panel from the DOM entirely. *)
val destroy : t -> unit

(** Check if the panel is currently visible. *)
val is_visible : t -> bool

(** Check if the panel is currently collapsed. *)
val is_collapsed : t -> bool


(** {1 Panel State} *)

(** Collapse the panel to just show the summary badge. *)
val collapse : t -> unit

(** Expand the panel to show the full warning list. *)
val expand : t -> unit

(** Toggle collapsed state. *)
val toggle_collapsed : t -> unit

(** Get the current position of the panel. *)
val position : t -> int * int

(** Move the panel to a new position. *)
val set_position : t -> int -> int -> unit


(** {1 Interaction} *)

(** Scroll to and highlight an element from a warning row.

    This is called internally when clicking a warning, but can be
    invoked programmatically. *)
val navigate_to_element : t -> browser_message -> unit

(** Get the currently highlighted element, if any. *)
val highlighted_element : t -> Brr.El.t option

(** Clear the current highlight. *)
val clear_highlight : t -> unit


(** {1 Event Callbacks}

    Register callbacks for panel events. *)

(** Called when a warning row is clicked. *)
val on_warning_click : t -> (browser_message -> unit) -> unit

(** Called when the panel is collapsed or expanded. *)
val on_collapse_toggle : t -> (bool -> unit) -> unit

(** Called when the panel is closed. *)
val on_close : t -> (unit -> unit) -> unit

(** Called when the panel is dragged to a new position. *)
val on_move : t -> (int * int -> unit) -> unit


(** {1 Global Panel State}

    For convenience, there's a single "current" panel that the
    JavaScript API manages. *)

(** Get the current panel, if one exists. *)
val current : unit -> t option

(** Hide and destroy the current panel. *)
val hide_current : unit -> unit


(** {1 Panel Elements}

    Access to the panel's DOM structure for custom styling. *)

(** The root panel element. *)
val root_element : t -> Brr.El.t

(** The header element (contains title and controls). *)
val header_element : t -> Brr.El.t

(** The content element (contains warning list). *)
val content_element : t -> Brr.El.t

(** The summary badge element (shown when collapsed). *)
val badge_element : t -> Brr.El.t


(** {1 CSS Classes}

    Classes used by the panel for custom styling. *)

module Css_class : sig
  val panel : Jstr.t
  val panel_header : Jstr.t
  val panel_content : Jstr.t
  val panel_collapsed : Jstr.t
  val panel_dragging : Jstr.t
  val warning_list : Jstr.t
  val warning_row : Jstr.t
  val warning_row_error : Jstr.t
  val warning_row_warning : Jstr.t
  val warning_row_info : Jstr.t
  val severity_badge : Jstr.t
  val message_text : Jstr.t
  val selector_path : Jstr.t
  val collapse_btn : Jstr.t
  val close_btn : Jstr.t
  val summary_badge : Jstr.t
  val error_count : Jstr.t
  val warning_count : Jstr.t
  val theme_light : Jstr.t
  val theme_dark : Jstr.t
end


(** {1 CSS Injection} *)

(** Inject default CSS styles for the panel.

    Styles include layout, colors, shadows, and animations.
    The styles are scoped to the panel's CSS classes.

    @param theme Color scheme to use.
    @return The injected style element. *)
val inject_default_styles : theme:[ `Light | `Dark | `Auto ] -> Brr.El.t