blitz_dom/

lib.rs

//! The core DOM abstraction in Blitz
//!
//! This crate implements a flexible headless DOM ([`BaseDocument`]), which is designed to emebedded in and "driven" by external code. Most users will want
//! to use a wrapper:
//!
//!  - [`HtmlDocument`](https://docs.rs/blitz-html/latest/blitz_html/struct.HtmlDocument.html) from the [blitz-html](https://docs.rs/blitz-html) crate.
//!    Allows you to parse HTML (or XHTML) into a Blitz [`BaseDocument`], and can be combined with a markdown-to-html converter like [comrak](https://docs.rs/comrak)
//!    or [pulldown-cmark](https://docs.rs/pulldown-cmark)) to render/process markdown.
//!  - [`DioxusDocument`](https://docs.rs/dioxus-native/latest/dioxus_native/struct.DioxusDocument.html) from the [dioxus-native](https://docs.rs/dioxus-native) crate.
//!    Combines a [`BaseDocument`] with a Dioxus `VirtualDom` to enable dynamic rendering and event handling.
//!
//! It includes: A DOM tree respresentation, CSS parsing and resolution, layout and event handling. Additional functionality is available in
//! separate crates, including html parsing ([blitz-html](https://docs.rs/blitz-html)), networking ([blitz-net](https://docs.rs/blitz-html)),
//! rendering ([blitz-paint](https://docs.rs/blitz-paint)) and windowing ([blitz-shell](https://docs.rs/blitz-shell)).
//!
//! Most of the functionality in this crates is provided through the  struct.
//!
//! `blitz-dom` has a native Rust API that is designed for higher-level abstractions to be built on top (although it can also be used directly).
//!
//! The goal behind this crate is that any implementor can interact with the DOM and render it out using any renderer
//! they want.
//!

#![allow(clippy::collapsible_if)]

// TODO: Document features
// ## Feature flags
//  - `default`: Enables the features listed below.
//  - `tracing`: Enables tracing support.

pub const DEFAULT_CSS: &str = include_str!("../assets/default.css");
pub const BULLET_FONT: &[u8] = include_bytes!("../assets/moz-bullet-font.otf");

/// The DOM implementation.
///
/// This is the primary entry point for this crate.
mod document;

/// The nodes themsleves, and their data.
pub mod node;

mod config;
mod debug;
mod events;
pub mod font_fallback;
mod font_metrics;
mod form;
mod html;
/// Loading of `<iframe>` elements into sub-documents.
mod iframe;
/// Integration of taffy and the DOM.
mod layout;
mod mutation_record;
mod mutator;
pub mod paint_damage;
/// Engine-backed CSSOM operations used by script bindings.
pub mod platform;
mod query_selector;
pub mod range;
pub mod release;
mod resolve;
mod select;
mod selection;
#[cfg(feature = "shadow-dom")]
mod shadow;
pub mod stash_policy;
/// Implementations that interact with servo's style engine
mod stylo;
mod stylo_to_cursor_icon;
mod stylo_to_kurbo;
mod stylo_to_parley;
mod traversal;
/// Versioned storage for the nodes of the DOM tree.
mod tree;

mod url;

pub use stylo_to_kurbo::resolve_2d_transform;

pub mod net;
pub mod util;

#[cfg(feature = "accessibility")]
pub mod accessibility;
/// The role vocabulary [`accessibility::implicit_role`] answers in.
///
/// Re-exported rather than left to the caller to depend on: a second copy of
/// `accesskit` in the graph makes its `Role` a different type from this one,
/// and the error that produces names the same enum on both sides of a
/// mismatch. Anything consuming the role rules gets the vocabulary from the
/// crate that owns them.
#[cfg(feature = "accessibility")]
pub use accesskit;

#[cfg(feature = "custom-widget")]
pub use crate::node::Widget;

#[cfg(feature = "shadow-dom")]
pub use crate::node::{
    CustomElement, CustomElementCtx, CustomElementDefinition, CustomElementRegistry,
    ShadowRootData, ShadowRootMode,
};
pub use blitz_traits::node_id::NodeId;
pub use config::{DocumentConfig, StyleThreading};
pub use document::{
    AnimationPacing, BaseDocument, DocGuard, DocGuardMut, Document, PlainDocument,
    PreClickActivation,
};
/// Per-resolve layout counters. Present only with `log-phase-times`, which is
/// the same feature that pays for the counting.
#[cfg(feature = "log-phase-times")]
pub use layout::layout_counters;
pub use markup5ever::{
    LocalName, Namespace, NamespaceStaticSet, Prefix, PrefixStaticSet, QualName, local_name,
    namespace_prefix, namespace_url, ns,
};
pub use mutation_record::DomMutation;
pub use mutator::DocumentMutator;
pub use node::{Attribute, DocumentData, ElementData, Node, NodeData, SelectData, TextNodeData};
pub use paint_damage::PaintDamage;
pub use range::{LiveRange, RangeBoundary, RangeBounds, RangeContent};
// Re-exported because `PaintDamage` takes and returns `kurbo::Rect` across the
// crate boundary. A consumer that pulls kurbo in itself and lands on a
// different version gets a type mismatch on a name that looks identical.
pub use kurbo;
pub use parley::FontContext;
pub use tree::NodeTree;

/// Convert a Blitz [`NodeId`] into a [`taffy::NodeId`] (which wraps a `u64`).
#[inline]
pub fn taffy_node_id(id: NodeId) -> taffy::NodeId {
    taffy::NodeId::from(id.as_u64())
}

/// Convert a [`taffy::NodeId`] produced by [`taffy_node_id`] back into a Blitz [`NodeId`].
#[inline]
pub fn dom_node_id(id: taffy::NodeId) -> NodeId {
    NodeId::from_u64(u64::from(id))
}
pub use style::Atom;
pub use style::invalidation::element::restyle_hints::RestyleHint;
pub use style::media_queries::MediaType;
pub type SelectorList = selectors::SelectorList<style::selector_parser::SelectorImpl>;
pub use events::{EventDriver, EventHandler, NoopEventHandler};
pub use html::{DummyHtmlParserProvider, HtmlParserProvider};
pub use util::{Point, decode_font_bytes};

/// Convenience builder for the one-font case: produces a [`FontContext`] with
/// system-font discovery disabled and the supplied font registered as the
/// fallback for every generic family. The standard setup for WASM, where
/// browsers don't expose system fonts. WOFF/WOFF2 inputs are decoded
/// automatically.
pub fn build_single_font_ctx(font_data: &[u8]) -> FontContext {
    use parley::fontique::{Blob, Collection, CollectionOptions, GenericFamily, SourceCache};
    use std::sync::Arc;

    let mut ctx = FontContext {
        source_cache: SourceCache::new_shared(),
        collection: Collection::new(CollectionOptions {
            shared: false,
            system_fonts: false,
        }),
    };
    let decoded = decode_font_bytes(font_data).into_owned();
    let registered = ctx
        .collection
        .register_fonts(Blob::new(Arc::new(decoded) as _), None);
    let family_ids: Vec<_> = registered.iter().map(|(id, _)| *id).collect();
    for generic in [
        GenericFamily::SansSerif,
        GenericFamily::Serif,
        GenericFamily::Monospace,
        GenericFamily::SystemUi,
    ] {
        ctx.collection
            .append_generic_families(generic, family_ids.iter().copied());
    }
    ctx
}