Crate rdom_core 

rdom-core — arena-backed DOM for Rust

A pure DOM tree with no rendering dependencies. Node / Element / Text / Comment / Fragment types, full tree mutation, attributes, classes, and (in later phases) query selectors, events, and O(1) index lookups.

Designed to be paired with rdom-tui for terminal rendering, or used standalone for headless tree manipulation, tests, templates, and hypothetical alternative renderers.

Quick tour

use rdom_core::{Dom, AdjacentPosition};

let mut dom: Dom = Dom::new();
let root = dom.root();

let hero = dom.create_element("div");
dom.node_mut(hero).set_id("hero").unwrap();
dom.node_mut(hero).add_class("active").unwrap();

let title = dom.create_element("h1");
let text = dom.create_text_node("Welcome");
dom.node_mut(title).append_child(text).unwrap();
dom.node_mut(hero).append_child(title).unwrap();
dom.node_mut(root).append_child(hero).unwrap();

assert_eq!(dom.node(root).child_element_count(), 1);
assert_eq!(dom.node(hero).first_element_child().unwrap().tag_name(), Some("h1"));

Modules

selectors

CSS selector grammar — tokenizer + parser + AST.

Structs

AbortController

The write end of an abort pair — fires the signal via abort.

AbortSignal

The read end of an abort pair — carried by listeners so dispatch can check whether they should still fire.

ChildIter

Iterator over all direct children (any node type), in document order.

DocumentPosition

Bitflags matching MDN’s Node.compareDocumentPosition return value. Multiple bits can be set — e.g. CONTAINED_BY | FOLLOWING when the other node is a descendant (descendants are considered “following” in document order).

Dom

DomStringMap

Read-side view of el.dataset. Borrows the element via NodeRef; lookup converts a camelCase key to a data-* attribute name on the fly.

DomStringMapMut

Write-side view of el.dataset. Borrows the element via NodeMut; mutations route through set_attribute / remove_attribute so the existing attribute-change mutation observer fires.

DomTokenList

Snapshot of an element’s ordered class tokens (DOM Element.classList read-side view). Re-construct via the element accessor to refresh after a class mutation.

DomTokenListMut

Mutable handle to an element’s class tokens. Holds a NodeMut so mutations route through the existing class-set machinery (add_class / remove_class / replace_class), keeping cascade dirty-tracking and the per-class index in sync.

ElementChildIter

Iterator over element children only.

Event

Minimal event — just routing state. Attach payload via a typed wrapper in rdom-tui or the caller’s crate.

EventCtx

Context passed to a handler: mutable Event + mutable Dom.

HtmlCollection

Snapshot of element ids captured at construction with name-based lookup. Used by form.elements, getElementsByTagName, etc.

InputDetail

beforeinput / input event payload, per UI Events / Input Events Level 2.

KeyboardDetail

keydown / keypress / keyup payload.

KeyboardModifiers

Four-boolean modifier set, matching the KeyboardEvent.{ctrl,shift,alt,meta}Key and MouseEvent.{ctrl,shift,alt,meta}Key accessor shape.

ListenerId

Handle returned from add_event_listener — pass to remove_event_listener to detach this specific registration.

ListenerOptions

Options for add_event_listener — matches the DOM spec object.

MouseDetail

Pointer event payload — click, mousedown, mouseup, mousemove, wheel, contextmenu.

NodeId

NodeList

Snapshot of node ids captured at construction. item(i) and iter() resolve against the borrowed &Dom; if a node has been removed since the snapshot, the resolution returns None for that slot (filtered out by iter()).

NodeMut

Mutable handle. All mutations go through this wrapper so future index maintenance hooks (Phase 4) have a single chokepoint.

NodeRef

Read-only handle to a node in the arena.

ObserverId

Handle returned from add_mutation_observer. Pass to remove_mutation_observer to unregister.

Position

A position within the DOM’s text content.

Range

A range of text in document order — start precedes or equals end. Built in document order by Dom::selection_range, which accepts any two positions and sorts them; Range::ordered_unchecked trusts the caller’s order.

Selection

Document-level selection. Two positions — anchor at the start of the interaction (e.g., mousedown, Shift+Click origin) and focus at the current cursor position.

SelectionSerial

A reading of Dom::selection_serial: a counter that advances on every actual selection change. Two equal readings mean the selection was not touched in between; a later reading compares greater (the counter is a u64, so it does not wrap in practice). An opaque bookkeeping value — no web API exposes it; new / get exist for tests and for backends that persist a reading.

SubmitDetail

submit event payload, per HTML §4.10.21.3 form submission.

ToggleDetail

toggle event payload — emitted by <details> and <dialog> when their open/closed state changes.

TransitionDetail

transitionstart / transitionend / transitioncancel event payload. CSS Transitions Level 1 §5.1.

Enums

ActivationPhase

Which activation step the Dom’s hook is being asked to run.

AdjacentPosition

Position relative to a reference node, for insert_adjacent*.

ContentEditableState

A contenteditable attribute’s explicit state (HTML §6.8.1). The inherit state is the absence of one (None).

DomError

EventDetail

Typed payload carried on Event::detail.

EventPhase

Which phase of dispatch is currently running.

FormEnctype

A form’s entry-list encoding — the enctype / formenctype enumerated attribute (HTML §4.10.19.6). Keywords are ASCII case-insensitive; the missing and invalid value default is UrlEncoded.

FormMethod

A form’s submission method — the method / formmethod enumerated attribute (HTML §4.10.19.6). Keywords are ASCII case-insensitive; the missing and invalid value default is Get.

InputType

UI Events InputEvent.inputType value.

InputTypeState

The state of an <input>’s type attribute (HTML §4.10.5, the table of keywords and states). rdom renders only some of them; the rest are still recognized so an unshipped type such as date is not mistaken for Text.

InteractionKind

Which interaction state changed. Fired by Dom::set_hovered / Dom::set_focused / Dom::set_focus_visible / Dom::set_active so pseudo-class matches (:hover, :focus, :focus-within, :focus-visible, :active) can invalidate cleanly. :hover, :focus-within and :active also match every ancestor of the element named, so their prev / next stand for those chains.

InvariantViolation

MouseButton

DOM MouseEvent.button mapping.

Mutation

One DOM mutation notification.

NodeData

Per-type payload.

NodeOrString

Either an existing node (by id) or a string to be wrapped in a fresh text node. Built via From impls so call sites read naturally — see module docs for an example.

NodeType

DOM-spec node types with the numeric values the spec assigns.

ToggleState

Open/closed state for <details> and <dialog> toggle event detail.

Constants

VOID_ELEMENTS

The void elements of HTML §13.3 (serialization) — elements that never have children and are serialized without an end tag. Shared with rdom-parser, which treats a start tag of one of these as the whole element; keeping one list means what the parser accepts is exactly what the serializer emits.

Traits

MutationObserver

Observer callback trait. Receives a mutable &mut Dom<Ext> so observers can READ freely — but any attempt to mutate the tree inside observe() panics via the is_observing guard. Installing or removing observers from inside the callback is allowed (the web’s MutationObserver.disconnect() inside the callback): a removed observer — including the one currently running — receives nothing further; an added one receives only later records.

Functions

is_void_element

Is tag (lowercase) one of VOID_ELEMENTS?

Type Aliases

ActivationHook

The Dom’s activation-behavior hook (DOM §2.9 steps 5.5 and 11). One per Dom; it receives every dispatched event and decides by target and event type whether the target has activation behavior. Runs regardless of stopPropagation().

FormControlsCollection

Alias for form.elements’s return type. The web platform distinguishes these at the IDL level but uses the same shape; rdom collapses them to a single struct + a type alias.

Result

ValidityHook

A backend’s constraint check: whether candidate id satisfies its constraints. The validity states need values, patterns and state the substrate does not model (rdom-tui’s validation builtin computes them), so the substrate asks the backend through this hook — a plain fn, so matching (&self) can call it. Installed with Dom::set_validity_hook.