Source file gap.ml

(** Gap and space-between utilities. *)

module Css = Cascade.Css

module Handler = struct
  open Style
  open Css

  type gap_value =
    | Standard of spacing
    | Bare_var of string (* gap-(--value), raw kept for round-trip/order *)
    | Arbitrary of string * Css.length (* gap-[4px], raw kept for round-trip *)
    | Arbitrary_var of string * string (* raw inner, then the var() text *)
    | Arbitrary_raw of string * string
  (* gap-[foo]: each axis names one longhand, so a bracket no length reader took
     still reaches it and the value is forwarded verbatim. *)

  type t =
    | Gap of { axis : [ `All | `X | `Y ]; value : gap_value }
    | Space of { negative : bool; axis : [ `X | `Y ]; value : spacing }
    | Space_arb of { axis : [ `X | `Y ]; value : Css.length; raw : string }
      (* [raw] is the original bracketed token (e.g. "[-0]"), kept verbatim for
         the class name since [value] normalises away signed zero. *)
    | Space_x_reverse
    | Space_y_reverse

  let name = "gap"
  let priority _ = 17

  (* Space reverse variables for flex-reverse support. Property order 2/3 places
     these after the transform group but before --tw-divide-*-reverse (4/5) and
     --tw-border-style (6), matching Tailwind's @layer properties order. Like
     divide, they must use ~family:`Border so they sort with that group by
     property_order rather than being pushed to family-order. *)
  let space_x_reverse_var =
    Var.property_default Css.Number_percentage ~initial:(Css.Num 0.0)
      ~property_order:2 ~family:`Border "tw-space-x-reverse"

  let space_y_reverse_var =
    Var.property_default Css.Number_percentage ~initial:(Css.Num 0.0)
      ~property_order:3 ~family:`Border "tw-space-y-reverse"

  (** {2 Typed Gap Utilities} *)

  let gap_standard ?theme (s : spacing) =
    let decl, len = Spacing.to_decl_len ?theme s in
    let gap_value = Lengths { row_gap = Some len; column_gap = Some len } in
    style (Option.to_list decl @ [ gap gap_value ])

  let gap_x_standard ?theme (s : spacing) =
    let decl, len = Spacing.to_decl_len ?theme s in
    style (Option.to_list decl @ [ column_gap len ])

  let gap_y_standard ?theme (s : spacing) =
    let decl, len = Spacing.to_decl_len ?theme s in
    style (Option.to_list decl @ [ row_gap len ])

  let gap_arb len =
    let gap_value = Lengths { row_gap = Some len; column_gap = Some len } in
    style [ gap gap_value ]

  let gap_x_arb len = style [ column_gap len ]
  let gap_y_arb len = style [ row_gap len ]

  let gap_var_ref var_str : Css.length =
    let bare_name = Parse.extract_var_name var_str in
    Css.Var (Var.bracket bare_name)

  (* The longhand each axis names, for a value no typed setter can hold. *)
  let property_of_axis = function
    | `All -> "gap"
    | `X -> "column-gap"
    | `Y -> "row-gap"

  let gap_value ?theme axis (v : gap_value) =
    match v with
    | Arbitrary_raw (_, value) ->
        style
          (Option.to_list
             (Parse.opaque_declaration (property_of_axis axis) value))
    | Standard s -> (
        match axis with
        | `All -> gap_standard ?theme s
        | `X -> gap_x_standard ?theme s
        | `Y -> gap_y_standard ?theme s)
    | Bare_var raw -> (
        let len = gap_var_ref ("var(" ^ Parse.bare_var_inner raw ^ ")") in
        match axis with
        | `All -> gap_arb len
        | `X -> gap_x_arb len
        | `Y -> gap_y_arb len)
    | Arbitrary (_, len) -> (
        match axis with
        | `All -> gap_arb len
        | `X -> gap_x_arb len
        | `Y -> gap_y_arb len)
    | Arbitrary_var (_, var_str) -> (
        let len = gap_var_ref var_str in
        match axis with
        | `All -> gap_arb len
        | `X -> gap_x_arb len
        | `Y -> gap_y_arb len)

  (** {2 Space Between Utilities} *)

  (* Build margin calc expressions for space utilities. The negative sign is
     already folded into [spacing_len] (calc(var(--spacing) * -n)), so the
     reverse mechanism just wraps it once, matching Tailwind. *)
  let space_margin_calcs ~spacing_len ~reverse_var_name =
    let base = Css.Calc.length spacing_len in
    (* Wrap sub-expression as an explicit calc() call, matching Tailwind's
       output: calc(... * calc(1 - var(--tw-space-y-reverse))) *)
    let one_minus_reverse =
      Css.Calc.length
        (Css.Calc
           (Css.Calc.sub (Css.Calc.float 1.0) (Css.Calc.var reverse_var_name)))
    in
    let start_expr = Css.Calc.(mul base (var reverse_var_name)) in
    let end_expr = Css.Calc.(mul base one_minus_reverse) in
    ((Css.Calc start_expr : Css.length), (Css.Calc end_expr : Css.length))

  let space_x ?theme n =
    (* [Float.sign_bit] (not [n < 0.0]) so negative zero keeps its sign: the
       class [-space-x-0] must render [.-space-x-0], distinct from [.space-x-0],
       even though the value collapses to the same [margin-inline: 0]. *)
    let negative = Float.sign_bit n in
    let abs_n = Float.abs n in
    let class_name =
      (if negative then "-space-x-" else "space-x-")
      ^ Spacing.pp_spacing_suffix (`Rem (abs_n *. 0.25))
    in
    let selector =
      Css.Selector.(where [ class_ class_name >> not [ Last_child ] ])
    in
    let spacing_decl, spacing_len = Theme.spacing_calc_float ?theme n in
    let reverse_decl, reverse_ref =
      Var.binding space_x_reverse_var (Css.Num 0.0)
    in
    let reverse_var_name = Css.var_name reverse_ref in
    let margin_start, margin_end =
      space_margin_calcs ~spacing_len ~reverse_var_name
    in
    let property_rules =
      [ Var.property_rule space_x_reverse_var ] |> List.filter_map Fun.id
    in
    let rule =
      Css.rule ~selector
        [
          spacing_decl;
          reverse_decl;
          margin_inline_start margin_start;
          margin_inline_end margin_end;
        ]
    in
    style ~rules:(Some [ rule ]) ~property_rules:(Css.concat property_rules) []

  (* space-x-px / space-y-px: the gap is a literal 1px (not a spacing multiple),
     so there is no --spacing declaration; the reverse mechanism wraps ±1px
     directly, matching Tailwind. *)
  let space_px ~axis ~negative
      (reverse_var : Css.number_percentage Var.property_default)
      ~margin_start_decl ~margin_end_decl =
    let axis_str = match axis with `X -> "x" | `Y -> "y" in
    let class_name =
      (if negative then "-space-" else "space-") ^ axis_str ^ "-px"
    in
    let selector =
      Css.Selector.(where [ class_ class_name >> not [ Last_child ] ])
    in
    let spacing_len : length = if negative then Px (-1.) else Px 1. in
    let reverse_decl, reverse_ref = Var.binding reverse_var (Css.Num 0.0) in
    let reverse_var_name = Css.var_name reverse_ref in
    let margin_start, margin_end =
      space_margin_calcs ~spacing_len ~reverse_var_name
    in
    let property_rules =
      [ Var.property_rule reverse_var ] |> List.filter_map Fun.id
    in
    let rule =
      Css.rule ~selector
        [
          reverse_decl;
          margin_start_decl margin_start;
          margin_end_decl margin_end;
        ]
    in
    style ~rules:(Some [ rule ]) ~property_rules:(Css.concat property_rules) []

  let space_y ?theme n =
    (* See [space_x]: negative zero ([-space-y-0]) must keep its sign. *)
    let negative = Float.sign_bit n in
    let abs_n = Float.abs n in
    let class_name =
      (if negative then "-space-y-" else "space-y-")
      ^ Spacing.pp_spacing_suffix (`Rem (abs_n *. 0.25))
    in
    let selector =
      Css.Selector.(where [ class_ class_name >> not [ Last_child ] ])
    in
    let spacing_decl, spacing_len = Theme.spacing_calc_float ?theme n in
    let reverse_decl, reverse_ref =
      Var.binding space_y_reverse_var (Css.Num 0.0)
    in
    let reverse_var_name = Css.var_name reverse_ref in
    let margin_start, margin_end =
      space_margin_calcs ~spacing_len ~reverse_var_name
    in
    let property_rules =
      [ Var.property_rule space_y_reverse_var ] |> List.filter_map Fun.id
    in
    let rule =
      Css.rule ~selector
        [
          spacing_decl;
          reverse_decl;
          margin_block_start margin_start;
          margin_block_end margin_end;
        ]
    in
    style ~rules:(Some [ rule ]) ~property_rules:(Css.concat property_rules) []

  (* Bracket arbitrary space: space-x-[4px], space-y-[10rem] *)
  let space_arb_x (len : Css.length) class_name =
    let selector =
      Css.Selector.(where [ class_ class_name >> not [ Last_child ] ])
    in
    let reverse_decl, reverse_ref =
      Var.binding space_x_reverse_var (Css.Num 0.0)
    in
    let reverse_var_name = Css.var_name reverse_ref in
    let margin_start : Css.length =
      Calc Calc.(mul (length len) (var reverse_var_name))
    in
    let margin_end : Css.length =
      Calc
        Calc.(
          mul (length len) (nested (sub (float 1.0) (var reverse_var_name))))
    in
    let property_rules =
      [ Var.property_rule space_x_reverse_var ] |> List.filter_map Fun.id
    in
    let rule =
      Css.rule ~selector
        [
          reverse_decl;
          margin_inline_start margin_start;
          margin_inline_end margin_end;
        ]
    in
    style ~rules:(Some [ rule ]) ~property_rules:(Css.concat property_rules) []

  let space_arb_y (len : Css.length) class_name =
    let selector =
      Css.Selector.(where [ class_ class_name >> not [ Last_child ] ])
    in
    let reverse_decl, reverse_ref =
      Var.binding space_y_reverse_var (Css.Num 0.0)
    in
    let reverse_var_name = Css.var_name reverse_ref in
    let margin_start : Css.length =
      Calc Calc.(mul (length len) (var reverse_var_name))
    in
    let margin_end : Css.length =
      Calc
        Calc.(
          mul (length len) (nested (sub (float 1.0) (var reverse_var_name))))
    in
    let property_rules =
      [ Var.property_rule space_y_reverse_var ] |> List.filter_map Fun.id
    in
    let rule =
      Css.rule ~selector
        [
          reverse_decl;
          margin_block_start margin_start;
          margin_block_end margin_end;
        ]
    in
    style ~rules:(Some [ rule ]) ~property_rules:(Css.concat property_rules) []

  (* Relative value order within one axis: px, then the rem scale ascending (max
     ~960 at gap-96), then full and named. Kept compact so a whole axis fits in
     a band well under 10000. *)
  let spacing_value_order = function
    | `Px -> 1
    | `Rem f -> int_of_float (f /. 0.25 *. 10.)
    | `Full -> 1000
    | `Named _ -> 1100

  (* space-x-reverse utility sets --tw-space-x-reverse: 1 on children *)
  let space_x_reverse_style () =
    let selector =
      Css.Selector.(where [ class_ "space-x-reverse" >> not [ Last_child ] ])
    in
    let decl = Var.set space_x_reverse_var (Css.Num 1.0) in
    let property_rules =
      [ Var.property_rule space_x_reverse_var ] |> List.filter_map Fun.id
    in
    let rule = Css.rule ~selector [ decl ] in
    style ~rules:(Some [ rule ]) ~property_rules:(Css.concat property_rules) []

  (* space-y-reverse utility sets --tw-space-y-reverse: 1 on children *)
  let space_y_reverse_style () =
    let selector =
      Css.Selector.(where [ class_ "space-y-reverse" >> not [ Last_child ] ])
    in
    let decl = Var.set space_y_reverse_var (Css.Num 1.0) in
    let property_rules =
      [ Var.property_rule space_y_reverse_var ] |> List.filter_map Fun.id
    in
    let rule = Css.rule ~selector [ decl ] in
    style ~rules:(Some [ rule ]) ~property_rules:(Css.concat property_rules) []

  let to_style theme t =
    let gap_value axis value = gap_value ~theme axis value in
    let space_x n = space_x ~theme n in
    let space_y n = space_y ~theme n in
    match t with
    | Gap { axis; value } -> gap_value axis value
    | Space { negative; axis; value = `Px } -> (
        match axis with
        | `X ->
            space_px ~axis:`X ~negative space_x_reverse_var
              ~margin_start_decl:margin_inline_start
              ~margin_end_decl:margin_inline_end
        | `Y ->
            space_px ~axis:`Y ~negative space_y_reverse_var
              ~margin_start_decl:margin_block_start
              ~margin_end_decl:margin_block_end)
    | Space { negative; axis; value } -> (
        let n =
          match value with
          | `Rem f -> f /. 0.25
          | `Px -> 0.0
          | `Full -> 0.0
          | `Named _ -> 0.0
        in
        let n = if negative then -.n else n in
        match axis with `X -> space_x n | `Y -> space_y n)
    | Space_arb { axis; value; raw } -> (
        let class_name =
          match axis with `X -> "space-x-" ^ raw | `Y -> "space-y-" ^ raw
        in
        match axis with
        | `X -> space_arb_x value class_name
        | `Y -> space_arb_y value class_name)
    | Space_x_reverse -> space_x_reverse_style ()
    | Space_y_reverse -> space_y_reverse_style ()

  let gap_value_order = function
    | Bare_var _ -> 0
    | Standard `Px -> 2100
    | Standard s -> spacing_value_order s
    | Arbitrary _ -> 2000
    | Arbitrary_var _ | Arbitrary_raw _ -> 2000

  (* gap and space share priority 17 with the alignment utilities. Tailwind
     emits them in CSS-property registration order, which interleaves the two
     families between justify-items and place-self: gap (all) -> margin-block
     (space-y) -> column-gap (gap-x) -> margin-inline (space-x) -> row-gap
     (gap-y) Each property gets a 10000-wide band starting at 1000 (above
     justify-items at <=75, below place-self at 76000); values sort within the
     band. *)
  let gap_rank = function `All -> 0 | `X -> 2 | `Y -> 4
  let space_rank = function `Y -> 1 | `X -> 3
  let band r = 1000 + (r * 10000)

  (* Within a space band: negatives (ascending magnitude) come first, then
     positive standards, then arbitrary (3000) and reverse (3100). *)
  let space_value_order ~negative value =
    if negative then spacing_value_order value
    else 1500 + spacing_value_order value

  let suborder = function
    | Gap { axis; value } -> band (gap_rank axis) + gap_value_order value
    | Space { negative; axis; value } ->
        band (space_rank axis) + space_value_order ~negative value
    | Space_arb { axis; _ } -> band (space_rank axis) + 3000
    | Space_x_reverse -> band (space_rank `X) + 3100
    | Space_y_reverse -> band (space_rank `Y) + 3100

  let pp_gap_value_suffix = function
    | Standard s -> Spacing.pp_spacing_suffix s
    | Bare_var raw -> raw
    | Arbitrary (raw, _) -> "[" ^ raw ^ "]"
    | Arbitrary_var (raw, _) | Arbitrary_raw (raw, _) -> "[" ^ raw ^ "]"

  let to_class = function
    | Gap { axis; value } -> (
        let suffix = pp_gap_value_suffix value in
        match axis with
        | `All -> "gap-" ^ suffix
        | `X -> "gap-x-" ^ suffix
        | `Y -> "gap-y-" ^ suffix)
    | Space { negative; axis; value } -> (
        let suffix = Spacing.pp_spacing_suffix value in
        let prefix = if negative then "-" else "" in
        match axis with
        | `X -> prefix ^ "space-x-" ^ suffix
        | `Y -> prefix ^ "space-y-" ^ suffix)
    | Space_arb { axis; raw; _ } -> (
        match axis with `X -> "space-x-" ^ raw | `Y -> "space-y-" ^ raw)
    | Space_x_reverse -> "space-x-reverse"
    | Space_y_reverse -> "space-y-reverse"

  let parse_gap_arbitrary s : gap_value option =
    if Parse.is_bracket_value s then
      let inner = Parse.bracket_inner s in
      (* A data-type hint chooses the longhand and says nothing about the value.
         Gap writes one longhand per axis, so every hint lands here and the
         readers below are handed what follows it. *)
      match Parse.value_after_hint inner with
      | None -> None
      | Some value -> (
          if Parse.is_var value then Some (Arbitrary_var (inner, value))
          else
            (* Route the value through the whole arbitrary decoder and the full
               length grammar (percent, container-query units, calc), keeping
               the raw token for round-trip. *)
            match Parse.arbitrary_length value with
            | Some l -> Some (Arbitrary (inner, l))
            | None ->
                Option.map
                  (fun raw -> Arbitrary_raw (inner, raw))
                  (Parse.arbitrary_declaration_value inner))
    else None

  (* Shared with padding and margin, so a named spacing reaches gap too:
     [gap-form] is a class Tailwind emits whenever the theme defines
     [--spacing-form]. *)
  let parse_gap_value ?theme value =
    if Parse.is_bare_var value then Some (Bare_var value)
    else if String.starts_with ~prefix:"[" value then parse_gap_arbitrary value
    else
      match Spacing.parse_value_string ?theme ~allow_auto:false value with
      | Some (#Style.spacing as s) -> Some (Standard s)
      | Some `Auto | None -> None

  let of_class theme class_name =
    let parse_gap_value value = parse_gap_value ~theme value in
    let parts = Parse.split_class class_name in
    let err_not_utility = Error (`Msg "Not a gap utility") in
    let parse_class = function
      | [ "gap"; value ] -> (
          match parse_gap_value value with
          | Some v -> Ok (Gap { axis = `All; value = v })
          | None -> err_not_utility)
      | [ "gap"; "x"; value ] -> (
          match parse_gap_value value with
          | Some v -> Ok (Gap { axis = `X; value = v })
          | None -> err_not_utility)
      | [ "gap"; "y"; value ] -> (
          match parse_gap_value value with
          | Some v -> Ok (Gap { axis = `Y; value = v })
          | None -> err_not_utility)
      | [ "space"; "x"; value ] -> (
          if value = "reverse" then Ok Space_x_reverse
          else if value = "px" then
            Ok (Space { negative = false; axis = `X; value = `Px })
          else
            match parse_gap_arbitrary value with
            | Some (Arbitrary (_, len)) ->
                Ok (Space_arb { axis = `X; value = len; raw = value })
            | _ -> (
                match Parse.spacing_value ~name:"space-x" value with
                | Ok n when Theme.has_spacing_step ~theme n ->
                    Ok
                      (Space
                         {
                           negative = false;
                           axis = `X;
                           value = `Rem (n *. 0.25);
                         })
                | Ok _ | Error _ -> err_not_utility))
      | [ "space"; "y"; value ] -> (
          if value = "reverse" then Ok Space_y_reverse
          else if value = "px" then
            Ok (Space { negative = false; axis = `Y; value = `Px })
          else
            match parse_gap_arbitrary value with
            | Some (Arbitrary (_, len)) ->
                Ok (Space_arb { axis = `Y; value = len; raw = value })
            | _ -> (
                match Parse.spacing_value ~name:"space-y" value with
                | Ok n when Theme.has_spacing_step ~theme n ->
                    Ok
                      (Space
                         {
                           negative = false;
                           axis = `Y;
                           value = `Rem (n *. 0.25);
                         })
                | Ok _ | Error _ -> err_not_utility))
      | [ ""; "space"; "x"; value ] -> (
          if value = "px" then
            Ok (Space { negative = true; axis = `X; value = `Px })
          else
            match Parse.spacing_value ~name:"space-x" value with
            | Ok n when Theme.has_spacing_step ~theme n ->
                Ok
                  (Space
                     { negative = true; axis = `X; value = `Rem (n *. 0.25) })
            | Ok _ | Error _ -> err_not_utility)
      | [ ""; "space"; "y"; value ] -> (
          if value = "px" then
            Ok (Space { negative = true; axis = `Y; value = `Px })
          else
            match Parse.spacing_value ~name:"space-y" value with
            | Ok n when Theme.has_spacing_step ~theme n ->
                Ok
                  (Space
                     { negative = true; axis = `Y; value = `Rem (n *. 0.25) })
            | Ok _ | Error _ -> err_not_utility)
      | _ -> err_not_utility
    in
    parse_class parts

  let examples =
    [
      Gap { axis = `All; value = Standard (`Rem 1.) };
      Gap { axis = `X; value = Standard (`Rem 1.) };
      Gap { axis = `Y; value = Standard (`Rem 1.) };
      Space { negative = false; axis = `X; value = `Rem 1. };
      Space { negative = false; axis = `Y; value = `Rem 1. };
    ]
end

open Handler

module Utility_factory = Utility.Make (Handler)
(** Register handler with Utility system *)

(** Public API *)
let utility = Utility_factory.v

(** Helpers to create Utility.t from Gap/Space *)
let gap_util axis value = utility (Gap { axis; value })

let space_util negative axis value = utility (Space { negative; axis; value })

(** {2 Int-based Gap Utilities} *)

(* Gap has no negative form in Tailwind, and the class printer writes a size's
   absolute value, so a negative one is refused rather than printed as a
   different gap. The space utilities below keep their sign: [-space-x-4] is a
   Tailwind class. *)
let checked_size name n =
  if n < 0 then
    invalid_arg (name ^ ": gap has no negative size, got " ^ string_of_int n)
  else Spacing.int n

let checked_size' name n =
  if n < 0. then
    invalid_arg (name ^ ": gap has no negative size, got " ^ Float.to_string n)
  else Spacing.float n

let gap n = gap_util `All (Handler.Standard (checked_size "gap" n))
let gap_x n = gap_util `X (Handler.Standard (checked_size "gap_x" n))
let gap_y n = gap_util `Y (Handler.Standard (checked_size "gap_y" n))
let gap' n = gap_util `All (Handler.Standard (checked_size' "gap'" n))
let gap_x' n = gap_util `X (Handler.Standard (checked_size' "gap_x'" n))
let gap_y' n = gap_util `Y (Handler.Standard (checked_size' "gap_y'" n))

(** {2 Special Gap Values} *)

let gap_px = gap_util `All (Handler.Standard `Px)
let gap_full = gap_util `All (Handler.Standard `Full)
let gap_x_px = gap_util `X (Handler.Standard `Px)
let gap_x_full = gap_util `X (Handler.Standard `Full)
let gap_y_px = gap_util `Y (Handler.Standard `Px)
let gap_y_full = gap_util `Y (Handler.Standard `Full)

(** {2 Space Between Utilities} *)

let space_x' n =
  let s = `Rem (Float.abs n *. 0.25) in
  let neg = n < 0.0 in
  space_util neg `X s

let space_y' n =
  let s = `Rem (Float.abs n *. 0.25) in
  let neg = n < 0.0 in
  space_util neg `Y s

let space_x n = space_x' (float_of_int n)
let space_y n = space_y' (float_of_int n)