Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / 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.