tuile 0.12.0 → 0.14.0

data/examples/sampler.rb

@@ -1,15 +1,17 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Tuile sampler. Two-pane demo app showcasing the components shipped with
-# the framework. The left pane is a navigation list; moving the cursor
-# loads the highlighted demo into the right pane. Tab / Shift+Tab move
-# focus between the list and the demo's widgets.
+# Tuile sampler. Demo app showcasing the components shipped with the framework.
+# A menu bar across the top groups the demos the way the README's Components
+# table does; the combo box at its right end jumps to one by name. Either way
+# the demo loads into the window below, and focus returns to the menu bar.
 #
 # Run from the gem root:
 #   bundle exec ruby -Ilib examples/sampler.rb
 #
-# Keys (global): q or ESC to quit.
+# Keys: ←→ along the strip, Enter/↓ to open a menu, or a letter for the
+# underlined mnemonic. Tab / Shift+Tab move focus between the strip, the jump
+# box and the demo's widgets. q or ESC quits.
 
 require "rainbow"
 require "tuile"
@@ -79,86 +81,216 @@ module SamplerExample
     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.
-  class Sampler < Tuile::Component::Layout::Absolute
+  # A {Tuile::Component::TextArea} that rebinds ENTER to "submit and clear" —
+  # the chat-prompt shape, and the one that made a multi-line paste fire the
+  # submit once per pasted line before Tuile drove bracketed paste. It handles
+  # no paste of its own: pasted text never arrives as ENTER, so the inherited
+  # insert-at-caret is already the wanted behavior, and `on_paste` here only
+  # feeds the demo's counter.
+  class PromptTextArea < Tuile::Component::TextArea
+    # @return [Proc, nil] called with the submitted text; the area then clears.
+    attr_accessor :on_submit
+    # @return [Proc, nil] called with the pasted text, before it is inserted.
+    attr_accessor :on_paste
+
+    def handle_paste(text)
+      @on_paste&.call(text)
+      super
+    end
+
+    protected
+
+    def handle_text_input_key(key)
+      return super unless key == Tuile::Keys::ENTER
+
+      @on_submit&.call(text)
+      self.text = ""
+      true
+    end
+  end
+
+  # Top-level sampler component: a shell row across the top — a
+  # {Tuile::Component::MenuBar} of the demos, grouped, and a
+  # {Tuile::Component::ComboBox} jump box at its right end — over one demo
+  # window filling the rest. Each load rebuilds the demo from scratch, so it
+  # always starts in a clean state.
+  #
+  # The two navigators are two *inputs to one selection*, not two selections:
+  # the menu answers "what is there?", the jump box answers "take me to X", and
+  # both write to the same place. See {#select_entry}.
+  class Sampler < Tuile::Component::Layout::Vertical
     def initialize
       super()
-      @entry_list = build_entry_list
-      @left_window = Tuile::Component::Window.new("Components").tap { _1.content = @entry_list }
-      @right_window = Tuile::Component::Window.new
-      add(@left_window)
-      add(@right_window)
-      load_entry(0)
+      @menu_bar = build_shell_bar
+      @jump_box = build_jump_box
+      @demo_window = Tuile::Component::Window.new
+      @status = Tuile::Component::Label.new
+      add(shell_row, Fixed[1])
+      add(@demo_window, Expand[1])
+      add(@status, Fixed[1])
+      select_entry(ENTRIES.first)
     end
 
-    attr_reader :left_window, :right_window, :entry_list
+    attr_reader :demo_window, :menu_bar, :jump_box
+
+    # The bottom row. Tuile draws no status bar and reserves no row
+    # (`D_status_bar`) — this one is the sampler's own, kept current by
+    # {Tuile::Screen#on_focus_changed=}. Naming the focused component makes Tab
+    # traversal visible as you walk a pane, which no per-pane label shows.
+    # @return [void]
+    def refresh_status
+      focused = screen.focused
+      name = focused ? focused.class.name.sub("Tuile::Component::", "") : "(none)"
+      @status.text = "q #{screen.theme.hint("quit")}  ⇥ #{screen.theme.hint(name)}"
+    end
 
     # 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?
-
-      list_width = (rect.width / 3).clamp(20, 40)
-      @left_window.rect = Tuile::Rect.new(rect.left, rect.top, list_width, rect.height)
-      @right_window.rect = Tuile::Rect.new(rect.left + list_width, rect.top,
-                                           rect.width - list_width, rect.height)
-    end
+    # Shows `entry`'s demo. **The jump box is the selection model** — every
+    # navigator writes to it and its `on_value_change` is the only caller of
+    # `load_entry` — so the round trip needs no re-entrancy guard:
+    # {Tuile::Component::HasValue#value=} returns early on an equal value, and
+    # re-picking the entry already shown is a silent no-op.
+    # @param entry [Entry]
+    # @return [void]
+    def select_entry(entry) = (@jump_box.value = entry)
 
     private
 
-    # Ordered list of demo entries: `[caption, builder_method]`. The
-    # builder runs at selection time, so every load gets a fresh component
-    # tree (an empty TextField, an un-clicked Button, etc.).
-    ENTRIES = [
-      ["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],
-      ["Notification", :build_notification_launcher],
-      ["Popup",        :build_popup_launcher],
-      ["InfoWindow",   :build_info_launcher],
-      ["PickerWindow", :build_picker_launcher],
-      ["LogWindow",    :build_log_window],
-      ["Focus & Tab",  :build_focus_demo]
+    # One demo: the caption shown everywhere, the builder that mints its pane,
+    # and the letter that reaches it from its own menu level. The builder runs
+    # at selection time, so every load gets a fresh component tree (an empty
+    # TextField, an un-clicked Button, etc.).
+    #
+    # A value type, because the jump box holds entries as its items and
+    # {Tuile::Component::HasValue#value=} compares them — see {#select_entry}.
+    Entry = Data.define(:caption, :builder, :mnemonic)
+
+    # A menu on the strip, or a submenu inside one: a caption, its letter, and
+    # its children — {Entry}s, or further `Menu`s.
+    Menu = Data.define(:caption, :mnemonic, :items)
+
+    # The strip, left to right. The grouping mirrors the README's **Components**
+    # sections (= book ch7's tour, organized by the job), so the sampler doubles
+    # as a live index of the catalogue and any drift between the two is visible.
+    #
+    # Mnemonics are *hand-picked*: {Tuile::Component::MenuBar#add_item} raises on
+    # a duplicate among siblings, and five leaves therefore answer to a letter
+    # other than their initial (Past`e`, Checkbox`G`roup, C`o`mboBox,
+    # Pic`k`erWindow, S`l`ash menu) — the underline shows which. No item may use
+    # `q`: quit is the unhandled-key fallback, so a `q` on the live level would
+    # swallow it while the bar has focus.
+    MENUS = [
+      Menu.new("Show", "s", [
+                 Entry.new("Label", :build_label, "l"),
+                 Entry.new("TextView", :build_text_view, "t"),
+                 Entry.new("ProgressBar", :build_progress_bar, "p")
+               ]),
+      Menu.new("Input", "i", [
+                 Menu.new("Text", "t", [
+                            Entry.new("TextField", :build_text_field, "t"),
+                            Entry.new("TextArea", :build_text_area, "a"),
+                            Entry.new("PasswordField", :build_password_field, "p"),
+                            Entry.new("Paste", :build_paste_demo, "e"),
+                            Entry.new("Slash menu", :build_slash_demo, "l")
+                          ]),
+                 Menu.new("Typed", "y", [
+                            Entry.new("IntegerField", :build_integer_field, "i"),
+                            Entry.new("FloatField", :build_float_field, "f"),
+                            Entry.new("BigDecimalField", :build_big_decimal_field, "b")
+                          ]),
+                 Menu.new("Choose", "c", [
+                            Entry.new("Checkbox", :build_checkboxes, "c"),
+                            Entry.new("CheckboxGroup", :build_checkbox_group, "g"),
+                            Entry.new("RadioGroup", :build_radio_group, "r"),
+                            Entry.new("Select", :build_select, "s"),
+                            Entry.new("ComboBox", :build_combo_box, "o"),
+                            Entry.new("List", :build_list, "l")
+                          ])
+               ]),
+      # One entry, so it is the item and not a menu — a top-level leaf on the
+      # strip is a button, which nothing else here demos.
+      Entry.new("Button", :build_buttons, "b"),
+      Menu.new("Overlay", "o", [
+                 Entry.new("Popup", :build_popup_launcher, "p"),
+                 Entry.new("Notification", :build_notification_launcher, "n"),
+                 Entry.new("ConfirmWindow", :build_confirm_launcher, "c"),
+                 Entry.new("InfoWindow", :build_info_launcher, "i"),
+                 Entry.new("PickerWindow", :build_picker_launcher, "k"),
+                 Entry.new("LogWindow", :build_log_window, "l")
+               ]),
+      Menu.new("Shell", "h", [
+                 Entry.new("TabSheet", :build_tab_sheet, "t"),
+                 Entry.new("MenuBar", :build_menu_bar, "m"),
+                 Entry.new("Narrow strips", :build_narrow_strips, "n"),
+                 Entry.new("Layout", :build_layout, "l"),
+                 Entry.new("Background", :build_background, "b"),
+                 Entry.new("Focus & Tab", :build_focus_demo, "f")
+               ])
     ].freeze
 
-    def build_entry_list
-      list = Tuile::Component::List.new
-      list.cursor = Tuile::Component::List::Cursor.new
-      list.lines = ENTRIES.map(&:first)
-      list.on_cursor_changed = ->(idx, _line) { load_entry(idx) if idx >= 0 }
-      list
+    # Every {Entry} in strip order — what the jump box offers.
+    ENTRIES = MENUS.flat_map { |node| node.is_a?(Entry) ? [node] : node.items }
+                   .flat_map { |node| node.is_a?(Entry) ? [node] : node.items }
+                   .freeze
+
+    # The shell: the strip takes what it needs, the jump box a fixed column at
+    # the right end. The bar paints only its {Tuile::Component::MenuBar#extent},
+    # so its `Expand` tail is the gap between the two.
+    def shell_row
+      Tuile::Component::Layout::Horizontal.new.tap do |r|
+        r.add(@menu_bar, Expand[1])
+        r.add(@jump_box, Fixed[JUMP_BOX_WIDTH])
+      end
+    end
+
+    JUMP_BOX_WIDTH = 26
+
+    def build_shell_bar
+      bar = Tuile::Component::MenuBar.new
+      MENUS.each { |node| add_menu_node(bar, node) }
+      bar
+    end
+
+    # Mints `node` under `parent` — the bar, or an {Tuile::Component::MenuBar::Item}
+    # holding a submenu. The two `add_item`s share a signature, so nesting is
+    # this one recursion.
+    def add_menu_node(parent, node)
+      if node.is_a?(Entry)
+        parent.add_item(node.caption, mnemonic: node.mnemonic) { select_entry(node) }
+      else
+        holder = parent.add_item(node.caption, mnemonic: node.mnemonic)
+        node.items.each { |child| add_menu_node(holder, child) }
+      end
     end
 
-    def load_entry(idx)
+    # Type a few letters of a demo's name and Enter to jump to it. Its `value`
+    # is the {Entry} — the selected *item*, never the typed text — which is what
+    # lets it be the selection model the menu also writes to.
+    def build_jump_box
+      combo = Tuile::Component::ComboBox.new(items: ENTRIES)
+      combo.item_label = :caption.to_proc
+      combo.on_value_change = ->(entry) { load_entry(entry) if entry }
+      combo
+    end
+
+    # Fires from the jump box's `on_value_change`, and from nowhere else.
+    def load_entry(entry)
       # The slash-menu demo parks a non-modal overlay on the pane (it lives
-      # outside the right pane's content tree), so close it before swapping
+      # outside the demo pane's content tree), so close it before swapping
       # demos or it would linger over the next one.
       @slash_overlay.close if @slash_overlay&.open?
       @slash_overlay = nil
-      caption, builder = ENTRIES[idx]
-      @right_window.caption = caption
-      @right_window.content = send(builder)
+      @demo_window.caption = entry.caption
+      @demo_window.content = send(entry.builder)
+      # Focus goes home to the strip after every load, whichever navigator ran:
+      # a no-op on the menu path (the bar holds focus through the cascade), and
+      # what pulls focus back out of the jump box after a commit. Guarded
+      # because the first load runs from the constructor, before attach — at
+      # startup it is the runner's own `menu_bar.focus` that lands.
+      @menu_bar.focus if attached?
     end
 
     # --- Tileable demos ----------------------------------------------------
@@ -360,24 +492,21 @@ module SamplerExample
     # Slash commands the demo offers; the menu filters these by what's typed.
     SLASH_COMMANDS = %w[/help /list /open /save /clear /quit].freeze
 
-    # A non-modal Popup used as an autocomplete menu. Focus (and the caret)
-    # stays in the TextArea the whole time: an `on_change` listener refills the
-    # menu, an `on_key` interceptor forwards Up/Down/Enter/ESC to it while it's
-    # open, and the menu floats above the field, anchored to the caret. None of
-    # this is baked into TextArea — it's all assembled here from stock hooks.
+    # A ListDropdown driven from a TextArea — the same shape {ComboBox} and
+    # {Select} use, but wired by app code onto a field that knows nothing about
+    # it. Focus (and the caret) stays in the TextArea the whole time: an
+    # `on_change` listener refills the menu, and an `on_key` interceptor hands
+    # movement keys to `#move` and Enter to `#choose` while it is open. None of
+    # this is baked into TextArea.
     def build_slash_demo
       prompt = Tuile::Component::Label.new
-      prompt.text = "Non-modal Popup as an autocomplete menu. Type a slash command\n" \
-                    "(try \"/\" or \"/s\"). The menu floats above the field without taking\n" \
+      prompt.text = "A ListDropdown driven from a TextArea. Type a slash command\n" \
+                    "(try \"/\" or \"/s\"). The menu floats over the field without taking\n" \
                     "focus: Down/Up move the selection, Enter accepts, ESC dismisses, and\n" \
                     "ordinary typing keeps editing the field and refilters the menu."
       area = Tuile::Component::TextArea.new
 
-      list = Tuile::Component::List.new
-      list.cursor = Tuile::Component::List::Cursor.new
-      list.show_cursor_when_inactive = true # highlight the selection though focus stays in the field
-      window = Tuile::Component::Window.new("Commands").tap { _1.content = list }
-      overlay = Tuile::Component::Popup.new(content: window, modal: false)
+      overlay = Tuile::Component::ListDropdown.new
       @slash_overlay = overlay
 
       refill = lambda do
@@ -385,20 +514,23 @@ module SamplerExample
         if matches.empty?
           overlay.close if overlay.open?
         else
+          overlay.items = matches
           overlay.open unless overlay.open?
-          list.lines = matches
-          anchor_overlay(overlay, area)
+          # Width is the driver's call, never the dropdown's: measure the
+          # commands rather than inherit the full-width TextArea's columns.
+          overlay.anchor_to(area.rect, rows: matches.size, width: slash_menu_width(matches))
         end
       end
 
       area.on_change = ->(_text) { refill.call }
-      list.on_item_chosen = ->(_idx, line) { accept_slash_command(area, line.to_s) }
+      overlay.on_item_chosen = ->(_idx, item) { accept_slash_command(area, item.to_s) }
       area.on_key = lambda do |key|
         next false unless overlay.open?
+        next true if overlay.move(key) # Up/Down/PgUp/PgDn/^U/^D
 
         case key
-        when Tuile::Keys::UP_ARROW, Tuile::Keys::DOWN_ARROW, Tuile::Keys::ENTER
-          list.handle_key(key) # works though the list is unfocused — dispatch gates on focus, not the list
+        when Tuile::Keys::ENTER
+          overlay.choose
         when Tuile::Keys::ESC
           overlay.close
           true
@@ -413,6 +545,43 @@ module SamplerExample
       end
     end
 
+    # Paste vs. Enter: the prompt submits on ENTER, so the two are only
+    # distinguishable because the terminal brackets a paste. Type a line and
+    # press Enter — `submits` ticks. Paste several lines — `submits` doesn't.
+    def build_paste_demo
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Enter submits the draft; a paste stays a draft.\n" \
+                    "Tab here, type a line, press Enter: it moves to\n" \
+                    "the log. Now paste several lines — they land as\n" \
+                    "one draft, and \"submits\" does not move."
+      stats = Tuile::Component::Label.new
+      log = Tuile::Component::TextView.new
+      area = PromptTextArea.new
+      submits = 0
+      pastes = 0
+
+      refresh = lambda do
+        stats.text = "submits: #{submits}   pastes: #{pastes}   rows in draft: #{area.row_count}"
+      end
+      area.on_change = ->(_text) { refresh.call }
+      area.on_paste = lambda do |text|
+        pastes += 1
+        log.add_line(Rainbow("pasted #{text.lines.size} line(s), #{text.length} chars").cyan)
+      end
+      area.on_submit = lambda do |text|
+        submits += 1
+        log.add_line(Rainbow("submitted: #{text.inspect}").green)
+      end
+      refresh.call
+
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(stats, Fixed[1])
+        f.add(area, Fixed[5])
+        f.add(Tuile::Component::Window.new("Log").tap { _1.content = log }, Expand[1])
+      end
+    end
+
     def build_text_view
       prompt = Tuile::Component::Label.new
       prompt.text = "Read-only viewer for prose. Word-wraps to width; ANSI formatting passes through.\n" \
@@ -760,6 +929,21 @@ module SamplerExample
       BgChoice.new("Hot pink (RGB)", Tuile::Color.rgb(120, 20, 70))
     ].freeze
 
+    # The one choice that can't be a constant: the terminal's *own* background
+    # stepped +10 per channel — the borderless-pane tint, which only sits right
+    # when it's derived from the real background. Nil on a terminal that
+    # reported none, which is the branch most users will actually see.
+    def terminal_tint_choice
+      bg = Tuile::Screen.instance.background_color
+      return BgChoice.new("Terminal background — none reported", nil) if bg.nil?
+
+      BgChoice.new("Terminal background +10 (derived)",
+                   Tuile::Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }))
+    end
+
+    # @param derived [BgChoice] the live terminal-derived tint, offered second.
+    def bg_choices(derived) = [BG_CHOICES.first, derived, *BG_CHOICES[1..]]
+
     def build_background
       intro = Tuile::Component::Label.new
       intro.text = "bg_color tints a component and every descendant that doesn't set its own.\n" \
@@ -783,7 +967,8 @@ module SamplerExample
       # their own well. Theme::Ref picks re-resolve on a scheme flip with no hook;
       # the hard-coded Colors are fixed by design, so no on_theme_changed here.
       outer = nil
-      combo = Tuile::Component::ComboBox.new(items: BG_CHOICES)
+      derived = terminal_tint_choice
+      combo = Tuile::Component::ComboBox.new(items: bg_choices(derived))
       combo.item_label = :label.to_proc
       combo.on_value_change = ->(choice) { outer.bg_color = choice.color }
 
@@ -792,6 +977,17 @@ module SamplerExample
         f.add(combo, Fixed[1], cross: Fixed[40])
         f.add(box, Expand[1])
       end
+      # The derived tint is the one pick whose *color* moves under it: a flip
+      # re-probes the terminal, so rebuild the choice and re-apply it if it is
+      # the current one. Expect it to correct itself a frame late — the flip
+      # report carries no RGB, so this hook runs once on the old background and
+      # again when the re-probe answers.
+      outer.on_theme_changed = lambda do
+        was_derived = combo.value.equal?(derived)
+        derived = terminal_tint_choice
+        combo.items = bg_choices(derived)
+        combo.value = derived if was_derived
+      end
       combo.value = BG_CHOICES.first # show "None" as the resting selection
       outer
     end
@@ -819,6 +1015,155 @@ module SamplerExample
     # seconds (and the grow-only width), and a long one shows the three-row wrap
     # ending in an ellipsis. Focus stays on whichever button you pressed
     # throughout — that is the whole point of the widget.
+    TAB_PROSE = "A TabSheet keeps only the selected tab's pane in the component tree; the others are " \
+                "detached. That is how Tuile hides a component — there is no visibility flag, and an empty " \
+                "rect gates painting only.\n\n" \
+                "Detaching is what makes the rest fall out for free. A hidden pane is invisible to the Tab " \
+                "cycle, to the focus cascades, to repaint and to the cursor, with no gate anywhere in the " \
+                "framework. Its state survives regardless, because state is ivars: scroll position, caret, " \
+                "list cursor and text are all exactly as you left them.\n\n" \
+                "Scroll down here, switch to another tab with ←→, and come back: this view is still on the " \
+                "row you left it on, and the status line below the sheet reports every pane's state as you " \
+                "switch. A pane that must keep a resource alive while hidden cannot — that resource belongs " \
+                "in the model the pane renders, not in the pane itself."
+
+    # TabSheet: the strip is one tab stop driven by ←→, and switching swaps the
+    # pane below it. The status line reads each pane's state on every switch,
+    # which is the property most likely to be doubted: a hidden pane is detached
+    # from the tree, and it still comes back exactly as it was left.
+    def build_tab_sheet
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here to focus the strip, then ←→ to switch tabs — selection is immediate, and the " \
+                    "selected caption stays bold once focus moves on.\n" \
+                    "Tab again to enter the pane. Enter, Space, Up/Down and Home/End are left to the app, " \
+                    "so they bubble past the strip."
+
+      field = Tuile::Component::TextField.new
+      field.text = "type here"
+      checkbox = Tuile::Component::Checkbox.new("Remember me", value: true)
+      list = Tuile::Component::List.new
+      list.cursor = Tuile::Component::List::Cursor.new
+      list.lines = (1..40).map { |i| "Row #{i}" }
+      view = Tuile::Component::TextView.new
+      view.text = TAB_PROSE
+
+      sheet = Tuile::Component::TabSheet.new
+      sheet.add_tab("Form", group do |g|
+        g.add(field, Fixed[1])
+        g.add(checkbox, Fixed[1])
+      end)
+      sheet.add_tab("List", list)
+      sheet.add_tab("Prose", view)
+
+      status = Tuile::Component::Label.new
+      report = lambda do
+        status.text = "Form: #{field.text.inspect}, #{checkbox.checked? ? "checked" : "unchecked"}  ·  " \
+                      "List row #{list.cursor.position}  ·  Prose row #{view.scroll_top_row}"
+      end
+      report.call
+      sheet.on_tab_selected = ->(_index, _tab) { report.call }
+
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(sheet, Expand[1])
+        f.add(status, Fixed[1])
+      end
+    end
+
+    def build_menu_bar
+      status = Tuile::Component::Label.new
+      status.text = "Nothing activated yet."
+      activate = ->(path) { status.text = "Activated: #{path}" }
+
+      bar = Tuile::Component::MenuBar.new
+      file = bar.add_item("File", mnemonic: "f")
+      file.add_item("New", mnemonic: "n") { activate.call("File ▸ New") }
+      file.add_item("Open", mnemonic: "o") { activate.call("File ▸ Open") }
+      recent = file.add_item("Open recent", mnemonic: "r")
+      %w[notes.txt report.md sampler.rb].each_with_index do |name, index|
+        # A mnemonic the caption doesn't contain: it fires, it just draws no cue.
+        recent.add_item(name, mnemonic: (index + 1).to_s) { activate.call("File ▸ Open recent ▸ #{name}") }
+      end
+      # Three deep, to show the cascade actually cascading.
+      archive = recent.add_item("Archive", mnemonic: "a")
+      %w[2024.zip 2025.zip].each do |name|
+        archive.add_item(name) { activate.call("… ▸ Archive ▸ #{name}") }
+      end
+      file.add_item("Quit", mnemonic: "q") { activate.call("File ▸ Quit") }
+
+      edit = bar.add_item("Edit", mnemonic: "e")
+      # "Cut" takes 'c' here; "Copy" can't, so it takes 'o'. Only siblings compete.
+      { "Cut" => "c", "Copy" => "o", "Paste" => "p", "Select all" => "s" }.each do |name, mnemonic|
+        edit.add_item(name, mnemonic: mnemonic) { activate.call("Edit ▸ #{name}") }
+      end
+      # A top-level item with no children is a button, not a menu.
+      bar.add_item("About", mnemonic: "a") { activate.call("About (a top-level leaf)") }
+      # …and one with neither children nor a listener is legal and inert.
+      bar.add_item("Inert")
+
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here to focus the bar, then ←→ to pick a menu and Enter/Space/Down to open it.\n" \
+                    "Inside: ↑↓ moves, → (or Enter) opens a submenu, ← goes back, ESC closes one level.\n" \
+                    "← at the first level and → on a plain row step to the neighbouring menu.\n" \
+                    "The underlined letters are mnemonics: press f then q for File ▸ Quit. Each level has\n" \
+                    "its own set, so 'o' is File ▸ Open and also Edit ▸ Copy — try f,o then e,o.\n" \
+                    "A letter that matches nothing in the open menu just beeps; it won't switch menus.\n" \
+                    "The panels overdraw this window and the nav list — they are overlays, not children.\n" \
+                    "\"About\" is a top-level leaf, so it acts as a button; \"Inert\" does nothing at all."
+
+      form do |f|
+        f.add(bar, Fixed[1])
+        f.add(prompt, Fixed[9])
+        f.add(status, Fixed[1])
+        f.add(Tuile::Component::Label.new, Expand[1])
+      end
+    end
+
+    # The same four tabs twice — at the width their captions need, and starved
+    # into sixteen columns — plus a menu bar given eighteen. A strip too narrow
+    # scrolls to keep the selection whole in view; the status line is the part
+    # worth watching, because it reports a selection that used to be able to
+    # walk off the edge and leave the visible strip unchanged.
+    def build_narrow_strips
+      captions = %w[Details Payment Shipping Billing]
+      wide = Tuile::Component::Tabs.new
+      narrow = Tuile::Component::Tabs.new
+      [wide, narrow].each { |strip| captions.each { |caption| strip.add_tab(caption) } }
+
+      status = Tuile::Component::Label.new
+      report = lambda do
+        status.text = "Starved strip: #{narrow.selected.caption} " \
+                      "(#{narrow.selected_index + 1} of #{narrow.tabs.size})"
+      end
+      report.call
+      narrow.on_tab_selected = ->(_index, _tab) { report.call }
+
+      bar = Tuile::Component::MenuBar.new
+      %w[File Edit View Window Help].each do |caption|
+        menu = bar.add_item(caption)
+        %w[First Second Third].each { |item| menu.add_item("#{caption} #{item}") }
+      end
+
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab to a strip, then ←→. The starved one scrolls by the minimum needed to show the\n" \
+                    "selected tab whole, so the selection can never hide off an edge — and it scrolls\n" \
+                    "back to column 0 the moment everything fits again.\n" \
+                    "< and > over the edge columns say there is more strip that way; the captions cut\n" \
+                    "under them say the same thing, but only when the cut lands mid-caption. They are\n" \
+                    "not buttons: clicking one selects the half-visible tab beneath it, which reveals it.\n" \
+                    "The menu bar scrolls the same way — ←→ along it, and a menu opens under its own\n" \
+                    "segment wherever the scrolling has put it."
+
+      form do |f|
+        f.add(prompt, Fixed[8])
+        f.add(labelled("Natural width", wide, field_width: 40), Fixed[1])
+        f.add(labelled("16 columns", narrow, field_width: 16), Fixed[1])
+        f.add(status, Fixed[1])
+        f.add(labelled("Menu bar (18)", bar, field_width: 18), Fixed[1])
+        f.add(Tuile::Component::Label.new, Expand[1])
+      end
+    end
+
     def build_notification_launcher
       label = Tuile::Component::Label.new
       label.text = "Notification.show puts a toast in the top-right corner for 3 seconds.\n" \
@@ -849,6 +1194,61 @@ module SamplerExample
       end
     end
 
+    # The three factories, the layer-1 builder (3-way), and a message long
+    # enough to scroll. The status row makes the one-dismissal-channel contract
+    # visible: every route out of a dialog lands in exactly one callback.
+    def build_confirm_launcher
+      label = Tuile::Component::Label.new
+      label.text = "ConfirmWindow asks a question with a row of buttons, in a popup sized to\n" \
+                   "its content (capped at half the screen). Every button closes the dialog;\n" \
+                   "ESC, q or an outside click dismiss it instead. An underlined letter presses\n" \
+                   "its button from anywhere; Up/Down scroll a long message meanwhile."
+      status = Tuile::Component::Label.new("Outcome: none yet")
+      report = ->(outcome) { status.text = "Outcome: #{outcome}" }
+      buttons = [
+        Tuile::Component::Button.new("Confirm") do
+          Tuile::Component::ConfirmWindow.confirm(
+            "Delete Report Q4?", "This cannot be undone.",
+            confirm: "Delete", on_dismiss: -> { report.call("kept the report") }
+          ) { report.call("deleted the report") }
+        end,
+        Tuile::Component::Button.new("Yes/No") do
+          Tuile::Component::ConfirmWindow.yes_no(
+            "Overwrite draft.txt?", "The file already exists.",
+            on_dismiss: -> { report.call("kept draft.txt") }
+          ) { report.call("overwrote draft.txt") }
+        end,
+        Tuile::Component::Button.new("Alert") do
+          Tuile::Component::ConfirmWindow.alert("Export failed", "Contact support@example.com.")
+        end,
+        Tuile::Component::Button.new("3-way") do
+          dialog = Tuile::Component::ConfirmWindow.new("Unsaved changes")
+          dialog.message = "Save your changes before leaving?"
+          dialog.button("Save")    { report.call("saved") }
+          dialog.button("Discard") { report.call("discarded") }
+          dialog.button("Cancel")
+          dialog.on_dismiss = -> { report.call("stayed put") }
+          dialog.open
+        end,
+        Tuile::Component::Button.new("Long") do
+          dialog = Tuile::Component::ConfirmWindow.new("Terms of Service")
+          dialog.message = (1..40).map { "#{_1}. Clause #{_1} of the agreement, spelled out in full." }.join("\n")
+          dialog.button("Accept")  { report.call("accepted the terms") }
+          dialog.button("Decline") { report.call("declined the terms") }
+          dialog.on_dismiss = -> { report.call("left the terms unanswered") }
+          dialog.open
+        end
+      ]
+      strip = row do |r|
+        buttons.each { |b| r.add(b, Fixed[button_width(b)]) }
+      end
+      form do |f|
+        f.add(label, Fixed[4])
+        f.add(strip, Fixed[1])
+        f.add(status, Fixed[1])
+      end
+    end
+
     def build_popup_launcher
       launcher(
         "Popup is a modal overlay wrapping any Component.\n" \
@@ -862,17 +1262,39 @@ module SamplerExample
     end
 
     def build_info_launcher
-      launcher(
-        "InfoWindow is a Window of read-only text lines, openable as a popup.",
-        "Open InfoWindow"
-      ) do
-        Tuile::Component::InfoWindow.open(
-          "Hello",
-          ["InfoWindow displays static text",
-           "inside a popup.",
-           "",
-           "Press ESC or q to close."]
-        )
+      label = Tuile::Component::Label.new
+      label.text = "InfoWindow is a Window with a read-only body: prose (message=) wraps in\n" \
+                   "a TextView, rows (lines=) stay one per row in a List, truncating. The\n" \
+                   "constructor picks the presentation by the body's type."
+      buttons = [
+        Tuile::Component::Button.new("Prose") do
+          Tuile::Component::InfoWindow.open(
+            "About",
+            "InfoWindow renders a String as wrapping prose: this sentence is long " \
+            "enough to wrap to the popup's width, and it scrolls when it outgrows " \
+            "the box. Press ESC or q to close."
+          )
+        end,
+        Tuile::Component::Button.new("Rows") do
+          Tuile::Component::InfoWindow.open(
+            "Files",
+            ["drwxr-xr-x  src/",
+             "drwxr-xr-x  spec/",
+             "-rw-r--r--  README.md   4.1k",
+             "-rw-r--r--  Rakefile     812",
+             "",
+             "Rows never wrap: a long row like this one is truncated at the popup's edge, keeping columns aligned.",
+             "",
+             "Press ESC or q to close."]
+          )
+        end
+      ]
+      strip = row do |r|
+        buttons.each { |b| r.add(b, Fixed[button_width(b)]) }
+      end
+      form do |f|
+        f.add(label, Fixed[3])
+        f.add(strip, Fixed[1])
       end
     end
 
@@ -890,7 +1312,7 @@ module SamplerExample
 
     def build_log_window
       log = Tuile::Component::LogWindow.new("Log")
-      ["LogWindow is a Window wrapping an auto-scrolling TextView.",
+      ["LogWindow is a Window framing an auto-scrolling LogTextView.",
        "Lines are appended via #log (safe from any thread).",
        "Used with Logger::IO it captures arbitrary log output."].each { |line| log.log(line) }
       log
@@ -998,18 +1420,13 @@ module SamplerExample
       area.caret = start + command.length + 1
     end
 
-    # Positions the overlay just below the caret, flipping above when there's
-    # no room beneath, and clamps it to the screen.
-    def anchor_overlay(overlay, area)
-      caret = area.cursor_position
-      return if caret.nil?
-
-      screen_size = Tuile::Screen.instance.size
-      size = overlay.rect
-      top = caret.y + 1
-      top = [caret.y - size.height, 0].max if top + size.height > screen_size.height - 1
-      left = caret.x.clamp(0, [screen_size.width - size.width, 0].max)
-      overlay.rect = Tuile::Rect.new(left, top, size.width, size.height)
+    # The slash menu's width: the widest command plus List's two row gutters,
+    # clamped to the screen. ListDropdown places itself but never measures — the
+    # width policy stays with the driver, exactly as it does for Select.
+    # @return [Integer]
+    def slash_menu_width(matches)
+      widest = matches.map { Tuile::StyledString.plain(_1).display_width }.max || 0
+      [widest + 2, Tuile::Screen.instance.size.width].min
     end
 
     # A button's natural width — enough to show "[ caption ]".
@@ -1023,7 +1440,9 @@ if $PROGRAM_NAME == __FILE__
   screen = Tuile::Screen.new
   sampler = SamplerExample::Sampler.new
   screen.content = sampler
-  sampler.entry_list.focus
+  screen.on_focus_changed = -> { sampler.refresh_status }
+  sampler.refresh_status
+  sampler.menu_bar.focus
   begin
     screen.run_event_loop
   ensure