/makepad-2.0-layout

name: makepad-2.0-layout
description: |
  CRITICAL: Use for Makepad 2.0 layout system. Triggers on:
  makepad layout, makepad width, makepad height, makepad flex, makepad flow,
  makepad padding, makepad margin, makepad spacing, makepad align, makepad sizing,
  Fill, Fit, Inset, Flow.Down, Flow.Right, ScrollXView, ScrollYView,
  布局, 对齐, 间距, 填充, 排版, 滚动视图, 尺寸, 宽度, 高度

Makepad 2.0 Layout System

Makepad uses a **layout turtle** system -- not CSS flexbox, not CSS grid. The turtle walks through children one by one, placing each widget according to two core concepts:

• **Walk** -- how a widget sizes itself (width, height, margin)
• **Layout** -- how a container arranges its children (flow, spacing, padding, align)

Every container widget (View, SolidView, RoundedView, ScrollYView, etc.) has both Walk properties (its own size) and Layout properties (how it lays out children).

---

Walk System (Widget Sizing)

Walk controls how an individual widget claims space inside its parent.

width / height

| Syntax | Meaning | |--------|---------| | `width: Fill` | Fill all remaining horizontal space (default) | | `width: Fit` | Shrink to fit content | | `width: 200` | Fixed 200 pixels | | `width: Fill{min: 100 max: 500}` | Fill with constraints | | `width: Fit{max: Abs(300)}` | Fit content, capped at 300px | | `height: Fill` | Fill all remaining vertical space (default) | | `height: Fit` | Shrink to fit content | | `height: 100` | Fixed 100 pixels |

use mod.prelude.widgets.*

// Fill: takes all available width
View{
    width: Fill height: Fit
    flow: Down
    Label{text: "I stretch to fill the width"}
}

// Fit: shrinks to content
View{
    width: Fit height: Fit
    padding: 10
    Label{text: "I am only as wide as this text"}
}

// Fixed: exact pixel size
View{
    width: 300 height: 200
    Label{text: "I am exactly 300x200 pixels"}
}

// Constrained Fill: fills but within bounds
View{
    width: Fill{min: 200 max: 600} height: Fit
    flow: Down padding: 16
    Label{text: "I fill available space but stay between 200-600px"}
}

CRITICAL: height: Fit on Containers

**This is the number one layout bug in Makepad.**

The default height is `Fill`. When your output renders inside a `Fit` container, `Fill` inside `Fit` creates a circular dependency and resolves to **0 pixels**. Your entire UI becomes invisible.

**Rule: ALWAYS set `height: Fit` on every View, SolidView, RoundedView, and similar container unless the parent has a fixed or Fill height.**

// CORRECT -- height: Fit makes the container visible
View{
    width: Fill height: Fit
    flow: Down padding: 10
    Label{text: "I am visible"}
}

// WRONG -- defaults to height: Fill, resolves to 0px, invisible
View{
    width: Fill
    flow: Down padding: 10
    Label{text: "I am invisible (0px tall)"}
}

**Exceptions where height: Fill is acceptable:** 1. Inside a fixed-height parent:

View{
    height: 400
    View{
        height: Fill
        Label{text: "I fill the 400px parent"}
    }
}

2. Inside a `height: Fill` chain that ultimately reaches a known size (e.g., Window body). 3. ScrollYView always uses `height: Fill` because it must fill its parent to scroll.

margin

Margin adds space around the outside of a widget.

// Uniform margin on all sides
Label{text: "Hello" margin: 10}

// Selective margin with Inset
Label{
    text: "Indented"
    margin: Inset{top: 5 bottom: 5 left: 20 right: 20}
}

// Zero margin (note the trailing dot for float literal)
Label{text: "Flush" margin: 0.}

---

Layout System (Child Arrangement)

Layout controls how a container positions its children.

flow (Direction)

| Syntax | Meaning | CSS Equivalent | |--------|---------|----------------| | `flow: Right` | Left-to-right, single line (default) | `flex-direction: row` | | `flow: Down` | Top-to-bottom, single column | `flex-direction: column` | | `flow: Overlay` | Stack children on top of each other | `position: absolute` stacking | | `flow: Flow.Right{wrap: true}` | Left-to-right with wrapping | `flex-wrap: wrap` | | `flow: Flow.Down{wrap: true}` | Top-to-bottom with wrapping | column wrap |

use mod.prelude.widgets.*

// Vertical stack (most common)
View{
    width: Fill height: Fit
    flow: Down spacing: 10
    Label{text: "First"}
    Label{text: "Second"}
    Label{text: "Third"}
}

// Horizontal row
View{
    width: Fill height: Fit
    flow: Right spacing: 10
    Label{text: "Left"}
    Label{text: "Center"}
    Label{text: "Right"}
}

// Overlay -- children stacked on top of each other
View{
    width: Fill height: 200
    flow: Overlay
    Image{width: Fill height: Fill fit: ImageFit.Biggest}
    View{
        width: Fill height: Fit
        align: Align{x: 0.5 y: 1.0}
        padding: 10
        Label{text: "Caption overlay" draw_text.color: #fff}
    }
}

// Wrapping flow -- like a tag cloud or grid of cards
View{
    width: Fill height: Fit
    flow: Flow.Right{wrap: true}
    spacing: 8
    padding: 10
    Label{text: "Tag 1" margin: 4}
    Label{text: "Tag 2" margin: 4}
    Label{text: "Tag 3" margin: 4}
    Label{text: "Tag 4" margin: 4}
}

spacing

Gap between children. A single number applies uniformly.

View{
    flow: Down spacing: 12
    Label{text: "12px gap below me"}
    Label{text: "12px gap above and below me"}
    Label{text: "12px gap above me"}
}

padding

Inner space between the container edge and its children.

// Uniform padding
View{
    width: Fill height: Fit
    padding: 20
    Label{text: "20px padding on all sides"}
}

// Selective padding with Inset
View{
    width: Fill height: Fit
    padding: Inset{top: 10 bottom: 10 left: 24 right: 24}
    Label{text: "Different padding per side"}
}

align (Child Alignment)

Alignment positions children within the remaining space of the container. Values range from 0.0 (start) to 1.0 (end) on each axis.

Alignment Reference Table

| Shorthand | Equivalent | Description | |-----------|