dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r32.md
# Region r32: CSS value and gradient parsing — what other regions need to know
Region r32 ports `CSS/Parser/ValueParsing.cpp` (5,818 lines) and `CSS/Parser/GradientParsing.cpp`
(504). The stub fragment `stubs/stub_r32_css_value_parsing.lucb` is gone; every one of its 118
functions is ported.
## Fragments
| Fragment | Donor |
| --- | --- |
| `css/parser/gradient_parsing` | `GradientParsing.cpp`: color stop lists, linear-, conic- and radial-gradient() |
| `css/parser/value_parsing_1` | `ValueParsing.cpp` 1-578: comma-separated value lists, `<declaration-value>`, `<family-name>`, `<urange>` (both overloads) |
| `css/parser/value_parsing_2` | 579-1191: `<integer>`, `<number>`, `<percentage>` and combinations, anchor(), anchor-size(), the dimensions and the static `parse_literal_*_value` helpers |
| `css/parser/value_parsing_3` | 1193-1493: `<'view-timeline-inset'>`, keywords, scroll(), view(), rect(), `[<hue> \| none]`, `[ / <alpha-value> ]` |
| `css/parser/value_parsing_4` | 1495-2080: rgb()/hsl()/hwb()/lab()/oklab()/lch()/oklch()/color(), `<color-interpolation-method>` |
| `css/parser/value_parsing_5` | 2082-2664: color-mix(), light-dark(), `<color>`, `<corner-shape-value>`, counter()/counters(), `<counter-style>`, `<ratio>`, `<string>` |
| `css/parser/value_parsing_6` | 2666-3132: `<image>`, image-set(), `<paint>`, `<position>` |
| `css/parser/value_parsing_7` | 3134-3599: easing functions, url()/src(), border radii, `<radial-size>`, fit-content() |
| `css/parser/value_parsing_8` | 3601-3940: font-style and the font-variant-* values |
| `css/parser/value_parsing_9` | 3942-4417: `<basic-shape>`, CSS-wide keywords, `<custom-ident>`, `<random-value-sharing>`, `<dashed-ident>` |
| `css/parser/value_parsing_10` | 4419-4928: grid breadths, line names, track lists, repeat(), minmax(), `<grid-line>` |
| `css/parser/value_parsing_11` | 4930-5333: math functions (parse a calculation), tree-counting functions, `<if-condition>` |
| `css/parser/value_parsing_12` | 5335-5818: `<opacity-value>`, `<opentype-tag>`, `<font-src>`, resolve_unresolved_style_value, transforms, `parse_value` |
| `css/parser/tests_css_value_parsing_cases`, `tests_css_value_parsing` | tests (Ladybird has none for these files) |
Lambdas are private functions named after their enclosing function, with a context pointer where
they capture; the `GridTrackParser`, `GridRepeatTypeParser`, `GridMinMaxParamParser` and
`ParseFunction` callables are `ak.Function1`s over them.
## What other regions must know
### Signatures
- `css_consume_if_starts_with(str_, start, found: bool*)` (was `found_callback: void*?`, a C++
`auto` lambda that sets its caller's flag) and
`css_parser_parse_color_stop_list(this, tokens, parse_position: ak.Function1[TokenStream*,
CssStyleValue*?])` (was `void*?`, an `auto` lambda). Both are internal to the region.
- The file-static `parse_literal_*_value` helpers and `consume_if_starts_with` are module-private.
- Everything else keeps the stub signature. `css_parser_parse_calculated_value(this,
component_value, context)` takes both by value; build contexts with
`css_calculation_context_accepting(type, range, percentages_resolve_as, resolve_numbers_as_integers)`
(value_parsing_2, private) or by hand as media_parsing_2 does.
### Types filled by hand
- `CssEasingStyleValueLinearStop { output, input }` (types_easing_style_value, r35's file; was
opaque) and `CssPolygonPoint { x, y }` (types_basic_shape_style_value, r35's file; was opaque).
- `CssValueTypeTraits` (generated/types_traits): `Traits<Enum>` hashes the underlying `u8` with
`u32_hash` (AK's `int_hash`) and compares with `==` (it trapped; every CalculationContext's
`accepted_ranges_by_type` needs it).
### Where phase-1 paths stop now (other regions' stubs)
- **r35**: every math function (`CalculatedStyleValue`, the calculation nodes and
`simplify_a_calculation_tree`), `EasingStyleValue`, `BasicShapeStyleValue`,
`TransformationStyleValue`, `FontStyleStyleValue`, `CounterStyleStyleValue`/`CounterStyleValue`,
`GridTrackPlacementStyleValue` and `FontSourceStyleValue` creation. Inputs without a function
token never reach the calc stubs.
- **r33**: `parse_all_as_single_keyword_value` (superellipse(), `<grid-line>` — every input, since
it checks `auto` first — and `<if-condition>`'s `else`), `parse_symbol_value`,
`parse_filter_value_list_value`, `parse_css_value` (resolve_unresolved_style_value) and the
arbitrary-substitution helpers.
- **r41**: `font_format_is_supported`, `font_tech_is_supported`; **r55**: `parse_path_data`
(path()).
## Deviations and notes
- Donor behaviors kept (each commented): parse_scroll_function_value discards whitespace from the
outer stream; parse_random_value_sharing returns without committing its transaction; a color
stop's second position is not checked for failure (the donor tests the pointer to the
variable); "parse a calculation" never takes a lone parenthesized block as the single value
(the donor's `ComponentValue const&` visitor lambda is not selected for the
`NonnullRawPtr<ComponentValue const>` alternative — checked with a small AK program), and a
run `a * b * c` becomes nested products (the run's end is only updated on a non-operator).
- The leaves of the CalcParsing tree point into the token stream's storage, as the C++ references
do (`&tokens.m_tokens[index]` of the consumed token).
- `parse_lab_like_color_value`/`parse_lch_like_color_value` return the array literal directly
(see Compiler issues).
## Tests
- `tests_css_value_parsing_cases` (427 cases) and `tests_css_value_parsing`: a local oracle
(`luce-browser-tools/oracles/luce-browser-engine/css_value_parsing`: `oracle.cpp` links the
reference build's LibWeb objects, `cases.txt`, `build.sh`, `gen_luce_cases.py`) runs each value
parser and prints the parsed value's serialization (or "none"), the tokens left and the
ErrorReporter's errors; the port prints the same and all cases match. Coverage is listed in the
test fragment's header. 20 more cases (marked `!` in cases.txt: math functions, easing,
transforms, basic shapes, font-style, counters, superellipse(), symbols()) run in the oracle and
wait for r33/r35; quirks-mode parsing (quirky colors and lengths) needs a document in quirks
mode and is not covered yet.
- r37's style-sheet oracle (`css_sheets`): 31 of its 52 waiting cases are turned on
(`@namespace` in every form and its dump, `@function` parameters, the namespace caches,
CSSRuleList insert/remove with `@namespace` rules, sheet insertRule/addRule paths that throw
before invalidating, a grouping-rule insert, invalid selectorText) and match;
`tests_css_sheets_cases` is regenerated (113 cases). The 21 still marked `!` (sheet
insertRule/deleteRule/addRule and style-rule selectorText on a sheet) stop in r42's
`invalidate_style_for_style_sheet_owners` / `determine_shadow_root_stylesheet_effects`.
## Compiler issues
`luce-browser-tools/compiler-issues/local_array_of_pointers_returned_by_value.lucb`: returning a
named local array of heap pointers (`let values: (Node*?)[2] = [...]; return values`) is rejected
by the escape check; returning the literal directly compiles, so the port needs no workaround.