dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r46.md
# Region r46: flex layout — what other regions need to know
Region r46 ports `Layout/FlexFormattingContext` (`.cpp` and `.h`). The stub fragment `stubs/stub_r46_layout_flex.lucb`
is gone. A box with `display: flex | inline-flex` is now laid out by the flex layout algorithm
(https://www.w3.org/TR/css-flexbox-1/#layout-algorithm): flex items in `order`, flex base sizes and hypothetical main
sizes, automatic minimum sizes, flex lines, flexible lengths, cross sizes and stretching, justify-content and auto
margins, align-items/align-self/align-content, gaps, baseline alignment, the intrinsic sizes of flex containers,
aspect ratios, and the static position of absolutely positioned children.
## Fragments
| Fragment | Donor |
| --- | --- |
| `layout/flex_formatting_context_1` | `FlexFormattingContext.h`'s inline members and `.cpp` 1-347: the items' outer sizes, `get_pixel_width/height`, construction, automatic content sizes, `run`, `parent_context_did_dimension_child_root_box`, the axes, `populate_specified_margins` |
| `layout/flex_formatting_context_2` | 349-653: `generate_anonymous_flex_items`, definite/inner/min/max main and cross sizes, setters, `determine_available_space_for_items`, `used_flex_basis_for_item`, aspect-ratio conversions |
| `layout/flex_formatting_context_3` | 655-1192: `determine_flex_base_size`, the automatic minimum size and its suggestions, `collect_flex_items_into_flex_lines`, `resolve_flexible_lengths(_for_line)` |
| `layout/flex_formatting_context_4` | 1194-1643: hypothetical and line cross sizes, used cross sizes, `distribute_any_remaining_free_space`, `dump_items`, `alignment_for_item`, cross-axis alignment, `resolve_baseline_aligned_items` |
| `layout/flex_formatting_context_5` | 1645-2068: `align_all_flex_lines`, `copy_dimensions_from_flex_items_to_boxes`, the container's intrinsic main/cross sizes, main-size contributions |
| `layout/flex_formatting_context_6` | 2070-2449: auto sizes and max sizes as none, cross-size contributions, the items' intrinsic and fit-content sizes, `flex_item_is_stretched`, computed sizes, cross-axis auto margins, `handle_align_content_stretch`, `calculate_static_position_rect`, the FlexLine sums, gaps |
| `layout/tests_layout_flex_cases`, `layout/tests_layout_flex` | tests (below) |
## What other regions must know
### Construction
`FormattingContext::create_independent_formatting_context_if_needed` (r44) makes the context with
`layout_make_formatting_context_storage[LayoutFlexFormattingContext]()` and `layout_flex_formatting_context_construct`,
which constructs the base, sets the class and initializes every member. `~FlexFormattingContext` is the default
destructor (`layout_formatting_context_destruct` has nothing to run for it). The context runs
`defer layout_formatting_context_destruct(...)` for the independent contexts `layout_inside` gives it for its items, as
r44 asks.
### Signatures changed from the stubs
- Every `FlexItem const&` parameter is `const LayoutFlexFormattingContextFlexItem*` (the stubs took the item by value);
`LayoutState::UsedValues const&` is `const LayoutStateUsedValues*` (`has_definite_main_size_layout_state_used_values`,
`has_definite_cross_size_...`, `inner_main_size_...`, `inner_cross_size_...`), as r44 asked.
- C++ private members are module-private, except `dump_items` and `calculate_fit_content_cross_size`, which nothing
calls (in C++ either) and which stay `pub` so the module checks without unused-function warnings. Public:
`construct`, the overrides (`run`, `automatic_content_width/height`, `inhibits_floating`,
`parent_context_did_dimension_child_root_box`), `flex_container`, `calculate_static_position_rect`.
### Types filled by hand
`types_flex_formatting_context`: `FlexItem` (C++'s `LayoutState::UsedValues&` is a pointer; `box` and `used_values`
are bare pointers, so an item is made with both), `FlexLine` (`Vector<FlexItem&>` is
`ak.Vector[LayoutFlexFormattingContextFlexItem*]`, pointers into the context's `m_flex_items`, which never grows after
`generate_anonymous_flex_items`) and the new `DirectionAgnosticMargins`
(`LayoutFlexFormattingContextDirectionAgnosticMargins`). The functions' local enums `FlexFactor` and
`FlexRegionRenderCursor` are module enums (`LayoutFlexFormattingContextFlexFactor`,
`LayoutFlexFormattingContextFlexRegionRenderCursor`). Namemap rows are updated or added for all of them.
### Where paths stop (other regions' stubs)
- Flex items that are grid containers, tables, `<svg>`, form controls (`<input>`, `<button>`, `<textarea>`): their
regions' stubs (r47, r48, r55, r24, r25).
- Under r57's runner every Layout test still stops before its dumps (backing stores with rendering; region r51a's
`ScrollState::create_scroll_frame_for` without it). Of the 137 Layout tests whose first stop was the
FlexFormattingContext, 130 now get through layout and commit and stop there; 7 stop at the GridFormattingContext.
## Deviations and notes
- C++ lambdas are functions: `run`'s `should_skip_automatic_minimum_size_clamp` and
`can_skip_automatic_minimum_size_for_item`, `determine_flex_base_size`'s flex base size
(`layout_flex_formatting_context_flex_base_size_of_item`) and `used_flex_basis_is_definite`
(`..._flex_basis_is_definite`), `content_based_minimum_size`'s `unclamped_size`,
`resolve_flexible_lengths_for_line`'s `calculate_remaining_free_space`, `distribute_any_remaining_free_space`'s
`place_item` and `align_all_flex_lines`' `place_items` (their mutated captures are pointer parameters),
`calculate_intrinsic_main_size_of_flex_container`'s `determine_main_size`, and the two `calculate_largest_contribution`
lambdas of `calculate_intrinsic_cross_size_of_flex_container`. The common "available inner space with an indefinite
width replaced by the width for an item's intrinsic height" of the four intrinsic item sizes is
`layout_flex_formatting_context_available_space_for_intrinsic_height`.
- `CSSPixels * size_t` (`main_gap() * (line.items.size() - 1)` and friends) converts the count with
`CSSPixels(Unsigned)`, which saturates; `layout_flex_formatting_context_mul_count` does the same (an empty line's count
wraps as in C++). `CSSPixels / int` is `layout_div_int`.
- `Optional<CSSPixels> != 0` is true for an empty Optional, `CSSPixels == Optional<CSSPixels>` false for one: both are
spelled out where `resolve_flexible_lengths_for_line` and `run` compare them.
- `calculate_intrinsic_main_size_of_flex_container` keeps the C++ `float` arithmetic of the chosen flex fraction
(`AK::max(float, double)` narrows the double).
- `dump_items` writes through Dump's `appendff` arguments (AK's number formatting) to `ak.dbgln`.
- Branch D of `determine_flex_base_size` (`... && false && false) { TODO(); }`) is kept as a comment.
- HANDOFF (luce-js HANDOFF.md §5 item 4) follow-ups: all were done by earlier regions (r44 and r45 list them).
## Tests
- `layout/tests_layout_flex_cases` (164 cases) + `layout/tests_layout_flex`, from the local oracle
`luce-browser-tools/oracles/luce-browser-engine/layout_geometry` (r44's, extended: `cases_flex.txt`,
`own_flex_cases.py`, `./oracle cases_flex.txt > expected_flex.txt`, `python3 gen_luce_cases.py flex`,
`compare_ladybird.py --full cases_flex.txt expected_flex.txt`). The harness is tests_layout_geometry's: layout,
commit, and the three dumps of a Layout test, compared byte for byte.
- 137 are Ladybird's Layout tests whose first stop (r57's `--no-rendering` rerun) was the FlexFormattingContext,
turned into cases by `from_ladybird.py`; the oracle reproduces 133 of their whole expected files (the other 4 move
`<style>` elements that the transformation changes: slots, shadow trees, a `<style>` after the content). The port
runs 129 of them and matches the oracle on all 129 (so it reproduces Ladybird's own expected layout, paint and
stacking-context dumps exactly for 126 Layout tests); 7 wait for grid layout (r47) and 1 for r53's paintables
(marked `!`).
- 35 are written for this region (each a document with many flex containers): every flex-direction,
justify-content in each direction and with gaps and overflow, align-items/align-self (baseline included),
wrap-reverse, align-content in rows and columns with wrap and wrap-reverse and negative free space, flex-grow
(factor sums below 1), flex-shrink (scaled factors, min-content and scroll containers), flex-basis (percentages,
calc, intrinsic keywords, indefinite containers, box-sizing), min/max violations, auto margins, gaps, `order`,
inline-flex/float/abspos/min-/max-/fit-content flex containers (intrinsic main and cross sizes, multi-line rows
and columns, flex fractions), column items' intrinsic heights, aspect ratios, abspos static positions, vertical
writing modes and rtl, percentages, nested containers, single-line cross clamps, anonymous items, quirks. All 35
match.
- A mutation check (space-around's initial offset halved differently) fails 4 cases, so the comparison bites.