dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r22.md
# Region r22: HTMLElement and its mixins — what other regions need to know
Region r22 ports `HTML/HTMLElement`, `HTMLOrSVGElement`, `GlobalEventHandlers`,
`WindowEventHandlers`, `HTMLUnknownElement`, `LazyLoadingElement`, `HTMLHyperlinkElementUtils`,
`DOMStringMap`, `Focus`, `Numbers`, `Dates`, `AttributeNames::is_boolean_attribute` and interns
`HTML::EventNames` (and, outside the closure, `Gamepad::EventNames`). The stub fragment
`stubs/stub_r22_html_element.lucb` is gone; every one of its 405 functions is ported.
## Fragments (in `html/` unless noted)
| Fragment | Donor |
| --- | --- |
| `attribute_names` | `AttributeNames.cpp` (r21's FlyStrings; `is_boolean_attribute` added) |
| `event_names`, `gamepad/event_names` | `EventNames.cpp/.h`, `Gamepad/EventNames.cpp/.h` (interned by `web_initialize_strings`) |
| `dates`, `numbers` | `Dates.cpp`, `Numbers.cpp` |
| `dom_string_map` | `DOMStringMap.cpp/.h` |
| `focus` | `Focus.cpp` |
| `global_event_handlers_1`, `_2`, `window_event_handlers` | the `ENUMERATE_*_EVENT_HANDLERS` expansions of `GlobalEventHandlers.cpp` / `WindowEventHandlers.cpp` |
| `html_element_1` … `html_element_6` | `HTMLElement.cpp` 1-455 / 457-947 / 947-1395 / 1386-1815 / 1816-2096 / 2097-2508 + `HTMLElement.h` inlines |
| `html_element_event_handler_attributes` | the `ENUMERATE_GLOBAL_EVENT_HANDLERS` expansion inside `HTMLElement::attribute_changed` |
| `html_hyperlink_element_utils`, `html_or_svg_element`, `html_unknown_element`, `lazy_loading_element` | the matching files |
| `tests_numbers_and_dates`, `tests_html_element_1`, `tests_html_element_2` | tests |
## What other regions must know
### Constructing HTML elements (r21's parser, r23–r27's element classes, r16's factory)
- `html_element_construct(this, document, qualified_name)` runs Element's constructor, then
constructs the GlobalEventHandlers, `HTMLOrSVGElement<HTMLElement>` and FormAssociatedElement
bases: the two `FACESubmissionValue` variants start `.empty` (C++'s `Variant` default; the
zero bits would be `file_api_file`), and **every mixin table moves to HTMLElement's**
(`slottable_mixin`, `aria_mixin`, `animatable`, `global_event_handlers`,
`form_associated_element`; the two HTML mixins' `class_id` is the cell's). Each subclass
constructor calls it and then moves the five tables to its own generated
`html_<class>_*_vtable`s, as `html_unknown_element_construct` does.
- `realm_create_html_element` / `realm_create_html_unknown_element` work in a settings realm
(r29) with a heap document: `dom_create_html_element` (the factory's tag dispatch) makes
HTMLElement for the 50 sectioning/phrasing names and valid custom names, HTMLUnknownElement for
the rest. `dom_create_element` itself still traps in r42
(`invalidate_style_after_custom_element_state_change`: the element's initial state is
`undefined` and creation sets `uncustomized`).
- `html_element_initialize_impl` is the `Base::initialize` of every HTML element class.
### On the critical path now (other regions' stubs every HTML element reaches)
- **r23**: `FormAssociatedElement::is_form_associated_element` (every `attribute_changed`,
`inserted`, `removed_from`, `moved_from` of an HTML element), `FormAssociatedElement::visit_edges`
(every HTML element's `visit_edges`, so **any collection with an HTML element alive traps until
r23 lands**), `is_autocapitalize_and_autocorrect_inheriting`, `enabled` (click()). The tests
use a FormAssociatedElement table answering C++'s `false`.
- **r42**: `invalidate_style_after_attribute_change` (after every attribute change),
`invalidate_style_after_directionality_change` (dir), `invalidate_style_after_hyperlink_state_change`.
- **P2**: `PolicyList::contains_header_delivered_policy` (HTMLOrSVGElement's insertion steps of a
browsing-context-connected element); **r28**: the document's base URL in
`encoding_parse_url` (HTMLHyperlinkElementUtils with an href).
### Mixins
- **HTMLOrSVGElement<T>** keeps its generic signatures (`this: HtmlOrSvgElement[T]*`); it is at
the same offset in HTMLElement, SVGElement and MathMLElement (asserted at module level), and
`static_cast<ElementBase*>(this)` is that offset. r55 (SVG) and r13b (MathML) call
`html_or_svg_element_attribute_changed(&this.html_or_svg_element, ...)` etc. as HTMLElement does.
- **LazyLoadingElement<T>**: the functions take the element, `[T: IsDomElement &
HasHtmlLazyLoadingElement[T]](this: T*)` (the stub took the mixin, from which the element cannot
be reached: it sits at different offsets in img and iframe). `HasHtmlLazyLoadingElement[T]`
(new, `types_lazy_loading_element`) is declared on HTMLImageElement and HTMLIFrameElement's
types with a one-line `html_lazy_loading_element()`; r26/r27 call e.g.
`html_lazy_loading_element_will_lazy_load_element(this)` with `this: HtmlImageElement*`.
- **GlobalEventHandlers / WindowEventHandlers**: the getters and setters go through the virtual
`*_to_event_target`; HTMLElement answers itself. The pure virtuals trap.
### Signature and type changes
- `html_element_close_entire_popover_list`, `_hide_popover_stack_until` (private) and
`html_element_topmost_popover_ancestor` take `const ak.Vector[HtmlElement*]*` (C++ `const&`:
hiding a popover removes it from the very list the loop reads; a copied Vector would not see
that). r17's two callers in `dom/document_13` pass `&this.m_showing_*_popover_list`.
- The focus helpers (private) take and answer `ak.Vector[DomNode*]` (C++ `GC::Root<Node>`;
the stub had `DomNode*?`).
- Private (C++ `static` / private): `html_parse_a_month_component`, `_date_component`,
`_time_component`, `html_fire_a_focus_event`, `html_run_focus_update_steps`,
`html_focus_chain`, `html_merge_with_the_next_text_node`, `html_rendered_text_collection_steps`,
`html_any_ancestor_establishes_a_fixed_position_containing_block` and HTMLElement's private
members (`rendered_text_fragment`, the popover helpers).
- **Types filled**: `HtmlDomStringMapNameValuePair` (`name`, `value`), `LayoutTextNodeChunk`
(`view`, `font`, `start`, `length`, the four flags, `text_type`); new opaque
`LayoutTextNodeChunkIterator` (`layout/types_text_node`).
- **Stubs added for r43** (`stubs/stub_r43_layout_tree.lucb`; the skeleton left ChunkIterator
out because only function bodies name it): `layout_text_node_chunk_iterator_construct`
(`ChunkIterator(TextNode const&, bool, bool)`) and `layout_text_node_chunk_iterator_next`.
- **Closure** (`stubs/stub_closure.lucb`, namemap rows): ported `js_to_integer_or_infinity`,
`js_make_time`; trap stubs `js_date_create` (P3), `js_value_to_string` (P3),
`content_security_policy_policy_list_contains_header_delivered_policy` (P2),
`html_navigation_set_focus_changed_during_ongoing_navigation` (P3),
`html_custom_element_definition_form_associated` / `_disable_internals` (P3),
`html_close_watcher_establish` / `_destroy` (P3), `HtmlToggleEventInit` +
`html_toggle_event_create` (P4), `html_popover_target_attributes_get_the_popover_target_element`
(P4); `UiEventsFocusEventInit` and an `event_init` parameter (defaulted, as in C++) on
`ui_events_focus_event_create`; `ui_events_pointer_event_create`'s init is defaulted (C++ `= {}`).
- Opaque platform types used as their bases: `(DomEvent*)` of a PointerEvent,
`(DomEventTarget*)` of a CloseWatcher (both derive from them first; correct once filled).
## Deviations and notes
- **Donor quirks kept**: `parse_a_time_component` checks `hour > 59` where the spec says minute
(minutes 60-99 parse); `hide_popover`'s cleanup steps test `if (nested_hide)` where the step says
"if nestedHide is false"; `is_valid_date_string` (and so local date-and-time strings) with a
whitespace-led year VERIFY-fails in `parse_ascii_digit` (`" 2020-01-01"`), and the port traps.
- `parse_floating_point_number`'s `goto`s are labeled once-loops (`break conversion`,
`break fraction`); the C++ `exponent *=` narrowing to i16 is spelled out.
- HTMLHyperlinkElementUtils mutates `m_url` through a reference to the optional's value; the port
takes the URL out, changes it and stores it back (a plain Url copy shares its CopyOnWrite data).
- `rendered_text_collection_steps` names its enum cases in full (`# LUCE-BUG:
enum_case_context_from_generic_argument`, below).
- Lambdas: show_popover's closeAction is a native function whose context is the element;
getEnabledState is a `gc.Function0[bool]`; the popover toggle task's captures are allocated with
`new`; checkAncestor is a function over a capture struct; labels()' filter's context is the
element.
## Tests
`tests_numbers_and_dates` (17): `Tests/LibWeb/TestNumbers.cpp` and `TestMicrosyntax.cpp` ported,
and every other Numbers/Dates function pinned to a local oracle compiling the donor's
`Numbers.cpp`/`Dates.cpp` against the reference build (30 integers, 43 floats as bits, 31 valid
floats, 15 last weeks, 92 valid week/month/date/time/local strings, 10 normalizations, 44 parsed
month/week/date/local date-and-time strings with the seconds' bits), plus
`convert_non_negative_integer_to_string`'s IndexSizeError, `parse_time_string`'s TypeError and
`make_time`. `tests_html_element_1` (12): factory construction and mixin tables, the virtuals,
event names and boolean attributes, translate/dir/title, contenteditable (states, editing hosts,
SyntaxError), hidden, inert (subtrees, escaping, insertion), popover states, accessKeyLabel,
draggable/spellcheck/writingSuggestions, autocapitalize/autocorrect, heading levels, default
ARIA roles. `tests_html_element_2` (11): popover validity and its DOMExceptions,
hidePopover/togglePopover, popover lists, attachInternals, the dataset's pairs, the nonce, the
hyperlink getters without an href and extracting an origin, Global/WindowEventHandlers, the
lazy loading attribute and resumption steps, the focus chain and the focusing steps' early
returns. Attributes are put in the NamedNodeMap and their change steps run through the
`attribute_changed` virtual (the caller continues into r42).
Scenario tests to add when the blockers land: setAttribute end to end (r42), the reflections'
setters, GC with HTML elements (r23), `dom_create_element` (r42), innerText/outerText and the
offset metrics (layout), showing popovers (ToggleEvent, CloseWatcher), the hyperlink getters and
setters with an href (r28, r42), focus with a browsing context (r28), click() (r23).
## Compiler issues
- `enum_case_context_from_generic_argument` (`luce-browser-tools/compiler-issues/`): a `.case`
argument whose parameter type is a generic parameter already fixed by an earlier argument
(`ak.vector_append_t(&items, .utf16_string(...))`) gets no enum context. Worked around in
`html_element_1` by naming the enum (tagged `LUCE-BUG`).
- Language note (not filed): an ASCII character literal adapts to `u8` only, so `u16` code units
are written `(u16)'-'`.