tuile 0.13.0 → 0.15.0

data/book/07-components.md

@@ -117,15 +117,13 @@ 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`
-handles ESC (with a sensible default). The subtle one is `on_key` — an
-interceptor consulted *before* the input's own key handling, which is the
-building block for an autocomplete or slash-command overlay: while the
-overlay is open, `on_key` claims Up/Down/Enter/ESC and forwards them to
-the list, so the caret stays in the field and typing keeps refilling the
-suggestions.
+Both inherit the same event hooks from the base. `on_change` fires whenever
+the text changes; `on_escape` handles ESC (with a sensible default);
+`on_enter`, `on_key_up` and `on_key_down` each claim one key. Notice what
+they have in common: every one of them either *reports* something or takes a
+**single named key** whose meaning the field itself has no use for. There is
+deliberately no callback that intercepts keys in general — to change what
+keys *do*, you subclass (see *Keeping input out of a field*, below).
 
 ```ruby
 field = Component::TextField.new
@@ -138,6 +136,83 @@ 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.
 
+Three editing keys are worth knowing because nothing on screen advertises
+them. Ctrl+Left and Ctrl+Right jump by a word; **Ctrl+W** deletes the word
+behind the caret — exactly what Ctrl+Left would have skipped over — and
+**Ctrl+U** deletes everything before the caret, which with the caret at the
+end is "clear this field". All three are readline's, so they already behave
+the way they do in your shell and in every prompt you have typed into. A
+TextArea has them too, and there Ctrl+U kills back to the start of the
+caret's *row* — the same place Home goes.
+
+What you cannot have is Shift+Backspace, and the reason is a useful window
+into terminal keys in general. Backspace arrives as a single byte with
+nowhere to carry a modifier, so a terminal sends Shift+Backspace as plain
+Backspace; the shift only survives under newer opt-in protocols that not
+every terminal speaks. That is why terminal software reaches for
+Ctrl+*letter* as often as it does — those are among the few combinations the
+wire can express at all.
+
+### The hint in an empty field
+
+A blank field tells the user nothing about what belongs in it. Usually that
+is fine — a caption beside it says "Name" and there is nothing more to know.
+But some fields want a *shape* rather than a label: a date field has to say
+which of the several orderings it writes back, and no caption can carry that
+without becoming a sentence.
+
+That is what a placeholder is for. Give a field one and it paints the hint
+into its own cells while it is empty:
+
+```ruby
+field = Component::TextField.new
+field.placeholder = "dd.mm.yyyy"
+field.text                        # => "" — the hint is not content
+```
+
+The last line is the whole contract. A placeholder is paint and nothing
+else: it never enters the value, never fires `on_value_change`, is never
+touched by a paste, and never counts against `max_text_length`. That
+asymmetry *is* the feature — a hint that lived in the buffer would be a
+default value, and a form saving an untouched field would write
+`"dd.mm.yyyy"` to your database.
+
+It stays on screen while the field has focus, which is worth saying out
+loud because browsers spent years doing the opposite. The reasoning is
+simply that a format hint is wanted *most* while someone is typing into the
+field — that is exactly the moment they need to know whether the month or
+the day comes first.
+
+The typed fields carry it too, and you set it on the field itself rather
+than reaching for the text field inside:
+
+```ruby
+port = Component::IntegerField.new
+port.placeholder = "1-65535"
+```
+
+Two smaller notes. A hint wider than its field is *ellipsized*, not cut, so
+you see `dd.mm.y…` rather than `dd.mm.yyy` — the second reads as a complete
+format that happens to be wrong, which is worse than obviously truncated.
+And a field marked invalid keeps showing its placeholder: an empty required
+field is the commonest invalid state there is, and the red well saying
+*something is wrong* pairs naturally with a hint saying *what goes here*.
+
+You will notice the ink is faint — deliberately so. A placeholder is a hint
+the user is welcome to miss; nothing breaks if they never read it, so it is
+tuned to sit just above invisible rather than to compete with the text they
+type. It comes from the theme (`placeholder_color`), which is also why the
+setter takes a plain `String` and refuses a `StyledString`: the colour is
+the theme's to choose, and one baked in by hand would be stale the moment
+the terminal flipped to light mode.
+
+One thing to resist: a placeholder is not a caption in disguise. It is
+tempting in a cramped form to drop the label and let the hint do that work,
+but the hint vanishes the instant the user types a character — and a filled
+form where every field has forgotten what it is called is a form nobody can
+check before submitting. Chapter 5's rule still holds: the caption belongs
+to the layout around the field.
+
 ## The value seam
 
 Every input component — a text field today, a combo box or a date field
@@ -162,9 +237,11 @@ 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
+The buffer only ever holds digits and at most one leading `-`; anything
+else is quietly refused without so much as nudging the caret — and that
+holds for a *paste* too, which is less obvious than it sounds (see
+*Keeping input out of a field*, below). 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
@@ -194,6 +271,327 @@ 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.
 
+### A date, where the display is a choice
+
+{Tuile::Component::DateField} follows the same naming rule — its value is a
+stdlib `Date`, or `nil` — but it is the first field where *how the value looks*
+is not settled by the type. `42` has one spelling; 4 September 2026 has a dozen.
+So the field holds a list of strftime formats rather than one:
+
+```ruby
+due = Component::DateField.new
+due.formats = ["%Y-%m-%d", "%d.%m.%Y"]   # accepts both
+due.value = Date.new(2026, 9, 4)         # shows "2026-09-04", the first one
+```
+
+Parsing tries them in order and the first whole match wins, while the *first*
+format is also the one the field writes back. That single asymmetry is the whole
+design: the field is lenient about what it accepts and strict about what it
+shows, with no mode flag and no ambiguity about which format is "the" format.
+Adding a format is therefore a UX decision as much as a parsing one — every
+format you accept is a class of complaint that stops happening.
+
+Which is why the list is *yours* and Tuile's default is a single ISO format
+rather than a generous handful. It is tempting to ship the generous one, and it
+cannot be done safely: `%m/%d/%Y` and `%d/%m/%Y` both match `04/09/2026` and
+disagree about what it means, and nothing in the framework can tell which
+reading you intended. Guessing would hand a European who typed 4 September a
+field holding April 9 — a wrong value that saves cleanly, which is strictly
+worse than input the user can see is bad. The order of your list is the
+disambiguation, so it has to be your call. An app that wants two-digit-year
+input is out of luck for the same class of reason: `%y` is rejected outright,
+because two characters cannot carry a century and Ruby's fixed 1969–2068 window
+silently misreads everything outside it.
+
+The payoff for the reader arrives when they leave the field. Type `4.9.2026`
+into the field above and Tab away, and it rewrites itself as `2026-09-04` —
+**the user sees that the field understood what they typed**, which is what makes
+a multi-format list legible rather than mysterious. Enter does the same, since a
+form whose Save button is reached by Enter never moves focus at all. This is a
+deliberate divergence from `IntegerField`, which leaves a typed `007` alone: a
+format list is a statement that input and display are separate vocabularies,
+which the integer field never made.
+
+Two smaller things this field is the first to need. Its empty well paints a hint
+— `yyyy-mm-dd` — *derived from the primary format*, because a date field is
+unguessable in a way an integer field is not, and because the bad-input message
+below deliberately cannot name the formats. And its calendar is proleptic
+Gregorian rather than Ruby's `Date::ITALY` default, which is why `1582-10-10` is
+an ordinary date here and a `Date::Error` in plain Ruby; `calendar_start` is
+there for an app that means the Julian one.
+
+### A time of day, where precision is the knob
+
+{Tuile::Component::TimeField} is the date field's twin, and it diverges in
+exactly two places worth knowing about.
+
+The first is the value. Ruby has no civil-time class — no `LocalTime` — so
+there is nothing to point at the way `DateField` points at `Date`. Tuile does
+not invent one: it owns *UI* value types (`Point`, `Rect`, `Color`, `Theme`)
+and no domain ones, because a time of day lands in your model, your column and
+your serializer, and a Tuile-owned class would be a type none of them speak. So
+the value is a plain `Time` pinned to a fixed epoch date in UTC — the shape
+Rails' `time` column already hands you:
+
+```ruby
+alarm = Component::TimeField.new
+alarm.set_to(7, 30)   # shows "07:30"
+alarm.value           # => 2000-01-01 07:30:00 UTC
+```
+
+That epoch is the accepted cost, and it is stated rather than hidden: the value
+is a real instant, so it is a perfectly good `Time` that is *wrong* anywhere an
+instant was meant. Combine it with a date at your own boundary. An app that
+forgets gets the year 2000 in its output — visible, which beats subtly wrong.
+
+The second divergence is the interesting one. A date has a spelling; a time has
+a spelling **and a precision**, and they are different questions. The spelling —
+`13.45` or `1:45 PM` or `13:45` — is a convention, so it comes from
+`Screen#locale` like the date formats do. The precision is the app's, and it
+rides on `step`:
+
+```ruby
+alarm.step = 1     # shows "07:30:00"; Up walks a second
+alarm.step = 60    # shows "07:30";    Up walks a minute — the default
+```
+
+One knob doing both jobs looks like a shortcut and is the opposite. Precision is
+a property of the format the buffer is written in, and the buffer is the single
+source of truth for the value — so a second knob for it could disagree with the
+first. Vaadin's `TimePicker` and the HTML `<input type="time">` both tie
+precision to `step` for the same reason. The cost, since it is real: you cannot
+ask for seconds *and* a minute-long stride.
+
+Up and Down walk that stride; PageUp and PageDown walk an hour whatever the
+stride is; either pair on an empty field lands on *now*. That is the whole
+picker. There is deliberately no dropdown of times the way Vaadin's `TimePicker`
+has one — a list of times tells you nothing you did not already know (a
+calendar is different: it answers what weekday the 17th is), and with your hands
+already on the keys, typing `1345` beats scrolling to it. Tuile is
+keyboard-first: the mouse gets what falls out of click routing for free and never
+motivates a widget on its own. The ranking behind that is `D_mouse` in
+`DECISIONS.md`.
+
+What you get for it is that the two questions stay independent. Switching
+precision never touches the spelling, so a Finnish user sees `13.45` and
+`13.45.00` and never a stray colon — which is the failure mode a per-field
+format setter would have, since overriding the format to add seconds would
+throw the locale's separator away with it.
+
+Two consequences that follow from the buffer being the truth. Stepping *adds*
+rather than snapping to a grid, and wraps at midnight — `23:59` plus a minute is
+`00:00`, because a clock has no day to carry into. And narrowing the precision
+never silently truncates: `13:45:00` becomes `13:45`, since dropping a zero
+discards nothing, but `13:45:30` stays exactly as typed and reads as bad input,
+because the seconds are something you meant.
+
+### Keeping input out of a field
+
+Say you want a field that holds only hex digits. The tempting move is to
+work at the keyboard: catch each keystroke, refuse the ones you don't
+want. It seems to work, and it is wrong, for a reason worth
+internalizing: **a paste is not a keystroke**. It arrives as one whole
+`String` (chapter 5), nowhere near your key handling, so a filter written
+there guards typing and waves the same characters through on Ctrl-V.
+Tuile's own numeric fields shipped with exactly that bug — twice, in three
+fields.
+
+The lesson generalizes past this one API: filter at the altitude of the
+thing you're constraining. You are constraining the *buffer*, so the seam
+is `insert_text`, where *every* insertion goes — a typed character, a
+pasted clipboard, the newline Enter puts in a text area:
+
+```ruby
+class HexField < Tuile::Component::TextField
+  protected
+
+  def insert_text(str)
+    super if @text.dup.insert(@caret, str).match?(/\A\h*\z/)
+  end
+end
+```
+
+Two things about that method are deliberate. It judges the **result**, not
+the fragment being inserted — sieving a paste character by character would
+turn a pasted `1,5` into `15`, a number the user never copied and can't see
+is wrong, where testing the whole buffer simply drops it. And it filters
+*user input* only: assigning `field.text =` still writes whatever you give
+it, which is what lets a `FloatField` display the `1.0e-05` that
+`value = 1e-5` produces.
+
+This kind of filtering only works when the field's grammar is
+**prefix-closed** — when every valid value can be reached through valid
+intermediate states. An integer qualifies: `""`, `-`, `-1`. A *date* does
+not. `2020-13-45` is well-formed at every single character and means
+nothing, and month lengths and leap years are facts about the whole string,
+so no filter over insertions can catch it. A field like that has to accept
+the input and *report* it as bad instead — which is exactly what
+{Tuile::Component::DateField} does: it filters nothing at all, typed or pasted.
+Prevention where it can be total, reporting where it can't; a half-filter is
+the one thing to avoid, because it reads like a guarantee.
+
+### Reporting bad input
+
+Even a total filter leaves a residue, because the buffers a value is typed
+*through* have to be admitted: an integer field must let you type a lone
+`-` on the way to `-1`. Read `value` at that moment and you get `nil` — and
+`empty?` says `true`, on a field with a glyph in it. Nothing distinguishes
+it from a field the user never touched, and a form that believes `empty?`
+will save `nil` over a number they think they entered.
+
+`on_value_change` cannot rescue you here, and it is worth seeing *why* it
+structurally can't: it is a diff over **values**, and every input the value
+can't represent collapses onto the same `nil`. The information was
+destroyed by the parse before the diff ran. Typing `-` into a blank field
+moves the buffer and not the value, so the listener stays silent — correctly.
+
+So a field whose parse can fail carries a second, separate question, the
+{Tuile::Component::HasBadInput} mixin:
+
+```ruby
+amount = Component::IntegerField.new
+# ... the user types a lone "-"
+amount.value            # => nil
+amount.empty?           # => true   — empty of *value*
+amount.bad_input?       # => true   — but there is input it could not use
+amount.bad_input_message # => "not a whole number"
+```
+
+Ask it before you ask `empty?`, and ask it whatever the value says. A form's
+Save handler is the canonical consumer, walking a mixed bag of fields —
+only some kinds can answer at all, which is what the `respond_to?` is for:
+
+```ruby
+bad = fields.select { _1.respond_to?(:bad_input?) && _1.bad_input? }
+if bad.any?
+  Component::ConfirmWindow.alert("Cannot save", bad.map(&:bad_input_message).join("\n"))
+else
+  save!
+end
+```
+
+Two properties to hold onto. **An empty field is empty, not bad** — a blank
+optional field has to save, so no field reports an empty buffer as bad
+input. And **the answer is derived on read, never stored**, which matters
+because the fact is *continuous*: every prefix of a valid date is bad input,
+so typing `2026-05-01` walks nine bad states before one good one. That makes
+it perfect for a gate you consult at the click and treacherous for anything
+that reacts per keystroke — an error message wired straight to it would flash
+red through the act of typing correctly. Ask at the moment you need the
+answer, and you always get the current one.
+
+Which fields carry it is decided by one question: *can my input be something
+my value cannot represent?* The numeric fields say yes, and the date field says
+yes so emphatically that it is the reason this mixin exists. A text field says no —
+its value *is* its input, so nothing can fail. A checkbox or a select says no
+for a different reason: there is nothing between the keystroke and the value
+for a parse to fail in.
+
+### Marking a field invalid
+
+Bad input is the field's *own* verdict — it owns the format, so it knows. A
+rule's verdict is a different animal: "at least 3 characters", "must be in the
+past", "these two passwords differ". The field cannot compute any of those. It
+cannot even see the sibling the last one compares against.
+
+So Tuile splits the job by *who has the cells for it*. The **verdict** — this
+field is invalid — fits the one row the field already owns, because it is a
+restyle of cells the field paints anyway. The **message** does not: it needs
+cells beside the field, which belong to whatever laid the field out. Hence
+{Tuile::Component::HasValidation}, which every field has:
+
+```ruby
+login.on_click = lambda do
+  username.error_message = username.empty? ? "Username is required" : nil
+  password.error_message = password.empty? ? "Password is required" : nil
+  next if [username, password].any?(&:error_message)
+
+  authenticate(username.value, password.value)
+end
+```
+
+Assigning a message turns the field's **well** red — `Theme#error_bg_color`,
+or `Theme#error_active_bg_color` while it has focus; assigning `nil` clears it.
+Notice there is no layout in that handler — it works the same inside a form, a
+`Layout::Vertical`, or a `Popup` — and no `invalid?` predicate: a non-nil
+message *is* the verdict, so there is only ever one thing to ask, and no
+ambiguity with `bad_input?` next door.
+
+A background rather than red text, for a reason worth spelling out: red text
+needs glyphs, and the commonest rule of all — *required* — fires on a field
+that has none. The well is what shows a field's boundary in the first place, so
+an invalid field gets a red one and loses nothing. It takes *two* colors
+because a focused invalid field still has to look focused; a `Select` paints no
+caret, so its well is the only focus indicator it has.
+
+Bad input reddens the well too, so a field you cannot save from looks like one
+whether the format or a rule is at fault. That does mean the well is *live*
+where the verdict is discrete: a `FloatField` goes red at the half-typed `1.`
+and back at `1.5`. Brief, and worth it — the well is telling you the field will
+refuse to save in that state.
+
+A `DateField` is where that stops being worth it, and the difference is
+instructive. Its residue is not one buffer but *all of them*: `2`, `20`, `202`
+are each bad input on the way to `2026-09-04`, so a live well would hold the
+field red from the first keystroke to the last, saying "you are wrong" when the
+truth is "you are not finished". So the date field **settles**: the well waits
+for a commit gesture — you leave the field, or press Enter — reddens what did
+not parse, and goes quiet again on your next edit. Only the *ink* waits.
+`bad_input?` is still answered from the current buffer the instant you ask it,
+which is what keeps the Save handler above correct with no change at all.
+
+The one discipline the writer owes is visible in those `: nil` branches: **set
+or clear on every pass.** Only assign the message where you validate, and a
+field that has been fixed goes back to normal on its own. Forget the clear and
+a corrected field stays red forever.
+
+To show the text, subscribe — and put it in cells you own:
+
+```ruby
+error = Component::Label.new
+username.on_error_message_change = ->(msg) { error.text = msg || StyledString::EMPTY }
+```
+
+That listener is not decoration. The field repaints *itself* when its verdict
+changes, but it knows nothing about your label, so without the notice your
+message would go stale.
+
+Two things follow from the split, both worth knowing before they surprise you.
+An **empty** invalid field has no glyphs to tint — which is exactly the
+required-field case — so on a bare pane the message *is* the whole signal; put
+it somewhere. And the ink is **inherited**, so a composed field like an
+`IntegerField` needs no help: the `TextField` inside it picks the color up from
+its parent, as do the rows of a `RadioGroup`'s list.
+
+Where does the caption go, then? The same rule answers it, in the other
+direction: a field can tint the row it has, but it cannot *add* a row for a
+label without displacing the value — so a field carries no caption at all. The
+`Label` beside it is yours (or, one day, a form layout's), which is why every
+form in this book builds its own captions.
+
+The sibling seam, one level up, is **which keys the field acts on at all**:
+override `handle_text_input_key` and call `super` for everything you don't
+claim.
+
+```ruby
+class SubmitField < Tuile::Component::TextArea
+  protected
+
+  def handle_text_input_key(key)
+    return super unless key == Tuile::Keys::ENTER
+
+    submit(text)     # Enter submits instead of inserting a newline
+    true
+  end
+end
+```
+
+Both seams are overrides rather than callbacks on purpose, and the reason is
+the same one that runs through this whole chapter: they *compose*. Two
+behaviors can stack through `super`, where one callback slot can only be held
+by one owner — and a key you decline still bubbles to an ancestor
+(chapter 5), which a callback that returned `false` could not arrange.
+
 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
@@ -283,7 +681,9 @@ widget then decorates, a row is the whole rendering.) It's the value seam doing
 `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
+and only a real commit fires `on_value_change`. Being a text field, it takes
+the editing keys above — Ctrl+U empties a query you want to start over in one
+press, rather than holding Backspace down. 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.
@@ -674,6 +1074,39 @@ 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*
@@ -769,44 +1202,70 @@ 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.
+### Two ways to hide something, and why a `TabSheet` picks the other one
+
+Here is the part with consequences beyond this widget. Hiding a component
+is one line:
+
+```ruby
+company_name.visible = false     # gone
+company_name.visible = true      # back, exactly as it was
+```
+
+The flag means **gone**, in the sense Android's `GONE` means it: the
+component paints nothing, takes no space in a box layout, and cannot be
+reached by Tab, keys, the cursor, the mouse or `Testing.find`. Say it as
+*as if detached, but it stays in the tree* — because the one thing it keeps
+that a detached component loses is the whole point. It keeps its parent, its
+rect, its box constraints, its state, and anything it had running: **no
+lifecycle hook fires**. A pane holding a subscription goes on holding it
+while out of sight.
+
+Two things it is worth being precise about. First, the flag is
+*ancestor-inclusive*: hide a panel and everything under it goes with it,
+whatever those components' own flags say — and their flags are remembered,
+so showing the panel brings back exactly the subtree that was showing
+before. Second, there is no "invisible but still occupying its space" state,
+because you already have one: a {Tuile::Component::Slot} with no content
+holds its rect open and paints nothing.
+
+The other way to hide something is to take it out of the tree, and it is
+what a `TabSheet` does: only the selected tab's pane is a child of the
+sheet, the rest are detached. That is a deliberate choice rather than
+history, and the reason is the sentence above about hooks — inverted:
+
+- **`on_detached` fires when a pane goes away, `on_attached` when it
+  returns.** A {Tuile::Component::ProgressBar} in a background tab stops its
+  ticker and restarts it on return, with no bookkeeping from you. Hiding
+  would keep it ticking, unseen.
+- **State survives either way, because state is ivars.** Scroll position,
+  caret, list cursor, typed text: all exactly as the user left them, hidden
+  or detached. You can go on mutating either — `invalidate` is a silent
+  no-op on a detached component, and a hidden one's repaint is dropped at
+  the drain.
+
+So the question to ask isn't "which is the real way to hide" but **should
+this thing keep running while nobody can see it?** If yes, hide it. If no —
+if you'd rather its ticker, its poller or its subscription stopped — detach
+it, and let the hooks do the work.
+
+One rule at the seam, worth knowing before you meet it as a bug: focus
+never stays on something the user cannot see. Hide the subtree that holds
+focus and it moves to the hidden component's parent, which passes it on to
+the first reachable field the same way it would after a removal. It is not
+handed back when the component reappears.
+
+An overlay is the exception: {Tuile::Component::Popup} and friends refuse
+`visible=` outright. An overlay is *closed*, not hidden — it already has
+`open` and `close` for exactly this, and a hidden-but-open modal would go on
+scoping every key and swallowing every click while painting nothing.
 
 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.
+under the sheet reports the row you left it on. The Shell → Visibility pane
+demonstrates the flag: tick "Business customer" and two more fields appear
+in the form, with the rows closing up cleanly when they go and the text you
+typed into them still there when they come back.
 
 ### When the strip is too narrow
 
@@ -1008,22 +1467,24 @@ every GUI dismisses its menus on a window resize too.
 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.
-
-**A left click outside a popup closes it**, modal or not — the same light
-dismissal a desktop dialog gives you. It's a per-popup switch,
-`close_on_outside_click`, on by default; a popup that must survive stray
+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.
@@ -1050,6 +1511,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
@@ -1105,18 +1676,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