tuile 0.9.0 → 0.11.0

data/examples/sampler.rb

@@ -15,11 +15,12 @@ require "rainbow"
 require "tuile"
 
 module SamplerExample
-  # Sampler-local container: a {Tuile::Component::Layout::Absolute} that
-  # runs a caller-supplied block on `rect=` to position its children.
-  # Sampler demos sometimes have a 1-row Label sitting in a tall pane,
-  # but the stock layout's auto-clear already handles those gaps for us
-  # — Panel just needs the rect-callback to drive child positioning.
+  # Sampler-local container: a {Tuile::Component::Layout::Absolute} that runs a
+  # caller-supplied block on `rect=` to position its children. Most demos are
+  # plain stacks and use the box layouts instead; this is what's left for the
+  # two that aren't — a sidebar whose width is `min(16, width / 3)`, which is a
+  # cap on a proportion and so outside {Tuile::Component::Layout::Box}'s
+  # Fixed/Percent/Expand vocabulary by design.
   class Panel < Tuile::Component::Layout::Absolute
     def initialize(&layout_block)
       super()
@@ -32,6 +33,52 @@ module SamplerExample
     end
   end
 
+  # A {Tuile::Component::Layout::Vertical} that runs {#on_tick} on every frame
+  # while it is on screen. The ticker is started on attach and cancelled on
+  # detach, so selecting another demo — which detaches this pane — cannot leave
+  # one firing at the old pane forever. Owning a mounted-lifetime resource this
+  # way is the whole point of the attach hooks.
+  class TickingBox < Tuile::Component::Layout::Vertical
+    def initialize(fps, **)
+      super(**)
+      @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
+
+  # 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
+  # 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.
+  class ShortcutBox < Tuile::Component::Layout::Vertical
+    def initialize(shortcut, **)
+      super(**)
+      @shortcut = shortcut
+    end
+
+    # @return [Proc, nil] called with no arguments when the shortcut arrives.
+    attr_writer :on_shortcut
+
+    def handle_key(key)
+      return false unless key == @shortcut
+
+      @on_shortcut&.call
+      true
+    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.
@@ -48,6 +95,10 @@ module SamplerExample
 
     attr_reader :left_window, :right_window, :entry_list
 
+    # Chrome for a demo pane: a blank row top and bottom, two columns either
+    # side, so content doesn't run flush to the window border.
+    FORM_PADDING = Insets[top: 1, bottom: 1, left: 2, right: 2]
+
     def rect=(new_rect)
       super
       return if rect.empty?
@@ -67,10 +118,21 @@ module SamplerExample
       ["Label",        :build_label],
       ["TextField",    :build_text_field],
       ["TextArea",     :build_text_area],
+      ["ComboBox",     :build_combo_box],
+      ["Select",       :build_select],
+      ["IntegerField", :build_integer_field],
+      ["FloatField",   :build_float_field],
+      ["BigDecimalField", :build_big_decimal_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],
@@ -116,10 +178,9 @@ module SamplerExample
       prompt = Tuile::Component::Label.new
       prompt.text = "Tab here, then type. Arrows, Home/End, Backspace, Delete all work."
       field = Tuile::Component::TextField.new
-      panel(prompt, field) do |r|
-        inner = inner_rect(r)
-        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 1)
-        field.rect = Tuile::Rect.new(inner.left, inner.top + 3, inner.width, 1)
+      form do |f|
+        f.add(prompt, Fixed[1])
+        f.add(field, Fixed[1])
       end
     end
 
@@ -133,11 +194,165 @@ module SamplerExample
       area.text = "The quick brown fox jumps over the lazy dog. " \
                   "Edit me — the text wraps to the area's width and scrolls vertically " \
                   "once the cursor leaves the visible rows."
-      panel(prompt, area) do |r|
-        inner = inner_rect(r)
-        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
-        area_height = [inner.height - 6, 4].max
-        area.rect = Tuile::Rect.new(inner.left, inner.top + 5, inner.width, area_height)
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(area, Expand[1])
+      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}" }
+      form do |f|
+        f.add(prompt, Fixed[3])
+        # A cross constraint clamps to the pane, so this is 30 columns or fewer.
+        f.add(combo, Fixed[1], cross: Fixed[30])
+        f.add(status, Fixed[1])
+      end
+    end
+
+    # One line-ending choice: the item type the second Select below holds, so its
+    # `value` is a LineEnding carrying the bytes to write — never a label to look
+    # a separator back up from.
+    LineEnding = Data.define(:label, :bytes)
+
+    LINE_ENDINGS = [
+      LineEnding.new("LF (Unix)", "\n"),
+      LineEnding.new("CRLF (Windows)", "\r\n"),
+      LineEnding.new("CR (classic Mac)", "\r")
+    ].freeze
+
+    # Two Selects, an enum each — developer-authored labels, which is what a
+    # Select is for and a ComboBox isn't. Three things worth watching: the
+    # dropdown is measured to its widest label rather than to the field (so the
+    # line-endings menu is wider than its face), a nil value is a legal blank
+    # face rather than a placeholder, and `r` reaches the *pane* while a Select
+    # has focus — no printable but Space belongs to the widget.
+    def build_select
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab between the two Selects. Enter, Space or ↓ opens;\n" \
+                    "↑↓ move the highlight, Enter or Space commits, ESC cancels.\n" \
+                    "Press r to reset — the pane gets the letter, not the Select."
+
+      level = Tuile::Component::Select.new(items: %w[debug info warn error fatal], value: "warn")
+      endings = Tuile::Component::Select.new(items: LINE_ENDINGS)
+      endings.item_label = :label.to_proc
+
+      status = Tuile::Component::Label.new
+      update = lambda do
+        status.text = "level: #{level.value.inspect}  endings: #{endings.value&.label.inspect}"
+      end
+      update.call
+      [level, endings].each { _1.on_value_change = ->(_v) { update.call } }
+
+      pane = ShortcutBox.new("r", spacing: 1, padding: FORM_PADDING)
+      pane.add(prompt, Fixed[3])
+      pane.add(labelled("Log level", level), Fixed[1])
+      pane.add(labelled("Line endings", endings), Fixed[1])
+      pane.add(status, Fixed[1])
+      pane.on_shortcut = lambda do
+        level.value = "warn"
+        endings.value = nil
+        update.call
+      end
+      pane
+    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}" }
+      form do |f|
+        f.add(prompt, Fixed[2])
+        f.add(field, Fixed[1], cross: Fixed[20])
+        f.add(status, Fixed[1])
+      end
+    end
+
+    # FloatField: the IntegerField one Ruby type over — a single decimal point
+    # is allowed too, and the value is a Float. The status line echoes the
+    # value, which is where the generous parse shows: a buffer of "1." already
+    # reads as 1.0 rather than blinking to nil while you reach for a digit.
+    def build_float_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, then type digits, one '.' and a leading -. Anything else is ignored.\n" \
+                    "Up/Down step the value by one. Watch the value while you type '1.5'."
+      field = Tuile::Component::FloatField.new
+      status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
+      field.on_value_change = ->(value) { status.text = "value: #{value.inspect}" }
+      form do |f|
+        f.add(prompt, Fixed[2])
+        f.add(field, Fixed[1], cross: Fixed[20])
+        f.add(status, Fixed[1])
+      end
+    end
+
+    # BigDecimalField: the same shape again, holding an exact decimal. The
+    # status line multiplies by three both ways, so typing "0.1" shows the
+    # difference the field exists for. Needs the bigdecimal gem — Tuile's one
+    # optional dependency, required by this component and nothing else.
+    def build_big_decimal_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here and type 0.1 — then compare the two products below.\n" \
+                    "This is the field for money: no binary rounding, and nothing pads or trims\n" \
+                    "what you typed (19.90 keeps its zero)."
+      field = Tuile::Component::BigDecimalField.new
+      status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
+      field.on_value_change = ->(value) { status.text = triple_report(value) }
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(field, Fixed[1], cross: Fixed[20])
+        f.add(status, Fixed[2])
+      end
+    end
+
+    # @param value [BigDecimal, nil]
+    # @return [String] the value tripled exactly, next to the same sum in Float.
+    def triple_report(value)
+      return "value: nil" if value.nil?
+
+      "value: #{value.to_s("F")}\n" \
+        "×3 exact: #{(value * 3).to_s("F")}    ×3 as Float: #{value.to_f * 3}"
+    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 } }
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add([user, password], Fixed[1], cross: Fixed[30]) # one constraint, both fields
+        f.add(reveal, Fixed[1])
+        f.add(status, Fixed[1])
       end
     end
 
@@ -191,11 +406,9 @@ module SamplerExample
         end
       end
 
-      panel(prompt, area) do |r|
-        inner = inner_rect(r)
-        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 4)
-        area_height = [inner.height - 7, 4].max
-        area.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, area_height)
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(area, Expand[1])
       end
     end
 
@@ -223,11 +436,9 @@ module SamplerExample
                   "freely."
       window.content = view
       window.scrollbar = true
-      panel(prompt, window) do |r|
-        inner = inner_rect(r)
-        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
-        view_height = [inner.height - 5, 4].max
-        window.rect = Tuile::Rect.new(inner.left, inner.top + 4, inner.width, view_height)
+      form do |f|
+        f.add(prompt, Fixed[2])
+        f.add(window, Expand[1])
       end
     end
 
@@ -246,13 +457,218 @@ module SamplerExample
         counters[:cancel] += 1
         refresh.call
       end
-      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)
-        result.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+      buttons = row do |r|
+        r.add(ok, Fixed[button_width(ok)])
+        r.add(cancel, Fixed[button_width(cancel)])
+      end
+      form do |f|
+        f.add(label, Fixed[2])
+        f.add(buttons, Fixed[1])
+        f.add(result, Fixed[1])
+      end
+    end
+
+    CHECKBOX_OPTIONS = ["Enable syslog forwarding", "Rotate logs daily", "Compress archives",
+                        "Email on failure", "Verbose output"].freeze
+
+    # Checkbox: Space, Enter (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 the rect's.
+    def build_checkboxes
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, then Space or Enter 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 } }
+      # The boxes sit flush against each other while the form keeps a blank row
+      # around the block: a spacing-0 group nested in the spacing-1 form, rather
+      # than a per-child gap the framework deliberately doesn't offer.
+      rows = group { |g| g.add(boxes, Fixed[1]) }
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(rows, Fixed[boxes.size])
+        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)
+
+    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 }
+
+      # The body keeps a rect-callback {Panel}: its sidebar is `min(16, width/3)`
+      # — a cap on a proportion, which Fixed/Percent/Expand can't say. The stack
+      # around it is a box, so only the part that needs arithmetic has any.
+      body = panel(group, log) do |r|
+        group_width = [16, r.width / 3].min
+        group.rect = Tuile::Rect.new(r.left, r.top, group_width, [LOG_LEVELS.size, r.height].min)
+        log.rect = Tuile::Rect.new(r.left + group_width + 2, r.top,
+                                   [r.width - group_width - 2, 4].max, r.height)
+      end
+      form do |f|
+        f.add(prompt, Fixed[4])
+        # Status above the body, so it stays next to the group however tall the
+        # pane gets; the log takes whatever height is left.
+        f.add(status, Fixed[1])
+        f.add(body, Expand[1])
+      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 }
+
+      # Side-by-side body on a rect-callback {Panel}, as in the CheckboxGroup
+      # demo — the sidebar width is a capped proportion, not a constraint.
+      body = panel(group, files) do |r|
+        # List pads a column either side of a row, so a label needs
+        # `width - 2`; the file rows lose one more to their scrollbar.
+        group_width = [14, r.width / 3].min
+        group.rect = Tuile::Rect.new(r.left, r.top, group_width, [SORT_ORDERS.size, r.height].min)
+        files.rect = Tuile::Rect.new(r.left + group_width + 2, r.top,
+                                     [r.width - group_width - 2, 4].max, r.height)
+      end
+      form do |f|
+        f.add(prompt, Fixed[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.
+        f.add(status, Fixed[1])
+        f.add(body, Expand[1])
       end
     end
 
@@ -264,16 +680,134 @@ 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
+
+      # Each bar sits flush against its caption, with a blank row between the two
+      # pairs — two spacing-0 groups inside the spacing-1 stack.
+      determinate = group do |g|
+        g.add(bar, Fixed[1])
+        g.add(status, Fixed[1])
+      end
+      indeterminate = group do |g|
+        g.add(spinner, Fixed[1])
+        g.add(spinner_caption, Fixed[2])
+      end
+      pane = TickingBox.new(PROGRESS_FPS, spacing: 1, padding: FORM_PADDING)
+      pane.add(prompt, Fixed[4])
+      pane.add(determinate, Fixed[2])
+      pane.add(indeterminate, Fixed[3])
+      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 = Tuile::Component::Layout::Vertical.new(spacing: 1)
+      box.add(list, Expand[1])
+      box.add(field, Fixed[1])
+
+      # 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 = form do |f|
+        f.add(intro, Fixed[3])
+        f.add(combo, Fixed[1], cross: Fixed[40])
+        f.add(box, Expand[1])
+      end
+      combo.value = BG_CHOICES.first # show "None" as the resting selection
+      outer
+    end
+
+    # Horizontal splitting a row between two equal Expand shares. Resize the
+    # terminal to watch it recompute: on an odd width the spare column goes to
+    # the left pane, since the remainder is handed to the earliest Expand first.
     def build_layout
       left = Tuile::Component::Window.new("Left")
-      left.content = Tuile::Component::Label.new.tap { _1.text = "Nested left window." }
+      left.content = Tuile::Component::Label.new.tap do
+        _1.text = "Horizontal splits the row\nbetween two Expand[1] panes."
+      end
       right = Tuile::Component::Window.new("Right")
-      right.content = Tuile::Component::Label.new.tap { _1.text = "Nested right window." }
-      panel(left, right) do |r|
-        half = r.width / 2
-        left.rect = Tuile::Rect.new(r.left, r.top, half, r.height)
-        right.rect = Tuile::Rect.new(r.left + half, r.top, r.width - half, r.height)
+      right.content = Tuile::Component::Label.new.tap do
+        _1.text = "No arithmetic here — the\nlayout does it."
       end
+      Tuile::Component::Layout::Horizontal.new.tap { _1.add([left, right], Expand[1]) }
     end
 
     # --- Modal launchers ---------------------------------------------------
@@ -319,11 +853,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
 
@@ -336,13 +868,14 @@ module SamplerExample
       a = Tuile::Component::Button.new("Button A")
       b = Tuile::Component::Button.new("Button B")
       field = Tuile::Component::TextField.new
-      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)
-        field.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+      buttons = row do |r|
+        r.add(a, Fixed[button_width(a)])
+        r.add(b, Fixed[button_width(b)])
+      end
+      form do |f|
+        f.add(label, Fixed[2])
+        f.add(buttons, Fixed[1])
+        f.add(field, Fixed[1])
       end
     end
 
@@ -354,14 +887,46 @@ module SamplerExample
       p
     end
 
+    # The standard demo shell: children stacked with a blank row between them,
+    # inset from the window border. Every constraint below reads unqualified —
+    # `Fixed`, `Expand`, `Insets` all live on {Tuile::Component::Layout}, which
+    # is an ancestor of this class.
+    #
+    #   form do |f|
+    #     f.add(prompt, Fixed[3])
+    #     f.add(field, Fixed[1], cross: Fixed[20])
+    #     f.add(log, Expand[1])          # takes whatever height is left
+    #   end
+    #
+    # @return [Tuile::Component::Layout::Vertical]
+    def form(&) = Tuile::Component::Layout::Vertical.new(spacing: 1, padding: FORM_PADDING).tap(&)
+
+    # A tight sub-stack for rows that belong together, nested inside a {#form} to
+    # suppress its blank row between them — the grouped-gap idiom, and the reason
+    # spacing is a property of the box rather than of each child.
+    # @return [Tuile::Component::Layout::Vertical]
+    def group(&) = Tuile::Component::Layout::Vertical.new.tap(&)
+
+    # Widgets side by side, two columns apart.
+    # @return [Tuile::Component::Layout::Horizontal]
+    def row(&) = Tuile::Component::Layout::Horizontal.new(spacing: 2).tap(&)
+
+    # One form row: a caption in a fixed left column, then the field.
+    # @return [Tuile::Component::Layout::Horizontal]
+    def labelled(caption, field, caption_width: 14, field_width: 22)
+      row do |r|
+        r.add(Tuile::Component::Label.new(caption), Fixed[caption_width])
+        r.add(field, Fixed[field_width])
+      end
+    end
+
     def launcher(description, button_caption, &on_click)
       label = Tuile::Component::Label.new
       label.text = description
       button = Tuile::Component::Button.new(button_caption, &on_click)
-      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)
+      form do |f|
+        f.add(label, Fixed[3])
+        f.add(button, Fixed[1], cross: Fixed[button_width(button)])
       end
     end
 
@@ -410,21 +975,21 @@ module SamplerExample
       overlay.rect = Tuile::Rect.new(left, top, size.width, size.height)
     end
 
-    # 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)
-      pad = 2
-      Tuile::Rect.new(rect.left + pad, rect.top, [rect.width - (pad * 2), 0].max, rect.height)
-    end
+    # A button's natural width — enough to show "[ caption ]".
+    def button_width(button) = button.caption.display_width + 4
   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