UI.Constellation
luastra/uiUI.Constellation(input: Input): Node
Creates one Orbit navigation depth with exactly one semantic center and between one and sixty-four nodes or clusters. The host owns spatial placement and list fallback.
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.
When to use it
Use UI.Constellation for each root or nested content space in an Orbit. Keep inactive neighbours as behind or ahead only when they are needed for bounded transitions.
Shared parameter groups
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| id | lowercase path, required | Unique constellation ID. |
| layerState | active | behind | ahead? | Current transition and accessibility state. |
| depth | integer 0…32? | Semantic navigation depth. |
| children | one OrbitCenter + 1…64 OrbitNode or OrbitCluster | Complete content of this navigation depth. |
| margin | none | xs | sm | md | lg | xl | All-side outer spacing. Group: Layout and surfaces. |
| marginX / marginY | none | xs | sm | md | lg | xl | Axis-specific outer spacing. Group: Layout and surfaces. |
| marginTop / marginBottom / marginStart / marginEnd | none | xs | sm | md | lg | xl | Logical side-specific outer spacing. Group: Layout and surfaces. |
| className | safe string ≤ 256 bytes | Additional admitted class tokens. Group: Layout and surfaces. |
| label | string | Accessible name. Group: State and semantics. |
| hidden | boolean | Visibility state. Group: State and semantics. |
Children and layout
Complete content of this navigation depth.
Accessibility and keyboard
Only the active layer remains interactive and exposed to assistive technology; source order remains the list and reading order.
Common mistakes
- Rendering more than one center.
- Referencing a related node outside the same constellation.
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.Constellation {
id = "map/root",
layerState = "active",
UI.OrbitCenter { id = "map/root/center", title = "My app" },
UI.OrbitNode { id = "map/start", title = "Start", onTap = "start" },
}Continue with a complete recipe
This checked recipe uses UI.Constellation inside complete authored files with the required manifest, test, and run steps.
Open build a small Constellation Orbit recipe