tuile 0.3.0 → 0.5.0

data/lib/tuile/component/window.rb

@@ -8,8 +8,9 @@ module Tuile
     #
     # The window's `content` is unset by default; assign one via {#content=}.
     #
-    # Window is considered invisible if {#rect} is empty or one of left/top is
-    # negative. The window won't draw when invisible.
+    # Window is considered invisible if {#rect} is empty. The window won't
+    # draw when invisible. (Repaint of detached windows is short-circuited
+    # by {Component#invalidate}; subclasses don't need to re-check.)
     class Window < Component
       include Component::HasContent
 
@@ -125,12 +126,6 @@ module Tuile
         Size.new(inner_w + 2, inner_h + 2)
       end
 
-      # @return [Boolean] true if {#rect} is off screen and the window won't
-      #   paint.
-      def visible?
-        !@rect.empty? && !@rect.top.negative? && !@rect.left.negative?
-      end
-
       # Fully repaints the window: both frame and contents.
       #
       # Window deliberately paints over its entire rect (border around the
@@ -143,7 +138,7 @@ module Tuile
       # cycle.
       # @return [void]
       def repaint
-        return unless visible?
+        return if rect.empty?
 
         super
         repaint_border
@@ -168,7 +163,7 @@ module Tuile
       # Paints the window border.
       # @return [void]
       def repaint_border
-        return unless visible?
+        return if rect.empty?
 
         frame = build_frame(frame_caption)
         frame = Rainbow(frame).green if active?

data/lib/tuile/component.rb

@@ -4,8 +4,10 @@ module Tuile
   # A UI component which is positioned on the screen and draws characters into
   # its bounding rectangle (in {#repaint}).
   #
-  # Component is considered invisible if {#rect} is empty or one of left/top is
-  # negative. The component won't draw when invisible.
+  # Painting is gated by attachment: a detached component (one whose {#root}
+  # isn't {Screen#pane}) is never enqueued for repaint via {#invalidate}, and
+  # any stale invalidation entries are filtered out at drain time. Subclasses
+  # can paint freely in {#repaint} without re-asserting attachment.
   class Component
     def initialize
       @rect = Rect.new(0, 0, 0, 0)
@@ -66,9 +68,11 @@ module Tuile
     # responsibility for {#rect}. Everything else should call super.
     #
     # A component must not draw outside of {#rect}.
+    #
+    # Only called when the component is attached.
     # @return [void]
     def repaint
-      return if rect.empty? || rect.left.negative? || rect.top.negative?
+      return if rect.empty?
       return if children.any? && children_tile_rect?
 
       clear_background
@@ -251,8 +255,16 @@ module Tuile
 
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
+    #
+    # No-op when the component is not {#attached?} — a detached component has
+    # no place on the screen to paint to, so {Screen} must never end up
+    # repainting it. Callers don't need to guard their own `invalidate` calls;
+    # mutating a detached component (e.g. setting `lines=` on a {List} sitting
+    # inside a closed {Component::Popup}) is silent.
     # @return [void]
     def invalidate
+      return unless attached?
+
       screen.invalidate(self)
     end
 

data/lib/tuile/event_queue.rb

@@ -47,17 +47,56 @@ module Tuile
       latch.wait
     end
 
+    # Schedules `block` to fire on the event-loop thread roughly `fps` times
+    # per second, passing a 0-based monotonically increasing tick counter. Use
+    # it for animations (e.g. a `/-\|` spinner in a {Component::Label}) or
+    # periodic UI refresh from a background task.
+    #
+    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
+    # stop it.
+    #
+    # **Errors:** if `block` raises, the {Ticker} cancels itself and the
+    # exception flows through the normal event-loop error path — i.e.
+    # {Screen#on_error} for the default Tuile setup. Auto-cancel prevents a
+    # broken block from spamming `on_error` at the tick rate.
+    #
+    # Tickers reuse `concurrent-ruby`'s shared timer thread
+    # ({Concurrent}.global_timer_set) — adding more tickers does not add more
+    # threads, just more work on the shared scheduler.
+    #
+    # @param fps [Numeric] firings per second, must be positive. Fractional
+    #   values are fine (`fps: 0.5` ⇒ one tick every two seconds).
+    # @yield [tick] called on the event-loop thread each firing.
+    # @yieldparam tick [Integer] 0-based monotonically increasing counter.
+    # @yieldreturn [void]
+    # @return [Ticker]
+    def tick(fps, &block)
+      raise ArgumentError, "block required" unless block
+      unless fps.is_a?(Numeric) && fps.positive?
+        raise ArgumentError, "fps must be a positive Numeric, got #{fps.inspect}"
+      end
+
+      Ticker.new(self, fps, block)
+    end
+
     # Runs the event loop and blocks. Must be run from at most one thread at the
     # same time. Blocks until some thread calls {#stop}. Calls block for all
-    # events submitted via {#post}; the block is always called from the thread
-    # running this function.
+    # events; the block is always called from the thread running this function.
     #
-    # Any exception raised by block is re-thrown, causing this function to
-    # terminate.
-    # @yield [event] called for each non-internal event.
+    # Any exception raised by the block is re-thrown, causing this function to
+    # terminate. Wrap the block body in `rescue` if you want to handle errors
+    # without tearing down the loop — see {Screen#event_loop} for an example.
+    #
+    # **Procs are yielded too.** A {#submit}ed block arrives as a `Proc` event;
+    # the consumer is responsible for invoking it (typically `event.call`).
+    # Yielding rather than dispatching inline means a raise inside the
+    # submitted block flows through the consumer's `rescue` like any other
+    # event-handler error, instead of bypassing it.
+    # @yield [event] called for each posted event.
     # @yieldparam event [Object] a posted event — typically a {KeyEvent},
-    #   {MouseEvent}, {TTYSizeEvent}, {EmptyQueueEvent}, or any object pushed
-    #   via {#post}.
+    #   {MouseEvent}, {TTYSizeEvent}, {EmptyQueueEvent}, a `Proc` from {#submit},
+    #   or any object pushed via {#post}. {ErrorEvent}s are not yielded — they
+    #   terminate the loop directly.
     # @yieldreturn [void]
     # @return [void]
     def run_loop(&)
@@ -152,6 +191,64 @@ module Tuile
       include Singleton
     end
 
+    # Handle returned by {EventQueue#tick}. Cancel a running ticker via
+    # {#cancel}.
+    #
+    # Internally wraps a `Concurrent::TimerTask` whose firing posts a single
+    # submit-block to the owning {EventQueue}; the user's block therefore
+    # always runs on the event-loop thread and may freely mutate UI. If the
+    # user block raises, the Ticker auto-cancels and the exception is
+    # re-raised so it flows through the loop's normal error handling
+    # ({Screen#on_error} for the default Tuile setup).
+    class Ticker
+      # @param event_queue [EventQueue] queue to dispatch tick calls onto.
+      # @param fps [Numeric] firings per second (positive).
+      # @param block [Proc] called as `block.call(tick_count)` on each fire.
+      def initialize(event_queue, fps, block)
+        @event_queue = event_queue
+        @block = block
+        @tick = 0
+        # AtomicBoolean rather than a plain ivar: cancel may run on any
+        # thread (caller code, the event-loop thread from inside the block,
+        # or the IO executor on an error path), and we want both a CAS-style
+        # one-shot guard against double-shutdown and well-defined visibility
+        # on non-MRI Rubies.
+        @cancelled = Concurrent::AtomicBoolean.new(false)
+        @timer = Concurrent::TimerTask.new(execution_interval: 1.0 / fps) do
+          @event_queue.submit { fire }
+        end
+        @timer.execute
+      end
+
+      # @return [Boolean] true once {#cancel} has been called.
+      def cancelled? = @cancelled.true?
+
+      # Stops the ticker. Idempotent and safe to call from any thread,
+      # including from inside the tick block. Any tick already queued on the
+      # event loop at the moment of cancellation is dropped before the user
+      # block runs.
+      # @return [void]
+      def cancel
+        return unless @cancelled.make_true # CAS: only the winner shuts down
+
+        @timer.shutdown
+      end
+
+      private
+
+      # Runs on the event-loop thread.
+      # @return [void]
+      def fire
+        return if @cancelled.true?
+
+        @block.call(@tick)
+        @tick += 1
+      rescue StandardError
+        cancel
+        raise
+      end
+    end
+
     private
 
     # @return [void]
@@ -169,8 +266,6 @@ module Tuile
             # while the loop's own backtrace shows up in the wrapper.
             raise Tuile::Error, "background event raised: #{event.error.class}: #{event.error.message}"
           end
-        elsif event.is_a? Proc
-          event.call
         else
           yield event
         end

data/lib/tuile/fake_event_queue.rb

@@ -4,6 +4,10 @@ module Tuile
   # A "synchronous" event queue – no loop is run, submitted blocks are run right
   # away and submitted events are thrown away. Intended for testing only.
   class FakeEventQueue
+    def initialize
+      @tickers = []
+    end
+
     # @return [Boolean]
     def locked? = true
     # @return [void]
@@ -27,5 +31,70 @@ module Tuile
     # @param event [Object]
     # @return [void]
     def post(event); end
+
+    # Mirrors {EventQueue#tick} but timeless: returns a {FakeTicker} that
+    # only fires when a test calls {#tick_once}. The `fps` argument is
+    # validated the same way the real queue validates it, then discarded —
+    # the fake has no clock, so frame cadence is up to the test.
+    #
+    # @param fps [Numeric] firings per second, must be positive. Validated
+    #   for parity with {EventQueue#tick}; otherwise unused.
+    # @yield [tick] called on each {#tick_once}.
+    # @yieldparam tick [Integer] 0-based monotonically increasing counter.
+    # @yieldreturn [void]
+    # @return [FakeTicker]
+    def tick(fps, &block)
+      raise ArgumentError, "block required" unless block
+      unless fps.is_a?(Numeric) && fps.positive?
+        raise ArgumentError, "fps must be a positive Numeric, got #{fps.inspect}"
+      end
+
+      FakeTicker.new(block).tap { |t| @tickers << t }
+    end
+
+    # Test helper: fires every live ticker's user block once and prunes
+    # cancelled tickers. No-op when no tickers are registered. Pumps once
+    # per call regardless of any ticker's fps — the fake has no clock, so
+    # tests pump N frames by calling this N times.
+    # @return [void]
+    def tick_once
+      @tickers.reject!(&:cancelled?)
+      @tickers.each(&:fire)
+    end
+
+    # Handle returned by {FakeEventQueue#tick}. Mirrors the public surface of
+    # {EventQueue::Ticker} (`cancel`, `cancelled?`) but does not auto-fire —
+    # the host {FakeEventQueue} drives firing via {FakeEventQueue#tick_once}.
+    class FakeTicker
+      # @param block [Proc] called as `block.call(tick_count)` on each {#fire}.
+      def initialize(block)
+        @block = block
+        @tick = 0
+        @cancelled = false
+      end
+
+      # @return [Boolean] true once {#cancel} has been called.
+      def cancelled? = @cancelled
+
+      # Marks the ticker cancelled. Idempotent. Subsequent {#fire} calls are
+      # no-ops; {FakeEventQueue#tick_once} also prunes the ticker on its next
+      # pass.
+      # @return [void]
+      def cancel
+        @cancelled = true
+      end
+
+      # Invokes the user block with the current tick counter, then advances.
+      # No-op when {#cancelled?}. Typically driven by
+      # {FakeEventQueue#tick_once}; safe to call directly from a test that
+      # wants to drive a single ticker.
+      # @return [void]
+      def fire
+        return if @cancelled
+
+        @block.call(@tick)
+        @tick += 1
+      end
+    end
   end
 end

data/lib/tuile/keys.rb

@@ -42,19 +42,71 @@ module Tuile
     # @return [String]
     PAGE_DOWN = "\e[6~"
     # @return [String]
-    BACKSPACE = ""
+    BACKSPACE = "\x7f"
     # @return [String]
     DELETE = "\e[3~"
+
+    # Ctrl+letter sends bytes 0x01..0x1a. Note that {CTRL_H} == `"\b"`,
+    # {CTRL_I} == {TAB}, {CTRL_J} == `"\n"`, and {CTRL_M} == {ENTER} —
+    # terminals deliver these key combinations indistinguishably from the
+    # corresponding named keys.
+    # @return [String]
+    CTRL_A = "\x01"
+    # @return [String]
+    CTRL_B = "\x02"
+    # @return [String]
+    CTRL_C = "\x03"
+    # @return [String]
+    CTRL_D = "\x04"
+    # @return [String]
+    CTRL_E = "\x05"
+    # @return [String]
+    CTRL_F = "\x06"
+    # @return [String]
+    CTRL_G = "\x07"
     # @return [String]
     CTRL_H = "\b"
-    # @return [Array<String>]
-    BACKSPACES = [BACKSPACE, CTRL_H].freeze
     # @return [String]
-    CTRL_U = ""
+    CTRL_I = "\t"
+    # @return [String]
+    CTRL_J = "\n"
+    # @return [String]
+    CTRL_K = "\x0b"
+    # @return [String]
+    CTRL_L = "\x0c"
+    # @return [String]
+    CTRL_M = "\r"
+    # @return [String]
+    CTRL_N = "\x0e"
+    # @return [String]
+    CTRL_O = "\x0f"
+    # @return [String]
+    CTRL_P = "\x10"
     # @return [String]
-    CTRL_D = ""
+    CTRL_Q = "\x11"
     # @return [String]
-    ENTER = "
+    CTRL_R = "\x12"
+    # @return [String]
+    CTRL_S = "\x13"
+    # @return [String]
+    CTRL_T = "\x14"
+    # @return [String]
+    CTRL_U = "\x15"
+    # @return [String]
+    CTRL_V = "\x16"
+    # @return [String]
+    CTRL_W = "\x17"
+    # @return [String]
+    CTRL_X = "\x18"
+    # @return [String]
+    CTRL_Y = "\x19"
+    # @return [String]
+    CTRL_Z = "\x1a"
+
+    # @return [Array<String>]
+    BACKSPACES = [BACKSPACE, CTRL_H].freeze
+    # @return [String]
+    ENTER = "\r"
     # @return [String]
     TAB = "\t"
     # The terminal sequence emitted by Shift+Tab in xterm-style terminals
@@ -62,6 +114,22 @@ module Tuile
     # @return [String]
     SHIFT_TAB = "\e[Z"
 
+    # 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
+    # ({TAB}, {ENTER}, {ESC}, {CTRL_A}..{CTRL_Z}, {BACKSPACE}), and the empty
+    # string; accepts ASCII letters/digits/punctuation/space *and* non-ASCII
+    # printables like "é".
+    #
+    # Used by {Screen#register_global_shortcut} to reject keys that would
+    # collide with typing, and by {Tuile::Component::TextField} to decide
+    # whether to insert a key at the caret.
+    # @param key [String]
+    # @return [Boolean]
+    def self.printable?(key)
+      key.length == 1 && !key.match?(/\p{C}/)
+    end
+
     # Grabs a key from stdin and returns it. Blocks until the key is obtained.
     # Reads a full ESC key sequence; see constants above for some values returned
     # by this function.
@@ -72,11 +140,26 @@ module Tuile
 
       # Escape sequence. Try to read more data.
       begin
-        # Read 6 chars: mouse events are e.g. `\e[Mxyz`
-        char += $stdin.read_nonblock(6)
+        # Read up to 5 bytes: that's the maximum tail length of any escape
+        # sequence Tuile recognizes after the initial \e (X10 mouse `[Mbxy`,
+        # CTRL+arrow `[1;5D`, etc.). Reading 6 here would over-read into the
+        # next sequence on tight mouse-event bursts — we'd silently steal
+        # the next event's leading \e and the rest of it would surface as
+        # individual printable keypresses in focused inputs.
+        char += $stdin.read_nonblock(5)
       rescue IO::EAGAINWaitReadable
         # The "ESC" key pressed => only the \e char is emitted.
+        return char
+      end
+
+      # If `read_nonblock` returned a partial X10 mouse-report prefix (the
+      # sequence is fixed-length: 3 bytes after `\e[M`), drain the remainder
+      # with a blocking read so the parser downstream sees a complete event
+      # instead of leaking tail bytes as keypresses.
+      if char.start_with?("\e[M") && char.bytesize < 6
+        char += $stdin.read(6 - char.bytesize)
       end
+
       char
     end
   end

data/lib/tuile/mouse_event.rb

@@ -5,7 +5,7 @@ module Tuile
   #
   # @!attribute [r] button
   #   @return [Symbol, nil] one of `:left`, `:middle`, `:right`, `:scroll_up`,
-  #     `:scroll_down`; `nil` if not known.
+  #     `:scroll_down`, `:scroll_left`, `:scroll_right`; `nil` if not known.
   # @!attribute [r] x
   #   @return [Integer] x coordinate, 0-based.
   # @!attribute [r] y
@@ -14,17 +14,34 @@ module Tuile
     # @return [Point] the event's position.
     def point = Point.new(x, y)
 
-    # Checks whether given key is a mouse event key
+    # Checks whether given key is a mouse event key. Returns true on the X10
+    # `\e[M` prefix regardless of length — {.parse} is the place that
+    # validates the full 6-byte shape and raises on malformed input.
     # @param key [String] key read via {Keys.getkey}
     # @return [Boolean] true if it is a mouse event
     def self.mouse_event?(key)
-      key.start_with?("\e[M") && key.size >= 6
+      key.start_with?("\e[M")
     end
 
+    # Parses an X10 mouse report (`\e[M` + 3 bytes: button, x, y).
+    #
+    # Raises {Tuile::Error} when `key` starts with the mouse prefix but is
+    # not exactly 6 bytes long. Both shorter and longer inputs are bugs in
+    # the upstream key-reader: a shorter prefix means the tail was lost on
+    # the way in, and a longer one means we over-consumed into the next
+    # escape sequence. We refuse to silently truncate either case because
+    # the trailing `\e` of an over-read corrupts the *next* getkey, and the
+    # corruption then surfaces as garbled keystrokes in focused inputs
+    # rather than as a parser failure pointing at the actual cause.
     # @param key [String] key read via {Keys.getkey}
-    # @return [MouseEvent, nil]
+    # @return [MouseEvent, nil] `nil` if `key` is not a mouse event
+    # @raise [Tuile::Error] if `key` is a malformed mouse event
     def self.parse(key)
       return nil unless mouse_event?(key)
+      unless key.bytesize == 6
+        raise Tuile::Error,
+              "malformed mouse event: expected 6 bytes after \\e[M prefix, got #{key.bytesize}: #{key.inspect}"
+      end
 
       button = key[3].ord - 32
       # XTerm reports coordinates 1-based (column N is encoded as N + 32);
@@ -37,6 +54,8 @@ module Tuile
                when 1 then :middle
                when 64 then :scroll_up
                when 65 then :scroll_down
+               when 66 then :scroll_left
+               when 67 then :scroll_right
                end
       MouseEvent.new(button, x, y)
     end