dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r13b.md
# Region r13b: ARIA, MathML and XLink — what other regions need to know
Region r13b ports `ARIA/ARIAMixin`, `AriaData`, `RoleType`, `Roles`, `StateAndProperties` and
`AttributeNames`; the ARIA role classes Ladybird generates at build time (`Build/.../ARIA/AriaRoles.h`
and `.cpp`, from `ARIA/AriaRoles.json` by `generate_libweb_aria_roles.py`); `MathML/MathMLElement`,
`MathMLMiElement`, `MathMLMspaceElement`, `AttributeNames`; and `XLink/AttributeNames`. The stub fragment
`stubs/stub_r13b_mathml_aria_misc.lucb` is gone: all 1,663 of its functions are ported, with the stub's
signatures (only parameter names differ). `MathML/TagNames` was ported by r21 and
`MathMLStyleSheetSource` by r39 (`tools/embed_css`).
## Fragments
| Fragment | Donor |
| --- | --- |
| `aria/aria_mixin_1` | `ARIAMixin.cpp` 17-26 (constructor, visit_edges; ported ahead by r16) |
| `aria/aria_mixin_2` | `ARIAMixin.h:38`: the getters and setters of ENUMERATE_ARIA_ATTRIBUTES (pure virtual; Element's overrides are `dom/element_8`) |
| `aria/aria_mixin_3` | `ARIAMixin.cpp` 28-281 + the rest of `ARIAMixin.h`: role_from_role_attribute_value, role_or_default, has_global_aria_attribute, ID references, the element(-list)-referencing attributes |
| `aria/aria_data` | `AriaData.cpp` + `AriaData.h` (constructor, build_data) |
| `aria/attribute_names`, `math_ml/attribute_names`, `x_link/attribute_names` | the three `AttributeNames.cpp` (interned by `web_initialize_strings`) |
| `aria/role_type` | `RoleType.cpp` + `RoleType.h` inlines; the two helpers of the generated classes |
| `aria/roles` | `Roles.cpp` (role_name, role_from_string, the role categories) |
| `aria/state_and_properties` | `StateAndProperties.cpp` |
| `generated/aria/aria_roles` | **generated** by `tools/gen_aria_roles` from `data/aria/AriaRoles.json` (`AriaRoles.cpp`) |
| `math_ml/math_ml_element`, `math_ml_mi_element`, `math_ml_mspace_element` | the matching `.cpp` + `.h` inlines |
| `aria/tests_aria_mathml_cases`, `aria/tests_aria_mathml` | tests (below) |
## The role classes generator
`tools/gen_aria_roles` (module, `emit_aria_roles`, and `json`/`text` copied from `tools/gen_css_values`)
is a Luce port of `Meta/Generators/generate_libweb_aria_roles.py`'s `write_implementation_file`. It reads
`data/aria/AriaRoles.json` (Ladybird's, with its `LICENSE`) and writes
`src/web/generated/aria/aria_roles.lucb`; `test.sh` builds it, regenerates into a temporary directory and
compares. The header half (the 100 classes, vtables, mixin vtables and class ids) stays the skeleton
generator's `generated/aria/types_aria_roles.lucb`. Where C++ and Luce differ:
- A function-local `static HashTable<...>` is a module variable of the fragment, filled on first use by
`aria_role_type_fill_static_table` in the C heap (DESIGN §3.3 rule 7), with the generated
`ensure_capacity(n)` before the `set`s (RoleType's own tables use `set_from`, without it), so the
tables iterate in the donor's order.
- Constructors run the bases' constructors (the first base takes the data, the others are
default-constructed, as in C++) and then install the class's vtable and class id in its RoleType and in
the RoleType of every further base along its first-base chain (`aria_role_type_set_class`; the C++
vptrs; the skeleton's "mixin" vtables, e.g. `aria_column_header_widget_vtable` at
`this.grid_cell.widget`).
- An implicit value of the JSON (a C++ expression: `true`, `100.0`, `AriaLive::Polite`) becomes the
matching case of `AriaDefaultValueType`.
- `RoleType::build_role_object` allocates the object (`aria_role_type_new`, a blob of the current
allocator) and answers the RoleType of its first-base chain, the RoleType C++'s static_casts pick.
## What other regions must know
- `aria_mixin_role_or_default` and `role_from_role_attribute_value` are real now: the role attribute's
tokens (case-insensitive), the synonyms (directory → list, img → image, presentation → none), the
required-context rules (a role's ancestors' `role_or_default`, recursively), named landmarks
(`form`/`region` need an accessible name: `dom_node_accessible_name`) and the presentation conflict
rules (focusable, or with a global ARIA attribute).
- The ARIA, MathML and XLink attribute names are interned by `web_initialize_strings`, so
`HTMLHeadingElement::aria_level` (r27) and the 54 reflected ARIA attributes of `dom/element_8` (r16)
read real names.
- MathML elements are constructed like SVG ones: `math_ml_math_ml_element_construct` runs Element's
constructor and points the four mixin tables at MathMLElement's; MathMLMiElement and
MathMLMspaceElement move them to their own. The factory (r16) makes all three.
### Signature and type changes
- `types_role_type`: `aria_supported_state_array` and `aria_supported_properties_array` are `let`s with
their C++ initializers (were unset `var`s).
- `generated/types_traits`: `AriaRoleTraits` and `AriaStateAndPropertiesTraits` filled (Traits<Enum>:
`u32_hash` of the underlying int).
- No stub signature changed.
## Deviations and notes
- **Donor quirk kept**: `RoleType::serialize_as_json` writes `required_properties()` under
`"prohibited_properties"`.
- `AriaData()`'s default constructor writes nothing: since region p2s a zeroed `ak.String` is the empty
string (C++'s default construction); the enum and bool members stay zero (uninitialized in C++).
- `role_from_role_attribute_value`'s twelve ancestor loops are one helper,
`aria_mixin_has_ancestor_with_role(this, roles)` (`first_is_one_of(ancestor->role_or_default(), ...)`);
`has_global_aria_attribute`'s `||` chain is a sequence of early returns.
- MathML's lambdas (`parse_non_percentage_value`, the scriptlevel style value) are functions.
- The ARIA element-referencing attributes' Vectors are made with `new` in the current allocator (C++
`make<Vector<...>>`); the cached JS arrays stay P3 (`aria_mixin_1`'s visit traps on one).
- None of luce-js `HANDOFF.md` §5 item 4's engine follow-ups concern this region (they are done).
## Tests
Ladybird has no unit tests for these files. `aria/tests_aria_mathml` runs 136 cases of a local oracle
(`luce-browser-tools/oracles/luce-browser-engine/aria_mathml`: oracle.cpp linked against the reference
build's LibWeb, cases.txt, expected.txt, gen_luce_cases.py, build.sh), generated into
`tests_aria_mathml_cases`: role_from_string; every role's name and categories; the role object of every
non-abstract role (flags, name source, table sizes, required context roles and owned elements in the
tables' iteration order, implicit values) through the generated classes; `role_or_default` of 59
documents (tokens, synonyms, every required-context rule incl. nested contexts, named and unnamed
landmarks, presentation/none conflicts, MathML and HTML defaults); `default_role`;
`has_global_aria_attribute`; `parse_id_reference_list`; `AriaData` and every
`state_or_property_to_string_value` for 8 elements (valid, invalid and edge values of every value type);
`serialize_as_json` of 29 elements' role objects; the factory's MathML classes; and MathML presentational
hints (dir, mathcolor, mathbackground, mathsize, displaystyle, scriptlevel, mathvariant, mspace
width/height/depth incl. the calc() concatenation) for 15 elements.
Turned on in other regions' oracles: html_elements' `<math>` document and the li/td/th roles (the
`<details>` role still waits for the CSP inline check, closure stub); svg_elements' four roles of r55
that waited for `role_from_role_attribute_value`. Two more (`<g>` with a `<title>`) still wait:
SVGTitleElement's children_changed reads the page's top-level browsing context, and the test documents'
page has no top-level traversable.
web_test: Layout 843/845 (was 841: the two css-namespace tests that stopped at
`MathMLElement::MathMLElement`), Ref 466 (was 465: mo-lspace-rspace), Crash 38 (was 37:
negative-mathsize-border-width); the expected-failure lists are rewritten.
## Compiler issues
- `writer_fmt_truncates_at_1024` (luce-browser-tools/compiler-issues): `Writer.write(f"...")` silently
cuts a formatted string at 1024 bytes (ending "..."). The generator writes long lists one value per
line, so it does not depend on it (no workaround in the code).