bliss_dom/
lib.rs

1//! The core DOM abstraction in Bliss
2//!
3//! This crate implements a flexible headless DOM ([`BaseDocument`]), designed to be embedded in and driven by external code.
4//! Most users will want to use a wrapper:
5//!
6//! - [`HtmlDocument`](https://docs.rs/bliss-html/latest/bliss_html/struct.HtmlDocument.html) from [bliss-html](https://docs.rs/bliss-html) — parse HTML into a `BaseDocument`
7//! - [`DioxusDocument`](https://docs.rs/dioxus-native/latest/dioxus_native/struct.DioxusDocument.html) from [dioxus-native](https://docs.rs/dioxus-native) — dynamic rendering with Dioxus
8//!
9//! This crate provides: DOM tree construction and mutation, CSS parsing and style resolution,
10//! layout computation (via taffy), text layout (via parley), event handling, form submission,
11//! script execution, text selection, and URL resolution.
12//!
13//! Companion crates: [bliss-html](https://docs.rs/bliss-html) (parsing), [bliss-net](https://docs.rs/bliss-net) (networking),
14//! [bliss-paint](https://docs.rs/bliss-paint) (rendering), [bliss-shell](https://docs.rs/bliss-shell) (windowing).
15//!
16//! ## Feature Flags
17//!
18//! - `tracing`: Enable `tracing` spans for performance instrumentation
19//! - `incremental`: Enable incremental layout with damage propagation (default: full relayout)
20//! - `parallel-construct`: Parallelize inline layout construction with rayon
21//! - `accessibility`: Enable accessibility tree support
22//! - `file_input`: Enable file upload form controls
23//! - `serde`: Enable serialization support
24
25pub const DEFAULT_CSS: &str = include_str!("../assets/default.css");
26pub const BULLET_FONT: &[u8] = include_bytes!("../assets/moz-bullet-font.otf");
27
28const INCREMENTAL: bool = cfg!(feature = "incremental");
29const NON_INCREMENTAL: bool = !INCREMENTAL;
30
31/// The core DOM implementation: [`BaseDocument`], [`DocGuard`], [`DocGuardMut`], [`Document`], [`PlainDocument`].
32///
33/// `BaseDocument` manages the node tree, style system, layout state, event handlers,
34/// and all cross-cutting concerns. Most of the high-level APIs live as methods on this struct.
35mod document;
36
37/// DOM node types: [`Node`], [`NodeData`], [`ElementData`], [`Attribute`], [`TextNodeData`].
38///
39/// Nodes are stored in [`BaseDocument`]'s arena and referenced by `usize` IDs.
40/// `ElementData` holds tag names, attributes, computed styles, layout state, and inline text data.
41pub mod node;
42
43/// Document construction options: [`DocumentConfig`].
44///
45/// Controls viewport, base URL, user-agent stylesheets, font context, and provider
46/// implementations for networking, navigation, shell, and HTML parsing.
47mod config;
48/// Debug and inspection utilities: `print_taffy_tree`, `debug_log_node`.
49///
50/// Methods on [`BaseDocument`] for dumping layout trees, inline content,
51/// and node metadata to stdout for debugging purposes.
52mod debug;
53/// Policy-based DOM controller: [`PolicyDomController`].
54///
55/// Provides sandboxing and security restrictions on DOM mutations.
56/// Used to enforce content-security policies and prevent unauthorized
57/// script-driven modifications.
58mod dom_control;
59/// DOM event system: [`EventDriver`], [`EventHandler`], [`NoopEventHandler`].
60///
61/// Sub-modules:
62/// - `driver`: Event dispatch and lifecycle
63/// - `focus`: Focus management (tab navigation, focusin/focusout)
64/// - `keyboard`: Keyboard event handling
65/// - `pointer`: Pointer/mouse/touch event handling
66/// - `ime`: Input method editor composition events
67mod events;
68/// Font metrics resolution for text measurement.
69///
70/// Caches parley `FontMetrics` per font family and style, used during
71/// inline layout construction to size text runs accurately.
72mod font_metrics;
73/// HTML form submission: form data construction, encoding, and navigation.
74///
75/// Implements the [form submission algorithm](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#form-submission-algorithm)
76/// including form data set construction, URL-encoded and multipart encoding,
77/// and navigation to the action URL.
78mod form;
79/// HTML parsing trait: [`HtmlParserProvider`], [`DummyHtmlParserProvider`].
80///
81/// Allows pluggable parsing of `innerHTML` into the DOM tree.
82/// The `DummyHtmlParserProvider` is a no-op placeholder; real parsing
83/// comes from [bliss-html](https://docs.rs/bliss-html).
84mod html;
85/// Layout tree construction, computation, and damage tracking.
86///
87/// Sub-modules:
88/// - `construct`: Builds the layout tree (inline layout, anonymous blocks, layout children)
89/// - `damage`: Damage flags for incremental layout
90/// - `inline`: Inline/block layout via parley
91/// - `list`: List-item marker generation
92/// - `replaced`: Replaced element sizing (images, canvas)
93/// - `table`: Table layout integration
94///
95/// Uses [taffy](https://docs.rs/taffy) as the block/flex/grid layout engine.
96mod layout;
97/// High-level DOM mutation API: [`DocumentMutator`].
98///
99/// Provides safe, ergonomic methods for creating, inserting, moving, and removing nodes,
100/// setting attributes, managing inline styles, and handling form control state.
101/// Acquired via [`BaseDocument::mutate()`].
102mod mutator;
103/// CSS selector matching: `querySelector` / `querySelectorAll`.
104///
105/// Finds elements in the DOM tree matching a CSS selector string,
106/// using Servo's `selectors` crate for parsing and matching.
107mod query_selector;
108/// Style resolution and layout computation pipeline.
109///
110/// Orchestrates: message processing → scroll animation → style resolution →
111/// damage propagation → layout children construction → deferred tasks →
112/// style-to-taffy flush → layout computation → damage clearing.
113///
114/// Entry point: [`BaseDocument::resolve()`].
115mod resolve;
116/// Script engine abstraction: [`ScriptEngine`], [`NoopScriptEngine`], [`BoxedScriptEngine`].
117///
118/// Provides a pluggable interface for running JavaScript or other scripting languages
119/// in a sandboxed execution context. The `NoopScriptEngine` is the default placeholder.
120mod script;
121/// Text selection state for non-input elements.
122///
123/// Tracks anchor/focus endpoints across inline roots, including anonymous blocks
124/// whose IDs may change across layout reconstructions. Used by event handling
125/// to implement click-to-select and drag-to-extend.
126mod selection;
127/// Integration with Servo's style engine (stylo).
128///
129/// Bridges Servo's CSS selector matching, property declaration resolution,
130/// and cascade logic into bliss-dom's node system. Provides the computed
131/// style data used by layout.
132mod stylo;
133/// Conversion from Servo's `cursor` CSS property values to system cursor icons.
134///
135/// Maps CSS cursor keywords (pointer, text, grab, etc.) to
136/// platform-specific cursor representations for [`bliss-shell`].
137mod stylo_to_cursor_icon;
138/// Conversion from Servo's computed styles to parley's text layout styles.
139///
140/// Translates CSS font properties (font-family, size, weight, style, letter-spacing,
141/// line-height, text-decoration, etc.) into parley's `Style` and `StyleProperty` types
142/// for text layout and shaping.
143mod stylo_to_parley;
144/// DOM tree traversal utilities: [`TreeTraverser`], [`AncestorTraverser`].
145///
146/// Provides iterators for pre-order DOM traversal, ancestor chain walking,
147/// document-order comparison, inline-root collection across anonymous blocks,
148/// and subtree mutation iteration.
149mod traversal;
150
151/// Engine tests
152#[cfg(test)]
153mod tests;
154/// Document URL resolution and Servo `UrlExtraData` integration.
155///
156/// Wraps `url::Url` in a thread-safe `ServoArc` for use by Servo's style system.
157/// Provides relative URL resolution for `<a href>`, `<img src>`, `@import`, etc.
158mod url;
159
160/// Networking and resource loading.
161///
162/// Types for HTTP requests, resource handling (CSS, images, fonts),
163/// and the [`StylesheetHandler`] that loads external stylesheets.
164/// Requires the `net` provider configured in [`DocumentConfig`].
165pub mod net;
166/// Shared utility types.
167///
168/// Exports [`Point`] and other geometry primitives used across the bliss crate family.
169pub mod util;
170
171#[cfg(feature = "accessibility")]
172mod accessibility;
173
174pub use config::DocumentConfig;
175pub use document::{BaseDocument, DocGuard, DocGuardMut, Document, PlainDocument};
176pub use dom_control::PolicyDomController;
177pub use markup5ever::{
178    LocalName, Namespace, NamespaceStaticSet, Prefix, PrefixStaticSet, QualName, local_name,
179    namespace_prefix, namespace_url, ns,
180};
181pub use mutator::DocumentMutator;
182pub use node::{Attribute, ElementData, Node, NodeData, TextNodeData};
183pub use parley::FontContext;
184pub use script::{
185    BoxedScriptEngine, EventHandled, ExecutionContext, NoopScriptEngine, ScriptEngine, ScriptError,
186    ScriptErrorCallback, ScriptLanguage, ScriptValue,
187};
188pub use style::Atom;
189pub use style::invalidation::element::restyle_hints::RestyleHint;
190pub type SelectorList = selectors::SelectorList<style::selector_parser::SelectorImpl>;
191pub use events::{EventDriver, EventHandler, NoopEventHandler};
192pub use html::{DummyHtmlParserProvider, HtmlParserProvider};
193pub use util::Point;
bliss_dom/lib.rs

bliss_dom/
lib.rs
