tuile 0.10.0 → 0.12.0

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
@@ -201,11 +219,38 @@ read-only or required flag yet. Room left for that layer to grow into.
 
 ## Choosing from a set
 
-{Tuile::Component::List} is the workhorse: a scrollable column of
-{Tuile::StyledString} lines, ellipsized (spans preserved) when too wide.
-What makes it flexible is that its *cursor behavior is a pluggable object*
-rather than a boolean. Assign one of three {Tuile::Component::List::Cursor}
-variants to fit the interaction:
+{Tuile::Component::List} is the workhorse: a scrollable column of *items*
+— objects of whatever type your app deals in — one row each. You give it
+the items and a `renderer` that turns one item into a row, and it does the
+rest: ellipsizing a row too wide for the viewport (spans preserved),
+scrolling, and handing your callbacks back **the item itself** rather than
+the text it drew for it.
+
+```ruby
+list = Component::List.new
+list.items    = User.all
+list.renderer = ->(u) { "#{u.name}  #{u.email}" }
+list.cursor   = Component::List::Cursor.new
+list.on_item_chosen = ->(_index, user) { open(user) }
+```
+
+That's the same bargain the value seam struck earlier in this chapter: the
+component speaks in your objects, and nothing has to map a row of text
+back to the thing it stood for. When your items *are* the text, skip the
+renderer entirely — `list.lines = entries` takes strings (or
+{Tuile::StyledString}s, or anything with a `to_s`), splits them on
+newlines, and shows each as its own row.
+
+The renderer runs when a row is *painted*, and only for the rows actually
+on screen: a hundred-thousand-item list renders the twenty you can see.
+That's what makes a long list cheap, and it comes with one rule — keep the
+renderer a pure function of its item. It may be called on any frame, so it
+is the wrong place to reach for a database; do that work when you build
+the items.
+
+What makes the list flexible beyond that is that its *cursor behavior is a
+pluggable object* rather than a boolean. Assign one of three
+{Tuile::Component::List::Cursor} variants to fit the interaction:
 
 - **`Cursor::None`** (the default) — no cursor at all. The list is a
   read-only scroll region: a log, a static report.
@@ -216,29 +261,24 @@ variants to fit the interaction:
   lines. For a list where only some rows are selectable (headers
   interspersed with items, say), it skips the rest.
 
-Two callbacks cover the events you care about. `on_item_chosen` fires when
-the user commits to the cursor's row — Enter or a left-click — and is the
-"open this" signal. `on_cursor_changed` fires when the highlighted row
-*changes*, which is exactly what you wire to keep a details pane in sync
-with the selection. For a tailing list — a live log — set `auto_scroll`;
-it pins to the bottom as lines arrive, but politely stops yanking you down
-the moment you scroll up to read history, and resumes once you scroll back
-(`following?` tells you which). A scrollbar is one assignment
-(`scrollbar_visibility`).
-
-```ruby
-list = Component::List.new
-list.lines  = entries
-list.cursor = Component::List::Cursor.new
-list.on_item_chosen = ->(index, line) { open(entries[index]) }
-```
+Two callbacks cover the events you care about, and both are handed the
+`(index, item)` pair. `on_item_chosen` fires when the user commits to the
+cursor's row — Enter or a left-click — and is the "open this" signal.
+`on_cursor_changed` fires when the highlighted row *changes*, which is
+exactly what you wire to keep a details pane in sync with the selection.
+For a tailing list — a live log — set `auto_scroll`; it pins to the bottom
+as items arrive, but politely stops yanking you down the moment you scroll
+up to read history, and resumes once you scroll back (`following?` tells
+you which). A scrollbar is one assignment (`scrollbar_visibility`).
 
 When the set is long and the user roughly knows what they want, a plain
 list makes them scroll for it. {Tuile::Component::ComboBox} is the answer:
 a text field with a dropdown that filters as you type. Hand it `items` (of
 any type) and, when their `to_s` isn't what you want shown, an
 `item_label` strategy to render each one; type to narrow, arrow to move,
-Enter or click to accept. It's the value seam doing real work — its
+Enter or click to accept. (The domain widgets all call that strategy
+`item_label`, where a bare list calls it `renderer` — a label is text the
+widget then decorates, a row is the whole rendering.) It's the value seam doing real work — its
 `value` is the selected *item*, the object and not its label, so a combo
 over `User`s hands back a `User`. The field's text is merely a transient
 query: it reverts to the selection's label when you dismiss the dropdown,
@@ -272,15 +312,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,
@@ -331,10 +378,11 @@ coerced), and let the widget's own toggling build the new sets for you.
 Here the cursor and the selection are genuinely two different things — the
 cursor says *where you are*, the checkmarks say *what you picked* — and
 that shape is exactly what a list already provides. So a checkbox group
-doesn't paint rows itself; it holds a {Tuile::Component::List} and gets the
-cursor, the scrolling, the scrollbar and the per-row mouse handling for
-free, in the same "wrap a generic component to make a domain one" way the
-combo box wraps a text field. That inheritance goes further than
+doesn't paint rows itself; it holds a {Tuile::Component::List} of the
+items, supplies the renderer that puts a `[x]` or `[ ]` in front of each
+label, and gets the cursor, the scrolling, the scrollbar and the per-row
+mouse handling for free, in the same "wrap a generic component to make a
+domain one" way the combo box wraps a text field. That inheritance goes further than
 convenience: a click anywhere on a row toggles it, and Enter toggles the
 cursor's row, because those are the list's own gestures for choosing an
 item.
@@ -412,6 +460,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
@@ -497,7 +615,7 @@ popups are for.
 
 The bottom border has two mutually exclusive uses, and the distinction is
 the top-down-layout principle from chapter 3 made concrete. `footer_text=`
-embeds decoration into the border line — chrome, mirroring the caption on
+embeds decoration into the border row — chrome, mirroring the caption on
 top, not focusable. `footer=` mounts a *real focusable component* spanning
 the full inner width — the search-field-in-the-border case. A footer
 component present takes the row and hides the text; neither drives the
@@ -544,6 +662,53 @@ A nested TextField still swallows printable keys first, so typing `q` into
 a field inside a popup doesn't dismiss it — the popup's own `q` handler sits
 on the ancestor, and only sees keys the field declined.
 
+## Notifications
+
+{Tuile::Component::Notification} is the one overlay you don't assemble at
+all. It's the TTY toast: a message in the top-right corner that shows up,
+holds for three seconds, and removes itself.
+
+```ruby
+Component::Notification.show("Saved")
+Component::Notification.show("Disk almost full", color: Color::RED)
+```
+
+That class method is the *only* way in — `new` is private. The reason is
+worth understanding, because it's the design in one line: there is never
+more than one notification box on screen. `show` looks for the live one in
+the popups stack and appends to it, so a burst of messages stacks as
+entries inside a single frame:
+
+```
+                                            ┌──────────────┐
+                                            │Job 1 finished│  ← goes in 3 s
+                                            │Job 2 finished│  ← then this one
+                                            │Job 3 finished│
+                                            └──────────────┘
+```
+
+They then leave **one at a time**, oldest first, three seconds apart. This
+is the interesting half of the design. Five notifications raised in the
+same instant would, given five independent timers, appear and vanish
+together — a flash you have no chance of reading. Draining them one per
+tick means the burst takes fifteen seconds to clear and you read it in
+peace. A message arriving mid-cycle just waits its turn rather than
+restarting the clock, which is also what stops a steady trickle of
+notifications from keeping the box alive forever.
+
+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.
+
+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
+the screen — and at most five messages are held, after which the newest is
+dropped and reported to `Tuile.logger`. Both are deliberate: a notification
+is a glance, not a document, and an app with more to say than five short
+lines wants a LogWindow, which is next.
+
 ## Batteries-included windows
 
 The last three components are conveniences: common Window-plus-content

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

data/examples/file_commander.rb

@@ -33,6 +33,7 @@ module FileCommanderExample
     def initialize(start_dir)
       super()
       self.cursor = Tuile::Component::List::Cursor.new
+      self.renderer = ->(entry) { Rainbow(entry[:display]).color(TYPE_COLORS[entry[:type]]) }
       @cwd = File.expand_path(start_dir)
       @on_cwd_changed = nil
       load_entries
@@ -60,8 +61,8 @@ module FileCommanderExample
 
     private
 
-    def descend(_index, line)
-      target = File.expand_path(File.join(@cwd, Rainbow.uncolor(line).chomp("/")))
+    def descend(_index, entry)
+      target = File.expand_path(File.join(@cwd, entry[:name]))
       change_to(target) if File.directory?(target)
     end
 
@@ -75,7 +76,7 @@ module FileCommanderExample
       @cwd = path
       load_entries
       self.cursor = Tuile::Component::List::Cursor.new
-      self.top_line = 0
+      self.scroll_top_row = 0
       @on_cwd_changed&.call
     rescue SystemCallError => e
       @cwd = previous
@@ -89,7 +90,7 @@ module FileCommanderExample
         { name: name, type: classify(path), display: is_dir ? "#{name}/" : name, dir_first: is_dir ? 0 : 1 }
       end
       entries.sort_by! { |e| [e[:dir_first], e[:name].downcase] }
-      self.lines = entries.map { |e| Rainbow(e[:display]).color(TYPE_COLORS[e[:type]]) }
+      self.items = entries
     end
 
     # Classify by symlink first so a symlink-to-dir still reads as a link.