tuile 0.10.0 → 0.12.0

data/lib/tuile/component/checkbox_group.rb

@@ -23,12 +23,13 @@ module Tuile
     # Treat it as *unordered*: it iterates in toggle order, so use
     # `cg.items & cg.value.to_a` when you need {#items} order.
     #
-    # Composes rather than subclasses, like {ComboBox}: a {List} is its single
-    # {HasContent} child, which is where the cursor, scrolling, the scrollbar and
-    # per-row mouse hit-testing come from. `content` is that list, so an app can
-    # tune it (`scrollbar_visibility`, `show_cursor_when_inactive`, …). Rows
-    # beyond {#rect}'s height scroll; the inner list is the tab stop, not the
-    # group.
+    # Composes rather than subclasses, like {ComboBox}: a {List} of the items is
+    # its single {HasContent} child, which is where the cursor, scrolling, the
+    # scrollbar and per-row mouse hit-testing come from — the group only supplies
+    # the {List#renderer} that puts the box in front of the label. `content` is
+    # that list, so an app can tune it (`scrollbar_visibility`,
+    # `show_cursor_when_inactive`, …). Rows beyond {#rect}'s height scroll; the
+    # inner list is the tab stop, not the group.
     #
     # == +items+ is chrome; +value+ is authoritative
     # {#items=} changes only what is *presented*. It never touches {#value} and
@@ -46,7 +47,7 @@ module Tuile
     # mutated after being selected becomes unfindable. Two `==`-equal items also
     # share one selection — their rows check and uncheck together — whereas two
     # *distinct* items that merely render the same label toggle independently,
-    # because a row resolves to an item by index.
+    # because a row resolves to its own item, never to its label.
     #
     # Rows repeat {Checkbox}'s `[x] `/`[ ] ` glyph convention rather than
     # importing a constant from it.
@@ -67,7 +68,6 @@ module Tuile
       #   matter to a form helper.
       def initialize(items: [], value: nil)
         super()
-        @items = items.to_a
         @item_label = :to_s.to_proc
         @value = coerce(value)
         @on_value_change = nil
@@ -75,13 +75,14 @@ module Tuile
         list = List.new
         # A List has no cursor at all by default (Cursor::None, position -1).
         list.cursor = List::Cursor.new
-        list.on_item_chosen = ->(index, _line) { toggle_at(index) }
+        list.renderer = method(:render_row)
+        list.on_item_chosen = ->(_index, item) { toggle(item) }
+        list.items = items.to_a
         self.content = list
-        rebuild_rows
       end
 
       # @return [Array] the presented items.
-      attr_reader :items
+      def items = content.items
 
       # @return [Proc, Method] item -> row label (a `String`, {StyledString}, or
       #   anything with `#to_s`); `:to_s` by default.
@@ -92,17 +93,14 @@ module Tuile
       # @raise [TypeError] unless `new_items` is an `Array`.
       # @return [void]
       def items=(new_items)
-        raise TypeError, "expected Array, got #{new_items.inspect}" unless new_items.is_a?(Array)
-
-        @items = new_items
-        rebuild_rows
+        content.items = new_items
       end
 
       # @param proc [Proc, Method] item -> row label.
       # @return [void]
       def item_label=(proc)
         @item_label = proc
-        rebuild_rows
+        content.refresh_rows
       end
 
       # @return [Set] the frozen empty set — {HasValue#empty?} means nothing is
@@ -122,7 +120,7 @@ module Tuile
         return if value == selected
 
         super(selected)
-        rebuild_rows
+        content.refresh_rows
       end
 
       # Toggles the cursor row on Space. Nothing else is claimed: the composed
@@ -148,22 +146,29 @@ module Tuile
       private
 
       # Flips membership of the item on row `index`; an index outside {#items} is
-      # ignored.
+      # ignored — {List::Cursor::None}'s `-1` would otherwise toggle the *last*
+      # item.
       # @param index [Integer]
       # @return [void]
       def toggle_at(index)
-        return unless index.between?(0, @items.size - 1)
+        return unless index.between?(0, items.size - 1)
 
-        item = @items[index]
-        self.value = value.include?(item) ? value - [item] : value + [item]
+        toggle(items[index])
       end
 
-      # Re-renders every row from the current items, labels and selection.
+      # Flips `item`'s membership of {#value}.
+      # @param item [Object]
       # @return [void]
-      def rebuild_rows
-        content.lines = @items.map do |item|
-          StyledString.plain(value.include?(item) ? "[x] " : "[ ] ") + label_for(item)
-        end
+      def toggle(item)
+        self.value = value.include?(item) ? value - [item] : value + [item]
+      end
+
+      # @param item [Object]
+      # @return [StyledString] the item's row: its label behind a checkmark box.
+      #   The {List} calls this at paint time, so the boxes track {#value}
+      #   without re-rendering anything but the visible rows.
+      def render_row(item)
+        StyledString.plain(value.include?(item) ? "[x] " : "[ ] ") + label_for(item)
       end
 
       # @param new_value [Enumerable, nil]

data/lib/tuile/component/combo_box.rb

@@ -52,7 +52,8 @@ module Tuile
         self.content = field
 
         @overlay = ListDropdown.new
-        @overlay.on_item_chosen = ->(index, _line) { commit(index) }
+        @overlay.renderer = ->(item) { @item_label.call(item) }
+        @overlay.on_item_chosen = ->(_index, item) { commit(item) }
       end
 
       # @return [Array] the candidate items.
@@ -147,11 +148,12 @@ module Tuile
       protected
 
       # Field spans the row bar the last column, which the `▾` occupies
-      # ({HasContent} layout hook).
+      # ({HasContent} layout hook). One row, or none at all when the combo itself
+      # was given none — a starved parent must not hand out a rect it doesn't own.
       # @param field [Component]
       # @return [void]
       def layout(field)
-        field.rect = Rect.new(rect.left, rect.top, [rect.width - 1, 0].max, 1)
+        field.rect = Rect.new(rect.left, rect.top, [rect.width - 1, 0].max, [rect.height, 1].min)
       end
 
       private
@@ -194,7 +196,7 @@ module Tuile
         if @filtered.empty?
           close_menu
         else
-          @overlay.lines = @filtered.map { |item| @item_label.call(item) }
+          @overlay.items = @filtered
           @overlay.cursor = List::Cursor.new(position: @filtered.index(value) || 0)
           @overlay.open unless @overlay.open?
           anchor
@@ -213,12 +215,11 @@ module Tuile
         @items.select { |item| @item_label.call(item).to_s.downcase.include?(needle) }
       end
 
-      # Commits the item at the menu's `index`: closes the dropdown and adopts
-      # it as {#value} (which repaints the field with its label).
-      # @param index [Integer]
+      # Commits the item chosen from the menu: closes the dropdown and adopts it
+      # as {#value} (which repaints the field with its label).
+      # @param item [Object]
       # @return [void]
-      def commit(index)
-        item = @filtered[index]
+      def commit(item)
         close_menu
         self.value = item
       end
@@ -234,6 +235,9 @@ module Tuile
 
       # Sets the field's text without triggering a refilter — for programmatic
       # value changes and query reverts, which must not spring the dropdown.
+      # Every programmatic write to the field goes through here; a direct
+      # `content.text =` reaches the field's `on_change` and pops the dropdown
+      # open on a {#value=} the user never asked to browse.
       # Parks the caret at the end: `text=` only *clamps* the caret, so a
       # shorter query replaced by a longer label would otherwise strand it
       # mid-word (commit "Go", then pick "Kotlin" → caret after "Ko").
@@ -251,31 +255,12 @@ module Tuile
       # @return [String] the plain-text label for `item`, or "" for nil.
       def display_for(item) = item.nil? ? "" : @item_label.call(item).to_s
 
-      # Sizes and positions the dropdown against the field: full combo width,
-      # `min(matches, 10)` rows, below the field — flipped above when it won't
-      # fit beneath, clamped (with the list scrolling) when it fits neither.
+      # Places the dropdown at the combo's own width, so both its edges line up
+      # with the field — at the cost of the scrollbar taking its column from the
+      # labels, which ellipsize a column earlier once the list scrolls. That is
+      # the trade a measuring driver ({Select}) makes the other way.
       # @return [void]
-      def anchor
-        desired = [@filtered.size, MAX_VISIBLE_ROWS].min
-        below = screen.size.height - (rect.top + 1)
-        above = rect.top
-        if desired <= below
-          top = rect.top + 1
-          height = desired
-        elsif above >= below
-          height = [desired, above].min
-          top = rect.top - height
-        else
-          height = below
-          top = rect.top + 1
-        end
-        @overlay.size = Size.new(rect.width, height)
-        @overlay.rect = Rect.new(rect.left, top, rect.width, height)
-      end
-
-      # Most matches shown before the dropdown scrolls.
-      # @return [Integer]
-      MAX_VISIBLE_ROWS = 10
+      def anchor = @overlay.anchor_to(rect, rows: @filtered.size)
     end
   end
 end

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/info_window.rb

@@ -25,7 +25,7 @@ module Tuile
       #   list wraps and scrolls within it. Defaults to {Fraction::HALF}.
       # @return [Popup] the opened popup.
       def self.open(caption, lines, size: Fraction::HALF)
-        Popup.open(content: InfoWindow.new(caption, lines), size: size)
+        Popup.new(content: InfoWindow.new(caption, lines), size: size).open
       end
     end
   end

data/lib/tuile/component/label.rb

@@ -16,8 +16,8 @@ module Tuile
         super()
         @text = StyledString::EMPTY
         @bg = nil
-        @clipped_lines = []
-        @blank_line = ""
+        @rows = []
+        @blank_row = ""
         self.text = text unless text.nil?
       end
 
@@ -43,7 +43,7 @@ module Tuile
         return if @text == new_text
 
         @text = new_text
-        update_clipped_lines
+        update_rows
         invalidate
       end
 
@@ -60,7 +60,7 @@ module Tuile
         return if @bg == new_bg
 
         @bg = new_bg
-        update_clipped_lines
+        update_rows
         invalidate
       end
 
@@ -69,15 +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. Rows go through {Component#draw_line}, so the padding and blank
+      # wipe. Rows go through {Component#draw_text}, 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
-          draw_line(rect.left, rect.top + row, line)
+          line = @rows[row] || @blank_row
+          draw_text(rect.left, rect.top + row, line)
         end
       end
 
@@ -86,22 +86,22 @@ module Tuile
       # @return [void]
       def on_width_changed
         super
-        update_clipped_lines
+        update_rows
       end
 
       private
 
-      # Recomputes {@clipped_lines} for the current text and rect width.
+      # 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_line} per
-      # row. {@blank_line} covers rows past the last text line. When {#bg} is
+      # 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.
       # @return [void]
-      def update_clipped_lines
+      def update_rows
         width = rect.width.clamp(0, nil)
-        @blank_line = apply_bg(StyledString.plain(" " * width))
-        @clipped_lines = @text.lines.map { |line| apply_bg(pad_to(line.ellipsize(width), width)) }
+        @blank_row = apply_bg(StyledString.plain(" " * width))
+        @rows = @text.lines.map { |line| apply_bg(pad_to(line.ellipsize(width), width)) }
       end
 
       # @param line [StyledString]