tuile 0.13.0 → 0.15.0

data/README.md

@@ -6,25 +6,16 @@ and Tuile runs a single-threaded event loop that dispatches keys and mouse
 events, then repaints everything that was invalidated since the last tick. The
 name is French for "roof tile": small pieces that compose into a larger whole.
 
-The design philosophy — "boxes within boxes" that talk via listeners and data
+The design philosophy — "composing components in layouts to create something bigger" that talk via listeners and data
 providers — is described in
 [component-oriented programming](https://mvysny.github.io/component-oriented-programming/).
 Tuile is that approach applied to a terminal.
 
-If you have looked at the alternatives:
-
-- [tty-toolkit](https://ttytoolkit.org/) (`tty-prompt`, `tty-cursor`, …) is a
-  set of low-level building blocks rather than a framework: there is no
-  component tree, no event loop, no invalidation. Tuile sits on top of
-  `tty-cursor`/`tty-screen` and adds the framework layer.
-- [vedeu](https://github.com/gavinlaking/vedeu) is the closest Ruby comparable
-  but is no longer maintained (last release 2017).
-- [ratatui](https://github.com/ratatui/ratatui) is the popular TUI framework
-  in the Rust ecosystem; its immediate-mode API is closer to `tty-prompt` than
-  to Tuile's retained component tree.
-
 Tuile is the only actively maintained component-oriented TUI framework for
-Ruby that we are aware of.
+Ruby that we are aware of. If you have looked at the alternatives —
+tty-toolkit, vedeu, ratatui, or the curses bindings your distro packages —
+[COMPARISON.md](COMPARISON.md) sizes each one up and says which of them you
+can actually reach from Ruby.
 
 ## Installation
 
@@ -64,6 +55,9 @@ else in Tuile loads it.
 - **API reference:** every public class and method carries YARD headers —
   browse them at <https://rubydoc.info/gems/tuile>, or run
   `bundle exec rake yard` for a local site.
+- **[COMPARISON.md](COMPARISON.md)** places Tuile among the neighbouring
+  toolkits, and answers what a Ruby program can reach without writing
+  bindings first.
 
 ## Hello world
 
@@ -149,9 +143,20 @@ status-bar hints — plus whatever `custom` tokens your app adds. Everything
 else inherits the terminal's own foreground and background, so Tuile looks at
 home in the user's palette instead of fighting it. Tuile probes the terminal
 background at startup, pairs a dark and a light theme in a `ThemeDef`, and
-re-picks on a live OS appearance flip.
+re-picks on a live OS appearance flip. The probed background is also yours to
+read — `Screen#background_color` — for panes tinted a few percent off the
+terminal's own, LazyVim-style.
 → [chapter 6](book/06-theming.md)
 
+**A `Locale` holds conventions, never prose.** Date formats, the calendar,
+month and weekday names, the decimal separator — detected from `locale(1)` at
+startup, but only when the environment actually asked for something, since the
+POSIX default is American and "said nothing" is indistinguishable from "wants
+American". Everything else falls back to `Locale::ISO`. Tuile ships no message
+catalogue and no per-country presets: this is the formatting half of what POSIX
+splits, and the wording half stays your app's.
+→ [chapter 10](book/10-locale.md)
+
 ## Components
 
 Every component lives under `Tuile::Component::*`, and every one of them is a
@@ -174,6 +179,7 @@ carries the per-method reference: `bundle exec rake yard`, or
 | component | what it is |
 |---|---|
 | `Window` | A frame with a `caption`, one content slot, and a border that lights up while the window is on the focus chain. `footer_text=` decorates the bottom border; `footer=` mounts a real component in it; `scrollbar=` reclaims the right border column. |
+| `Slot` | A one-child region for content that may be absent, arrive late, or be swapped. Give a multi-region container one per region and the tree stays honest — the occupant fills the slot's rect, and an empty slot holds its place rather than collapsing. |
 | `MenuBar` | A one-row strip of menu captions, each dropping a cascade of submenus that nests without limit. Items are handles from `#add_item`, each with its own `on_click`. See [Menus](book/07-components.md#menus). |
 | `Tabs` | A one-row strip of captions with one selected, Left/Right switching immediately. Knows nothing about content — pair it with `TabSheet`, or drive your own view swap from `on_tab_selected`. |
 | `TabSheet` | A `Tabs` strip plus the pane belonging to the selected tab. Unselected panes are *detached*, so they keep their state and stay out of the Tab cycle. See [Switching between views](book/07-components.md#switching-between-views). |
@@ -201,6 +207,8 @@ carries the per-method reference: `bundle exec rake yard`, or
 | `IntegerField` | A one-row field whose `value` is an `Integer` or `nil`, filtering input to digits and one leading `-`. |
 | `FloatField` | The same, one Ruby type over: `value` is a `Float` or `nil`. |
 | `BigDecimalField` | The same for money, where a binary `Float` is the wrong answer. Tuile's one optional dependency — add `bigdecimal` yourself if you name this component. |
+| `DateField` | A one-row field whose `value` is a `Date` or `nil`, over a list of strftime formats taken from `Screen#locale`: it accepts any of them and writes the first one back when you leave the field. Manual entry — there is no calendar popup yet. |
+| `TimeField` | A one-row field whose `value` is a time of day — a `Time` on a fixed epoch date, or `nil` — spelled the way `Screen#locale` says. `step` is both the Up/Down stride and the precision: it shows seconds only when set below a minute. |
 
 ### Choosing from a set — [book ch7](book/07-components.md#choosing-from-a-set)
 
@@ -224,17 +232,23 @@ carries the per-method reference: `bundle exec rake yard`, or
 
 | component | what it is |
 |---|---|
-| `Popup` | The modal overlay host: it wraps any component, paints nothing itself, and is sized by `size=` (a `Size` or a `Fraction` of the screen) rather than by its content. ESC or `q` dismisses. |
+| `Overlay` | The bare floating layer: it wraps any component, paints nothing itself, and sits at the rect you assign it. Takes no focus and no keys — the building block for anchored panels and toasts. |
+| `Popup` | The modal dialog: an `Overlay` that centers itself, grabs focus, scopes keys to its own subtree and blocks clicks beneath it. Sized by `declared_size=` (a `Size` or a `Fraction` of the screen) rather than by its content; ESC or `q` dismisses. |
 | `Notification` | A transient corner toast — `Notification.show("Saved")` — stacking messages in one box that a single ticker drains. Non-modal, and it never takes focus. |
-| `InfoWindow` | A `Window` of static lines, tiled or popped up. For read-only information you don't want to assemble by hand. |
+| `ConfirmWindow` | The confirm dialog: a message and a row of buttons in a popup sized to fit. `alert` / `confirm` / `yes_no` cover the common shapes; `#button` builds any other. Every button closes; ESC, `q` or an outside click fire `on_dismiss`. See [The confirm dialog](book/07-components.md#the-confirm-dialog). |
+| `InfoWindow` | A `Window` with a read-only body, tiled or popped up: prose that wraps (`message=`), or rows that don't (`lines=`). |
 | `PickerWindow` | A `Window` of options identified by single keystrokes, firing a callback with the key that was pressed. |
-| `LogWindow` | A scrolling log view. Point your logger at a `LogWindow::IO` and lines land here from any thread, marshalled through the event queue. |
+| `LogTextView` | An auto-scrolling `TextView` for log output. Point your logger at a `LogTextView::IO` and lines land here from any thread, marshalled through the event queue. |
+| `LogWindow` | A `Window` framing a `LogTextView` — the framed log pane. |
 
 The mixins those share — `HasValue` (the `value` / `empty?` / `clear` /
-`on_value_change` seam every input speaks), `HasContent` (one-child
-containers) and `HasCaption` (app-authored chrome text) — are the seams to
-include when you write your own; chapter 7's "value seam" section is the
-walkthrough.
+`on_value_change` seam every input speaks), `HasValidation` (`error_message`,
+the verdict a validator writes and the field shows as a red well), `HasBadInput`
+(`bad_input?`, for a field whose input can be something its value cannot
+represent — a lone `-` in a number), `HasContent` (a primary child the caller
+populates, named `content`) and
+`HasCaption` (app-authored chrome text) — are the seams to include when you
+write your own; chapter 7's "value seam" section is the walkthrough.
 
 ## Geometry primitives
 
@@ -252,13 +266,13 @@ interface:
 ```ruby
 Tuile.logger = Logger.new($stderr)              # or:
 Tuile.logger = TTY::Logger.new                  # duck-typed, works directly
-Tuile.logger = Logger.new(Tuile::Component::LogWindow::IO.new(window))
+Tuile.logger = Logger.new(Tuile::Component::LogTextView::IO.new(view))
 ```
 
 ## Testing
 
 Tuile ships with a `Tuile::FakeScreen` that you install in place of the real
-screen for unit tests. It fixes the viewport at 160×50, disables the UI lock,
+screen for unit tests. It fixes the viewport at 160×50,
 paints into an in-memory back buffer (assert on it for painted content) while
 capturing cursor/housekeeping escapes into an array, and uses a synchronous
 `FakeEventQueue` (submitted blocks run inline; posted events are discarded).
@@ -303,6 +317,12 @@ Key hooks:
   to its current value should typically *not* invalidate.
 - `Screen.instance.clear` — drops accumulated `prints` without resetting
   invalidation.
+- `Tuile::Testing.get` / `.find` — locate a component to drive, by class,
+  mixin, `Component#id`, caption or a block:
+  `Testing.get(Component::Button, caption: "Save")`. `get` demands exactly
+  one match and prints the tree it searched when it doesn't get one; `find`
+  returns all matches and takes `count:`. Both take `in:` to scope the
+  search, and default to the whole screen. Call them qualified.
 
 Because `FakeEventQueue#submit` runs the block immediately on the calling
 thread, code paths that marshal work back via `screen.event_queue.submit { … }`

data/TERMINOLOGY.md

@@ -4,7 +4,7 @@ Tuile's house vocabulary — one line per term, looked up by word.
 
 This file owns **definitions only**. The *rules that bite* live in AGENTS.md
 ("Nomenclature" and the sections each word belongs to); the *why we chose a word
-and not its synonym* lives in DECISIONS.md (`D-scroll-nomenclature` for the
+and not its synonym* lives in DECISIONS.md (`D_scroll_nomenclature` for the
 row/line/item split); the *concepts* live in the book. When a definition here
 needs a paragraph of justification, that paragraph belongs in one of those three.
 
@@ -15,7 +15,7 @@ needs a paragraph of justification, that paragraph belongs in one of those three
 | **row** | one row of the terminal grid — the framework's only word for it. A wrapped unit of text *is* a row; wrapping is what turns text into rows. |
 | **column** | one cell-column of the terminal grid; the unit `display_width` counts. |
 | **cell** | one grid position: a grapheme plus a {Tuile::StyledString::Style}, in {Tuile::Buffer}. |
-| **glyph** | what the terminal draws in one or more cells. Ambiguous-width glyphs count as **one** column (the bet in `D-ambiguous-width`). |
+| **glyph** | what the terminal draws in one or more cells. Ambiguous-width glyphs count as **one** column (the bet in `D_ambiguous_width`). |
 | **cluster** | a grapheme cluster — the unit measurement, slicing, caret motion and deletion all work in. Never `each_char`. |
 | **row_in_viewport** | a row measured `0...rect.height`, i.e. relative to a component's own rect. |
 | **scroll_top_row** | the content row currently sitting at the top of the viewport. |
@@ -23,7 +23,9 @@ needs a paragraph of justification, that paragraph belongs in one of those three
 | **viewport_rows** | how many rows of content are visible — always `rect.height`; kept private, since `rect.height` is the public form. |
 | **row_count** | how many rows the wrapped content occupies. Public on `TextArea` (with `caret_row`, its companion); also on the private `WrappedText` and as `VerticalScrollBar.new(row_count:)`. Not on `TextView` / `List`, which have no caller for it. |
 | **caret_row** | the row a text input's caret sits in, counted from the content's first row. `TextArea` only. |
-| **extent** | the sub-rect a one-row widget actually paints, used for its highlight and hit test — narrower than the `rect` it was given. The arithmetic is each widget's own (a `Checkbox`'s glyph plus caption; a `Tabs` strip's segments and separators), never a `Component` method. |
+| **extent** | the `Size` a widget actually paints inside the `rect` it was given — `Component#extent`, `nil` unless declared, always at the rect's top-left (`Component#extent_rect` positions it). What the widget clears outside of, hit-tests, highlights and anchors its dropdown to. The arithmetic is each widget's own (a `Checkbox`'s glyph plus caption; a `Tabs` strip's segments and separators). Distinct from a *slot extent*. |
+| **handle** | the moving part of a {Tuile::VerticalScrollBar} — the rows standing for the slice of content in view (`handle_start` … `handle_end`, `handle_char`). CSS calls it the *thumb*; Tuile does not. Not drawn at all when the content fits. |
+| **track** | the scrollbar's fixed part: the full viewport height the handle moves within, and the glyph (`track_char`) painted on the rows the handle doesn't cover. Never the bar's *column*, which is "the scrollbar column" (`D_scrollbar_reserve`). |
 | **segment** | one tab's span on a {Tuile::Component::Tabs} strip: its caption plus a padding column either side. The unit a click resolves to; the separator column between two segments belongs to neither. |
 
 **Space rule 1.** An object with only one row space leaves `row` unqualified:
@@ -42,7 +44,7 @@ content-space.
 | **line_count** | a count of `\n` units (`TextView::Region#line_count`). Never a row count. |
 | **item** | a domain object a widget holds and renders — `List#items`, and the enum widgets above it. |
 | **renderer** | the `item -> row` proc a generic component uses to render an item it knows nothing about. |
-| **selection** | which item or tab a selector currently points at. *View state* when nothing would save it ({Tuile::Component::Tabs}`#selected`), a *value* when a form would (`RadioGroup#value`) — the split `D-tabs` calls the "would a form save it?" test. |
+| **selection** | which item or tab a selector currently points at. *View state* when nothing would save it ({Tuile::Component::Tabs}`#selected`), a *value* when a form would (`RadioGroup#value`) — the split `D_tabs` calls the "would a form save it?" test. |
 | **item_count** / **item_index** | how a `List::Cursor` counts and addresses; equal to a row count in a `List`, but the cursor indexes *items*. |
 | **text** | the user-editable **value** of an input ({Tuile::Component::HasValue}, aliased as `text` on `AbstractStringField`). |
 | **caption** | app-authored **chrome** text ({Tuile::Component::HasCaption}) — a `Window` title, a `Button` label. Never a value. |
@@ -54,17 +56,30 @@ content-space.
 | term | means |
 |---|---|
 | **component** | a node of the UI tree ({Tuile::Component}); the only thing that paints. |
+| **slot extent** | in a `Layout::Box`, the size a parent *allocates* a child along an axis — what `Fixed` / `Percent` / `Expand` declare, and what `main_extent` / `cross_extent` measure. The parent's allocation, where a component's *extent* is the child's own painted region; `D_extent` turns on the two being different. Here `slot` is the box's allocation for one child and has **nothing** to do with {Tuile::Component::Slot} — the phrase is glossary-only (the code says `main_extent` / `cross_extent`), so read it as one term, never as "the extent of a `Slot`". |
 | **tile** / **tiled** | the non-popup part of the tree — `ScreenPane#content` and its descendants. Also *to tile*: to cover a rect completely. |
 | **attached** | reachable from a {Tuile::ScreenPane} via the parent chain — the one axis `attached?` consults. |
-| **slot** | a named child a container holds by identity (`content`, `footer`) as well as in `children`. |
+| **wrapping field** | a field that owns and hides one *inner editor* and carries a typed value over it — {Tuile::Component::AbstractWrappingField} and its subclasses. The editor is private machinery: no public accessor, `children` the only way in. |
+| **inner editor** | the {Tuile::Component::AbstractStringField} a *wrapping field* wraps. Always this phrase — never "the wrapped field", which would name the wrong one of the two fields in play. |
+| **slot** | a named region of a container, reached by identity (`content`, `footer`) as well as through `children`. Two forms: a plain named child the caller populates directly (`HasContent#content`, the primary one); or a {Tuile::Component::Slot}, the one-child region component, wired once so its occupant may be absent or swapped (`Window#footer`). Capital-`S` `Slot` always means the class. |
 | **cascade** | the stack of open {Tuile::Component::ListDropdown} panels a {Tuile::Component::MenuBar} drives, one per level, the last deepest. Each is an overlay on the pane, not a child of the bar. |
 | **submenu** | a menu item that opens a further panel instead of doing something — `MenuBar::Item#submenu?`, true iff the item has children. Painted with a trailing `▸`. |
 | **mnemonic** | a letter that activates one {Tuile::Component::MenuBar} item, underlined in its caption. Always *level-scoped*: matched against the top-level items while the cascade is closed and the deepest open panel while it is open, never across the two. |
 | **strip** | the one-row {Tuile::Component::Tabs} component: captions, one selected, no content of its own. A {Tuile::Component::MenuBar} has one too — same word, and the same extent-based hit testing, deliberately not the same look. |
 | **tab** | a {Tuile::Component::Tabs::Tab} — a caption plus an identity, minted and owned by the strip. Not a component (it never paints itself) and not an *item* (it holds per-element state, and the set is never assigned whole). Say "a tab" and "the Tab key"; never let the two words touch. |
-| **pane** | the component a {Tuile::Component::TabSheet} shows for the selected tab. The unselected ones are *detached*, which is how Tuile hides a component. |
+| **pane** | the component a {Tuile::Component::TabSheet} shows for the selected tab. The unselected ones are *detached* — one of the two ways to take something off the screen, and the one that fires the lifecycle hooks. |
+| **hidden** | carrying `visible? == false` — the component's own flag. *Gone*, not merely unpainted: as if detached, but still in the tree, so no lifecycle hook fires. Says nothing about the ancestors. |
+| **shown** | reachable by the user: this component and every ancestor visible. The effective, ancestor-inclusive state, and always the walk's word (`on_shown_tree`, `Box#shown_children`) — there is deliberately no `shown?` reader. |
 | **invalidate** | record a component as needing repaint; the loop coalesces and repaints once per tick. |
 | **cursor** | *(two senses, both live)* the hardware terminal cursor (`Screen#cursor_position`), and a `List::Cursor` — the selection position within a list. |
-| **well** | the explicit background an input paints over its whole rect (`Theme#input_bg_color` / `#active_bg_color`), which opts it out of `bg_color` inheritance. |
+| **well** | the background an input paints over its whole extent (`Theme#input_bg_color` / `#active_bg_color`), declared as its `default_bg_color`. It terminates inheritance — an ancestor's tint doesn't reach it — but loses to a `bg_color` set on the input itself. Exactly one per widget: a composed field owns the well and marks the field it wraps `Component::BG_INHERIT`. |
 | **token** | a semantic colour name on {Tuile::Theme} — an accent, never a global fg/bg. |
 | **scheme** | `:dark` or `:light`; a {Tuile::ThemeDef} pairs one {Tuile::Theme} per scheme. |
+
+## Locale
+
+| term | means |
+|---|---|
+| **conventions** | the formatting facts a {Tuile::Locale} carries — how a value is *rendered and parsed* (date formats, calendar, month and weekday names, decimal separator). Deliberately the opposite pole from *prose*, which a `Locale` never holds. |
+| **prose** | wording: a message in one language, belonging to one component. Outside `Locale` by rule, and outside Tuile by default — the wording fork of `D_bad_input` is where a translated one arrives. |
+| **primary format** | `formats.first` of a date field or a {Tuile::Locale#date_formats} list — the one a value is *written* in, and the only one that must survive a `strftime`/`strptime` round-trip. The rest only ever parse. |

data/book/03-layout.md

@@ -160,8 +160,9 @@ common case, debuggability, and auditability all at once.
 
 The place you actually write layout code is a `rect=` override. The base
 class for this is `Tuile::Component::Layout::Absolute`: it inherits all
-the focus and key-dispatch wiring, paints nothing itself, and asks only
-that you position your children whenever your own rectangle is assigned —
+the focus, key-dispatch and mouse-routing wiring, paints nothing itself,
+and asks only that you position your children whenever your own rectangle
+is assigned —
 which happens once at startup and again on every resize.
 
 ```ruby
@@ -396,24 +397,24 @@ class Fraction < Data.define(:width, :height)   # each a float in 0.0..1.0
 end
 ```
 
-A popup's size is set with `Popup#size=`, which accepts either a
+A popup's box is set with `Popup#declared_size=`, which accepts either a
 `Fraction` (resolved against the screen at layout time, so it tracks
 resize) or an absolute `Size` (clamped to the screen):
 
 ```ruby
 popup = Tuile::Component::Popup.new(content: some_window)
-popup.size = Tuile::Fraction::HALF     # the default — half the screen, centered
-popup.size = Tuile::Fraction::FULL     # fullscreen
-popup.size = Tuile::Fraction.new(0.8, 0.5)          # 80% wide, half tall
-popup.size = Tuile::Size.new(50, 12)                # exact, clamped to screen
+popup.declared_size = Tuile::Fraction::HALF     # the default — half the screen, centered
+popup.declared_size = Tuile::Fraction::FULL     # fullscreen
+popup.declared_size = Tuile::Fraction.new(0.8, 0.5)          # 80% wide, half tall
+popup.declared_size = Tuile::Size.new(50, 12)                # exact, clamped to screen
 ```
 
 The default is `Fraction::HALF`, resolved on every layout pass, so a
 popup you never size at all is half-screen and follows the terminal as
 it resizes. `Fraction::FULL` is the fullscreen shorthand.
 
-A subtle but important point: `size=` is **authoritative, not a
-preference**. The name is `size`, not `preferred_size`, on purpose.
+A subtle but important point: `declared_size=` is **authoritative, not a
+preference**. The name says *declared*, not *preferred*, on purpose.
 There is no parent that might negotiate it downward — the screen simply
 *applies* what you asked for (clamping an oversized absolute `Size` to
 fit). Calling it a preference would invite a future "well, the parent
@@ -434,7 +435,7 @@ wrong for a paragraph.
 > height) and it isn't even reliably pretty — a single long line
 > collapses the popup to one row. Half-screen-and-wrap sidesteps all of
 > it. When you genuinely know the right size — an autocomplete dropdown
-> whose items you own — you set it yourself: `popup.size =
+> whose items you own — you set it yourself: `popup.declared_size =
 > Tuile::Size.new(longest_item, [items.size, 8].min)`. That's still
 > caller-decides, top-down.
 
@@ -482,6 +483,12 @@ A component in the footer slot always fills the width — there is no
 sizing policy to configure, because the window already knows its inner
 width and that's the only dimension a bottom-row widget needs.
 
+The word *slot* is literal here: the footer is a
+{Tuile::Component::Slot}, the one-child region you'd use for the same job
+in a container of your own (chapter 7). That's why `footer=` needs no
+sizing argument and why setting it to `nil` restores the border cleanly —
+the region stays in the tree either way, occupied or not.
+
 The two are mutually exclusive by precedence: if a `footer=` component
 is present it occupies the bottom row and `footer_text` is hidden;
 otherwise `footer_text` embeds into the border. No window needs both at

data/book/05-focus.md

@@ -45,7 +45,10 @@ 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. The same rule governs
+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
 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.
@@ -70,6 +73,24 @@ that scope in tree order and advances by one, wrapping around; Shift+Tab
 walks backward. This is what keeps Tab from escaping an open dialog — the
 scope is the dialog, so cycling stays inside it.
 
+There is a third gate, and it isn't a predicate you override:
+{Tuile::Component#visible?}. A hidden component — or any component under a
+hidden one — is skipped by Tab, by click-to-focus, and by the forwarding a
+container does, because it is skipped by the walk that collects candidates
+at all. You never write a `visible?` check yourself; chapter 7 covers what
+the flag is for.
+
+The rule to know here is what happens when you hide the thing that
+currently *has* focus. Focus does not stay there, and it does not become
+nothing either: it moves to the hidden component's parent, which forwards
+it on to the first field it can reach — exactly what happens when a
+component is removed from the tree. Nothing is stashed, so bringing the
+component back does not bring focus back with it. That is the same
+behaviour a browser and every desktop toolkit settle on, and the reason
+Tuile can't simply drop focus is worth knowing: with focus at nothing, keys
+reach nobody at all, so an unhandled `q` would fall through to the event
+loop and quit your app.
+
 ## The dispatch order
 
 When a key arrives, it's offered to the tree in a fixed order, and the
@@ -204,8 +225,10 @@ 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`;
-- straight to {Tuile::Component#handle_paste}, delivered down the focus
-  chain and bubbling exactly like a 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
+  wants a clipboard;
 - the whole clipboard as one `String`, `\n`-normalized.
 
 The default `handle_paste` returns `false` and the text is dropped.
@@ -270,6 +293,47 @@ needed. With dispatch resting on nothing but "did you return `true`," the
 proxy is gone, and a component's decision to consume a key is the only
 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
+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}
+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
+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)
+end
+```
+
+Both hooks fire on one component, so a *composed* widget — a
+{Tuile::Component::ComboBox}, whose inner field is what actually holds focus —
+gets the blur on the child, not on itself. When the question is "has focus left
+this whole widget", override `active=` instead and compare before and after;
+that's exactly what the combo box does to close its dropdown when you tab away.
+
+It is a notification, not a veto — focus has already moved by the time you
+hear about it, and a handler that tries to hold focus is picking a fight with
+the one key nothing can suppress. It also fires wherever focus is *dropped*,
+not only where a user moved it: when a popup closes, the component being
+blurred has usually been detached already, so an `invalidate` there does
+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`, which is where framework-invoked plumbing belongs.
+
 ## Writing a status line
 
 Chapter 1 pointed out that Tuile draws no status bar. This is the chapter

data/book/06-theming.md

@@ -23,18 +23,28 @@ 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 shortcut captions
+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
 a {Tuile::Theme} carries — `active_bg_color`, `active_border_color`,
-`input_bg_color`, `hint_color`. There is no global `bg` or `fg` token,
+`input_bg_color`, `scrollbar_color`, `hint_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
 terminal's defaults everywhere, which is precisely the thing that makes a
 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.
 
-So a {Tuile::Theme} is a frozen value type — a `Data.define` of four
-colors plus an app-extensible `custom` hash — and that's all. Two are
+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.
+
+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
 built in: {Tuile::Theme::DARK}, the colors Tuile has always used, and
 {Tuile::Theme::LIGHT}, counterparts legible on a pale background.
 
@@ -66,9 +76,47 @@ terminal default is just the root of that chain, which is why an unset
 
 A widget with a background of its *own* keeps it. A text field paints its
 well across its whole rect, so dropping one into a tinted panel shows the
-field in its own well, not the panel tint — the explicit background wins
-over the inherited one, the terminal equivalent of a CSS element that sets
-its own `background`.
+field in its own well, not the panel tint — the terminal equivalent of a CSS
+element that sets its own `background`. That is a *default*, though, not a
+refusal: set `bg_color` on the field itself and it wins, because the chain
+asks three questions in order — what did the app set on this component, what
+background does this widget claim of its own, and what surrounds it.
+
+Which is also how you get a field that reads as plain text inside a tinted
+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
+```
+
+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.
+
+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
+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,
+and a flat `bg_color` replaces *both* shades — fine for a field, which shows a
+caret when focused, and a deliberate choice for something like a
+{Tuile::Component::Select}, which has no caret and nothing else to indicate
+focus with. Name the states when you want to keep the distinction:
+
+```ruby
+field.bg_color = grey                            # flat: focused or not
+field.bg_color = { normal: grey, active: blue }  # your own pair
+field.bg_color = { active: blue }                # keep the widget's own well,
+                                                 # override only the focus shade
+```
+
+The keys are a small closed set (`:normal`, `:active`) that Tuile defines —
+a state with no key simply isn't answered there, and the question falls
+through to the next level of the chain, which is what makes the third line
+above mean what it reads as.
 
 `bg_color` takes either a concrete {Tuile::Color} or a *live theme
 reference* — `Theme.ref(:panel_bg)` — that names one of your app's custom
@@ -170,6 +218,104 @@ theme. From your code's perspective a live appearance flip and a startup
 detection are the same thing arriving through the same channel — which is
 exactly the single-threaded-loop payoff chapter 4 promised.
 
+## Building on the terminal's own background
+
+Everything so far picks colors to sit *against* the background. Some
+designs want the opposite: a color derived *from* it. The borderless-pane
+idiom — LazyVim's editor-versus-explorer split is the one most people
+have seen — leaves the primary pane at the terminal's own background and
+tints the secondary panes a few percent off it. No borders, no boxes; the
+panes separate because one is very slightly lighter than the other.
+
+You cannot do that with a fixed color. A tint tuned against `#1e1e2e`
+looks like a deliberate panel against `#000000` and disappears entirely
+against `#282c34`. What the effect needs is the terminal's *actual*
+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}.
+
+```ruby
+bg = Tuile::Screen.instance.background_color
+sidebar.bg_color =
+  bg ? Tuile::Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }) : FALLBACK_TINT
+```
+
+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
+`background_color` is nil for every one of them. The fixed near-neutral
+you would have shipped anyway becomes the fallback; the reported color is
+the upgrade for terminals that can support it.
+
+The value stays honest across an appearance flip, and doing so takes one
+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}`#on_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.
+
+## Not every terminal can show what you computed
+
+There is a catch hiding in that last section, and it is worth seeing
+clearly because it applies to every color you *compute* rather than
+declare.
+
+A 24-bit color goes out as `\e[48;2;30;30;34m`. That sequence assumes the
+terminal on the other end understands 24-bit color — and plenty don't.
+A `TERM=xterm-256color` session understands only the 256-color palette; a
+Linux console understands sixteen colors; tmux without
+`terminal-features "*:RGB"` mangles or approximates whatever passes
+through it. When you *declared* your colors, this was somebody else's
+problem: you picked them by eye, in a terminal you were looking at, and
+if they came out wrong you picked different ones. A tint computed at
+runtime from the reported background has nobody to eyeball it.
+
+So Tuile detects what the terminal can show, and degrades on the way out.
+
+```ruby
+Tuile::Screen.instance.color_depth   # => :truecolor, :palette256, or :ansi16
+```
+
+Detection reads the environment — `COLORTERM`, then `TERM` — and never
+asks the terminal anything, so unlike the background probe there is no
+timing to respect and no staleness to worry about: the depth is settled
+at construction and stays put. Terminals do lie, in both directions, and
+`COLORTERM` in particular tends not to survive ssh or tmux. Two things
+make that survivable. Misdetection lands *conservatively* — a truecolor
+tmux advertising only `tmux-256color` reads as `:palette256`, which
+renders coarser but never garbled — and `TUILE_COLOR_DEPTH` overrides the
+detection outright, which is what you reach for when a terminal reports
+itself wrong.
+
+The part that matters for your code is that **you don't have to do
+anything about it**. The degradation happens inside
+{Tuile::Buffer}`#flush`, at the moment cells become bytes: every color is
+mapped to the nearest one the terminal can actually show, and the RGB
+you computed is what stays in the component. Paint `Color.rgb(30, 30, 34)`
+on a 256-color terminal and the wire carries palette cell 234; read the
+component back and it still holds your RGB. Nothing you store is ever
+quantized — which is the point, because a stored palette cell has
+forgotten what it was derived from, and the next tint you compute from it
+would compound the error.
+
+That leaves one thing worth doing deliberately, and only sometimes. If
+you want to know what a color will *become* — checking that a computed
+tint still contrasts with the background after both round to the same
+coarse palette — ask it:
+
+```ruby
+tint.quantize(Tuile::Screen.instance.color_depth)   # => the color the terminal will show
+```
+
+This is a question, not a step you owe the framework. It returns the
+receiver unchanged whenever the depth can show the color as-is, so it is
+also the cheapest way to ask "would this degrade at all?".
+
 ## Theming an app durably
 
 Detection picks between *Tuile's* two themes. To give your app its own