(*--------------------------------------------------------------------------- Copyright (c) 2025 Anil Madhavapeddy . All rights reserved. SPDX-License-Identifier: MIT ---------------------------------------------------------------------------*) (** JavaScript API for HTML5 validation in the browser. This module provides the main entry points for validating HTML in a browser environment. It wraps the core {!Htmlrw_check} validator and adds browser-specific functionality for element mapping and annotation. {2 JavaScript Usage} After loading the compiled JavaScript, the API is available on [window]: {v // Validate an element (recommended) const result = html5rw.validateElement(document.body); console.log(result.errorCount, "errors found"); // Validate with annotation html5rw.validateAndAnnotate(document.body, { showTooltips: true, showPanel: true }); // Validate a raw HTML string const result = html5rw.validateString("

Hello

"); result.warnings.forEach(w => console.log(w.message)); v} {2 OCaml Usage} {[ let result = Htmlrw_js.validate_element (Brr.Document.body G.document) in List.iter (fun bm -> Brr.Console.log [Jstr.v bm.Htmlrw_js_types.message.text] ) result.messages ]} *) open Htmlrw_js_types (** {1 Validation} *) (** Validate an HTML string. This is the simplest form of validation. Since there's no source element, the returned messages will not have element references. {[ let result = validate_string "" in if Htmlrw_check.has_errors result.core_result then (* handle errors *) ]} *) val validate_string : string -> result (** Validate a DOM element's HTML. Serializes the element to HTML, validates it, and maps the results back to the live DOM elements. {[ let result = validate_element (Document.body G.document) in List.iter (fun bm -> match bm.element_ref with | Some { element = Some el; _ } -> El.set_class (Jstr.v "has-error") true el | _ -> () ) result.messages ]} *) val validate_element : Brr.El.t -> result (** {1 Validation with Annotation} These functions validate and immediately annotate the DOM with results. *) (** Validate and annotate an element. This combines validation with DOM annotation. The element and its descendants are annotated with data attributes, classes, and optionally tooltips based on the validation results. @param config Annotation configuration. Defaults to [Htmlrw_js_types.default_annotation_config]. *) val validate_and_annotate : ?config:annotation_config -> Brr.El.t -> result (** Validate, annotate, and show the warning panel. The all-in-one function for browser validation with full UI. @param annotation_config How to annotate elements. @param panel_config How to display the warning panel. *) val validate_and_show_panel : ?annotation_config:annotation_config -> ?panel_config:panel_config -> Brr.El.t -> result (** {1 Result Inspection} *) (** Get messages filtered by severity. *) val errors : result -> browser_message list val warnings_only : result -> browser_message list val infos : result -> browser_message list (** Check if there are any errors. *) val has_errors : result -> bool (** Check if there are any warnings or errors. *) val has_issues : result -> bool (** Get total count of all messages. *) val message_count : result -> int (** {1 JavaScript Export} These functions register the API on the JavaScript global object. *) (** Register the validation API on [window.html5rw]. Call this from your main entry point to expose the JavaScript API: {[ let () = Htmlrw_js.register_global_api () ]} This exposes: - [html5rw.validateString(html)] -> result object - [html5rw.validateElement(el)] -> result object - [html5rw.validateAndAnnotate(el, config?)] -> result object - [html5rw.validateAndShowPanel(el, config?)] -> result object - [html5rw.clearAnnotations(el)] -> void - [html5rw.hidePanel()] -> void *) val register_global_api : unit -> unit (** Register the API on a custom object instead of [window.html5rw]. Useful for module bundlers or when you want to control the namespace. *) val register_api_on : Jv.t -> unit (** {1 Low-level Access} *) (** Access the element map from a validation result. Useful for custom element lookup logic. Returns [None] if the result was from {!validate_string} (no source element). *) val element_map : result -> Htmlrw_js_dom.t option