dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r34.md
# Region r34: CSS style values I — what other regions need to know
Region r34 ports `CSS/StyleValues/StyleValue` (the base class, its `is_*`/`as_*` and helpers) and
the leaf and composite style values of phase 1: keywords, custom idents, strings, integers,
numbers and the dimensions (angle, flex, frequency, length, percentage, resolution, time),
`StyleValueList`, `ShorthandStyleValue`, the colors (`ColorStyleValue`, `ColorFunctionStyleValue`,
`ColorMixStyleValue`, `LightDarkStyleValue`, `ColorSchemeStyleValue`,
`ColorInterpolationMethodStyleValue`), the images (`AbstractImageStyleValue`, `ImageStyleValue`,
`ImageSetStyleValue`, `CursorStyleValue`, the linear, radial and conic gradients,
`RadialSizeStyleValue`), positions and edges, rects and radii, shadows, tuples, `URLStyleValue`,
`UnresolvedStyleValue`, `PendingSubstitutionStyleValue`, `GuaranteedInvalidStyleValue`,
`UnicodeRangeStyleValue`, `RandomValueSharingStyleValue`, `ComputationContext` and the rest of
the region's 62 donor files. The stub fragment `stubs/stub_r34_style_values_1.lucb` is gone;
every one of its 853 functions is ported.
## Fragments
| Fragment | Donor |
| --- | --- |
| `css/style_values/style_value_1` | `StyleValue.cpp`/`.h`: construction, to_string, the CSS-wide keyword checks, tokenize, reify, subdivide, `int/number/string_from_style_value`, `ColorResolutionContext` |
| `css/style_values/style_value_2`, `style_value_3` | the `is_*` and `as_*` of `StyleValue.h` (mechanical) |
| `css/style_values/shorthand_style_value_1` … `_3` | `ShorthandStyleValue.cpp`: creation, longhands and equality (1); `serialize` split into one function per shorthand group: background … fonts (2), grid, mask, text, white-space (3) |
| `css/style_values/<class>` | one fragment per style value class (`keyword_style_value`, `color_function_style_value`, `linear_gradient_style_value`, …) |
| `html/supported_image_types` | `HTML/SupportedImageTypes.cpp` (`html_is_supported_image_type`; the skeleton missed the file; namemap row added) |
| `css/style_values/tests_style_values_1_values`, `tests_style_values_1`, `tests_style_values_1_2`, `tests_style_values_1_expected` | the oracle test (below) |
## What other regions must know
### Constructing and classes
- Every class has `css_<class>_create(...)` (the C++ `create`) and `css_<class>_construct(this,
...)`. `create` allocates with plain `alloc` in the current allocator, so under `with heap` a
style value is a **heap blob** (r37's `css_weak_image_style_value` relies on this; r32's
parser should create values only through these `create`s).
- The most-derived constructor installs the vtable and class id with
`css_style_value_set_class(this, (const CssStyleValueVTable*)&X_vtable, &X_class)`; a subclass
constructor calls its base's `construct` first, then `set_class`.
- Statics (`LengthStyleValue` 0px/1px, the CSS-wide keyword `KeywordStyleValue`s,
`GuaranteedInvalidStyleValue`) are module vars created once `with memory.heap` (the C heap),
so they outlive any test heap and are compared by pointer like the C++ singletons.
### Equality
- `ValueComparingNonnullRefPtr ==` is `css_style_values_equal`, `ValueComparingRefPtr ==` is
`css_optional_style_values_equal` (r36); `NonnullRefPtr ==` compares pointers.
- The CRTP `StyleValueWithDefaultOperators::equals` is ported per class as `<class>_equals_impl`
(type check + `properties_equal`); the generic template's namemap row is removed.
- Shared pub helpers: `css_style_value_vectors_equal` (style_value_list),
`css_optional_fly_strings_equal`, `css_appendff(builder, fmt, args)` (style_value_1), and the
color-stop helpers in abstract_image_style_value (`css_color_stop_lists_equal`,
`css_color_stop_list_absolutized`, …).
### Signatures and types changed from the stubs
- `css_anchor_size_style_value_anchor_name` and `css_anchor_style_value_anchor_name` return
`ak.FlyString?` (was `const ak.FlyString*?`; no callers outside the region).
- `types_color_function_style_value`: the anonymous `ResolvedChannels` struct is
`CssResolvedChannels` (namemap updated). `types_color_mix_style_value`: `NormalizedPercentages`
and `PercentageNormalizationResult` filled in. `types_image_set_style_value`: `Option` filled
in. `generated/types_traits`: `CssRandomCachingKeyTraits` calls
`css_random_caching_key_hash`/`_equals`.
- C++-private and internal-linkage functions are module-private.
- Added to `stubs/stub_closure` (section "CSS Typed OM", phase 3): opaque `CssKeywordValue`,
`CssImageValue`, `CssTransformValue` and the `create`s `StyleValue::reify` and its overrides
call (`css_css_style_value_create`, `css_keyword_value_create`, `css_image_value_create`,
`css_unparsed_value_create`, `css_variable_reference_value_create`,
`css_transform_value_create`).
### Where phase-1 paths stop now (other regions' stubs)
- `ShorthandStyleValue::serialize` for most shorthands reaches r39's
`for_each_property_expanding_shorthands` and r12c's `property_initial_value`, so the test
covers only its coordinating-list and longhand paths.
- `reify` reaches the phase-3 Typed OM stubs; image loading reaches the Fetch/resource stubs.
## Deviations and notes
- Lambdas are private functions with capture structs. `ImageStyleValue::load_any_resources`'
`weak_callback(*this, …)` captures a `gc.Weak` to the value's blob via r37's
`css_weak_image_style_value`.
- `CursorStyleValue::make_image_cursor` paints with the CPU display-list player
(DESIGN.md §7.3), not Skia.
- `AK::min`/`max` on doubles keep their semantics (`ak.min_f64`/`max_f64`); HWB clamps in
double then converts to f32, as C++ does.
## Tests
- `tests_style_values_1*`: a local oracle
(`luce-browser-tools/oracles/luce-browser-engine/style_values_1`: `oracle.cpp` links the
reference build's LibWeb objects, `build.sh`, `expected.txt`, `gen_luce_expected.py` writing
`tests_style_values_1_expected.lucb`) builds ~170 values of every class and prints their
serializations (normal and resolved), flags, computational independence, colors (light and
dark), absolutized values, the full equality matrix plus separately built equal values,
tokenization, the helpers and statics, `is_color` over all 850 keywords, supported image
types, lists, subdivision, longhands, radii, edges, gradient angles and radial sizes. The Luce
dump matches all 1303 lines. Cases whose C++ VERIFYs (edges without offsets, tuples with nulls,
…) are skipped for independence on both sides; the radial box with zero width is 1x50
(division by zero is UB in C++ and traps in Luce).
## Compiler issues
None found.