tuile 0.10.0 → 0.12.0

data/README.md

@@ -49,6 +49,12 @@ gem "tuile", git: "https://github.com/mvysny/tuile.git"
 
 Tuile requires Ruby 3.3+.
 
+One component — `Component::BigDecimalField` — additionally needs the
+`bigdecimal` gem, which Tuile deliberately does *not* depend on (it has been a
+bundled gem since Ruby 3.4, so Bundler no longer puts it on the load path for
+free). Add `gem "bigdecimal"` to your Gemfile if you use that field; nothing
+else in Tuile loads it.
+
 ## Documentation
 
 - **[The Tuile guide](book/README.md)** teaches Tuile cover to cover — the
@@ -126,7 +132,7 @@ bytes sent to the terminal. There is no clipping in between.
      `cursor_position` (e.g. into a focused text field).
 
 Components never write escape sequences to the terminal. They paint styled
-cells into a back buffer (`Tuile::Buffer`) via `set_line` / `fill` /
+cells into a back buffer (`Tuile::Buffer`) via `set_text` / `fill` /
 `set_char`. When the pass finishes, `Buffer#flush` emits the **minimal diff**
 — only the cells that actually changed since the last flush — wrapped in one
 synchronized-output batch. That is what keeps repaint flicker-free on any
@@ -145,7 +151,7 @@ of its own and positions its children within its rect.
 
 `Tuile::Screen#run_event_loop` reads keys and mouse events on a worker thread,
 funnels them through `Tuile::EventQueue`, and processes them on the main
-thread. **All** UI mutations — `rect=`, `content=`, `add_line`, `invalidate`,
+thread. **All** UI mutations — `rect=`, `content=`, `items=`, `invalidate`,
 `screen.focused=` — must run on that thread. Most UI methods will raise
 `"UI lock not held"` if you violate this.
 
@@ -380,7 +386,7 @@ Tuile::ThemeDef.default = APP_THEME   # every Screen.fake now carries it
 
 Built-in components read `screen.theme` at paint time, so their accents
 restyle automatically. Content you rendered yourself does not: a
-`StyledString` stored in `Label#text` / `List#lines` / `TextView#text`
+`StyledString` stored in `Label#text` / `List#lines=` / `TextView#text`
 has its colors baked in at construction, and only your app knows which of
 those were theme-derived (as opposed to inherent to the data — log-level
 colors, say). `Component#on_theme_changed` fires on every attached
@@ -472,15 +478,17 @@ focusable; focus delegates to content (or footer when active).
 
 ### `Component::List`
 
-A scrollable list of strings with optional cursor and scrollbar.
+A scrollable list of items — one row each, rendered by a `renderer` — with
+optional cursor and scrollbar. `lines=` is the shortcut for items that are
+their own rendering.
 
 ```ruby
 list = Tuile::Component::List.new
 list.lines = ["alpha", "beta", "gamma"]
 list.cursor = Tuile::Component::List::Cursor.new
-list.on_item_chosen = ->(index, line) { Tuile.logger.info("picked #{line}") }
-list.auto_scroll = true       # auto-scroll to bottom on add_line
-list.add_line("delta")
+list.on_item_chosen = ->(index, item) { Tuile.logger.info("picked #{item}") }
+list.auto_scroll = true       # auto-scroll to bottom as the list grows
+list.lines = list.items + ["delta"]   # no appenders: assign the items whole
 ```
 
 Cursor variants:
@@ -493,8 +501,8 @@ Cursor variants:
 
 Pressing Enter or left-clicking an item fires `on_item_chosen(index, line)`.
 
-Key API: `lines=`, `add_line`, `add_lines`, `cursor=`, `top_line=`,
-`auto_scroll=`, `scrollbar_visibility=`, `on_item_chosen`,
+Key API: `items=`, `renderer=`, `lines=`, `build_lines`, `cursor=`,
+`scroll_top_row=`, `auto_scroll=`, `scrollbar_visibility=`, `on_item_chosen`,
 `select_next` / `select_prev` (search).
 
 ### `Component::TextField`
@@ -528,10 +536,7 @@ drawn on top of the tiled content; multiple popups stack.
 ```ruby
 window = Tuile::Component::Window.new("Help")
 window.content = help_list
-Tuile::Component::Popup.open(content: window, size: Tuile::Fraction::HALF)
-# or, equivalently:
-popup = Tuile::Component::Popup.new(content: window)
-popup.open
+popup = Tuile::Component::Popup.new(content: window, size: Tuile::Fraction::HALF).open
 # popup.close, popup.open?
 ```
 

data/TERMINOLOGY.md

@@ -0,0 +1,61 @@
+# TERMINOLOGY.md
+
+Tuile's house vocabulary — one line per term, looked up by word.
+
+This file owns **definitions only**. The *rules that bite* live in AGENTS.md
+("Nomenclature" and the sections each word belongs to); the *why we chose a word
+and not its synonym* lives in DECISIONS.md (`D-scroll-nomenclature` for the
+row/line/item split); the *concepts* live in the book. When a definition here
+needs a paragraph of justification, that paragraph belongs in one of those three.
+
+## The grid
+
+| term | means |
+|---|---|
+| **row** | one row of the terminal grid — the framework's only word for it. A wrapped unit of text *is* a row; wrapping is what turns text into rows. |
+| **column** | one cell-column of the terminal grid; the unit `display_width` counts. |
+| **cell** | one grid position: a grapheme plus a {Tuile::StyledString::Style}, in {Tuile::Buffer}. |
+| **glyph** | what the terminal draws in one or more cells. Ambiguous-width glyphs count as **one** column (the bet in `D-ambiguous-width`). |
+| **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. |
+| **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`. |
+
+**Space rule 1.** An object with only one row space leaves `row` unqualified:
+{Tuile::Buffer} *is* the grid, so its rows are screen rows;
+`TextArea::WrappedText` is content, so its rows are content rows.
+
+**Space rule 2.** A component holding both spaces qualifies the viewport one
+(`row_in_viewport`); its unqualified `row` and its `scroll_top_row` are
+content-space.
+
+## Text and content
+
+| term | means |
+|---|---|
+| **line** | a `\n`-delimited unit of a String — exactly what `String#lines` returns. **Never a coordinate.** |
+| **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. |
+| **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. |
+| **caret** | the index into an input's `text` where editing happens; always on a cluster boundary. Distinct from the *cursor*. |
+
+## Tree, paint and theme
+
+| term | means |
+|---|---|
+| **component** | a node of the UI tree ({Tuile::Component}); the only thing that paints. |
+| **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`. |
+| **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. |
+| **token** | a semantic colour name on {Tuile::Theme} — an accent, never a global fg/bg. |
+| **scheme** | `:dark` or `:light`; a {Tuile::ThemeDef} pairs one {Tuile::Theme} per scheme. |

data/book/02-repaint.md

@@ -50,7 +50,7 @@ cells into the screen's **back buffer** — a {Tuile::Buffer}, an in-memory
 grid of styled cells mirroring the terminal — through three methods:
 
 ```ruby
-screen.buffer.set_line(x, y, styled_string)   # a run of text
+screen.buffer.set_text(x, y, styled_string)   # a run of text
 screen.buffer.set_char(x, y, grapheme, style) # one cell
 screen.buffer.fill(rect, style)               # a blank region
 ```

data/book/03-layout.md

@@ -125,6 +125,15 @@ complex TUIs — tmux, neovim's splits, k9s, lazygit, htop — are all
 them needs flex grow/shrink/wrap/basis or a constraint solve. The
 hardest real terminal UIs already live comfortably inside "simple."
 
+Be precise about what that validates, though: it's TUI *app architecture*,
+not TUI *framework feature lists*. Several terminal frameworks do ship a
+full engine — Textual has CSS, Ink embeds Yoga (the flexbox engine React
+Native uses), ratatui runs a real Cassowary solver. The reason isn't that
+terminals need one; it's that those frameworks never hand you a rectangle,
+so an engine is the only way their users can lay anything out. Tuile hands
+you coordinates, which is what makes richer layout *optional* here —
+available where it helps, declinable everywhere else.
+
 It's stronger than "simple happens to work," though. Importing a CSS-like
 system would be *actively worse* on a terminal, for three concrete
 reasons:
@@ -204,6 +213,146 @@ That's the whole "responsive" story: plain Ruby, recomputed on a
 discrete resize event. No breakpoint DSL, no media queries — just the
 arithmetic you'd write anyway.
 
+## Stacks without the arithmetic: `Vertical` and `Horizontal`
+
+`Absolute` is the right tool for genuinely two-dimensional geometry, and
+tedious for the most common shape in any app: a stack. So Tuile ships two
+*box* layouts that do that arithmetic for you. You declare what extent each
+child should get, and the box hands down rectangles through the very same
+`rect=`:
+
+```ruby
+form = Tuile::Component::Layout::Vertical.new(spacing: 1)
+form.add(prompt, Tuile::Component::Layout::Fixed[3])    # 3 rows
+form.add(field,  Tuile::Component::Layout::Fixed[1])    # 1 row
+form.add(log,    Tuile::Component::Layout::Expand[1])   # …all that's left
+```
+
+`Horizontal` is the same with the axes swapped — the constraint is a width,
+and `Expand` claims the rest of the row:
+
+```ruby
+split = Tuile::Component::Layout::Horizontal.new
+split.add(sidebar, Tuile::Component::Layout::Fixed[30])
+split.add(main,    Tuile::Component::Layout::Expand[1])
+```
+
+Inside a subclass the constraint names need no prefix, since they live on
+`Layout`, an ancestor:
+
+```ruby
+class LoginForm < Tuile::Component::Layout::Vertical
+  def initialize
+    super(spacing: 1, padding: Insets[top: 1])
+    add(@user = Tuile::Component::TextField.new, Fixed[1], cross: Fixed[30])
+    add(@log  = Tuile::Component::TextView.new,  Expand[1])
+  end
+end
+```
+
+### The three constraints
+
+- **`Fixed[n]`** — exactly `n` cells, clamped to what's still unassigned.
+- **`Percent[n]`** — `n`% of the space *available*, measured after padding
+  and the gaps between children come off. So two `Percent[50]` children fit
+  exactly instead of overflowing by the gap between them.
+- **`Expand[weight]`** — a share of whatever is left once the `Fixed` and
+  `Percent` children have taken theirs, split in proportion to the weights.
+
+That's the entire vocabulary, and the omission is the point: **there is no
+`Auto`.** Nothing asks a child how big it would like to be. This is the same
+rule as the rest of the chapter, wearing a friendlier face.
+
+Two more knobs, both on the box rather than on each child: `spacing:` (blank
+cells between adjacent children) and `padding:` (an inset from the box's own
+rect — `Insets[top: 1, left: 2]`, or a plain integer for all four edges).
+
+### The cross axis, and alignment
+
+Each child also gets a `cross:` constraint — its width in a `Vertical`, its
+height in a `Horizontal`. It defaults to `Percent[100]`, so children fill the
+box across the axis, which is usually what you want. Narrow one when it isn't:
+
+```ruby
+form.add(field, Fixed[1], cross: Fixed[30])                  # 30 columns
+form.add(title, Fixed[1], cross: Percent[50], align: :center)
+```
+
+`align:` is `:start`, `:center` or `:end` — axis-agnostic on purpose, since
+`:start` means the left edge in a `Vertical` and the top edge in a
+`Horizontal`. It does something only when the child is narrower than the
+space available.
+
+Alignment might look like it contradicts the top-down rule — surely centering
+needs to know how wide the child is? It doesn't. It needs *a* width, and the
+`cross:` constraint is where that width came from. Nothing gets measured.
+(`Expand` is main-axis only for a related reason: across the axis a child has
+no siblings to compete with, so a weight would have nothing to mean. Passing
+one as `cross:` raises.)
+
+### Packing, starving, and remainders
+
+Three behaviours worth knowing, because they are what you get *instead of* a
+solver:
+
+**Children pack from the start edge.** With no `Expand` among them the slack
+is simply left at the end — there's no invisible filler to add, the way
+Swing's `BoxLayout` needs glue.
+
+**Over-subscription starves rather than raising.** If the children ask for
+more than there is, they're satisfied in declaration order and whoever is
+left over gets an empty rect — which, as chapter 2 established, paints
+nothing. A pane too short for its content degrades quietly instead of
+throwing or spilling outside its rect.
+
+**A remainder goes to the earliest `Expand` children, one cell each.** Five
+equal `Expand`s in 12 rows get `3, 3, 2, 2, 2` — never `2, 2, 2, 2, 4`, which
+is what "give the leftover to the last one" produces. On a character grid a
+doubled pane is plainly visible, so spare cells are spread rather than dumped.
+One wrinkle, since this chapter showed you the hand-written version first: the
+two-pane `Absolute` example above gives the odd column to the *right* pane,
+while two `Expand[1]` children give it to the *left*. Both are deterministic;
+they're just different code.
+
+### Varying the gap: nest, don't configure
+
+`spacing` belongs to the box rather than to individual children, deliberately.
+A gap sits *between* two children, so "whose gap is it?" has no good answer —
+and both possible conventions confuse readers.
+
+When you want tighter grouping, nest a box. A `spacing: 0` stack inside a
+`spacing: 1` stack keeps two rows flush while the rest of the form breathes:
+
+```ruby
+pair = Tuile::Component::Layout::Vertical.new           # spacing: 0
+pair.add(bar,     Fixed[1])
+pair.add(caption, Fixed[1])                             # flush under the bar
+
+form = Tuile::Component::Layout::Vertical.new(spacing: 1)
+form.add(prompt, Fixed[4])
+form.add(pair,   Fixed[2])                              # blank row around the pair
+```
+
+That *states* the grouping instead of faking it with a per-child gap — boxes
+within boxes, which is how the rest of Tuile composes anyway.
+
+### When to stay with `Absolute`
+
+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
+```
+
+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.
+
 ## Geometry: `Point`, `Size`, `Rect`
 
 The values you compute with are three small frozen types
@@ -294,7 +443,7 @@ A `Window`'s bottom border can carry one of two things, and they are
 genuinely different jobs, so they are two different members.
 
 **`footer_text=`** is *border chrome* — a styled string (a `String` is
-coerced) embedded into the bottom border line, mirroring the caption on
+coerced) embedded into the bottom border row, mirroring the caption on
 the top line. It draws at its own width with the border's dashes filling
 the remainder, clipped to the inner width. Like the caption, it embeds
 with **no added padding** — it butts straight against the left corner:
@@ -369,11 +518,7 @@ own code and set the size top-down. Keep measurement opt-in and
 caller-side; the moment the framework starts consulting children for
 sizes automatically, it's on the road back to the constraint solver.
 
-And if you find yourself building many dynamic, user-draggable splits by
-hand and wishing for a `Layout.vertical([Length(3), Fill(1), …])`
-convenience — that's a known, *deliberately deferred* addition. It would
-be pure sugar: a rect producer running a small greedy 1-D pass and
-feeding results to the very same `rect=` setter you already use, with no
-change to the foundation. Absolute-first is the base; a descriptive
-split layer is an optional convenience on top, added if and when the
-convenience pays for itself.
+Note that the box layouts above are not an exception to any of this. They
+compute rectangles *for* you, but they compute them from constraints you
+supplied, and they hand them down through the same `rect=`. No child is ever
+consulted.

data/book/05-focus.md

@@ -159,6 +159,8 @@ The same mechanism gives you a form's default button, one form per popup:
 | `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 |
+| `Checkbox` | consumes it (toggles) | the form never sees it |
+| `Select` | consumes it (opens, then commits) | the form never sees it |
 
 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

data/book/06-theming.md

@@ -121,7 +121,7 @@ For plain chrome — a border string, a status-bar hint — the theme's
 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
+{Tuile::Component::Window} feeds its whole border row, cursor moves and
 all, through `active_border`.
 
 But chrome text is flat. Content is not. A list row or a label may be a