dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r40.md
# Region r40: ComputedProperties, ComputedValues, StyleProperty — what other regions need to know
Region r40 ports `CSS/ComputedProperties.cpp/.h` (the property store and its ~150 typed readers),
`CSS/ComputedValues.h` (the value structs, `InitialValues`, `ComputedValues`' readers and
`MutableComputedValues`' setters) and `CSS/StyleProperty.cpp` (3,916 donor lines). The stub
fragment `stubs/stub_r40_computed_properties.lucb` is gone; all 720 of its functions are ported.
## Fragments
| Fragment | Donor |
| --- | --- |
| `css/computed_properties_1` | `ComputedProperties.cpp` 1-422 and the inline members of `ComputedProperties.h`: the store (value array, important/inherited/animation flag bits), animated values, `property()`, revert, and the readers up to `opacity` |
| `css/computed_properties_2` | 422-890: SVG fill/stroke, flex, order, background layers, border-spacing, clip, box alignment, transforms, accent-color, appearance, filters, position |
| `css/computed_properties_3` | 891-1398: operator==, the text readers, `content` (quotes, counters, alt text), cursor, visibility, display, decorations, list-style, overflow, shadows, text-indent |
| `css/computed_properties_4` | 1400-1898: fonts (font-variant-*, feature and variation settings), grid, tables, writing modes, touch-action, contain, container-type |
| `css/computed_properties_5` | 1900-2355: animations, transitions, quotes, counters, scrollbars, paint-order, will-change, the cached font list and first available font, the font and math readers |
| `css/computed_values_1` … `_6` | `ComputedValues.h`: the small structs and the default-constructing helpers (1), InitialValues (1-2), SVGPaint/MaskReference/ClipPathReference/TouchActionData/ContentData/BorderRadiusData/to_gfx_scaling_mode (2), ComputedValues' construction and readers (3-4), MutableComputedValues (5-6) |
| `css/style_property` | `StyleProperty.cpp` |
| `css/tests_computed_properties_cases`, `tests_computed_properties`, `tests_computed_properties_2` | tests (below) |
Ladybird does not generate `ComputedValues.h` (InitialValues and the accessors are hand-written C++),
so it is ported as hand-written Luce; there is nothing for `tools/gen_css_values` to generate.
## What other regions must know
### Constructing
- `css_computed_values_create()` is `make<ComputedValues>()`: a managed `CssComputedValues` with every
default member initializer applied (`css_computed_values_construct(this)` on existing storage).
Layout (r43) builds its nodes' ComputedValues with it; `CssMutableComputedValues*` and
`CssImmutableComputedValues*` are casts of the same storage (the subclasses add no fields).
- The structs that hold a LengthPercentage are not zeroable, so their `init_fields` (types file,
filled here) write **every** field and work on uninitialized storage (`var p: CssPosition = ---;
css_position_init_fields(&p)`). Value helpers for `T {}`: `css_position_new`,
`css_transform_origin_new`, `css_shadow_data_new`, `css_border_radius_data_new`,
`css_touch_action_data_new` (all six touch-action flags true: the generator had dropped the
bit-fields' `{ true }`, now in `css_touch_action_data_init_fields`).
- `CssScrollbarColorData` is now an alias of `display_list.ScrollbarColorData`, and
`css_initial_values_scrollbar_color` forwards to `display_list.initial_values_scrollbar_color`
(DESIGN §4.1.3; the luce-js HANDOFF §5 item 4 follow-up).
- ComputedProperties are made by r39's `heap_allocate_css_computed_properties(heap)`;
`css_computed_properties_construct` runs the init fields (display-before-box-type-transformation =
`InitialValues::display()`).
### Signatures changed from the stubs
- `css_computed_properties_for_each_property[TCallback: CssComputedPropertiesPropertyCallback](this, callback: TCallback*)`:
the interface has `mutating func call(property_id, value: CssStyleValue*)`; Dump's
`DumpTreeComputedProperty` (dump_1) now declares conformance.
- `css_computed_properties_list_style_type(this, style_scope: const CssStyleScope*)` (r39 passes
StyleScope by pointer); dom/element_2's call is updated.
- `css_computed_values_font_list(this) -> const web_fonts.FontCascadeList*` (C++ returns a
reference; the stub copied the struct) and `css_mutable_computed_values_inherit_from(this,
other: const CssComputedValues*)` (C++ `const&`; ComputedValues is not copyable). No callers yet.
- Added to `stubs/stub_closure` (phase 4, for `animations()`'s `scroll()` timeline):
`BindScrollAxis`, `AnimationsScrollTimelineAnonymousSource`, `animations_scroll_timeline_create`
(answers the base `AnimationsAnimationTimeline*`) and `animations_css_axis_to_bindings_scroll_axis`.
### Where the readers stop now (other regions' stubs)
- `color_scheme` reaches r42's `preferred_color_scheme_to_string`/`from_string`.
- `font_variant_alternates` with `stylistic()`/`styleset()`/... reaches r41's
`font_feature_value_type_from_string`; `computed_font_list` reaches r41's FontComputer.
- `animations` and `transitions` reach the phase-4 `EasingFunction::from_style_value` (r39's closure
stub) and, for `scroll()`, the ScrollTimeline stubs above. The phase-4 timeline types are opaque,
so `document.timeline()` (a DocumentTimeline) is cast to `AnimationsAnimationTimeline*`.
- `caret_color`, the shadows and `scrollbar_color` reach r43's layout nodes
(`ColorResolutionContext::for_layout_node_with_style`, `computed_values()`); `content` with
counters reaches r39's counters; `Position::resolved` reaches `PercentageOr::to_px` (layout).
## Deviations and notes
- Donor behaviours kept (commented): `ComputedValues::rx()` answers `m_noninherited.ry`;
`position_value` (object-/perspective-origin) sets only the offsets, so the edges stay left/top;
`visibility()` of a non-keyword answers `Visibility {}` (collapse, the enum's zero);
`transitions()` expands a shorthand's longhands twice (`ensure_capacity` and the loop).
- C++ copies the inherited values in `inherit_from`/`clone_inherited_values`; the port copies the
struct, sharing the Vectors' and HashMap's buffers (DESIGN §3.3 rule 2 would clone them): the
C++ API only ever replaces those containers (setters) and hands out const references, so sharing
is not observable. A caller that mutates a returned container must clone it.
- `Vector::contains_slow` over WillChange's variant entries and over `Vector<String>` with a
StringView are small private loops; `first_matching` uses `ak.vector_first_matching_const`.
- `dbgln` of unsupported `content`/`contain`/`container-type` items prints through `ak.dbgln`.
## Tests
- `tests_computed_properties_cases` (195 cases) + `tests_computed_properties`: a local oracle
(`luce-browser-tools/oracles/luce-browser-engine/computed_properties`: `oracle.cpp` linking the
reference build's LibWeb objects, `build.sh`, `cases.txt`, `gen_luce_cases.py`) builds a
ComputedProperties from initial values and the case's declarations, computing every longhand with
`StyleComputer::compute_value_of_property` (800x600, 16px font, no element), calls one reader
group and prints the result; one case prints InitialValues and a default ComputedValues. Every
reader the oracle can reach without an element, a layout node or a font computer is covered (font,
sizes, gaps, length boxes, colors, anchor names, text, backgrounds, clip, display, cursor,
tab-size, white-space, spacing, decorations, flex, alignment, appearance, filters, opacities,
overflow, vertical-align, font variants and settings, grid, tables, object-fit/position, writing
modes, touch-action, containment, transforms, SVG, paint-order, will-change, quotes, counters,
math, position/z-index). All match. Eight cases marked `!` run in the oracle only (color-scheme:
r42; font-variant-alternates functions: r41).
- `tests_computed_properties_2` (focused): the flag bits at both ends of the arrays, animated vs
important vs transitioned values, revert, operator==, for_each_property, the pseudo-class bitmap,
`content` with quotes and nesting (worked through from the C++), the mutable setters and the
border-radius flag, inherit_from, clone_inherited_values, the axis reversals, the value structs,
to_gfx_scaling_mode and StyleProperty::operator==.
- r39's `style_computer_values` oracle: its 28 font-size, font-weight and math-depth cases that
waited for InitialValues now run (`tests_style_computer_values_cases` regenerated,
`tests_style_computer_2` runs `compute_font_size/_weight/_math_depth`). All match.
## Compiler issues
None.