tuile 0.10.0 → 0.11.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

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
@@ -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/07-components.md

@@ -175,7 +175,25 @@ qty.on_value_change = ->(n) { recompute(n) }  # n is an Integer, or nil
 qty.value = 3
 ```
 
-Both the combo box and the integer field are built the same way, and it's
+{Tuile::Component::FloatField} is the same field one type over — it also
+accepts a single decimal point, and its value is a `Float`. That naming is
+a small rule worth knowing, because it tells you what you're getting: a
+typed field is named after the Ruby class of its value, so `IntegerField`
+hands back an `Integer` and `FloatField` a `Float` — a binary double, which
+makes it exactly the wrong field for money. It parses generously while you
+type: a buffer of `1.` already reads as `1.0`, so reaching for the decimal
+point doesn't blink the value to `nil` and back in the listener you wired.
+
+Money gets {Tuile::Component::BigDecimalField}, the same field once more with
+an exact decimal inside — type `0.1` and it is `0.1`, not the `0.1000…0055`
+a binary double stores. It is strict about how that exactness is preserved:
+assigning a `Float` raises rather than quietly converting, because by the time
+`19.99` reaches the setter it is already not `19.99`. This is the one
+component with a dependency Tuile itself doesn't carry — `bigdecimal` has
+been a *bundled* gem since Ruby 3.4, so an app that uses this field names it
+in its own `Gemfile`, and an app that doesn't never loads it.
+
+The combo box and the two numeric fields are built the same way, and it's
 worth seeing why: each *wraps* a text field rather than *being* one. A
 subclass would inherit the text field's `String`-typed value and wear it
 on its face right next to the real typed one — two conflicting answers to
@@ -272,15 +290,22 @@ cb.toggle       # unchecks it, firing the listener with false
 
 Two of its choices are worth understanding, because they're really
 statements about how Tuile widgets behave in general. The first: **Enter
-does nothing.** A checkbox has no action to confirm — Space is the native
-gesture for flipping one — so Enter is left unhandled, and by chapter 5's
-rules it bubbles up to an ancestor. It's tempting to read that as a
-guarantee, as though the framework kept Enter clear for a form's
-submit button. It doesn't, and chapter 5's table shows why: a text area
-claims Enter for a newline, a button claims it to activate itself. Whether
-Enter reaches your form depends on the widget that has focus. A checkbox
-declines it because it has nothing to do with it — which is a fact about
-this widget, not a promise about all of them.
+toggles it, just as Space does.** Space is the native gesture for flipping
+a checkbox, and for a while Enter was deliberately left alone — a checkbox
+has no action to confirm. What settled it is the checkbox group further
+down this chapter: a checkable row inside a list flips on Enter, because
+Enter is how a list chooses the row under its cursor. Had the standalone
+widget stayed silent, the same `[ ] Verbose` would have responded to Enter
+in a group and ignored it in a form, which is a distinction the person at
+the keyboard has no way to see.
+
+The consequence is worth stating plainly, because it's the general rule
+hiding behind the specific choice: a focused checkbox *consumes* Enter, so
+a form's submit button on an ancestor won't see it. That's not a
+regression from some guarantee — the framework never kept Enter clear, and
+chapter 5's table shows why it can't: a text area claims Enter for a
+newline, a button claims it to activate itself. Whether Enter reaches your
+form always depends on the widget that has focus.
 
 The second is about *where the widget actually is*. A form column will
 happily hand a checkbox forty columns for a caption that needs twenty-two,
@@ -412,6 +437,76 @@ one cell, and keeps the set of characters riding on that bet small enough
 to enumerate, so a new widget reaches for ASCII and offers the pretty
 glyph only where someone can opt in knowing their terminal.
 
+A radio group spends a row per option, permanently. When the form has six
+of these and a terminal has twenty-four rows, that arithmetic stops
+working, and {Tuile::Component::Select} is the same single answer on *one*
+row: the selected label plus a `▾`, with the options appearing only while
+you're choosing between them.
+
+```ruby
+level = Component::Select.new(items: %w[debug info warn error], value: "warn")
+level.on_value_change = ->(l) { logger.level = l }
+```
+
+Enter, Space or Down opens the dropdown, the arrows move the highlight,
+Enter or Space commits, ESC closes it having changed nothing. `value` is
+the selected item as always, `nil` while nothing is selected — and that
+`nil` is a perfectly ordinary state here, which is why there's no
+placeholder text: an optional enum field simply shows a blank face.
+
+So when do you reach for which? The temptation is to decide by item count,
+and that's the wrong axis. Ask instead **who wrote the labels**:
+
+| The options are… | Widget | Why |
+|---|---|---|
+| a developer-authored enum, on one form row | `Select` | one row; borrows *n* transiently |
+| the same enum, worth comparing side by side | `RadioGroup` | spends *n* rows permanently |
+| supplied by the app, open-ended, labels you don't control | `ComboBox` | filtering *is* the navigation |
+| an enum, several of which apply | `CheckboxGroup` | a frozen `Set` value |
+
+A select is for a closed set you knew when you wrote the code — log level,
+sort order, line endings, Yes/No/Ask. A combo box is for countries, users,
+branches: data. A twelve-value enum is still a select, and a three-row
+country list loaded from a database is still a combo box, because next
+release it's two hundred rows and the widget you chose shouldn't have to
+change. Count is a symptom; authorship is the criterion.
+
+Which brings up the property that really separates the two, and it's not
+the filtering. **A select claims no printable key but Space.** Every other
+letter and digit bubbles straight past it, up the focus chain, to your
+application — so a form's `s`-to-save, or a layout's `1`/`2`/`3` jumps
+between panes, keep working while focus sits in a select. A combo box can
+never offer that: its field must eat every printable, because every
+printable is potentially part of the query. Add the fact that a select has
+no caret, and the two together are the whole case for the component. A
+caret is the strongest promise a terminal can make about what a widget
+does, and spending it on "you may type free text here" over a four-value
+enum is a lie the user then has to discover.
+
+Space is the one exception, and it's a safe one precisely because Space was
+never yours to begin with: every activatable widget in Tuile already claims
+it — a button, a checkbox, a radio group. Home and End, by contrast, are
+declined, so they stay available for you to bind app-wide.
+
+You may be waiting for type-ahead — press `f` and jump to the first item
+starting with `f`, the way desktop lists do. It isn't there, deliberately.
+The single-key version is silently wrong: with Finland, Fiji and Jamaica in
+the list, typing `fij` selects *Jamaica*, because each key is a fresh
+one-character match. The fix everyone reaches for next is a small
+accumulating buffer that clears after a second of idleness — and that
+buffer *is* the combo box's query with the display removed. If you're
+holding query state, showing it is strictly better than hiding it, and
+showing it is a combo box. On a terminal it's worse still: the timer leans
+on inter-keystroke gaps, and gaps are exactly what a laggy SSH link or a
+paste destroys.
+
+One small nicety worth noticing: the dropdown is never narrower than the
+select itself, and grows past it when a label needs the room — so its edges
+line up with the face you clicked, and the labels are never the thing that
+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

data/book/README.md

@@ -52,7 +52,9 @@ one, not to fill an outline.
    the design. Top-down, absolute, integer coordinates; a parent
    assigns its children's `rect` and components never negotiate a size.
    The C64 argument for *why simple layouting is enough* on a character
-   grid, `Layout::Absolute` and the `rect=` override, `Fraction` for
+   grid, `Layout::Absolute` and the `rect=` override, the `Vertical` /
+   `Horizontal` box layouts and their three constraints (`Fixed` /
+   `Percent` / `Expand`) as sugar over that same rule, `Fraction` for
    sizing a popup against the screen, and resize as a discrete
    recompute. Geometry primitives (`Point` / `Size` / `Rect`) live here.
 4. **[The event loop and background work](04-event-loop.md).** The