tuile 0.9.0 → 0.11.0

data/book/07-components.md

@@ -56,14 +56,36 @@ decision.
 ## Editing text
 
 When you need input back from the user, the two editable components share
-a base — {Tuile::Component::TextInput} — and differ only in shape.
+a base — {Tuile::Component::AbstractStringField} — and differ only in shape.
 
 {Tuile::Component::TextField} is a single line with a real hardware caret.
-It does not scroll; a keystroke that would push the text past the field's
-width is simply rejected, so the field always shows its whole contents.
-Because it owns the hardware cursor while focused, it's the component that
-triggers the cursor-ownership rule from chapter 5 — printable keys flow
-straight to it and sibling shortcuts stay muted while you type.
+Its width bounds what you can *see*, not what it can hold: the text scrolls
+horizontally, moving by the minimum needed to keep the caret in view. If you
+want an actual limit, set `max_text_length` — a cap in characters, after
+which typing quietly does nothing. Because it consumes every printable key
+while focused (including the ones it ignores at the cap), it's also what
+keeps a scope-wide key binding from firing while you type: as chapter 5
+explains, an ancestor only hears the keys its descendants declined.
+
+That cap counts *characters*, and the distinction matters more than it
+looks. A field position is either an index into the text or a column on the
+terminal, and the two coincide only while every glyph is one column wide —
+a fullwidth CJK character is two columns, a combining mark zero. So `caret`
+and `max_text_length` speak indices, while `rect`, `left_column` and a mouse
+click speak columns, and the field converts between them rather than
+assuming they're the same number. You don't need to think about this to use
+a TextField; you do the moment you write a component that paints text.
+
+There's a third unit hiding in there, and it's the one your *user* thinks
+in: the glyph they see. A single visible character can be several characters
+of storage — an `e` with a combining accent, a flag, an emoji family — and
+editing a field one storage character at a time is how you get a Backspace
+that strips the accent and leaves a bare `e`. So while `caret` counts
+characters, it may only ever sit *between* glyphs, and the editing keys work
+in glyphs too: one arrow press moves over one, one Backspace deletes one,
+however many characters that turns out to be. Assign a caret into the middle
+of a glyph and the field quietly moves it to that glyph's far edge — where
+it was already being drawn anyway.
 
 {Tuile::Component::TextArea} is the multi-line counterpart: a word-wrapping
 editor that scrolls vertically to keep the caret's line visible, with
@@ -71,6 +93,29 @@ Enter inserting a newline as in any text editor. Like everything else,
 it's sized by its parent — it does not grow to fit its content; text that
 overflows the rect is reached by scrolling.
 
+{Tuile::Component::PasswordField} is a text field that paints a mask —
+one `*` per character — instead of its text. Everything else is the text
+field's, unchanged: you edit it, click into it, and scroll it exactly the
+same way, and `value` hands back the plaintext whenever you ask. Setting
+`revealed = true` shows the real text; there's no in-field reveal button,
+because a terminal row has nowhere to put one, so apps wire that to a
+"show password" checkbox or a key of their own.
+
+Two of its details are worth knowing, because both come straight from the
+index-versus-column distinction above. The mask is one *single-column*
+glyph per character, which is why the default is a plain `*` rather than a
+prettier `•`: a bullet is one of those characters whose width depends on
+how the terminal is configured, and a mask that's occasionally two columns
+wide would put the caret in the wrong place. (You can still set
+`mask_char` yourself if you know your terminal.) And because the mask
+replaces each character with exactly one column, a masked CJK passphrase
+takes *fewer* columns than the plaintext would — which is fine, and the
+field's caret, scrolling and click handling all measure the mask rather
+than the hidden text. The one thing it deliberately does *not* do is
+protect the plaintext in memory: it's an ordinary Ruby string, and
+anything stronger is a job for a type the whole application cooperates
+with.
+
 Both inherit the same event hooks from the base, and this is where the
 design pays off: you customize an input by assigning callbacks, not by
 subclassing. `on_change` fires whenever the text changes; `on_escape`
@@ -92,6 +137,86 @@ left `nil`, let those keys *fall through* to the parent — that's how Enter
 in a search field can trigger the surrounding window's action while the
 field still handles ordinary typing.
 
+## The value seam
+
+Every input component — a text field today, a combo box or a date field
+tomorrow — answers the same handful of questions, so Tuile gives them a
+shared vocabulary: the {Tuile::Component::HasValue} mixin. Read or set
+`value`, ask `empty?`, `clear` it, and subscribe to `on_value_change`.
+Write code against that seam and it doesn't care which kind of input each
+field is.
+
+The idea worth internalizing is that **a component's `value` is of its own
+natural type, not a string**. A text field's value *is* its text (a
+`String` — `value` and `text` are two names for the one buffer, `text`
+reading better while you're editing prose). But a combo box's value is the
+*object you picked*, not the text shown for it — pick a `User` and you get
+the `User` back, even when two users render to the same name. That typing
+is free in Ruby: a "value" is just whatever you stored, there's no generic
+to declare, so Tuile leans into it rather than making everything a string
+you map back by hand.
+
+A typed value can relate to the text on screen in two different ways, and
+the input components show both. A combo box's value is kept *quite apart*
+from the text — you type a query, but the value is the object you pick. An
+{Tuile::Component::IntegerField}'s value is instead *derived from* the
+text: it holds an `Integer` (or `nil`), parsed from the buffer on demand.
+You may type only digits and at most one leading `-`; anything else is
+quietly refused without so much as nudging the caret, and Up/Down step the
+number by one (an empty field counting as zero). Read `value` and you
+get an `Integer`, or `nil` when the buffer is blank or only half a number
+(a lone `-`). It reports changes as you type, but only when the number
+*itself* changes — padding `7` out to `07` moves the text without moving
+the value, and stays silent.
+
+```ruby
+qty = Component::IntegerField.new
+qty.on_value_change = ->(n) { recompute(n) }  # n is an Integer, or nil
+qty.value = 3
+```
+
+{Tuile::Component::FloatField} is the same field one type over — it also
+accepts a single decimal point, and its value is a `Float`. That naming is
+a small rule worth knowing, because it tells you what you're getting: a
+typed field is named after the Ruby class of its value, so `IntegerField`
+hands back an `Integer` and `FloatField` a `Float` — a binary double, which
+makes it exactly the wrong field for money. It parses generously while you
+type: a buffer of `1.` already reads as `1.0`, so reaching for the decimal
+point doesn't blink the value to `nil` and back in the listener you wired.
+
+Money gets {Tuile::Component::BigDecimalField}, the same field once more with
+an exact decimal inside — type `0.1` and it is `0.1`, not the `0.1000…0055`
+a binary double stores. It is strict about how that exactness is preserved:
+assigning a `Float` raises rather than quietly converting, because by the time
+`19.99` reaches the setter it is already not `19.99`. This is the one
+component with a dependency Tuile itself doesn't carry — `bigdecimal` has
+been a *bundled* gem since Ruby 3.4, so an app that uses this field names it
+in its own `Gemfile`, and an app that doesn't never loads it.
+
+The combo box and the two numeric fields are built the same way, and it's
+worth seeing why: each *wraps* a text field rather than *being* one. A
+subclass would inherit the text field's `String`-typed value and wear it
+on its face right next to the real typed one — two conflicting answers to
+"what's your value?". Composing sidesteps that: the wrapper holds a text
+field privately, does its own filtering and parsing, and exposes only the
+value that makes sense for it. (This is the "configure a generic component
+to make a domain one" idea from the architecture the whole library is
+built on.)
+
+The password field is the same rule read the other way. Its value *is* its
+text — same type, same vocabulary — so there's no second seam to collide
+with, and it simply *is* a text field, subclassed to paint differently.
+That's the test when you build your own input: if what you hand back
+differs in type from what the user types, wrap a field; if it's the same
+thing shown another way, extend one.
+
+Turning a field's value into a domain model — parsing, validation, the
+box-holds-a-`String` ⟷ bean-holds-an-`Integer` conversion — is
+deliberately *not* the field's job; it belongs to a forms/binder layer
+that will one day sit above these components. So the seam is kept thin on
+purpose: `on_value_change` carries just the new value, and there's no
+read-only or required flag yet. Room left for that layer to grow into.
+
 ## Choosing from a set
 
 {Tuile::Component::List} is the workhorse: a scrollable column of
@@ -126,11 +251,335 @@ list.cursor = Component::List::Cursor.new
 list.on_item_chosen = ->(index, line) { open(entries[index]) }
 ```
 
+When the set is long and the user roughly knows what they want, a plain
+list makes them scroll for it. {Tuile::Component::ComboBox} is the answer:
+a text field with a dropdown that filters as you type. Hand it `items` (of
+any type) and, when their `to_s` isn't what you want shown, an
+`item_label` strategy to render each one; type to narrow, arrow to move,
+Enter or click to accept. It's the value seam doing real work — its
+`value` is the selected *item*, the object and not its label, so a combo
+over `User`s hands back a `User`. The field's text is merely a transient
+query: it reverts to the selection's label when you dismiss the dropdown,
+and only a real commit fires `on_value_change`. The dropdown itself is a
+borderless popup tinted apart from the content beneath it (chapter 6's
+background inheritance again), floating below the field or flipping above
+when it's near the bottom of the screen.
+
+```ruby
+combo = Component::ComboBox.new
+combo.items = User.all
+combo.item_label = ->(u) { u.full_name }
+combo.on_value_change = ->(u) { show(u) }
+```
+
+When the choice is simply yes-or-no, {Tuile::Component::Checkbox} is a
+single row — `[x] Enable syslog forwarding` — that Space or a left-click
+flips. Its `value` is the value seam again, at its simplest: always `true`
+or `false`, never `nil`. Unchecked is the *empty* value, so a fresh
+checkbox reports `empty?` and `clear` unchecks it. Because `value` reads a
+little colorlessly in application code, the same state answers to
+`checked?`, `checked=` and `toggle` — four names, one piece of state, and
+one write path, so your `on_value_change` listener fires exactly once
+however you flip it.
+
+```ruby
+cb = Component::Checkbox.new("Enable syslog forwarding", value: true)
+cb.on_value_change = ->(on) { config.syslog = on }
+cb.toggle       # unchecks it, firing the listener with false
+```
+
+Two of its choices are worth understanding, because they're really
+statements about how Tuile widgets behave in general. The first: **Enter
+toggles it, just as Space does.** Space is the native gesture for flipping
+a checkbox, and for a while Enter was deliberately left alone — a checkbox
+has no action to confirm. What settled it is the checkbox group further
+down this chapter: a checkable row inside a list flips on Enter, because
+Enter is how a list chooses the row under its cursor. Had the standalone
+widget stayed silent, the same `[ ] Verbose` would have responded to Enter
+in a group and ignored it in a form, which is a distinction the person at
+the keyboard has no way to see.
+
+The consequence is worth stating plainly, because it's the general rule
+hiding behind the specific choice: a focused checkbox *consumes* Enter, so
+a form's submit button on an ancestor won't see it. That's not a
+regression from some guarantee — the framework never kept Enter clear, and
+chapter 5's table shows why it can't: a text area claims Enter for a
+newline, a button claims it to activate itself. Whether Enter reaches your
+form always depends on the widget that has focus.
+
+The second is about *where the widget actually is*. A form column will
+happily hand a checkbox forty columns for a caption that needs twenty-two,
+and the extra eighteen are blank. Both the focus highlight and the click
+target stop at the end of the caption rather than filling the row — the
+painted glyph is the affordance, so a click that visibly lands on nothing
+must not toggle anything, and a full-width highlight band would read as a
+selected *row*, which is the wrong signal for one field among ten.
+(Clicking the blank tail still moves *focus* there; it's the field's row,
+after all.) {Tuile::Component::Button} follows the identical rule, which is
+why both expose that painted region as `extent`.
+
+The glyphs are plain ASCII — `[x] ` and `[ ] `, three columns and a space
+— rather than the prettier `☑`/`☐`. Not for the column-width reason you
+might expect: those box characters genuinely measure one cell everywhere. They're simply missing from most monospace fonts, and missing
+*asymmetrically* — `☐` is the worse-covered of the two, so the unchecked
+state can degrade to tofu while the checked one renders, which reads as a
+bug rather than a fallback.
+
+When the user should pick *several* things from a handful,
+{Tuile::Component::CheckboxGroup} stacks those rows into one widget: a
+cursor moves with the arrows, Space toggles the row it sits on, and `value`
+is the `Set` of items you selected.
+
+```ruby
+levels = Component::CheckboxGroup.new(items: LogLevel.all)
+levels.item_label = ->(l) { l.name }
+levels.on_value_change = ->(set) { refilter(set) }   # a Set of LogLevels
+```
+
+Notice what `value` holds: the *items*, exactly as the combo box does — a
+group over `LogLevel`s hands back `LogLevel`s, so filtering is
+`selected.include?(level)` and never a lookup from a label back to the
+thing it named. A `Set` rather than an array, because the selection has no
+inherent order — which brings a wrinkle worth knowing up front. The set
+iterates in the order things were *toggled*, so if you need the order the
+rows are shown in, ask for it: `items & value.to_a`. Treat the set as
+unordered and you'll never be surprised.
+
+The set is also **frozen**. That's deliberate, and it's the one thing that
+can bite you if you don't expect it: `group.value << item` raises rather
+than quietly working. It has to, because a listener that fires on change
+can only notice a change if the value is *replaced* rather than edited in
+place — mutate the set you were handed and the group would have no way to
+tell anyone. So assign a new selection instead (an array is fine, it's
+coerced), and let the widget's own toggling build the new sets for you.
+
+Here the cursor and the selection are genuinely two different things — the
+cursor says *where you are*, the checkmarks say *what you picked* — and
+that shape is exactly what a list already provides. So a checkbox group
+doesn't paint rows itself; it holds a {Tuile::Component::List} and gets the
+cursor, the scrolling, the scrollbar and the per-row mouse handling for
+free, in the same "wrap a generic component to make a domain one" way the
+combo box wraps a text field. That inheritance goes further than
+convenience: a click anywhere on a row toggles it, and Enter toggles the
+cursor's row, because those are the list's own gestures for choosing an
+item.
+
+Which is worth pausing on, because it looks like a contradiction of what
+you just read about the standalone checkbox, where a click on the blank
+space past the caption pointedly does *not* toggle. Both are right, and the
+difference is what the user is aiming at. A lone checkbox in a form column
+is a small painted thing surrounded by emptiness — the glyph is the
+target. A row in a list is a *row*: it highlights across its full width, so
+its full width is what you can click. The rule didn't bend; the thing being
+clicked changed.
+
+One thing the group deliberately does *not* do is reconcile `items` against
+`value`. Replacing the items changes only what's on screen — the selection
+is left exactly as it was, even if some of it is now invisible, and no
+change event fires. It sounds careless until you picture a form: a user
+ticks three boxes, some code refreshes the item list, and a selection
+silently narrows itself. The user saves without touching anything and has
+just changed data they never edited. Keeping `value` authoritative means
+that can't happen, and reconciling — when you actually want it — is a line
+of your own: `group.value &= group.items.to_set`. The combo box makes the
+identical promise for its single value.
+
+When exactly one of a handful will do, {Tuile::Component::RadioGroup} is
+the same widget with a single answer.
+
+```ruby
+sort = Component::RadioGroup.new(items: SORT_ORDERS)
+sort.item_label = ->(order) { order.label }
+sort.on_value_change = ->(order) { resort(order) }
+```
+
+Its `value` is the selected item — the object, not its label, as always —
+and `nil` when nothing is selected, which is where a fresh group starts.
+That `nil` is also the only way back out: Space on the row that's already
+selected does nothing, because a radio group has no deselect gesture. If
+"none of these" is a legitimate answer, give it a row of its own. Items
+are chrome here too, with the same reasoning as above: replacing them
+never touches `value`, and a selection that's no longer among the rows
+simply shows nothing marked.
+
+The interaction is worth dwelling on, because it deliberately breaks with
+the desktop convention. In a graphical radio group the arrow keys move the
+*selection*: press Down and you have chosen the next option. Tuile splits
+the two. The arrows move a cursor, and you select with Space, Enter or a
+click — the same gestures as the checkbox group above.
+
+Two reasons, the second of which decides it. First, consistency: "a cursor
+roams, Enter chooses" is how every list-shaped thing in Tuile behaves, and
+two group widgets sitting one Tab apart in the same form must not answer
+Down differently. Second, and more practically, selection-follows-arrows
+fires your listener once per row you cross. Arrow from the first option to
+the fifth, and a listener that re-sorts a table, refetches a page or
+rewrites a config file does that work four times — three of them for
+choices the user never made. Committing on a keystroke means it happens
+once, when it was meant.
+
+So the cursor is *chrome*: presentation state, like `items`, rather than
+part of the value. Assigning `value` doesn't move it, and the two
+indicators say two different things — the `(*)` marks what's selected and
+is always visible, while the highlighted row marks where you are and fades
+when focus leaves. The one thing that *does* move the cursor is `items=`,
+which pulls it back into range when the row set shrinks beneath it.
+
+The glyphs are `(*) ` and `( ) `, and this time the reason is the column
+width the checkbox section set aside. A filled bullet — `(•)` — is the
+nicer mark, but U+2022 is one of Unicode's East-Asian *ambiguous* width
+characters: a terminal configured for CJK text draws it two cells wide, a
+Western one draws it in a single cell, and a program cannot ask which it's
+talking to. Guess wrong and every row's text sits one column off — not a
+cosmetic blemish but a coordinate error, since Tuile computes every rect
+and clip from the width it believes each character has. Tuile bets on
+one cell, and keeps the set of characters riding on that bet small enough
+to enumerate, so a new widget reaches for ASCII and offers the pretty
+glyph only where someone can opt in knowing their terminal.
+
+A radio group spends a row per option, permanently. When the form has six
+of these and a terminal has twenty-four rows, that arithmetic stops
+working, and {Tuile::Component::Select} is the same single answer on *one*
+row: the selected label plus a `▾`, with the options appearing only while
+you're choosing between them.
+
+```ruby
+level = Component::Select.new(items: %w[debug info warn error], value: "warn")
+level.on_value_change = ->(l) { logger.level = l }
+```
+
+Enter, Space or Down opens the dropdown, the arrows move the highlight,
+Enter or Space commits, ESC closes it having changed nothing. `value` is
+the selected item as always, `nil` while nothing is selected — and that
+`nil` is a perfectly ordinary state here, which is why there's no
+placeholder text: an optional enum field simply shows a blank face.
+
+So when do you reach for which? The temptation is to decide by item count,
+and that's the wrong axis. Ask instead **who wrote the labels**:
+
+| The options are… | Widget | Why |
+|---|---|---|
+| a developer-authored enum, on one form row | `Select` | one row; borrows *n* transiently |
+| the same enum, worth comparing side by side | `RadioGroup` | spends *n* rows permanently |
+| supplied by the app, open-ended, labels you don't control | `ComboBox` | filtering *is* the navigation |
+| an enum, several of which apply | `CheckboxGroup` | a frozen `Set` value |
+
+A select is for a closed set you knew when you wrote the code — log level,
+sort order, line endings, Yes/No/Ask. A combo box is for countries, users,
+branches: data. A twelve-value enum is still a select, and a three-row
+country list loaded from a database is still a combo box, because next
+release it's two hundred rows and the widget you chose shouldn't have to
+change. Count is a symptom; authorship is the criterion.
+
+Which brings up the property that really separates the two, and it's not
+the filtering. **A select claims no printable key but Space.** Every other
+letter and digit bubbles straight past it, up the focus chain, to your
+application — so a form's `s`-to-save, or a layout's `1`/`2`/`3` jumps
+between panes, keep working while focus sits in a select. A combo box can
+never offer that: its field must eat every printable, because every
+printable is potentially part of the query. Add the fact that a select has
+no caret, and the two together are the whole case for the component. A
+caret is the strongest promise a terminal can make about what a widget
+does, and spending it on "you may type free text here" over a four-value
+enum is a lie the user then has to discover.
+
+Space is the one exception, and it's a safe one precisely because Space was
+never yours to begin with: every activatable widget in Tuile already claims
+it — a button, a checkbox, a radio group. Home and End, by contrast, are
+declined, so they stay available for you to bind app-wide.
+
+You may be waiting for type-ahead — press `f` and jump to the first item
+starting with `f`, the way desktop lists do. It isn't there, deliberately.
+The single-key version is silently wrong: with Finland, Fiji and Jamaica in
+the list, typing `fij` selects *Jamaica*, because each key is a fresh
+one-character match. The fix everyone reaches for next is a small
+accumulating buffer that clears after a second of idleness — and that
+buffer *is* the combo box's query with the display removed. If you're
+holding query state, showing it is strictly better than hiding it, and
+showing it is a combo box. On a terminal it's worse still: the timer leans
+on inter-keystroke gaps, and gaps are exactly what a laggy SSH link or a
+paste destroys.
+
+One small nicety worth noticing: the dropdown is never narrower than the
+select itself, and grows past it when a label needs the room — so its edges
+line up with the face you clicked, and the labels are never the thing that
+gets ellipsized. It opens below the select, flips above near the bottom of
+the screen, slides left rather than running off the right edge, and grows a
+scrollbar when there are more options than it can show.
+
 For a discrete action rather than a selection, {Tuile::Component::Button}
 is a one-row `[ caption ]` that fires `on_click` on Enter, Space, or a
 left-click, highlighting its background while focused. It's a tab stop, so
 it joins the normal Tab cycle.
 
+## Reporting progress
+
+Everything so far either shows text or captures input.
+{Tuile::Component::ProgressBar} does neither: it reports, and it is the
+first component in this tour you never focus and never type into. A run of
+`█` grows left to right over a `░` track, measured against a range you set:
+
+```ruby
+bar = Component::ProgressBar.new(range: 0..files.size)
+bar.value = done
+```
+
+The first thing to notice is what it *doesn't* have — text. No percentage
+sits on the bar, and there is no slot to put one there. That looks like an
+omission until you try to write the alternative: centering a string over a
+fill boundary means slicing it in two and restyling each half so it stays
+legible against both, and the result can only ever be one centered line
+clipped to the bar's width. A {Tuile::Component::Label} underneath is
+strictly more capable and costs one line:
+
+```ruby
+label.text = "#{bar.percent}% — #{done}/#{files.size} files"
+```
+
+Now the app words it. "Scanning…", a filename, two lines, a count — none of
+which a formatting knob on the bar could have produced. This is the
+composition argument from chapter 1 in miniature, and the frameworks Tuile
+takes after land in the same place: Vaadin's `ProgressBar` has no text API
+either, and its own docs tell you to put a label beside it.
+
+That leaves `fraction` and `percent` as real API rather than conveniences,
+since they're what the label reads. Both scale the same way, and it's worth
+knowing the rule: **the endpoints are exact.** A full bar means done and
+`percent` returns 100 only at the maximum — 99.9 % floors to 99 and paints
+one empty cell. The alternative, rounding, paints a *full* bar at 97.5 % on
+a 20-cell rect, and a progress bar that says "finished" before it is has
+told you the one lie it exists to avoid. At the other end the rule is
+mirrored: anything above zero lights at least one cell, because a job that
+has started and shows nothing reads as a job that has hung.
+
+When you don't know the total, say so:
+
+```ruby
+bar.indeterminate = true
+```
+
+and the fill is replaced by a block sliding across the bar. It animates
+itself — the bar starts a ticker when it's added to the tree and cancels it
+when it's removed, so there is nothing to remember and nothing to leak.
+That is the attach-hook idiom from chapter 4, and this is the first
+component to use it. The cost is that an animating bar keeps the event loop
+awake, so switch it off (or take the bar off screen) when the work ends.
+
+One consequence of measuring against a range is worth calling out because
+it looks like an edge case and isn't: `range = 0..0` is legal, and reads as
+complete. An empty file list is a job with nothing outstanding, so
+`bar.range = 0..files.size` needs no special case for the empty run — and
+an app that reaches that state because it hasn't counted yet wanted
+`indeterminate` anyway.
+
+The bar takes its color from `bar_color`, which is `nil` by default — the
+terminal's own foreground, the same choice chapter 6 makes for every
+non-accent cell. Assign a {Tuile::Color} for a branded or threshold color
+(green under 50 %, red over 90 %), or a `Theme.ref` to have it track the
+light/dark scheme. Both glyphs take that one color: what distinguishes
+filled from empty is the *density* of the character, not its hue, so the
+bar still reads on a terminal with no color at all.
+
 ## Framing content
 
 {Tuile::Component::Window} is the frame: a bordered box with a `caption`
@@ -186,9 +635,9 @@ window.content = Component::TextView.new.tap { _1.text = help_text }
 Component::Popup.new(content: window).open
 ```
 
-A nested TextField that owns the cursor still swallows printable keys
-first, so typing `q` into a field inside a popup doesn't dismiss it — the
-same cursor-ownership rule, working through the layers.
+A nested TextField still swallows printable keys first, so typing `q` into
+a field inside a popup doesn't dismiss it — the popup's own `q` handler sits
+on the ancestor, and only sees keys the field declined.
 
 ## Batteries-included windows
 

data/book/08-testing.md

@@ -97,14 +97,27 @@ list.handle_key(Keys::DOWN_ARROW)          # exercises the cursor directly
 list.handle_mouse(MouseEvent.new(:left, 5, 2))
 ```
 
-**High: go through the screen.** {Tuile::Screen#handle_key} runs the *full*
-dispatch pipeline from chapter 5 — Tab cycling, global shortcuts, the
-subtree `key_shortcut` search, then the focus chain. When your test is
-about routing — that a shortcut jumps focus, that a modal popup traps Tab,
-that a focused text field swallows a key its sibling would otherwise claim
-— you drive `Screen.instance.handle_key` and let the real machinery run.
-Set focus the way production does, with `screen.focused = component` or
-`component.focus`.
+**High: go through the pane.** {Tuile::ScreenPane#handle_key} runs the
+dispatch rung from chapter 5 that routing is actually about: delivery to
+{Tuile::Screen#focused}, then the bubble up its ancestor chain to the scope
+root. So when your test is about routing — that a layout's one-key pane jump
+fires, that a focused text field swallows a key its ancestor would otherwise
+claim, that an open modal keeps the content beneath it from seeing keys — you
+drive the pane and let the real machinery run:
+
+```ruby
+screen.focused = list                # focus as production does — or list.focus
+assert screen.pane.handle_key("1")   # the layout's ancestor binding fires
+```
+
+The two rungs *above* the pane have their own doors, because `Screen`'s own
+`handle_key` — the top of the ladder — is private: it belongs to the key
+thread, not to app code. Tab cycling is {Tuile::Screen#focus_next} /
+`focus_previous`, both already scoped to the topmost modal popup, which is
+what "a popup traps Tab" means. A global shortcut is a block you registered,
+so test the action it calls; the registry itself is a lookup table `Screen`
+consults before handing the key to the pane, and `register_global_shortcut`
+is worth a test only for what it *rejects* (printables, Tab, `EDITING_KEYS`).
 
 Two more test-only hooks close the loop. After you mutate something, call
 `Screen.instance.repaint` to flush the pending invalidations into the