Crate waterui_layout

Expand description

Layout building blocks for WaterUI.

This crate bridges the declarative View system with the imperative, backend-driven layout pass. It contains:

the low-level Layout trait and its geometry helpers,
reusable containers such as spacer(), padding::Padding, and stacks,
thin wrappers (for example scroll()) that signal backend-specific behaviour.

§Logical Pixels (Points)

All layout values use logical pixels (points/dp) - the same unit as design tools like Figma, Sketch, and Adobe XD. Native backends handle conversion to physical pixels based on screen density:

iOS/macOS: Uses points natively
Android: Converts dp → pixels via displayMetrics.density

This ensures spacing(8.0) or width(100.0) renders at the same physical size across all platforms, matching your design specifications exactly.

§Example

use waterui::prelude::*;

pub fn toolbar() -> impl View {
    hstack((
        text("WaterUI"),
        spacer(),
        vstack((text("Docs"), text("Blog"))),
    ))
    .spacing(8.0) // 8pt spacing - same as Figma/Sketch
}

For a broader tour see the crate README.

Modules§

absolute: Absolute positioning layout for WaterUI.
alignment_guide: Alignment-guide wrapper views.
aspect_ratio: Constrains a view to a width-to-height ratio.
background: Background layout for rendering content behind a view.
collection_transition: Opt-in animation for reactive-collection membership changes.
container: View wrapper that lets arbitrary Layout implementations participate in the WaterUI view tree.
divider: Divider layout primitive shared across WaterUI surfaces.
frame: Reactive frame constraints for overriding a child’s incoming proposal.
grid: A two-dimensional layout that arranges views in columns and rows.
overlay: Overlay helpers for layering content on top of a base view.
padding: Padding layouts that inset a child by fixed edge distances.
safe_area: Safe area handling for layout containers.
scroll: Scroll containers that defer behaviour to the active renderer backend.
spacer: Flexible layout gaps used by stacks and other containers.
stack: Stack-based layout primitives.

Structs§

Absolute: Container for absolutely positioned children.
AbsoluteLayout: Layout that fills parent and gives each child full bounds.
Affine2: 2D affine transform stored as a row-major 2x3 matrix.
Alignment: Combined two-dimensional alignment used by layout containers.
AlignmentKeyId: Stable identifier for a built-in alignment guide in the layout runtime.
AspectRatio: A view constrained to a width-to-height ratio.
AspectRatioLayout: Layout that sizes its single child to a fixed width-to-height ratio.
BackgroundLayout: Layout used by BackgroundView to render a background behind content.
BackgroundView: A view that renders a background behind the content.
CollectionTransition: Environment request to animate reactive-collection membership changes.
Divider: A thin line that separates content.
EdgeSet: Specifies which edges should ignore safe area insets.
Grid: A view that arranges content in rows and columns.
GridRow: A data-carrying struct that represents a single row in a Grid. It does not implement View itself; it is consumed by the Grid.
HorizontalAlignment: Horizontal alignment guide handle.
HorizontalAlignmentGuide: A wrapper view that overrides one horizontal alignment guide.
IgnoreSafeArea: Marker metadata indicating this view should ignore safe area insets.
LayoutPriority: How strongly a view holds on to space when its container runs short.
LazyContainer: A view wrapper that executes an arbitrary Layout implementation with reconstructable views, which can support lazy layouting.
MemoizedSubView: A SubView that remembers what each proposal measured.
Overlay: A view that layers overlay content on top of a base view without allowing the overlay to influence layout sizing.
OverlayLayout: Layout used by Overlay to keep the base child’s size authoritative while still allowing aligned overlay content.
PinConstraints: Edge-based constraints for absolute positioning.
PlacedSubview: A child view together with its placed frame inside a container.
Point: Absolute coordinate relative to a parent layout’s origin.
PositionedChild: A view with positioning information, for use in Absolute container.
PositionedLayout: Layout that positions a single child within received bounds.
ProposalSize: A size proposal from parent to child during layout negotiation.
Rect: Axis-aligned rectangle relative to its parent.
SafeAreaInsets: The window’s safe area, published by the platform backend.
ScrollController: Explicit programmatic control for a scrollable view.
ScrollView: A scrollable view that displays content larger than its frame.
Size: Two-dimensional size expressed in points.
Spacer: A flexible space that expands to push views apart.
UnitPoint: Normalized coordinates (0.0–1.0) for positioning and gradient endpoints.
Vec2: Two-dimensional displacement vector (e.g. velocity, gravity, wind, offset).
VerticalAlignment: Vertical alignment guide handle.
VerticalAlignmentGuide: A wrapper view that overrides one vertical alignment guide.
ViewDimensions: Measured dimensions together with explicit alignment guides.

Enums§

ContentMode: How a view fills a ratio-constrained box.
LayoutDirection: The logical horizontal direction used by layout containers.
PositionTarget: Target position for absolute positioning.
StretchAxis: Specifies which axis (or axes) a view wants to stretch to fill available space.

Constants§

MEMOIZED_PROPOSALS: How many distinct proposals one child’s memo retains.

Traits§

Layout: A layout algorithm for arranging child views.
PositionExt: Extension trait for absolute positioning of views.
SubView: A proxy for querying child view sizes during layout.

Functions§

absolute: Creates an Absolute container for positioning children.
aspect_ratio: Constrains content to ratio, shrinking to fit inside what is offered.
background: Convenience constructor for creating a BackgroundView.
collection_transition: Wraps content so every reactive collection within it animates membership changes with animation (see CollectionTransition).
grid: Creates a new grid with the specified number of columns and rows.
layout_direction: Resolves the reactive layout direction installed in an environment.
measure_layout: Measures a layout and resolves its explicit guides for the given children.
overlay: Convenience constructor for creating an Overlay with the default alignment.
row: Creates a new grid row containing the specified views.
scroll: Creates a vertical ScrollView with the given content.
scroll_both: Creates a ScrollView that can scroll in both directions.
scroll_horizontal: Creates a horizontal ScrollView with the given content.
spacer: Creates a flexible spacer with zero minimum length.
spacer_min: Creates a spacer with a specific minimum length.
with_memoized_children: Runs pass with every child wrapped in a MemoizedSubView, so repeated probes within that one layout pass measure each child at most once per distinct proposal.