tuile 0.12.0 → 0.13.0

data/TERMINOLOGY.md

@@ -19,10 +19,12 @@ needs a paragraph of justification, that paragraph belongs in one of those three
 | **cluster** | a grapheme cluster — the unit measurement, slicing, caret motion and deletion all work in. Never `each_char`. |
 | **row_in_viewport** | a row measured `0...rect.height`, i.e. relative to a component's own rect. |
 | **scroll_top_row** | the content row currently sitting at the top of the viewport. |
+| **left_column** | the content column currently painted in a widget's leftmost cell — the horizontal counterpart of `scroll_top_row`. Private wherever it exists (`TextField`, `Tabs`, `MenuBar`): what a caller relies on is the invariant it maintains — the caret, or the selected segment, is in view — not the number. |
 | **viewport_rows** | how many rows of content are visible — always `rect.height`; kept private, since `rect.height` is the public form. |
 | **row_count** | how many rows the wrapped content occupies. Public on `TextArea` (with `caret_row`, its companion); also on the private `WrappedText` and as `VerticalScrollBar.new(row_count:)`. Not on `TextView` / `List`, which have no caller for it. |
 | **caret_row** | the row a text input's caret sits in, counted from the content's first row. `TextArea` only. |
-| **extent** | the sub-rect a one-row caption widget actually occupies (`min(caption width + 4, rect.width)`), used for its highlight and hit test — narrower than its `rect`. |
+| **extent** | the sub-rect a one-row widget actually paints, used for its highlight and hit test — narrower than the `rect` it was given. The arithmetic is each widget's own (a `Checkbox`'s glyph plus caption; a `Tabs` strip's segments and separators), never a `Component` method. |
+| **segment** | one tab's span on a {Tuile::Component::Tabs} strip: its caption plus a padding column either side. The unit a click resolves to; the separator column between two segments belongs to neither. |
 
 **Space rule 1.** An object with only one row space leaves `row` unqualified:
 {Tuile::Buffer} *is* the grid, so its rows are screen rows;
@@ -40,10 +42,11 @@ content-space.
 | **line_count** | a count of `\n` units (`TextView::Region#line_count`). Never a row count. |
 | **item** | a domain object a widget holds and renders — `List#items`, and the enum widgets above it. |
 | **renderer** | the `item -> row` proc a generic component uses to render an item it knows nothing about. |
+| **selection** | which item or tab a selector currently points at. *View state* when nothing would save it ({Tuile::Component::Tabs}`#selected`), a *value* when a form would (`RadioGroup#value`) — the split `D-tabs` calls the "would a form save it?" test. |
 | **item_count** / **item_index** | how a `List::Cursor` counts and addresses; equal to a row count in a `List`, but the cursor indexes *items*. |
 | **text** | the user-editable **value** of an input ({Tuile::Component::HasValue}, aliased as `text` on `AbstractStringField`). |
 | **caption** | app-authored **chrome** text ({Tuile::Component::HasCaption}) — a `Window` title, a `Button` label. Never a value. |
-| **chrome** | framework- or app-authored decoration around content: captions, borders, footers, the status bar. |
+| **chrome** | framework- or app-authored decoration around content: captions, borders, footers, an app's status line. |
 | **caret** | the index into an input's `text` where editing happens; always on a cluster boundary. Distinct from the *cursor*. |
 
 ## Tree, paint and theme
@@ -54,6 +57,12 @@ content-space.
 | **tile** / **tiled** | the non-popup part of the tree — `ScreenPane#content` and its descendants. Also *to tile*: to cover a rect completely. |
 | **attached** | reachable from a {Tuile::ScreenPane} via the parent chain — the one axis `attached?` consults. |
 | **slot** | a named child a container holds by identity (`content`, `footer`) as well as in `children`. |
+| **cascade** | the stack of open {Tuile::Component::ListDropdown} panels a {Tuile::Component::MenuBar} drives, one per level, the last deepest. Each is an overlay on the pane, not a child of the bar. |
+| **submenu** | a menu item that opens a further panel instead of doing something — `MenuBar::Item#submenu?`, true iff the item has children. Painted with a trailing `▸`. |
+| **mnemonic** | a letter that activates one {Tuile::Component::MenuBar} item, underlined in its caption. Always *level-scoped*: matched against the top-level items while the cascade is closed and the deepest open panel while it is open, never across the two. |
+| **strip** | the one-row {Tuile::Component::Tabs} component: captions, one selected, no content of its own. A {Tuile::Component::MenuBar} has one too — same word, and the same extent-based hit testing, deliberately not the same look. |
+| **tab** | a {Tuile::Component::Tabs::Tab} — a caption plus an identity, minted and owned by the strip. Not a component (it never paints itself) and not an *item* (it holds per-element state, and the set is never assigned whole). Say "a tab" and "the Tab key"; never let the two words touch. |
+| **pane** | the component a {Tuile::Component::TabSheet} shows for the selected tab. The unselected ones are *detached*, which is how Tuile hides a component. |
 | **invalidate** | record a component as needing repaint; the loop coalesces and repaints once per tick. |
 | **cursor** | *(two senses, both live)* the hardware terminal cursor (`Screen#cursor_position`), and a `List::Cursor` — the selection position within a list. |
 | **well** | the explicit background an input paints over its whole rect (`Theme#input_bg_color` / `#active_bg_color`), which opts it out of `bg_color` inheritance. |

data/book/01-first-app.md

@@ -104,11 +104,10 @@ window.focus
 
 `screen.content = window` makes the window the screen's **tiled content**
 — the component that fills the terminal. Setting it triggers a layout
-pass: the window is handed a rectangle spanning the whole screen (minus
-one bottom row, which we'll get to), and it in turn sizes the label
-inside its border. This is the top-down cascade in miniature — the screen
-sizes the window, the window sizes its content — and it re-runs, top
-down, every time the terminal is resized.
+pass: the window is handed a rectangle spanning the whole screen, and it
+in turn sizes the label inside its border. This is the top-down cascade in
+miniature — the screen sizes the window, the window sizes its content —
+and it re-runs, top down, every time the terminal is resized.
 
 `window.focus` marks the window as the **focused** component: the one
 that receives keystrokes. Focus flows down toward interactive content
@@ -117,30 +116,36 @@ the active thing." In a one-window app it's mostly cosmetic (it draws the
 border in the active color); in a real app, focus is what routes the
 keyboard, and it gets its own chapter (chapter 5).
 
-You may have noticed you never created a status bar, yet the app has one
-— the bottom row showing `q quit`. That's because your window isn't the
-whole story of what's on screen.
+Run it and you'll notice what *isn't* there: no status bar, no menu, no
+title chrome beyond the border you asked for. **Tuile paints nothing you
+didn't build.** Other TUI toolkits hand you a status row and a hint line
+for free; Tuile gives your content the whole terminal and lets you decide
+whether a bottom row is worth one of your rows. A status line is three
+lines of layout when you want one — `examples/hello_world.rb` adds one,
+and chapter 3 shows the mechanism.
+
+That is the same instinct as top-down layout: the framework declines to
+make sizing decisions on your behalf, here by declining to spend a row.
 
 ## The tree you didn't build
 
 Your `window` isn't actually the root of the tree. The real root is a
 structural node called the {Tuile::ScreenPane}, owned by the screen, and
-it holds three things:
+it holds two things:
 
 ```
 ScreenPane                (structural root — paints nothing itself)
 ├── content               your window (the tiled UI)
-├── popups                modal overlays, when you open them (none yet)
-└── status_bar            the bottom row (that "q quit" hint)
+└── popups                modal overlays, when you open them (none yet)
 ```
 
 You only ever manage the `content` slot directly (via `screen.content=`);
-the pane, the popup stack, and the status bar are the framework's. The
-reason everything — including popups — lives under one parent is
-uniformity: focus traversal, "is this component still on screen?", and
-cleanup when a component is removed all work the same way for every node,
-with no special cases. You'll meet popups in chapter 7; for now it's
-enough to know the pane is up there, quietly being the root.
+the pane and the popup stack are the framework's. The reason everything —
+including popups — lives under one parent is uniformity: focus traversal,
+"is this component still on screen?", and cleanup when a component is
+removed all work the same way for every node, with no special cases.
+You'll meet popups in chapter 7; for now it's enough to know the pane is
+up there, quietly being the root.
 
 ## Run the loop, and always close
 

data/book/02-repaint.md

@@ -136,14 +136,27 @@ Meeting that second half is easy, because the default
 - A **leaf** component (no children) gets its background cleared
   automatically, so you can paint your content and trust the rest is
   blanked.
-- A **container whose children exactly tile its rect** skips the clear —
-  the children will cover everything anyway.
 - A **container with gaps** between its children (a form with
-  mixed-width fields, say) gets the background cleared *and* its children
-  re-invalidated, so they repaint cleanly on top. This is what makes
-  gappy layouts safe without every container writing its own
+  mixed-width fields, say) gets the background cleared, because those gap
+  cells are ones no child will paint over.
+- A **container whose children exactly tile its rect** skips the clear —
+  the children cover every cell anyway, and blanking a cell you are about
+  to repaint would only mark it dirty for the flush.
+- **Either way, a container re-invalidates its children.** That is what
+  makes gappy layouts safe without every container writing its own
   damage-tracking pass.
 
+That last point is worth a moment, because the obvious optimization is
+wrong. A clear wipes the container's *whole* rect — every descendant's
+cells, not just the gaps — but a container only ever notifies its own
+direct children, so the notice has to keep travelling down on its own. A
+tiling container that stayed quiet ("my children cover everything, nothing
+to do") would be a dead end: its grandchildren would never learn their
+cells had been blanked by an ancestor, and their content would vanish until
+some unrelated event happened to invalidate them. Repainting more than
+strictly necessary costs nothing here — identical glyphs leave a cell
+unchanged, so the diff is still empty and nothing reaches the wire.
+
 The practical rule for writing a component: **call `super` in your
 `repaint`** to inherit that clearing, then paint your content. The only
 components that skip `super` are the few that paint every cell of their

data/book/03-layout.md

@@ -40,9 +40,9 @@ rectangles they are given. If new content arrives that is too tall for
 its pane, the pane scrolls or clips — it does not push back on the
 parent to grow.
 
-This is already how Tuile's tiled UI works today: `ScreenPane` sizes
-your content and the status bar; every real layout you write positions
-its children the same way. The chapter's job is to convince you that
+This is already how Tuile's tiled UI works today: `ScreenPane` hands your
+content the whole terminal; every real layout you write positions its
+children the same way. The chapter's job is to convince you that
 this is a feature, then show you the few pieces of vocabulary that make
 it comfortable.
 
@@ -342,16 +342,17 @@ The boxes are sugar, not a replacement, and they can't say everything. A **cap
 on a proportion** is the case to recognise:
 
 ```ruby
-list_width  = (rect.width / 3).clamp(20, 40)  # a third, but never <20 or >40
 group_width = [16, rect.width / 3].min        # a third, but never more than 16
+list_width  = (rect.width / 3).clamp(20, 40)  # a third, but never <20 or >40
 ```
 
-Both of these are in `examples/sampler.rb`, and both keep a `rect=`
-override. That's the intended division of labour rather than a gap to work
-around: use a box for the stack, drop to `Absolute` for the region that
-genuinely needs arithmetic — usually nesting one inside the other, so only the
-awkward part carries any. The sampler does exactly that, and porting it to
-these layouts took it from 59 hand-written rectangles down to 7.
+The first is in `examples/sampler.rb` twice — the sidebar in its CheckboxGroup
+pane and the one in its List pane — and both keep a `rect=` override. That's
+the intended division of labour rather than a gap to work around: use a box for
+the stack, drop to `Absolute` for the region that genuinely needs arithmetic —
+usually nesting one inside the other, so only the awkward part carries any. The
+sampler does exactly that, and porting it to these layouts took it from 59
+hand-written rectangles down to a handful (5 today).
 
 ## Geometry: `Point`, `Size`, `Rect`
 

data/book/05-focus.md

@@ -125,6 +125,17 @@ 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.
 
+One thing does happen *after* the ladder, and it lives in the loop rather
+than in dispatch: if nothing handled the key and it was `q` or ESC, the
+loop stops and your program exits. That is what a `q quit` hint in an app's
+status line is describing — not a binding anyone registered, but the fate
+of an unclaimed quit key. It also explains why ESC means different
+things in different places: an open {Tuile::Component::Popup} handles ESC
+itself (dismissing is its job), so the loop never sees it and the popup
+closes instead of the app. And a widget keeps a stray `q` from quitting
+simply by consuming it, which a focused {Tuile::Component::TextField} was
+doing anyway — it's a printable character.
+
 ## Scope-wide keys live on an ancestor
 
 Two things every app wants: `1`/`2`/`3` to jump between panes, and Enter to
@@ -161,6 +172,7 @@ The same mechanism gives you a form's default button, one form per popup:
 | `Button` | consumes it | activates *itself*, not the default |
 | `Checkbox` | consumes it (toggles) | the form never sees it |
 | `Select` | consumes it (opens, then commits) | the form never sees it |
+| `Tabs` | declines | bubbles up → submit |
 
 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
@@ -172,6 +184,76 @@ 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.
 
+## Paste is not a keystroke
+
+Everything above is about keys. A paste looks like keys — and that
+resemblance is a genuine problem, not a convenience.
+
+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
+arrives, the information is gone.
+
+The fix has to happen one layer down, at the code that talks to the
+terminal. {Tuile::Screen#run_event_loop} enables **bracketed paste** (DEC
+private mode 2004), which asks the terminal to wrap pasted text in
+`\e[200~` … `\e[201~` markers. Tuile's key thread recognizes the opening
+marker, reads the payload raw up to the terminator, and posts it as a
+single `PasteEvent` — which never enters the ladder at all:
+
+- no Tab traversal, no global shortcuts, no `handle_key`;
+- straight to {Tuile::Component#handle_paste}, delivered down the focus
+  chain and bubbling exactly like a key;
+- the whole clipboard as one `String`, `\n`-normalized.
+
+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
+once per character, and a subclass that claims Enter needs no paste code of
+its own:
+
+```ruby
+class PromptTextArea < Tuile::Component::TextArea
+  protected
+
+  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 = ""
+    true
+  end
+end
+```
+
+Override `handle_paste` yourself when a paste should mean something other
+than "insert this": collapsing a huge clipboard to a `[Pasted 230 lines]`
+placeholder, say, or pulling a file path out of it.
+
+```ruby
+def handle_paste(text)
+  return super if text.lines.size < 20
+
+  attach_as_file(text)
+  self.text = "#{text.lines.size} lines attached"
+  true
+end
+```
+
+Two smaller consequences worth knowing. Because the payload is read raw
+rather than through {Tuile::Keys.getkey}, a pasted ESC or Tab stays payload
+— unbracketed, a pasted Tab moves focus and a pasted ESC swallows the five
+bytes behind it. And the line endings are normalized for you: terminals
+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
+again, with the ambiguity that implies — reach for it only if a terminal
+mishandles the mode.
+
 ## Where the cursor comes in — and where it doesn't
 
 A component signals cursor ownership through
@@ -188,28 +270,61 @@ 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
+## Writing a status line
+
+Chapter 1 pointed out that Tuile draws no status bar. This is the chapter
+where you find out that's a decision about *ownership*, not an omission —
+and that most status lines don't need this chapter's machinery at all.
+
+A status line is a `Label` in your layout. That's the whole idea:
 
-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.
+```ruby
+status = Tuile::Component::Label.new
+status.text = "q #{screen.theme.hint("quit")}  Tab #{screen.theme.hint("Switch")}"
+
+root = Tuile::Component::Layout::Vertical.new
+root.add(main_ui, Tuile::Component::Layout::Expand[1])
+root.add(status, Tuile::Component::Layout::Fixed[1])
+```
+
+If the keys your app offers are the same wherever the user is, you are
+done — set the text once and never touch it again. `examples/file_commander.rb`
+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.
 
-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:
+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
+{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.
 
-- **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).
+### When the row does depend on focus
+
+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:
+
+```ruby
+screen.on_focus_changed = -> { status.text = hint_for(screen.focused) }
+```
 
-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.
+It fires after every focus *change* — to and from `nil` included, and after
+the repair that runs when a popup closes. It's edge-triggered, so
+re-focusing what already has focus fires nothing and your callback can
+rebuild the string unconditionally. Two things it must tolerate: `focused`
+being `nil`, and firing during `screen.close`, which clears focus as it
+unmounts.
+
+What `hint_for` does is entirely yours — Tuile has no notion of a hint and
+no method for one, so there is no interface here to conform to.
+`examples/sampler.rb` names the focused component's class, which makes Tab
+traversal visible as you walk a pane. An app with per-window keys usually
+walks up the focus chain from `screen.focused` and takes the first answer,
+because that mirrors the direction a key bubbles — but that's an app's
+design decision, not a framework pattern.
 
 ---
 

data/book/06-theming.md

@@ -24,7 +24,7 @@ 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
+in a status line you write. Those are the accents, and they are exactly the tokens
 a {Tuile::Theme} carries — `active_bg_color`, `active_border_color`,
 `input_bg_color`, `hint_color`. There is no global `bg` or `fg` token,
 and that absence is intentional: adding one would mean painting over the
@@ -250,7 +250,10 @@ 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.
+declaration site says nothing. All 256 xterm palette names are there as
+constants — `Color::DODGER_BLUE1`, `Color::GREY37` — and
+`Color::PALETTE_NAMES` is the enumerable map behind them if you'd rather
+browse than guess.
 
 ## When the theme changes under your content