apace_dom/

lib.rs

//! The core DOM abstraction in Apace
//!
//! 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/apace-html/latest/apace_html/struct.HtmlDocument.html) from the [apace-html](https://docs.rs/apace-html) crate.
//!    Allows you to parse HTML (or XHTML) into a Apace [`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 ([apace-html](https://docs.rs/apace-html)), networking ([apace-net](https://docs.rs/apace-html)),
//! rendering ([apace-paint](https://docs.rs/apace-paint)) and windowing ([apace-shell](https://docs.rs/apace-shell)).
//!
//! Most of the functionality in this crates is provided through the  struct.
//!
//! `apace-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;
/// CSSOM stylesheet access (`document.styleSheets`, `CSSStyleSheet`, `CSSRule`)
mod cssom;
mod debug;
mod events;
mod font_metrics;
mod form;
mod html;
/// Loading of `<iframe>` elements into sub-documents.
mod iframe;
/// Integration of takia and the DOM.
mod layout;
#[cfg(all(test, feature = "system-fonts"))]
mod layout_drop_tests;
#[cfg(test)]
mod layout_move_tests;
mod mutator;
mod placeholder;
#[cfg(all(test, feature = "system-fonts"))]
mod placeholder_tests;
pub mod profile;
mod query_selector;
mod radio;
#[cfg(test)]
mod radio_tests;
mod resolve;
mod resource_queue;
mod resources;
#[cfg(all(test, feature = "system-fonts"))]
mod style_damage_tests;
pub use resources::{
    ImageLoadEvent, ImageLoadStatus, ImageRequestId, ResourceLimits, ResourceStats,
};
/// Computation of resolved CSS property values (`getComputedStyle()`)
mod resolved_style;
/// Scrolling of nodes and the viewport, and scroll animations.
mod scrolling;
mod selection;
/// Implementations that interact with servo's style engine
mod stylo;
mod stylo_device;
mod stylo_to_cursor_icon;
mod stylo_to_kurbo;
mod stylo_to_parley;
mod top_layer;
pub mod traversal;
/// Versioned storage for the nodes of the DOM tree.
mod tree;
pub use top_layer::{MAX_TOP_LAYERS, TopLayer, TopLayerConfig, TopLayerError};
#[cfg(all(test, feature = "system-fonts"))]
mod top_layer_tests;

mod url;

pub use cssom::{CssRuleInfo, CssomError};
pub use resolved_style::{
    css_property_is_supported, parse_transform_matrix, resolved_style_property_names,
};
pub use stylo_to_kurbo::resolve_2d_transform;

pub mod net;
pub mod util;

#[cfg(feature = "accessibility")]
mod accessibility;

pub use crate::layout::paint_tree::{HoistedPaintChild, StackingContext, hoisted_child_position};
pub use crate::layout::replaced::IntrinsicSizes;
pub use crate::layout::text_transform::{full_size_kana, full_width};
#[cfg(feature = "custom-widget")]
pub use crate::node::Widget;

pub use apace_traits::node_id::NodeId;
// Re-export takia: it is part of apace-dom's public API (e.g. `Node::style`,
// `Node::final_layout`)
pub use config::{DocumentConfig, StyleThreading};
pub use document::{
    BaseDocument, BoundingRect, DocGuard, DocGuardMut, Document, PlainDocument, UserAgentStylesheet,
};
pub use markup5ever::{
    LocalName, Namespace, NamespaceStaticSet, Prefix, PrefixStaticSet, QualName, local_name,
    namespace_prefix, namespace_url, ns,
};
pub use mutator::DocumentMutator;
pub use node::{Attribute, DocumentData, ElementData, Node, NodeData, TextNodeData};
pub use parley::FontContext;
pub use scrolling::{ScrollBehavior, ScrollLogicalPosition};
pub use tree::NodeTree;

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

/// Convert a [`takia::NodeId`] produced by [`takia_node_id`] back into a Apace [`NodeId`].
#[inline]
pub fn dom_node_id(id: takia::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 use style::stylist::RegisterCustomPropertyResult;
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
}

#[cfg(test)]
mod indeterminate_tests;

#[cfg(test)]
mod animation_retirement_tests;
#[cfg(test)]
mod layout_contents_tests;