dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r24.md
# Regions r24 and r25: HTMLInputElement and the other form controls
Region r24 ports `HTML/HTMLInputElement`. Region r25 ports `HTMLButtonElement`,
`HTMLSelectElement`, `HTMLOptionElement`, `HTMLOptGroupElement`, `HTMLOptionsCollection`,
`HTMLSelectedContentElement`, `HTMLTextAreaElement`, `HTMLMeterElement`, `HTMLProgressElement`
and `HTMLDataListElement`. They were ported together on one branch. The stub fragments
`stubs/stub_r24_html_input.lucb` and `stubs/stub_r25_html_controls.lucb` are gone, and all 461 of
their functions are ported.
## Fragments
| Fragment | Donor |
| --- | --- |
| `html/html_input_element_1` | `HTMLInputElement.cpp`: helpers, construction, layout node, checkedness, `list`, pattern, files, pickers |
| `html/html_input_element_2` | activation behavior, the value setter, the static shadow tree styles, placeholder |
| `html/html_input_element_3` | the user-agent shadow trees and their native event listeners |
| `html/html_input_element_4` | focus, attribute changes, `type`, `src`, value sanitization, reset, clear |
| `html/html_input_element_5` | hints, cloning, radio groups, legacy pre-activation, ImageProvider, reflected attributes |
| `html/html_input_element_6` | number / date conversions, min / max / step, `valueAs*`, stepUp / stepDown |
| `html/html_input_element_7` | the default role, activation, the "applies to" tables |
| `html/html_input_element_8` | constraint validation, mutability, the stringifier, the inline functions in `.h` |
| `html/popover_target_attributes` | `PopoverTargetAttributes.cpp/.h`. This was a closure stub, and input and button are its only users |
| `html/file_filter` | `FileFilter.cpp`. `types_file_filter` is filled in |
| `external/lib_js/date_and_number` | LibJS's time value helpers (`Date.h/.cpp`: msPerDay … MakeDate), `Number::toString` (radix 10) and `Value::is_finite_number`. This is plain double arithmetic. JS::Date objects stay in phase 3 |
| `html/html_button_element`, `html_data_list_element`, `html_meter_element`, `html_opt_group_element`, `html_option_element`, `html_options_collection`, `html_progress_element`, `html_selected_content_element` | the matching files |
| `html/html_select_element_1` / `_2` | `HTMLSelectElement.cpp`, split at a section boundary. `_2` holds the shadow tree, the picker and the select update notifications |
| `html/html_text_area_element_1` / `_2` | `HTMLTextAreaElement.cpp`. `_2` holds the shadow tree, maxlength, the placeholder and text edit tasks |
| `html/tests_form_controls`, `html/tests_form_controls_cases` | tests (see below) |
## What other regions must know
- **Static GC roots.** These hold a `gc.Root` in a module `var`, following the C++
function-local `static GC::Root`, as `internal_css_realm` already does:
- the six shadow tree style functions (`html_inner_text_style_when_visible`, …,
`html_placeholder_style_when_hidden`);
- `create_text_input_shadow_tree`'s two styles (`html_input_element_create_text_input_shadow_tree_s_*`).
`html_valid_email_address_regex` is a C-heap static. In Ladybird these live as long as the
process's one VM. The unit tests create and destroy one VM per test, so a test that builds
input shadow trees must reset the roots after `web_test_destroy_vm`. The same applies to
`internal_css_realm_s_*`, which any style parse of a `style` attribute creates.
`test_form_controls_forget_statics` in `html/tests_form_controls.lucb` shows how. Without the
reset, a later test reads a destroyed heap and the test process dies on a signal.
- `html_list_of_options` keeps the generated stub's `ak.Vector[HtmlOptionElement*?]`, because
r23's form control infrastructure already uses it.
- The mixin casts follow r23. Input, select, textarea and button move their mixin tables in
their constructors. Functions that take a mixin base recover the element with
`offsetof(<Element>, <mixin field>)` (for example `html_text_area_element_from_text_control`).
Accessors such as `html_text_area_element_text_control` go the other way.
- `PopoverTargetAttributes` has no vtable. It is found through ClassInfo's mixin offsets
(`as_if_popover_target_attributes`).
- Number inputs' steppers and selects' chevrons are SVG elements. Their shadow trees build now
that r55 has landed. Their layout still stops at `SVGSVGBox` (r49).
### Signature and type changes
- Made private, matching C++ `static`, private or protected members: the input element's
conversion, step, shadow tree, sanitization and radio group helpers, together with
`html_is_valid_simple_color`, `html_is_in_same_radio_button_group`, `html_convert_*`,
`html_valid_email_address_regex` and `html_determine_if_a_command_is_valid_for_a_target`.
Also private: meter's, progress's, option's, select's and textarea's internal helpers
(`create_shadow_tree_if_needed`, `update_*`, `display_size`, `set_raw_value`, …). This covers
89 stub functions in total.
- `html_input_element_compiled_pattern_regular_expression` returns `web_url.RegexEcmaScriptRegex*?`
instead of a regex by value.
- `html_input_element_user_interaction_did_change_input_value(this, input_type = ak.FlyString(), data = none)`:
`input_type` gets its C++ default.
- `html_concatenate_descendants_text_content(node: DomNode*, …)` takes a node that is not null,
as C++ does.
- `html_select_element_add` / `html_options_collection_add`: `before` gets its C++ default
(`.empty`).
- **Types filled**: `HtmlFileFilter` (`filters: Vector[HtmlFileFilterFilterType]`), with
`HtmlFileFilterFileType`, `HtmlFileFilterMimeType`, `HtmlFileFilterExtension` and the
`HtmlFileFilterFilterType` variant.
- **Closure stubs added** in `stubs/stub_closure.lucb`, under the section "regions r24/r25
call", with namemap rows: P3 traps for `JS::Date::date_value`, `is<JS::Date>` and
`JS::Value::get`; P2 traps for `FileAPI::FileList::create` and `add_file`; a P4 trap for
`CommandEvent::create`, with `HtmlCommandEventInit`. The `get_the_popover_target_element`
closure stub is removed because it is ported.
### What runs in phase 1 and what traps
- **Runs**:
- every input type's value modes, sanitization, checkedness and radio groups;
- attribute changes, `valueAsNumber` / `valueAsDate`'s number side, min / max / step and
stepUp / stepDown;
- every number↔string conversion;
- constraint validation, the selection and setRangeText of input and textarea;
- the user-agent shadow trees of text, color, file, range, number, button, checkbox,
textarea, select, meter and progress;
- select's list of options and selectedness, options collections, textarea values,
meter's and progress's values, button commands, datalist suggestions and the default
roles.
- **Traps until other regions land**:
- `valueAsDate` with a Date object (P3), file inputs with files (FileList, P2), image inputs
(fetch, P2) and `command` events (P4);
- the picker (page client, r28);
- layout of the checkbox and radio paintables (r53) and of the SVG steppers and chevron
(`SVGSVGBox`, r49).
## Deviations and notes
- `HTMLSelectElement::type` and `HTMLTextAreaElement::type` return a new String each time.
C++ caches it in a function-local static, but a module global is not scanned by the
collector.
- The C++ `R"~~~(…)~~~"` style strings are ported as escaped string literals, so they match
byte for byte. The serialized `style` attributes are pinned by the shadow tree oracle cases.
Luce's `"""` removes the first newline and the closing delimiter's indentation, so it cannot
reproduce these strings exactly.
- Lambdas such as element tasks and native event listeners are capture structs with
`ak.Function0` or `js_native_function_create`. The `Function` callbacks of the shadow tree
listeners are realm callbacks (`realm_create_idl_callback_type_realm`).
- `TRY_OR_THROW_OOM` is `try` (its only failure is running out of memory).
## Tests
Ladybird has no unit tests for these files. The two test fragments are:
- `html/tests_form_controls_cases` has 276 cases generated from a local oracle. The oracle
links the reference build's LibWeb objects and runs the same inputs through them. It lives in
`luce-browser-tools/oracles/luce-browser-engine/form_controls/` (`oracle.cpp`, `build.sh`,
`cases.txt`, `gen_luce_cases.py`, `README.txt`) and is never committed here.
- `html/tests_form_controls` (22 tests) runs each mode through the port. The modes cover:
- input values and sanitization, the value setter, attribute changes;
- numbers, min / max / step and the suffering-from states, stepUp / stepDown,
`valueAsNumber`'s setter, number↔string conversion;
- checked and radio groups;
- select state and setters, option selectedness;
- textarea state and setter, setSelectionRange, setRangeText in every mode;
- meter, progress, button;
- validity and mutability, default roles;
- the user-agent shadow trees, compared tag by tag with attributes, pseudo-elements, inline
styles and text.
A case's markup is either parsed into a test document or is a detached element
(`@tag attrs|children`).
r23's text control selection test (`tests_html_forms_2`) now runs on a real textarea instead
of a test FormAssociatedTextControlElement mixin.
web_test, compared with main before r24/r25 (both on r55):
| Suite | Before | After |
| --- | --- | --- |
| Layout | 727 | 763 |
| Ref | 388 | 397 |
| Crash | 28 | 29 |
The expected failures are rewritten. The form control tests that still fail stop at:
- `SVGSVGBox` (the number input steppers and the select chevron, r49);
- the checkbox and radio paintables (acid1, css-appearance-none, r53);
- an image input's fetch (P2).
## Compiler issues
None found.