tuile 0.13.0 → 0.15.0

data/examples/sampler.rb

@@ -109,6 +109,37 @@ 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
+
   # 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
@@ -134,7 +165,7 @@ module SamplerExample
     attr_reader :demo_window, :menu_bar, :jump_box
 
     # 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
+    # (`D_status_bar`) — this one is the sampler's own, kept current by
     # {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]
@@ -199,7 +230,11 @@ 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("Bad input", :build_bad_input, "a"),
+                            Entry.new("Validation", :build_validation, "v")
                           ]),
                  Menu.new("Choose", "c", [
                             Entry.new("Checkbox", :build_checkboxes, "c"),
@@ -216,6 +251,7 @@ module SamplerExample
       Menu.new("Overlay", "o", [
                  Entry.new("Popup", :build_popup_launcher, "p"),
                  Entry.new("Notification", :build_notification_launcher, "n"),
+                 Entry.new("ConfirmWindow", :build_confirm_launcher, "c"),
                  Entry.new("InfoWindow", :build_info_launcher, "i"),
                  Entry.new("PickerWindow", :build_picker_launcher, "k"),
                  Entry.new("LogWindow", :build_log_window, "l")
@@ -226,6 +262,7 @@ 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")
                ])
     ].freeze
@@ -308,10 +345,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
@@ -407,6 +447,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|
@@ -453,6 +495,185 @@ 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
+
+    # 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)
@@ -491,52 +712,36 @@ module SamplerExample
     # Slash commands the demo offers; the menu filters these by what's typed.
     SLASH_COMMANDS = %w[/help /list /open /save /clear /quit].freeze
 
-    # A non-modal Popup used as an autocomplete menu. Focus (and the caret)
-    # stays in the TextArea the whole time: an `on_change` listener refills the
-    # menu, an `on_key` interceptor forwards Up/Down/Enter/ESC to it while it's
-    # open, and the menu floats above the field, anchored to the caret. None of
-    # this is baked into TextArea — it's all assembled here from stock hooks.
+    # 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
+    # movement keys to `#move` and Enter to `#choose` while it is open.
     def build_slash_demo
       prompt = Tuile::Component::Label.new
-      prompt.text = "Non-modal Popup as an autocomplete menu. Type a slash command\n" \
-                    "(try \"/\" or \"/s\"). The menu floats above the field without taking\n" \
+      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
-
-      list = Tuile::Component::List.new
-      list.cursor = Tuile::Component::List::Cursor.new
-      list.show_cursor_when_inactive = true # highlight the selection though focus stays in the field
-      window = Tuile::Component::Window.new("Commands").tap { _1.content = list }
-      overlay = Tuile::Component::Popup.new(content: window, modal: false)
+      overlay = Tuile::Component::ListDropdown.new
       @slash_overlay = overlay
+      area = SlashCommandTextArea.new(overlay)
 
       refill = lambda do
         matches = slash_matches(area)
         if matches.empty?
           overlay.close if overlay.open?
         else
+          overlay.items = matches
           overlay.open unless overlay.open?
-          list.lines = matches
-          anchor_overlay(overlay, area)
+          # 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))
         end
       end
 
       area.on_change = ->(_text) { refill.call }
-      list.on_item_chosen = ->(_idx, line) { accept_slash_command(area, line.to_s) }
-      area.on_key = lambda do |key|
-        next false unless overlay.open?
-
-        case key
-        when Tuile::Keys::UP_ARROW, Tuile::Keys::DOWN_ARROW, Tuile::Keys::ENTER
-          list.handle_key(key) # works though the list is unfocused — dispatch gates on focus, not the list
-        when Tuile::Keys::ESC
-          overlay.close
-          true
-        else
-          false
-        end
-      end
+      overlay.on_item_chosen = ->(_idx, item) { accept_slash_command(area, item.to_s) }
 
       form do |f|
         f.add(prompt, Fixed[4])
@@ -667,6 +872,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)
@@ -807,7 +1048,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
@@ -818,9 +1059,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.
@@ -928,6 +1169,21 @@ 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" \
@@ -951,7 +1207,8 @@ module SamplerExample
       # 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.
       outer = nil
-      combo = Tuile::Component::ComboBox.new(items: BG_CHOICES)
+      derived = terminal_tint_choice
+      combo = Tuile::Component::ComboBox.new(items: bg_choices(derived))
       combo.item_label = :label.to_proc
       combo.on_value_change = ->(choice) { outer.bg_color = choice.color }
 
@@ -960,6 +1217,17 @@ module SamplerExample
         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
@@ -1166,6 +1434,61 @@ module SamplerExample
       end
     end
 
+    # The three factories, the layer-1 builder (3-way), and a message long
+    # enough to scroll. The status row makes the one-dismissal-channel contract
+    # visible: every route out of a dialog lands in exactly one callback.
+    def build_confirm_launcher
+      label = Tuile::Component::Label.new
+      label.text = "ConfirmWindow asks a question with a row of buttons, in a popup sized to\n" \
+                   "its content (capped at half the screen). Every button closes the dialog;\n" \
+                   "ESC, q or an outside click dismiss it instead. An underlined letter presses\n" \
+                   "its button from anywhere; Up/Down scroll a long message meanwhile."
+      status = Tuile::Component::Label.new("Outcome: none yet")
+      report = ->(outcome) { status.text = "Outcome: #{outcome}" }
+      buttons = [
+        Tuile::Component::Button.new("Confirm") do
+          Tuile::Component::ConfirmWindow.confirm(
+            "Delete Report Q4?", "This cannot be undone.",
+            confirm: "Delete", on_dismiss: -> { report.call("kept the report") }
+          ) { report.call("deleted the report") }
+        end,
+        Tuile::Component::Button.new("Yes/No") do
+          Tuile::Component::ConfirmWindow.yes_no(
+            "Overwrite draft.txt?", "The file already exists.",
+            on_dismiss: -> { report.call("kept draft.txt") }
+          ) { report.call("overwrote draft.txt") }
+        end,
+        Tuile::Component::Button.new("Alert") do
+          Tuile::Component::ConfirmWindow.alert("Export failed", "Contact support@example.com.")
+        end,
+        Tuile::Component::Button.new("3-way") do
+          dialog = Tuile::Component::ConfirmWindow.new("Unsaved changes")
+          dialog.message = "Save your changes before leaving?"
+          dialog.button("Save")    { report.call("saved") }
+          dialog.button("Discard") { report.call("discarded") }
+          dialog.button("Cancel")
+          dialog.on_dismiss = -> { report.call("stayed put") }
+          dialog.open
+        end,
+        Tuile::Component::Button.new("Long") do
+          dialog = Tuile::Component::ConfirmWindow.new("Terms of Service")
+          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.open
+        end
+      ]
+      strip = row do |r|
+        buttons.each { |b| r.add(b, Fixed[button_width(b)]) }
+      end
+      form do |f|
+        f.add(label, Fixed[4])
+        f.add(strip, Fixed[1])
+        f.add(status, Fixed[1])
+      end
+    end
+
     def build_popup_launcher
       launcher(
         "Popup is a modal overlay wrapping any Component.\n" \
@@ -1179,17 +1502,39 @@ module SamplerExample
     end
 
     def build_info_launcher
-      launcher(
-        "InfoWindow is a Window of read-only text lines, openable as a popup.",
-        "Open InfoWindow"
-      ) do
-        Tuile::Component::InfoWindow.open(
-          "Hello",
-          ["InfoWindow displays static text",
-           "inside a popup.",
-           "",
-           "Press ESC or q to close."]
-        )
+      label = Tuile::Component::Label.new
+      label.text = "InfoWindow is a Window with a read-only body: prose (message=) wraps in\n" \
+                   "a TextView, rows (lines=) stay one per row in a List, truncating. The\n" \
+                   "constructor picks the presentation by the body's type."
+      buttons = [
+        Tuile::Component::Button.new("Prose") do
+          Tuile::Component::InfoWindow.open(
+            "About",
+            "InfoWindow renders a String as wrapping prose: this sentence is long " \
+            "enough to wrap to the popup's width, and it scrolls when it outgrows " \
+            "the box. Press ESC or q to close."
+          )
+        end,
+        Tuile::Component::Button.new("Rows") do
+          Tuile::Component::InfoWindow.open(
+            "Files",
+            ["drwxr-xr-x  src/",
+             "drwxr-xr-x  spec/",
+             "-rw-r--r--  README.md   4.1k",
+             "-rw-r--r--  Rakefile     812",
+             "",
+             "Rows never wrap: a long row like this one is truncated at the popup's edge, keeping columns aligned.",
+             "",
+             "Press ESC or q to close."]
+          )
+        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
 
@@ -1207,7 +1552,7 @@ module SamplerExample
 
     def build_log_window
       log = Tuile::Component::LogWindow.new("Log")
-      ["LogWindow is a Window wrapping an auto-scrolling TextView.",
+      ["LogWindow is a Window framing an auto-scrolling LogTextView.",
        "Lines are appended via #log (safe from any thread).",
        "Used with Logger::IO it captures arbitrary log output."].each { |line| log.log(line) }
       log
@@ -1315,18 +1660,13 @@ module SamplerExample
       area.caret = start + command.length + 1
     end
 
-    # Positions the overlay just below the caret, flipping above when there's
-    # no room beneath, and clamps it to the screen.
-    def anchor_overlay(overlay, area)
-      caret = area.cursor_position
-      return if caret.nil?
-
-      screen_size = Tuile::Screen.instance.size
-      size = overlay.rect
-      top = caret.y + 1
-      top = [caret.y - size.height, 0].max if top + size.height > screen_size.height - 1
-      left = caret.x.clamp(0, [screen_size.width - size.width, 0].max)
-      overlay.rect = Tuile::Rect.new(left, top, size.width, size.height)
+    # 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
+    # width policy stays with the driver, exactly as it does for Select.
+    # @return [Integer]
+    def slash_menu_width(matches)
+      widest = matches.map { Tuile::StyledString.plain(_1).display_width }.max || 0
+      [widest + 2, Tuile::Screen.instance.size.width].min
     end
 
     # A button's natural width — enough to show "[ caption ]".

data/ideas/arrow-key-navigation.md

@@ -107,7 +107,7 @@ Recorded here so the open questions below stay narrow.
 - **{Tuile::Component::Tabs} already left the vertical axis free for this.**
   The strip claims Left/Right and *declines* Up/Down specifically so that this
   feature can move focus out of it vertically while Left/Right keep switching
-  tabs inside it (`D-tabs`). It composes for nothing: the strip declines, the
+  tabs inside it (`D_tabs`). It composes for nothing: the strip declines, the
   key bubbles, the navigating ancestor moves. That is also the shape to copy
   for any future one-axis widget — claim one axis, leave the other.
 
@@ -215,7 +215,7 @@ Also: any public signature change means `rake sig` in the same commit.
 
 If built: the user-facing half goes to book ch5 (the key/Enter tables live
 there), the invariants half to AGENTS.md's key-dispatch section, and the
-choice-plus-rejected-roads half to `DECISIONS.md` as `D-arrow-navigation` —
+choice-plus-rejected-roads half to `DECISIONS.md` as `D_arrow_navigation` —
 which must record the `Layout::Form` rejection and the Vaadin FormGroup
 precedent behind it, since that's the reasoning most likely to be
 re-litigated. Then retire this file.