tuile 0.9.0 → 0.10.0

data/ideas/per-component-buffers.md

@@ -0,0 +1,55 @@
+# Per-component back buffers + a z-order compositor
+
+**Status:** deferred, not worth doing yet. Graduated out of `Buffer`'s
+rdoc (it was speculative design musing, not caller contract — see the
+doc-kinds rules in AGENTS.md). Parked here so the thinking isn't lost.
+
+## The idea
+
+Today there is one global {Tuile::Buffer}: every component paints into
+the same grid via `set_line` / `set_char` / `fill`, and {Tuile::Screen}
+flushes its minimal diff to the terminal.
+
+Components already paint through that drawing surface *without knowing*
+whether it's the one global buffer or a private one — the indirection is
+deliberate. So per-component back buffers plus a z-order compositor could
+drop in **without touching component code**: give each component its own
+`Buffer`, let it paint into that, and have a compositor blend the
+per-component buffers in stacking order into the frame the terminal sees.
+
+## Why it's not worth doing yet
+
+The current single-buffer diff already captures most of the win a
+compositor would give:
+
+- The flush drops unchanged cells from the wire, so an unchanged region
+  costs nothing on the terminal side regardless of how many components
+  overlap it.
+- An occluded component that didn't change is never repainted at all —
+  invalidation gates it out before `repaint` runs.
+
+So a compositor would only save **residual `repaint` CPU**: the cost of a
+component re-rendering its content into a buffer, when that content then
+turns out to be occluded or unchanged after compositing.
+
+## The one regime where it pays off
+
+High repeat-rate scroll — a held arrow key or a spun mouse wheel — over a
+**large** component on a **large** screen, where re-rendering the
+component's content on every repeat is the dominant cost. A per-component
+buffer would let an unchanged-but-scrolled component be re-composited
+(cheap) instead of re-rendered (expensive) each repeat.
+
+Until Tuile has a real workload in that regime, the extra machinery
+(per-component buffer allocation, a compositor pass, dirty propagation
+across buffer layers) buys nothing over what the single-buffer diff
+already delivers.
+
+## If we revisit
+
+- The component-facing drawing API (`set_line` / `set_char` / `fill`)
+  stays the same — that's the whole point of the existing indirection.
+- What changes is *who owns the buffer* and the addition of a
+  composite-into-frame step between `repaint` and `Buffer#flush`.
+- Measure first: prove the residual-`repaint`-CPU regime is real and
+  material before adding a layer.

data/lib/tuile/buffer.rb

@@ -21,17 +21,10 @@ module Tuile
   # size. There is deliberately no per-frame whole-buffer clear or copy;
   # un-touched cells retain the previous frame's value.
   #
-  # The bookkeeping avoids hashing and full-grid scans: a dirty flag **on each
-  # cell** (O(1) set, no `Set` bucket math, no separate array), a per-row
-  # boolean so {#flush} scans only the rows that changed, and one global flag
-  # so {#dirty?} and the "nothing changed" early-out are O(1). {#flush} clears
-  # every flag it consumes.
-  #
-  # Cells are **mutable and pre-allocated**: the grid builds its {Cell}s once
+  # Cells are **mutable and pre-allocated** — the grid builds its {Cell}s once
   # (at construction and {#resize}) and rewrites them in place, so a normal
-  # paint allocates nothing per cell. That is why {Cell} is a plain mutable
-  # object rather than a frozen value type. The empty state of a cell is a
-  # space in the default style.
+  # paint allocates nothing per cell. That's why {Cell} is a plain mutable
+  # object, not a frozen value type.
   #
   # ## Wide characters
   #
@@ -40,19 +33,6 @@ module Tuile
   # nothing for, since the glyph itself advances the cursor two columns).
   # Overwriting either half of a wide glyph blanks the orphaned half, so the
   # grid never holds a dangling continuation or a headless one.
-  #
-  # ## Future direction
-  #
-  # Components paint through this drawing surface ({#set_line} / {#set_char})
-  # without knowing whether it is the one global buffer or a private one — that
-  # indirection is deliberate, so per-component back buffers plus a z-order
-  # compositor could drop in without touching component code. It is not worth
-  # doing yet: the diff already drops unchanged cells from the wire, and an
-  # occluded component that didn't change is never repainted at all, so a
-  # compositor would only save residual `repaint` CPU. It pays off in exactly
-  # one regime — high repeat-rate scroll (held arrow / mouse wheel) of a large
-  # component on a large screen, where re-rendering the content each repeat is
-  # the dominant cost.
   class Buffer
     # One screen cell: a single grapheme cluster, the {StyledString::Style} it's
     # drawn in, and a dirty flag. Mutable by design (see {Buffer} "Dirty
@@ -118,10 +98,15 @@ module Tuile
     # emoji), so the per-grapheme width lookup — the dominant cost of a repaint
     # (see `benchmark/display_width.rb`) — collapses to a Hash read after the
     # first sighting. Shared across all buffers and unbounded, but bounded in
-    # practice by the font's glyph set; safe to share because all painting runs
-    # on the single UI thread (see AGENTS.md "Threading rule").
+    # practice by the font's glyph set.
+    #
+    # The memo carries its weight most for emoji: resolving a sequence under
+    # {StyledString::EMOJI_WIDTH} costs ~20x a plain lookup, and this pays it
+    # once per distinct cluster. Racing writes from a non-UI thread are benign
+    # rather than merely absent — the value for a grapheme is deterministic, so
+    # a lost write only costs a recomputation.
     # @return [Hash{String => Integer}]
-    WIDTH_CACHE = Hash.new { |h, g| h[g] = Unicode::DisplayWidth.of(g) }
+    WIDTH_CACHE = Hash.new { |h, g| h[g] = Unicode::DisplayWidth.of(g, emoji: StyledString::EMOJI_WIDTH) }
     private_constant :WIDTH_CACHE
 
     # Memoized {Unicode::DisplayWidth.of}. Use this for every paint-path width
@@ -174,9 +159,8 @@ module Tuile
     end
 
     # Writes a {StyledString} starting at `(x, y)`, advancing by each grapheme's
-    # display width and clipping at the right edge. The workhorse that replaces
-    # the old `screen.print(TTY::Cursor.move_to(x, y), styled.to_ansi)` per-row
-    # paint. Newlines in the string are not handled — pass one physical line.
+    # display width and clipping at the right edge. Newlines are not handled —
+    # pass one physical line.
     # @param x [Integer] starting column.
     # @param y [Integer] row.
     # @param styled [StyledString]
@@ -346,21 +330,27 @@ module Tuile
       return unless in_bounds?(x, y)
       return if w <= 0
 
-      if w == 2 && !in_bounds?(x + 1, y)
+      if w > 1 && !in_bounds?(x + w - 1, y)
         blank_left_partner(x, y)
         return write_cell(x, y, " ", style)
       end
 
-      # Repair only the glyphs we'd leave half-overwritten on our flanks: a wide
-      # glyph whose right half sits at `x`, or one whose left half sits at the
-      # last cell we write. The cells we fully rewrite need no pre-blanking —
-      # pre-blanking the continuation only to re-empty it would churn it
-      # spuriously dirty, which misplaces the next flush onto the glyph's right
-      # half (see bug/, balloon corruption).
+      # Repair only the glyphs we'd leave half-overwritten on our flanks: one
+      # whose tail reaches `x`, or one whose head sits at the last cell we write.
+      # The cells we fully rewrite need no pre-blanking — pre-blanking a
+      # continuation only to re-empty it would churn it spuriously dirty, which
+      # misplaces the next flush onto the glyph's right half (see bug/, balloon
+      # corruption).
       blank_left_partner(x, y)
       blank_right_partner(x + w - 1, y)
       write_cell(x, y, grapheme, style)
-      write_cell(x + 1, y, "", style) if w == 2
+      # A while loop, not (1...w).each: this runs once per painted cell, and a
+      # Range allocation per cell is 8000 per full-screen repaint.
+      i = 1
+      while i < w
+        write_cell(x + i, y, "", style)
+        i += 1
+      end
     end
 
     # (Re)allocates a blank grid of `size` with clean dirty state. Callers
@@ -451,31 +441,42 @@ module Tuile
       @any_dirty = true
     end
 
-    # If `(x, y)` holds the right half (continuation) of a wide glyph, blanks the
-    # orphaned left half at `x - 1`. Called before a write lands on `x`, so the
-    # wide glyph to the left isn't left headless.
+    # If `(x, y)` holds a continuation, blanks the head of the glyph it belongs to
+    # and every continuation up to — but not including — `x`. Called before a
+    # write lands on `x`, so the glyph reaching into `x` isn't left headless.
+    # Walks left rather than assuming the head sits at `x - 1`: a glyph may be
+    # wider than two columns, so its tail can run several cells.
     # @param x [Integer] column
     # @param y [Integer] row
     # @return [void]
     def blank_left_partner(x, y)
-      return unless in_bounds?(x, y) && @cells[index(x, y)].continuation? && in_bounds?(x - 1, y)
+      return unless in_bounds?(x, y) && @cells[index(x, y)].continuation?
 
-      write_cell(x - 1, y, " ", DEFAULT_STYLE)
+      head = x - 1
+      head -= 1 while in_bounds?(head, y) && @cells[index(head, y)].continuation?
+      return unless in_bounds?(head, y)
+
+      cx = head
+      while cx < x
+        write_cell(cx, y, " ", DEFAULT_STYLE)
+        cx += 1
+      end
     end
 
-    # If the cell just right of `(x, y)` is a continuation (the right half of a
-    # wide glyph whose origin is `(x, y)`), blanks it. Called before a write
-    # lands on `x`, so overwriting a wide origin doesn't strand its continuation.
-    # A continuation can only ever belong to the wide glyph immediately to its
-    # left, so the empty-grapheme test is exact — and cheaper than re-measuring
-    # the origin's width.
+    # Blanks the run of continuations immediately right of `(x, y)` — the tail of
+    # a glyph whose head is at or before `x`, and which the write landing on `x`
+    # is about to decapitate. A continuation always belongs to the nearest glyph
+    # on its left, so the empty-grapheme test is exact — and cheaper than
+    # re-measuring that glyph's width.
     # @param x [Integer] column
     # @param y [Integer] row
     # @return [void]
     def blank_right_partner(x, y)
-      return unless in_bounds?(x + 1, y) && @cells[index(x + 1, y)].continuation?
-
-      write_cell(x + 1, y, " ", DEFAULT_STYLE)
+      cx = x + 1
+      while in_bounds?(cx, y) && @cells[index(cx, y)].continuation?
+        write_cell(cx, y, " ", DEFAULT_STYLE)
+        cx += 1
+      end
     end
   end
 end

data/lib/tuile/color.rb

@@ -29,16 +29,10 @@ module Tuile
   # Color.coerce(nil)            # nil → nil
   # ```
   #
-  # Which entry point to use is a deliberate policy split. High-traffic
-  # call sites ({StyledString} and friends) stay lenient and {.coerce} raw
-  # forms — you don't want factory ceremony on every styled span.
-  # Declaration sites ({Theme}, defined once per app) are strict and take
-  # only {Color} instances, where `Color.palette(130)` documents itself in
-  # a way the bare `130` (palette index? RGB channel?) does not.
-  #
-  # {#to_ansi} renders a full SGR escape (`"\e[31m"`); {#sgr_codes} returns the
-  # raw numeric codes so callers (notably {StyledString}) can combine them with
-  # other SGR attributes in a single sequence.
+  # {.coerce} is the lenient entry point (raw forms plus `nil`); the named
+  # factories and constants are the strict, self-documenting path for
+  # declaration sites — see the book's chapter 6 for why theme colors take
+  # {Color} instances only.
   class Color
     # Symbolic color names. Order is significant: indices 0..7 map to the
     # standard ANSI colors (SGR 30..37 fg / 40..47 bg); indices 8..15 map to

data/lib/tuile/component/{text_input.rb → abstract_string_field.rb}

@@ -2,13 +2,33 @@
 
 module Tuile
   class Component
-    # Abstract base for editable text components ({TextField}, {TextArea}).
+    # Abstract base for the **String-valued** editable text components
+    # ({TextField}, {TextArea}): a field whose {HasValue#value} *is* its text.
+    # A field whose value is a different type (an `Integer`, a domain object)
+    # *composes* one of these rather than subclassing it — subclassing would
+    # drag this String-typed `text`/`value` seam onto its face alongside the
+    # real typed one.
     #
     # Holds the shared state — a mutable {#text} buffer, a {#caret} index,
     # {#on_change} and {#on_escape} callbacks — and the keyboard machinery
     # that single-line and multi-line inputs both need: ESC handling,
     # LEFT/RIGHT caret movement, CTRL+LEFT/CTRL+RIGHT word jumps, and the
-    # `focusable?`/`tab_stop?` flags.
+    # `tab_stop?` flag (`focusable?` comes from {HasValue}).
+    #
+    # {#caret} counts *characters* into {#text} but may only sit *between*
+    # grapheme clusters — the glyphs a terminal draws. Both write sites snap it
+    # forward onto the enclosing cluster's end, and every edit steps by a whole
+    # cluster:
+    #
+    #   f.text  = "e\u{0301}x"   # a decomposed e-acute then "x": 3 chars, 2 glyphs
+    #   f.caret = 1              # into the middle of the e-acute …
+    #   f.caret                  # => 2, its end — where the caret already drew
+    #   f.handle_key(Keys::BACKSPACE)
+    #   f.text                   # => "x": the whole glyph went, not its accent
+    #
+    # Insertion stays character-native, so `String#insert` merges a typed
+    # combining mark into its base; {#text=}'s snap covers the case where that
+    # re-segments the text around the caret.
     #
     # Subclasses implement the layout-specific pieces ({#cursor_position},
     # {#repaint}) and add their own keys (HOME/END, ENTER, UP/DOWN,
@@ -25,12 +45,15 @@ module Tuile
     # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
-    class TextInput < Component
+    class AbstractStringField < Component
+      include HasValue
+
       def initialize
         super
         @text = +""
         @caret = 0
         @on_change = nil
+        @on_value_change = nil
         @on_key = nil
         @on_escape = method(:default_on_escape)
       end
@@ -38,10 +61,24 @@ module Tuile
       # @return [String] current text contents.
       attr_reader :text
 
-      # @return [Boolean] true iff {#text} is the empty string.
-      def empty? = @text.empty?
+      # A text component's value *is* its text: {#value}/{#value=} are the
+      # {HasValue} seam over the same buffer as {#text}/{#text=}, so a form can
+      # drive it alongside typed fields. `text` stays the text-native name.
+      # @return [String]
+      def value = text
 
-      # @return [Integer] caret index in `0..text.length`.
+      # @param new_value [String, #to_s]
+      # @return [void]
+      def value=(new_value)
+        self.text = new_value.to_s
+      end
+
+      # `""` (not `nil`): a text field is empty when its buffer is blank.
+      # @return [String]
+      def empty_value = ""
+
+      # @return [Integer] caret index in `0..text.length`, counting characters
+      #   and always on a grapheme-cluster boundary (see the class doc).
       attr_reader :caret
 
       # Optional callback fired whenever {#text} changes. Receives the new text
@@ -72,30 +109,32 @@ module Tuile
       # @return [Proc, Method, nil] no-arg callable, or nil.
       attr_accessor :on_escape
 
-      def focusable? = true
-
       def tab_stop? = true
 
       # Sets the text. Runs {#preprocess_text} first (subclasses may filter or
-      # truncate). Caret is clamped to the new text length. Fires {#on_change}
-      # only on a real change.
+      # truncate). Caret is clamped to the new text length, then snapped back
+      # onto a cluster boundary of the *new* text. Fires {#on_change} only on a
+      # real change.
       # @param new_text [String]
       def text=(new_text)
         new_text = preprocess_text(new_text)
         return if @text == new_text
 
         @text = +new_text
-        @caret = @caret.clamp(0, @text.length)
+        @caret = snap_to_cluster(@caret.clamp(0, @text.length))
         on_text_mutated
         invalidate
         @on_change&.call(@text)
+        on_value_change&.call(@text)
       end
 
-      # Sets the caret position. Clamped to `0..text.length`. Fires
-      # {#on_caret_mutated} hook for subclasses (e.g. {TextArea} scrolls).
+      # Clamps to `0..text.length`, then snaps forward onto a grapheme-cluster
+      # boundary, so an index that fell inside a cluster reads back as that
+      # cluster's end. Fires the {#on_caret_mutated} hook for subclasses (e.g.
+      # {TextArea} scrolls).
       # @param new_caret [Integer]
       def caret=(new_caret)
-        new_caret = new_caret.clamp(0, @text.length)
+        new_caret = snap_to_cluster(new_caret.clamp(0, @text.length))
         return if @caret == new_caret
 
         @caret = new_caret
@@ -134,6 +173,15 @@ module Tuile
       # @return [String] possibly transformed text.
       def preprocess_text(new_text) = new_text.to_s
 
+      # The one measurement primitive both inputs share: a caret index counts
+      # characters, but every rect, cursor and click counts columns, and only
+      # this converts between them.
+      # @param str [String]
+      # @return [Integer] `str`'s width in terminal columns, measured per
+      #   grapheme cluster — so a combining mark adds nothing and a fullwidth
+      #   glyph adds two.
+      def columns_of(str) = str.each_grapheme_cluster.sum { |g| Buffer.display_width(g) }
+
       # Hook called after {#text} has been mutated, before invalidation /
       # {#on_change}. Default no-op. Subclasses use this to invalidate caches
       # ({TextArea}'s wrap cache) and update derived state.
@@ -148,7 +196,8 @@ module Tuile
 
       # Dispatch hook for {#handle_key}. Handles ESC and the navigation keys
       # that have identical semantics in single-line and multi-line inputs:
-      # LEFT/RIGHT arrows, CTRL+LEFT/CTRL+RIGHT for word jumps. Subclasses
+      # LEFT/RIGHT arrows (one grapheme cluster per press, so a press always
+      # moves), CTRL+LEFT/CTRL+RIGHT for word jumps. Subclasses
       # override to add their own keys (HOME/END, UP/DOWN, ENTER, BACKSPACE/
       # DELETE, printable insertion) and call `super` to fall back to the
       # common navigation handling.
@@ -156,8 +205,8 @@ module Tuile
       # @return [Boolean] true if the key was handled.
       def handle_text_input_key(key)
         case key
-        when Keys::LEFT_ARROW then self.caret = @caret - 1
-        when Keys::RIGHT_ARROW then self.caret = @caret + 1
+        when Keys::LEFT_ARROW then self.caret = cluster_boundary_before(@caret)
+        when Keys::RIGHT_ARROW then self.caret = cluster_boundary_after(@caret)
         when Keys::CTRL_LEFT_ARROW then self.caret = word_left
         when Keys::CTRL_RIGHT_ARROW then self.caret = word_right
         when Keys::ESC
@@ -170,27 +219,71 @@ module Tuile
         true
       end
 
+      # Removes the whole grapheme cluster before the caret — one press, one
+      # glyph, whatever it is built from (a ZWJ emoji family and a three-jamo
+      # Hangul syllable each go whole).
       # @return [void]
       def delete_before_caret
         return if @caret.zero?
 
+        start = cluster_boundary_before(@caret)
         new_text = @text.dup
-        new_text.slice!(@caret - 1)
-        @caret -= 1
+        new_text.slice!(start...@caret)
+        @caret = start
         self.text = new_text
       end
 
+      # Removes the whole grapheme cluster at the caret.
       # @return [void]
       def delete_at_caret
         return if @caret >= @text.length
 
         new_text = @text.dup
-        new_text.slice!(@caret)
+        new_text.slice!(@caret...cluster_boundary_after(@caret))
         self.text = new_text
       end
 
       private
 
+      # @param index [Integer] a {#text} index in `0..text.length`.
+      # @return [Integer] the smallest grapheme-cluster boundary `>= index`.
+      def snap_to_cluster(index)
+        offset = 0
+        @text.each_grapheme_cluster do |g|
+          return offset if offset >= index
+
+          offset += g.length
+        end
+        offset
+      end
+
+      # @param index [Integer]
+      # @return [Integer] the greatest grapheme-cluster boundary `< index`, or
+      #   0 at the start of the text.
+      def cluster_boundary_before(index)
+        last = 0
+        offset = 0
+        @text.each_grapheme_cluster do |g|
+          offset += g.length
+          return last if offset >= index
+
+          last = offset
+        end
+        last
+      end
+
+      # @param index [Integer]
+      # @return [Integer] the smallest grapheme-cluster boundary `> index`, or
+      #   `text.length` at the end of the text.
+      def cluster_boundary_after(index)
+        offset = 0
+        @text.each_grapheme_cluster do |g|
+          offset += g.length
+          return offset if offset > index
+        end
+        offset
+      end
+
       # Default {#on_escape} action: clear focus. Component deactivates; user
       # can re-focus by clicking or tabbing back in.
       # @return [void]

data/lib/tuile/component/button.rb

@@ -12,34 +12,26 @@ module Tuile
     # {Component#handle_mouse}.
     #
     # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
-    # show `[ caption ]` — that natural width is `caption.length + 4`.
+    # show `[ caption ]` — that natural width is `caption.display_width + 4`.
+    # A narrower {#rect} truncates the label with an ellipsis; a wider one leaves
+    # a tail that focuses but doesn't activate (see {#extent}).
     class Button < Component
-      # @param caption [String] the button's label.
+      include Component::HasCaption
+
+      # @param caption [String, StyledString, nil] the button's label, coerced
+      #   the same way {HasCaption#caption=} coerces it.
       # @yield optional `on_click` callback; same as assigning {#on_click=}.
-      def initialize(caption = "", &on_click)
+      def initialize(caption = nil, &on_click)
         super()
-        @caption = caption.to_s
+        self.caption = caption
         @on_click = on_click
       end
 
-      # @return [String] the button's label.
-      attr_reader :caption
-
       # Callback fired when the button is activated (Enter, Space, or
       # left-click). The callable receives no arguments.
       # @return [Proc, Method, nil] no-arg callable, or nil.
       attr_accessor :on_click
 
-      # Sets a new caption and invalidates the button. No-op if unchanged.
-      # @param new_caption [String]
-      def caption=(new_caption)
-        new_caption = new_caption.to_s
-        return if @caption == new_caption
-
-        @caption = new_caption
-        invalidate
-      end
-
       def focusable? = true
 
       def tab_stop? = true
@@ -56,11 +48,23 @@ module Tuile
         end
       end
 
+      # The cells the button actually paints: one row, `caption.display_width + 4`
+      # columns, clipped to {#rect}. Both the focus highlight and the click hit
+      # test use it, so a click on the blank tail of an over-wide rect — or on a
+      # lower row, when the rect is taller than one — does not fire {#on_click}.
+      # It still *focuses*: {Component#handle_mouse}'s click-to-focus is ungated
+      # by geometry. Same rule as {Checkbox#extent}, which documents the two
+      # traps behind it.
+      # @return [Rect]
+      def extent = Rect.new(rect.left, rect.top, [caption.display_width + 4, rect.width].min, 1)
+
+      # Fires {#on_click} on a left click within {#extent}; `super` runs first, so
+      # a click anywhere in {#rect} still focuses.
       # @param event [MouseEvent]
       # @return [void]
       def handle_mouse(event)
         super
-        return unless event.button == :left && rect.contains?(event.point)
+        return unless event.button == :left && extent.contains?(event.point)
 
         @on_click&.call
       end
@@ -70,9 +74,9 @@ module Tuile
         super
         return if rect.empty?
 
-        label = "[ #{@caption} ]"[0, rect.width]
-        styled = active? ? StyledString.styled(label, bg: screen.theme.active_bg_color) : StyledString.plain(label)
-        screen.buffer.set_line(rect.left, rect.top, styled)
+        label = (StyledString.plain("[ ") + caption + StyledString.plain(" ]")).ellipsize(rect.width)
+        label = label.with_bg(screen.theme.active_bg_color) if active?
+        draw_line(rect.left, rect.top, label)
       end
     end
   end