dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r47.md
# Region r47: grid layout — what other regions need to know
Region r47 ports `Layout/GridFormattingContext` (`.cpp` and `.h`). The stub fragment `stubs/stub_r47_layout_grid.lucb`
is gone. A box with `display: grid | inline-grid` is now laid out by the grid layout algorithm
(https://www.w3.org/TR/css-grid-2/#layout-algorithm): explicit grid lines and named lines from `grid-template-*`,
implicitly-assigned line names from `grid-template-areas`, `repeat()` with fixed, `auto-fill` and `auto-fit` counts,
grid item placement (line numbers, negative lines, spans, named lines and areas, sparse and dense auto-placement in
rows and columns, `order`), implicit tracks from `grid-auto-*`, gutters as fixed-size tracks, collapsed auto-fit
tracks, the track sizing algorithm (base sizes and growth limits, intrinsic contributions of single-track and spanning
items, items crossing flexible tracks, maximizing, flexible tracks and the size of an fr, stretched auto tracks), the
second row sizing pass against the container's used height, the items' sizes, margins and self-alignment in their grid
areas, content distribution of the gutters, the intrinsic sizes of grid containers, the containing blocks of absolutely
positioned children in the augmented grid, and the used `grid-template-columns`/`-rows` that `getComputedStyle()` reads.
## Fragments
| Fragment | Donor |
| --- | --- |
| `layout/grid_formatting_context_1` | `GridFormattingContext.h`'s inline members (GridItem, OccupationGrid, `grid_container`, `has_gaps`, `for_each_spanned_track_by_item`, `has_flexible_tracks`) and `.cpp` 1-269: the four `to_alignment`, the GridTrack factories, construction, `resolve_definite_track_size`, `count_of_repeated_auto_fill_or_fit_tracks` |
| `layout/grid_formatting_context_2` | 271-659: `resolve_grid_position`, `resolve_grid_span`, the `place_item_*` functions, `OccupationGrid::find_unoccupied_place`, `record_grid_placement`, the explicit and implicit tracks, `initialize_gap_tracks` |
| `layout/grid_formatting_context_3` | 661-1121: `initialize_track_sizes`, `resolve_intrinsic_track_sizes`, the two `distribute_extra_space_across_spanned_tracks_*`, the two `increase_sizes_to_accommodate_spanning_items_*` |
| `layout/grid_formatting_context_4` | 1123-1611: `maximize_tracks(_using_available_size)`, `expand_flexible_tracks`, `stretch_auto_tracks`, `run_track_sizing`, `build_grid_areas`, `place_grid_items`, the container's height and the second row pass |
| `layout/grid_formatting_context_5` | 1613-2056: `alignment_for_item`, `resolve_grid_item_sizes`, `resolve_track_spacing`, `resolve_items_box_metrics`, `collapse_auto_fit_tracks_if_needed`, `get_grid_area_rect` |
| `layout/grid_formatting_context_6` | 2058-2462: `run`, `resolve_abspos_containing_block_info`, `parent_context_did_dimension_child_root_box`, the container's intrinsic and automatic sizes, `get_free_space`, named lines, `init_grid_lines`, OccupationGrid's cells, `GridItem::gap_adjusted_row/column` |
| `layout/grid_formatting_context_7` | 2464-2850: the container's maximum size, the items' content sizes and (limited) contributions, `calculate_fixed_max_track_size_limit`, the size suggestions, the content-based and automatic minimum sizes, `calculate_minimum_contribution`, `calculate_static_position_rect` |
| `layout/tests_layout_grid_cases`, `layout/tests_layout_grid` | 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[LayoutGridFormattingContext]()` and `layout_grid_formatting_context_construct`,
which constructs the base, sets the class, takes the container's UsedValues and starts every other member at its
default (an empty occupation grid). `~GridFormattingContext` is the default destructor (`layout_formatting_context_destruct`
has nothing to run for it). `run` destructs the independent contexts `layout_inside` gives it for its items, as r44 asks.
### Signatures changed from the stubs
- Every `GridItem const&` parameter is `const LayoutGridItem*` (the stubs took the item by value);
`CSS::ExplicitGridTrack const&` is `const CssExplicitGridTrack*` (`GridTrack::create_from_definition`, which keeps its
default `is_auto_fit = false`, and `count_of_repeated_auto_fill_or_fit_tracks`); `CSS::GridSize const&` is
`const CssGridSize*` (`resolve_definite_track_size`).
- `GridItem::computed_values` answers `const CssComputedValues*` (a `const&` in C++).
- The templates `for_each_spanned_track_by_item<Callback>` (both overloads) are iterables:
`for track in layout_grid_formatting_context_for_each_spanned_track_by_item(this, item, dimension)` yields each spanned
track, then the gap after it unless it is the last (`LayoutGridFormattingContextSpannedTracks` /
`...SpannedTrackIterator`, DESIGN §2.9).
- `distribute_extra_space_across_spanned_tracks_base_size/_growth_limit<Match>` take the matcher as
`ak.Function1[const LayoutGridFormattingContextGridTrack*, bool]` whose context is the available size the C++ lambda
captures (`layout_grid_formatting_context_matcher`).
- C++ private members and the file's `static` functions are module-private, except the overrides, `construct`,
`grid_container`, `calculate_static_position_rect`, the GridItem and OccupationGrid members (public in C++), and
`calculate_max_content_size`, which nothing calls (in C++ either) and stays `pub` so the module checks without an
unused-function warning.
### Types filled by hand
- `types_grid_formatting_context`: `GridTrack` (its `growth_limit` defaults to a present zero, `Optional<CSSPixels> { 0 }`,
which the factories set), `PlacementPosition`, and `GridItem`'s spans as `usize?` (`Optional<size_t>`; the generator
wrote `u64?`). Namemap rows updated (`struct`), plus the local `ItemAlignment` of `resolve_grid_item_sizes`
(`LayoutGridFormattingContextItemAlignment`).
- `generated/types_traits`: `LayoutGridPositionTraits` (`Traits<GridPosition>::hash`, `pair_int_hash(row, column)`, and
the defaulted `operator==`).
### Where paths stop (other regions' stubs)
Grid items that are tables (r48, `TableWrapper`), `<svg>` (r55/r49), form controls (r24, r25), and list item markers
(r53's `MarkerPaintable`). Of the 187 Layout tests whose first stop was the GridFormattingContext, all 187 now pass;
`grid/floating-table-wrapper-width` and `grid/svg-width-only-stretches-height` (which stopped earlier, in the tree
builder) wait for r48 and the SVG regions.
## Deviations and notes
- C++ lambdas are functions: `resolve_grid_item_sizes`' `try_compute_size`, `calculate_inner_size` and
`tentative_size_for_replaced_element`; `get_grid_area_rect`'s `place_into_track` and
`place_into_track_formed_by_last_line_and_grid_container_padding_edge` (they write the rectangle through a pointer);
`resolve_abspos_containing_block_info`'s `grid_area_rect`, `explicit_line_position`, `augmented_grid_padding_edge` and
`override_mixed_auto_axis`; `expand_flexible_tracks`' `find_the_size_of_an_fr` and `flex_fraction`;
`maximize_tracks_using_available_size`'s `get_free_space_px`; the matchers and `item_size_contribution` of the
spanning-item steps; `dominated_by_available_size`; `run`'s `serialize`; `init_grid_lines`' recursive
`expand_lines_definition`; the contributions' `should_treat_preferred_size_as_auto`.
- `initialize_grid_tracks_for_columns_and_rows` repeats the same steps for columns and rows; both halves are one
function over the dimension (`..._initialize_grid_tracks_for_dimension`), called in the same order.
- C++ mixes `int` and `size_t` in placement (`row_count() + end + 2`, `end - span`, `cursor += span - 1`,
`item_index + span`, `nth_line - 1`): the size_t arithmetic wraps and converts back to int, spelled with `+%`/`-%` on
usize and an `(i32)` cast. `max(0, count - 1)` is `AK::max<int>`.
- `CSSPixels / size_t` is a CSSPixelFraction over `CSSPixels(Unsigned)` read back as CSSPixels
(`layout_grid_formatting_context_div_count`); `CSSPixels / int` is `layout_div_int`. The used flex fraction stays a
CSSPixelFraction until it scales a flex factor, as in C++; `AK::max` of two fractions is
`layout_grid_formatting_context_max_fraction`.
- `place_grid_items`' `remove(i); i--;` loops keep the index where they remove; its two unread copies of
grid-template-columns/rows are left out (noted in place), as is `calculate_minimum_contribution`'s unread
`preferred_size`.
- `init_grid_lines` clones the pending line names before appending them, since `Vector::clear` frees the buffer the copy
would share (DESIGN §3.3 rule 2); `tracks_to_grow_beyond_limits = affected_tracks` clones too.
- `HashMap<GridTrack*, CSSPixels>` iterates in pointer-hash order, which does not change the result (each track is
updated on its own).
- HANDOFF (luce-js HANDOFF.md §5 item 4) follow-ups: all were done by earlier regions (r44, r45 list them).
- `--update-failures` writes the trap messages' absolute paths, so ref.txt's notes for the `.xht` reference failures
now name this worktree (`luce-browser-engine-r47`) where they named r51b's; only the notes changed.
## Tests
- web_test (Ladybird's Layout/Ref/Crash tests): Layout 427 → 614 passing of 845 (all 187 Layout tests that stopped at
the GridFormattingContext pass, among them all of `Layout/input/grid` but the two above), Ref 352 → 367, Crash 23 → 25;
no new failures. `tests/expected_failures` rewritten with `--update-failures`.
- `layout/tests_layout_grid_cases` (203 cases) + `layout/tests_layout_grid`, from the local oracle
`luce-browser-tools/oracles/luce-browser-engine/layout_geometry` (`cases_grid.txt`, `own_grid_cases.py`,
`./oracle cases_grid.txt > expected_grid.txt`, `python3 gen_luce_cases.py grid`,
`compare_ladybird.py --full cases_grid.txt expected_grid.txt`), with tests_layout_geometry's harness (layout, commit,
the three dumps):
- 180 are Ladybird's Layout tests whose first stop was the GridFormattingContext (`from_ladybird.py`); the oracle
reproduces 179 of their whole expected files (`grid/grid-template` moves a `<style>`), and the port matches the
oracle on all 180. The 7 grid tests r46 had marked as waiting for grid in `cases_flex.txt` are unmarked there (and
left out of `cases_grid.txt`); `tests_layout_flex_cases` now has 171 cases, all matching.
- 23 are written for this region (each a document with many grids): fixed/percentage/calc tracks and gutters, fr
tracks in definite and indefinite containers (inline-grid, float, abspos, min-/max-content widths), intrinsic and
fit-content() and minmax() tracks, spanning items, line numbers (negative, implicit, reversed, two spans), named
lines, template areas, auto-flow (row/column, dense, mixed definite columns, order), auto-fill/auto-fit (gaps,
minmax, named lines in the repeat, collapsing), every justify-content/align-content with fixed and auto tracks,
justify-items/align-items and justify-self/align-self values and auto margins, item sizes (fit-/min-/max-content,
percentages, box-sizing, aspect ratios), automatic minimum sizes (scroll containers, min-width:0, spanning items),
container min/max sizes, abspos children in the augmented grid, nested grids and flex, box model items, large grids,
quirks. All match.
- A mutation check (space-around gutters divided by count + 2) fails 2 grid cases and 1 flex case.
- `OccupationGrid` unit test: sizes (including `OccupationGrid(0, 0)`), occupied cells and areas, negative indexes, and
the auto-placement search in both flows, pinned to the C++ logic.