Warning, huge PR. There are 1500+ lines of tests 🤧 I'd split this up if I wasn't working by myself.

This PR is to implement two new components:

• FlexGroup
• Flex

Which implement a similar layout algorithm as flexbox on the web and flex widgets in Flutter.

It also makes a series of related changes to other modules, like Vector2, and implements a new test_util workspace crate. I'm hoping the tests set some precedent for how I can begin testing other widgets.

This PR refactors the Container widget adds a new margin property to SizedLayoutBox and LayoutBox.

Previously, a Container was implementing margin and padding by nesting another widget inside itself and setting its own material to Material::None.

This is pretty redundant and pollutes the LayoutTree with additional widgets that exist simply to offset their child. This is a symptom of the layout abstraction not being powerful enough; padding and margins are common properties and should be baked into the layout model.

This is already done in the CSS box model and in Flutter and various other layout libraries.

The new responsibilities of LayoutBox are:

• Padding should be implemented by the parent widget passing custom constraints to it's child, and positioning it accordingly
• Margin should be implemented through the SizedLayoutBox return type

In the canary_layouts_flex_sidebar canary layout test, it reduces the number of generated LayoutBox items from 9 to 6! That's a ~44% reduction. Good stuff 👌

This PR refactors Material and the platform/browser module to add support for solid-colored borders around for all LayoutBox elements. Currently it only adds support on Container widgets, but it should be easy to expand this out in the future.

A border increases the size of the LayoutBox according to the size of the border. This is the same as the CSS box-sizing: content-box property.

This PR is mixed up with #3 because I was tired and forgot to switch branches before writing new code, and then they got tangled. Since I'm the only one working on this right now, I don't mind 🤷‍♂️ I'll resolve anything when I merge them both.

This PR simplifies the API for the flex container and introduces "canary layout" integration tests. It also adds a bunch of rustdoc comments.

Simplified flex container API

Before this PR, flex layout was done inside a FlexGroup which required that each child was wrapped in a Flex::Flexible or Flex::Fixed enum instance:

let widgets = FlexGroup {
    children: vec![
        Flex::Fixed {
            child: Box::new(/* fixed child */),
        },
        Flex::Flexible {
            flex: 1.0,
            child: Box::new(/* flexible child */),
        },
    ],
    ..Default::default()
};

This PR removes the Flex num requirement, and renames FlexGroup to Flex. We now only need to wrap flexible children with a Flexible widget:

let widgets = Flex {
    children: vec![
        Box::new(/* fixed child */),
        Flexible {
            flex: 1.0,
            child: Box::new(/* flexible child */),
        },
    ],
    ..Default::default()
};

Which is much nicer to use.

This is achieved by making the Flex struct accept Box<dyn FlexLayout> children instead of Box<dyn Layout>:

pub trait FlexLayout: Debug {
    fn flex_factor(&self) -> Option<f32>;
    fn flex_layout(&self, tree: &mut LayoutTree, constraints: &BoxConstraints) -> SizedLayoutBox;
}

pub struct Flex {
    /* snip */
    pub children: Vec<Box<dyn FlexLayout>>,
}

And implements FlexLayout as a metatrait on all existing Layout types:

impl<T> FlexLayout for T
where
    T: Layout,
{
    fn flex_factor(&self) -> Option<f32> {
        None
    }

    fn flex_layout(&self, tree: &mut LayoutTree, constraints: &BoxConstraints) -> SizedLayoutBox {
        self.layout(tree, constraints)
    }
}

Rust traits to the rescue!

Canary layout integration tests

Although the flex module already has an obscene number of tests, they are unit tests that target very specific and very small units of layout logic. They don't how different widgets might interact with each other.

The integration tests live in the tests/ folder alongside src/ and are for testing the composition of widgets in complex layouts.

Hi @harrisonturton ,

I've been actively looking for a webGL framework to help me build out a project I'm working on (flowbench.io) and something like this would be super useful. I'm surprised the webGL community hasn't gotten onto something like this sooner.

I've been considering ensoGL but am finding it a bit intimidating. I love how clean and simple your syntax is.

Good luck!

Currently, transparent colors like this:

Color::green().alpha(0.5)

Results in a lighter shade of green. When two widgets are drawn on top of each other, the topmost widget just covers the bottom one with its own color, rather than mixing the two.

The browser rendering engine currently doesn't have a compositing step, it's a very basic immediate-mode renderer that just naively paints the LayoutBox geometry. I think fixing this would require introducing some more logic around layers.

Currently the crates/platform/browser module doesn't have any tests.

It should have tests.

Since testing wasm-bindgen directly seems to be a bit tricky, this issue might involve writing a browser test utils library.