tessera_components/

column.rs

//! A vertical layout component.
//!
//! ## Usage
//!
//! Use to stack children vertically.
use tessera_ui::{
    __private::configure_layout_node,
    AxisConstraint, ComputedData, Constraint, LayoutResult, MeasurementError, Modifier,
    NoopDrawModifier, Px, PxPosition, RenderSlot,
    layout::{LayoutChild, LayoutPlacementTarget, MeasureScope, PlacementResult, PlacementScope},
    tessera,
};

use crate::{
    alignment::{CrossAxisAlignment, MainAxisAlignment},
    layout_flex::{classify_children, cross_axis_child_constraint},
};

/// # column
///
/// A layout component that arranges its children in a vertical column.
///
/// ## Usage
///
/// Stack components vertically, with options for alignment and flexible
/// spacing.
///
/// ## Parameters
///
/// - `modifier` — modifier chain applied to the column container.
/// - `main_axis_alignment` — alignment along the vertical axis.
/// - `cross_axis_alignment` — alignment along the horizontal axis.
/// - `children` — child slot rendered inside the column.
///
/// ## Examples
///
/// ```
/// use tessera_components::{
///     column::column, modifier::ModifierExt as _, spacer::spacer, text::text,
/// };
/// use tessera_ui::Modifier;
///
/// # use tessera_ui::tessera;
/// # #[tessera]
/// # fn component() {
/// column().children(|| {
///     text("First item");
///     spacer().modifier(Modifier::new().weight(1.0));
///     text("Last item");
/// });
/// # }
/// # tessera_ui::testing::layout_test(component).run();
/// ```
#[tessera(tessera_ui, layout)]
pub fn column(
    modifier: Option<Modifier>,
    main_axis_alignment: Option<MainAxisAlignment>,
    cross_axis_alignment: Option<CrossAxisAlignment>,
    children: Option<RenderSlot>,
) {
    let modifier = modifier.unwrap_or_default();
    let main_axis_alignment = main_axis_alignment.unwrap_or_default();
    let cross_axis_alignment = cross_axis_alignment.unwrap_or_default();
    configure_layout_node(
        ColumnLayout {
            main_axis_alignment,
            cross_axis_alignment,
        },
        NoopDrawModifier,
        modifier,
    );
    children.unwrap_or_else(RenderSlot::empty).render();
}

#[derive(Clone, PartialEq)]
struct ColumnLayout {
    main_axis_alignment: MainAxisAlignment,
    cross_axis_alignment: CrossAxisAlignment,
}

impl tessera_ui::LayoutModifierNode for ColumnLayout {
    fn measure_eq(&self, other: &Self) -> bool {
        (self.cross_axis_alignment == CrossAxisAlignment::Stretch)
            == (other.cross_axis_alignment == CrossAxisAlignment::Stretch)
    }

    fn place_children(
        &self,
        scope: &PlacementScope<'_>,
        _inner: &PlacementResult,
    ) -> Option<PlacementResult> {
        let children = scope.children();
        let children_sizes = children
            .iter()
            .map(|child| Some(child.size()))
            .collect::<Vec<_>>();
        let total_children_height = children
            .iter()
            .map(|child| child.size().height)
            .fold(Px::ZERO, |total, size| total + size);
        let mut result = LayoutResult::new(scope.size());
        place_children_with_alignment(
            &PlaceChildrenArgs {
                children_sizes: &children_sizes,
                children: &children,
                final_column_width: scope.size().width,
                final_column_height: scope.size().height,
                total_children_height,
                main_axis_alignment: self.main_axis_alignment,
                cross_axis_alignment: self.cross_axis_alignment,
                child_count: children.len(),
            },
            &mut result,
        );
        Some(result.into_placement_result())
    }

    fn measure(&self, input: &mut MeasureScope<'_>) -> Result<LayoutResult, MeasurementError> {
        let mut result = LayoutResult::default();
        let children = input.children();
        let child_weights = collect_child_weights(input, &children);
        let n = child_weights.len();
        assert_eq!(
            children.len(),
            n,
            "Mismatch between children defined in scope and runtime children count"
        );

        let column_parent_constraint = *input.parent_constraint().as_ref();

        let mut children_sizes = vec![None; n];
        let mut max_child_width = Px(0);

        let has_weighted_children = child_weights.iter().any(|&weight| weight > 0.0);
        let should_use_weight_for_height =
            has_weighted_children && column_parent_constraint.height.resolve_max().is_some();

        let (final_column_width, final_column_height, total_measured_children_height) =
            if should_use_weight_for_height {
                measure_weighted_column(
                    &children,
                    input,
                    &child_weights,
                    &column_parent_constraint,
                    &mut children_sizes,
                    &mut max_child_width,
                    self.cross_axis_alignment,
                )?
            } else {
                measure_unweighted_column(
                    &children,
                    input,
                    &column_parent_constraint,
                    &mut children_sizes,
                    &mut max_child_width,
                    self.cross_axis_alignment,
                )?
            };

        place_children_with_alignment(
            &PlaceChildrenArgs {
                children_sizes: &children_sizes,
                children: &children,
                final_column_width,
                final_column_height,
                total_children_height: total_measured_children_height,
                main_axis_alignment: self.main_axis_alignment,
                cross_axis_alignment: self.cross_axis_alignment,
                child_count: n,
            },
            &mut result,
        );

        Ok(result.with_size(ComputedData {
            width: final_column_width,
            height: final_column_height,
        }))
    }
}

struct PlaceChildrenArgs<'a, T> {
    children_sizes: &'a [Option<ComputedData>],
    children: &'a [T],
    final_column_width: Px,
    final_column_height: Px,
    total_children_height: Px,
    main_axis_alignment: MainAxisAlignment,
    cross_axis_alignment: CrossAxisAlignment,
    child_count: usize,
}

fn measure_unweighted_children_for_column(
    children: &[LayoutChild],
    input: &mut MeasureScope<'_>,
    indices: &[usize],
    children_sizes: &mut [Option<ComputedData>],
    max_child_width: &mut Px,
    column_parent_constraint: &Constraint,
    cross_axis_alignment: CrossAxisAlignment,
) -> Result<Px, MeasurementError> {
    let mut total = Px(0);

    let parent_offered_constraint_for_child = Constraint::new(
        cross_axis_child_constraint(column_parent_constraint.width, cross_axis_alignment),
        column_parent_constraint.height.without_min(),
    );

    for &child_idx in indices {
        let child_id = children[child_idx];
        let child_result = child_id.measure(input, &parent_offered_constraint_for_child)?;
        children_sizes[child_idx] = Some(child_result.size());
        total += child_result.height;
        *max_child_width = (*max_child_width).max(child_result.width);
    }

    Ok(total)
}

struct WeightedColumnMeasureContext<'a> {
    children_sizes: &'a mut [Option<ComputedData>],
    max_child_width: &'a mut Px,
    column_parent_constraint: &'a Constraint,
    child_weights: &'a [f32],
    cross_axis_alignment: CrossAxisAlignment,
}

fn measure_weighted_children_for_column(
    children: &[LayoutChild],
    scope: &mut MeasureScope<'_>,
    ctx: WeightedColumnMeasureContext<'_>,
    weighted_indices: &[usize],
    remaining_height: Px,
    total_weight: f32,
) -> Result<(), MeasurementError> {
    if total_weight <= 0.0 {
        return Ok(());
    }

    for &child_idx in weighted_indices {
        let child_weight = ctx.child_weights[child_idx];
        let allocated_height =
            Px((remaining_height.0 as f32 * (child_weight / total_weight)) as i32);
        let child_id = children[child_idx];
        let parent_offered_constraint_for_child = Constraint::new(
            cross_axis_child_constraint(
                ctx.column_parent_constraint.width,
                ctx.cross_axis_alignment,
            ),
            AxisConstraint::exact(allocated_height),
        );
        let child_result = child_id.measure(scope, &parent_offered_constraint_for_child)?;
        ctx.children_sizes[child_idx] = Some(child_result.size());
        *ctx.max_child_width = (*ctx.max_child_width).max(child_result.width);
    }

    Ok(())
}

fn measure_weighted_column(
    children: &[LayoutChild],
    input: &mut MeasureScope<'_>,
    child_weights: &[f32],
    column_parent_constraint: &Constraint,
    children_sizes: &mut [Option<ComputedData>],
    max_child_width: &mut Px,
    cross_axis_alignment: CrossAxisAlignment,
) -> Result<(Px, Px, Px), MeasurementError> {
    let available_height_for_children = column_parent_constraint
        .height
        .resolve_max()
        .expect("Column height Fill expected with finite max constraint");

    let (weighted_children_indices, unweighted_children_indices, total_weight_sum) =
        classify_children(child_weights);

    let total_height_of_unweighted_children = measure_unweighted_children_for_column(
        children,
        input,
        &unweighted_children_indices,
        children_sizes,
        max_child_width,
        column_parent_constraint,
        cross_axis_alignment,
    )?;

    let remaining_height_for_weighted_children =
        (available_height_for_children - total_height_of_unweighted_children).max(Px(0));

    measure_weighted_children_for_column(
        children,
        input,
        WeightedColumnMeasureContext {
            children_sizes,
            max_child_width,
            column_parent_constraint,
            child_weights,
            cross_axis_alignment,
        },
        &weighted_children_indices,
        remaining_height_for_weighted_children,
        total_weight_sum,
    )?;

    let total_measured_children_height: Px = children_sizes
        .iter()
        .filter_map(|s| s.as_ref().map(|s| s.height))
        .fold(Px(0), |acc, h| acc + h);

    let final_column_height = column_parent_constraint
        .height
        .clamp(total_measured_children_height);
    let final_column_width = column_parent_constraint.width.clamp(*max_child_width);

    Ok((
        final_column_width,
        final_column_height,
        total_measured_children_height,
    ))
}

fn collect_child_weights(input: &MeasureScope<'_>, children: &[LayoutChild]) -> Vec<f32> {
    children
        .iter()
        .map(|child_id| {
            child_id
                .parent_data::<crate::modifier::WeightParentData>(input)
                .map(|data| data.weight)
                .unwrap_or(0.0)
        })
        .collect()
}

fn measure_unweighted_column(
    children: &[LayoutChild],
    input: &mut MeasureScope<'_>,
    column_parent_constraint: &Constraint,
    children_sizes: &mut [Option<ComputedData>],
    max_child_width: &mut Px,
    cross_axis_alignment: CrossAxisAlignment,
) -> Result<(Px, Px, Px), MeasurementError> {
    let n = children_sizes.len();
    let mut total_children_measured_height = Px(0);

    let parent_offered_constraint_for_child = Constraint::new(
        cross_axis_child_constraint(column_parent_constraint.width, cross_axis_alignment),
        column_parent_constraint.height.without_min(),
    );

    for (i, child_id) in children.iter().enumerate().take(n) {
        let child_result = child_id.measure(input, &parent_offered_constraint_for_child)?;
        children_sizes[i] = Some(child_result.size());
        total_children_measured_height += child_result.height;
        *max_child_width = (*max_child_width).max(child_result.width);
    }

    let final_column_height = column_parent_constraint
        .height
        .clamp(total_children_measured_height);
    let final_column_width = column_parent_constraint.width.clamp(*max_child_width);
    Ok((
        final_column_width,
        final_column_height,
        total_children_measured_height,
    ))
}

fn place_children_with_alignment<T: LayoutPlacementTarget>(
    args: &PlaceChildrenArgs<'_, T>,
    result: &mut LayoutResult,
) {
    let (mut current_y, spacing_between_children) = crate::layout_flex::main_axis_offsets(
        args.final_column_height,
        args.total_children_height,
        args.main_axis_alignment,
        args.child_count,
    );

    for (i, child_size_opt) in args.children_sizes.iter().enumerate() {
        if let Some(child_actual_size) = child_size_opt {
            let child_id = args.children[i];
            let x_offset = crate::layout_flex::cross_axis_offset(
                child_actual_size.width,
                args.final_column_width,
                args.cross_axis_alignment,
            );
            result.place_child(child_id, PxPosition::from_f32_xy(x_offset, current_y));
            current_y += child_actual_size.height.0 as f32;
            if i < args.child_count - 1 {
                current_y += spacing_between_children;
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use tessera_ui::{
        AxisConstraint, ComputedData, Dp, LayoutResult, MeasurementError, Modifier,
        NoopDrawModifier, Px,
        layout::{MeasureScope, layout},
        tessera,
    };

    use crate::{
        alignment::{CrossAxisAlignment, MainAxisAlignment},
        modifier::{ModifierExt as _, SemanticsArgs},
    };

    use super::column;

    #[derive(Clone, PartialEq)]
    struct FixedTestLayout {
        width: i32,
        height: i32,
    }

    #[derive(Clone, PartialEq)]
    struct FillHeightTestLayout {
        width: i32,
    }

    impl tessera_ui::LayoutModifierNode for FixedTestLayout {
        fn measure(&self, _input: &mut MeasureScope<'_>) -> Result<LayoutResult, MeasurementError> {
            Ok(LayoutResult::new(ComputedData {
                width: Px::new(self.width),
                height: Px::new(self.height),
            }))
        }
    }

    impl tessera_ui::LayoutModifierNode for FillHeightTestLayout {
        fn measure(&self, input: &mut MeasureScope<'_>) -> Result<LayoutResult, MeasurementError> {
            let height = input
                .parent_constraint()
                .height()
                .resolve_max()
                .expect("FillHeightTestLayout requires a bounded height constraint");

            Ok(LayoutResult::new(ComputedData {
                width: Px::new(self.width),
                height,
            }))
        }
    }

    #[tessera]
    fn fixed_test_box(tag: Option<String>, width: Option<i32>, height: Option<i32>) {
        let tag = tag.unwrap_or_default();
        let width = width.unwrap_or_default();
        let height = height.unwrap_or_default();

        layout()
            .policy(FixedTestLayout { width, height })
            .draw(NoopDrawModifier)
            .modifier(Modifier::new().semantics(SemanticsArgs {
                test_tag: Some(tag),
                ..Default::default()
            }));
    }

    #[tessera]
    fn fill_height_test_box(tag: Option<String>, width: Option<i32>) {
        let tag = tag.unwrap_or_default();
        let width = width.unwrap_or_default();

        layout()
            .policy(FillHeightTestLayout { width })
            .draw(NoopDrawModifier)
            .modifier(Modifier::new().semantics(SemanticsArgs {
                test_tag: Some(tag),
                ..Default::default()
            }));
    }

    #[tessera]
    fn column_layout_case() {
        column()
            .modifier(Modifier::new().constrain(
                Some(AxisConstraint::exact(Px::new(100))),
                Some(AxisConstraint::exact(Px::new(60))),
            ))
            .main_axis_alignment(MainAxisAlignment::Start)
            .cross_axis_alignment(CrossAxisAlignment::Center)
            .children(|| {
                column_first_box();
                column_second_box();
            });
    }

    #[tessera]
    fn column_first_box() {
        fixed_test_box()
            .tag("column_first".to_string())
            .width(20)
            .height(10);
    }

    #[tessera]
    fn column_second_box() {
        fixed_test_box()
            .tag("column_second".to_string())
            .width(40)
            .height(15);
    }

    #[tessera]
    fn column_weighted_case() {
        column()
            .modifier(Modifier::new().constrain(
                Some(AxisConstraint::exact(Px::new(60))),
                Some(AxisConstraint::exact(Px::new(90))),
            ))
            .main_axis_alignment(MainAxisAlignment::Start)
            .cross_axis_alignment(CrossAxisAlignment::Start)
            .children(|| {
                fixed_test_box()
                    .tag("column_weighted_fixed".to_string())
                    .width(20)
                    .height(10);
                layout().modifier(Modifier::new().weight(1.0)).child(|| {
                    fill_height_test_box()
                        .tag("column_weighted_fill".to_string())
                        .width(15);
                });
            });
    }

    #[test]
    fn column_centers_children_on_cross_axis() {
        tessera_ui::assert_layout! {
            viewport: (120, 80),
            content: {
                column_layout_case();
            },
            expect: {
                node("column_first").position(40, 0).size(20, 10);
                node("column_second").position(30, 10).size(40, 15);
            }
        }
    }

    #[test]
    fn column_allocates_remaining_height_to_weighted_child() {
        tessera_ui::assert_layout! {
            viewport: (100, 100),
            content: {
                column_weighted_case();
            },
            expect: {
                node("column_weighted_fixed").position(0, 0).size(20, 10);
                node("column_weighted_fill").position(0, 10).size(15, 80);
            }
        }
    }

    #[tessera]
    fn sized_test_box(tag: Option<String>, width: Option<Dp>, height: Option<Dp>) {
        let tag = tag.unwrap_or_default();
        let width = width.unwrap_or(Dp(0.0));
        let height = height.unwrap_or(Dp(0.0));

        layout()
            .draw(NoopDrawModifier)
            .modifier(
                Modifier::new()
                    .size(width, height)
                    .semantics(SemanticsArgs {
                        test_tag: Some(tag),
                        ..Default::default()
                    }),
            );
    }

    #[tessera]
    fn column_center_sized_case() {
        column()
            .modifier(Modifier::new().fill_max_width())
            .main_axis_alignment(MainAxisAlignment::Start)
            .cross_axis_alignment(CrossAxisAlignment::Center)
            .children(|| {
                sized_test_box()
                    .tag("column_center_sized".to_string())
                    .width(Dp(32.0))
                    .height(Dp(4.0));
            });
    }

    #[tessera]
    fn column_stretch_sized_case() {
        column()
            .modifier(Modifier::new().fill_max_width())
            .main_axis_alignment(MainAxisAlignment::Start)
            .cross_axis_alignment(CrossAxisAlignment::Stretch)
            .children(|| {
                sized_test_box()
                    .tag("column_stretch_sized".to_string())
                    .width(Dp(32.0))
                    .height(Dp(4.0));
            });
    }

    #[test]
    fn column_measures_center_aligned_sized_child_intrinsically() {
        tessera_ui::assert_layout! {
            viewport: (100, 60),
            content: {
                column_center_sized_case();
            },
            expect: {
                node("column_center_sized").position(34, 0).size(32, 4);
            }
        }
    }

    #[test]
    fn column_stretches_sized_child_to_container_width() {
        tessera_ui::assert_layout! {
            viewport: (100, 60),
            content: {
                column_stretch_sized_case();
            },
            expect: {
                node("column_stretch_sized").position(0, 0).size(100, 4);
            }
        }
    }
}