tuile 0.12.0 → 0.13.0

data/book/07-components.md

@@ -71,10 +71,11 @@ That cap counts *characters*, and the distinction matters more than it
 looks. A field position is either an index into the text or a column on the
 terminal, and the two coincide only while every glyph is one column wide —
 a fullwidth CJK character is two columns, a combining mark zero. So `caret`
-and `max_text_length` speak indices, while `rect`, `left_column` and a mouse
-click speak columns, and the field converts between them rather than
-assuming they're the same number. You don't need to think about this to use
-a TextField; you do the moment you write a component that paints text.
+and `max_text_length` speak indices, while `rect`, the field's horizontal
+scroll offset and a mouse click speak columns, and the field converts between
+them rather than assuming they're the same number. You don't need to think
+about this to use a TextField; you do the moment you write a component that
+paints text.
 
 There's a third unit hiding in there, and it's the one your *user* thinks
 in: the glyph they see. A single visible character can be several characters
@@ -530,16 +531,59 @@ gets ellipsized. It opens below the select, flips above near the bottom of
 the screen, slides left rather than running off the right edge, and grows a
 scrollbar when there are more options than it can show.
 
-For a discrete action rather than a selection, {Tuile::Component::Button}
-is a one-row `[ caption ]` that fires `on_click` on Enter, Space, or a
-left-click, highlighting its background while focused. It's a tab stop, so
-it joins the normal Tab cycle.
+## Taking an action
+
+Every component so far *holds* something — a value, a selection, a cursor
+into a list. {Tuile::Component::Button} holds nothing. It runs a block:
+
+```ruby
+save = Component::Button.new("Save") { form.submit }
+save.on_click = -> { form.submit }   # or assign it afterwards
+```
+
+It paints as `[ Save ]` on one row, highlights its background while it is on
+the focus chain, and is a tab stop, so Tab reaches it like any field. Enter,
+Space and a left click all fire `on_click`, and the callback takes no
+arguments — a button has nothing to report, because that it was pressed *is*
+the event.
+
+**Sizing it is your job**, exactly as chapter 3 promised: there is no channel
+for a component to advertise the width it would like, so the caller does the
+arithmetic. For a button that's the caption plus the four columns `[ ` and
+` ]` occupy:
+
+```ruby
+# inside a Layout subclass, where the constraint names are already in scope
+add(save, Fixed[save.caption.display_width + 4])
+```
+
+Get it wrong in either direction and the failure is graceful rather than
+broken: a narrower rect ellipsizes the label, and a wider one leaves a tail
+that *focuses* but doesn't fire — the same `extent` rule the checkbox above
+spells out, and buttons follow it identically. (The sampler keeps a one-line
+`button_width` helper for this, which is what "the app does the arithmetic"
+looks like in practice.)
+
+**A focused button consumes Enter**, and that matters the moment you have
+more than one. Enter on a focused `Save` activates *that* button — not some
+form-wide default, because Tuile has no notion of a default button at all.
+The form's Enter-to-submit is a `handle_key` on the ancestor that owns the
+form (chapter 5), and it only ever sees Enter when the focused widget
+declined it. So a dialog's two buttons are just two widgets, and which one
+Enter hits is simply which one has focus.
+
+One thing you will look for and not find: **there is no disabled state.**
+Tuile has no enabled/disabled seam on any component, so a button that
+shouldn't be pressable yet is one you don't add to the tree, or one whose
+block checks the precondition and says why. That's less of a gap than it
+sounds on a TTY, where a greyed-out control is hard to distinguish from a
+styled one anyway.
 
 ## Reporting progress
 
-Everything so far either shows text or captures input.
-{Tuile::Component::ProgressBar} does neither: it reports, and it is the
-first component in this tour you never focus and never type into. A run of
+Everything so far either shows text, captures input, or acts on it.
+{Tuile::Component::ProgressBar} does none of those: it reports, and it is
+the first component in this tour you never focus and never type into. A run of
 `█` grows left to right over a `░` track, measured against a range you set:
 
 ```ruby
@@ -630,6 +674,334 @@ window.content = Component::List.new.tap { _1.lines = entries }
 window.scrollbar = true
 ```
 
+## Switching between views
+
+When a screen has more content than fits and the parts are *alternatives*
+rather than neighbours — a settings dialog's General / Network / Advanced,
+a monitor's Requests / Errors / Config — you want one visible at a time and
+a way to pick. That's {Tuile::Component::TabSheet}: a one-row strip of
+captions across the top, and below it the pane belonging to whichever tab
+is selected.
+
+```ruby
+sheet = Component::TabSheet.new
+sheet.add_tab("Details", details_form)     # the first tab is selected
+sheet.add_tab("Payment", payment_form)
+sheet.on_tab_selected = ->(index, tab) { status.text = "on #{tab&.caption}" }
+```
+
+The strip is a component in its own right, {Tuile::Component::Tabs}, and
+you can use it alone when the thing being switched isn't a pane you want
+the sheet to own — repointing a `TextView` at a different document, say, or
+driving a swap somewhere else entirely on the screen. `TabSheet` is the
+convenience of "strip plus the pane that goes with it"; `Tabs` is the
+selector by itself.
+
+### A selection is not a value
+
+`Tabs` is not a {Tuile::Component::HasValue} field, and the test that
+tells you why is worth carrying to your own components: **would a form save
+it?** A {Tuile::Component::RadioGroup}'s selection *is* the datum being
+edited — it goes in the record — so it's a value. A tab's selection is
+where the user happens to be looking. Nothing saves it, nothing validates
+it, and a form iterating its fields should never find it. So the strip
+speaks in its own words — `selected`, `selected_index`, `on_tab_selected`
+— and stays out of the seam the value section earlier in this chapter set
+up.
+
+`on_tab_selected` reports that the selection *changed*, not that the user
+pressed something: arrows, a click, an assignment from your own code, the
+autoselect of the very first tab, and the re-selection that follows
+removing the selected tab all reach it. When the last tab goes it fires
+with `(nil, nil)`, which matters if you render from it — you have to be
+told to render *nothing*, or the departed tab's content sits there with no
+tab pointing at it.
+
+### The strip is one tab stop, and arrows switch immediately
+
+Tab lands on the strip, and Tab again enters the pane — the browser's
+order, and you get it for free: the strip is the sheet's first child, and
+Tab collects the tab stops in tree order (chapter 5). Within the strip,
+Left and Right switch tabs. Tab itself
+never moves *between* tabs: it means "leave this widget" everywhere in
+Tuile, and a strip is one widget.
+
+Switching is immediate — there is no cursor to walk across the strip and no
+Enter to confirm — and that is a design choice with a visible payoff.
+Manual activation would need two states on one row, the tab you're on and
+the tab you're pointing at, and therefore two ways of marking them. Making
+the arrows *be* the selection leaves exactly one thing highlighted, which
+is why the strip can spend both of its visual channels on saying where you
+are: the selected caption is **bold always**, and it additionally sits on
+the theme's `active_bg_color` while the strip has focus. Bold is the one
+that survives focus moving away — the strip is the map of where you are in
+the app, and a map shouldn't go blank when you look somewhere else.
+
+Everything else bubbles. Enter, Space, Home, End, the vertical arrows and
+every printable pass straight through to your ancestors, so a form's
+default button and an app's own keys keep working while the strip has
+focus. If you want a key elsewhere in the app to drive the strip — a
+`Ctrl+PageDown` habit from your editor — bind it yourself and call
+`select_next` / `select_previous`. Tuile ships no such binding, because
+"one key, anywhere, meaning switch tab" is a statement about your app, and
+with nested sheets it would be ambiguous about *which* sheet.
+
+### Tabs are handles, not items
+
+Everywhere else in this chapter, a widget takes a collection: `items=`,
+`lines=`. A strip doesn't. `add_tab` mints a {Tuile::Component::Tabs::Tab}
+and hands it back, and you keep it:
+
+```ruby
+payment = sheet.add_tab("Payment", payment_form)
+payment.caption = "Payment ⚠"    # repaints the strip
+payment.remove                   # the handle raises from here on
+```
+
+The difference isn't cosmetic. An item is an element of a collection
+somebody else owns — assign the whole array and the widget renders what it
+finds. A tab is an identity with its own state, and it is what a
+`TabSheet` keys its pane mapping by. Handing the strip a fresh array would
+destroy those identities and the mapping with them, so the operation
+simply isn't offered: you add and remove tabs one at a time. Captions are
+mutable through the handle, and a removed one raises on every mutation and
+on anything it would have to ask the strip — better than quietly answering
+about a tab that is no longer there. Its caption stays readable, so an
+error message can still name it.
+
+### Hiding a component means detaching it
+
+Here is the part with consequences beyond this widget. **Tuile has no
+visibility flag.** There is no `visible?`, no `display`; the empty rect you
+met in chapter 2 gates *painting* and nothing else — an "invisible" widget
+with an empty rect is still in the Tab cycle, still a target of the focus
+cascades, still answering for the cursor. So hiding, in Tuile, means taking
+something out of the tree, and that is exactly what a `TabSheet` does: only
+the selected tab's pane is a child of the sheet, and the rest are detached.
+
+Three things fall out of that, and they're the reason it's the right
+mechanism rather than a workaround for a missing feature:
+
+- **A hidden pane is invisible to everything** — the Tab cycle, focus,
+  repaint, the cursor, tree walks. Not because anything checks a flag, but
+  because it isn't there. There is no gate to get wrong.
+- **Its state survives, because state is ivars.** Scroll position, caret,
+  list cursor, typed text: all exactly as the user left them. You can go on
+  mutating a hidden pane too, with no special handling and no "am I
+  visible?" check — `invalidate` on a detached component is a silent no-op,
+  and the sheet assigns it a rect and invalidates it when it comes back.
+- **The lifecycle hooks fire on every switch.** `on_detached` when a pane
+  goes away, `on_attached` when it returns — so a
+  {Tuile::Component::ProgressBar} in a hidden tab stops its ticker and
+  restarts it on return, with no bookkeeping from you.
+
+The cost is the mirror image of that last point: a pane that must keep
+something *alive* while hidden can't, because chapter 4's
+`on_attached`/`on_detached` contract is exactly what detachment triggers. The
+way out is to move the thing that must not stop: give the resource to the
+model your pane renders rather than to the pane, and let the pane pick up
+its current state on return. That is usually the better shape anyway — if
+you're reluctant to let a hidden pane's poller or subscription die, it
+probably wanted to outlive the view all along.
+
+The `TabSheet` pane in `examples/sampler.rb` demonstrates the state part
+directly: scroll the prose tab, switch away, come back, and the status line
+under the sheet reports the row you left it on.
+
+### When the strip is too narrow
+
+Give a strip the width its captions need and there is nothing here to think
+about; with the three to five tabs this shape is actually for, that is the
+normal case. When a layout can't give it that width — a narrow terminal, a
+caption that grew a badge — the strip **scrolls** rather than putting some of
+its tabs out of reach. It keeps the selected segment whole in view and moves
+its window by the smallest amount that does so, so arrowing along an
+overflowing strip walks the selection off one edge and the strip follows it,
+a tab at a time.
+
+Two things tell you there is more strip than you can see. The captions at the
+edges are cut mid-word, which is the oldest overflow hint there is; and a `<`
+or `>` is painted over the edge column itself. The cue is there because the
+cut alone isn't reliable — scroll to just the right place and a segment
+boundary lands exactly on the edge, leaving clean space that reads as "that's
+all of them". The cues are ASCII, they are painted whether or not the strip
+has focus (overflow is a fact about the captions and the rect, not about
+where you are), and they are not buttons: a click on one lands on the
+half-visible segment underneath, which selects that tab and pulls it into
+view — the direction the cue was pointing anyway.
+
+The one thing a strip cannot do is show a caption wider than the whole rect.
+There it gives you the head and clips the tail, on the grounds that the start
+of a word identifies it and the end usually doesn't.
+
+## Menus
+
+A menu bar is the other way to say "the app can do these things", and it
+answers a different question from tabs. Tabs are a *map*: they show where
+you are, and switching one changes what you're looking at. A menu is a
+*catalogue of verbs*: it shows what you can do, it closes again the moment
+you pick, and it leaves the screen exactly as it was. If the caption names
+a place, use tabs; if it names an action, use a menu.
+
+{Tuile::Component::MenuBar} is one row of captions, and each of them drops
+open a menu:
+
+```ruby
+bar = Component::MenuBar.new
+
+file = bar.add_item("File")
+file.add_item("New")  { new_document }
+file.add_item("Open") { open_dialog }
+recent = file.add_item("Open recent")            # no block ⇒ a submenu
+recent.add_item("notes.txt") { open("notes.txt") }
+
+bar.add_item("About") { show_about }             # a top-level leaf: a button
+```
+
+Two things about that snippet do most of the work. First, `add_item` is the
+*same* method on the bar and on an item, so nesting needs no new vocabulary
+— and because an item can hold items, submenus go as deep as you build
+them. Second, whether an item is a submenu or an action is not something
+you declare: an item with children *is* a submenu, and its own block (if
+you gave it one) is simply dead. That's why `recent` above takes no block
+and `"New"` does. A top-level item with no children isn't a menu at all —
+it's a button on the bar, which is exactly how you get a single "About" or
+"Help" entry without inventing a one-item menu for it.
+
+An item with neither children nor a block is legal, and does nothing. It
+highlights, Enter closes the menu, and nothing happens. That is a deliberate
+non-decision: a half-built menu is a programming error you'll see the moment
+you run the app, and it isn't worth an exception that fires while you're
+still assembling the thing.
+
+### The bar keeps focus the whole time
+
+This is the part worth understanding, because it explains everything else.
+The open menus are **overlays**, not children of the bar — they're mounted on
+the screen pane, floating above whatever they cover, and they never take
+focus. Focus stays on the strip from the moment you open a menu until it
+closes, however deep you drill. So the bar receives every keystroke and
+decides what to do with it; the panels are things it draws and drives.
+
+That is the same arrangement {Tuile::Component::Select} uses for its
+dropdown (chapter 5 has the key-dispatch ladder this rests on), and it
+buys two properties. The whole widget is one tab stop — Tab moves *past*
+the bar, never into a menu. And nothing about menus needed adding to the
+framework's key handling: a menu is not a mode.
+
+The keyboard map is the one every menu bar has had since Turbo Vision, and
+it's worth learning once because Vaadin, the web's ARIA pattern and every
+other TUI toolkit agree on it:
+
+| While the bar has focus | |
+|---|---|
+| Left / Right | move along the strip |
+| Enter, Space, Down | open the highlighted menu |
+| a mnemonic letter | open that menu (see below) |
+| anything else | bubbles to your app |
+| **Inside an open menu** | |
+| Up / Down (PgUp/PgDn, Ctrl+U/D) | move the highlight |
+| Right, Enter, Space | open the submenu under the highlight |
+| Enter, Space | activate a row that has no submenu |
+| Left | back to the previous menu |
+| Left at the first level, Right on a plain row | step to the neighbouring menu |
+| a mnemonic letter | activate that row of *this* menu |
+| ESC | close one level |
+
+Stepping sideways *shows* the neighbour's menu; it never presses anything. So
+arrowing onto a top-level button — an item with a listener and no menu — closes
+whatever was open and highlights it, and it fires only when you press Enter or
+Space. Otherwise walking the strip would trigger every button on it.
+
+The last row of the first block matters for real apps: while the bar merely
+has focus, every other key **bubbles past it**, so a form's `s`-to-save or
+a layout's `1`/`2`/`3` pane jumps keep working. An *open* menu is different
+— it swallows what it doesn't recognize. A menu is a quasi-modal moment, and
+an app key firing behind a panel you can see would be worse than a keystroke
+that does nothing.
+
+### What it looks like, and why it isn't a tab strip
+
+The strip paints ` File  Edit  View ` — each caption with a space either
+side, no separator column, and the menu that Enter would open highlighted
+while the bar has focus. Move focus away and the highlight goes entirely.
+
+Compare that with the tab strip earlier in this chapter, which keeps its
+selected caption **bold** even unfocused and rules its segments apart with
+`│`. The difference is on purpose. A tab strip has to say where you are
+after focus has moved on, so its selection is permanent and needs a channel
+that survives losing focus. A menu bar has nothing permanent to say: close
+the menu and no item is selected, because you are not "in" File the way you
+are "on" the Details tab. Two one-row caption strips that looked the same
+would make you work out which control you were looking at; these two don't.
+
+What the two *do* share is everything from "When the strip is too narrow"
+above. A bar that outgrows its terminal scrolls to keep the highlighted menu
+whole in view, cues the hidden captions the same way, and stays reachable by
+arrow, by mnemonic and by click — a mnemonic jumping to a menu off the right
+edge brings it on screen before its panel opens.
+
+### Mnemonics: one letter per level
+
+Give an item a letter and it answers to it:
+
+```ruby
+file = bar.add_item("File", mnemonic: "f")
+file.add_item("Export", mnemonic: "e") { export }
+file.add_item("Quit",   mnemonic: "q") { quit }
+bar.add_item("Edit", mnemonic: "e").add_item("Copy", mnemonic: "c") { copy }
+```
+
+The letter is underlined in the caption where it occurs — `F̲ile` — on the
+strip and in every open panel, whether or not the bar has focus. There is no
+Alt key to reveal them with, so they are simply always visible.
+
+Now press `f`, then `q`: File opens, Quit fires. That reads like a two-key
+accelerator, but it is nothing so clever — it is two ordinary keystrokes, and
+the second one means something different because the first one changed what
+is on screen. That is the whole rule:
+
+> A mnemonic is matched against **one** set of items: the top-level ones
+> while no menu is open, and the deepest open menu's while one is. Nothing
+> else is ever consulted.
+
+Read the example again with that in mind and notice what *cannot* happen.
+`Export` and `Edit` both bind `e`, and there is no conflict to resolve —
+with File open, `Edit` is not one of the candidates, so `e` means Export. If
+you close the menu first, `e` means Edit. The two are never in the same
+lookup, so the framework never has to guess, and you never have to hunt for
+a free letter across the whole tree. Only *siblings* compete, and two
+siblings claiming one letter is a mistake Tuile refuses at `add_item` rather
+than resolving at the keyboard.
+
+The same rule says what a *wrong* letter does. With File open, `v` matches
+nothing in File's menu — and nothing happens. It does not fall out to the
+strip and open the View menu, because a mistyped letter tearing down the
+menu you are reading would be a poor trade for a shortcut. You get the
+terminal bell instead, and Left, Right and ESC are still there to move.
+
+One cost to know about, because it is what a mnemonic *means*: while the bar
+has focus, its letters win. A `mnemonic: "s"` eats the `s`-to-save described
+above, and a `mnemonic: "q"` inside a popup eats the popup's own `q`-to-close.
+That is the bubble working correctly — the focused component is asked first
+— but it is worth a thought before binding a common letter.
+
+**A click outside an open menu closes it.** The panels float above the UI
+without blocking it (chapter 3's overlays are all like this), so the click
+still reaches whatever it was aimed at — but on its way the screen dismisses
+the cascade, so a menu can't linger over content it no longer belongs to.
+Clicking *within* the menu is not outside it, whichever panel you land on:
+the panels are chained to each other, so drilling into a submenu by mouse
+leaves the levels above it standing. ESC and Tab also get you out.
+
+### One thing it deliberately doesn't do
+
+**A resize closes an open menu.** Every panel is positioned against
+something — the strip segment it dropped from, or the parent row it cascaded
+out of — so after the terminal changes size those positions are all stale.
+Recomputing them level by level is possible; closing is unambiguous, and
+every GUI dismisses its menus on a window resize too.
+
 ## Overlays
 
 {Tuile::Component::Popup} is how you float something above the tiled UI.
@@ -649,6 +1021,22 @@ floats above the content without taking focus — the autocomplete-list case
 from earlier, where the caller positions it against a field's caret and
 drives it from app code.
 
+**A left click outside a popup closes it**, modal or not — the same light
+dismissal a desktop dialog gives you. It's a per-popup switch,
+`close_on_outside_click`, on by default; a popup that must survive stray
+clicks turns it off, as a Notification does. The click still reaches
+whatever was beneath it, unless an open modal swallowed it — in which case
+the first click dismisses and a second one acts.
+
+"Outside" means more than "outside this rectangle". An overlay opened by a
+component that lives inside another popup — a ComboBox on a dialog, whose
+dropdown drops past the dialog's own border — says so with `owner`, and a
+click landing in it then counts as landing inside the dialog too. Otherwise
+picking from the dropdown would dismiss the form under it. Overlays that
+*aren't* related that way stay independent: clicking one dismisses the
+other, as two dismissable windows should. You only need `owner` when you
+build a compound overlay of your own; the built-in ones already set it.
+
 Because the popup is just a transparent host, you get a bordered dialog by
 wrapping a Window:
 
@@ -700,7 +1088,9 @@ Everything else follows from "a toast must not interrupt": it's a non-modal
 popup, so it takes no focus, receives no keys (not even the `q` a normal
 popup would claim), and blocks no click outside its own box. You keep
 typing into whatever you were typing into, and the notification appears and
-leaves around you. A left-click on the box dismisses the whole thing early.
+leaves around you. A left-click on the box dismisses the whole thing early;
+a click anywhere else doesn't, because a toast is timed and an unrelated
+click isn't about it.
 
 Two limits are worth knowing before you reach them. A long message wraps to
 at most three rows and is then ellipsized — the box is capped at 40 % of

data/book/08-testing.md

@@ -28,10 +28,13 @@ after  { Screen.close }
 `Screen.fake` installs a {Tuile::FakeScreen} as the process singleton — a
 `Screen` subclass with the terminal amputated. It has a fixed 160×50
 viewport (so geometry is deterministic, independent of whoever's terminal
-runs the suite), it writes nothing to any TTY, its `check_locked` is a
-no-op so you can mutate the UI freely from the test thread without holding
-the UI lock, and its event queue is the synchronous {Tuile::FakeEventQueue}
-(more on that below). It also pins the color scheme to `:dark`, skipping
+runs the suite), it writes nothing to any TTY, and its event queue is the
+synchronous {Tuile::FakeEventQueue} (more on that below). You can mutate the
+UI directly from your example — and note there is no lock *bypass* doing
+that for you: the fake runs no loop, so `running?` is false and chapter 4's
+rule falls back to "the thread that created the screen," which is yours. A
+spec that mutates the UI from a **spawned** thread therefore raises, exactly
+as an app would. It also pins the color scheme to `:dark`, skipping
 the OSC 11 probe from chapter 6 — a probe would otherwise write an escape
 query to the test runner's terminal and swallow its input.
 
@@ -44,6 +47,17 @@ from nothing. Skip the `after` and you get the classic singleton test
 smell: passes in isolation, fails in suite, order-dependent. The pair is
 not boilerplate you can trim.
 
+One more line of setup earns its place if your app has a theme of its own. A
+fresh `Screen.fake` starts from the built-in {Tuile::ThemeDef}, so a
+component reading `theme[:my_token]` would `KeyError` in every example.
+Rather than assigning `Screen.instance.theme_def` in every `before` block,
+point the construction-time default at your definition once, in
+`spec_helper`:
+
+```ruby
+Tuile::ThemeDef.default = APP_THEME   # every Screen.fake now carries it
+```
+
 ## Asserting what got painted
 
 Here's where the back buffer earns its keep. Recall from chapter 2 that

data/book/README.md

@@ -66,17 +66,19 @@ one, not to fill an outline.
    `focusable?`, and the three-rung order in which a keystroke is offered
    to the tree — Tab, global shortcuts, then `handle_key` delivered to
    focus and bubbling up its ancestors. Why scope-wide keys (pane jumps, a
-   form's default button) belong on an ancestor, and how `keyboard_hint`
-   drives the status bar.
+   form's default button) belong on an ancestor, why a paste rides its own
+   path rather than the ladder, and how to write a status line over
+   `on_focus_changed` — Tuile draws none for you.
 6. **[Theming](06-theming.md).** Semantic color tokens read at paint
    time, opt-in component backgrounds that inherit down the tree
    (`bg_color`), light/dark auto-detection at startup and live OS
    appearance flips, pairing variants in a `ThemeDef`, app-specific custom
    tokens, and rebuilding theme-derived content in `on_theme_changed`.
 7. **[The component library](07-components.md).** A narrative tour of
-   the shipped toolbox — Window, List, the text inputs and views,
-   ProgressBar, Popup, and the window conveniences — framed around
-   *when and why* you reach for each. Signatures stay in the rdoc.
+   the shipped toolbox — the text inputs and views, the value fields, the
+   selectors, Button, ProgressBar, Window, TabSheet, MenuBar, Popup and the
+   window conveniences — framed around *when and why* you reach for each.
+   Signatures stay in the rdoc.
 8. **[Testing a Tuile app](08-testing.md).** The testing approach:
    `FakeScreen`, asserting against the painted buffer, driving
    invalidation, and PTY-based end-to-end tests of runnable scripts.

data/examples/file_commander.rb

@@ -4,7 +4,9 @@
 # Tuile two-pane file commander. Two windows side by side, each showing a
 # directory listing. Tab switches active pane; arrows / jk move the cursor;
 # Enter descends into a directory (no-op on a regular file); Backspace
-# ascends to the parent. The header label shows the active pane's cwd.
+# ascends to the parent. The header label shows the active pane's cwd, and a
+# static status line spells out the keys — Tuile draws no status bar and
+# reserves no row, so both are ordinary children of the layout.
 # Unreadable directories surface an InfoWindow. Layout follows the
 # terminal on resize (WINCH) — the framework dispatches a TTYSizeEvent and
 # the layout's `rect=` rebuilds the geometry.
@@ -107,18 +109,6 @@ module FileCommanderExample
     end
   end
 
-  # A pane window that advertises navigation shortcuts in the status bar.
-  # The active window's `keyboard_hint` is rendered by {Tuile::Screen}
-  # alongside the global `q` quit hint, so all the user-facing controls
-  # land in one place.
-  class PaneWindow < Tuile::Component::Window
-    def keyboard_hint
-      "Tab #{screen.theme.hint("Switch")}  " \
-        "Enter #{screen.theme.hint("Open")}  " \
-        "Bksp #{screen.theme.hint("Up")}"
-    end
-  end
-
   # Top-level layout. Header label on the first row, two side-by-side
   # windows below. `rect=` re-runs on the initial mount and on every WINCH,
   # so the split tracks the terminal size automatically.
@@ -128,19 +118,34 @@ module FileCommanderExample
       @header = Tuile::Component::Label.new
       add(@header)
 
-      @left_window = PaneWindow.new
+      @left_window = Tuile::Component::Window.new
       @left_list = DirList.new(left_dir)
       @left_list.on_cwd_changed = method(:refresh_header)
       @left_window.content = @left_list
       @left_window.scrollbar = true
       add(@left_window)
 
-      @right_window = PaneWindow.new
+      @right_window = Tuile::Component::Window.new
       @right_list = DirList.new(right_dir)
       @right_list.on_cwd_changed = method(:refresh_header)
       @right_window.content = @right_list
       @right_window.scrollbar = true
       add(@right_window)
+
+      # The status line. Every key here works in both panes, so the row never
+      # changes and nothing needs to watch focus — a status line is only worth
+      # wiring to Tuile::Screen#on_focus_changed= when its text actually varies
+      # with the focused component. `theme.hint` bakes its colors in, so the
+      # one thing this label does watch is a light/dark flip.
+      @status = Tuile::Component::Label.new
+      render_status = lambda do
+        t = screen.theme
+        @status.text = "q #{t.hint("quit")}  Tab #{t.hint("Switch")}  " \
+                       "Enter #{t.hint("Open")}  Bksp #{t.hint("Up")}"
+      end
+      render_status.call
+      @status.on_theme_changed = render_status
+      add(@status)
     end
 
     attr_reader :left_window
@@ -150,8 +155,9 @@ module FileCommanderExample
       return if rect.empty?
 
       @header.rect = Tuile::Rect.new(rect.left, rect.top, rect.width, 1)
+      @status.rect = Tuile::Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
       body_top = rect.top + 1
-      body_height = [rect.height - 1, 0].max
+      body_height = [rect.height - 2, 0].max
       half = rect.width / 2
       @left_window.rect = Tuile::Rect.new(rect.left, body_top, half, body_height)
       @right_window.rect = Tuile::Rect.new(rect.left + half, body_top,

data/examples/hello_world.rb

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Tuile hello-world. A Window wrapping a Label.
+# Tuile hello-world. A Window wrapping a Label, over a status line the app
+# owns — Tuile draws no chrome of its own and reserves no row.
 #
 # Run from the gem root:
 #   bundle exec ruby -Ilib examples/hello_world.rb
@@ -14,12 +15,23 @@ require "tuile"
 # Tuile::Screen.instance during invalidate/repaint hooks.
 screen = Tuile::Screen.new
 
-label = Tuile::Component::Label.new("Hello, world!")
-
 window = Tuile::Component::Window.new("Tuile")
-window.content = label
+window.content = Tuile::Component::Label.new("Hello, world!")
+
+# The status line. `theme.hint` styles the *description* half of a "key what"
+# pair, and bakes the color in — so the label rebuilds itself from
+# `on_theme_changed` to follow a light/dark flip.
+status = Tuile::Component::Label.new
+render_status = -> { status.text = "q #{screen.theme.hint("quit")}" }
+render_status.call
+status.on_theme_changed = render_status
+
+# One row for the status line, everything else to the window.
+root = Tuile::Component::Layout::Vertical.new
+root.add(window, Tuile::Component::Layout::Expand[1])
+root.add(status, Tuile::Component::Layout::Fixed[1])
 
-screen.content = window
+screen.content = root
 window.focus
 begin
   screen.run_event_loop