//! Every value the engine has for an out-of-flow box when it calls the `containing_block`
//! generated function, under the one name and type each value has, and the fixed fields of
//! the function's answer.
//!
//! The function's types file (`containing_block_types.rs`) is written by a model, and the
//! engine fills its inputs struct without knowing in advance which values it holds: the call
//! site (`fragment.rs` `containing_block_for`) builds a [`ContainingBlockEngineValues`], and
//! `containing_block::inputs_from`, which `build.rs` writes from the types file in place,
//! copies each field the inputs struct declares from the field of the same name here. So a
//! types file's inputs struct may only take fields of [`ContainingBlockEngineValues`], under
//! the same names and types, and its outputs struct has exactly the fields of
//! [`ContainingBlockEngineAnswer`]. `job-check types --engine` checks both on the file alone
//! (`jobs/src/types_file.rs` `check_names`).
//!
//! The inputs borrow the ancestor chain for a lifetime, named `'a` in both the engine's
//! struct and the types file's: the engine hands the function the chain it collected without
//! copying it. The types a field names (`Position`, `Rect`, `AncestorBox`,
//! `ContainingBlockRule`) are the engine's own and live in `crate::containing_block`, which a
//! types file imports from.
//!
//! Every rect is in viewport coordinates: the x/y of the root element's border box is the
//! canvas origin.
//!
//! A value whose doc has a paragraph opening `Needed:` is one the specification's rules
//! read whenever the specification text says one of the quoted phrases in it: a types
//! file written from that text takes the value. `job-check types --engine <file>
//! --specification <folder>` refuses a types file that does not while the text says the
//! phrase (`jobs/src/types_file.rs` `check_needs`).

use dom::computed::Position;

use crate::containing_block::{AncestorBox, ContainingBlockRule, Rect};

/// Every value the engine has worked out for the box at the call, and nothing else.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ContainingBlockEngineValues<'a> {
    /// The box's own `position`, the value CSS 2.1 10.1 branches on first. The engine asks
    /// about a box it takes out of normal flow, so `Absolute` or `Fixed`, but every
    /// `Position` can be handed over.
    ///
    /// Needed: the specification text says "'position'".
    pub position: Position,
    /// Every ancestor of the box, nearest first, ending at the root element, each with its
    /// own `position`, whether it is a block container, whether it is the root element, and
    /// its content-box and padding-box rects in viewport coordinates. Empty for the root
    /// element itself.
    ///
    /// Needed: the specification text says "nearest ancestor".
    pub ancestors: &'a [AncestorBox],
    /// The initial containing block: a viewport-sized rect at the canvas origin, in px.
    ///
    /// Needed: the specification text says "initial containing block".
    pub viewport: Rect,
}

/// The fields of the function's answer, which the engine reads by these names: a types
/// file's outputs struct declares exactly these.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ContainingBlockEngineAnswer {
    /// The rect the containing block covers, in px in viewport coordinates. The engine
    /// resolves the box's percentages and offsets against it.
    pub rect: Rect,
    /// Which rule of CSS 2.1 10.1 chose the rect. The engine reports it and never reads it
    /// for geometry.
    pub rule: ContainingBlockRule,
    /// Which ancestor `rect` belongs to, as an index (unitless) into the ancestor chain, or
    /// `None` when the rect is the initial containing block and belongs to no box. The engine
    /// reports it and never reads it for geometry.
    pub ancestor: Option<usize>,
}