tuile 0.12.0 → 0.14.0

data/book/07-components.md

@@ -71,10 +71,11 @@ 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.
+and `max_text_length` speak indices, while `rect`, the field's horizontal
+scroll offset 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
@@ -530,16 +531,59 @@ 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.
+## Taking an action
+
+Every component so far *holds* something — a value, a selection, a cursor
+into a list. {Tuile::Component::Button} holds nothing. It runs a block:
+
+```ruby
+save = Component::Button.new("Save") { form.submit }
+save.on_click = -> { form.submit }   # or assign it afterwards
+```
+
+It paints as `[ Save ]` on one row, highlights its background while it is on
+the focus chain, and is a tab stop, so Tab reaches it like any field. Enter,
+Space and a left click all fire `on_click`, and the callback takes no
+arguments — a button has nothing to report, because that it was pressed *is*
+the event.
+
+**Sizing it is your job**, exactly as chapter 3 promised: there is no channel
+for a component to advertise the width it would like, so the caller does the
+arithmetic. For a button that's the caption plus the four columns `[ ` and
+` ]` occupy:
+
+```ruby
+# inside a Layout subclass, where the constraint names are already in scope
+add(save, Fixed[save.caption.display_width + 4])
+```
+
+Get it wrong in either direction and the failure is graceful rather than
+broken: a narrower rect ellipsizes the label, and a wider one leaves a tail
+that *focuses* but doesn't fire — the same `extent` rule the checkbox above
+spells out, and buttons follow it identically. (The sampler keeps a one-line
+`button_width` helper for this, which is what "the app does the arithmetic"
+looks like in practice.)
+
+**A focused button consumes Enter**, and that matters the moment you have
+more than one. Enter on a focused `Save` activates *that* button — not some
+form-wide default, because Tuile has no notion of a default button at all.
+The form's Enter-to-submit is a `handle_key` on the ancestor that owns the
+form (chapter 5), and it only ever sees Enter when the focused widget
+declined it. So a dialog's two buttons are just two widgets, and which one
+Enter hits is simply which one has focus.
+
+One thing you will look for and not find: **there is no disabled state.**
+Tuile has no enabled/disabled seam on any component, so a button that
+shouldn't be pressable yet is one you don't add to the tree, or one whose
+block checks the precondition and says why. That's less of a gap than it
+sounds on a TTY, where a greyed-out control is hard to distinguish from a
+styled one anyway.
 
 ## 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
+Everything so far either shows text, captures input, or acts on it.
+{Tuile::Component::ProgressBar} does none of those: 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
@@ -630,24 +674,403 @@ window.content = Component::List.new.tap { _1.lines = entries }
 window.scrollbar = true
 ```
 
+### Reserving a region: `Slot`
+
+A `Window` has one content region. When *you* build a container with
+several — a dialog with a message, a button row and maybe a header — give
+each region a {Tuile::Component::Slot}: a component whose whole job is to
+hold one child and size it to itself.
+
+```ruby
+@message = Component::Slot.new
+add(@message, Expand[1])              # the region, wired once at construction
+@message.content = Component::Label.new("Delete this file?")   # the occupant
+```
+
+The reason to bother is an arithmetic problem you'd otherwise have to
+solve. Children are ordered, and order decides paint order and Tab order —
+so if you held the message and the buttons as direct children, "where does
+the message get inserted?" would depend on whether the header happens to be
+present right now. Inside a slot the answer is always index 0, because the
+slot itself never leaves the tree. Add regions, reorder them, leave some
+empty: none of it changes a swap.
+
+Which leads to the one thing that surprises people: **an empty slot doesn't
+collapse.** It keeps the rectangle its parent gave it and clears it, so a
+dialog with no message shows the hole — exactly as it would with an *empty*
+message. If you want the gap closed, that's the parent's arithmetic (give
+the slot a zero extent), which is the same top-down rule as everything else
+in chapter 3. Don't detach the slot to make it go away; that hands you back
+the insert-index problem it exists to remove.
+
+A slot is invisible to input: it can't take focus, clicks pass straight
+through to the occupant, and when an occupant leaves, the focus repair is
+handed up to your container rather than stranding focus on the slot.
+
+## Switching between views
+
+When a screen has more content than fits and the parts are *alternatives*
+rather than neighbours — a settings dialog's General / Network / Advanced,
+a monitor's Requests / Errors / Config — you want one visible at a time and
+a way to pick. That's {Tuile::Component::TabSheet}: a one-row strip of
+captions across the top, and below it the pane belonging to whichever tab
+is selected.
+
+```ruby
+sheet = Component::TabSheet.new
+sheet.add_tab("Details", details_form)     # the first tab is selected
+sheet.add_tab("Payment", payment_form)
+sheet.on_tab_selected = ->(index, tab) { status.text = "on #{tab&.caption}" }
+```
+
+The strip is a component in its own right, {Tuile::Component::Tabs}, and
+you can use it alone when the thing being switched isn't a pane you want
+the sheet to own — repointing a `TextView` at a different document, say, or
+driving a swap somewhere else entirely on the screen. `TabSheet` is the
+convenience of "strip plus the pane that goes with it"; `Tabs` is the
+selector by itself.
+
+### A selection is not a value
+
+`Tabs` is not a {Tuile::Component::HasValue} field, and the test that
+tells you why is worth carrying to your own components: **would a form save
+it?** A {Tuile::Component::RadioGroup}'s selection *is* the datum being
+edited — it goes in the record — so it's a value. A tab's selection is
+where the user happens to be looking. Nothing saves it, nothing validates
+it, and a form iterating its fields should never find it. So the strip
+speaks in its own words — `selected`, `selected_index`, `on_tab_selected`
+— and stays out of the seam the value section earlier in this chapter set
+up.
+
+`on_tab_selected` reports that the selection *changed*, not that the user
+pressed something: arrows, a click, an assignment from your own code, the
+autoselect of the very first tab, and the re-selection that follows
+removing the selected tab all reach it. When the last tab goes it fires
+with `(nil, nil)`, which matters if you render from it — you have to be
+told to render *nothing*, or the departed tab's content sits there with no
+tab pointing at it.
+
+### The strip is one tab stop, and arrows switch immediately
+
+Tab lands on the strip, and Tab again enters the pane — the browser's
+order, and you get it for free: the strip is the sheet's first child, and
+Tab collects the tab stops in tree order (chapter 5). Within the strip,
+Left and Right switch tabs. Tab itself
+never moves *between* tabs: it means "leave this widget" everywhere in
+Tuile, and a strip is one widget.
+
+Switching is immediate — there is no cursor to walk across the strip and no
+Enter to confirm — and that is a design choice with a visible payoff.
+Manual activation would need two states on one row, the tab you're on and
+the tab you're pointing at, and therefore two ways of marking them. Making
+the arrows *be* the selection leaves exactly one thing highlighted, which
+is why the strip can spend both of its visual channels on saying where you
+are: the selected caption is **bold always**, and it additionally sits on
+the theme's `active_bg_color` while the strip has focus. Bold is the one
+that survives focus moving away — the strip is the map of where you are in
+the app, and a map shouldn't go blank when you look somewhere else.
+
+Everything else bubbles. Enter, Space, Home, End, the vertical arrows and
+every printable pass straight through to your ancestors, so a form's
+default button and an app's own keys keep working while the strip has
+focus. If you want a key elsewhere in the app to drive the strip — a
+`Ctrl+PageDown` habit from your editor — bind it yourself and call
+`select_next` / `select_previous`. Tuile ships no such binding, because
+"one key, anywhere, meaning switch tab" is a statement about your app, and
+with nested sheets it would be ambiguous about *which* sheet.
+
+### Tabs are handles, not items
+
+Everywhere else in this chapter, a widget takes a collection: `items=`,
+`lines=`. A strip doesn't. `add_tab` mints a {Tuile::Component::Tabs::Tab}
+and hands it back, and you keep it:
+
+```ruby
+payment = sheet.add_tab("Payment", payment_form)
+payment.caption = "Payment ⚠"    # repaints the strip
+payment.remove                   # the handle raises from here on
+```
+
+The difference isn't cosmetic. An item is an element of a collection
+somebody else owns — assign the whole array and the widget renders what it
+finds. A tab is an identity with its own state, and it is what a
+`TabSheet` keys its pane mapping by. Handing the strip a fresh array would
+destroy those identities and the mapping with them, so the operation
+simply isn't offered: you add and remove tabs one at a time. Captions are
+mutable through the handle, and a removed one raises on every mutation and
+on anything it would have to ask the strip — better than quietly answering
+about a tab that is no longer there. Its caption stays readable, so an
+error message can still name it.
+
+### Hiding a component means detaching it
+
+Here is the part with consequences beyond this widget. **Tuile has no
+visibility flag.** There is no `visible?`, no `display`; the empty rect you
+met in chapter 2 gates *painting* and nothing else — an "invisible" widget
+with an empty rect is still in the Tab cycle, still a target of the focus
+cascades, still answering for the cursor. So hiding, in Tuile, means taking
+something out of the tree, and that is exactly what a `TabSheet` does: only
+the selected tab's pane is a child of the sheet, and the rest are detached.
+
+Three things fall out of that, and they're the reason it's the right
+mechanism rather than a workaround for a missing feature:
+
+- **A hidden pane is invisible to everything** — the Tab cycle, focus,
+  repaint, the cursor, tree walks. Not because anything checks a flag, but
+  because it isn't there. There is no gate to get wrong.
+- **Its state survives, because state is ivars.** Scroll position, caret,
+  list cursor, typed text: all exactly as the user left them. You can go on
+  mutating a hidden pane too, with no special handling and no "am I
+  visible?" check — `invalidate` on a detached component is a silent no-op,
+  and the sheet assigns it a rect and invalidates it when it comes back.
+- **The lifecycle hooks fire on every switch.** `on_detached` when a pane
+  goes away, `on_attached` when it returns — so a
+  {Tuile::Component::ProgressBar} in a hidden tab stops its ticker and
+  restarts it on return, with no bookkeeping from you.
+
+The cost is the mirror image of that last point: a pane that must keep
+something *alive* while hidden can't, because chapter 4's
+`on_attached`/`on_detached` contract is exactly what detachment triggers. The
+way out is to move the thing that must not stop: give the resource to the
+model your pane renders rather than to the pane, and let the pane pick up
+its current state on return. That is usually the better shape anyway — if
+you're reluctant to let a hidden pane's poller or subscription die, it
+probably wanted to outlive the view all along.
+
+The `TabSheet` pane in `examples/sampler.rb` demonstrates the state part
+directly: scroll the prose tab, switch away, come back, and the status line
+under the sheet reports the row you left it on.
+
+### When the strip is too narrow
+
+Give a strip the width its captions need and there is nothing here to think
+about; with the three to five tabs this shape is actually for, that is the
+normal case. When a layout can't give it that width — a narrow terminal, a
+caption that grew a badge — the strip **scrolls** rather than putting some of
+its tabs out of reach. It keeps the selected segment whole in view and moves
+its window by the smallest amount that does so, so arrowing along an
+overflowing strip walks the selection off one edge and the strip follows it,
+a tab at a time.
+
+Two things tell you there is more strip than you can see. The captions at the
+edges are cut mid-word, which is the oldest overflow hint there is; and a `<`
+or `>` is painted over the edge column itself. The cue is there because the
+cut alone isn't reliable — scroll to just the right place and a segment
+boundary lands exactly on the edge, leaving clean space that reads as "that's
+all of them". The cues are ASCII, they are painted whether or not the strip
+has focus (overflow is a fact about the captions and the rect, not about
+where you are), and they are not buttons: a click on one lands on the
+half-visible segment underneath, which selects that tab and pulls it into
+view — the direction the cue was pointing anyway.
+
+The one thing a strip cannot do is show a caption wider than the whole rect.
+There it gives you the head and clips the tail, on the grounds that the start
+of a word identifies it and the end usually doesn't.
+
+## Menus
+
+A menu bar is the other way to say "the app can do these things", and it
+answers a different question from tabs. Tabs are a *map*: they show where
+you are, and switching one changes what you're looking at. A menu is a
+*catalogue of verbs*: it shows what you can do, it closes again the moment
+you pick, and it leaves the screen exactly as it was. If the caption names
+a place, use tabs; if it names an action, use a menu.
+
+{Tuile::Component::MenuBar} is one row of captions, and each of them drops
+open a menu:
+
+```ruby
+bar = Component::MenuBar.new
+
+file = bar.add_item("File")
+file.add_item("New")  { new_document }
+file.add_item("Open") { open_dialog }
+recent = file.add_item("Open recent")            # no block ⇒ a submenu
+recent.add_item("notes.txt") { open("notes.txt") }
+
+bar.add_item("About") { show_about }             # a top-level leaf: a button
+```
+
+Two things about that snippet do most of the work. First, `add_item` is the
+*same* method on the bar and on an item, so nesting needs no new vocabulary
+— and because an item can hold items, submenus go as deep as you build
+them. Second, whether an item is a submenu or an action is not something
+you declare: an item with children *is* a submenu, and its own block (if
+you gave it one) is simply dead. That's why `recent` above takes no block
+and `"New"` does. A top-level item with no children isn't a menu at all —
+it's a button on the bar, which is exactly how you get a single "About" or
+"Help" entry without inventing a one-item menu for it.
+
+An item with neither children nor a block is legal, and does nothing. It
+highlights, Enter closes the menu, and nothing happens. That is a deliberate
+non-decision: a half-built menu is a programming error you'll see the moment
+you run the app, and it isn't worth an exception that fires while you're
+still assembling the thing.
+
+### The bar keeps focus the whole time
+
+This is the part worth understanding, because it explains everything else.
+The open menus are **overlays**, not children of the bar — they're mounted on
+the screen pane, floating above whatever they cover, and they never take
+focus. Focus stays on the strip from the moment you open a menu until it
+closes, however deep you drill. So the bar receives every keystroke and
+decides what to do with it; the panels are things it draws and drives.
+
+That is the same arrangement {Tuile::Component::Select} uses for its
+dropdown (chapter 5 has the key-dispatch ladder this rests on), and it
+buys two properties. The whole widget is one tab stop — Tab moves *past*
+the bar, never into a menu. And nothing about menus needed adding to the
+framework's key handling: a menu is not a mode.
+
+The keyboard map is the one every menu bar has had since Turbo Vision, and
+it's worth learning once because Vaadin, the web's ARIA pattern and every
+other TUI toolkit agree on it:
+
+| While the bar has focus | |
+|---|---|
+| Left / Right | move along the strip |
+| Enter, Space, Down | open the highlighted menu |
+| a mnemonic letter | open that menu (see below) |
+| anything else | bubbles to your app |
+| **Inside an open menu** | |
+| Up / Down (PgUp/PgDn, Ctrl+U/D) | move the highlight |
+| Right, Enter, Space | open the submenu under the highlight |
+| Enter, Space | activate a row that has no submenu |
+| Left | back to the previous menu |
+| Left at the first level, Right on a plain row | step to the neighbouring menu |
+| a mnemonic letter | activate that row of *this* menu |
+| ESC | close one level |
+
+Stepping sideways *shows* the neighbour's menu; it never presses anything. So
+arrowing onto a top-level button — an item with a listener and no menu — closes
+whatever was open and highlights it, and it fires only when you press Enter or
+Space. Otherwise walking the strip would trigger every button on it.
+
+The last row of the first block matters for real apps: while the bar merely
+has focus, every other key **bubbles past it**, so a form's `s`-to-save or
+a layout's `1`/`2`/`3` pane jumps keep working. An *open* menu is different
+— it swallows what it doesn't recognize. A menu is a quasi-modal moment, and
+an app key firing behind a panel you can see would be worse than a keystroke
+that does nothing.
+
+### What it looks like, and why it isn't a tab strip
+
+The strip paints ` File  Edit  View ` — each caption with a space either
+side, no separator column, and the menu that Enter would open highlighted
+while the bar has focus. Move focus away and the highlight goes entirely.
+
+Compare that with the tab strip earlier in this chapter, which keeps its
+selected caption **bold** even unfocused and rules its segments apart with
+`│`. The difference is on purpose. A tab strip has to say where you are
+after focus has moved on, so its selection is permanent and needs a channel
+that survives losing focus. A menu bar has nothing permanent to say: close
+the menu and no item is selected, because you are not "in" File the way you
+are "on" the Details tab. Two one-row caption strips that looked the same
+would make you work out which control you were looking at; these two don't.
+
+What the two *do* share is everything from "When the strip is too narrow"
+above. A bar that outgrows its terminal scrolls to keep the highlighted menu
+whole in view, cues the hidden captions the same way, and stays reachable by
+arrow, by mnemonic and by click — a mnemonic jumping to a menu off the right
+edge brings it on screen before its panel opens.
+
+### Mnemonics: one letter per level
+
+Give an item a letter and it answers to it:
+
+```ruby
+file = bar.add_item("File", mnemonic: "f")
+file.add_item("Export", mnemonic: "e") { export }
+file.add_item("Quit",   mnemonic: "q") { quit }
+bar.add_item("Edit", mnemonic: "e").add_item("Copy", mnemonic: "c") { copy }
+```
+
+The letter is underlined in the caption where it occurs — `F̲ile` — on the
+strip and in every open panel, whether or not the bar has focus. There is no
+Alt key to reveal them with, so they are simply always visible.
+
+Now press `f`, then `q`: File opens, Quit fires. That reads like a two-key
+accelerator, but it is nothing so clever — it is two ordinary keystrokes, and
+the second one means something different because the first one changed what
+is on screen. That is the whole rule:
+
+> A mnemonic is matched against **one** set of items: the top-level ones
+> while no menu is open, and the deepest open menu's while one is. Nothing
+> else is ever consulted.
+
+Read the example again with that in mind and notice what *cannot* happen.
+`Export` and `Edit` both bind `e`, and there is no conflict to resolve —
+with File open, `Edit` is not one of the candidates, so `e` means Export. If
+you close the menu first, `e` means Edit. The two are never in the same
+lookup, so the framework never has to guess, and you never have to hunt for
+a free letter across the whole tree. Only *siblings* compete, and two
+siblings claiming one letter is a mistake Tuile refuses at `add_item` rather
+than resolving at the keyboard.
+
+The same rule says what a *wrong* letter does. With File open, `v` matches
+nothing in File's menu — and nothing happens. It does not fall out to the
+strip and open the View menu, because a mistyped letter tearing down the
+menu you are reading would be a poor trade for a shortcut. You get the
+terminal bell instead, and Left, Right and ESC are still there to move.
+
+One cost to know about, because it is what a mnemonic *means*: while the bar
+has focus, its letters win. A `mnemonic: "s"` eats the `s`-to-save described
+above, and a `mnemonic: "q"` inside a popup eats the popup's own `q`-to-close.
+That is the bubble working correctly — the focused component is asked first
+— but it is worth a thought before binding a common letter.
+
+**A click outside an open menu closes it.** The panels float above the UI
+without blocking it (chapter 3's overlays are all like this), so the click
+still reaches whatever it was aimed at — but on its way the screen dismisses
+the cascade, so a menu can't linger over content it no longer belongs to.
+Clicking *within* the menu is not outside it, whichever panel you land on:
+the panels are chained to each other, so drilling into a submenu by mouse
+leaves the levels above it standing. ESC and Tab also get you out.
+
+### One thing it deliberately doesn't do
+
+**A resize closes an open menu.** Every panel is positioned against
+something — the strip segment it dropped from, or the parent row it cascaded
+out of — so after the terminal changes size those positions are all stale.
+Recomputing them level by level is possible; closing is unambiguous, and
+every GUI dismisses its menus on a window resize too.
+
 ## Overlays
 
 {Tuile::Component::Popup} is how you float something above the tiled UI.
 The popup itself paints nothing — it's a transparent host that wraps any
 component as its content and manages the lifecycle (`open` / `close`,
 ESC/`q` to dismiss). Crucially, and per chapter 3, **it does not size
-itself to its content**: its box is declared by `size` — a `Fraction`
+itself to its content**: its box is set by `declared_size` — a `Fraction`
 (default `Fraction::HALF`, half the screen, re-resolved on every resize)
 or an absolute `Size`. The content then fills that box, so use content
 that can cope with overflow — a TextView or TextArea that scrolls, not a
 bare Label that only truncates.
 
-A popup is **modal by default**: centered, it grabs focus, eats keys, and
+A popup is **always modal**: centered, it grabs focus, eats keys, and
 blocks clicks beneath it — that's what makes an open dialog trap Tab and
-input inside itself. Pass `modal: false` for a non-modal overlay that
-floats above the content without taking focus — the autocomplete-list case
-from earlier, where the caller positions it against a field's caret and
-drives it from app code.
+input inside itself. For a layer that floats *without* taking focus — the
+autocomplete-list case from earlier, where the caller positions it against a
+field's caret and drives it from app code — use its base class, `Overlay`,
+directly. An `Overlay` is a Popup minus the modality: same open/close
+lifecycle, same outside-click dismissal, but it sits at the rect you assign
+and never disturbs focus or key dispatch.
+
+**A left click outside an overlay closes it**, modal or not — the same light
+dismissal a desktop dialog gives you. It's a per-overlay switch,
+`close_on_outside_click`, on by default; one that must survive stray
+clicks turns it off, as a Notification does. The click still reaches
+whatever was beneath it, unless an open modal swallowed it — in which case
+the first click dismisses and a second one acts.
+
+"Outside" means more than "outside this rectangle". An overlay opened by a
+component that lives inside another popup — a ComboBox on a dialog, whose
+dropdown drops past the dialog's own border — says so with `owner`, and a
+click landing in it then counts as landing inside the dialog too. Otherwise
+picking from the dropdown would dismiss the form under it. Overlays that
+*aren't* related that way stay independent: clicking one dismisses the
+other, as two dismissable windows should. You only need `owner` when you
+build a compound overlay of your own; the built-in ones already set it.
 
 Because the popup is just a transparent host, you get a bordered dialog by
 wrapping a Window:
@@ -662,6 +1085,116 @@ 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.
 
+## The confirm dialog
+
+That Window-in-a-Popup assembly is how you build any dialog. One dialog is
+so common it comes pre-assembled: {Tuile::Component::ConfirmWindow}, the
+"are you sure?" box — a caption, a short message, a row of buttons.
+
+```ruby
+Component::ConfirmWindow.confirm("Delete Report Q4?", "This cannot be undone.",
+                                 confirm: "Delete") { delete! }
+```
+
+```
+              ┌Delete Report Q4?───────────┐
+              │ This cannot be undone.     │
+              │                            │
+              │    [ Delete ]  [ Cancel ]  │
+              └────────────────────────────┘
+```
+
+Three factories cover the shapes you'll actually write: `alert(caption,
+message)` is the one-button acknowledgement, `confirm` the two-button
+question — its labels are keywords, so it is also your OK/Cancel and
+Delete/Cancel — and `yes_no` the other canonical phrasing. That's
+deliberately the whole list: Windows' `MessageBoxButtons` enum grew six
+values by naming every label pair, and any set the factories don't cover is
+a few lines of the builder below.
+
+### Why a block, and not an answer
+
+Everyone's first instinct here is the blocking call — `if confirm?("Delete?")`
+— because that's what Swing's `JOptionPane`, tkinter's `askyesno` and GTK's
+`dialog.run` all offer. Tuile can't, and it's worth understanding why: the
+whole UI runs on one thread (chapter 4), so a call that *waits* for the
+answer would have to nest a second event loop inside the first, re-entering
+raw mode under a key thread that's already reading stdin. The dialog
+therefore takes callbacks: the block is the action, and the dialog returns
+immediately.
+
+### One kind of way out
+
+Every button closes the dialog. A button *with* a block then fires it; a
+button *without* one is a Cancel. And ESC, `q`, a click outside the box and
+that Cancel button are all the same event — `on_dismiss`, fired exactly
+once, and only when no action button was chosen. You never write a `case`
+over outcomes, and you never have to enumerate the ways out: there is the
+action you asked about, and there is "do nothing", however the user spells
+it.
+
+There is deliberately no way to keep the dialog open after a press. A
+dialog that leads somewhere — "Copy files" showing a progress window —
+opens the next window *from its callback*, which is safe because the block
+fires after the dialog has already closed and focus has been repaired.
+
+For any other button set, the component is its own builder — buttons are
+declared one at a time, each a caption and an optional block:
+
+```ruby
+dialog = Component::ConfirmWindow.new("Unsaved changes")
+dialog.message = "Save your changes before leaving?"
+dialog.button("Save")    { save! }
+dialog.button("Discard") { discard! }
+dialog.button("Cancel")            # no block: pressing it dismisses
+dialog.on_dismiss = -> { stay_put }
+dialog.open
+```
+
+### Keys, and the underlined letters
+
+Focus opens on the first button — which, since Enter presses the *focused*
+button, makes it the default. Left/Right and Tab walk the row; Enter or
+Space press.
+
+Each button also answers to a **mnemonic**: a letter, underlined in its
+caption, that presses the button from anywhere in the dialog. By default
+it's the caption's first letter (Save gets `s`, Discard `d`), matched
+case-insensitively; pass `mnemonic:` to pick another letter — the case you
+give chooses which occurrence gets the underline — or `nil` for none. The
+underline isn't decoration: Tuile draws no status bar to advertise keys in,
+so the caption *is* the advertisement.
+
+Three letters are never mnemonics. `q` is unconditionally the do-nothing
+route out — a dialog that forces a choice only thinks it does, since the
+user can always Ctrl+C, and pretending there's no escape route just trains
+them to reach for it. And `g`/`G` belong to the message: the body scrolls
+*without taking focus* — Up/Down, PgUp/PgDn, Ctrl+U/D, Home/End and the
+less-style `g`/`G` are handed to it while a button keeps focus, so a long
+message reads without any focus gymnastics. The body is also a tab stop:
+Shift+Tab reaches it, so overflowing prose is visibly reachable, not
+secretly scrollable.
+
+### The popup that sizes itself
+
+Chapter 3 was firm that nothing in Tuile sizes itself to its content, and a
+plain Popup takes half the screen whatever it wraps — absurd around a
+one-line "Delete?". The confirm dialog is the sanctioned exception *shape*:
+it measures **content it owns** — its caption, its message, its buttons —
+and asks the screen for exactly that box, still capped at half the screen
+(a message longer than the cap wraps and scrolls). Assign a `Component` as
+the message and the measuring honestly gives up: injected content is not
+the dialog's to measure, so the popup takes the full half-screen box.
+
+### What it deliberately isn't
+
+The message is prose — a `String` or {Tuile::StyledString}, which on a TTY
+already covers color, emphasis and iconography — not a content slot. A
+dialog collecting *input* is not a confirm dialog: the moment you want a
+form, a picker or a diff view in there, you've outgrown the sugar, and the
+general mechanism is one line away — `Popup.new(content: your_layout)`,
+exactly as in the previous section.
+
 ## Notifications
 
 {Tuile::Component::Notification} is the one overlay you don't assemble at
@@ -700,7 +1233,9 @@ Everything else follows from "a toast must not interrupt": it's a non-modal
 popup, so it takes no focus, receives no keys (not even the `q` a normal
 popup would claim), and blocks no click outside its own box. You keep
 typing into whatever you were typing into, and the notification appears and
-leaves around you. A left-click on the box dismisses the whole thing early.
+leaves around you. A left-click on the box dismisses the whole thing early;
+a click anywhere else doesn't, because a toast is timed and an unrelated
+click isn't about it.
 
 Two limits are worth knowing before you reach them. A long message wraps to
 at most three rows and is then ellipsized — the box is capped at 40 % of
@@ -715,18 +1250,23 @@ The last three components are conveniences: common Window-plus-content
 assemblies you'd otherwise build by hand. Each works tiled (add it to a
 layout) *or* as a popup (via a class-level `open`).
 
-- {Tuile::Component::InfoWindow} — a Window preloaded with a List of
-  static lines. The read-only "here's some information" box;
-  `InfoWindow.open(caption, lines)` pops it up.
+- {Tuile::Component::InfoWindow} — a Window with a read-only body, in one
+  of two presentations: `message=` is *prose*, wrapped by a scrollable
+  TextView; `lines=` is *rows*, a List keeping one item per row and
+  truncating — the choice for columnar output, where a wrap would destroy
+  the alignment. `InfoWindow.open(caption, body)` pops it up, picking the
+  presentation from the body's type (an Array is rows, text is prose).
 - {Tuile::Component::PickerWindow} — a menu of options each bound to a
   single key, firing your block with the picked key. Popped up via `open`,
   it closes itself after a pick; ESC/`q` cancels without firing.
-- {Tuile::Component::LogWindow} — a Window wrapping an auto-scrolling,
-  scrollbar-equipped TextView, purpose-built for log output. Its `log`
-  method is **thread-safe** — it marshals the append back onto the UI
-  thread via the event queue (chapter 4), so background work can log
-  freely. And it carries an `IO`-shaped adapter so you can point a stdlib
-  `Logger` (or a `TTY::Logger`) straight at it:
+- {Tuile::Component::LogWindow} — a Window framing a
+  {Tuile::Component::LogTextView}: an auto-scrolling, scrollbar-equipped
+  TextView purpose-built for log output. The view is where the behavior
+  lives — compose it bare into a layout when you don't want the frame.
+  Its `log` method is **thread-safe** — it marshals the append back onto
+  the UI thread via the event queue (chapter 4), so background work can
+  log freely. And the view carries an `IO`-shaped adapter so you can point
+  a stdlib `Logger` (or a `TTY::Logger`) straight at either of them:
 
 ```ruby
 window = Component::LogWindow.new