tuile 0.14.0 → 0.16.0

data/lib/tuile/component/integer_field.rb

@@ -3,10 +3,11 @@
 module Tuile
   class Component
     # A single-line field whose {#value} is an `Integer` (or `nil` when empty).
-    # The user may type only `0`–`9` and a single leading `-`; anything else is
-    # silently rejected without moving the caret. Up/Down step the value by one
-    # (an empty field counting as `0`). An empty or otherwise un-parseable
-    # buffer reads back as `nil`:
+    # The buffer only ever holds `0`–`9` and a single leading `-`: a key that
+    # would break that is dropped without moving the caret, and so is a *paste*
+    # that would (`"12abc34"` lands nothing, rather than sieving through as
+    # `"1234"`). Up/Down step the value by one (an empty field counting as `0`).
+    # An empty or otherwise un-parseable buffer reads back as `nil`:
     #
     #   field = Component::IntegerField.new
     #   field.on_value_change = ->(n) { puts n.inspect }  # Integer or nil, per change
@@ -14,11 +15,10 @@ module Tuile
     #   field.value                                        # => 42
     #   field.clear                                        # empties it; value => nil
     #
-    # Like {ComboBox}, it *composes* a {TextField} (its single {HasContent}
-    # child) rather than subclassing one — its face carries only the typed
-    # {HasValue} value seam, never the widget's `String`-typed `text`. It's the
-    # same wrapper shape as {ComboBox} minus the dropdown: a digit-filtered text
-    # field re-exposed as a typed input. Give it a single-row {#rect}.
+    # It *wraps* a {TextField} rather than subclassing one, so its face carries
+    # only the typed {HasValue} value seam and never the widget's `String`-typed
+    # `text`; {AbstractWrappingField} supplies the wrapping. Give it a
+    # single-row {#rect}.
     #
     # == The value is a *derived parse* of the buffer
     # {#value} is `Integer(buffer, 10)` (or `nil`), recomputed on read — the
@@ -32,23 +32,49 @@ module Tuile
     # scope (range and formatting are a forms concern).
     #
     # UI-thread-confined, like every component (see {Screen}).
-    class IntegerField < Component
-      include HasContent
-      include HasValue
+    class IntegerField < AbstractWrappingField
+      include HasBadInput
+
+      # @return [String] what {#bad_input_message} reports for a buffer that is
+      #   typeable but not an integer.
+      BAD_INPUT_MESSAGE = "not a whole number"
+      private_constant :BAD_INPUT_MESSAGE
+
+      # The face: a {TextField} that admits only the buffers an integer can be
+      # typed through, however the characters arrive.
+      class Field < TextField
+        # Buffers reachable by typing an integer: an optional leading `-`, then
+        # digits. Looser than the parse on purpose — the half-typed `""` and
+        # `"-"` are members, or no value could be typed at all, and
+        # {IntegerField#value} reads both back as nil.
+        # @return [Regexp]
+        TYPEABLE = /\A-?\d*\z/
+        private_constant :TYPEABLE
+
+        protected
+
+        # Accepts the insertion only if the whole resulting buffer is still
+        # typeable, so `"12abc34"` is dropped rather than sieved into `"1234"`.
+        # @param str [String]
+        # @return [Boolean] true if the text changed.
+        def insert_text(str)
+          return false unless TYPEABLE.match?(@text.dup.insert(@caret, str))
+
+          super
+        end
+      end
 
       def initialize
-        super()
-        @last_value = nil
-        field = TextField.new
-        field.on_change = ->(_text) { fire_if_changed }
-        field.on_key = method(:field_key)
-        self.content = field
+        super(Field.new)
+        # Not the general on_key interceptor: that slot stays free for the app.
+        editor.on_key_up = -> { step(1) }
+        editor.on_key_down = -> { step(-1) }
       end
 
       # @return [Integer, nil] the parsed buffer; `nil` when empty or not a
       #   valid integer (e.g. a lone `"-"`).
       def value
-        Integer(content.text, 10)
+        Integer(editor.text, 10)
       rescue ArgumentError
         nil
       end
@@ -58,78 +84,25 @@ module Tuile
       # @param new_value [Integer, nil] `nil` empties the field.
       # @return [void]
       def value=(new_value)
-        content.text = new_value.nil? ? "" : new_value.to_s
-        content.caret = content.text.length
+        editor.text = new_value.nil? ? "" : new_value.to_s
+        editor.caret = editor.text.length
       end
 
       # `nil`, not `""`: an integer field with no parseable number is empty.
       # @return [nil]
       def empty_value = nil
 
-      # @return [Point, nil] the field's caret (the hardware cursor is delegated
-      #   to the inner field).
-      def cursor_position = content.cursor_position
-
-      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
-      # @return [Proc, Method, nil] no-arg callable, or nil.
-      def on_enter = content.on_enter
-
-      # @param callback [Proc, Method, nil]
-      # @return [void]
-      def on_enter=(callback)
-        content.on_enter = callback
-      end
-
-      protected
-
-      # Places the wrapped field across the whole rect ({HasContent} hook).
-      # @param field [Component]
-      # @return [void]
-      def layout(field) = (field.rect = rect)
+      # The lone `"-"` the filter has to admit is the field's whole bad-input
+      # residue; an *empty* buffer is empty, not bad ({HasBadInput}).
+      # @return [String, nil]
+      def bad_input_message = value.nil? && !editor.text.empty? ? BAD_INPUT_MESSAGE : nil
 
       private
 
-      # The field's key interceptor, consulted *before* the field acts on the
-      # key: Up/Down step the value; a printable key the field mustn't accept is
-      # swallowed (so a rejected key never moves the caret); everything else —
-      # digits, the leading sign, and all editing/navigation keys — falls
-      # through.
-      # @param key [String]
-      # @return [Boolean] true to consume the key.
-      def field_key(key)
-        case key
-        when Keys::UP_ARROW then step(1)
-        when Keys::DOWN_ARROW then step(-1)
-        else return Keys.printable?(key) && !accepts?(key)
-        end
-        true
-      end
-
       # Nudges {#value} by `delta`, treating an empty/un-parseable field as `0`.
       # @param delta [Integer]
       # @return [void]
       def step(delta) = (self.value = (value || 0) + delta)
-
-      # A digit anywhere, or a `-` only as the very first character.
-      # @param char [String] a single printable character.
-      # @return [Boolean]
-      def accepts?(char)
-        return true if char.match?(/\A[0-9]\z/)
-
-        char == "-" && content.caret.zero? && !content.text.start_with?("-")
-      end
-
-      # Re-emits {#on_value_change} with the freshly-parsed {#value}, but only
-      # when it differs from the last one fired — so a buffer edit that leaves
-      # the value unchanged (`"7"`→`"07"`) stays silent.
-      # @return [void]
-      def fire_if_changed
-        v = value
-        return if v == @last_value
-
-        @last_value = v
-        on_value_change&.call(v)
-      end
     end
   end
 end

data/lib/tuile/component/label.rb

@@ -15,7 +15,6 @@ module Tuile
       def initialize(text = nil)
         super()
         @text = StyledString::EMPTY
-        @bg = nil
         @rows = []
         @blank_row = ""
         self.text = text unless text.nil?
@@ -25,13 +24,6 @@ module Tuile
       #   {StyledString}.
       attr_reader :text
 
-      # @return [Color, nil] a local background laid over *every* span and the
-      #   row padding (via {StyledString#with_bg}), overriding the text's own
-      #   span bgs — stronger than the inherited {#bg_color}. `nil` (default)
-      #   keeps each span's bg and lets the inherited {#effective_bg_color}
-      #   fill the rest.
-      attr_reader :bg
-
       # Replaces the text. A `String` is parsed via {StyledString.parse}
       # (embedded ANSI is honored); a `StyledString` is used as-is; `nil` is
       # coerced to an empty {StyledString}. Lines wider than {#rect} are
@@ -47,30 +39,14 @@ module Tuile
         invalidate
       end
 
-      # Sets a local background painted over every span and the row padding
-      # (trailing pad and blank rows included), overriding the text's own span
-      # bgs. Coerced via {Color.coerce} (Symbol, Integer, Array, {Color}, or
-      # `nil`). `nil` clears the override — spans keep their own bg and the
-      # inherited {#bg_color} fills the rest.
-      #
-      # @param value [Color, Symbol, Integer, Array<Integer>, nil]
-      # @return [void]
-      def bg=(value)
-        new_bg = Color.coerce(value)
-        return if @bg == new_bg
-
-        @bg = new_bg
-        update_rows
-        invalidate
-      end
-
       # Paints the text into {#rect}.
       #
       # Skips the {Component#repaint} default's auto-clear: every row is
       # painted explicitly (with pre-padded blanks past the last line), so
       # the "fully draw over your rect" contract is met without an upfront
-      # wipe. Rows go through {Component#draw_text}, so the padding and blank
-      # rows inherit {Component#effective_bg_color} when {#bg} is unset.
+      # wipe. Rows go through {Component#draw_text}, so the text, the trailing
+      # padding and the blank rows all take {Component#bg_color}, and a span
+      # that carries its own background keeps it.
       # @return [void]
       def repaint
         return if rect.empty?
@@ -84,7 +60,7 @@ module Tuile
       protected
 
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         update_rows
       end
@@ -94,20 +70,12 @@ module Tuile
       # Recomputes {@rows} for the current text and rect width.
       # Each line is ellipsized to fit and padded with trailing spaces out to
       # the full width, so {#repaint} is just a lookup + {Buffer#set_text} per
-      # row. {@blank_row} covers rows past the last text line. When {#bg} is
-      # set, every produced line (and the blank row) has the bg applied
-      # uniformly.
+      # row. {@blank_row} covers rows past the last text line.
       # @return [void]
       def update_rows
         width = rect.width.clamp(0, nil)
-        @blank_row = apply_bg(StyledString.plain(" " * width))
-        @rows = @text.lines.map { |line| apply_bg(pad_to(line.ellipsize(width), width)) }
-      end
-
-      # @param line [StyledString]
-      # @return [StyledString]
-      def apply_bg(line)
-        @bg ? line.with_bg(@bg) : line
+        @blank_row = StyledString.plain(" " * width)
+        @rows = @text.lines.map { |line| pad_to(line.ellipsize(width), width) }
       end
 
       # @param line [StyledString]

data/lib/tuile/component/layout/box.rb

@@ -26,6 +26,13 @@ module Tuile
       # Nest boxes to vary the gap — a `Vertical.new(spacing: 0)` inside a
       # `Vertical.new(spacing: 1)` groups two rows tightly within a looser stack.
       #
+      # **Hiding a pane is {#remove}, not `Fixed[0]`** (see {Fixed} for why an
+      # empty rect is not hiding). {#add}'s `at:` is what makes it reversible —
+      # keep the index and the constraints on your side:
+      #
+      #   remove(@sidebar)                    # hide: siblings reclaim the space
+      #   add(@sidebar, Expand[1], at: 0)     # show: back where it was
+      #
       # == Implementation details
       #
       # Every child-list mutation re-runs the whole pass, because in a box the
@@ -98,6 +105,7 @@ module Tuile
         #
         #   add(field, Fixed[1], cross: Fixed[30], align: :center)
         #   add([ok, cancel], Fixed[1])
+        #   add(sidebar, Expand[1], at: 0)   # back where it was, after a #remove
         #
         # @param child [Component, Enumerable<Component>]
         # @param main [Fixed, Percent, Expand] extent along the main axis.
@@ -105,24 +113,58 @@ module Tuile
         # @param align [Symbol] one of {ALIGNMENTS} — where a child narrower than
         #   the cross extent sits. {Vertical} / {Horizontal} say which edge
         #   `:start` is.
+        # @param at [Integer, nil] position among the existing children; appends
+        #   when nil. An Enumerable is inserted in order from there. This is what
+        #   makes hiding-by-{#remove} reversible — see the class doc.
         # @raise [ArgumentError] on an unknown constraint or alignment, or an
         #   {Expand} passed as `cross` (see {Expand}).
         # @raise [TypeError] if `child` is not a {Component}.
         # @return [void]
-        def add(child, main = Fixed[1], cross: Percent[100], align: :start)
+        def add(child, main = Fixed[1], cross: Percent[100], align: :start, at: nil)
           if child.is_a? Enumerable
-            child.each { add(_1, main, cross:, align:) }
+            child.each_with_index { |c, i| add(c, main, cross:, align:, at: at && at + i) }
             return
           end
 
           validate_main(main)
           validate_cross(cross)
           validate_align(align)
-          add_child(child)
+          add_child(child, at:)
           @placements[child] = { main:, cross:, align: }
           relayout
         end
 
+        # Re-constrains a child already in the layout and re-runs the pass. A
+        # `nil` argument keeps what that axis already had, so one can move alone:
+        #
+        #   box.constrain(sidebar, Fixed[0])   # collapse it; cross: and align: stand
+        #
+        # `Fixed[0]` *collapses* — see {Fixed} for why that is not the same as
+        # hiding, and the class doc for what is.
+        #
+        # @param child [Component] a child of this layout.
+        # @param main [Fixed, Percent, Expand, nil] extent along the main axis.
+        # @param cross [Fixed, Percent, nil] extent across it.
+        # @param align [Symbol, nil] one of {ALIGNMENTS}.
+        # @raise [ArgumentError] if `child` is not a child of this layout, or on
+        #   an unknown constraint or alignment.
+        # @return [void]
+        def constrain(child, main = nil, cross: nil, align: nil)
+          raise ArgumentError, "#{child} is not a child of #{self}" unless children.any? { _1.equal?(child) }
+
+          validate_main(main) unless main.nil?
+          validate_cross(cross) unless cross.nil?
+          validate_align(align) unless align.nil?
+
+          current = placement(child)
+          updated = { main: main || current[:main], cross: cross || current[:cross],
+                      align: align || current[:align] }
+          return if current == updated
+
+          @placements[child] = updated
+          relayout
+        end
+
         # Removes the child, forgets its constraints, and closes the gap it left
         # by re-running the layout.
         # @param child [Component]
@@ -140,19 +182,37 @@ module Tuile
           relayout
         end
 
+        protected
+
+        # Re-divides the space: a child that went hidden gives its slot *and*
+        # the {#spacing} around it to its siblings, and one that came back takes
+        # them again with the constraints it was added with — which is what
+        # {Component#visible=} buys over `remove` plus `add(…, at:)`.
+        # @param _child [Component]
+        # @return [void]
+        def handle_child_visibility_changed(_child)
+          super
+          relayout
+        end
+
         private
 
-        # Recomputes and assigns every child's rect. Silent until this layout has
-        # a rect of its own — {#add} runs during construction, long before a
-        # parent assigns one.
+        # Recomputes and assigns every child's rect, giving each an empty one
+        # when this layout's own rect — or {#inner_rect} — is empty.
+        #
+        # Deliberately *no* `return if rect.empty?` guard: that strands the
+        # children at the coordinates they last had, and the next full repaint
+        # paints them there (`D_empty_ancestor`). Construction is silent without
+        # one anyway — {#add} runs before a parent assigns a rect, so the
+        # children are already empty and `invalidate` no-ops while detached.
         # @return [void]
         def relayout
-          return if rect.empty?
-
           inner = inner_rect
-          if inner.empty?
-            children.each { _1.rect = Rect.new(rect.left, rect.top, 0, 0) }
+          collapsed = Rect.new(rect.left, rect.top, 0, 0)
+          if rect.empty? || inner.empty?
+            children.each { _1.rect = collapsed }
           else
+            children.each { _1.rect = collapsed unless _1.visible? }
             place_children(inner)
           end
           invalidate
@@ -168,20 +228,30 @@ module Tuile
         # @param inner [Rect] {#inner_rect}, known non-empty.
         # @return [void]
         def place_children(inner)
-          sizes = main_sizes(inner)
+          kids = shown_children
+          sizes = main_sizes(inner, kids)
           available = cross_extent(inner)
           offset = 0
-          children.each_with_index do |child, i|
+          kids.each_with_index do |child, i|
             cross_offset, cross_size = cross_placement(child, available)
             child.rect = build_rect(inner, offset, sizes[i], cross_offset, cross_size)
             offset += sizes[i] + spacing
           end
         end
 
+        # The children this pass divides space between — a hidden one is out of
+        # the {#spacing} count as well as the arithmetic, so hiding a middle
+        # child closes the row up rather than leaving a double gap. Contrast a
+        # `Fixed[0]` child, still a member of the sequence and still paying for
+        # its gap (`D_visibility`).
+        # @return [Array<Component>]
+        def shown_children = children.select(&:visible?)
+
         # @param inner [Rect] {#inner_rect}.
-        # @return [Array<Integer>] main-axis extent per child, in child order.
-        def main_sizes(inner)
-          count = children.size
+        # @param kids [Array<Component>] {#shown_children}.
+        # @return [Array<Integer>] main-axis extent per shown child, in order.
+        def main_sizes(inner, kids)
+          count = kids.size
           return [] if count.zero?
 
           available = [main_extent(inner) - (spacing * (count - 1)), 0].max
@@ -189,7 +259,7 @@ module Tuile
           expanding = []
           unassigned = available
 
-          children.each_with_index do |child, i|
+          kids.each_with_index do |child, i|
             case (constraint = placement(child)[:main])
             when Expand then expanding << i
             when Fixed then unassigned -= (sizes[i] = constraint.cells.clamp(0, unassigned))
@@ -197,19 +267,20 @@ module Tuile
             end
           end
 
-          distribute_expand(sizes, expanding, unassigned) unless expanding.empty?
+          distribute_expand(sizes, kids, expanding, unassigned) unless expanding.empty?
           sizes
         end
 
         # Splits `slack` between the {Expand} children by weight, writing the
         # results into `sizes`.
         # @param sizes [Array<Integer>] mutated in place.
+        # @param kids [Array<Component>] {#shown_children}, which `indices` index.
         # @param indices [Array<Integer>] child indices carrying an {Expand}.
         # @param slack [Integer] cells left over; a negative value yields zeroes.
         # @return [void]
-        def distribute_expand(sizes, indices, slack)
+        def distribute_expand(sizes, kids, indices, slack)
           slack = 0 if slack.negative?
-          weights = indices.map { placement(children[_1])[:main].weight }
+          weights = indices.map { placement(kids[_1])[:main].weight }
           total = weights.sum
           shares = weights.map { slack * _1 / total }
           # Under one cell is lost per floor, so the remainder can't outrun the

data/lib/tuile/component/layout.rb

@@ -23,7 +23,14 @@ module Tuile
       #   add(prompt, Fixed[4])                    # 4 rows in a Vertical
       #   add(field, Fixed[1], cross: Fixed[30])   # 1 row, 30 columns wide
       #
-      # `Fixed[0]` hides the child — it gets an empty rect and paints nothing.
+      # `Fixed[0]` *collapses* the child: it and its whole subtree get an empty
+      # rect and paint nothing. That is not the same as hiding it — an empty
+      # rect is a paint convention and gates nothing else, so the subtree keeps
+      # its tab stops and still takes keys. **To hide a child, set
+      # {Component#visible=} false**; it then costs no {Box#spacing} gap either,
+      # where a collapsed child still does. The difference is exactly that: a
+      # collapsed child is still a member of the sequence, a hidden one is not
+      # (`D_visibility`).
       #
       # @!attribute [r] cells
       #   @return [Integer] cell count along the axis.
@@ -166,7 +173,7 @@ module Tuile
       # the popup. Layouts don't paint any visible chrome of their own
       # (the auto-cleared background is just blank space), so this has no
       # mouse-routing consequences — clicks on a gap area land back on the
-      # Layout itself and the on_focus cascade forwards to a tab stop.
+      # Layout itself and the handle_focus cascade forwards to a tab stop.
       def focusable? = true
 
       # Adds a child component to this layout.
@@ -191,7 +198,7 @@ module Tuile
       end
 
       # @return [void]
-      def on_focus
+      def handle_focus
         super
         # Forward focus to the first interactive widget in the subtree so the
         # user can start typing / cursoring immediately. Prefer a {#tab_stop?}
@@ -199,12 +206,15 @@ module Tuile
         # containers like a {Window} or another {Layout}. Fall back to the
         # first focusable direct child for the rare case where the layout has
         # focusable but non-tab-stop children (e.g. an empty {Window}).
+        #
+        # Both halves skip hidden subtrees — this is the cascade that would
+        # otherwise walk straight back into the pane just hidden.
         first_tab_stop = nil
-        on_tree { |c| first_tab_stop ||= c if !c.equal?(self) && c.tab_stop? }
+        walk_shown_tree { |c| first_tab_stop ||= c if !c.equal?(self) && c.tab_stop? }
         if first_tab_stop
           screen.focused = first_tab_stop
         else
-          first_focusable = @children.find(&:focusable?)
+          first_focusable = @children.find { _1.visible? && _1.focusable? }
           screen.focused = first_focusable unless first_focusable.nil?
         end
       end