Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.1

0.6.1 / docs / regions / r16.md

# Region r16: DOM Element and ElementFactory — what other regions need to know

Region r16 ports `DOM::Element` (`Element.cpp`, 4,828 lines, and the inline functions of
`Element.h`) and `DOM::ElementFactory` (`ElementFactory.cpp`). The stub fragment
`stubs/stub_r16_dom_element.lucb` is gone; every one of its 430 functions is ported. Each
fragment's header names the donor lines it holds; the C++ order is kept.

| Fragment | Donor |
| --- | --- |
| `dom/element_1` | `Element.cpp` 132-539: constructor, structural-flag setters, initialize, visit_edges, getAttribute(NS)/value, an element's target and noopener, cannot navigate, following hyperlinks, getAttributeNode(NS), setAttribute, the name validity checks, validate and extract |
| `dom/element_2` | 541-918: setAttributeNS, append/set attribute values, setAttributeNode(NS), remove/has/toggle attributes, getAttributeNames, attr-associated element(s), create_layout_node(_for_display_type), attribute change steps, compute_required_invalidation |
| `dom/element_3` | 920-1334: recompute_style, recompute_inherited_style, classList/part, valid shadow host names, attach a shadow root, attachShadow, shadowRoot, matches, closest |
| `dom/element_4` | 1336-1683: innerHTML, focus/activation, document element, shadow host, set_shadow_root, inline style, HTML-uppercased qualified name, queue an element task, void elements, client rects and client* metrics |
| `dom/element_5` | 1685-2347: inserted/removed_from/moved_from/children_changed, pseudo-element nodes, the pseudo-class matchers, JSON serialization, tabIndex, potential scrollability, scrollTop/Left (get/set), scrollWidth/Height, actually disabled |
| `dom/element_6` | 2349-2703: fragment parsing, outerHTML, insertAdjacentHTML, fullscreen, onfullscreen*, insert adjacent (element/text) |
| `dom/element_7` | 2705-2963: scrollIntoView |
| `dom/element_8` | 2965-2979: the 54 reflected ARIA attributes (ENUMERATE_ARIA_ATTRIBUTES, expanded in order) |
| `dom/element_9` | 2981-3359: hidden/referenced, accessibility tree rules, element queues, custom element reactions, upgrade, try to upgrade, defined/custom states |
| `dom/element_10` | 3361-3733: prefixes, for_each_attribute, layout-node accessors, cascaded/computed properties, pseudo-elements, custom property data, scroll()/scrollBy(), checkVisibility() |
| `dom/element_11` | 3735-4245 and 4534-4563: viewport proximity, relevance, list owners and ordinals (with `for_each_numbered_item_owned_by_list_owner`), ID references, intersection observers, scroll offsets, translation mode, directionality, inline-style image prefetch |
| `dom/element_12` | 4247-4532 and 4565-4828: attribute_changed, reaction queue, state set, style sheets / ID maps of the root, getHTML, setHTMLUnsafe, counters, lang, rendering, pointer capture, attributes(), animations after display changes, focus, computedStyleMap, random base values, pointer lock, style inheritance, render blocking |
| `dom/element_13` | the inline functions of `Element.h` (lines 122-616, 776-811) |
| `dom/element_factory_1` | `ElementFactory.cpp` 149-319: valid local names per interface, `is_unknown_html_element` |
| `dom/element_factory_2` | 321-608: `create_html_element`, `create_svg_element`, `create_mathml_element` (the tag dispatch tables, in order) |
| `dom/element_factory_3` | 610-800: `create_element_internal`, `create_element` |
| `dom/tests_element` | 18 tests (Ladybird has none for these files) |

## Conventions other regions will meet

- **Mixin vtables.** `dom_element_construct` constructs the ARIAMixin base and points the three
  mixin vtables (`slottable_mixin`, `aria_mixin`, `animatable`) at Element's tables. Every
  subclass constructor (r22 HTMLElement and the HTML elements, r55/r56 SVG, MathML) must move
  them to its own generated tables (`html_input_element_aria_mixin_vtable`, …) after calling its
  base constructor, as r14's DOMException does for `serializable`.
- **From a mixin to its element**: `dom_element_from_aria_mixin(base)` (and the private
  `dom_element_from_slottable_mixin`) subtract the mixin's offset in `DomElement`; every subclass
  embeds Element first, so the offset is the same.
- **Private helpers other fragments may reuse**: `dom_element_document`, `dom_element_realm`,
  `dom_element_abstract_element(element, pseudo_element)`, `DomElementIsAsciiWhitespace` (the
  `split_view_if(Infra::is_ascii_whitespace)` predicate), `dom_element_string_equals_ignoring_ascii_case`,
  `dom_fly_string_is_one_of_fly_strings`.
- **`heap.allocate<T>()` of layout nodes** (create_layout_node_for_display_type) uses the generated
  `realm_create_layout_*` helpers in the document's realm (a layout node's `initialize` is
  JS::Cell's, empty). PseudoElement(TreeNode) cells come from the new
  `heap_allocate_dom_pseudo_element(_tree_node)` in `dom/types_pseudo_element.lucb` (over r14's
  `web_heap_allocate_cell`).
- `Element::initialize` calls `web_set_prototype_for_interface(base, realm, BindInterfaceName.element)`
  then EventTarget's initialize (ParentNode and Node do not override it).
- Template callbacks: `for_each_numbered_item_owned_by_list_owner(_const)` take
  `ak.Function1[DomElement*, ak.IterationDecision]`; `create_element_internal` takes the interface
  as `func(DomDocument*, DomQualifiedName) -> DomElement*` (`DomElementInterface`).
- `recompute_inherited_style`'s `HashMap<size_t, RefPtr<StyleValue>>` is a Vector of pairs: the
  indices are visited in increasing order once each, and the only use is OR-ing invalidations.

## Signature and type changes

### This region's own functions
- `dom_create_element`: `is_value` and `initial_registry` now have their C++ defaults (`none`,
  `.dom_default(DomDefault(empty_ = 0))`).
- `dom_create_element_internal` is no longer generic (see above);
  `dom_element_for_each_numbered_item_owned_by_list_owner(_const)` likewise.
- `dom_element_maybe_invalidate_ordinals_for_list_owner(this, skip_node: (DomElement*?)? = none)`:
  C++'s `Optional<Element*>` (was `DomElement*?`).
- C++ private members and `static` functions are module-private (`insert_adjacent`,
  `ensure_pseudo_element`, `exit_fullscreen_on_element_removal`, `make_html_uppercased_qualified_name`,
  `play_or_cancel_animations_after_display_property_change`, the directionality helpers,
  `compute_required_invalidation`, `is_valid_shadow_host_name`, the scroll-into-view statics,
  `prefetch_inline_style_image_resources`, `create_html/svg/mathml_element`).

### Types filled
- `HtmlNavigableChosenNavigable` (`navigable`, `window_type`) and the new `HtmlWindowType`
  (`html/types_navigable.lucb`).
- `CssComputedPropertiesContentDataAndQuoteNestingLevel` (`content_data`,
  `final_quote_nesting_level`), `CssStyleComputerAnimatedInheritValue` (`value`,
  `is_result_of_transition`).

### Declarations outside the phase-1 closure (`stubs/stub_closure.lucb`, rows in `namemap.tsv`)
- Ported whole because element creation needs them: `html_is_valid_custom_element_name`,
  `html_look_up_a_custom_element_registry`, `html_normalize_non_finite_values_f64/_optional`.
- Ported partially (the steps that need no unported state): `animations_animatable_visit_edges`
  and `animations_animatable_has_css_defined_animations` (no Impl → nothing / false),
  `html_look_up_a_custom_element_definition` (null registry or non-HTML namespace → null).
- Trap stubs: the TrustedTypes checks (`get_trusted_types_compliant_attribute_value`,
  `get_trusted_type_compliant_string`, enum `TrustedTypesTrustedTypeName`), `referrer_policy_from_string`,
  the CustomElementDefinition accessors (+ enum `HtmlCustomElementDefinitionConstructionStackEntry`),
  `html_custom_state_set_create`, `html_window_or_worker_global_scope_mixin_report_an_exception`,
  `html_temporary_execution_context_destruct` (C++'s destructor, run with `defer`),
  `geometry_dom_rect_construct_impl`, `geometry_dom_rect_list_create`,
  `css_style_property_map_create`, `css_style_property_map_read_only_create_computed_style`,
  `xml_fragment_parser_parse_xml_fragment`, `selection_selection_contains_node`, the Animation
  play/pause/cancel/play-state calls, and the phase-3 JS seams `js_type_error_create`,
  `js_native_function_create`, `js_primitive_string_create_*`, `js_value_is_string`,
  `js_value_as_string_utf8_string`, `js_same_value`, `js_completion_release_value`,
  `js_take_pending_exception_value`, `js_value_as_if_html_element`, and the FlyString
  `html_custom_element_reaction_names_attribute_changed_callback`.

## Deviations and notes

- `follow_the_hyperlink` stops at step 13 with `trap("unported (P2): …")`: `Navigable::NavigateParams`
  is opaque in phase 1.
- The JS-facing steps (custom element upgrade/construct, the connectedMoveCallback native
  function, TrustedTypes) call the phase-3 seams above; DOMExceptions go through `idl_throw`,
  `vm.throw_completion<TypeError>` through r14's `vm_throw_completion`.
- `client_top`/`client_left` and the two `scroll_top`/`scroll_left` pairs stay separate
  functions, as in C++.
- `scrollIntoView`'s "Do nothing" branches are expressed by guarding the following `else if`s
  with `if not both_outside:`; the `if (true)` FIXME branch keeps only its body.
- `css_display_to_string` is printed with `ak.dbgln` for unsupported displays, as C++ does with dbgln.

## Tests

`dom/tests_element.lucb` (18 tests, run by `./test.sh`): the name validity checks against values
taken by compiling the donor's `is_valid_*` and `is_valid_custom_element_name` against the
reference build's AK (28 names, including non-ASCII, controls and reserved names); every
exception of validate-and-extract and toggleAttribute (with r14's test VM and realm); the
attribute queries of an element without attributes; has_class in both case modes; the
removed-attribute bookkeeping; the structural flags and the parent's backward flag; the
tree-counting flag on the parent; custom element states; dir-driven directionality (auto with no
text is 'ltr'); translation mode; scroll offsets; cached lang and ordinal values; an element's
target (the C++ looks for the three-character sequence "\t\n\r" before '<'); the mixins' way back
to their element; pseudo-element queries without data; the factory's local-name tables.

Elements are built by hand (r15's `test_node`), since constructing one traps in r19's EventTarget
constructor (and in r13b's `aria_mixin_construct`, a defaulted constructor still stubbed). Once
r17-r19 and r18's QualifiedName land, scenario tests should cover: create_element for the HTML,
SVG and MathML tables and unknown/custom names, the attribute API over a NamedNodeMap
(set/toggle/remove, attribute_changed for id/class/name/dir/part/slot), validate_and_extract's
success path, attachShadow, matches/closest, the directionality algorithms over text, list
ordinals and `is_unknown_html_element` with interned tag names.