.. index:: pair: page; HTML Compatibility Layer
.. _doxid-ui_html_compatibility:

HTML Compatibility Layer
========================

eepp includes an HTML/CSS compatibility layer for rendering document-like content inside the UI system.

This layer is used primarily by:

* ``UIWebView``;

* ``UIMarkdownView``;

* HTML-derived widgets such as ``UIRichText``, ``UITextSpan``, HTML tables, forms, images, and inputs.

It is intentionally distinct from normal eepp application UI authoring.

For ordinary application UI, use native eepp layouts such as ``vbox``, ``hbox``, ``UIRelativeLayout``, ``UIGridLayout``, ``UIFlowLayout``, ``UISplitter``, and ``UITabWidget``. See ```ui_authoring.md```, ```ui_layout_reference.md```, and ```ui_css_for_applications.md```.

This document describes the **HTML compatibility model**, the browser-style layout concepts it implements, and the important places where it differs from a full browser engine.



.. _doxid-ui_html_compatibility_1autotoc_md840:

1. The most important boundary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

eepp has two related but different layout worlds.



.. _doxid-ui_html_compatibility_1autotoc_md841:

Native application UI
---------------------

Normal eepp application interfaces use:

.. ref-code-block:: cpp

	UILinearLayout / vbox / hbox
	UIRelativeLayout
	UIGridLayout
	UIFlowLayout
	UISplitter
	UITabWidget
	UIScrollView
	layout-width
	layout-height
	layout-weight
	layout-gravity

CSS can configure those widgets, but CSS does not replace their native layout algorithms.





.. _doxid-ui_html_compatibility_1autotoc_md842:

HTML compatibility UI
---------------------

HTML-derived widgets can instead participate in browser-style formatting contexts:

.. ref-code-block:: cpp

	block
	inline
	inline-block
	list-item
	
	flex
	inline-flex
	
	grid
	inline-grid
	
	table
	
	float / clear
	absolute / fixed / sticky positioning

The same CSS parser and property system are shared by both worlds, but the **layout semantics depend on the widget type and formatting context**.

Do not use browser layout properties merely because the stylesheet parser accepts them.







.. _doxid-ui_html_compatibility_1autotoc_md844:

2. <tt>UIWebView</tt> is the full document host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``UIWebView`` is the main host for HTML documents.

It is implemented as a ``UIScrollView`` containing an embedded ``UISceneNode`` dedicated to the loaded document.

Conceptually:

.. ref-code-block:: cpp

	UIWebView
	    scroll viewport
	        embedded UISceneNode
	            document container
	                html
	                    head
	                    body

The embedded scene gives the document its own:

* widget tree;

* stylesheet state;

* document URI;

* resource loading context;

* font-face registrations;

* navigation handling;

* text-selection context.

Use:

.. ref-code-block:: cpp

	auto* webView = UIWebView::New();
	webView->loadURI( URI( "file:///path/document.html" ) );

or an HTTP/HTTPS URI.

``UIWebView`` supports navigation history through:

.. ref-code-block:: cpp

	goHistoryBack();
	goHistoryForward();
	refresh();
	reload();
	canGoBack();
	canGoForward();

It also exposes navigation events for started, completed, and failed loads.





.. _doxid-ui_html_compatibility_1autotoc_md846:

3. <tt>UIMarkdownView</tt> uses the HTML compatibility layer too
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``UIMarkdownView`` converts Markdown to XHTML and then loads the resulting body children as eepp HTML widgets.

Its pipeline is approximately:

.. ref-code-block:: cpp

	Markdown
	    -> Markdown::toXHTML()
	    -> HTMLFormatter::HTMLBodyToXML()
	    -> eepp HTML widgets

Unlike ``UIWebView``, ``UIMarkdownView`` is not a standalone browsing context with document navigation and a dedicated embedded scene.

It is a native vertical layout hosting HTML-derived content and loads the **basic HTML default styles** needed for Markdown rendering.

Use ``UIMarkdownView`` for rendered Markdown content, not as a general browser replacement.





.. _doxid-ui_html_compatibility_1autotoc_md848:

4. HTML is parsed before eepp widgets are created
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``UIWebView`` does not feed arbitrary HTML directly into the normal XML layout parser.

HTML is first parsed with Gumbo, then serialized into strict XML through ``Tools::HTMLFormatter``.

This stage handles browser-style HTML parsing details such as:

* malformed/non-XML HTML syntax;

* omitted closing syntax where HTML permits it;

* HTML void elements;

* boolean attributes;

* normalized tag names.

The resulting strict XML is then loaded through eepp's widget creation system.

This architecture is important:

.. ref-code-block:: cpp

	HTML source
	    -> Gumbo HTML tree
	    -> strict XML representation
	    -> UIWidgetCreator
	    -> eepp widget tree

The final rendered document is therefore still made of eepp widgets.





.. _doxid-ui_html_compatibility_1autotoc_md850:

5. Only registered HTML elements are materialized
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML compatibility is not based on a generic DOM element class that accepts every possible tag.

HTML tags are mapped through ``UIWidgetCreator``.

Currently registered HTML elements include the major supported groups:

.. ref-code-block:: cpp

	document:
	    html
	    head
	    body
	
	text and inline:
	    a
	    label
	    span
	    em
	    b
	    strong
	    small
	    i
	    cite
	    kbd
	    sub
	    sup
	    time
	    u
	    ins
	    s
	    strike
	    del
	    font
	    code
	    abbr
	    tt
	    mark
	
	blocks:
	    div
	    p
	    blockquote
	    h1 ... h6
	    br
	    hr
	    pre
	
	lists:
	    ul
	    ol
	    dl
	    dt
	    dd
	    li
	
	semantic containers:
	    header
	    article
	    figure
	    figcaption
	    footer
	    main
	    section
	    nav
	    aside
	    center
	
	interactive/details:
	    details
	    summary
	
	media/replaced content:
	    picture
	    img
	    svg
	
	forms:
	    form
	    input
	    textarea
	    button
	
	tables:
	    table
	    thead
	    tbody
	    tfoot
	    tr
	    th
	    td

The exact set is defined in:

.. ref-code-block:: cpp

	src/eepp/ui/uiwidgetcreator.cpp

An unregistered tag does not automatically become a transparent generic HTML container.

Applications can register additional widget creators if they need custom tags.





.. _doxid-ui_html_compatibility_1autotoc_md852:

6. This is not a JavaScript browser runtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``<script>`` nodes are ignored by the UI layout loader.

The HTML compatibility layer should therefore be understood as:

.. ref-code-block:: cpp

	HTML parsing
	CSS styling
	document layout
	native interaction for supported elements
	navigation/resource loading

not as:

.. ref-code-block:: cpp

	HTML + DOM + JavaScript browser engine

There is no browser JavaScript environment or general DOM scripting model implied by ``UIWebView``.

If application logic is required, implement it through eepp/C++ behavior.





.. _doxid-ui_html_compatibility_1autotoc_md854:

7. Default HTML styles
~~~~~~~~~~~~~~~~~~~~~~

eepp provides built-in HTML default styles.

The basic defaults cover conventional document presentation for elements such as:

.. ref-code-block:: cpp

	body
	h1 ... h6
	p
	pre
	blockquote
	hr
	ul / ol / dl
	b / strong
	i / em
	small
	u / ins
	s / strike / del
	code / kbd
	sub / sup
	mark
	a
	summary

``UIWebView`` also loads document-oriented defaults for controls and document colors, including inputs, textareas, buttons, checkboxes, and radio buttons.

These defaults are inserted with lower selector specificity so author styles can override them.

``UIMarkdownView`` loads the basic HTML defaults rather than the complete standalone-document defaults.

The source of the defaults is:

.. ref-code-block:: cpp

	src/eepp/ui/uiwidgetcreator.cpp





.. _doxid-ui_html_compatibility_1autotoc_md856:

8. HTML attributes and native XML attributes have different cascade behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is an important distinction.

For **normal native eepp widgets**, XML attributes are treated as inline-style properties with inline specificity.

For widgets marked as HTML elements, ordinary HTML attributes are loaded with low specificity so CSS can override them in the expected HTML-like way.

For example:

.. ref-code-block:: cpp

	<img width="200" class="preview">

can still be overridden by author CSS:

.. ref-code-block:: cpp

	.preview {
	    width: 100px;
	}

The explicit HTML ``style`` attribute remains inline style:

.. ref-code-block:: cpp

	<img style="width: 200px">

and therefore has inline specificity.

This distinction exists specifically so HTML presentation attributes do not behave like native eepp XML configuration.





.. _doxid-ui_html_compatibility_1autotoc_md858:

9. Attribute selectors are supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The selector engine supports attribute selectors.

For HTML widgets, ``data-*`` attributes are stored as HTML data properties and can participate in attribute matching.

Examples:

.. ref-code-block:: cpp

	input[type="text"] {
	    ...
	}
	
	input[type="password"] {
	    ...
	}
	
	[data-state="warning"] {
	    ...
	}

Supported attribute operators include:

.. ref-code-block:: cpp

	[attr]
	[attr=value]
	[attr~=value]
	[attr|=value]
	[attr^=value]
	[attr$=value]
	[attr*=value]

For native widgets, attribute selectors operate through properties exposed by the widget property system.

For HTML widgets, ``data-*`` attributes are additionally available directly.





.. _doxid-ui_html_compatibility_1autotoc_md860:

10. Block and inline formatting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The HTML layer implements separate formatting behavior for:

.. ref-code-block:: cpp

	display: block;
	display: inline;
	display: inline-block;
	display: list-item;
	display: none;

Block and inline content is laid out through the HTML layouter system rather than native ``UILinearLayout``.

Inline text and inline widgets are integrated into ``RichText`` line construction.

This includes:

* text runs;

* line wrapping;

* inline boxes;

* atomic inline boxes;

* inline replaced elements;

* baselines;

* line-height;

* vertical alignment;

* inline background/text painting.

Block elements participate in vertical document flow and intrinsic sizing.

``display: none`` removes the element from layout and hit testing.





.. _doxid-ui_html_compatibility_1autotoc_md862:

11. Flexbox
~~~~~~~~~~~

HTML widgets support:

.. ref-code-block:: cpp

	display: flex;
	display: inline-flex;

with a dedicated ``FlexLayouter``.

The currently implemented flex state includes:

.. ref-code-block:: cpp

	flex-direction
	flex-wrap
	justify-content
	align-items
	align-content
	align-self
	
	flex-grow
	flex-shrink
	flex-basis
	order
	
	row-gap
	column-gap
	gap

Supported direction values include:

.. ref-code-block:: cpp

	row
	row-reverse
	column
	column-reverse

Wrapping includes:

.. ref-code-block:: cpp

	nowrap
	wrap
	wrap-reverse

The layouter handles multiple flex lines, grow/shrink distribution, gaps, alignment, auto margins, baseline alignment, order, percentage flex bases, intrinsic measurement, and stretching.

Children of flex containers are blockified for layout, including inline children.



.. _doxid-ui_html_compatibility_1autotoc_md863:

Important distinction
---------------------

Flexbox belongs to the HTML formatting layer.

Do not replace a normal application ``<hbox>`` with:

.. ref-code-block:: cpp

	display: flex;

unless the subtree is intentionally HTML content.

For normal application UI, ``UILinearLayout`` remains the canonical row/column layout.







.. _doxid-ui_html_compatibility_1autotoc_md865:

12. CSS Grid
~~~~~~~~~~~~

HTML widgets support:

.. ref-code-block:: cpp

	display: grid;
	display: inline-grid;

through ``GridLayouter``.

The current grid model supports properties including:

.. ref-code-block:: cpp

	grid-template-rows
	grid-template-columns
	grid-template-areas
	
	grid-auto-rows
	grid-auto-columns
	grid-auto-flow
	
	grid-row-start
	grid-row-end
	grid-column-start
	grid-column-end
	
	grid-row
	grid-column
	grid-area
	
	justify-items
	justify-self
	align-items
	align-self
	
	row-gap
	column-gap
	gap
	
	order

The track model supports:

.. ref-code-block:: cpp

	fixed lengths
	percentages
	fr tracks
	auto
	min-content
	max-content
	fit-content(...)
	minmax(...)
	repeat(...)
	auto-fill
	auto-fit
	named lines
	template areas
	implicit tracks

Grid items support definite placement, spans, automatic placement, dense auto-flow, intrinsic track sizing, and alignment.



.. _doxid-ui_html_compatibility_1autotoc_md866:

Native <tt>UIGridLayout</tt> is unrelated
-----------------------------------------

Do not confuse:

.. ref-code-block:: cpp

	UIGridLayout

with:

.. ref-code-block:: cpp

	display: grid

``UIGridLayout`` is a native eepp repeated-cell layout.

CSS Grid is implemented by the HTML compatibility layer.

They have different APIs, sizing rules, and intended uses.







.. _doxid-ui_html_compatibility_1autotoc_md868:

13. Tables
~~~~~~~~~~

HTML tables use dedicated HTML widgets and ``TableLayouter``.

Supported structural elements include:

.. ref-code-block:: cpp

	table
	thead
	tbody
	tfoot
	tr
	th
	td

The table implementation includes:

.. ref-code-block:: cpp

	intrinsic column sizing
	table-layout: auto
	table-layout: fixed
	cell padding
	cell spacing
	colspan
	row/cell sizing

Table layout is not implemented by native ``UIGridLayout``.

If the source content is HTML tabular content, use HTML table semantics.

If the application is building an interactive application data view, prefer native widgets such as ``UITableView`` or ``UITreeView``.





.. _doxid-ui_html_compatibility_1autotoc_md870:

14. Floats and <tt>clear</tt>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML widgets support:

.. ref-code-block:: cpp

	float: left;
	float: right;
	float: none;
	
	clear: left;
	clear: right;
	clear: both;

Floats participate in block/inline document formatting and create text exclusions so following inline content can wrap around them.

Floated inline elements are blockified for layout.

Floats also establish a block formatting context where applicable.

These semantics exist for document layout and should not be used as a general native application placement system.





.. _doxid-ui_html_compatibility_1autotoc_md872:

15. Positioned layout
~~~~~~~~~~~~~~~~~~~~~

The HTML property system recognizes:

.. ref-code-block:: cpp

	position: static;
	position: relative;
	position: absolute;
	position: fixed;
	position: sticky;



.. _doxid-ui_html_compatibility_1autotoc_md873:

Absolute positioning
--------------------

``absolute`` elements are removed from normal flow.

The containing block is selected from the nearest positioned HTML ancestor, with root fallback.

Insets are supported:

.. ref-code-block:: cpp

	top
	right
	bottom
	left

including percentage values where the containing block has the required definite size.

Opposing insets can determine the used size of an auto-sized positioned box.

Auto margins are also handled in the positioned constraint equation.





.. _doxid-ui_html_compatibility_1autotoc_md874:

Fixed positioning
-----------------

``fixed`` elements are positioned against the relevant scroll/document viewport rather than ordinary normal flow and are updated when scrolling changes.





.. _doxid-ui_html_compatibility_1autotoc_md875:

Sticky positioning
------------------

``sticky`` participates in normal flow and is adjusted relative to a scroll viewport while respecting the containing block.

Current sticky handling focuses on vertical top/bottom constraints.





.. _doxid-ui_html_compatibility_1autotoc_md876:

Relative positioning
--------------------

``relative`` currently participates in the positioned-element model, including containing-block and stacking behavior.

Do not assume complete browser parity for relative ``top/right/bottom/left`` displacement; the current implementation's explicit inset positioning logic is primarily implemented for absolute/fixed and sticky positioning.







.. _doxid-ui_html_compatibility_1autotoc_md878:

16. <tt>z-index</tt> and paint order
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The HTML layer has CSS-aware paint ordering rather than relying only on raw widget child order.

The current model distinguishes categories broadly corresponding to the supported CSS stacking subset:

.. ref-code-block:: cpp

	negative positioned/z-index content
	normal-flow content
	floats
	positioned auto/zero content
	positive positioned/z-index content

``z-index`` applies to positioned elements and to flex/grid items where supported.

The implementation supports stacking groups for:

.. ref-code-block:: cpp

	fixed/sticky elements
	positioned elements with applicable z-index
	flex/grid items with applicable z-index

This is intentionally a supported subset of browser stacking-context behavior, not a claim of full CSS Appendix E parity.





.. _doxid-ui_html_compatibility_1autotoc_md880:

17. CSS sizing and the box model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML widgets support browser-style CSS sizing properties:

.. ref-code-block:: cpp

	width
	height
	min-width
	min-height
	max-width
	max-height
	
	margin
	padding
	border
	box-sizing

``box-sizing`` supports:

.. ref-code-block:: cpp

	content-box
	border-box

For HTML widgets, ``width`` and ``height`` are interpreted through the CSS box model rather than merely as raw native widget dimensions.

This is one reason the HTML compatibility layer should remain conceptually separate from normal native application layout.





.. _doxid-ui_html_compatibility_1autotoc_md882:

18. Percentage sizing uses containing blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML percentage sizing is resolved against CSS containing-block dimensions.

This applies to relevant properties such as:

.. ref-code-block:: cpp

	width
	height
	margin
	padding
	position offsets
	flex-basis
	grid tracks

The implementation also distinguishes cases where percentage height cannot resolve because the containing block does not have a definite height.

In those cases, the HTML layer avoids treating the percentage as an ordinary fixed native dimension.

The root document uses the document viewport as the initial containing block for relevant root/body calculations.





.. _doxid-ui_html_compatibility_1autotoc_md884:

19. Intrinsic sizing
~~~~~~~~~~~~~~~~~~~~

The HTML layout layer has explicit intrinsic sizing support.

Concepts used internally include:

.. ref-code-block:: cpp

	minimum intrinsic width
	maximum intrinsic width
	min-content
	max-content
	fit-content
	shrink-to-fit

These are used by block, flex, grid, table, replaced-element, and out-of-flow layout.

This is different from native eepp ``WrapContent``.

They may eventually produce similar-looking results, but they are not the same algorithm.

Do not explain HTML ``min-content`` or ``max-content`` in terms of native ``SizePolicy``.





.. _doxid-ui_html_compatibility_1autotoc_md886:

20. Auto margins
~~~~~~~~~~~~~~~~

HTML formatting contexts implement context-specific auto-margin behavior.

Examples include:

* horizontal centering of normal-flow blocks;

* free-space absorption in flex layouts;

* item alignment behavior in grid/flex;

* auto margins in positioned constraint equations.

This is distinct from ordinary native-layout auto-margin handling.

The HTML layer resolves used margins for the current formatting role without treating every ``margin: auto`` as the same generic layout operation.





.. _doxid-ui_html_compatibility_1autotoc_md888:

21. Overflow is only partially browser-equivalent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The CSS property is recognized:

.. ref-code-block:: cpp

	overflow: visible;
	overflow: hidden;
	overflow: auto;
	overflow: scroll;

For HTML widgets, non- ``visible`` overflow also establishes a block formatting context.

However, the underlying native widget behavior currently maps:

.. ref-code-block:: cpp

	hidden
	auto
	scroll

to clipping of the widget content box.

It does **not** create an independent browser-like scroll container for every arbitrary HTML element.

``UIWebView`` itself provides document scrolling through its native ``UIScrollView``.

Also note that ``overflow-x`` and ``overflow-y`` currently alias the same ``overflow`` property; they are not independent axes yet.

This is an important compatibility limitation.





.. _doxid-ui_html_compatibility_1autotoc_md890:

22. <tt>visibility</tt> is not fully browser-equivalent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML widgets recognize:

.. ref-code-block:: cpp

	visibility: visible;
	visibility: hidden;
	visibility: collapse;

The current implementation maps ``hidden`` to native widget visibility.

As a result, ``visibility: hidden`` does not currently guarantee the browser behavior of preserving the element's normal-flow geometry while suppressing painting.

Flex layout has specific handling for ``visibility: collapse``, but this should not be interpreted as complete ``visibility`` parity across every formatting context.

When precise browser-compatible visibility geometry matters, verify the current behavior rather than assuming browser semantics.





.. _doxid-ui_html_compatibility_1autotoc_md892:

23. Text formatting and inheritance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML text is rendered through ``UIRichText``, ``UITextSpan``, and ``UITextNode``.

Supported text-oriented CSS includes concepts such as:

.. ref-code-block:: cpp

	font-family
	font-size
	font-style
	font-weight
	color
	text-decoration
	text-align
	text-indent
	text-transform
	line-height
	white-space
	white-space-collapse
	tab-size
	text shadow/stroke

Relevant properties participate in eepp's current inheritance system.

HTML inline elements therefore behave much more like document text than ordinary independent native application widgets.

The exact supported property set is documented in ```css_specification.md```.





.. _doxid-ui_html_compatibility_1autotoc_md894:

24. Text selection is document-wide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``UIWebView`` and ``UIMarkdownView`` both provide a ``UITextSelectionController``.

Selection can cross individual rich-text/span widget boundaries rather than being limited to a single widget.

HTML widgets support:

.. ref-code-block:: cpp

	user-select: auto;
	user-select: text;
	user-select: none;
	user-select: contain;
	user-select: all;

``-webkit-user-select`` is accepted as an alias.

The default used behavior is text-selectable unless inherited ``none`` or ``all`` semantics change it.

This is one of the important differences between document content and ordinary isolated text widgets.





.. _doxid-ui_html_compatibility_1autotoc_md896:

25. Links and navigation
~~~~~~~~~~~~~~~~~~~~~~~~

``<a>`` is represented by ``UIAnchorSpan``.

Anchor activation uses the scene navigation path.

Inside a ``UIWebView``, navigation requests are intercepted by the embedded document scene and routed back into the owning ``UIWebView``, including relative URL resolution.

This means ordinary links can navigate the current web view.

``UIWebView`` maintains its own navigation history.

Anchor interaction also cooperates with document text selection so a completed text drag does not accidentally activate the link.





.. _doxid-ui_html_compatibility_1autotoc_md898:

26. Forms
~~~~~~~~~

The compatibility layer includes basic form support.

Supported form-oriented widgets currently include:

.. ref-code-block:: cpp

	form
	input
	textarea
	button
	label

``UIHTMLInput`` hosts native eepp controls internally.

Recognized input types include:

.. ref-code-block:: cpp

	button
	checkbox
	color
	date
	datetime-local
	email
	file
	hidden
	image
	month
	number
	password
	radio
	range
	reset
	search
	submit
	tel
	text
	time
	url
	week

Not every type has a specialized native implementation. Unsupported/specialized types fall back to the generic text-input implementation unless explicitly mapped otherwise.

Current explicit native mappings include:

.. ref-code-block:: cpp

	button / submit / reset -> UIPushButton
	checkbox                -> UICheckBox
	hidden                  -> no visible child
	number                  -> UISpinBox
	password                -> password text input
	radio                   -> UIRadioButton
	other text-like types   -> UIHTMLTextInput

``textarea`` uses a ``UITextEdit`` -based implementation with ``rows`` and ``cols`` intrinsic sizing.

Forms collect named control values and can submit navigation requests.

Supported submission encodings include:

.. ref-code-block:: cpp

	application/x-www-form-urlencoded
	multipart/form-data
	text/plain

GET and POST submission paths are implemented.





.. _doxid-ui_html_compatibility_1autotoc_md900:

27. Labels
~~~~~~~~~~

``<label for="...">`` is interactive.

The label resolves the referenced widget and can activate supported controls such as checkboxes and radio buttons.

Keyboard activation is also supported.

This behavior is implemented natively rather than through JavaScript.





.. _doxid-ui_html_compatibility_1autotoc_md902:

28. Images and SVG
~~~~~~~~~~~~~~~~~~

HTML images use ``UIHTMLImage``.

They participate as replaced elements with intrinsic sizing and CSS width/height behavior.

``<svg>`` is backed by ``UISvg`` marked as an HTML element so it can participate in HTML sizing/layout.

Resource URLs can be:

.. ref-code-block:: cpp

	file URLs
	HTTP/HTTPS URLs
	data URLs where supported
	eepp resource locators

Relative document/style resources are resolved against the relevant document or stylesheet base URI.





.. _doxid-ui_html_compatibility_1autotoc_md904:

29. Stylesheets and resource loading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML documents can contain:

.. ref-code-block:: cpp

	<style>
	...
	</style>

and stylesheet links:

.. ref-code-block:: cpp

	<link rel="stylesheet" href="...">

``UIWebView`` can load local and HTTP/HTTPS stylesheets.

Relative stylesheet resource URLs are resolved against the stylesheet/document base URI when one is available.

Supported stylesheet at-rules include those documented in ```css_specification.md```, including:

.. ref-code-block:: cpp

	@import
	@media
	@font-face
	@keyframes

``@font-face`` can load local, data-backed, and HTTP/HTTPS font resources through the document scene.





.. _doxid-ui_html_compatibility_1autotoc_md906:

30. Media queries
~~~~~~~~~~~~~~~~~

The same media-query engine used elsewhere in eepp is available to HTML document styles.

Supported features are documented in ```css_specification.md```.

Document layout should still rely primarily on normal CSS layout mechanisms such as:

.. ref-code-block:: cpp

	block flow
	flex wrapping
	grid tracks
	intrinsic sizing

rather than reproducing layout entirely with breakpoint-specific absolute dimensions.





.. _doxid-ui_html_compatibility_1autotoc_md908:

31. HTML visibility and document extent inside <tt>UIWebView</tt>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``UIWebView`` maintains document viewport and content extent separately.

The document scene is updated when:

* the web view changes size;

* scrollbars appear/disappear;

* HTML layout changes;

* resources load and alter geometry;

* viewport-dependent percentages need recomputation.

The root ``html`` and ``body`` boxes are synchronized with the document viewport while still allowing content to grow beyond it.

Out-of-flow content can contribute to the final scrollable document extent when appropriate.

Fixed-position content is treated separately from normal scrollable document extent.





.. _doxid-ui_html_compatibility_1autotoc_md910:

32. Root <tt>html</tt> / <tt>body</tt> behavior is special
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The root document boxes have browser-oriented special handling.

``body`` maintains a minimum height based on:

.. ref-code-block:: cpp

	viewport height
	its local min-height
	document content extent

The root ``html`` box is kept at least large enough to cover the document viewport/content.

The body's background may propagate to the root HTML element when the root background is otherwise transparent.

These rules should not be inferred from ordinary native ``UILayout`` behavior.





.. _doxid-ui_html_compatibility_1autotoc_md912:

33. Paint order and hit testing follow the HTML layer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML positioned/floating content can be painted in an order different from raw widget child order.

Hit testing follows the corresponding HTML paint traversal when required.

This matters for:

.. ref-code-block:: cpp

	z-index
	positioned descendants
	floats
	overlapping HTML content
	flex/grid order

Do not debug overlapping HTML content by looking only at the native child insertion order.

Use the actual HTML layout/paint state.





.. _doxid-ui_html_compatibility_1autotoc_md914:

34. Structural CSS selectors can react to document structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The selector engine supports structural selectors such as:

.. ref-code-block:: cpp

	:first-child
	:last-child
	:nth-child(...)
	:nth-last-child(...)
	:first-of-type
	:last-of-type
	:nth-of-type(...)
	:nth-last-of-type(...)
	:only-child
	:only-of-type
	:empty
	:not(...)

Structural and relationship-dependent selectors are treated as volatile where needed so relevant widgets can be restyled when structure/state changes.

This is especially important for HTML-like document styling.





.. _doxid-ui_html_compatibility_1autotoc_md916:

35. CSS state rollback still uses eepp's common style engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML widgets share the same ``UIStyle`` implementation as native widgets.

That means the current limitation around properties that stop matching a pseudo-class/volatile selector also applies to HTML content.

eepp currently preserves prior values through a best-effort stateless/current-value fallback rather than a complete browser-style computed-cascade rollback model.





.. _doxid-ui_html_compatibility_1autotoc_md918:

36. Compatibility does not mean complete browser parity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The HTML layer intentionally implements a useful subset of browser layout and interaction behavior.

It should not be described as a fully compliant browser engine.

Examples of known boundaries include:

.. ref-code-block:: cpp

	no JavaScript runtime
	only registered HTML elements are materialized
	overflow does not create arbitrary per-element scroll containers
	overflow-x / overflow-y are not independent yet
	visibility semantics are not fully browser-equivalent
	relative positioning should not be assumed to implement every browser offset behavior
	stacking/paint order is a supported subset
	form controls map onto native eepp widgets
	CSS state rollback is not a complete computed-style rollback model

Other browser features should be considered supported only when they are implemented and tested in eepp.

When compatibility behavior matters, the implementation and HTML-specific unit tests are the source of truth.





.. _doxid-ui_html_compatibility_1autotoc_md920:

37. Where to look in the source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The main implementation is concentrated in:

.. ref-code-block:: cpp

	HTML host / navigation:
	    include/eepp/ui/uiwebview.hpp
	    src/eepp/ui/uiwebview.cpp
	
	HTML widget semantics:
	    include/eepp/ui/uihtmlwidget.hpp
	    src/eepp/ui/uihtmlwidget.cpp
	
	HTML parsing:
	    include/eepp/ui/tools/htmlformatter.hpp
	    src/eepp/ui/tools/htmlformatter.cpp
	
	formatting contexts:
	    src/eepp/ui/blocklayouter.cpp
	    src/eepp/ui/inlinelayouter.cpp
	    src/eepp/ui/flexlayouter.cpp
	    src/eepp/ui/gridlayouter.cpp
	    src/eepp/ui/tablelayouter.cpp
	
	text:
	    src/eepp/ui/uirichtext.cpp
	    src/eepp/ui/uitextspan.cpp
	
	HTML widgets:
	    src/eepp/ui/uihtmlimage.cpp
	    src/eepp/ui/uihtmlinput.cpp
	    src/eepp/ui/uihtmltextarea.cpp
	    src/eepp/ui/uihtmlform.cpp
	    src/eepp/ui/uihtmltable.cpp
	    src/eepp/ui/uihtmldetails.cpp
	    src/eepp/ui/uihtmllistitem.cpp
	
	Markdown:
	    src/eepp/ui/uimarkdownview.cpp
	
	HTML element registration/default CSS:
	    src/eepp/ui/uiwidgetcreator.cpp

The most useful tests are under:

.. ref-code-block:: cpp

	src/tests/unit_tests/uihtml_tests.cpp
	src/tests/unit_tests/uihtml_flex_test.cpp
	src/tests/unit_tests/uihtml_grid_test.cpp
	src/tests/unit_tests/uihtml_float_tests.cpp
	src/tests/unit_tests/uihtml_position_tests.cpp
	src/tests/unit_tests/uihtmlform_tests.cpp
	src/tests/unit_tests/uiwebview_tests.cpp





.. _doxid-ui_html_compatibility_1autotoc_md922:

38. Related documentation
~~~~~~~~~~~~~~~~~~~~~~~~~

* ```ui_introduction.md``` — introduction to the eepp UI system.

* ```ui_authoring.md``` — recommended native application UI mental model.

* ```ui_layout_reference.md``` — exact native layout semantics.

* ```ui_css_for_applications.md``` — CSS conventions for ordinary application widgets.

* ```css_specification.md``` — CSS property, selector, value, and at-rule reference.

* ```ui_inspector.md``` — runtime UI inspection and automation protocol.

* ```ui_databinding.md``` — UI data binding.

* ```ui_charts.md``` — charting widgets and chart-specific behavior.

The practical rule is simple:

Use native eepp layouts to build applications. Use the HTML compatibility layer when the content itself is HTML/Markdown/document-oriented.