tuile 0.15.0 → 0.16.0

data/book/04-event-loop.md

@@ -188,28 +188,28 @@ class Spinner < Tuile::Component::Label
 
   protected
 
-  def on_attached
+  def handle_attached
     @ticker = screen.event_queue.tick_fps(8) { |n| self.text = FRAMES[n % FRAMES.size] }
   end
 
-  def on_detached
+  def handle_detached
     @ticker&.cancel
     @ticker = nil
   end
 end
 ```
 
-`on_attached` fires the moment this component's tree is mounted on the
-screen; `on_detached` fires the moment it's unmounted. Add the spinner to a
+`handle_attached` fires the moment this component's tree is mounted on the
+screen; `handle_detached` fires the moment it's unmounted. Add the spinner to a
 popup and it starts; close the popup and it stops. Nothing at the call site
 remembers anything — `popup.close` is the whole teardown.
 
-The contract is a mirror: **`on_attached` starts what `on_detached` stops.**
+The contract is a mirror: **`handle_attached` starts what `handle_detached` stops.**
 Keep both cheap and idempotent, because a component *moved* from one parent
-to another gets `on_detached` and then `on_attached` — between those two
+to another gets `handle_detached` and then `handle_attached` — between those two
 calls it genuinely is off the screen, possibly for a long time, so stopping
 and restarting is the honest thing to do. And whatever you acquire in
-`on_attached` you must release in `on_detached`, because nothing else will.
+`handle_attached` you must release in `handle_detached`, because nothing else will.
 
 This generalizes well beyond tickers, and the interesting case is
 subscriptions. A component may depend on a service, but a service must never
@@ -226,11 +226,11 @@ class BuildStatus < Tuile::Component::Label
 
   protected
 
-  def on_attached
+  def handle_attached
     @subscription = @service.on_change { |s| screen.event_queue.submit { self.text = s } }
   end
 
-  def on_detached
+  def handle_detached
     @subscription&.unsubscribe
     @subscription = nil
   end
@@ -245,16 +245,16 @@ screen, and no view-closing code path has to know that the subscription
 exists at all.
 
 `screen.close` counts as unmounting, so the `screen.close` at the end of
-your `main` gives every component still on screen its `on_detached` — the
+your `main` gives every component still on screen its `handle_detached` — the
 tickers stop, the subscriptions come off, and you didn't write any of that
 teardown. What *doesn't* fire is a process that exits without closing the
 screen at all: these are lifecycle hooks, not destructors, and Tuile
-installs no `at_exit`. If your `on_detached` does something that matters
+installs no `at_exit`. If your `handle_detached` does something that matters
 beyond the process — flushing a file, say — close the screen deliberately
 rather than relying on exit.
 
 The other thing the hooks are not is a place to do layout. When
-`on_attached` runs, your parent hasn't assigned your `rect` yet. If you need
+`handle_attached` runs, your parent hasn't assigned your `rect` yet. If you need
 to paint, invalidate here and do the work in `repaint`, which is what
 chapter 2 was about anyway.
 

data/book/05-focus.md

@@ -43,12 +43,12 @@ they're independent on purpose.
 target *at all*. It's `false` by default — a {Tuile::Component::Label} is
 decoration; clicking one shouldn't yank focus away from the window around
 it. Controls that accept input (a text field, a list, a button) override
-it to `true`. This gate is what makes click-to-focus sane: clicking lands
-focus on the component under the cursor *only if it's focusable*,
-otherwise the click is ignored for focus purposes. A click descends the
-tree — every component whose rectangle contains the point sees it, outermost
-first — so "the component under the cursor" is really all of them, and focus
-settles on the deepest focusable one. The same rule governs
+it to `true`. This gate is what makes click-to-focus sane: a press lands
+focus on the component under the pointer *only if it's focusable*,
+otherwise it is ignored for focus purposes. The router resolves a path
+down the tree — every component whose rectangle contains the point, outermost
+first — so "the component under the pointer" is really all of them, and focus
+settles on the deepest focusable one, before any handler runs. The same rule governs
 the automatic focus-forwarding a container does when it's focused — a
 window handed focus passes it down to its content, but only if that
 content is focusable.
@@ -111,7 +111,7 @@ sees the key. These are for app-wide actions — "Ctrl+L opens the log,"
 
 ```ruby
 screen.register_global_shortcut(Tuile::Keys::CTRL_L,
-                                hint: "^L #{screen.theme.hint("log")}") do
+                                hint: "^L #{screen.theme.fg(:hint, "log")}") do
   log_popup.open
 end
 ```
@@ -128,15 +128,15 @@ left is yours: control keys, ESC, PgUp/PgDn, function keys. A shortcut can
 opt to fire even while a modal popup is open (`over_popups: true`); by
 default it's suppressed while a popup is up, so the popup stays modal.
 
-**3. `handle_key`, delivered to focus and bubbling up.** Everything else
-goes to the focused component's {Tuile::Component#handle_key}, and if that
+**3. `handle_key?`, delivered to focus and bubbling up.** Everything else
+goes to the focused component's {Tuile::Component#handle_key?}, and if that
 returns `false` (didn't handle it), the key bubbles up the ancestor chain —
 the focused component, then its parent, then *its* parent — until someone
 returns `true` or the scope root is reached. This is how a list handles
 arrow keys itself but lets an unhandled key rise to the window around it.
 
 A component only ever receives a key when it's on the focus chain, so
-`handle_key` implementations act on the key alone — they never need to
+`handle_key?` implementations act on the key alone — they never need to
 check their own `active?` state. And if focus is `nil`, or sits outside
 the current modal scope, delivery reaches no one: that's precisely what
 makes an open modal popup modal.
@@ -166,7 +166,7 @@ right shape. **Put the key on the ancestor that owns the region.**
 
 ```ruby
 class AppLayout < Tuile::Component::Layout::Absolute
-  def handle_key(key)
+  def handle_key?(key)
     case key
     when "1" then @files.focus; true
     when "2" then @log.focus; true
@@ -214,7 +214,7 @@ Ask a terminal to paste eight lines and, by default, it types them at your
 program: one byte at a time, with every line break converted to `\r`. That
 `\r` is byte-identical to the Enter you press with your finger. So a prompt
 that rebinds Enter to "submit" submits eight times, and no amount of
-cleverness in `handle_key` can tell the two apart — by the time the key
+cleverness in `handle_key?` can tell the two apart — by the time the key
 arrives, the information is gone.
 
 The fix has to happen one layer down, at the code that talks to the
@@ -224,7 +224,7 @@ private mode 2004), which asks the terminal to wrap pasted text in
 marker, reads the payload raw up to the terminator, and posts it as a
 single `PasteEvent` — which never enters the ladder at all:
 
-- no Tab traversal, no global shortcuts, no `handle_key`;
+- no Tab traversal, no global shortcuts, no `handle_key?`;
 - straight to {Tuile::Component#handle_paste} on the focused component —
   and *only* it: unlike a key, a paste does not bubble to ancestors, because
   the reasons a key does are all about scope-wide bindings and none of them
@@ -241,7 +241,7 @@ its own:
 class PromptTextArea < Tuile::Component::TextArea
   protected
 
-  def handle_text_input_key(key)
+  def handle_text_input_key?(key)
     return super unless key == Tuile::Keys::ENTER
 
     submit(text)   # a typed Enter, and only ever a typed Enter
@@ -273,10 +273,76 @@ disagree about whether a bracketed line break is `\r`, `\r\n` or `\n`, so
 Tuile settles on `\n` before the text reaches a component.
 
 `run_event_loop(bracketed_paste: false)` turns the mode off, the same way
-`capture_mouse: false` turns off mouse tracking. Then a paste is keystrokes
+`capture_mouse: false` turns off mouse tracking — the next section has that
+knob's other settings. Then a paste is keystrokes
 again, with the ambiguity that implies — reach for it only if a terminal
 mishandles the mode.
 
+## The mouse takes a different road
+
+A key goes to whoever has focus. A press goes to whoever is *under the
+pointer*, which is a different question with a different answer, so the
+mouse has its own dispatcher — {Tuile::Mouse::Router} — and its own
+handlers. Components no longer walk the tree for it at all:
+
+```ruby
+class Tile < Component
+  def handle_mouse_down?(event)          # claims the press, and is then grabbed
+    return false unless event.button == :left
+
+    flip
+    true
+  end
+end
+```
+
+The router resolves a path first: the topmost popup containing the point,
+else the tiled content (a modal popup eats everything outside itself), then
+down through the children whose rects contain it. A left press **focuses the
+innermost focusable on that path before any handler runs** — you never write
+click-to-focus, and you cannot forget it. Then `handle_mouse_down?` is
+offered to the innermost component and **bubbles outward until one answers
+`true`**, exactly as a key bubbles up the focus chain. A wheel notch travels
+the same road through `handle_mouse_scroll?`, which is why a `List` scrolled
+to its top answers `false` and lets the pane behind it scroll instead.
+
+Two things follow that are easy to miss. **Geometry is the router's job, not
+yours**: a widget that declared an `extent` (chapter 7) only sees presses
+inside it, so a press on a `Button`'s blank tail focuses the button and fires
+nothing — no hit test in your code. And **whoever claims a press is
+*grabbed***: until the button comes up, `handle_mouse_up` and
+`handle_mouse_drag` go to that component wherever the pointer travels,
+including well outside its own rect — which is what keeps a fast drag from
+escaping the widget that started it. There is no `grab_mouse` and no
+`release_mouse` to call: the claim *is* the request.
+
+Because a release can be lost — over ssh, over tmux — a widget **activates on
+the press**, never on a synthesized click, and the grab also ends on the next
+press or on any keystroke. Treat `handle_mouse_up` as press feedback and
+drag-ending, never as the thing that runs the action.
+
+How much of this the terminal ever sends is the `capture_mouse:` ladder, each
+rung a superset of the one before:
+
+```ruby
+screen.run_event_loop(capture_mouse: false)     # nothing; native select-to-copy
+screen.run_event_loop                           # == :clicks — presses, releases, the wheel
+screen.run_event_loop(capture_mouse: :drag)     # + motion while a button is held
+screen.run_event_loop(capture_mouse: :hover)    # + motion with none, and enter/exit
+```
+
+`:hover` adds `handle_mouse_move?` and the argument-less
+`handle_mouse_enter` / `handle_mouse_exit` pair, along with
+{Tuile::Screen#hovered}. Ask for it only if something uses it: a terminal
+reports up to ~84 moves a second. And keep whatever hover does *cosmetic* —
+no terminal reports the pointer leaving the window, so an exit may arrive
+very late, or never.
+
+The rung is one app-wide choice, made here and nowhere else — so a component
+that overrides a hover hook under a lower rung simply never hears from it, with
+nothing to warn you. The sampler's *Mouse* pane answers all seven handlers on
+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
@@ -296,23 +362,23 @@ declaration in the system.
 ## A component that reacts to its own focus
 
 Two hooks tell a component about itself, and a component overrides them —
-nothing else calls them. {Tuile::Component#on_focus} fires when it gains
-focus; {Tuile::Component#on_blur} fires when it loses it. Both fire on that
+nothing else calls them. {Tuile::Component#handle_focus} fires when it gains
+focus; {Tuile::Component#handle_blur} fires when it loses it. Both fire on that
 one component, never on the ancestors that light up and go dark with it.
 
-`on_focus` is the forwarding hook. It's how a {Tuile::Component::Window}
+`handle_focus` is the forwarding hook. It's how a {Tuile::Component::Window}
 handed focus passes it to its content, and how a {Tuile::Component::Layout}
 skips ahead to the first tab stop underneath it — which is also why it fires
 on *every* assignment, even one that re-focuses what's already focused.
 
-`on_blur` is the commit point. Nothing else in Tuile is one: Tab is
+`handle_blur` is the commit point. Nothing else in Tuile is one: Tab is
 unconditional, so a user leaving a half-finished field usually leaves by a
 key no component ever sees, and `on_enter` never fires. If your field wants
 to tidy up what was typed, this is where:
 
 ```ruby
 class TrimmedField < Tuile::Component::TextField
-  protected def on_blur = (self.text = text.strip)
+  protected def handle_blur = (self.text = text.strip)
 end
 ```
 
@@ -331,7 +397,7 @@ nothing; and `screen.close` blurs the focused component on its way out. Keep
 the handler cheap and it won't matter.
 
 The framework sends both hooks with `__send__`, so declare them public,
-protected or private as you like — the example above groups `on_blur` under
+protected or private as you like — the example above groups `handle_blur` under
 `protected`, which is where framework-invoked plumbing belongs.
 
 ## Writing a status line
@@ -344,7 +410,7 @@ A status line is a `Label` in your layout. That's the whole idea:
 
 ```ruby
 status = Tuile::Component::Label.new
-status.text = "q #{screen.theme.hint("quit")}  Tab #{screen.theme.hint("Switch")}"
+status.text = "q #{screen.theme.fg(:hint, "quit")}  Tab #{screen.theme.fg(:hint, "Switch")}"
 
 root = Tuile::Component::Layout::Vertical.new
 root.add(main_ui, Tuile::Component::Layout::Expand[1])
@@ -357,10 +423,13 @@ is exactly this: Tab, Enter and Backspace work in both panes, so its row is
 a constant. Reaching for a focus callback there would be machinery computing
 a value that never changes.
 
-Two details about the text itself. `theme.hint(...)` styles the descriptive
-half of a `key what` pair so hints look consistent (chapter 6), and it
-**bakes the color in** — so a label built from it rebuilds itself from
-`on_theme_changed` to follow a light/dark flip. And keys registered with
+Two details about the text itself. The `:hint` above is one of *your*
+`custom` theme tokens, not one of Tuile's — the framework colors only the
+chrome it paints, and this row isn't its. Chapter 6 shows the four lines
+that define the pair; the shade to reach for is a grey dimmer than the
+terminal's own foreground, so the *key* is what pulls the eye. `theme.fg`
+also **bakes the color in**, so a label built from it rebuilds itself from
+its `on_theme_changed` slot to follow a light/dark flip. And keys registered with
 {Tuile::Screen#register_global_shortcut} don't advertise themselves: the
 registry runs actions, it doesn't describe them, so a `^K menu` in your row
 is text you write next to the registration.

data/book/06-theming.md

@@ -24,10 +24,9 @@ defaults for free.
 What Tuile *does* color is the small set of cues that signal
 interaction: the highlight behind the focused list row, the border of the
 active window, the resting "well" of a text field, the scrollbar down a
-scrollable pane's edge, the shortcut captions
-in a status line you write. Those are the accents, and they are exactly the tokens
+scrollable pane's edge. Those are the accents, and they are exactly the tokens
 a {Tuile::Theme} carries — `active_bg_color`, `active_border_color`,
-`input_bg_color`, `scrollbar_color`, `hint_color`, the three that mark a field
+`input_bg_color`, `scrollbar_color`, the three that mark a field
 invalid (`error_color` and the two error wells), and `placeholder_color` for
 the hint an empty field paints into itself. There is no global `bg` or `fg` token,
 and that absence is intentional: adding one would mean painting over the
@@ -36,12 +35,16 @@ TUI look wrong on someone else's color scheme. The theme touches only
 what the framework must color to be legible, and leaves the rest to the
 terminal.
 
-Two of them are worth a second look, because they pull in opposite
-directions. `hint_color` is an *accent* — a blue that draws the eye to a
-shortcut caption you want noticed. `placeholder_color` is its temperamental
-opposite: a grey tuned to sit just above invisible, because a placeholder is
-a hint the reader is welcome to miss. Reaching for the wrong one of the two
-makes an empty field louder than a filled one.
+Note what that list does *not* include: a color for secondary text. The
+shortcut captions in a status line are a good example — they want to be
+dimmer than the keys beside them, and Tuile has no opinion about how dim,
+because Tuile does not paint them. A status line is yours (the framework
+reserves no row for one), so its shades are yours too, and they go in
+`custom` — which the next section covers. The one token that *looks* like
+a secondary-text color is `placeholder_color`, and it isn't one: it is
+tuned to sit just above invisible, for the specific case of a hint the
+reader is welcome to miss, on the specific background of a field's own
+well.
 
 So a {Tuile::Theme} is a frozen value type — a `Data.define` of colors
 plus an app-extensible `custom` hash — and that's all. Two are
@@ -122,7 +125,7 @@ above mean what it reads as.
 reference* — `Theme.ref(:panel_bg)` — that names one of your app's custom
 tokens and re-resolves it against the current theme on every paint. The
 reference is the ergonomic path: assign it once and the panel follows
-light and dark on its own, with no `on_theme_changed` handler. That works
+light and dark on its own, with no `handle_theme_changed` handler. That works
 precisely because a background — unlike the baked-in colors of your
 *content* (below) — is resolved *live* at paint, exactly like the
 framework's own accents; `bg_color` is a single value read late, so
@@ -163,14 +166,15 @@ colors. Done.
 When a component has a themed color in hand, it applies it in one of two
 ways, and which one depends on the text.
 
-For plain chrome — a border string, a status-bar hint — the theme's
+For plain chrome — a border string, a button caption — the theme's
 **rendering helpers** wrap the text in the token's SGR color and a reset:
-`theme.active_bg("[ Ok ]")`, `theme.hint("quit")`. The helper picks the
-right channel for the token's role (a `*_bg` token wraps as a background,
-a hint as a foreground) and passes the content through verbatim, so the
-string may already contain other escape sequences — which is how
-{Tuile::Component::Window} feeds its whole border row, cursor moves and
-all, through `active_border`.
+`theme.active_bg("[ Ok ]")`, `theme.active_border("┌──┐")`, and
+`theme.fg(:hint, "quit")` for one of your own `custom` tokens. The helper
+picks the right channel for the token's role (a `*_bg` token wraps as a
+background, a border as a foreground) and passes the content through
+verbatim, so the string may already contain other escape sequences — which
+is how {Tuile::Component::Window} feeds its whole border row, cursor moves
+and all, through `active_border`.
 
 But chrome text is flat. Content is not. A list row or a label may be a
 {Tuile::StyledString} with its own per-span colors, and wrapping that in
@@ -253,7 +257,7 @@ more round trip than you might expect. The mode-2031 report says only
 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}`#on_theme_changed` across the tree exactly as a theme
+{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
@@ -353,7 +357,21 @@ one with `theme[:accent]`, which **fail-fasts**: a typo'd token raises
 `KeyError` rather than silently painting a default, so a missing color is
 a loud bug and not a mystery. And you render with the generic `fg` / `bg`
 helpers — `theme.fg(:accent, "NEW")` — the custom-token counterparts of
-the built-in `hint` / `active_bg` helpers.
+the built-in `active_border` / `active_bg` helpers.
+
+This is where a status line's shades belong, and it is worth doing even
+for a single token. The examples that ship with Tuile all carry one
+`hint` grey for the descriptive half of their `"q quit"` rows, paired
+dark and light so the row follows an appearance flip:
+
+```ruby
+APP_THEME = Tuile::ThemeDef.new(
+  dark:  Tuile::Theme::DARK.with(custom:  { hint: Tuile::Color::GREY54 }),
+  light: Tuile::Theme::LIGHT.with(custom: { hint: Tuile::Color::GREY62 })
+)
+screen.theme_def = APP_THEME
+status.text = "q #{screen.theme.fg(:hint, "quit")}"
+```
 
 For an app with more than a couple of custom tokens, the tidier move is
 to **subclass** {Tuile::Theme} and give each token a named coloring
@@ -422,21 +440,35 @@ because only *you* know which of the string's colors came from the theme
 versus which are inherent to the data (a log line's level color, say,
 should *not* follow the theme).
 
-The hook for this is {Tuile::Component#on_theme_changed}, fired on every
+The hook for this is {Tuile::Component#handle_theme_changed}, fired on every
 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**:
+
 ```ruby
 label.on_theme_changed = -> { label.text = render_status_line }
 ```
 
-There are two ways to consume it, matching how you built the component.
-If you assembled stock components, assign the `on_theme_changed=` proc as
-above. If you subclassed, override the method — and call `super`, so an
-assigned listener still fires. Either way the rule is the same: the hook
-is where theme-derived content gets rebuilt, and the framework handles
-everything else.
+If you subclassed, override `handle_theme_changed`, the **override point**
+— and call `super`, so an assigned listener still fires:
+
+```ruby
+class StatusLabel < Tuile::Component::Label
+  protected def handle_theme_changed
+    super
+    self.text = render_status_line
+  end
+end
+```
+
+That pair is the house rule across the whole widget set, not a special
+case for theming. Either way the rule here is the same — the hook is where
+theme-derived content gets rebuilt, and the framework handles everything
+else.
 
 ---
 

data/book/07-components.md

@@ -370,7 +370,7 @@ 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`.
+`design/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
@@ -540,6 +540,24 @@ 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.
 
+There is a second half to this, and it bites harder, because some prefixes of a
+date do not merely fail to parse — they parse *cleanly*. In a `dd.mm.yyyy`
+field, `1.1.2` on the way to `1.1.2024` is the first of January in the year 2:
+a perfectly good `Date`, one `bad_input?` will never flag, and one your
+listener would be handed while the user is still typing, along with whatever
+recalculation hangs off it. So the date and time fields settle their *notice*
+on those same two gestures: `on_value_change` fires when you leave the field or
+press Enter, not as you type. Reading `value` is again unaffected, so a Save on
+a keyboard shortcut that never moves focus still sees the date on screen — and
+a value nobody had to type, a `value=` or an Up/Down step or a `clear`, is
+announced the moment it happens.
+
+The ink and the notice settle together because one question decides both, and
+it is the prefix-closed question from a few pages back. Every buffer an
+`IntegerField` passes through really is the number it shows, so `4` on the way
+to `42` is worth announcing and worth reddening. A date's are neither. That one
+property of the grammar settles the filter, the ink and the notice alike.
+
 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
@@ -570,14 +588,14 @@ label without displacing the value — so a field carries no caption at all. The
 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
+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)
+  def handle_text_input_key?(key)
     return super unless key == Tuile::Keys::ENTER
 
     submit(text)     # Enter submits instead of inserting a newline
@@ -616,6 +634,41 @@ 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.
 
+### Two fields, one value
+
+{Tuile::Component::DateTimeField} is the first field made of *fields*: the date
+field and the time field from earlier in this chapter, side by side on one row,
+behind a single `DateTime`.
+
+```ruby
+starts = Component::DateTimeField.new
+starts.value = DateTime.new(2026, 9, 14, 13, 45)   # [2026-09-14] [13:45]
+starts.date_field.formats = "%d.%m.%Y"             # tune a half in place…
+starts.time_field.step = 900                       # …rather than through a forwarder
+```
+
+The halves are exposed read-only: a child you *tune* but never *supply* is
+reached directly, so there is no second set of names to keep in step — and no
+argument about whether `formats=` on the composite would mean the date's or the
+time's.
+
+The value is non-nil only when both halves parse, and a half going bad nils the
+whole thing rather than holding the last good one: a field holds bad input **or**
+a value, never both. What is genuinely new is the question of who goes red, and
+the answer is one sentence — **the composite paints only the fault no half can
+wear**. Garbage in the date half is attributable, so that half reddens itself on
+the latch you saw a moment ago, and the composite paints nothing. A date with no
+time is nobody else's fault, so the composite reddens *whole* — but only once you
+leave it, so it judges you when you are done rather than while you are filling it
+in. A rule's verdict is not attributable either, and reddens whole with no latch
+at all.
+
+One wrinkle follows from that. Pressing Enter over a half-filled field reports
+`bad_input?` and its message but does not redden it; the ink waits for you to
+leave. Latching on Enter would reopen exactly the window the rule closes — the
+one where the field tells you that you are wrong when the truth is that you are
+not finished.
+
 ## Choosing from a set
 
 {Tuile::Component::List} is the workhorse: a scrollable column of *items*
@@ -967,7 +1020,7 @@ 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
+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.
@@ -1234,7 +1287,7 @@ 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
+- **`handle_detached` fires when a pane goes away, `handle_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.
@@ -1684,7 +1737,9 @@ layout) *or* as a popup (via a class-level `open`).
   presentation from the body's type (an Array is rows, text is prose).
 - {Tuile::Component::PickerWindow} — a menu of options each bound to a
   single key, firing your block with the picked key. Popped up via `open`,
-  it closes itself after a pick; ESC/`q` cancels without firing.
+  it closes itself after a pick; ESC/`q` cancels without firing. Captions
+  paint in the terminal's own foreground; hand in a {Tuile::StyledString}
+  (or the ANSI string `theme.fg` returns) to color one, per option.
 - {Tuile::Component::LogWindow} — a Window framing a
   {Tuile::Component::LogTextView}: an auto-scrolling, scrollbar-equipped
   TextView purpose-built for log output. The view is where the behavior

data/book/08-testing.md

@@ -107,7 +107,7 @@ method* assembled, and the test never held a reference to it.
 one component matching a spec:
 
 ```ruby
-Testing.get(Component::Button, caption: "Save").handle_key(Keys::ENTER)
+Testing.get(Component::Button, caption: "Save").handle_key?(Keys::ENTER)
 Testing.get(id: :amount).value = 42
 ```
 
@@ -132,7 +132,7 @@ walk that takes the first match —
 
 ```ruby
 combo = nil
-window.on_tree { |c| combo ||= c if c.is_a?(Component::ComboBox) }
+window.walk_tree { |c| combo ||= c if c.is_a?(Component::ComboBox) }
 ```
 
 — and the day the pane grows a second `ComboBox`, that silently re-points
@@ -178,34 +178,36 @@ terser, and changes nothing about the assertion channel. What a component
 There are two altitudes at which you feed input, and picking the right one
 is most of writing a good Tuile test.
 
-**Low: call the component directly.** {Tuile::Component#handle_key} and
-`handle_mouse` are public, and calling them straight tests a component's
-own logic in isolation — no focus, no dispatch, just "given this key, does
-the list move its cursor?" `handle_key` returns whether it consumed the
-key, so you assert on that too:
+**Low: call the component directly.** {Tuile::Component#handle_key?} and the
+`handle_mouse_*` handlers are public, and calling one straight tests a
+component's own logic in isolation — no focus, no dispatch, just "given this
+key, does the list move its cursor?" Both answer whether they consumed the
+event, so you assert on that too:
 
 ```ruby
-list.handle_key(Keys::DOWN_ARROW)          # exercises the cursor directly
+list.handle_key?(Keys::DOWN_ARROW)                            # exercises the cursor directly
+list.handle_mouse_scroll?(Mouse::ScrollEvent.new(:up, 5, 2))  # false at the top: an ancestor gets it
 ```
 
-**A mouse test needs the component mounted, where a key test doesn't.** A
-click doesn't only *do* something, it also *focuses* — and
-{Tuile::Screen#focused=} refuses a component that isn't on the pane, so
-`handle_mouse` on a component you never attached raises "is not attached to
-this screen". Give it a tree first:
+**A press, though, wants the high altitude.** It does not only *do* something:
+it focuses, it dismisses popups, and which component it even reaches is the
+router's answer rather than the component's — so calling `handle_mouse_down?`
+by hand tests a third of what a click is. Drive it through
+{Tuile::FakeScreen}, which posts the gesture the terminal would:
 
 ```ruby
-screen.content = list                      # a click focuses; focus needs a tree
+screen.content = list                      # a press focuses; focus needs a tree
 list.rect = Rect.new(0, 0, 10, 5)
-list.handle_mouse(MouseEvent.new(:left, 5, 2))
+screen.click(5, 2)                         # press then release, at that cell
 ```
 
-That applies to containers too, and to more of them than you might expect:
-a click descends to every child whose rect contains the point, so testing a
-window's footer by clicking it exercises the window, the footer's slot and
-the footer, all of which want to be attached.
+`click` is the whole gesture; `press` / `release` are its halves, for a test
+about what the grab does in between, and `scroll` / `move` post the other two
+events. They all take screen-absolute, 0-based coordinates, so a test asserts
+against the rect it assigned — and a press on a cell no component covers
+simply does nothing.
 
-**High: go through the pane.** {Tuile::ScreenPane#handle_key} runs the
+**High: go through the pane.** {Tuile::ScreenPane#handle_key?} runs the
 dispatch rung from chapter 5 that routing is actually about: delivery to
 {Tuile::Screen#focused}, then the bubble up its ancestor chain to the scope
 root. So when your test is about routing — that a layout's one-key pane jump
@@ -215,11 +217,11 @@ drive the pane and let the real machinery run:
 
 ```ruby
 screen.focused = list                # focus as production does — or list.focus
-assert screen.pane.handle_key("1")   # the layout's ancestor binding fires
+assert screen.pane.handle_key?("1")   # the layout's ancestor binding fires
 ```
 
 The two rungs *above* the pane have their own doors, because `Screen`'s own
-`handle_key` — the top of the ladder — is private: it belongs to the key
+`handle_key?` — the top of the ladder — is private: it belongs to the key
 thread, not to app code. Tab cycling is {Tuile::Screen#focus_next} /
 `focus_previous`, both already scoped to the topmost modal popup, which is
 what "a popup traps Tab" means. A global shortcut is a block you registered,