tuile 0.9.0 → 0.11.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.on_item_chosen = ->(index, _line) { commit(index) }
+      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_line(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.lines = @items.map { |item| label_for(item) }
+        @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 item on row `index` as {#value} and closes the dropdown.
+      # @param index [Integer]
+      # @return [void]
+      def commit(index)
+        item = @items[index]
+        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.rb

@@ -10,24 +10,42 @@ module Tuile
     # follows the caret so the line being edited stays visible. There is no
     # horizontal scrolling.
     #
-    # The caret is a logical index in `0..text.length`. When the caret falls
+    # The caret is a logical index in `0..text.length`, always on a
+    # grapheme-cluster boundary ({AbstractStringField}). When the caret falls
     # inside a whitespace run that was absorbed by a soft wrap, it displays
     # at the end of the previous row (which is visually identical to the
     # start of the next row in nearly all cases).
     #
-    # Currently only {#on_change} is wired; Enter inserts a newline as in any
-    # plain `<textarea>` or text editor. A future `on_enter`/`on_submit`
-    # callback may opt out of that by consuming Enter instead.
-    class TextArea < TextInput
+    # Enter inserts a newline, as in a plain `<textarea>` or text editor; only
+    # {#on_change} is wired. A pasted line break arrives as `\n`
+    # ({Keys::CTRL_J}) rather than the `\r` a typed Enter sends, so both are
+    # accepted — otherwise a multi-line paste would silently lose its
+    # newlines.
+    #
+    # == Implementation details
+    #
+    # The same two axes {TextField} names apply, and the wrap straddles both: an
+    # **index** counts characters into {#text} ({#caret}, a row's `start` and
+    # `length`), a **column** counts terminal cells ({#rect}, a row's `columns`,
+    # {#cursor_position}, a {MouseEvent}). A row therefore carries *both* counts,
+    # and the wrap fills each row to a column budget while recording a character
+    # span. Everything crossing between them goes through the inherited
+    # `columns_of` and the private `chars_for_column`.
+    #
+    # 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.
+    class TextArea < AbstractStringField
       def initialize
         super
         @top_display_row = 0
         # Lazy cache of the word-wrapped layout: an
         # `Array<Hash{Symbol=>Integer}>` whose entries are
-        # `{start: <text-index>, length: <chars>}`, one per display row, built
-        # by {#compute_display_rows}. `nil` means "stale, recompute on next
-        # read". Reset to nil whenever {#text} mutates or the width changes;
-        # see {#on_text_mutated} and {#on_width_changed}.
+        # `{start: <text-index>, length: <chars>, columns: <cols>}`, one per
+        # display row, built by {#compute_display_rows}. `nil` means "stale,
+        # recompute on next read". Reset to nil whenever {#text} mutates or the
+        # width changes; see {#on_text_mutated} and {#on_width_changed}.
         @display_rows = nil
       end
 
@@ -62,7 +80,7 @@ module Tuile
           self.caret = @text.length
         else
           r = rows[target_row]
-          self.caret = r[:start] + target_col.clamp(0, r[:length])
+          self.caret = r[:start] + chars_for_column(r, target_col)
         end
       end
 
@@ -73,13 +91,7 @@ module Tuile
         rows = display_rows
         (0...rect.height).each do |screen_row|
           row_idx = screen_row + @top_display_row
-          line = if row_idx >= rows.size
-                   " " * rect.width
-                 else
-                   r = rows[row_idx]
-                   chunk = @text[r[:start], r[:length]] || ""
-                   chunk + (" " * (rect.width - r[:length]))
-                 end
+          line = row_idx >= rows.size ? " " * rect.width : padded_row(rows[row_idx])
           screen.buffer.set_line(rect.left, rect.top + screen_row, background(line))
         end
       end
@@ -107,7 +119,7 @@ module Tuile
         when *Keys::ENDS_ then move_caret_to_row_end
         when *Keys::BACKSPACES then delete_before_caret
         when Keys::DELETE then delete_at_caret
-        when Keys::ENTER then insert_char("\n")
+        when Keys::ENTER, Keys::CTRL_J then insert_char("\n")
         else
           return insert_char(key) if Keys.printable?(key)
 
@@ -131,78 +143,149 @@ module Tuile
         @display_rows ||= compute_display_rows
       end
 
-      # Greedy word-wrap. Whitespace at a soft-wrap break point is absorbed
-      # (not rendered on either row). A token longer than {Rect#width} hard-
-      # wraps inside the token. Newlines force a hard break and the wrap
-      # restarts on the next character.
+      # @return [Array<Hash{Symbol=>Object}>] one entry per grapheme cluster of
+      #   {#text}: `{offset: <text-index>, text: <cluster>, width: <columns>}`.
+      #   Rebuilt per wrap and discarded — the wrap is what's cached.
+      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
+      # {Rect#width} hard-wraps inside the token. Newlines force a hard break and
+      # the wrap restarts on the next cluster.
       # @return [Array<Hash{Symbol=>Integer}>]
       def compute_display_rows
         width = rect.width
-        return [{ start: 0, length: 0 }] if width <= 0 || @text.empty?
+        return [{ start: 0, length: 0, columns: 0 }] if width <= 0 || @text.empty?
 
+        cl = cluster_table
         rows = []
-        pos = 0
-        n = @text.length
-
-        while pos < n
-          row_start = pos
-          row_chars = 0
-
-          while pos < n
-            c = @text[pos]
-            break if c == "\n"
-
-            if c.match?(/[ \t]/)
-              if row_chars < width
-                row_chars += 1
-                pos += 1
+        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
-                row_chars = trim_trailing_whitespace(row_start, row_chars)
-                pos += 1 while pos < n && @text[pos].match?(/[ \t]/)
+                chars, cols = trim_trailing_whitespace(start, chars, cols)
+                i += 1 while i < n && blank?(cl[i])
                 break
               end
             else
-              word_end = pos
-              word_end += 1 while word_end < n && !@text[word_end].match?(/\s/)
-              word_len = word_end - pos
-
-              if row_chars + word_len <= width
-                row_chars += word_len
-                pos = word_end
-              elsif row_chars.zero?
-                row_chars = width
-                pos += width
+              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, width)
                 break
               else
-                row_chars = trim_trailing_whitespace(row_start, row_chars)
+                chars, cols = trim_trailing_whitespace(start, chars, cols)
                 break
               end
             end
           end
 
-          rows << { start: row_start, length: row_chars }
+          rows << { start: start, length: chars, columns: cols }
 
-          if pos < n && @text[pos] == "\n"
-            pos += 1
-            rows << { start: pos, length: 0 } if pos == n
-          end
+          next unless i < n && newline?(cl[i])
+
+          i += 1
+          rows << { start: @text.length, length: 0, columns: 0 } if i >= n
         end
 
-        rows << { start: 0, length: 0 } if rows.empty?
+        rows << { start: 0, length: 0, columns: 0 } if rows.empty?
         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 the rect holds and {#padded_row} 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]
+      # @param width [Integer] column budget.
+      # @return [Array(Integer, Integer, Integer)] `[chars, columns, next_index]`
+      def hard_wrap(clusters, index, width)
+        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]
-      # @return [Integer] new row_chars.
-      def trim_trailing_whitespace(row_start, row_chars)
-        row_chars -= 1 while row_chars.positive? && @text[row_start + row_chars - 1].match?(/[ \t]/)
-        row_chars
+      # @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 caret [Integer]
@@ -213,10 +296,51 @@ module Tuile
           next_start = i + 1 < rows.size ? rows[i + 1][:start] : @text.length + 1
           next unless caret >= r[:start] && caret < next_start
 
-          return [i, (caret - r[:start]).clamp(0, r[:length])]
+          return [i, caret_column_in(r, caret)]
+        end
+        [rows.size - 1, caret_column_in(rows.last, caret)]
+      end
+
+      # @param row [Hash{Symbol=>Integer}]
+      # @param caret [Integer]
+      # @return [Integer] `caret`'s column offset within `row`.
+      def caret_column_in(row, caret)
+        chars = (caret - row[:start]).clamp(0, row[:length])
+        columns_of(@text[row[:start], chars] || "").clamp(0, row[:columns])
+      end
+
+      # @param row [Hash{Symbol=>Integer}]
+      # @param column [Integer] a column offset within `row`.
+      # @return [Integer] characters from the row's start. A column landing in a
+      #   wide glyph's right half resolves past it, as a click does in
+      #   {TextField}.
+      def chars_for_column(row, column)
+        chars = 0
+        col = 0
+        (@text[row[:start], row[:length]] || "").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 [Hash{Symbol=>Integer}]
+      # @return [String] the row's text padded to `rect.width` columns. A glyph
+      #   with no room left is dropped rather than half-painted.
+      def padded_row(row)
+        out = +""
+        cols = 0
+        (@text[row[:start], row[:length]] || "").each_grapheme_cluster do |g|
+          w = Buffer.display_width(g)
+          break if cols + w > rect.width
+
+          out << g
+          cols += w
         end
-        r = rows.last
-        [rows.size - 1, (caret - r[:start]).clamp(0, r[:length])]
+        out << (" " * (rect.width - cols))
       end
 
       # @param delta [Integer] `+1` for down, `-1` for up.
@@ -233,7 +357,7 @@ module Tuile
         end
 
         r = rows[new_row]
-        self.caret = r[:start] + cur_col.clamp(0, r[:length])
+        self.caret = r[:start] + chars_for_column(r, cur_col)
       end
 
       # @return [void]