tuile 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 246774aae8809b045b95adef86263642f561d726cb907162101cef1c94135142
-  data.tar.gz: d6858c0ece1e461a5ff767572ac1fd6255eb338a84caff1b12d0a0db66aec6b0
+  metadata.gz: 7e96464e067ccbb78bd11cf6639b53dc4f53de48519f7e47143a594b520bb99c
+  data.tar.gz: 668bd3ac1b4130919949dce95867cccfa89dac387b6f164a2c7ea027cf04c1da
 SHA512:
-  metadata.gz: 97ecd56ae772b96c8944d78245ee628f56dbcf4a4c0a955319bc8d1bf630132dd6b23ec6bb23899a97f45b6b4b92b3686fd548c056bc9eb107caa06bcaf97a89
-  data.tar.gz: 6b0f6c0f887ede7a2e7aa3309241b3b39844f5a2819f92fafdee52b1be4e88a2c9fc5a32f18ddcc3e0a671c0dedb4724de833da75d4c391a62619b8d4be58136
+  metadata.gz: 6e9e20049c86bab8649b3d53604a61438f27608ae62d009c6a556fe76b146e186072c46a4c5036173c3b40197d8648dee855dce401d4536060f269e159a40c98
+  data.tar.gz: 2ddccc6f2d1664935ba7c64b523f09b3a1ba9a57c7c356620beef39fd623b4a76a60d7fd1fda109aa11e9a5693a911cc1736d0f07dc99aad507008726d3fd301

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-15
+
+- Add `Component::TextArea` with multi-line editing, word navigation, and VT220-style Home/End handling.
+- Add `Component::Button`.
+- Add Tab / Shift+Tab focus cycling.
+- Add Ctrl+arrow word navigation to `Component::TextField`.
+- Add `Component::List#on_cursor_changed`.
+- Add `examples/sampler.rb`.
+- Paint `TextField` with a colored background.
+- Buffer `Screen#print` into a per-frame buffer during repaint, and release it on exception.
+- Join the key thread after killing it in `run_loop`'s ensure block.
+- Auto-clear gappy children in `Component#repaint`.
+- Inline a minimal truncation helper and drop the `strings-truncation` dependency.
+- Lower the Ruby floor to 3.4; pin CI head to 4.0; fix Ruby 3.4 compatibility.
+- Bump `minitest` to 6.0.
+- Document `TextField` SGR constants; refresh `sig/tuile.rbs`.
+
 ## [0.1.0] - 2026-05-02
 
 - Initial release

data/README.md

@@ -28,31 +28,28 @@ Ruby that we are aware of.
 
 ## Installation
 
-> **Note:** the gem name on RubyGems is being finalised. Until release, install
-> from git (see below). Replace
-> `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with
-> the gem name once published.
-
 Install the gem and add it to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add tuile
 ```
 
 If bundler is not being used to manage dependencies, install the gem by
 executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install tuile
 ```
 
-Until then, point your `Gemfile` at git:
+Or pin to git directly:
 
 ```ruby
 gem "tuile", git: "https://github.com/mvysny/tuile.git"
 ```
 
-Tuile requires Ruby 4.0+.
+Tuile requires Ruby 3.4+.
+
+API documentation: <https://rubydoc.info/gems/tuile>.
 
 ## Hello world
 

data/examples/file_commander.rb

@@ -156,22 +156,8 @@ module FileCommanderExample
                                            rect.width - half, body_height)
     end
 
-    def handle_key(key)
-      if key == "\t"
-        toggle_focus
-        true
-      else
-        super
-      end
-    end
-
     private
 
-    def toggle_focus
-      target = @left_window.active? ? @right_window : @left_window
-      screen.focused = target
-    end
-
     def refresh_header
       active_list = @left_list.active? ? @left_list : @right_list
       @header.text = " #{active_list.cwd}"

data/examples/sampler.rb

@@ -0,0 +1,287 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Tuile sampler. Two-pane demo app showcasing the components shipped with
+# the framework. The left pane is a navigation list; moving the cursor
+# loads the highlighted demo into the right pane. Tab / Shift+Tab move
+# focus between the list and the demo's widgets.
+#
+# Run from the gem root:
+#   bundle exec ruby -Ilib examples/sampler.rb
+#
+# Keys (global): q or ESC to quit.
+
+require "tuile"
+
+module SamplerExample
+  # Sampler-local container: a {Tuile::Component::Layout::Absolute} that
+  # runs a caller-supplied block on `rect=` to position its children.
+  # Sampler demos sometimes have a 1-row Label sitting in a tall pane,
+  # but the stock layout's auto-clear already handles those gaps for us
+  # — Panel just needs the rect-callback to drive child positioning.
+  class Panel < Tuile::Component::Layout::Absolute
+    def initialize(&layout_block)
+      super()
+      @layout_block = layout_block
+    end
+
+    def rect=(new_rect)
+      super
+      @layout_block&.call(rect) unless rect.empty?
+    end
+  end
+
+  # Top-level sampler component. Splits the screen into a left entry list
+  # and a right demo pane; each `load_entry` rebuilds the demo from
+  # scratch so it always starts in a clean state.
+  class Sampler < Tuile::Component::Layout::Absolute
+    def initialize
+      super()
+      @entry_list = build_entry_list
+      @left_window = Tuile::Component::Window.new("Components").tap { it.content = @entry_list }
+      @right_window = Tuile::Component::Window.new
+      add(@left_window)
+      add(@right_window)
+      load_entry(0)
+    end
+
+    attr_reader :left_window, :right_window, :entry_list
+
+    def rect=(new_rect)
+      super
+      return if rect.empty?
+
+      list_width = (rect.width / 3).clamp(20, 40)
+      @left_window.rect = Tuile::Rect.new(rect.left, rect.top, list_width, rect.height)
+      @right_window.rect = Tuile::Rect.new(rect.left + list_width, rect.top,
+                                           rect.width - list_width, rect.height)
+    end
+
+    private
+
+    # Ordered list of demo entries: `[caption, builder_method]`. The
+    # builder runs at selection time, so every load gets a fresh component
+    # tree (an empty TextField, an un-clicked Button, etc.).
+    ENTRIES = [
+      ["Label",        :build_label],
+      ["TextField",    :build_text_field],
+      ["TextArea",     :build_text_area],
+      ["Button",       :build_buttons],
+      ["List",         :build_list],
+      ["Layout",       :build_layout],
+      ["Popup",        :build_popup_launcher],
+      ["InfoWindow",   :build_info_launcher],
+      ["PickerWindow", :build_picker_launcher],
+      ["LogWindow",    :build_log_window],
+      ["Focus & Tab",  :build_focus_demo]
+    ].freeze
+
+    def build_entry_list
+      list = Tuile::Component::List.new
+      list.cursor = Tuile::Component::List::Cursor.new
+      list.lines = ENTRIES.map(&:first)
+      list.on_cursor_changed = ->(idx, _line) { load_entry(idx) if idx >= 0 }
+      list
+    end
+
+    def load_entry(idx)
+      caption, builder = ENTRIES[idx]
+      @right_window.caption = caption
+      @right_window.content = send(builder)
+    end
+
+    # --- Tileable demos ----------------------------------------------------
+
+    def build_label
+      label = Tuile::Component::Label.new
+      label.text = "Label paints static text in its rect.\n" \
+                   "Multiple lines split on \\n.\n" \
+                   "Long lines are clipped to the rect width.\n\n" \
+                   "Rainbow formatting works too:\n" \
+                   "  #{Rainbow("* red").red}\n" \
+                   "  #{Rainbow("* green").green}\n" \
+                   "  #{Rainbow("* blue").blue}"
+      label
+    end
+
+    def build_text_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, then type. Arrows, Home/End, Backspace, Delete all work."
+      field = Tuile::Component::TextField.new
+      panel(prompt, field) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 1)
+        field.rect = Tuile::Rect.new(inner.left, inner.top + 3, inner.width, 1)
+      end
+    end
+
+    def build_text_area
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Multi-line input. Type to see word wrap; Enter inserts a newline.\n" \
+                    "Arrows move the caret; Ctrl+Left/Right jump by word; " \
+                    "Home/End jump to row start/end; Up/Down at the first/last row jumps to text start/end.\n" \
+                    "Overflowing rows scroll vertically to keep the caret visible."
+      area = Tuile::Component::TextArea.new
+      area.text = "The quick brown fox jumps over the lazy dog. " \
+                  "Edit me — the text wraps to the area's width and scrolls vertically " \
+                  "once the cursor leaves the visible rows."
+      panel(prompt, area) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
+        area_height = [inner.height - 6, 4].max
+        area.rect = Tuile::Rect.new(inner.left, inner.top + 5, inner.width, area_height)
+      end
+    end
+
+    def build_buttons
+      label = Tuile::Component::Label.new
+      label.text = "Buttons fire on Enter, Space, or a left-click. Tab to focus, then activate."
+      counters = { ok: 0, cancel: 0 }
+      result = Tuile::Component::Label.new
+      refresh = -> { result.text = "Clicks: OK=#{counters[:ok]}  Cancel=#{counters[:cancel]}" }
+      refresh.call
+      ok = Tuile::Component::Button.new("OK") do
+        counters[:ok] += 1
+        refresh.call
+      end
+      cancel = Tuile::Component::Button.new("Cancel") do
+        counters[:cancel] += 1
+        refresh.call
+      end
+      panel(label, ok, cancel, result) do |r|
+        inner = inner_rect(r)
+        label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
+        ok.rect = Tuile::Rect.new(inner.left, inner.top + 4, ok.content_size.width, 1)
+        cancel.rect = Tuile::Rect.new(inner.left + ok.content_size.width + 2, inner.top + 4,
+                                      cancel.content_size.width, 1)
+        result.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+      end
+    end
+
+    def build_list
+      list = Tuile::Component::List.new
+      list.cursor = Tuile::Component::List::Cursor.new
+      list.lines = (1..40).map { |i| "Item #{i}" }
+      list.scrollbar_visibility = :visible
+      list
+    end
+
+    def build_layout
+      left = Tuile::Component::Window.new("Left")
+      left.content = Tuile::Component::Label.new.tap { it.text = "Nested left window." }
+      right = Tuile::Component::Window.new("Right")
+      right.content = Tuile::Component::Label.new.tap { it.text = "Nested right window." }
+      panel(left, right) do |r|
+        half = r.width / 2
+        left.rect = Tuile::Rect.new(r.left, r.top, half, r.height)
+        right.rect = Tuile::Rect.new(r.left + half, r.top, r.width - half, r.height)
+      end
+    end
+
+    # --- Modal launchers ---------------------------------------------------
+
+    def build_popup_launcher
+      launcher(
+        "Popup is a modal overlay wrapping any Component.\n" \
+        "ESC or q closes it.",
+        "Open Popup"
+      ) do
+        list = Tuile::Component::List.new
+        list.lines = ["Hello", "from", "a Popup!", "", "Press ESC to close."]
+        Tuile::Component::Popup.new(content: list).open
+      end
+    end
+
+    def build_info_launcher
+      launcher(
+        "InfoWindow is a Window of read-only text lines, openable as a popup.",
+        "Open InfoWindow"
+      ) do
+        Tuile::Component::InfoWindow.open(
+          "Hello",
+          ["InfoWindow displays static text",
+           "inside a popup.",
+           "",
+           "Press ESC or q to close."]
+        )
+      end
+    end
+
+    def build_picker_launcher
+      launcher(
+        "PickerWindow asks the user to pick one option by a single keystroke.",
+        "Open PickerWindow"
+      ) do
+        Tuile::Component::PickerWindow.open(
+          "Pick a fruit",
+          [%w[a Apple], %w[b Banana], %w[c Cherry]]
+        ) { |key| Tuile.logger.info("Picked: #{key}") }
+      end
+    end
+
+    def build_log_window
+      log = Tuile::Component::LogWindow.new("Log")
+      log.content.add_lines([
+                              "LogWindow is a Window wrapping an auto-scrolling List.",
+                              "Lines are appended via #add_line / #add_lines.",
+                              "Used with Logger::IO it captures arbitrary log output."
+                            ])
+      log
+    end
+
+    # --- Cross-cutting -----------------------------------------------------
+
+    def build_focus_demo
+      label = Tuile::Component::Label.new
+      label.text = "Tab and Shift+Tab cycle focus through the tab stops below.\n" \
+                   "The active button highlights its background; the field shows a caret."
+      a = Tuile::Component::Button.new("Button A")
+      b = Tuile::Component::Button.new("Button B")
+      field = Tuile::Component::TextField.new
+      panel(label, a, b, field) do |r|
+        inner = inner_rect(r)
+        label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
+        a.rect = Tuile::Rect.new(inner.left, inner.top + 4, a.content_size.width, 1)
+        b.rect = Tuile::Rect.new(inner.left + a.content_size.width + 2, inner.top + 4,
+                                 b.content_size.width, 1)
+        field.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+      end
+    end
+
+    # --- Helpers -----------------------------------------------------------
+
+    def panel(*children, &layout_block)
+      p = Panel.new(&layout_block)
+      p.add(children)
+      p
+    end
+
+    def launcher(description, button_caption, &on_click)
+      label = Tuile::Component::Label.new
+      label.text = description
+      button = Tuile::Component::Button.new(button_caption, &on_click)
+      panel(label, button) do |r|
+        inner = inner_rect(r)
+        label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
+        button.rect = Tuile::Rect.new(inner.left, inner.top + 5, button.content_size.width, 1)
+      end
+    end
+
+    # Carves a 2-column padding out of the panel rect so the demo content
+    # doesn't run flush to the window border.
+    def inner_rect(rect)
+      pad = 2
+      Tuile::Rect.new(rect.left + pad, rect.top, [rect.width - (pad * 2), 0].max, rect.height)
+    end
+  end
+end
+
+screen = Tuile::Screen.new
+sampler = SamplerExample::Sampler.new
+screen.content = sampler
+sampler.entry_list.focus
+begin
+  screen.run_event_loop
+ensure
+  screen.close
+end

data/lib/tuile/component/button.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A clickable button. Activated by Enter, Space, or a left mouse click;
+    # fires the {#on_click} callback. Renders as `[ caption ]` on a single
+    # row; the background is highlighted when the button is focused so the
+    # user can see which button is active.
+    #
+    # Buttons are tab stops — Tab and Shift+Tab will land on them as part of
+    # the standard focus cycle. Click-to-focus also works via the inherited
+    # {Component#handle_mouse}.
+    #
+    # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
+    # show `[ caption ]`; {#content_size} reports that natural width.
+    class Button < Component
+      # @param caption [String] the button's label.
+      # @yield optional `on_click` callback; same as assigning {#on_click=}.
+      def initialize(caption = "", &on_click)
+        super()
+        @caption = caption.to_s
+        @on_click = on_click
+      end
+
+      # @return [String] the button's label.
+      attr_reader :caption
+
+      # Callback fired when the button is activated (Enter, Space, or
+      # left-click). The callable receives no arguments.
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      attr_accessor :on_click
+
+      # Sets a new caption and invalidates the button. No-op if unchanged.
+      # @param new_caption [String]
+      def caption=(new_caption)
+        new_caption = new_caption.to_s
+        return if @caption == new_caption
+
+        @caption = new_caption
+        invalidate
+      end
+
+      def focusable? = true
+
+      def tab_stop? = true
+
+      # @return [Size] natural width is `caption.length + 4` to fit
+      #   `[ caption ]`; height is 1.
+      def content_size = Size.new(@caption.length + 4, 1)
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return false unless active?
+        return true if super
+
+        case key
+        when Keys::ENTER, " "
+          @on_click&.call
+          true
+        else
+          false
+        end
+      end
+
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        return unless event.button == :left && rect.contains?(event.point)
+
+        @on_click&.call
+      end
+
+      # @return [void]
+      def repaint
+        super
+        return if rect.empty?
+
+        label = "[ #{@caption} ]"[0, rect.width]
+        styled = active? ? Rainbow(label).bg(:darkslategray) : label
+        screen.print TTY::Cursor.move_to(rect.left, rect.top), styled
+      end
+    end
+  end
+end

data/lib/tuile/component/label.rb

@@ -29,7 +29,7 @@ module Tuile
 
       # @return [void]
       def repaint
-        clear_background
+        super
         height = rect.height.clamp(0, nil)
         lines_to_print = @clipped_lines.length.clamp(nil, height)
         (0..lines_to_print - 1).each do |index|
@@ -51,7 +51,7 @@ module Tuile
       def update_clipped_text
         len = rect.width.clamp(0, nil)
         clipped = @lines.map do |line|
-          Strings::Truncation.truncate(line, length: len)
+          Truncate.truncate(line, length: len)
         end
         return if @clipped_lines == clipped
 

data/lib/tuile/component/layout.rb

@@ -5,9 +5,11 @@ module Tuile
     # A layout doesn't paint anything by itself: its job is to position child
     # components.
     #
-    # All children must completely cover the contents of a layout: that way,
-    # the layout itself doesn't have to draw and no clipping algorithm is
-    # necessary.
+    # Children that fully tile the layout's rect repaint themselves and
+    # cover everything; children that leave gaps (e.g. a form with widgets
+    # of varying widths) trigger {Component#repaint}'s default behavior —
+    # the background is cleared and children are re-invalidated so they
+    # paint over a clean surface.
     class Layout < Component
       def initialize
         super
@@ -17,6 +19,16 @@ module Tuile
       # @return [Array<Component>]
       def children = @children.to_a
 
+      # Layouts are focusable containers — like {Window} and {Popup}, they
+      # don't accept input themselves but they need to participate in the
+      # {HasContent} focus cascade so a Popup wrapping a Layout wrapping a
+      # {TextField} ends up focusing the field rather than parking focus on
+      # the popup. Layouts don't paint any visible chrome of their own
+      # (the auto-cleared background is just blank space), so this has no
+      # mouse-routing consequences — clicks on a gap area land back on the
+      # Layout itself and the on_focus cascade forwards to a tab stop.
+      def focusable? = true
+
       # Adds a child component to this layout.
       # @param child [Component, Array<Component>]
       # @return [void]
@@ -53,11 +65,6 @@ module Tuile
         Size.new(right - rect.left, bottom - rect.top)
       end
 
-      # @return [void]
-      def repaint
-        clear_background if @children.empty?
-      end
-
       # Dispatches the event to the child under the mouse cursor.
       # @param event [MouseEvent]
       # @return [void]
@@ -83,10 +90,20 @@ module Tuile
       # @return [void]
       def on_focus
         super
-        # Let the content component receive focus, so that it can immediately
-        # start responding to key presses.
-        first_focusable = @children.find(&:focusable?)
-        screen.focused = first_focusable unless first_focusable.nil?
+        # Forward focus to the first interactive widget in the subtree so the
+        # user can start typing / cursoring immediately. Prefer a {#tab_stop?}
+        # descendant (TextField, List, Button…) so we skip past intermediate
+        # containers like a {Window} or another {Layout}. Fall back to the
+        # first focusable direct child for the rare case where the layout has
+        # focusable but non-tab-stop children (e.g. an empty {Window}).
+        first_tab_stop = nil
+        on_tree { |c| first_tab_stop ||= c if !c.equal?(self) && c.tab_stop? }
+        if first_tab_stop
+          screen.focused = first_tab_stop
+        else
+          first_focusable = @children.find(&:focusable?)
+          screen.focused = first_focusable unless first_focusable.nil?
+        end
       end
 
       # Absolute layout. Extend this class, register any children, and