tuile 0.15.0 → 0.17.0

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
 ```
 
@@ -370,7 +382,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
@@ -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)
@@ -540,6 +552,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
@@ -549,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
@@ -565,19 +595,75 @@ 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
+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
@@ -613,8 +699,44 @@ 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
+
+{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
 
@@ -628,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
@@ -647,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:
@@ -660,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
@@ -692,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
@@ -707,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
 ```
 
@@ -756,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
@@ -814,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 —
@@ -869,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,
@@ -938,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
@@ -967,7 +1108,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.
@@ -1107,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*
@@ -1120,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
@@ -1234,7 +1417,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.
@@ -1366,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
@@ -1479,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,
@@ -1573,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
 ```
 
@@ -1684,7 +1885,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