tuile 0.1.0

data/lib/tuile/screen.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+module Tuile
+  # The TTY screen. There is exactly one screen per app.
+  #
+  # A screen runs the event loop; call {#run_event_loop} to do that.
+  #
+  # A screen holds the screen lock; any UI modifications must be called from
+  # the event queue.
+  #
+  # All UI lives under a single {ScreenPane} owned by the screen. Set tiled
+  # content via {#content=}; the pane fills the entire terminal and is
+  # responsible for laying out its children.
+  #
+  # Modal popups are supported too, via {Component::Popup#open}. They
+  # auto-size to their wrapped content and are drawn centered over the
+  # tiled content.
+  #
+  # The drawing procedure is very simple: when a window needs repaint, it
+  # invalidates itself, but won't draw immediately. After the keyboard press
+  # event processing is done in the event loop, {#repaint} is called which
+  # then repaints all invalidated windows. This prevents repeated paintings.
+  class Screen
+    # Class variable (not class instance var) so the singleton survives
+    # subclassing — `FakeScreen < Screen` and `Screen.instance` see the same slot.
+    @@instance = nil # rubocop:disable Style/ClassVars
+
+    def initialize
+      @@instance = self # rubocop:disable Style/ClassVars
+      @event_queue = EventQueue.new
+      @size = EventQueue::TTYSizeEvent.create.size
+      @invalidated = Set.new
+      # Components being repainted right now. A component may invalidate its
+      # children during its repaint phase; this prevents double-draw.
+      @repainting = Set.new
+      # Until the event loop is run, we pretend we're in the UI thread.
+      @pretend_ui_lock = true
+      # Structural root of the component tree: holds tiled content, popup
+      # stack and status bar.
+      @pane = ScreenPane.new
+      @on_error = ->(e) { raise e }
+    end
+
+    # @return [ScreenPane] the structural root of the component tree.
+    attr_reader :pane
+
+    # Handler invoked when a {StandardError} escapes an event handler inside
+    # the event loop (e.g. a {Component::TextField}'s `on_change` raises).
+    #
+    # The default re-raises, so the exception propagates out of
+    # {#run_event_loop} and crashes the script with a stacktrace — unhandled
+    # exceptions are bugs and should be surfaced loudly.
+    #
+    # Replace it when the host has somewhere visible to put errors, e.g. a
+    # {Component::LogWindow} wired to {Tuile.logger}:
+    #
+    #   screen.on_error = lambda do |e|
+    #     Tuile.logger.error("#{e.class}: #{e.message}\n#{e.backtrace&.join("\n")}")
+    #   end
+    #
+    # The handler runs on the event-loop thread with the UI lock held.
+    # Returning normally keeps the loop alive; raising from within the handler
+    # tears the loop down and propagates out of {#run_event_loop}.
+    # @return [Proc] one-arg callable receiving the {StandardError} instance.
+    attr_accessor :on_error
+
+    # @return [Screen] the singleton instance.
+    def self.instance
+      raise Tuile::Error, "Screen not initialized; call Screen.new first" if @@instance.nil?
+
+      @@instance
+    end
+
+    # @return [Component, nil] tiled content (forwarded to {ScreenPane}).
+    def content = @pane.content
+
+    # @param content [Component]
+    # @return [void]
+    def content=(content)
+      @pane.content = content
+      layout
+    end
+
+    # @return [Size] current screen size.
+    attr_reader :size
+
+    # @return [Array<Component>] currently active popup components (forwarded
+    #   to {ScreenPane}). The array must not be modified!
+    def popups = @pane.popups
+
+    # @return [EventQueue] the event queue.
+    attr_reader :event_queue
+
+    # Checks that the UI lock is held and the current code runs in the "UI
+    # thread".
+    # @return [void]
+    def check_locked
+      return if @pretend_ui_lock || @event_queue.locked?
+
+      raise Tuile::Error,
+            "UI lock not held: UI mutations must run on the event-loop thread; " \
+            "marshal via screen.event_queue.submit { ... }"
+    end
+
+    # Clears the TTY screen.
+    # @return [void]
+    def clear
+      print TTY::Cursor.move_to(0, 0), TTY::Cursor.clear_screen
+    end
+
+    # Invalidates a component: causes the component to be repainted on next
+    # call to {#repaint}.
+    # @param component [Component]
+    # @return [void]
+    def invalidate(component)
+      check_locked
+      raise TypeError, "expected Component, got #{component.inspect}" unless component.is_a? Component
+
+      @invalidated << component unless @repainting.include? component
+    end
+
+    # @return [Component, nil] currently focused component.
+    attr_reader :focused
+
+    # Sets the focused {Component}. Focused component receives keyboard events.
+    # All focusable components live under {#pane}, so this is a single uniform
+    # path (no separate popup-vs-content branches).
+    # @param focused [Component, nil] the new component to be focused.
+    def focused=(focused)
+      unless focused.nil? || focused.is_a?(Component)
+        raise TypeError, "expected Component or nil, got #{focused.inspect}"
+      end
+
+      check_locked
+      if focused.nil?
+        @focused = nil
+        @pane.on_tree { it.active = false }
+      else
+        raise Tuile::Error, "#{focused} is not attached to this screen" if focused.root != @pane
+
+        @focused = focused
+        active = Set[focused]
+        cursor = focused.parent
+        until cursor.nil?
+          active << cursor
+          cursor = cursor.parent
+        end
+        @pane.on_tree { it.active = active.include?(it) }
+        @focused.on_focus
+      end
+      # Popups own their own "q Close" prefix in #keyboard_hint; for the tiled
+      # case Screen tacks on the global "q quit" instead.
+      top_popup = @pane.popups.last
+      @pane.status_bar.text = if top_popup.nil?
+                                "q #{Rainbow("quit").cadetblue}  #{active_window&.keyboard_hint}".strip
+                              else
+                                top_popup.keyboard_hint
+                              end
+    end
+
+    # Internal — use {Component::Popup#open} instead. Adds the popup to
+    # {#pane}, centers and focuses it.
+    # @api private
+    # @param window [Component::Popup]
+    # @return [void]
+    def add_popup(window)
+      check_locked
+      @pane.add_popup(window)
+      # No need to fully repaint the scene: a popup simply paints over the
+      # current screen contents.
+    end
+
+    # Runs event loop – waits for keys and sends them to active window. The
+    # function exits when the 'ESC' or 'q' key is pressed.
+    # @return [void]
+    def run_event_loop
+      @pretend_ui_lock = false
+      $stdin.echo = false
+      print MouseEvent.start_tracking
+      $stdin.raw do
+        event_loop
+      end
+    ensure
+      print MouseEvent.stop_tracking
+      print TTY::Cursor.show
+      $stdin.echo = true
+    end
+
+    # @return [Component, nil] current active tiled component.
+    def active_window
+      check_locked
+      result = nil
+      @pane.content&.on_tree { result = it if it.is_a?(Component::Window) && it.active? }
+      result
+    end
+
+    # Internal — use {Component::Popup#close} instead. Removes the popup
+    # from {#pane}, repairs focus, and repaints the scene.
+    #
+    # Does nothing if the window is not open on this screen.
+    # @api private
+    # @param window [Component::Popup]
+    # @return [void]
+    def remove_popup(window)
+      check_locked
+      @pane.remove_popup(window)
+      needs_full_repaint
+    end
+
+    # Internal — use {Component::Popup#open?} instead.
+    # @api private
+    # @param window [Component::Popup]
+    # @return [Boolean] true if this popup is currently mounted.
+    def has_popup?(window) # rubocop:disable Naming/PredicatePrefix
+      check_locked
+      @pane.has_popup?(window)
+    end
+
+    # Testing only — creates new screen, locks the UI, and prevents any
+    # redraws, so that test TTY is not painted over. {FakeScreen#initialize}
+    # self-installs as the singleton, so subsequent {Screen.instance} calls
+    # return the same object.
+    # @return [FakeScreen]
+    def self.fake = FakeScreen.new
+
+    # @return [void]
+    def close
+      clear
+      @pane = nil
+      @@instance = nil # rubocop:disable Style/ClassVars
+    end
+
+    # @return [void]
+    def self.close
+      @@instance&.close
+    end
+
+    # Prints given strings.
+    # @param args [String] stuff to print.
+    # @return [void]
+    def print(*args)
+      Kernel.print(*args)
+    end
+
+    # Repaints the screen; tries to be as effective as possible, by only
+    # considering invalidated windows.
+    # @return [void]
+    def repaint
+      check_locked
+      # This simple TUI framework doesn't support window clipping since tiled
+      # windows are not expected to overlap. If there rarely is a popup, we
+      # just repaint all windows in correct order — sure they will paint over
+      # other windows, but if this is done in the right order, the final
+      # drawing will look okay. Not the most effective algorithm, but very
+      # simple and very fast in common cases.
+
+      did_paint = false
+      until @invalidated.empty?
+        did_paint = true
+        popups = @pane.popups
+
+        # Partition invalidated components into tiled vs popup-tree. Sorting
+        # by depth across the whole tree would interleave them: a tiled
+        # grandchild (depth 3) sorts after a popup's content (depth 2) and
+        # overdraws it.
+        popup_tree = Set.new
+        popups.each { |p| p.on_tree { popup_tree << it } }
+        tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(it) }
+
+        # Within the tiled tree, paint parents before children.
+        tiled.sort_by!(&:depth)
+
+        repaint = if tiled.empty?
+                    # Only popups need repaint — paint just their invalidated
+                    # components in depth order.
+                    popup_invalidated.sort_by(&:depth)
+                  else
+                    # Tiled components may overdraw popups; repaint each open
+                    # popup's full subtree on top, in stacking order
+                    # (parent-before-child within each popup).
+                    tiled + popups.flat_map { |p| collect_subtree(p) }
+                  end
+
+        @repainting = repaint.to_set
+        @invalidated.clear
+
+        # Don't call {#clear} before repaint — causes flickering, and only
+        # needed when @content doesn't cover the entire screen.
+        repaint.each(&:repaint)
+
+        # Repaint done, mark all components as up-to-date.
+        @repainting.clear
+      end
+      position_cursor if did_paint
+    end
+
+    # Returns the absolute screen coordinates where the hardware cursor should
+    # sit, or nil if it should be hidden. Only the {#focused} component owns
+    # the cursor: there can be multiple active components (the focus path),
+    # but only one focused.
+    # @return [Point, nil]
+    def cursor_position = @focused&.cursor_position
+
+    private
+
+    # Collects a component and all its descendants in tree order
+    # (parent before children).
+    # @param component [Component]
+    # @return [Array<Component>]
+    def collect_subtree(component)
+      result = []
+      component.on_tree { result << it }
+      result
+    end
+
+    # Hides or moves the hardware cursor based on the current focus state.
+    # @return [void]
+    def position_cursor
+      pos = cursor_position
+      if pos.nil?
+        print TTY::Cursor.hide
+      else
+        print TTY::Cursor.move_to(pos.x, pos.y), TTY::Cursor.show
+      end
+    end
+
+    # Recalculates positions of all windows, and repaints the scene.
+    # Automatically called whenever terminal size changes. Call when the app
+    # starts. {#size} provides correct size of the terminal.
+    # @return [void]
+    def layout
+      check_locked
+      needs_full_repaint
+      @pane.rect = Rect.new(0, 0, size.width, size.height)
+      repaint
+    end
+
+    # Called after a popup is closed. Since a popup can cover any window,
+    # top-level component or other popups, we need to redraw everything.
+    # @return [void]
+    def needs_full_repaint
+      @pane&.on_tree { invalidate it }
+    end
+
+    # A key has been pressed on the keyboard. Handle it, or forward to active
+    # window.
+    # @param key [String]
+    # @return [Boolean] true if the key was handled by some window.
+    def handle_key(key) = @pane.handle_key(key)
+
+    # Finds target window and calls {Component::Window#handle_mouse}.
+    # @param event [MouseEvent]
+    # @return [void]
+    def handle_mouse(event) = @pane.handle_mouse(event)
+
+    # @return [void]
+    def event_loop
+      @event_queue.run_loop do |event|
+        case event
+        when EventQueue::KeyEvent
+          key = event.key
+          handled = handle_key(key)
+          @event_queue.stop if !handled && ["q", Keys::ESC].include?(key)
+        when MouseEvent
+          handle_mouse(event)
+        when EventQueue::TTYSizeEvent
+          @size = event.size
+          layout
+        when EventQueue::EmptyQueueEvent
+          repaint
+        end
+      rescue StandardError => e
+        @on_error.call(e)
+      end
+    end
+  end
+end

data/lib/tuile/screen_pane.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Tuile
+  # The structural root of the {Screen}'s component tree.
+  #
+  # {Screen} is a singleton runtime owner (event loop, lock, terminal IO,
+  # invalidation set). All actual UI lives under a {ScreenPane}: the tiled
+  # {#content}, the modal {#popups} stack, and the bottom {#status_bar}.
+  # Putting them under a single Component parent gives focus traversal a real
+  # root, makes {Component#attached?} a one-liner, and lets popup-focus repair
+  # fall out of the standard {Component#on_child_removed} hook.
+  #
+  # The pane is not a {Component::Layout}: popups deliberately overlap content
+  # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
+  # modal-popup rules rather than active-child dispatch.
+  class ScreenPane < Component
+    def initialize
+      super
+      @popups = []
+      # Per-popup snapshot of {Screen#focused} taken just before the popup was
+      # added. Restored when the popup closes so focus returns to where the
+      # user was, instead of falling through to {#content} and getting
+      # cascaded to the first focusable child.
+      @popup_prior_focus = {}
+      @status_bar = Component::Label.new
+      @status_bar.parent = self
+    end
+
+    # @return [Component, nil] the tiled content component.
+    attr_reader :content
+    # @return [Array<Component>] modal popups in stacking order; last is
+    #   topmost. The array must not be mutated by callers.
+    attr_reader :popups
+    # @return [Component::Label] the bottom status bar.
+    attr_reader :status_bar
+
+    def focusable? = false
+
+    # Children for tree traversal: content first, popups in stacking order,
+    # status bar last.
+    def children = [*[@content].compact, *@popups, @status_bar]
+
+    # Replaces the tiled content. Wipes focus first (the new tree starts
+    # fresh), detaches the old content, then attaches the new one and
+    # re-lays out.
+    # @param content [Component]
+    def content=(content)
+      raise TypeError, "expected Component, got #{content.inspect}" unless content.is_a? Component
+      raise ArgumentError, "#{content} already has a parent #{content.parent}" unless content.parent.nil?
+      return if @content == content
+
+      screen.focused = nil
+      old = @content
+      old&.parent = nil
+      @content = content
+      content.parent = self
+      layout
+    end
+
+    # Adds a popup, centers it, focuses it, and invalidates it for repaint.
+    # @param window [Component::Popup]
+    # @return [void]
+    def add_popup(window)
+      raise TypeError, "expected Popup, got #{window.inspect}" unless window.is_a? Component::Popup
+      raise ArgumentError, "#{window} already has a parent #{window.parent}" unless window.parent.nil?
+
+      @popup_prior_focus[window] = screen.focused
+      @popups << window
+      window.parent = self
+      window.center
+      screen.focused = window
+      screen.invalidate(window)
+    end
+
+    # Removes a popup. If the popup held focus, focus shifts to the now-topmost
+    # remaining popup, falling back to the focus snapshotted when the popup
+    # was opened (if still attached), then to {#content}, then to nil.
+    # @param window [Component]
+    # @return [void]
+    def remove_popup(window)
+      raise Tuile::Error, "#{window} is not an open popup on this pane" unless @popups.delete(window)
+
+      prior = @popup_prior_focus.delete(window)
+      # Detach first so the popup becomes its own root; then any prior
+      # pointing *inside* that popup is detectable via `p.root == window`.
+      window.parent = nil
+      # If any other popup recorded its prior focus inside the popup we're
+      # removing, forward it to *our* prior so chained closures still climb
+      # back to the original owner instead of stopping at a detached
+      # component.
+      @popup_prior_focus.transform_values! { |p| p && p.root == window ? prior : p }
+
+      @removing_popup_prior = prior
+      on_child_removed(window)
+    ensure
+      @removing_popup_prior = nil
+    end
+
+    # @param window [Component]
+    # @return [Boolean] true if this pane currently hosts the popup.
+    def has_popup?(window) = @popups.include?(window) # rubocop:disable Naming/PredicatePrefix
+
+    # Re-lays out children whenever the pane's own rect changes.
+    # @param new_rect [Rect]
+    # @return [void]
+    def rect=(new_rect)
+      super
+      layout
+    end
+
+    # Lays out content (full pane minus the bottom row) and the status bar
+    # (bottom row). Popups self-position via {Component::Popup#center}.
+    # @return [void]
+    def layout
+      return if rect.empty?
+
+      @content.rect = Rect.new(rect.left, rect.top, rect.width, [rect.height - 1, 0].max) unless @content.nil?
+      @popups.each(&:center)
+      @status_bar.rect = Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
+    end
+
+    # Pane paints nothing itself; its children paint over the entire rect.
+    # @return [void]
+    def repaint; end
+
+    # Topmost popup is modal: it eats keys. Falls through to content only
+    # when no popup is open.
+    def handle_key(key)
+      topmost = @popups.last
+      return topmost.handle_key(key) unless topmost.nil?
+      return @content.handle_key(key) unless @content.nil?
+
+      false
+    end
+
+    # Mouse events check popups in reverse stacking order (topmost first), and
+    # fall through to content only when no popup is hit *and* there are no
+    # popups open. This preserves modal click-blocking: an open popup eats
+    # clicks even outside its rect.
+    # @param event [MouseEvent]
+    # @return [void]
+    def handle_mouse(event)
+      clicked = @popups.rfind { it.rect.contains?(event.point) }
+      clicked = @content if clicked.nil? && @popups.empty?
+      clicked&.handle_mouse(event)
+    end
+
+    # Focus repair when a child detaches. Default {Component#on_child_removed}
+    # would refocus to `self` (the pane), which isn't a useful focus target.
+    # Instead, route focus to the now-topmost popup, then to the prior focus
+    # snapshotted when this popup was opened (if still attached), then to
+    # content, then nil.
+    # @param child [Component]
+    # @return [void]
+    def on_child_removed(child)
+      return unless attached?
+
+      f = screen.focused
+      return if f.nil?
+
+      cursor = f
+      while cursor
+        if cursor == child
+          fallback = @popups.last
+          fallback ||= @removing_popup_prior if @removing_popup_prior&.attached?
+          fallback ||= @content
+          screen.focused = fallback
+          return
+        end
+        cursor = cursor.parent
+      end
+    end
+  end
+end

data/lib/tuile/size.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A size with integer `width` and `height`.
+  #
+  # @!attribute [r] width
+  #   @return [Integer] width.
+  # @!attribute [r] height
+  #   @return [Integer] height.
+  class Size < Data.define(:width, :height)
+    # @return [String]
+    def to_s = "#{width}x#{height}"
+
+    # @return [Boolean] true if either {#width} or {#height} is zero or negative.
+    def empty?
+      width <= 0 || height <= 0
+    end
+
+    # @param width [Integer]
+    # @param height [Integer]
+    # @return [Size]
+    def plus(width, height) = Size.new(self.width + width, self.height + height)
+
+    # Clamp both width and height and return a size.
+    # @param max_size [Size] the max size
+    # @return [Size]
+    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 : Size.new(new_width, new_height)
+    end
+
+    # Clamp height and return a size.
+    # @param max_height [Integer] the max height
+    # @return [Size]
+    def clamp_height(max_height) = clamp(Size.new(width, max_height))
+
+    # An empty size constant.
+    # @return [Size]
+    ZERO = Size.new(0, 0)
+  end
+end

data/lib/tuile/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Tuile
+  # @return [String]
+  VERSION = "0.1.0"
+end

data/lib/tuile/vertical_scroll_bar.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A vertical scrollbar that computes which character to draw at each row.
+  #
+  # Uses `█` for the handle (filled track) and `░` for the empty track. There
+  # are no up/down arrows; the full height is used as the track. Handle
+  # geometry is precomputed in the constructor as {#handle_height},
+  # {#handle_start}, and {#handle_end}.
+  class VerticalScrollBar
+    # @return [Integer] number of track rows the handle occupies (height >= 1
+    #   only).
+    attr_reader :handle_height
+    # @return [Integer] 0-based row where the handle starts (height >= 1 only).
+    attr_reader :handle_start
+    # @return [Integer] 0-based row where the handle ends (height >= 1 only).
+    attr_reader :handle_end
+
+    # @param height [Integer] number of rows in the scrollbar (== viewport
+    #   height).
+    # @param line_count [Integer] total number of content lines.
+    # @param top_line [Integer] index of the first visible content line.
+    def initialize(height, line_count:, top_line:)
+      @height = height
+
+      return unless height >= 1
+
+      if line_count <= height
+        @handle_height = height
+        @handle_start  = 0
+        @handle_end    = height - 1
+      else
+        @handle_height = [(height * height / line_count.to_f).ceil, 1].max
+        @handle_start  = (height * top_line / line_count.to_f).floor
+        @handle_end    = @handle_start + @handle_height - 1
+      end
+    end
+
+    # Returns the scrollbar character for the given viewport row.
+    # @param row_in_viewport [Integer] 0-based row index within the viewport.
+    # @return [String] single scrollbar character.
+    def scrollbar_char(row_in_viewport)
+      row_in_viewport >= @handle_start && row_in_viewport <= @handle_end ? "█" : "░"
+    end
+  end
+end

data/lib/tuile.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require "io/console"
+require "logger"
+require "rainbow"
+require "singleton"
+require "strings-truncation"
+require "tty-cursor"
+require "tty-screen"
+require "unicode/display_width"
+require "zeitwerk"
+
+# Tuile is a small component-oriented terminal UI framework, built on top of
+# the TTY toolkit. The name is French for a roof tile — a small piece that
+# composes into a larger whole, which mirrors how Tuile UIs are built from
+# {Component}s nested under a single {Screen}.
+module Tuile
+  class Error < StandardError; end
+
+  class << self
+    # The logger Tuile writes to. Defaults to a null logger, so the gem is
+    # silent unless the host app opts in via `Tuile.logger = ...`. Any object
+    # duck-typing the stdlib `Logger` interface (`debug/info/warn/error/fatal`
+    # taking a string) works — including `TTY::Logger`.
+    # @return [Logger]
+    attr_writer :logger
+
+    # @return [Logger]
+    def logger
+      @logger ||= Logger.new(IO::NULL)
+    end
+  end
+
+  loader = Zeitwerk::Loader.for_gem
+  loader.setup
+end