tuile 0.1.0

data/lib/tuile/component.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+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.
+  class Component
+    def initialize
+      @rect = Rect.new(0, 0, 0, 0)
+      @active = false
+    end
+
+    # @return [Rect] the rectangle the component occupies on screen.
+    attr_reader :rect
+
+    # Sets new position of the component. This is the absolute component
+    # positioning on screen, not a relative positioning relative to component's
+    # {#parent}.
+    #
+    # The component must not stick outside of {#parent}'s rect.
+    #
+    # The component is invalidated and will paint over the new rectangle. It is
+    # parent's job to paint over the old component position.
+    # @param new_rect [Rect] new position. Does nothing if the new rectangle is
+    #   the same as the old one.
+    def rect=(new_rect)
+      raise TypeError, "expected Rect, got #{new_rect.inspect}" unless new_rect.is_a? Rect
+      return if @rect == new_rect
+
+      prev_width = @rect.width
+      @rect = new_rect
+      on_width_changed if prev_width != new_rect.width
+      invalidate
+    end
+
+    # @return [Screen] the screen which owns this component.
+    def screen = Screen.instance
+
+    # Focuses this component. Equivalent to `screen.focused = self`.
+    # @return [void]
+    def focus
+      screen.focused = self
+    end
+
+    # Repaints the component. Default implementation does nothing.
+    #
+    # The component must fully draw over {#rect}, and must not draw outside of
+    # {#rect}.
+    #
+    # Tip: use {#clear_background} to clear component background before painting.
+    # @return [void]
+    def repaint; end
+
+    # Called when a character is pressed on the keyboard.
+    #
+    # Also called for inactive components. Inactive component should just return
+    # false.
+    #
+    # Default implementation searches for a component with {#key_shortcut} and
+    # focuses it. The shortcut search is suppressed while the focused component
+    # owns the hardware cursor (e.g. a {Component::TextField} the user is
+    # typing into) so that hotkeys don't steal printable keys from the editor.
+    # @param key [String] a key.
+    # @return [Boolean] true if the key was handled, false if not.
+    def handle_key(key)
+      return false unless screen.cursor_position.nil?
+
+      c = find_shortcut_component(key)
+      if !c.nil?
+        screen.focused = c
+        true
+      else
+        false
+      end
+    end
+
+    # A global keyboard shortcut. When pressed, will focus this component.
+    # @return [String, nil] shortcut, `nil` by default.
+    attr_accessor :key_shortcut
+
+    # @param key [String] keyboard key to look up.
+    # @return [Component, nil] the component whose {#key_shortcut} matches `key`,
+    #   or nil.
+    def find_shortcut_component(key)
+      return self if key_shortcut == key
+
+      children.each do |child|
+        sc = child.find_shortcut_component(key)
+        return sc unless sc.nil?
+      end
+      nil
+    end
+
+    # Handles mouse event. Default implementation focuses this component when
+    # clicked (if {#focusable?}).
+    # @param event [MouseEvent]
+    # @return [void]
+    def handle_mouse(event)
+      screen.focused = self unless event.button != :left || active? || !focusable?
+    end
+
+    # @return [Boolean] true if the component is on the active chain — i.e. it
+    #   is the focused component or an ancestor of it. Set by {Screen#focused=}.
+    def active? = @active
+
+    # @param active [Boolean] true if active. Set by {Screen#focused=} as it
+    #   marks the focus chain (root → focused); not meant to be called directly.
+    # @return [void]
+    def active=(active)
+      active = active ? true : false
+      return unless @active != active
+
+      @active = active
+      invalidate
+    end
+
+    # Whether this component is a valid focus target. `false` by default —
+    # passive components like {Label} are decoration and don't accept focus.
+    # The flag gates click-to-focus ({#handle_mouse}) and the focus-cascade
+    # in container components ({HasContent#on_focus}, {Layout#on_focus}).
+    # Independent from {#active?}: every component carries the active flag, but
+    # only focusable ones can become a focus target that puts themselves and
+    # their ancestors on the active chain.
+    # @return [Boolean] true if this component can be focused.
+    def focusable? = false
+
+    # @return [Component, nil] the parent component or nil if the component has
+    #   no parent.
+    attr_reader :parent
+
+    # @return [Integer] the distance from the root component; 0 if {#parent}
+    #   is nil.
+    def depth = parent.nil? ? 0 : parent.depth + 1
+
+    # @return [Component] the root component of this component hierarchy.
+    def root = parent.nil? ? self : parent.root
+
+    # List of child components, defaults to an empty array.
+    # @return [Array<Component>] child components. Must not be mutated! May be
+    #   empty.
+    def children = []
+
+    # Calls block for this component and for every descendant component.
+    # @yield [component]
+    # @yieldparam component [Component]
+    # @yieldreturn [void]
+    # @return [void]
+    def on_tree(&block)
+      block.call(self)
+      children.each { it.on_tree(&block) }
+    end
+
+    # Called when the component receives focus.
+    # @return [void]
+    def on_focus; end
+
+    # @return [Boolean] true if this component's tree is currently mounted on
+    #   the {Screen}, i.e. its root is the {ScreenPane}.
+    def attached? = root == screen.pane
+
+    # Called by container components after `child` has been detached from
+    # `self.children` (its `parent` is already nil and it is no longer in the
+    # children list). Default behavior repairs dangling focus: if the focused
+    # component lived inside the removed subtree, focus shifts to `self` so the
+    # cursor doesn't dangle on a detached component. No-op if `self` is not
+    # attached to the screen — focus state in a detached subtree is moot.
+    # @param child [Component] the just-detached child.
+    # @return [void]
+    def on_child_removed(child)
+      return unless attached?
+
+      f = screen.focused
+      return if f.nil?
+
+      cursor = f
+      until cursor.nil?
+        if cursor == child
+          screen.focused = self
+          return
+        end
+        cursor = cursor.parent
+      end
+    end
+
+    # The {Size} big enough to show the entire component contents without
+    # scrolling. Plain components have no intrinsic content and report
+    # {Size::ZERO}; container/decorative components (e.g. {Label}, {List},
+    # {Layout}, {Window}) override this to fold in their content's natural
+    # extent. Used by callers like {Component::Popup} to auto-size to
+    # whatever content was assigned, regardless of its concrete type.
+    # @return [Size]
+    def content_size = Size::ZERO
+
+    # Where the hardware terminal cursor should sit when this component is the
+    # cursor owner. Returns `nil` to indicate the cursor should be hidden. The
+    # {Screen} positions the hardware cursor after each repaint cycle by
+    # consulting the {Screen#focused} component only.
+    # @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
+
+    # @param parent [Component, nil]
+    attr_writer :parent
+
+    # Called whenever the component width changes. Does nothing by default.
+    # @return [void]
+    def on_width_changed; end
+
+    # Invalidates the component: {Screen} records this component as
+    # needs-repaint and once all events are processed, will call {#repaint}.
+    # @return [void]
+    def invalidate
+      screen.invalidate(self)
+    end
+
+    # Clears the background: prints spaces into all characters occupied by the
+    # component's rect.
+    # @return [void]
+    def clear_background
+      return if rect.empty?
+
+      spaces = " " * rect.width
+      (rect.top..(rect.top + rect.height - 1)).each do |row|
+        screen.print TTY::Cursor.move_to(rect.left, row), spaces
+      end
+    end
+  end
+end

data/lib/tuile/event_queue.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Tuile
+  # An event queue. The idea is that all UI-related updates run from the thread
+  # which runs the event queue only; this removes any need for locking and/or
+  # need for thread-safety mechanisms.
+  #
+  # Any events (keypress, timer, term resize – WINCH) are captured in background
+  # threads; instead of processing the events directly the events are pushed
+  # into the event queue: this causes the events to be processed centrally,
+  # by a single thread only.
+  class EventQueue
+    # @param listen_for_keys [Boolean] if true, fires {KeyEvent}.
+    def initialize(listen_for_keys: true)
+      @queue = Thread::Queue.new
+      @listen_for_keys = listen_for_keys
+      @run_lock = Mutex.new
+    end
+
+    # Posts event into the event queue. The event may be of any type. Since the
+    # event is passed between threads, the event object should be frozen.
+    #
+    # The function may be called from any thread.
+    # @param event [Object] the event to post to the queue, should be frozen.
+    # @return [void]
+    def post(event)
+      raise ArgumentError, "event passed across threads must be frozen, got #{event.inspect}" unless event.frozen?
+
+      @queue << event
+    end
+
+    # Submits block to be run in the event queue. Returns immediately.
+    #
+    # The function may be called from any thread.
+    # @yield called from the event-loop thread.
+    # @yieldreturn [void]
+    # @return [void]
+    def submit(&block)
+      @queue << block
+    end
+
+    # Awaits until the event queue is empty (all events have been processed).
+    # @return [void]
+    def await_empty
+      latch = Concurrent::CountDownLatch.new(1)
+      submit { latch.count_down }
+      latch.wait
+    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.
+    #
+    # Any exception raised by block is re-thrown, causing this function to
+    # terminate.
+    # @yield [event] called for each non-internal event.
+    # @yieldparam event [Object] a posted event — typically a {KeyEvent},
+    #   {MouseEvent}, {TTYSizeEvent}, {EmptyQueueEvent}, or any object pushed
+    #   via {#post}.
+    # @yieldreturn [void]
+    # @return [void]
+    def run_loop(&)
+      raise ArgumentError, "run_loop requires a block" unless block_given?
+
+      @run_lock.synchronize do
+        start_key_thread if @listen_for_keys
+        begin
+          trap_winch
+          event_loop(&)
+        ensure
+          Signal.trap("WINCH", "SYSTEM_DEFAULT")
+          @key_thread&.kill
+          @queue.clear
+        end
+      end
+    end
+
+    # @return [Boolean] true if this thread is running inside an event queue.
+    def locked? = @run_lock.owned?
+
+    # Stops ongoing {#run_loop}. The stop may not be immediate: {#run_loop} may
+    # process a bunch of events before terminating.
+    #
+    # Can be called from any thread, including the thread which runs the event
+    # loop.
+    # @return [void]
+    def stop
+      @queue.clear
+      post(nil)
+    end
+
+    # A keypress event. See {Keys} for a list of key codes.
+    #
+    # @!attribute [r] key
+    #   @return [String] key code.
+    class KeyEvent < Data.define(:key)
+    end
+
+    # An error event, causes {EventQueue#run_loop} to throw `StandardError` with
+    # {#error} as its origin.
+    #
+    # @!attribute [r] error
+    #   @return [StandardError] the underlying error.
+    class ErrorEvent < Data.define(:error)
+    end
+
+    # TTY has been resized. Contains the current width and height of the TTY
+    # terminal.
+    #
+    # @!attribute [r] width
+    #   @return [Integer] terminal width in columns.
+    # @!attribute [r] height
+    #   @return [Integer] terminal height in rows.
+    class TTYSizeEvent < Data.define(:width, :height)
+      # @param width [Integer]
+      # @param height [Integer]
+      def initialize(width:, height:)
+        super
+        return unless !width.is_a?(Integer) || !height.is_a?(Integer) || width.negative? || height.negative?
+
+        raise ArgumentError, "TTY size must be non-negative integers, got #{width.inspect} x #{height.inspect}"
+      end
+
+      # @return [TTYSizeEvent] event with current TTY size.
+      def self.create
+        height, width = TTY::Screen.size
+        TTYSizeEvent.new(width, height)
+      end
+
+      # @return [Size]
+      def size = Size.new(width, height)
+    end
+
+    # Emitted once when the queue is cleared, all messages are processed and the
+    # event loop will block waiting for more messages. Perfect time for
+    # repainting windows.
+    class EmptyQueueEvent
+      include Singleton
+    end
+
+    private
+
+    # @return [void]
+    def event_loop
+      loop do
+        yield EmptyQueueEvent.instance if @queue.empty?
+        event = @queue.pop
+        break if event.nil?
+
+        if event.is_a? ErrorEvent
+          begin
+            raise event.error
+          rescue StandardError
+            # Re-raise wrapped so the original error is preserved as `cause`
+            # 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
+      end
+    end
+
+    # Starts listening for stdin, firing {KeyEvent} on keypress.
+    # @return [void]
+    def start_key_thread
+      @key_thread = Thread.new do
+        loop do
+          key = Keys.getkey
+          event = MouseEvent.parse(key)
+          event = KeyEvent.new(key) if event.nil?
+          post event
+        end
+      rescue StandardError => e
+        post ErrorEvent.new(e)
+      end
+    end
+
+    # Trap the WINCH signal (TTY resize signal) and fire {TTYSizeEvent}.
+    # @return [void]
+    def trap_winch
+      Signal.trap("WINCH") do
+        post TTYSizeEvent.create
+      rescue StandardError => e
+        post ErrorEvent.new(e)
+      end
+    end
+  end
+end

data/lib/tuile/fake_event_queue.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+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
+    # @return [Boolean]
+    def locked? = true
+    # @return [void]
+    def stop; end
+
+    # @return [void]
+    def run_loop
+      raise Tuile::Error, "FakeEventQueue does not run an event loop"
+    end
+
+    # @return [void]
+    def await_empty; end
+
+    # @yield runs the block synchronously.
+    # @yieldreturn [void]
+    # @return [void]
+    def submit
+      yield
+    end
+
+    # @param event [Object]
+    # @return [void]
+    def post(event); end
+  end
+end

data/lib/tuile/fake_screen.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Testing only — a screen which doesn't paint anything and pretends that the
+  # lock is held. This way, the TTY running the tests is not painted over.
+  #
+  # Intended for unit-testing individual components: instantiate a component,
+  # mutate it, and assert against {#prints} or {#invalidated?}. It does not
+  # run an event loop, so it is *not* suitable for system-testing whole apps
+  # — for that, drive the real script through a PTY (see `spec/examples/`).
+  #
+  # Call {Screen.fake} to initialize the fake screen easily. Typical usage:
+  #
+  #   before { Screen.fake }
+  #   after  { Screen.close }
+  #
+  #   it "paints its content" do
+  #     label = Component::Label.new.tap { |l| l.text = "hi" }
+  #     Screen.instance.content = Component::Window.new("Greeting").tap { |w| w.content = label }
+  #     Screen.instance.repaint
+  #     assert_includes Screen.instance.prints.join, "hi"
+  #   end
+  class FakeScreen < Screen
+    def initialize
+      super
+      @event_queue = FakeEventQueue.new
+      @size = Size.new(160, 50)
+      @prints = []
+    end
+
+    # @return [Array<String>] whatever {#print} printed so far.
+    attr_reader :prints
+
+    # @return [void]
+    def check_locked; end
+
+    # @return [void]
+    def clear
+      @prints.clear
+    end
+
+    # Doesn't print anything: collects all strings in {#prints}.
+    # @param args [String]
+    # @return [void]
+    def print(*args)
+      @prints += args
+    end
+
+    # @param component [Component] the component to check.
+    # @return [Boolean]
+    def invalidated?(component) = @invalidated.include?(component)
+
+    # @return [void]
+    def invalidated_clear
+      @invalidated.clear
+    end
+  end
+end

data/lib/tuile/keys.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Constants for keys returned by {.getkey} and helpers for reading them from
+  # stdin. The constants are the raw escape sequences emitted by the terminal;
+  # see https://en.wikipedia.org/wiki/ANSI_escape_code for the encoding.
+  module Keys
+    # @return [String]
+    DOWN_ARROW = "\e[B"
+    # @return [String]
+    UP_ARROW = "\e[A"
+    # @return [Array<String>]
+    DOWN_ARROWS = [DOWN_ARROW, "j"].freeze
+    # @return [Array<String>]
+    UP_ARROWS = [UP_ARROW, "k"].freeze
+    # @return [String]
+    LEFT_ARROW = "\e[D"
+    # @return [String]
+    RIGHT_ARROW = "\e[C"
+    # @return [String]
+    ESC = "\e"
+    # @return [String]
+    HOME = "\e[H"
+    # @return [String]
+    END_ = "\e[F"
+    # @return [String]
+    PAGE_UP = "\e[5~"
+    # @return [String]
+    PAGE_DOWN = "\e[6~"
+    # @return [String]
+    BACKSPACE = "\u007f"
+    # @return [String]
+    DELETE = "\e[3~"
+    # @return [String]
+    CTRL_H = "\b"
+    # @return [Array<String>]
+    BACKSPACES = [BACKSPACE, CTRL_H].freeze
+    # @return [String]
+    CTRL_U = "\u0015"
+    # @return [String]
+    CTRL_D = "\u0004"
+    # @return [String]
+    ENTER = "\u000d"
+
+    # 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.
+    # @return [String] key, such as {DOWN_ARROW}.
+    def self.getkey
+      char = $stdin.getch
+      return char unless char == Keys::ESC
+
+      # Escape sequence. Try to read more data.
+      begin
+        # Read 6 chars: mouse events are e.g. `\e[Mxyz`
+        char += $stdin.read_nonblock(6)
+      rescue IO::EAGAINWaitReadable
+        # The "ESC" key pressed => only the \e char is emitted.
+      end
+      char
+    end
+  end
+end

data/lib/tuile/mouse_event.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A mouse event.
+  #
+  # @!attribute [r] button
+  #   @return [Symbol, nil] one of `:left`, `:middle`, `:right`, `:scroll_up`,
+  #     `:scroll_down`; `nil` if not known.
+  # @!attribute [r] x
+  #   @return [Integer] x coordinate, 0-based.
+  # @!attribute [r] y
+  #   @return [Integer] y coordinate, 0-based.
+  class MouseEvent < Data.define(:button, :x, :y)
+    # @return [Point] the event's position.
+    def point = Point.new(x, y)
+
+    # Checks whether given key is a mouse event key
+    # @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
+    end
+
+    # @param key [String] key read via {Keys.getkey}
+    # @return [MouseEvent, nil]
+    def self.parse(key)
+      return nil unless mouse_event?(key)
+
+      button = key[3].ord - 32
+      # 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
+      button = case button
+               when 0 then :left
+               when 2 then :right
+               when 1 then :middle
+               when 64 then :scroll_up
+               when 65 then :scroll_down
+               end
+      MouseEvent.new(button, x, y)
+    end
+
+    # @return [String]
+    def self.start_tracking = "\e[?1000h"
+    # @return [String]
+    def self.stop_tracking = "\e[?1000l"
+  end
+end

data/lib/tuile/point.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A point with `x` and `y` integer coordinates, both 0-based.
+  #
+  # @!attribute [r] x
+  #   @return [Integer] x coordinate, 0-based.
+  # @!attribute [r] y
+  #   @return [Integer] y coordinate, 0-based.
+  class Point < Data.define(:x, :y)
+    # @return [String]
+    def to_s = "#{x},#{y}"
+  end
+end

data/lib/tuile/rect.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A rectangle, with integer `left`, `top`, `width` and `height`, all 0-based.
+  #
+  # @!attribute [r] left
+  #   @return [Integer] left edge, 0-based.
+  # @!attribute [r] top
+  #   @return [Integer] top edge, 0-based.
+  # @!attribute [r] width
+  #   @return [Integer] width.
+  # @!attribute [r] height
+  #   @return [Integer] height.
+  class Rect < Data.define(:left, :top, :width, :height)
+    # @return [String]
+    def to_s = "#{top_left} #{size}"
+
+    # @return [Boolean] true if either {#width} or {#height} is zero or negative.
+    def empty?
+      width <= 0 || height <= 0
+    end
+
+    # @param point [Point] new top-left corner.
+    # @return [Rect] positioned at the new `left`/`top`.
+    def at(point)
+      Rect.new(point.x, point.y, width, height)
+    end
+
+    # Centers the rectangle — keeps {#width} and {#height} but modifies
+    # {#top} and {#left} so that the rectangle is centered on a screen.
+    # @param screen_size [Size] screen size
+    # @return [Rect] moved rectangle.
+    def centered(screen_size)
+      at(Point.new((screen_size.width - width) / 2, (screen_size.height - height) / 2))
+    end
+
+    # Clamp both width and height and return a rectangle.
+    # @param max_size [Size] the max size
+    # @return [Rect]
+    def clamp(max_size)
+      new_width = width.clamp(nil, max_size.width)
+      new_height = height.clamp(nil, max_size.height)
+      new_width == width && new_height == height ? self : Rect.new(left, top, new_width, new_height)
+    end
+
+    # @param point [Point]
+    # @return [Boolean]
+    def contains?(point)
+      point.x >= left && point.x < left + width && point.y >= top && point.y < top + height
+    end
+
+    # @return [Size]
+    def size = Size.new(width, height)
+
+    # @return [Point]
+    def top_left = Point.new(left, top)
+  end
+end