tuile 0.9.0 → 0.11.0

data/lib/tuile/component/has_value.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # The value seam every input component shares: a settable/gettable {#value}
+    # of *any* type, an {#on_value_change} listener, {#empty?}, and {#clear}. A
+    # form (a future binder) drives a mix of field types uniformly through it,
+    # not caring that a {TextField}'s value is a `String` while another field's
+    # is a domain object.
+    #
+    #   field.on_value_change = ->(v) { puts "now: #{v.inspect}" }
+    #   field.value = "hello"   # fires the listener
+    #   field.clear             # value = empty_value, fires again
+    #
+    # The default {#value=}/{#value} keep the value in `@value` and are enough
+    # for a component with nothing more natural — you get a repaint and the
+    # listener for free. An includer whose value lives elsewhere overrides both
+    # ({AbstractStringField} backs them with its text buffer). Override {#empty_value}
+    # when the empty sentinel isn't `nil` (a text field's is `""`).
+    #
+    # == Implementation details
+    # Deliberately smaller than Vaadin's `HasValue`: read-only,
+    # required-indicator, the from-client/old-value event payload, and
+    # converters all belong to the not-yet-built form layer, not here.
+    module HasValue
+      # @return [Proc, Method, nil] one-arg callable fired with the new value
+      #   whenever {#value} actually changes — never on a no-op set.
+      attr_accessor :on_value_change
+
+      # @return [Object] the current value; `nil` until first set.
+      def value = @value
+
+      # No-op (no repaint, no listener) when equal to the current value.
+      # @param new_value [Object]
+      # @return [void]
+      def value=(new_value)
+        return if value == new_value
+
+        @value = new_value
+        invalidate
+        on_value_change&.call(new_value)
+      end
+
+      # @return [Boolean] true iff {#value} equals {#empty_value}.
+      def empty? = value == empty_value
+
+      # Resets {#value} to {#empty_value}.
+      # @return [void]
+      def clear = (self.value = empty_value)
+
+      # @return [Object] the value {#empty?}/{#clear} treat as empty; `nil`
+      #   unless an includer overrides it.
+      def empty_value = nil
+
+      # Input fields are focusable by default (overrides {Component#focusable?});
+      # a read-only display field could override back to `false`. Only
+      # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
+      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # `D-integer-field`).
+      # @return [Boolean]
+      def focusable? = true
+    end
+  end
+end

data/lib/tuile/component/integer_field.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+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`:
+    #
+    #   field = Component::IntegerField.new
+    #   field.on_value_change = ->(n) { puts n.inspect }  # Integer or nil, per change
+    #   field.value = 42                                   # field shows "42"
+    #   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}.
+    #
+    # == The value is a *derived parse* of the buffer
+    # {#value} is `Integer(buffer, 10)` (or `nil`), recomputed on read — the
+    # buffer is the single source of truth, {#value=} just writes it. So `"-"`
+    # alone and `""` both read as `nil`, and `on_value_change` fires eagerly
+    # once per real *value* change: typing `0`→`7` in `"07"` shifts the buffer
+    # but not the value (`7`), so it does not fire. No normalization — a typed
+    # `"007"` stays `"007"` on screen though its value is `7`.
+    #
+    # `min`/`max`, a `+` sign, and thousands separators are deliberately out of
+    # scope (range and formatting are a forms concern).
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class IntegerField < Component
+      include HasContent
+      include HasValue
+
+      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 [Integer, nil] the parsed buffer; `nil` when empty or not a
+      #   valid integer (e.g. a lone `"-"`).
+      def value
+        Integer(content.text, 10)
+      rescue ArgumentError
+        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 [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
+      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)
+
+      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

@@ -25,9 +25,11 @@ module Tuile
       #   {StyledString}.
       attr_reader :text
 
-      # @return [Color, nil] background color applied uniformly across every
-      #   painted row (including padding past the text). `nil` (default)
-      #   leaves whatever bg the text's own styling carries.
+      # @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}
@@ -45,11 +47,11 @@ module Tuile
         invalidate
       end
 
-      # Sets the background color. Coerced via {Color.coerce}, so a Symbol,
-      # Integer, Array, {Color}, or `nil` all work. `nil` clears the override
-      # — the label paints with whatever bg the text's own styling provides.
-      # Otherwise the bg overlays every span (including the trailing pad and
-      # blank rows past the last text line).
+      # 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]
@@ -67,14 +69,15 @@ module Tuile
       # 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.
+      # wipe. Rows go through {Component#draw_line}, so the padding and blank
+      # rows inherit {Component#effective_bg_color} when {#bg} is unset.
       # @return [void]
       def repaint
         return if rect.empty?
 
         (0...rect.height).each do |row|
           line = @clipped_lines[row] || @blank_line
-          screen.buffer.set_line(rect.left, rect.top + row, line)
+          draw_line(rect.left, rect.top + row, line)
         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