ux-tui
The TERMINAL RENDERER of the UX projection (EXPERIMENTAL x/ tier;
#787 W5): the second of two peers over cx-x/ux's semantic vocabulary, and
the reason R5's renderer-agnostic claim is testable rather than asserted.
It lowers a semantic tree to a terminal tree, paints that to lines at a
given width with measured table columns, wrapped text, box-drawn panels and
SGR tones from a token document validated exactly as the CSS one is, and
derives a document-order focus ring so a keyboard shell can move, edit and
submit. Deliberately unlike a browser — a fixed cell grid, no CSS, no DOM,
no out-of-band swap engine, no pointer — so anything the vocabulary
silently assumed about a browser fails here rather than passing unnoticed.
Painting is pure: reading keys and writing the tty belong to the shell,
over cx-x/term. content-of-tui reads the terminal tree back to the
common content normal form the web renderer also targets.
Experimental x/ tier — imported as cx-x/ux-tui. Bundled and gated in-tree like any other module, but EXEMPT from the frozen-surface stability promise (std-lib README, decision D3): a semver-breaking change is allowed here while the surface settles, and the frozen-surface canary never counts it. Pin behaviour you depend on with your own fixtures.
ux-tui:render
[$ux-tui:render] ($el::any $ctx::map $opts::map) -> string | [err …] — Paint one semantic tree as a terminal block, or refuse with one [err …] — running the SHARED semantic gate first, so a tree this renderer accepts and the web renderer rejects cannot exist.
ux-tui:lines-of
[$ux-tui:lines-of] ($t::any $opts::map) -> [sequence string] — Paint a terminal tree to its lines — what the shell writes into a region of the screen.
ux-tui:lower
[$ux-tui:lower] ($el::any $ctx::map $opts::map) -> any — Lower a semantic tree to the terminal tree — structure and content, no escape codes and no geometry.
ux-tui:value-of
[$ux-tui:value-of] ($opts::map $name::string $dflt::string) -> string — A control's edited value from the shell's overlay, or the tree's own.
ux-tui:panel-stops
[$ux-tui:panel-stops] ($t::any) -> [sequence element] — The ring positions that begin a new panel — the coarse movement scale. A flat ring puts every table row between the operator and the form below it, which is what makes a keyboard surface feel unnavigable however good each stop is.
ux-tui:focusables
[$ux-tui:focusables] ($t::any) -> [sequence element] — The focus ring in document order — derived from the tree rather than hand-listed, so it stays correct when the projection changes.
ux-tui:focus-at
[$ux-tui:focus-at] ($t::any $i::int) -> element | () — The focusable at a 1-based ring position, WRAPPING — a ring that clamps strands the last control.
ux-tui:form-inputs
[$ux-tui:form-inputs] ($t::any $fid::string) -> [sequence element] — Every input and hidden field under one form — what a submit collects, including the CSRF token, from the same tree the browser posts.
ux-tui:base-theme
[$ux-tui:base-theme] () -> element — The pack's default terminal theme: one token per visual decision, values as SGR parameter strings.
ux-tui:token-value-safe
[$ux-tui:token-value-safe] ($v::string) -> bool — Is a terminal token value safe — digits and semicolons only? An SGR parameter is tenant data reaching a control sequence, an injection surface exactly like a stylesheet.
ux-tui:theme-refusals
[$ux-tui:theme-refusals] ($theme::element) -> [sequence element] — Every unsafe token value in one terminal theme document.
ux-tui:editor-kind-of
[$ux-tui:editor-kind-of] ($kind::string) -> string — Map a declared CX kind to this renderer's editor. Deliberately NOT the web mapping — kind states the type, never the widget — though money and decimal stay text for the same carrier reason.
ux-tui:vis-len
[$ux-tui:vis-len] ($s::string) -> int — A string's VISIBLE width, with SGR sequences removed — every pad and border measures with this, because raw length counts escape bytes as columns and shears every table once colour is on.
ux-tui:pad-vis
[$ux-tui:pad-vis] ($s::string $w::int) -> string — Pad a possibly-styled string to a visible width.
ux-tui:wrap
[$ux-tui:wrap] ($s::string $w::int) -> [sequence string] — Word-wrap text to a width — a terminal has a hard right edge and no reflow engine, and the vocabulary never said how wide anything is.
ux-tui:inline
[$ux-tui:inline] ($t::any $opts::map) -> string — An element's content as one line — the terminal analogue of inline flow, for leaves and runs of badges and links.
ux-tui:content-of-tui
[$ux-tui:content-of-tui] ($t::any) -> element — Read the terminal tree back to the common content normal form — the TERMINAL side of the three-way equivalence assertion.
ux-tui:content-repr-tui
[$ux-tui:content-repr-tui] ($el::any $ctx::map) -> string — The canonical bytes the terminal rendering contributes to the equivalence assertion.
ux-tui:alt-screen-on
[$ux-tui:alt-screen-on] () -> string — Enter the alternate screen buffer and hide the cursor — a full-screen surface must not scroll the user's scrollback away.
ux-tui:alt-screen-off
[$ux-tui:alt-screen-off] () -> string — Restore the cursor and leave the alternate screen, putting the terminal back exactly as it was found.
ux-tui:clear-home
[$ux-tui:clear-home] () -> string — Clear the screen and home the cursor — the start of every repaint.
ux-tui:status-bar
[$ux-tui:status-bar] ($keys::any $w::int $opts::map) -> string — The footer keymap: bindings on screen, so nothing has to be memorized or documented elsewhere.
ux-tui:sgr
[$ux-tui:sgr] ($code::string) -> string — One SGR control sequence from its parameter string.
ux-tui:esc
[$ux-tui:esc] () -> string — The ESC byte — CX string literals cannot encode it, so it comes from bytes.
ux-tui:sgr-reset
[$ux-tui:sgr-reset] () -> string — The SGR reset sequence.
ux-tui:style
[$ux-tui:style] ($s::string $theme::any $token::string $color::bool) -> string — Wrap a string in one theme token's SGR, or leave it alone when colour is off.
ux-tui:join-lines
[$ux-tui:join-lines] ($ls::any) -> string — Join a sequence of rendered lines with newlines into one screen string — a pure, total reduction; the empty sequence yields the empty string.