[Merged by Bors] - Document how padding and margin behave with percentage values

[ickshonpe]

Objective

Add a comment explaining that percentage padding is calculated based on the width of the parent node.

[nicoburns]

This change looks good, but:

• I think it would be good to explicitly write out that this applies to even top/bottom padding
• It would be good to add the same note to margin and border

[ickshonpe]

I thought borders were implemented in Bevy and occupied space around a node but just weren't rendered, but that doesn't seem to be right like in this example:

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_startup_system(setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2dBundle::default());
    let root = commands.spawn(NodeBundle {
        style: Style {
            flex_direction: FlexDirection::Column,
            flex_basis: Val::Percent(100.0),
            margin: UiRect::all(Val::Px(25.0)),
            flex_wrap: FlexWrap::Wrap,
            justify_content: JustifyContent::FlexStart,
            align_items: AlignItems::FlexStart,
            align_content: AlignContent::FlexStart,
            ..Default::default()
        },
        background_color: BackgroundColor(Color::BLACK),
        ..Default::default()
    }).id();

    let borders = [
        UiRect::all(Val::Auto),
        UiRect::all(Val::Px(0.)),
        UiRect::all(Val::Px(25.0)),
        UiRect::all(Val::Px(250.0)),
        UiRect::all(Val::Undefined),
        UiRect::all(Val::Percent(25.0)),
        UiRect::all(Val::Percent(100.0)),
        UiRect::all(Val::Percent(1000.0)),
        UiRect::left(Val::Px(25.0)),
        UiRect::right(Val::Px(25.0)),
        UiRect::top(Val::Px(25.0)),
        UiRect::bottom(Val::Px(25.0)),
        UiRect::left(Val::Percent(25.0)),
        UiRect::right(Val::Percent(25.0)),
        UiRect::top(Val::Percent(25.0)),
        UiRect::bottom(Val::Percent(25.0)),
        UiRect::left(Val::Percent(1000.0)),
        UiRect::vertical(Val::Percent(200.0)),
        UiRect::vertical(Val::Px(200.0)),
        UiRect::horizontal(Val::Px(200.0)),
        UiRect::vertical(Val::Percent(200.0)),
    ];

    for border in borders.into_iter().cycle().take(400) { 
        let b = commands.spawn(NodeBundle {
            style: Style {
                size: Size::all(Val::Px(50.)),
                border,
                margin: UiRect::all(Val::Px(5.)),
                ..Default::default()
            },
            background_color: BackgroundColor(Color::BLUE),
            ..Default::default()
        }).id();
        commands.entity(root).add_child(b);    
    }
}

Draws the squares in a regular grid pattern, even with all the different border values. Am I missing something?

[ickshonpe]

oh this one is fine though:

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_startup_system(setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2dBundle::default());
    let root = commands.spawn(NodeBundle {
        style: Style {
            border: UiRect::all(Val::Px(25.0)),
            align_self: AlignSelf::FlexStart,
            ..Default::default()
        },
        background_color: BackgroundColor(Color::BLACK),
        ..Default::default()
    }).id();
    
    let square = commands.spawn(NodeBundle {
        style: Style {
            size: Size::all(Val::Px(200.0)),
            border: UiRect::all(Val::Px(50.0)),
            ..Default::default()
        },
        background_color: BackgroundColor(Color::RED),
        ..Default::default()
    }).id();

    let inner = commands.spawn(NodeBundle {
        style: Style {
            size: Size::all(Val::Px(100.0)),
            ..Default::default()
        },
        background_color: BackgroundColor(Color::BLACK),
        ..Default::default()
    }).id();

    commands.entity(root).add_child(square);
    commands.entity(square).add_child(inner);
}

[ickshonpe]

Improved the examples a bit but they aren't great without the option to test them against a generated layout.
It would be nice to be able to generate layouts for tests without having to go through the flex_node_system machinery.

As for borders, I'm not sure I understand how borders work. I had thought borders followed mostly the same rules as margins, except for having no automatic determination and being drawn.

As the rendering isn't implemented, they aren't useful anyway at the moment, so should we just have a comment saying "not implemented yet, don't use"? Or even remove the field until the implementation is ready.

[nicoburns]

Should we just have a comment saying "not implemented yet, don't use"? Or even remove the field until the implementation is ready.

IMO it ought to be removed entirely if borders aren't actually drawn. Looks like there's already an issue for actual border support #5924

[ickshonpe]

I could implement basic solid coloured border support myself just quickly, but I'm not quite sure where to get the border geometry.
Is it just that the node size is increased by the size of the border, and you just go inwards from each edge by the border value?

edit: oh. that wouldn't work with percentages though.

[nicoburns]

Is it just that the node size is increased by the size of the border, and you just go inwards from each edge by the border value?

You go inwards from each edge by the border value (in CSS varies depending on the box-sizing property. We assume box-sizing: border-box which is basically what "everyone" on the web uses too (it's not the default for historical reasons but the vast majority of websites are using a CSS reset which sets border-box) See: https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing

Percentage borders are not a thing on web (they are a taffy/bevy proprietary extension). They are resolved against the computed width of the parent node by analogy with padding/margin.

[ickshonpe]

Ah, I think I understand borders after hacking out this implementation.

What I was missing is that the size of the node only needs to be expanded by the size of the border if there are constraints that prevent the layout algorithm from placing the border within the existing node boundary.

[nicoburns]

What I was missing is that the size of the node only needs to be expanded by the size of the border if there are constraints that prevent the layout algorithm from placing the border within the existing node boundary.

I believe this is correct, but that even if it does "need" to be expanded, a node won't necessarily be expanded just to accommodate a border. It's also entirely possible that the border is just clipped. An example would a node with a fixed width which is smaller than the size needed to accommodate the border

EDIT: Nope. I tested this and it seems that nodes are always expanded to accommodate borders if necessary.

[alice-i-cecile]

Very helpful.

bors r+

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-and-install-on-iOS
• build-android
• build (macos-latest)
• build (ubuntu-latest)
• build-wasm
• build (windows-latest)
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• check-compiles
• check-doc
• check-missing-examples-in-docs
• ci
• markdownlint
• msrv
• run-examples
• run-examples-on-wasm
• run-examples-on-windows-dx12