spindrift 0.1.0

A HTML/CSS to PDF renderer, targeting spec compliance and efficiency
Documentation
use std::borrow::Cow;

use super::*;

/// Child box generated for a flex or grid formatting context.
///
/// CSS Flexbox and CSS Grid both create one item from each in-flow child, wrap
/// non-whitespace text runs in anonymous items, ignore text runs containing
/// only CSS document white space independent of the computed `white-space`
/// value, and exclude absolutely positioned descendants from item layout:
/// <https://www.w3.org/TR/css-flexbox-1/#flex-items> and
/// <https://www.w3.org/TR/css-grid-1/#grid-items>.
#[derive(Debug, Clone)]
pub(in crate::layout) struct FormattingContextChild<'a> {
    pub(in crate::layout) kind: FormattingContextChildKind<'a>,
    pub(in crate::layout) style: ComputedStyle,
}

#[derive(Debug, Clone)]
pub(in crate::layout) enum FormattingContextChildKind<'a> {
    Element {
        element: &'a Element,
        signature: Box<ElementSignature>,
        generated_pseudo: Option<box_tree::GeneratedPseudoKind>,
        children: Option<Cow<'a, [box_tree::FormattingBox<'a>]>>,
        /// Durable table structure for replay through a flex/grid item.
        table_fragment: Option<Box<box_tree::TableFragment<'a>>>,
    },
    AnonymousContent {
        children: Vec<box_tree::FormattingBox<'a>>,
    },
}

impl<'a> FormattingContextChild<'a> {
    pub(in crate::layout) fn element_parts(
        &self,
    ) -> Option<(
        &'a Element,
        &ElementSignature,
        Option<&[box_tree::FormattingBox<'a>]>,
    )> {
        match &self.kind {
            FormattingContextChildKind::Element {
                element,
                signature,
                children,
                ..
            } => Some((*element, signature.as_ref(), children.as_deref())),
            FormattingContextChildKind::AnonymousContent { .. } => None,
        }
    }

    pub(in crate::layout) fn anonymous_content(&self) -> Option<&[box_tree::FormattingBox<'a>]> {
        match &self.kind {
            FormattingContextChildKind::AnonymousContent { children } => Some(children),
            FormattingContextChildKind::Element { .. } => None,
        }
    }

    /// Returns the tree-abiding pseudo kind when this item originated from a
    /// generated `::before` or `::after` box rather than an element's
    /// principal box. Flex/grid replay must retain this identity so generated
    /// content and its counter scope are laid out by the pseudo path.
    /// <https://www.w3.org/TR/css-pseudo-4/#generated-content>
    pub(in crate::layout) fn generated_pseudo_kind(&self) -> Option<box_tree::GeneratedPseudoKind> {
        match &self.kind {
            FormattingContextChildKind::Element {
                generated_pseudo, ..
            } => *generated_pseudo,
            FormattingContextChildKind::AnonymousContent { .. } => None,
        }
    }

    pub(in crate::layout) fn table_fragment(&self) -> Option<&box_tree::TableFragment<'a>> {
        match &self.kind {
            FormattingContextChildKind::Element { table_fragment, .. } => table_fragment.as_deref(),
            FormattingContextChildKind::AnonymousContent { .. } => None,
        }
    }

    pub(in crate::layout) fn is_replaced_element(&self) -> bool {
        self.element_parts()
            .is_some_and(|(element, _, _)| is_replaced_element(element))
    }
}

#[derive(Debug, Clone, Copy)]
pub(in crate::layout) struct ItemizationOptions {
    pub(in crate::layout) anonymous_item_tag: &'static str,
    pub(in crate::layout) strip_blockified_inline_text_paint: bool,
    pub(in crate::layout) establish_independent_formatting_context: bool,
}

pub(in crate::layout) fn itemize_blockified_children<'a>(
    child_boxes: &'a [box_tree::FormattingBox<'a>],
    options: ItemizationOptions,
) -> (
    Vec<FormattingContextChild<'a>>,
    Vec<FormattingContextChild<'a>>,
) {
    let mut in_flow = Vec::new();
    let mut positioned = Vec::new();
    let mut anonymous_run = Vec::new();
    for box_ in child_boxes {
        if matches!(box_, box_tree::FormattingBox::Text(_))
            || formatting_box_is_contents_generated_pseudo(box_)
        {
            anonymous_run.push(box_.clone());
            continue;
        }
        flush_anonymous_item_run(&mut in_flow, &mut anonymous_run, options);
        let Some((element, signature, style, children)) = box_.element_parts() else {
            continue;
        };
        let generated_pseudo = box_.element_core().and_then(|core| match &core.source {
            box_tree::BoxSource::Principal => None,
            box_tree::BoxSource::GeneratedPseudo(pseudo) => Some(pseudo.kind),
        });
        if style.display.is_none() {
            continue;
        }
        let source_display = style.display;
        let mut style = style.clone();
        style.display = style.display.blockified();
        let children = blockified_item_children(
            source_display,
            &style,
            children,
            options.strip_blockified_inline_text_paint,
        );
        if options.establish_independent_formatting_context {
            style = independent_formatting_context_item_style(style);
        }
        let table_fragment = match box_ {
            box_tree::FormattingBox::Table(table) => Some(Box::new(table.fragment.clone())),
            _ => None,
        };
        let child = FormattingContextChild {
            kind: FormattingContextChildKind::Element {
                element,
                signature: Box::new(signature.clone()),
                generated_pseudo,
                children: Some(children),
                table_fragment,
            },
            style,
        };
        if matches!(child.style.position, Position::Absolute | Position::Fixed) {
            positioned.push(child);
        } else {
            in_flow.push(child);
        }
    }
    flush_anonymous_item_run(&mut in_flow, &mut anonymous_run, options);
    in_flow.sort_by_key(|child| child.style.order);
    (in_flow, positioned)
}

/// A generated pseudo-element with `display: contents` contributes generated
/// text/atoms directly to its parent's anonymous flex or grid item. Keeping a
/// formatting-box record preserves its counter source for evaluation, but it
/// must not become an item of its own.
/// <https://drafts.csswg.org/css-display-3/#valdef-display-contents>
fn formatting_box_is_contents_generated_pseudo(box_: &box_tree::FormattingBox<'_>) -> bool {
    box_.element_core().is_some_and(|core| {
        core.style.display.is_contents()
            && matches!(core.source, box_tree::BoxSource::GeneratedPseudo(_))
    })
}

/// Build the style used when a flex/grid item lays out ordinary flow contents.
///
/// Flex and grid items establish independent formatting contexts. For ordinary
/// flow children, Spindrift models that by changing the item inner display to
/// `flow-root`, which keeps descendant margins and floats contained by the item:
/// <https://www.w3.org/TR/css-display-3/#independent-formatting-context>.
pub(in crate::layout) fn independent_formatting_context_item_style(
    mut style: ComputedStyle,
) -> ComputedStyle {
    if style.display.is_inline_level() {
        style.display = style.display.blockified();
    }
    if style.display.is_flow() {
        style.display = style.display.with_inner(DisplayInner::FlowRoot);
    }
    style
}

/// Returns the child box list appropriate for a blockified flex/grid item.
///
/// If an inline flow source becomes a block flow item, its children were built
/// for an inline parent and need anonymous block-container fixup before block
/// layout consumes them:
/// <https://www.w3.org/TR/CSS22/visuren.html#anonymous-block-level>.
pub(in crate::layout) fn blockified_item_children<'a>(
    source_display: Display,
    item_style: &ComputedStyle,
    children: &'a [box_tree::FormattingBox<'a>],
    strip_inline_text_paint: bool,
) -> Cow<'a, [box_tree::FormattingBox<'a>]> {
    if source_display.is_inline_or_run_in_level()
        && source_display.is_flow()
        && item_style.display.is_block_level()
        && item_style.display.is_flow()
    {
        let mut children = box_tree::clone_frozen_child_boxes_as_mutable(children);
        if strip_inline_text_paint {
            strip_blockified_inline_text_paint(&mut children);
        }
        return Cow::Owned(box_tree::freeze_child_boxes(
            box_tree::normalize_block_container_children(children, item_style),
        ));
    }
    Cow::Borrowed(children)
}

fn flush_anonymous_item_run<'a>(
    children: &mut Vec<FormattingContextChild<'a>>,
    anonymous_run: &mut Vec<box_tree::FormattingBox<'a>>,
    options: ItemizationOptions,
) {
    if anonymous_run.is_empty() {
        return;
    }
    // Keep this defensive check for callers that supply child boxes outside
    // normal box-tree construction. The canonical predicate matches the
    // structural Flexbox/Grid whitespace rule, independently of `white-space`.
    if anonymous_run
        .iter()
        .all(box_tree::formatting_box_is_document_whitespace)
    {
        anonymous_run.clear();
        return;
    }
    let mut style = anonymous_item_style(options.anonymous_item_tag, &anonymous_run[0]);
    if options.establish_independent_formatting_context {
        style = independent_formatting_context_item_style(style);
    }
    children.push(FormattingContextChild {
        kind: FormattingContextChildKind::AnonymousContent {
            children: std::mem::take(anonymous_run),
        },
        style,
    });
}

fn anonymous_item_style(tag: &'static str, source: &box_tree::FormattingBox<'_>) -> ComputedStyle {
    let mut style = css::style_for_element_with_signature(
        ElementSignature::new(tag, HashMap::new()),
        None,
        &css::Stylesheets::document_only(&[]),
        Some(source.style()),
        &[],
    );
    style.display = Display::BLOCK;
    style
}

fn strip_blockified_inline_text_paint(children: &mut [box_tree::MutableFormattingBox<'_>]) {
    for child in children {
        if matches!(child, box_tree::MutableFormattingBox::Text(_)) {
            strip_text_fragment_paint(child.style_mut());
        }
    }
}

fn strip_text_fragment_paint(style: &mut ComputedStyle) {
    style.background.background_color = css::BackgroundColor::TRANSPARENT;
    style.background.background_image = css::ComputedImage::None;
    style.background.background_layers.clear();
    style.border_width = 0.0;
    style.border_widths = css::Edges::ZERO;
    style.border_styles = css::BorderStyles::NONE;
    style.border_image = css::BorderImage::initial();
}