# `tecs.ui` Retained interfaces made from Tecs entities, with layout computed by Taffy. `Style` and `ChildOf` describe a tree. `Root` supplies its available size; `Paint(true)` stretches a drawing leaf to its computed box. Shapes, sprites and text draw through the ordinary graphics pipeline. Keep containers at unit scale and put stretched paint on leaves. Write component fields through `world:getMut` so layout and rendering observe the edit. ```nupp tecs.ui.install(world, {width = 800, height = 450}) const root = world:spawn(tecs.ui.Root(), tecs.ui.Style({padding = 16, gap = 12})) world:spawn(tecs.ecs.ChildOf(root), tecs.ui.Style({width = 120, height = 40}), tecs.ui.Paint(true), tecs.gfx.Tint(0.3, 0.6, 1, 1), tecs.gfx.Renderable2D, tecs.ui.Interaction()) ``` Layout retains its native tree, measures intrinsic text and images without foreign callbacks, and returns changed boxes. Scrolling clips descendants; interaction supports pointer capture, dragging, focus scopes and activation. Screen roots follow `resize`, and `plugin(app)` connects window size and input. ## Types ### `Dimension` _type_ ```nupp type Dimension = number | string ``` A logical length: pixels, a percent string, or "auto". ### `Edges` _type_ ```nupp type Edges = { left: Dimension?, right: Dimension?, top: Dimension?, bottom: Dimension? } ``` Per-edge logical lengths; missing edges are automatic. ### `Event` _record_ ```nupp record Event kind: string target: integer currentTarget: integer x: number y: number button: integer pointerId: string pointerType: string deltaX: number deltaY: number source: string consumed: boolean end ``` `@derive(nupp.events.Event)` `@event(name="tecs.ui.Event")` A semantic interaction delivered first to its target, then its ancestors. Observed at an entity address, or at address zero after bubbling. #### Fields ##### `kind` ```nupp kind: string ``` Read-only. Identifies the interaction. ##### `target` ```nupp target: integer ``` Read-only. Identifies the original target. ##### `currentTarget` ```nupp currentTarget: integer ``` Read-only. Identifies the current bubbling recipient. ##### `x` ```nupp x: number ``` Read-only. Reports the pointer position in target pixels. ##### `y` ```nupp y: number ``` Read-only. Reports the pointer position in target pixels. ##### `button` ```nupp button: integer ``` Read-only. Reports the pointer button. ##### `pointerId` ```nupp pointerId: string ``` Read-only. Identifies the pointer, including a touch contact. ##### `pointerType` ```nupp pointerType: string ``` Read-only. Identifies mouse, touch, or none. ##### `deltaX` ```nupp deltaX: number ``` Read-only. Reports horizontal movement or wheel delta. ##### `deltaY` ```nupp deltaY: number ``` Read-only. Reports vertical movement or wheel delta. ##### `source` ```nupp source: string ``` Read-only. Identifies pointer, keyboard, controller, or programmatic input. ##### `consumed` ```nupp consumed: boolean ``` Caller-writable. Stops bubbling when true. ### `Interaction` _type_ ```nupp type Interaction = InteractionValue ``` The value stored by Interaction. ### `InteractionOptions` _type_ ```nupp type InteractionOptions = { enabled: (boolean)?, focusable: (boolean)?, tabIndex: (integer)?, order: (integer)?, draggable: (boolean)? } ``` Constructor options for Interaction. ### `InteractionState` _type_ ```nupp type InteractionState = InteractionStateValue ``` The value stored by InteractionState. ### `InteractionStateOptions` _type_ ```nupp type InteractionStateOptions = { hovered: (boolean)?, pressed: (boolean)?, focused: (boolean)?, dragging: (boolean)? } ``` Constructor options for InteractionState. ### `Intrinsic` _type_ ```nupp type Intrinsic = IntrinsicValue ``` The value stored by Intrinsic. ### `IntrinsicOptions` _type_ ```nupp type IntrinsicOptions = { source: ("custom" | "text" | "image")?, width: (number)?, height: (number)?, minWidth: (number)?, scale: (number)?, wrap: (boolean)? } ``` Constructor options for Intrinsic. ### `Layout` _type_ ```nupp type Layout = LayoutValue ``` The value stored by Layout. ### `LayoutOptions` _type_ ```nupp type LayoutOptions = { x: (number)?, y: (number)?, width: (number)?, height: (number)?, contentWidth: (number)?, contentHeight: (number)? } ``` Constructor options for Layout. ### `Options` _type_ ```nupp type Options = { width: number?, height: number?, pixelDensity: number?, firstClip: integer?, lastClip: integer?, layer: integer?, wheelStep: number?, dragThreshold: number?, input: Input?, inputLayer: Layer? } ``` Settings for layout, clipping and interaction. ### `Paint` _type_ ```nupp type Paint = PaintValue ``` The value stored by Paint. ### `Root` _type_ ```nupp type Root = RootValue ``` The value stored by Root. ### `RootOptions` _type_ ```nupp type RootOptions = { space: ("screen" | "world")?, width: (number)?, height: (number)?, pixelDensity: (number)?, sizing: ("auto" | "manual" | "camera")? } ``` Constructor options for Root. ### `Scroll` _type_ ```nupp type Scroll = ScrollValue ``` The value stored by Scroll. ### `Scrollbar` _type_ ```nupp type Scrollbar = ScrollbarValue ``` The value stored by Scrollbar. ### `ScrollbarOptions` _type_ ```nupp type ScrollbarOptions = { axis: ("horizontal" | "vertical")?, thickness: (number)?, inset: (number)?, minLength: (number)? } ``` Constructor options for Scrollbar. ### `ScrollOptions` _type_ ```nupp type ScrollOptions = { x: (number)?, y: (number)?, contentWidth: (number)?, contentHeight: (number)? } ``` Constructor options for Scroll. ### `Style` _type_ ```nupp type Style = StyleValue ``` The value stored by Style. ### `StyleOptions` _type_ ```nupp type StyleOptions = { display: ("flex" | "none" | "grid" | "block")?, position: ("relative" | "absolute")?, flexDirection: ("row" | "rowReverse" | "column" | "columnReverse")?, flexWrap: ("nowrap" | "wrap")?, justifyContent: ("start" | "center" | "end" | "spaceBetween" | "spaceAround" | "spaceEvenly")?, alignItems: ("stretch" | "center" | "end" | "baseline" | "start")?, alignContent: ("stretch" | "center" | "end" | "spaceBetween" | "spaceAround" | "spaceEvenly" | "start")?, flexGrow: number?, flexShrink: number?, flexBasis: Dimension?, width: Dimension?, height: Dimension?, minWidth: Dimension?, minHeight: Dimension?, maxWidth: Dimension?, maxHeight: Dimension?, margin: (Dimension | Edges)?, padding: (Dimension | Edges)?, border: (Dimension | Edges)?, gap: Dimension?, rowGap: Dimension?, inset: (Dimension | Edges)?, order: integer? } ``` Taffy layout properties. Omitted values use Taffy's flex defaults. ## Functions ### `blur` _function_ ```nupp function blur(exclusive world: World): boolean ``` Clears focus and reports whether an entity was focused. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive world` | `World` | the installed world | #### Returns | Type | Description | | --- | --- | | `boolean` | whether focus changed | ### `focus` _function_ ```nupp function focus(exclusive world: World, entity: integer): boolean ``` Focuses an enabled, focusable entity in the active scope. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive world` | `World` | the installed world | | `entity` | `integer` | the requested entity | #### Returns | Type | Description | | --- | --- | | `boolean` | whether focus moved | ### `focused` _function_ ```nupp function focused(borrows world: World): integer ``` Returns the focused entity, or zero. #### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows world` | `World` | the installed world | #### Returns | Type | Description | | --- | --- | | `integer` | the focused entity | ### `install` _function_ ```nupp function install(exclusive world: World, options: Options?): nil ``` Installs retained layout and observes platform events; repeated installation is harmless. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive world` | `World` | the world to install into | | `options` | `Options?` | viewport, clip allocation and input settings | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `layouts` _function_ ```nupp function layouts(borrows world: World): integer ``` Reports native synchronization calls, useful for checking idle layout work. #### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows world` | `World` | the installed world | #### Returns | Type | Description | | --- | --- | | `integer` | the synchronization count | ### `plugin` _function_ ```nupp function plugin(exclusive app: Application, options: Options?): nil ``` Installs UI using the application's viewport and input. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive app` | `Application` | the application whose world hosts the UI | | `options` | `Options?` | optional layout and interaction settings | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `popFocusScope` _function_ ```nupp function popFocusScope(exclusive world: World, entity: integer?): boolean ``` Pops the top scope and restores its previous focus when still valid. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive world` | `World` | the installed world | | `entity` | `integer?` | the expected scope, or nil | #### Returns | Type | Description | | --- | --- | | `boolean` | whether a scope was popped | ### `pushFocusScope` _function_ ```nupp function pushFocusScope(exclusive world: World, entity: integer): boolean ``` Restricts focus and hit testing to a subtree until popped. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive world` | `World` | the installed world | | `entity` | `integer` | an entity carrying FocusScope | #### Returns | Type | Description | | --- | --- | | `boolean` | whether the scope was pushed | ### `resize` _function_ ```nupp function resize(exclusive world: World, width: number, height: number, density: number?): nil ``` Updates the logical viewport used by automatic screen roots. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive world` | `World` | the installed world | | `width` | `number` | the logical viewport width | | `height` | `number` | the logical viewport height | | `density` | `number?` | the target pixels per logical point | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `reveal` _function_ ```nupp function reveal(exclusive world: World, entity: integer, align: string?): boolean ``` Reveals a descendant by scrolling every ancestor viewport. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive world` | `World` | the installed world | | `entity` | `integer` | the descendant to reveal | | `align` | `string?` | nearest, start, center, or end; omitted means nearest | #### Returns | Type | Description | | --- | --- | | `boolean` | whether an ancestor scrolled | ### `update` _function_ ```nupp function update(exclusive world: World): nil ``` Runs layout, geometry and pending interaction for the current world state. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive world` | `World` | the installed world | #### Returns | Type | Description | | --- | --- | | `nil` | | ## Values ### `FocusScope` _variable_ ```nupp const FocusScope ``` Marks a subtree that can own a modal focus scope. ### `Interaction` _variable_ ```nupp const Interaction: ComponentDefinition ``` Constructs Interaction with its default values for omitted fields. ### `InteractionState` _variable_ ```nupp const InteractionState: ComponentDefinition ``` Constructs InteractionState with its default values for omitted fields. ### `Intrinsic` _variable_ ```nupp const Intrinsic: ComponentDefinition ``` Constructs Intrinsic with its default values for omitted fields. ### `Layout` _variable_ ```nupp const Layout: ComponentDefinition ``` Constructs Layout with its default values for omitted fields. ### `Node` _variable_ ```nupp const Node ``` Marks a retained UI node. The persisted name is UiNode. ### `Paint` _variable_ ```nupp const Paint: ComponentDefinition ``` Constructs Paint with its default values for omitted fields. ### `Root` _variable_ ```nupp const Root: ComponentDefinition ``` Constructs Root with its default values for omitted fields. ### `Scroll` _variable_ ```nupp const Scroll: ComponentDefinition ``` Constructs Scroll with its default values for omitted fields. ### `Scrollbar` _variable_ ```nupp const Scrollbar: ComponentDefinition ``` Constructs Scrollbar with its default values for omitted fields. ### `Style` _variable_ ```nupp const Style: ComponentDefinition ``` Constructs Style with its default values for omitted fields.