tuile 0.12.0 → 0.13.0

data/lib/tuile/component/popup.rb

@@ -40,6 +40,10 @@ module Tuile
     # declined it (see {ScreenPane#handle_key}). That's why typing `q` into a
     # nested {Component::TextField} doesn't dismiss the popup: the field
     # consumes it first.
+    #
+    # A left click *outside* the popup closes it too, modal or not — see
+    # {#close_on_outside_click?} for the exact contract and {#on_close=} for
+    # the notice a driver hears when it happens.
     class Popup < Component
       include Component::HasContent
 
@@ -52,10 +56,16 @@ module Tuile
       # @param size [Size, Fraction] the popup's size, applied top-down. A
       #   {Fraction} is resolved against the screen each layout pass; a {Size}
       #   is clamped to the screen. Defaults to {Fraction::HALF}.
-      def initialize(content: nil, modal: true, size: Fraction::HALF)
+      # @param close_on_outside_click [Boolean] true (default) to dismiss on a
+      #   left click that misses this popup. See {#close_on_outside_click?}.
+      def initialize(content: nil, modal: true, size: Fraction::HALF,
+                     close_on_outside_click: true)
         super()
         @modal = modal
         @size = size
+        @close_on_outside_click = close_on_outside_click
+        @owner = nil
+        @on_close = nil
         @content = nil
         self.content = content unless content.nil?
         reposition
@@ -67,6 +77,63 @@ module Tuile
       # @return [Boolean] whether this popup is modal. See {#initialize}.
       def modal? = @modal
 
+      # Whether a left click outside this popup closes it (default true, modal or
+      # not). The pane does the closing — {ScreenPane#handle_mouse} snapshots
+      # the open popups *before* routing the click and closes the dismissable
+      # ones *after*, so a widget that toggles its own overlay from a click on
+      # its face (a {Component::Select}, a {Component::MenuBar} title) still
+      # toggles correctly: the delivered click closes the overlay and the
+      # dismissal then no-ops on it, rather than closing and reopening it. Only
+      # `:left` dismisses; scroll and right clicks never do.
+      #
+      # **"Outside" spans the {#owner} chain, not just this rect.** A click
+      # counts as inside this popup when it lands in its rect *or* in any popup
+      # that belongs to it — so a dialog is not dismissed by a click on a
+      # dropdown its own field opened, and a menu cascade is not dismissed by a
+      # click on one of its deeper panels. Popups with no owner relationship are
+      # independent: clicking one dismisses the other, which is what a
+      # window-like overlay should do. A popup that must survive unrelated
+      # clicks entirely ({Component::Notification}) sets this false.
+      #
+      # Every dismissable popup closes, not just the topmost, and stacking order
+      # plays no part: a {Component::MenuBar} cascade must vanish whole on one
+      # click on the background, not peel one panel per click.
+      # @return [Boolean]
+      def close_on_outside_click? = @close_on_outside_click
+
+      # @return [Boolean] see {#close_on_outside_click?}.
+      attr_writer :close_on_outside_click
+
+      # The component this overlay is *part of*, or `nil` (the default) when it
+      # is an overlay in its own right. It exists for outside-click dismissal:
+      # a click inside this popup also counts as inside whatever popup encloses
+      # its owner, so the host is not dismissed by a click on a panel it put
+      # there. See {#close_on_outside_click?}.
+      #
+      # Set it to the *driver* — {Component::ComboBox} hands its dropdown
+      # `self` — rather than to the enclosing popup: the driver knows what it
+      # is, while the popup above it is a tree relationship the pane resolves
+      # at click time (so it cannot go stale). Any {Component} is accepted, and
+      # a `Popup` resolves to itself, which is how a
+      # {Component::MenuBar::Cascade} chains each panel to the one it dropped
+      # out of.
+      # @return [Component, nil]
+      attr_accessor :owner
+
+      # A callback taking no arguments, fired once this popup has left the
+      # screen — **however it left**: {#close}, a direct {Screen#remove_popup},
+      # an outside click, or teardown via {Screen#close}. That unconditionality
+      # is the point, so it hangs off {#on_detached} rather than {#close}; a
+      # driver keeping its own record of open popups reconciles it here and
+      # cannot drift ({Component::MenuBar::Cascade} is the worked example).
+      #
+      # It fires *after* the popup is detached, so {#open?} is already false and
+      # the usual {Component#on_detached} caveats apply: release state, don't
+      # inspect the tree, keep it trivial (it may run while the pane is mid-way
+      # through closing a batch of popups, and a raise propagates).
+      # @return [Proc, nil]
+      attr_accessor :on_close
+
       def focusable? = true
 
       # Sets the popup's size and repositions it. Accepts a {Fraction}
@@ -147,14 +214,6 @@ module Tuile
         self.rect = rect.centered(screen.size)
       end
 
-      # Hint for the status bar: own "q Close" plus the wrapped content's hint.
-      # @return [String]
-      def keyboard_hint
-        prefix = "q #{screen.theme.hint("Close")}"
-        child_hint = @content&.keyboard_hint.to_s
-        child_hint.empty? ? prefix : "#{prefix}  #{child_hint}"
-      end
-
       # `q` and ESC close the popup. The popup sits on the focus chain of
       # whatever it wraps, so the key reaches here by bubbling up from the
       # focused content after that content declined to handle it.
@@ -169,6 +228,13 @@ module Tuile
         end
       end
 
+      # Fires {#on_close}. A subclass overriding this **must** call `super`, or
+      # the popup's driver never hears that it closed.
+      # @return [void]
+      def on_detached
+        @on_close&.call
+      end
+
       protected
 
       # Content fills the popup's full rect — Popup has no border to subtract.

data/lib/tuile/component/select.rb

@@ -72,6 +72,9 @@ module Tuile
         @value = value
         @on_value_change = nil
         @overlay = ListDropdown.new
+        # Outside-click dismissal spans the owner chain, so a click on this
+        # select's dropdown must not dismiss a dialog the select sits in.
+        @overlay.owner = self
         @overlay.renderer = method(:label_for)
         @overlay.on_item_chosen = ->(_index, item) { commit(item) }
       end
@@ -108,7 +111,6 @@ module Tuile
       end
 
       # @return [String]
-      def keyboard_hint = "⏎ #{screen.theme.hint("open")}  ↑↓ #{screen.theme.hint("select")}"
 
       # Re-anchors the (open) dropdown after a move or resize.
       # @param new_rect [Rect]

data/lib/tuile/component/tab_sheet.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A {Component::Tabs} strip on its top row plus the pane belonging to the
+    # selected tab underneath it:
+    #
+    #   ␣Details␣│␣Payment␣│␣Shipping␣
+    #   the selected tab's pane fills the rest of the rect
+    #
+    #   sheet = Component::TabSheet.new
+    #   sheet.add_tab("Details", details_form)     # selected, and shown
+    #   sheet.add_tab("Payment", payment_form)
+    #   sheet.select_next                          # shows payment_form
+    #   sheet.on_tab_selected = ->(index, tab) { log("now on #{tab&.caption}") }
+    #
+    # Tab lands on the strip first and enters the pane on the next press, which
+    # is the browser's order; switching tabs does *not* move focus into the new
+    # pane, but if focus was inside the pane that just went away it lands back
+    # on the strip.
+    #
+    # == Hidden panes are detached
+    # Only the selected tab's pane is in the component tree — the others are
+    # detached, which is how Tuile hides a component (there is no visibility
+    # flag, and an empty rect gates painting only). Consequences worth
+    # designing around:
+    #
+    # - A hidden pane is invisible to *everything*: the Tab cycle, focus
+    #   cascades, repaint, the cursor, `on_tree` walks. No gates anywhere.
+    # - Its state survives, because state is ivars — scroll position, caret,
+    #   list cursor, text are all exactly as the user left them, and mutating a
+    #   hidden pane is safe (`invalidate` while detached is a silent no-op).
+    # - {Component#on_detached} / {Component#on_attached} fire on every switch,
+    #   so a pane holding a mounted-lifetime resource — a {Component::ProgressBar}'s
+    #   ticker — releases it while hidden and re-acquires it on return. A pane
+    #   that must keep something alive while hidden can't; that something
+    #   belongs in the model the pane renders, not in the pane.
+    #
+    # == Implementation details
+    # `children` is `[strip, pane]`, the strip pinned at index 0, so pre-order
+    # traversal gives the strip-then-pane Tab order for free. The swap follows
+    # the slot-swap recipe {Component#detach_child} documents — detach, rewire,
+    # `on_child_removed` last, so the focus repair sees the new occupant.
+    #
+    # Panes live in an identity-keyed `Tab => Component` map here rather than in
+    # a slot on {Tabs::Tab}: the strip's tab array stays the sole ordering
+    # authority, and the strip itself stays ignorant of panes. One idempotent
+    # `sync_pane` is the sole writer of the visible pane, deriving it from
+    # `strip.selected` on every call, so registering a pane and selecting a tab
+    # can happen in either order.
+    #
+    # The sheet owns the strip's `on_tab_selected` (that is what drives the
+    # swap); an app's listener goes on {#on_tab_selected} here, which fires
+    # after the pane has been swapped in.
+    class TabSheet < Component
+      # An app's own selection listener, called after the pane has been swapped
+      # in — `(index, tab)`, or `(nil, nil)` once the last tab is gone. Same
+      # contract as {Tabs#on_tab_selected}: it reports that the selection
+      # changed, whatever changed it.
+      # @return [Proc, nil]
+      attr_accessor :on_tab_selected
+
+      # @param separator [String, StyledString] the strip's separator; see
+      #   {Tabs#separator=}.
+      def initialize(separator: Tabs::DEFAULT_SEPARATOR)
+        super()
+        @panes = {}.compare_by_identity
+        @strip = Tabs.new(separator:)
+        add_child(@strip)
+        @strip.on_tab_selected = lambda do |index, tab|
+          sync_pane
+          @on_tab_selected&.call(index, tab)
+        end
+      end
+
+      # @return [Tabs] the strip. Reach through it for the rest of its API —
+      #   `sheet.strip.separator = "|"` — but leave its `on_tab_selected` alone:
+      #   the sheet drives the pane swap through it, and {#on_tab_selected} is
+      #   where an app's listener goes.
+      attr_reader :strip
+
+      # @return [Component, nil] the pane currently in the tree — the selected
+      #   tab's, `nil` while the sheet has no tabs.
+      attr_reader :pane
+
+      # Adds a tab and the pane to show while it is selected. The first tab
+      # added becomes the selection, so its pane is shown immediately.
+      # @param caption [String, StyledString, nil] parsed as {Tabs::Tab#caption=}
+      #   parses it.
+      # @param pane [Component] shown while this tab is selected, detached while
+      #   it isn't.
+      # @raise [TypeError] when `pane` isn't a {Component}.
+      # @raise [ArgumentError] when `pane` is already this sheet's pane for
+      #   another tab — a component has one parent, so two tabs cannot share it.
+      # @return [Tabs::Tab] the new tab's handle.
+      def add_tab(caption, pane)
+        raise TypeError, "expected Component, got #{pane.inspect}" unless pane.is_a?(Component)
+
+        forget_removed_tabs
+        if @panes.each_value.any? { |existing| existing.equal?(pane) }
+          raise ArgumentError, "#{pane} is already a pane of this TabSheet"
+        end
+
+        tab = @strip.add_tab(caption)
+        @panes[tab] = pane
+        sync_pane
+        tab
+      end
+
+      # Removes a tab and forgets its pane, detaching it if it was the visible
+      # one. The strip re-selects as {Tabs#remove_tab} describes, and this
+      # sheet shows whatever it lands on.
+      # @param tab [Tabs::Tab] one of this sheet's tabs.
+      # @raise [ArgumentError] when the tab isn't on this sheet's strip.
+      # @return [Component, nil] the pane that tab owned.
+      def remove_tab(tab)
+        pane = @panes[tab] # read first: the strip's own removal may prune the entry
+        @strip.remove_tab(tab)
+        @panes.delete(tab)
+        pane
+      end
+
+      # @param tab [Tabs::Tab, nil]
+      # @return [Component, nil] the pane registered for `tab`; `nil` for a
+      #   removed tab, a tab of another sheet, or `nil`.
+      def pane_for(tab)
+        return nil unless tab&.attached?
+
+        @panes[tab]
+      end
+
+      # @return [Array<Tabs::Tab>] the strip's tabs, in order.
+      def tabs = @strip.tabs
+
+      # @return [Tabs::Tab, nil] the selected tab.
+      def selected = @strip.selected
+
+      # @param tab [Tabs::Tab] one of this sheet's tabs.
+      # @return [void]
+      def selected=(tab)
+        @strip.selected = tab
+      end
+
+      # @return [Integer, nil] the selected tab's position.
+      def selected_index = @strip.selected_index
+
+      # @param index [Integer] a position in `0...tabs.size`.
+      # @return [void]
+      def selected_index=(index)
+        @strip.selected_index = index
+      end
+
+      # Selects the next tab, clamping at the last one.
+      # @return [Boolean] `false` only when there are no tabs.
+      def select_next = @strip.select_next
+
+      # Selects the previous tab, clamping at the first one.
+      # @return [Boolean] `false` only when there are no tabs.
+      def select_previous = @strip.select_previous
+
+      # @param new_rect [Rect]
+      # @return [void]
+      def rect=(new_rect)
+        super
+        @strip.rect = Rect.new(rect.left, rect.top, rect.width, [rect.height, 1].min)
+        layout_pane
+      end
+
+      # Forwards to whichever child the click landed on — the strip's row, or
+      # the pane below it.
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        children.each do |child|
+          child.handle_mouse(event) if child.rect.contains?(event.point)
+        end
+      end
+
+      # Sends focus to the strip: a sheet is a container, and the strip is where
+      # a tab switch is driven from. The pane is a Tab press away.
+      # @return [void]
+      def on_focus
+        super
+        screen.focused = @strip
+      end
+
+      # Lands focus on the strip rather than on `self` when the focused pane is
+      # swapped out — a bare container can't use keys, and the user's last
+      # action was a tab switch.
+      # @param child [Component]
+      # @return [void]
+      def on_child_removed(child)
+        super
+        screen.focused = @strip if attached? && screen.focused.equal?(self)
+      end
+
+      private
+
+      # Makes the visible pane match `strip.selected`, swapping if it doesn't.
+      # Idempotent and the sole writer of `@pane`: it derives everything from
+      # current state, so {#add_tab} can register a pane after the strip has
+      # already selected its tab.
+      # @return [void]
+      def sync_pane
+        forget_removed_tabs
+        wanted = @panes[@strip.selected]
+        return if wanted.equal?(@pane)
+
+        old = @pane
+        detach_child(old) unless old.nil?
+        @pane = wanted
+        unless wanted.nil?
+          add_child(wanted) # appended: the strip stays at index 0
+          wanted.invalidate
+          layout_pane
+        end
+        invalidate
+        on_child_removed(old) unless old.nil?
+      end
+
+      # Drops entries whose tab is gone. {Tabs::Tab#remove} takes a tab off the
+      # strip without passing through {#remove_tab}, and a detached tab can never
+      # be selected again, so its entry is dead weight — it pins the pane against
+      # garbage collection and makes {#add_tab} reject that pane as still in use.
+      # Idempotent and the only cleaner, because the rule it enforces is an
+      # invariant ("every key is a live tab of my strip") rather than a step in
+      # one code path.
+      # @return [void]
+      def forget_removed_tabs
+        @panes.delete_if { |tab, _pane| !tab.attached? }
+      end
+
+      # @return [void]
+      def layout_pane
+        return if @pane.nil?
+
+        @pane.rect = Rect.new(rect.left, rect.top + 1, rect.width, [rect.height - 1, 0].max)
+      end
+    end
+  end
+end