tuile 0.15.0 → 0.17.0

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.
@@ -165,8 +165,8 @@ the tree — and neither needs machinery, because bubbling already has the
 right shape. **Put the key on the ancestor that owns the region.**
 
 ```ruby
-class AppLayout < Tuile::Component::Layout::Absolute
-  def handle_key(key)
+class AppLayout < Tuile::Component::Layout
+  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
@@ -233,7 +233,7 @@ single `PasteEvent` — which never enters the ladder at all:
 
 The default `handle_paste` returns `false` and the text is dropped.
 {Tuile::Component::AbstractStringField} overrides it to insert at the caret
-as **one** mutation — so `on_change` fires once for the paste rather than
+as **one** mutation — so `on_value_change` fires once for the paste rather than
 once per character, and a subclass that claims Enter needs no paste code of
 its own:
 
@@ -241,11 +241,11 @@ 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
-    self.text = ""
+    self.value = ""
     true
   end
 end
@@ -260,7 +260,7 @@ def handle_paste(text)
   return super if text.lines.size < 20
 
   attach_as_file(text)
-  self.text = "#{text.lines.size} lines attached"
+  self.value = "#{text.lines.size} lines attached"
   true
 end
 ```
@@ -273,15 +273,84 @@ 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
-{Tuile::Component#cursor_position} — return a `Point` and the terminal
-cursor is shown there; return `nil` (the default) and there's no cursor. A
+{Tuile::Component#cursor_position} — return a `Point` in your *own*
+coordinates (the ones you paint in) and the terminal cursor is shown there;
+return `nil` (the default) and there's no cursor. {Tuile::Screen} is what
+converts the point to a screen position, so a caret is a column and a row and
+nothing more. A
 {Tuile::Component::TextField} being edited returns its caret position, so
 the caret you see blinking is the focused component's answer to that one
 question.
@@ -296,23 +365,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.value = text.strip)
 end
 ```
 
@@ -331,7 +400,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 +413,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 +426,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.
@@ -369,10 +441,10 @@ is text you write next to the registration.
 
 Some apps genuinely show different keys in different places — a window with
 a search mode, or a pane whose commands only apply to it. For those,
-{Tuile::Screen#on_focus_changed=} is the notification:
+{Tuile::Screen#on_focus_changed} is the notification:
 
 ```ruby
-screen.on_focus_changed = -> { status.text = hint_for(screen.focused) }
+screen.on_focus_changed { status.text = hint_for(screen.focused) }
 ```
 
 It fires after every focus *change* — to and from `nil` included, and after

data/book/06-theming.md

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