tuile 0.9.0 → 0.10.0

data/README.md

@@ -98,9 +98,8 @@ Shift+Tab move focus between the list and the demo's widgets.
 ### Component tree
 
 Everything on screen is a `Tuile::Component`. Components have a `parent`,
-`children`, a `rect` (absolute position), an `active?` flag (true for every
-component on the focus chain root → focused), and an optional `key_shortcut`
-that the framework will route keys to from anywhere in the tree.
+`children`, a `rect` (absolute position), and an `active?` flag (true for
+every component on the focus chain root → focused).
 
 A single `Tuile::Screen` (process singleton) owns the tree. Under it sits a
 structural `ScreenPane` with three slots: tiled `content` (your app's main
@@ -194,11 +193,13 @@ mechanism that handles it wins:
    screen.unregister_global_shortcut(Tuile::Keys::CTRL_L)
    ```
 
-   Only unprintable keys are accepted (control characters, ESC, BACKSPACE,
-   arrows, F-keys); printable keys raise so they can't hijack typing into
-   a `TextField`. By default, the shortcut is suppressed while any popup
-   is open and the popup receives the key; pass `over_popups: true` to
-   pre-empt the popup.
+   This registry sits above the component tree and nothing suppresses it,
+   so it only accepts keys no widget can need: printable keys raise (they'd
+   hijack typing), as do Tab/Shift+Tab and `Screen::EDITING_KEYS` (Enter,
+   Backspace, Delete, the arrows). Control characters, ESC, `PgUp`/`PgDn`
+   and F-keys are yours. By default, the shortcut is suppressed while any
+   popup is open and the popup receives the key; pass `over_popups: true`
+   to pre-empt the popup.
 
    Pass `hint:` to surface the shortcut in the status bar. It's a
    preformatted string the caller fully owns (color it however the rest
@@ -207,23 +208,10 @@ mechanism that handles it wins:
    `over_popups: true` hints show up, prepended before the popup's
    `q Close`. Omit `hint:` to leave the shortcut silent in the status bar.
 
-3. **`Component#key_shortcut`** — a declarative hotkey attached to a
-   component. The framework walks the focused component's subtree for a
-   match and focuses the winner. Good fit for "press F to focus the filter
-   field" or one-key tab pickers. The lookup is suppressed while the
-   focused component owns the hardware cursor (e.g. a `TextField` the user
-   is typing into) so editing isn't interrupted:
-
-   ```ruby
-   filter_field.key_shortcut = "f"
-   ```
-
-4. **`Component#handle_key`** — override this on your own component when
+3. **`Component#handle_key`** — override this on your own component when
    it needs to react to keys directly (a list reacting to arrows, a custom
    widget handling Enter, …). Return `true` to mark the key handled,
-   `false` to let the dispatcher keep walking. Call `super` to keep the
-   default `key_shortcut` subtree lookup; suppress it only when you
-   deliberately want this component to swallow everything:
+   `false` to let the key keep travelling:
 
    ```ruby
    class Toggle < Tuile::Component
@@ -233,7 +221,26 @@ mechanism that handles it wins:
          invalidate
          true
        else
-         super
+         false
+       end
+     end
+   end
+   ```
+
+   The key goes to the focused component first, then **bubbles up its
+   ancestors** to the scope root (the topmost popup, or the tiled content).
+   That makes an ancestor the right home for scope-wide keys — a form's
+   default button, or one-key jumps between panes — and it needs no special
+   protection, because a focused `TextField` consumes the key before the
+   ancestor ever sees it:
+
+   ```ruby
+   class AppLayout < Tuile::Component::Layout::Absolute
+     def handle_key(key)
+       case key
+       when "1" then @files.focus; true
+       when "2" then @log.focus; true
+       else false
        end
      end
    end

data/book/04-event-loop.md

@@ -172,6 +172,92 @@ Reach for `tick` when you're pacing work ("check every two seconds"),
 `tick_fps` when you're driving an animation ("spin at 8 fps"). Same
 machinery underneath; pick the unit that matches how you're thinking.
 
+## Owning a resource for as long as you're on screen
+
+Both examples above end with a loose thread: *who calls `cancel`, and
+when?* If the spinner lives in a popup the user can close, then someone
+has to remember to stop the ticker at exactly the moment the popup goes
+away — and "someone remembers" is how you end up with a timer firing
+against a component nobody can see, forever.
+
+The component itself is the only thing that knows. So it gets told:
+
+```ruby
+class Spinner < Tuile::Component::Label
+  FRAMES = %w[/ - \\ |]
+
+  protected
+
+  def on_attached
+    @ticker = screen.event_queue.tick_fps(8) { |n| self.text = FRAMES[n % FRAMES.size] }
+  end
+
+  def on_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
+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.**
+Keep both cheap and idempotent, because a component *moved* from one parent
+to another gets `on_detached` and then `on_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.
+
+This generalizes well beyond tickers, and the interesting case is
+subscriptions. A component may depend on a service, but a service must never
+reach back up into the UI — so when data has to flow *upward*, the component
+subscribes and the service emits blind. That subscription is a resource with
+exactly the lifetime the hooks describe:
+
+```ruby
+class BuildStatus < Tuile::Component::Label
+  def initialize(service)
+    super()
+    @service = service
+  end
+
+  protected
+
+  def on_attached
+    @subscription = @service.on_change { |s| screen.event_queue.submit { self.text = s } }
+  end
+
+  def on_detached
+    @subscription&.unsubscribe
+    @subscription = nil
+  end
+end
+```
+
+Note the `submit` inside the listener — the service emits from whatever
+thread it likes, and marshalling onto the UI thread is the listener's job,
+exactly as earlier in this chapter. What the hooks add is the other half:
+the subscription exists for precisely as long as the component is on
+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
+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
+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
+to paint, invalidate here and do the work in `repaint`, which is what
+chapter 2 was about anyway.
+
 ## Resize is just another event
 
 A terminal resize could have been handled off the `SIGWINCH` signal

data/book/05-focus.md

@@ -55,8 +55,8 @@ Shift+Tab land on this component while cycling. It's also `false` by
 default, and it *implies* focusable — a tab stop is always a valid focus
 target, but not every focus target is a tab stop. The distinction matters
 for containers: a {Tuile::Component::Window} is focusable (so a click on
-its chrome, or a `key_shortcut`, can focus it) but is *not* a tab stop
-(Tab should skip the frame and stop on the actual inputs inside it). So:
+its chrome can focus it) but is *not* a tab stop (Tab should skip the frame
+and stop on the actual inputs inside it). So:
 
 - **Label** — neither. Decoration.
 - **Window, Popup** — focusable, not a tab stop. Clickable chrome,
@@ -80,8 +80,8 @@ earlier.
 **1. Tab and Shift+Tab — focus navigation, first, always.** These are
 intercepted before anything else and drive the cycling described above.
 They're taken off the top deliberately: a focused text field swallows
-almost every printable key (step 3 explains how), and if Tab weren't
-reserved here, a field would trap it too and you could never Tab out.
+almost every printable key, and if Tab weren't reserved here, a field would
+trap it too and you could never Tab out.
 
 **2. Global shortcuts.** App-level shortcuts registered with
 {Tuile::Screen#register_global_shortcut} fire next, before any component
@@ -95,32 +95,24 @@ screen.register_global_shortcut(Tuile::Keys::CTRL_L,
 end
 ```
 
-Only *unprintable* keys are allowed here (control keys, function keys,
-escape sequences). Printable keys are rejected at registration time,
-because a global binding on `a` would hijack someone typing `a` into a
-text field — that's what the per-component `key_shortcut` in step 3 is
-for. 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. A `key_shortcut` anywhere in the focused scope.** Every component can
-carry a {Tuile::Component#key_shortcut} — a single key that, when pressed,
-*jumps focus to that component*. The screen searches the current modal
-scope's subtree for a component whose shortcut matches; if it finds one,
-it focuses it and consumes the key. A window advertises its shortcut in
-its caption (`[f]-Files`), so a whole pane can be reachable with one key.
-
-But this search is **suppressed while a text widget is mid-edit** — and
-that suppression is the subtle, important part, so it gets its own
-section below.
-
-**4. `handle_key` on the focus chain.** Finally, if nothing above claimed
-the key, it's delivered to the focused component's
-{Tuile::Component#handle_key}, and if that returns `false` (didn't handle
-it), it 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.
+This registry is the only keyboard mechanism that sits *above* the
+component tree, and nothing suppresses it — which is exactly why it's
+picky about what it accepts. Printable keys are rejected at registration
+time, because a global binding on `a` would hijack someone typing `a` into
+a text field. So are Tab and Shift+Tab (step 1 already took them), and so
+are `Screen::EDITING_KEYS` — Enter, Backspace, Delete and the arrows —
+because every editable widget needs those, and a global binding would
+break text entry app-wide with no way for a field to defend itself. What's
+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
+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
@@ -128,32 +120,71 @@ 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.
 
-## Why a text field can just type
+Three rungs, and that's the whole ladder. Tuile used to have a fourth — a
+scan of the scope for a component carrying a matching "shortcut key,"
+which would jump focus to it. It's gone; the next section explains why the
+bubble does that job better.
 
-Here's the problem the cursor-ownership rule solves. Suppose a window has
-a search field, and elsewhere in the same window a list has `key_shortcut
-= "d"` for "delete." You click into the field and type "add item." Should
-the "d" in "add" trigger delete?
+## Scope-wide keys live on an ancestor
 
-Obviously not — and step 3 is where it would go wrong, because "d" *is* a
-registered `key_shortcut` in the scope. The rule that saves you: the
-`key_shortcut` search in step 3 is skipped whenever a component **owns
-the hardware cursor**.
+Two things every app wants: `1`/`2`/`3` to jump between panes, and Enter to
+submit a form. Neither is a *global* action — each belongs to one region of
+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)
+    case key
+    when "1" then @files.focus; true
+    when "2" then @log.focus; true
+    else false
+    end
+  end
+end
+```
+
+Now think about what happens when the user clicks into a search field
+inside `@files` and types "add item". Should the `1` in a typed "item 1"
+jump panes? Obviously not — and it doesn't, for a reason that requires no
+special case at all: **the focused field consumes the key at step 3 and
+returns `true`, so the layout never sees it.** An ancestor only hears the
+keys its descendants declined. That's the whole protection.
+
+The same mechanism gives you a form's default button, one form per popup:
+
+| focused widget | Enter | outcome |
+|---|---|---|
+| `TextArea` | consumes it (newline) | the form never sees it |
+| `TextField` with an `on_enter` | consumes it | no double-submit |
+| `TextField` without one | declines | bubbles up → submit |
+| `Button` | consumes it | activates *itself*, not the default |
+
+Because bubbling stops at the scope root, two forms in two popups each get
+their own Enter — something a global registry structurally cannot do. This
+is also why registering Enter globally is refused in step 2: the registry
+would take it away from all of them at once.
+
+The one thing this shape asks of you is that the *parent* holds the key →
+child table, rather than each widget declaring its own mnemonic. That's a
+fair trade: which key jumps where is a decision about the assembly, and it
+reads well in one place.
+
+## 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::TextField} being edited returns its caret position,
-which is non-`nil`, so the screen knows a text widget is mid-edit and
-suppresses shortcut capture. The "d" flows straight through step 3 to
-step 4, where the focused field's `handle_key` inserts it. Tab (step 1)
-still works, because it's reserved above all this — so you can always Tab
-out of the field, at which point the cursor goes away and shortcuts light
-back up.
-
-That's the entire mechanism: printable keys belong to whoever owns the
-cursor, and owning the cursor mutes the sibling shortcuts that would
-otherwise pick them off.
+cursor is shown there; return `nil` (the default) and there's no cursor. 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.
+
+That's all it does. It positions the hardware cursor; it does not route
+keys. Tuile briefly used it as a proxy for "this widget is in text-entry
+mode, don't steal its printable keys" — a signal the deleted fourth rung
+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.
 
 ## The status bar writes itself
 

data/book/06-theming.md

@@ -38,6 +38,55 @@ 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.
 
+## Backgrounds are opt-in
+
+The stance above — paint accents, leave the rest to the terminal — is how
+the *framework* paints. But sometimes your *app* wants a real background:
+an overlay panel, a slash-command menu, a dropdown that has to read as one
+solid tinted block floating over the content beneath it — filler rows
+included, not a ragged half-shaded box. That is {Tuile::Component#bg_color}.
+
+Set it on a component and that component paints a background behind
+everything it draws; leave it unset (the default) and you get the
+terminal default, exactly as before. The useful part is that it
+**inherits**: set `bg_color` once on a container — a
+{Tuile::Component::Popup}, a layout, a window — and every descendant that
+hasn't set its own picks it up. You tint the panel, and the labels and
+lists inside come out on the same tint without being told individually.
+
+That inheritance has to be *manufactured*, because a terminal has no
+transparency: every cell holds exactly one background, and painting a
+glyph replaces the whole cell (chapter 2's opaque grid). So Tuile resolves
+the effective background at paint time by walking up to the nearest
+ancestor that set a `bg_color` — the same read-at-paint discipline the
+theme uses, and for the same reason: change a container's background and
+its subtree is invalidated and simply repaints in the new color. The
+terminal default is just the root of that chain, which is why an unset
+`bg_color` everywhere behaves exactly like it always has.
+
+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`.
+
+`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
+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
+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
+late-binding it to a token costs nothing. It is the one place an app color
+tracks the theme without the hook.
+
+A reference reaches your *custom* tokens only, never a framework-imposed
+global, so the "no global background token" line holds either way: the
+framework still paints no background of its own. You opt in per
+component — a concrete `Color` when you want it fixed, a `Theme.ref` when
+you want it to follow the scheme.
+
 ## Read at paint time, never cached
 
 There is one rule about *using* the theme that everything else depends
@@ -207,7 +256,10 @@ declaration site says nothing.
 
 The built-in components restyle for free because they read the theme at
 paint time. Your *content* can't always do that — and this is the one
-theming responsibility that lands on the app.
+theming responsibility that lands on the app. (A *background* is the
+exception: `bg_color = Theme.ref(:token)` tracks the theme live with no
+handler, because it's resolved at paint — see "Backgrounds are opt-in"
+above. The hook below is for baked-in *content* colors.)
 
 The problem: when you build a {Tuile::StyledString} for a
 {Tuile::Component::Label} or a {Tuile::Component::List} row, its colors