blitz_dom/node/

element.rs

use blitz_traits::node_id::NodeId;
use cssparser::ParserInput;
use kurbo::{Affine, Rect as KurboRect};
use linebender_resource_handle::Blob;
use markup5ever::{LocalName, QualName, local_name};
use selectors::matching::{ElementSelectorFlags, QuirksMode};
use std::cell::Cell;
use std::str::FromStr;
use std::sync::Arc;
use std::sync::atomic::AtomicBool;
use style::Atom;
use style::parser::ParserContext;
use style::properties::ComputedValues;
use style::properties::{Importance, PropertyDeclaration, PropertyId, SourcePropertyDeclaration};
use style::stylesheets::{DocumentStyleSheet, Origin, UrlExtraData};
use style::values::computed::Display as StyloDisplay;
use style::{
    properties::{PropertyDeclarationBlock, parse_style_attribute},
    servo_arc::Arc as ServoArc,
    shared_lock::{Locked, SharedRwLock},
    stylesheets::CssRuleType,
};
use style_dom::ElementState;
use style_traits::ParsingMode;
use taffy::{
    Cache,
    prelude::{Layout, Style},
};
use url::Url;

use super::stylo_data::StyloData;
use super::{Attribute, Attributes};
use crate::Document;
use crate::layout::table::TableContext;
use crate::node::{SelectData, TextBrush, TextInputData, TextLayout};

#[cfg(feature = "shadow-dom")]
use super::custom_element::CustomElementData;
#[cfg(feature = "custom-widget")]
use super::custom_widget::CustomWidgetData;

macro_rules! local_names {
    ($($name:tt),+) => {
        [$(local_name!($name),)+]
    };
}

pub struct ElementData {
    /// The elements tag name, namespace and prefix
    pub name: QualName,

    /// The elements id attribute parsed as an atom (if it has one)
    pub id: Option<Atom>,

    /// The element's attributes
    pub attrs: Attributes,

    /// Whether the element is focussable
    pub is_focussable: bool,

    /// The element's parsed style attribute (used by stylo)
    pub style_attribute: Option<ServoArc<Locked<PropertyDeclarationBlock>>>,

    /// Heterogeneous data that depends on the element's type.
    /// For example:
    ///   - The image data for \<img\> elements.
    ///   - The parley Layout for inline roots.
    ///   - The text editor for input/textarea elements
    pub special_data: SpecialElementData,

    pub background_images: Vec<Option<ImageResourceData>>,

    pub mask_images: Vec<Option<ImageResourceData>>,

    /// Parley text layout (elements with inline inner display mode only)
    pub inline_layout_data: Option<Box<TextLayout>>,

    /// Data associated with display: list-item. Note that this display mode
    /// does not exclude inline_layout_data
    pub list_item_data: Option<Box<ListItemLayout>>,

    /// The element's template contents (\<template\> elements only)
    pub template_contents: Option<NodeId>,

    /// The node id of the shadow root attached to this element (if it is a
    /// shadow host). The shadow root node's children form the shadow tree.
    pub shadow_root: Option<NodeId>,

    /// If this element is a light-DOM child of a shadow host, the node id of
    /// the `<slot>` element it has been assigned to in the host's shadow tree
    /// (if any). Recomputed during slot assignment.
    pub assigned_slot: Option<NodeId>,
    // /// Whether the node is a [HTML integration point] (https://html.spec.whatwg.org/multipage/#html-integration-point)
    // pub mathml_annotation_xml_integration_point: bool,

    // ---------------------------------------------------------------------
    // Fields moved from `Node`. These live on the element data so that the
    // `Node` struct itself only carries tree-structure information.
    // ---------------------------------------------------------------------
    /// Style data from stylo, plus a lock guard that allows access to it.
    pub stylo_element_data: StyloData,
    pub selector_flags: Cell<ElementSelectorFlags>,
    /// A clone of the document's shared style lock. Set when the owning
    /// [`Node`](super::Node) is constructed.
    pub guard: Option<SharedRwLock>,
    pub element_state: ElementState,
    pub has_snapshot: bool,
    pub snapshot_handled: AtomicBool,
    /// Whether any descendant of this node needs restyling.
    /// Used by Stylo's incremental style traversal to skip unchanged subtrees.
    pub dirty_descendants: AtomicBool,

    // Pseudo element nodes
    pub before: Option<NodeId>,
    pub after: Option<NodeId>,

    /// Detailed grid track sizing information from the most recent layout
    /// (grid containers only). Used by devtools grid inspection.
    pub detailed_grid_info: Option<Box<taffy::DetailedGridInfo>>,

    // Taffy layout data:
    pub style: Style<Atom>,
    /// Whether flushing this subtree contributes anything to an ancestor's
    /// paint order: a hoisted `position: fixed` node, or a descendant that
    /// pushes into an ancestor's stacking context.
    ///
    /// Set while flushing, read to decide whether a subtree with no damage can
    /// be skipped entirely. Without it the walk cannot be skipped at all: an
    /// ancestor rebuilds its stacking context from scratch, so a subtree that
    /// feeds it and is not walked simply vanishes from paint.
    pub subtree_hoists: bool,

    /// The computed values [`style`](Self::style) was built from, held alive.
    ///
    /// A taffy `Style` does not own its `calc()` values. `stylo_taffy` stores a
    /// raw pointer to the stylo `CalcLengthPercentage`, and that value lives
    /// inside these `ComputedValues`. Drop them while the taffy style survives
    /// and the next layout dereferences freed memory. Keeping the arc here
    /// keeps the pointee alive, and comparing its identity is how a restyle is
    /// told apart from a no-op. See `flush_styles_to_layout_impl`.
    pub style_source: Option<ServoArc<ComputedValues>>,
    pub display_constructed_as: StyloDisplay,
    /// Taffy's layout cache, allocated on first use.
    ///
    /// `Box`ed rather than inline because it is **1616 bytes, 57% of this
    /// whole struct**, and most nodes never use it. A `heap` census of a
    /// running instance found 264,891 live allocations in the 3KB size class
    /// totalling 814 MB, which is `ElementData` at 2848 bytes each; the cache
    /// accounts for 428 MB of that.
    ///
    /// The cache is two fixed-size arrays (`measure_entries` and
    /// `measure_inputs`, `CACHE_SIZE` slots each) plus a final-layout entry.
    /// It is created for every node that can be addressed by taffy, but a
    /// `display: none` subtree, a node that never reaches layout, and any
    /// element before its first measurement all hold an entirely empty one.
    ///
    /// `None` means "no cache yet", which is observationally identical to an
    /// empty cache: a lookup against an absent cache misses exactly as it
    /// would against a present-but-empty one. Only the mutable accessor
    /// allocates, so a node pays the 1616 bytes at the moment taffy first
    /// stores a measurement for it, and never before.
    cache: Option<Box<Cache>>,
    pub unrounded_layout: Layout,
    pub final_layout: Layout,
    pub scroll_offset: crate::Point<f64>,
    pub scrollable_overflow: KurboRect,
    pub transform: Option<Affine>,
}

/// Data specific to the [`Document`](super::super::Document) root node.
///
/// The document node participates in layout and styling like an element, so it
/// carries the same style/layout fields that were previously stored directly on
/// [`Node`](super::Node).
pub struct DocumentData {
    pub stylo_element_data: StyloData,
    /// Selector flags deposited here by `apply_selector_flags` when a
    /// `for_parent()` flag is applied while matching the root `<html>` element,
    /// whose parent node is the document.
    pub selector_flags: Cell<ElementSelectorFlags>,
    /// A clone of the document's shared style lock. Set when the owning
    /// [`Node`](super::Node) is constructed.
    pub guard: Option<SharedRwLock>,
    pub dirty_descendants: AtomicBool,
    pub element_state: ElementState,
    pub has_snapshot: bool,
    pub snapshot_handled: AtomicBool,
    pub style: Style<Atom>,
    /// See [`ElementData::subtree_hoists`].
    pub subtree_hoists: bool,

    /// See [`ElementData::style_source`]. The document node is styled and laid
    /// out like an element, so it carries the same hazard.
    pub style_source: Option<ServoArc<ComputedValues>>,
    pub display_constructed_as: StyloDisplay,
    /// Taffy's layout cache, allocated on first use.
    ///
    /// `Box`ed rather than inline because it is **1616 bytes, 57% of this
    /// whole struct**, and most nodes never use it. A `heap` census of a
    /// running instance found 264,891 live allocations in the 3KB size class
    /// totalling 814 MB, which is `ElementData` at 2848 bytes each; the cache
    /// accounts for 428 MB of that.
    ///
    /// The cache is two fixed-size arrays (`measure_entries` and
    /// `measure_inputs`, `CACHE_SIZE` slots each) plus a final-layout entry.
    /// It is created for every node that can be addressed by taffy, but a
    /// `display: none` subtree, a node that never reaches layout, and any
    /// element before its first measurement all hold an entirely empty one.
    ///
    /// `None` means "no cache yet", which is observationally identical to an
    /// empty cache: a lookup against an absent cache misses exactly as it
    /// would against a present-but-empty one. Only the mutable accessor
    /// allocates, so a node pays the 1616 bytes at the moment taffy first
    /// stores a measurement for it, and never before.
    cache: Option<Box<Cache>>,
    pub unrounded_layout: Layout,
    pub final_layout: Layout,
    pub scroll_offset: crate::Point<f64>,
    pub scrollable_overflow: KurboRect,
    pub transform: Option<Affine>,
}

// Hand-written like `ElementData`'s, because `ElementSelectorFlags` does not
// implement `Debug`. Every other field is still reported.
impl std::fmt::Debug for DocumentData {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("DocumentData")
            .field("stylo_element_data", &self.stylo_element_data)
            .field("guard", &self.guard)
            .field("dirty_descendants", &self.dirty_descendants)
            .field("element_state", &self.element_state)
            .field("has_snapshot", &self.has_snapshot)
            .field("snapshot_handled", &self.snapshot_handled)
            .field("style", &self.style)
            .field("display_constructed_as", &self.display_constructed_as)
            .field("cache", &self.cache)
            .field("unrounded_layout", &self.unrounded_layout)
            .field("final_layout", &self.final_layout)
            .field("scroll_offset", &self.scroll_offset)
            .field("scrollable_overflow", &self.scrollable_overflow)
            .field("transform", &self.transform)
            .finish_non_exhaustive()
    }
}

impl DocumentData {
    /// As [`ElementData::cache`](ElementData::cache). There is only one
    /// document node, so this saves nothing by itself; it exists so both node
    /// kinds present the same accessor and the forwarding on
    /// [`Node`](super::Node) stays uniform.
    #[inline]
    pub fn cache(&self) -> &Cache {
        self.cache.as_deref().unwrap_or(&EMPTY_CACHE)
    }

    #[inline]
    pub fn cache_mut(&mut self) -> &mut Cache {
        self.cache.get_or_insert_with(|| Box::new(Cache::new()))
    }

    #[inline]
    pub fn cache_release(&mut self) {
        self.cache = None;
    }

    pub fn new() -> Self {
        Self {
            stylo_element_data: Default::default(),
            selector_flags: Cell::new(ElementSelectorFlags::empty()),
            guard: None,
            dirty_descendants: AtomicBool::new(true),
            element_state: ElementState::empty(),
            has_snapshot: false,
            snapshot_handled: AtomicBool::new(false),
            style: Default::default(),
            style_source: None,
            subtree_hoists: false,
            display_constructed_as: StyloDisplay::Block,
            cache: None,
            unrounded_layout: Layout::new(),
            final_layout: Layout::new(),
            scroll_offset: crate::Point::ZERO,
            scrollable_overflow: KurboRect::ZERO,
            transform: None,
        }
    }
}

impl Default for DocumentData {
    fn default() -> Self {
        Self::new()
    }
}

impl Clone for DocumentData {
    fn clone(&self) -> Self {
        // Runtime style/layout state is reset (the document node is not
        // meaningfully cloneable), matching `ElementData`'s clone semantics.
        Self {
            guard: self.guard.clone(),
            ..Self::new()
        }
    }
}

impl std::fmt::Debug for ElementData {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ElementData")
            .field("name", &self.name)
            .field("id", &self.id)
            .field("attrs", &self.attrs)
            .field("is_focussable", &self.is_focussable)
            .field("style_attribute", &self.style_attribute)
            .field("special_data", &self.special_data)
            .field("background_images", &self.background_images)
            .field("mask_images", &self.mask_images)
            .field("inline_layout_data", &self.inline_layout_data)
            .field("list_item_data", &self.list_item_data)
            .field("template_contents", &self.template_contents)
            .field("element_state", &self.element_state)
            .field("display_constructed_as", &self.display_constructed_as)
            .finish_non_exhaustive()
    }
}

impl Clone for ElementData {
    /// Clones the *content* of the element (name, attributes, style attribute,
    /// special data, etc.). Runtime style/layout state (stylo data, taffy
    /// layout, caches, pseudo-element ids, ...) is reset to its default so that
    /// the clone behaves like a freshly-created element that has not yet been
    /// styled or laid out.
    fn clone(&self) -> Self {
        Self {
            name: self.name.clone(),
            id: self.id.clone(),
            attrs: self.attrs.clone(),
            is_focussable: self.is_focussable,
            style_attribute: self.style_attribute.clone(),
            special_data: self.special_data.clone(),
            background_images: self.background_images.clone(),
            mask_images: self.mask_images.clone(),
            inline_layout_data: self.inline_layout_data.clone(),
            list_item_data: self.list_item_data.clone(),
            template_contents: self.template_contents,

            // Runtime state: reset to defaults.
            //
            // A shadow root belongs to exactly one host, so a clone must not
            // claim its original's, and slot assignment is recomputed from the
            // flattened tree on the next resolve.
            shadow_root: None,
            assigned_slot: None,
            stylo_element_data: Default::default(),
            selector_flags: Cell::new(ElementSelectorFlags::empty()),
            guard: self.guard.clone(),
            element_state: self.element_state,
            has_snapshot: false,
            snapshot_handled: AtomicBool::new(false),
            dirty_descendants: AtomicBool::new(true),
            before: None,
            after: None,
            detailed_grid_info: None,
            style: Default::default(),
            style_source: None,
            subtree_hoists: false,
            display_constructed_as: StyloDisplay::Block,
            cache: None,
            unrounded_layout: Layout::new(),
            final_layout: Layout::new(),
            scroll_offset: crate::Point::ZERO,
            scrollable_overflow: KurboRect::ZERO,
            transform: None,
        }
    }
}

#[derive(Copy, Clone, Default)]
#[non_exhaustive]
pub enum SpecialElementType {
    Stylesheet,
    Image,
    Canvas,
    TableRoot,
    TextInput,
    CheckboxInput,
    Select,
    #[cfg(feature = "file-input")]
    FileInput,
    #[default]
    None,
}

/// Heterogeneous data that depends on the element's type.
#[derive(Default)]
pub enum SpecialElementData {
    /// A sub-document such an \<iframe\> or \<web-view\> element
    SubDocument(Box<dyn Document>),
    /// A custom widget
    #[cfg(feature = "custom-widget")]
    CustomWidget(CustomWidgetData),
    /// A custom element (a Rust object that controls an attached shadow DOM)
    #[cfg(feature = "shadow-dom")]
    CustomElement(CustomElementData),
    /// A stylesheet
    Stylesheet(DocumentStyleSheet),
    /// An \<img\> element's image data
    Image(Box<ImageData>),
    /// A \<canvas\> element's custom paint source
    Canvas(CanvasData),
    /// Pre-computed table layout data
    TableRoot(Arc<TableContext>),
    /// Parley text editor (text inputs)
    TextInput(TextInputData),
    /// Checkbox checked state
    CheckboxInput(bool),
    /// A \<select\> element's selectedness and open state
    Select(SelectData),
    /// Selected files
    #[cfg(feature = "file-input")]
    FileInput(FileData),
    /// No data (for nodes that don't need any node-specific data)
    #[default]
    None,
}

impl Clone for SpecialElementData {
    fn clone(&self) -> Self {
        match self {
            Self::SubDocument(_) => Self::None, // TODO
            #[cfg(feature = "custom-widget")]
            Self::CustomWidget(_) => Self::None, // TODO
            #[cfg(feature = "shadow-dom")]
            Self::CustomElement(_) => Self::None, // TODO
            Self::Stylesheet(data) => Self::Stylesheet(data.clone()),
            Self::Image(data) => Self::Image(data.clone()),
            Self::Canvas(data) => Self::Canvas(data.clone()),
            Self::TableRoot(data) => Self::TableRoot(data.clone()),
            Self::TextInput(data) => Self::TextInput(data.clone()),
            Self::CheckboxInput(data) => Self::CheckboxInput(*data),
            Self::Select(data) => Self::Select(data.clone()),
            #[cfg(feature = "file-input")]
            Self::FileInput(data) => Self::FileInput(data.clone()),
            Self::None => Self::None,
        }
    }
}

impl SpecialElementData {
    pub fn take(&mut self) -> Self {
        std::mem::take(self)
    }
}

/// A shared empty cache, handed out when a node has never been laid out.
///
/// Returning a reference to this rather than allocating keeps `cache()` an
/// infallible `&Cache` for callers, which is what lets the lazy allocation stay
/// invisible above this module. It is only ever read: a lookup against it
/// misses, which is the same answer an owned empty cache would give. Nothing
/// can write through a shared reference, so the `is_empty` fast path inside
/// taffy stays correct for every node pointing here.
static EMPTY_CACHE: Cache = Cache::new();

impl ElementData {
    /// This node's layout cache, or a shared empty one if it has never been
    /// laid out. See the [`cache`](Self::cache) field for why it is optional.
    #[inline]
    pub fn cache(&self) -> &Cache {
        self.cache.as_deref().unwrap_or(&EMPTY_CACHE)
    }

    /// This node's layout cache, allocating it if this is the first use.
    ///
    /// Every caller of this is taffy storing or clearing a measurement, which
    /// is exactly the moment a node stops being one that never lays out.
    #[inline]
    pub fn cache_mut(&mut self) -> &mut Cache {
        self.cache.get_or_insert_with(|| Box::new(Cache::new()))
    }

    /// Drop the cache entirely rather than emptying it in place.
    ///
    /// `cache_clear` runs on every node whose layout is invalidated, and the
    /// old code zeroed 1616 bytes there. Releasing the box instead returns the
    /// memory, and a node that is cleared and never re-measured (a subtree that
    /// became `display: none`, say) stops paying for the cache at all.
    #[inline]
    pub fn cache_release(&mut self) {
        self.cache = None;
    }

    pub fn new(name: QualName, attrs: Vec<Attribute>) -> Self {
        let id_attr_atom = attrs
            .iter()
            .find(|attr| &attr.name.local == "id")
            .map(|attr| attr.value.as_ref())
            .map(|value: &str| Atom::from(value));

        let mut data = ElementData {
            name,
            id: id_attr_atom,
            attrs: Attributes::new(attrs),
            is_focussable: false,
            style_attribute: Default::default(),
            inline_layout_data: None,
            list_item_data: None,
            special_data: SpecialElementData::None,
            template_contents: None,
            shadow_root: None,
            assigned_slot: None,
            background_images: Vec::new(),
            mask_images: Vec::new(),

            stylo_element_data: Default::default(),
            selector_flags: Cell::new(ElementSelectorFlags::empty()),
            guard: None,
            element_state: ElementState::empty(),
            has_snapshot: false,
            snapshot_handled: AtomicBool::new(false),
            dirty_descendants: AtomicBool::new(true),
            before: None,
            after: None,
            detailed_grid_info: None,
            style: Default::default(),
            style_source: None,
            subtree_hoists: false,
            display_constructed_as: StyloDisplay::Block,
            cache: None,
            unrounded_layout: Layout::new(),
            final_layout: Layout::new(),
            scroll_offset: crate::Point::ZERO,
            scrollable_overflow: KurboRect::ZERO,
            transform: None,
        };
        data.flush_is_focussable();

        // The element state needs to be modified if the element can be disabled.
        if data.can_be_disabled() {
            data.element_state
                .insert(match data.has_attr(local_name!("disabled")) {
                    true => ElementState::DISABLED,
                    false => ElementState::ENABLED,
                });
        }

        data
    }

    pub fn attrs(&self) -> &[Attribute] {
        &self.attrs
    }

    pub fn attr(&self, name: impl PartialEq<LocalName>) -> Option<&str> {
        let attr = self.attrs.iter().find(|attr| name == attr.name.local)?;
        Some(&attr.value)
    }

    pub fn attr_parsed<T: FromStr>(&self, name: impl PartialEq<LocalName>) -> Option<T> {
        let attr = self.attrs.iter().find(|attr| name == attr.name.local)?;
        attr.value.parse::<T>().ok()
    }

    /// Detects the presence of the attribute, treating *any* value as truthy.
    pub fn has_attr(&self, name: impl PartialEq<LocalName>) -> bool {
        self.attrs.iter().any(|attr| name == attr.name.local)
    }

    pub fn can_be_disabled(&self) -> bool {
        local_names!("button", "input", "select", "textarea").contains(&self.name.local)
    }

    pub fn image_data(&self) -> Option<&ImageData> {
        match &self.special_data {
            SpecialElementData::Image(data) => Some(&**data),
            _ => None,
        }
    }

    pub fn image_data_mut(&mut self) -> Option<&mut ImageData> {
        match self.special_data {
            SpecialElementData::Image(ref mut data) => Some(&mut **data),
            _ => None,
        }
    }

    pub fn raster_image_data(&self) -> Option<&RasterImageData> {
        match self.image_data()? {
            ImageData::Raster(data) => Some(data),
            _ => None,
        }
    }

    pub fn raster_image_data_mut(&mut self) -> Option<&mut RasterImageData> {
        match self.image_data_mut()? {
            ImageData::Raster(data) => Some(data),
            _ => None,
        }
    }

    pub fn canvas_data(&self) -> Option<&CanvasData> {
        match &self.special_data {
            SpecialElementData::Canvas(data) => Some(data),
            _ => None,
        }
    }

    pub fn sub_doc_data(&self) -> Option<&dyn Document> {
        match &self.special_data {
            SpecialElementData::SubDocument(data) => Some(data.as_ref()),
            _ => None,
        }
    }

    pub fn sub_doc_data_mut(&mut self) -> Option<&mut dyn Document> {
        match &mut self.special_data {
            SpecialElementData::SubDocument(data) => Some(data.as_mut()),
            _ => None,
        }
    }

    #[cfg(feature = "svg")]
    pub fn svg_data(&self) -> Option<&usvg::Tree> {
        match self.image_data()? {
            ImageData::Svg(data) => Some(&data.tree),
            _ => None,
        }
    }

    pub fn text_input_data(&self) -> Option<&TextInputData> {
        match &self.special_data {
            SpecialElementData::TextInput(data) => Some(data),
            _ => None,
        }
    }

    pub fn text_input_data_mut(&mut self) -> Option<&mut TextInputData> {
        match &mut self.special_data {
            SpecialElementData::TextInput(data) => Some(data),
            _ => None,
        }
    }

    #[cfg(feature = "custom-widget")]
    pub fn custom_widget_data(&self) -> Option<&CustomWidgetData> {
        match &self.special_data {
            SpecialElementData::CustomWidget(data) => Some(data),
            _ => None,
        }
    }

    #[cfg(feature = "custom-widget")]
    pub fn custom_widget_data_mut(&mut self) -> Option<&mut CustomWidgetData> {
        match &mut self.special_data {
            SpecialElementData::CustomWidget(data) => Some(data),
            _ => None,
        }
    }

    #[cfg(feature = "shadow-dom")]
    pub fn custom_element_data(&self) -> Option<&CustomElementData> {
        match &self.special_data {
            SpecialElementData::CustomElement(data) => Some(data),
            _ => None,
        }
    }

    #[cfg(feature = "shadow-dom")]
    pub fn custom_element_data_mut(&mut self) -> Option<&mut CustomElementData> {
        match &mut self.special_data {
            SpecialElementData::CustomElement(data) => Some(data),
            _ => None,
        }
    }

    pub fn checkbox_input_checked(&self) -> Option<bool> {
        match self.special_data {
            SpecialElementData::CheckboxInput(checked) => Some(checked),
            _ => None,
        }
    }

    pub fn checkbox_input_checked_mut(&mut self) -> Option<&mut bool> {
        match self.special_data {
            SpecialElementData::CheckboxInput(ref mut checked) => Some(checked),
            _ => None,
        }
    }

    /// The live state of a `<select>`, or `None` for anything else.
    ///
    /// Deliberately not modelled the way `checkbox_input_checked` is: that one
    /// hands back an `Option<bool>` whose `None` means both "not a checkbox"
    /// and, to every caller that reaches for `unwrap_or(false)`, "unchecked".
    /// A select's answer to "what is selected" is a whole vector, so the
    /// borrow is handed out instead and the two questions stay apart.
    pub fn select_data(&self) -> Option<&SelectData> {
        match &self.special_data {
            SpecialElementData::Select(data) => Some(data),
            _ => None,
        }
    }

    pub fn select_data_mut(&mut self) -> Option<&mut SelectData> {
        match &mut self.special_data {
            SpecialElementData::Select(data) => Some(data),
            _ => None,
        }
    }

    #[cfg(feature = "file-input")]
    pub fn file_data(&self) -> Option<&FileData> {
        match &self.special_data {
            SpecialElementData::FileInput(data) => Some(data),
            _ => None,
        }
    }

    #[cfg(feature = "file-input")]
    pub fn file_data_mut(&mut self) -> Option<&mut FileData> {
        match &mut self.special_data {
            SpecialElementData::FileInput(data) => Some(data),
            _ => None,
        }
    }

    pub fn flush_is_focussable(&mut self) {
        let disabled: bool = self.attr_parsed(local_name!("disabled")).unwrap_or(false);
        let tabindex: Option<i32> = self.attr_parsed(local_name!("tabindex"));
        let contains_sub_document: bool = self.sub_doc_data().is_some();

        self.is_focussable = contains_sub_document
            || (!disabled
                && match tabindex {
                    Some(index) => index >= 0,
                    None => {
                        // Some focusable HTML elements have a default tabindex value of 0 set under the hood by the user agent.
                        // These elements are:
                        //   - <a> or <area> with href attribute
                        //   - <button>, <frame>, <iframe>, <input>, <object>, <select>, <textarea>, and SVG <a> element
                        //   - <summary> element that provides summary for a <details> element.

                        if [local_name!("a"), local_name!("area")].contains(&self.name.local) {
                            self.attr(local_name!("href")).is_some()
                        } else {
                            const DEFAULT_FOCUSSABLE_ELEMENTS: [LocalName; 7] = [
                                local_name!("button"),
                                local_name!("input"),
                                local_name!("select"),
                                local_name!("textarea"),
                                local_name!("frame"),
                                local_name!("iframe"),
                                local_name!("summary"),
                            ];
                            DEFAULT_FOCUSSABLE_ELEMENTS.contains(&self.name.local)
                        }
                    }
                })
    }

    pub fn flush_style_attribute(&mut self, guard: &SharedRwLock, url_extra_data: &UrlExtraData) {
        self.style_attribute = self.attr(local_name!("style")).map(|style_str| {
            ServoArc::new(guard.wrap(parse_style_attribute(
                style_str,
                url_extra_data,
                None,
                QuirksMode::NoQuirks,
                CssRuleType::Style,
            )))
        });
    }

    pub fn set_style_property(
        &mut self,
        name: &str,
        value: &str,
        guard: &SharedRwLock,
        url_extra_data: UrlExtraData,
    ) -> bool {
        let context = ParserContext::new(
            Origin::Author,
            &url_extra_data,
            Some(CssRuleType::Style),
            ParsingMode::DEFAULT,
            QuirksMode::NoQuirks,
            /* namespaces = */ Default::default(),
            None,
            None,
            /* attr_taint = */ Default::default(),
        );

        let Ok(property_id) = PropertyId::parse(name, &context) else {
            #[cfg(feature = "tracing")]
            tracing::warn!(property = name, "Unsupported property");
            return false;
        };
        let mut source_property_declaration = SourcePropertyDeclaration::default();
        let mut input = ParserInput::new(value);
        let mut parser = style::values::Parser::new(&mut input);
        let Ok(_) = PropertyDeclaration::parse_into(
            &mut source_property_declaration,
            property_id,
            &context,
            &mut parser,
        ) else {
            #[cfg(feature = "tracing")]
            tracing::warn!(property = name, value, "Invalid property value");
            return false;
        };

        if self.style_attribute.is_none() {
            self.style_attribute = Some(ServoArc::new(guard.wrap(PropertyDeclarationBlock::new())));
        }
        self.style_attribute
            .as_mut()
            .unwrap()
            .write_with(&mut guard.write())
            .extend(source_property_declaration.drain(), Importance::Normal);

        true
    }

    pub fn remove_style_property(
        &mut self,
        name: &str,
        guard: &SharedRwLock,
        url_extra_data: UrlExtraData,
    ) -> bool {
        let context = ParserContext::new(
            Origin::Author,
            &url_extra_data,
            Some(CssRuleType::Style),
            ParsingMode::DEFAULT,
            QuirksMode::NoQuirks,
            /* namespaces = */ Default::default(),
            None,
            None,
            /* attr_taint = */ Default::default(),
        );
        let Ok(property_id) = PropertyId::parse(name, &context) else {
            #[cfg(feature = "tracing")]
            tracing::warn!(property = name, "Unsupported property");
            return false;
        };

        if let Some(style) = &mut self.style_attribute {
            let mut guard = guard.write();
            let style = style.write_with(&mut guard);
            if let Some(index) = style.first_declaration_to_remove(&property_id) {
                style.remove_property(&property_id, index);
                return true;
            }
        }

        false
    }

    pub fn set_sub_document(&mut self, sub_document: Box<dyn Document>) {
        self.special_data = SpecialElementData::SubDocument(sub_document);
    }

    pub fn remove_sub_document(&mut self) {
        self.special_data = SpecialElementData::None;
    }

    #[cfg(feature = "custom-widget")]
    pub fn set_custom_widget(&mut self, widget: Box<dyn crate::Widget>) {
        use crate::node::custom_widget::CustomWidgetData;
        self.special_data = SpecialElementData::CustomWidget(CustomWidgetData::new(widget));
    }

    #[cfg(feature = "custom-widget")]
    pub fn remove_custom_widget(&mut self) -> Vec<anyrender::ResourceId> {
        let resource_ids = self
            .custom_widget_data_mut()
            .map(|widget_data| widget_data.take_resource_ids())
            .unwrap_or_default();
        self.special_data = SpecialElementData::None;
        resource_ids
    }

    pub fn take_inline_layout(&mut self) -> Option<Box<TextLayout>> {
        std::mem::take(&mut self.inline_layout_data)
    }

    pub fn is_submit_button(&self) -> bool {
        if self.name.local != local_name!("button") {
            return false;
        }
        let type_attr = self.attr(local_name!("type"));
        let is_submit = type_attr == Some("submit");
        let is_auto_submit = type_attr.is_none()
            && self.attr(LocalName::from("command")).is_none()
            && self.attr(LocalName::from("commandfor")).is_none();
        is_submit || is_auto_submit
    }
}

#[derive(Debug, Clone, PartialEq)]
pub struct RasterImageData {
    /// The width of the image
    pub width: u32,
    /// The height of the image
    pub height: u32,
    /// The raw image data in RGBA8 format
    pub data: Blob<u8>,
}
impl RasterImageData {
    pub fn new(width: u32, height: u32, data: Arc<Vec<u8>>) -> Self {
        Self {
            width,
            height,
            data: Blob::new(data),
        }
    }
}

/// A parsed SVG image.
///
/// usvg always resolves the root `<svg>` to a concrete [`usvg::Tree::size`],
/// falling back to the `viewBox` size when `width`/`height` are absent or given
/// as percentages. For CSS sizing purposes, however, such an SVG has *no*
/// intrinsic width/height (only an intrinsic aspect ratio). The accessors on
/// this type resolve the CSS intrinsic dimensions lazily from
/// [`usvg::Tree::intrinsic_dimensions`], which preserves what was actually
/// declared on the root element.
#[cfg(feature = "svg")]
#[derive(Debug, Clone)]
pub struct SvgImageData {
    /// The parsed SVG tree.
    pub tree: Arc<usvg::Tree>,
}

#[cfg(feature = "svg")]
impl SvgImageData {
    /// The intrinsic width in CSS px, present only when the root `<svg>`
    /// declared an absolute (non-percentage) `width`.
    pub fn intrinsic_width(&self) -> Option<f32> {
        use usvg::svgtypes::LengthUnit;
        let declared = self
            .tree
            .intrinsic_dimensions()
            .width
            .is_some_and(|len| len.unit != LengthUnit::Percent);
        declared.then(|| self.tree.size().width())
    }

    /// The intrinsic height in CSS px, present only when the root `<svg>`
    /// declared an absolute (non-percentage) `height`.
    pub fn intrinsic_height(&self) -> Option<f32> {
        use usvg::svgtypes::LengthUnit;
        let declared = self
            .tree
            .intrinsic_dimensions()
            .height
            .is_some_and(|len| len.unit != LengthUnit::Percent);
        declared.then(|| self.tree.size().height())
    }

    /// The aspect ratio of the root `<svg>`'s `viewBox`, if it declares one.
    pub fn viewbox_aspect_ratio(&self) -> Option<f32> {
        self.tree
            .intrinsic_dimensions()
            .view_box
            .map(|vb| vb.width() / vb.height())
    }

    /// The root `width` attribute resolved against a containing block width:
    /// percentages resolve against the containing block (`None` if it is
    /// indefinite) and an absent attribute is `None`.
    ///
    /// This is only appropriate for an inline `<svg>` element, where the
    /// attributes behave as presentation attributes. SVG used as an image
    /// (e.g. `<img src>` or a background) must use [`Self::intrinsic_width`],
    /// as its intrinsic dimensions are context-free per CSS.
    pub fn resolved_width(&self, container_width: Option<f32>) -> Option<f32> {
        use usvg::svgtypes::LengthUnit;
        match self.tree.intrinsic_dimensions().width {
            Some(len) if len.unit != LengthUnit::Percent => Some(self.tree.size().width()),
            Some(len) => container_width.map(|cw| cw * (len.number as f32) / 100.0),
            None => None,
        }
    }

    /// The root `height` attribute resolved against a containing block height.
    /// See [`Self::resolved_width`].
    pub fn resolved_height(&self, container_height: Option<f32>) -> Option<f32> {
        use usvg::svgtypes::LengthUnit;
        match self.tree.intrinsic_dimensions().height {
            Some(len) if len.unit != LengthUnit::Percent => Some(self.tree.size().height()),
            Some(len) => container_height.map(|ch| ch * (len.number as f32) / 100.0),
            None => None,
        }
    }

    /// The intrinsic aspect ratio of the SVG: the ratio of its declared
    /// `width`/`height` when both are absolute lengths, otherwise the
    /// `viewBox` ratio, otherwise the ratio of the resolved
    /// [`usvg::Tree::size`] (which is always non-zero).
    pub fn aspect_ratio(&self) -> f32 {
        match (self.intrinsic_width(), self.intrinsic_height()) {
            (Some(w), Some(h)) => w / h,
            _ => self.viewbox_aspect_ratio().unwrap_or_else(|| {
                let size = self.tree.size();
                size.width() / size.height()
            }),
        }
    }

    /// The intrinsic dimensions of the SVG resolved per CSS replaced element
    /// sizing: a missing dimension is computed from the declared one and the
    /// intrinsic aspect ratio; if neither is declared, the resolved
    /// [`usvg::Tree::size`] is used as a fallback.
    pub fn intrinsic_size(&self) -> (f32, f32) {
        let aspect_ratio = self.aspect_ratio();
        match (self.intrinsic_width(), self.intrinsic_height()) {
            (Some(w), Some(h)) => (w, h),
            (Some(w), None) => (w, w / aspect_ratio),
            (None, Some(h)) => (h * aspect_ratio, h),
            (None, None) => {
                // No intrinsic dimensions. If there is an intrinsic aspect ratio, apply
                // the CSS default sizing algorithm: contain within the default object
                // size of 300x150. Otherwise fall back to the resolved tree size.
                if self.viewbox_aspect_ratio().is_some() {
                    let scale = (300.0 / aspect_ratio).min(150.0);
                    (scale * aspect_ratio, scale)
                } else {
                    let size = self.tree.size();
                    (size.width(), size.height())
                }
            }
        }
    }
}

#[derive(Debug, Clone)]
pub enum ImageData {
    Raster(RasterImageData),
    #[cfg(feature = "svg")]
    Svg(SvgImageData),
    None,
}

#[derive(Debug, Clone, PartialEq)]
pub enum Status {
    Ok,
    Error,
    Loading,
}

#[derive(Debug, Clone)]
pub struct ImageResourceData {
    /// The url of the background image
    pub url: ServoArc<Url>,
    /// The loading status of the background image
    pub status: Status,
    /// The image data
    pub image: ImageData,
}

impl ImageResourceData {
    pub fn new(url: ServoArc<Url>) -> Self {
        Self {
            url,
            status: Status::Loading,
            image: ImageData::None,
        }
    }
}

#[derive(Debug, Clone)]
pub struct CanvasData {
    pub custom_paint_source_id: u64,
}

impl std::fmt::Debug for SpecialElementData {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            SpecialElementData::SubDocument(_) => f.write_str("NodeSpecificData::SubDocument"),
            #[cfg(feature = "custom-widget")]
            SpecialElementData::CustomWidget(_) => f.write_str("NodeSpecificData::CustomWidget"),
            #[cfg(feature = "shadow-dom")]
            SpecialElementData::CustomElement(_) => f.write_str("NodeSpecificData::CustomElement"),
            SpecialElementData::Stylesheet(_) => f.write_str("NodeSpecificData::Stylesheet"),
            SpecialElementData::Image(data) => match **data {
                ImageData::Raster(_) => f.write_str("NodeSpecificData::Image(Raster)"),
                #[cfg(feature = "svg")]
                ImageData::Svg(_) => f.write_str("NodeSpecificData::Image(Svg)"),
                ImageData::None => f.write_str("NodeSpecificData::Image(None)"),
            },
            SpecialElementData::Canvas(_) => f.write_str("NodeSpecificData::Canvas"),
            SpecialElementData::TableRoot(_) => f.write_str("NodeSpecificData::TableRoot"),
            SpecialElementData::TextInput(_) => f.write_str("NodeSpecificData::TextInput"),
            SpecialElementData::CheckboxInput(_) => f.write_str("NodeSpecificData::CheckboxInput"),
            SpecialElementData::Select(data) => {
                write!(f, "NodeSpecificData::Select({data:?})")
            }
            #[cfg(feature = "file-input")]
            SpecialElementData::FileInput(_) => f.write_str("NodeSpecificData::FileInput"),
            SpecialElementData::None => f.write_str("NodeSpecificData::None"),
        }
    }
}

#[derive(Clone)]
pub struct ListItemLayout {
    pub marker: Marker,
    pub position: ListItemLayoutPosition,
}

//We seperate chars from strings in order to optimise rendering - ie not needing to
//construct a whole parley layout for simple char markers
#[derive(Debug, PartialEq, Clone)]
pub enum Marker {
    Char(char),
    String(String),
}

//Value depends on list-style-position, determining whether a seperate layout is created for it
#[derive(Clone)]
pub enum ListItemLayoutPosition {
    Inside,
    Outside(Box<parley::Layout<TextBrush>>),
}

impl std::fmt::Debug for ListItemLayout {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "ListItemLayout - marker {:?}", self.marker)
    }
}

#[cfg(feature = "file-input")]
mod file_data {
    use std::ops::{Deref, DerefMut};
    use std::path::PathBuf;

    #[derive(Clone, Debug)]
    pub struct FileData(pub Vec<PathBuf>);
    impl Deref for FileData {
        type Target = Vec<PathBuf>;

        fn deref(&self) -> &Self::Target {
            &self.0
        }
    }
    impl DerefMut for FileData {
        fn deref_mut(&mut self) -> &mut Self::Target {
            &mut self.0
        }
    }
    impl From<Vec<PathBuf>> for FileData {
        fn from(files: Vec<PathBuf>) -> Self {
            Self(files)
        }
    }
}
#[cfg(feature = "file-input")]
pub use file_data::FileData;

#[cfg(test)]
mod tests {
    use super::{ElementData, TextInputData};
    use parley::{FontContext, LayoutContext};

    /// `ElementData` is allocated once per element, so its size is a direct
    /// multiplier on the DOM's footprint.
    ///
    /// A `heap` census of a running instance found 264,891 live allocations in
    /// the 3KB malloc class totalling **814 MB**, which was this struct at
    /// 2848 bytes each. Boxing the taffy cache took it to 1240 and out of that
    /// size class entirely.
    ///
    /// The bound is deliberately loose and one-sided: it does not care what
    /// the exact number is, only that nobody puts a kilobyte back inline
    /// without noticing. If a field genuinely has to grow past this, raise the
    /// bound and say why, rather than deleting the test.
    #[test]
    fn element_data_stays_out_of_the_large_size_classes() {
        let size = std::mem::size_of::<ElementData>();
        assert!(
            size <= 1536,
            "ElementData grew to {size} bytes. It is allocated per element, so \
             this is a multiplier on the whole DOM's footprint: at 2848 bytes \
             it was 814 MB of a live instance. Box the new field instead, as \
             `cache` is."
        );
    }

    /// The cache is what was boxed, so its absence has to stay cheap.
    ///
    /// If this ever fails, the `Option<Box<Cache>>` has been flattened back to
    /// an inline `Cache` and the 428 MB is back.
    #[test]
    fn an_unlaid_out_element_carries_no_cache() {
        let data = ElementData::new(
            markup5ever::QualName::new(None, markup5ever::ns!(html), "div".into()),
            Vec::new(),
        );
        assert!(
            std::mem::size_of_val(&data) < std::mem::size_of::<taffy::Cache>() * 2,
            "the cache must not be inline: a fresh element should be smaller \
             than two caches"
        );
    }

    /// Build a [`TextInputData`] with the given text laid out at scale 1.0.
    fn make_input(is_multiline: bool, text: &str) -> TextInputData {
        let mut font_ctx = FontContext::new();
        let mut layout_ctx = LayoutContext::new();
        let mut data = TextInputData::new(is_multiline);
        data.editor.set_scale(1.0);
        data.editor.set_text(text);
        data.editor
            .driver(&mut font_ctx, &mut layout_ctx)
            .refresh_layout();
        data
    }

    #[test]
    fn short_text_does_not_scroll() {
        let mut data = make_input(false, "hi");
        // A wide content box that comfortably fits the text.
        data.clamp_scroll_offset(1000.0, 100.0);
        assert_eq!(data.scroll_offset, 0.0);
    }

    #[test]
    fn single_line_scrolls_to_follow_caret() {
        let text = "the quick brown fox jumps over the lazy dog repeatedly and at length";
        let mut data = make_input(false, text);
        let content_box_width = 40.0;
        let content_box_height = 20.0;

        // Caret at the end of a string that overflows a narrow input should scroll right.
        data.editor
            .driver(&mut FontContext::new(), &mut LayoutContext::new())
            .move_to_text_end();
        data.clamp_scroll_offset(content_box_width, content_box_height);

        let layout_width = data.editor.try_layout().unwrap().full_width();
        if layout_width > content_box_width {
            assert!(
                data.scroll_offset > 0.0,
                "expected horizontal scroll for overflowing single-line input"
            );
            // The caret must be within the visible region after scrolling.
            let caret = data.editor.cursor_geometry(1.5).unwrap();
            assert!(caret.x1 as f32 <= data.scroll_offset + content_box_width + 0.5);
            assert!(caret.x0 as f32 >= data.scroll_offset - 0.5);
        }

        // Moving the caret back to the start should reset the scroll offset.
        data.editor
            .driver(&mut FontContext::new(), &mut LayoutContext::new())
            .move_to_text_start();
        data.clamp_scroll_offset(content_box_width, content_box_height);
        assert_eq!(data.scroll_offset, 0.0);
    }

    #[test]
    fn multiline_scrolls_vertically_not_horizontally() {
        let text = (0..40)
            .map(|i| format!("line {i}"))
            .collect::<Vec<_>>()
            .join("\n");
        let mut data = make_input(true, &text);
        // Constrain the width so wrapping is well-defined.
        data.editor.set_width(Some(200.0));
        data.editor
            .driver(&mut FontContext::new(), &mut LayoutContext::new())
            .refresh_layout();

        let content_box_width = 200.0;
        let content_box_height = 30.0;

        data.editor
            .driver(&mut FontContext::new(), &mut LayoutContext::new())
            .move_to_text_end();
        data.clamp_scroll_offset(content_box_width, content_box_height);

        let layout_height = data.editor.try_layout().unwrap().height();
        if layout_height > content_box_height {
            assert!(
                data.scroll_offset > 0.0,
                "expected vertical scroll for overflowing multi-line input"
            );
        }
    }

    /// macOS only: the scrollable extent it clamps against comes from shaped
    /// text, so with no font registered there is nothing to scroll and the
    /// clamp has no work to do. See the target-scoped `parley` dev-dependency
    /// in this crate's manifest.
    #[cfg(target_os = "macos")]
    #[test]
    fn scroll_by_clamps_and_bubbles() {
        let text = (0..40)
            .map(|i| format!("line {i}"))
            .collect::<Vec<_>>()
            .join("\n");
        let mut data = make_input(true, &text);
        data.editor.set_width(Some(200.0));
        data.editor
            .driver(&mut FontContext::new(), &mut LayoutContext::new())
            .refresh_layout();

        let content_box_width = 200.0;
        let content_box_height = 30.0;
        let max = data.max_scroll_offset(content_box_width, content_box_height);
        assert!(max > 0.0, "test text should overflow the content box");

        // Scrolling up (positive delta decreases offset) while already at the top is a no-op and
        // the whole delta bubbles.
        assert_eq!(data.scroll_offset, 0.0);
        let bubbled = data.scroll_by(15.0, content_box_width, content_box_height);
        assert_eq!(data.scroll_offset, 0.0);
        assert_eq!(bubbled, 15.0);

        // Scrolling down moves the offset and consumes the delta.
        let bubbled = data.scroll_by(-10.0, content_box_width, content_box_height);
        assert_eq!(data.scroll_offset, 10.0);
        assert_eq!(bubbled, 0.0);

        // Scrolling past the end clamps to the maximum and bubbles the remainder. Starting at
        // offset 10 with max headroom of `max - 10`, a delta of `-(max + 100)` consumes
        // `max - 10` and bubbles the rest (`-110`).
        let bubbled = data.scroll_by(-(max + 100.0), content_box_width, content_box_height);
        assert_eq!(data.scroll_offset, max);
        assert!((bubbled - (-110.0)).abs() < 1e-3);
    }

    #[test]
    fn single_line_does_not_scroll_when_text_fits() {
        let mut data = make_input(false, "hi");
        // Wide content box; nothing to scroll, so all delta bubbles.
        let bubbled = data.scroll_by(-50.0, 1000.0, 100.0);
        assert_eq!(data.scroll_offset, 0.0);
        assert_eq!(bubbled, -50.0);
    }
}