tuile 0.16.0 → 0.17.0

data/lib/tuile/component/time_field.rb

@@ -7,7 +7,7 @@ module Tuile
     # {MIDNIGHT}. Give it a single-row {#rect}:
     #
     #   field = Component::TimeField.new
-    #   field.on_value_change = ->(t) { puts t&.strftime("%H:%M") }
+    #   field.on_value_change { |e| puts e.value&.strftime("%H:%M") }
     #   field.set_to(13, 45)   # field shows "13:45"
     #   field.placeholder      # => "hh:mm"
     #   field.value            # => 2000-01-01 13:45:00 UTC
@@ -157,8 +157,8 @@ module Tuile
         editor.max_text_length = MAX_TEXT_LENGTH
         # Claiming the editor's two arrow slots, not the general interceptor:
         # that one stays free for the app.
-        editor.on_key_up = -> { step_by(@step) }
-        editor.on_key_down = -> { step_by(-@step) }
+        editor.on_key_up { step_by(@step) }
+        editor.on_key_down { step_by(-@step) }
         @settled = false
         @placeholder_override = nil
         @step = DEFAULT_STEP
@@ -192,12 +192,13 @@ module Tuile
       # @return [void]
       # @raise [TypeError] on a `Date` (it has no hour, and midnight would be
       #   invented) or a `String` (that is what the buffer is for).
-      def value=(new_value)
-        editor.text = new_value.nil? ? "" : coerce(new_value).strftime(formats.first)
+      # @param from_user [Boolean] see {HasValue#set_value}.
+      def set_value(new_value, from_user:)
+        editor.set_value(new_value.nil? ? "" : coerce(new_value).strftime(formats.first), from_user:)
         editor.caret = editor.text.length
         # The edit above announced nothing ({#notify_on_edit?}); a time written
         # rather than typed has no prefix to be mistaken for a value.
-        fire_if_changed
+        fire_if_changed(from_user:)
       end
 
       # Sets the value from its parts, so nothing assembles a `Time` on the
@@ -320,6 +321,14 @@ module Tuile
       # @return [String, nil]
       def bad_input_message = value.nil? && !editor.text.empty? ? BAD_INPUT_MESSAGE : nil
 
+      # Every prefix of a time is bad input, so the report is latched to the
+      # commit gestures instead of shown per keystroke: `1`, `13`, `13:` on the
+      # way to `13:45` never redden and announce nothing, and a time the field
+      # cannot parse reddens the moment the user leaves the field or presses
+      # ENTER ({HasBadInput}).
+      # @return [Boolean]
+      def bad_input_settled? = @settled
+
       # Claims PageUp/PageDown for the hour step; they reach this field only
       # because the editor declines them.
       # @param key [String]
@@ -342,7 +351,8 @@ module Tuile
       # @return [void]
       def commit
         time = value
-        self.value = time unless time.nil? # …which unsettles, hence the order
+        # The user's: a commit gesture, and a held notice announces here.
+        set_value(time, from_user: true) unless time.nil? # …which unsettles, hence the order
         settle(true)
       end
 
@@ -352,20 +362,14 @@ module Tuile
       # @return [Boolean]
       def notify_on_edit? = false
 
-      # Every prefix of a time is bad input, so the well is latched to the
-      # commit gestures instead of painted per keystroke: `1`, `13`, `13:` on
-      # the way to `13:45` never redden, and a time the field cannot parse
-      # reddens the moment the user leaves the field or presses ENTER
-      # ({HasBadInput}).
-      # @return [Boolean]
-      def bad_input_settled? = @settled
-
       # An edit is the user having another go, so the well goes quiet again
       # until the next commit gesture.
       # @return [void]
       def handle_editor_change
-        super
+        # Unsettled before the sync riding `super`, which would otherwise read
+        # the new buffer against the old latch.
         settle(false)
+        super
       end
 
       # @return [void]
@@ -387,7 +391,7 @@ module Tuile
         sync_placeholder
         time = value || losslessly(carried)
         self.value = time unless time.nil?
-        fire_if_changed # for the buffer that just *stopped* parsing: nothing above touched it
+        fire_if_changed(from_user: false) # for the buffer that just *stopped* parsing: nothing above touched it
       end
 
       # A narrowing {#step=} must not discard seconds the user typed — but
@@ -432,14 +436,12 @@ module Tuile
       end
 
       # Steps {#value} by `delta` seconds; an empty or unparseable field steps
-      # to *now* ({#set_to_now}) instead, and `delta` is ignored.
+      # to *now* (as {#set_to_now} would) instead, and `delta` is ignored.
       # @param delta [Integer] seconds, either sign.
       # @return [void]
       def step_by(delta)
         time = value
-        return set_to_now if time.nil?
-
-        self.value = advance(time, delta)
+        set_value(time.nil? ? now : advance(time, delta), from_user: true)
       end
 
       # @param time [Time]
@@ -463,6 +465,9 @@ module Tuile
         # Nothing else painted: an ENTER on an untouched buffer writes no cells,
         # and neither does leaving the field with bad input in it.
         invalidate
+        # The latch moves without the buffer, so this is the one input to the
+        # showable report that {HasBadInput}'s edit funnel cannot see.
+        sync_bad_input
       end
 
       # @return [void]

data/lib/tuile/component/vertical_scroll_bar.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A one-column scrollbar the user can drag, and press the track of to page.
+    # It is chrome a container owns: you hand it a column, keep it told how
+    # tall the content is and how far it has scrolled, and listen for the row
+    # it asks for:
+    #
+    #   @scrollbar = VerticalScrollBar.new(row_count: @content_rows)
+    #   @scrollbar.on_scroll_request { self.scroll_top_row = _1.scroll_top_row }
+    #   add_child(@scrollbar)
+    #   # …and from wherever the geometry settles:
+    #   @scrollbar.rect = Rect.new(rect.width - 1, 0, 1, rect.height)
+    #   @scrollbar.scroll_top_row = @scroll_top_row
+    #
+    # **It never moves itself.** Both gestures compute a row and fire
+    # {#on_scroll_request}; nothing changes until the owner assigns
+    # {#scroll_top_row=}. So an unwired bar is inert — the honest picture,
+    # nothing behind it having scrolled either.
+    #
+    # **Dragging needs `run_event_loop(capture_mouse: :drag)`**: the `:clicks`
+    # default asks the terminal for no motion reports, so
+    # {Component#handle_mouse_drag} never fires and the handle sits still.
+    # Pressing the track works at every level.
+    #
+    # Its track is the whole {#rect} — no arrow buttons — so `rect.height` is
+    # the viewport height. The glyphs are the app-global {handle_char} /
+    # {track_char} pair and the color is `Theme#scrollbar_color`, read at paint
+    # time. {Scroller} is the worked example; why a component rather than drag
+    # handlers on the owner, and why the handle sits where it does, are
+    # `D_draggable_scrollbar`.
+    class VerticalScrollBar < Component
+      class << self
+        # The glyph drawn where the handle covers a row, `█` by default. Set
+        # the pair at startup for a lazygit-style bar:
+        #
+        #   Tuile::Component::VerticalScrollBar.handle_char = "▐"
+        #   Tuile::Component::VerticalScrollBar.track_char  = "│"
+        #
+        # Process-global, and assigning invalidates nothing — a change after
+        # the first paint shows up only where something repaints anyway. Why
+        # app-global rather than per instance is `D_scrollbar_ink`.
+        # @return [String]
+        attr_reader :handle_char
+
+        # The glyph drawn on the rows the handle doesn't cover, `░` by
+        # default — and on every row when nothing scrolls ({#repaint}).
+        # @return [String]
+        attr_reader :track_char
+
+        # @param char [String]
+        # @return [String]
+        # @raise [TypeError] when `char` is not a String.
+        # @raise [ArgumentError] when `char` is not exactly one grapheme
+        #   cluster one column wide.
+        def handle_char=(char)
+          @handle_char = StyledString.validate_glyph(char, :handle_char)
+        end
+
+        # @param char [String] see {handle_char=}.
+        # @return [String]
+        def track_char=(char)
+          @track_char = StyledString.validate_glyph(char, :track_char)
+        end
+      end
+
+      self.handle_char = "█"
+      self.track_char = "░"
+
+      # What {#on_scroll_request} fires.
+      #
+      # @!attribute [r] source
+      #   @return [VerticalScrollBar] the bar that was dragged or pressed.
+      # @!attribute [r] scroll_top_row
+      #   @return [Integer] the content row the user is asking to see at the
+      #     top, clamped so it never asks past the last scrollable row.
+      ScrollRequestEvent = Data.define(:source, :scroll_top_row) { include Tuile::Event }
+
+      # @!method on_scroll_request
+      #   Fired with a {ScrollRequestEvent} when a drag or a track press asks
+      #   for a row other than the current one — never from {#scroll_top_row=},
+      #   so an owner assigning the row it was just handed loops nothing.
+      #
+      #   **Empty means a bar that does not move**: it reports the request and
+      #   waits to be told, so nothing at all happens until somebody listens.
+      #   @return [Listeners]
+      listener :on_scroll_request
+
+      # @param row_count [Integer] see {#row_count=}.
+      # @param scroll_top_row [Integer] see {#scroll_top_row=}.
+      def initialize(row_count: 0, scroll_top_row: 0)
+        super()
+        @row_count = validate_rows(row_count, :row_count)
+        @scroll_top_row = validate_rows(scroll_top_row, :scroll_top_row)
+        @drag_origin = nil
+      end
+
+      # @return [Integer] how many rows of content the bar stands for.
+      attr_reader :row_count
+
+      # @return [Integer] the content row currently at the top of the viewport.
+      attr_reader :scroll_top_row
+
+      # @param count [Integer] `>= 0`.
+      # @raise [ArgumentError] unless a non-negative Integer.
+      # @return [void]
+      def row_count=(count)
+        count = validate_rows(count, :row_count)
+        return if @row_count == count
+
+        @row_count = count
+        invalidate
+      end
+
+      # Not clamped against {#row_count} — the owner's scroll state is
+      # authoritative, and a bar that silently disagreed with it would paint a
+      # handle where the content is not.
+      # @param row [Integer] `>= 0`.
+      # @raise [ArgumentError] unless a non-negative Integer.
+      # @return [void]
+      def scroll_top_row=(row)
+        row = validate_rows(row, :scroll_top_row)
+        return if @scroll_top_row == row
+
+        @scroll_top_row = row
+        invalidate
+      end
+
+      # @return [Boolean] whether there is content out of view — `false` also
+      #   for an empty rect, and what {#repaint} asks before drawing a handle.
+      def scrollable? = rect.height >= 1 && @row_count > rect.height
+
+      # Rows the handle covers, capped at one below the track so there is
+      # always somewhere to drag to: a 10-row viewport onto 11 rows of content
+      # gets a 9-row handle, not an immovable 10-row one.
+      # @return [Integer] `0` for an empty rect, the whole track when the
+      #   content fits (nothing is *painted* then — see {#repaint}).
+      def handle_height
+        return rect.height unless scrollable?
+
+        (rect.height**2.0 / @row_count).ceil.clamp(1, [rect.height - 1, 1].max)
+      end
+
+      # The handle's first row, mapped over the *free* track so that the last
+      # scrollable row puts the handle's last row at the bottom of the track.
+      # @return [Integer] 0-based row within the track; `0` when the content
+      #   fits.
+      def handle_start
+        free = free_rows
+        return 0 if free.zero?
+
+        (free * @scroll_top_row.clamp(0, max_top) / max_top.to_f).round
+      end
+
+      # One column wide, however wide a rect it was handed — which is also what
+      # the router hit-tests, so a press on the dead columns beside the bar
+      # reaches whatever is behind it instead.
+      # @return [Size]
+      def extent = Size.new([1, rect.width].min, rect.height)
+
+      # Claims every left press: on the handle it starts a drag, on the track
+      # it pages towards the pointer.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
+
+        @drag_origin = nil
+        if scrollable? && event.y >= handle_start && event.y < handle_start + handle_height
+          @drag_origin = [event.y, @scroll_top_row]
+        else
+          request(@scroll_top_row + (event.y < handle_start ? -page_rows : page_rows))
+        end
+        true
+      end
+
+      # Scrolls by how far the pointer has moved *since the press*, not by
+      # where it is. Absolute positioning would jump on the first report: the
+      # track has a row per several rows of content, so inverting the handle's
+      # rounded position does not give back the row it came from.
+      # @param event [Mouse::DragEvent]
+      # @return [void]
+      def handle_mouse_drag(event)
+        super
+        return if @drag_origin.nil? || free_rows.zero?
+
+        y_at_press, top_at_press = @drag_origin
+        request(top_at_press + ((event.y - y_at_press) * max_top / free_rows.to_f).round)
+      end
+
+      # @param event [Mouse::UpEvent]
+      # @return [void]
+      def handle_mouse_up(event)
+        super
+        @drag_origin = nil
+      end
+
+      # Paints {track_char} down the column with {handle_char} over it — and
+      # bare track when {#scrollable?} is false, a solid handle filling the
+      # track carrying no information (`D_scrollbar_ink`).
+      # @param canvas [Canvas] see {Component#repaint}.
+      # @return [void]
+      def repaint(canvas)
+        super
+        return if rect.empty?
+
+        style = StyledString::Style.new(fg: screen.theme.scrollbar_color)
+        handle = (handle_start...handle_start + handle_height) if scrollable?
+        rect.height.times do |row|
+          # Named, not `self.class` — a class-level ivar is not inherited, so a
+          # subclassed bar would read nil off its own class.
+          glyph = handle&.cover?(row) ? VerticalScrollBar.handle_char : VerticalScrollBar.track_char
+          canvas.set_char(0, row, glyph, style)
+        end
+      end
+
+      # @return [Array<String>]
+      def inspect_details = super + ["#{scroll_top_row}/#{row_count} rows"]
+
+      private
+
+      # @return [Integer] the largest {#scroll_top_row} that still fills the
+      #   viewport; `0` when the content fits.
+      def max_top = [@row_count - rect.height, 0].max
+
+      # @return [Integer] track rows the handle can travel over; `0` means no
+      #   drag is possible.
+      def free_rows = scrollable? ? rect.height - handle_height : 0
+
+      # @return [Integer] a viewport, at least one row.
+      def page_rows = [rect.height, 1].max
+
+      # Fires {#on_scroll_request} for `row`, clamped; silent on a no-op.
+      # @param row [Integer]
+      # @return [void]
+      def request(row)
+        row = row.clamp(0, max_top)
+        return if row == @scroll_top_row
+
+        on_scroll_request.fire(ScrollRequestEvent.new(source: self, scroll_top_row: row))
+      end
+
+      # @param rows [Integer]
+      # @param name [Symbol] the accessor, for the message.
+      # @return [Integer] `rows`.
+      # @raise [ArgumentError] unless `rows` is a non-negative Integer.
+      def validate_rows(rows, name)
+        unless rows.is_a?(Integer) && !rows.negative?
+          raise ArgumentError, "#{name} expects a non-negative Integer, got #{rows.inspect}"
+        end
+
+        rows
+      end
+    end
+  end
+end

data/lib/tuile/component/window.rb

@@ -66,17 +66,10 @@ module Tuile
       # @return [void]
       def footer=(new_footer)
         @footer_slot.content = new_footer
-        layout_footer
+        invalidate_layout
         invalidate # repaint border row that the footer covers/uncovers
       end
 
-      # @param new_rect [Rect]
-      # @return [void]
-      def rect=(new_rect)
-        super
-        layout_footer
-      end
-
       # @param value [Boolean]
       # @return [void]
       def scrollbar=(value)
@@ -88,7 +81,7 @@ module Tuile
         content.scrollbar_visibility = value ? :visible : :gone
         @border_right = value ? 0 : 1
         invalidate
-        layout(content)
+        invalidate_layout
       end
 
       # Fully repaints the window: the border ring here, the interior through
@@ -103,57 +96,65 @@ module Tuile
       # (`D_component_contract`). The ring is this window's own paint and the
       # interior is the content's, so the only cell nobody covers is an
       # interior with no content in it — cleared here, exactly.
+      # @param canvas [Canvas] see {Component#repaint}.
       # @return [void]
-      def repaint
+      def repaint(canvas)
         return if rect.empty?
 
-        clear_background(content_rect) if content.nil? && !content_rect.empty?
+        inner = content_rect
+        canvas.fill(inner) if content.nil? && !inner.empty?
         invalidate_children
-        repaint_border
+        repaint_border(canvas)
       end
 
       protected
 
-      # @param content [Component]
+      # The content takes the interior, the footer slot the bottom border row.
       # @return [void]
-      def layout(content) = content.rect = content_rect
+      def relayout
+        content&.rect = content_rect
+        layout_footer
+      end
 
       # The interior the content fills: inside the border on three sides, and on
       # the fourth only while there is a right border — {#scrollbar=} drops it so
       # the content's own bar takes that column.
+      #
+      # One rect for both jobs, since a window paints and places its children in
+      # the same coordinates: it is what {#relayout} assigns the content, and what
+      # {#repaint} blanks when there is no content to cover it.
       # @return [Rect] may be {Rect#empty? empty}, for a window too small to have
       #   an inside.
       def content_rect
-        Rect.new(rect.left + 1, rect.top + 1, rect.width - 1 - @border_right, rect.height - 2)
+        Rect.new(1, 1, rect.width - 1 - @border_right, rect.height - 2)
       end
 
-      # Paints the window border via {Component#draw_text}/{Component#draw_char},
-      # so the border cells inherit {Component#effective_bg_color} — a
+      # Paints the window border via {Canvas#set_text} / {Canvas#set_char},
+      # so the border cells inherit {ComponentBackground#effective} — a
       # {Component#bg_color} on the window tints border and content alike. Both
       # border rows are clipped by *display* width, so no caption overflows the
       # box; when the window is active the whole border — the caption's own
       # colors included — is drawn in {Theme#active_border_color}.
+      # @param canvas [Canvas] the surface to paint onto.
       # @return [void]
-      def repaint_border
+      def repaint_border(canvas)
         return if rect.empty?
 
         w = rect.width
         h = rect.height
-        top = rect.top
-        left = rect.left
         inner_w = [w - 2, 0].max
 
         fg = active? ? screen.theme.active_border_color : nil
         bar = StyledString::Style.new(fg: fg)
-        draw_text(left, top, top_border(inner_w, fg).slice(0, w))
-        (1..(h - 2)).each do |dy|
-          draw_char(left, top + dy, "│", bar)
+        canvas.set_text(0, 0, top_border(inner_w, fg).slice(0, w))
+        (1..(h - 2)).each do |row|
+          canvas.set_char(0, row, "│", bar)
           # Skipped once {#scrollbar=} has given that column to the content: the
           # bar would paint over the border anyway, and painting it first only
           # dirties the column into every frame's diff (`D_component_contract`).
-          draw_char(left + w - 1, top + dy, "│", bar) if @border_right.positive?
+          canvas.set_char(w - 1, row, "│", bar) if @border_right.positive?
         end
-        draw_text(left, top + h - 1, bottom_border(inner_w, fg).slice(0, w)) if h >= 2
+        canvas.set_text(0, h - 1, bottom_border(inner_w, fg).slice(0, w)) if h >= 2
       end
 
       # Builds the top border row: corners, {#caption} embedded at its own
@@ -204,7 +205,7 @@ module Tuile
         end
 
         width = [rect.width - 2, 0].max
-        @footer_slot.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
+        @footer_slot.rect = Rect.new(1, rect.height - 1, width, 1)
       end
     end
   end