parley 0.12.0

// Copyright 2026 the Parley Authors
// SPDX-License-Identifier: Apache-2.0 OR MIT

//! Per-style span box metrics.
//!
//! Every entry of the style table is a *span*: a styled range of text nested inside its parent
//! span, the root style being the outermost. On each line it intersects, a span generates a *span
//! box* (what CSS calls an inline box; Parley uses "inline box" for [`InlineBox`], an atomic box
//! embedded in the text). The root span box is the block container's "strut" (CSS 2 §10.8). This
//! module resolves, once per layout, the metrics of each span box from the span's first available
//! font and `line-height`, and computes the baseline shift implied by its `vertical-align`
//! relative to its parent.
//!
//! # Aligned subtrees
//!
//! CSS Inline Layout 3 §4.2.3 defines the *aligned subtree* of a span box recursively: it is that
//! box together with the aligned subtrees of each child span box (or [`InlineBox`]) whose
//! `vertical-align` is parent-relative (`baseline`, `sub`, `super`, `text-top`, `text-bottom`,
//! `middle`, or a `<length>`/`<percentage>`). Children with `vertical-align: top | bottom` are
//! aligned to the line box instead, so they and their descendants are left out.
//!
//! By that definition every span box has an aligned subtree, most of them nested inside their
//! parent's. The ones that matter for layout are those that are not part of a larger one, which
//! Parley calls *independent aligned subtrees* (our term; the specifications don't name them).
//! Their roots are the root span box, whose subtree is the *root aligned subtree*, and every box
//! with `vertical-align: top | bottom`. They don't overlap, and each box on a line belongs to
//! exactly one of them: the one rooted at its nearest ancestor (or self) with
//! `vertical-align: top | bottom`, or the root aligned subtree if there is none (see
//! [`StyleMetrics::aligned_subtree_root`]). Where the rest of this crate says just "aligned
//! subtree", it means an independent one. For example, with these spans:
//!
//! ```text
//! root
//! ├─ a (super)
//! │  └─ b (baseline)
//! └─ c (top)
//!    └─ d (sub)
//! ```
//!
//! the CSS definition gives five aligned subtrees (`{root, a, b}`, `{a, b}`, `{b}`, `{c, d}` and
//! `{d}`), of which two are independent: `{root, a, b}` (the root aligned subtree) and `{c, d}`.
//!
//! Within an independent aligned subtree all baselines are fixed relative to each other, so its
//! extents can be accumulated relative to the root's baseline while the line is being built; the
//! independent aligned subtrees are only positioned against each other, and the line box sized,
//! once the line is complete.
//! See <https://drafts.csswg.org/css-inline-3/#aligned-subtree> and CSS 2 §10.8
//! <https://www.w3.org/TR/CSS22/visudet.html#line-height>.

use alloc::vec::Vec;

#[cfg(feature = "libm")]
#[allow(unused_imports)]
use core_maths::CoreFloat;
use fontique::{Query, QueryFamily};
use parley_engine::{FontInstance, FontMetrics, ShapedText};

use crate::resolve::{ResolveContext, ResolvedStyle};
use crate::style::Brush;
use crate::{AlignmentBaseline, BaselineShift, FontContext, FontData, InlineBox, VerticalAlign};

/// Metrics of the span box generated by one style table entry.
///
/// All distances are in layout units and measured from the box's own baseline; `over`/`ascent`
/// extend upwards, `under`/`descent` downwards.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub(crate) struct StyleMetrics {
    /// Ascent of the first available font (the top of the content area).
    pub(crate) ascent: f32,
    /// Descent of the first available font (the bottom of the content area).
    pub(crate) descent: f32,
    /// x-height of the first available font, used by `vertical-align: middle`.
    pub(crate) x_height: f32,
    /// Distance from the baseline to the top of the line-height expanded span box.
    pub(crate) over: f32,
    /// Distance from the baseline to the bottom of the line-height expanded span box.
    pub(crate) under: f32,
    /// Offset of this box's baseline above the baseline of the root of the
    /// [independent aligned subtree] it belongs to.
    ///
    /// [independent aligned subtree]: Self::aligned_subtree_root
    pub(crate) baseline_offset: f32,
    /// [`Self::baseline_offset`] before quantization. Children accumulate their shifts from this
    /// so that rounding never compounds along the ancestor chain.
    pub(crate) exact_baseline_offset: f32,
    /// Style index of the root of the [independent aligned subtree] this box belongs to: the
    /// nearest ancestor (or self) with `vertical-align: top | bottom`, or `0` (the root span box)
    /// if there is none.
    ///
    /// [independent aligned subtree]: self#aligned-subtrees
    pub(crate) aligned_subtree_root: u16,
    /// Style index of the parent span; always less than the span's own index, except for the
    /// root (index `0`), whose parent is `0`.
    pub(crate) parent: u16,
    /// The style's font size, against which `sub`/`super` of children are resolved.
    pub(crate) font_size: f32,
}

/// Resolve the [`StyleMetrics`] of every style in `styles`, in table order.
///
/// Relies on the style table being ordered parent-first (`style.parent <= index`), which both
/// style builders guarantee. `shaped_text` is the already shaped text of the layout, whose run
/// metrics are reused where a style's first available font was also used for shaping.
pub(crate) fn resolve_style_metrics<B: Brush>(
    rcx: &ResolveContext,
    fcx: &mut FontContext,
    styles: &[ResolvedStyle<B>],
    shaped_text: &ShapedText,
    quantize: bool,
    out: &mut Vec<StyleMetrics>,
) {
    out.clear();
    out.reserve(styles.len());

    let mut query = fcx.collection.query(&mut fcx.source_cache);

    for (index, style) in styles.iter().enumerate() {
        let font_metrics = first_available_font(&mut query, rcx, style)
            .and_then(|font| {
                let variations = rcx.variations(style.font_variations).unwrap_or(&[]);
                shaped_run_metrics(shaped_text, &font, style.font_size, variations)
                    .or_else(|| FontMetrics::from_font_instance(&font, style.font_size, variations))
            })
            .unwrap_or_else(|| FontMetrics::fallback(style.font_size));

        let line_height = style
            .line_height
            .resolve(style.font_size, &font_metrics, quantize);

        let mut metrics = StyleMetrics::from_font(&font_metrics, line_height, quantize);
        metrics.font_size = style.font_size;

        if index == 0 {
            // The root span box (the strut).
            metrics.parent = 0;
            metrics.baseline_offset = 0.;
            metrics.exact_baseline_offset = 0.;
            metrics.aligned_subtree_root = 0;
        } else {
            let parent_index = usize::from(style.parent);
            debug_assert!(
                parent_index < index,
                "style table must be ordered parent-first"
            );
            // Never let a malformed table create an orphaned span; treat it as a child of the root.
            let parent_index = if parent_index < index {
                parent_index
            } else {
                0
            };
            metrics.parent = parent_index as u16;
            let parent = &out[parent_index];
            let align = style.vertical_align;
            if align.is_line_relative() {
                metrics.baseline_offset = 0.;
                metrics.exact_baseline_offset = 0.;
                metrics.aligned_subtree_root = index as u16;
            } else {
                let shift = shift_from_parent(align, metrics.over, metrics.under, parent);
                metrics.exact_baseline_offset = parent.exact_baseline_offset + shift;
                // Rounded once from the accumulated offset (not per level) so the total error
                // stays within half a pixel.
                metrics.baseline_offset = if quantize {
                    metrics.exact_baseline_offset.round()
                } else {
                    metrics.exact_baseline_offset
                };
                metrics.aligned_subtree_root = parent.aligned_subtree_root;
            }
        }

        out.push(metrics);
    }
}

/// The metrics of a shaped run using `font` at `font_size`, if any: the shaper has then already
/// computed the metrics this style needs. Only used at the font's default variation location,
/// which covers the common non-variable-font case without re-resolving axes.
fn shaped_run_metrics(
    shaped_text: &ShapedText,
    font: &FontInstance,
    font_size: f32,
    variations: &[crate::FontVariation],
) -> Option<FontMetrics> {
    if !variations.is_empty() || !font.synthesis.variation_settings().is_empty() {
        return None;
    }
    let font_index = shaped_text.fonts().iter().position(|f| f == font)?;
    let coords = shaped_text.normalized_coords();
    shaped_text
        .runs()
        .iter()
        .find(|run| {
            run.font_index == font_index
                && run.font_size.to_bits() == font_size.to_bits()
                && coords[run.normalized_coords_range.clone()]
                    .iter()
                    .all(|c| c.to_bits() == 0)
        })
        .map(|run| run.font_metrics)
}

/// The line-height expanded box of a font at a resolved `line-height`: the font's content area
/// (`ascent`/`descent`) with the leading distributed around it (`over`/`under`).
///
/// All distances are measured from the box's own baseline; `over`/`ascent` extend upwards,
/// `under`/`descent` downwards.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub(crate) struct BoxMetrics {
    /// Ascent of the font (the top of the content area).
    pub(crate) ascent: f32,
    /// Descent of the font (the bottom of the content area).
    pub(crate) descent: f32,
    /// Distance from the baseline to the top of the line-height expanded box.
    pub(crate) over: f32,
    /// Distance from the baseline to the bottom of the line-height expanded box.
    pub(crate) under: f32,
}

impl BoxMetrics {
    /// The box of `font` expanded to `line_height`.
    ///
    /// The half-leading is distributed as in CSS 2 §10.8.1. With `quantize`, ascent and descent
    /// are rounded to whole pixels and the leading above the baseline is floored, mirroring how
    /// text runs are placed.
    pub(crate) fn from_font(font: &FontMetrics, line_height: f32, quantize: bool) -> Self {
        let (ascent, descent) = if quantize {
            (font.ascent.round(), font.descent.round())
        } else {
            (font.ascent, font.descent)
        };
        let half_leading = (line_height - (ascent + descent)) / 2.;
        let over = if quantize {
            ascent + half_leading.floor()
        } else {
            ascent + half_leading
        };
        Self {
            ascent,
            descent,
            over,
            under: line_height - over,
        }
    }
}

impl StyleMetrics {
    /// The font-derived metrics of a span box: its [`BoxMetrics`] and x-height. The remaining
    /// fields describe the box's place in the style tree and are filled in by
    /// [`resolve_style_metrics`].
    fn from_font(font: &FontMetrics, line_height: f32, quantize: bool) -> Self {
        let box_metrics = BoxMetrics::from_font(font, line_height, quantize);
        // Fonts without an `OS/2.sxHeight` get the same estimate Gecko and Blink use
        // (`DEFAULT_XHEIGHT_FACTOR`); css-inline-3 §A.2 suggests measuring the `x` glyph or
        // `0.5em` instead, but this keeps us in line with browsers.
        let x_height = font.x_height.unwrap_or(box_metrics.ascent * 0.56);
        Self {
            ascent: box_metrics.ascent,
            descent: box_metrics.descent,
            x_height: if quantize { x_height.round() } else { x_height },
            over: box_metrics.over,
            under: box_metrics.under,
            baseline_offset: 0.,
            exact_baseline_offset: 0.,
            aligned_subtree_root: 0,
            parent: 0,
            font_size: 0.,
        }
    }
}

/// The baseline shift (positive upwards) of a box extending `over` above and `under` below its
/// baseline, relative to the baseline of its `parent` span box, for a parent-relative
/// `vertical-align` value: the `alignment-baseline` offset plus the `baseline-shift`.
/// Line-relative values (`top`, `bottom`) yield no shift.
pub(crate) fn shift_from_parent(
    align: VerticalAlign,
    over: f32,
    under: f32,
    parent: &StyleMetrics,
) -> f32 {
    let alignment = match align.alignment {
        AlignmentBaseline::Baseline => 0.,
        AlignmentBaseline::TextTop => parent.ascent - over,
        AlignmentBaseline::TextBottom => under - parent.descent,
        AlignmentBaseline::Middle => parent.x_height / 2. - (over - under) / 2.,
    };
    let shift = match align.shift {
        BaselineShift::Length(length) => length,
        // Constants as used by WebKit and Blink.
        BaselineShift::Sub => -(parent.font_size / 5.),
        BaselineShift::Super => parent.font_size / 3.,
        BaselineShift::Top | BaselineShift::Bottom => 0.,
    };
    alignment + shift
}

/// Where an in-flow [`InlineBox`] sits relative to the baseline of the independent aligned
/// subtree it belongs to.
#[derive(Clone, Copy, Debug)]
pub(crate) struct InlineBoxPlacement {
    /// Style index of the aligned subtree root (see [`StyleMetrics::aligned_subtree_root`]).
    pub(crate) aligned_subtree_root: u16,
    /// Offset of the box's baseline above the subtree root's baseline.
    pub(crate) baseline_offset: f32,
    /// Height of the box above its baseline.
    pub(crate) ascent: f32,
    /// Height of the box below its baseline.
    pub(crate) descent: f32,
}

/// Resolve the parent-relative alignment of `inline_box` against the span box of the style
/// containing it (`parent_style`).
///
/// A box without an explicit baseline sits on the baseline, i.e. it is all ascent. For
/// `vertical-align: top | bottom` the returned offset is relative to the subtree the parent
/// belongs to, but such boxes are positioned against the line box instead (see
/// [`crate::Line::inline_box_top`]).
pub(crate) fn inline_box_placement(
    inline_box: &InlineBox,
    parent_style: u16,
    style_metrics: &[StyleMetrics],
    quantize: bool,
) -> InlineBoxPlacement {
    let ascent = inline_box.baseline.unwrap_or(inline_box.height);
    let descent = inline_box.height - ascent;
    let parent = style_metrics
        .get(usize::from(parent_style))
        .copied()
        .unwrap_or_default();
    let shift = shift_from_parent(inline_box.vertical_align, ascent, descent, &parent);
    let baseline_offset = parent.exact_baseline_offset + shift;
    InlineBoxPlacement {
        aligned_subtree_root: parent.aligned_subtree_root,
        baseline_offset: if quantize {
            baseline_offset.round()
        } else {
            baseline_offset
        },
        ascent,
        descent,
    }
}

/// The [first available font] of `style`.
///
/// [first available font]: https://drafts.csswg.org/css-fonts-4/#first-available-font
fn first_available_font<B: Brush>(
    query: &mut Query<'_>,
    rcx: &ResolveContext,
    style: &ResolvedStyle<B>,
) -> Option<FontInstance> {
    let families = rcx.stack(style.font_family).unwrap_or(&[]);
    query.set_families(families.iter().copied().map(QueryFamily::Id));
    query.set_attributes(fontique::Attributes {
        width: style.font_width,
        weight: style.font_weight,
        style: style.font_style,
    });
    let font = query.first_available_font()?;
    Some(FontInstance {
        font: FontData {
            data: font.blob,
            index: font.index,
        },
        synthesis: font.synthesis,
    })
}