OCaml HTML5 parser/serialiser based on Python's JustHTML
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: MIT
4 ---------------------------------------------------------------------------*)
5
6(** Floating warning panel UI.
7
8 This module creates and manages a draggable, floating panel that displays
9 validation warnings. The panel supports:
10 - Grouping by severity (errors first)
11 - Click-to-navigate to problematic elements
12 - Collapse/expand functionality
13 - Light/dark themes *)
14
15open Htmlrw_js_types
16
17
18(** {1 Panel Management} *)
19
20(** The warning panel. *)
21type t
22
23(** Create and display a warning panel.
24
25 The panel is appended to [document.body] and positioned according
26 to the configuration.
27
28 @param config Panel configuration.
29 @param result Validation result to display. *)
30val create : config:panel_config -> result -> t
31
32(** Update the panel with new validation results.
33
34 Use this to re-validate and refresh the panel without destroying it. *)
35val update : t -> result -> unit
36
37(** Show the panel if hidden. *)
38val show : t -> unit
39
40(** Hide the panel (but keep it in the DOM). *)
41val hide : t -> unit
42
43(** Remove the panel from the DOM entirely. *)
44val destroy : t -> unit
45
46(** Check if the panel is currently visible. *)
47val is_visible : t -> bool
48
49(** Check if the panel is currently collapsed. *)
50val is_collapsed : t -> bool
51
52
53(** {1 Panel State} *)
54
55(** Collapse the panel to just show the summary badge. *)
56val collapse : t -> unit
57
58(** Expand the panel to show the full warning list. *)
59val expand : t -> unit
60
61(** Toggle collapsed state. *)
62val toggle_collapsed : t -> unit
63
64(** Get the current position of the panel. *)
65val position : t -> int * int
66
67(** Move the panel to a new position. *)
68val set_position : t -> int -> int -> unit
69
70
71(** {1 Interaction} *)
72
73(** Scroll to and highlight an element from a warning row.
74
75 This is called internally when clicking a warning, but can be
76 invoked programmatically. *)
77val navigate_to_element : t -> browser_message -> unit
78
79(** Get the currently highlighted element, if any. *)
80val highlighted_element : t -> Brr.El.t option
81
82(** Clear the current highlight. *)
83val clear_highlight : t -> unit
84
85
86(** {1 Event Callbacks}
87
88 Register callbacks for panel events. *)
89
90(** Called when a warning row is clicked. *)
91val on_warning_click : t -> (browser_message -> unit) -> unit
92
93(** Called when the panel is collapsed or expanded. *)
94val on_collapse_toggle : t -> (bool -> unit) -> unit
95
96(** Called when the panel is closed. *)
97val on_close : t -> (unit -> unit) -> unit
98
99(** Called when the panel is dragged to a new position. *)
100val on_move : t -> (int * int -> unit) -> unit
101
102
103(** {1 Global Panel State}
104
105 For convenience, there's a single "current" panel that the
106 JavaScript API manages. *)
107
108(** Get the current panel, if one exists. *)
109val current : unit -> t option
110
111(** Hide and destroy the current panel. *)
112val hide_current : unit -> unit
113
114
115(** {1 Panel Elements}
116
117 Access to the panel's DOM structure for custom styling. *)
118
119(** The root panel element. *)
120val root_element : t -> Brr.El.t
121
122(** The header element (contains title and controls). *)
123val header_element : t -> Brr.El.t
124
125(** The content element (contains warning list). *)
126val content_element : t -> Brr.El.t
127
128(** The summary badge element (shown when collapsed). *)
129val badge_element : t -> Brr.El.t
130
131
132(** {1 CSS Classes}
133
134 Classes used by the panel for custom styling. *)
135
136module Css_class : sig
137 val panel : Jstr.t
138 val panel_header : Jstr.t
139 val panel_content : Jstr.t
140 val panel_collapsed : Jstr.t
141 val panel_dragging : Jstr.t
142 val warning_list : Jstr.t
143 val warning_row : Jstr.t
144 val warning_row_error : Jstr.t
145 val warning_row_warning : Jstr.t
146 val warning_row_info : Jstr.t
147 val severity_badge : Jstr.t
148 val message_text : Jstr.t
149 val selector_path : Jstr.t
150 val collapse_btn : Jstr.t
151 val close_btn : Jstr.t
152 val summary_badge : Jstr.t
153 val error_count : Jstr.t
154 val warning_count : Jstr.t
155 val theme_light : Jstr.t
156 val theme_dark : Jstr.t
157end
158
159
160(** {1 CSS Injection} *)
161
162(** Inject default CSS styles for the panel.
163
164 Styles include layout, colors, shadows, and animations.
165 The styles are scoped to the panel's CSS classes.
166
167 @param theme Color scheme to use.
168 @return The injected style element. *)
169val inject_default_styles : theme:[ `Light | `Dark | `Auto ] -> Brr.El.t