UI.OrbitCluster
luastra/uiUI.OrbitCluster(input: Input): Node
Creates one semantic entry for an application-authored group and exposes its bounded item count. It participates in relationships, priority placement, semantic zoom, and list fallback as one button.
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.OrbitCluster when several nodes have a real domain grouping and a local destination constellation. Do not group items only because their current screen coordinates happen to be close.
Shared parameter groups
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| id | lowercase path, required | Unique cluster ID. |
| title | string 1…160 bytes, required | Stable group identity. |
| count | integer 1…9999, required | Authored group item count. |
| priority | integer 1…3? | Detail and placement importance. |
| ring | integer 1…3? | Optional authoritative ring hint. |
| relatedTo | component ID[] 1…8? | Neutral same-constellation relationships. |
| signalIcon | bounded icon name? | Host-rendered compact Signal icon. |
| status | string 1…80 bytes? | Human-readable state. |
| statusTone | neutral | active | success | warning | error? | Redundant visual state treatment. |
| onTap | action string, required | Opens the authored local constellation. |
| 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. |
| 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. |
| disabled | boolean | Disabled state. Group: State and semantics. |
| busy | boolean | aria-busy state. Group: State and semantics. |
Children and layout
This component does not accept arbitrary child nodes; named parameters provide its content.
Accessibility and keyboard
The group title and item count form one accessible button name; cluster membership and navigation remain application-authored.
Common mistakes
- Using a cluster as visual decoration without a semantic group.
- Supplying a count that does not match the authored destination.
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.OrbitCluster {
id = "map/examples",
title = "Examples",
count = 48,
signalIcon = "grid",
onTap = "open-examples",
}