tuile 0.16.0 → 0.17.0

data/lib/tuile/component/list_dropdown.rb

@@ -9,12 +9,11 @@ module Tuile
     # highlight, and reads the pick.
     #
     #   drop = Component::ListDropdown.new
-    #   drop.renderer = method(:label_for)                 # caller renders
-    #   drop.on_item_chosen = ->(_index, item) { commit(item) }   # caller commits
+    #   drop.renderer = ->(item, _w) { label_for(item) }   # caller renders
+    #   drop.list.on_item_chosen { |e| commit(e.item) }    # caller commits
     #   # …then, from the driver's key handler:
     #   drop.items = matches                         # caller filters
-    #   drop.anchor_to(rect, rows: matches.size)     # below the driver, or flipped
-    #   drop.open
+    #   drop.anchor_to(self)                         # opens it below the driver, or flipped
     #   return true if drop.move(key)  # Up/Down/PgUp/PgDn/^U/^D → list scroll
     #   drop.choose if key == Keys::ENTER            # commit the highlight
     #
@@ -64,42 +63,120 @@ module Tuile
       # @return [Integer]
       MAX_VISIBLE_ROWS = 10
 
+      # The placement {#anchor_to} and {#anchor_beside} open the dropdown with:
+      # hung off `anchor`, `side` `:below` or `:beside` it, as tall as its rows
+      # up to `max_rows`. The pane re-reads the anchor on every pass and again
+      # once the content has settled, so the panel follows a field that moves.
+      #
+      # @!attribute [r] anchor
+      #   @return [Component, Rect] {Overlay::Placement#anchor}: a component,
+      #     followed for as long as it is on screen, or a fixed rect in screen
+      #     coordinates.
+      # @!attribute [r] side
+      #   @return [Symbol] `:below` or `:beside`.
+      # @!attribute [r] width
+      #   @return [Integer, #call, nil] columns, or something answering them when
+      #     called; `nil` takes the anchor's width.
+      # @!attribute [r] max_rows
+      #   @return [Integer] rows shown before the list scrolls.
+      Anchored = Data.define(:anchor, :side, :width, :max_rows) do
+        include Overlay::Placement
+
+        # @param drop [ListDropdown]
+        # @param screen_size [Size]
+        # @param anchor_rect [Rect] {#anchor} in screen coordinates, resolved by the pane.
+        # @return [Rect]
+        def rect_for(drop, screen_size, anchor_rect)
+          columns = width.nil? ? anchor_rect.width : width
+          columns = [columns.respond_to?(:call) ? columns.call : columns, screen_size.width].min
+          if side == :below
+            below(anchor_rect, drop.items.size, columns, screen_size)
+          else
+            beside(anchor_rect, drop.items.size, columns, screen_size)
+          end
+        end
+
+        private
+
+        # Beneath the anchor, flipped above when the rows won't fit below,
+        # clamped — with the list scrolling — when neither side has room; the
+        # left edges line up, sliding left only far enough to stay on screen.
+        # @param anchor [Rect]
+        # @param rows [Integer]
+        # @param width [Integer]
+        # @param screen_size [Size]
+        # @return [Rect]
+        def below(anchor, rows, width, screen_size)
+          desired = [rows, max_rows].min
+          beneath = anchor.top + anchor.height
+          room_below = screen_size.height - beneath
+          if desired <= room_below
+            top = beneath
+            height = desired
+          elsif anchor.top >= room_below
+            height = [desired, anchor.top].min
+            top = anchor.top - height
+          else
+            height = room_below
+            top = beneath
+          end
+          Rect.new([anchor.left, screen_size.width - width].min.clamp(0, nil), top, width, height)
+        end
+
+        # Against the anchor's right edge, flipped to its left when the right
+        # has no room; the first row lines up with the anchor, sliding up only
+        # far enough to stay on screen.
+        # @param anchor [Rect]
+        # @param rows [Integer]
+        # @param width [Integer]
+        # @param screen_size [Size]
+        # @return [Rect]
+        def beside(anchor, rows, width, screen_size)
+          height = [rows, max_rows, screen_size.height].min
+          right = anchor.left + anchor.width
+          left = if right + width <= screen_size.width || (anchor.left - width).negative?
+                   right
+                 else
+                   anchor.left - width
+                 end
+          left = left.clamp(0, [screen_size.width - width, 0].max)
+          top = [anchor.top, screen_size.height - height].min.clamp(0, nil)
+          Rect.new(left, top, width, height)
+        end
+      end
+
       def initialize
         @list = Menu.new
         @list.cursor = List::Cursor.new
         @list.show_cursor_when_inactive = true # highlight the selection though focus stays on the driver
+        @list.scrollbar_visibility = :auto # the list fills the panel, so the bar is on exactly when the rows outrun it
         super(content: @list)
         self.bg_color = Theme.ref(:input_bg_color)
       end
 
       # @param items [Array] the items to show, one row each; see {List#items=}.
+      #   An open dropdown resizes to the new count on the next settle.
       # @return [void]
       def items=(items)
         @list.items = items
+        reposition
       end
 
       # @return [Array] the items currently shown.
       def items = @list.items
 
-      # @param proc [Proc, Method] item -> row; see {List#renderer}.
+      # @param proc [Proc, Method] `(item, text_width) -> 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]
-      def on_item_chosen=(proc)
-        @list.on_item_chosen = proc
-      end
-
-      # @param proc [Proc, Method, nil] highlight-moved callback; see
-      #   {List#on_cursor_changed}. A cascading driver needs it to drop the
-      #   panels that belonged to the row the highlight just left.
-      # @return [void]
-      def on_cursor_changed=(proc)
-        @list.on_cursor_changed = proc
-      end
+      # The wrapped list, exposed so a driver can register on {List#on_item_chosen}
+      # (its commit) and {List#on_cursor_changed} (a cascading driver drops the
+      # panels belonging to the row the highlight just left). A driver tunes it
+      # but never supplies it (`D_has_content`).
+      # @return [List]
+      attr_reader :list
 
       # @param cursor [List::Cursor] the highlight; see {List#cursor=}.
       # @return [void]
@@ -117,13 +194,14 @@ module Tuile
       # @return [Boolean] whether the highlight moved there.
       def select(index) = @list.select(index)
 
-      # Sizes and places the dropdown against `anchor`: directly beneath it,
-      # flipped above when `rows` won't fit below, clamped — with the list
-      # scrolling — when neither side has room. Horizontally the left edges line
-      # up, sliding left only far enough to keep the panel on screen.
+      # Opens the dropdown against `anchor` — directly beneath it, flipped above
+      # when its rows won't fit below, clamped (with the list scrolling) when
+      # neither side has room — or moves it there if it is open already.
+      # Horizontally the left edges line up, sliding left only far enough to
+      # keep the panel on screen.
       #
-      #   drop.anchor_to(field.rect, rows: matches.size)            # field width
-      #   drop.anchor_to(rect, rows: items.size, width: measured)   # own width
+      #   drop.anchor_to(self)                            # follows the field, its width
+      #   drop.anchor_to(self, width: method(:menu_width))
       #
       # Vertical flips but horizontal slides because covering the driver would
       # hide what is being chosen, while sharing its columns is the point.
@@ -131,49 +209,34 @@ module Tuile
       # **`anchor` is the region actually occupied, and may be taller than one
       # row** — "beneath" means the row *after* it, so a multi-row driver (a
       # {Component::TextArea} carrying an autocomplete menu) is cleared entirely
-      # rather than overdrawn from its second row down. A widget that paints one
-      # row but may be *assigned* more height passes its face, not its rect:
-      # {ComboBox} and {Select} both do, since a {Window} content slot hands them
-      # the full inner height.
+      # rather than overdrawn from its second row down. A component anchor is
+      # read through its {Component#absolute_extent_rect}, so a widget that
+      # paints one row but is *assigned* more height ({ComboBox}, {Select})
+      # hangs the panel off its face.
+      #
+      # The height is the item count, capped at `max_rows`, and follows
+      # {#items=}. Settles before it returns, so a driver can forward a key to
+      # the list, or read {#cursor_row_rect}, in the same handler.
       #
-      # @param anchor [Rect] the region the driver occupies, of any height; the
-      #   dropdown never covers it.
-      # @param rows [Integer] how many rows there are to show — the content
-      #   count, not the height: more than fits turns the scrollbar on. `0`
-      #   collapses the dropdown to an empty rect (drivers close instead).
-      # @param width [Integer] the panel's width in columns, clamped to the
-      #   screen. Defaults to the anchor's, which lines both edges up with a
-      #   field; a driver that measured its labels passes its own. A label wider
-      #   than the screen clips — {List} has no horizontal scrolling.
+      # @param anchor [Component, Rect] the driver, followed wherever it moves,
+      #   or a fixed region in screen coordinates. Of any height; the dropdown
+      #   never covers it.
+      # @param width [Integer, #call, nil] the panel's width in columns, clamped
+      #   to the screen, or something answering it; `nil` (the default) takes
+      #   the anchor's, which lines both edges up with a field. A driver that
+      #   measures its labels passes its own. A label wider than the screen
+      #   clips — {List} has no horizontal scrolling.
       # @param max_rows [Integer] rows shown before the list scrolls.
       # @return [void]
-      def anchor_to(anchor, rows:, width: anchor.width, max_rows: MAX_VISIBLE_ROWS)
-        desired = [rows, max_rows].min
-        beneath = anchor.top + anchor.height
-        below = screen.size.height - beneath
-        above = anchor.top
-        if desired <= below
-          top = beneath
-          height = desired
-        elsif above >= below
-          height = [desired, above].min
-          top = anchor.top - height
-        else
-          height = below
-          top = beneath
-        end
-        width = [width, screen.size.width].min
-        self.rect = Rect.new([anchor.left, screen.size.width - width].min.clamp(0, nil), top, width, height)
-        # After the geometry: the setter rebuilds the list's padded rows against
-        # the width it can see, and the gutter takes a column off it.
-        @list.scrollbar_visibility = rows > height ? :visible : :gone
+      def anchor_to(anchor, width: nil, max_rows: MAX_VISIBLE_ROWS)
+        anchor_with(Anchored.new(anchor:, side: :below, width:, max_rows:))
       end
 
-      # Sizes and places the dropdown *beside* `anchor` — the placement a
-      # cascading submenu wants, where {#anchor_to} is the placement a field's
-      # dropdown wants.
+      # Opens the dropdown *beside* `anchor` — the placement a cascading submenu
+      # wants, where {#anchor_to} is the placement a field's dropdown wants —
+      # or moves it there if it is open already.
       #
-      #   sub.anchor_beside(parent.cursor_row_rect, rows: kids.size, width: measured)
+      #   sub.anchor_beside(parent.cursor_row_rect, width: measured)
       #
       # Horizontally it sits against `anchor`'s right edge, **flipping** to its
       # left when the right has no room (and clamping to the screen when neither
@@ -186,38 +249,22 @@ module Tuile
       # submenu must not cover its parent panel, so it flips *horizontally* and
       # shares its rows.
       #
-      # @param anchor [Rect] the row the submenu belongs to — typically the
-      #   parent dropdown's {#cursor_row_rect}. Its width is the parent panel's,
-      #   which is what the submenu clears.
-      # @param rows [Integer] how many rows there are to show — the content
-      #   count, not the height; more than fits turns the scrollbar on. `0`
-      #   collapses the dropdown to an empty rect (drivers close instead).
-      # @param width [Integer] the panel's width in columns, clamped to the
-      #   screen. **Required, with no default:** `anchor.width` is the *parent's*
-      #   width and would be meaningless here, so the caller measures (see
+      # @param anchor [Rect, Component] the row the submenu belongs to, in screen
+      #   coordinates — typically the parent dropdown's {#cursor_row_rect}.
+      # @param width [Integer, #call] the panel's width in columns, clamped to
+      #   the screen. **Required, with no default:** the anchor's width is the
+      #   *parent's* and would be meaningless here, so the caller measures (see
       #   `design/decisions.md` `D_select` on why the width policy stays with the
       #   driver).
       # @param max_rows [Integer] rows shown before the list scrolls.
       # @return [void]
-      def anchor_beside(anchor, rows:, width:, max_rows: MAX_VISIBLE_ROWS)
-        height = [rows, max_rows, screen.size.height].min
-        width = [width, screen.size.width].min
-        right = anchor.left + anchor.width
-        left = if right + width <= screen.size.width || (anchor.left - width).negative?
-                 right
-               else
-                 anchor.left - width
-               end
-        left = left.clamp(0, [screen.size.width - width, 0].max)
-        top = [anchor.top, screen.size.height - height].min.clamp(0, nil)
-        self.rect = Rect.new(left, top, width, height)
-        # After the geometry, as in {#anchor_to}: the setter rebuilds the list's
-        # padded rows against the width it can see.
-        @list.scrollbar_visibility = rows > height ? :visible : :gone
+      def anchor_beside(anchor, width:, max_rows: MAX_VISIBLE_ROWS)
+        anchor_with(Anchored.new(anchor:, side: :beside, width:, max_rows:))
       end
 
-      # The highlighted row's rect on screen — what a cascading submenu anchors
-      # against, via {#anchor_beside}.
+      # The highlighted row's rect **on screen** — what a cascading submenu
+      # anchors against, via {#anchor_beside}. Screen coordinates because the
+      # submenu is a sibling overlay rather than a child (`D_relative_rect`).
       #
       # It lives here rather than in the driver because {ListDropdown} owns the
       # list's geometry: a driver computing `top + position - scroll_top_row`
@@ -232,7 +279,7 @@ module Tuile
         row = @list.cursor.position - @list.scroll_top_row
         return nil unless row.between?(0, @list.rect.height - 1)
 
-        Rect.new(@list.rect.left, @list.rect.top + row, @list.rect.width, 1)
+        Rect.new(0, 0, @list.rect.width, 1).at(@list.to_screen(Point.new(0, row)))
       end
 
       # Forwards a cursor-movement key to the list. The driver calls this from
@@ -254,6 +301,19 @@ module Tuile
       # @return [Boolean] true iff a row was chosen (false when the cursor is
       #   off-content).
       def choose = @list.handle_key?(Keys::ENTER)
+
+      private
+
+      # Opens or moves the panel and settles the pass, because both anchor
+      # methods promise a panel that *is* placed: a driver reads
+      # {#cursor_row_rect} or forwards a key to the list in the same handler,
+      # and both measure rects this just assigned.
+      # @param placement [Anchored]
+      # @return [void]
+      def anchor_with(placement)
+        open? ? self.placement = placement : self.open(placement)
+        flush_layout
+      end
     end
   end
 end

data/lib/tuile/component/menu_bar/cascade.rb

@@ -8,9 +8,14 @@ module Tuile
       # machinery of {MenuBar}; an app never names it.
       #
       #   cascade.open_below(segment_rect, item)   # Enter/Down on the strip
+      #   cascade.step_to(segment_rect, item)      # LEFT/RIGHT along the strip
       #   return true if cascade.handle_key?(key)   # MenuBar#handle_key?, first
       #   cascade.close                            # focus lost, or rect changed
       #
+      # It also holds the bar's *menu mode* ({#browsing?}), which outlives the
+      # panels: stepping onto a top-level item with no menu shows nothing and
+      # stays in the mode, so the next step opens its neighbour's menu again.
+      #
       # A panel is a **non-modal overlay, not a child**, so it never takes focus:
       # focus stays on the {MenuBar} for the whole interaction and every key
       # arrives via {MenuBar#handle_key?}, which offers it here first. That is
@@ -24,9 +29,10 @@ module Tuile
       # == Implementation details
       # While open it consumes **everything** except the two keys that mean
       # "leave this menu sideways", which only the strip can answer: LEFT at
-      # depth 1, and RIGHT on a row with no submenu. An open menu is quasi-modal
-      # — firing an app's `s`-to-save behind a visible panel is worse than a dead
-      # keystroke.
+      # depth 1, and RIGHT with no submenu under the highlight — a panel opened
+      # with `highlight: false` has none at all, so it declines RIGHT throughout.
+      # An open menu is quasi-modal — firing an app's `s`-to-save behind a
+      # visible panel is worse than a dead keystroke.
       #
       # UI-thread-confined, like everything in the tree (see {Screen}).
       class Cascade
@@ -44,29 +50,50 @@ module Tuile
 
         def initialize
           @levels = []
+          @browsing = false
         end
 
         # @return [Boolean] whether any panel is open.
         def open? = !@levels.empty?
 
+        # @return [Boolean] whether the bar is in *menu mode* — which is not
+        #   {#open?}: stepping onto a top-level item with no menu keeps the mode
+        #   with no panel to show for it. Cleared with the last panel, however
+        #   it went.
+        def browsing? = @browsing
+
         # @return [Integer] how many panels are open; `0` when closed.
         def depth = @levels.size
 
-        # Opens `item`'s children directly beneath `anchor`, closing anything
-        # already open first.
+        # Opens `item`'s children directly beneath `anchor`, first row
+        # highlighted, closing anything already open first.
         # @param anchor [Rect] the strip segment the menu drops from.
-        # @param item [Item] a childless one opens nothing.
+        # @param item [Item] a childless one opens nothing and leaves menu mode
+        #   off: Enter on a top-level button is not menu navigation.
         # @return [void]
-        def open_below(anchor, item)
-          close
-          return unless item.submenu?
+        def open_below(anchor, item) = show(anchor, item, highlight: true)
 
-          push(item) { |drop, rows, width| drop.anchor_to(anchor, rows: rows, width: width) }
+        # Shows `item`'s children beneath `anchor` with no row highlighted — the
+        # sideways step along the strip. Menu mode survives a childless `item`,
+        # which is the whole difference from {#open_below}: walking past a
+        # top-level button must not end the walk.
+        # @param anchor [Rect] the strip segment the menu drops from.
+        # @param item [Item]
+        # @return [void]
+        def step_to(anchor, item)
+          show(anchor, item, highlight: false)
+          @browsing = true
         end
 
-        # Closes every open panel, deepest first.
+        # Closes every open panel, deepest first, and leaves menu mode.
+        #
+        # The flag earns its own line: menu mode outlives the panels, so at the
+        # panel-less stop `truncate` has nothing to close and nothing to notify.
         # @return [void]
-        def close = truncate(0)
+        def close
+          truncate(0)
+          @browsing = false
+        end
 
         # Offers a key to the deepest panel and to the cascade's own verbs.
         # @param key [String]
@@ -75,6 +102,7 @@ module Tuile
         #   (see the class docs).
         def handle_key?(key)
           return false unless open?
+          return true if enter_panel?(key)
           return true if deepest.move(key)
 
           case key
@@ -120,6 +148,41 @@ module Tuile
 
         private
 
+        # The body both entry verbs share: drop what is open, then mount a panel
+        # for `item`'s children if it has any.
+        # @param anchor [Rect]
+        # @param item [Item]
+        # @param highlight [Boolean] whether the panel's first row starts highlighted.
+        # @return [void]
+        def show(anchor, item, highlight:)
+          close
+          return unless item.submenu?
+
+          @browsing = true
+          push(item, highlight: highlight) { |drop, width| drop.anchor_to(anchor, width: width) }
+        end
+
+        # Moves into a panel opened with no highlighted row — Down, Enter and
+        # Space onto its first row, Up onto its last. Every other key leaves the
+        # empty highlight alone, RIGHT above all: it falls through to be
+        # declined, which is what lets a sideways step keep stepping.
+        #
+        # Up is answered here rather than by {ListDropdown#move}, which would
+        # clamp backwards onto the *first* row ({List::Cursor#go} floors at `0`).
+        # @param key [String]
+        # @return [Boolean] whether it moved in.
+        def enter_panel?(key)
+          level = depth - 1
+          return false unless highlighted(level).nil?
+
+          item, drop = @levels[level]
+          case key
+          when *Keys::DOWN_ARROWS, Keys::ENTER, " " then drop.select(0)
+          when *Keys::UP_ARROWS then drop.select(item.items.size - 1)
+          else false
+          end
+        end
+
         # @return [ListDropdown] the deepest open panel.
         def deepest = @levels.last[1]
 
@@ -144,7 +207,7 @@ module Tuile
             # doesn't paint it under a menu. A listener-less leaf still closes:
             # activation stays uniform.
             close
-            item.on_click&.call
+            item.on_click.fire(Item::ClickEvent.new(source: item))
           end
         end
 
@@ -156,27 +219,29 @@ module Tuile
           anchor = @levels[level][1].cursor_row_rect
           return if anchor.nil?
 
-          push(item) { |drop, rows, width| drop.anchor_beside(anchor, rows: rows, width: width) }
+          push(item) { |drop, width| drop.anchor_beside(anchor, width: width) }
         end
 
-        # Mounts a panel for `item`'s children and yields it for geometry.
+        # Builds a panel for `item`'s children and yields it to be anchored,
+        # which is what opens it.
         # @param item [Item]
+        # @param highlight [Boolean] `false` parks the cursor off content, so
+        #   nothing is highlighted.
         # @yieldparam drop [ListDropdown]
-        # @yieldparam rows [Integer]
         # @yieldparam width [Integer]
         # @return [void]
-        def push(item)
+        def push(item, highlight: true)
           children = item.items
           drop = ListDropdown.new
           drop.renderer = renderer_for(children)
           drop.items = children
-          drop.cursor = List::Cursor.new
+          drop.cursor = List::Cursor.new(position: highlight ? 0 : -1)
           level = @levels.size
           # Wired *after* the items and cursor: {List#items=} and {List#cursor=}
           # both fire on_cursor_changed, so wiring first would have the fresh
           # panel truncate itself away as it was built.
-          drop.on_item_chosen = ->(_index, child) { activate(level, child) }
-          drop.on_cursor_changed = ->(_index, _child) { truncate(level + 1) }
+          drop.list.on_item_chosen { |e| activate(level, e.item) }
+          drop.list.on_cursor_changed { truncate(level + 1) }
           # The cascade's own record of what is open is reconciled from the
           # popup's own closure, not maintained alongside it: an outside click
           # closes panels behind our back ({Overlay#close_on_outside_click?}), and
@@ -184,15 +249,19 @@ module Tuile
           # `deepest` and `highlighted` all lying. Identity-keyed and idempotent,
           # because the notice also arrives from `truncate` (which has already
           # popped the entry) and from teardown, in no guaranteed order.
-          drop.on_close = -> { @levels.delete_if { |(_i, d)| d.equal?(drop) } }
+          # Menu mode ends with the last panel, whoever took it: this notice is
+          # what covers a dismissal {#close} never hears about.
+          drop.on_close do
+            @levels.delete_if { |(_i, d)| d.equal?(drop) }
+            @browsing = false if @levels.empty?
+          end
           # Chain each panel to the one it dropped out of, so a click on a
           # deeper panel is "inside" the shallower ones and doesn't dismiss
           # them. Level 0 owns nothing on purpose: a click on a dialog hosting
           # the bar *should* close the whole menu and keep the dialog.
           drop.owner = @levels.last&.last
           @levels << [item, drop]
-          drop.open
-          yield(drop, children.size, width_for(children))
+          yield(drop, width_for(children))
         end
 
         # Closes the deepest panel; at depth 1 that closes the cascade.
@@ -221,13 +290,14 @@ module Tuile
         # @param items [Array<Item>]
         # @return [Proc] item -> row: the label padded to the level's widest, plus
         #   an arrow column when any sibling has a submenu — so every arrow lands
-        #   in the same column without asking the {List} how wide it ended up.
+        #   in the same column. The width {List} offers a renderer is no use
+        #   here: {#width_for} derives the panel's width from these same labels,
+        #   so laying out against it would be circular.
         def renderer_for(items)
           label_width = label_width_of(items)
           arrows = items.any?(&:submenu?)
-          lambda do |item|
-            row = item.cued_caption.ellipsize(label_width)
-            row += StyledString.plain(" " * (label_width - row.display_width))
+          lambda do |item, _text_width|
+            row = item.cued_caption.ellipsize(label_width).ljust(label_width)
             next row unless arrows
 
             row + StyledString.plain(item.submenu? ? " #{SUBMENU_ARROW}" : " " * ARROW_WIDTH)