Documentation menu

Layout Engine

Express constraints, measurements, and child placement as derived attributes in the client runtime.

The layout engine gives an evaluated view description concrete sizes and positions before reconciliation. LayoutSystem represents each node's constraints, intrinsic size, resolved size, and position as runtime attributes, then connects them through computations appropriate to that node's layout kind.

Structure and Input Synchronization

A candidate tree supplies layout kinds, children, text content, alignments, and explicit geometry. Synchronization reuses compatible layout storage and reconfigures computations when relevant structure or policy changes.

Intrinsic updates use changed-value checks where appropriate so unchanged measurements do not unnecessarily invalidate downstream work.

Wrapper Configuration

Wrapper layout transforms the proposal on its way to the child and the measured result on its way back. Padding subtracts its insets before proposing space, then adds them back around the child's size. A frame instead combines explicit dimensions, min/max bounds, and parent constraints to establish a region in which alignment determines the child's position.

Decoration uses the content's result as the proposal for its decorative children. A background can therefore cover the resolved content bounds without contributing an independent intrinsic size that would change the measurement it is meant to decorate.

Stack Measurement

For a stack, the engine records child sizes and their accumulated origins in one shared measurement attribute. The stack's size and each child's position then read that result, avoiding a separate scan of the entire sibling list for every output.

Spacer allocation must avoid feeding its own result back into measurement. It therefore reads only the parent bounds and non-spacer child sizes, subtracts fixed extents and gaps, and divides the unused main-axis space among direct spacers. Including spacer size among those inputs would introduce a dependency cycle.

Grid Track Measurement

Grid layout similarly shares an aggregate measurement of row heights, column widths, and track origins. Size and position outputs read that aggregate instead of recording independent dependencies on every sibling. The implementation normalizes the requested column count to at least one before assigning cells.

Track size is content-derived. It is not an equal-fraction layout algorithm, and clamping the container's size does not automatically repartition every oversized child.

Text Reflow and Scroll Content

Text adds width-dependent shaping to this graph. Its measurement reads the effective available width and shaping configuration, and can reuse a result for the same current width. Measurement failures remain part of the result so invalid text layout cannot silently supply inconsistent geometry for publication.

Scroll layout loosens the selected content axes to positive infinity while keeping a finite viewport where one is offered. Its post-layout geometry derives clamped offsets and indicator bounds.

Publication Validation

Frames and insets require valid finite/nonnegative dimensions where specified. Maximum bounds can intentionally be infinite, but invalid min/max combinations fail layout evaluation.

A failed candidate must not replace accepted geometry. See reconciliation for the publication boundary and layout fundamentals for application-level rules.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/layout/mod.rs
  • crates/kit/src/layout/validation.rs
  • crates/kit/src/view/visual_modifiers.rs
  • crates/kit/src/text/field/reflow.rs