tuile 0.11.0 → 0.12.0

data/lib/tuile/component/list_dropdown.rb

@@ -9,9 +9,10 @@ module Tuile
     # highlight, and reads the pick.
     #
     #   drop = Component::ListDropdown.new
-    #   drop.on_item_chosen = ->(index, _line) { commit(index) } # caller commits
+    #   drop.renderer = method(:label_for)                 # caller renders
+    #   drop.on_item_chosen = ->(_index, item) { commit(item) }   # caller commits
     #   # …then, from the driver's key handler:
-    #   drop.lines = matches.map { |m| render(m) }   # caller filters + renders
+    #   drop.items = matches                         # caller filters
     #   drop.anchor_to(rect, rows: matches.size)     # below the driver, or flipped
     #   drop.open
     #   return true if drop.move(key)  # Up/Down/PgUp/PgDn/^U/^D → list scroll
@@ -66,14 +67,20 @@ module Tuile
         self.bg_color = Theme.ref(:input_bg_color)
       end
 
-      # @param lines [Array] the rows to show; see {List#lines=}.
+      # @param items [Array] the items to show, one row each; see {List#items=}.
       # @return [void]
-      def lines=(lines)
-        @list.lines = lines
+      def items=(items)
+        @list.items = items
       end
 
-      # @return [Array<StyledString>] the current rows.
-      def lines = @list.lines
+      # @return [Array] the items currently shown.
+      def items = @list.items
+
+      # @param proc [Proc, Method] item -> row; see {List#renderer}.
+      # @return [void]
+      def renderer=(proc)
+        @list.renderer = proc
+      end
 
       # @param proc [Proc, Method, nil] commit callback; see {List#on_item_chosen}.
       # @return [void]

data/lib/tuile/component/notification.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A transient message in the screen's top-right corner — the TTY toast:
+    #
+    #   Component::Notification.show("Saved")
+    #   Component::Notification.show("Disk full", color: Theme.ref(:error))
+    #
+    #   ┌─────────┐  ← flush: row 0, right edge at the last column
+    #   │Saved    │  ← oldest on top, retires in 3 s
+    #   │Disk full│  ← then this one, 3 s after that
+    #   └─────────┘
+    #
+    # {show} is the only entry point ({new} is private): it finds the live
+    # notification and appends to it, so a burst stacks as entries in one box
+    # instead of opening five overlapping ones.
+    #
+    # One repeating ticker retires the **oldest** entry every {DISPLAY_SECONDS}
+    # and closes the box when the last one goes — five messages raised together
+    # appear at once and drain over fifteen seconds. A message arriving mid-cycle
+    # waits its turn and does *not* restart the clock, so the bottom entry of a
+    # full box is visible for about `N × DISPLAY_SECONDS`. Past {MAX_MESSAGES} a
+    # message is dropped and reported to {Tuile.logger}; an app notifying faster
+    # than that wants a {Component::LogWindow}.
+    #
+    # The box is flush to the corner, at most {WIDTH_FRACTION} of the screen wide
+    # (floor {MIN_CAP_WIDTH}) and {HEIGHT_FRACTION} tall, and **grows but never
+    # shrinks** while it lives; a long message wraps to {MAX_ROWS_PER_MESSAGE}
+    # rows and is then ellipsized, and entries past the height cap wait unpainted.
+    # `DECISIONS.md` `D-notification` has why each of those is what it is.
+    #
+    # Three things it deliberately doesn't do:
+    #
+    # - **Take focus, or receive keys.** A non-modal popup sits off the
+    #   key-dispatch scope ({ScreenPane#handle_key}), so not even {Popup}'s
+    #   `q`/ESC arrives here. A left click dismisses ({#handle_mouse}); an app
+    #   wanting a key registers a global shortcut and calls {#close}.
+    # - **Follow a theme flip.** A `Theme::Ref` `color:` is resolved once, when
+    #   the message is added — a toast lives seconds, so there is no
+    #   {Component#on_theme_changed} rebuild.
+    # - **Take a size.** {#size=} raises; the messages decide.
+    class Notification < Popup
+      # Most messages held at once, counting both the painted ones and any
+      # waiting for room. Chosen from reading time rather than geometry: the
+      # drain rate is one message per {DISPLAY_SECONDS}, so the queue length *is*
+      # a duration, and 5 × 3 s is about the longest a corner box should own the
+      # screen — and about as many short lines as anyone reads.
+      # @return [Integer]
+      MAX_MESSAGES = 5
+
+      # Rows a single message may occupy before it is ellipsized.
+      # @return [Integer]
+      MAX_ROWS_PER_MESSAGE = 3
+
+      # Seconds between retirements — how long the oldest message is held.
+      # @return [Float]
+      DISPLAY_SECONDS = 3.0
+
+      # Fraction of the screen width the box may not exceed (see {MIN_CAP_WIDTH}).
+      # @return [Float]
+      WIDTH_FRACTION = 0.4
+
+      # Fraction of the screen height the box may not exceed.
+      # @return [Float]
+      HEIGHT_FRACTION = 0.4
+
+      # Floor under the width cap, so 40 % of an 80-column terminal doesn't
+      # ellipsize every message down to five words.
+      # @return [Integer]
+      MIN_CAP_WIDTH = 34
+
+      # Separator for re-joining wrapped rows before ellipsizing.
+      # @return [StyledString]
+      SPACE = StyledString.parse(" ")
+
+      # Hard-line separator handed to {TextView#text=}.
+      # @return [StyledString]
+      ROW_BREAK = StyledString.parse("\n")
+      private_constant :SPACE, :ROW_BREAK
+
+      # Shows `text` in the corner, creating the box if none is open and
+      # appending to it if one is.
+      #
+      # @param text [String, StyledString, nil] the message. A `String` is parsed
+      #   via {StyledString.parse}, so embedded ANSI is honored. `nil` and the
+      #   empty string are no-ops (nothing is shown, nothing is created).
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      #   applied to every span of the message via {StyledString#with_fg}. A
+      #   {Theme::Ref} is resolved against the current theme *now* — see the
+      #   class docs on theme following. `nil` leaves the message's own colors
+      #   alone.
+      # @return [Notification, nil] the live notification, or `nil` when `text`
+      #   was empty.
+      # @raise [Tuile::Error] when the screen is closed, or when called from a
+      #   thread that doesn't currently own the UI — a background job raising a
+      #   notification must marshal it: `screen.event_queue.submit { ... }`.
+      def self.show(text, color: nil)
+        Screen.instance.check_locked
+        return nil if StyledString.parse(text).empty?
+
+        live = Screen.instance.pane.popups.find { _1.is_a?(Notification) }
+        return live.tap { _1.add_message(text, color: color) } unless live.nil?
+
+        # Message first, so the box is sized before it is mounted: opening an
+        # empty 0×0 popup and then growing it would paint a frame of nothing.
+        new.tap do |notification|
+          notification.add_message(text, color: color)
+          notification.open
+        end
+      end
+
+      private_class_method :new
+
+      def initialize
+        # Built before `super`, because Popup#initialize assigns the content and
+        # calls #reposition, and our override reads every one of these.
+        @messages = []
+        @high_water = 0
+        @ticker = nil
+        @view = TextView.new
+        @window = Window.new
+        @window.content = @view
+        super(content: @window, modal: false)
+      end
+
+      # Load-bearing, not cosmetic: focus landing inside a non-modal popup sits
+      # outside the key-dispatch scope, where {ScreenPane#handle_key} delivers to
+      # nobody — every keystroke would go dead until the user pressed Tab.
+      # @return [Boolean] false.
+      def focusable? = false
+
+      # @return [Boolean] false — see {#focusable?}.
+      def tab_stop? = false
+
+      # Empty: a non-modal popup never owns the status bar, and {Popup}'s
+      # inherited `q Close` hint would be a lie here — no key ever reaches a
+      # notification.
+      # @return [String]
+      def keyboard_hint = ""
+
+      # Appends a message, dropping it (with a {Tuile.logger} warning) once
+      # {MAX_MESSAGES} are held. Public so a caller holding the instance can
+      # append without repeating {show}'s lookup.
+      # @param text [String, StyledString, nil] see {show}. Empty is a no-op.
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      #   see {show}.
+      # @return [void]
+      # @raise [Tuile::Error] see {show}.
+      def add_message(text, color: nil)
+        # Explicit rather than inherited-through-invalidate: this appends to
+        # @messages before anything repaints, so a wrong-thread call has to fail
+        # before the message is recorded, not after.
+        screen.check_locked
+        message = build_message(text, color)
+        return if message.empty?
+
+        if @messages.size >= MAX_MESSAGES
+          Tuile.logger.warn("Notification: dropping #{message.to_s.inspect}, " \
+                            "#{MAX_MESSAGES} messages already queued")
+          return
+        end
+
+        @messages << message
+        @high_water = [@high_water, natural_width(message)].max
+        reposition
+        sync_ticker
+      end
+
+      # Recomputes the box from its messages and re-anchors it to the screen's
+      # top-right corner — so a SIGWINCH re-wraps and re-anchors, where
+      # {Popup#reposition} would have kept the stale left column of a *derived*
+      # position (off-screen entirely if the terminal narrowed).
+      #
+      # Rebuilds the {TextView}'s text too, and every mutation routes through
+      # here, because the four are one computation: the wrap width *is* the box
+      # width, the height *is* the wrapped row count, the left edge *is* derived
+      # from the width.
+      # @return [void]
+      def reposition
+        if @messages.empty?
+          self.rect = Rect.new(0, 0, 0, 0)
+          return
+        end
+
+        width = box_width
+        rows = @messages.flat_map { |message| wrap_message(message, width - 2) }
+        height = [rows.size + 2, cap_height].min
+        @size = Size.new(width, height)
+        @view.text = join_rows(rows)
+        self.rect = Rect.new([screen.size.width - width, 0].max, 0, width, height)
+      end
+
+      # A notification is sized by its messages, so this always raises. Failing
+      # loudly beats accepting a size the next {#reposition} would discard.
+      # @param _new_size [Size, Fraction]
+      # @raise [Tuile::Error] always.
+      # @return [void]
+      def size=(_new_size)
+        raise Tuile::Error, "Notification sizes itself from its messages; #{self.class}#size= is not settable"
+      end
+
+      # A left click dismisses the whole box, every message with it. Other buttons
+      # are consumed and inert — including the scroll wheel, which would otherwise
+      # nuke the box on a stray spin.
+      #
+      # Deliberately *replaces* rather than augments: neither `super` nor
+      # {HasContent#handle_mouse} may run, since both end at a
+      # `screen.focused = …` inside this subtree (see {#focusable?}).
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        close if event.button == :left
+      end
+
+      # @return [void]
+      def on_attached = sync_ticker
+
+      # @return [void]
+      def on_detached = sync_ticker
+
+      private
+
+      # Retires the oldest message, closing the box when it was the last. Runs on
+      # the event-loop thread, from the ticker.
+      # @return [void]
+      def retire_oldest
+        @messages.shift
+        @messages.empty? ? close : reposition
+        sync_ticker
+      end
+
+      # Syncs the retirement clock from the invariant "something to retire, and on
+      # screen" — the sole writer of `@ticker`. Four sites change whether it is
+      # wanted (append, a retirement that empties the queue, {#close}, detach),
+      # which is the 2×2 a start-in-{#on_attached} / cancel-in-{#on_detached} pair
+      # gets half wrong. The early return is also what keeps an append from
+      # *restarting* the clock and extending the oldest message's life.
+      # @return [void]
+      def sync_ticker
+        want = attached? && !@messages.empty?
+        return if want == !@ticker.nil?
+
+        if want
+          @ticker = screen.event_queue.tick(DISPLAY_SECONDS) { retire_oldest }
+        else
+          @ticker.cancel
+          @ticker = nil
+        end
+      end
+
+      # @param text [String, StyledString, nil]
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      # @return [StyledString]
+      def build_message(text, color)
+        message = StyledString.parse(text)
+        return message if color.nil? || message.empty?
+
+        message.with_fg(color.is_a?(Theme::Ref) ? color.resolve(screen.theme) : color)
+      end
+
+      # Columns the message would like, ignoring wrapping — the *widest* of its
+      # hard lines, not the sum of its spans (which would add every line
+      # together for a message carrying `\n`).
+      # @param message [StyledString]
+      # @return [Integer]
+      def natural_width(message) = message.lines.map(&:display_width).max || 0
+
+      # Grow-only: the high-water mark is kept in *desired* columns and the cap
+      # is applied here, last. Storing the clamped value instead would let a
+      # SIGWINCH that narrows the terminal ratchet the box permanently down to
+      # the narrow cap, with nothing to restore it when the terminal widens.
+      # @return [Integer]
+      def box_width = [@high_water + 2, cap_width].min
+
+      # @return [Integer]
+      def cap_width
+        [[(screen.size.width * WIDTH_FRACTION).to_i, MIN_CAP_WIDTH].max, screen.size.width].min
+      end
+
+      # @return [Integer] at least 3: two border rows plus one row of message.
+      def cap_height
+        [[(screen.size.height * HEIGHT_FRACTION).to_i, 3].max, screen.size.height].min
+      end
+
+      # Wraps one message to `width` columns, capped at {MAX_ROWS_PER_MESSAGE}
+      # rows.
+      #
+      # The overflow is ellipsized from the *joined remainder*, not by
+      # ellipsizing the last kept row: that row usually already fits `width`, so
+      # {StyledString#ellipsize} would be a no-op and the message would be
+      # truncated with no `…` to say so.
+      # @param message [StyledString]
+      # @param width [Integer]
+      # @return [Array<StyledString>]
+      def wrap_message(message, width)
+        rows = message.wrap(width)
+        return rows if rows.size <= MAX_ROWS_PER_MESSAGE
+
+        kept = rows.take(MAX_ROWS_PER_MESSAGE - 1)
+        rest = rows[(MAX_ROWS_PER_MESSAGE - 1)..].inject { |joined, row| joined + SPACE + row }
+        kept + [rest.ellipsize(width)]
+      end
+
+      # Joins pre-wrapped rows into one {StyledString} with `\n` separators, so
+      # {TextView} takes them as hard lines and its own wrap is a no-op over
+      # them (each row already fits the width it will be painted at).
+      # @param rows [Array<StyledString>]
+      # @return [StyledString]
+      def join_rows(rows)
+        return StyledString::EMPTY if rows.empty?
+
+        rows.inject { |joined, row| joined + ROW_BREAK + row }
+      end
+    end
+  end
+end

data/lib/tuile/component/picker_window.rb

@@ -37,9 +37,10 @@ module Tuile
         @options = options.map { Option.new(_1[0], _1[1]) }
         @block = block
         list = Component::List.new
-        list.lines = @options.map { "#{_1.key} #{screen.theme.hint(_1.caption)}" }
+        list.renderer = ->(option) { "#{option.key} #{screen.theme.hint(option.caption)}" }
+        list.items = @options
         list.cursor = Component::List::Cursor.new
-        list.on_item_chosen = ->(index, _line) { select_option(@options[index].key) }
+        list.on_item_chosen = ->(_index, option) { select_option(option.key) }
         self.content = list
         # Optional hook for a containing Popup to dismiss itself after a pick.
         @on_pick = nil
@@ -83,7 +84,6 @@ module Tuile
         popup = Popup.new(content: picker)
         picker.on_pick = -> { popup.close }
         popup.open
-        popup
       end
 
       protected

data/lib/tuile/component/popup.rb

@@ -98,19 +98,17 @@ module Tuile
 
       # Mounts this popup on the {Screen}, re-resolving its {#size} against the
       # current screen first.
-      # @return [void]
+      #
+      #   popup = Component::Popup.new(content: window).open   # construct and mount
+      #
+      # There is deliberately no class-level `Popup.open` factory — see
+      # `DECISIONS.md` `D-popup-open`; returning `self` is what keeps the
+      # one-liner above available without one.
+      # @return [self]
       def open
         reposition
         screen.add_popup(self)
-      end
-
-      # Constructs and opens a popup in one call.
-      # @param content [Component, nil]
-      # @param modal [Boolean] see {#initialize}.
-      # @param size [Size, Fraction] see {#initialize}.
-      # @return [Popup] the opened popup.
-      def self.open(content: nil, modal: true, size: Fraction::HALF)
-        Popup.new(content: content, modal: modal, size: size).tap(&:open)
+        self
       end
 
       # Removes this popup from the {Screen}. No-op if not currently open.

data/lib/tuile/component/progress_bar.rb

@@ -207,7 +207,7 @@ module Tuile
       def repaint
         return if rect.empty?
 
-        draw_line(rect.left, rect.top, StyledString.styled(glyphs(rect.width), fg: resolved_bar_color))
+        draw_text(rect.left, rect.top, StyledString.styled(glyphs(rect.width), fg: resolved_bar_color))
         clear_background(Rect.new(rect.left, rect.top + 1, rect.width, rect.height - 1)) if rect.height > 1
       end
 

data/lib/tuile/component/radio_group.rb

@@ -21,12 +21,13 @@ module Tuile
     # initial state, and assigning it is the only way back, since Space on the
     # already-selected row is a no-op rather than a deselect.
     #
-    # Composes rather than subclasses, like {ComboBox}: a {List} is its single
-    # {HasContent} child, which is where the cursor, scrolling, the scrollbar
-    # and per-row mouse hit-testing come from. `content` is that list, so an app
-    # can tune it (`scrollbar_visibility`, `show_cursor_when_inactive`, …). Rows
-    # beyond {#rect}'s height scroll; the inner list is the tab stop, not the
-    # group.
+    # Composes rather than subclasses, like {ComboBox}: a {List} of the items
+    # is its single {HasContent} child, which is where the cursor, scrolling,
+    # the scrollbar and per-row mouse hit-testing come from — the group only
+    # supplies the {List#renderer} that puts the marker in front of the label.
+    # `content` is that list, so an app can tune it (`scrollbar_visibility`,
+    # `show_cursor_when_inactive`, …). Rows beyond {#rect}'s height scroll; the
+    # inner list is the tab stop, not the group.
     #
     # == The cursor is chrome
     # The cursor and the selection are two independent things, as in
@@ -50,7 +51,7 @@ module Tuile
     # == Implementation details
     # Two `==`-equal items share one selection, so selecting either marks both
     # rows; two *distinct* items that merely render the same label stay
-    # independent, because a row resolves to an item by index.
+    # independent, because a row resolves to its own item, never to its label.
     #
     # Rows are `(*) `/`( ) ` literals, mirroring {Checkbox}'s convention rather
     # than importing constants from it. ASCII deliberately: `(•)` would measure
@@ -69,7 +70,6 @@ module Tuile
       #   doesn't matter to a form helper.
       def initialize(items: [], value: nil)
         super()
-        @items = items.to_a
         @item_label = :to_s.to_proc
         @value = value
         @on_value_change = nil
@@ -77,13 +77,14 @@ module Tuile
         list = List.new
         # A List has no cursor at all by default (Cursor::None, position -1).
         list.cursor = List::Cursor.new
-        list.on_item_chosen = ->(index, _line) { select_at(index) }
+        list.renderer = method(:render_row)
+        list.on_item_chosen = ->(_index, item) { self.value = item }
+        list.items = items.to_a
         self.content = list
-        rebuild_rows
       end
 
       # @return [Array] the presented items.
-      attr_reader :items
+      def items = content.items
 
       # @return [Proc, Method] item -> row label (a `String`, {StyledString}, or
       #   anything with `#to_s`); `:to_s` by default.
@@ -97,18 +98,17 @@ module Tuile
       def items=(new_items)
         raise TypeError, "expected Array, got #{new_items.inspect}" unless new_items.is_a?(Array)
 
-        @items = new_items
-        # Before the rebuild, so the single {List#on_cursor_changed} that
-        # {List#lines=} fires reports the final row rather than a stale one.
-        clamp_cursor
-        rebuild_rows
+        # Before the items land, so the single {List#on_cursor_changed} that
+        # {List#items=} fires reports the final row rather than a stale one.
+        clamp_cursor(new_items.size)
+        content.items = new_items
       end
 
       # @param proc [Proc, Method] item -> row label.
       # @return [void]
       def item_label=(proc)
         @item_label = proc
-        rebuild_rows
+        content.refresh_rows
       end
 
       # Selects `new_value`, firing {HasValue#on_value_change} when it really
@@ -122,7 +122,7 @@ module Tuile
         return if value == new_value
 
         super
-        rebuild_rows
+        content.refresh_rows
       end
 
       # Selects the cursor row on Space. Nothing else is claimed: the composed
@@ -147,33 +147,35 @@ module Tuile
 
       private
 
-      # Selects the item on row `index`; an index outside {#items} is ignored.
+      # Selects the item on row `index`; an index outside {#items} is ignored —
+      # {List::Cursor::None}'s `-1` would otherwise select the *last* item.
       # @param index [Integer]
       # @return [void]
       def select_at(index)
-        return unless index.between?(0, @items.size - 1)
+        return unless index.between?(0, items.size - 1)
 
-        self.value = @items[index]
+        self.value = items[index]
       end
 
-      # Re-renders every row from the current items, labels and selection.
-      # @return [void]
-      def rebuild_rows
-        content.lines = @items.map do |item|
-          StyledString.plain(item == value ? "(*) " : "( ) ") + label_for(item)
-        end
+      # @param item [Object]
+      # @return [StyledString] the item's row: its label behind a selection
+      #   marker. The {List} calls this at paint time, so the marker tracks
+      #   {#value} without re-rendering anything but the visible rows.
+      def render_row(item)
+        StyledString.plain(item == value ? "(*) " : "( ) ") + label_for(item)
       end
 
       # Pulls an over-range cursor back onto the last row (row 0 when there are
-      # none). {List#lines=} leaves a stale cursor alone, which would strand it
+      # none). {List#items=} leaves a stale cursor alone, which would strand it
       # off-content: no highlight, a dead Enter, and a Space that resolves to
       # `nil` and silently clears the selection.
+      # @param item_count [Integer] size of the incoming item list.
       # @return [void]
-      def clamp_cursor
+      def clamp_cursor(item_count)
         cursor = content.cursor
         # go_to_last funnels through Cursor#go's clamp(0, nil), so an empty
         # items list floors at 0 instead of going negative.
-        cursor.go_to_last(@items.size) if cursor.position >= @items.size
+        cursor.go_to_last(item_count) if cursor.position >= item_count
       end
 
       # @param item [Object]

data/lib/tuile/component/select.rb

@@ -72,7 +72,8 @@ module Tuile
         @value = value
         @on_value_change = nil
         @overlay = ListDropdown.new
-        @overlay.on_item_chosen = ->(index, _line) { commit(index) }
+        @overlay.renderer = method(:label_for)
+        @overlay.on_item_chosen = ->(_index, item) { commit(item) }
       end
 
       # @return [Array] the options.
@@ -171,7 +172,7 @@ module Tuile
 
         tail = Rect.new(rect.left, rect.top + 1, rect.width, rect.height - 1)
         clear_background(tail) unless tail.empty?
-        draw_line(rect.left, rect.top, face_row)
+        draw_text(rect.left, rect.top, face_row)
       end
 
       private
@@ -196,7 +197,7 @@ module Tuile
           return
         end
 
-        @overlay.lines = @items.map { |item| label_for(item) }
+        @overlay.items = @items
         @overlay.cursor = List::Cursor.new(position: @items.index(value) || 0)
         @overlay.open unless @overlay.open?
         anchor
@@ -208,11 +209,10 @@ module Tuile
       # @return [void]
       def close_menu = (@overlay.close if @overlay.open?)
 
-      # Adopts the item on row `index` as {#value} and closes the dropdown.
-      # @param index [Integer]
+      # Adopts the chosen item as {#value} and closes the dropdown.
+      # @param item [Object]
       # @return [void]
-      def commit(index)
-        item = @items[index]
+      def commit(item)
         close_menu
         self.value = item
       end