tuile 0.14.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.
@@ -802,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
 

data/book/08-testing.md

@@ -95,6 +95,84 @@ lives in the buffer; cursor behavior lives in `prints`. Keeping the two
 apart is deliberate, and mixing them up is the most common way a first
 Tuile test goes wrong.
 
+## Finding the component to drive
+
+Asserting on the buffer needs a `rect`; driving a component needs the
+component itself. For a two-line test you have it already — you just built
+it. The awkward case is the one that shows up as soon as an app grows: the
+widget you want to poke is four levels down inside something a *builder
+method* assembled, and the test never held a reference to it.
+
+{Tuile::Testing} is the answer. `Testing.get` walks the tree and returns the
+one component matching a spec:
+
+```ruby
+Testing.get(Component::Button, caption: "Save").handle_key(Keys::ENTER)
+Testing.get(id: :amount).value = 42
+```
+
+The spec is a class, an `id`, a caption, a block, or any combination of
+them — never a path through the hierarchy, which would break every time you
+nested one more layout. The class slot also takes a *mixin*, which is where
+the `Has*` family from chapter 7 pays off a second time:
+`Testing.find(Component::HasBadInput)` finds every field in the tree whose
+parse can fail, whatever their classes.
+
+The `id` in that second line is a plain `Symbol` tag you set on any
+component, purely so a test can ask for it back:
+
+```ruby
+amount = Component::IntegerField.new
+amount.id = :amount           # nothing paints this, and nothing reads it
+```
+
+`get` is strict on purpose: it raises unless *exactly one* component
+matches. That is the whole feature. The obvious thing to write by hand is a
+walk that takes the first match —
+
+```ruby
+combo = nil
+window.on_tree { |c| combo ||= c if c.is_a?(Component::ComboBox) }
+```
+
+— and the day the pane grows a second `ComboBox`, that silently re-points
+your test at a different widget. Nothing fails; the assertions just start
+describing something else. `get` calls that ambiguity what it is, and the
+failure comes with a dump of the tree it searched:
+
+```
+expected 1 Component::ComboBox, found 2
+searched:
+  #<ScreenPane rect=(0,0 160x50)>
+    #<Window rect=(0,0 40x10) caption="Settings">
+→     #<ComboBox rect=(1,1 38x1) value=nil>
+→     #<ComboBox rect=(1,2 38x1) value="dark">
+```
+
+Which usually tells you the fix immediately: narrow the search. Every
+lookup takes `in:` to scope it to a subtree, and by default searches the
+whole screen — popups included, since chapter 1's pane holds them under the
+same root as the content.
+
+```ruby
+Testing.get(Component::ComboBox, in: sampler.demo_window)
+```
+
+Its sibling `Testing.find` returns *all* matches as an array, and takes an
+optional `count:` — an Integer for exactly, a Range for a bound — so an
+assertion about how many of something exists is one call:
+
+```ruby
+Testing.find(Component::Checkbox, in: form, count: 3)   # raises unless 3
+```
+
+Two habits worth forming. Call these qualified, as `Testing.get(...)`:
+`find` and `get` are the most collision-prone names in a spec suite, so
+Tuile deliberately neither installs them on `Component` nor asks you to mix
+the module in. And remember this is *additive* — it makes driving a tree
+terser, and changes nothing about the assertion channel. What a component
+*shows* is still asserted on the buffer.
+
 ## Driving the system
 
 There are two altitudes at which you feed input, and picking the right one