Luce packages
LuceLuce BaseLuciaOS

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.