ocaml-html5rw / lib / check / element / attr.mli

(*---------------------------------------------------------------------------
  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
  SPDX-License-Identifier: MIT
 ---------------------------------------------------------------------------*)

(** Typed HTML5 attribute representations using polymorphic variants.

    This module provides typed representations for HTML attributes with
    proper value types for enumerated attributes. Parsing raw attribute
    name-value pairs produces typed variants that can be pattern-matched
    with exhaustiveness checking.

    {2 Design Philosophy}

    HTML5 attributes have specific value constraints that this module
    encodes in the type system:

    - Boolean attributes: Present means true (e.g., [disabled], [checked])
    - Enumerated attributes: Fixed set of valid values (e.g., [dir], [method])
    - Numeric attributes: Integer or float values (e.g., [tabindex], [colspan])
    - URL attributes: String values representing URLs (e.g., [href], [src])
    - Free-form attributes: Any string value (e.g., [class], [title])

    {2 Parsing Strategy}

    Attributes are parsed with validation:
    - Known attributes are parsed into typed variants
    - Invalid values for enumerated attributes fall back to [Unknown_attr]
    - Unknown attribute names are captured as [Unknown_attr]
    - Special handling for [data-*] and [aria-*] prefixed attributes

    @see <https://html.spec.whatwg.org/multipage/dom.html#global-attributes>
         HTML Standard: Global attributes
*)

(** {1 Attribute Value Types}

    These types represent the valid values for enumerated HTML attributes. *)

(** Direction attribute values for [dir]. *)
type dir_value = [ `Ltr | `Rtl | `Auto ]

(** Hidden attribute values. *)
type hidden_value = [ `Hidden | `Until_found ]

(** Popover attribute values. *)
type popover_value = [ `Auto | `Manual | `Hint ]

(** Link target attribute values. *)
type target_value = [ `Self | `Blank | `Parent | `Top | `Named of string ]

(** Image/resource loading behavior. *)
type loading_value = [ `Eager | `Lazy ]

(** Image decoding hint. *)
type decoding_value = [ `Sync | `Async | `Auto ]

(** Fetch priority hint. *)
type fetchpriority_value = [ `High | `Low | `Auto ]

(** CORS settings. *)
type crossorigin_value = [ `Anonymous | `Use_credentials ]

(** Media preload hint. *)
type preload_value = [ `None | `Metadata | `Auto ]

(** Form method values. *)
type method_value = [ `Get | `Post | `Dialog ]

(** Form encoding type values. *)
type enctype_value = [ `Urlencoded | `Multipart | `Plain ]

(** Textarea wrap mode. *)
type wrap_value = [ `Soft | `Hard ]

(** Table cell scope. *)
type scope_value = [ `Row | `Col | `Rowgroup | `Colgroup ]

(** Input element type values. *)
type input_type = [
  | `Hidden | `Text | `Search | `Tel | `Url | `Email | `Password
  | `Date | `Month | `Week | `Time | `Datetime_local | `Number
  | `Range | `Color | `Checkbox | `Radio | `File | `Submit
  | `Image | `Reset | `Button
]

(** Button element type values. *)
type button_type = [ `Submit | `Reset | `Button ]

(** Referrer policy values. *)
type referrerpolicy_value = [
  | `No_referrer | `No_referrer_when_downgrade | `Origin
  | `Origin_when_cross_origin | `Same_origin | `Strict_origin
  | `Strict_origin_when_cross_origin | `Unsafe_url
]

(** Iframe sandbox flags. *)
type sandbox_flag = [
  | `Allow_downloads | `Allow_forms | `Allow_modals | `Allow_orientation_lock
  | `Allow_pointer_lock | `Allow_popups | `Allow_popups_to_escape_sandbox
  | `Allow_presentation | `Allow_same_origin | `Allow_scripts
  | `Allow_top_navigation | `Allow_top_navigation_by_user_activation
  | `Allow_top_navigation_to_custom_protocols
]

(** Enter key hint values for virtual keyboards. *)
type enterkeyhint_value = [
  | `Enter | `Done | `Go | `Next | `Previous | `Search | `Send
]

(** Input mode hint for virtual keyboards. *)
type inputmode_value = [
  | `None | `Text | `Decimal | `Numeric | `Tel | `Search | `Email | `Url
]

(** Content editable values. *)
type contenteditable_value = [ `True | `False | `Plaintext_only ]

(** Autocapitalize values. *)
type autocapitalize_value = [
  | `Off | `None | `On | `Sentences | `Words | `Characters
]

(** Image map shape values. *)
type shape_value = [ `Rect | `Circle | `Poly | `Default ]

(** Input capture values for file inputs. *)
type capture_value = [ `User | `Environment ]

(** Ordered list type values. *)
type list_type_value = [
  | `Decimal | `Lower_alpha | `Upper_alpha | `Lower_roman | `Upper_roman
]

(** Track element kind values. *)
type kind_value = [
  | `Subtitles | `Captions | `Descriptions | `Chapters | `Metadata
]

(** {1 Typed Attribute Variant} *)

(** Typed attribute representation.

    This type covers all HTML5 attributes with appropriate value types.
    Attributes are organized into logical groups. *)
type t = [
  (* Global attributes *)
  | `Id of string
  | `Class of string
  | `Style of string
  | `Title of string
  | `Lang of string
  | `Dir of dir_value
  | `Hidden of hidden_value option
  | `Tabindex of int
  | `Accesskey of string
  | `Autocapitalize of autocapitalize_value
  | `Autofocus
  | `Contenteditable of contenteditable_value option
  | `Draggable of bool
  | `Enterkeyhint of enterkeyhint_value
  | `Inert
  | `Inputmode of inputmode_value
  | `Is of string
  | `Nonce of string
  | `Popover of popover_value option
  | `Slot of string
  | `Spellcheck of bool option
  | `Translate of bool
  | `Exportparts of string
  | `Part of string

  (* Microdata *)
  | `Itemscope
  | `Itemtype of string
  | `Itemprop of string
  | `Itemid of string
  | `Itemref of string

  (* ARIA *)
  | `Role of string
  | `Aria of string * string

  (* Event handlers *)
  | `Event of string * string

  (* Link/navigation attributes *)
  | `Href of string
  | `Target of target_value
  | `Rel of string
  | `Download of string option
  | `Hreflang of string
  | `Ping of string
  | `Referrerpolicy of referrerpolicy_value
  | `Type_link of string

  (* Media/resource attributes *)
  | `Src of string
  | `Srcset of string
  | `Sizes of string
  | `Alt of string
  | `Width of string
  | `Height of string
  | `Loading of loading_value
  | `Decoding of decoding_value
  | `Fetchpriority of fetchpriority_value
  | `Crossorigin of crossorigin_value option
  | `Ismap
  | `Usemap of string
  | `Media of string

  (* Audio/Video specific *)
  | `Controls
  | `Autoplay
  | `Loop
  | `Muted
  | `Preload of preload_value
  | `Poster of string
  | `Playsinline

  (* Image map *)
  | `Coords of string
  | `Shape of shape_value

  (* iframe *)
  | `Sandbox of sandbox_flag list option
  | `Allow of string
  | `Allowfullscreen
  | `Srcdoc of string
  | `Csp of string

  (* Form attributes *)
  | `Action of string
  | `Method of method_value
  | `Enctype of enctype_value
  | `Novalidate
  | `Accept_charset of string
  | `Autocomplete of string
  | `Name of string
  | `Form of string

  (* Form control attributes *)
  | `Value of string
  | `Type_input of input_type
  | `Type_button of button_type
  | `Disabled
  | `Readonly
  | `Required
  | `Checked
  | `Selected
  | `Multiple
  | `Placeholder of string
  | `Min of string
  | `Max of string
  | `Step of string
  | `Minlength of int
  | `Maxlength of int
  | `Pattern of string
  | `Size of int
  | `Cols of int
  | `Rows of int
  | `Wrap of wrap_value
  | `Accept of string
  | `Capture of capture_value
  | `Dirname of string
  | `For of string
  | `List of string

  (* Form submission attributes *)
  | `Formaction of string
  | `Formmethod of method_value
  | `Formenctype of enctype_value
  | `Formnovalidate
  | `Formtarget of target_value

  (* Table attributes *)
  | `Colspan of int
  | `Rowspan of int
  | `Headers of string
  | `Scope of scope_value
  | `Span of int

  (* Details/Dialog *)
  | `Open

  (* Script *)
  | `Async
  | `Defer
  | `Integrity of string
  | `Nomodule
  | `Blocking of string
  | `Type_script of string

  (* Meta *)
  | `Charset of string
  | `Content of string
  | `Http_equiv of string

  (* Link element *)
  | `As of string
  | `Imagesizes of string
  | `Imagesrcset of string

  (* Object/Embed *)
  | `Data_object of string

  (* Output *)
  | `For_output of string

  (* Meter/Progress *)
  | `Low of float
  | `High of float
  | `Optimum of float

  (* Time *)
  | `Datetime of string

  (* Ol *)
  | `Start of int
  | `Reversed
  | `Type_list of list_type_value

  (* Track *)
  | `Kind of kind_value
  | `Srclang of string
  | `Default

  (* Td/Th *)
  | `Abbr of string

  (* Data attributes *)
  | `Data_attr of string * string

  (* RDFa *)
  | `Property of string
  | `Typeof of string
  | `Resource of string
  | `Prefix of string
  | `Vocab of string
  | `About of string
  | `Datatype of string
  | `Inlist
  | `Rev of string

  (* Escape hatch *)
  | `Unknown_attr of string * string
]

(** {1 Parsing Functions} *)

val parse_dir : string -> dir_value option
(** [parse_dir value] parses a direction attribute value. *)

val parse_target : string -> target_value
(** [parse_target value] parses a target attribute value. *)

val parse_loading : string -> loading_value option
(** [parse_loading value] parses a loading attribute value. *)

val parse_decoding : string -> decoding_value option
(** [parse_decoding value] parses a decoding attribute value. *)

val parse_fetchpriority : string -> fetchpriority_value option
(** [parse_fetchpriority value] parses a fetchpriority attribute value. *)

val parse_crossorigin : string -> crossorigin_value option
(** [parse_crossorigin value] parses a crossorigin attribute value. *)

val parse_preload : string -> preload_value option
(** [parse_preload value] parses a preload attribute value. *)

val parse_method : string -> method_value option
(** [parse_method value] parses a form method attribute value. *)

val parse_enctype : string -> enctype_value option
(** [parse_enctype value] parses a form enctype attribute value. *)

val parse_wrap : string -> wrap_value option
(** [parse_wrap value] parses a textarea wrap attribute value. *)

val parse_scope : string -> scope_value option
(** [parse_scope value] parses a table scope attribute value. *)

val parse_input_type : string -> input_type option
(** [parse_input_type value] parses an input type attribute value. *)

val parse_button_type : string -> button_type option
(** [parse_button_type value] parses a button type attribute value. *)

val parse_shape : string -> shape_value option
(** [parse_shape value] parses an area shape attribute value. *)

val parse_capture : string -> capture_value option
(** [parse_capture value] parses an input capture attribute value. *)

val parse_list_type : string -> list_type_value option
(** [parse_list_type value] parses an ordered list type attribute value. *)

val parse_kind : string -> kind_value option
(** [parse_kind value] parses a track kind attribute value. *)

val parse_referrerpolicy : string -> referrerpolicy_value option
(** [parse_referrerpolicy value] parses a referrer policy attribute value. *)

val parse_sandbox_flag : string -> sandbox_flag option
(** [parse_sandbox_flag value] parses a single sandbox flag token. *)

val parse_sandbox : string -> sandbox_flag list option
(** [parse_sandbox value] parses a space-separated sandbox attribute value. *)

val parse_enterkeyhint : string -> enterkeyhint_value option
(** [parse_enterkeyhint value] parses an enterkeyhint attribute value. *)

val parse_inputmode : string -> inputmode_value option
(** [parse_inputmode value] parses an inputmode attribute value. *)

val parse_contenteditable : string -> contenteditable_value option
(** [parse_contenteditable value] parses a contenteditable attribute value. *)

val parse_autocapitalize : string -> autocapitalize_value option
(** [parse_autocapitalize value] parses an autocapitalize attribute value. *)

val parse_hidden : string -> hidden_value option
(** [parse_hidden value] parses a hidden attribute value. *)

val parse_popover : string -> popover_value option
(** [parse_popover value] parses a popover attribute value. *)

val parse_int : string -> int option
(** [parse_int value] attempts to parse an integer from a string. *)

val parse_float : string -> float option
(** [parse_float value] attempts to parse a float from a string. *)

val parse_bool : string -> bool option
(** [parse_bool value] parses a boolean attribute value. *)

val parse_attr : string -> string -> t
(** [parse_attr name value] parses a single attribute name-value pair.

    @param name The attribute name
    @param value The attribute value
    @return A typed attribute variant

    {b Example:}
    {[
      parse_attr "class" "container"  (* `Class "container" *)
      parse_attr "disabled" ""        (* `Disabled *)
      parse_attr "data-id" "123"      (* `Data_attr ("id", "123") *)
    ]} *)

val parse_attrs : (string * string) list -> t list
(** [parse_attrs attrs] parses multiple attributes.

    @param attrs List of (name, value) pairs
    @return List of typed attributes *)

(** {1 Accessor Functions} *)

val get_id : t list -> string option
(** [get_id attrs] extracts the id attribute value if present. *)

val get_class : t list -> string option
(** [get_class attrs] extracts the class attribute value as a raw string. *)

val get_class_list : t list -> string list
(** [get_class_list attrs] extracts the class attribute as a list of class names.
    Returns empty list if not present. Space-separated values are split. *)

val get_href : t list -> string option
(** [get_href attrs] extracts the href attribute value if present. *)

val get_src : t list -> string option
(** [get_src attrs] extracts the src attribute value if present. *)

val get_alt : t list -> string option
(** [get_alt attrs] extracts the alt attribute value if present. *)

val get_name : t list -> string option
(** [get_name attrs] extracts the name attribute value if present. *)

val get_value : t list -> string option
(** [get_value attrs] extracts the value attribute value if present. *)

val get_role : t list -> string option
(** [get_role attrs] extracts the role attribute value if present. *)

val get_aria : string -> t list -> string option
(** [get_aria name attrs] extracts a specific aria-* attribute value.

    @param name The aria attribute name without the "aria-" prefix *)

val get_data : string -> t list -> string option
(** [get_data name attrs] extracts a specific data-* attribute value.

    @param name The data attribute name without the "data-" prefix *)

val has_disabled : t list -> bool
(** [has_disabled attrs] checks if the disabled attribute is present. *)

val has_required : t list -> bool
(** [has_required attrs] checks if the required attribute is present. *)

val has_readonly : t list -> bool
(** [has_readonly attrs] checks if the readonly attribute is present. *)

val has_checked : t list -> bool
(** [has_checked attrs] checks if the checked attribute is present. *)

val has_autofocus : t list -> bool
(** [has_autofocus attrs] checks if the autofocus attribute is present. *)

val has_hidden : t list -> bool
(** [has_hidden attrs] checks if the hidden attribute is present. *)

val has_inert : t list -> bool
(** [has_inert attrs] checks if the inert attribute is present. *)

val has_open : t list -> bool
(** [has_open attrs] checks if the open attribute is present. *)

val get_all_aria : t list -> (string * string) list
(** [get_all_aria attrs] extracts all aria-* attributes. *)

val get_all_data : t list -> (string * string) list
(** [get_all_data attrs] extracts all data-* attributes. *)

(** {2 Space-Separated Attribute List Getters} *)

val get_rel : t list -> string option
(** [get_rel attrs] extracts the rel attribute value as a raw string. *)

val get_rel_list : t list -> string list
(** [get_rel_list attrs] extracts the rel attribute as a list of link types.
    Returns empty list if not present. Space-separated values are split. *)

val get_headers : t list -> string option
(** [get_headers attrs] extracts the headers attribute value as a raw string. *)

val get_headers_list : t list -> string list
(** [get_headers_list attrs] extracts the headers attribute as a list of IDs.
    Returns empty list if not present. Space-separated values are split. *)

val get_itemref : t list -> string option
(** [get_itemref attrs] extracts the itemref attribute value as a raw string. *)

val get_itemref_list : t list -> string list
(** [get_itemref_list attrs] extracts the itemref attribute as a list of IDs.
    Returns empty list if not present. Space-separated values are split. *)

val get_itemprop : t list -> string option
(** [get_itemprop attrs] extracts the itemprop attribute value as a raw string. *)

val get_itemprop_list : t list -> string list
(** [get_itemprop_list attrs] extracts the itemprop attribute as a list of property names.
    Returns empty list if not present. Space-separated values are split. *)

val get_itemtype : t list -> string option
(** [get_itemtype attrs] extracts the itemtype attribute value as a raw string. *)

val get_itemtype_list : t list -> string list
(** [get_itemtype_list attrs] extracts the itemtype attribute as a list of URLs.
    Returns empty list if not present. Space-separated values are split. *)

val get_aria_list : string -> t list -> string list
(** [get_aria_list name attrs] extracts a specific aria-* attribute as a list.
    Useful for space-separated aria values like aria-labelledby, aria-describedby.
    Returns empty list if not present. *)

val find : (t -> 'a option) -> t list -> 'a option
(** [find f attrs] finds the first attribute matching predicate [f]. *)

val exists : (t -> bool) -> t list -> bool
(** [exists f attrs] checks if any attribute matches predicate [f]. *)

val filter : (t -> bool) -> t list -> t list
(** [filter f attrs] filters attributes matching predicate [f]. *)