tuile 0.16.0 → 0.17.0

data/book/05-focus.md

@@ -165,7 +165,7 @@ the tree — and neither needs machinery, because bubbling already has the
 right shape. **Put the key on the ancestor that owns the region.**
 
 ```ruby
-class AppLayout < Tuile::Component::Layout::Absolute
+class AppLayout < Tuile::Component::Layout
   def handle_key?(key)
     case key
     when "1" then @files.focus; true
@@ -233,7 +233,7 @@ single `PasteEvent` — which never enters the ladder at all:
 
 The default `handle_paste` returns `false` and the text is dropped.
 {Tuile::Component::AbstractStringField} overrides it to insert at the caret
-as **one** mutation — so `on_change` fires once for the paste rather than
+as **one** mutation — so `on_value_change` fires once for the paste rather than
 once per character, and a subclass that claims Enter needs no paste code of
 its own:
 
@@ -245,7 +245,7 @@ class PromptTextArea < Tuile::Component::TextArea
     return super unless key == Tuile::Keys::ENTER
 
     submit(text)   # a typed Enter, and only ever a typed Enter
-    self.text = ""
+    self.value = ""
     true
   end
 end
@@ -260,7 +260,7 @@ def handle_paste(text)
   return super if text.lines.size < 20
 
   attach_as_file(text)
-  self.text = "#{text.lines.size} lines attached"
+  self.value = "#{text.lines.size} lines attached"
   true
 end
 ```
@@ -346,8 +346,11 @@ one surface, and is why that app asks for `:hover`.
 ## Where the cursor comes in — and where it doesn't
 
 A component signals cursor ownership through
-{Tuile::Component#cursor_position} — return a `Point` and the terminal
-cursor is shown there; return `nil` (the default) and there's no cursor. A
+{Tuile::Component#cursor_position} — return a `Point` in your *own*
+coordinates (the ones you paint in) and the terminal cursor is shown there;
+return `nil` (the default) and there's no cursor. {Tuile::Screen} is what
+converts the point to a screen position, so a caret is a column and a row and
+nothing more. A
 {Tuile::Component::TextField} being edited returns its caret position, so
 the caret you see blinking is the focused component's answer to that one
 question.
@@ -378,7 +381,7 @@ to tidy up what was typed, this is where:
 
 ```ruby
 class TrimmedField < Tuile::Component::TextField
-  protected def handle_blur = (self.text = text.strip)
+  protected def handle_blur = (self.value = text.strip)
 end
 ```
 
@@ -438,10 +441,10 @@ is text you write next to the registration.
 
 Some apps genuinely show different keys in different places — a window with
 a search mode, or a pane whose commands only apply to it. For those,
-{Tuile::Screen#on_focus_changed=} is the notification:
+{Tuile::Screen#on_focus_changed} is the notification:
 
 ```ruby
-screen.on_focus_changed = -> { status.text = hint_for(screen.focused) }
+screen.on_focus_changed { status.text = hint_for(screen.focused) }
 ```
 
 It fires after every focus *change* — to and from `nil` included, and after

data/book/06-theming.md

@@ -90,17 +90,17 @@ prompt. You *can* name the panel's colour again on the field — but there is a
 shorter way to say "I have no background of my own, use whatever is behind me":
 
 ```ruby
-field.bg_color = Component::BG_INHERIT
+field.bg_color = ComponentBackground::INHERIT
 ```
 
 That is CSS's `background: inherit`, and it is different from leaving
 `bg_color` unset: unset means "ask *my* default first", which for a field is
-its well. `BG_INHERIT` skips the well and goes straight to what surrounds it.
+its well. `ComponentBackground::INHERIT` skips the well and goes straight to what surrounds it.
 
 It is the same mechanism Tuile uses internally. A
 {Tuile::Component::ComboBox} is one widget with one surface, built out of a
 {Tuile::Component::TextField} plus a `▾` — so the ComboBox paints the well and
-marks its inner field `BG_INHERIT`. Exactly one well per widget, which is what
+marks its inner field `ComponentBackground::INHERIT`. Exactly one well per widget, which is what
 lets you tint the ComboBox and have the tint reach the cells the field draws.
 
 Backgrounds can differ by state. An input is brighter while it holds focus,
@@ -238,12 +238,30 @@ background, and Tuile has it: the OSC 11 reply carries the RGB, and
 {Tuile::Screen}`#background_color` hands it to you as a
 {Tuile::Color}.
 
+The place to use it is the theme itself. A token may be a Proc of the
+background instead of a fixed {Tuile::Color}, and the screen calls it for
+you:
+
 ```ruby
-bg = Tuile::Screen.instance.background_color
-sidebar.bg_color =
-  bg ? Tuile::Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }) : FALLBACK_TINT
+LIFT = ->(color, by) { Tuile::Color.rgb(*color.rgb.map { (_1 + by).clamp(0, 255) }) }
+
+APP_THEME = Tuile::ThemeDef.new(
+  dark: Tuile::Theme::DARK.with(custom: {
+    pane_bg:    ->(bg) { bg ? LIFT.call(bg, 10) : FALLBACK_TINT },
+    pane_frame: ->(_bg, t) { LIFT.call(t[:pane_bg], 20) }
+  }),
+  light: …
+)
+screen.theme_def = APP_THEME
+sidebar.bg_color = Tuile::Theme.ref(:pane_bg)
 ```
 
+The arithmetic is yours — Tuile ships no `lighten`, because how far to
+step, in which direction, and whether to step at all is a design choice,
+not a fact about the terminal. The second parameter, when a Proc asks for
+it, reads the other tokens, so a hairline can be derived from the pane it
+sits on, whatever order you declared them in.
+
 That `FALLBACK_TINT` is not defensive padding — it's the branch you
 should expect to hit. Plenty of terminals answer neither probe, and the
 `COLORFGBG` fallback reports a palette *index* with no RGB behind it, so
@@ -256,12 +274,21 @@ more round trip than you might expect. The mode-2031 report says only
 "the OS is light now" — it carries no RGB — so when the screen sees one,
 it writes the OSC 11 query again, and the reply comes back through the
 key thread as another event. The new color therefore lands a frame after
-the new theme. When it does, Tuile fires
-{Tuile::Component}`#handle_theme_changed` across the tree exactly as a theme
-swap does, on the reasoning that a tint derived from the background *is*
-a theme-derived color, and that hook is already where you rebuild those.
-So the same override handles both halves of a flip, and you don't need to
-know which one woke you.
+the new theme. When it does, the screen calls every derived token again,
+producing a fresh, fully concrete {Tuile::Screen}`#theme`, and fires
+{Tuile::Component}`#handle_theme_changed` across the tree once, exactly as a
+theme swap does. A `Theme.ref` slot follows with no code of yours; content
+you baked from the theme rebuilds in the same hook it always did, and you
+don't need to know which half of the flip woke you.
+
+Why a Proc in the theme, rather than a color that knows how to recompute
+itself? Because {Tuile::Color} is a value: the back buffer decides whether a
+cell changed by comparing colors, and a color that answered differently
+depending on the terminal would compare equal to itself while painting
+something new. Deriving once, when the inputs change, keeps every color
+Tuile paints with a plain value — and the tree walks once per change,
+instead of an app re-assigning its theme from inside the very hook the
+walk is calling.
 
 ## Not every terminal can show what you computed
 
@@ -445,16 +472,27 @@ attached component whenever the theme changes. Your handler does exactly
 one thing: **re-run the code that rendered the content**, so it rebuilds
 the StyledString against the now-current theme.
 
-There are two ways to consume it, matching how you built the component,
-and they are two different method names — the `=` tells them apart. If you
-assembled stock components, assign the `on_theme_changed=` **listener slot**:
+There are two ways to consume it, matching how you built the component, and
+they are two different names: `on_` for the slot, `handle_` for the override. If
+you assembled stock components, register on the `on_theme_changed` **listener
+slot** — the reader *is* the registrar, and a slot holds as many listeners as
+you give it:
+
+```ruby
+label.on_theme_changed { label.text = render_status_line }
+```
+
+There is no `on_theme_changed=`, deliberately: nothing you register can displace
+what the widget — or another part of your app — already wired there. Hold what
+`on_theme_changed` returns you if you mean to take it back off later:
 
 ```ruby
-label.on_theme_changed = -> { label.text = render_status_line }
+cb = label.on_theme_changed { … }
+label.on_theme_changed.remove(cb)
 ```
 
 If you subclassed, override `handle_theme_changed`, the **override point**
-— and call `super`, so an assigned listener still fires:
+— and call `super`, so registered listeners still fire:
 
 ```ruby
 class StatusLabel < Tuile::Component::Label

data/book/07-components.md

@@ -117,9 +117,9 @@ 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. `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
+Both inherit the same event hooks from the base. `on_value_change` fires
+whenever the text changes; `on_escape` reacts to ESC; `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
@@ -127,14 +127,26 @@ keys *do*, you subclass (see *Keeping input out of a field*, below).
 
 ```ruby
 field = Component::TextField.new
-field.on_change = ->(text) { filter_results(text) }
-field.on_enter  = -> { submit }        # nil (default) → Enter bubbles to the parent
+field.on_value_change { |e| filter_results(e.value) }
+field.on_enter { submit }              # empty (default) → Enter bubbles to the parent
 ```
 
-Note that `on_enter` / `on_key_up` / `on_key_down` on a TextField, when
-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.
+Note that `on_enter` / `on_key_up` / `on_key_down` on a TextField, while
+*empty*, 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. Register a listener and the field starts consuming the
+key; remove it again and the key bubbles once more.
+
+ESC is the one that does not start out falling through, because a field blurs
+on it — cancelling text entry rather than quitting the app. That blur is
+`escape_clears_focus`, a flag rather than a listener sitting in the slot, so an
+`on_escape` listener runs *beside* it. Turn the flag off to give ESC another
+meaning outright, and with the slot empty as well ESC bubbles like the rest:
+
+```ruby
+field.escape_clears_focus = false
+field.on_escape { close_search_row }    # ESC closes the row; focus stays put
+```
 
 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
@@ -249,7 +261,7 @@ the value, and stays silent.
 
 ```ruby
 qty = Component::IntegerField.new
-qty.on_value_change = ->(n) { recompute(n) }  # n is an Integer, or nil
+qty.on_value_change { |e| recompute(e.value) }  # e.value is an Integer, or nil
 qty.value = 3
 ```
 
@@ -501,7 +513,7 @@ 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
+login.on_click 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)
@@ -567,7 +579,7 @@ 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 }
+username.on_error_message_change { |e| error.text = e.error_message || StyledString::EMPTY }
 ```
 
 That listener is not decoration. The field repaints *itself* when its verdict
@@ -583,9 +595,65 @@ 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.
+label without displacing the value — so a field carries no caption at all. Those
+cells belong to whatever surrounds the field, and
+{Tuile::Component::FormItem} is that surround: one row of a form, around one
+field.
+
+```ruby
+item = Component::FormItem.new(username, caption: "Username", required: true)
+```
+
+```
+   Username ∙            ← the caption, with the required marker
+   [________________]    ← the field you wrapped
+   Must not be blank     ← the message, when there is one
+```
+
+The item does the subscribing you just saw — to the verdict *and* to the field's
+own report of input it cannot parse — so the label-and-listener pair is what you
+write when the message belongs somewhere else entirely, one status row for a
+whole form, say. Otherwise wrap a field and drop the item wherever a component
+goes: a `Vertical` of items is already a form.
+
+It is always three rows, and the last is the message row *and* the gap row. That
+fusion is the point: a form that grew a row when a field went invalid would push
+everything below it down while you are typing into it, and on a 24-row terminal
+that walks the focused field off the bottom edge. The price is that a form with
+several errors looks tight exactly where it is least happy.
+
+Two habits follow. A widget that paints its own text — a `Checkbox`, a `Button` —
+is wrapped *without* a caption and reserves no caption row, because the form owns
+a column and the widget owns its face; move `[x] Enable logging` into the column
+and the checkbox has nothing left to say. And hide the **item**, never the field:
+`item.visible = false` takes the caption and the message with it, where hiding
+the field alone strands its caption above a gap.
+
+Stack items and you have a form. {Tuile::Component::FormLayout} is that column,
+and it does the wrapping for you:
+
+```ruby
+form = Component::FormLayout.new
+form.add(username, caption: "Username", required: true)
+item = form.add(notes, caption: "Notes", rows: 5)   # rows: is the *content* height
+form.add(logging)                                   # a Checkbox, so no caption row
+form.add(save)                                      # nor does a Button
+```
+
+Everything it holds is a `FormItem` — `add` returns the one it built, so
+`item.required = true` later goes to the right receiver — and the arithmetic is
+one line: a captioned item is `1 + rows + 1` rows tall, a captionless one
+`rows + 1`. There is no `spacing`, because the message row already *is* the gap;
+a looser form is a `Vertical` of several `FormLayout`s, and a tighter one isn't
+available.
+
+Two things it deliberately won't do. It **measures nothing** — `rows:` is yours
+to declare, exactly as `Fixed[n]` is in a `Vertical`, because a field that could
+ask for a height is the bottom-up channel chapter 3 doesn't have. And it
+**doesn't scroll**: items are laid from the top, the one straddling the bottom
+edge keeps the rows that are left, and anything past it is clipped away. A form
+taller than its rect either wants splitting — across a `TabSheet`, say — or
+wants wrapping in a `Scroller`, later in this chapter.
 
 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
@@ -631,8 +699,9 @@ Turning a field's value into a domain model — parsing, validation, the
 box-holds-a-`String` ⟷ bean-holds-an-`Integer` conversion — is
 deliberately *not* the field's job; it belongs to a forms/binder layer
 that will one day sit above these components. So the seam is kept thin on
-purpose: `on_value_change` carries just the new value, and there's no
-read-only or required flag yet. Room left for that layer to grow into.
+purpose: the event `on_value_change` carries just the new value and its
+source, and there's no read-only or required flag yet. Room left for that
+layer to grow into.
 
 ### Two fields, one value
 
@@ -681,9 +750,9 @@ the text it drew for it.
 ```ruby
 list = Component::List.new
 list.items    = User.all
-list.renderer = ->(u) { "#{u.name}  #{u.email}" }
+list.renderer = ->(u, _w) { "#{u.name}  #{u.email}" }
 list.cursor   = Component::List::Cursor.new
-list.on_item_chosen = ->(_index, user) { open(user) }
+list.on_item_chosen { |e| open(e.item) }
 ```
 
 That's the same bargain the value seam struck earlier in this chapter: the
@@ -700,6 +769,25 @@ 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.
 
+That second parameter is the width, in columns, that the row you return
+will get — the list's own width, less a gutter either side and less the
+scrollbar's column when one is showing. Most renderers ignore it and let
+the list ellipsize what doesn't fit, which is why it is usually spelled
+`_w`. Take it when the *shape* of a row depends on how much room there is:
+a right-hand column that has to line up down the pane, or a path you want
+cut from the *left* so its tail survives (`ellipsize(n, at: :start)` —
+`…/shared/markdown/` tells you more than `lib/shared/mar…`). Note the
+direction: the list divides up the space it was given and tells you your
+share, and never asks how much you would like.
+
+There is one place that can bite. The list re-runs the renderer on every
+width change — that is what keeps the columns lined up after a resize, and
+it costs only the rows on screen — but it re-runs it *per row*. So a
+measurement over the whole collection, like "how wide is the widest
+`+12/-3` in this snapshot", is computed once where you assign the items and
+closed over. Compute it inside the renderer and you have written an
+`items²` pass that fires on every drag of the terminal's edge.
+
 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:
@@ -713,9 +801,9 @@ pluggable object* rather than a boolean. Assign one of three
   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, 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.
+Two slots cover the events you care about, and both are handed an event
+carrying `position` and `item`. `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
@@ -745,7 +833,7 @@ when it's near the bottom of the screen.
 combo = Component::ComboBox.new
 combo.items = User.all
 combo.item_label = ->(u) { u.full_name }
-combo.on_value_change = ->(u) { show(u) }
+combo.on_value_change { |e| show(e.value) }
 ```
 
 When the choice is simply yes-or-no, {Tuile::Component::Checkbox} is a
@@ -760,7 +848,7 @@ however you flip it.
 
 ```ruby
 cb = Component::Checkbox.new("Enable syslog forwarding", value: true)
-cb.on_value_change = ->(on) { config.syslog = on }
+cb.on_value_change { |e| config.syslog = e.value }
 cb.toggle       # unchecks it, firing the listener with false
 ```
 
@@ -809,7 +897,7 @@ is the `Set` of items you selected.
 ```ruby
 levels = Component::CheckboxGroup.new(items: LogLevel.all)
 levels.item_label = ->(l) { l.name }
-levels.on_value_change = ->(set) { refilter(set) }   # a Set of LogLevels
+levels.on_value_change { |e| refilter(e.value) }     # e.value is a Set of LogLevels
 ```
 
 Notice what `value` holds: the *items*, exactly as the combo box does — a
@@ -867,7 +955,7 @@ the same widget with a single answer.
 ```ruby
 sort = Component::RadioGroup.new(items: SORT_ORDERS)
 sort.item_label = ->(order) { order.label }
-sort.on_value_change = ->(order) { resort(order) }
+sort.on_value_change { |e| resort(e.value) }
 ```
 
 Its `value` is the selected item — the object, not its label, as always —
@@ -922,7 +1010,7 @@ you're choosing between them.
 
 ```ruby
 level = Component::Select.new(items: %w[debug info warn error], value: "warn")
-level.on_value_change = ->(l) { logger.level = l }
+level.on_value_change { |e| logger.level = e.value }
 ```
 
 Enter, Space or Down opens the dropdown, the arrows move the highlight,
@@ -991,14 +1079,14 @@ 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
+save.on_click { form.submit }        # or register 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.
+Space and a left click all fire `on_click`, and its event carries nothing but
+its `source` — a button has nothing else 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
@@ -1160,6 +1248,48 @@ 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.
 
+### Showing more than fits: `Scroller`
+
+A slot sizes its occupant to itself. A {Tuile::Component::Scroller} does the
+opposite: it gives its content *more* rows than it has, and shows a window onto
+them.
+
+```ruby
+form = Component::FormLayout.new
+# …nine fields, 27 rows of them…
+window.content = Component::Scroller.new(form, content_rows: 27)
+```
+
+`content_rows` is the part that looks odd at first, and it is the same rule as
+everywhere else in this book: **nothing measures**, so the number is yours to
+supply, exactly as `rows:` and `Fixed[n]` are. The form is then handed a rect 27
+rows tall inside a viewport that may be 12 — the first rect in Tuile *meant* not
+to fit its parent, and, once you scroll, the first with a negative `top`.
+Nothing goes wrong, because every component is bounded by the rect it was given
+and its ancestors': the rows above and below the viewport are painted into
+nothing (chapter 2). Below the viewport height the number is ignored and the
+content simply fills the viewport.
+
+What makes it usable is that it scrolls **on focus**. A field scrolled out of
+sight is not hidden — it keeps its rect, its keys and its place in the Tab cycle
+(chapter 5) — so Tab reaches the eighth field as readily as the first, and
+`Screen#focused=` then makes the same request your own code can make:
+
+```ruby
+field.scroll_to_visible                    # "show me this"
+editor.scroll_to_visible(caret_row_rect)   # or just this much of me
+```
+
+It climbs the parent chain to the nearest scroller, which scrolls the minimum
+distance that makes the rect visible and passes the request on to whatever
+scrolls above it.
+
+The wheel scrolls it too, and `scroll_half_page_up` / `scroll_half_page_down`
+are there for app code. What it deliberately does **not** do is claim keys: the
+arrows and PgUp/PgDn belong to the field you are typing in. Content with no tab
+stop anywhere in it — a long label, a read-only panel — therefore has no
+keyboard way to scroll; bind one yourself on the container around it.
+
 ## Switching between views
 
 When a screen has more content than fits and the parts are *alternatives*
@@ -1173,7 +1303,7 @@ is selected.
 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}" }
+sheet.on_tab_selected { |e| status.text = "on #{e.tab&.caption}" }
 ```
 
 The strip is a component in its own right, {Tuile::Component::Tabs}, and
@@ -1419,11 +1549,28 @@ other TUI toolkit agree on it:
 | 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.
+| **In a menu you stepped to** | |
+| Down, Enter, Space | move onto its first row |
+| Up | move onto its last row |
+| Left, Right | keep walking the strip |
+| ESC, on an item with no menu | leave menu mode |
+
+Stepping sideways only *shows* the neighbour's menu: it arrives with no row
+highlighted, so the next Right goes on walking the strip instead of drilling
+into whatever that menu happens to list first. Down, Enter or Space moves onto
+its first row, Up onto its last.
+
+It never presses anything, either. 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.
+
+A button has no menu to show, and the walk carries on across it. What the arrows
+follow is *menu mode*: the bar enters it when a menu opens and leaves it when the
+last panel goes — or when you press ESC at a button, where there is no panel left
+to close. That ESC is the one the strip keeps from your app, which matters
+because an unhandled one quits (chapter 5). Enter on a button fires it and enters
+no mode at all.
 
 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
@@ -1532,8 +1679,9 @@ 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.
+lifecycle, same outside-click dismissal, but it sits where you open it —
+`overlay.open(Overlay::At[rect])` — 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,
@@ -1626,7 +1774,7 @@ 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.on_dismiss { stay_put }
 dialog.open
 ```