tuile 0.4.0 → 0.6.0

data/lib/tuile/component/window.rb

@@ -19,9 +19,12 @@ module Tuile
         super()
         @border_right = 1
         @caption = caption
+        @content = nil
         # Optional bottom-row chrome that overlays the bottom border (e.g. a
         # search field).
         @footer = nil
+        @footer_sizing = Sizing::FILL
+        update_content_size
       end
 
       def focusable? = true
@@ -30,8 +33,25 @@ module Tuile
       #   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.
+      # @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.
       #
       # Symmetric to {#content=}: validates the new component, swaps parent
       # pointers, invalidates the old/new components and the window border, and
@@ -110,20 +130,36 @@ module Tuile
       def caption=(new_caption)
         @caption = new_caption
         invalidate
+        update_content_size
       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)
+      # 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.
@@ -150,6 +186,7 @@ module Tuile
         super
         # The shortcut key is shown in the caption — repaint.
         invalidate
+        update_content_size
       end
 
       protected
@@ -166,7 +203,7 @@ module Tuile
         return if rect.empty?
 
         frame = build_frame(frame_caption)
-        frame = Rainbow(frame).green if active?
+        frame = screen.theme.active_border(frame) if active?
         screen.print frame
       end
 
@@ -206,11 +243,28 @@ module Tuile
 
       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.
       # @return [void]
       def layout_footer
         return if @footer.nil? || rect.empty?
 
-        width = [rect.width - 2, 0].max
+        available = [rect.width - 2, 0].max
+        width = @footer_sizing.resolve(available, @footer.content_size.width)
         @footer.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
       end
     end

data/lib/tuile/component.rb

@@ -12,6 +12,8 @@ module Tuile
     def initialize
       @rect = Rect.new(0, 0, 0, 0)
       @active = false
+      @content_size = Size::ZERO
+      @on_theme_changed = nil
     end
 
     # @return [Rect] the rectangle the component occupies on screen.
@@ -195,6 +197,38 @@ module Tuile
     # @return [void]
     def on_focus; end
 
+    # Optional zero-arg listener fired by the base {#on_theme_changed} — the
+    # composition-style alternative to overriding the method, for apps that
+    # assemble stock components rather than subclass:
+    #
+    #   label.on_theme_changed = -> { label.text = render_status_line }
+    #
+    # @return [Proc, nil]
+    attr_writer :on_theme_changed
+
+    # Called on every attached component (pre-order, popups included) when
+    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=}
+    # assignment and on OS appearance flips.
+    #
+    # Built-in components read {Screen#theme} at paint time, so their accents
+    # restyle automatically; this hook exists for *content* whose colors the
+    # app baked in from the old theme — a {Label#text} / {List#lines} /
+    # {TextView#text} {StyledString} styled with `theme[:accent]` and the
+    # like. Only the app knows which of its colors were theme-derived (as
+    # opposed to inherent to the data, e.g. log-level colors), so it rebuilds
+    # them here, re-running the same code that rendered them initially.
+    #
+    # Runs on the UI thread; {Screen#theme} already returns the new theme.
+    # Mutating content (`text=`, `lines=`, …) is safe — repaint coalesces per
+    # event-loop tick. Do not assign {Screen#theme=} from inside the hook.
+    #
+    # Subclasses overriding this should call `super` so an assigned
+    # {#on_theme_changed=} listener keeps firing.
+    # @return [void]
+    def on_theme_changed
+      @on_theme_changed&.call
+    end
+
     # @return [Boolean] true if this component's tree is currently mounted on
     #   the {Screen}, i.e. its root is the {ScreenPane}.
     def attached? = root == screen.pane
@@ -225,12 +259,27 @@ module Tuile
 
     # The {Size} big enough to show the entire component contents without
     # scrolling. Plain components have no intrinsic content and report
-    # {Size::ZERO}; container/decorative components (e.g. {Label}, {List},
-    # {Layout}, {Window}) override this to fold in their content's natural
-    # extent. Used by callers like {Component::Popup} to auto-size to
-    # whatever content was assigned, regardless of its concrete type.
+    # {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]
-    def content_size = Size::ZERO
+    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
@@ -253,6 +302,26 @@ module Tuile
     # @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}.
     #

data/lib/tuile/event_queue.rb

@@ -47,17 +47,56 @@ 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.
+    #
+    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
+    # stop it.
+    #
+    # **Errors:** if `block` raises, the {Ticker} cancels itself and the
+    # exception flows through the normal event-loop error path — i.e.
+    # {Screen#on_error} for the default Tuile setup. Auto-cancel prevents a
+    # broken block from spamming `on_error` at the tick rate.
+    #
+    # Tickers reuse `concurrent-ruby`'s shared timer thread
+    # ({Concurrent}.global_timer_set) — adding more tickers does not add more
+    # threads, just more work on the shared scheduler.
+    #
+    # @param fps [Numeric] firings per second, must be positive. Fractional
+    #   values are fine (`fps: 0.5` ⇒ one tick 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)
+      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)
+    end
+
     # Runs the event loop and blocks. Must be run from at most one thread at the
     # same time. Blocks until some thread calls {#stop}. Calls block for all
-    # events submitted via {#post}; the block is always called from the thread
-    # running this function.
+    # events; the block is always called from the thread running this function.
     #
-    # Any exception raised by block is re-thrown, causing this function to
-    # terminate.
-    # @yield [event] called for each non-internal event.
+    # Any exception raised by the block is re-thrown, causing this function to
+    # terminate. Wrap the block body in `rescue` if you want to handle errors
+    # without tearing down the loop — see {Screen#event_loop} for an example.
+    #
+    # **Procs are yielded too.** A {#submit}ed block arrives as a `Proc` event;
+    # the consumer is responsible for invoking it (typically `event.call`).
+    # Yielding rather than dispatching inline means a raise inside the
+    # submitted block flows through the consumer's `rescue` like any other
+    # event-handler error, instead of bypassing it.
+    # @yield [event] called for each posted event.
     # @yieldparam event [Object] a posted event — typically a {KeyEvent},
-    #   {MouseEvent}, {TTYSizeEvent}, {EmptyQueueEvent}, or any object pushed
-    #   via {#post}.
+    #   {MouseEvent}, {TTYSizeEvent}, {EmptyQueueEvent}, a `Proc` from {#submit},
+    #   or any object pushed via {#post}. {ErrorEvent}s are not yielded — they
+    #   terminate the loop directly.
     # @yieldreturn [void]
     # @return [void]
     def run_loop(&)
@@ -145,6 +184,31 @@ module Tuile
       def size = Size.new(width, height)
     end
 
+    # The terminal's color scheme changed — the user flipped the OS between
+    # light and dark appearance. Terminals supporting mode 2031 (kitty,
+    # foot, contour, ghostty, …) push the DSR-style report `\e[?997;1n`
+    # (dark) / `\e[?997;2n` (light) once {Screen#run_event_loop} enables
+    # the mode via {TerminalBackground::NOTIFY_ON}; the key thread parses
+    # it into this event and {Screen#event_loop} follows by assigning the
+    # matching {Theme}.
+    #
+    # @!attribute [r] scheme
+    #   @return [Symbol] `:light` or `:dark`.
+    class ColorSchemeEvent < Data.define(:scheme)
+      # The DSR-style color-scheme report: `\e[?997;1n` dark, `\e[?997;2n`
+      # light.
+      # @return [Regexp]
+      REPORT = /\A\e\[\?997;([12])n\z/
+
+      # @param key [String] key read via {Keys.getkey}.
+      # @return [ColorSchemeEvent, nil] nil when `key` is not a
+      #   color-scheme report.
+      def self.parse(key)
+        match = REPORT.match(key)
+        match && new(match[1] == "2" ? :light : :dark)
+      end
+    end
+
     # Emitted once when the queue is cleared, all messages are processed and the
     # event loop will block waiting for more messages. Perfect time for
     # repainting windows.
@@ -152,6 +216,64 @@ module Tuile
       include Singleton
     end
 
+    # Handle returned by {EventQueue#tick}. Cancel a running ticker via
+    # {#cancel}.
+    #
+    # Internally wraps a `Concurrent::TimerTask` whose firing posts a single
+    # submit-block to the owning {EventQueue}; the user's block therefore
+    # always runs on the event-loop thread and may freely mutate UI. If the
+    # user block raises, the Ticker auto-cancels and the exception is
+    # re-raised so it flows through the loop's normal error handling
+    # ({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 block [Proc] called as `block.call(tick_count)` on each fire.
+      def initialize(event_queue, fps, block)
+        @event_queue = event_queue
+        @block = block
+        @tick = 0
+        # AtomicBoolean rather than a plain ivar: cancel may run on any
+        # thread (caller code, the event-loop thread from inside the block,
+        # or the IO executor on an error path), and we want both a CAS-style
+        # 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
+          @event_queue.submit { fire }
+        end
+        @timer.execute
+      end
+
+      # @return [Boolean] true once {#cancel} has been called.
+      def cancelled? = @cancelled.true?
+
+      # Stops the ticker. Idempotent and safe to call from any thread,
+      # including from inside the tick block. Any tick already queued on the
+      # event loop at the moment of cancellation is dropped before the user
+      # block runs.
+      # @return [void]
+      def cancel
+        return unless @cancelled.make_true # CAS: only the winner shuts down
+
+        @timer.shutdown
+      end
+
+      private
+
+      # Runs on the event-loop thread.
+      # @return [void]
+      def fire
+        return if @cancelled.true?
+
+        @block.call(@tick)
+        @tick += 1
+      rescue StandardError
+        cancel
+        raise
+      end
+    end
+
     private
 
     # @return [void]
@@ -169,8 +291,6 @@ module Tuile
             # while the loop's own backtrace shows up in the wrapper.
             raise Tuile::Error, "background event raised: #{event.error.class}: #{event.error.message}"
           end
-        elsif event.is_a? Proc
-          event.call
         else
           yield event
         end
@@ -183,8 +303,7 @@ module Tuile
       @key_thread = Thread.new do
         loop do
           key = Keys.getkey
-          event = MouseEvent.parse(key)
-          event = KeyEvent.new(key) if event.nil?
+          event = MouseEvent.parse(key) || ColorSchemeEvent.parse(key) || KeyEvent.new(key)
           post event
         end
       rescue StandardError => e

data/lib/tuile/fake_event_queue.rb

@@ -4,6 +4,10 @@ module Tuile
   # A "synchronous" event queue – no loop is run, submitted blocks are run right
   # away and submitted events are thrown away. Intended for testing only.
   class FakeEventQueue
+    def initialize
+      @tickers = []
+    end
+
     # @return [Boolean]
     def locked? = true
     # @return [void]
@@ -27,5 +31,70 @@ module Tuile
     # @param event [Object]
     # @return [void]
     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
+    # 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.
+    # @yield [tick] called on each {#tick_once}.
+    # @yieldparam tick [Integer] 0-based monotonically increasing counter.
+    # @yieldreturn [void]
+    # @return [FakeTicker]
+    def tick(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 }
+    end
+
+    # Test helper: fires every live ticker's user block once and prunes
+    # cancelled tickers. No-op when no tickers are registered. Pumps once
+    # per call regardless of any ticker's fps — the fake has no clock, so
+    # tests pump N frames by calling this N times.
+    # @return [void]
+    def tick_once
+      @tickers.reject!(&:cancelled?)
+      @tickers.each(&:fire)
+    end
+
+    # Handle returned by {FakeEventQueue#tick}. Mirrors the public surface of
+    # {EventQueue::Ticker} (`cancel`, `cancelled?`) but does not auto-fire —
+    # the host {FakeEventQueue} drives firing via {FakeEventQueue#tick_once}.
+    class FakeTicker
+      # @param block [Proc] called as `block.call(tick_count)` on each {#fire}.
+      def initialize(block)
+        @block = block
+        @tick = 0
+        @cancelled = false
+      end
+
+      # @return [Boolean] true once {#cancel} has been called.
+      def cancelled? = @cancelled
+
+      # Marks the ticker cancelled. Idempotent. Subsequent {#fire} calls are
+      # no-ops; {FakeEventQueue#tick_once} also prunes the ticker on its next
+      # pass.
+      # @return [void]
+      def cancel
+        @cancelled = true
+      end
+
+      # Invokes the user block with the current tick counter, then advances.
+      # No-op when {#cancelled?}. Typically driven by
+      # {FakeEventQueue#tick_once}; safe to call directly from a test that
+      # wants to drive a single ticker.
+      # @return [void]
+      def fire
+        return if @cancelled
+
+        @block.call(@tick)
+        @tick += 1
+      end
+    end
   end
 end

data/lib/tuile/fake_screen.rb

@@ -54,5 +54,13 @@ module Tuile
     def invalidated_clear
       @invalidated.clear
     end
+
+    private
+
+    # No terminal probing in tests: skip {TerminalBackground.detect}
+    # (which would write an OSC 11 query to the test runner's TTY and
+    # steal its input) and pin the deterministic default.
+    # @return [Symbol]
+    def detect_scheme = :dark
   end
 end

data/lib/tuile/keys.rb

@@ -160,6 +160,16 @@ module Tuile
         char += $stdin.read(6 - char.bytesize)
       end
 
+      # Private-mode CSI reports (`\e[?` params… final byte in 0x40..0x7E)
+      # can outgrow the 5-byte gulp above — the mode-2031 color-scheme
+      # notification `\e[?997;1n` (see {EventQueue::ColorSchemeEvent}) is 8
+      # bytes after the `\e`. Drain to the final byte with blocking 1-byte
+      # reads so the tail doesn't surface as phantom keypresses. Keyboard
+      # sequences never start with `\e[?`, so this can't eat a regular key.
+      if char.start_with?("\e[?")
+        char += $stdin.read(1) until char.match?(/[\x40-\x7e]\z/)
+      end
+
       char
     end
   end