tuile 0.16.0 → 0.17.0

data/lib/tuile/component/menu_bar.rb

@@ -22,7 +22,16 @@ module Tuile
     # the highlight, Enter or Space activates a row or opens its submenu, RIGHT
     # opens a submenu, LEFT returns to the previous menu, ESC closes one level.
     # LEFT at the first level and RIGHT on a row with no submenu step to the
-    # sibling menu, as they do in every menu bar. Book ch7 has the table.
+    # sibling menu, as they do in every menu bar. A menu stepped to that way is
+    # only *shown*: it opens with no row highlighted, so RIGHT steps on again,
+    # and Down, Enter or Space moves onto its first row, Up onto its last. Book
+    # ch7 has the table.
+    #
+    # The walk is governed by *menu mode*, not by whether a panel is up: a
+    # top-level item with no menu shows nothing when you step onto it, and the
+    # step after it still opens the next menu. ESC leaves the mode there — the
+    # one place the strip claims ESC, an unclaimed one being what stops the loop
+    # (`D_quit_key`). Enter on such an item fires it and enters no mode.
     #
     # == Mnemonics
     # An item given a `mnemonic:` answers to that letter, underlined in its
@@ -93,6 +102,14 @@ module Tuile
       #
       # Apps don't construct items; {MenuBar#add_item} and {#add_item} do.
       class Item
+        extend Listeners::Declare
+
+        # What {#on_click} fires.
+        #
+        # @!attribute [r] source
+        #   @return [Item] the item that was activated.
+        ClickEvent = Data.define(:source) { include Tuile::Event }
+
         # @param caption [StyledString] already coerced by the caller.
         # @param mnemonic [String, nil] already validated by the caller, in the
         #   case it was given in.
@@ -101,7 +118,7 @@ module Tuile
           @caption = caption
           @mnemonic = mnemonic&.downcase
           @cued_caption = build_cued_caption(caption, mnemonic)
-          @on_click = on_click
+          self.on_click << on_click if on_click
           @items = []
         end
 
@@ -126,10 +143,12 @@ module Tuile
         #   convention, like {Component#children} — grow it through {#add_item}.
         attr_reader :items
 
-        # @return [Proc, Method, nil] no-arg callable fired when the item is
-        #   activated (Enter, Space or a left click), exactly as
-        #   {Button#on_click}. Never fired on an item with children.
-        attr_accessor :on_click
+        # @!method on_click
+        #   Fired with a {ClickEvent} when the item is activated (Enter, Space or
+        #   a left click), exactly as {Button#on_click}. Never fired on an item
+        #   with children.
+        #   @return [Listeners]
+        listener :on_click
 
         # @return [Boolean] whether this item opens a submenu, i.e. has children.
         def submenu? = !@items.empty?
@@ -140,7 +159,7 @@ module Tuile
         # @param mnemonic [String, nil] the letter that activates this child
         #   while *this* item's children are the live level; see
         #   {MenuBar#add_item}.
-        # @yield optional `on_click` callback; same as assigning {#on_click=}.
+        # @yield optional `on_click` listener; same as registering one on {#on_click}.
         # @raise [ArgumentError] see {MenuBar#add_item}.
         # @return [Item]
         def add_item(caption = nil, mnemonic: nil, &on_click)
@@ -251,14 +270,14 @@ module Tuile
         Size.new([painted_width - @left_column, rect.width].min, 1)
       end
 
-      # @param new_rect [Rect]
+      # Closes the cascade — only on a *changed* rect, which is all this hook
+      # hears: a layout re-assigning the same rect (which {Layout::Box} does on
+      # any child mutation) must not.
+      # @param old_rect [Rect]
       # @return [void]
-      def rect=(new_rect)
-        # Only a *changed* rect closes the menu: a layout re-assigning the same
-        # rect (which {Layout::Box} does on any child mutation) must not.
-        changed = rect != new_rect
+      def handle_rect_changed(old_rect)
         super
-        @cascade.close if changed
+        @cascade.close
       end
 
       # Closes the cascade when the strip leaves the focus chain, so tabbing (or
@@ -281,11 +300,11 @@ module Tuile
       end
 
       # Offers the key to the open cascade first, then to the strip's own
-      # LEFT/RIGHT/Enter/Space/Down.
+      # LEFT/RIGHT/Enter/Space/Down/ESC.
       #
       # With a cascade open, the only keys reaching the strip are the two the
-      # cascade declines — LEFT at the first level, RIGHT on a row with no
-      # submenu — and both step to the sibling menu.
+      # cascade declines — LEFT at the first level, RIGHT with no submenu under
+      # the highlight — and both step to the sibling menu.
       # @param key [String]
       # @return [Boolean]
       def handle_key?(key)
@@ -294,19 +313,12 @@ module Tuile
         return true if handle_mnemonic?(key)
         return true if @cascade.handle_key?(key)
 
-        if @cascade.open?
-          case key
-          when Keys::LEFT_ARROW then step_menu(-1)
-          when Keys::RIGHT_ARROW then step_menu(1)
-          else false
-          end
-        else
-          case key
-          when Keys::LEFT_ARROW then move_highlight(-1)
-          when Keys::RIGHT_ARROW then move_highlight(1)
-          when Keys::ENTER, " ", Keys::DOWN_ARROW then open_highlighted
-          else false
-          end
+        case key
+        when Keys::LEFT_ARROW then @cascade.browsing? ? step_menu(-1) : move_highlight(-1)
+        when Keys::RIGHT_ARROW then @cascade.browsing? ? step_menu(1) : move_highlight(1)
+        when Keys::ENTER, " ", Keys::DOWN_ARROW then open_highlighted
+        when Keys::ESC then leave_menus
+        else false
         end
       end
 
@@ -330,14 +342,15 @@ module Tuile
         true
       end
 
+      # @param canvas [Canvas] see {Component#repaint}.
       # @return [void]
-      def repaint
+      def repaint(canvas)
         super
         return if rect.empty?
 
         row = strip_row.slice(@left_column, rect.width)
-        draw_text(rect.left, rect.top, row)
-        draw_cues(row)
+        canvas.set_text(0, 0, row)
+        draw_cues(canvas, row)
       end
 
       private
@@ -368,11 +381,10 @@ module Tuile
         invalidate
       end
 
-      # The rect's *width* is the only part of it the offset depends on, so this
-      # hook is the whole geometry story; {Component#rect=} invalidates for us,
-      # and {#rect=} closes the cascade rather than re-anchoring it.
+      # The offset follows the width; {Component#rect=} invalidates for us,
+      # and {#handle_rect_changed} closes the cascade rather than re-anchoring it.
       # @return [void]
-      def handle_width_changed
+      def relayout
         super
         adjust_left_column
       end
@@ -427,23 +439,25 @@ module Tuile
       # make the window width a function of the offset computed from it. Painted
       # focused or not: overflow is a fact about the captions and the rect, not
       # about focus.
+      # @param canvas [Canvas] the surface to paint onto.
       # @param row [StyledString] the windowed row, as painted.
       # @return [void]
-      def draw_cues(row)
-        draw_cue(row, 0, "<") if @left_column.positive?
-        draw_cue(row, rect.width - 1, ">") if @left_column + rect.width < painted_width
+      def draw_cues(canvas, row)
+        draw_cue(canvas, row, 0, "<") if @left_column.positive?
+        draw_cue(canvas, row, rect.width - 1, ">") if @left_column + rect.width < painted_width
       end
 
       # The cue keeps the style of the cell it covers, so one landing on the
       # highlighted segment doesn't punch a default-background hole in its
       # highlight.
+      # @param canvas [Canvas] the surface to paint onto.
       # @param row [StyledString] the windowed row.
       # @param column [Integer] relative to {#rect}`.left`.
       # @param glyph [String]
       # @return [void]
-      def draw_cue(row, column, glyph)
+      def draw_cue(canvas, row, column, glyph)
         style = row.slice(column, 1).spans.first&.style || StyledString::Style::DEFAULT
-        draw_char(rect.left + column, rect.top, glyph, style)
+        canvas.set_char(column, 0, glyph, style)
       end
 
       # One `[item, start_column, width]` triple per top-level item, in strip
@@ -470,17 +484,19 @@ module Tuile
       # @return [Integer, nil] the index of the item painted at `point`; `nil`
       #   for the blank tail or a row the strip doesn't paint.
       def index_at(point)
-        return nil unless extent_rect.contains?(point)
+        return nil unless local_extent_rect.contains?(point)
 
-        column = point.x - rect.left + @left_column
+        column = point.x + @left_column
         segments.index { |_item, start, width| column >= start && column < start + width }
       end
 
+      # The cascade hangs off {ScreenPane}, so it shares no offset with this
+      # strip and has to be given screen coordinates (`D_relative_rect`).
       # @param index [Integer]
       # @return [Rect] the segment's cells on screen — the cascade's anchor.
       def segment_rect(index)
         _item, start, width = segments[index]
-        Rect.new(rect.left + start - @left_column, rect.top, width, 1)
+        Rect.new(0, 0, width, 1).at(to_screen(Point.new(start - @left_column, 0)))
       end
 
       # @return [StyledString] the whole strip as one row, unclipped. {#repaint}
@@ -536,21 +552,33 @@ module Tuile
         true
       end
 
-      # Steps to the neighbouring menu, showing *its* menu instead — or closing
-      # the cascade, when the neighbour is a top-level button with no menu to
-      # show. The cascade is left alone when the highlight is already at an end:
-      # reopening the same menu would throw away the submenu the user is standing
-      # in.
+      # Steps to the neighbour and shows *its* menu; a top-level button shows
+      # nothing and keeps menu mode. The cascade is left alone when the
+      # highlight is already at an end: reopening the same menu would throw away
+      # the submenu the user is standing in.
       #
       # It deliberately never *activates*. An item arrowed past is highlighted,
       # not pressed, so a top-level button waits for Enter or Space — otherwise
       # walking the strip would fire every button on it.
       # @param delta [Integer] `+1` / `-1`.
-      # @return [Boolean] always `true`: an open menu swallows the key either way.
+      # @return [Boolean] always `true`: menu mode swallows the key either way.
       def step_menu(delta)
         was = @highlighted_index
         move_highlight(delta)
-        show_highlighted_menu unless @highlighted_index == was
+        return true if @highlighted_index == was
+
+        @cascade.step_to(segment_rect(@highlighted_index), items[@highlighted_index])
+        true
+      end
+
+      # Leaves menu mode — the ESC that gets you out where stepping has landed
+      # on a top-level item with no menu, so there is no panel left to close.
+      # Declined otherwise, so ESC keeps its app-level meaning (`D_quit_key`).
+      # @return [Boolean]
+      def leave_menus
+        return false unless @cascade.browsing?
+
+        @cascade.close
         true
       end
 
@@ -562,20 +590,12 @@ module Tuile
         return false if items.empty?
 
         item = items[@highlighted_index]
-        show_highlighted_menu
-        # Fired after the close above, exactly as {Cascade} activates a leaf: an
-        # action that opens a dialog must not paint it under a menu.
-        item.on_click&.call unless item.submenu?
-        true
-      end
-
-      # Shows the highlighted item's menu, closing the cascade when it has none.
-      # @return [void]
-      def show_highlighted_menu
-        item = items[@highlighted_index]
-        return @cascade.close unless item.submenu?
-
         @cascade.open_below(segment_rect(@highlighted_index), item)
+        # Fired after the close inside `open_below`, exactly as {Cascade}
+        # activates a leaf: an action that opens a dialog must not paint it
+        # under a menu.
+        item.on_click.fire(Item::ClickEvent.new(source: item)) unless item.submenu?
+        true
       end
     end
   end

data/lib/tuile/component/notification.rb

@@ -42,8 +42,7 @@ module Tuile
     # - **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#handle_theme_changed} rebuild.
-    # - **Take a size.** An {Overlay} has no declared box; the messages decide
-    #   this one's, in {#reposition}.
+    # - **Take a size.** The messages decide the box, in {#declared_size_in}.
     class Notification < Overlay
       # Most messages held at once, counting both the painted ones and any
       # waiting for room. Chosen from reading time rather than geometry: the
@@ -117,8 +116,6 @@ module Tuile
       private_class_method :new
 
       def initialize
-        # Built before `super`, because Overlay#initialize assigns the content
-        # and our #reposition override reads every one of these.
         @messages = []
         @high_water = 0
         @ticker = nil
@@ -152,31 +149,22 @@ module Tuile
 
         @messages << message
         @high_water = [@high_water, natural_width(message)].max
-        reposition
+        restack
         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
-      # {Overlay#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
+      # @return [Overlay::TopRight] a notification opens in the corner.
+      def default_placement = TopRight[]
+
+      # The box its messages need: as wide as the widest message held so far
+      # and as tall as they wrap to at that width, each capped by the screen.
+      # @param screen_size [Size]
+      # @return [Size]
+      def declared_size_in(screen_size)
+        return Size.new(0, 0) if @messages.empty?
 
-        width = box_width
-        rows = @messages.flat_map { |message| wrap_message(message, width - 2) }
-        height = [rows.size + 2, cap_height].min
-        @view.text = join_rows(rows)
-        self.rect = Rect.new([screen.size.width - width, 0].max, 0, width, height)
+        width = box_width(screen_size)
+        Size.new(width, [wrapped_rows(width).size + 2, cap_height(screen_size)].min)
       end
 
       # A left press dismisses the whole box, every message with it. Every other
@@ -218,14 +206,36 @@ module Tuile
         sync_ticker
       end
 
+      protected
+
+      # Wraps the messages to the width the pane gave the box — the wrap the
+      # height in {#declared_size_in} was measured with.
+      # @return [void]
+      def relayout
+        super
+        @view.text = join_rows(wrapped_rows(rect.width)) if rect.width > 2
+      end
+
       private
 
+      # A message came or went: the text is re-wrapped here, and the box is
+      # re-measured by the pane.
+      # @return [void]
+      def restack
+        invalidate_layout
+        reposition
+      end
+
+      # @param width [Integer] the box width, border included.
+      # @return [Array<StyledString>] every message, wrapped inside the border.
+      def wrapped_rows(width) = @messages.flat_map { |message| wrap_message(message, width - 2) }
+
       # 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
+        @messages.empty? ? close : restack
         sync_ticker
       end
 
@@ -269,17 +279,20 @@ module Tuile
       # 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.
+      # @param screen_size [Size]
       # @return [Integer]
-      def box_width = [@high_water + 2, cap_width].min
+      def box_width(screen_size) = [@high_water + 2, cap_width(screen_size)].min
 
+      # @param screen_size [Size]
       # @return [Integer]
-      def cap_width
-        [[(screen.size.width * WIDTH_FRACTION).to_i, MIN_CAP_WIDTH].max, screen.size.width].min
+      def cap_width(screen_size)
+        [[(screen_size.width * WIDTH_FRACTION).to_i, MIN_CAP_WIDTH].max, screen_size.width].min
       end
 
+      # @param screen_size [Size]
       # @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
+      def cap_height(screen_size)
+        [[(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}