Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / docs / regions / r36.md

# Region r36: CSS values and units — what other regions need to know

Region r36 ports `CSS/Angle`, `CalculationResolutionContext`, `Clip`, `ColorFunctionDescriptor`,
`ColorInterpolation`, `ColumnCount`, `CounterStyle`, `CounterStyleDefinition`,
`DescriptorNameAndID`, `Display`, `EdgeRect`, `Fetch`, `Filter`, `Flex`, `Frequency`,
`GridTrackPlacement`, `GridTrackSize`, `Length`, `LengthBox`, `NumericRange`, `Percentage`,
`PercentageOr`, `PropertyName` (`is_a_valid_css_property`; the other two are css_data's),
`PropertyNameAndID`, `Ratio`, `Resolution`, `Size`, `Sizing`, `SystemColor`, `Time`, `URL` and
`ValueType`, and the generated `DefaultStyleSheetSource`, `QuirksModeStyleSheetSource`,
`GeneratedCSSNumericFactoryMethods` and `Parser/GeneratedValueTypesParsing`. The stub fragment
`stubs/stub_r36_css_values_units.lucb` is gone. Every function is ported except
`PercentageOr<T>::resolved(Layout::Node const&, T)`, which `requires(!IsSame<T, Length>)` and so
is never instantiated (namemap row removed).

## Fragments

| Fragment | Donor |
| --- | --- |
| `css/angle`, `flex`, `frequency`, `resolution`, `time`, `percentage`, `ratio`, `numeric_range` | the dimension types (.cpp + .h) |
| `css/length` | `Length.cpp/.h`: Length, FontMetrics, ResolutionContext, LengthOrAuto |
| `css/percentage_or` | `PercentageOr.h`: PercentageOr, LengthPercentage, LengthPercentageOrAuto |
| `css/length_box`, `size`, `sizing`, `clip`, `edge_rect`, `column_count`, `filter`, `calculation_resolution_context` | the box and size values |
| `css/display` | `Display.cpp/.h` |
| `css/grid_track_placement`, `grid_track_size` | the grid values |
| `css/counter_style_1`, `counter_style_2`, `counter_style_definition` | `CounterStyle.cpp` (1-197, 199-694), `CounterStyleDefinition.cpp` |
| `css/color_function_descriptor`, `color_interpolation_1`, `color_interpolation_2` | `ColorFunctionDescriptor.cpp`, `ColorInterpolation.cpp` (1-520, 522-1010) |
| `css/system_color`, `value_type`, `property_name`, `property_name_and_id`, `descriptor_name_and_id`, `url`, `fetch` | the rest |
| `generated/default_style_sheet_source`, `quirks_mode_style_sheet_source` | **tools/embed_css** (new; port of `embed_as_string.py`) from `data/css/Default.css`, `QuirksMode.css` |
| `generated/generated_css_numeric_factory_methods` | tools/gen_css_values `emit_numeric_factory_methods` from `data/css/Units.json` |
| `generated/generated_value_types_parsing` | tools/gen_css_values `emit_value_types_parsing` from `data/css/ValueTypes.json` (ports the Python generator and `Meta/Utils/CSSGrammar`); replaces r30b's hand-written `css/parser/generated_value_types_parsing` |
| `css/tests_css_values_units_1`, `_2`, `_3`, `_expected` | tests (below) |

test.sh checks tools/embed_css and regenerates and compares its fragments with gen_css_values'.

## What other regions must know

### Values, constructors and equality

- Every value type has a `css_<type>_new(...)` that makes it as a value (`css_length_new(1.5,
  .em)`, `css_angle_make_degrees`, `css_length_or_auto_new(length)`, `css_display_new(outside,
  inside)`, `css_display_new_list_item`, `css_display_new_display_box/_internal`,
  `css_grid_size_new`, `css_explicit_grid_track_new`, `css_missing_components_new`,
  `css_component_categories_new`, …). LengthPercentage's inherited constructors are
  `css_length_percentage_new_css_length/_css_percentage/_css_calculated_style_value`;
  `css_length_percentage_or_auto_new(length_percentage)`.
- C++ `operator==`s that Luce's structural `==` cannot give (a String, a FlyString, a style
  value compared by value, a variant) are functions: `css_length_eq` … (as stubbed), and for the
  defaulted ones `css_size_eq`, `css_length_box_eq`, `css_length_percentage_or_auto_eq`,
  `css_grid_size_eq`, `css_grid_min_max_eq`, `css_grid_repeat_eq`, `css_explicit_grid_track_eq`,
  `css_grid_line_names_eq`, `css_grid_track_placement_eq`, `css_counter_style_algorithm_eq`,
  `css_counter_style_negative_sign_eq`, `css_counter_style_pad_eq`, `css_counter_style_ranges_eq`.
  `ValueComparingNonnullRefPtr`/`ValueComparingRefPtr<StyleValue const>`'s `==` (same pointer or
  `StyleValue::equals`) is `css_style_values_equal` / `css_optional_style_values_equal`.
  Length, LengthOrAuto, EdgeRect, FontMetrics, ResolutionContext, Display (use `css_display_eq`
  for the union) compare with `==` where their fields allow it.

### Signature and type changes

- `CssPercentageOr[T].m_value` is `CssPercentageOrValue[T]` (`.t`, `.css_percentage`,
  `.css_calculated_style_value`; types_percentage_or). PercentageOr has one instantiation,
  `PercentageOr<Length>` (Ladybird's own FIXME): the members that use T's operations take
  `const CssPercentageOr[CssLength]*` — `css_percentage_or_to_px`, `_resolved_css_pixels`,
  `_serialize`, `_to_string`, `_eq` and the free `css_eq_*`; the variant-only members stay
  generic. A LengthPercentage is `lp.percentage_or`. CssPercentageOr (and so CssLengthPercentage,
  ComputedValues' structs holding one) is not zeroable: build one with the constructors.
- `css_counter_style_from_counter_style_definition(definition: const CssCounterStyleDefinition*,
  style_scope: const CssStyleScope*)` and `css_generate_a_counter_representation(counter_style,
  style_scope: const CssStyleScope*, value)` (C++ `const&`; the stubs took copies).
- `css_calculation_resolution_context_from_computation_context(..., percentage_basis = .empty)`
  and `css_ratio_construct(this, first, second = 1.0)` have the C++ defaults.
- The embedded sheets are `str` constants: `css_default_stylesheet_source`,
  `css_quirks_mode_stylesheet_source` (C++ `String`; make one with `ak.string_from_str`). r39's
  `StyleComputer::user_agent_style_sheet_source` uses them.
- C++-private and internal-linkage functions are module-private (`resolve_*` of
  CounterStyleDefinition, Fetch's helpers, ColorInterpolation's steps).
- Types filled: `CssAdditiveCounterStyleAlgorithmAdditiveTuple { weight, symbol }`; the four
  numeric ranges are `let` constants with their real values (they were zero `var`s);
  `css_color_type_count` is the constant 16; `CssAbsolutizesToRgb` is `as u8` with `yes = 1` (the
  generator mapped the `enum class : bool` to i64 with `yes = -1`); the ColorInterpolation
  `init_fields` set their defaults; `CssDescriptorNameAndIdTraits` hashes and compares.
- Added (fetch types_requests) `FetchRequestMode` and `FetchRequestInitiatorType`; added phase-2
  stubs to stubs/stub_closure for what Fetch.cpp and URL.cpp call (`fetch_request_create`, the
  Request setters, `fetch_request_mode`, `fetch_request_url`, `fetch_algorithms_create`,
  `fetch_fetching_fetch`) and the phase-3 `css_unit_value_create` for the numeric factories.

### Statics

`CounterStyle::decimal()`/`disc()`'s statics are module variables made in the C heap (`with
memory.heap`), as r30b's ErrorReporter: the collector neither scans nor sweeps module data.
`s_color_function_descriptors` is built on first use (it holds only scalars and views of
literals).

### Where phase-1 paths go now

`PropertyNameAndID::from_name`, `DescriptorNameAndID`, `value_type_from_string` and the
generated value-type parsers no longer trap; the paths behind them reach r32/r33's value
parsers, r34/r35's style values (`StyleValue::is_*`/`as_*`, `CalculatedStyleValue::resolve_*`),
r39's StyleScope and r43's layout nodes. Fetch reaches the phase-2 stubs.

## Deviations and notes

- `ColorFunctionDescriptor::build_color_function_descriptors` fills the static table through a
  span instead of returning it (`# LUCE-BUG: local_array_of_views_returned_by_value`).
- Counter representations keep C++'s unsigned arithmetic where an i64 value meets a size_t
  (`(value - 1) % symbol_list.size()`), and `difference -= size_t` truncation.
- GridTrackSizeList::append(GridLineNames) appends to the last names in place; here the updated
  names are stored back into the list. `absolutized` clones the copied names (DESIGN §3.3 rule 2).
- PropertyNameAndID::name caches through a cast (`m_name` is `mutable`).
- Size::from_style_value's `dbgln` prints through `ak.dbgln`.

## Tests

- `tests_css_values_units_1`/`_2` build a 1,095-line dump and compare it line by line with
  `tests_css_values_units_expected`, the output of the local oracle
  `luce-browser-tools/oracles/luce-browser-engine/css_values_units` (`oracle.cpp` over the
  reference build's LibWeb, including `ColorInterpolation.cpp` to reach its internal helpers;
  `build.sh`; `gen_luce_expected.py` writes the expected fragment). It covers every length unit
  (flags, serialization in both modes, to_px with viewport and font metrics, absolutize) and the
  other dimensions, percentages, ratios, the numeric ranges, every display keyword and short
  display, the system colors, the default sizing algorithm (126 cases), edge rects, sizes,
  length-percentages, length boxes, grid line names and track lists, counter styles (every
  algorithm and extended CJK style over 34 values, decimal/disc, padding and negative signs,
  auto ranges), ColorInterpolation's conversions, missing-component carrying, powerless
  components, premultiplication and hue fixups, the color function table, value types, property
  and descriptor names (with the Traits hash), URLs and request modifiers, and the embedded style
  sheets' sizes and FNV hashes. All match.
- `tests_css_values_units_3`: definitions made into counter styles, Clip, ColumnCount, Filter,
  the ranges' exact limits, the cached property name, the sheets' text.
- Ladybird has no unit tests for these files (TestCSSPixels.cpp is luce-browser-render's).

## Compiler issues

`luce-browser-tools/compiler-issues/local_array_of_views_returned_by_value.lucb`: returning a
local array by value is rejected ("this pointer or view names a local and must not escape")
when its element type holds a view, even of string literals; the same struct returned alone is
accepted. Worked around in ColorFunctionDescriptor (above).