tuile 0.10.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,14 +33,14 @@ 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)
+  # 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
 
@@ -56,6 +57,28 @@ module SamplerExample
     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.
@@ -72,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?
@@ -92,7 +119,10 @@ module SamplerExample
       ["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],
@@ -148,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
 
@@ -165,11 +194,9 @@ 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
 
@@ -184,12 +211,59 @@ module SamplerExample
       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)
+      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
@@ -203,14 +277,59 @@ module SamplerExample
       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)
+      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`,
@@ -229,14 +348,11 @@ module SamplerExample
       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)
+      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
 
@@ -290,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
 
@@ -322,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
 
@@ -345,25 +457,26 @@ 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, 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)
+      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 (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.
+    # 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 to toggle; a left-click on a label toggles too.\n" \
+      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
@@ -374,13 +487,14 @@ module SamplerExample
       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)
+      # 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
 
@@ -452,18 +566,21 @@ module SamplerExample
       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)
+      # 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.
-        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)
+        f.add(status, Fixed[1])
+        f.add(body, Expand[1])
       end
     end
 
@@ -536,20 +653,22 @@ module SamplerExample
       # 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
+      # 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, 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)
+        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
 
@@ -595,15 +714,20 @@ module SamplerExample
       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)
+      # 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
-      pane.add([prompt, bar, status, spinner, spinner_caption])
+      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
@@ -648,11 +772,9 @@ module SamplerExample
       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
+      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
@@ -664,26 +786,28 @@ module SamplerExample
       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)
+      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 ---------------------------------------------------
@@ -744,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, 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)
+      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
 
@@ -762,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_width(button), 1)
+      form do |f|
+        f.add(label, Fixed[3])
+        f.add(button, Fixed[1], cross: Fixed[button_width(button)])
       end
     end
 
@@ -820,13 +977,6 @@ module SamplerExample
 
     # 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)
-      pad = 2
-      Tuile::Rect.new(rect.left + pad, rect.top, [rect.width - (pad * 2), 0].max, rect.height)
-    end
   end
 end