dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r23.md
# Region r23: forms โ FormAssociatedElement, the form-control infrastructure and the form elements
Region r23 ports `HTML/AutocompleteElement`, `ElementInternals`, `FormAssociatedElement` (with
`FormAssociatedTextControlElement`), `FormControlInfrastructure`, `HTMLFieldSetElement`,
`HTMLFormControlsCollection`, `HTMLFormElement`, `HTMLLabelElement`, `HTMLLegendElement`,
`HTMLOutputElement` and `ValidityState`. The stub fragment `stubs/stub_r23_html_forms.lucb` is
gone; every one of its 259 functions is ported.
## Fragments (in `html/`)
| Fragment | Donor |
| --- | --- |
| `autocomplete_element` | `AutocompleteElement.cpp/.h` |
| `element_internals` | `ElementInternals.cpp` |
| `form_associated_element_1` | `FormAssociatedElement.cpp` 1-303 + `.h`: construction, categories, the form owner, enabled, the FACE disabled state |
| `form_associated_element_2` | `FormAssociatedElement.cpp` 305-633 + `.h`: formAction, constraint validation, the suffering-from states, the FACE state, visit_edges, the inline virtuals |
| `form_associated_element_3` | `FormAssociatedElement.cpp` 635-1036: the text control selection API |
| `form_associated_element_4` | `FormAssociatedElement.cpp` 1038-1359 + `.h`: editing and cursor movement (InputEventsTarget overrides) |
| `form_control_infrastructure` | `FormControlInfrastructure.cpp` |
| `html_field_set_element`, `html_form_controls_collection`, `html_label_element`, `html_legend_element`, `html_output_element`, `validity_state` | the matching files |
| `html_form_element_1` / `_2` / `_3` | `HTMLFormElement.cpp` 1-553 / 554-800 / 801-1237 + `.h` |
| `tests_html_forms_1`, `tests_html_forms_2` | tests |
## What other regions must know
### Every HTML element (r22, r24-r27, r21's parser)
- `FormAssociatedElement::visit_edges` and `is_form_associated_element` are real now, so
collections with HTML elements alive and every attribute change / insertion / removal / move
of an HTML element run. r22's test FormAssociatedElement table is removed.
- **New**: `html_form_associated_element_construct(fae)` โ FormAssociatedElement's defaulted
constructor (the two Strings empty, the two FACESubmissionValues Empty). `html_element_construct`
now calls it (it set only the two variants before; a zeroed `ak.String` is the invalid sentinel,
not the empty string).
- Element classes that mix in FormAssociatedElement override its virtuals in their generated
`html_<class>_form_associated_element_vtable`; the constructor moves the five mixin tables, as
`html_field_set_element_construct` does. The mixin's element is
`html_form_associated_element_form_associated_element_to_html_element(fae)`.
- r24/r25 (input, select, textarea, button): `FormAssociatedTextControlElement`'s functions cast
an `InputEventsTarget*` base to the mixin (its first field); `selection_was_changed` VERIFYs the
element is an input or a textarea. `AutocompleteElement`'s functions take the mixin; its element
comes from `autocomplete_element_to_html_element`.
- r21's parser calls `html_form_associated_element_set_parser_inserted` (and `set_form`).
### Signature and type changes
- `html_construct_entry_list(realm, form, submitter = none, encoding = none)`: `encoding` gets its
C++ default (`Optional<String> {}`); the generated stub had none after a defaulted parameter.
- **Types filled** (the generator left them opaque): `HtmlAutocompleteElementAttributeDetails`,
`XhrFormDataEntry` (+ new variant `XhrFormDataEntryValue`, `FormDataEntry.h:17`),
`DomurlQueryParam`, `HtmlPostResourceDirective`, `HtmlFormElementSubmitFormOptions`,
`HtmlFormElementStaticValidationResult`, `HtmlFormElementPastNameEntry`,
**`HtmlNavigableNavigateParams`** (r28: every member of `Navigable::NavigateParams`, with C++'s
defaults; SerializationRecord is `ak.Vector[u8]?`).
- Made private (C++ `static` / private): `html_string_to_selection_direction`,
`html_determine_a_field_category`, `html_construct_face_entry`, `html_method_attribute_to_method_state`,
`html_encoding_type_attribute_to_encoding_type_state`, `html_is_form_control`,
`html_convert_to_list_of_name_value_pairs`, `html_plain_text_encode`,
`html_form_element_number_of_fields_blocking_implicit_submission`, and the text control's
`collapse_selection_to_offset`, `scroll_cursor_into_view`, `selection_was_changed`.
- **Closure stubs added** (`stubs/stub_closure.lucb`, namemap rows): the reaction names
`formAssociatedCallback` / `formResetCallback` / `formDisabledCallback` and the input types
`insertText` / `insertFromPaste` (zero until interned, as r15's); P2/P3/P4 traps for
`XHR::FormData::entry_list` / `construct_impl`, `FileAPI::Blob::type` / `raw_bytes`,
`is<FileAPI::File>`, `File::create` (+ `FileApiFilePropertyBag`), `File::name` /
`last_modified`, `FileList::length` / `item`, `FormDataEvent::construct_impl`
(+ `HtmlFormDataEventInit`), `SubmitEvent::create` (+ `HtmlSubmitEventInit`),
`RadioNodeList::create`, `DOMURL::url_encode`, `as<UIEvents::MouseEvent>`, `UIEvent::detail`,
`MouseEvent::client_x` / `client_y` / `clone` / `set_offset_x` / `set_offset_y`.
- Opaque platform types used as their first bases: `(DomEvent*)` of a MouseEvent / FormDataEvent
/ SubmitEvent, `(FileApiBlob*)` of a File, `(DomNodeList*)` of a RadioNodeList.
### What runs in phase 1 and what traps
- Runs: form owners (ancestor form, the form attribute through the document's list, removal),
categories, enabled / disabled fieldsets, the constraint validation API and ValidityState,
elements collections, the submittable elements, statically validating, reset (fires `reset`),
the supported property names, labels' controls, output's value, the autofill model.
- Traps until other regions land: form submission (SubmitEvent, FormData, navigables r28),
`namedItem` returning a RadioNodeList and the form's named properties (RadioNodeList, P3),
entry lists with File entries (FileAPI, P2), a label's activation behavior (MouseEvent, P4),
the text control's selection changes (r24/r25 elements, layout), `formAction` / `action` with a
non-empty attribute (the document's base URL, r28).
## Deviations and notes
- **Donor quirks kept**: `normalize_line_breaks` drops a CR LF pair (`consume_until("\r\n")` stops
at the CR and `ignore(2)` skips both: `"a\r\nb"` โ `"ab"`, pinned by the oracle);
`mail_with_headers` discards the result of `headers.replace("+", "%20")`.
- `HTMLFieldSetElement::type` / `HTMLOutputElement::type` return a new String each time (C++
caches it in a function-local static; a module global is not scanned by the collector).
- `TRY_OR_THROW_OOM` is `try` (the only failure is out of memory).
- A FACESubmissionValue's list of entries is cloned when set (C++ copies the variant).
- Lambdas: the select-event task and the planned navigation task are capture structs allocated
with `new`; the HTMLCollection / RadioNodeList filters take the form or a capture struct as
context; `parse_autocomplete_attribute`'s step_default / step_done are functions over their
captures; `supported_property_names`' SourcedName is a local struct sorted with AK's quick_sort.
- `HTMLLabelElement::activation_behavior`'s ScopeGuard block has no early exit, so the click flag
is unset at its end.
## Tests
Ladybird has no unit tests for these files. `tests_html_forms_1` (7): factory construction and
the mixin tables and answers of form / fieldset / legend / label / output; **garbage collection
with HTML elements alive** (a document tree of form, fieldset, legend and output survives two
collections, a collected detached form owner leaves the weak `m_form` null, a ValidityState and
an ElementInternals visit their element); resetting the form owner (ancestor, the form attribute
naming another form or nothing, removing the attribute, removal from the tree, the parser
inserted flag); enabled and nested disabled fieldsets with their legends, the fieldset's
elements; the constraint validation API, setCustomValidity's newline normalization, ValidityState
over the FACE flags; formAction / action defaults; ElementInternals' eight NotSupportedErrors.
`tests_html_forms_2` (8): the autofill processing model on 23 attribute values (expected values
from a local oracle running the donor's algorithm against the reference build's AK, including
the hint set's HashTable order), tokens, the IDL attribute and the field categories; the text
control selection over a test mixin (offsets, clamping on a value change, direction, the
stringifier, setRangeText, IndexSizeError); normalizing line breaks (oracle values); name-value
pairs, text/plain and multipart/form-data of string entries; the form's method / enctype /
action, elements and length, indexed values, submittable elements, validation, the constructing
entry list flag, relList and picking an encoding; supported property names with the past names
map and namedItem; a label's control by `for` and by descendant; output's value and defaultValue.
The GC test collects with test tables for the document (its visit reaches StyleScope, r39, and
members a phase-1 test document leaves null, such as its FontFaceSet) and heap test pages
(Page::visit_edges is r28's; tests_document's pages are off-heap cells the collector cannot
mark). It used to run under `with heap`, because WeakImpls held only from C-heap memory were
recycled by a collection. Since fix/weak-impls a Weak stays valid wherever it is held
(DESIGN.md ยง3.7), and the test runs with the test's own allocator.
## Compiler issues
None found. (`enum_case_context_from_generic_argument` was not met.)