tuile 0.8.0 → 0.10.0

data/examples/sampler.rb

@@ -32,6 +32,30 @@ module SamplerExample
     end
   end
 
+  # A {Panel} 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 one firing at the old pane
+  # forever. Owning a mounted-lifetime resource this way is the whole point of
+  # the attach hooks.
+  class TickingPanel < Panel
+    def initialize(fps, &layout_block)
+      super(&layout_block)
+      @fps = fps
+    end
+
+    # @return [Proc, nil] called with no arguments on each frame.
+    attr_writer :on_tick
+
+    def on_attached
+      @ticker = screen.event_queue.tick_fps(@fps) { @on_tick&.call }
+    end
+
+    def on_detached
+      @ticker&.cancel
+      @ticker = nil
+    end
+  end
+
   # Top-level sampler component. Splits the screen into a left entry list
   # and a right demo pane; each `load_entry` rebuilds the demo from
   # scratch so it always starts in a clean state.
@@ -67,10 +91,18 @@ module SamplerExample
       ["Label",        :build_label],
       ["TextField",    :build_text_field],
       ["TextArea",     :build_text_area],
+      ["ComboBox",     :build_combo_box],
+      ["IntegerField", :build_integer_field],
+      ["PasswordField", :build_password_field],
       ["Slash menu",   :build_slash_demo],
       ["TextView",     :build_text_view],
       ["Button",       :build_buttons],
+      ["Checkbox",     :build_checkboxes],
+      ["CheckboxGroup", :build_checkbox_group],
+      ["RadioGroup",   :build_radio_group],
       ["List",         :build_list],
+      ["ProgressBar",  :build_progress_bar],
+      ["Background",   :build_background],
       ["Layout",       :build_layout],
       ["Popup",        :build_popup_launcher],
       ["InfoWindow",   :build_info_launcher],
@@ -141,6 +173,73 @@ module SamplerExample
       end
     end
 
+    # ComboBox: its value is the selected item, not the typed text — the status
+    # line echoes it as it commits. The dropdown closes itself on blur, so no
+    # overlay bookkeeping is needed here (unlike the slash demo below).
+    def build_combo_box
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, then type to filter. ↑↓ move the highlight, Enter accepts, ESC dismisses.\n" \
+                    "The dropdown floats above or below the field and tints itself apart from the content."
+      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}" }
+      panel(prompt, combo, status) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
+        combo.rect = Tuile::Rect.new(inner.left, inner.top + 5, [inner.width, 30].min, 1)
+        status.rect = Tuile::Rect.new(inner.left, inner.top + 7, inner.width, 1)
+      end
+    end
+
+    # IntegerField: its value is a typed Integer (or nil), parsed from the
+    # digits you type — the status line echoes it. Up/Down step it like a
+    # spinner. Only the value seam shows on its face; the digit filtering and
+    # parsing are internal.
+    def build_integer_field
+      prompt = Tuile::Component::Label.new
+      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
+      status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
+      field.on_value_change = ->(value) { status.text = "value: #{value.inspect}" }
+      panel(prompt, field, status) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
+        field.rect = Tuile::Rect.new(inner.left, inner.top + 4, [inner.width, 20].min, 1)
+        status.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+      end
+    end
+
+    # PasswordField: a TextField that paints a mask instead of its text. The
+    # plaintext stays in `value` throughout — the status line proves it by
+    # reporting the length — and the "Show password" box flips `revealed`,
+    # since a TTY field has no room for an in-field reveal button.
+    def build_password_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab through the two fields and type. The password paints one * per character,\n" \
+                    "whatever you type — try a CJK passphrase: the caret still tracks the mask.\n" \
+                    "Ctrl+Left/Right jump to the ends while masked, so the caret can't give away\n" \
+                    "where the spaces are; they resume word jumping once revealed."
+      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 }
+      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 } }
+      panel(prompt, user, password, reveal, status) do |r|
+        inner = inner_rect(r)
+        width = [inner.width, 30].min
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 4)
+        user.rect = Tuile::Rect.new(inner.left, inner.top + 6, width, 1)
+        password.rect = Tuile::Rect.new(inner.left, inner.top + 8, width, 1)
+        reveal.rect = Tuile::Rect.new(inner.left, inner.top + 10, inner.width, 1)
+        status.rect = Tuile::Rect.new(inner.left, inner.top + 12, inner.width, 1)
+      end
+    end
+
     # Slash commands the demo offers; the menu filters these by what's typed.
     SLASH_COMMANDS = %w[/help /list /open /save /clear /quit].freeze
 
@@ -249,13 +348,211 @@ module SamplerExample
       panel(label, ok, cancel, result) do |r|
         inner = inner_rect(r)
         label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
-        ok.rect = Tuile::Rect.new(inner.left, inner.top + 4, ok.content_size.width, 1)
-        cancel.rect = Tuile::Rect.new(inner.left + ok.content_size.width + 2, inner.top + 4,
-                                      cancel.content_size.width, 1)
+        ok.rect = Tuile::Rect.new(inner.left, inner.top + 4, button_width(ok), 1)
+        cancel.rect = Tuile::Rect.new(inner.left + button_width(ok) + 2, inner.top + 4,
+                                      button_width(cancel), 1)
         result.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
       end
     end
 
+    CHECKBOX_OPTIONS = ["Enable syslog forwarding", "Rotate logs daily", "Compress archives",
+                        "Email on failure", "Verbose output"].freeze
+
+    # Checkbox: Space (or a click on the label) toggles. Each box is handed the
+    # full column width, which is what makes the extent visible — the highlight
+    # and the click target stop at the end of the caption, not at the rect's.
+    def build_checkboxes
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, then Space to toggle; a left-click on a label toggles too.\n" \
+                    "Each box spans the whole column, but only the caption highlights —\n" \
+                    "clicking the empty space to its right just moves focus."
+      status = Tuile::Component::Label.new
+      boxes = CHECKBOX_OPTIONS.map { Tuile::Component::Checkbox.new(_1) }
+      refresh = lambda do
+        on = boxes.select(&:checked?).map { _1.caption.to_s }
+        status.text = "checked: #{on.empty? ? "(none)" : on.join(", ")}"
+      end
+      refresh.call
+      boxes.each { _1.on_value_change = ->(_) { refresh.call } }
+      panel(prompt, *boxes, status) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
+        boxes.each_with_index do |box, i|
+          box.rect = Tuile::Rect.new(inner.left, inner.top + 5 + i, inner.width, 1)
+        end
+        status.rect = Tuile::Rect.new(inner.left, inner.top + 6 + boxes.size, inner.width, 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)
+
+    LOG_LEVELS = [
+      LogLevel.new("Debug", "DEBUG", :cyan),
+      LogLevel.new("Info", "INFO", :green),
+      LogLevel.new("Warnings", "WARN", :yellow),
+      LogLevel.new("Errors", "ERROR", :red)
+    ].freeze
+
+    # `[tag, message]` pairs; the tag names the LogLevel that owns the line.
+    SAMPLE_LOG = [
+      ["DEBUG", "config loaded from /etc/tuile.conf"],
+      ["INFO", "listening on 0.0.0.0:8080"],
+      ["DEBUG", "cache warm: 128 entries"],
+      ["WARN", "TLS certificate expires in 6 days"],
+      ["INFO", "GET /health 200 (1.2ms)"],
+      ["DEBUG", "pool checkout: 3/16 busy"],
+      ["ERROR", "upstream timeout after 5000ms"],
+      ["INFO", "GET /index 200 (18ms)"],
+      ["WARN", "slow query: 1.8s SELECT * FROM tiles"],
+      ["DEBUG", "gc pause 4ms"],
+      ["ERROR", "connection reset by peer (retrying)"],
+      ["INFO", "POST /tiles 201 (32ms)"],
+      ["DEBUG", "pool checkout: 11/16 busy"],
+      ["WARN", "queue depth 240, above the 200 mark"],
+      ["INFO", "GET /tiles/42 200 (7ms)"],
+      ["ERROR", "failed to write /var/log/tuile.log: no space left"],
+      ["DEBUG", "flush wrote 96 cells"],
+      ["INFO", "shutdown signal received"]
+    ].freeze
+
+    # CheckboxGroup filtering an adjacent log. Its value is a Set of the selected
+    # *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).
+    def build_checkbox_group
+      prompt = Tuile::Component::Label.new
+      # Kept under 48 columns a line, so an 80-column terminal shows it whole.
+      prompt.text = "Tab here. ↑↓ moves the cursor, Space toggles.\n" \
+                    "Enter or a click anywhere on a row toggles too —\n" \
+                    "in a list, the whole row is the target.\n" \
+                    "The log redraws from the value on every toggle."
+      levels_by_tag = LOG_LEVELS.to_h { [_1.tag, _1] }
+      entries = SAMPLE_LOG.map { |tag, message| [levels_by_tag.fetch(tag), message] }
+
+      group = Tuile::Component::CheckboxGroup.new(items: LOG_LEVELS, value: LOG_LEVELS.last(2))
+      group.item_label = ->(level) { Rainbow(level.label).color(level.color) }
+
+      log = Tuile::Component::List.new
+      log.cursor = Tuile::Component::List::Cursor.new
+      log.scrollbar_visibility = :visible
+      status = Tuile::Component::Label.new
+
+      refresh = lambda do
+        selected = group.value
+        log.lines = entries.select { |level, _| selected.include?(level) }
+                           .map { |level, message| "#{Rainbow(level.tag.ljust(5)).color(level.color)} #{message}" }
+        # The Set iterates in *toggle* order, so intersect with items to report
+        # it in the order the rows are shown — the documented idiom.
+        shown = (LOG_LEVELS & selected.to_a).map(&:label)
+        status.text = "value: {#{shown.join(", ")}} — #{log.lines.size} of #{entries.size} lines"
+      end
+      refresh.call
+      group.on_value_change = ->(_set) { refresh.call }
+
+      panel(prompt, group, log, status) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 4)
+        # Status above the body, so it stays next to the group however tall the
+        # pane gets; the log takes whatever height is left.
+        status.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+        top = inner.top + 8
+        body_height = [inner.height - 9, LOG_LEVELS.size].max
+        group_width = [16, inner.width / 3].min
+        group.rect = Tuile::Rect.new(inner.left, top, group_width, LOG_LEVELS.size)
+        log.rect = Tuile::Rect.new(inner.left + group_width + 2, top,
+                                   [inner.width - group_width - 2, 4].max, body_height)
+      end
+    end
+
+    # One sort order: the item type a RadioGroup holds. Its `value` is one of
+    # *these*, and the chosen object carries the behavior — so re-sorting is
+    # `value.sorter.call(files)`, never a lookup from a label back to a
+    # comparator.
+    SortOrder = Data.define(:label, :sorter)
+
+    SORT_ORDERS = [
+      SortOrder.new("Name A-Z", ->(files) { files.sort_by(&:name) }),
+      SortOrder.new("Name Z-A", ->(files) { files.sort_by(&:name).reverse }),
+      SortOrder.new("Biggest", ->(files) { files.sort_by { -_1.size } }),
+      SortOrder.new("Newest", ->(files) { files.sort_by(&:date).reverse })
+    ].freeze
+
+    SampleFile = Data.define(:name, :size, :date)
+
+    # Names stay under 14 columns and sizes round to distinct k values, so the
+    # rows fit the pane at 80 columns and every sort order reorders visibly.
+    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("Gemfile", 312, "2026-06-18"),
+      SampleFile.new("README.md", 9674, "2026-07-12"),
+      SampleFile.new("Rakefile", 2118, "2026-06-18"),
+      SampleFile.new("list.rb", 21_006, "2026-07-24"),
+      SampleFile.new("sampler.rb", 22_180, "2026-07-31"),
+      SampleFile.new("screen.rb", 18_442, "2026-07-28"),
+      SampleFile.new("text_view.rb", 14_338, "2026-07-19"),
+      SampleFile.new("theme.rb", 6512, "2026-07-23"),
+      SampleFile.new("tuile.gemspec", 1284, "2026-06-20")
+    ].freeze
+
+    # RadioGroup driving an adjacent file list. Two things worth watching: the
+    # value is the selected *item* (a SortOrder carrying its own comparator),
+    # and the cursor is chrome — arrows move it without touching the value, so
+    # the status line's two halves drift apart until you press Space.
+    def build_radio_group
+      prompt = Tuile::Component::Label.new
+      # Kept under 48 columns a line, so an 80-column terminal shows it whole.
+      prompt.text = "Tab here. ↑↓ move the cursor only.\n" \
+                    "Space, Enter or a click selects — and only\n" \
+                    "then does the list re-sort. Picking another\n" \
+                    "clears the previous; there is no deselect."
+
+      group = Tuile::Component::RadioGroup.new(items: SORT_ORDERS, value: SORT_ORDERS.first)
+      group.item_label = :label.to_proc
+
+      files = Tuile::Component::List.new
+      files.cursor = Tuile::Component::List::Cursor.new
+      files.scrollbar_visibility = :visible
+      status = Tuile::Component::Label.new
+      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]
+        status.text = "value: #{group.value.label} — cursor: #{under_cursor&.label}"
+      end
+      resort = lambda do
+        files.lines = group.value.sorter.call(SAMPLE_FILES).map do |file|
+          "#{file.name.ljust(13)} #{short_size.call(file.size).rjust(4)} #{file.date}"
+        end
+        update_status.call
+      end
+      resort.call
+      group.on_value_change = ->(_order) { resort.call }
+      # `content` 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 }
+
+      panel(prompt, group, files, status) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 4)
+        # Status above the body, so it stays next to the group however tall the
+        # pane gets; the file list takes whatever height is left.
+        status.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+        top = inner.top + 8
+        body_height = [inner.height - 9, SORT_ORDERS.size].max
+        # 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, inner.width / 3].min
+        group.rect = Tuile::Rect.new(inner.left, top, group_width, SORT_ORDERS.size)
+        files.rect = Tuile::Rect.new(inner.left + group_width + 2, top,
+                                     [inner.width - group_width - 2, 4].max, body_height)
+      end
+    end
+
     def build_list
       list = Tuile::Component::List.new
       list.cursor = Tuile::Component::List::Cursor.new
@@ -264,6 +561,119 @@ module SamplerExample
       list
     end
 
+    # Files the fake job in the ProgressBar demo pretends to process.
+    PROGRESS_TOTAL = 50
+
+    # Frames per second of the demo's fake job — its own pace, unrelated to
+    # {Tuile::Component::ProgressBar::INDETERMINATE_FPS}, which paces only the
+    # animation the bar runs for itself.
+    PROGRESS_FPS = 8
+
+    # Two bars: a determinate one whose value a pane-owned ticker walks up and
+    # wraps around, and an indeterminate one that animates itself. Neither
+    # paints text — the lines beneath them are sibling Labels fed from
+    # {Tuile::Component::ProgressBar#percent}, which is what lets the app word
+    # the progress ("42% — 21/50 files") instead of taking whatever the widget
+    # would have formatted.
+    def build_progress_bar
+      prompt = Tuile::Component::Label.new
+      prompt.text = "A ProgressBar paints no text of its own —\n" \
+                    "the line below it is a sibling Label fed\n" \
+                    "from bar.percent. A ticker owned by this\n" \
+                    "pane advances the value while it's on screen."
+
+      bar = Tuile::Component::ProgressBar.new(range: 0..PROGRESS_TOTAL)
+      bar.bar_color = Tuile::Color::GREEN
+      status = Tuile::Component::Label.new
+
+      spinner = Tuile::Component::ProgressBar.new(indeterminate: true)
+      spinner_caption = Tuile::Component::Label.new
+      spinner_caption.text = "Indeterminate: no total yet, so the bar owns\n" \
+                             "its own animation — no ticker in the app."
+
+      done = 0
+      refresh = -> { status.text = "#{bar.percent}% — #{done}/#{PROGRESS_TOTAL} files" }
+      refresh.call
+
+      pane = TickingPanel.new(PROGRESS_FPS) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 4)
+        bar.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+        status.rect = Tuile::Rect.new(inner.left, inner.top + 7, inner.width, 1)
+        spinner.rect = Tuile::Rect.new(inner.left, inner.top + 9, inner.width, 1)
+        spinner_caption.rect = Tuile::Rect.new(inner.left, inner.top + 10, inner.width, 2)
+      end
+      pane.add([prompt, bar, status, spinner, spinner_caption])
+      pane.on_tick = lambda do
+        done = done < PROGRESS_TOTAL ? done + 1 : 0
+        bar.value = done
+        refresh.call
+      end
+      pane
+    end
+
+    # One background the Background demo offers: a display label and the value
+    # handed to {Component#bg_color=} — a live {Tuile::Theme::Ref}, a hard-coded
+    # {Tuile::Color}, or nil (terminal default).
+    BgChoice = Data.define(:label, :color)
+
+    # The palette the Background combo filters over: theme refs first (they
+    # re-resolve on a light/dark flip, so they track the scheme), then a spread
+    # of hard-coded ANSI / 256-palette / RGB colors that stay put across flips.
+    BG_CHOICES = [
+      BgChoice.new("None (terminal default)", nil),
+      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)),
+      BgChoice.new("ANSI blue", Tuile::Color::BLUE),
+      BgChoice.new("ANSI magenta", Tuile::Color::MAGENTA),
+      BgChoice.new("ANSI bright black", Tuile::Color::BRIGHT_BLACK),
+      BgChoice.new("Palette 236 (charcoal)", Tuile::Color.palette(236)),
+      BgChoice.new("Palette 22 (deep green)", Tuile::Color.palette(22)),
+      BgChoice.new("Deep purple (RGB)", Tuile::Color.rgb(48, 25, 82)),
+      BgChoice.new("Midnight teal (RGB)", Tuile::Color.rgb(10, 40, 45)),
+      BgChoice.new("Hot pink (RGB)", Tuile::Color.rgb(120, 20, 70))
+    ].freeze
+
+    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" \
+                   "Pick one below — this label and the list inherit it; input widgets keep their own well.\n" \
+                   "Theme refs track light/dark flips; hard-coded colors stay put."
+
+      list = Tuile::Component::List.new
+      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"
+
+      # A borderless sub-box holding the list + field; it inherits the tint too.
+      box = panel(list, field) do |r|
+        list_h = [r.height - 2, 1].max
+        list.rect = Tuile::Rect.new(r.left, r.top, r.width, list_h)
+        field.rect = Tuile::Rect.new(r.left, r.top + list_h + 1, r.width, 1)
+      end
+
+      # 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 on_theme_changed here.
+      outer = nil
+      combo = Tuile::Component::ComboBox.new(items: BG_CHOICES)
+      combo.item_label = :label.to_proc
+      combo.on_value_change = ->(choice) { outer.bg_color = choice.color }
+
+      outer = panel(intro, combo, box) do |r|
+        inner = inner_rect(r)
+        intro.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
+        combo.rect = Tuile::Rect.new(inner.left, inner.top + 5, [inner.width, 40].min, 1)
+        box.rect = Tuile::Rect.new(inner.left, inner.top + 7, inner.width, [inner.height - 8, 2].max)
+      end
+      combo.value = BG_CHOICES.first # show "None" as the resting selection
+      outer
+    end
+
     def build_layout
       left = Tuile::Component::Window.new("Left")
       left.content = Tuile::Component::Label.new.tap { _1.text = "Nested left window." }
@@ -319,11 +729,9 @@ module SamplerExample
 
     def build_log_window
       log = Tuile::Component::LogWindow.new("Log")
-      log.content.add_lines([
-                              "LogWindow is a Window wrapping an auto-scrolling List.",
-                              "Lines are appended via #add_line / #add_lines.",
-                              "Used with Logger::IO it captures arbitrary log output."
-                            ])
+      ["LogWindow is a Window wrapping an auto-scrolling TextView.",
+       "Lines are appended via #log (safe from any thread).",
+       "Used with Logger::IO it captures arbitrary log output."].each { |line| log.log(line) }
       log
     end
 
@@ -339,9 +747,9 @@ module SamplerExample
       panel(label, a, b, field) do |r|
         inner = inner_rect(r)
         label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
-        a.rect = Tuile::Rect.new(inner.left, inner.top + 4, a.content_size.width, 1)
-        b.rect = Tuile::Rect.new(inner.left + a.content_size.width + 2, inner.top + 4,
-                                 b.content_size.width, 1)
+        a.rect = Tuile::Rect.new(inner.left, inner.top + 4, button_width(a), 1)
+        b.rect = Tuile::Rect.new(inner.left + button_width(a) + 2, inner.top + 4,
+                                 button_width(b), 1)
         field.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
       end
     end
@@ -361,7 +769,7 @@ module SamplerExample
       panel(label, button) do |r|
         inner = inner_rect(r)
         label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
-        button.rect = Tuile::Rect.new(inner.left, inner.top + 5, button.content_size.width, 1)
+        button.rect = Tuile::Rect.new(inner.left, inner.top + 5, button_width(button), 1)
       end
     end
 
@@ -410,6 +818,9 @@ module SamplerExample
       overlay.rect = Tuile::Rect.new(left, top, size.width, size.height)
     end
 
+    # A button's natural width — enough to show "[ caption ]".
+    def button_width(button) = button.caption.display_width + 4
+
     # Carves a 2-column padding out of the panel rect so the demo content
     # doesn't run flush to the window border.
     def inner_rect(rect)
@@ -419,12 +830,16 @@ module SamplerExample
   end
 end
 
-screen = Tuile::Screen.new
-sampler = SamplerExample::Sampler.new
-screen.content = sampler
-sampler.entry_list.focus
-begin
-  screen.run_event_loop
-ensure
-  screen.close
+# Guard the runner so specs can `require` this file to unit-test the Sampler
+# component tree without spinning up the real event loop.
+if $PROGRAM_NAME == __FILE__
+  screen = Tuile::Screen.new
+  sampler = SamplerExample::Sampler.new
+  screen.content = sampler
+  sampler.entry_list.focus
+  begin
+    screen.run_event_loop
+  ensure
+    screen.close
+  end
 end

data/ideas/new-components.md

@@ -0,0 +1,109 @@
+# Components Vaadin has and Tuile doesn't — the survey
+
+**Status:** survey done 2026-07-25 against Vaadin **25.2** (54 free/OSS
+components, via the Vaadin docs MCP). This file is the roadmap; each
+component we actually decide to build gets its own `ideas/<name>.md`.
+Retire this file once the interesting part of the list is either built or
+explicitly rejected — the tiering below is the only nugget worth keeping,
+and it belongs here, not in a durable doc, because it goes stale as we
+build.
+
+Batch 1 ("field components only") is **done** — every idea filed under it has
+graduated: `checkbox` (`DECISIONS.md` `D-boolean-fields`) and `checkbox-group`
+(`D-checkbox-group`), both built 2026-07-30; `radio-group` (`D-radio-group`),
+built 2026-07-31; `progress-bar` (`D-color-slots`, book ch7 "Reporting
+progress") and `password-field` (`D-integer-field`'s taxonomy, book ch7
+"Editing text"), both built 2026-08-02.
+
+## What Tuile already has
+
+Seven of the 54 have a counterpart: Button, Text Field, Text Area,
+Integer Field, Combo Box (1:1), Dialog ({Tuile::Component::Popup} plus
+`Window`/`InfoWindow`/`PickerWindow`), Themable Mixin
+({Tuile::Theme}/{Tuile::ThemeDef}). **List Box** is half-there:
+{Tuile::Component::List} is line-based, with no typed items and no
+multi-select.
+
+Tuile also has pieces Vaadin doesn't name as components — `ListDropdown`,
+`TextView`, `LogWindow`, `VerticalScrollBar` — so the gap is not
+symmetric.
+
+That leaves ~46 gaps.
+
+## Tier 1 — reachable from what exists (S–M each)
+
+| Component | Builds on | Note |
+|---|---|---|
+| Box layouts (H/V) | `Layout` | Tuile has only `Layout::Absolute`. Biggest structural win; unblocks half of this table |
+| ~~Checkbox~~ | `HasValue` | **built** 2026-07-30 (`D-boolean-fields`); tri-state still deferred |
+| ~~Radio Group~~ | `List` + `HasValue` | **built** 2026-07-31 (`D-radio-group`); composes a `List`, cursor roams and Space selects |
+| ~~Checkbox Group~~ | `List` + `HasValue` | **built** 2026-07-30 (`D-checkbox-group`); composes a `List`, frozen `Set` value |
+| Select | `ComboBox` − filter | ComboBox with a read-only field; near-free. Deferred once already in `D-combobox` (wants the parked read-only axis) |
+| Password Field | `TextField` | masked repaint only |
+| Number Field | `IntegerField` twin | same composed-field shape, `Float` |
+| Progress Bar | `draw_line` + `EventQueue#tick_fps` | ticker for the indeterminate mode |
+| Notification | `Popup` + `Ticker` | needs corner-anchored (non-centered) popup placement |
+| Confirm Dialog | `Popup`+`Window`+`Button` | fold `PickerWindow` in |
+| Details → Accordion | `HasContent` | Details is the atom, Accordion the group |
+| Tabs → Tabsheet | `HasValue` (index) + `HasContent` | strip, then strip + content swap |
+| Popover | extract `ComboBox#anchor` + `ListDropdown` geometry | generalize the anchored non-modal overlay; gates the next two |
+| Menu Bar | `ListDropdown::Menu` + Popover | |
+| Context Menu | same | `:right` button already parses |
+| Slider | `draw_line` | arrows/PgUp; 25.2 also has a two-thumb *range* variant |
+| Breadcrumbs | `Label`/`StyledString` | clickable path segments |
+| Markdown | `TextView` + `StyledString` | Markdown subset → styled text; high value on a TTY |
+
+## Tier 2 — worth doing, each blocked on a new seam
+
+| Component | Blocked on |
+|---|---|
+| **Grid** (the flagship gap) | column model + renderer strategies + typed items + horizontal scroll (L) |
+| Form Layout | a field label/helper seam (Vaadin's `HasLabel`) — Tuile fields carry no caption |
+| Email Field | a validation seam (`HasValidation`: invalid state + error line) |
+| Date / Time / DateTime Picker | calendar-grid popup over Popover (L) |
+| Multi Select Combo Box | Checkbox Group + ComboBox |
+| Split Layout → Master Detail Layout | mouse **motion/drag**: Tuile runs X10 mode 1000 (press only, no release, no motion) |
+| Virtual List | a lazy data-provider strategy on `List` |
+| Side Nav | hierarchical collapsible list (the sampler's nav is the prototype) |
+| App Layout | shell: title bar + drawer + content slot |
+| Custom Field | formalize the composed typed-field pattern — or *reject* it as a shared base (COP: inherit to *be*, not to share); `D-integer-field` already sketches the taxonomy |
+| Message Input / Message List / Login | nothing — pure assemblies, good example fodder |
+| Upload | reinterpret as a file-chooser dialog (`file_commander` has the ingredients) |
+| Icon | a glyph / Nerd-Font constants module |
+
+## Tier 3 — design tension or marginal
+
+- **Scroller** — scrolling *arbitrary* content needs clipping/viewport
+  machinery and pushes against the top-down layout invariant (it wants to
+  measure content). Best kept as a documented road-not-taken.
+- **Tooltip** — competes with Tuile's status-bar `keyboard_hint` idiom.
+- **Card** — overlaps `Window` almost entirely.
+- **Avatar / Avatar Group** — initials in a box; little value on a TTY.
+- **Not applicable:** Field Highlighter (collaboration), Themable Mixin
+  (covered by `Theme`).
+
+## Infrastructure that gates clusters
+
+These are prerequisites, not components, and each deserves its own idea
+file when its cluster comes up:
+
+1. **Box layouts** (H/V) — everything form-shaped wants them.
+2. **Field label + helper text seam** → Form Layout.
+3. **Validation seam** → Email Field, forms generally.
+4. **Anchored Popover extraction** → Menu Bar, Context Menu, pickers,
+   Tooltip.
+5. **Mouse motion/drag** (modes 1002/1006, release events) → Split
+   divider, Slider drag, scrollbar drag.
+6. **Typed items + data provider on `List`** → List Box, Grid, Virtual
+   List.
+
+Vaadin's `Binder` is the natural companion for the forms cluster but is
+not a component; `D-has-value` already parks the forms-layer questions
+(converters, read-only, required indicator).
+
+## ~~Cross-cutting open question: component color slots vs. theme tokens~~
+
+**Settled 2026-08-01 as `DECISIONS.md` `D-color-slots`** — the slot, defaulting
+to `nil`. Slider and Badge are bound by it when they land; Badge's promotion
+trigger (a *second* built-in needing the same semantic color) is written up
+there, so neither has to re-argue it.