package toffee

  1. Overview
  2. Docs
CSS layout engine for OCaml (Flexbox, Grid, Block)

Install 

dune-project
 Dependency

github.com Readme Changelog Edit opam file Versions (1)

Authors

  1. Thibaut Mattio

Maintainers

  1. Thibaut Mattio

Sources

mosaic-0.1.0.tbz
sha256=9e4e90d17f9b2af1b07071fe425bc2c519c849c4f1d1ab73cde512be2d874849
sha512=06e9c4a741590942e81a27738d0b5c0413fafec8cf3b7dae047ad69f155e7b718aa4223818dc161b7d028efffcfd3365905e264d6fd31d453910ddfa91dcf9b9

doc/compute_grid/Compute_grid/Grid_item/index.html

Module Compute_grid.Grid_itemSource

Grid item representation for CSS Grid layout algorithm.

This module defines the grid item type used during track sizing and placement. Each item represents a single child node positioned within the grid, with cached intrinsic size contributions.

Key Invariants

  • row_indexes and column_indexes are initialized during placement and remain valid throughout layout.
  • All contribution caches (min_content_contribution_cache, etc.) are valid only for a single track-sizing run.
  • available_space_cache must match the current known_dimensions input or be None.
  • baseline_shim acts as additional top margin for baseline alignment.

Coordinate Systems

Grid items track placement in two coordinate systems:

  • Origin-zero coordinates: row and column fields, with lines numbered from the grid origin.
  • Track vector indices: row_indexes and column_indexes, indexing into GridTrack arrays.

Cache Invalidation

Intrinsic size caches are tied to available_space_cache. When the available space changes, all caches must be cleared by setting available_space_cache to None.

Sourcetype origin_zero_line = int

Origin-zero line coordinate type.

Sourcetype t = {
  1. node : Tree.Node_id.t;
  2. source_order : int;
  3. row : origin_zero_line Geometry.line;
  4. column : origin_zero_line Geometry.line;
  5. is_compressible_replaced : bool;
  6. overflow : Style.overflow Geometry.point;
  7. box_sizing : Style.box_sizing;
  8. size : Style.dimension Geometry.size;
  9. min_size : Style.dimension Geometry.size;
  10. max_size : Style.dimension Geometry.size;
  11. aspect_ratio : float option;
  12. padding : Style.length_percentage Geometry.rect;
  13. border : Style.length_percentage Geometry.rect;
  14. margin : Style.length_percentage_auto Geometry.rect;
  15. align_self : Style.align_self;
  16. justify_self : Style.justify_self;
  17. mutable baseline : float option;
  18. mutable baseline_shim : float;
  19. mutable row_indexes : int Geometry.line;
  20. mutable column_indexes : int Geometry.line;
  21. mutable crosses_flexible_row : bool;
  22. mutable crosses_flexible_column : bool;
  23. mutable crosses_intrinsic_row : bool;
  24. mutable crosses_intrinsic_column : bool;
  25. mutable available_space_cache : float option Geometry.size option;
  26. mutable min_content_contribution_cache : float option Geometry.size;
  27. mutable minimum_contribution_cache : float option Geometry.size;
  28. mutable max_content_contribution_cache : float option Geometry.size;
  29. mutable y_position : float;
  30. mutable height : float;
}

Grid item representation.

Sourceval new_with_placement_style_and_order : node:Tree.Node_id.t -> col_span:origin_zero_line Geometry.line -> row_span:origin_zero_line Geometry.line -> style:Style.t -> parent_align_items:Style.align_items -> parent_justify_items:Style.justify_items -> source_order:int -> t

new_with_placement_style_and_order ~node ~col_span ~row_span ~style ~parent_align_items ~parent_justify_items ~source_order creates a grid item with concrete placement.

Initializes style properties from style and sets align_self/justify_self to parent values if not explicitly specified. All index and crossing fields are set to default values and must be initialized later.

placement t axis returns the item's placement in origin-zero coordinates for axis.

Sourceval placement_indexes : t -> Geometry.abstract_axis -> int Geometry.line

placement_indexes t axis returns the item's placement as GridTrack vector indices for axis.

Sourceval track_range_excluding_lines : t -> Geometry.abstract_axis -> int * int

track_range_excluding_lines t axis returns (start_idx, end_idx) covering all tracks the item spans in axis, excluding bounding lines.

Used to slice GridTrack arrays for iteration over spanned tracks.

Sourceval span : t -> Geometry.abstract_axis -> int

span t axis returns the number of tracks the item spans in axis. Returns 0 if placement is invalid.

Sourceval crosses_flexible_track : t -> Geometry.abstract_axis -> bool

crosses_flexible_track t axis returns the pre-computed flag indicating whether the item crosses a flexible track in axis.

Sourceval crosses_intrinsic_track : t -> Geometry.abstract_axis -> bool

crosses_intrinsic_track t axis returns the pre-computed flag indicating whether the item crosses an intrinsic track in axis.

Sourceval spanned_track_limit : t -> Geometry.abstract_axis -> Compute_grid__.Grid_track.t array -> float option -> (int -> float -> float) -> float option

spanned_track_limit t axis axis_tracks axis_parent_size resolve_calc_value computes the upper limit for the item's min/max-content contribution.

Returns Some limit if the item spans only tracks with definite max track sizing functions, where limit is the sum of those maximums. Otherwise returns None.

This implements the limited min-/max-content contribution per CSS Grid specification.

Sourceval known_dimensions : (module Tree.LAYOUT_PARTIAL_TREE with type t = 'tree) -> t -> 'tree -> float option Geometry.size -> float option Geometry.size -> float option Geometry.size

known_dimensions tree t inner_node_size grid_area_size computes the known_dimensions for child sizing.

Applies stretch alignment to resolve percentage sizes correctly. Algorithm:

  1. Resolve margins, padding, border, and box-sizing adjustments.
  2. Resolve inherent size and clamp by min/max.
  3. Apply stretch alignment for width if justify_self = Stretch and margins are not auto.
  4. Reapply aspect ratio.
  5. Apply stretch alignment for height if align_self = Stretch and margins are not auto.
  6. Reapply aspect ratio and clamp by min/max.

Returns the final known_dimensions to pass to child layout functions.

Sourceval spanned_fixed_track_limit : t -> Geometry.abstract_axis -> Compute_grid__.Grid_track.t array -> float option -> (int -> float -> float) -> float option

spanned_fixed_track_limit t axis axis_tracks axis_parent_size resolve_calc_value computes the limit for automatic minimum contributions.

Similar to spanned_track_limit but excludes fit-content arguments. Returns Some limit if all spanned tracks have definite max track sizing functions (excluding fit-content).

Sourceval min_content_contribution : (module Tree.LAYOUT_PARTIAL_TREE with type t = 'tree) -> t -> Geometry.abstract_axis -> 'tree -> float option Geometry.size -> float option Geometry.size -> float

min_content_contribution tree t axis available_space inner_node_size computes the item's min-content contribution in axis.

Measures the child with min-content available space in axis.

Sourceval min_content_contribution_cached : t -> Geometry.abstract_axis -> (module Tree.LAYOUT_PARTIAL_TREE with type t = 'tree) -> 'tree -> float option Geometry.size -> float option Geometry.size -> float

min_content_contribution_cached t axis tree available_space inner_node_size retrieves the cached min-content contribution or computes it.

Cache is invalidated when available_space_cache changes.

Sourceval max_content_contribution : (module Tree.LAYOUT_PARTIAL_TREE with type t = 'tree) -> t -> Geometry.abstract_axis -> 'tree -> float option Geometry.size -> float option Geometry.size -> float

max_content_contribution tree t axis available_space inner_node_size computes the item's max-content contribution in axis.

Measures the child with max-content available space in axis.

Sourceval max_content_contribution_cached : t -> Geometry.abstract_axis -> (module Tree.LAYOUT_PARTIAL_TREE with type t = 'tree) -> 'tree -> float option Geometry.size -> float option Geometry.size -> float

max_content_contribution_cached t axis tree available_space inner_node_size retrieves the cached max-content contribution or computes it.

Cache is invalidated when available_space_cache changes.

Sourceval available_space : t -> Geometry.abstract_axis -> Compute_grid__.Grid_track.t array -> float option -> (Compute_grid__.Grid_track.t -> float option -> float option) -> float option Geometry.size

available_space t axis other_axis_tracks other_axis_available_space get_track_size_estimate computes the available space for sizing in axis.

Uses track size estimates from the opposite axis to determine cross-axis constraints. The result has the opposite axis dimension set and the sizing axis set to None.