# Layout

The pad from chapter 6 works, but the layout could use some attention. The
sidebar, editor, and preview panes are functional but not well-proportioned,
and the spacing is inconsistent. In this chapter we will fix that by learning
Plushie's layout system.

We will cover the layout containers you use every day, how sizing works, and
how spacing and alignment give your UI structure. The full container catalog
is in the [Built-in Widgets reference](../reference/built-in-widgets.md) --
here we focus on the ones that matter most.

## Layout containers

Plushie provides several layout containers. These are the workhorses:

### column

Stacks children vertically, top to bottom. Accepts `spacing:` (gap between
children), `padding:` (space inside the container), `width:`, `height:`, and
`align_x:`.

```elixir
column spacing: 12, padding: 16 do
  text("one", "First")
  text("two", "Second")
  text("three", "Third")
end
```

### row

Stacks children horizontally, left to right. Same props as `column`, plus
`align_y:`. Also supports `wrap: true` to flow children to the next line
when they overflow.

```elixir
row spacing: 8 do
  button("a", "Left")
  button("b", "Right")
end
```

### container

A single-child wrapper. Use it for styling (background, border, shadow),
for scoping (gives children a named ID scope), or for alignment and padding.

```elixir
container "card", padding: 16, background: "#f5f5f5" do
  text("content", "Inside the card")
end
```

### scrollable

Adds scroll bars when content overflows. Direction can be `:vertical`
(default), `:horizontal`, or `:both`. Set a fixed height to constrain the
scrollable area.

```elixir
scrollable "list", height: 300, direction: :vertical do
  column spacing: 4 do
    for item <- items do
      text(item.id, item.name)
    end
  end
end
```

`scrollable` supports `auto_scroll: true` for chat-like behaviour where
new content scrolls into view automatically.

## Sizing: fill, shrink, and fixed

Every widget has `width:` and `height:` props. They accept four kinds of
values:

| Value | Behaviour |
|---|---|
| `:fill` | Take all available space |
| `:shrink` | Take only as much as the content needs |
| `{:fill_portion, n}` | Take a proportional share of available space |
| number | Exact pixel size |

Most widgets default to `:shrink`. Layout containers grow to fit their
children.

### fill vs shrink

In a `row`, a `:fill` child takes all remaining space after `:shrink`
children are measured:

```elixir
row width: :fill do
  text_input("search", model.query, width: :fill, placeholder: "Search...")
  button("go", "Go")
end
```

The button shrinks to fit its label. The text input fills the rest.

### fill_portion

When multiple children use `:fill`, they share space equally. Use
`{:fill_portion, n}` for proportional splits:

```elixir
row width: :fill do
  container "sidebar", width: {:fill_portion, 1} do
    text("nav", "Sidebar")
  end
  container "main", width: {:fill_portion, 3} do
    text("content", "Main content")
  end
end
```

The sidebar gets 1/4 of the width, the main area gets 3/4. The numbers are
relative. `{:fill_portion, 1}` and `{:fill_portion, 3}` is the same ratio
as `{:fill_portion, 2}` and `{:fill_portion, 6}`.

### Fixed size

A plain number means exact pixels:

```elixir
container "icon", width: 48, height: 48 do
  text("x", "X")
end
```

## Spacing and padding

**Spacing** is the gap between sibling children inside a container:

```elixir
column spacing: 12 do
  text("a", "First")    # 12px gap below
  text("b", "Second")   # 12px gap below
  text("c", "Third")    # no gap after last child
end
```

**Padding** is the space between a container's edges and its content.
It accepts several forms:

```elixir
# Uniform: 16px on all sides
column padding: 16 do ... end

# Vertical/horizontal: 8px top/bottom, 16px left/right
column padding: {8, 16} do ... end

# Per-side via do-block:
column do
  padding do
    top 16
    bottom 8
    left 12
    right 12
  end
  text("hello", "Hello")
end
```


## Alignment

`align_x:` and `align_y:` control how children are positioned within a
container:

| `align_x` values | `align_y` values |
|---|---|
| `:left` (default), `:center`, `:right` | `:top` (default), `:center`, `:bottom` |

```elixir
container width: :fill, height: 200, align_x: :center, align_y: :center do
  text("centered", "I am centred")
end
```

The shorthand `center: true` sets both axes at once:

```elixir
container width: :fill, height: :fill, center: true do
  text("centered", "Centred both ways")
end
```

## Other layout tools

These containers cover specialised needs. We will not use them in the pad
right now, but they are good to know about:

- **stack** - layers children on top of each other (z-axis). Useful for
  overlays, badges, and loading spinners.
- **grid** - CSS-like grid layout. Supports fixed column count (`columns: 3`)
  or fluid mode (`fluid: 200`) that auto-wraps.
- **pin** - positions a child at exact `(x, y)` pixel coordinates.
- **floating** - applies translate and scale transforms to a child.
- **responsive** - adapts layout based on available size.
- **space** - explicit empty space with configurable width and height.

See the [Built-in Widgets reference](../reference/built-in-widgets.md) for
full details on each.

## Applying it: the polished pad layout

With these layout tools, refine the pad into a clean three-pane layout:

```elixir
def view(model) do
  window "main", title: "Plushie Pad" do
    column width: :fill, height: :fill, spacing: 0 do
      # Main area: sidebar + editor + preview
      row width: :fill, height: :fill, spacing: 0 do
        file_list(model)

        text_editor "editor", model.source do
          width {:fill_portion, 1}
          height :fill
          highlight_syntax "ex"
          font :monospace
        end

        container "preview", width: {:fill_portion, 1}, height: :fill, padding: 12 do
          # ...preview content...
        end
      end

      # Toolbar: compact, horizontal
      row padding: {4, 8}, spacing: 8 do
        button("save", "Save")
        checkbox("auto-save", model.auto_save)
        text("auto-label", "Auto-save")
      end

      # Event log: fixed height at the bottom
      scrollable "log", height: 100 do
        column spacing: 2, padding: {2, 8} do
          for {entry, i} <- Enum.with_index(model.event_log) do
            text("log-#{i}", entry, size: 11, font: :monospace)
          end
        end
      end
    end
  end
end
```

Key changes: `spacing: 0` on the outer containers eliminates unwanted gaps.
The toolbar uses `{4, 8}` padding (vertical, horizontal) for a compact look.
The event log has a smaller fixed height and tighter text. Each section
manages its own internal spacing.

The update logic is unchanged from chapter 6. Only the view and helper
functions changed.

## Verify it

Test that the three-pane layout renders with the expected structure:

```elixir
test "three-pane layout with sidebar, editor, and preview" do
  assert_exists("#file-scroll")
  assert_exists("#editor")

  # Typing in the editor still works after layout changes
  type_text("#editor", ~s[text("test", "hello")])
  click("#save")
  assert_text("#preview/test", "hello")
end
```

This verifies the layout didn't break the editing flow. The editor,
save button, and preview pane all still work together.

## Try it

Write a layout experiment in your pad:

- Build a sidebar + content layout using `row` with a fixed-width `column`
  and a `:fill` container.
- Try different `{:fill_portion, n}` ratios. Give one pane `2` and another
  `1` to see the 2:1 split.
- Nest a `scrollable` inside a fixed-height container. Add enough items to
  trigger scrolling.
- Experiment with `align_x: :center` and `align_y: :bottom` on a container.
- Try `row` with `wrap: true` and enough buttons to overflow the width.

In the next chapter, we will style the pad with themes, colours, and
per-widget styling to make it look polished.

---

Next: [Styling](08-styling.md)
