Source file layout.ml

(** Layout utilities for basic display, positioning, and object properties *)

module Css = Cascade.Css

(** Screen reader utilities handler - priority 0 to appear first *)
module Screen_reader_handler = struct
  open Style
  open Css

  type t = Sr_only | Not_sr_only

  let name = "screen_reader"
  let priority _ = 0

  let suborder = function
    (* Negative suborders to appear before absolute (suborder 0) *)
    | Sr_only -> -2
    | Not_sr_only -> -1

  let to_class = function Sr_only -> "sr-only" | Not_sr_only -> "not-sr-only"

  let to_style _theme = function
    | Sr_only ->
        (* Property order matches Tailwind: position, width, height, padding,
           margin, overflow, clip-path, white-space, border-width *)
        style
          [
            Css.position Absolute;
            width (Px 1.);
            height (Px 1.);
            padding [ Zero ];
            margin [ Px (-1.) ];
            overflow Hidden;
            clip_path
              (Css.Clip_path_inset
                 {
                   top = Pct 50.;
                   right = None;
                   bottom = None;
                   left = None;
                   rounded = None;
                 });
            white_space Nowrap;
            border_width Zero;
          ]
    | Not_sr_only ->
        (* Property order matches Tailwind: position, width, height, padding,
           margin, overflow, clip-path, white-space *)
        style
          [
            Css.position Static;
            width Auto;
            height Auto;
            padding [ Zero ];
            margin [ Zero ];
            overflow Visible;
            clip_path Css.Clip_path_none;
            white_space Normal;
          ]

  let of_class _theme class_name =
    let parts = Parse.split_class class_name in
    match parts with
    | [ "sr"; "only" ] -> Ok Sr_only
    | [ "not"; "sr"; "only" ] -> Ok Not_sr_only
    | _ -> Error (`Msg "Not a screen reader utility")

  let examples = []
end

(* Theme variable for z-index-auto. When the threaded theme overrides this token
   (e.g. an [@theme] block sets [--z-index-auto: 42]), produces a custom
   declaration --z-index-auto: 42 in the :root, :host block. *)
let z_index_auto_var = Var.theme Css.Z_index "z-index-auto" ~order:(4, 750)

(* Generate z-auto style: either theme var with custom declaration, or bare
   theme_ref fallback *)
let z_auto_style ?theme () =
  match Scheme.theme_value theme "z-index-auto" with
  | Some value_str ->
      (* Parse theme value as z_index *)
      let z_value : Css.z_index =
        match value_str with
        | "auto" -> Auto
        | s -> Css.Properties.read_z_index (Cascade.Cursor.of_string s)
      in
      let decl, ref = Var.binding z_index_auto_var z_value in
      Style.style [ decl; Css.z_index (Var ref) ]
  (* Without a theme override Tailwind writes the keyword, not a reference to a
     token nothing declares. *)
  | None -> Style.style [ Css.z_index Auto ]

(* An [object-[...]] value that is not a var() reference is a <position>, read
   with cascade's grammar for it rather than a local one. Splitting on the space
   and reading each side as a length took the two-length and one-length forms
   and nothing else, so every keyword the grammar allows was refused. The
   [bg-position-] bracket reads the same CSS type through the same reader; the
   two families must not disagree about what a position is. *)
let parse_object_position raw : Css.position_value option =
  let cursor = Cascade.Cursor.of_string (Parse.decode_arbitrary_value raw) in
  match
    Cascade.Cursor.try_parse_full_err Css.Properties.read_position_value cursor
  with
  | Ok pos -> Some pos
  | Error _ -> None

module Handler = struct
  open Style
  open Css

  type t =
    | (* Display *)
      Block
    | Inline
    | Inline_block
    | Inline_table
    | Table
    | Table_caption
    | Table_cell
    | Table_column
    | Table_column_group
    | Table_footer_group
    | Table_header_group
    | Table_row
    | Table_row_group
    | List_item
    | Flow_root
    | Contents
    | Hidden
    | (* Visibility *)
      Visible
    | Invisible
    | Collapse
    | (* Isolation *)
      Isolate
    | Isolation_auto
    | (* Z-index *)
      Z_0
    | Z_10
    | Z_20
    | Z_30
    | Z_40
    | Z_50
    | Z_auto
    | Z of int (* Dynamic z-index: z-5, z-100, etc. *)
    | Neg_z of int (* Negative z-index: -z-10, -z-50, etc. *)
    (* Arbitrary values (z-[123]). The author's bracket text travels with what
       it denotes, so the class name is spelled exactly as it was written. The
       bracket carries either a value the z-index grammar reads or, when it does
       not, that text verbatim: Tailwind hands a bracket to the declaration
       unvalidated. *)
    | Z_arbitrary of string * [ `Index of Css.z_index | `Raw of string ]
    | Neg_z_arbitrary of
        string * Css.z_index (* Negative arbitrary: -z-[var(--value)] *)
    | (* Object fit *)
      Object_contain
    | Object_cover
    | Object_fill
    | Object_none
    | Object_scale_down
    | (* Object position *)
      Object_center
    | Object_top
    | Object_bottom
    | Object_left
    | Object_right
    | Object_bottom_left
    | Object_bottom_right
    | Object_left_bottom
    | Object_left_top
    | Object_right_bottom
    | Object_right_top
    | Object_top_left
    | Object_top_right
    | Object_arbitrary of string
    | Object_raw of string * string
      (* object-[foo]: the family writes one longhand, so a bracket no reader
         took still names it and the value is forwarded verbatim. *)
    | (* Float *)
      Float_left
    | Float_right
    | Float_none
    | Float_start
    | Float_end
    | (* Clear *)
      Clear_left
    | Clear_right
    | Clear_none
    | Clear_both
    | Clear_start
    | Clear_end
    | (* Box decoration break *)
      Box_decoration_clone
    | Box_decoration_slice
    | Decoration_clone (* legacy alias, keeps its class name *)
    | Decoration_slice
    | (* Break before/after/inside - page/column breaks *)
      Break_before_all
    | Break_before_auto
    | Break_before_avoid
    | Break_before_avoid_page
    | Break_before_column
    | Break_before_left
    | Break_before_page
    | Break_before_right
    | Break_after_all
    | Break_after_auto
    | Break_after_avoid
    | Break_after_avoid_page
    | Break_after_column
    | Break_after_left
    | Break_after_page
    | Break_after_right
    | Break_inside_auto
    | Break_inside_avoid
    | Break_inside_avoid_column
    | Break_inside_avoid_page

  let name = "layout"

  (* Most layout utilities are the display family (priority 4). Visibility,
     z-index, break controls, box decoration, and object controls occupy their
     own property bands. *)
  let priority = function
    | Collapse | Invisible | Visible -> 0
    | Neg_z _ | Z_0 | Z _ | Z_10 | Z_20 | Z_30 | Z_40 | Z_50 | Neg_z_arbitrary _
    | Z_arbitrary _ | Z_auto ->
        0
    (* isolation (rank 11) sits between inset and z-index. *)
    | Isolate | Isolation_auto -> 0
    (* float and clear (ranks 21-22) sit between the grid-column/grid-row group
       and .container, both at priority 1. *)
    | Float_end | Float_left | Float_none | Float_right | Float_start
    | Clear_both | Clear_end | Clear_left | Clear_none | Clear_right
    | Clear_start ->
        1
    (* object-fit / object-position (rank ~72): after svg fill/stroke, which
       shares this priority, and before padding (23). *)
    | Object_contain | Object_cover | Object_fill | Object_none
    | Object_scale_down | Object_center | Object_top | Object_bottom
    | Object_left | Object_right | Object_bottom_left | Object_bottom_right
    | Object_left_bottom | Object_left_top | Object_right_bottom
    | Object_right_top | Object_top_left | Object_top_right | Object_arbitrary _
    | Object_raw _ ->
        22
    | Break_before_all | Break_before_auto | Break_before_avoid
    | Break_before_avoid_page | Break_before_column | Break_before_left
    | Break_before_page | Break_before_right | Break_inside_auto
    | Break_inside_avoid | Break_inside_avoid_column | Break_inside_avoid_page
    | Break_after_all | Break_after_auto | Break_after_avoid
    | Break_after_avoid_page | Break_after_column | Break_after_left
    | Break_after_page | Break_after_right ->
        14
    | Box_decoration_clone | Box_decoration_slice | Decoration_clone
    | Decoration_slice ->
        21
    | _ -> 4

  let suborder = function
    (* Display utilities - ordered alphabetically per Tailwind. Gaps left for
       flex(3), grid(5), inline-flex(9), inline-grid(10) which live in flex.ml
       and grid.ml with the same priority. *)
    | Block -> 1
    | Contents -> 2
    (* flex = 3, in flex.ml *)
    | Flow_root -> 4
    (* grid = 5, in grid.ml *)
    | Hidden -> 6
    | Inline -> 7
    | Inline_block -> 8
    (* inline-flex = 9, in flex.ml *)
    (* inline-grid = 10, in grid.ml *)
    | Inline_table -> 11
    | List_item -> 12
    | Table -> 13
    | Table_caption -> 15
    | Table_cell -> 16
    | Table_column -> 17
    | Table_column_group -> 18
    | Table_footer_group -> 20
    | Table_header_group -> 21
    | Table_row -> 22
    | Table_row_group -> 23
    (* Visibility (priority 0) - first in Tailwind's order, before sr-only
       (suborder -2). Alphabetical: collapse, invisible, visible. *)
    | Collapse -> -20
    | Invisible -> -19
    | Visible -> -18
    (* Isolation (priority 0) - after inset (up to ~13M in position.ml), before
       z-index (20M). Order: isolate, isolation-auto *)
    | Isolate -> 15_000_000
    | Isolation_auto -> 15_000_001
    (* Z-index (priority 0) - after inset (up to ~13M in position.ml), before
       container (priority 1). Order: negative, positive, arbitrary, auto. *)
    | Neg_z n -> 20_000_000 + 500 + n (* -z-50, -z-10 *)
    | Z_0 -> 20_000_000 + 600
    | Z n -> 20_000_000 + 601 + n (* z-10 *)
    | Z_10 -> 20_000_000 + 611
    | Z_20 -> 20_000_000 + 621
    | Z_30 -> 20_000_000 + 631
    | Z_40 -> 20_000_000 + 641
    | Z_50 -> 20_000_000 + 651
    | Neg_z_arbitrary _ -> 20_000_000 + 560
    | Z_arbitrary _ -> 20_000_000 + 700
    | Z_auto -> 20_000_000 + 750
    (* Object fit, after every fill and stroke: svg.ml shares this priority and
       Tailwind emits it first of the two, so the whole family starts past what
       that handler assigns. *)
    | Object_contain -> Svg.suborder_ceiling + 600
    | Object_cover -> Svg.suborder_ceiling + 601
    | Object_fill -> Svg.suborder_ceiling + 602
    | Object_none -> Svg.suborder_ceiling + 603
    | Object_scale_down -> Svg.suborder_ceiling + 604
    (* Object position - alphabetical: bottom, bottom-left, ..., top-right *)
    | Object_bottom -> Svg.suborder_ceiling + 700
    | Object_bottom_left -> Svg.suborder_ceiling + 701
    | Object_bottom_right -> Svg.suborder_ceiling + 702
    | Object_center -> Svg.suborder_ceiling + 703
    | Object_left -> Svg.suborder_ceiling + 704
    | Object_left_bottom -> Svg.suborder_ceiling + 705
    | Object_left_top -> Svg.suborder_ceiling + 706
    | Object_right -> Svg.suborder_ceiling + 707
    | Object_right_bottom -> Svg.suborder_ceiling + 708
    | Object_right_top -> Svg.suborder_ceiling + 709
    | Object_top -> Svg.suborder_ceiling + 710
    | Object_top_left -> Svg.suborder_ceiling + 711
    | Object_top_right -> Svg.suborder_ceiling + 712
    | Object_arbitrary _ | Object_raw _ -> Svg.suborder_ceiling + 650
    (* Float (priority 1) - after the grid-column/grid-row group (up to ~2.6K in
       grid_item.ml), before .container (9M). Alphabetical: end, left, none,
       right, start *)
    | Float_end -> 3_000_000
    | Float_left -> 3_000_001
    | Float_none -> 3_000_002
    | Float_right -> 3_000_003
    | Float_start -> 3_000_004
    (* Clear (priority 1) - right after float. Alphabetical: both, end, left,
       none, right, start *)
    | Clear_both -> 3_000_100
    | Clear_end -> 3_000_101
    | Clear_left -> 3_000_102
    | Clear_none -> 3_000_103
    | Clear_right -> 3_000_104
    | Clear_start -> 3_000_105
    (* Box decoration break (priority 21) sits after mask-image and its gradient
       variables, before background-size. *)
    | Box_decoration_clone -> Utility.Property_order.last 250
    | Box_decoration_slice -> Utility.Property_order.last 250
    | Decoration_clone -> Utility.Property_order.last 250
    | Decoration_slice -> Utility.Property_order.last 250
    (* Break before - alphabetical order (Tailwind: break-before < break-inside
       < break-after) *)
    | Break_before_all -> 1100
    | Break_before_auto -> 1101
    | Break_before_avoid -> 1102
    | Break_before_avoid_page -> 1103
    | Break_before_column -> 1104
    | Break_before_left -> 1105
    | Break_before_page -> 1106
    | Break_before_right -> 1107
    (* Break inside - alphabetical order *)
    | Break_inside_auto -> 1200
    | Break_inside_avoid -> 1201
    | Break_inside_avoid_column -> 1202
    | Break_inside_avoid_page -> 1203
    (* Break after - alphabetical order *)
    | Break_after_all -> 1300
    | Break_after_auto -> 1301
    | Break_after_avoid -> 1302
    | Break_after_avoid_page -> 1303
    | Break_after_column -> 1304
    | Break_after_left -> 1305
    | Break_after_page -> 1306
    | Break_after_right -> 1307

  (** {1 Style Generation} *)

  let to_class = function
    | Block -> "block"
    | Inline -> "inline"
    | Inline_block -> "inline-block"
    | Inline_table -> "inline-table"
    | Table -> "table"
    | Table_caption -> "table-caption"
    | Table_cell -> "table-cell"
    | Table_column -> "table-column"
    | Table_column_group -> "table-column-group"
    | Table_footer_group -> "table-footer-group"
    | Table_header_group -> "table-header-group"
    | Table_row -> "table-row"
    | Table_row_group -> "table-row-group"
    | List_item -> "list-item"
    | Flow_root -> "flow-root"
    | Contents -> "contents"
    | Hidden -> "hidden"
    | Visible -> "visible"
    | Invisible -> "invisible"
    | Collapse -> "collapse"
    | Isolate -> "isolate"
    | Isolation_auto -> "isolation-auto"
    | Z_0 -> "z-0"
    | Z n -> "z-" ^ string_of_int n
    | Z_10 -> "z-10"
    | Z_20 -> "z-20"
    | Z_30 -> "z-30"
    | Z_40 -> "z-40"
    | Z_50 -> "z-50"
    | Z_auto -> "z-auto"
    | Neg_z n -> "-z-" ^ string_of_int n
    | Z_arbitrary (s, _) -> "z-[" ^ s ^ "]"
    | Neg_z_arbitrary (s, _) -> "-z-[" ^ s ^ "]"
    | Object_contain -> "object-contain"
    | Object_cover -> "object-cover"
    | Object_fill -> "object-fill"
    | Object_none -> "object-none"
    | Object_scale_down -> "object-scale-down"
    | Object_center -> "object-center"
    | Object_top -> "object-top"
    | Object_bottom -> "object-bottom"
    | Object_left -> "object-left"
    | Object_right -> "object-right"
    | Object_bottom_left -> "object-bottom-left"
    | Object_bottom_right -> "object-bottom-right"
    | Object_left_bottom -> "object-left-bottom"
    | Object_left_top -> "object-left-top"
    | Object_right_bottom -> "object-right-bottom"
    | Object_right_top -> "object-right-top"
    | Object_top_left -> "object-top-left"
    | Object_top_right -> "object-top-right"
    | Object_arbitrary s | Object_raw (s, _) -> "object-[" ^ s ^ "]"
    | Float_left -> "float-left"
    | Float_right -> "float-right"
    | Float_none -> "float-none"
    | Float_start -> "float-start"
    | Float_end -> "float-end"
    | Clear_left -> "clear-left"
    | Clear_right -> "clear-right"
    | Clear_none -> "clear-none"
    | Clear_both -> "clear-both"
    | Clear_start -> "clear-start"
    | Clear_end -> "clear-end"
    | Box_decoration_clone -> "box-decoration-clone"
    | Box_decoration_slice -> "box-decoration-slice"
    | Decoration_clone -> "decoration-clone"
    | Decoration_slice -> "decoration-slice"
    | Break_before_all -> "break-before-all"
    | Break_before_auto -> "break-before-auto"
    | Break_before_avoid -> "break-before-avoid"
    | Break_before_avoid_page -> "break-before-avoid-page"
    | Break_before_column -> "break-before-column"
    | Break_before_left -> "break-before-left"
    | Break_before_page -> "break-before-page"
    | Break_before_right -> "break-before-right"
    | Break_after_all -> "break-after-all"
    | Break_after_auto -> "break-after-auto"
    | Break_after_avoid -> "break-after-avoid"
    | Break_after_avoid_page -> "break-after-avoid-page"
    | Break_after_column -> "break-after-column"
    | Break_after_left -> "break-after-left"
    | Break_after_page -> "break-after-page"
    | Break_after_right -> "break-after-right"
    | Break_inside_auto -> "break-inside-auto"
    | Break_inside_avoid -> "break-inside-avoid"
    | Break_inside_avoid_column -> "break-inside-avoid-column"
    | Break_inside_avoid_page -> "break-inside-avoid-page"

  (* An [object-<position>] class reads its keyword off
     [--object-position-<pos>] when the theme binds one. The token name and the
     keyword travel together with the constructor that names them, so there is
     no second list of positions to keep in step with the first. *)
  let object_position_style theme pos (default : Css.position_value) =
    let name = "object-position-" ^ pos in
    match Scheme.theme_value (Some theme) name with
    | Some value ->
        let theme_decl =
          Css.custom_property ~layer:"theme" ("--" ^ name) value
        in
        let pos_ref : Css.position_value Css.var = Var.bracket name in
        style [ theme_decl; object_position (Var pos_ref) ]
    (* Without a theme override Tailwind writes the keyword, not a reference to
       a token nothing declares. *)
    | None -> style [ object_position default ]

  let to_style theme =
    let z_auto_style () = z_auto_style ~theme () in
    function
    | Block -> style [ display Block ]
    | Inline -> style [ display Inline ]
    | Inline_block -> style [ display Inline_block ]
    | Inline_table -> style [ display Inline_table ]
    | Table -> style [ display Table ]
    | Table_caption -> style [ display Table_caption ]
    | Table_cell -> style [ display Table_cell ]
    | Table_column -> style [ display Table_column ]
    | Table_column_group -> style [ display Table_column_group ]
    | Table_footer_group -> style [ display Table_footer_group ]
    | Table_header_group -> style [ display Table_header_group ]
    | Table_row -> style [ display Table_row ]
    | Table_row_group -> style [ display Table_row_group ]
    | List_item -> style [ display List_item ]
    | Flow_root -> style [ display Flow_root ]
    | Contents -> style [ display Contents ]
    | Hidden -> style [ display None ]
    | Visible -> style [ visibility Visible ]
    | Invisible -> style [ visibility Hidden ]
    | Collapse -> style [ visibility Collapse ]
    | Isolate -> style [ isolation Isolate ]
    | Isolation_auto -> style [ isolation Auto ]
    | Z_0 -> style [ z_index (Index 0) ]
    | Z n -> style [ z_index (Index n) ]
    | Z_10 -> style [ z_index (Index 10) ]
    | Z_20 -> style [ z_index (Index 20) ]
    | Z_30 -> style [ z_index (Index 30) ]
    | Z_40 -> style [ z_index (Index 40) ]
    | Z_50 -> style [ z_index (Index 50) ]
    | Z_auto -> z_auto_style ()
    | Neg_z n -> style [ z_index (Index (-n)) ]
    | Z_arbitrary (_, `Index zi) -> style [ z_index zi ]
    | Z_arbitrary (_, `Raw v) -> (
        match Parse.opaque_declaration "z-index" v with
        | Some declaration -> style [ declaration ]
        | None -> style [])
    | Neg_z_arbitrary (_, zi) ->
        style [ z_index (Calc (Css.Calc.mul (Val zi) (Css.Calc.float (-1.)))) ]
    | Object_contain -> style [ object_fit Contain ]
    | Object_cover -> style [ object_fit Cover ]
    | Object_fill -> style [ object_fit Fill ]
    | Object_none -> style [ object_fit None ]
    | Object_scale_down -> style [ object_fit Scale_down ]
    | Object_center -> object_position_style theme "center" Center
    | Object_top -> object_position_style theme "top" Top
    | Object_bottom -> object_position_style theme "bottom" Bottom
    | Object_left -> object_position_style theme "left" Left
    | Object_right -> object_position_style theme "right" Right
    | Object_bottom_left ->
        object_position_style theme "bottom-left" Bottom_left
    | Object_bottom_right ->
        object_position_style theme "bottom-right" Bottom_right
    | Object_left_bottom ->
        object_position_style theme "left-bottom" Left_bottom
    | Object_left_top -> object_position_style theme "left-top" Left_top
    | Object_right_bottom ->
        object_position_style theme "right-bottom" Right_bottom
    | Object_right_top -> object_position_style theme "right-top" Right_top
    | Object_top_left -> object_position_style theme "top-left" Top_left
    | Object_top_right -> object_position_style theme "top-right" Top_right
    | Object_raw (_, v) ->
        style (Option.to_list (Parse.opaque_declaration "object-position" v))
    | Object_arbitrary bracket -> (
        (* Only a var() reference names a variable; anything else is a position
           value, which [object-[50%]] used to turn into [var(--50)]. [of_class]
           refused an empty hint, so the peel succeeds here. *)
        let raw =
          Option.value (Parse.value_after_hint bracket) ~default:bracket
        in
        match parse_object_position raw with
        | Some pos -> style [ object_position pos ]
        | None ->
            let bare_name = Parse.extract_var_name raw in
            let pos_ref : Css.position_value Css.var = Var.bracket bare_name in
            style [ object_position (Var pos_ref) ])
    | Float_left -> style [ Css.float Left ]
    | Float_right -> style [ Css.float Right ]
    | Float_none -> style [ Css.float None ]
    | Float_start -> style [ Css.float Inline_start ]
    | Float_end -> style [ Css.float Inline_end ]
    | Clear_left -> style [ Css.clear Left ]
    | Clear_right -> style [ Css.clear Right ]
    | Clear_none -> style [ Css.clear None ]
    | Clear_both -> style [ Css.clear Both ]
    | Clear_start -> style [ Css.clear Inline_start ]
    | Clear_end -> style [ Css.clear Inline_end ]
    | Box_decoration_clone ->
        style
          [
            Css.webkit_box_decoration_break Clone;
            Css.box_decoration_break Clone;
          ]
    | Box_decoration_slice ->
        style
          [
            Css.webkit_box_decoration_break Slice;
            Css.box_decoration_break Slice;
          ]
    | Decoration_clone ->
        style
          [
            Css.webkit_box_decoration_break Clone;
            Css.box_decoration_break Clone;
          ]
    | Decoration_slice ->
        style
          [
            Css.webkit_box_decoration_break Slice;
            Css.box_decoration_break Slice;
          ]
    (* Break before *)
    | Break_before_all -> style [ Css.break_before All ]
    | Break_before_auto -> style [ Css.break_before Auto ]
    | Break_before_avoid -> style [ Css.break_before Avoid ]
    | Break_before_avoid_page -> style [ Css.break_before Avoid_page ]
    | Break_before_column -> style [ Css.break_before Column ]
    | Break_before_left -> style [ Css.break_before Left ]
    | Break_before_page -> style [ Css.break_before Page ]
    | Break_before_right -> style [ Css.break_before Right ]
    (* Break after *)
    | Break_after_all -> style [ Css.break_after All ]
    | Break_after_auto -> style [ Css.break_after Auto ]
    | Break_after_avoid -> style [ Css.break_after Avoid ]
    | Break_after_avoid_page -> style [ Css.break_after Avoid_page ]
    | Break_after_column -> style [ Css.break_after Column ]
    | Break_after_left -> style [ Css.break_after Left ]
    | Break_after_page -> style [ Css.break_after Page ]
    | Break_after_right -> style [ Css.break_after Right ]
    (* Break inside *)
    | Break_inside_auto -> style [ Css.break_inside Auto ]
    | Break_inside_avoid -> style [ Css.break_inside Avoid ]
    | Break_inside_avoid_column -> style [ Css.break_inside Avoid_column ]
    | Break_inside_avoid_page -> style [ Css.break_inside Avoid_page ]

  (** {1 Parsing Functions} *)

  (* The z-index a [z-[...]] bracket denotes. [None] is a bracket the z-index
     grammar cannot read, and [of_class] refuses the utility rather than leaving
     [to_style] to raise. *)
  let arbitrary_z_index inner : Css.z_index option =
    let cursor =
      Cascade.Cursor.of_string (Parse.decode_arbitrary_value inner)
    in
    match
      Cascade.Cursor.try_parse_full_err Css.Properties.read_z_index cursor
    with
    | Ok zi -> Some zi
    | Error _ -> None

  let of_class _theme class_name =
    let parts = Parse.split_class class_name in
    match parts with
    | [ "block" ] -> Ok Block
    | [ "contents" ] -> Ok Contents
    | [ "flow"; "root" ] -> Ok Flow_root
    | [ "inline" ] -> Ok Inline
    | [ "inline"; "block" ] -> Ok Inline_block
    | [ "inline"; "table" ] -> Ok Inline_table
    | [ "list"; "item" ] -> Ok List_item
    | [ "table" ] -> Ok Table
    | [ "table"; "caption" ] -> Ok Table_caption
    | [ "table"; "cell" ] -> Ok Table_cell
    | [ "table"; "column" ] -> Ok Table_column
    | [ "table"; "column"; "group" ] -> Ok Table_column_group
    | [ "table"; "footer"; "group" ] -> Ok Table_footer_group
    | [ "table"; "header"; "group" ] -> Ok Table_header_group
    | [ "table"; "row" ] -> Ok Table_row
    | [ "table"; "row"; "group" ] -> Ok Table_row_group
    | [ "hidden" ] -> Ok Hidden
    | [ "visible" ] -> Ok Visible
    | [ "invisible" ] -> Ok Invisible
    | [ "collapse" ] -> Ok Collapse
    | [ "isolate" ] -> Ok Isolate
    | [ "isolation"; "auto" ] -> Ok Isolation_auto
    | [ "z"; "0" ] -> Ok Z_0
    | [ "z"; "10" ] -> Ok Z_10
    | [ "z"; "20" ] -> Ok Z_20
    | [ "z"; "30" ] -> Ok Z_30
    | [ "z"; "40" ] -> Ok Z_40
    | [ "z"; "50" ] -> Ok Z_50
    | [ "z"; "auto" ] -> Ok Z_auto
    | [ "z"; n ] when String.starts_with ~prefix:"[" n ->
        (* Arbitrary value: z-[123] *)
        if Parse.is_bracket_value n then
          let inner = Parse.bracket_inner n in
          match arbitrary_z_index inner with
          | Some zi -> Ok (Z_arbitrary (inner, `Index zi))
          | None -> (
              (* Not a z-index, so it goes to the declaration as written. *)
              match Parse.arbitrary_declaration_value inner with
              | Some v -> Ok (Z_arbitrary (inner, `Raw v))
              | None -> Error (`Msg ("Invalid z-index arbitrary value: " ^ n)))
        else Error (`Msg ("Invalid z-index arbitrary value: " ^ n))
    | [ "z"; n ] -> (
        (* Dynamic z-index: z-5, z-100, etc. *)
        match Parse.decimal_int n with
        | Some i -> Ok (Z i)
        | None -> Error (`Msg ("Invalid z-index value: " ^ n)))
    | "" :: "z" :: rest when rest <> [] -> (
        (* Negative z-index: -z-10, -z-50, -z-[var(--value)], etc. *)
        let value = String.concat "-" rest in
        if Parse.is_bracket_value value then
          let inner = Parse.bracket_inner value in
          match arbitrary_z_index inner with
          | Some zi -> Ok (Neg_z_arbitrary (inner, zi))
          | None -> Error (`Msg ("Invalid negative z-index value: " ^ value))
        else
          match Parse.decimal_int value with
          | Some i -> Ok (Neg_z i)
          | None -> Error (`Msg ("Invalid negative z-index value: " ^ value)))
    | [ "object"; "contain" ] -> Ok Object_contain
    | [ "object"; "cover" ] -> Ok Object_cover
    | [ "object"; "fill" ] -> Ok Object_fill
    | [ "object"; "none" ] -> Ok Object_none
    | [ "object"; "scale"; "down" ] -> Ok Object_scale_down
    | [ "object"; "center" ] -> Ok Object_center
    | [ "object"; "top" ] -> Ok Object_top
    | [ "object"; "bottom" ] -> Ok Object_bottom
    | [ "object"; "left" ] -> Ok Object_left
    | [ "object"; "right" ] -> Ok Object_right
    | [ "object"; "bottom"; "left" ] -> Ok Object_bottom_left
    | [ "object"; "bottom"; "right" ] -> Ok Object_bottom_right
    | [ "object"; "left"; "bottom" ] -> Ok Object_left_bottom
    | [ "object"; "left"; "top" ] -> Ok Object_left_top
    | [ "object"; "right"; "bottom" ] -> Ok Object_right_bottom
    | [ "object"; "right"; "top" ] -> Ok Object_right_top
    | [ "object"; "top"; "left" ] -> Ok Object_top_left
    | [ "object"; "top"; "right" ] -> Ok Object_top_right
    | [ "object"; value ] when Parse.is_bracket_value value -> (
        let inner = Parse.bracket_inner value in
        (* Only a var() reference names a variable; anything the position parser
           rejects is not a utility. A data-type hint chooses which longhand a
           bracket lands in and says nothing about the value, and this family
           writes one, so the reader is handed what follows it. The constructor
           keeps the bracket whole, because the class name is what the markup
           carries. *)
        let readable v = parse_object_position v <> None || Parse.is_var v in
        if Option.fold ~none:false ~some:readable (Parse.value_after_hint inner)
        then Ok (Object_arbitrary inner)
        else
          match Parse.arbitrary_declaration_value inner with
          | Some raw -> Ok (Object_raw (inner, raw))
          | None -> Error (`Msg ("Invalid object-position value: " ^ inner)))
    | [ "float"; "left" ] -> Ok Float_left
    | [ "float"; "right" ] -> Ok Float_right
    | [ "float"; "none" ] -> Ok Float_none
    | [ "float"; "start" ] -> Ok Float_start
    | [ "float"; "end" ] -> Ok Float_end
    | [ "clear"; "left" ] -> Ok Clear_left
    | [ "clear"; "right" ] -> Ok Clear_right
    | [ "clear"; "none" ] -> Ok Clear_none
    | [ "clear"; "both" ] -> Ok Clear_both
    | [ "clear"; "start" ] -> Ok Clear_start
    | [ "clear"; "end" ] -> Ok Clear_end
    | [ "box"; "decoration"; "clone" ] -> Ok Box_decoration_clone
    | [ "box"; "decoration"; "slice" ] -> Ok Box_decoration_slice
    | [ "decoration"; "clone" ] -> Ok Decoration_clone
    | [ "decoration"; "slice" ] -> Ok Decoration_slice
    (* Break before *)
    | [ "break"; "before"; "all" ] -> Ok Break_before_all
    | [ "break"; "before"; "auto" ] -> Ok Break_before_auto
    | [ "break"; "before"; "avoid" ] -> Ok Break_before_avoid
    | [ "break"; "before"; "avoid"; "page" ] -> Ok Break_before_avoid_page
    | [ "break"; "before"; "column" ] -> Ok Break_before_column
    | [ "break"; "before"; "left" ] -> Ok Break_before_left
    | [ "break"; "before"; "page" ] -> Ok Break_before_page
    | [ "break"; "before"; "right" ] -> Ok Break_before_right
    (* Break after *)
    | [ "break"; "after"; "all" ] -> Ok Break_after_all
    | [ "break"; "after"; "auto" ] -> Ok Break_after_auto
    | [ "break"; "after"; "avoid" ] -> Ok Break_after_avoid
    | [ "break"; "after"; "avoid"; "page" ] -> Ok Break_after_avoid_page
    | [ "break"; "after"; "column" ] -> Ok Break_after_column
    | [ "break"; "after"; "left" ] -> Ok Break_after_left
    | [ "break"; "after"; "page" ] -> Ok Break_after_page
    | [ "break"; "after"; "right" ] -> Ok Break_after_right
    (* Break inside *)
    | [ "break"; "inside"; "auto" ] -> Ok Break_inside_auto
    | [ "break"; "inside"; "avoid" ] -> Ok Break_inside_avoid
    | [ "break"; "inside"; "avoid"; "column" ] -> Ok Break_inside_avoid_column
    | [ "break"; "inside"; "avoid"; "page" ] -> Ok Break_inside_avoid_page
    | _ -> Error (`Msg "Not a layout utility")

  let examples =
    [
      Block;
      Visible;
      Z_auto;
      Isolate;
      Float_left;
      Clear_both;
      Object_contain;
      Object_center;
      Break_before_page;
      Break_after_page;
      Break_inside_avoid;
    ]
end

open Handler
module Screen_reader_utility = Utility.Make (Screen_reader_handler)
module Utility_factory = Utility.Make (Handler)

(** {1 Public API - Utility Values} *)

(* Layout utilities *)
let utility = Utility_factory.v
let block = utility Block
let contents = utility Contents
let flow_root = utility Flow_root
let inline = utility Inline
let inline_block = utility Inline_block
let inline_table = utility Inline_table
let list_item = utility List_item
let table = utility Table
let table_caption = utility Table_caption
let table_cell = utility Table_cell
let table_column = utility Table_column
let table_column_group = utility Table_column_group
let table_footer_group = utility Table_footer_group
let table_header_group = utility Table_header_group
let table_row = utility Table_row
let table_row_group = utility Table_row_group
let hidden = utility Hidden
let visible = utility Visible
let invisible = utility Invisible
let collapse = utility Collapse
let isolate = utility Isolate
let isolation_auto = utility Isolation_auto
let z_0 = utility Z_0
let z_10 = utility Z_10
let z_20 = utility Z_20
let z_30 = utility Z_30
let z_40 = utility Z_40
let z_50 = utility Z_50
let z n = utility (Z n)
let z_auto = utility Z_auto
let object_contain = utility Object_contain
let object_cover = utility Object_cover
let object_fill = utility Object_fill
let object_none = utility Object_none
let object_scale_down = utility Object_scale_down
let object_center = utility Object_center
let object_top = utility Object_top
let object_bottom = utility Object_bottom
let object_left = utility Object_left
let object_right = utility Object_right
let object_bottom_left = utility Object_bottom_left
let object_bottom_right = utility Object_bottom_right
let object_left_bottom = utility Object_left_bottom
let object_left_top = utility Object_left_top
let object_right_bottom = utility Object_right_bottom
let object_right_top = utility Object_right_top
let object_top_left = utility Object_top_left
let object_top_right = utility Object_top_right
let float_left = utility Float_left
let float_right = utility Float_right
let float_none = utility Float_none
let float_start = utility Float_start
let float_end = utility Float_end
let clear_left = utility Clear_left
let clear_right = utility Clear_right
let clear_none = utility Clear_none
let clear_both = utility Clear_both
let clear_start = utility Clear_start
let clear_end = utility Clear_end

(* Screen reader utilities *)
let sr_utility = Screen_reader_utility.v
let sr_only = sr_utility Screen_reader_handler.Sr_only
let not_sr_only = sr_utility Screen_reader_handler.Not_sr_only

(* Box decoration break utilities *)
let box_decoration_clone = utility Box_decoration_clone
let box_decoration_slice = utility Box_decoration_slice

(* Break before/after/inside utilities - page/column breaks *)
let break_before_all = utility Break_before_all
let break_before_auto = utility Break_before_auto
let break_before_avoid = utility Break_before_avoid
let break_before_avoid_page = utility Break_before_avoid_page
let break_before_column = utility Break_before_column
let break_before_left = utility Break_before_left
let break_before_page = utility Break_before_page
let break_before_right = utility Break_before_right
let break_after_all = utility Break_after_all
let break_after_auto = utility Break_after_auto
let break_after_avoid = utility Break_after_avoid
let break_after_avoid_page = utility Break_after_avoid_page
let break_after_column = utility Break_after_column
let break_after_left = utility Break_after_left
let break_after_page = utility Break_after_page
let break_after_right = utility Break_after_right
let break_inside_auto = utility Break_inside_auto
let break_inside_avoid = utility Break_inside_avoid
let break_inside_avoid_column = utility Break_inside_avoid_column
let break_inside_avoid_page = utility Break_inside_avoid_page