tuile 0.1.0

data/lib/tuile/component/picker_window.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A {Window} that lists options identified by single keyboard keys, asks
+    # the user to pick one, and fires a callback with the picked key.
+    #
+    # Usable tiled (just add to a {Layout} and read picks via the block) or
+    # as a popup via {.open}, which wraps it in a {Popup} that closes itself
+    # after a pick. ESC / `q` close without firing the callback.
+    class PickerWindow < Window
+      # Scrolls the window when more items.
+      # @return [Integer]
+      MAX_ITEMS = 10
+
+      # One picker option.
+      #
+      # @!attribute [r] key
+      #   @return [String] the keyboard key that picks this option.
+      # @!attribute [r] caption
+      #   @return [String] the option caption.
+      class Option < Data.define(:key, :caption)
+      end
+
+      # @param caption [String] the window caption.
+      # @param options [Array<Array(String, String)>] pairs of keyboard key and
+      #   option caption. No Rainbow formatting must be used.
+      # @yield [key] called with the option key once one is selected by the
+      #   user. Not called if the picker is dismissed without picking.
+      # @yieldparam key [String] the picked option key.
+      # @yieldreturn [void]
+      def initialize(caption, options, &block)
+        raise ArgumentError, "block required" unless block
+        raise ArgumentError, "options must not be empty" if options.empty?
+
+        super(caption)
+        @options = options.map { Option.new(it[0], it[1]) }
+        @block = block
+        list = Component::List.new
+        list.lines = @options.map { "#{it.key} #{Rainbow(it.caption).cadetblue}" }
+        list.cursor = Component::List::Cursor.new
+        list.on_item_chosen = ->(index, _line) { select_option(@options[index].key) }
+        self.content = list
+        # Optional hook for a containing Popup to dismiss itself after a pick.
+        @on_pick = nil
+      end
+
+      # Callback invoked after the user picks an option (after the block
+      # fires). The {Popup} returned by {.open} sets this to its own `close`.
+      # @return [Proc, nil]
+      attr_accessor :on_pick
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return true if super
+
+        if @options.any? { it.key == key }
+          select_option(key)
+          true
+        else
+          false
+        end
+      end
+
+      # @return [String]
+      def keyboard_hint
+        @options.map { "#{it.key} #{Rainbow(it.caption).cadetblue}" }.join("  ")
+      end
+
+      # Opens a picker as a popup. Picking an option fires `block`, then
+      # closes the popup; ESC / `q` close without firing `block`.
+      # @param caption [String]
+      # @param options [Array<Array(String, String)>]
+      # @yield [key]
+      # @yieldparam key [String]
+      # @yieldreturn [void]
+      # @return [Popup] the wrapping popup.
+      def self.open(caption, options, &block)
+        picker = PickerWindow.new(caption, options, &block)
+        popup = Popup.new(content: picker)
+        picker.on_pick = -> { popup.close }
+        popup.open
+        popup
+      end
+
+      protected
+
+      # @param key [String]
+      # @return [void]
+      def select_option(key)
+        @block.call(key)
+        @on_pick&.call
+      end
+    end
+  end
+end

data/lib/tuile/component/popup.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A modal overlay that wraps any {Component} as its content. Popup itself
+    # paints nothing — it's a transparent host that handles modality
+    # ({#open} / {#close} / {#open?}, ESC/q to close), centers itself on the
+    # screen, and auto-sizes to the wrapped content.
+    #
+    # The wrapped content fills the popup's full {#rect}; if you want a frame
+    # and caption, wrap a {Component::Window} (or any subclass — including
+    # {Component::LogWindow}) and let it draw its own border:
+    #
+    #   window = Component::Window.new("Help")
+    #   window.content = Component::List.new.tap { _1.lines = lines }
+    #   Component::Popup.new(content: window).open
+    #
+    # Bare content also works (a {Component::Label}, a {Component::List}…), in
+    # which case the popup is borderless.
+    #
+    # `q` and ESC close the popup. Any nested {Component::TextField} that owns
+    # the hardware cursor swallows printable keys first via the standard
+    # cursor-owner suppression in {Component#handle_key}, so typing `q` into a
+    # text field doesn't dismiss the popup.
+    class Popup < Component
+      include Component::HasContent
+
+      # @param content [Component, nil] initial content; can be set later via
+      #   {#content=}. When provided here, the popup auto-sizes to fit.
+      def initialize(content: nil)
+        super()
+        @content = nil
+        # Off-screen sentinel until the content sets a real size and the popup
+        # is centered on open.
+        @rect = Rect.new(-1, -1, 0, 0)
+        self.content = content unless content.nil?
+      end
+
+      def focusable? = true
+
+      # Mounts this popup on the {Screen}.
+      # @return [void]
+      def open
+        screen.add_popup(self)
+      end
+
+      # Constructs and opens a popup in one call.
+      # @param content [Component, nil]
+      # @return [Popup] the opened popup.
+      def self.open(content: nil)
+        Popup.new(content: content).tap(&:open)
+      end
+
+      # Removes this popup from the {Screen}. No-op if not currently open.
+      # @return [void]
+      def close
+        screen.remove_popup(self)
+      end
+
+      # @return [Boolean] true if this popup is currently mounted on the screen.
+      def open?
+        screen.has_popup?(self)
+      end
+
+      # Recenters the popup on the screen, preserving its current width/height.
+      # Called automatically by the screen's layout pass and by {#content=}
+      # when the popup is open.
+      # @return [void]
+      def center
+        self.rect = rect.centered(screen.size)
+      end
+
+      # @return [Integer] max height the popup will grow to fit its content,
+      #   defaults to 12. Override in a subclass to allow taller popups.
+      def max_height = 12
+
+      # Sets the popup's content and auto-sizes the popup to fit.
+      # @param new_content [Component, nil]
+      def content=(new_content)
+        super
+        update_rect unless new_content.nil?
+      end
+
+      # Hint for the status bar: own "q Close" plus the wrapped content's hint.
+      # @return [String]
+      def keyboard_hint
+        prefix = "q #{Rainbow("Close").cadetblue}"
+        child_hint = @content&.keyboard_hint.to_s
+        child_hint.empty? ? prefix : "#{prefix}  #{child_hint}"
+      end
+
+      # @param key [String]
+      # @return [Boolean] true if the key was handled.
+      def handle_key(key)
+        return true if super
+
+        if [Keys::ESC, "q"].include?(key)
+          close
+          true
+        else
+          false
+        end
+      end
+
+      protected
+
+      # Content fills the popup's full rect — Popup has no border to subtract.
+      # @param content [Component]
+      # @return [void]
+      def layout(content)
+        content.rect = rect
+      end
+
+      private
+
+      # Recompute width/height from {#content}'s natural size and recenter
+      # if currently open. Called whenever content is (re)assigned.
+      # @return [void]
+      def update_rect
+        size = @content.content_size.clamp_height(max_height)
+        size = size.clamp(Size.new(screen.size.width * 4 / 5, screen.size.height * 4 / 5))
+        self.rect = Rect.new(-1, -1, size.width, size.height)
+        center if open?
+      end
+    end
+  end
+end

data/lib/tuile/component/text_field.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A single-line text input field with hardware-cursor caret.
+    #
+    # The field does not scroll. Any keystroke that would make {#text} longer
+    # than `rect.width - 1` (the last column is reserved for the caret past the
+    # last char) is rejected.
+    #
+    # The caret is a logical index in `0..text.length`. The hardware cursor is
+    # positioned by {Screen} after each repaint cycle when this component is
+    # focused; see {Component#cursor_position}.
+    class TextField < Component
+      def initialize
+        super
+        @text = +""
+        @caret = 0
+        @on_escape = nil
+        @on_change = nil
+        @on_key_up = nil
+        @on_key_down = nil
+        @on_enter = nil
+      end
+
+      # @return [String] current text contents.
+      attr_reader :text
+
+      # @return [Integer] caret index in `0..text.length`.
+      attr_reader :caret
+
+      # Optional callback fired when ESC is pressed. When set, ESC is consumed
+      # by the field; when nil, ESC falls through to the parent (default
+      # behavior).
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      attr_accessor :on_escape
+
+      # Optional callback fired whenever {#text} changes. Receives the new text
+      # as a single argument. Not fired by {#caret=} (text unchanged) and not
+      # fired when a setter is a no-op.
+      # @return [Proc, Method, nil] one-arg callable, or nil.
+      attr_accessor :on_change
+
+      # Optional callback fired when the UP arrow key is pressed. When set, UP
+      # is consumed by the field; when nil, UP falls through to the parent
+      # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
+      # since `k` is a printable character inserted into {#text}.
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      attr_accessor :on_key_up
+
+      # Optional callback fired when the DOWN arrow key is pressed. When set,
+      # DOWN is consumed by the field; when nil, DOWN falls through to the
+      # parent (default behavior). Only triggered by {Keys::DOWN_ARROW}, not by
+      # `j`, since `j` is a printable character inserted into {#text}.
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      attr_accessor :on_key_down
+
+      # Optional callback fired when ENTER is pressed. When set, ENTER is
+      # consumed by the field; when nil, ENTER falls through to the parent
+      # (default behavior).
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      attr_accessor :on_enter
+
+      # Sets the text. Truncates to fit if longer than `rect.width - 1`. Caret
+      # is clamped to the new text length.
+      # @param new_text [String]
+      def text=(new_text)
+        new_text = new_text.to_s
+        new_text = new_text[0, max_text_length] if new_text.length > max_text_length
+        return if @text == new_text
+
+        @text = +new_text
+        @caret = @caret.clamp(0, @text.length)
+        invalidate
+        @on_change&.call(@text)
+      end
+
+      # Sets the caret position. Clamped to `0..text.length`.
+      # @param new_caret [Integer]
+      def caret=(new_caret)
+        new_caret = new_caret.clamp(0, @text.length)
+        return if @caret == new_caret
+
+        @caret = new_caret
+        invalidate
+      end
+
+      def focusable? = true
+
+      # @return [Point, nil]
+      def cursor_position
+        return nil unless rect.width.positive?
+
+        Point.new(rect.left + @caret, rect.top)
+      end
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return false unless active?
+        return true if super
+
+        case key
+        when Keys::LEFT_ARROW then self.caret = @caret - 1
+        when Keys::RIGHT_ARROW then self.caret = @caret + 1
+        when Keys::HOME then self.caret = 0
+        when Keys::END_ then self.caret = @text.length
+        when *Keys::BACKSPACES then delete_before_caret
+        when Keys::DELETE then delete_at_caret
+        when Keys::ESC
+          return false if @on_escape.nil?
+
+          @on_escape.call
+        when Keys::UP_ARROW
+          return false if @on_key_up.nil?
+
+          @on_key_up.call
+        when Keys::DOWN_ARROW
+          return false if @on_key_down.nil?
+
+          @on_key_down.call
+        when Keys::ENTER
+          return false if @on_enter.nil?
+
+          @on_enter.call
+        else
+          return insert(key) if printable?(key)
+
+          return false
+        end
+        true
+      end
+
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        return unless event.button == :left && rect.contains?(event.point)
+
+        self.caret = (event.x - rect.left).clamp(0, @text.length)
+      end
+
+      # @return [void]
+      def repaint
+        clear_background
+        return if rect.empty?
+
+        screen.print TTY::Cursor.move_to(rect.left, rect.top), @text
+      end
+
+      protected
+
+      # @return [void]
+      def on_width_changed
+        super
+        return if @text.length <= max_text_length
+
+        @text = @text[0, [max_text_length, 0].max]
+        @caret = @caret.clamp(0, @text.length)
+        @on_change&.call(@text)
+      end
+
+      private
+
+      # Maximum number of characters {#text} can hold given current width.
+      # @return [Integer]
+      def max_text_length = (rect.width - 1).clamp(0, nil)
+
+      # @param char [String]
+      # @return [Boolean]
+      def insert(char)
+        return false if @text.length >= max_text_length
+
+        @text = @text.dup.insert(@caret, char)
+        @caret += 1
+        invalidate
+        @on_change&.call(@text)
+        true
+      end
+
+      # @return [void]
+      def delete_before_caret
+        return if @caret.zero?
+
+        @text = @text.dup
+        @text.slice!(@caret - 1)
+        @caret -= 1
+        invalidate
+        @on_change&.call(@text)
+      end
+
+      # @return [void]
+      def delete_at_caret
+        return if @caret >= @text.length
+
+        @text = @text.dup
+        @text.slice!(@caret)
+        invalidate
+        @on_change&.call(@text)
+      end
+
+      # @param key [String]
+      # @return [Boolean]
+      def printable?(key)
+        key.length == 1 && key.ord >= 0x20 && key.ord < 0x7f
+      end
+    end
+  end
+end

data/lib/tuile/component/window.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A window with a frame, a {#caption} and a content {Component}. Doesn't
+    # support overlapping with other windows: it paints its entire contents and
+    # doesn't clip if there are other overlapping windows.
+    #
+    # 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.
+    class Window < Component
+      include Component::HasContent
+
+      # @param caption [String]
+      def initialize(caption = "")
+        super()
+        @border_right = 1
+        @caption = caption
+        # Optional bottom-row chrome that overlays the bottom border (e.g. a
+        # search field).
+        @footer = nil
+      end
+
+      def focusable? = true
+
+      # @return [Component, nil] optional component overlaying the bottom border
+      #   row.
+      attr_reader :footer
+
+      # Sets the bottom-row chrome slot. The footer overlays the bottom border at
+      # full inner width and is positioned automatically; pass `nil` to remove.
+      #
+      # Symmetric to {#content=}: validates the new component, swaps parent
+      # pointers, invalidates the old/new components and the window border, and
+      # repairs focus via {#on_child_removed} if the removed footer held it.
+      # @param new_footer [Component, nil]
+      def footer=(new_footer)
+        unless new_footer.nil? || new_footer.is_a?(Component)
+          raise TypeError, "expected Component or nil, got #{new_footer.inspect}"
+        end
+        return if @footer == new_footer
+        if !new_footer.nil? && !new_footer.parent.nil?
+          raise ArgumentError, "#{new_footer} already has a parent #{new_footer.parent}"
+        end
+
+        old = @footer
+        old&.parent = nil
+        @footer = new_footer
+        unless new_footer.nil?
+          new_footer.parent = self
+          new_footer.invalidate
+          layout_footer
+        end
+        invalidate # repaint border row that the footer covers/uncovers
+        on_child_removed(old) unless old.nil?
+      end
+
+      # @return [Array<Component>]
+      def children
+        @footer.nil? ? super : super + [@footer]
+      end
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return @footer.handle_key(key) if @footer&.active?
+
+        super
+      end
+
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        if @footer&.rect&.contains?(event.point)
+          @footer.handle_mouse(event)
+        else
+          super
+        end
+      end
+
+      # @param new_rect [Rect]
+      # @return [void]
+      def rect=(new_rect)
+        super
+        layout_footer
+      end
+
+      # @param value [Boolean]
+      # @return [void]
+      def scrollbar=(value)
+        unless content.is_a?(Component::List)
+          raise Tuile::Error,
+                "scrollbar= requires a Component::List as content, got #{content.inspect}"
+        end
+
+        content.scrollbar_visibility = value ? :visible : :gone
+        @border_right = value ? 0 : 1
+        invalidate
+        layout(content)
+      end
+
+      # @return [String] the current caption, empty by default.
+      attr_reader :caption
+
+      # Sets new caption and repaints the window.
+      # @param new_caption [String]
+      def caption=(new_caption)
+        @caption = new_caption
+        invalidate
+      end
+
+      # @return [Size] the size needed to fit the window's content, footer
+      #   (width only — footer overlays the bottom border), and caption,
+      #   plus the 2-character border. Returns {Size}`.new(2, 2)` when the
+      #   window has no content, footer, or caption.
+      def content_size
+        inner_w = [
+          content&.content_size&.width || 0,
+          @footer&.content_size&.width || 0,
+          frame_caption.length
+        ].max
+        inner_h = content&.content_size&.height || 0
+        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.
+      # @return [void]
+      def repaint
+        super
+        repaint_border
+        # Border paints over content: invalidate the content to have it
+        # repainted.
+        content&.invalidate
+      end
+
+      # @param key [String, nil]
+      # @return [void]
+      def key_shortcut=(key)
+        super
+        # The shortcut key is shown in the caption — repaint.
+        invalidate
+      end
+
+      protected
+
+      # @param content [Component]
+      # @return [void]
+      def layout(content)
+        content.rect = Rect.new(rect.left + 1, rect.top + 1, rect.width - 1 - @border_right, rect.height - 2)
+      end
+
+      # Paints the window border.
+      # @return [void]
+      def repaint_border
+        return unless visible?
+
+        frame = build_frame(frame_caption)
+        frame = Rainbow(frame).green if active?
+        screen.print frame
+      end
+
+      # The caption text as it appears in the rendered border, including the
+      # shortcut prefix when {#key_shortcut} is set.
+      # @return [String]
+      def frame_caption
+        c = @caption || ""
+        key_shortcut.nil? ? c : "[#{key_shortcut}]-#{c}"
+      end
+
+      # Builds the border as a single string with embedded cursor-positioning
+      # escapes, mirroring the layout {TTY::Box.frame} used to produce. Title
+      # is clipped to fit the inner width so the box never overflows {#rect}.
+      # @param caption [String]
+      # @return [String]
+      def build_frame(caption)
+        w = @rect.width
+        h = @rect.height
+        top = @rect.top
+        left = @rect.left
+        inner_w = [w - 2, 0].max
+
+        title = caption.to_s
+        title = title[0, inner_w] if title.length > inner_w
+        dashes = "─" * (inner_w - title.length)
+
+        out = +""
+        out << TTY::Cursor.move_to(left, top) << "┌#{title}#{dashes}┐"
+        (1..(h - 2)).each do |dy|
+          out << TTY::Cursor.move_to(left, top + dy) << "│"
+          out << TTY::Cursor.move_to(left + w - 1, top + dy) << "│"
+        end
+        out << TTY::Cursor.move_to(left, top + h - 1) << "└#{"─" * inner_w}┘" if h >= 2
+        out
+      end
+
+      private
+
+      # @return [void]
+      def layout_footer
+        return if @footer.nil? || rect.empty?
+
+        width = [rect.width - 2, 0].max
+        @footer.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
+      end
+    end
+  end
+end