tuile 0.11.0 → 0.13.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
@@ -219,11 +220,38 @@ read-only or required flag yet. Room left for that layer to grow into.
 
 ## Choosing from a set
 
-{Tuile::Component::List} is the workhorse: a scrollable column of
-{Tuile::StyledString} lines, ellipsized (spans preserved) when too wide.
-What makes it flexible is that its *cursor behavior is a pluggable object*
-rather than a boolean. Assign one of three {Tuile::Component::List::Cursor}
-variants to fit the interaction:
+{Tuile::Component::List} is the workhorse: a scrollable column of *items*
+— objects of whatever type your app deals in — one row each. You give it
+the items and a `renderer` that turns one item into a row, and it does the
+rest: ellipsizing a row too wide for the viewport (spans preserved),
+scrolling, and handing your callbacks back **the item itself** rather than
+the text it drew for it.
+
+```ruby
+list = Component::List.new
+list.items    = User.all
+list.renderer = ->(u) { "#{u.name}  #{u.email}" }
+list.cursor   = Component::List::Cursor.new
+list.on_item_chosen = ->(_index, user) { open(user) }
+```
+
+That's the same bargain the value seam struck earlier in this chapter: the
+component speaks in your objects, and nothing has to map a row of text
+back to the thing it stood for. When your items *are* the text, skip the
+renderer entirely — `list.lines = entries` takes strings (or
+{Tuile::StyledString}s, or anything with a `to_s`), splits them on
+newlines, and shows each as its own row.
+
+The renderer runs when a row is *painted*, and only for the rows actually
+on screen: a hundred-thousand-item list renders the twenty you can see.
+That's what makes a long list cheap, and it comes with one rule — keep the
+renderer a pure function of its item. It may be called on any frame, so it
+is the wrong place to reach for a database; do that work when you build
+the items.
+
+What makes the list flexible beyond that is that its *cursor behavior is a
+pluggable object* rather than a boolean. Assign one of three
+{Tuile::Component::List::Cursor} variants to fit the interaction:
 
 - **`Cursor::None`** (the default) — no cursor at all. The list is a
   read-only scroll region: a log, a static report.
@@ -234,29 +262,24 @@ variants to fit the interaction:
   lines. For a list where only some rows are selectable (headers
   interspersed with items, say), it skips the rest.
 
-Two callbacks cover the events you care about. `on_item_chosen` fires when
-the user commits to the cursor's row — Enter or a left-click — and is the
-"open this" signal. `on_cursor_changed` fires when the highlighted row
-*changes*, which is exactly what you wire to keep a details pane in sync
-with the selection. For a tailing list — a live log — set `auto_scroll`;
-it pins to the bottom as lines arrive, but politely stops yanking you down
-the moment you scroll up to read history, and resumes once you scroll back
-(`following?` tells you which). A scrollbar is one assignment
-(`scrollbar_visibility`).
-
-```ruby
-list = Component::List.new
-list.lines  = entries
-list.cursor = Component::List::Cursor.new
-list.on_item_chosen = ->(index, line) { open(entries[index]) }
-```
+Two callbacks cover the events you care about, and both are handed the
+`(index, item)` pair. `on_item_chosen` fires when the user commits to the
+cursor's row — Enter or a left-click — and is the "open this" signal.
+`on_cursor_changed` fires when the highlighted row *changes*, which is
+exactly what you wire to keep a details pane in sync with the selection.
+For a tailing list — a live log — set `auto_scroll`; it pins to the bottom
+as items arrive, but politely stops yanking you down the moment you scroll
+up to read history, and resumes once you scroll back (`following?` tells
+you which). A scrollbar is one assignment (`scrollbar_visibility`).
 
 When the set is long and the user roughly knows what they want, a plain
 list makes them scroll for it. {Tuile::Component::ComboBox} is the answer:
 a text field with a dropdown that filters as you type. Hand it `items` (of
 any type) and, when their `to_s` isn't what you want shown, an
 `item_label` strategy to render each one; type to narrow, arrow to move,
-Enter or click to accept. It's the value seam doing real work — its
+Enter or click to accept. (The domain widgets all call that strategy
+`item_label`, where a bare list calls it `renderer` — a label is text the
+widget then decorates, a row is the whole rendering.) It's the value seam doing real work — its
 `value` is the selected *item*, the object and not its label, so a combo
 over `User`s hands back a `User`. The field's text is merely a transient
 query: it reverts to the selection's label when you dismiss the dropdown,
@@ -356,10 +379,11 @@ coerced), and let the widget's own toggling build the new sets for you.
 Here the cursor and the selection are genuinely two different things — the
 cursor says *where you are*, the checkmarks say *what you picked* — and
 that shape is exactly what a list already provides. So a checkbox group
-doesn't paint rows itself; it holds a {Tuile::Component::List} and gets the
-cursor, the scrolling, the scrollbar and the per-row mouse handling for
-free, in the same "wrap a generic component to make a domain one" way the
-combo box wraps a text field. That inheritance goes further than
+doesn't paint rows itself; it holds a {Tuile::Component::List} of the
+items, supplies the renderer that puts a `[x]` or `[ ]` in front of each
+label, and gets the cursor, the scrolling, the scrollbar and the per-row
+mouse handling for free, in the same "wrap a generic component to make a
+domain one" way the combo box wraps a text field. That inheritance goes further than
 convenience: a click anywhere on a row toggles it, and Enter toggles the
 cursor's row, because those are the list's own gestures for choosing an
 item.
@@ -507,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
@@ -592,7 +659,7 @@ popups are for.
 
 The bottom border has two mutually exclusive uses, and the distinction is
 the top-down-layout principle from chapter 3 made concrete. `footer_text=`
-embeds decoration into the border line — chrome, mirroring the caption on
+embeds decoration into the border row — chrome, mirroring the caption on
 top, not focusable. `footer=` mounts a *real focusable component* spanning
 the full inner width — the search-field-in-the-border case. A footer
 component present takes the row and hides the text; neither drives the
@@ -607,6 +674,334 @@ window.content = Component::List.new.tap { _1.lines = entries }
 window.scrollbar = true
 ```
 
+## 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.
@@ -626,6 +1021,22 @@ 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
+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:
 
@@ -639,6 +1050,55 @@ 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.
 
+## Notifications
+
+{Tuile::Component::Notification} is the one overlay you don't assemble at
+all. It's the TTY toast: a message in the top-right corner that shows up,
+holds for three seconds, and removes itself.
+
+```ruby
+Component::Notification.show("Saved")
+Component::Notification.show("Disk almost full", color: Color::RED)
+```
+
+That class method is the *only* way in — `new` is private. The reason is
+worth understanding, because it's the design in one line: there is never
+more than one notification box on screen. `show` looks for the live one in
+the popups stack and appends to it, so a burst of messages stacks as
+entries inside a single frame:
+
+```
+                                            ┌──────────────┐
+                                            │Job 1 finished│  ← goes in 3 s
+                                            │Job 2 finished│  ← then this one
+                                            │Job 3 finished│
+                                            └──────────────┘
+```
+
+They then leave **one at a time**, oldest first, three seconds apart. This
+is the interesting half of the design. Five notifications raised in the
+same instant would, given five independent timers, appear and vanish
+together — a flash you have no chance of reading. Draining them one per
+tick means the burst takes fifteen seconds to clear and you read it in
+peace. A message arriving mid-cycle just waits its turn rather than
+restarting the clock, which is also what stops a steady trickle of
+notifications from keeping the box alive forever.
+
+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;
+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
+the screen — and at most five messages are held, after which the newest is
+dropped and reported to `Tuile.logger`. Both are deliberate: a notification
+is a glance, not a document, and an app with more to say than five short
+lines wants a LogWindow, which is next.
+
 ## Batteries-included windows
 
 The last three components are conveniences: common Window-plus-content

data/book/08-testing.md

@@ -28,10 +28,13 @@ after  { Screen.close }
 `Screen.fake` installs a {Tuile::FakeScreen} as the process singleton — a
 `Screen` subclass with the terminal amputated. It has a fixed 160×50
 viewport (so geometry is deterministic, independent of whoever's terminal
-runs the suite), it writes nothing to any TTY, its `check_locked` is a
-no-op so you can mutate the UI freely from the test thread without holding
-the UI lock, and its event queue is the synchronous {Tuile::FakeEventQueue}
-(more on that below). It also pins the color scheme to `:dark`, skipping
+runs the suite), it writes nothing to any TTY, and its event queue is the
+synchronous {Tuile::FakeEventQueue} (more on that below). You can mutate the
+UI directly from your example — and note there is no lock *bypass* doing
+that for you: the fake runs no loop, so `running?` is false and chapter 4's
+rule falls back to "the thread that created the screen," which is yours. A
+spec that mutates the UI from a **spawned** thread therefore raises, exactly
+as an app would. It also pins the color scheme to `:dark`, skipping
 the OSC 11 probe from chapter 6 — a probe would otherwise write an escape
 query to the test runner's terminal and swallow its input.
 
@@ -44,6 +47,17 @@ from nothing. Skip the `after` and you get the classic singleton test
 smell: passes in isolation, fails in suite, order-dependent. The pair is
 not boilerplate you can trim.
 
+One more line of setup earns its place if your app has a theme of its own. A
+fresh `Screen.fake` starts from the built-in {Tuile::ThemeDef}, so a
+component reading `theme[:my_token]` would `KeyError` in every example.
+Rather than assigning `Screen.instance.theme_def` in every `before` block,
+point the construction-time default at your definition once, in
+`spec_helper`:
+
+```ruby
+Tuile::ThemeDef.default = APP_THEME   # every Screen.fake now carries it
+```
+
 ## Asserting what got painted
 
 Here's where the back buffer earns its keep. Recall from chapter 2 that