UI.FocusSurface

UI.FocusSurface(input: Input): Node

Creates the full-detail dialog opened from an Orbit leaf while retaining deterministic focus restoration, host-owned transition geometry, bounded scrolling, and reduced-motion behavior.

Mental model

This is a declarative node: app.render describes it again from current state, while the host matches its stable id to the existing view.

Before you use it

Add luastra/ui to this module's dependencies in luastra.json, then import it with require("luastra/ui"). The project must declare the ui.render capability. app.render must return one UI.Screen root; place this node inside that tree rather than invoking it for a hidden side effect.

How it fits

The constructor validates its fields immediately and returns a UI.Node. After app.render returns, the host reconciles that node by stable id with the current semantic DOM-based interface. Current desktop and mobile hosts package the same web artifact; native adapters are used at capability boundaries.

Shared parameter groups

Parameters

Children and layout

FocusHeader followed by full leaf content.

Accessibility and keyboard

The host names the dialog from its visible heading, traps focus, supports Escape, and restores focus to the originating node.

Common mistakes

• Opening it outside navigation state.
• Removing the explicit return control and relying only on Escape.

Returns

Node — a validated declarative UI node that becomes part of the next host-neutral render tree.

What happens next

A validated declarative node appears after it is returned as part of the current render tree.

Failures and fixes

Invalid fields, duplicate IDs, unsupported child combinations, or a missing ui.render capability fail during check, render-tree validation, or host startup.

Availability

Experimental Constellation Orbit API in 0.5.0-alpha. Verify it against the selected SDK before depending on its shape.

Focused example

UI.FocusSurface {
    id = "map/focus",
    label = "Build details",
    open = focused,
    onDismiss = "close-focus",
    UI.FocusHeader {
        id = "map/focus/header",
        UI.Text { id = "map/focus/title", text = "Build", variant = "heading" },
        UI.Button { id = "map/focus/close", text = "Back", onTap = "close-focus" },
    },
}

Continue learning

Complete inventory