tuile 0.12.0 → 0.13.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,215 @@ 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("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
 
-    def load_entry(idx)
+    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
+
+    # 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 ----------------------------------------------------
@@ -413,6 +544,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" \
@@ -819,6 +987,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" \
@@ -1023,7 +1340,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

data/ideas/arrow-key-navigation.md

@@ -104,6 +104,12 @@ Recorded here so the open questions below stay narrow.
   stop. See open question on backwards entry.
 - **Mouse is untouched.** Popups are untouched — the bubble is already scoped
   to the topmost modal popup.
+- **{Tuile::Component::Tabs} already left the vertical axis free for this.**
+  The strip claims Left/Right and *declines* Up/Down specifically so that this
+  feature can move focus out of it vertically while Left/Right keep switching
+  tabs inside it (`D-tabs`). It composes for nothing: the strip declines, the
+  key bubbles, the navigating ancestor moves. That is also the shape to copy
+  for any future one-axis widget — claim one axis, leave the other.
 
 ## The honest argument against
 
@@ -180,6 +186,16 @@ exactly virtui's shape, so the answer matters more there than in a form.
 (`combo_box.rb:181`) but declines Up. So Up would jump out of a closed combo
 while Down opens it. Browsers eat both. Deliberate choice or accident to fix?
 
+**Q12 — Down out of a `Tabs` strip: to the pane, or past the whole
+`TabSheet`?** The strip is a child of the sheet, not of the navigating layout,
+so "walk direct children" sees the *sheet* holding focus and would move to the
+sheet's next sibling — skipping the pane the user is looking at. Entering the
+pane is almost certainly what a user means by Down here. Options: let a
+`TabSheet` claim Down when focus is on its strip (a `handle_key` on the sheet,
+no framework change, but a second place that binds an arrow); or have the
+navigating walk descend into a child that holds focus deeper than its first
+tab stop. Interacts with Q1's placement question.
+
 **Q9 — Naming.** "Form" is the wrong word for the behavior — it's *focus
 navigation*. `navigation` / `arrow_nav` / `key_navigation` /
 `focus_navigation`? Whatever it is, it must not imply validation or submit,

data/ideas/new-components.md

@@ -50,10 +50,9 @@ That leaves ~46 gaps.
 | ~~Notification~~ | `Popup` + `Ticker` | **built** 2026-08-17 (`D-notification`, book ch7); one non-modal top-right box, N messages, one 3 s ticker retiring the oldest. Corner anchor is its own `reposition` override, so `Popup` was untouched — and the `Popover` extraction still waits for a second *kind* of anchoring |
 | Confirm Dialog | `Popup`+`Window`+`Button` | fold `PickerWindow` in |
 | Details → Accordion | `HasContent` | Details is the atom, Accordion the group |
-| Tabs → Tabsheet | `HasValue` (index) + `HasContent` | strip, then strip + content swap |
-| Popover | `ListDropdown#anchor_to` (extracted 2026-08-12) | generalize the anchored non-modal overlay: `anchor_to` moves down to it and `ListDropdown` inherits it. Build it when the second *kind* of anchoring appears (a point; a right edge that flips) — not the second caller of the same kind. Gates the next two |
-| Menu Bar | `ListDropdown::Menu` + Popover | |
-| Context Menu | same | `:right` button already parses |
+| ~~Tabs → TabSheet~~ | plain `Component` + the tree API | **built** 2026-08-23 (`D-tabs`, book ch7); a strip (one tab stop, Left/Right, immediate activation) plus a sheet whose `children` are `[strip, pane]`. Neither is `HasValue` — a tab selection is view state — and neither is `HasContent`; hiding a pane means *detaching* it, since Tuile has no visibility flag; the strip owns mutable `Tabs::Tab` handles rather than the `items`/`item_label` shell. Hidden/disabled/closeable tabs, lazy panes and a scrolling strip are deferred, each additive (`D-tabs`) |
+| Popover | `ListDropdown#anchor_to` (extracted 2026-08-12) | generalize the anchored non-modal overlay: `anchor_to` moves down to it and `ListDropdown` inherits it. Build it when the second *kind* of anchoring appears (a point; a right edge that flips) — not the second caller of the same kind. Nothing gates on it today: Menu Bar shipped without it |
+| ~~Menu Bar~~ | `ListDropdown` (+ `anchor_beside`) | **built** 2026-08-24 (`D-menu-bar`, book ch7), mnemonics the same day. Turned out *not* to need the Popover extraction: a focused strip drives a cascade of non-modal `ListDropdown`s the way `Select` drives one, so the additions were a side-anchor method, a highlighted-row rect and a cursor pass-through. Unlimited submenu depth; checkable/disabled items and global-shortcut activation deferred indefinitely |
 | Slider | `draw_line` | arrows/PgUp; 25.2 also has a two-thumb *range* variant |
 | Breadcrumbs | `Label`/`StyledString` | clickable path segments |
 | Markdown | `TextView` + `StyledString` | Markdown subset → styled text; high value on a TTY |
@@ -100,8 +99,10 @@ file when its cluster comes up:
 2. **Field label + helper text seam** → Form Layout. Note this is what Form
    Layout is actually blocked on — the layout half now exists.
 3. **Validation seam** → Email Field, forms generally.
-4. **Anchored Popover extraction** → Menu Bar, Context Menu, pickers,
-   Tooltip.
+4. **Anchored Popover extraction** → pickers, Tooltip. **No longer gates Menu
+   Bar** — `D-menu-bar` argues the side-anchor is a sibling method on
+   `ListDropdown`, since both callers still wrap a `List`; the extraction's
+   trigger is now the first non-`List` content that wants anchoring.
 5. **Mouse motion/drag** (modes 1002/1006, release events) → Split
    divider, Slider drag, scrollbar drag.
 6. **Typed items + data provider on `List`** → List Box, Grid, Virtual

data/lib/tuile/ansi.rb

@@ -12,6 +12,16 @@ module Tuile
     # @return [String]
     RESET = "\e[0m"
 
+    # The bell (`BEL`, `\a`, 0x07) — the "that keystroke went nowhere" signal.
+    # Ring it with {Screen#beep} rather than printing it: the bell is terminal
+    # IO, which is {Screen}'s job.
+    #
+    # What the user gets is the *terminal's* business — an audible beep, a
+    # visual flash, or nothing at all — and Tuile keeps no preference of its
+    # own about that.
+    # @return [String]
+    BEL = "\a"
+
     # Begin Synchronized Update (DEC private mode 2026, "Synchronized
     # Output"). The terminal stops refreshing its display and buffers every
     # subsequent write until {SYNC_END}, then composites the whole batch

data/lib/tuile/component/abstract_string_field.rb

@@ -42,6 +42,8 @@ module Tuile
     #
     # - {#preprocess_text} — input filter (e.g. {TextField} truncates to
     #   fit `rect.width - 1`).
+    # - {#preprocess_paste} — the same for {#handle_paste}, which lands a
+    #   whole clipboard at the caret in one mutation.
     # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
@@ -155,8 +157,42 @@ module Tuile
         handle_text_input_key(key)
       end
 
+      # Inserts pasted text at the caret as **one** mutation, so {#on_change}
+      # fires once for the whole paste rather than once per character.
+      # {#preprocess_paste} filters it first.
+      # @param text [String]
+      # @return [Boolean] always true — a field consumes every paste, an empty
+      #   one included.
+      def handle_paste(text)
+        insert_text(preprocess_paste(text))
+        true
+      end
+
       protected
 
+      # Input filter for {#handle_paste}, the paste-side counterpart of
+      # {#preprocess_text}. Strips the C0 control characters a text buffer
+      # cannot hold — a raw `\e` or `\t` reaching {Buffer} would move the real
+      # terminal cursor mid-frame — keeping `\n`, and turning a tab into a
+      # single space so pasted code keeps its word gaps. {TextField} narrows it
+      # further; an app wanting tab *expansion* overrides {#handle_paste}.
+      # @param text [String]
+      # @return [String]
+      def preprocess_paste(text) = text.tr("\t", " ").gsub(/[\x00-\x09\x0b-\x1f\x7f]/, "")
+
+      # Inserts `str` at the caret, leaving the caret behind it. The bulk
+      # counterpart of a subclass's per-key insert.
+      # @param str [String]
+      # @return [Boolean] true if the text changed.
+      def insert_text(str)
+        return false if str.empty?
+
+        new_text = @text.dup.insert(@caret, str)
+        @caret += str.length
+        self.text = new_text
+        true
+      end
+
       # Renders `text` on the field's background well, looked up from the
       # current {Screen#theme} at paint time: {Theme#active_bg_color} when this
       # input is on the active (focus) chain, {Theme#input_bg_color} otherwise —