Terminal-relative dimensions
Giving a negative width or height the meaning "terminal size minus that many cells", re-resolved on every resize, since OpenTUI percentages resolve against the parent.
- #opentui
- #patches
- #layout
A rule that runs the width of the screen except for a two-cell gutter, or a
pane that is the terminal's height less a status line. Both are ordinary
layouts, and OpenTUI has no vocabulary for them. width accepts
number | "auto" | "<n>%", and a percentage resolves against the parent,
not the screen.
What is left is arithmetic at the call site. Read useTerminalDimensions(),
subtract, pass the number, re-render on resize, and do it again in the next
component that needs the same thing.
This patch gives a negative number a meaning instead:
Negative numbers were unused. Upstream's validateOptions throws
Invalid width for Renderable <id>: -4 on them, so no existing layout can
depend on what they used to do.
Two seams, because a dimension arrives two ways
A width reaches a renderable through two code paths that share nothing, and both need handling.
Construction
Renderable's constructor callsvalidateOptions(id, options)itself, which throws on a negative beforesetupYogaPropertiesruns. Thewidthsetter is never involved.validateOptionsis module-private, so nothing reachable from the prototype can get in front of it. The only seam is rewritingoptionsbeforesuper(), which means re-registering the React catalogue as subclasses.Updates
React's reconciler applies a changed prop as a plain assignment (
instance.width = value), so the patch wraps thewidthandheightaccessors onRenderable.prototypetoo. That path does no validation at all. Before this patch a negative reached yoga as undefined behaviour.
Wrapping Renderable.prototype.setupYogaProperties was the first attempt. It
is the method that pushes the value into yoga, and the throw beats it by about
five lines.
Resolved again on every resize
A size resolved once at construction is stale after the first SIGWINCH, and
re-resolving it is the point of the feature. The patch keeps the raw negative
alongside the renderable:
A plain Map rather than a WeakMap, because the resize sweep has to iterate
it. track drops an entry on the renderable's destroyed event, so an
unmounted page does not keep its whole subtree alive. Setting a non-negative
value on either axis drops that axis, and a renderable with neither axis left
leaves the map entirely.
The sweep writes through the original setters it captured before patching.
Going through the patched ones would re-enter track and, on the way, clear the
tracking it depends on:
CliRenderer updates its own width and height before it emits resize, so
ctx is already current by the time the sweep reads it. wireResize
subscribes once per context, on the first tracked renderable.
Clamped at zero
resolve clamps, so a terminal narrower than the requested inset yields an
empty element rather than a negative one, which would hit the same upstream
Invalid width throw from the other direction. A laid-out renderable then
reports Math.max(layout.width, 1), so reading .width back gives 1 rather
than 0.
The module
Installing it
Both halves patch shared state, so the call belongs before the first renderable exists:
What it does not cover
The construction seam is the React catalogue, so a renderable built by hand still throws on a negative constructor option:
The accessor seam covers it afterwards, which means box.width = -4 works on a
hand-built renderable. A test for this patch therefore has to mount real JSX
through createRoot rather than construct renderables directly. At a 40-cell
terminal, <box width={-4}> lays out at 36, and the same box reports 76 after
a resize to 80 columns.
Still required
Checked against @opentui/core 0.6.6, where the module runs unchanged.
validateOptions still rejects a negative constructor option and is still
module-private, the width/height setters on Renderable.prototype still
validate nothing, and the React reconciler still applies a changed dimension
as a plain assignment. Mounted at a 40-cell terminal, <box width={-4}> lays
out at 36; after a resize to 80 columns the same box reports 76; and assigning
box.width = -10 afterwards gives 70.
What did change is where a resolved dimension ends up: 0.6.0 hands it to the native scene rather than pushing it into yoga directly. The patch is untouched by that because it never reaches below the public setters.
Related entries
- Making drag-selection opt-in. The other catalogue patch, and the first use of the subclass seam.
- Clipping box borders. Patches a prototype method instead, where the catalogue would be the wrong level. Resolved upstream in 0.6.0.
Files in this entry
Saved beside the document, and served as-is.
Related entries
Clipping box borders
OpenTUI's native box draw ignored the scissor stack, so a bordered box painted its border over everything around its scroll container. Fixed upstream in 0.6.0; kept for the detour it describes.
Making drag-selection opt-in
OpenTUI's text renderables are selectable by default, so a click-to-navigate UI starts a drag-selection instead. Flipping the default without disabling selection.
Reading the host terminal's colours
Subscribing to the terminal's own palette from React, including the DEC mode OpenTUI never enables and the cache the poll fallback has to clear.