ui/Layout

A convenient tool for laying-out content using Layout, Cell, Row, and Column.

Layout is a powerful and versatile tool used for arranging content on the screen. On a conceptual level, it mixes the best parts of HTML tables wtih the best parts of HTML framesets, both of which were largely abandoned for their drawbacks, ignoring their strengths. A Layout is simply a container for Cell, the only "legal" child. Conversely, Cell may only be used in a Layout. Cells in a Layout can either be positioned next to each other (horizontally) or above/below each other (vertically) in what we refer to as a Row or Column, respectively.

The Row and Column layout presets describe the direction of layout for their children. This can sometimes cause confusion. A Row of children naturally forms a layout whose children can have the appearance of columns. To keep things clear, think about the layout rather than the what the children themselves represent.

Layout is an implementation of flex-box, but with built-in rails, properties, and features to help avoid common problems with flex-box; things like content overflowing, sizing quirks, and positioning problems regarding content of unknown or undefined dimension.

The following scenarios are some common cases where Layout can truly help out. A quality of Cell you'll see below is that when a Cell has no defined size, it automatically sizes to fill any remaining space in the Layout. If there are multiple auto-sizing Cell components, they share the space, subdividing it equally among themselves. It's great to leverage this and only apply sizes to Cells which must have defined sizes. shrink is one of the ways you can impose size guidelines on a Cell. It automatically fits the size of the Cell to the size of its content.

A row of cells where the last one should always attach to the right side, regardless of the size of the main "content" cell:

┌───────┬─┐
│Main   │R│
└───────┴─┘

<Row>
	<Cell>Main Content</Cell>
	<Cell shrink>Right Side</Cell>
</Row>

A "two-column" layout with equal sized cells using Row:

┌────┬────┐
│L   │R   │
└────┴────┘

<Row style={{height: '100%'}}>
	<Cell>Left Column</Cell>
	<Cell>Right Column</Cell>
</Row>

Remember: The cells of the Row are the columns in our layout. It's likely that in a complex layout Column would be used inside the left and right cells to arrange the components, as in the example below.

A full-height sidebar with a header and body to the right:

┌──┬──────┐
│S │HEADER│
│  ├──────┤
│  │Body  │
│  │      │
└──┴──────┘

<Row style={{height: '100%'}}>
	<Cell size="20%">Sidebar</Cell>
	<Cell>
		<Column>
			<Cell size={90} component="header">
				<h1>HEADER</h1>
			</Cell>
			<Cell>
				<p>Body area</p>
			</Cell>
		</Column>
	</Cell>
</Row>

Note: Here, we've set the height of Row so it fills the height of the screen, allowing the Sidebar Cell and content Cell to stretch from the top to the bottom. We've also leveraged the component prop on the header cell, which tells Cell to render itself as a "header" HTML tag rather than its usual "div" tag.

The example below produces a layout like the following:

┌─┬─────┬─┐
│o│Item │o│
└─┴─────┴─┘

You'll notice the use of some special classes in the example: "debug layout". Adding these on any element in your DOM hierarchy will enable borders in Layout and Cell to help visualize what is happening in the layout. They automatically change color the deeper in the stack they go.