tuile 0.11.0 → 0.13.0

data/lib/tuile/component/text_area.rb

@@ -6,7 +6,7 @@ module Tuile
     #
     # Sized by the caller — {#rect} is fixed; the area does not grow with
     # content. Text is wrapped to {Rect#width} columns and any text that
-    # doesn't fit vertically is reached by scrolling: {#top_display_row}
+    # doesn't fit vertically is reached by scrolling: {#scroll_top_row}
     # follows the caret so the line being edited stays visible. There is no
     # horizontal scrolling.
     #
@@ -17,54 +17,75 @@ module Tuile
     # start of the next row in nearly all cases).
     #
     # 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.
+    # {#on_change} is wired. {Keys::CTRL_J} does the same, since that is the
+    # byte a terminal sends for a typed Ctrl+J. A *pasted* line break arrives
+    # through {AbstractStringField#handle_paste} instead and never as a key at
+    # all — so a subclass rebinding Enter to submit keeps working under a
+    # multi-line paste, which lands as one draft.
     #
-    # == Implementation details
+    # Up/Down move the caret between rows and, at the first/last row, snap to
+    # the start/end of the text. A subclass can claim the key at that edge
+    # instead — shell-style history recall is the motivating case — by asking
+    # {#caret_row} and {#row_count} before delegating:
+    #
+    #   class PromptArea < Component::TextArea
+    #     protected
+    #
+    #     def handle_text_input_key(key)
+    #       return recall_previous if key == Keys::UP_ARROW && caret_row.zero?
+    #       return recall_next if key == Keys::DOWN_ARROW && caret_row == row_count - 1
+    #
+    #       super # anywhere else: the caret moves, and the edge still snaps
+    #     end
+    #   end
     #
-    # 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`.
+    # Both recalls return `true` to consume the key; app code that would rather
+    # not subclass claims the same keys through {AbstractStringField#on_key}.
     #
-    # 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.
+    # == Implementation details
+    #
+    # The wrap itself — and with it every conversion between a character
+    # **index** and a **row/column** — lives in {WrappedText}, a
+    # snapshot of `(text, rect.width)` this class caches and drops whenever
+    # either changes. What stays here is the widget: keys, mouse, painting, and
+    # the {#scroll_top_row} viewport, which {WrappedText} deliberately knows
+    # nothing about (it is a pure function of text and width; the viewport is
+    # stateful and needs {Rect#height}).
     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>, 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
+        @scroll_top_row = 0
+        # Lazy cache; nil means "stale, rebuild on next read". Reset whenever
+        # {#text} mutates or the width changes.
+        @wrap = nil
       end
 
-      # @return [Integer] index of the topmost display row currently visible.
-      attr_reader :top_display_row
+      # @return [Integer] index of the topmost row currently visible.
+      attr_reader :scroll_top_row
+
+      # The caret's row, counted from the text's first row — *not* from the top
+      # of the viewport (subtract {#scroll_top_row} for that).
+      # @return [Integer] a row index in `0...row_count`.
+      def caret_row = wrap.row_at(@caret)
+
+      # @return [Integer] rows the wrapped text occupies at the current
+      #   {Rect#width}; always `>= 1`, since empty text still wraps to one
+      #   (empty) row.
+      def row_count = wrap.row_count
 
       # @return [Point, nil]
       def cursor_position
         return nil if rect.empty?
 
-        row, col = caret_to_display(@caret)
-        screen_row = row - @top_display_row
-        return nil if screen_row.negative? || screen_row >= rect.height
+        row, col = wrap.position_at(@caret)
+        row_in_viewport = row - @scroll_top_row
+        return nil if row_in_viewport.negative? || row_in_viewport >= rect.height
 
         # Cap so the hardware cursor never lands at rect.left+rect.width
         # (one past the rect). Terminals with auto-wrap interpret that as
         # column 0 of the row below; capping pins the cursor on the last
         # visible cell instead.
-        Point.new(rect.left + col.clamp(0, rect.width - 1), rect.top + screen_row)
+        Point.new(rect.left + col.clamp(0, rect.width - 1), rect.top + row_in_viewport)
       end
 
       # @param event [MouseEvent]
@@ -73,26 +94,21 @@ module Tuile
         super
         return unless event.button == :left && rect.contains?(event.point)
 
-        target_row = (event.y - rect.top) + @top_display_row
-        target_col = event.x - rect.left
-        rows = display_rows
-        if target_row >= rows.size
-          self.caret = @text.length
-        else
-          r = rows[target_row]
-          self.caret = r[:start] + chars_for_column(r, target_col)
-        end
+        target_row = (event.y - rect.top) + @scroll_top_row
+        self.caret = if target_row >= wrap.row_count
+                       @text.length
+                     else
+                       wrap.index_at(target_row, event.x - rect.left)
+                     end
       end
 
       # @return [void]
       def repaint
         return if rect.empty?
 
-        rows = display_rows
-        (0...rect.height).each do |screen_row|
-          row_idx = screen_row + @top_display_row
-          line = row_idx >= rows.size ? " " * rect.width : padded_row(rows[row_idx])
-          screen.buffer.set_line(rect.left, rect.top + screen_row, background(line))
+        (0...rect.height).each do |row_in_viewport|
+          line = wrap.row_text(row_in_viewport + @scroll_top_row)
+          screen.buffer.set_text(rect.left, rect.top + row_in_viewport, background(line))
         end
       end
 
@@ -100,13 +116,13 @@ module Tuile
 
       # @return [void]
       def on_text_mutated
-        @display_rows = nil
-        adjust_top_display_row
+        @wrap = nil
+        adjust_scroll_top_row
       end
 
       # @return [void]
       def on_caret_mutated
-        adjust_top_display_row
+        adjust_scroll_top_row
       end
 
       # @param key [String]
@@ -131,248 +147,40 @@ module Tuile
       # @return [void]
       def on_width_changed
         super
-        @display_rows = nil
-        adjust_top_display_row
+        @wrap = nil
+        adjust_scroll_top_row
       end
 
       private
 
-      # @return [Array<Hash{Symbol=>Integer}>] cached wrap of {#text} for the
-      #   current {Rect#width}. Each entry is `{start:, length:}`.
-      def display_rows
-        @display_rows ||= compute_display_rows
-      end
-
-      # @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, columns: 0 }] 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, width)
-                break
-              else
-                chars, cols = trim_trailing_whitespace(start, chars, cols)
-                break
-              end
-            end
-          end
-
-          rows << { start: start, length: chars, columns: cols }
-
-          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, 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]
-      # @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]
-      # @return [Array(Integer, Integer)] `[row_index, column]` for `caret`.
-      def caret_to_display(caret)
-        rows = display_rows
-        rows.each_with_index do |r, i|
-          next_start = i + 1 < rows.size ? rows[i + 1][:start] : @text.length + 1
-          next unless caret >= r[:start] && caret < next_start
-
-          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
-        out << (" " * (rect.width - cols))
+      # @return [WrappedText] the current wrap of {#text} at {Rect#width}.
+      def wrap
+        @wrap ||= WrappedText.new(@text, rect.width)
       end
 
       # @param delta [Integer] `+1` for down, `-1` for up.
       # @return [void]
       def move_caret_vertical(delta)
-        rows = display_rows
-        cur_row, cur_col = caret_to_display(@caret)
-        new_row = (cur_row + delta).clamp(0, rows.size - 1)
+        cur_row, cur_col = wrap.position_at(@caret)
+        new_row = (cur_row + delta).clamp(0, wrap.row_count - 1)
         if new_row == cur_row
-          # Already at the top/bottom display row. Snap to the absolute
-          # start/end of the text so the user has a quick way to reach it.
+          # Already at the top/bottom row. Snap to the absolute start/end of the
+          # text so the user has a quick way to reach it.
           self.caret = delta.positive? ? @text.length : 0
           return
         end
 
-        r = rows[new_row]
-        self.caret = r[:start] + chars_for_column(r, cur_col)
+        self.caret = wrap.index_at(new_row, cur_col)
       end
 
       # @return [void]
       def move_caret_to_row_start
-        rows = display_rows
-        cur_row, = caret_to_display(@caret)
-        self.caret = rows[cur_row][:start]
+        self.caret = wrap.row_start(wrap.row_at(@caret))
       end
 
       # @return [void]
       def move_caret_to_row_end
-        rows = display_rows
-        cur_row, = caret_to_display(@caret)
-        r = rows[cur_row]
-        self.caret = r[:start] + r[:length]
+        self.caret = wrap.row_end(wrap.row_at(@caret))
       end
 
       # @param char [String]
@@ -386,18 +194,17 @@ module Tuile
 
       # Keeps the caret visible by scrolling vertically.
       # @return [void]
-      def adjust_top_display_row
+      def adjust_scroll_top_row
         return if rect.empty?
 
-        rows = display_rows
-        cur_row, = caret_to_display(@caret)
-        if cur_row < @top_display_row
-          @top_display_row = cur_row
-        elsif cur_row >= @top_display_row + rect.height
-          @top_display_row = cur_row - rect.height + 1
+        cur_row = wrap.row_at(@caret)
+        if cur_row < @scroll_top_row
+          @scroll_top_row = cur_row
+        elsif cur_row >= @scroll_top_row + rect.height
+          @scroll_top_row = cur_row - rect.height + 1
         end
-        max_top = (rows.size - rect.height).clamp(0, nil)
-        @top_display_row = @top_display_row.clamp(0, max_top)
+        max_top = (wrap.row_count - rect.height).clamp(0, nil)
+        @scroll_top_row = @scroll_top_row.clamp(0, max_top)
       end
     end
   end

data/lib/tuile/component/text_field.rb

@@ -20,8 +20,8 @@ module Tuile
     #
     # - 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}.
+    # - a **column** counts terminal cells — {#rect}, {#cursor_position}, a
+    #   {MouseEvent}, and the private horizontal scroll offset `left_column`.
     #
     # 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
@@ -68,10 +68,6 @@ module Tuile
         @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`,
@@ -118,7 +114,7 @@ module Tuile
       def repaint
         return if rect.empty?
 
-        screen.buffer.set_line(rect.left, rect.top, background(visible_text))
+        screen.buffer.set_text(rect.left, rect.top, background(visible_text))
       end
 
       protected
@@ -151,6 +147,19 @@ module Tuile
         true
       end
 
+      # Flattens the paste onto the field's one row — newlines become spaces —
+      # and trims it to what {#max_text_length} still allows. Trimming rather
+      # than rejecting: a paste that overshoots the cap fills the field, which
+      # is what typing the same characters would have done.
+      # @param text [String]
+      # @return [String]
+      def preprocess_paste(text)
+        flat = super.tr("\n", " ")
+        return flat if @max_text_length.nil?
+
+        flat[0, [@max_text_length - @text.length, 0].max] || ""
+      end
+
       # @return [void]
       def on_text_mutated
         adjust_left_column
@@ -235,6 +244,14 @@ module Tuile
         visible << (" " * (rect.width - width))
       end
 
+      # Internal — the field's own scroll state, with no caller outside this
+      # class: the paint, the cursor and the hit test all read the ivar, and
+      # nothing above the field has a column to spend it on. Specs assert the
+      # scrolling through `send`.
+      # @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
+
       # Scrolls the minimum needed to keep the caret's column visible.
       # @return [void]
       def adjust_left_column