tuile 0.7.0 → 0.9.0

data/lib/tuile/component/window.rb

@@ -20,38 +20,46 @@ module Tuile
         @border_right = 1
         @caption = caption
         @content = nil
-        # Optional bottom-row chrome that overlays the bottom border (e.g. a
-        # search field).
+        # Optional bottom-row widget slot (e.g. a search field), spanning the
+        # full inner width; and optional bottom-border chrome text embedded in
+        # the border line (mutually exclusive — the component, when present,
+        # occupies the row and hides the text).
         @footer = nil
-        @footer_sizing = Sizing::FILL
-        update_content_size
+        @footer_text = StyledString::EMPTY
       end
 
       def focusable? = true
 
-      # @return [Component, nil] optional component overlaying the bottom border
-      #   row.
+      # @return [Component, nil] optional focusable component occupying the
+      #   bottom border row, always spanning the full inner width.
       attr_reader :footer
 
-      # @return [Sizing] how the footer's width is computed from the window's
-      #   inner width; defaults to {Sizing::FILL} (the footer spans the full
-      #   inner width). The footer's height is always 1 (the border row).
-      attr_reader :footer_sizing
-
-      # Sets the footer width policy and re-lays-out the footer.
-      # @param sizing [Sizing]
-      def footer_sizing=(sizing)
-        raise TypeError, "expected Sizing, got #{sizing.inspect}" unless sizing.is_a?(Sizing)
-        return if @footer_sizing == sizing
-
-        @footer_sizing = sizing
-        layout_footer
-        invalidate # repaint border cells the footer may have just vacated
-      end
-
-      # Sets the bottom-row chrome slot. The footer overlays the bottom border
-      # row and is positioned automatically — its width is governed by
-      # {#footer_sizing}; pass `nil` to remove.
+      # @return [StyledString] optional chrome embedded into the bottom border
+      #   line, mirroring {#caption} on the top line. Empty by default; hidden
+      #   whenever a {#footer} component is present.
+      attr_reader :footer_text
+
+      # Sets the bottom-border chrome. Accepts a `String` (parsed via
+      # {StyledString.parse}), a {StyledString}, or `nil` (clears it). The text
+      # embeds into the bottom border at its own width with the border's dashes
+      # filling the remainder, clipped to the inner width — border decoration,
+      # not a component (not focusable). Hidden whenever a {#footer} component
+      # occupies the bottom row (see the precedence note on {#footer=}).
+      # @param text [String, StyledString, nil]
+      def footer_text=(text)
+        new_text = StyledString.parse(text)
+        return if @footer_text == new_text
+
+        @footer_text = new_text
+        invalidate # repaint the bottom border line
+      end
+
+      # Sets the bottom-row widget slot. The footer occupies the bottom border
+      # row, spanning the full inner width, and is positioned automatically;
+      # pass `nil` to remove.
+      #
+      # Precedence: a footer component present hides {#footer_text}; absent, the
+      # text embeds into the bottom border. No window needs both at once.
       #
       # Symmetric to {#content=}: validates the new component, swaps parent
       # pointers, invalidates the old/new components and the window border, and
@@ -83,14 +91,6 @@ module Tuile
         @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)
@@ -130,36 +130,6 @@ module Tuile
       def caption=(new_caption)
         @caption = new_caption
         invalidate
-        update_content_size
-      end
-
-      # Sets the new content. Also recomputes the window's natural size.
-      # @param new_content [Component, nil]
-      def content=(new_content)
-        super
-        update_content_size
-      end
-
-      # Re-lays-out a {Sizing::WRAP_CONTENT} footer when the footer's natural
-      # size changes, and folds a content resize into the window's own
-      # natural size (whose change then bubbles to the window's parent — e.g.
-      # a {Popup} re-self-sizes). The footer deliberately does *not*
-      # participate in the window's {#content_size}: it is decoration
-      # overlaying the border, and must not drive the window's size — if it
-      # doesn't fit, it is clipped to the inner width.
-      # @param child [Component]
-      # @return [void]
-      def on_child_content_size_changed(child)
-        if child.equal?(@footer)
-          old_rect = @footer.rect
-          layout_footer
-          # Repaint on any footer geometry change: a shrinking footer vacates
-          # border cells that must be re-dashed (a growing one merely
-          # overdraws, but distinguishing isn't worth the code).
-          invalidate if @footer.rect != old_rect
-        else
-          update_content_size
-        end
       end
 
       # Fully repaints the window: both frame and contents.
@@ -186,7 +156,6 @@ module Tuile
         super
         # The shortcut key is shown in the caption — repaint.
         invalidate
-        update_content_size
       end
 
       protected
@@ -197,14 +166,50 @@ module Tuile
         content.rect = Rect.new(rect.left + 1, rect.top + 1, rect.width - 1 - @border_right, rect.height - 2)
       end
 
-      # Paints the window border.
+      # Paints the window border into the {Screen#buffer}. Title is clipped to
+      # the inner width so the box never overflows {#rect}; when the window is
+      # active the whole border is drawn in {Theme#active_border_color}.
       # @return [void]
       def repaint_border
         return if rect.empty?
 
-        frame = build_frame(frame_caption)
-        frame = screen.theme.active_border(frame) if active?
-        screen.print frame
+        w = rect.width
+        h = rect.height
+        top = rect.top
+        left = rect.left
+        inner_w = [w - 2, 0].max
+        title = frame_caption.to_s
+        title = title[0, inner_w] if title.length > inner_w
+        dashes = "─" * (inner_w - title.length)
+
+        fg = active? ? screen.theme.active_border_color : nil
+        bar = StyledString::Style.new(fg: fg)
+        buf = screen.buffer
+        buf.set_line(left, top, StyledString.styled("┌#{title}#{dashes}┐", fg: fg))
+        (1..(h - 2)).each do |dy|
+          buf.set_char(left, top + dy, "│", bar)
+          buf.set_char(left + w - 1, top + dy, "│", bar)
+        end
+        buf.set_line(left, top + h - 1, bottom_border(inner_w, fg)) if h >= 2
+      end
+
+      # Builds the bottom border line. The corners take the border color; the
+      # interior is plain dashes when a {#footer} component occupies the row
+      # (it overpaints them) or when there's no chrome, otherwise it carries
+      # {#footer_text} embedded at its own width — keeping the text's own
+      # styling — with dashes filling the remainder up to the inner width.
+      # @param inner_w [Integer] the border's interior width.
+      # @param fg [Color, nil] the active-border color, or nil when inactive.
+      # @return [StyledString]
+      def bottom_border(inner_w, fg)
+        interior =
+          if @footer || @footer_text.empty?
+            StyledString.styled("─" * inner_w, fg: fg)
+          else
+            embedded = @footer_text.slice(0, inner_w)
+            embedded + StyledString.styled("─" * (inner_w - embedded.display_width), fg: fg)
+          end
+        StyledString.styled("└", fg: fg) + interior + StyledString.styled("┘", fg: fg)
       end
 
       # The caption text as it appears in the rendered border, including the
@@ -215,56 +220,16 @@ module Tuile
         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
 
-      # Recomputes the window's natural size: content's natural size (or the
-      # caption, whichever is wider) plus the 2-character border. The footer
-      # is deliberately excluded — see {#on_child_content_size_changed}. A
-      # window with no content or caption sizes to `Size.new(2, 2)` (bare
-      # border).
-      # @return [void]
-      def update_content_size
-        inner_w = [content&.content_size&.width || 0, frame_caption.length].max
-        inner_h = content&.content_size&.height || 0
-        self.content_size = Size.new(inner_w + 2, inner_h + 2)
-      end
-
-      # Positions the footer over the bottom border row, with its width
-      # resolved by {#footer_sizing} against the inner width. A
-      # {Sizing::WRAP_CONTENT} footer with zero natural width gets an empty
-      # rect — i.e. it is invisible, as if never assigned.
+      # Positions the footer over the bottom border row, spanning the full
+      # inner width (the only dimension a bottom-row widget needs — the window
+      # already knows it).
       # @return [void]
       def layout_footer
         return if @footer.nil? || rect.empty?
 
-        available = [rect.width - 2, 0].max
-        width = @footer_sizing.resolve(available, @footer.content_size.width)
+        width = [rect.width - 2, 0].max
         @footer.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
       end
     end

data/lib/tuile/component.rb

@@ -12,7 +12,6 @@ module Tuile
     def initialize
       @rect = Rect.new(0, 0, 0, 0)
       @active = false
-      @content_size = Size::ZERO
       @on_theme_changed = nil
     end
 
@@ -81,27 +80,22 @@ module Tuile
       children.each { |c| screen.invalidate(c) }
     end
 
-    # Called when a character is pressed on the keyboard.
+    # Called when a character is pressed on the keyboard. The default does
+    # nothing and reports the key as unhandled; input components
+    # ({Component::TextField}, {Component::List}, {Component::Button}, …)
+    # override it to act on keys they care about.
     #
-    # 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.
+    # Dispatch is owned by {ScreenPane#handle_key}: a {#key_shortcut} match
+    # anywhere in the active scope is captured first (suppressed while a
+    # cursor-owner is mid-edit), then the key is delivered to {Screen#focused}
+    # and bubbles up its ancestor chain until some component handles it. A
+    # component therefore only ever receives keys when it is on the focus chain
+    # — or when app code hands it a key directly — so it acts on the key alone
+    # and must never gate on its own {#active?} state.
+    # @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
+    def handle_key(_key)
+      false
     end
 
     # A global keyboard shortcut. When pressed, will focus this component.
@@ -257,30 +251,6 @@ module Tuile
       end
     end
 
-    # The {Size} big enough to show the entire component contents without
-    # scrolling. Plain components have no intrinsic content and report
-    # {Size::ZERO}; content-bearing components (e.g. {Label}, {List},
-    # {TextView}, {Window}) maintain it eagerly via {#content_size=} from
-    # their mutators, so reads are O(1). Used by callers like
-    # {Component::Popup} to auto-size to whatever content was assigned,
-    # regardless of its concrete type, and by {Sizing::WRAP_CONTENT} slots.
-    # @return [Size]
-    attr_reader :content_size
-
-    # Called by a child component whose {#content_size} just changed (fired
-    # from the child's {#content_size=}). Does nothing by default — a plain
-    # container is not size-coupled to its children. Containers that derive
-    # their own natural size or child layout from a child's natural size
-    # override this (e.g. {Component::Window} re-lays-out a
-    # {Sizing::WRAP_CONTENT} footer and recomputes its own size from content;
-    # {Component::Popup} re-self-sizes). If the receiver's own
-    # {#content_size} changes as a consequence, its {#content_size=} notifies
-    # *its* parent in turn — so the event bubbles exactly as far as geometry
-    # keeps changing, and stops where it doesn't.
-    # @param child [Component] the resized direct child.
-    # @return [void]
-    def on_child_content_size_changed(child); end
-
     # 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
@@ -295,33 +265,13 @@ module Tuile
 
     protected
 
-    # @param parent [Component, nil]
+    # @return [Component, nil]
     attr_writer :parent
 
     # Called whenever the component width changes. Does nothing by default.
     # @return [void]
     def on_width_changed; end
 
-    # Memoizes the component's natural size and notifies {#parent} via
-    # {#on_child_content_size_changed} when the value actually changed.
-    # Subclasses call this from their content mutators (`text=`, `add_lines`,
-    # `caption=`, …) instead of caching ad-hoc.
-    #
-    # Call this as the *last* step of a mutator: the parent hook may
-    # reentrantly reposition this component (assign {#rect} — e.g. {Window}
-    # re-laying-out a wrap-content footer, or {Popup} re-self-sizing), which
-    # triggers {#on_width_changed} and {#repaint}-related recomputation, so
-    # all internal state must already be consistent.
-    # @param new_size [Size]
-    # @return [void]
-    def content_size=(new_size)
-      raise TypeError, "expected Size, got #{new_size.inspect}" unless new_size.is_a?(Size)
-      return if @content_size == new_size
-
-      @content_size = new_size
-      parent&.on_child_content_size_changed(self)
-    end
-
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
     #
@@ -354,12 +304,7 @@ module Tuile
     # 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
+      screen.buffer.fill(rect)
     end
   end
 end

data/lib/tuile/event_queue.rb

@@ -47,10 +47,13 @@ module Tuile
       latch.wait
     end
 
-    # Schedules `block` to fire on the event-loop thread roughly `fps` times
-    # per second, passing a 0-based monotonically increasing tick counter. Use
-    # it for animations (e.g. a `/-\|` spinner in a {Component::Label}) or
-    # periodic UI refresh from a background task.
+    # Schedules `block` to fire on the event-loop thread every `seconds`,
+    # passing a 0-based monotonically increasing tick counter. The interval is
+    # in **seconds** — the conventional scheduling unit (`sleep`,
+    # `Concurrent::TimerTask#execution_interval`, …) — so `tick(0.2)` fires five
+    # times a second. Use it for periodic UI refresh from a background task
+    # (poll a status, redraw a clock). For animation, where frames-per-second
+    # is the natural unit, {#tick_fps} reads better.
     #
     # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
     # stop it.
@@ -64,19 +67,37 @@ module Tuile
     # ({Concurrent}.global_timer_set) — adding more tickers does not add more
     # threads, just more work on the shared scheduler.
     #
+    # @param seconds [Numeric] interval between firings, must be positive.
+    #   Fractional values are fine (`tick(0.05)` ⇒ ~20 firings a second).
+    # @yield [tick] called on the event-loop thread each firing.
+    # @yieldparam tick [Integer] 0-based monotonically increasing counter.
+    # @yieldreturn [void]
+    # @return [Ticker]
+    def tick(seconds, &block)
+      raise ArgumentError, "block required" unless block
+      unless seconds.is_a?(Numeric) && seconds.positive?
+        raise ArgumentError, "seconds must be a positive Numeric, got #{seconds.inspect}"
+      end
+
+      Ticker.new(self, seconds, block)
+    end
+
+    # Frames-per-second convenience over {#tick}: `tick_fps(15)` is exactly
+    # `tick(1.0 / 15)`. Reads naturally for animation (a `/-\|` spinner, a
+    # progress pulse) where you think in frames, not intervals.
     # @param fps [Numeric] firings per second, must be positive. Fractional
-    #   values are fine (`fps: 0.5` ⇒ one tick every two seconds).
+    #   values are fine (`tick_fps(0.5)` ⇒ one firing every two seconds).
     # @yield [tick] called on the event-loop thread each firing.
     # @yieldparam tick [Integer] 0-based monotonically increasing counter.
     # @yieldreturn [void]
     # @return [Ticker]
-    def tick(fps, &block)
+    def tick_fps(fps, &block)
       raise ArgumentError, "block required" unless block
       unless fps.is_a?(Numeric) && fps.positive?
         raise ArgumentError, "fps must be a positive Numeric, got #{fps.inspect}"
       end
 
-      Ticker.new(self, fps, block)
+      tick(1.0 / fps, &block)
     end
 
     # Runs the event loop and blocks. Must be run from at most one thread at the
@@ -227,9 +248,9 @@ module Tuile
     # ({Screen#on_error} for the default Tuile setup).
     class Ticker
       # @param event_queue [EventQueue] queue to dispatch tick calls onto.
-      # @param fps [Numeric] firings per second (positive).
+      # @param interval [Numeric] seconds between firings (positive).
       # @param block [Proc] called as `block.call(tick_count)` on each fire.
-      def initialize(event_queue, fps, block)
+      def initialize(event_queue, interval, block)
         @event_queue = event_queue
         @block = block
         @tick = 0
@@ -239,7 +260,7 @@ module Tuile
         # one-shot guard against double-shutdown and well-defined visibility
         # on non-MRI Rubies.
         @cancelled = Concurrent::AtomicBoolean.new(false)
-        @timer = Concurrent::TimerTask.new(execution_interval: 1.0 / fps) do
+        @timer = Concurrent::TimerTask.new(execution_interval: interval) do
           @event_queue.submit { fire }
         end
         @timer.execute

data/lib/tuile/fake_event_queue.rb

@@ -33,23 +33,39 @@ module Tuile
     def post(event); end
 
     # Mirrors {EventQueue#tick} but timeless: returns a {FakeTicker} that
-    # only fires when a test calls {#tick_once}. The `fps` argument is
+    # only fires when a test calls {#tick_once}. The `seconds` argument is
     # validated the same way the real queue validates it, then discarded —
     # the fake has no clock, so frame cadence is up to the test.
     #
-    # @param fps [Numeric] firings per second, must be positive. Validated
-    #   for parity with {EventQueue#tick}; otherwise unused.
+    # @param seconds [Numeric] interval between firings, must be positive.
+    #   Validated for parity with {EventQueue#tick}; otherwise unused.
     # @yield [tick] called on each {#tick_once}.
     # @yieldparam tick [Integer] 0-based monotonically increasing counter.
     # @yieldreturn [void]
     # @return [FakeTicker]
-    def tick(fps, &block)
+    def tick(seconds, &block)
+      raise ArgumentError, "block required" unless block
+      unless seconds.is_a?(Numeric) && seconds.positive?
+        raise ArgumentError, "seconds must be a positive Numeric, got #{seconds.inspect}"
+      end
+
+      FakeTicker.new(block).tap { |t| @tickers << t }
+    end
+
+    # Mirrors {EventQueue#tick_fps}: validates `fps` for parity, then delegates
+    # to {#tick} (the fake discards the interval regardless).
+    # @param fps [Numeric] firings per second, must be positive.
+    # @yield [tick] called on each {#tick_once}.
+    # @yieldparam tick [Integer] 0-based monotonically increasing counter.
+    # @yieldreturn [void]
+    # @return [FakeTicker]
+    def tick_fps(fps, &block)
       raise ArgumentError, "block required" unless block
       unless fps.is_a?(Numeric) && fps.positive?
         raise ArgumentError, "fps must be a positive Numeric, got #{fps.inspect}"
       end
 
-      FakeTicker.new(block).tap { |t| @tickers << t }
+      tick(1.0 / fps, &block)
     end
 
     # Test helper: fires every live ticker's user block once and prunes

data/lib/tuile/fake_screen.rb

@@ -25,10 +25,14 @@ module Tuile
       super
       @event_queue = FakeEventQueue.new
       @size = Size.new(160, 50)
+      @buffer.resize(@size) # super sized it to the test runner's TTY
       @prints = []
     end
 
-    # @return [Array<String>] whatever {#print} printed so far.
+    # @return [Array<String>] whatever {#print} / {#emit} produced so far.
+    #   Component painting lands in {#buffer}, not here — assert on
+    #   {Buffer#row_text} / {Buffer#row_ansi} / {Buffer#cell} for content, and
+    #   on `prints` for cursor and housekeeping escapes.
     attr_reader :prints
 
     # @return [void]
@@ -46,6 +50,15 @@ module Tuile
       @prints += args
     end
 
+    # Captures the assembled repaint frame instead of writing to the test
+    # runner's TTY. Lands in {#prints} so cursor/sync escapes can be asserted;
+    # painted content is read from {#buffer}.
+    # @param str [String]
+    # @return [void]
+    def emit(str)
+      @prints << str
+    end
+
     # @param component [Component] the component to check.
     # @return [Boolean]
     def invalidated?(component) = @invalidated.include?(component)

data/lib/tuile/fraction.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A width/height ratio, each a float in `0.0..1.0` — the single relational
+  # sizing primitive in Tuile. It exists for exactly one job: sizing a
+  # {Component::Popup} against the screen. A popup has no siblings competing for
+  # space and no rectangle in a tiled layout, so "half the screen, centered" is
+  # the sensible default, and that wants a ratio rather than a hard-coded cell
+  # count that would be wrong on the next terminal size.
+  #
+  # Tiled components are *not* sized this way: their parent computes explicit
+  # integer rects in its own `rect=` and hands them down. `Fraction` is
+  # deliberately scoped to {Component::Popup#size=} and is not a general layout
+  # primitive.
+  #
+  # Resolve it against a reference {Size} (the screen) to get concrete integer
+  # cells:
+  #
+  #   Fraction::HALF.resolve(Size.new(80, 24))  # => 40x12
+  #
+  # Integer arguments are coerced to float, so `Fraction.new(1, 1) == FULL`.
+  class Fraction < Data.define(:width, :height)
+    # @param width [Numeric] fraction of the reference width, `0.0..1.0`.
+    # @param height [Numeric] fraction of the reference height, `0.0..1.0`.
+    def initialize(width:, height:)
+      super(width: width.to_f, height: height.to_f)
+    end
+
+    # Resolves this fraction against a reference size, rounding each axis to the
+    # nearest cell and flooring at 1 — so a fraction never yields a zero-size
+    # result on a tiny terminal.
+    # @param reference [Size] the size to take a fraction of (usually the screen).
+    # @return [Size]
+    def resolve(reference)
+      Size.new([(reference.width * width).round, 1].max,
+               [(reference.height * height).round, 1].max)
+    end
+
+    # Half the reference size on each axis — the default {Component::Popup} size.
+    # @return [Fraction]
+    HALF = new(0.5, 0.5)
+    # The full reference size on each axis — fullscreen for a {Component::Popup}.
+    # @return [Fraction]
+    FULL = new(1.0, 1.0)
+  end
+end