LavaUI ↔ SwiftUI parity

LavaUI is deliberately SwiftUI-shaped (View, @ViewBuilder, @State, stacks, modifiers) but is not source-compatible. This document tracks what is still missing or only partially present, ordered so the next work is obvious.

It is an API gap list, not a bug list. Incorrect behaviour goes in issues.md. Product-specific needs live in their own gap docs. The broader framework assessment is lavaui-assessment.md.

Status legend

Guiding principles

1. Match the call site when cheap. .padding(.horizontal, 8) is worth looking like SwiftUI; a full PreferenceKey system is not free.
2. Keep Lava strengths. Yoga flex, @DrawState, dual overlays, Canvas gestures, Scene3D, client/compositor mode — do not delete these to chase source compatibility.
3. One layer at a time. Prefer finishing a small cluster (edge padding + frame completeness) over scattering half-done modifiers.
4. Document intentional divergence in api.md when we ship a different shape on purpose.

Tier 0 — Easy wins

Small surface area, Yoga/modifier machinery already exists, immediate payoff for every app. Start here.

0.1 Edge-aware padding — done (2026-08-08)

content.padding(8)                                              // all edges
content.padding(.horizontal, 12)
content.padding(.top, 4)
content.padding(EdgeInsets(top: 1, leading: 2, bottom: 3, trailing: 4))

ViewStyle / YogaBoxNode store EdgeInsets; Yoga gets per-edge YGNodeStyleSetPadding with LTR mapping (leading→left, trailing→right). Stack/button/overlay inits still take uniform Float and convert with .all(...). Padding after another modifier still forces an outer box.

0.2 View opacity

Proposed: .opacity(Float) -> … on View, stored on ViewStyle, applied at emit (multiply subtree alpha). Composes with transition alpha.

Cheap once emit has a place to multiply; no layout impact.

0.3 Offset (2D)

Proposed: .offset(x:y:) — paint + hit-test shift without affecting Yoga layout (SwiftUI semantics). Layout-affecting position can wait.

0.4 Disabled / hidden as modifiers

Tree-wide disable should block clicks on descendants. Hidden should remove from hit testing and ideally from layout (hidden that still occupies space vs a true collapse — pick SwiftUI’s “occupies space, not hit-testable, not drawn” unless we also want a collapse helper).

0.5 Lifecycle hooks

Appear/disappear fire from mount/unmount (and transition leave finish). onChange needs a retained previous value on the node or a small wrapper. High value for apps; moderate plumbing.

0.6 Fuller .frame

Done: alignment:. Alignment is a HorizontalAlignment × VerticalAlignment pair with the nine named corners as statics, and OverlayAnchor is now a spelling of it rather than a second copy of the same switch. Stating one wraps the content in a StyleBoxNode laid out as a row — justifyContent is the horizontal half, alignItems the vertical — so the frame keeps its stated size and the content sits inside at its natural one.

The default is nil, not .center as in SwiftUI, because this modifier carries two meanings that SwiftUI splits. Without an alignment the size lands on the view's own node, which is what every existing caller means by it: a VStack given a width is that width and lays its children across it. With one, it is SwiftUI's frame — a box, with the content placed in it. nil records "never asked", which is not the same answer as .center, and is what keeps existing layouts still.

Worth knowing: it took a calendar to surface this. Text paints its glyphs at its box's leading edge, .frame made the text's box the whole 34pt cell, and the day number sat 4pt left of the highlight drawn around it. There was nowhere for the number to be centred in.

Still proposed — max/ideal sizes:

func frame(
    width: Dimension? = nil, height: Dimension? = nil,
    minWidth: Float? = nil, maxWidth: Float? = nil,
    minHeight: Float? = nil, maxHeight: Float? = nil,
    alignment: Alignment? = nil
) -> …

Yoga already has min/max width/height.

0.7 Edge padding on stacks (optional follow-on)

Once EdgeInsets exists, consider:

HStack(padding: EdgeInsets.horizontal(8), …) { … }

or keep stack padding uniform. Modifier-only is enough for Tier 0.

Tier 1 — Everyday app surface

Needed by most non-trivial UIs once Tier 0 is done.

Layout

Controls & text

Interaction

Animation

Environment & wrappers

Presentation

Tier 2 — Structure & scale

Tier 3 — Platform & infrastructure

Tracked more fully in the assessment; listed here so parity work doesn’t forget them.

Already present (do not re-implement)

Use as the baseline when reading the tables above.

Core: View, @ViewBuilder (no bare for), EmptyView, ForEach, retained identity, Observation.

State: @State, Binding, @Bindable, @DrawState (Lava-only).

Layout: HStack, VStack, Spacer, ScrollView, LazyVStack, LazyVGrid, Dimension (auto / pt / pct), flex grow/shrink.

Controls: Text, Button, TextField, Toggle, Slider, Divider, Expand, Image, Canvas, EditorView, MarkdownView.

Modifiers: padding (uniform), background color, hoverBackground, cornerRadius, frame (partial), flexGrow/Shrink, blur, backdropBlur, clipped, theme, font, transition, onDrop, overlay (composed + presented), agentId.

Other: menus, FileDialog, Scene3D, client/compositor frame path, agent server.

Intentional divergences (not gaps)

Suggested implementation order

Concrete sequence for the next few PRs:

After that, pick by product pressure (navigation, gestures, a11y, lazy horizontal).

When closing a gap

1. Implement against the proposed API in this doc (or update the proposal first if reality disagrees).
2. Add a short example to api.md.
3. Mark the row here done with a one-line note (and date if useful).
4. Prefer a unit or layout test where the behaviour is structural (padding edges, frame max, ZStack order).

Changelog

docs/swiftui-parity.md