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(** DOM annotation for validation warnings.
7
8 This module applies validation results to the live DOM by adding
9 data attributes, CSS classes, and tooltip overlays to elements
10 that have warnings. *)
11
12open Htmlrw_js_types
13
14
15(** {1 Annotation} *)
16
17(** Annotate elements in a subtree based on validation results.
18
19 For each message with an element reference, this function:
20 1. Adds data attributes ([data-html5rw-severity], etc.) if configured
21 2. Adds CSS classes ([html5rw-error], etc.) if configured
22 3. Creates tooltip elements if configured
23
24 @param config Annotation configuration.
25 @param root The root element to annotate within.
26 @param messages The validation messages with element references. *)
27val annotate :
28 config:annotation_config ->
29 root:Brr.El.t ->
30 browser_message list ->
31 unit
32
33(** Annotate a single element with a message.
34
35 Lower-level function for custom annotation logic. *)
36val annotate_element :
37 config:annotation_config ->
38 Brr.El.t ->
39 Htmlrw_check.message ->
40 unit
41
42
43(** {1 Clearing Annotations} *)
44
45(** Remove all annotations from a subtree.
46
47 This removes:
48 - All [data-html5rw-*] attributes
49 - All [html5rw-*] CSS classes
50 - All tooltip elements created by this module *)
51val clear : Brr.El.t -> unit
52
53(** Remove annotations from a single element (not descendants). *)
54val clear_element : Brr.El.t -> unit
55
56
57(** {1 Tooltips} *)
58
59(** Tooltip state for an element. *)
60type tooltip
61
62(** Create a tooltip for an element.
63
64 The tooltip is not immediately visible; it appears on hover
65 if CSS is set up correctly, or can be shown programmatically.
66
67 @param position Where to position the tooltip.
68 @param el The element to attach the tooltip to.
69 @param messages All messages for this element (may be multiple). *)
70val create_tooltip :
71 position:[ `Above | `Below | `Auto ] ->
72 Brr.El.t ->
73 Htmlrw_check.message list ->
74 tooltip
75
76(** Show a tooltip immediately. *)
77val show_tooltip : tooltip -> unit
78
79(** Hide a tooltip. *)
80val hide_tooltip : tooltip -> unit
81
82(** Remove a tooltip from the DOM. *)
83val remove_tooltip : tooltip -> unit
84
85(** Get all tooltips created in a subtree. *)
86val tooltips_in : Brr.El.t -> tooltip list
87
88
89(** {1 Highlighting} *)
90
91(** Highlight an element (for click-to-navigate in the panel).
92
93 Adds a temporary visual highlight and scrolls the element into view. *)
94val highlight_element : Brr.El.t -> unit
95
96(** Remove highlight from an element. *)
97val unhighlight_element : Brr.El.t -> unit
98
99(** Remove all highlights. *)
100val clear_highlights : unit -> unit
101
102
103(** {1 Data Attributes}
104
105 Constants for the data attributes used by annotation. *)
106
107module Data_attr : sig
108 (** [data-html5rw-severity] - "error", "warning", or "info" *)
109 val severity : Jstr.t
110
111 (** [data-html5rw-message] - The warning message text *)
112 val message : Jstr.t
113
114 (** [data-html5rw-code] - The error code *)
115 val code : Jstr.t
116
117 (** [data-html5rw-count] - Number of warnings on this element *)
118 val count : Jstr.t
119end
120
121
122(** {1 CSS Classes}
123
124 Constants for the CSS classes used by annotation. *)
125
126module Css_class : sig
127 (** [html5rw-error] - Element has at least one error *)
128 val error : Jstr.t
129
130 (** [html5rw-warning] - Element has warnings but no errors *)
131 val warning : Jstr.t
132
133 (** [html5rw-info] - Element has only info messages *)
134 val info : Jstr.t
135
136 (** [html5rw-has-issues] - Element has any validation messages *)
137 val has_issues : Jstr.t
138
139 (** [html5rw-highlighted] - Element is currently highlighted *)
140 val highlighted : Jstr.t
141
142 (** [html5rw-tooltip] - The tooltip container element *)
143 val tooltip : Jstr.t
144
145 (** [html5rw-tooltip-visible] - Tooltip is currently visible *)
146 val tooltip_visible : Jstr.t
147end
148
149
150(** {1 CSS Injection}
151
152 Optionally inject default styles for annotations. *)
153
154(** Inject default CSS styles for annotations and tooltips.
155
156 Adds a [<style>] element to the document head with styles for:
157 - Annotation classes (outlines, backgrounds)
158 - Tooltip positioning and appearance
159 - Highlight animation
160
161 @param theme Light or dark theme. [`Auto] uses [prefers-color-scheme].
162 @return The injected style element (can be removed later). *)
163val inject_default_styles : theme:[ `Light | `Dark | `Auto ] -> Brr.El.t
164
165(** Remove the injected style element. *)
166val remove_injected_styles : Brr.El.t -> unit