tuile 0.11.0 → 0.13.0

data/lib/tuile/component/list_dropdown.rb

@@ -9,18 +9,20 @@ 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
     #   drop.choose if key == Keys::ENTER            # commit the highlight
     #
     # It owns only what every such dropdown shares — *placement* included, via
-    # {#anchor_to}. What stays with the driver: the width **policy** ({#anchor_to}
-    # measures nothing itself), filtering, row rendering, the commit action, and
-    # ESC/Enter handling. ESC and Enter carry driver-specific tails (ESC may
+    # {#anchor_to} (below a field) and {#anchor_beside} (beside a parent row, for
+    # a cascading submenu). What stays with the driver: the width **policy**
+    # (neither placement method measures anything itself), filtering, row
+    # rendering, the commit action, and ESC/Enter handling. ESC and Enter carry driver-specific tails (ESC may
     # revert a query; Enter may commit via {#choose} *or* via a separate submit
     # path), so {#move} claims neither — the driver calls {#choose} and {#close}
     # from its own branches.
@@ -66,14 +68,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]
@@ -81,6 +89,14 @@ module Tuile
         @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
+
       # @param cursor [List::Cursor] the highlight; see {List#cursor=}.
       # @return [void]
       def cursor=(cursor)
@@ -90,6 +106,13 @@ module Tuile
       # @return [List::Cursor] the list's cursor (the current highlight).
       def cursor = @list.cursor
 
+      # Moves the highlight to the item at `index`, scrolling it into view; see
+      # {List#select}. The positional counterpart of {#move}, for a driver that
+      # picked a row by something other than a key — a mnemonic letter, say.
+      # @param index [Integer]
+      # @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
@@ -133,6 +156,73 @@ module Tuile
         @list.scrollbar_visibility = rows > height ? :visible : :gone
       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.
+      #
+      #   sub.anchor_beside(parent.cursor_row_rect, rows: kids.size, 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
+      # side does). Vertically it **slides**: the panel's first row lines up with
+      # the anchored row, sliding up only far enough to keep the panel on screen.
+      #
+      # The two axes are the mirror image of {#anchor_to}'s, for the same reason:
+      # never cover the thing being chosen from. A field's dropdown must not
+      # cover the field, so it flips *vertically* and shares its columns; a
+      # 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
+      #   `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.size = Size.new(width, height)
+        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
+      end
+
+      # The highlighted row's rect on screen — what a cascading submenu anchors
+      # against, via {#anchor_beside}.
+      #
+      # It lives here rather than in the driver because {ListDropdown} owns the
+      # list's geometry: a driver computing `top + position - scroll_top_row`
+      # itself would have to reach through to the private list.
+      # @return [Rect, nil] one row spanning the panel's width, or `nil` when
+      #   the cursor is off-content ({List::Cursor::None}, an empty list) or its
+      #   row is scrolled out of the viewport.
+      def cursor_row_rect
+        return nil if @list.rect.empty?
+        return nil unless @list.cursor.position.between?(0, @list.items.size - 1)
+
+        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)
+      end
+
       # Forwards a cursor-movement key to the list. The driver calls this from
       # its own key handler; a truthy return means "consumed — stop here", falsy
       # means "not mine — proceed with normal editing/dispatch". Only {MOVE_KEYS}

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

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    class MenuBar
+      # The stack of open menu panels — one {ListDropdown} per level, the last
+      # deepest — and the drill/pop/activate logic driving them. Private
+      # machinery of {MenuBar}; an app never names it.
+      #
+      #   cascade.open_below(segment_rect, item)   # Enter/Down on the strip
+      #   return true if cascade.handle_key(key)   # MenuBar#handle_key, first
+      #   cascade.close                            # focus lost, or rect changed
+      #
+      # 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
+      # {Component::Select}'s architecture extended to N levels, and it is why
+      # nothing in the key-dispatch ladder changes.
+      #
+      # Widths are measured here, per level — the panel is as wide as the level's
+      # widest label — because {ListDropdown} deliberately measures nothing
+      # itself (`DECISIONS.md` `D-select`).
+      #
+      # == 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.
+      #
+      # UI-thread-confined, like everything in the tree (see {Screen}).
+      class Cascade
+        # The affordance painted on a row that opens a submenu. U+25B8 rather
+        # than the obvious `▶`: like {Component::Select}'s `▾` it is East-Asian
+        # **Neutral**, so it measures one column even under ambiguous-as-wide and
+        # stays outside `D-ambiguous-width`'s bet, where `▶` and `▼` are
+        # Ambiguous and would need an ASCII opt-in.
+        # @return [String]
+        SUBMENU_ARROW = "▸"
+
+        # Columns a submenu arrow occupies, the space before it included.
+        # @return [Integer]
+        ARROW_WIDTH = 2
+
+        def initialize
+          @levels = []
+        end
+
+        # @return [Boolean] whether any panel is open.
+        def open? = !@levels.empty?
+
+        # @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.
+        # @param anchor [Rect] the strip segment the menu drops from.
+        # @param item [Item] a childless one opens nothing.
+        # @return [void]
+        def open_below(anchor, item)
+          close
+          return unless item.submenu?
+
+          push(item) { |drop, rows, width| drop.anchor_to(anchor, rows: rows, width: width) }
+        end
+
+        # Closes every open panel, deepest first.
+        # @return [void]
+        def close = truncate(0)
+
+        # Offers a key to the deepest panel and to the cascade's own verbs.
+        # @param key [String]
+        # @return [Boolean] `true` when consumed — almost always, while open.
+        #   `false` when closed, and for the two sideways keys {MenuBar} answers
+        #   (see the class docs).
+        def handle_key(key)
+          return false unless open?
+          return true if deepest.move(key)
+
+          case key
+          when Keys::ENTER, " " then activate_highlighted
+          when Keys::RIGHT_ARROW
+            return false unless highlighted(depth - 1)&.submenu?
+
+            activate_highlighted
+          when Keys::LEFT_ARROW
+            return false if depth < 2
+
+            pop
+          when Keys::ESC then pop
+          else
+            # Only a printable: an open menu also swallows HOME, function keys
+            # and the five-byte junk Keys.getkey returns for an unrecognized
+            # escape sequence, and ringing at terminal noise is worse than
+            # silence. A printable is a deliberate, visible act.
+            Screen.instance.beep if Keys.printable?(key)
+          end
+          true
+        end
+
+        # Activates the deepest level's item bound to `key` — the drill-or-fire
+        # the mnemonic shares with Enter. The highlight moves there *first*, so a
+        # submenu anchors beside the row that opened it rather than beside
+        # wherever the cursor happened to be.
+        # @param key [String] a single printable, already downcased.
+        # @return [Boolean] whether an item on the deepest level claimed it. A
+        #   miss is never offered to a shallower level.
+        def handle_mnemonic(key)
+          return false unless open?
+
+          level = depth - 1
+          item, drop = @levels[level]
+          index = item.items.index { |child| child.mnemonic == key }
+          return false if index.nil?
+
+          drop.select(index)
+          activate(level, item.items[index])
+          true
+        end
+
+        private
+
+        # @return [ListDropdown] the deepest open panel.
+        def deepest = @levels.last[1]
+
+        # @return [void]
+        def activate_highlighted = activate(depth - 1, highlighted(depth - 1))
+
+        # Drills into `item`, or fires it and closes the cascade.
+        #
+        # @param level [Integer] the panel the item belongs to.
+        # @param item [Item, nil] `nil` (an off-content cursor) does nothing.
+        # @return [void]
+        def activate(level, item)
+          # Truncate first, for the mouse: a click on a shallower panel that is
+          # still visible routes to *that* panel, so anything deeper is stale.
+          truncate(level + 1)
+          return if item.nil?
+
+          if item.submenu?
+            push_beside(level, item)
+          else
+            # Closed before the listener runs, so an action that opens a dialog
+            # doesn't paint it under a menu. A listener-less leaf still closes:
+            # activation stays uniform.
+            close
+            item.on_click&.call
+          end
+        end
+
+        # Opens `item`'s children beside the row highlighted in `level`.
+        # @param level [Integer]
+        # @param item [Item]
+        # @return [void]
+        def push_beside(level, item)
+          anchor = @levels[level][1].cursor_row_rect
+          return if anchor.nil?
+
+          push(item) { |drop, rows, width| drop.anchor_beside(anchor, rows: rows, width: width) }
+        end
+
+        # Mounts a panel for `item`'s children and yields it for geometry.
+        # @param item [Item]
+        # @yieldparam drop [ListDropdown]
+        # @yieldparam rows [Integer]
+        # @yieldparam width [Integer]
+        # @return [void]
+        def push(item)
+          children = item.items
+          drop = ListDropdown.new
+          drop.renderer = renderer_for(children)
+          drop.items = children
+          drop.cursor = List::Cursor.new
+          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) }
+          # 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 ({Popup#close_on_outside_click?}), and
+          # a level left in `@levels` after its panel is gone would have `depth`,
+          # `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) } }
+          # 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))
+        end
+
+        # Closes the deepest panel; at depth 1 that closes the cascade.
+        # @return [void]
+        def pop = truncate(depth - 1)
+
+        # @param count [Integer] how many panels to keep.
+        # @return [void]
+        def truncate(count)
+          while depth > count
+            _item, drop = @levels.pop
+            drop.close
+          end
+        end
+
+        # @param level [Integer]
+        # @return [Item, nil] the item under `level`'s cursor; `nil` when it sits
+        #   off-content. The range guard matters: a cursor at `-1` would
+        #   otherwise index the *last* child.
+        def highlighted(level)
+          item, drop = @levels[level]
+          position = drop.cursor.position
+          position.between?(0, item.items.size - 1) ? item.items[position] : nil
+        end
+
+        # @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.
+        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))
+            next row unless arrows
+
+            row + StyledString.plain(item.submenu? ? " #{SUBMENU_ARROW}" : " " * ARROW_WIDTH)
+          end
+        end
+
+        # @param items [Array<Item>]
+        # @return [Integer] the panel width: the rendered row plus {List}'s two
+        #   row gutters, plus a scrollbar column when the rows can't all be shown.
+        #   As in {Component::Select}, the scrollbar is predicted from the item
+        #   count rather than the final height — a panel the screen clamps
+        #   shorter than {ListDropdown::MAX_VISIBLE_ROWS} scrolls without having
+        #   bought that column, and ellipsizes one character early.
+        def width_for(items)
+          row = label_width_of(items) + (items.any?(&:submenu?) ? ARROW_WIDTH : 0)
+          row + 2 + (items.size > ListDropdown::MAX_VISIBLE_ROWS ? 1 : 0)
+        end
+
+        # @param items [Array<Item>]
+        # @return [Integer]
+        def label_width_of(items) = items.map { _1.cued_caption.display_width }.max || 0
+      end
+    end
+  end
+end