UI.Layer
luastra/uiUI.Layer(input: Input): Node
Places all children in the same coordinate space instead of adding their sizes sequentially. The first child establishes the layer bounds; later children are overlaid and aligned within those bounds.
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.Layer for text over artwork, badges, card faces, and other overlapping compositions. Put the size-defining background first and wrap overlay content in a full-size Column or Row when it needs predictable alignment.
Shared parameter groups
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| id | lowercase path, required | Unique ID. |
| children | UI.Node[] | The first child defines the bounds; later children overlay the same area. |
| gap | none | xs | sm | md | lg | xl | Space between children. Group: Layout and surfaces. |
| padding | none | xs | sm | md | lg | xl | responsive | All-side inner spacing; responsive is supported only by padding. Group: Layout and surfaces. |
| margin | none | xs | sm | md | lg | xl | All-side outer spacing. Group: Layout and surfaces. |
| paddingX / paddingY | none | xs | sm | md | lg | xl | Axis-specific inner spacing. Group: Layout and surfaces. |
| paddingTop / paddingBottom / paddingStart / paddingEnd | none | xs | sm | md | lg | xl | Logical side-specific inner 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. |
| surface | plain | card | elevated | accent | Background, border, and elevation. Group: Layout and surfaces. |
| width | full | content | wide | Available width, 720 px maximum, or 1180 px maximum. Group: Layout and surfaces. |
| align | start | center | end | stretch | between | Cross-axis alignment. Group: Layout and surfaces. |
| justify | start | center | end | between | Main-axis alignment. Group: Layout and surfaces. |
| flow | wrap | nowrap | Flex wrapping. Group: Layout and surfaces. |
| responsive | boolean | Narrow-screen adaptation. Group: Layout and surfaces. |
| className | safe string ≤ 256 bytes | Additional admitted class tokens. Group: Layout and surfaces. |
| tone | muted | error | success | Semantic text tone. Group: State and semantics. |
| appearance | primary | secondary | danger | ghost | Action appearance. Group: State and semantics. |
| variant | body | subheading | heading | title | Body text or h3, h2, and h1 heading semantics. Group: State and semantics. |
| role | alert | group | status | Supported ARIA role. Group: State and semantics. |
| label | string | Accessible name. Group: State and semantics. |
| hidden | boolean | Visibility state. Group: State and semantics. |
| disabled | boolean | Disabled state. Group: State and semantics. |
| busy | boolean | aria-busy state. Group: State and semantics. |
| required | boolean | Required input state. Group: State and semantics. |
| errorId | component id | Associates a visible role=alert. Group: State and semantics. |
| textColor | token | #RRGGBB | Local or inherited foreground. Group: Text and local colors. |
| backgroundColor | token | #RRGGBB | Component-box background. Group: Text and local colors. |
| Color tokens | accent | danger | muted | surface | success | text | transparent | warning | Current Screen theme colors. Group: Text and local colors. |
| motion | { [property]: Tween | Sequence } | Opacity, rotation, scale, and translation channels. Group: Events and motion. |
Children and layout
The first child defines the bounds; later children overlay the same area.
Accessibility and keyboard
A stable id, logical render-tree order, and visible labels preserve predictable keyboard and screen-reader navigation.
Common mistakes
- Leaving the first child unsized while expecting a stable shared frame.
- Expecting padding on one overlay child to constrain every sibling.
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
Source API in 0.5.0-alpha; the public installer targets 0.5.0-alpha. Verify host-specific behavior against the selected SDK.
Focused example
UI.Layer {
id = "welcome/layer",
width = 280,
height = 380,
UI.Shape { id = "welcome/background", shape = "roundedRectangle", width = 280, height = 380, fill = "surface" },
UI.Column { id = "welcome/content", width = "full", align = "center", justify = "center",
UI.Text { id = "welcome/title", width = "full", textAlign = "center", text = "Welcome" },
},
}