Component · Overlays

Dialog

Canonical modal surface: title, description, body, actions, close policy, focus trap via OverlayStack, initial focus, opener restoration, scrolling, loading, validation; recipes normal/compact/wide/fullscreen/destructive; safe Enter (no accidental submit from body).

Kind: widget
Input: interactive
Canvas: 120×40

Live preview

Ghostty· TermRock —dialog/messageloading poster…

Loading terminal poster…

○ loading posterNo input — rendered state only

Dialog · exact mounted Rust story

01 · Purpose

What it is for

Best fit: Overlays · overlay · widget

02 · Behavior

What the mounted story proves

01
Dialog
Representative 120×40 terminal state.
02
Passive paint
No keyboard or pointer action is claimed by this representative story.
03
Evidence stays explicit
6 covered · 8 partial · 4 missing axes.

03 · Implement

Install, then start from exact code

Install

cargo add termrock --git https://github.com/tailrocks/termrock.git --rev 5283c2acf9154d0cfcd37b1ffe821c00faf90ea2

Add TermRock once. Keep domain effects in the host application.

Minimal implementation

Exact Rust setup used by dialog/message.

Open to load code.

04 · Adapt

Variants and composition

Variants

Use the preview Variant menu when alternate registered stories exist. Each selection mounts a fresh configuration.

Composition

Overlays · overlay · widget

05 · Reference

API, tokens, accessibility

API

DialogOpen source ↗

Tokens

DesignSystemInspect exact story code for roles and capability projection.

Accessibility

Input contract mountedNo input claim in the representative story.

Contract

Evidence in progress6/23 axes covered

06 · Go deeper

Advanced guidance

Authored implementation guidance

Purpose. Frame a short message or choice as a modal layer: title, body, optional actions. TermRock places and paints; you decide open/close policy and effects.

Use ChoiceDialog when actions need stable IDs and keyboard traversal. place_dialog / OverlayStack integrate with Esc peel law.

When to use / when not

Use Dialog	Prefer
Confirm destructive action	—
Short system message	—
Multi-step forms	Form / FormWizard
Agent trust gates	PermissionPrompt
Fuzzy command jump	Command palette

Focus law

Concern	Owner
Overlay trap / Esc peel	OverlayStack
Surface focus (which layer)	Host / InteractionScene
Action cursor among buttons	`ChoiceDialogState::cursor` (host may project scene focus into it)
Tab between action ids when registered	Host scene only — not ChoiceDialog

Outcomes (`interaction::Outcome`)

Ignored
Changed — action cursor moved
Activated(Id)
Cancelled — Esc

Intents

default_choice_dialog_intent — Left/Right (j/k), Home/End, Enter, Esc. Tab is not mapped.

Non-color

Cursor: ActionFocused role, or ›label‹ / [label] with ascii / colorless
Danger variant: ! title prefix + danger border
Backdrop: terminal Reset (not hard black)

Responsive

Width	Layout
≥ 28	Horizontal action bar
< 28	Vertical stack of actions
height < 3	Title/border only

State ownership

TermRock	Consumer
Action cursor, hit regions, loading gate	Open policy, message copy, effects
Overlay place/open helpers	Scene registration of action ids (optional)

Ownership boundary

TermRock owns reusable terminal rendering and interaction state. The host owns domain data, policy, persistence, authorization, and side effects.

Evidence status

6 covered, 8 partial, and 4 missing contract axes. Missing evidence is not a behavior claim.

Choice Dialog

Modal choice prompt on the canonical Dialog engine — stable actions, loading gate, Esc dismiss / confirm-only policy via dialog_mut().

Dialog Scroll

DialogScroll is the exact public behavior owner for overlay terminal UI.