tuile 0.14.0 → 0.16.0

data/examples/sampler.rb

@@ -12,11 +12,25 @@
 # Keys: ←→ along the strip, Enter/↓ to open a menu, or a letter for the
 # underlined mnemonic. Tab / Shift+Tab move focus between the strip, the jump
 # box and the demo's widgets. q or ESC quits.
+#
+# Runs at `capture_mouse: :hover` — the Mouse demo needs it, and the level is
+# one app-wide choice made at the event loop.
 
 require "rainbow"
 require "tuile"
 
 module SamplerExample
+  # `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.
+  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 })
+  )
+
   # 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
@@ -49,18 +63,18 @@ module SamplerExample
     # @return [Proc, nil] called with no arguments on each frame.
     attr_writer :on_tick
 
-    def on_attached
+    def handle_attached
       @ticker = screen.event_queue.tick_fps(@fps) { @on_tick&.call }
     end
 
-    def on_detached
+    def handle_detached
       @ticker&.cancel
       @ticker = nil
     end
   end
 
   # A {Tuile::Component::Layout::Vertical} that claims one key for itself. An
-  # ancestor's `handle_key` is where a scope-wide binding belongs (key-dispatch
+  # ancestor's `handle_key?` is where a scope-wide binding belongs (key-dispatch
   # rung 3); the Select demo uses one to show the letter still arriving while a
   # Select has focus — the capability a ComboBox, which eats every printable
   # unconditionally, cannot offer.
@@ -73,7 +87,7 @@ module SamplerExample
     # @return [Proc, nil] called with no arguments when the shortcut arrives.
     attr_writer :on_shortcut
 
-    def handle_key(key)
+    def handle_key?(key)
       return false unless key == @shortcut
 
       @on_shortcut&.call
@@ -100,7 +114,7 @@ module SamplerExample
 
     protected
 
-    def handle_text_input_key(key)
+    def handle_text_input_key?(key)
       return super unless key == Tuile::Keys::ENTER
 
       @on_submit&.call(text)
@@ -109,6 +123,322 @@ module SamplerExample
     end
   end
 
+  # A {Tuile::Component::TextArea} that steers a {Tuile::Component::ListDropdown}
+  # while it is open: movement keys move the highlight, ENTER accepts and ESC
+  # dismisses, and everything else — printables, editing, the ENTER that inserts
+  # a newline with no menu up — stays the TextArea's own.
+  #
+  # Subclassing *is* the seam for this. A component receives keys through
+  # `handle_key?`, so one that wants different keys overrides it (here its
+  # `handle_text_input_key?` hook) and calls `super` for the rest, which composes
+  # and stacks. None of this is baked into TextArea.
+  class SlashCommandTextArea < Tuile::Component::TextArea
+    # @param overlay [Tuile::Component::ListDropdown] the menu to steer.
+    def initialize(overlay)
+      super()
+      @overlay = overlay
+    end
+
+    protected
+
+    def handle_text_input_key?(key)
+      return super unless @overlay.open?
+      return true if @overlay.move(key) # Up/Down/PgUp/PgDn/^U/^D
+
+      case key
+      when Tuile::Keys::ENTER then @overlay.choose
+      when Tuile::Keys::ESC then @overlay.close
+      else return super
+      end
+      true
+    end
+  end
+
+  # A drawing surface answering every mouse handler, in two inks that both
+  # persist: a left-drag strokes `X`, a plain hover leaves a `.` trail behind
+  # the pointer, and a right-drag lifts marks again.
+  #
+  #      X          a diagonal drag, then one hover sweep across it
+  #       X
+  #        X
+  #         X
+  #     .....X........
+  #           X
+  #
+  # A trail never overwrites a stroke, so the picture stays a readout of which
+  # channel drew which cell — an eraser-on-hover would instead make the drawing
+  # 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})" }
+  #
+  # Two slots, because the traffic is two: {#on_event} 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.
+  #
+  # Every gesture owes a key (`D_mouse`): the arrows move the caret, space or
+  # `x` strokes it, Delete lifts it, `c` clears. The trail, the enter/exit lines
+  # and {#on_move} need `capture_mouse: :hover` and arrive as nothing below it;
+  # the drag works from `:drag`, a single-cell stroke from `:clicks`.
+  #
+  # == Implementation details
+  # Both glyphs are ASCII on purpose: `·` is East-Asian Ambiguous, so a
+  # 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}
+  # 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
+  # one cell on the wire, since a cell dirties only on a real change.
+  #
+  # Marks are keyed by rect-local {Tuile::Point}: ink beyond a narrowed rect
+  # stops painting and comes back when the rect grows again.
+  class Canvas < Tuile::Component
+    # @return [String] the drag/keyboard ink.
+    STROKE = "X"
+    # @return [String] the hover ink.
+    TRAIL = "."
+
+    # Which ink each button drags — `nil` erases. The middle button is absent:
+    # a press this component declines bubbles on to the window around it.
+    # @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
+
+    # @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
+
+    # @return [Tuile::Point] the keyboard caret, in rect-local coordinates.
+    attr_reader :caret
+
+    # The marks, keyed by rect-local {Tuile::Point} — read-only in practice:
+    # writing one behind {#paint}'s back skips the `invalidate`.
+    # @return [Hash{Tuile::Point => String}]
+    attr_reader :ink
+
+    def initialize
+      super
+      @ink = {}
+      @caret = Tuile::Point.new(0, 0)
+      @moves = 0
+      @drag_ink = nil
+      @drag_outside = false
+    end
+
+    def focusable? = true
+
+    def tab_stop? = true
+
+    # @return [Tuile::Point, nil]
+    def cursor_position
+      return nil if rect.empty?
+
+      Tuile::Point.new(rect.left + @caret.x, rect.top + @caret.y)
+    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)
+      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))
+    end
+
+    # @return [void]
+    def repaint
+      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) }
+    end
+
+    # @param event [Tuile::Mouse::DownEvent]
+    # @return [Boolean]
+    def handle_mouse_down?(event)
+      unless DRAG_INK.key?(event.button)
+        report("down #{event.button} at #{event.x},#{event.y} — declined, bubbles to the window")
+        return false
+      end
+
+      report("down #{event.button} at #{event.x},#{event.y} — claimed, grab held")
+      @drag_ink = DRAG_INK.fetch(event.button)
+      @drag_outside = false
+      mark(cell_at(event))
+      true
+    end
+
+    # @param event [Tuile::Mouse::DragEvent]
+    # @return [void]
+    def handle_mouse_drag(event)
+      super
+      cell = cell_at(event)
+      if @drag_outside != cell.nil?
+        @drag_outside = cell.nil?
+        report(@drag_outside ? "drag left the canvas — the grab still delivers" : "drag back inside")
+      end
+      mark(cell)
+      report_move(event)
+    end
+
+    # @param event [Tuile::Mouse::UpEvent]
+    # @return [void]
+    def handle_mouse_up(event)
+      super
+      report("up at #{event.x},#{event.y} — grab released")
+      @drag_ink = nil
+    end
+
+    # @param event [Tuile::Mouse::MoveEvent]
+    # @return [Boolean]
+    def handle_mouse_move?(event)
+      cell = cell_at(event)
+      paint(cell, TRAIL) if cell && @ink[cell].nil?
+      report_move(event)
+      true
+    end
+
+    # @return [void]
+    def handle_mouse_enter
+      super
+      report("enter")
+    end
+
+    # @return [void]
+    def handle_mouse_exit
+      super
+      report("exit")
+    end
+
+    # Declines the notch — nothing here scrolls — which is what lets it bubble
+    # on to an ancestor that does.
+    # @param event [Tuile::Mouse::ScrollEvent]
+    # @return [Boolean] always false.
+    def handle_mouse_scroll?(event)
+      report("wheel #{event.direction} — declined, bubbles on")
+      false
+    end
+
+    # @param key [String]
+    # @return [Boolean]
+    def handle_key?(key)
+      case key
+      when Tuile::Keys::UP_ARROW then move_caret(0, -1)
+      when Tuile::Keys::DOWN_ARROW then move_caret(0, 1)
+      when Tuile::Keys::LEFT_ARROW then move_caret(-1, 0)
+      when Tuile::Keys::RIGHT_ARROW then move_caret(1, 0)
+      when " ", "x" then stroke_caret(STROKE)
+      when Tuile::Keys::DELETE, *Tuile::Keys::BACKSPACES then stroke_caret(nil)
+      when "c" then clear_marks
+      else return super
+      end
+      true
+    end
+
+    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`).
+    # @param row [Integer] rect-local row.
+    # @param trail_color [Tuile::Color]
+    # @return [void]
+    def draw_row(row, trail_color)
+      column = 0
+      while column < rect.width
+        glyph = @ink[Tuile::Point.new(column, row)]
+        run = 1
+        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)
+        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.
+    # @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)
+
+      Tuile::Point.new(column, row)
+    end
+
+    # Lays the dragged ink at `cell` and takes the caret with it, so a stroke
+    # can be continued from the keyboard. Outside the rect (`nil`) it is a
+    # no-op, which is a grabbed drag's normal case.
+    # @param cell [Tuile::Point, nil] rect-local.
+    # @return [void]
+    def mark(cell)
+      return if cell.nil?
+
+      paint(cell, @drag_ink)
+      @caret = cell
+    end
+
+    # @param cell [Tuile::Point] rect-local.
+    # @param ink [String, nil] nil lifts the mark.
+    # @return [void]
+    def paint(cell, ink)
+      return if @ink[cell] == ink
+
+      ink.nil? ? @ink.delete(cell) : @ink.store(cell, ink)
+      invalidate
+    end
+
+    # @param ink [String, nil]
+    # @return [void]
+    def stroke_caret(ink)
+      paint(@caret, ink)
+      report("#{ink || "lift"} at #{@caret.x},#{@caret.y} — from the keyboard")
+    end
+
+    # @param columns [Integer]
+    # @param rows [Integer]
+    # @return [void]
+    def move_caret(columns, rows)
+      return if rect.empty?
+
+      @caret = Tuile::Point.new((@caret.x + columns).clamp(0, rect.width - 1),
+                                (@caret.y + rows).clamp(0, rect.height - 1))
+      invalidate # the hardware cursor is placed from #cursor_position at flush
+    end
+
+    # @return [void]
+    def clear_marks
+      return if @ink.empty?
+
+      @ink.clear
+      report("cleared")
+      invalidate
+    end
+
+    # @param line [String]
+    # @return [void]
+    def report(line) = @on_event&.call(line)
+
+    # @param event [Tuile::Mouse::Event]
+    # @return [void]
+    def report_move(event)
+      @moves += 1
+      @on_move&.call(event, @moves)
+    end
+  end
+
   # Top-level sampler component: a shell row across the top — a
   # {Tuile::Component::MenuBar} of the demos, grouped, and a
   # {Tuile::Component::ComboBox} jump box at its right end — over one demo
@@ -141,7 +471,8 @@ module SamplerExample
     def refresh_status
       focused = screen.focused
       name = focused ? focused.class.name.sub("Tuile::Component::", "") : "(none)"
-      @status.text = "q #{screen.theme.hint("quit")}  ⇥ #{screen.theme.hint(name)}"
+      t = screen.theme
+      @status.text = "q #{t.fg(:hint, "quit")}  ⇥ #{t.fg(:hint, name)}"
     end
 
     # Chrome for a demo pane: a blank row top and bottom, two columns either
@@ -177,9 +508,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 five leaves therefore answer to a letter
+    # a duplicate among siblings, and six 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) — the underline shows which. No item may use
+    # Pic`k`erWindow, S`l`ash menu, DateTi`m`eField) — 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.
     MENUS = [
@@ -199,7 +531,12 @@ module SamplerExample
                  Menu.new("Typed", "y", [
                             Entry.new("IntegerField", :build_integer_field, "i"),
                             Entry.new("FloatField", :build_float_field, "f"),
-                            Entry.new("BigDecimalField", :build_big_decimal_field, "b")
+                            Entry.new("BigDecimalField", :build_big_decimal_field, "b"),
+                            Entry.new("DateField", :build_date_field, "d"),
+                            Entry.new("TimeField", :build_time_field, "t"),
+                            Entry.new("DateTimeField", :build_date_time_field, "m"),
+                            Entry.new("Bad input", :build_bad_input, "a"),
+                            Entry.new("Validation", :build_validation, "v")
                           ]),
                  Menu.new("Choose", "c", [
                             Entry.new("Checkbox", :build_checkboxes, "c"),
@@ -211,7 +548,7 @@ module SamplerExample
                           ])
                ]),
       # One entry, so it is the item and not a menu — a top-level leaf on the
-      # strip is a button, which nothing else here demos.
+      # strip is a button rather than a drop-down.
       Entry.new("Button", :build_buttons, "b"),
       Menu.new("Overlay", "o", [
                  Entry.new("Popup", :build_popup_launcher, "p"),
@@ -227,8 +564,12 @@ module SamplerExample
                  Entry.new("Narrow strips", :build_narrow_strips, "n"),
                  Entry.new("Layout", :build_layout, "l"),
                  Entry.new("Background", :build_background, "b"),
+                 Entry.new("Visibility", :build_visibility, "v"),
                  Entry.new("Focus & Tab", :build_focus_demo, "f")
-               ])
+               ]),
+      # The one demo needing a tracking level above the default, which is why
+      # the runner asks for `capture_mouse: :hover` for the whole app.
+      Entry.new("Mouse", :build_mouse_demo, "m")
     ].freeze
 
     # Every {Entry} in strip order — what the jump box offers.
@@ -309,10 +650,13 @@ module SamplerExample
 
     def build_text_field
       prompt = Tuile::Component::Label.new
-      prompt.text = "Tab here, then type. Arrows, Home/End, Backspace, Delete all work."
+      prompt.text = "Tab here, then type. Arrows, Home/End, Backspace, Delete all work.\n" \
+                    "While it is empty it shows a placeholder — a hint in ink faint " \
+                    "enough to miss, which is the point."
       field = Tuile::Component::TextField.new
+      field.placeholder = "dd.mm.yyyy"
       form do |f|
-        f.add(prompt, Fixed[1])
+        f.add(prompt, Fixed[2])
         f.add(field, Fixed[1])
       end
     end
@@ -408,6 +752,8 @@ module SamplerExample
       prompt.text = "Tab here, then type digits (and a leading -). Non-digits are ignored.\n" \
                     "Up/Down step the value by one; an empty field counts as 0."
       field = Tuile::Component::IntegerField.new
+      # 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}" }
       form do |f|
@@ -454,6 +800,218 @@ module SamplerExample
       end
     end
 
+    # DateField: several formats in, one format out. Type a date in any of the
+    # three spellings this pane accepts and Tab away — the field rewrites it in
+    # the *first* one, which is how the user sees that it understood them. Both
+    # halves of the settling rule are visible here too: nothing reddens while a
+    # date is being typed, and a buffer that never parsed reddens on the way
+    # out. The echo row is deliberately driven by `on_value_change` alone, so
+    # garbage leaves it stale: bad_input? is a *pull*, and the button is the "a
+    # form asks once, at the click" gesture that consults it (it also gives Tab
+    # somewhere to go, which is what makes both behaviours visible at all).
+    def build_date_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, then type 4.9.2026 — or 09/04/2026, or 2026-09-04.\n" \
+                    "Tab away or press Enter and a buffer that parses is rewritten as yyyy-mm-dd;\n" \
+                    "one that doesn't is left as you typed it, and *then* the well goes red.\n" \
+                    "Up/Down step a day, and an empty field steps to today."
+      field = Tuile::Component::DateField.new
+      field.formats = ["%Y-%m-%d", "%d.%m.%Y", "%m/%d/%Y"]
+      status = Tuile::Component::Label.new
+      # to_s, not inspect: Date#inspect spells out the Julian day and the
+      # 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 }
+      ask = Tuile::Component::Button.new("Ask again") { report.call }
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(field, Fixed[1], cross: Fixed[20])
+        f.add(status, Fixed[1])
+        f.add(ask, Fixed[1], cross: Fixed[button_width(ask)])
+      end
+    end
+
+    # TimeField: one knob for two things, and the reason it is one. Both fields
+    # below sit under a *Finnish* spelling that this pane installs on the
+    # screen, because the whole point is invisible under ISO: switching
+    # precision must not cost you the locale's separator. So the left field
+    # shows 13.45 and the right 13.45.00 — a dot either way, which a per-field
+    # format override could not have managed.
+    def build_time_field
+      # Assigned here rather than detected, so the pane demonstrates the same
+      # thing on an American box as on a Finnish one.
+      Tuile::Screen.instance.locale = Tuile::Locale::ISO.with(time_formats: ["%H.%M.%S", "%H:%M:%S"])
+      prompt = Tuile::Component::Label.new
+      prompt.text = "The session spells times the Finnish way (13.45). Tab into either field.\n" \
+                    "Up/Down step a minute on the left, a second on the right (PageUp/PageDown an hour in both) —\n" \
+                    "one knob, because precision is a property of the format the buffer holds.\n" \
+                    "Note the dot survives the switch: that is what a per-field format would cost."
+      minutes = time_field_with(step: 60)
+      seconds = time_field_with(step: 1)
+      status = Tuile::Component::Label.new
+      report = lambda do
+        status.text = "minutes: #{minutes.value&.strftime("%H:%M:%S") || "nil"} (#{minutes.formats.first})    " \
+                      "seconds: #{seconds.value&.strftime("%H:%M:%S") || "nil"} (#{seconds.formats.first})"
+      end
+      report.call
+      [minutes, seconds].each { _1.on_value_change = ->(_value) { report.call } }
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(labelled("Minute stride", minutes, field_width: 12), Fixed[1], cross: Fixed[30])
+        f.add(labelled("Second stride", seconds, field_width: 12), Fixed[1], cross: Fixed[30])
+        f.add(status, Fixed[1])
+      end
+    end
+
+    # @param step [Integer]
+    # @return [Tuile::Component::TimeField]
+    def time_field_with(step:)
+      Tuile::Component::TimeField.new.tap do |field|
+        field.step = step
+        field.set_to(13, 45)
+      end
+    end
+
+    # DateTimeField: the ink rule, which neither half can show alone. Leave the
+    # time empty and the *whole* widget reddens — half-filled is a fault no
+    # single half committed — where garbage in the date half reddens that half
+    # by itself. Both only on the way out, which is why pressing Enter first
+    # visibly changes nothing.
+    #
+    # The echo row carries the value and Save the verdict, the division
+    # `D_bad_input` draws: the notice is a push, fired when a half commits;
+    # `bad_input?` is a pull, read at the click. The Saved alert spells the
+    # value out with the `+00:00` the halves cannot fill in — `D_time_field`'s
+    # epoch cost, visible rather than hidden.
+    def build_date_time_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, type 2026-09-14, leave the time empty — then press Enter: nothing reddens.\n" \
+                    "Tab away and both halves redden at once: half-filled is the composite's own fault.\n" \
+                    "Now type 2026-99-99 in the date half instead — it reddens alone, the time half stays clean.\n" \
+                    "Save asks bad_input? at the click and names whichever fault it found."
+      field = Tuile::Component::DateTimeField.new
+      status = Tuile::Component::Label.new
+      # strftime, not inspect: DateTime#inspect spells out the Julian day, noise
+      # 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 }
+      save = Tuile::Component::Button.new("Save") { save_form("Starts at" => field) }
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(labelled("Starts at", field, field_width: 20), Fixed[1], cross: Fixed[36])
+        f.add(status, Fixed[1])
+        f.add(save, Fixed[1], cross: Fixed[button_width(save)])
+      end
+    end
+
+    # HasBadInput: the one fact on_value_change cannot carry. Type a lone "-"
+    # and watch the echo row stay silent — the value was nil before and is nil
+    # after, so there is no diff to report — while Save, which asks bad_input?
+    # instead of empty?, refuses and names the field.
+    def build_bad_input
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Type a lone '-' into Amount (or '1e' into Rate), then press Save.\n" \
+                    "Both read value: nil and empty?: true, exactly like an untouched field —\n" \
+                    "which is why a form must ask bad_input? before it saves a nil over your work."
+      # The one pane that tags its widgets with `id`, so the sampler's own spec
+      # can drive them through Tuile::Testing.get by name.
+      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}" }
+      save = Tuile::Component::Button.new("Save") { save_form("Amount" => amount, "Rate" => rate) }
+      save.id = :save
+      rows = group do |g|
+        g.add(labelled("Amount", amount), Fixed[1])
+        g.add(labelled("Rate", rate), Fixed[1])
+      end
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(rows, Fixed[2])
+        f.add(echo, Fixed[1])
+        f.add(save, Fixed[1], cross: Fixed[button_width(save)])
+      end
+    end
+
+    # The login form of `D_has_validation`: the click writes a verdict onto
+    # each field and the field paints itself red, while *this* pane owns the
+    # cells the messages go in — one Label per field, refilled from
+    # `on_error_message_change`. Note the handler sets *or clears* on every
+    # pass, which is the whole writer discipline; and that no field computes
+    # anything, so nothing here fights the fields' own `bad_input?`.
+    def build_validation
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Press Log in empty, then with a 2-letter username: the message lands in\n" \
+                    "this pane's cells (via a listener) and the field's well turns red.\n" \
+                    "Tab between them — an invalid field still shows which one has focus."
+      username = Tuile::Component::TextField.new
+      password = Tuile::Component::PasswordField.new
+      fields = { "Username" => username, "Password" => password }
+      rows = group do |g|
+        fields.each { |caption, field| g.add(validated_row(caption, field), Fixed[1]) }
+      end
+      login = Tuile::Component::Button.new("Log in") { validate_login(fields) }
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(rows, Fixed[2])
+        f.add(login, Fixed[1], cross: Fixed[button_width(login)])
+      end
+    end
+
+    # @param caption [String]
+    # @param field [Tuile::Component] a field carrying {Tuile::Component::HasValidation}.
+    # @return [Tuile::Component] a row of caption, field, and the error Label
+    #   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 }
+      row do |r|
+        r.add(Tuile::Component::Label.new(caption), Fixed[14])
+        r.add(field, Fixed[22])
+        r.add(error, Expand[1])
+      end
+    end
+
+    # Two rules, so the pane shows both halves: "required" has nothing to tint,
+    # "too short" does.
+    # @param fields [Hash{String => Tuile::Component}] caption => field.
+    def validate_login(fields)
+      fields.each { |caption, field| field.error_message = login_problem(caption, field) }
+      return if fields.each_value.any?(&:error_message)
+
+      Tuile::Component::ConfirmWindow.alert("Logged in", "Welcome, #{fields["Username"].value}.")
+    end
+
+    # @param caption [String]
+    # @param field [Tuile::Component]
+    # @return [String, nil] the verdict, or `nil` — the *clear* half of
+    #   set-or-clear-on-every-pass, without which a fixed field stays red.
+    def login_problem(caption, field)
+      return "#{caption} is required" if field.empty?
+      return "at least 3 characters" if field.value.length < 3
+
+      nil
+    end
+
+    # The Save gate of `D_bad_input`: asked once, at the click, so the
+    # continuously-true fact ("2" is a bad date on the way to "2026") is only
+    # ever read in a settled state.
+    # @param fields [Hash{String => Tuile::Component}] caption => field.
+    def save_form(fields)
+      bad = fields.filter_map do |caption, field|
+        "#{caption}: #{field.bad_input_message}" if field.respond_to?(:bad_input?) && field.bad_input?
+      end
+      if bad.empty?
+        values = fields.map { |caption, field| "#{caption}: #{field.value.inspect}" }
+        Tuile::Component::ConfirmWindow.alert("Saved", values.join("\n"))
+      else
+        Tuile::Component::ConfirmWindow.alert("Cannot save", "#{bad.size} problem(s):\n#{bad.join("\n")}")
+      end
+    end
+
     # @param value [BigDecimal, nil]
     # @return [String] the value tripled exactly, next to the same sum in Float.
     def triple_report(value)
@@ -495,19 +1053,17 @@ 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 an `on_key` interceptor hands
-    # movement keys to `#move` and Enter to `#choose` while it is open. None of
-    # this is baked into TextArea.
+    # `on_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
       prompt.text = "A ListDropdown driven from a TextArea. Type a slash command\n" \
                     "(try \"/\" or \"/s\"). The menu floats over the field without taking\n" \
                     "focus: Down/Up move the selection, Enter accepts, ESC dismisses, and\n" \
                     "ordinary typing keeps editing the field and refilters the menu."
-      area = Tuile::Component::TextArea.new
-
       overlay = Tuile::Component::ListDropdown.new
       @slash_overlay = overlay
+      area = SlashCommandTextArea.new(overlay)
 
       refill = lambda do
         matches = slash_matches(area)
@@ -524,20 +1080,6 @@ module SamplerExample
 
       area.on_change = ->(_text) { refill.call }
       overlay.on_item_chosen = ->(_idx, item) { accept_slash_command(area, item.to_s) }
-      area.on_key = lambda do |key|
-        next false unless overlay.open?
-        next true if overlay.move(key) # Up/Down/PgUp/PgDn/^U/^D
-
-        case key
-        when Tuile::Keys::ENTER
-          overlay.choose
-        when Tuile::Keys::ESC
-          overlay.close
-          true
-        else
-          false
-        end
-      end
 
       form do |f|
         f.add(prompt, Fixed[4])
@@ -668,6 +1210,42 @@ module SamplerExample
       end
     end
 
+    # `visible=` on a conditional form: the fields a checkbox above them
+    # governs. The rows close up completely when they go — a hidden child costs
+    # neither its slot nor the box's `spacing` gap, which is what separates it
+    # from a `Fixed[0]` collapse — and come back with their constraints and
+    # their typed text intact, since nothing was ever detached.
+    def build_visibility
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tick 'Business customer' to reveal two more fields.\n" \
+                    "The rows close up with no double gap, Tab skips what is hidden,\n" \
+                    "and text typed into a field survives being hidden and shown."
+      status = Tuile::Component::Label.new
+      company = labelled("Company", Tuile::Component::TextField.new)
+      vat = labelled("VAT id", Tuile::Component::TextField.new)
+      conditional = [company, vat]
+      business = Tuile::Component::Checkbox.new("Business customer")
+      apply = lambda do
+        conditional.each { _1.visible = business.checked? }
+        status.text = "visible fields: #{business.checked? ? 4 : 2}"
+      end
+      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])
+        g.add(labelled("Email", Tuile::Component::TextField.new), Fixed[1])
+        g.add(company, Fixed[1])
+        g.add(vat, Fixed[1])
+      end
+      apply.call
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(business, Fixed[1])
+        f.add(rows, Fixed[4])
+        f.add(status, Fixed[1])
+      end
+    end
+
     # One filterable log level: the item type a CheckboxGroup holds. Its `value`
     # is a Set of *these*, never of the labels shown on the rows.
     LogLevel = Data.define(:label, :tag, :color)
@@ -705,7 +1283,7 @@ module SamplerExample
     # *items* — LogLevel objects, not their labels — so the filter below is plain
     # set membership, no lookup table. Rows come from `item_label`, which may
     # return styled text (these colors are inherent to the data, not theme
-    # accents, so they need no on_theme_changed hook).
+    # accents, so they need no handle_theme_changed hook).
     def build_checkbox_group
       prompt = Tuile::Component::Label.new
       # Kept under 48 columns a line, so an 80-column terminal shows it whole.
@@ -774,7 +1352,7 @@ module SamplerExample
     SAMPLE_FILES = [
       SampleFile.new("AGENTS.md", 31_402, "2026-07-30"),
       SampleFile.new("CHANGELOG.md", 4118, "2026-07-05"),
-      SampleFile.new("DECISIONS.md", 48_990, "2026-07-31"),
+      SampleFile.new("design/decisions.md", 48_990, "2026-07-31"),
       SampleFile.new("Gemfile", 312, "2026-06-18"),
       SampleFile.new("README.md", 9674, "2026-07-12"),
       SampleFile.new("Rakefile", 2118, "2026-06-18"),
@@ -808,7 +1386,7 @@ module SamplerExample
       short_size = ->(bytes) { bytes < 1024 ? bytes.to_s : "#{(bytes / 1024.0).round}k" }
 
       update_status = lambda do
-        under_cursor = SORT_ORDERS[group.content.cursor.position]
+        under_cursor = SORT_ORDERS[group.list.cursor.position]
         status.text = "value: #{group.value.label} — cursor: #{under_cursor&.label}"
       end
       resort = lambda do
@@ -819,9 +1397,9 @@ module SamplerExample
       end
       resort.call
       group.on_value_change = ->(_order) { resort.call }
-      # `content` is the composed List, which is where the cursor lives.
+      # `list` is the composed List, which is where the cursor lives.
       # Watching it is what makes the chrome/value split visible above.
-      group.content.on_cursor_changed = ->(_idx, _line) { update_status.call }
+      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.
@@ -965,7 +1543,7 @@ module SamplerExample
       # 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 on_theme_changed here.
+      # the hard-coded Colors are fixed by design, so no handle_theme_changed here.
       outer = nil
       derived = terminal_tint_choice
       combo = Tuile::Component::ComboBox.new(items: bg_choices(derived))
@@ -1303,9 +1881,14 @@ module SamplerExample
         "PickerWindow asks the user to pick one option by a single keystroke.",
         "Open PickerWindow"
       ) do
+        # Captions paint in the terminal's own foreground — the picker
+        # recommends no color of its own. Styling one is the app's call, and
+        # per option: a caption may be a String, an ANSI-coded String (what
+        # `theme.fg` hands back) or a StyledString.
         Tuile::Component::PickerWindow.open(
           "Pick a fruit",
-          [%w[a Apple], %w[b Banana], %w[c Cherry]]
+          [%w[a Apple], %w[b Banana],
+           ["c", "Cherry #{screen.theme.fg(:hint, "(in season)")}"]]
         ) { |key| Tuile.logger.info("Picked: #{key}") }
       end
     end
@@ -1338,6 +1921,31 @@ module SamplerExample
       end
     end
 
+    def build_mouse_demo
+      intro = Tuile::Component::Label.new
+      intro.text = "Drag on the canvas to draw X; right-drag erases; just hovering leaves a dim\n" \
+                   "trail. Arrows move the caret, space or x strokes it, Delete lifts it, c clears.\n" \
+                   "Discrete events go to the log; the row below is the live pointer."
+      canvas = Canvas.new
+      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)"
+      end
+      surface = row do |r|
+        r.add(Tuile::Component::Window.new("Canvas").tap { _1.content = canvas }, Percent[55])
+        r.add(log, Expand[1])
+      end
+      form do |f|
+        f.add(intro, Fixed[3])
+        f.add(surface, Expand[1])
+        f.add(pointer, Fixed[1])
+      end
+    end
+
     # --- Helpers -----------------------------------------------------------
 
     def panel(*children, &layout_block)
@@ -1438,13 +2046,19 @@ end
 # component tree without spinning up the real event loop.
 if $PROGRAM_NAME == __FILE__
   screen = Tuile::Screen.new
+  screen.theme_def = SamplerExample::APP_THEME
   sampler = SamplerExample::Sampler.new
   screen.content = sampler
   screen.on_focus_changed = -> { sampler.refresh_status }
   sampler.refresh_status
   sampler.menu_bar.focus
   begin
-    screen.run_event_loop
+    # `:hover` for the whole app, because the level is set once here and is
+    # all-or-nothing: the Mouse demo's trail and enter/exit lines arrive at no
+    # lower one. The upgrade from the default `:clicks` costs the ~84 motion
+    # reports a second (`R_mouse_reporting`) — not select-to-copy, which mode
+    # 1000 had already taken.
+    screen.run_event_loop(capture_mouse: :hover)
   ensure
     screen.close
   end