tuile 0.8.0 → 0.10.0

data/book/05-focus.md

@@ -0,0 +1,219 @@
+# 5. Focus and the keyboard
+
+Chapter 4 ended on a promise: because everything runs on one thread, this
+chapter can describe keyboard handling without a single caveat about
+concurrency. When a key is dispatched, nothing else is happening — no
+repaint mid-flight, no background thread mutating the tree. So the only
+question left is the interesting one: given a keystroke and a tree of
+components, *who gets it?*
+
+The answer has two halves. **Focus** decides which component is the
+current target. **Dispatch** decides the order in which components are
+offered a key — because focus is the common case, not the only case.
+
+## The focus chain
+
+At any moment, at most one component is **focused**. You set it directly:
+
+```ruby
+screen.focused = some_component     # or: some_component.focus
+screen.focused = nil                # nothing focused
+```
+
+Focus is not just a flag on one component, though — it's a *chain*.
+Setting focus walks from the target up through its parents to the root,
+and marks every component on that path **active**. Everything not on the
+path is deactivated. So if you focus a text field inside a window inside
+the content area, the field, the window, and the content are all active;
+their siblings are not.
+
+That active chain is what components paint against. A {Tuile::Component::Window}
+draws its border in the accent color when it's active and a plain color
+when it isn't — which is why, in a multi-window layout, exactly the
+window containing the focused widget lights up. "Active" means "on the
+path to what has focus," and it falls out of one assignment.
+
+## Two gates: `focusable?` and `tab_stop?`
+
+Not everything can be focused, and not everything focusable participates
+in every way of *getting* focused. Two predicates draw those lines, and
+they're independent on purpose.
+
+{Tuile::Component#focusable?} gates whether a component can become a focus
+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. 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.
+
+{Tuile::Component#tab_stop?} gates something narrower: whether Tab and
+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 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,
+  skipped by Tab.
+- **TextField, List, Button** — both. Real inputs you can click *and*
+  Tab to.
+
+Tab cycling is confined to a **modal scope**: the topmost modal popup if
+one is open, otherwise the tiled content. Tab collects the tab stops in
+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.
+
+## The dispatch order
+
+When a key arrives, it's offered to the tree in a fixed order, and the
+first handler to claim it wins. Understanding this order is the whole
+game, because a key you expected one component to get can be intercepted
+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, 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
+sees the key. These are for app-wide actions — "Ctrl+L opens the log,"
+"F1 shows help" — that should work regardless of what's focused:
+
+```ruby
+screen.register_global_shortcut(Tuile::Keys::CTRL_L,
+                                hint: "^L #{screen.theme.hint("log")}") do
+  log_popup.open
+end
+```
+
+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
+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.
+
+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.
+
+## Scope-wide keys live on an ancestor
+
+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, 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
+
+You've seen the bottom row showing hints like `q quit` since chapter 1.
+It's driven by focus. Whenever focus changes, the screen rebuilds the
+status bar from two sources: the currently-relevant shortcuts, and the
+focused context's own advertised hint.
+
+A component advertises its hint by overriding
+{Tuile::Component#keyboard_hint} to return a preformatted string
+(components build these with `theme.hint(...)` so the styling matches).
+The screen composes the bar differently depending on what's in front:
+
+- **Tiled (no popup):** `q quit`, then any global-shortcut hints, then the
+  active window's `keyboard_hint`.
+- **Popup open:** the over-popups global hints, then the popup's own hint
+  (a popup owns its `q Close` prefix).
+
+You don't assemble the bar yourself; you override `keyboard_hint` on the
+components that have shortcuts worth advertising, register global
+shortcuts with a `hint:`, and the composition happens on every focus
+change. The status bar is a *view* of the focus state, not a thing you
+maintain.
+
+---
+
+Focus and dispatch are the last piece of the runtime. You now have the
+whole loop: build a tree (chapter 1), it repaints without flicker
+(chapter 2), sized top-down (chapter 3), driven by a single-threaded
+event loop (chapter 4), with keys routed through focus (this chapter).
+Chapter 6 adds the last cross-cutting concern — color — and then chapters
+7 and 8 turn from *how the framework works* to *what you build with it*.

data/book/06-theming.md

@@ -0,0 +1,302 @@
+# 6. Theming
+
+Every chapter so far has been about *structure* — the tree, the repaint,
+the loop, focus. This one is about a single presentational concern that
+cuts across all of them: color. It's the last cross-cutting piece of the
+runtime, and it's small, because Tuile takes a deliberately narrow view
+of what a "theme" is. A theme in Tuile is not a stylesheet. It does not
+describe how your app looks. It describes the handful of *accents* the
+framework itself paints — and nothing else.
+
+That restraint is the whole design. Understand why the theme is small
+and you understand theming.
+
+## The theme colors only the accents
+
+Look at any Tuile screen and most of what you see is the terminal's own
+colors: the default foreground text on the default background. A label's
+text, a window's interior, the body of a list — none of that is themed.
+It inherits whatever the user's terminal is set to, which already matches
+their preferences perfectly. Tuile writes no background fill and no
+foreground color for those cells, so they come out in the terminal's
+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
+in the status bar. 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,
+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
+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
+on, and it's stated as an invariant in AGENTS.md because breaking it
+breaks live theme switching: **a component reads `screen.theme` at paint
+time, inside `repaint`, and never stores a theme color in an ivar.**
+
+The reason is the repaint model from chapter 2. When the theme changes,
+Tuile does not hunt down every component and tell it which colors to
+update. It does the crude, correct thing: it invalidates the entire tree
+and lets the normal repaint redraw everything. On that repaint each
+component asks `screen.theme` for its accents afresh — so it simply comes
+out in the new colors, with no per-component update logic anywhere. A
+component that cached `theme.active_bg_color` in its constructor would
+keep painting the old color after a switch, an island of stale palette in
+an otherwise-restyled screen. Read it every time; the lookup is a hash
+access, and the repaint that follows a theme change was going to redraw
+you regardless.
+
+This is why the built-in components need no theme-change handling at all.
+They read at paint time, the tree is invalidated, they repaint in the new
+colors. Done.
+
+## Two ways to apply a token
+
+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
+**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 line, 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
+one blunt SGR color would flatten every span to a single hue. For those,
+the theme exposes the raw color as a `*_color` reader
+(`theme.active_bg_color`) and you hand it to the StyledString, which
+composites it *underneath* the existing spans — {Tuile::Component::List}
+highlights its cursor row with `base.with_bg(theme.active_bg_color)`,
+preserving whatever foreground colors the row already carried. The rule
+of thumb: **plain chrome text → helper; structured text → `*_color`
+reader plus StyledString.**
+
+## Following the terminal, automatically
+
+An app never has to ask which theme to use. Tuile picks one by detecting
+whether the terminal background is light or dark, through
+{Tuile::TerminalBackground}.detect — two mechanisms in order of
+reliability. First an **OSC 11 query**: Tuile writes an escape sequence
+asking the terminal for its background color, and a modern terminal
+replies with the RGB, whose luminance decides light versus dark.
+Terminals that don't understand the query simply never answer, so the
+read is bounded by a short timeout and falls through to the second
+mechanism, the `COLORFGBG` environment variable that a few terminals
+export. If both are inconclusive, Tuile assumes dark.
+
+The timing of that detection is subtle enough to be a design constraint.
+The OSC 11 *reply arrives on stdin* — the same stream the key thread will
+own once the event loop is running. If detection ran after the loop
+started, those reply bytes would land in the key thread and be consumed
+as a garbage keystroke. So detection must happen *before* stdin is
+claimed, which is why {Tuile::Screen} runs it in its constructor, seeding
+`theme` before your app has built a single component. This is not an
+implementation detail you can relocate — it's why the constructor, not
+some later `setup` call, is where the scheme is decided.
+
+Detection at startup handles the common case. But a user can also flip
+their OS between light and dark *while your app is running*, and Tuile
+follows that too, on terminals that support **mode 2031**. The event loop
+enables the mode on startup; the terminal then pushes a small report
+whenever the OS appearance changes; the key thread recognizes that report
+(it's a private-mode CSI sequence, longer than an ordinary key, so it's
+drained specially) and turns it into an {Tuile::EventQueue::ColorSchemeEvent};
+and the loop, receiving that event like any other, re-picks the matching
+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.
+
+## Theming an app durably
+
+Detection picks between *Tuile's* two themes. To give your app its own
+colors, you supply your own — and here the distinction between a
+transient override and a durable definition matters, because it's easy to
+reach for the wrong one.
+
+You *can* assign `screen.theme = ...` directly, and it works: the whole
+UI restyles immediately. But it's a **transient override**. The next time
+the OS appearance flips, Tuile re-picks from its theme *definition* and
+replaces whatever you set. A bare `theme=` is the right tool for a
+one-shot experiment, not for how your app looks.
+
+The durable tool is a {Tuile::ThemeDef} — a pair of themes, one for dark
+backgrounds and one for light — assigned once to `screen.theme_def=`.
+Now Tuile picks the matching member at startup *and* re-picks from your
+pair on every appearance flip, so your app stays your app's colors
+through a light/dark toggle. That's the durable path: define the pair,
+assign it once, forget about it.
+
+The pair is required to be a *pair* for a reason. A {Tuile::ThemeDef}
+enforces at construction time that its dark and light members declare the
+same set of custom tokens. Without that check, a token you defined only
+on the dark side would raise `KeyError` the moment the user flipped to
+light — at an unpredictable time, far from the mistake. Checking up front
+turns a lurking runtime crash into an immediate, obvious construction
+error.
+
+### Custom tokens
+
+Your app almost certainly paints colors the framework knows nothing
+about — a "tool call" cyan, an "error" red, diff-line backgrounds. Those
+live in the theme's `custom` hash, a `Hash{Symbol => Color}`. You read
+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.
+
+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
+method:
+
+```ruby
+class AppTheme < Tuile::Theme
+  def error(text) = fg(:error, text)
+  def tool(text)  = fg(:tool, text)
+end
+```
+
+Call sites then read `theme.error("...")` instead of the stringly-typed
+`theme.fg(:error, "...")`, and because a `Data` subclass survives `with`,
+your `AppTheme` stays an `AppTheme` through any `with` derivation. You
+build the dark and light instances from the built-in themes plus your
+custom hashes and pair them in a `ThemeDef` — the pattern is small enough
+to state in full:
+
+```ruby
+class AppTheme < Tuile::Theme
+  def error(text) = fg(:error, text)
+
+  DARK  = new(**Tuile::Theme::DARK.to_h.merge(custom: { error: Tuile::Color::RED }))
+  LIGHT = new(**Tuile::Theme::LIGHT.to_h.merge(custom: { error: Tuile::Color::RED3 }))
+  THEME_DEF = Tuile::ThemeDef.new(dark: DARK, light: LIGHT)
+end
+
+screen.theme_def = AppTheme::THEME_DEF   # once, at boot
+```
+
+Note the light-side error color isn't the same red — bright ANSI accents
+that pop on black often turn illegible on white, so a real light theme
+steps its accents darker. That per-side tuning is the entire point of
+carrying two themes instead of one.
+
+One aside on declaring theme colors: a {Tuile::Theme} takes {Tuile::Color}
+instances *only*, never the lenient coercions (`"red"`, a bare palette
+integer) that {Tuile::Color}.coerce accepts elsewhere. A theme is
+declared once per app, so the extra verbosity buys self-documentation —
+`Color.palette(130)` says "palette index," and the named constant
+`Color::DARK_ORANGE3` says even more, where a bare `130` at the
+declaration site says nothing.
+
+## When the theme changes under your content
+
+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. (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
+are **baked in at construction**. The string is a frozen value with its
+SGR bytes already computed; it does not consult the theme at paint time,
+because {Tuile::StyledString} deliberately knows nothing about `Screen` at
+all (that independence is what lets it be a pure, memoizable value type).
+So if you colored a label with `theme[:accent]` and the theme later
+changes, that label keeps its old accent — the framework can't fix it,
+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
+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.
+
+```ruby
+label.on_theme_changed = -> { label.text = render_status_line }
+```
+
+There are two ways to consume it, matching how you built the component.
+If you assembled stock components, assign the `on_theme_changed=` proc as
+above. If you subclassed, override the method — and call `super`, so an
+assigned listener still fires. Either way the rule is the same: the hook
+is where theme-derived content gets rebuilt, and the framework handles
+everything else.
+
+---
+
+That closes the runtime. Across six chapters you've seen the whole
+machine: a tree of components (chapter 1), repainting without flicker
+(chapter 2), sized top-down by their parents (chapter 3), driven by a
+single-threaded event loop (chapter 4), with keys routed through focus
+(chapter 5) and accents drawn from a terminal-following theme (this one).
+Everything from here is *application*: chapter 7 tours the component
+library — what Tuile ships so you don't build it — and chapter 8 shows
+how to test a UI built this way, using the fakes the design has been
+quietly setting up all along.