tuile 0.9.0 → 0.10.0

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]

data/lib/tuile/component/text_field.rb

@@ -2,23 +2,76 @@
 
 module Tuile
   class Component
-    # A single-line text input field with hardware-cursor caret.
+    # A single-line text input with a real hardware caret, scrolling
+    # horizontally to keep that caret in view:
     #
-    # The field does not scroll. Any keystroke that would make {#text} longer
-    # than `rect.width - 1` (the last column is reserved for the caret past the
-    # last char) is rejected.
+    #   f = TextField.new
+    #   f.rect  = Rect.new(0, 0, 6, 1)   # six columns wide …
+    #   f.text  = "hello world"          # … eleven columns of text, so it scrolls
+    #   f.caret = 11                     # paints "world " — left_column 6, cursor on the last column
+    #   f.caret = 0                      # paints "hello " — left_column 0
     #
-    # The caret is a logical index in `0..text.length`. The hardware cursor is
-    # positioned by {Screen} after each repaint cycle when this component is
-    # focused; see {Component#cursor_position}.
-    class TextField < TextInput
+    # The field's width never bounds its contents — {#max_text_length} does, and
+    # only for typing.
+    #
+    # == Implementation details
+    #
+    # Two axes run through this class and are *not* interchangeable:
+    #
+    # - an **index** counts characters into {#text} — {#caret},
+    #   {#max_text_length}, `text[i]`, every edit;
+    # - a **column** counts terminal cells — {#rect}, {#left_column},
+    #   {#cursor_position}, a {MouseEvent}.
+    #
+    # They coincide only while every glyph is one column wide. A fullwidth CJK
+    # char is two columns and a combining mark zero, so index 3 of `"日本語"` is
+    # column 6. Every crossing goes through the private `column_at` / `index_at`
+    # pair; adding an index to a column anywhere else is the bug those two exist
+    # to prevent.
+    #
+    # Indices count characters while widths measure grapheme clusters, but the
+    # caret never falls between the two: {AbstractStringField} keeps it on a
+    # cluster boundary, so a column derived from it always names a real glyph
+    # edge.
+    #
+    # What gets *painted* is {#display_text}, a third seam that is `text` itself
+    # here and the mask in {PasswordField}. Every column measurement reads it, so
+    # a subclass showing something else overrides that and never {#repaint} —
+    # overriding the paint alone leaves the measurements on the buffer while the
+    # cells show the substitute, and the two drift apart by a growing offset.
+    class TextField < AbstractStringField
       def initialize
         super
+        @left_column = 0
+        @max_text_length = nil
         @on_key_up = nil
         @on_key_down = nil
         @on_enter = nil
       end
 
+      # Optional cap on {#text}'s length **in characters** — a wide glyph counts
+      # once. Typing into a field already at the cap does nothing.
+      #
+      # Deliberately does not police {#text=}: lowering the cap under an existing
+      # value leaves that value intact rather than silently trimming it.
+      # @return [Integer, nil] maximum characters, or nil for unbounded (default).
+      attr_reader :max_text_length
+
+      # @param max [Integer, nil]
+      # @return [void]
+      # @raise [TypeError] unless `max` is an Integer or nil.
+      # @raise [ArgumentError] if `max` is negative.
+      def max_text_length=(max)
+        raise TypeError, "expected Integer or nil, got #{max.inspect}" unless max.nil? || max.is_a?(Integer)
+        raise ArgumentError, "expected a non-negative max, got #{max}" if max&.negative?
+
+        @max_text_length = max
+      end
+
+      # @return [Integer] text column drawn in the field's leftmost cell — the
+      #   horizontal scroll offset. Follows {#caret}, always on a glyph boundary.
+      attr_reader :left_column
+
       # Optional callback fired when the UP arrow key is pressed. When set, UP
       # is consumed by the field; when nil, UP falls through to the parent
       # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
@@ -43,37 +96,33 @@ module Tuile
       def cursor_position
         return nil unless rect.width.positive?
 
-        Point.new(rect.left + @caret, rect.top)
+        # Scrolling already keeps the caret inside the rect, so the cap is a
+        # guard rather than a policy: a cursor parked at rect.left + rect.width
+        # reads as column 0 of the next row on an auto-wrapping terminal.
+        offset = (column_at(@caret) - @left_column).clamp(0, rect.width - 1)
+        Point.new(rect.left + offset, rect.top)
       end
 
+      # Places the caret at the clicked column. A click on the right half of a
+      # wide glyph lands *after* it, as in any editor.
       # @param event [MouseEvent]
       # @return [void]
       def handle_mouse(event)
         super
         return unless event.button == :left && rect.contains?(event.point)
 
-        self.caret = (event.x - rect.left).clamp(0, @text.length)
+        self.caret = index_at(event.x - rect.left + @left_column)
       end
 
       # @return [void]
       def repaint
         return if rect.empty?
 
-        padded = @text + (" " * (rect.width - @text.length))
-        screen.buffer.set_line(rect.left, rect.top, background(padded))
+        screen.buffer.set_line(rect.left, rect.top, background(visible_text))
       end
 
       protected
 
-      # Truncate to fit `rect.width - 1` — single-line fields can't grow past
-      # their width.
-      # @param new_text [String]
-      # @return [String]
-      def preprocess_text(new_text)
-        new_text = new_text.to_s
-        new_text.length > max_text_length ? new_text[0, max_text_length] : new_text
-      end
-
       # @param key [String]
       # @return [Boolean]
       def handle_text_input_key(key)
@@ -102,32 +151,121 @@ module Tuile
         true
       end
 
+      # @return [void]
+      def on_text_mutated
+        adjust_left_column
+      end
+
+      # @return [void]
+      def on_caret_mutated
+        adjust_left_column
+      end
+
       # @return [void]
       def on_width_changed
         super
-        return if @text.length <= max_text_length
-
-        @text = @text[0, [max_text_length, 0].max]
-        @caret = @caret.clamp(0, @text.length)
-        @on_change&.call(@text)
+        adjust_left_column
       end
 
-      private
+      # What the field paints in place of {#text}: one display character per
+      # {#text} character, in order. `column_at` measures `display_text[0, i]` as
+      # the rendering of `text[0, i]`, so an override that changes the character
+      # count — or reorders — desynchronizes the caret from the display. Nothing
+      # enforces it at runtime; a subclass pins it with a spec.
+      # @return [String] {#text} itself, unless a subclass substitutes.
+      def display_text = @text
 
-      # Maximum number of characters {#text} can hold given current width.
-      # @return [Integer]
-      def max_text_length = (rect.width - 1).clamp(0, nil)
+      private
 
       # @param char [String]
-      # @return [Boolean]
+      # @return [Boolean] always true — a field at {#max_text_length} swallows the
+      #   key rather than declining it, so typing can never fall through to a
+      #   scope-wide binding.
       def insert(char)
-        return false if @text.length >= max_text_length
+        return true if @max_text_length && @text.length >= @max_text_length
 
         new_text = @text.dup.insert(@caret, char)
         @caret += 1
         self.text = new_text
         true
       end
+
+      # @param index [Integer] a {#text} index in `0..text.length`.
+      # @return [Integer] the column it sits at. An index landing inside a
+      #   grapheme cluster measures the whole cluster, putting the caret just
+      #   past it.
+      def column_at(index) = columns_of(display_text[0, index] || "")
+
+      # @param column [Integer] a text column (0 is the first glyph).
+      # @return [Integer] the nearest {#text} index — a column falling in a wide
+      #   glyph's right half resolves past it.
+      def index_at(column)
+        col = 0
+        i = 0
+        display_text.each_grapheme_cluster do |g|
+          w = Buffer.display_width(g)
+          return i if column < col + ((w + 1) / 2)
+
+          col += w
+          i += g.length
+        end
+        i
+      end
+
+      # @return [Integer] total display width of {#text}.
+      def text_columns = column_at(@text.length)
+
+      # @return [String] the windowed text, padded with spaces to `rect.width`.
+      #   A wide glyph straddling the right edge is dropped rather than painted
+      #   as a half glyph.
+      def visible_text
+        right = @left_column + rect.width
+        visible = +""
+        width = 0
+        col = 0
+        display_text.each_grapheme_cluster do |g|
+          start = col
+          col += Buffer.display_width(g)
+          next if start < @left_column
+          break if col > right
+
+          visible << g
+          width = col - @left_column
+        end
+        visible << (" " * (rect.width - width))
+      end
+
+      # Scrolls the minimum needed to keep the caret's column visible.
+      # @return [void]
+      def adjust_left_column
+        return unless rect.width.positive?
+
+        col = column_at(@caret)
+        @left_column = col if col < @left_column
+        @left_column = col - rect.width + 1 if col > @left_column + rect.width - 1
+        # The caret may park one column past the last glyph, so the scrollable
+        # range runs one column past the text.
+        @left_column = snap_to_glyph_start(@left_column.clamp(0, [text_columns - rect.width + 1, 0].max))
+      end
+
+      # @param column [Integer]
+      # @return [Integer] the smallest glyph-boundary column `>= column`, so the
+      #   window never opens on a wide glyph's right half.
+      #
+      # Snapping *right* is the only safe direction, and not because it shows
+      # more: the caret's own column is always a glyph boundary, so the next
+      # boundary at or after `left_column` can never overshoot it. Snapping left
+      # instead pulls the window's right edge inward, which strands the caret
+      # outside it whenever wide glyphs exactly fill a narrow field.
+      def snap_to_glyph_start(column)
+        col = 0
+        display_text.each_grapheme_cluster do |g|
+          return col if col >= column
+
+          col += Buffer.display_width(g)
+        end
+        col
+      end
     end
   end
 end