tuile 0.14.0 → 0.16.0

data/lib/tuile/mouse/router.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Tuile
+  module Mouse
+    # Delivers {Mouse::Event}s to the component tree. {Screen} owns one and hands
+    # it every event the terminal reports; a component only answers the handlers
+    # it calls, and walks nothing itself.
+    #
+    #   screen.handle_mouse(Mouse::DownEvent.new(:left, 5, 2))   # what the loop does
+    #
+    # Every event resolves against one **path**: the topmost popup containing the
+    # point, else the tiled content unless a modal popup is open
+    # ({ScreenPane#mouse_root_at}), then down through the shown children whose
+    # {Component#rect} contains it.
+    #
+    # - **{DownEvent}** — focuses the innermost {Component#focusable?} on that
+    #   path, then offers {Component#handle_mouse_down?} innermost-first until one
+    #   component answers `true`. That claimant becomes {#grabbed}.
+    # - **{ScrollEvent}**, **{MoveEvent}** — bubble the same way through
+    #   {Component#handle_mouse_scroll?} / {Component#handle_mouse_move?}, and grab
+    #   nothing. A move fires the enter/exit hooks first, and arrives only at
+    #   `:hover`.
+    # - **{DragEvent}**, **{UpEvent}** — skip the path entirely: they go to
+    #   {#grabbed}, wherever the pointer is, and an up ends the grab.
+    #
+    # The two geometries are deliberately different. Focus follows `rect`, so a
+    # press on the dead tail a widget does not paint still focuses it; the
+    # handlers bubble only along the prefix whose {Component#extent_rect} contains
+    # the point, so that same press activates nothing (`D_extent`).
+    #
+    # UI-thread-confined.
+    #
+    # == Implementation details
+    #
+    # **The grab has three releases and no relinquishing**: the up, the next
+    # down (the up was lost — ssh and tmux do lose them), and any key
+    # ({#release_grab}). None of the last two tells the grabbed component. Hiding
+    # or detaching it does not end the grab either; the router just stops
+    # delivering to it until the release (`D_mouse_dispatch`).
+    #
+    # **The hovered chain is synced, not toggled**: a move re-resolves it and
+    # diffs, and {#sync_hover} — run by {Screen#repaint} — drops members that
+    # were detached, hidden or reparented since, firing their exits.
+    class Router
+      # @param screen [Screen]
+      def initialize(screen)
+        @screen = screen
+        @level = :hover
+        @hovered = []
+        @grabbed = nil
+        @grab_button = nil
+      end
+
+      # The tracking level {Screen#run_event_loop} asked the terminal for, one of
+      # {Mouse::LEVELS}; `:hover` while no loop is running, so a spec may post
+      # anything. An ungrabbed move is dropped below `:hover` — under `:drag` the
+      # terminal reports one only while a button nobody claimed is held, and
+      # enter/exit that fire *sometimes* are worse than none.
+      # @return [Symbol, nil]
+      attr_accessor :level
+
+      # @return [Component, nil] the component whose {Component#handle_mouse_down?}
+      #   claimed the press currently held.
+      attr_reader :grabbed
+
+      # @return [Component, nil] the innermost component under the pointer, as of
+      #   the last move under `:hover`.
+      def hovered = @hovered.last
+
+      # @param event [Mouse::Event]
+      # @return [void]
+      def dispatch(event)
+        case event
+        when DownEvent then press(event)
+        when UpEvent then release(event)
+        when ScrollEvent then bubble(extent_path(event.point), :handle_mouse_scroll?, event)
+        when MoveEvent then move(event)
+        when DragEvent
+          # No route of its own: it is manufactured here from a move while
+          # something holds the grab, so a posted one can only be a mistake.
+          raise Tuile::Error,
+                "a Mouse::DragEvent is the router's own; post " \
+                "Mouse::MoveEvent.new(:#{event.button}, #{event.x}, #{event.y}) " \
+                "— or FakeScreen#drag — to drive a grabbed component"
+        else raise TypeError, "not a routable Mouse::Event: #{event.inspect}"
+        end
+      end
+
+      # Ends the grab without telling the grabbed component.
+      # @return [void]
+      def release_grab
+        @grabbed = nil
+        @grab_button = nil
+      end
+
+      # Drops the hovered-chain members that are no longer attached, shown, or
+      # children of the member before them, firing
+      # {Component#handle_mouse_exit} innermost first. Idempotent.
+      # @return [void]
+      def sync_hover
+        valid = @hovered.each_with_index.take_while do |c, i|
+          c.attached? && c.visible? && (i.zero? || c.parent.equal?(@hovered[i - 1]))
+        end.size
+        return if valid == @hovered.size
+
+        rehover(@hovered.take(valid))
+      end
+
+      private
+
+      # @param event [DownEvent]
+      # @return [void]
+      def press(event)
+        release_grab
+        point = event.point
+        pane = @screen.pane
+        root = pane.mouse_root_at(point)
+        path = rect_path(root, point)
+        pane.dismissing_popups_outside(point, left: event.button == :left) do
+          focus_innermost(root, path) if event.button == :left
+          claimant = bubble(path.take_while { _1.extent_rect.contains?(point) }, :handle_mouse_down?, event)
+          unless claimant.nil?
+            @grabbed = claimant
+            @grab_button = event.button
+          end
+        end
+      end
+
+      # @param event [UpEvent]
+      # @return [void]
+      def release(event)
+        grabbed = @grabbed
+        release_grab
+        grabbed.__send__(:handle_mouse_up, event) if reachable?(grabbed)
+      end
+
+      # @param event [MoveEvent]
+      # @return [void]
+      def move(event)
+        unless @grabbed.nil?
+          drag = DragEvent.new(@grab_button, event.x, event.y)
+          @grabbed.__send__(:handle_mouse_drag, drag) if reachable?(@grabbed)
+          return
+        end
+        return unless @level == :hover
+
+        path = extent_path(event.point)
+        rehover(path)
+        bubble(path, :handle_mouse_move?, event)
+      end
+
+      # A non-modal overlay is never focused into: it sits outside the key scope,
+      # so focus there would make every keystroke go dead (`D_overlay`).
+      # @param root [Component, nil]
+      # @param path [Array<Component>]
+      # @return [void]
+      def focus_innermost(root, path)
+        return if root.is_a?(Component::Overlay) && !root.modal?
+
+        target = path.reverse_each.find(&:focusable?)
+        @screen.focused = target unless target.nil? || target.active?
+      end
+
+      # @param path [Array<Component>] root first.
+      # @param handler [Symbol] a routed `handle_mouse_…?`.
+      # @param event [Mouse::Event]
+      # @return [Component, nil] the component that answered true.
+      def bubble(path, handler, event)
+        # A handler may detach what is below it on the path (a click that swaps
+        # a slot's occupant), so re-check before each delivery.
+        path.reverse_each.find { |c| c.attached? && c.__send__(handler, event) }
+      end
+
+      # @param point [Point]
+      # @return [Array<Component>] the shown components under `point` whose
+      #   extent contains it, root first.
+      def extent_path(point)
+        rect_path(@screen.pane.mouse_root_at(point), point).take_while { _1.extent_rect.contains?(point) }
+      end
+
+      # @param root [Component, nil]
+      # @param point [Point]
+      # @return [Array<Component>] the shown components whose rect contains
+      #   `point`, root first. Tiled siblings never overlap, so at most one child
+      #   qualifies at each level.
+      def rect_path(root, point)
+        path = []
+        component = root
+        while component&.visible? && component.rect.contains?(point)
+          path << component
+          component = component.children.find { _1.visible? && _1.rect.contains?(point) }
+        end
+        path
+      end
+
+      # @param chain [Array<Component>] the new hovered chain, root first.
+      # @return [void]
+      def rehover(chain)
+        old = @hovered
+        @hovered = chain
+        (old - chain).reverse_each { _1.__send__(:handle_mouse_exit) }
+        (chain - old).each { _1.__send__(:handle_mouse_enter) }
+      end
+
+      # @param component [Component, nil]
+      # @return [Boolean] whether `component` is attached and it and every
+      #   ancestor are shown.
+      def reachable?(component)
+        return false if component.nil? || !component.attached?
+
+        cursor = component
+        cursor = cursor.parent while cursor&.visible?
+        cursor.nil?
+      end
+    end
+  end
+end

data/lib/tuile/mouse.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Tuile
+  # The mouse: the events, their parser, and the tracking levels
+  # {Screen#run_event_loop} asks the terminal for. Who gets one is
+  # {Mouse::Router}'s story.
+  #
+  # Four of the five classes are what {.parse} reads off the wire; {DragEvent} is
+  # the router's own, a move while something holds the grab. Each is a
+  # `Data.define` including the {Event} marker — no inheritance, so a `case`
+  # matches either one class or `Mouse::Event` for all of them. Enter and exit
+  # have no class at all: nothing is parsed, they are the difference between two
+  # hovered chains.
+  #
+  # Coordinates are screen-absolute and 0-based everywhere.
+  module Mouse
+    # Included by every mouse event class: a marker for `case`/`is_a?`, plus the
+    # {#point} they share.
+    module Event
+      # @return [Point] the event's position.
+      def point = Point.new(x, y)
+    end
+
+    # A button went down.
+    #
+    # @!attribute [r] button
+    #   @return [Symbol] `:left`, `:middle` or `:right`.
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    DownEvent = Data.define(:button, :x, :y) { include Event }
+
+    # A button came up. **Deliberately no `button`**: an up reaches only the
+    # component that claimed the press, and that grab already knows which button
+    # it holds (`D_mouse_dispatch`).
+    #
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    UpEvent = Data.define(:x, :y) { include Event }
+
+    # One wheel notch. A notch is not a button, which is why this is not a
+    # {DownEvent}.
+    #
+    # @!attribute [r] direction
+    #   @return [Symbol] `:up`, `:down`, `:left` or `:right`.
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    ScrollEvent = Data.define(:direction, :x, :y) { include Event }
+
+    # The pointer moved and nothing holds the grab.
+    #
+    # @!attribute [r] button
+    #   @return [Symbol, nil] the button held while moving, or nil.
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    MoveEvent = Data.define(:button, :x, :y) { include Event }
+
+    # The pointer moved while a component holds the grab.
+    #
+    # The one event {Router} *makes* rather than routes, so posting one to
+    # {Screen#handle_mouse} raises: drive a grabbed component with a
+    # {MoveEvent} carrying the held button, or with {FakeScreen#drag}.
+    #
+    # @!attribute [r] button
+    #   @return [Symbol] the button whose press took the grab.
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column — may lie outside the grabbed
+    #     component's rect, and even outside the screen's last known size.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    DragEvent = Data.define(:button, :x, :y) { include Event }
+
+    # The `capture_mouse:` levels, each a strict superset of the one before, and
+    # each unlocking one tier of events: `:clicks` (mode 1000) gives
+    # down, up and scroll; `:drag` (1002) adds drag; `:hover` (1003) adds move,
+    # enter and exit (`R_mouse_reporting`).
+    # @return [Array<Symbol>]
+    LEVELS = %i[clicks drag hover].freeze
+
+    # @return [Hash{Symbol => Integer}] the DEC private mode each level sets.
+    MODES = { clicks: 1000, drag: 1002, hover: 1003 }.freeze
+    private_constant :MODES
+
+    # X10 button code layout: `button | 4 shift | 8 meta | 16 ctrl | 32 motion |
+    # 64 wheel`, button 3 meaning "released" (`R_mouse_reporting`).
+    # @return [Integer]
+    MODIFIER_BITS = 4 | 8 | 16
+    private_constant :MODIFIER_BITS
+
+    class << self
+      # Normalizes a `capture_mouse:` argument to a level.
+      # @param capture_mouse [Boolean, Symbol] `false`, `true` (== `:clicks`),
+      #   or one of {LEVELS}.
+      # @return [Symbol, nil] the level; nil when tracking is off.
+      # @raise [ArgumentError] on anything else.
+      def level(capture_mouse)
+        case capture_mouse
+        when false, nil then nil
+        when true then :clicks
+        when *LEVELS then capture_mouse
+        else
+          raise ArgumentError,
+                "capture_mouse: expected true, false or one of #{LEVELS}, got #{capture_mouse.inspect}"
+        end
+      end
+
+      # @param level [Symbol] one of {LEVELS}.
+      # @return [String] the escape enabling that level.
+      def start_tracking(level) = "\e[?#{MODES.fetch(level)}h"
+
+      # @param level [Symbol] one of {LEVELS}.
+      # @return [String] the escape disabling that level.
+      def stop_tracking(level) = "\e[?#{MODES.fetch(level)}l"
+
+      # Whether `key` is a mouse report. 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]
+      def report?(key) = key.start_with?("\e[M")
+
+      # Parses an X10 mouse report (`\e[M` + 3 bytes: button, x, y) into one of
+      # {DownEvent}, {UpEvent}, {ScrollEvent} or {MoveEvent}. Modifier bits are
+      # ignored.
+      #
+      # 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 [Event, nil] `nil` if `key` is not a mouse report, or reports
+      #   a wheel button beyond the four directions.
+      # @raise [Tuile::Error] if `key` is a malformed mouse report
+      def parse(key)
+        return nil unless report?(key)
+        unless key.bytesize == 6
+          raise Tuile::Error,
+                "malformed mouse event: expected 6 bytes after \\e[M prefix, got #{key.bytesize}: #{key.inspect}"
+        end
+
+        code = (key[3].ord - 32) & ~MODIFIER_BITS
+        # XTerm reports coordinates 1-based (column N is encoded as N + 32);
+        # subtract 33 so that `x` and `y` are 0-based.
+        x = key[4].ord - 33
+        y = key[5].ord - 33
+        low = code & 3
+        if code.anybits?(64)
+          direction = %i[up down left right][low]
+          direction && ScrollEvent.new(direction, x, y)
+        elsif code.anybits?(32)
+          MoveEvent.new(button(low), x, y)
+        elsif low == 3
+          UpEvent.new(x, y)
+        else
+          DownEvent.new(button(low), x, y)
+        end
+      end
+
+      private
+
+      # @param low [Integer] the code's two low bits.
+      # @return [Symbol, nil]
+      def button(low) = %i[left middle right][low]
+    end
+  end
+end