tuile 0.11.0 → 0.12.0

data/README.md

@@ -132,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
@@ -151,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.
 
@@ -386,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
@@ -478,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:
@@ -499,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`
@@ -534,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

@@ -443,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:

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

data/book/07-components.md

@@ -219,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.
@@ -234,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,
@@ -356,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.
@@ -592,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
@@ -639,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/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.

data/examples/sampler.rb

@@ -134,6 +134,7 @@ module SamplerExample
       ["ProgressBar",  :build_progress_bar],
       ["Background",   :build_background],
       ["Layout",       :build_layout],
+      ["Notification", :build_notification_launcher],
       ["Popup",        :build_popup_launcher],
       ["InfoWindow",   :build_info_launcher],
       ["PickerWindow", :build_picker_launcher],
@@ -561,7 +562,7 @@ module SamplerExample
         # The Set iterates in *toggle* order, so intersect with items to report
         # it in the order the rows are shown — the documented idiom.
         shown = (LOG_LEVELS & selected.to_a).map(&:label)
-        status.text = "value: {#{shown.join(", ")}} — #{log.lines.size} of #{entries.size} lines"
+        status.text = "value: {#{shown.join(", ")}} — #{log.items.size} of #{entries.size} lines"
       end
       refresh.call
       group.on_value_change = ->(_set) { refresh.call }
@@ -812,6 +813,42 @@ module SamplerExample
 
     # --- Modal launchers ---------------------------------------------------
 
+    # Four buttons, because the interesting things about a notification are all
+    # about *several* of them: one short toast shows the box hugging its content
+    # in the corner, a burst shows the stack draining one message every three
+    # seconds (and the grow-only width), and a long one shows the three-row wrap
+    # ending in an ellipsis. Focus stays on whichever button you pressed
+    # throughout — that is the whole point of the widget.
+    def build_notification_launcher
+      label = Tuile::Component::Label.new
+      label.text = "Notification.show puts a toast in the top-right corner for 3 seconds.\n" \
+                   "It never takes focus; a left-click on the box dismisses it.\n" \
+                   "Raise several and watch them drain one at a time."
+      counter = 0
+      buttons = [
+        Tuile::Component::Button.new("Short") { Tuile::Component::Notification.show("Saved") },
+        Tuile::Component::Button.new("Burst") do
+          5.times { Tuile::Component::Notification.show("Job #{counter += 1} finished") }
+        end,
+        Tuile::Component::Button.new("Long") do
+          Tuile::Component::Notification.show(
+            "Could not connect to the build server at 10.0.0.1: connection refused after " \
+            "three attempts, giving up and falling back to the local cache"
+          )
+        end,
+        Tuile::Component::Button.new("Colored") do
+          Tuile::Component::Notification.show("Disk almost full", color: Tuile::Color::RED)
+        end
+      ]
+      strip = row do |r|
+        buttons.each { |b| r.add(b, Fixed[button_width(b)]) }
+      end
+      form do |f|
+        f.add(label, Fixed[3])
+        f.add(strip, Fixed[1])
+      end
+    end
+
     def build_popup_launcher
       launcher(
         "Popup is a modal overlay wrapping any Component.\n" \

data/ideas/new-components.md

@@ -25,8 +25,9 @@ Seven of the 54 have a counterpart: Button, Text Field, Text Area,
 Integer Field, Combo Box (1:1), Dialog ({Tuile::Component::Popup} plus
 `Window`/`InfoWindow`/`PickerWindow`), Themable Mixin
 ({Tuile::Theme}/{Tuile::ThemeDef}). **List Box** is half-there:
-{Tuile::Component::List} is line-based, with no typed items and no
-multi-select.
+{Tuile::Component::List} takes typed items and a renderer since 2026-08-14
+(`D-list-items`), but has no multi-select — {Tuile::Component::CheckboxGroup}
+is the nearest thing.
 
 Tuile also has pieces Vaadin doesn't name as components — `ListDropdown`,
 `TextView`, `LogWindow`, `VerticalScrollBar` — so the gap is not
@@ -46,7 +47,7 @@ That leaves ~46 gaps.
 | ~~Password Field~~ | `TextField` | **built** 2026-08-02 (`D-integer-field`'s taxonomy — subclass, since a password's value *is* its text; mask default in `D-ambiguous-width`); a `display_text` seam, one mask glyph per character |
 | ~~Number Field~~ | `IntegerField` twin | **built** 2026-08-07 as `FloatField` (`D-float-field`) and `BigDecimalField` (`D-bigdecimal-field`, on Tuile's first optional dep); each named for its Ruby value type, deliberate copies of `IntegerField` |
 | ~~Progress Bar~~ | `draw_line` + `EventQueue#tick_fps` | **built** 2026-08-02 (`D-progress-bar`, book ch7); a `value` that stays out of `HasValue`, ticker synced from `attached? && indeterminate?` |
-| Notification | `Popup` + `Ticker` | needs corner-anchored (non-centered) popup placement |
+| ~~Notification~~ | `Popup` + `Ticker` | **built** 2026-08-17 (`D-notification`, book ch7); one non-modal top-right box, N messages, one 3 s ticker retiring the oldest. Corner anchor is its own `reposition` override, so `Popup` was untouched — and the `Popover` extraction still waits for a second *kind* of anchoring |
 | Confirm Dialog | `Popup`+`Window`+`Button` | fold `PickerWindow` in |
 | Details → Accordion | `HasContent` | Details is the atom, Accordion the group |
 | Tabs → Tabsheet | `HasValue` (index) + `HasContent` | strip, then strip + content swap |
@@ -104,7 +105,11 @@ file when its cluster comes up:
 5. **Mouse motion/drag** (modes 1002/1006, release events) → Split
    divider, Slider drag, scrollbar drag.
 6. **Typed items + data provider on `List`** → List Box, Grid, Virtual
-   List.
+   List. **Half done** 2026-08-14 (`D-list-items`): `List` takes `items` +
+   a `renderer` and renders only the visible rows, and the five composers
+   are folded onto it. The remaining half is *sourcing* items lazily (a
+   data provider behind `items`), which lazy rendering was chosen to keep
+   reachable without a redesign.
 
 Vaadin's `Binder` is the natural companion for the forms cluster but is
 not a component; `D-has-value` already parks the forms-layer questions

data/lib/tuile/buffer.rb

@@ -3,7 +3,7 @@
 module Tuile
   # An in-memory grid of styled cells mirroring the terminal screen. This is
   # the back buffer behind flicker-free rendering: components paint into it
-  # (via {#set_line} / {#set_char} / {#fill}) instead of writing escape
+  # (via {#set_text} / {#set_char} / {#fill}) instead of writing escape
   # sequences straight to the terminal, and {#flush} emits the minimal escape
   # string needed to bring a terminal — one that already matches the buffer's
   # state as of the previous flush — up to date. Only cells that actually
@@ -133,7 +133,7 @@ module Tuile
     # @param x [Integer] column.
     # @param y [Integer] row.
     # @return [Cell, nil] the live cell at `(x, y)` (do not mutate — paint via
-    #   {#set_char} / {#set_line} so dirty tracking stays correct), or nil when
+    #   {#set_char} / {#set_text} so dirty tracking stays correct), or nil when
     #   out of bounds.
     def cell(x, y)
       return nil unless in_bounds?(x, y)
@@ -160,12 +160,12 @@ module Tuile
 
     # Writes a {StyledString} starting at `(x, y)`, advancing by each grapheme's
     # display width and clipping at the right edge. Newlines are not handled —
-    # pass one physical line.
+    # pass the text of one row.
     # @param x [Integer] starting column.
     # @param y [Integer] row.
     # @param styled [StyledString]
     # @return [void]
-    def set_line(x, y, styled)
+    def set_text(x, y, styled)
       col = x
       styled.spans.each do |span|
         span.text.grapheme_clusters.each do |g|
@@ -281,7 +281,7 @@ module Tuile
     # @param y [Integer] row.
     # @return [String] row `y` rendered to ANSI across its full width — the
     #   minimal-SGR encoding of its cells, equivalent to what a component's
-    #   `set_line` of the whole row would have printed. Intended for tests that
+    #   `set_text` of the whole row would have printed. Intended for tests that
     #   assert on styled output (see {FakeScreen}); empty for an out-of-range row.
     def row_ansi(y)
       return "" unless y >= 0 && y < @height
@@ -304,7 +304,7 @@ module Tuile
 
     # @param rect [Rect]
     # @return [Array<String>] each row within `rect` rendered to ANSI, top to
-    #   bottom — byte-identical to what a component's per-row `set_line` over
+    #   bottom — byte-identical to what a component's per-row `set_text` over
     #   that rect emitted. The region equivalent of {#row_ansi}. Intended for
     #   tests asserting styled output.
     def region_ansi(rect)
@@ -316,7 +316,7 @@ module Tuile
     private
 
     # Core of {#set_char} with the grapheme's display width already known.
-    # {#set_line} computes each width once while advancing the column and passes
+    # {#set_text} computes each width once while advancing the column and passes
     # it straight through, so the paint hot path measures every grapheme exactly
     # once (and that once is a {.display_width} memo read). See {#set_char} for
     # the wide-glyph / clipping / out-of-bounds contract.

data/lib/tuile/component/button.rb

@@ -76,7 +76,7 @@ module Tuile
 
         label = (StyledString.plain("[ ") + caption + StyledString.plain(" ]")).ellipsize(rect.width)
         label = label.with_bg(screen.theme.active_bg_color) if active?
-        draw_line(rect.left, rect.top, label)
+        draw_text(rect.left, rect.top, label)
       end
     end
   end

data/lib/tuile/component/checkbox.rb

@@ -127,7 +127,7 @@ module Tuile
 
         label = (StyledString.plain(value ? "[x] " : "[ ] ") + caption).ellipsize(rect.width)
         label = label.with_bg(screen.theme.active_bg_color) if active?
-        draw_line(rect.left, rect.top, label)
+        draw_text(rect.left, rect.top, label)
       end
     end
   end