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

(** DOM annotation for validation warnings.

    This module applies validation results to the live DOM by adding
    data attributes, CSS classes, and tooltip overlays to elements
    that have warnings. *)

open Htmlrw_js_types


(** {1 Annotation} *)

(** Annotate elements in a subtree based on validation results.

    For each message with an element reference, this function:
    1. Adds data attributes ([data-html5rw-severity], etc.) if configured
    2. Adds CSS classes ([html5rw-error], etc.) if configured
    3. Creates tooltip elements if configured

    @param config Annotation configuration.
    @param root The root element to annotate within.
    @param messages The validation messages with element references. *)
val annotate :
  config:annotation_config ->
  root:Brr.El.t ->
  browser_message list ->
  unit

(** Annotate a single element with a message.

    Lower-level function for custom annotation logic. *)
val annotate_element :
  config:annotation_config ->
  Brr.El.t ->
  Htmlrw_check.message ->
  unit


(** {1 Clearing Annotations} *)

(** Remove all annotations from a subtree.

    This removes:
    - All [data-html5rw-*] attributes
    - All [html5rw-*] CSS classes
    - All tooltip elements created by this module *)
val clear : Brr.El.t -> unit

(** Remove annotations from a single element (not descendants). *)
val clear_element : Brr.El.t -> unit


(** {1 Tooltips} *)

(** Tooltip state for an element. *)
type tooltip

(** Create a tooltip for an element.

    The tooltip is not immediately visible; it appears on hover
    if CSS is set up correctly, or can be shown programmatically.

    @param position Where to position the tooltip.
    @param el The element to attach the tooltip to.
    @param messages All messages for this element (may be multiple). *)
val create_tooltip :
  position:[ `Above | `Below | `Auto ] ->
  Brr.El.t ->
  Htmlrw_check.message list ->
  tooltip

(** Show a tooltip immediately. *)
val show_tooltip : tooltip -> unit

(** Hide a tooltip. *)
val hide_tooltip : tooltip -> unit

(** Remove a tooltip from the DOM. *)
val remove_tooltip : tooltip -> unit

(** Get all tooltips created in a subtree. *)
val tooltips_in : Brr.El.t -> tooltip list


(** {1 Highlighting} *)

(** Highlight an element (for click-to-navigate in the panel).

    Adds a temporary visual highlight and scrolls the element into view. *)
val highlight_element : Brr.El.t -> unit

(** Remove highlight from an element. *)
val unhighlight_element : Brr.El.t -> unit

(** Remove all highlights. *)
val clear_highlights : unit -> unit


(** {1 Data Attributes}

    Constants for the data attributes used by annotation. *)

module Data_attr : sig
  (** [data-html5rw-severity] - "error", "warning", or "info" *)
  val severity : Jstr.t

  (** [data-html5rw-message] - The warning message text *)
  val message : Jstr.t

  (** [data-html5rw-code] - The error code *)
  val code : Jstr.t

  (** [data-html5rw-count] - Number of warnings on this element *)
  val count : Jstr.t
end


(** {1 CSS Classes}

    Constants for the CSS classes used by annotation. *)

module Css_class : sig
  (** [html5rw-error] - Element has at least one error *)
  val error : Jstr.t

  (** [html5rw-warning] - Element has warnings but no errors *)
  val warning : Jstr.t

  (** [html5rw-info] - Element has only info messages *)
  val info : Jstr.t

  (** [html5rw-has-issues] - Element has any validation messages *)
  val has_issues : Jstr.t

  (** [html5rw-highlighted] - Element is currently highlighted *)
  val highlighted : Jstr.t

  (** [html5rw-tooltip] - The tooltip container element *)
  val tooltip : Jstr.t

  (** [html5rw-tooltip-visible] - Tooltip is currently visible *)
  val tooltip_visible : Jstr.t
end


(** {1 CSS Injection}

    Optionally inject default styles for annotations. *)

(** Inject default CSS styles for annotations and tooltips.

    Adds a [<style>] element to the document head with styles for:
    - Annotation classes (outlines, backgrounds)
    - Tooltip positioning and appearance
    - Highlight animation

    @param theme Light or dark theme. [`Auto] uses [prefers-color-scheme].
    @return The injected style element (can be removed later). *)
val inject_default_styles : theme:[ `Light | `Dark | `Auto ] -> Brr.El.t

(** Remove the injected style element. *)
val remove_injected_styles : Brr.El.t -> unit