UI.OrbitSearch
luastra/uiUI.OrbitSearch(input: Input): Node
Creates a controlled local-constellation search input plus a live result summary. The application owns filtering and supplies both the current result count and total count.
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.OrbitSearch when the active constellation can become difficult to scan. Keep the query in Luau state, preserve stable node IDs, and hide non-matching nodes instead of creating a parallel result model.
Shared parameter groups
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| id | lowercase path, required | Unique search ID. |
| query | string ≤ 160 bytes? | Controlled local query. |
| resultCount | non-negative integer, required | Visible matching node count. |
| totalCount | integer ≥ resultCount, required | Total node count before filtering. |
| label | string? | Accessible input name. |
| placeholder | string? | Visible empty-query hint. |
| onInput | action string, required | Committed query action. |
| 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. |
| hidden | boolean | Visibility 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 generated result summary is a live status; Escape clears a non-empty query before it performs Orbit return navigation.
Common mistakes
- Filtering only the visual layer while leaving hidden nodes interactive.
- Putting the query into host-only state instead of Luau state.
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.OrbitSearch {
id = "map/search",
query = query,
resultCount = resultCount,
totalCount = #nodes,
onInput = "search",
}