Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / 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.