tuile 0.10.0 → 0.12.0

data/lib/tuile/component/select.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A closed-choice field on one row: the selected item's label plus a `▾`
+    # affordance, dropping open a {ListDropdown} of the options. Enter, Space or
+    # Down opens it; the arrows (and PgUp/PgDn) move the highlight; Enter or
+    # Space commits; ESC dismisses without committing.
+    #
+    #   warn                ▾     <- the face: one row, on a field well
+    #    debug                    <- the dropdown, measured to the widest label
+    #    info                        (the one-column gutters are {List}'s)
+    #    warn                     <- highlighted: the value's row, on open
+    #    error
+    #
+    #   sel = Component::Select.new(items: LogLevel.all)
+    #   sel.item_label = ->(l) { l.name }          # item -> shown label; default :to_s
+    #   sel.on_value_change = ->(l) { relog(l) }   # fires on commit, with the item
+    #   sel.value = LogLevel::WARN                 # selects it; the face shows its label
+    #
+    # Use it for an **enum** — labels the developer authored, a closed set known
+    # when the code is written: log level, sort order, line endings, Yes/No/Ask.
+    # For items the app supplies at runtime with labels you don't control
+    # (countries, users, branches) reach for {ComboBox} instead, where filtering
+    # is the navigation. Item count is a symptom, not the criterion; book ch7 has
+    # the widget-choice table.
+    #
+    # {#value} is the selected *item*, of whatever type {#items} holds, never its
+    # label; `nil` — a blank face — is the initial state and stays legal, so an
+    # optional enum field needs no placeholder. As on {ComboBox}, {#items=} is
+    # chrome: it never touches {#value}, never fires {HasValue#on_value_change},
+    # and a value absent from {#items} survives intact while rendering nothing
+    # selected. Keeping the two in sync is the app's job.
+    #
+    # == It claims no printable key but Space
+    # Enter, Space, ESC, {ListDropdown::MOVE_KEYS} and the mouse. *Every other*
+    # printable key bubbles past it (key-dispatch rung 3), so a form's `s`-to-save
+    # and a layout's `1`/`2`/`3` pane jumps keep working while a Select has focus
+    # — the one capability no {ComboBox} configuration can offer, since a text
+    # field eats printables unconditionally. Space is the single exception, and it
+    # forecloses nothing: every activatable widget in the gem already claims it.
+    # Home/End are declined too, so they stay available app-wide.
+    #
+    # There is no type-ahead: a hidden prefix buffer *is* the ComboBox query with
+    # the feedback removed (`DECISIONS.md` `D-select`). Which is also why labels
+    # need no prefix-disambiguation.
+    #
+    # == Implementation details
+    # A leaf widget: it paints its own row (the face is *derived* from {#value}
+    # each paint, never a synced copy) and owns the dropdown as an overlay, which
+    # is not a child — like {ComboBox}'s. The well is read from
+    # {Screen#theme} at paint time, so it tracks a theme flip with no hook.
+    #
+    # The dropdown is at least as wide as the face and grows to fit the widest
+    # label, so the labels are never the thing that ellipsizes. It is not opened
+    # at all when {#items} is empty: an item-less Select is a programming bug, and
+    # an empty tinted panel reads as a broken list rather than as "nothing to
+    # pick". Enter/Space/Down are claimed either way.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class Select < Component
+      include HasValue
+
+      # @param items [Array] the options (any type); also settable via {#items=}.
+      # @param value [Object, nil] the initially selected item. Seeds the backing
+      #   ivar directly, so no listener fires and assignment order doesn't matter
+      #   to a form helper.
+      def initialize(items: [], value: nil)
+        super()
+        @items = items.to_a
+        @item_label = :to_s.to_proc
+        @value = value
+        @on_value_change = nil
+        @overlay = ListDropdown.new
+        @overlay.renderer = method(:label_for)
+        @overlay.on_item_chosen = ->(_index, item) { commit(item) }
+      end
+
+      # @return [Array] the options.
+      attr_reader :items
+
+      # @return [Proc, Method] item -> shown label (a `String` or
+      #   {StyledString}); `:to_s` by default. Never called with `nil` — an
+      #   unselected Select renders a blank face.
+      attr_reader :item_label
+
+      def tab_stop? = true
+
+      # Replaces the options, leaving {#value} untouched. An open dropdown is
+      # rebuilt (and re-measured) around them, or closed when none are left.
+      # @param new_items [Array]
+      # @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
+        refill if @overlay.open?
+        invalidate
+      end
+
+      # @param proc [Proc, Method] item -> shown label.
+      # @return [void]
+      def item_label=(proc)
+        @item_label = proc
+        refill if @overlay.open?
+        invalidate
+      end
+
+      # @return [String]
+      def keyboard_hint = "⏎ #{screen.theme.hint("open")}  ↑↓ #{screen.theme.hint("select")}"
+
+      # Re-anchors the (open) dropdown after a move or resize.
+      # @param new_rect [Rect]
+      # @return [void]
+      def rect=(new_rect)
+        super
+        anchor if @overlay.open?
+      end
+
+      # Closes the dropdown when the Select leaves the focus chain, so tabbing
+      # away doesn't strand an open menu. Safe against re-entrancy: focus never
+      # sits inside the (non-focusable) {ListDropdown}, so closing it repairs no
+      # focus.
+      # @param flag [Boolean]
+      # @return [void]
+      def active=(flag)
+        was = active?
+        super
+        close_menu if was && !active?
+      end
+
+      # Opens the dropdown on Enter, Space or Down; while it is open, forwards
+      # {ListDropdown::MOVE_KEYS} to it, commits the highlight on Enter or Space,
+      # and dismisses on ESC. Everything else — every other printable included —
+      # is left unhandled so it bubbles to an ancestor.
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        if @overlay.open?
+          return true if @overlay.move(key)
+
+          case key
+          when Keys::ENTER, " " then @overlay.choose
+          when Keys::ESC then close_menu
+          else return false
+          end
+          true
+        elsif [Keys::ENTER, " ", Keys::DOWN_ARROW].include?(key)
+          open_menu
+          true
+        else
+          false
+        end
+      end
+
+      # Toggles the dropdown on a left click anywhere in {#rect} — a field's
+      # affordance is its whole row, as the well advertises; `super` runs first,
+      # so the click also focuses.
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        return unless event.button == :left && rect.contains?(event.point)
+
+        @overlay.open? ? close_menu : open_menu
+      end
+
+      # @return [void]
+      def repaint
+        return if rect.empty?
+
+        tail = Rect.new(rect.left, rect.top + 1, rect.width, rect.height - 1)
+        clear_background(tail) unless tail.empty?
+        draw_text(rect.left, rect.top, face_row)
+      end
+
+      private
+
+      # The painted row: the value's label padded across all but the last column,
+      # then the `▾`, all on the field well — {Theme#active_bg_color} while on the
+      # focus chain, {Theme#input_bg_color} otherwise.
+      # @return [StyledString]
+      def face_row
+        width = [rect.width - 1, 0].max
+        label = label_for(value).ellipsize(width)
+        row = label + StyledString.plain("#{" " * (width - label.display_width)}▾")
+        row.with_bg(active? ? screen.theme.active_bg_color : screen.theme.input_bg_color)
+      end
+
+      # Rebuilds the dropdown's rows, highlight and geometry, opening it if
+      # needed; closes it instead when there is nothing to show.
+      # @return [void]
+      def refill
+        if @items.empty?
+          close_menu
+          return
+        end
+
+        @overlay.items = @items
+        @overlay.cursor = List::Cursor.new(position: @items.index(value) || 0)
+        @overlay.open unless @overlay.open?
+        anchor
+      end
+
+      # @return [void]
+      def open_menu = refill
+
+      # @return [void]
+      def close_menu = (@overlay.close if @overlay.open?)
+
+      # Adopts the chosen item as {#value} and closes the dropdown.
+      # @param item [Object]
+      # @return [void]
+      def commit(item)
+        close_menu
+        self.value = item
+      end
+
+      # @return [void]
+      def anchor = @overlay.anchor_to(rect, rows: @items.size, width: menu_width)
+
+      # The dropdown's width: the widest label plus {List}'s two row gutters, plus
+      # the scrollbar column when the rows can't all be shown at once — but never
+      # narrower than the Select itself, so both edges line up with the face and
+      # the panel reads as belonging to it. Only a label that needs more pushes it
+      # wider.
+      #
+      # A dropdown the screen clamps shorter than
+      # {ListDropdown::MAX_VISIBLE_ROWS} scrolls without having bought that
+      # column, ellipsizing its labels one early — the {ComboBox} trade, in the
+      # one case measuring can't predict the height.
+      # @return [Integer]
+      def menu_width
+        widest = @items.map { |item| label_for(item).display_width }.max || 0
+        measured = widest + 2 + (@items.size > ListDropdown::MAX_VISIBLE_ROWS ? 1 : 0)
+        [measured, rect.width].max
+      end
+
+      # @param item [Object]
+      # @return [StyledString] `item`'s label, or empty for `nil` — so {#value}
+      #   being unset never reaches an {#item_label} that assumes an item.
+      def label_for(item)
+        return StyledString::EMPTY if item.nil?
+
+        label = @item_label.call(item)
+        label.is_a?(StyledString) ? label : StyledString.parse(label.to_s)
+      end
+    end
+  end
+end

data/lib/tuile/component/text_area/wrapped_text.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    class TextArea < AbstractStringField
+      # The word-wrapped layout of a {TextArea}'s text: which row each
+      # character lands on, and which glyphs each row paints.
+      #
+      #   wrap = WrappedText.new("hello world", 6)
+      #   wrap.row_count        # => 2
+      #   wrap.position_at(8)   # => [1, 2]    index 8 ("r") sits at row 1, column 2
+      #   wrap.index_at(1, 2)   # => 8         and back again
+      #   wrap.row_text(0)      # => "hello "  padded out to the width
+      #
+      # A snapshot of `(text, width)` — rebuild it whenever either changes.
+      #
+      # == Implementation details
+      #
+      # Two axes meet here, and every method name says which one it speaks: an
+      # **index** counts characters into {#text}, a **column** counts terminal
+      # cells. They agree only for one-column glyphs. A {Row} therefore carries
+      # *both* counts — the wrap fills each row to a column budget while
+      # recording the character span that produced it.
+      #
+      # The wrap walks **grapheme clusters**, not characters: a combining mark
+      # must add no columns and must not be split from its base across a row
+      # break. Note `"\r\n"` is a *single* cluster, so a hard break tests
+      # `end_with?("\n")` rather than equality. Every branch of the wrap
+      # consumes at least one cluster — `"\v"` and `"\f"` match `/\s/` but are
+      # neither blank nor a newline here, and a loop that measured them as zero
+      # and did not advance would hang the UI thread on
+      # `area.text = File.read(...)`.
+      class WrappedText
+        # One row's span, measured on both axes.
+        #
+        # Both counts cover only the row's *visible* content: whitespace absorbed
+        # at a soft wrap, and the newline ending a hard one, belong to no row. So
+        # the next row's `start` may sit past this row's `start + length`, and an
+        # index in that gap resolves to the earlier row (see {WrappedText#row_at}).
+        #
+        # @!attribute [r] start
+        #   @return [Integer] character index into {WrappedText#text} where the
+        #     row begins.
+        # @!attribute [r] length
+        #   @return [Integer] visible characters from `start`.
+        # @!attribute [r] columns
+        #   @return [Integer] terminal cells those characters occupy. Exceeds
+        #     {WrappedText#width} only for a single glyph too wide for a row.
+        class Row < Data.define(:start, :length, :columns)
+          # A zero-length row; `EMPTY.with(start: n)` rebases it onto an index.
+          # @return [Row]
+          EMPTY = new(start: 0, length: 0, columns: 0)
+        end
+
+        # @param text [String] the full buffer, unwrapped.
+        # @param width [Integer] column budget per row; `0` or less yields a
+        #   single empty row.
+        def initialize(text, width)
+          @text = text
+          @width = width
+          @rows = compute_rows
+        end
+
+        # @return [String]
+        attr_reader :text
+
+        # @return [Integer]
+        attr_reader :width
+
+        # @return [Integer] rows the text occupies; always `>= 1`, since
+        #   empty text still wraps to one (empty) row.
+        def row_count = @rows.size
+
+        # Display row holding `index`. An index inside a whitespace run absorbed
+        # by a soft wrap belongs to the row *before* the break.
+        # @param index [Integer] a character index into {#text}.
+        # @return [Integer] a row index in `0...row_count`.
+        def row_at(index)
+          @rows.each_with_index do |r, i|
+            next_start = i + 1 < @rows.size ? @rows[i + 1].start : @text.length + 1
+            return i if index >= r.start && index < next_start
+          end
+          @rows.size - 1
+        end
+
+        # @param index [Integer] a character index into {#text}.
+        # @return [Array(Integer, Integer)] `[row, column]` for `index`.
+        def position_at(index)
+          row = row_at(index)
+          [row, column_in(@rows[row], index)]
+        end
+
+        # Inverse of {#position_at}. A column landing in a wide glyph's right
+        # half resolves *past* it, as a click does in {TextField}.
+        # @param row [Integer] a row index in `0...row_count`.
+        # @param column [Integer] a column offset within that row.
+        # @return [Integer] a character index into {#text}.
+        def index_at(row, column)
+          r = @rows[row]
+          r.start + chars_for_column(r, column)
+        end
+
+        # @param row [Integer] a row index in `0...row_count`.
+        # @return [Integer] character index where the row begins.
+        def row_start(row) = @rows[row].start
+
+        # @param row [Integer] a row index in `0...row_count`.
+        # @return [Integer] character index one past the row's last *visible*
+        #   character — whitespace absorbed by a soft wrap is excluded.
+        def row_end(row)
+          r = @rows[row]
+          r.start + r.length
+        end
+
+        # The row's glyphs, padded with spaces out to {#width}. A trailing glyph
+        # with no room left is dropped rather than half-painted. A row past the
+        # end of the text is all spaces, so a caller can paint a viewport taller
+        # than the text without a bounds check.
+        # @param row [Integer]
+        # @return [String]
+        def row_text(row)
+          r = @rows[row]
+          return " " * @width if r.nil?
+
+          out = +""
+          cols = 0
+          glyphs_of(r).each_grapheme_cluster do |g|
+            w = Buffer.display_width(g)
+            break if cols + w > @width
+
+            out << g
+            cols += w
+          end
+          out << (" " * (@width - cols))
+        end
+
+        private
+
+        # A plain Hash rather than a {Row}-style Data: this table is one entry
+        # per grapheme cluster, built and discarded inside a single {#compute_rows}
+        # call and never handed to another method as a documented type.
+        # @return [Array<Hash{Symbol=>Object}>] one entry per grapheme cluster of
+        #   {#text}: `{offset: <text-index>, text: <cluster>, width: <columns>}`.
+        def cluster_table
+          offset = 0
+          @text.each_grapheme_cluster.map do |g|
+            entry = { offset: offset, text: g, width: Buffer.display_width(g) }
+            offset += g.length
+            entry
+          end
+        end
+
+        # @param cluster [Hash{Symbol=>Object}]
+        # @return [Boolean] true for a space or tab (each exactly one column).
+        def blank?(cluster) = cluster[:text].match?(/[ \t]/)
+
+        # @param cluster [Hash{Symbol=>Object}]
+        # @return [Boolean] true for a hard line break. Tests the suffix rather
+        #   than equality because `"\r\n"` is one grapheme cluster.
+        def newline?(cluster) = cluster[:text].end_with?("\n")
+
+        # Greedy word-wrap, filling each row to a **column** budget while recording
+        # the **character** span that produced it. Whitespace at a soft-wrap break
+        # point is absorbed (not rendered on either row). A token wider than
+        # {#width} hard-wraps inside the token. Newlines force a hard break and
+        # the wrap restarts on the next cluster.
+        # @return [Array<Row>] one entry per row.
+        def compute_rows
+          return [Row::EMPTY] if @width <= 0 || @text.empty?
+
+          cl = cluster_table
+          rows = []
+          i = 0
+          n = cl.size
+
+          while i < n
+            start = cl[i][:offset]
+            chars = 0
+            cols = 0
+
+            while i < n
+              g = cl[i]
+              break if newline?(g)
+
+              if blank?(g)
+                if cols < @width
+                  chars += g[:text].length
+                  cols += g[:width]
+                  i += 1
+                else
+                  chars, cols = trim_trailing_whitespace(start, chars, cols)
+                  i += 1 while i < n && blank?(cl[i])
+                  break
+                end
+              else
+                word_chars, word_cols, word_end = measure_word(cl, i)
+
+                if cols + word_cols <= @width
+                  chars += word_chars
+                  cols += word_cols
+                  i = word_end
+                elsif cols.zero?
+                  chars, cols, i = hard_wrap(cl, i)
+                  break
+                else
+                  chars, cols = trim_trailing_whitespace(start, chars, cols)
+                  break
+                end
+              end
+            end
+
+            rows << Row.new(start: start, length: chars, columns: cols)
+
+            next unless i < n && newline?(cl[i])
+
+            i += 1
+            rows << Row::EMPTY.with(start: @text.length) if i >= n
+          end
+
+          rows
+        end
+
+        # @param clusters [Array<Hash{Symbol=>Object}>]
+        # @param index [Integer] cluster index of the word's first glyph.
+        # @return [Array(Integer, Integer, Integer)] `[chars, columns, next_index]`
+        #   for the run of non-whitespace starting at `index`.
+        def measure_word(clusters, index)
+          chars = 0
+          cols = 0
+          while index < clusters.size && !blank?(clusters[index]) && !newline?(clusters[index])
+            chars += clusters[index][:text].length
+            cols += clusters[index][:width]
+            index += 1
+          end
+          [chars, cols, index]
+        end
+
+        # Splits a token too wide for a whole row, taking entire glyphs while they
+        # fit. Consumes at least one glyph even when that single glyph is wider than
+        # the row — otherwise the wrap would not terminate (the row would stay empty
+        # and the same token be reconsidered forever). Such a row reports more
+        # columns than {#width} holds and {#row_text} drops the glyph; a 2-column
+        # glyph in a 1-column area is unpaintable either way.
+        # @param clusters [Array<Hash{Symbol=>Object}>]
+        # @param index [Integer]
+        # @return [Array(Integer, Integer, Integer)] `[chars, columns, next_index]`
+        def hard_wrap(clusters, index)
+          chars = 0
+          cols = 0
+          while index < clusters.size && cols + clusters[index][:width] <= @width
+            chars += clusters[index][:text].length
+            cols += clusters[index][:width]
+            index += 1
+          end
+          if chars.zero? && index < clusters.size
+            chars = clusters[index][:text].length
+            cols = clusters[index][:width]
+            index += 1
+          end
+          [chars, cols, index]
+        end
+
+        # Trims trailing space/tab characters off a row's visible length so the
+        # whitespace at a soft-wrap point is absorbed (not rendered) rather than
+        # left at the end of the row. Without this, soft-wrapping `"foo bar"`
+        # to width 4 would yield row 0 length 4 (`"foo "`) and the natural
+        # end-of-row caret position would coincide with row 1's start.
+        #
+        # Both counts drop by one per trimmed character: a space and a tab each
+        # measure exactly one column.
+        # @param row_start [Integer]
+        # @param row_chars [Integer]
+        # @param row_cols [Integer]
+        # @return [Array(Integer, Integer)] `[row_chars, row_cols]`
+        def trim_trailing_whitespace(row_start, row_chars, row_cols)
+          while row_chars.positive? && @text[row_start + row_chars - 1].match?(/[ \t]/)
+            row_chars -= 1
+            row_cols -= 1
+          end
+          [row_chars, row_cols]
+        end
+
+        # @param row [Row]
+        # @param index [Integer]
+        # @return [Integer] `index`'s column offset within `row`.
+        def column_in(row, index)
+          chars = (index - row.start).clamp(0, row.length)
+          columns_of(@text[row.start, chars] || "").clamp(0, row.columns)
+        end
+
+        # @param row [Row]
+        # @param column [Integer]
+        # @return [Integer] characters from the row's start.
+        def chars_for_column(row, column)
+          chars = 0
+          col = 0
+          glyphs_of(row).each_grapheme_cluster do |g|
+            w = Buffer.display_width(g)
+            return chars if column < col + ((w + 1) / 2)
+
+            col += w
+            chars += g.length
+          end
+          chars
+        end
+
+        # @param row [Row]
+        # @return [String] the row's visible characters.
+        def glyphs_of(row) = @text[row.start, row.length] || ""
+
+        # Mirrors {AbstractStringField}'s measurement primitive, which this class
+        # can't inherit. Per-cluster rather than whole-string so a multi-codepoint
+        # emoji measures as the one glyph a terminal draws.
+        # @param str [String]
+        # @return [Integer] columns.
+        def columns_of(str) = str.each_grapheme_cluster.sum { |g| Buffer.display_width(g) }
+      end
+    end
+  end
+end