tuile 0.16.0 → 0.17.0

data/lib/tuile/component/layout.rb

@@ -3,13 +3,35 @@
 module Tuile
   class Component
     # A layout doesn't paint anything by itself: its job is to position child
-    # components. Two families, both top-down (see book ch3):
+    # components. Three ways to use one, all top-down (see book ch3):
     #
-    # - {Absolute} — you override {Component#rect=} and compute every child's
-    #   rectangle yourself. Total control, and the base for anything unusual.
+    # - Subclass {Layout} and compute every child's rectangle yourself in a
+    #   {Component#relayout} override. Total control, and the base for anything
+    #   unusual:
+    #
+    #     class SplitPane < Component::Layout
+    #       def initialize
+    #         super
+    #         add(@sidebar = Component::List.new)
+    #         add(@main = Component::Window.new("Main"))
+    #       end
+    #
+    #       protected
+    #
+    #       def relayout
+    #         left = width * 4 / 10
+    #         @sidebar.rect = Rect.new(0, 0, left, height)
+    #         @main.rect = Rect.new(left, 0, width - left, height)
+    #       end
+    #     end
+    #
+    #   The framework runs it after a resize, an `add` or `remove`, and a
+    #   child's {Component#visible=}.
+    # - {Absolute} — you give each child a fixed {Rect} and the layout assigns
+    #   exactly that.
     # - {Box} / {Vertical} / {Horizontal} — you declare each child's extent as
-    #   a {Fixed}, {Percent} or {Expand} constraint and the layout does the
-    #   arithmetic. Sugar over the same `rect=` assignment, for the common case.
+    #   a {Fixed}, {Percent} or {Expand} constraint — a {Percent} optionally
+    #   bounded with {Percent#clamp} — and the layout does the arithmetic.
     #
     # Children that fully tile the layout's rect repaint themselves and
     # cover everything; children that leave gaps (e.g. a form with widgets
@@ -17,6 +39,18 @@ module Tuile
     # the background is cleared and children are re-invalidated so they
     # paint over a clean surface.
     class Layout < Component
+      # What {Fixed}, {Percent}, {Expand} and {Clamp} have in common: each is a
+      # value a {Box} resolves against the space it has. The set is closed —
+      # {Box#add} accepts these four and nothing else, so an app never
+      # implements the protocol.
+      module Constraint
+        # @api private
+        # @param available [Integer] the extent a {Box} divides.
+        # @return [Integer, nil] cells wanted, before the box clamps to what is
+        #   left; `nil` for an {Expand}, which takes a share of the residue instead.
+        def resolve(available) = raise(NotImplementedError, "#{self.class} must implement resolve")
+      end
+
       # How much space a child gets along one axis of a {Box}: exactly {#cells},
       # clamped to whatever is still unassigned.
       #
@@ -35,6 +69,8 @@ module Tuile
       # @!attribute [r] cells
       #   @return [Integer] cell count along the axis.
       class Fixed < Data.define(:cells)
+        include Constraint
+
         # @param cells [Integer] cell count along the axis; `>= 0`.
         # @raise [ArgumentError] unless `cells` is a non-negative Integer.
         def initialize(cells:)
@@ -44,6 +80,11 @@ module Tuile
 
           super
         end
+
+        # @api private
+        # @param _available [Integer]
+        # @return [Integer] {#cells}.
+        def resolve(_available) = cells
       end
 
       # A percentage of the space *available* along a {Box}'s axis — measured
@@ -56,6 +97,8 @@ module Tuile
       # @!attribute [r] percent
       #   @return [Numeric] percentage of the available extent, `0..100`.
       class Percent < Data.define(:percent)
+        include Constraint
+
         # @param percent [Numeric] percentage of the available extent, `0..100`.
         # @raise [ArgumentError] unless `percent` is a Numeric in `0..100`.
         def initialize(percent:)
@@ -65,6 +108,25 @@ module Tuile
 
           super
         end
+
+        # Bounds the cells this share resolves to:
+        #
+        #   add(sidebar, Percent[33].clamp(..16))    # a third, never over 16
+        #   add(list, Percent[33].clamp(20..40))     # a third, within 20..40
+        #
+        # The floor is best-effort: a {Box} still clamps the result to what is
+        # unassigned, so an over-subscribed box starves a clamped child like any
+        # other.
+        # @param range [Range] inclusive, non-negative Integer endpoints, either
+        #   one `nil` for unbounded.
+        # @raise [ArgumentError] on an unusable `range`.
+        # @return [Clamp]
+        def clamp(range) = Clamp[self, range]
+
+        # @api private
+        # @param available [Integer]
+        # @return [Integer] {#percent} of `available`, rounded.
+        def resolve(available) = (available * percent / 100.0).round
       end
 
       # A share of whatever a {Box} has left once its {Fixed} and {Percent}
@@ -81,6 +143,8 @@ module Tuile
       # @!attribute [r] weight
       #   @return [Integer] relative share of the leftover space.
       class Expand < Data.define(:weight)
+        include Constraint
+
         # @param weight [Integer] relative share; `>= 1`.
         # @raise [ArgumentError] unless `weight` is a positive Integer.
         def initialize(weight:)
@@ -90,6 +154,61 @@ module Tuile
 
           super
         end
+
+        # @api private
+        # @param _available [Integer]
+        # @return [nil] an Expand has no size of its own — see {Constraint#resolve}.
+        def resolve(_available) = nil
+      end
+
+      # A {Percent} whose cells are bounded by {#range} — what {Percent#clamp}
+      # builds, and the way to say "half the width, but never more than 60
+      # columns":
+      #
+      #   add(system, Percent[50].clamp(..60))
+      #
+      # Only a {Percent}: a {Fixed} is already exact, one range already carries
+      # both bounds, and an {Expand}'s share depends on its siblings, so capping
+      # it would have to hand cells back to them.
+      #
+      # @!attribute [r] percent
+      #   @return [Percent] the share being bounded.
+      # @!attribute [r] range
+      #   @return [Range] the inclusive bounds, in cells.
+      class Clamp < Data.define(:percent, :range)
+        include Constraint
+
+        # @param percent [Percent]
+        # @param range [Range] see {Percent#clamp}.
+        # @raise [ArgumentError] unless `percent` is a {Percent}; see {Percent#clamp}.
+        def initialize(percent:, range:)
+          raise ArgumentError, "Clamp expects a Percent, got #{percent.inspect}" unless percent.is_a?(Percent)
+
+          validate_range(range)
+          super
+        end
+
+        # @api private
+        # @param available [Integer]
+        # @return [Integer] {#percent}'s cells, clamped to {#range}.
+        def resolve(available) = percent.resolve(available).clamp(range)
+
+        private
+
+        # @param range [Object]
+        # @raise [ArgumentError] unless an inclusive Range of non-negative
+        #   Integers (or `nil`s), ascending, bounded on at least one end.
+        # @return [void]
+        def validate_range(range)
+          valid = range.is_a?(Range) && !range.exclude_end? &&
+                  [range.begin, range.end].all? { _1.nil? || (_1.is_a?(Integer) && !_1.negative?) } &&
+                  !(range.begin.nil? && range.end.nil?) &&
+                  (range.begin.nil? || range.end.nil? || range.begin <= range.end)
+          return if valid
+
+          raise ArgumentError, "clamp expects an inclusive Range of non-negative Integers bounded on " \
+                               "at least one end, like ..60 or 20..40, got #{range.inspect}"
+        end
       end
 
       # Per-edge padding for a {Box}, in cells:
@@ -218,11 +337,6 @@ module Tuile
           screen.focused = first_focusable unless first_focusable.nil?
         end
       end
-
-      # Absolute layout. Extend this class, register any children, and
-      # override {Component#rect=} to reposition the children.
-      class Absolute < Layout
-      end
     end
   end
 end