OverlayRootWidget

Defined in: src/dom/overlay.ts:134

The full-screen root that every layer (dialog / sticky panel) is portalled into. It is added to Screen.overlays, so the app lays it out to the full screen and paints it after the normal widget tree.

The root paints nothing of its own by default (it is transparent — the layer below stays visible); only its children draw. A dim modal optionally blanks the backdrop, and passThrough (sticky panels) lets clicks that miss the panel fall through to the layer below.

It also owns its single panel child’s position (via the app’s custom-layout hook): a modal panel is centered, a sticky panel is placed next to its anchor (flipping above/below to fit) or at the screen offsets given by its style — and in every case the result is clamped to stay fully on-screen.

Extends

Widget

Constructors

Constructor

new OverlayRootWidget(): OverlayRootWidget

Defined in: src/dom/overlay.ts:176

Returns

OverlayRootWidget

Overrides

Widget.constructor

Properties

anchor

anchor: Widget | null = null

Defined in: src/dom/overlay.ts:164

Sticky panels: the widget the panel attaches to (e.g. the chat input). The panel is laid edge-to-edge with this widget — directly above or below it — instead of at fixed screen offsets. Its live region is read each layout, so the panel tracks the anchor as the layout changes.

anchorRect

anchorRect: Region | null = null

Defined in: src/dom/overlay.ts:174

Rect-anchored placement (context menus / popovers): the panel is placed beside this screen rect on the best side per placement — flipping across top/bottom/left/right to find one that fits, else best-fit, always clamped on-screen (see placeByBestSide). A cursor is a 0-size rect. Takes precedence over anchor.

centered

centered: boolean = false

Defined in: src/dom/overlay.ts:138

Center the (single) panel child within the screen.

children

children: DOMNode[] = []

Defined in: src/dom/dom.ts:16

Child nodes in document order.

Inherited from

Widget.children

classes

classes: Set<string>

Defined in: src/dom/dom.ts:10

Advisory class names (no CSS cascade today).

Inherited from

Widget.classes

defaultStyle

defaultStyle: WidgetStyles = {}

Defined in: src/dom/widget.ts:201

The widget’s built-in look, overridden by style. Set by subclasses.

Inherited from

Widget.defaultStyle

dim

dim: boolean = false

Defined in: src/dom/overlay.ts:146

Blank the backdrop behind a modal panel so the layer below reads as inert.

dimAlpha

dimAlpha: number = 1

Defined in: src/dom/overlay.ts:152

Scrim opacity multiplier in [0,1], applied on top of the base scrim alpha. Lets a dim modal fade its backdrop in (1 = full scrim). Default 1 so a dim overlay with no animation looks exactly as before.

disabled

disabled: boolean = false

Defined in: src/dom/widget.ts:315

When true, this widget (and its descendants) are inert: not focusable, they ignore key/mouse input, and interactive controls render in a muted style. Set via the disabled prop. Checked through isDisabled so disabling a container disables everything inside it.

Inherited from

Widget.disabled

focusable

focusable: boolean = false

Defined in: src/dom/widget.ts:291

Whether this widget can take keyboard focus.

Inherited from

Widget.focusable

focused

focused: boolean = false

Defined in: src/dom/widget.ts:306

True while this widget holds keyboard focus.

Inherited from

Widget.focused

focusOnClick

focusOnClick: boolean = false

Defined in: src/dom/widget.ts:298

When a click lands on this (non-focusable) container — its padding, border, or any non-focusable child — move focus to its first focusable descendant. Lets a Form/Panel/Box act like one click target that hands focus to its first field. Off by default.

Inherited from

Widget.focusOnClick

hoverInterest

hoverInterest: boolean = false

Defined in: src/dom/widget.ts:197

Opt-in hint: this widget visually or behaviorally cares about passive hover motion.

Inherited from

Widget.hoverInterest

id

id: string = ""

Defined in: src/dom/dom.ts:8

Optional stable identifier (from the id prop).

Inherited from

Widget.id

label?

optional label?: string

Defined in: src/dom/widget.ts:344

Structural/accessible label; also the tab title inside TabContainer.

Inherited from

Widget.label

measuredHeight

measuredHeight: number = 0

Defined in: src/dom/widget.ts:287

Intrinsic height from the last measure.

Inherited from

Widget.measuredHeight

measuredWidth

measuredWidth: number = 0

Defined in: src/dom/widget.ts:285

Intrinsic width from the last measure, before layout distributes space.

Inherited from

Widget.measuredWidth

modal: boolean = false

Defined in: src/dom/overlay.ts:136

Blocks key/mouse fallthrough and traps focus to this layer.

onClick?

optional onClick?: (ev) => void

Defined in: src/dom/widget.ts:356

Pointer click handler.

Parameters

ev

any

Returns

void

Inherited from

Widget.onClick

onDragEnd?

optional onDragEnd?: (x, y, moved) => void

Defined in: src/dom/widget.ts:380

Drag released; moved is false for a tap with no movement.

Parameters

x

number

y

number

moved

boolean

Returns

void

Inherited from

Widget.onDragEnd

onDragMove?

optional onDragMove?: (x, y) => void

Defined in: src/dom/widget.ts:378

Pointer moved while dragging from this widget.

Parameters

x

number

y

number

Returns

void

Inherited from

Widget.onDragMove

onDragStart?

optional onDragStart?: (x, y) => void

Defined in: src/dom/widget.ts:376

Drag began on this widget (pointer pressed).

Parameters

x

number

y

number

Returns

void

Inherited from

Widget.onDragStart

onKey?

optional onKey?: (ev) => void

Defined in: src/dom/widget.ts:365

Key handler invoked while focused (the base handleKey forwards here).

Parameters

ev

any

Returns

void

Inherited from

Widget.onKey

onMouseDown?

optional onMouseDown?: (ev) => void

Defined in: src/dom/widget.ts:363

Pointer pressed on this widget, for any button — fired on press before the left-button focus/onClick path. The event carries button and x/y, so this is how to react to a right-click (e.g. open a context menu). Set ev.handled = true to suppress the default focus/click.

Parameters

ev

MouseEvent

Returns

void

Inherited from

Widget.onMouseDown

onMouseEnter?

optional onMouseEnter?: (ev) => void

Defined in: src/dom/widget.ts:369

Called when the pointer enters this widget’s region.

Parameters

ev

any

Returns

void

Inherited from

Widget.onMouseEnter

onMouseLeave?

optional onMouseLeave?: (ev) => void

Defined in: src/dom/widget.ts:371

Called when the pointer leaves this widget’s region.

Parameters

ev

any

Returns

void

Inherited from

Widget.onMouseLeave

onScroll?

optional onScroll?: (ev) => void

Defined in: src/dom/widget.ts:367

Wheel/scroll handler (the base handleScroll forwards here).

Parameters

ev

MouseEvent

Returns

void

Inherited from

Widget.onScroll

parent

parent: DOMNode | null = null

Defined in: src/dom/dom.ts:14

Parent node, or null when detached / at the root.

Inherited from

Widget.parent

passThrough

passThrough: boolean = false

Defined in: src/dom/overlay.ts:157

Sticky panels: clicks that miss the panel are not captured here, so the app’s hit-test continues to the layer below (keeping the chatbox clickable).

placement

placement: OverlayPlacement = "auto"

Defined in: src/dom/overlay.ts:166

Preferred side of the anchor (default auto: pick whichever fits).

pointerTransparent

pointerTransparent: boolean = false

Defined in: src/dom/widget.ts:304

This widget (and its subtree) never captures the pointer — hit-testing falls through to whatever is beneath. For decorative full-screen overlays like the DevTools highlight. CSS pointer-events: none. Off by default.

Inherited from

Widget.pointerTransparent

positionFixed

positionFixed: boolean = false

Defined in: src/dom/widget.ts:335

When true, an absolutely-positioned child is pinned to its parent’s viewport and is NOT shifted by the parent’s scroll offset (CSS position: fixed semantics). Used by overlay chrome like the copy button so it stays in the top-right corner instead of scrolling away with the content.

Inherited from

Widget.positionFixed

prevRegion

prevRegion: Region = Region.EMPTY

Defined in: src/dom/widget.ts:283

The region as of the last laid-out frame, for geometry-stability detection: a queueRepaintWidget may scope a frame to one widget only when a fresh layout leaves every region equal to its prevRegion (nothing moved). Updated by the App after each layout pass.

Inherited from

Widget.prevRegion

region

region: Region = Region.EMPTY

Defined in: src/dom/widget.ts:276

This widget’s rectangle in terminal cells, assigned by the layout engine.

Inherited from

Widget.region

scrollOffset

scrollOffset: Offset = Offset.ORIGIN

Defined in: src/dom/widget.ts:289

Scroll position of this widget’s content (see Scrollable).

Inherited from

Widget.scrollOffset

selectable

selectable: boolean = true

Defined in: src/dom/widget.ts:328

Whether this widget’s selectable content participates in read-only text selection. Default true; set false on chrome leaves (e.g. Markdown list bullets / horizontal rules) so they register no content runs and are skipped.

Inherited from

Widget.selectable

selectionContainer

selectionContainer: boolean = false

Defined in: src/dom/widget.ts:322

When true, a read-only text selection started on any descendant is anchored to this widget’s region instead of the leaf, so a drag can span the composed children (e.g. selecting across the paragraphs/code blocks a Markdown widget renders into separate leaves). See widgets/readonly-selection.

Inherited from

Widget.selectionContainer

selectionRaw

selectionRaw: string | null = null

Defined in: src/dom/widget.ts:342

Original source text for this subtree (e.g. the raw markdown of the block a Markdown widget rendered it from). When a read-only selection fully covers the subtree’s content, copy emits this verbatim instead of the rendered text, so copied markdown round-trips its formatting.

Inherited from

Widget.selectionRaw

shadow

shadow: boolean = true

Defined in: src/dom/overlay.ts:144

Cast a soft drop shadow under the panel. On by default for dialogs/menus/ popovers; turn off for lightweight panels (e.g. a one-line tooltip) where the fixed-size shadow would dwarf the panel.

style

style: WidgetStyles = {}

Defined in: src/dom/widget.ts:199

Author-set inline styles; override the widget’s defaultStyle key-by-key.

Inherited from

Widget.style

tagName

tagName: string = ""

Defined in: src/dom/dom.ts:12

Host element tag, lowercased (e.g. “ztui-button”).

Inherited from

Widget.tagName

visible

visible: boolean = true

Defined in: src/dom/widget.ts:308

Whether this widget renders and participates in layout.

Inherited from

Widget.visible

Accessors

app

Get Signature

get app(): WidgetApp | null

Defined in: src/dom/widget.ts:267

The App that owns this widget, found by walking the parent chain to the tree root (the App node sets screen.parent = this). Returns null when the widget is detached (e.g. mid-construction, before it’s mounted).

Prefer this over the App.instance singleton for anything that must act on this widget’s app — style resolution, render scheduling — so multiple live apps (tests, the web backend) don’t resolve each other’s trees.

Returns

WidgetApp | null

Inherited from

Widget.app

borderSize

Get Signature

get borderSize(): Spacing

Defined in: src/dom/widget.ts:538

Border thickness as a Spacing — 1 per side that has a border, else zero.

Returns

Spacing

Inherited from

Widget.borderSize

computedStyle

Get Signature

get computedStyle(): WidgetStyles

Defined in: src/dom/widget.ts:207

Fully resolved styles for this frame ($tokens, hover/focus, defaults folded in). Read this in render, not style.

Returns

WidgetStyles

Set Signature

set computedStyle(val): void

Defined in: src/dom/widget.ts:211

Set by the engine each frame after resolving styles; you rarely set this yourself.

Parameters

val

WidgetStyles

Returns

void

Inherited from

RichTextWidget.computedStyle

cursorShape

Get Signature

get cursorShape(): "default" | "move" | "pointer" | "text" | "vertical-text" | "wait" | "progress" | "help" | "crosshair" | "cell" | "grab" | "grabbing" | "alias" | "copy" | "no-drop" | "not-allowed" | "zoom-in" | "zoom-out" | "n-resize" | "e-resize" | "s-resize" | "w-resize" | "ne-resize" | "nw-resize" | "se-resize" | "sw-resize" | "ew-resize" | "ns-resize" | "nesw-resize" | "nwse-resize" | null

Defined in: src/dom/widget.ts:233

The mouse-pointer shape shown over this widget, or null (default arrow). An explicit cursor style wins (resolved style first, so a :hover rule applies); otherwise the role-based defaultCursor is used. A disabled interactive widget always reports "not-allowed".

Returns

Inherited from

Widget.cursorShape

margin

Get Signature

get margin(): Spacing

Defined in: src/dom/widget.ts:485

This widget’s margin as a normalized Spacing.

Returns

Spacing

Inherited from

Widget.margin

padding

Get Signature

get padding(): Spacing

Defined in: src/dom/widget.ts:496

This widget’s padding as a normalized Spacing.

Returns

Spacing

Inherited from

Widget.padding

theme

Get Signature

get theme(): string | undefined

Defined in: src/dom/widget.ts:347

Theme name applied to this subtree; descendants resolve $tokens against it.

Returns

string | undefined

Set Signature

set theme(val): void

Defined in: src/dom/widget.ts:351

Apply a theme name to this subtree (descendants resolve $tokens against it).

Parameters

val

string | undefined

Returns

void

Inherited from

Widget.theme

Methods

animate()

animate(key, target, opts?): number

Defined in: src/dom/widget.ts:606

Drive a named scalar tween toward target, returning the value to show this frame. Call it from render: while the tween is still moving it books the next animation frame on this widget, so the value advances on its own without any external clock or state. This is the framework-agnostic counterpart to React’s useAnimatedValue — the engine lives on the widget, so every binding gets smooth motion for the same call.

A non-positive duration (or opts omitted with a default of 0 from the caller) snaps immediately, so animation can be turned off by passing duration: 0.

Parameters

key

string

target

number

opts?

TweenOptions

Returns

number

Inherited from

Widget.animate

animateColor()

animateColor(key, target, opts?): string

Defined in: src/dom/widget.ts:628

Colour counterpart to animate: tweens a named CSS colour toward target, returning the rgb(...) string to paint this frame and booking the next frame while in flight.

Parameters

key

string

target

string

opts?

TweenOptions

Returns

string

Inherited from

Widget.animateColor

appendChild()

appendChild(child): void

Defined in: src/dom/dom.ts:23

Append child, detaching it from any previous parent.

Parameters

child

DOMNode

Returns

void

Inherited from

Widget.appendChild

cursorShapeAt()

cursorShapeAt(_x, _y): "default" | "move" | "pointer" | "text" | "vertical-text" | "wait" | "progress" | "help" | "crosshair" | "cell" | "grab" | "grabbing" | "alias" | "copy" | "no-drop" | "not-allowed" | "zoom-in" | "zoom-out" | "n-resize" | "e-resize" | "s-resize" | "w-resize" | "ne-resize" | "nw-resize" | "se-resize" | "sw-resize" | "ew-resize" | "ns-resize" | "nesw-resize" | "nwse-resize" | null

Defined in: src/dom/widget.ts:249

The pointer shape at a specific cell (absolute screen coordinates), letting a widget vary the cursor across its own area — e.g. a list returns its pointer over rows but the default arrow over its scrollbar gutter. The base ignores position and returns cursorShape; override for sub-region control. Returning null defers to the ancestor / default arrow.

Parameters

_x

number

_y

number

Returns

Inherited from

Widget.cursorShapeAt

describe()

describe(): string

Defined in: src/dom/dom.ts:59

Human/LLM-readable identity for logs and diagnostics, e.g. button#submit.primary @ (2,1 10x1). Includes the laid-out region when one is present (widgets), and the text preview for text nodes.

Returns

string

Inherited from

Widget.describe

findResolvedBackground()

findResolvedBackground(): string

Defined in: src/dom/widget.ts:645

This widget’s effective background, walking up to ancestors when unset — used to composite translucent fills.

Returns

string

Inherited from

Widget.findResolvedBackground

getAccessibleNode()

getAccessibleNode(): AccessibleNode | null

Defined in: src/dom/widget.ts:685

A semantic snapshot of this widget for accessibility / non-visual output (see Screen.toAccessibleText). Returns null to be skipped — the default for pure layout containers that carry no inline text — so the accessible tree shows meaningful nodes (controls, labels, headings) without the structural scaffolding around them.

The base infers a reasonable node from the tag, inline text, focus/disabled state, and a structurally-read checked/value/label. Interactive widgets that know more (a slider’s range, a select’s options) should override to add value/state, calling super.getAccessibleNode() for the common fields.

Returns

AccessibleNode | null

Inherited from

Widget.getAccessibleNode

getClientRect()

getClientRect(): Region

Defined in: src/dom/widget.ts:548

The region inside the margin (the widget’s visible box, border included).

Returns

Region

Inherited from

Widget.getClientRect

getContentRect()

getContentRect(): Region

Defined in: src/dom/widget.ts:559

The drawable region inside margin + border + padding — paint custom content here.

Returns

Region

Inherited from

Widget.getContentRect

getTextContent()

getTextContent(): string

Defined in: src/dom/widget.ts:663

Concatenates the text of all direct TextNode children.

This is the canonical way widgets read their inline JSX text content. Subclasses may override to add behavior (e.g. trimming, or falling back to a label field), typically by post-processing super.getTextContent().

Returns

string

Inherited from

Widget.getTextContent

handleKey()

handleKey(ev): void

Defined in: src/dom/widget.ts:430

Handle a key event while this widget is focused. Override to implement keyboard interaction; mark ev.handled = true for keys you consume so they don’t fall through to global hotkeys. The base forwards to onKey. Requires focusable to be true to receive focus.

Parameters

ev

KeyEvent

Returns

void

Inherited from

Widget.handleKey

handleMouse()

handleMouse(ev): void

Defined in: src/dom/widget.ts:456

Handle a mouse event hit-tested to this widget (press/release/drag/move). Override for click/drag interaction; call super.handleMouse(ev) to keep the built-in drag-source lifecycle (onDragStart/onDragMove/onDragEnd). Set ev.handled = true to consume the event.

Parameters

ev

MouseEvent

Returns

void

Inherited from

Widget.handleMouse

handleScroll()

handleScroll(ev): void

Defined in: src/dom/widget.ts:417

Handle a wheel/scroll event. Override to scroll your own content; set ev.handled = true to stop it bubbling. The base forwards to onScroll.

Parameters

ev

MouseEvent

Returns

void

Inherited from

Widget.handleScroll

hasCursorStyle()

hasCursorStyle(): boolean

Defined in: src/dom/widget.ts:254

Whether the pointer takes on any shape over this widget (style or role).

Returns

boolean

Inherited from

Widget.hasCursorStyle

insertBefore()

insertBefore(child, before): void

Defined in: src/dom/dom.ts:41

Insert child before the before sibling (appends if before isn’t found).

Parameters

child

DOMNode

before

DOMNode

Returns

void

Inherited from

Widget.insertBefore

isDisabled()

isDisabled(): boolean

Defined in: src/dom/widget.ts:575

True when this widget or any ancestor is disabled, so a disabled container (e.g. a <Form disabled>) propagates to every control inside it.

Returns

boolean

Inherited from

Widget.isDisabled

layoutChildren()

layoutChildren(): boolean

Defined in: src/dom/overlay.ts:193

Custom-layout hook (invoked by the app) that positions the single panel child. Returns true to take over layout for this node (its subtree is still laid out afterwards).

Returns

boolean

matchesSelector()

matchesSelector(selector): boolean

Defined in: src/dom/dom.ts:87

Match a compound selector against this node — tags, IDs, and classes (e.g. tag#id.a.b).

Parameters

selector

string

Returns

boolean

Inherited from

Widget.matchesSelector

measure()

measure(maxW, maxH): void

Defined in: src/dom/widget.ts:982

Compute this widget’s intrinsic size into measuredWidth / measuredHeight, given the space the parent offers (maxW/maxH). Runs bottom-up (children first). Override point for content-sized custom widgets (e.g. measure your text); call super.measure(maxW, maxH) first if you also have children. Clamp to the offered space so you never overflow.

Parameters

maxW

number

maxH

number

Returns

void

Inherited from

Widget.measure

onMount()

onMount(): void

Defined in: src/dom/widget.ts:970

Called once when the widget enters the live tree. Override to start timers, subscribe to stores, or kick off async loads; pair cleanup in onUnmount.

Returns

void

Inherited from

Widget.onMount

onUnmount()

onUnmount(): void

Defined in: src/dom/widget.ts:973

Called once when the widget leaves the tree. Override to release whatever onMount acquired (timers, subscriptions) so nothing leaks.

Returns

void

Inherited from

Widget.onUnmount

removeChild()

removeChild(child): void

Defined in: src/dom/dom.ts:32

Remove child if it’s a child of this node.

Parameters

child

DOMNode

Returns

void

Inherited from

Widget.removeChild

render()

render(buffer): void

Defined in: src/dom/overlay.ts:267

Paint this widget into the cell buffer. The base draws the background, border, and children. Custom-widget override point: call super.render(buffer) to keep background/border, then paint your content within getContentRect using buffer.setCell(...). Stay inside your region — the parent clips children to its content box by default. Keep render pure and fast: it runs every frame and must not mutate the tree.

Parameters

buffer

ScreenBuffer

Returns

void

Overrides

Widget.render

renderChildren()

renderChildren(buffer): void

Defined in: src/dom/widget.ts:912

Paint child widgets (z-index ordered, clipped to the content box). The base render already calls this; override only for unusual child handling (e.g. a custom scroll transform). Most custom widgets don’t need to.

Parameters

buffer

ScreenBuffer

Returns

void

Inherited from

Widget.renderChildren

walk()

walk(callback): void

Defined in: src/dom/dom.ts:74

Depth-first visit of this node and its descendants, in z-index order.

Parameters

callback

(node) => void

Returns

void

Inherited from

Widget.walk

wantsTab()

wantsTab(_ev): boolean

Defined in: src/dom/widget.ts:446

Return true to claim a Tab/Shift+Tab press before it triggers focus traversal. The app consults the focused widget; when it returns true the key is dispatched to handleKey (to consume it) instead of moving focus. Default false, so Tab navigates as usual — override only for the states where Tab does in-widget work (e.g. accepting an open completion or inline suggestion), and return false again once there’s nothing to accept so the next Tab moves on.

Parameters

_ev

KeyEvent

Returns

boolean

Inherited from

Widget.wantsTab