Proposal: Introducing Flexbox to Rich

[darrenburns]

What

Flex provides us with a powerful method of widget layout. We can use it to space items out with equal space between them, equal space around them, center the items on the axis, align them all at the start of the axis, align them all at the end of the axis. This alignment is typically offered on both the main and cross axis.

Why

I've found it to be an intuitive and efficient way of laying things out, which solves many of the use cases I commonly run into when doing web development work.

While a grid system is helpful for the broader, macro-level layout, flex offers a means of spacing items within the cells of the grid.

Flex is really well known, is framework-agnostic, and is implemented in HTML/CSS and other popular UI frameworks such as Flutter (which has a fantastic API with some similarities to Rich). There are many resources available for learning it online.

The Columns and Layout objects aren't flexible enough to support some common layouts without workarounds.

API

Prior art

Here's how Flutter does it:

Row(  // also works with Column
    mainAxisAlignment: MainAxisAlignment.spaceAround,
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
        MyWidget(),
        MyWidget(height: 200.0, width: 200.0),
        MyWidget(height: 50.0, width: 50.0)
    ]
);

When you create a Column or Row of widgets, you can set the mainAxisAlignment [docs] to declare how you wish for children to be aligned on that axis. You can set crossAxisAlignment to layout children on the other axis. In the example above, the child widgets are laid out with equal space around each of them (meaning there'd also be space at the left and right of the widgets).

|  [widget1]    [widget2]    [widget3]  |

Note that each widget has 2 spaces at each side, so there are 2 spaces between the terminal edge (represented by |) and the widget boundary, but 4 spaces between each widget.

A Flutter Row is roughly analogous to a Rich Columns object. Rich doesn't seem to have a Rows, which could allow alignment on the vertical axis.

Flex in Rich

Columns in Rich already have an align: AlignMethod attribute which covers aligning each item within its column: left, center and right. However, Flex is concerned with the spacing between the items themselves, which as far as I understand, Rich doesn't support.

I'd like to propose a Flex widget, which allows alignment on both the horizontal and vertical axes.

Here's an example:

lhs = Panel("My Fancy App")
rhs = Panel("v90")
Flex(lhs, rhs, align_horizontal="space-evenly", align_vertical="end", height=6)

Would render as:

|                                |
|                                |
|                                |
|   ╭──────────────╮   ╭─────╮   |
|   │ My Fancy App │   │ v90 │   |
|   ╰──────────────╯   ╰─────╯   |

Notice that on the horizontal axis, the items are evenly spaced. On the vertical axis, the items are rendered at end.

More Examples

Again, I represent the edge of the parent container of the Flex (which may be the edge of the terminal window) with |.

align_horizontal=space-between

Consider the case where we have two widgets, and we wish to align one at the left edge of the terminal, and one at the right edge:

|╭──────────────╮                                                     ╭─────╮|
|│ My Fancy App │                                                     │ v90 │|
|╰──────────────╯                                                     ╰─────╯|
|                                                                            |

I've tried to achieve this using Table and Columns, and can't work it out.

I tried this:

    left = Panel("My Fancy App", expand=False)
    right = Panel("v90", expand=False)
    grid = Table.grid(expand=True)
    grid.add_column()
    grid.add_column(justify="right")
    grid.add_row(left, right)
    rich_console.print(grid)

With Flex, I'd suggest the layout above be achieve with something like:

lhs = Panel("My Fancy App")
rhs = Panel("v90")
rich_console.print(
    Flex(lhs, rhs, align_children="space-between")
)

align_horizontal=space-evenly

The code:

lhs = Panel("My Fancy App")
rhs = Panel("v90")
rich_console.print(
    Flex(lhs, rhs, align_horizontal="space-evenly")
)

Would result in:

|     ╭──────────────╮     ╭─────╮     |
|     │ My Fancy App │     │ v90 │     |
|     ╰──────────────╯     ╰─────╯     |
|                                      |

align_horiztonal=center

The code:

lhs = Panel("My Fancy App")
rhs = Panel("v90")
rich_console.print(
    Flex(lhs, rhs, align_horizontal="center")
)

Would result in:

|        ╭──────────────╮╭─────╮        |
|        │ My Fancy App ││ v90 │        |
|        ╰──────────────╯╰─────╯        |
|                                       |

align_horizontal=end

To align widgets at the end of the main axis.

The code could look something like:

lhs = Panel("My Fancy App")
rhs = Panel("v90")
rich_console.print(
    Flex(lhs, rhs, align_horizontal="end")
)

Resulting in...

|                 ╭──────────────╮╭─────╮|
|                 │ My Fancy App ││ v90 │|
|                 ╰──────────────╯╰─────╯|
|                                        |

Closing thoughts

This isn't an exhaustive proposal, as it just touches on a portion of what is usually offered by a flex implementation. However, hopefully I've conveyed the ideas behind Flex and gave a taste of how I think it could work. I'd love to hear any thoughts.

Thanks!

[willmcgugan]

Hi Darren,

I've always taken inspiration from CSS/html when implementing Rich, so I can see how flex would be a good fit.

I think you can achieve most layouts with the current primitives. The only thing you were missing in your example is that the justify applies to text (if it was css it would probably be text-align). If your v90 panel had expand=True, you would see that the text is aligned to the right edge of the panel. To align a renderable, and not just the text contents, you can use Align.right:

from rich.align import Align
from rich.panel import Panel
from rich.table import Table
from rich.console import Console

rich_console = Console()

left = Panel("My Fancy App", expand=False)
right = Panel("v90", expand=False)
grid = Table.grid(expand=True)
grid.add_row(left, Align.right(right))
rich_console.print(grid)

However, I can't deny that the flex api is way more intuitive!

Flex would also benefit textual where I would like to render "documents" which will be suspiciously like web-pages. What would benefit me is if we did have a Flex class it could produce an intermediate data structure that contains a map of the x, y and width, height coordinates of each flex element within the document. I can use that to render partial updates.

Another possibility is CSS grid, which I'm less familiar with, but which could be very powerful for creating advanced layouts.

So yeah, I'm open to flex or grid. Did you have any thoughts re implementation? I'm quite busy at the moment with Textual, so I'm unlikely to attempt this any time soon.

[darrenburns]

Thanks for the feedback! I agree a grid system would also be really useful, perhaps a Bootstrap-style grid system might work well in Rich too? I'm not too sure how it would relate to the existing Columns or Table.grid() though.

GridRow(
  GridColumn(
    *renderables,
    ratio=1,
  ),
  GridColumn(
    *other_renderables,
    ratio=3,
  ),
)

I might try to put something together for review when I get time, but not sure if/when that would be.