tuile 0.12.0 → 0.13.0

data/lib/tuile/component.rb

@@ -94,20 +94,29 @@ module Tuile
     end
 
     # Repaints the component. The default does the bookkeeping most components
-    # need: it clears the background, and for a container whose children leave
-    # gaps in {#rect} it re-invalidates those children so they repaint over the
-    # cleared area (what makes mixed-width form layouts safe). A container whose
-    # children fully tile {#rect} is left alone — the children cover everything.
+    # need: it clears the background — unless the direct children already tile
+    # {#rect}, in which case there is no gap to wipe and blanking cells they are
+    # about to repaint would only make them dirty — and then re-invalidates
+    # those children so they paint over the cleared area. That is what makes
+    # mixed-width form layouts safe.
     #
     # Call `super` from your own `repaint` to inherit this. Skip it only if you
     # paint the whole {#rect} yourself ({Window}'s border, {Component::List}'s
     # row-by-row paint). Never draw outside {#rect}. Only called when attached.
+    #
+    # **The children are re-invalidated whether or not they tile.** A container
+    # that paints nothing of its own can only redraw its area *through* them, so
+    # a tiling container that skipped this would be a dead end in the cascade: an
+    # ancestor's `clear_background` wipes the whole ancestor rect — siblings and
+    # grandchildren included — and re-invalidates only its *direct* children, so
+    # the notice has to keep travelling down or the cleared cells are never
+    # repainted. Cheap by construction: repainting the same glyphs leaves
+    # {Buffer::Cell} unchanged, so nothing extra reaches the wire.
     # @return [void]
     def repaint
       return if rect.empty?
-      return if children.any? && children_tile_rect?
 
-      clear_background
+      clear_background unless children.any? && children_tile_rect?
       children.each { |c| screen.invalidate(c) }
     end
 
@@ -122,6 +131,27 @@ module Tuile
       false
     end
 
+    # Called when text is pasted while this component is on the focus chain;
+    # override to accept it (the default reports every paste unhandled, and
+    # unhandled text is dropped). Arrives whole and `\n`-normalized, so
+    # `text.lines.size` is the paste's line count and a single mutation can
+    # absorb it:
+    #
+    #   def handle_paste(text)
+    #     self.caption = "[Pasted #{text.lines.size} lines]"
+    #     true
+    #   end
+    #
+    # Reaching here means the terminal said "this came from the clipboard" —
+    # {Component::AbstractStringField} inserts it at the caret, which is why a
+    # subclass that rebinds ENTER to submit needs no paste handling of its own
+    # to stop firing once per pasted line.
+    # @param _text [String] the pasted text.
+    # @return [Boolean] true if the paste was consumed.
+    def handle_paste(_text)
+      false
+    end
+
     # Handles mouse event. Default implementation focuses this component when
     # clicked (if {#focusable?}).
     # @param event [MouseEvent]
@@ -268,17 +298,12 @@ module Tuile
     # @return [Point, nil] absolute screen coordinates, or nil to hide.
     def cursor_position = nil
 
-    # @return [String] formatted keyboard hint surfaced in the status bar by
-    #   {Screen} when this component is the active tiled window or the
-    #   topmost popup. Empty by default; override to advertise shortcuts.
-    def keyboard_hint = ""
-
     protected
 
     # Adopts `child`: places it in {#children} and wires its parent pointer.
     #
-    #   add_child(@status_bar)                              # paints last
-    #   add_child(popup, at: @children.index(@status_bar))  # …just before it
+    #   add_child(content, at: 0)   # the tiled layer, painted beneath …
+    #   add_child(@footer)          # … and chrome appended, painted over it
     #
     # @param child [Component] must not already have a parent.
     # @param at [Integer, nil] index to insert at; appends when nil.

data/lib/tuile/event_queue.rb

@@ -167,6 +167,26 @@ module Tuile
     class KeyEvent < Data.define(:key)
     end
 
+    # Text arrived from the clipboard rather than the keyboard: the terminal
+    # bracketed it in {Keys::PASTE_START} … {Keys::PASTE_END} because
+    # {Screen#run_event_loop} enabled mode 2004. The whole paste is one event,
+    # so a component sees one mutation instead of a keystroke per character —
+    # and a pasted line break can no longer be mistaken for a typed Enter.
+    #
+    # {Screen#event_loop} routes it to {Component#handle_paste} down the focus
+    # chain. It never enters the key ladder: no Tab traversal, no global
+    # shortcut, no {Component#handle_key}.
+    #
+    # @!attribute [r] text
+    #   @return [String] the pasted text, `\n`-normalized by
+    #     {Keys.normalize_paste}.
+    class PasteEvent < Data.define(:text)
+      # @param text [String]
+      def initialize(text:)
+        super(text: text.freeze)
+      end
+    end
+
     # An error event, causes {EventQueue#run_loop} to throw `StandardError` with
     # {#error} as its origin.
     #
@@ -321,7 +341,11 @@ module Tuile
       @key_thread = Thread.new do
         loop do
           key = Keys.getkey
-          event = MouseEvent.parse(key) || ColorSchemeEvent.parse(key) || KeyEvent.new(key)
+          event = if key == Keys::PASTE_START
+                    PasteEvent.new(Keys.read_paste)
+                  else
+                    MouseEvent.parse(key) || ColorSchemeEvent.parse(key) || KeyEvent.new(key)
+                  end
           post event
         end
       rescue StandardError => e

data/lib/tuile/fake_screen.rb

@@ -58,6 +58,20 @@ module Tuile
       @prints << str
     end
 
+    # Pastes `text` into the focused component, as a real terminal would with
+    # bracketed paste on:
+    #
+    #   area.focus
+    #   Screen.instance.paste("one\r\ntwo")
+    #   area.text   # => "one\ntwo" — one mutation, no ENTER anywhere
+    #
+    # Goes through {Keys.normalize_paste} first, so a spec can hand it the
+    # CR-flavored line endings terminals actually deliver and still assert
+    # against `\n`.
+    # @param text [String]
+    # @return [Boolean] true if some component consumed it.
+    def paste(text) = handle_paste(Keys.normalize_paste(text))
+
     # @param component [Component] the component to check.
     # @return [Boolean]
     def invalidated?(component) = @invalidated.include?(component)

data/lib/tuile/keys.rb

@@ -114,6 +114,24 @@ module Tuile
     # @return [String]
     SHIFT_TAB = "\e[Z"
 
+    # Enables **bracketed paste** (DEC private mode 2004): the terminal wraps
+    # pasted text in {PASTE_START} … {PASTE_END} instead of feeding it as
+    # keystrokes. Terminals that don't know the mode ignore it, so
+    # {Screen#run_event_loop} prints it unconditionally.
+    # @return [String]
+    BRACKETED_PASTE_ON = "\e[?2004h"
+    # Disables bracketed paste. See {BRACKETED_PASTE_ON}.
+    # @return [String]
+    BRACKETED_PASTE_OFF = "\e[?2004l"
+    # Opens a bracketed paste. {.getkey} returns it like any other key; the
+    # payload behind it is read by {.read_paste}.
+    # @return [String]
+    PASTE_START = "\e[200~"
+    # Closes a bracketed paste. Never surfaces as a key — {.read_paste}
+    # consumes it as the payload terminator.
+    # @return [String]
+    PASTE_END = "\e[201~"
+
     # True iff `key` is a single printable character — a one-character string
     # whose codepoint is not in Unicode's C (Other) category. Rejects multi-
     # character escape sequences ({UP_ARROW}, mouse events, …), control bytes
@@ -168,5 +186,52 @@ module Tuile
 
       char
     end
+
+    # Reads the body of a bracketed paste, having just read {PASTE_START}, and
+    # returns it {.normalize_paste}d:
+    #
+    #   Keys.getkey                    # => "\e[200~"
+    #   Keys.read_paste                # => "one\ntwo"   (terminator consumed)
+    #
+    # Reads **raw**, one byte at a time, rather than looping on {.getkey}: a
+    # pasted `\e` would send `getkey` gulping five bytes of the *payload* as an
+    # escape tail, surfacing them as phantom keypresses. One byte at a time is
+    # also what keeps the terminator from being over-read — nothing past
+    # {PASTE_END} is consumed, so typing that lands behind a paste survives.
+    #
+    # Blocks until the terminator arrives; returns what it has at EOF.
+    # @return [String] the pasted text, UTF-8, without the brackets.
+    def self.read_paste
+      buffer = +"".b
+      terminator = PASTE_END.b
+      until buffer.end_with?(terminator)
+        byte = $stdin.read(1)
+        break if byte.nil?
+
+        buffer << byte
+      end
+      buffer.delete_suffix!(terminator)
+      normalize_paste(buffer.force_encoding(Encoding::UTF_8))
+    end
+
+    # Rewrites a raw paste payload into the one convention callers see: `\n`
+    # line endings, valid UTF-8.
+    #
+    #   Keys.normalize_paste("a\r\nb\rc")   # => "a\nb\nc"
+    #
+    # Both are terminal-layer artifacts, not text: a terminal with bracketed
+    # paste *off* rewrites the clipboard's `\n` to `\r` so a paste looks like
+    # typing, and several keep doing it inside the brackets — so the byte a
+    # line break arrives as is not something a component should have to know.
+    # Invalid bytes are scrubbed to `U+FFFD`, which is what lets
+    # {Component#handle_paste} take any clipboard, a binary file included,
+    # without the grapheme-cluster walk raising downstream.
+    #
+    # Control characters other than `\n` are left alone: they are content, and
+    # what a *text buffer* may hold is {Component::AbstractStringField}'s call,
+    # not this layer's.
+    # @param text [String] raw payload.
+    # @return [String]
+    def self.normalize_paste(text) = text.scrub.gsub(/\r\n?/, "\n")
   end
 end

data/lib/tuile/screen.rb

@@ -14,10 +14,15 @@ module Tuile
   # Everything on screen hangs off {#pane} (a {ScreenPane}): the tiled
   # {#content} (set via {#content=}, filling the whole terminal and laying
   # out its own children), the modal/overlay {#popups} stack (opened via
-  # {Component::Popup#open}, drawn on top of the content), and the bottom
-  # status bar. Popups are *not* sized from their content — each carries its
-  # own top-down {Component::Popup#size} — and they deliberately overdraw the
-  # content without clipping.
+  # {Component::Popup#open}, drawn on top of the content). Popups are *not*
+  # sized from their content — each carries its own top-down
+  # {Component::Popup#size} — and they deliberately overdraw the content
+  # without clipping.
+  #
+  # Tuile draws no chrome of its own: there is no status bar and no reserved
+  # row, so {#content} gets the whole terminal. An app that wants a status line
+  # builds one into its own layout and drives it from {#on_focus_changed=}
+  # (`D-status-bar`).
   #
   # ## Repaint model
   #
@@ -69,8 +74,8 @@ module Tuile
       @color_scheme = detect_scheme
       @theme_def = ThemeDef.default
       @theme = @theme_def.for(@color_scheme)
-      # Structural root of the component tree: holds tiled content, popup
-      # stack and status bar.
+      # Structural root of the component tree: holds tiled content and the
+      # popup stack.
       @pane = ScreenPane.new
       @on_error = ->(e) { raise e }
       # App-level keyboard shortcuts dispatched by {#handle_key} before keys
@@ -82,10 +87,10 @@ module Tuile
       @buffer = Buffer.new(@size)
     end
 
-    # Entry in the global shortcut registry: the block to run, whether it
-    # pre-empts open popups, and an optional preformatted status-bar hint.
+    # Entry in the global shortcut registry: the block to run, and whether it
+    # pre-empts open popups.
     # @api private
-    Shortcut = Data.define(:block, :over_popups, :hint)
+    Shortcut = Data.define(:block, :over_popups)
     private_constant :Shortcut
 
     # Keys {#register_global_shortcut} refuses because every editable widget
@@ -193,12 +198,10 @@ module Tuile
     end
 
     # Replaces the theme and restyles the whole UI: fires
-    # {Component#on_theme_changed} across the attached tree, refreshes the
-    # status bar, and invalidates every attached component. No-op when
-    # `new_theme` equals the current theme. This is a *transient* override —
-    # the next OS appearance flip re-picks from {#theme_def}; assign {#theme_def=}
-    # for durable theming. Preformatted status-bar hints (see
-    # {#register_global_shortcut}) have their colors baked in and aren't restyled.
+    # {Component#on_theme_changed} across the attached tree and invalidates
+    # every attached component. No-op when `new_theme` equals the current theme.
+    # This is a *transient* override — the next OS appearance flip re-picks from
+    # {#theme_def}; assign {#theme_def=} for durable theming.
     # @param new_theme [Theme]
     # @return [void]
     def theme=(new_theme)
@@ -209,7 +212,6 @@ module Tuile
 
       @theme = new_theme
       @pane&.on_tree(&:on_theme_changed)
-      refresh_status_bar
       needs_full_repaint
     end
 
@@ -287,6 +289,7 @@ module Tuile
       end
 
       check_locked
+      previous = @focused
       if focused.nil?
         @focused = nil
         @pane.on_tree { _1.active = false }
@@ -303,45 +306,34 @@ module Tuile
         @pane.on_tree { _1.active = active.include?(_1) }
         @focused.on_focus
       end
-      refresh_status_bar
+      @on_focus_changed&.call unless @focused.equal?(previous)
     end
 
-    # Rebuild the status-bar text from the current focus and global-shortcut
-    # registry. Called from {#focused=} and whenever the global registry
-    # changes. Popups own their own "q Close" prefix in `#keyboard_hint`;
-    # for the tiled case Screen tacks on the global "q quit" instead.
-    # Global-shortcut hints get spliced in too — see {#global_shortcut_hints}
-    # for the over_popups filter rule.
-    # @api private
-    # @return [void]
-    def refresh_status_bar
-      top_popup = @pane.modal_popup
-      globals = global_shortcut_hints(popup_open: !top_popup.nil?)
-      @pane.status_bar.text = if top_popup.nil?
-                                ["q #{@theme.hint("quit")}", *globals,
-                                 active_window&.keyboard_hint].compact.reject(&:empty?).join("  ")
-                              else
-                                [*globals, top_popup.keyboard_hint].reject(&:empty?).join("  ")
-                              end
-    end
-    private :refresh_status_bar
-
-    # Status-bar hints from currently-registered global shortcuts.
-    # When a popup is open, only `over_popups: true` shortcuts contribute —
-    # the rest don't fire in that context, so showing them would be a lie.
-    # Insertion order is preserved (Hash iteration order).
-    # @api private
-    # @param popup_open [Boolean]
-    # @return [Array<String>]
-    def global_shortcut_hints(popup_open:)
-      @global_shortcuts.each_value.filter_map do |s|
-        next if s.hint.nil? || s.hint.empty?
-        next if popup_open && !s.over_popups
-
-        s.hint
-      end
-    end
-    private :global_shortcut_hints
+    # Called after the focused component *changes* — including to and from
+    # `nil`, and including the focus repair that runs when a popup closes.
+    # Takes no arguments; read {#focused} (and walk its `parent` chain) for the
+    # new state.
+    #
+    # This is the hook an app drives its own status line from. Tuile owns no
+    # status bar and reserves no row: build a {Component::Label} into your own
+    # layout and fill it here (`D-status-bar`).
+    #
+    #   screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
+    #
+    # **Edge-triggered**, like {Component#on_attached}: re-assigning the
+    # component that already has focus fires nothing, so a callback can be as
+    # expensive as rebuilding a hint string without a `did it really change?`
+    # guard of its own. That matters more than it looks — `ScreenPane#content=`
+    # clears focus on every content swap, which on a level-triggered hook would
+    # fire a nil→nil notification during assembly.
+    #
+    # It runs *after* the active-flag cascade and `on_focus`, so the tree is
+    # settled. Two things a callback must tolerate: {#focused} being `nil`, and
+    # firing during {#close} — teardown clears focus, exactly as it fires
+    # {Component#on_detached}. A raising callback propagates out of {#focused=}
+    # and leaves focus assigned; keep it trivial, as with the attach hooks.
+    # @return [Proc, nil]
+    attr_accessor :on_focus_changed
 
     # Internal — use {Component::Popup#open} instead. Adds the popup to
     # {#pane}, centers and focuses it.
@@ -370,9 +362,16 @@ module Tuile
     #   you want if the app benefits more from select-to-copy than from
     #   click-to-focus. Components' `handle_mouse` is simply never invoked
     #   from the loop in that mode (the terminal stops sending the bytes).
+    # @param bracketed_paste [Boolean] when true (default), enables DEC private
+    #   mode 2004 so pasted text arrives whole, as {Component#handle_paste},
+    #   instead of as one keystroke per character — which is the only way a
+    #   pasted line break can be told from a typed Enter. When false, a paste
+    #   streams in as keys again and a component that gives ENTER a meaning
+    #   fires it once per pasted line. Turn it off only for a terminal that
+    #   mishandles the mode.
     # @raise [Tuile::Error] if the screen is already {#close}d.
     # @return [void]
-    def run_event_loop(capture_mouse: true)
+    def run_event_loop(capture_mouse: true, bracketed_paste: true)
       raise Tuile::Error, "Screen is closed: cannot run the event loop" if @closed
 
       # The guard above stays outside the begin: teardown for a setup that never
@@ -381,6 +380,7 @@ module Tuile
       begin
         $stdin.echo = false
         print MouseEvent.start_tracking if capture_mouse
+        print Keys::BRACKETED_PASTE_ON if bracketed_paste
         # Follow OS light/dark flips live: terminals supporting mode 2031
         # push color-scheme reports that the key thread turns into
         # {EventQueue::ColorSchemeEvent}s.
@@ -390,6 +390,7 @@ module Tuile
         end
       ensure
         print TerminalBackground::NOTIFY_OFF
+        print Keys::BRACKETED_PASTE_OFF if bracketed_paste
         print MouseEvent.stop_tracking if capture_mouse
         print TTY::Cursor.show
         $stdin.echo = true
@@ -425,9 +426,7 @@ module Tuile
     # - **{EDITING_KEYS}** — `ENTER`, `BACKSPACE`, `DELETE` and the arrows,
     #   which every editable widget needs.
     #
-    #   screen.register_global_shortcut(Keys::CTRL_L,
-    #                                   over_popups: true,
-    #                                   hint: "^L #{screen.theme.hint("log")}") do
+    #   screen.register_global_shortcut(Keys::CTRL_L, over_popups: true) do
     #     log_popup.open
     #   end
     #
@@ -435,11 +434,9 @@ module Tuile
     # @param over_popups [Boolean] when true, fires even while a modal popup is
     #   open (pre-empting the popup); when false (default), suppressed while any
     #   popup is open so the popup gets the key.
-    # @param hint [String, nil] preformatted status-bar hint; nil (default) is
-    #   silent. Colors are baked in — re-register after a {#theme=} to recolor.
     # @yield invoked with no arguments when `key` is pressed.
     # @return [void]
-    def register_global_shortcut(key, over_popups: false, hint: nil, &block)
+    def register_global_shortcut(key, over_popups: false, &block)
       raise ArgumentError, "block required" if block.nil?
       raise ArgumentError, "key must be a String, got #{key.inspect}" unless key.is_a?(String)
       raise ArgumentError, "key cannot be empty" if key.empty?
@@ -461,10 +458,7 @@ module Tuile
               "button, handle ENTER in the form's own handle_key instead — a focused " \
               "TextArea/TextField gets first refusal there."
       end
-      raise ArgumentError, "hint must be a String or nil, got #{hint.inspect}" unless hint.nil? || hint.is_a?(String)
-
-      @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups, hint: hint)
-      refresh_status_bar
+      @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups)
     end
 
     # Removes a shortcut previously installed by {#register_global_shortcut}.
@@ -473,15 +467,6 @@ module Tuile
     # @return [void]
     def unregister_global_shortcut(key)
       @global_shortcuts.delete(key)
-      refresh_status_bar
-    end
-
-    # @return [Component, nil] current active tiled component.
-    def active_window
-      check_locked
-      result = nil
-      @pane.content&.on_tree { result = _1 if _1.is_a?(Component::Window) && _1.active? }
-      result
     end
 
     # Internal — use {Component::Popup#close} instead. Removes the popup
@@ -572,6 +557,26 @@ module Tuile
       Kernel.print(*args)
     end
 
+    # Rings the terminal bell ({Ansi::BEL}) — the signal for a keystroke that
+    # went nowhere, e.g. a letter matching no menu mnemonic while a menu is
+    # open.
+    #
+    #   return true if activate_mnemonic(key)
+    #
+    #   screen.beep   # no match: the key is swallowed, say so
+    #   true
+    #
+    # Writes **immediately** rather than riding the next frame: a beep is not
+    # part of a frame, and the keystrokes worth beeping at are precisely the
+    # ones that invalidate nothing, so {#repaint} may never emit at all. Whether
+    # the user hears anything is the terminal's setting to make, so there is no
+    # Tuile-level enable/disable knob.
+    # @return [void]
+    def beep
+      check_locked
+      print(Ansi::BEL)
+    end
+
     # Repaints the screen; tries to be as effective as possible, by only
     # considering invalidated components and flushing just the changed cells
     # of {#buffer}. Called once per event-loop tick (on {EventQueue::EmptyQueueEvent});
@@ -602,10 +607,9 @@ module Tuile
 
         # Build the repaint list in z-order, leaning on the tree itself rather
         # than a depth sort. The pane's pre-order traversal already orders the
-        # tiled layer (content subtree + status bar) parent-before-child; the
-        # popups are the top layer and must paint last. The status bar is a
-        # *late* pane child yet sits under the popups, so a single pane.on_tree
-        # walk won't do — we collect the tiled layer first, then append popups.
+        # tiled layer (the content subtree) parent-before-child; the popups are
+        # the top layer and must paint last, so we collect the tiled layer first
+        # and append popups rather than taking a single pane.on_tree walk.
         popup_members = Set.new
         popups.each { |p| p.on_tree { popup_members << _1 } }
 
@@ -770,6 +774,17 @@ module Tuile
     # @return [void]
     def handle_mouse(event) = @pane.handle_mouse(event)
 
+    # Delivers pasted text down the focus chain ({ScreenPane#handle_paste}).
+    #
+    # Deliberately *not* the key ladder: a paste is not a keystroke, so it
+    # skips Tab traversal and the global-shortcut registry entirely and goes
+    # straight to delivery. Unhandled text is dropped — there is no fallback
+    # that replays it as keys, which would put back the very ambiguity mode
+    # 2004 exists to remove.
+    # @param text [String]
+    # @return [Boolean] true if some component consumed it.
+    def handle_paste(text) = @pane.handle_paste(text)
+
     # @return [void]
     def event_loop
       @event_queue.run_loop do |event|
@@ -778,6 +793,8 @@ module Tuile
           key = event.key
           handled = handle_key(key)
           @event_queue.stop if !handled && ["q", Keys::ESC].include?(key)
+        when EventQueue::PasteEvent
+          handle_paste(event.text)
         when MouseEvent
           handle_mouse(event)
         when EventQueue::TTYSizeEvent