tuile 0.10.0 → 0.11.0

data/lib/tuile/component/float_field.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A single-line field whose {#value} is a `Float` (or `nil` when empty) —
+    # the {IntegerField} twin, one Ruby type over. Give it a single-row {#rect}:
+    #
+    #   field = Component::FloatField.new
+    #   field.on_value_change = ->(x) { puts x.inspect }  # Float or nil, per change
+    #   field.value = 19.99                               # field shows "19.99"
+    #   field.clear                                       # empties it; value => nil
+    #
+    # Only `0`–`9`, one leading `-` and one `.` can be typed; any other
+    # printable key is dropped without moving the caret. Up/Down step by `1.0`
+    # (an empty field counting as `0.0`). A `Float` is a binary double, so this
+    # is the wrong field for money — hold that as `Integer` cents in an
+    # {IntegerField} — and range checks (`min`/`max`) belong to a forms layer,
+    # not here.
+    #
+    # == Implementation details
+    # {#value} is a *derived parse*: the buffer is the single source of truth,
+    # recomputed on read and left exactly as typed (`"007"` keeps its zeros).
+    # It reads `nil` for a buffer that isn't a number (`""`, a lone `"-"`) but
+    # `1.0` / `0.5` for a half-typed `"1."` / `".5"`, so reaching for the
+    # decimal point doesn't blink the value to `nil` and back through
+    # {#on_value_change} — which fires per keystroke, but only on a real *value*
+    # change (`"7"`→`"07"` is silent). The parse also accepts the exponent
+    # `Float#to_s` writes for extreme magnitudes, so `value = 1e-5` round-trips
+    # through the `"1.0e-05"` it displays, though no key types an `e`.
+    #
+    # It *composes* a {TextField} (its single {HasContent} child) rather than
+    # subclassing one, so its face carries only the typed {HasValue} seam, never
+    # the widget's `String`-typed `text`.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class FloatField < Component
+      include HasContent
+      include HasValue
+
+      # A buffer {#value} parses: an optional sign, digits with an optional
+      # fractional part (either side may be empty, but not both), and the
+      # exponent {#value=} can write.
+      # @return [Regexp]
+      NUMERIC = /\A-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?\z/
+      private_constant :NUMERIC
+
+      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
+      end
+
+      # @return [Float, nil] the parsed buffer; `nil` when empty or not a
+      #   number (e.g. a lone `"-"`).
+      def value
+        text = content.text
+        text.match?(NUMERIC) ? text.to_f : nil
+      end
+
+      # Writes `new_value` into the buffer and parks the caret at its end; fires
+      # {#on_value_change} only if the value actually changed.
+      # @param new_value [Numeric, nil] `nil` empties the field; anything else
+      #   is coerced with `Float()`, so an `Integer` `3` shows as `"3.0"`.
+      # @raise [ArgumentError] on a non-numeric `String`, a NaN or an infinity.
+      # @raise [TypeError] on a value `Float()` won't take at all (an `Array`).
+      # @return [void]
+      def value=(new_value)
+        content.text = new_value.nil? ? "" : coerce(new_value).to_s
+        content.caret = content.text.length
+      end
+
+      # `nil`, not `""`: a numeric 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)
+
+      private
+
+      # @param new_value [Numeric]
+      # @return [Float]
+      # @raise [ArgumentError] on a NaN or an infinity — `Float::NAN.to_s` is
+      #   `"NaN"`, which no parse reads back, so writing one would silently
+      #   turn the value `nil`.
+      def coerce(new_value)
+        float = Float(new_value)
+        raise ArgumentError, "value must be finite, got #{float}" unless float.finite?
+
+        float
+      end
+
+      # The field's key interceptor, consulted *before* the field acts on the
+      # key — which is what lets a rejected character be swallowed without the
+      # caret ever moving.
+      # @param key [String]
+      # @return [Boolean] true to consume the key.
+      def field_key(key)
+        case key
+        when Keys::UP_ARROW then step(1.0)
+        when Keys::DOWN_ARROW then step(-1.0)
+        else return Keys.printable?(key) && !accepts?(key)
+        end
+        true
+      end
+
+      # Nudges {#value} by `delta`, treating an empty/un-parseable field as
+      # `0.0`.
+      # @param delta [Float]
+      # @return [void]
+      def step(delta) = (self.value = (value || 0.0) + delta)
+
+      # Whether `char` may be inserted. Deliberately shallow: it keeps the
+      # buffer *typeable* rather than always-valid — a transient `"-"` or
+      # `"1."` has to be reachable — and {#value} decides what parses.
+      # @param char [String] a single printable character.
+      # @return [Boolean]
+      def accepts?(char)
+        case char
+        when /\A[0-9]\z/ then true
+        when "-" then content.caret.zero? && !content.text.start_with?("-")
+        when "." then !content.text.include?(".")
+        else false
+        end
+      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/layout/box.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    class Layout
+      # Abstract base of the one-dimensional box layouts. Children are stacked
+      # along a *main* axis in the order they were added, each getting the extent
+      # its constraint asks for; across the *cross* axis they are sized one at a
+      # time, since nothing competes with them there. {Vertical} and {Horizontal}
+      # pick which axis is which.
+      #
+      #   class LoginForm < Tuile::Component::Layout::Vertical
+      #     def initialize
+      #       super(spacing: 1, padding: Insets[top: 1])
+      #       add(@prompt = Tuile::Component::Label.new, Fixed[4])
+      #       add(@user = Tuile::Component::TextField.new, Fixed[1], cross: Fixed[30])
+      #       add(@log = Tuile::Component::TextView.new, Expand[1])
+      #     end
+      #   end
+      #
+      # The constraint names need no prefix inside a subclass — Ruby finds them on
+      # `Layout`, an ancestor. Component classes are not on that chain and still do.
+      #
+      # Children pack from the start edge, so with no {Expand} among them the
+      # slack is simply left at the end: there is no filler component to add.
+      # 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.
+      #
+      # == Implementation details
+      #
+      # Every child-list mutation re-runs the whole pass, because in a box the
+      # children move: removing one shifts everything after it, and adding one
+      # shrinks every {Expand} share. ({Absolute} can skip this — there, siblings
+      # are independent.)
+      #
+      # Main-axis resolution order, against
+      # `available = extent - padding - spacing * (children - 1)`:
+      #
+      # 1. {Fixed} takes its cells, clamped to what is still unassigned.
+      # 2. {Percent} takes its share *of `available`*, likewise clamped.
+      # 3. {Expand} children split the residue by weight; the integer remainder
+      #    goes to the earliest of them, one cell each.
+      #
+      # So over-subscription starves in declaration order rather than raising:
+      # a child with nothing left gets an empty rect and paints nothing. Padding
+      # wider than the layout does the same to every child.
+      class Box < Layout
+        # Constraints for a child wired in through `add_child` instead of {#add}.
+        # @return [Hash{Symbol => Object}]
+        DEFAULT_PLACEMENT = { main: Fixed[1], cross: Percent[100], align: :start }.freeze
+
+        # Where a child narrower than the cross extent sits within it.
+        # @return [Array<Symbol>]
+        ALIGNMENTS = %i[start center end].freeze
+
+        # @param spacing [Integer] blank cells between adjacent children; `>= 0`.
+        # @param padding [Insets, Integer] inset from this layout's own rect; an
+        #   Integer is coerced to a uniform {Insets}.
+        # @raise [ArgumentError] on a negative `spacing` or an unusable `padding`.
+        def initialize(spacing: 0, padding: 0)
+          super()
+          @spacing = validate_spacing(spacing)
+          @padding = Insets.coerce(padding)
+          # Identity-keyed: two == children are still two distinct slots.
+          @placements = {}.compare_by_identity
+        end
+
+        # @return [Integer] blank cells between adjacent children.
+        attr_reader :spacing
+
+        # @return [Insets] inset from this layout's own rect.
+        attr_reader :padding
+
+        # @param cells [Integer] blank cells between adjacent children; `>= 0`.
+        # @raise [ArgumentError] on a negative value.
+        # @return [void]
+        def spacing=(cells)
+          cells = validate_spacing(cells)
+          return if @spacing == cells
+
+          @spacing = cells
+          relayout
+        end
+
+        # @param insets [Insets, Integer] an Integer becomes a uniform inset.
+        # @raise [ArgumentError] on anything else.
+        # @return [void]
+        def padding=(insets)
+          insets = Insets.coerce(insets)
+          return if @padding == insets
+
+          @padding = insets
+          relayout
+        end
+
+        # Adds a child — or every element of an Enumerable, all with the same
+        # constraints — and re-runs the layout.
+        #
+        #   add(field, Fixed[1], cross: Fixed[30], align: :center)
+        #   add([ok, cancel], Fixed[1])
+        #
+        # @param child [Component, Enumerable<Component>]
+        # @param main [Fixed, Percent, Expand] extent along the main axis.
+        # @param cross [Fixed, Percent] extent across it.
+        # @param align [Symbol] one of {ALIGNMENTS} — where a child narrower than
+        #   the cross extent sits. {Vertical} / {Horizontal} say which edge
+        #   `:start` is.
+        # @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)
+          if child.is_a? Enumerable
+            child.each { add(_1, main, cross:, align:) }
+            return
+          end
+
+          validate_main(main)
+          validate_cross(cross)
+          validate_align(align)
+          add_child(child)
+          @placements[child] = { main:, cross:, align: }
+          relayout
+        end
+
+        # Removes the child, forgets its constraints, and closes the gap it left
+        # by re-running the layout.
+        # @param child [Component]
+        # @return [void]
+        def remove(child)
+          super
+          @placements.delete(child)
+          relayout
+        end
+
+        # @param new_rect [Rect]
+        # @return [void]
+        def rect=(new_rect)
+          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.
+        # @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) }
+          else
+            place_children(inner)
+          end
+          invalidate
+        end
+
+        # @return [Rect] {#rect} with {#padding} taken off each edge; may be
+        #   {Rect#empty? empty}.
+        def inner_rect
+          Rect.new(rect.left + padding.left, rect.top + padding.top,
+                   rect.width - padding.horizontal, rect.height - padding.vertical)
+        end
+
+        # @param inner [Rect] {#inner_rect}, known non-empty.
+        # @return [void]
+        def place_children(inner)
+          sizes = main_sizes(inner)
+          available = cross_extent(inner)
+          offset = 0
+          children.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
+
+        # @param inner [Rect] {#inner_rect}.
+        # @return [Array<Integer>] main-axis extent per child, in child order.
+        def main_sizes(inner)
+          count = children.size
+          return [] if count.zero?
+
+          available = [main_extent(inner) - (spacing * (count - 1)), 0].max
+          sizes = Array.new(count, 0)
+          expanding = []
+          unassigned = available
+
+          children.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))
+            else unassigned -= (sizes[i] = percent_of(available, constraint).clamp(0, unassigned))
+            end
+          end
+
+          distribute_expand(sizes, 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 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)
+          slack = 0 if slack.negative?
+          weights = indices.map { placement(children[_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
+          # share count — the earliest Expand children each take one.
+          (slack - shares.sum).times { |i| shares[i] += 1 }
+          indices.each_with_index { |child_index, i| sizes[child_index] = shares[i] }
+        end
+
+        # @param child [Component]
+        # @param available [Integer] cross extent of {#inner_rect}.
+        # @return [Array(Integer, Integer)] offset from `inner`'s start edge, and
+        #   extent, along the cross axis.
+        def cross_placement(child, available)
+          spec = placement(child)
+          size = case (constraint = spec[:cross])
+                 when Fixed then constraint.cells.clamp(0, available)
+                 else percent_of(available, constraint).clamp(0, available)
+                 end
+          [align_offset(spec[:align], available - size), size]
+        end
+
+        # @param align [Symbol] one of {ALIGNMENTS}.
+        # @param slack [Integer] unused cells across the axis.
+        # @return [Integer]
+        def align_offset(align, slack)
+          case align
+          when :center then slack / 2
+          when :end then slack
+          else 0
+          end
+        end
+
+        # @param extent [Integer]
+        # @param constraint [Percent]
+        # @return [Integer]
+        def percent_of(extent, constraint) = (extent * constraint.percent / 100.0).round
+
+        # @param child [Component]
+        # @return [Hash{Symbol => Object}] the child's `main`/`cross`/`align`.
+        def placement(child) = @placements[child] || DEFAULT_PLACEMENT
+
+        # @param rect [Rect]
+        # @return [Integer] the extent along the main axis.
+        def main_extent(rect) = raise(NotImplementedError, "#{self.class} must implement main_extent")
+
+        # @param rect [Rect]
+        # @return [Integer] the extent along the cross axis.
+        def cross_extent(rect) = raise(NotImplementedError, "#{self.class} must implement cross_extent")
+
+        # @param inner [Rect] {#inner_rect}, the origin both offsets are relative to.
+        # @param main_offset [Integer] cells along the main axis.
+        # @param main_size [Integer] extent along the main axis.
+        # @param cross_offset [Integer] cells along the cross axis.
+        # @param cross_size [Integer] extent along the cross axis.
+        # @return [Rect] absolute screen rect for one child.
+        def build_rect(inner, main_offset, main_size, cross_offset, cross_size)
+          raise NotImplementedError, "#{self.class} must implement build_rect"
+        end
+
+        # @param cells [Integer]
+        # @raise [ArgumentError] unless `cells` is a non-negative Integer.
+        # @return [Integer] `cells`.
+        def validate_spacing(cells)
+          unless cells.is_a?(Integer) && !cells.negative?
+            raise ArgumentError, "spacing expects a non-negative Integer, got #{cells.inspect}"
+          end
+
+          cells
+        end
+
+        # @param constraint [Object]
+        # @raise [ArgumentError] unless it is a {Fixed}, {Percent} or {Expand}.
+        # @return [void]
+        def validate_main(constraint)
+          return if [Fixed, Percent, Expand].any? { constraint.is_a?(_1) }
+
+          raise ArgumentError, "expected Fixed, Percent or Expand, got #{constraint.inspect}"
+        end
+
+        # @param constraint [Object]
+        # @raise [ArgumentError] unless it is a {Fixed} or {Percent}.
+        # @return [void]
+        def validate_cross(constraint)
+          if constraint.is_a? Expand
+            raise ArgumentError, "Expand is main-axis only — a child has no siblings competing " \
+                                 "across the axis; use Fixed or Percent for cross:"
+          end
+          return if constraint.is_a?(Fixed) || constraint.is_a?(Percent)
+
+          raise ArgumentError, "expected Fixed or Percent for cross:, got #{constraint.inspect}"
+        end
+
+        # @param align [Object]
+        # @raise [ArgumentError] unless it is one of {ALIGNMENTS}.
+        # @return [void]
+        def validate_align(align)
+          return if ALIGNMENTS.include?(align)
+
+          raise ArgumentError, "expected one of #{ALIGNMENTS.inspect}, got #{align.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    class Layout
+      # Lays children out left to right. The main axis is horizontal, so a
+      # child's positional constraint is its **width** and `cross:` is its
+      # **height**; `align: :start` is the top edge, `:end` the bottom.
+      #
+      #   split = Component::Layout::Horizontal.new
+      #   split.add(sidebar, Component::Layout::Fixed[30])
+      #   split.add(main, Component::Layout::Expand[1])   # takes the rest of the row
+      #
+      # Inside a subclass the constraints need no prefix at all — see {Box}.
+      #
+      # See {Box} for the constraint vocabulary and how the space is divided.
+      class Horizontal < Box
+        private
+
+        # @param rect [Rect]
+        # @return [Integer]
+        def main_extent(rect) = rect.width
+
+        # @param rect [Rect]
+        # @return [Integer]
+        def cross_extent(rect) = rect.height
+
+        # @param inner [Rect]
+        # @param main_offset [Integer] columns right of `inner`'s left.
+        # @param main_size [Integer] width.
+        # @param cross_offset [Integer] rows down from `inner`'s top.
+        # @param cross_size [Integer] height.
+        # @return [Rect]
+        def build_rect(inner, main_offset, main_size, cross_offset, cross_size)
+          Rect.new(inner.left + main_offset, inner.top + cross_offset, main_size, cross_size)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    class Layout
+      # Stacks children top to bottom. The main axis is vertical, so a child's
+      # positional constraint is its **height** and `cross:` is its **width**;
+      # `align: :start` is the left edge, `:end` the right.
+      #
+      #   form = Component::Layout::Vertical.new(spacing: 1)
+      #   form.add(caption, Component::Layout::Fixed[1])
+      #   form.add(field, Component::Layout::Fixed[1], cross: Component::Layout::Fixed[30])
+      #   form.add(log, Component::Layout::Expand[1])   # takes whatever is left below
+      #
+      # Inside a subclass the constraints need no prefix at all — see {Box}.
+      #
+      # See {Box} for the constraint vocabulary and how the space is divided.
+      class Vertical < Box
+        private
+
+        # @param rect [Rect]
+        # @return [Integer]
+        def main_extent(rect) = rect.height
+
+        # @param rect [Rect]
+        # @return [Integer]
+        def cross_extent(rect) = rect.width
+
+        # @param inner [Rect]
+        # @param main_offset [Integer] rows down from `inner`'s top.
+        # @param main_size [Integer] height.
+        # @param cross_offset [Integer] columns right of `inner`'s left.
+        # @param cross_size [Integer] width.
+        # @return [Rect]
+        def build_rect(inner, main_offset, main_size, cross_offset, cross_size)
+          Rect.new(inner.left + cross_offset, inner.top + main_offset, cross_size, main_size)
+        end
+      end
+    end
+  end
+end