Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r48.md

# Region r48: table layout — what other regions need to know

Region r48 ports `Layout/TableFormattingContext`, `Layout/TableGrid` and `Layout/TableWrapper` (`.cpp` and `.h`). The
stub fragment `stubs/stub_r48_layout_table.lucb` is gone, and so is r43's `layout/table_grid_predicates.lucb` (its three
predicates moved into `layout/table_grid`, in TableGrid.h's order). A `display: table | inline-table` box is now
wrapped in its TableWrapper and laid out by the table formatting context: forming the table grid
(https://html.spec.whatwg.org/multipage/tables.html#forming-a-table), border conflict resolution in the collapsing
border model, cell measures, the column and row measures over spanning cells with their intrinsic percentages, CAPMIN,
GRIDMIN/GRIDMAX and the used table width, the width distribution algorithm and the excess width rules in auto and fixed
mode, the two passes of the table height, the distribution of the table height to the rows, the positions of rows, row
groups and cells with vertical alignment, captions above and below, and the absolutely positioned descendants.

## Fragments

| Fragment | Donor |
| --- | --- |
| `layout/table_grid` | `TableGrid.h` (the inline members, the predicates, `for_each_child_box_matching`) and `TableGrid.cpp` 1-174 |
| `layout/table_wrapper` | `TableWrapper.cpp` 1-25 and `TableWrapper.h` |
| `layout/table_formatting_context_1` | `TableFormattingContext.h`'s inline members and `.cpp` 1-467: construction, the wrapper's containing block, captions, constrainedness, cell measures, outer content sizes, `initialize_table_measures`, `compute_intrinsic_percentage`, `compute_table_measures` |
| `layout/table_formatting_context_2` | 469-905: CAPMIN, `width_is_auto_or_indefinite_percentage`, `compute_table_width`, the sizing-guesses, the excess width distribution (auto and fixed mode) |
| `layout/table_formatting_context_3` | 907-1274: `compute_table_height`, `distribute_height_to_rows`, `position_row_boxes`, `position_cell_boxes`, `use_fixed_mode_layout` |
| `layout/table_formatting_context_4` | 1276-1702 and the header's BorderConflictFinder: border conflict resolution, `compute_row_content_height`, `finish_grid_initialization` |
| `layout/table_formatting_context_5` | 1704-1992: `run_until_width_calculation`, `parent_context_did_dimension_child_root_box`, `run`, the automatic content sizes, the RowOrColumn specializations, border spacing, `calculate_static_position_rect` |
| `layout/tests_layout_table_cases`, `layout/tests_layout_table` | tests (below) |

## What other regions must know

### Construction

`FormattingContext::create_independent_formatting_context_if_needed` and `compute_table_box_width_inside_table_wrapper`
(r44) make the context with `layout_make_formatting_context_storage[LayoutTableFormattingContext]()` and
`layout_table_formatting_context_construct`. `~TableFormattingContext` is the default destructor; the contexts the table
formatting context gets from `create_independent_formatting_context_if_needed` (captions) and `layout_inside` (cells)
are destructed where C++ drops them (`defer layout_formatting_context_destruct(...)`), as r44 asks.

### Signatures changed from the stubs

- **The templates over RowOrColumn take a `LayoutTableDimension`** (TableFormattingContext.h's own enum) instead of a type
  parameter, since a generic body cannot specialize on its type: `compute_table_measures(this, dimension)`,
  `compute_intrinsic_percentage(this, dimension, max_cell_span)`, `initialize_intrinsic_percentages_from_cells(this,
  dimension)`. The specializations keep their stub names (`cell_span_row`, `..._column`, `table_rows_or_columns_row`,
  ...); a function without the suffix chooses between them, and `layout_table_formatting_context_table_row_or_column(this,
  dimension, index)` answers a `LayoutTableFormattingContextRowOrColumn` (pointers to the members `min_size`,
  `max_size`, `has_intrinsic_percentage`, `intrinsic_percentage` that Row and Column share).
- `Cell const&` / `ConflictingEdge const&` parameters are `const LayoutTableGridCell*` /
  `const LayoutTableFormattingContextConflictingEdge*` (the stubs took them by value); `winning_conflicting_edge` answers
  a copy of the winner; `finish_grid_initialization` takes `const LayoutTableGrid*`; `commit_candidate_column_widths` and
  `assign_columns_width_linear_combination` take `const ak.Vector[gfx.CssPixels]*`.
- The column filters and base width getters of the `distribute_excess_width_*` templates are function pointers over a
  `const LayoutTableFormattingContextColumn*`.
- `layout_table_grid_for_each_child_box_matching(_2)[TCallback: LayoutTableGridChildBoxCallback](parent, matcher:
  func(LayoutNode*) -> bool, callback: TCallback*)`: the callback is a capture struct conforming to the new interface
  `LayoutTableGridChildBoxCallback` (`mutating func call(child_box: LayoutBox*)`). r43's two fixup structs in
  `tree_builder_3` now declare that conformance. The `_2` overload (C++'s non-const one) calls the first. The table
  formatting context and the grid walk the same children with the loop `for child_box in
  layout_table_grid_child_boxes_matching(parent, matcher)` (DESIGN §2.9).
- The file-static `is_table_column_group` / `is_table_column` of TableFormattingContext.cpp take a `LayoutNode*` (they
  are only used as matchers, always with a Box).
- Private members and file-static functions are module-private. Public: the constructor, the overrides,
  `run_until_width_calculation` (r44's table wrapper width), `table_box`, `table_wrapper`, `border_is_less_specific`
  (r52's TableBordersPainting), `calculate_static_position_rect`, and TableGrid's and TableWrapper's functions.

### Types filled by hand

`types_table_grid` (Row, Cell), `types_table_formatting_context` (Column, ConflictingEdge, and the new ConflictingSide,
BorderConflictFinder with its RowGroupInfo, and RowOrColumn), and `generated/types_traits`'s
`LayoutTableGridGridPositionTraits` (`pair_int_hash` of the coordinates, structural equality). Namemap rows are updated
or added for all of them and for the BorderConflictFinder's methods and the lambdas that became functions.

### Where paths stop (other regions' stubs)

- Grid containers around and inside tables are r47's (merged). Of the 113 Layout tests
  whose first stop was the TableWrapper, 108 passed with r48 alone; with r47 merged all 113 pass.
- Form controls in cells, `<svg>` in cells: their regions (r24, r25, r55).

## Deviations and notes

- C++ lambdas are functions: TableGrid's `process_row` (its by-reference captures are
  `LayoutTableGridCalculateRowColumnGridLocals`), `compute_capmin`'s `outer_size_for_inner_size`, `position_cell_boxes`'
  `cell_is_anonymous_wrapper_for_flex_or_grid`, the excess width filters and getters, and `border_is_less_specific`'s
  static `line_style_score` HashMap (a `match`; a missing style traps as `*get()` would VERIFY).
- `border_conflict_resolution`'s four identical per-side blocks call one helper
  (`layout_table_formatting_context_winning_edge_of_cell_side`), in the same order.
- `CSSPixels * size_t` and `CSSPixels / size_t` convert the count with CSSPixels(Unsigned), which saturates
  (`layout_table_formatting_context_mul_count` / `_div_count`); `CSSPixels / int` is `layout_div_int`; `double *
  CSSPixels` and `CSSPixels / double` are doubles, as in C++. `get_col_element(column_index - column_span)` wraps as
  size_t arithmetic does (`-%`).
- The empty `if (cell_grows_downward) { }` of the grid's step 15 is a FIXME comment.
- HANDOFF (luce-js HANDOFF.md §5 item 4) follow-ups: all were done by earlier regions (r44, r45 and r33 list them).

## Tests

- `layout/tests_layout_table_cases` (145 cases) + `layout/tests_layout_table`, from the local oracle
  `luce-browser-tools/oracles/luce-browser-engine/layout_geometry` (extended: `cases_table.txt`, `own_table_cases.py`,
  modes `table` and `border-specificity` in `oracle.cpp`, `./oracle cases_table.txt > expected_table.txt`,
  `python3 gen_luce_cases.py table`, `compare_ladybird.py --full cases_table.txt expected_table.txt`).
  - 113 are Ladybird's Layout tests whose first stop was the TableWrapper (`from_ladybird.py`); the oracle reproduces
    all 113 of their whole expected files, and the port matches all 113 (5 of them need r47's grid layout).
  - 29 `layout` cases written for this region, each a document with many tables: auto layout with text, percent and
    constrained columns, columns without originating cells, fixed layout (lengths, percentages, intrinsic widths,
    `<col>`), colspan and rowspan contributions with border spacing, table heights (auto, specified, percentages,
    border-box) and row heights, border spacing, collapsed borders (widths, every style, hidden/none, colors, rows, row
    groups, cols, colgroups, spans), captions (both sides, boxes, CAPMIN, widths, size containment), every
    vertical-align keyword and lengths, row groups out of order, `visibility: collapse`, anonymous table parts, cells
    with flex, table width keywords and min/max, tables in floats, inline-blocks, intrinsic containers, flex
    containers, abspos, margins and `align`, nested tables, `<col>`/`<colgroup>` widths, positioned boxes in tables,
    presentational hints, quirks mode, and grid edge cases (rowspan 0, spans past the end, overlaps). All match.
  - 2 `table` cases (TableGrid::calculate_row_column_grid of every table: rows, cells, spans and the occupied slots in
    the AK HashMap's iteration order, which pins GridPosition's hash) and 1 `border-specificity` case
    (`border_is_less_specific` over 30 × 30 borders). All match.
- Mutation checks (dividing excess width by one column too many, a wrong line style score, middle alignment by 3, the
  normalized min-content contribution dropped) fail 9, 1, 43 and 1 cases.
- r43's layout tree case with `display: table` (marked `!` for r48) is unmarked and passes.

## web_test

Before (main at 6b18042) → r48 alone: Layout 427 → 535 passing (+108), Ref 352 → 373 (+21; the other 2 that stopped at
the TableWrapper need P2's XHTML loading), Crash 23 → 26 (+3). Merged with r47 (main at f813a91): Layout 727, Ref 388,
Crash 28. `tests/expected_failures/*.txt` were rewritten with `--update-failures`, after the runner's notes were made
relative to the repository root (r57.md).