tuile 0.16.0 → 0.17.0

data/examples/sampler.rb

@@ -20,35 +20,33 @@ require "rainbow"
 require "tuile"
 
 module SamplerExample
+  # `color` with `by` added to each RGB channel, clamped. Tuile ships no color
+  # arithmetic; this is the app's.
+  STEP = ->(color, by) { Tuile::Color.rgb(*color.rgb.map { (_1 + by).clamp(0, 255) }) }
+
   # `hint` is the app's token, not Tuile's: the framework carries accents for
   # the chrome *it* paints, and the status row below is the sampler's own
   # (`D_status_bar` — Tuile draws none). Paired in a ThemeDef so it survives an
   # OS appearance flip, where a bare `theme=` would be replaced. Both greys
   # quantize to :bright_black on a 16-color terminal, so the description stays
   # dimmer than the key beside it even there.
+  #
+  # `terminal_tint` is derived: the terminal's *own* background stepped 10 per
+  # channel away from the ink — the borderless-pane tint, which only sits right
+  # when it comes from the real background. The screen re-derives it whenever
+  # the background changes; the fixed grey is for a terminal that reported none,
+  # which is the branch most users will actually see.
   APP_THEME = Tuile::ThemeDef.new(
-    dark: Tuile::Theme::DARK.with(custom: { hint: Tuile::Color::GREY54 }),
-    light: Tuile::Theme::LIGHT.with(custom: { hint: Tuile::Color::GREY62 })
+    dark: Tuile::Theme::DARK.with(custom: {
+                                    hint: Tuile::Color::GREY54,
+                                    terminal_tint: ->(bg) { bg ? STEP.call(bg, 10) : Tuile::Color::GREY15 }
+                                  }),
+    light: Tuile::Theme::LIGHT.with(custom: {
+                                      hint: Tuile::Color::GREY62,
+                                      terminal_tint: ->(bg) { bg ? STEP.call(bg, -10) : Tuile::Color::GREY89 }
+                                    })
   )
 
-  # Sampler-local container: a {Tuile::Component::Layout::Absolute} that runs a
-  # caller-supplied block on `rect=` to position its children. Most demos are
-  # plain stacks and use the box layouts instead; this is what's left for the
-  # two that aren't — a sidebar whose width is `min(16, width / 3)`, which is a
-  # cap on a proportion and so outside {Tuile::Component::Layout::Box}'s
-  # Fixed/Percent/Expand vocabulary by design.
-  class Panel < Tuile::Component::Layout::Absolute
-    def initialize(&layout_block)
-      super()
-      @layout_block = layout_block
-    end
-
-    def rect=(new_rect)
-      super
-      @layout_block&.call(rect) unless rect.empty?
-    end
-  end
-
   # A {Tuile::Component::Layout::Vertical} that runs {#on_tick} on every frame
   # while it is on screen. The ticker is started on attach and cancelled on
   # detach, so selecting another demo — which detaches this pane — cannot leave
@@ -60,11 +58,16 @@ module SamplerExample
       @fps = fps
     end
 
-    # @return [Proc, nil] called with no arguments on each frame.
-    attr_writer :on_tick
+    # What `on_tick` fires.
+    TickEvent = Data.define(:source) { include Tuile::Event }
+
+    # @!method on_tick
+    #   Fired once per frame while this box is attached.
+    #   @return [Tuile::Listeners]
+    listener :on_tick
 
     def handle_attached
-      @ticker = screen.event_queue.tick_fps(@fps) { @on_tick&.call }
+      @ticker = screen.event_queue.tick_fps(@fps) { on_tick.fire(TickEvent.new(source: self)) }
     end
 
     def handle_detached
@@ -84,13 +87,18 @@ module SamplerExample
       @shortcut = shortcut
     end
 
-    # @return [Proc, nil] called with no arguments when the shortcut arrives.
-    attr_writer :on_shortcut
+    # What `on_shortcut` fires.
+    ShortcutEvent = Data.define(:source) { include Tuile::Event }
+
+    # @!method on_shortcut
+    #   Fired when the claimed key arrives.
+    #   @return [Tuile::Listeners]
+    listener :on_shortcut
 
     def handle_key?(key)
       return false unless key == @shortcut
 
-      @on_shortcut&.call
+      on_shortcut.fire(ShortcutEvent.new(source: self))
       true
     end
   end
@@ -99,16 +107,28 @@ module SamplerExample
   # the chat-prompt shape, and the one that made a multi-line paste fire the
   # submit once per pasted line before Tuile drove bracketed paste. It handles
   # no paste of its own: pasted text never arrives as ENTER, so the inherited
-  # insert-at-caret is already the wanted behavior, and `on_paste` here only
-  # feeds the demo's counter.
+  # insert-at-caret is already the wanted behavior, and `on_paste_received` here
+  # only feeds the demo's counter.
   class PromptTextArea < Tuile::Component::TextArea
-    # @return [Proc, nil] called with the submitted text; the area then clears.
-    attr_accessor :on_submit
-    # @return [Proc, nil] called with the pasted text, before it is inserted.
-    attr_accessor :on_paste
+    # What `on_submit` fires.
+    SubmitEvent = Data.define(:source, :text) { include Tuile::Event }
+
+    # What `on_paste_received` fires.
+    PasteEvent = Data.define(:source, :text) { include Tuile::Event }
+
+    # @!method on_submit
+    #   Fired with the submitted text; the area then clears.
+    #   @return [Tuile::Listeners]
+    listener :on_submit
+
+    # @!method on_paste_received
+    #   Fired with the pasted text, before it is inserted. Not `on_paste`:
+    #   `handle_paste` is the override point, and a slot may not take its name.
+    #   @return [Tuile::Listeners]
+    listener :on_paste_received
 
     def handle_paste(text)
-      @on_paste&.call(text)
+      on_paste_received.fire(PasteEvent.new(source: self, text: text))
       super
     end
 
@@ -117,8 +137,8 @@ module SamplerExample
     def handle_text_input_key?(key)
       return super unless key == Tuile::Keys::ENTER
 
-      @on_submit&.call(text)
-      self.text = ""
+      on_submit.fire(SubmitEvent.new(source: self, text: text))
+      self.value = ""
       true
     end
   end
@@ -170,10 +190,10 @@ module SamplerExample
   # unviewable with the pointer over it.
   #
   #   canvas = Canvas.new
-  #   canvas.on_event = ->(line) { log.log(line) }
-  #   canvas.on_move = ->(event, count) { label.text = "#{event.x},#{event.y} (#{count})" }
+  #   canvas.on_report { |e| log.log(e.line) }
+  #   canvas.on_move { |e| label.text = "#{e.mouse.x},#{e.mouse.y} (#{e.moves})" }
   #
-  # Two slots, because the traffic is two: {#on_event} carries the discrete
+  # Two slots, because the traffic is two: {#on_report} carries the discrete
   # events to a log, {#on_move} the ~84-a-second moves to one replaced row.
   # Feeding both to a log would drown enter/exit inside 12 ms.
   #
@@ -187,7 +207,7 @@ module SamplerExample
   # two-column trail cell would push every painted row past `rect.width`
   # (`D_ambiguous_width`).
   #
-  # It paints every cell of its rect itself, one {Tuile::Component#draw_text}
+  # It paints every cell of its rect itself, one {Tuile::Canvas#set_text}
   # per run of like cells, and so skips `super` in {#repaint} — whose
   # auto-clear blanks the whole rect, which would re-emit every cell this widget
   # is about to paint over anyway. Repainting whole on every move still costs
@@ -206,12 +226,23 @@ module SamplerExample
     # @return [Hash{Symbol => String, nil}]
     DRAG_INK = { left: STROKE, right: nil }.freeze
 
-    # @return [Proc, nil] called with one line (String) per discrete event.
-    attr_accessor :on_event
+    # What `on_report` fires.
+    ReportEvent = Data.define(:source, :line) { include Tuile::Event }
+
+    # What `on_move` fires.
+    MoveEvent = Data.define(:source, :mouse, :moves) { include Tuile::Event }
+
+    # @!method on_report
+    #   Fired with one line of commentary per discrete event.
+    #   @return [Tuile::Listeners]
+    listener :on_report
 
-    # @return [Proc, nil] called with the {Tuile::Mouse::Event} and the number
-    #   of moves so far (Integer), on every move and every drag.
-    attr_accessor :on_move
+    # @!method on_move
+    #   Fired on every move and every drag, with the {Tuile::Mouse::Event} as
+    #   `mouse` — not `event`, which would read as the event's event — and the
+    #   number of moves so far.
+    #   @return [Tuile::Listeners]
+    listener :on_move
 
     # @return [Tuile::Point] the keyboard caret, in rect-local coordinates.
     attr_reader :caret
@@ -228,40 +259,40 @@ module SamplerExample
       @moves = 0
       @drag_ink = nil
       @drag_outside = false
+      bg.default_color = Tuile::ComponentBackground::INPUT_WELL
     end
 
     def focusable? = true
 
     def tab_stop? = true
 
+    # The caret is already rect-local, and so is what a cursor position means —
+    # {Tuile::Screen#cursor_position} puts it on screen.
     # @return [Tuile::Point, nil]
     def cursor_position
       return nil if rect.empty?
 
-      Tuile::Point.new(rect.left + @caret.x, rect.top + @caret.y)
+      @caret
     end
 
-    # @return [Tuile::Color]
-    def default_bg_color = active? ? screen.theme.active_bg_color : screen.theme.input_bg_color
-
     # Clamps the caret into the new rect, so a shrink cannot strand it — and
     # with it the hardware cursor — outside what this widget paints.
-    # @param new_rect [Tuile::Rect]
-    def rect=(new_rect)
+    # @param old_rect [Tuile::Rect]
+    def handle_rect_changed(old_rect)
       super
-      @caret = Tuile::Point.new(@caret.x.clamp(0, [new_rect.width - 1, 0].max),
-                                @caret.y.clamp(0, [new_rect.height - 1, 0].max))
+      @caret = Tuile::Point.new(@caret.x.clamp(0, [rect.width - 1, 0].max),
+                                @caret.y.clamp(0, [rect.height - 1, 0].max))
     end
 
     # @return [void]
-    def repaint
+    def repaint(canvas)
       return if rect.empty?
 
       # The clear is what a self-painter opts out of; the cascade never is
       # (`D_repaint_cascade`), leaf or not.
       invalidate_children
       trail_color = screen.theme[:hint]
-      rect.height.times { |row| draw_row(row, trail_color) }
+      rect.height.times { |row| draw_row(canvas, row, trail_color) }
     end
 
     # @param event [Tuile::Mouse::DownEvent]
@@ -349,11 +380,13 @@ module SamplerExample
     private
 
     # One row, as runs of like cells: every cell is painted exactly once, so
-    # none is blanked and then painted over (`D_progress_bar`).
+    # none is blanked and then painted over (`D_progress_bar`). The canvas
+    # paints in the same rect-local coordinates the marks are keyed by, so a
+    # run goes straight to `set_text` with no offset.
     # @param row [Integer] rect-local row.
     # @param trail_color [Tuile::Color]
     # @return [void]
-    def draw_row(row, trail_color)
+    def draw_row(canvas, row, trail_color)
       column = 0
       while column < rect.width
         glyph = @ink[Tuile::Point.new(column, row)]
@@ -361,21 +394,21 @@ module SamplerExample
         run += 1 while column + run < rect.width && @ink[Tuile::Point.new(column + run, row)] == glyph
         text = (glyph || " ") * run
         styled = glyph == TRAIL ? Tuile::StyledString.styled(text, fg: trail_color) : Tuile::StyledString.plain(text)
-        draw_text(rect.left + column, rect.top + row, styled)
+        canvas.set_text(column, row, styled)
         column += run
       end
     end
 
-    # The event's cell in rect-local coordinates, or nil when it lands outside
-    # — which a grabbed {Tuile::Mouse::DragEvent} routinely does.
+    # The event's cell, or nil when it lands outside — which a grabbed
+    # {Tuile::Mouse::DragEvent} routinely does. A mouse event already arrives in
+    # this component's own coordinates, so there is nothing to subtract; the
+    # bounds test is the whole job.
     # @param event [Tuile::Mouse::Event]
     # @return [Tuile::Point, nil]
     def cell_at(event)
-      column = event.x - rect.left
-      row = event.y - rect.top
-      return nil unless (0...rect.width).cover?(column) && (0...rect.height).cover?(row)
+      return nil unless (0...rect.width).cover?(event.x) && (0...rect.height).cover?(event.y)
 
-      Tuile::Point.new(column, row)
+      Tuile::Point.new(event.x, event.y)
     end
 
     # Lays the dragged ink at `cell` and takes the caret with it, so a stroke
@@ -429,13 +462,13 @@ module SamplerExample
 
     # @param line [String]
     # @return [void]
-    def report(line) = @on_event&.call(line)
+    def report(line) = on_report.fire(ReportEvent.new(source: self, line: line))
 
     # @param event [Tuile::Mouse::Event]
     # @return [void]
     def report_move(event)
       @moves += 1
-      @on_move&.call(event, @moves)
+      on_move.fire(MoveEvent.new(source: self, mouse: event, moves: @moves))
     end
   end
 
@@ -465,7 +498,7 @@ module SamplerExample
 
     # The bottom row. Tuile draws no status bar and reserves no row
     # (`D_status_bar`) — this one is the sampler's own, kept current by
-    # {Tuile::Screen#on_focus_changed=}. Naming the focused component makes Tab
+    # {Tuile::Screen#on_focus_changed}. Naming the focused component makes Tab
     # traversal visible as you walk a pane, which no per-pane label shows.
     # @return [void]
     def refresh_status
@@ -508,9 +541,10 @@ module SamplerExample
     # as a live index of the catalogue and any drift between the two is visible.
     #
     # Mnemonics are *hand-picked*: {Tuile::Component::MenuBar#add_item} raises on
-    # a duplicate among siblings, and six leaves therefore answer to a letter
+    # a duplicate among siblings, and seven leaves therefore answer to a letter
     # other than their initial (Past`e`, Checkbox`G`roup, C`o`mboBox,
-    # Pic`k`erWindow, S`l`ash menu, DateTi`m`eField) — the underline shows which.
+    # Pic`k`erWindow, S`l`ash menu, DateTi`m`eField, F`o`rmLayout) — the
+    # underline shows which.
     # No item may use
     # `q`: quit is the unhandled-key fallback, so a `q` on the live level would
     # swallow it while the bar has focus.
@@ -559,6 +593,8 @@ module SamplerExample
                  Entry.new("LogWindow", :build_log_window, "l")
                ]),
       Menu.new("Shell", "h", [
+                 Entry.new("FormLayout", :build_form_layout, "o"),
+                 Entry.new("Scroller", :build_scroller, "s"),
                  Entry.new("TabSheet", :build_tab_sheet, "t"),
                  Entry.new("MenuBar", :build_menu_bar, "m"),
                  Entry.new("Narrow strips", :build_narrow_strips, "n"),
@@ -613,7 +649,7 @@ module SamplerExample
     def build_jump_box
       combo = Tuile::Component::ComboBox.new(items: ENTRIES)
       combo.item_label = :caption.to_proc
-      combo.on_value_change = ->(entry) { load_entry(entry) if entry }
+      combo.on_value_change { |e| load_entry(e.value) if e.value }
       combo
     end
 
@@ -668,7 +704,7 @@ module SamplerExample
                     "Home/End jump to row start/end; Up/Down at the first/last row jumps to text start/end.\n" \
                     "Overflowing rows scroll vertically to keep the caret visible."
       area = Tuile::Component::TextArea.new
-      area.text = "The quick brown fox jumps over the lazy dog. " \
+      area.value = "The quick brown fox jumps over the lazy dog. " \
                   "Edit me — the text wraps to the area's width and scrolls vertically " \
                   "once the cursor leaves the visible rows."
       form do |f|
@@ -687,7 +723,7 @@ module SamplerExample
       items = %w[Ruby Python JavaScript TypeScript Rust Go Elixir Crystal Haskell Kotlin Swift Zig]
       combo = Tuile::Component::ComboBox.new(items: items)
       status = Tuile::Component::Label.new.tap { _1.text = "(nothing selected)" }
-      combo.on_value_change = ->(value) { status.text = "Selected: #{value}" }
+      combo.on_value_change { |e| status.text = "Selected: #{e.value}" }
       form do |f|
         f.add(prompt, Fixed[3])
         # A cross constraint clamps to the pane, so this is 30 columns or fewer.
@@ -728,14 +764,14 @@ module SamplerExample
         status.text = "level: #{level.value.inspect}  endings: #{endings.value&.label.inspect}"
       end
       update.call
-      [level, endings].each { _1.on_value_change = ->(_v) { update.call } }
+      [level, endings].each { _1.on_value_change { update.call } }
 
       pane = ShortcutBox.new("r", spacing: 1, padding: FORM_PADDING)
       pane.add(prompt, Fixed[3])
       pane.add(labelled("Log level", level), Fixed[1])
       pane.add(labelled("Line endings", endings), Fixed[1])
       pane.add(status, Fixed[1])
-      pane.on_shortcut = lambda do
+      pane.on_shortcut do
         level.value = "warn"
         endings.value = nil
         update.call
@@ -755,7 +791,7 @@ module SamplerExample
       # Set on the composed field, not on the TextField inside it.
       field.placeholder = "1-65535"
       status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
-      field.on_value_change = ->(value) { status.text = "value: #{value.inspect}" }
+      field.on_value_change { |e| status.text = "e.value: #{e.value.inspect}" }
       form do |f|
         f.add(prompt, Fixed[2])
         f.add(field, Fixed[1], cross: Fixed[20])
@@ -773,7 +809,7 @@ module SamplerExample
                     "Up/Down step the value by one. Watch the value while you type '1.5'."
       field = Tuile::Component::FloatField.new
       status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
-      field.on_value_change = ->(value) { status.text = "value: #{value.inspect}" }
+      field.on_value_change { |e| status.text = "e.value: #{e.value.inspect}" }
       form do |f|
         f.add(prompt, Fixed[2])
         f.add(field, Fixed[1], cross: Fixed[20])
@@ -792,7 +828,7 @@ module SamplerExample
                     "what you typed (19.90 keeps its zero)."
       field = Tuile::Component::BigDecimalField.new
       status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
-      field.on_value_change = ->(value) { status.text = triple_report(value) }
+      field.on_value_change { |e| status.text = triple_report(e.value) }
       form do |f|
         f.add(prompt, Fixed[3])
         f.add(field, Fixed[1], cross: Fixed[20])
@@ -822,7 +858,7 @@ module SamplerExample
       # calendar reform, which is noise next to the one fact this row is for.
       report = -> { status.text = "value: #{field.value&.to_s || "nil"}    bad_input?: #{field.bad_input?}" }
       report.call
-      field.on_value_change = ->(_value) { report.call }
+      field.on_value_change { report.call }
       ask = Tuile::Component::Button.new("Ask again") { report.call }
       form do |f|
         f.add(prompt, Fixed[4])
@@ -855,7 +891,7 @@ module SamplerExample
                       "seconds: #{seconds.value&.strftime("%H:%M:%S") || "nil"} (#{seconds.formats.first})"
       end
       report.call
-      [minutes, seconds].each { _1.on_value_change = ->(_value) { report.call } }
+      [minutes, seconds].each { _1.on_value_change { report.call } }
       form do |f|
         f.add(prompt, Fixed[4])
         f.add(labelled("Minute stride", minutes, field_width: 12), Fixed[1], cross: Fixed[30])
@@ -896,7 +932,7 @@ module SamplerExample
       # next to the one fact this row carries.
       report = -> { status.text = "value: #{field.value&.strftime("%Y-%m-%d %H:%M") || "nil"}" }
       report.call
-      field.on_value_change = ->(_value) { report.call }
+      field.on_value_change { report.call }
       save = Tuile::Component::Button.new("Save") { save_form("Starts at" => field) }
       form do |f|
         f.add(prompt, Fixed[4])
@@ -920,8 +956,8 @@ module SamplerExample
       amount = Tuile::Component::IntegerField.new.tap { _1.id = :amount }
       rate = Tuile::Component::FloatField.new.tap { _1.id = :rate }
       echo = Tuile::Component::Label.new.tap { _1.text = "on_value_change: (nothing yet)" }
-      amount.on_value_change = ->(v) { echo.text = "on_value_change: amount = #{v.inspect}" }
-      rate.on_value_change = ->(v) { echo.text = "on_value_change: rate = #{v.inspect}" }
+      amount.on_value_change { |e| echo.text = "on_value_change: amount = #{e.value.inspect}" }
+      rate.on_value_change { |e| echo.text = "on_value_change: rate = #{e.value.inspect}" }
       save = Tuile::Component::Button.new("Save") { save_form("Amount" => amount, "Rate" => rate) }
       save.id = :save
       rows = group do |g|
@@ -967,7 +1003,7 @@ module SamplerExample
     #   the field's listener keeps current.
     def validated_row(caption, field)
       error = Tuile::Component::Label.new
-      field.on_error_message_change = ->(msg) { error.text = msg || Tuile::StyledString::EMPTY }
+      field.on_error_message_change { |e| error.text = e.error_message || Tuile::StyledString::EMPTY }
       row do |r|
         r.add(Tuile::Component::Label.new(caption), Fixed[14])
         r.add(field, Fixed[22])
@@ -1034,11 +1070,11 @@ module SamplerExample
       user = Tuile::Component::TextField.new
       password = Tuile::Component::PasswordField.new
       reveal = Tuile::Component::Checkbox.new("Show password")
-      reveal.on_value_change = ->(on) { password.revealed = on }
+      reveal.on_value_change { |e| password.revealed = e.value }
       status = Tuile::Component::Label.new
       refresh = -> { status.text = "user: #{user.text.inspect}  password: #{password.value.length} chars" }
       refresh.call
-      [user, password].each { _1.on_change = ->(_) { refresh.call } }
+      [user, password].each { _1.on_value_change { refresh.call } }
       form do |f|
         f.add(prompt, Fixed[4])
         f.add([user, password], Fixed[1], cross: Fixed[30]) # one constraint, both fields
@@ -1053,7 +1089,7 @@ module SamplerExample
     # A ListDropdown driven from a TextArea — the same shape {ComboBox} and
     # {Select} use, but wired by app code onto a field that knows nothing about
     # it. Focus (and the caret) stays in the TextArea the whole time: an
-    # `on_change` listener refills the menu, and {SlashCommandTextArea} hands
+    # `on_value_change` listener refills the menu, and {SlashCommandTextArea} hands
     # movement keys to `#move` and Enter to `#choose` while it is open.
     def build_slash_demo
       prompt = Tuile::Component::Label.new
@@ -1071,15 +1107,14 @@ module SamplerExample
           overlay.close if overlay.open?
         else
           overlay.items = matches
-          overlay.open unless overlay.open?
           # Width is the driver's call, never the dropdown's: measure the
           # commands rather than inherit the full-width TextArea's columns.
-          overlay.anchor_to(area.rect, rows: matches.size, width: slash_menu_width(matches))
+          overlay.anchor_to(area, width: slash_menu_width(matches))
         end
       end
 
-      area.on_change = ->(_text) { refill.call }
-      overlay.on_item_chosen = ->(_idx, item) { accept_slash_command(area, item.to_s) }
+      area.on_value_change { refill.call }
+      overlay.list.on_item_chosen { |e| accept_slash_command(area, e.item.to_s) }
 
       form do |f|
         f.add(prompt, Fixed[4])
@@ -1105,14 +1140,14 @@ module SamplerExample
       refresh = lambda do
         stats.text = "submits: #{submits}   pastes: #{pastes}   rows in draft: #{area.row_count}"
       end
-      area.on_change = ->(_text) { refresh.call }
-      area.on_paste = lambda do |text|
+      area.on_value_change { refresh.call }
+      area.on_paste_received do |e|
         pastes += 1
-        log.add_line(Rainbow("pasted #{text.lines.size} line(s), #{text.length} chars").cyan)
+        log.add_line(Rainbow("pasted #{e.text.lines.size} line(s), #{e.text.length} chars").cyan)
       end
-      area.on_submit = lambda do |text|
+      area.on_submit do |e|
         submits += 1
-        log.add_line(Rainbow("submitted: #{text.inspect}").green)
+        log.add_line(Rainbow("submitted: #{e.text.inspect}").green)
       end
       refresh.call
 
@@ -1198,7 +1233,7 @@ module SamplerExample
         status.text = "checked: #{on.empty? ? "(none)" : on.join(", ")}"
       end
       refresh.call
-      boxes.each { _1.on_value_change = ->(_) { refresh.call } }
+      boxes.each { _1.on_value_change { refresh.call } }
       # The boxes sit flush against each other while the form keeps a blank row
       # around the block: a spacing-0 group nested in the spacing-1 form, rather
       # than a per-child gap the framework deliberately doesn't offer.
@@ -1229,7 +1264,7 @@ module SamplerExample
         conditional.each { _1.visible = business.checked? }
         status.text = "visible fields: #{business.checked? ? 4 : 2}"
       end
-      business.on_value_change = ->(_) { apply.call }
+      business.on_value_change { apply.call }
       # The rows sit flush; the form keeps its blank row around the block.
       rows = group do |g|
         g.add(labelled("Name", Tuile::Component::TextField.new), Fixed[1])
@@ -1312,16 +1347,13 @@ module SamplerExample
         status.text = "value: {#{shown.join(", ")}} — #{log.items.size} of #{entries.size} lines"
       end
       refresh.call
-      group.on_value_change = ->(_set) { refresh.call }
+      group.on_value_change { refresh.call }
 
-      # The body keeps a rect-callback {Panel}: its sidebar is `min(16, width/3)`
-      # — a cap on a proportion, which Fixed/Percent/Expand can't say. The stack
-      # around it is a box, so only the part that needs arithmetic has any.
-      body = panel(group, log) do |r|
-        group_width = [16, r.width / 3].min
-        group.rect = Tuile::Rect.new(r.left, r.top, group_width, [LOG_LEVELS.size, r.height].min)
-        log.rect = Tuile::Rect.new(r.left + group_width + 2, r.top,
-                                   [r.width - group_width - 2, 4].max, r.height)
+      # The sidebar is a third of the row but never over 16 columns — a capped
+      # proportion, which is a Percent with a clamp.
+      body = row do |r|
+        r.add(group, Percent[33].clamp(..16), cross: Fixed[LOG_LEVELS.size])
+        r.add(log, Expand[1])
       end
       form do |f|
         f.add(prompt, Fixed[4])
@@ -1396,20 +1428,17 @@ module SamplerExample
         update_status.call
       end
       resort.call
-      group.on_value_change = ->(_order) { resort.call }
+      group.on_value_change { resort.call }
       # `list` is the composed List, which is where the cursor lives.
       # Watching it is what makes the chrome/value split visible above.
-      group.list.on_cursor_changed = ->(_idx, _line) { update_status.call }
-
-      # Side-by-side body on a rect-callback {Panel}, as in the CheckboxGroup
-      # demo — the sidebar width is a capped proportion, not a constraint.
-      body = panel(group, files) do |r|
-        # List pads a column either side of a row, so a label needs
-        # `width - 2`; the file rows lose one more to their scrollbar.
-        group_width = [14, r.width / 3].min
-        group.rect = Tuile::Rect.new(r.left, r.top, group_width, [SORT_ORDERS.size, r.height].min)
-        files.rect = Tuile::Rect.new(r.left + group_width + 2, r.top,
-                                     [r.width - group_width - 2, 4].max, r.height)
+      group.list.on_cursor_changed { update_status.call }
+
+      # Side-by-side body with a capped sidebar, as in the CheckboxGroup demo.
+      # List pads a column either side of a row, so a label needs `width - 2`;
+      # the file rows lose one more to their scrollbar.
+      body = row do |r|
+        r.add(group, Percent[33].clamp(..14), cross: Fixed[SORT_ORDERS.size])
+        r.add(files, Expand[1])
       end
       form do |f|
         f.add(prompt, Fixed[4])
@@ -1476,7 +1505,7 @@ module SamplerExample
       pane.add(prompt, Fixed[4])
       pane.add(determinate, Fixed[2])
       pane.add(indeterminate, Fixed[3])
-      pane.on_tick = lambda do
+      pane.on_tick do
         done = done < PROGRESS_TOTAL ? done + 1 : 0
         bar.value = done
         refresh.call
@@ -1494,6 +1523,7 @@ module SamplerExample
     # of hard-coded ANSI / 256-palette / RGB colors that stay put across flips.
     BG_CHOICES = [
       BgChoice.new("None (terminal default)", nil),
+      BgChoice.new("Terminal background, stepped (derived)", Tuile::Theme.ref(:terminal_tint)),
       BgChoice.new("Theme: input well", Tuile::Theme.ref(:input_bg_color)),
       BgChoice.new("Theme: active", Tuile::Theme.ref(:active_bg_color)),
       BgChoice.new("Theme: active border", Tuile::Theme.ref(:active_border_color)),
@@ -1507,21 +1537,6 @@ module SamplerExample
       BgChoice.new("Hot pink (RGB)", Tuile::Color.rgb(120, 20, 70))
     ].freeze
 
-    # The one choice that can't be a constant: the terminal's *own* background
-    # stepped +10 per channel — the borderless-pane tint, which only sits right
-    # when it's derived from the real background. Nil on a terminal that
-    # reported none, which is the branch most users will actually see.
-    def terminal_tint_choice
-      bg = Tuile::Screen.instance.background_color
-      return BgChoice.new("Terminal background — none reported", nil) if bg.nil?
-
-      BgChoice.new("Terminal background +10 (derived)",
-                   Tuile::Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }))
-    end
-
-    # @param derived [BgChoice] the live terminal-derived tint, offered second.
-    def bg_choices(derived) = [BG_CHOICES.first, derived, *BG_CHOICES[1..]]
-
     def build_background
       intro = Tuile::Component::Label.new
       intro.text = "bg_color tints a component and every descendant that doesn't set its own.\n" \
@@ -1532,7 +1547,7 @@ module SamplerExample
       list.cursor = Tuile::Component::List::Cursor.new
       list.lines = (1..12).map { |i| "List row #{i}" }
       field = Tuile::Component::TextField.new
-      field.text = "TextField keeps its own background"
+      field.value = "TextField keeps its own background"
 
       # A borderless sub-box holding the list + field; it inherits the tint too.
       box = Tuile::Component::Layout::Vertical.new(spacing: 1)
@@ -1542,34 +1557,81 @@ module SamplerExample
       # A ComboBox over BG_CHOICES swaps the whole panel's bg_color on commit, so
       # the tint flows down to every descendant without its own background — the
       # label and the list — while the input widgets (the combo, the field) keep
-      # their own well. Theme::Ref picks re-resolve on a scheme flip with no hook;
-      # the hard-coded Colors are fixed by design, so no handle_theme_changed here.
+      # their own well. Theme::Ref picks re-resolve on a scheme flip with no hook —
+      # the derived terminal tint too, re-derived when the background changes —
+      # and the hard-coded Colors are fixed by design, so no handle_theme_changed.
       outer = nil
-      derived = terminal_tint_choice
-      combo = Tuile::Component::ComboBox.new(items: bg_choices(derived))
+      combo = Tuile::Component::ComboBox.new(items: BG_CHOICES)
       combo.item_label = :label.to_proc
-      combo.on_value_change = ->(choice) { outer.bg_color = choice.color }
+      combo.on_value_change { |e| outer.bg_color = e.value.color }
 
       outer = form do |f|
         f.add(intro, Fixed[3])
         f.add(combo, Fixed[1], cross: Fixed[40])
         f.add(box, Expand[1])
       end
-      # The derived tint is the one pick whose *color* moves under it: a flip
-      # re-probes the terminal, so rebuild the choice and re-apply it if it is
-      # the current one. Expect it to correct itself a frame late — the flip
-      # report carries no RGB, so this hook runs once on the old background and
-      # again when the re-probe answers.
-      outer.on_theme_changed = lambda do
-        was_derived = combo.value.equal?(derived)
-        derived = terminal_tint_choice
-        combo.items = bg_choices(derived)
-        combo.value = derived if was_derived
-      end
       combo.value = BG_CHOICES.first # show "None" as the resting selection
       outer
     end
 
+    # FormLayout: hand it fields and captions, and it stacks the FormItems it
+    # builds. No binder here — the two name fields validate themselves from
+    # their own `on_value_change`, and `error_message=` is what puts the text
+    # in the item's message row. That row is also the gap, so a field going
+    # invalid while you type into the one below it moves nothing.
+    def build_form_layout
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab into a name field, type a letter, then erase it: the message row under it\n" \
+                    "fills and the well goes red, and nothing below moves. The ∙ beside a caption\n" \
+                    "is the required marker — chrome, not a rule; the listener is the rule."
+      fields = Tuile::Component::FormLayout.new
+      first = Tuile::Component::TextField.new
+      surname = Tuile::Component::TextField.new
+      [first, surname].each do |field|
+        field.on_value_change { |e| e.source.error_message = e.value.empty? ? "Must not be blank" : nil }
+      end
+      fields.add(first, caption: "First name", required: true)
+      fields.add(surname, caption: "Surname", required: true)
+      fields.add(Tuile::Component::DateField.new, caption: "Date of birth")
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(fields, Expand[1], cross: Fixed[FORM_WIDTH])
+      end
+    end
+
+    # Wide enough for the longest message row below a field.
+    FORM_WIDTH = 30
+
+    # A form taller than its viewport. Every field starts empty, hence
+    # invalid, so each message row is filled and visibly scrolls in with it.
+    def build_scroller
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab down the form: the view follows focus, caption and message included, and\n" \
+                    "the wheel scrolls it too. The Scroller claims no keys — ↑↓ stay the fields'."
+      fields = Tuile::Component::FormLayout.new
+      ["First name", "Surname", "Email", "Phone", "Street", "City", "Postcode"].each do |caption|
+        fields.add(non_empty(Tuile::Component::TextField.new), caption:, required: true)
+      end
+      fields.add(non_empty(Tuile::Component::DateField.new), caption: "Date of birth", required: true)
+      # Nothing measures (`D_scroller`): eight items, three rows each.
+      scroller = Tuile::Component::Scroller.new(fields, content_rows: 8 * 3)
+      form do |f|
+        f.add(prompt, Fixed[2])
+        f.add(scroller, Fixed[10], cross: Fixed[FORM_WIDTH + 2])
+      end
+    end
+
+    # Validates `field` as non-empty now and on every change, setting *or
+    # clearing* the verdict each time, as {Tuile::Component::HasValidation} asks.
+    # @param field [Tuile::Component]
+    # @return [Tuile::Component] `field`.
+    def non_empty(field)
+      validate = -> { field.error_message = field.empty? ? "Can not be empty" : nil }
+      field.on_value_change(&validate)
+      validate.call
+      field
+    end
+
     # Horizontal splitting a row between two equal Expand shares. Resize the
     # terminal to watch it recompute: on an odd width the spare column goes to
     # the left pane, since the remainder is handed to the earliest Expand first.
@@ -1617,7 +1679,7 @@ module SamplerExample
                     "so they bubble past the strip."
 
       field = Tuile::Component::TextField.new
-      field.text = "type here"
+      field.value = "type here"
       checkbox = Tuile::Component::Checkbox.new("Remember me", value: true)
       list = Tuile::Component::List.new
       list.cursor = Tuile::Component::List::Cursor.new
@@ -1639,7 +1701,7 @@ module SamplerExample
                       "List row #{list.cursor.position}  ·  Prose row #{view.scroll_top_row}"
       end
       report.call
-      sheet.on_tab_selected = ->(_index, _tab) { report.call }
+      sheet.on_tab_selected { report.call }
 
       form do |f|
         f.add(prompt, Fixed[3])
@@ -1714,7 +1776,7 @@ module SamplerExample
                       "(#{narrow.selected_index + 1} of #{narrow.tabs.size})"
       end
       report.call
-      narrow.on_tab_selected = ->(_index, _tab) { report.call }
+      narrow.on_tab_selected { report.call }
 
       bar = Tuile::Component::MenuBar.new
       %w[File Edit View Window Help].each do |caption|
@@ -1805,7 +1867,7 @@ module SamplerExample
           dialog.button("Save")    { report.call("saved") }
           dialog.button("Discard") { report.call("discarded") }
           dialog.button("Cancel")
-          dialog.on_dismiss = -> { report.call("stayed put") }
+          dialog.on_dismiss { report.call("stayed put") }
           dialog.open
         end,
         Tuile::Component::Button.new("Long") do
@@ -1813,7 +1875,7 @@ module SamplerExample
           dialog.message = (1..40).map { "#{_1}. Clause #{_1} of the agreement, spelled out in full." }.join("\n")
           dialog.button("Accept")  { report.call("accepted the terms") }
           dialog.button("Decline") { report.call("declined the terms") }
-          dialog.on_dismiss = -> { report.call("left the terms unanswered") }
+          dialog.on_dismiss { report.call("left the terms unanswered") }
           dialog.open
         end
       ]
@@ -1930,10 +1992,10 @@ module SamplerExample
       pointer = Tuile::Component::Label.new
       pointer.text = "pointer: (move over the canvas)"
       log = Tuile::Component::LogWindow.new("Events")
-      canvas.on_event = ->(line) { log.log(line) }
-      canvas.on_move = lambda do |event, count|
-        kind = event.is_a?(Tuile::Mouse::DragEvent) ? "drag" : "move"
-        pointer.text = "pointer: #{event.x},#{event.y}  (#{kind}, #{count} reported so far)"
+      canvas.on_report { |e| log.log(e.line) }
+      canvas.on_move do |e|
+        kind = e.mouse.is_a?(Tuile::Mouse::DragEvent) ? "drag" : "move"
+        pointer.text = "pointer: #{e.mouse.x},#{e.mouse.y}  (#{kind}, #{e.moves} reported so far)"
       end
       surface = row do |r|
         r.add(Tuile::Component::Window.new("Canvas").tap { _1.content = canvas }, Percent[55])
@@ -1948,12 +2010,6 @@ module SamplerExample
 
     # --- Helpers -----------------------------------------------------------
 
-    def panel(*children, &layout_block)
-      p = Panel.new(&layout_block)
-      p.add(children)
-      p
-    end
-
     # The standard demo shell: children stacked with a blank row between them,
     # inset from the window border. Every constraint below reads unqualified —
     # `Fixed`, `Expand`, `Insets` all live on {Tuile::Component::Layout}, which
@@ -2017,19 +2073,19 @@ module SamplerExample
     end
 
     # Replaces the slash token at the caret with `command` plus a trailing
-    # space, then drops the caret after it (which re-fires on_change → refill,
+    # space, then drops the caret after it (which re-fires on_value_change → refill,
     # so the now-tokenless text closes the menu).
     def accept_slash_command(area, command)
       text = area.text
       caret = area.caret
       start = caret
       start -= 1 while start.positive? && !text[start - 1].match?(/\s/)
-      area.text = "#{text[0...start]}#{command} #{text[caret..]}"
+      area.value = "#{text[0...start]}#{command} #{text[caret..]}"
       area.caret = start + command.length + 1
     end
 
     # The slash menu's width: the widest command plus List's two row gutters,
-    # clamped to the screen. ListDropdown places itself but never measures — the
+    # clamped to the screen. ListDropdown hangs off its anchor but never measures — the
     # width policy stays with the driver, exactly as it does for Select.
     # @return [Integer]
     def slash_menu_width(matches)
@@ -2049,7 +2105,7 @@ if $PROGRAM_NAME == __FILE__
   screen.theme_def = SamplerExample::APP_THEME
   sampler = SamplerExample::Sampler.new
   screen.content = sampler
-  screen.on_focus_changed = -> { sampler.refresh_status }
+  screen.on_focus_changed { sampler.refresh_status }
   sampler.refresh_status
   sampler.menu_bar.focus
   begin