The Document builds the tree

Generated components call the Dom trait in vapors-dom. The Document type in vapors-elements implements that trait over the element tree that is styled, laid out and drawn. RecordingDom, the other implementation in vapors-dom, records each call for tests.

A document starts with html and body. Components mount into body or an element below it. Each update restyles, lays out and paints the tree. When an update refuses something, ElementsApp reports the refusal (on stderr natively, in the page’s #error element on the web) and stops drawing, so it never shows a frame the document refused.

Elements it draws

KindTags
Blockhtml, body, div, p, h1 to h6, section, header, footer, main, nav, aside, article, blockquote, figure, figcaption, hr
Inlinespan, b, strong, em, i, var, code, kbd, samp, mark, abbr
Controlbutton, input (text, number, range, checkbox)
Replacedimg, svg with path, rect and circle children, gpu-surface

A user-agent stylesheet gives these elements HTML’s default display, margins, heading sizes, bold and italic, and a button style. b and strong are bold; em, i and var italic; code, kbd and samp use the bundled Geist Mono.

A button is laid out only as a flex or grid item. In a block container its inline-block display is refused. A disabled button receives no click and matches :disabled.

Input controls

input with no type, or type="text", is a text field: a caret, pointer and keyboard selection, word moves, undo and redo, paste, select-all and the platform’s IME. type="number" is typed into, stepped by the arrow keys and committed on Enter or blur; a data-scrub attribute makes a sideways drag step it. type="range" is dragged, moved by a press on its track and stepped by the arrow keys. type="checkbox" toggles on click or Space. Any other type is refused.

bind:value on a text field is a Signal<String>; on a number or range input it is a Signal<f64>. bind:checked on a checkbox is a Signal<bool>. The field, number, slider and checkbox demos on the examples page show each one.

Elements it refuses

The compiler accepts more of HTML than the tree draws. The document refuses these tags when it updates, naming the unsupported tag:

TagsStatus at this revision
br, aNot yet supported
canvasNot yet supported
textarea, select, option, optgroup, label, fieldset, legend, ul, ol, li, pre, table, caption, col, colgroup, tbody, thead, tfoot, tr, td, th, meter, progressNot yet supported
dialog, details, summaryNot yet supported

Any other tag the compiler accepts, small among them, is not supported. bind:value on select or textarea compiles, but the document refuses those elements at this revision.

Events

The document fires click, dblclick, pointerdown, pointermove, pointerup, pointercancel, gotpointercapture, lostpointercapture, keydown, keyup, focus, blur, focusin, focusout, input, change, selectionchange and paste, and a component’s own declared events. A listener for any other event, such as onmouseover, is refused when the document updates, because it would never run.

  • A hit test finds the topmost box under the pointer, in paint order. Inside a paragraph it finds the inline element under the pointer, so <span onclick> receives its own clicks.
  • click fires on the nearest common ancestor of the press and release targets. Events bubble from the target through its ancestors, and stop_propagation() ends that.
  • A touch arrives as a tap, which fires one click.
  • A pointer event carries its position (client, offset, pointer), and a handler can take pointer capture with set_pointer_capture.
  • :hover is set on the element under the pointer and its ancestors. :active is set from press to release.
  • pointer-events: none and visibility: hidden exclude a box from hit testing.

Focus and keyboard

tabindex="0" and tabindex="-1" make an element focusable; buttons and inputs are focusable by default. Tab and Shift+Tab move focus in document order and fire the focus events in Chromium’s order. :focus, :focus-within and :focus-visible are set, and :focus-visible draws the user-agent outline ring unless the component sets outline. Focus is kept across a window losing and regaining focus, and after each update the document moves it off an element that is no longer focusable.

Space and Enter press a focused button, Space toggles a checkbox and the arrow keys move a range input or step a number field.

Scrolling

overflow: scroll and overflow: auto on an element make a scroll region, scrolled by wheel and by touch. Its overlay thumbs are styled by scrollbar-color and scrollbar-width. The page itself does not scroll: overflow: scroll or auto on html or body is refused. A touch scroll keeps moving after the finger lifts and slows down on the curve Chrome on Android uses, and the thumbs fade as Chrome on Android’s overlay thumbs do. Wheel momentum and position: sticky are not built. The scroll demo has two regions side by side under a fixed bar.

Images and icons

An img draws an image the application registered with Document::register_image under the name in its src, sized as a replaced box from its CSS width and height. An image inside a line of text is refused: give it display: block or put it in a flex or grid container. alt is not read.

An icon is an inline <svg viewBox width height> whose children are stroked <path> elements (M, L, H, V, A and Z commands, fill="none", stroke="currentColor"), at most 256 device pixels on a side, with aria-hidden="true" or role="img" and an aria-label. Icons are drawn into the same texture as text glyphs.

Any other inline <svg> of <path>, <rect> and <circle> elements is drawn as shapes: fills and strokes are turned into triangles, rectangles and circles are drawn from their exact outlines, and edges are antialiased on the GPU after the transform. fill, stroke and stroke-width come from CSS or attributes. Other SVG elements, gradients and text in SVG are refused.

A title attribute is the element’s accessible name or description and shows as a tooltip after 500 ms, following Chromium’s desktop rules; img and svg do not show one yet.

Accessibility

The document keeps an accessibility tree: a node per element with a role (a WAI-ARIA 1.2 role token, or the implicit role of a button, link, text field, checkbox, slider, number field or named section), a name, a value, states and bounds, read from the last update. The framework’s corpus compares that tree with Chromium 155’s. A driver finds a node by role and name and presses, focuses, types into it or sends it keys (Document::drive, with JSON requests), for tests; Accessibility tree and driving lists the commands and refusals. In the browser build the tree is copied into hidden DOM elements beside the canvas; native builds have no operating-system adapter yet.

Layout

Layout uses Taffy 0.15 for block, flex and grid containers, and Parley for text.

  • Grid: grid-template-columns and grid-template-rows with lengths, %, fr, auto, min-content, max-content, minmax() and repeat() with a count; auto tracks, grid-auto-flow including dense, and line and span placement. Line names and repeat(auto-fill) or repeat(auto-fit) are refused.
  • Sizing: min-content, max-content and fit-content in width, height and flex-basis; refused in min-* and max-*. calc() with a % term is resolved against its basis.
  • Position: relative, absolute and fixed, with top, right, bottom and left in px or %. sticky is not supported.
  • Stacking: z-index on positioned boxes and on flex and grid items creates stacking contexts, which order both painting and hit testing.
  • Clipping: overflow: hidden and overflow: clip clip descendants to a rectangle at the padding box; scroll and auto clip and scroll. A clip with a border-radius is refused.

Inline text

A block’s consecutive inline content is laid out as one run: white space is collapsed across element boundaries and each inline element keeps its own text style. The document reads font-style, font-weight (including bolder and lighter), letter-spacing and left-to-right text-align. An inline element can have a background, painted behind its text on each line it covers.

The document refuses, naming the element:

  • an inline element whose font size or line height differs from its block’s;
  • right-to-left text;
  • a block inside an inline element;
  • margin, padding or a border on an inline element;
  • an inline-block outside a flex or grid container.

Paint

  • Solid borders with a width and colour per side. dashed, dotted and double are refused.
  • Circular corner radii in px. A % radius is refused, and so is a radius where two different border widths meet.
  • Outer box-shadow lists with offset, blur and spread. inset and a negative blur are refused.
  • outline with a width, style, colour and offset, drawn outside the border box.
  • The cursor property sets the pointer over the hovered element.

The framework’s tests compare layout fixtures with Chromium’s layout (within 1/64 px for boxes, 0.1 px for inline text) and paint fixtures with Chromium’s screenshots at 1x and 2x.

CSS properties not applied yet

vapors-css parses more properties than the document applies. A property the document does not apply yet is refused when its computed value differs from its initial value. The refusal names the property, the element and the declaration’s position.

PropertiesStatus at this revision
transition-*, animation-*, transform, text-decoration, font-feature-settings, font-variation-settingsNot yet supported
opacity, filterNot yet supported
user-selectNot yet supported
container-type, container-nameNot yet supported

Updates and frames

An update reuses unaffected results and recomputes elements whose style or layout depends on a change: the document keeps each element’s computed style, each text layout and each box’s layout cache between updates. A randomized test compares every incremental update with an update from scratch.

ElementsApp asks for a frame only when the document changed, so an unchanged interface needs no continuous redraw loop. Application activity can request more frames. Platform::waker lets an application ask for a frame from outside its event handler, for work that finishes elsewhere.

The performance page explains targeted updates, retained layout and drawing data, scrolling, and the work that remains at runtime.

Mount a component in an application

There is no project template at this revision. crates/demos/src/lib.rs and crates/web-demo/src/main.rs show the steps: create a Document with a FontSystem, mount the component into the document’s body, pass the document to ElementsApp::new, and start it with vapors_platform::run. The same code runs in a native window and on the web canvas. An application with its own renderer draws it inside a gpu-surface element, sized and placed by the document’s layout. A 3D scene is drawn the same way, through the scene components described in HTML, SVG and 3D in one frame.