tuile 0.15.0 → 0.17.0

data/lib/tuile/buffer.rb

@@ -3,7 +3,7 @@
 module Tuile
   # An in-memory grid of styled cells mirroring the terminal screen. This is
   # the back buffer behind flicker-free rendering: components paint into it
-  # (via {#set_text} / {#set_char} / {#fill}) instead of writing escape
+  # through a {Canvas}, whose {Canvas::Backend} it is, instead of writing escape
   # sequences straight to the terminal, and {#flush} emits the minimal escape
   # string needed to bring a terminal — one that already matches the buffer's
   # state as of the previous flush — up to date. Only cells that actually
@@ -34,6 +34,10 @@ module Tuile
   # Overwriting either half of a wide glyph blanks the orphaned half, so the
   # grid never holds a dangling continuation or a headless one.
   class Buffer
+    # The three primitives below are exactly {Canvas::Backend}'s, so a canvas
+    # paints into a buffer with no adapter between them.
+    include Canvas::Backend
+
     # One screen cell: a single grapheme cluster, the {StyledString::Style} it's
     # drawn in, and a dirty flag. Mutable by design (see {Buffer} "Dirty
     # tracking") — the grid rewrites cells in place. A continuation cell (right
@@ -317,6 +321,13 @@ module Tuile
       region_cells(rect).map { |row| row.map(&:grapheme).join }
     end
 
+    # {#region_text} over the whole buffer, for one {Testing.paint} returned:
+    #
+    #   Testing.paint(window).text   # => ["┌Caption─────┐", "│ alpha      │", …]
+    #
+    # @return [Array<String>] the plain text of every row, top to bottom.
+    def text = region_text(Rect.new(0, 0, @width, @height))
+
     # @param rect [Rect]
     # @return [Array<String>] each row within `rect` rendered to ANSI, top to
     #   bottom — byte-identical to what a component's per-row `set_text` over

data/lib/tuile/canvas/backend.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Canvas
+    # Where a {Canvas}'s cells land: three primitives taking a fully resolved
+    # style. Include it to *be* one — {Tuile::Buffer} does, and needs no adapter:
+    #
+    #   Canvas.new(screen.buffer)
+    #
+    # A backend is dumb by contract: no theme, no component, no background
+    # chain, no translation, and no default arguments — the canvas resolves all
+    # of that and hands down a whole style at a coordinate in the backend's own
+    # grid. What varies here is only *where* the cells go;
+    # how a write is transformed on the way there belongs to the {Canvas}, which
+    # is final. See `D_canvas`.
+    #
+    # **`include`, never `prepend`.** A class's own methods win over an included
+    # module's, which is what lets {Tuile::Buffer} carry this while defining all
+    # three itself; prepended, these bodies would sit *ahead* of the class and
+    # every write would raise.
+    #
+    # Out-of-range writes are **dropped, not raised** — the terminal-edge clip
+    # belongs here, which is what lets a component paint a row the terminal is
+    # too narrow for without checking first.
+    module Backend
+      # @param x [Integer] starting column, in this backend's own grid —
+      #   the canvas has already applied its {Canvas#origin}.
+      # @param y [Integer] row, likewise.
+      # @param styled [StyledString] the text of one row; newlines are not handled.
+      # @return [void]
+      def set_text(x, y, styled) = raise(NotImplementedError, "#{self.class}#set_text")
+
+      # @param x [Integer] column, in this backend's own grid.
+      # @param y [Integer] row, likewise.
+      # @param grapheme [String] one grapheme cluster.
+      # @param style [StyledString::Style] fully resolved.
+      # @return [void]
+      def set_char(x, y, grapheme, style) = raise(NotImplementedError, "#{self.class}#set_char")
+
+      # @param rect [Rect] in this backend's own grid.
+      # @param style [StyledString::Style] fully resolved; only its `bg` shows.
+      # @return [void]
+      def fill(rect, style) = raise(NotImplementedError, "#{self.class}#fill")
+    end
+  end
+end

data/lib/tuile/canvas.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Tuile
+  # The paint context a component draws through: a {Backend} that says where
+  # cells land, plus the state every write needs — the {#origin} that puts
+  # `(0, 0)` at the component's own top-left, and the background to fill in
+  # behind content that carries none.
+  #
+  # A component never builds one. It paints onto the canvas its
+  # {Component#repaint} was handed, already loaded with that component's
+  # {ComponentBackground#effective} and positioned at its {Component#rect}, and
+  # derives a second for the cells that are not its own ink:
+  #
+  #   def repaint(canvas)
+  #     canvas.set_text(0, 0, label)                              # my well
+  #     canvas.with(bg_color: bg.ambient) { _1.fill(tail) }       # not my ink
+  #   end
+  #
+  # Three methods, in **paint coordinates**: `(0, 0)` is the component's own
+  # top-left, not the screen's, and {Component#local_rect} is its whole rect
+  # over here. Passing {Component#rect} instead lands the write at twice the
+  # offset, silently. Everything outside painting stays screen-space — `rect`,
+  # {Mouse::Event}, {Component#cursor_position} — which `D_canvas` argues.
+  #
+  # A `nil` {#bg_color} is the terminal default, never "inherit" — inheritance
+  # is resolved before a canvas is built ({Screen#canvas_for}).
+  #
+  # == Implementation details
+  #
+  # Frozen, and final by convention: {#with} yields a *derived* canvas and never
+  # mutates, so there are no save/restore pairs and no state to leave dangling
+  # for whatever paints next. Subclassing is not the extension point — {Backend}
+  # is, and it is the half that varies. See `D_canvas`.
+  #
+  # UI-thread-confined.
+  class Canvas
+    # @return [Backend] where the cells land.
+    attr_reader :backend
+
+    # @return [Color, nil] the background painted behind content that states
+    #   none; `nil` leaves the terminal default showing.
+    attr_reader :bg_color
+
+    # Where this canvas's `(0, 0)` sits in {#backend} coordinates — the
+    # component's {Component#rect}`.top_left`, as {Screen#canvas_for} built it.
+    # A component never reads it: adding the offset back by hand is the one
+    # thing it exists to make unnecessary.
+    # @return [Point]
+    attr_reader :origin
+
+    # The region of the {#backend}'s grid this canvas may write to —
+    # {Screen#clip_for}'s answer moved into backend coordinates, or `nil` for a
+    # canvas nobody bounded, which costs one test per write and nothing else.
+    # Every canvas {Screen#canvas_for} builds carries one; {Screen#canvas}, the
+    # root, is the `nil` case.
+    #
+    # In **backend** coordinates, like {#origin} and unlike every argument the
+    # three paint methods take: a canvas's *state* says where it sits in the
+    # world, its arguments are in paint coordinates (`D_clip`).
+    #
+    # An {Rect#empty? empty} clip is not `nil`: it means *paint nothing*, and it
+    # is what a component that can show nothing gets — collapsed, or scrolled
+    # clean out of its viewport. Every write is judged against the clip on its
+    # own terms, so this needs no special case; it is simply the case where they
+    # all fail.
+    #
+    # The one cell it does not protect: {Buffer#put_char} blanks the head of a
+    # wide glyph whose continuation half a clipped write overwrites, one column
+    # outside. That is the terminal's physical truth, and better than the
+    # dangling half-glyph the alternative leaves.
+    # @return [Rect, nil]
+    attr_reader :clip
+
+    # @param backend [Backend]
+    # @param bg_color [Color, nil] already resolved — a canvas consults no
+    #   component and no theme.
+    # @param origin [Point] the {#origin}; the default paints in backend
+    #   coordinates, which is what {Screen#canvas} is.
+    # @param clip [Rect, nil] the {#clip}, in backend coordinates —
+    #   {Screen#canvas_for} converts.
+    # @raise [Error] if `backend` does not include {Backend}, which is worth
+    #   catching here rather than mid-paint.
+    def initialize(backend, bg_color: nil, origin: Point::ZERO, clip: nil)
+      raise Error, "#{backend.class} must include Tuile::Canvas::Backend" unless backend.is_a?(Backend)
+
+      @backend = backend
+      @bg_color = bg_color
+      @origin = origin
+      @clip = clip
+      @blank_style = bg_color ? StyledString::Style.new(bg: bg_color) : StyledString::Style::DEFAULT
+      freeze
+    end
+
+    # Yields a canvas onto the same backend with a different background, for the
+    # span of the block — the *only* way to change it.
+    #
+    #   canvas.with(bg_color: bg.ambient) do |c|
+    #     c.fill(right)
+    #     c.fill(below)
+    #   end
+    #
+    # The receiver is untouched, so nothing has to be restored afterwards and
+    # the block cannot leave the wrong background on for whatever paints next.
+    # The {#origin} and the {#clip} ride along, so a derived canvas paints in
+    # the same coordinates and is bounded the same way.
+    # @param bg_color [Color, nil] the background inside the block.
+    # @return [Object] the block's value.
+    # @raise [Error] if no block is given — a derived canvas nobody scoped is
+    #   the dangling state this shape exists to make impossible.
+    def with(bg_color:)
+      raise Error, "Canvas#with needs a block: with(bg_color:) { |canvas| … }" unless block_given?
+      return yield self if bg_color == @bg_color
+
+      yield Canvas.new(@backend, bg_color:, origin: @origin, clip: @clip)
+    end
+
+    # Writes a {StyledString}, filling {#bg_color} behind any span that states
+    # no background of its own — so an inherited tint, or an invalid field's
+    # error well, shows through content the component did not colour.
+    # @param x [Integer] starting column, relative to {#origin}.
+    # @param y [Integer] row, relative to {#origin}.
+    # @param styled [StyledString] the text of one row; newlines are not handled.
+    # @return [void]
+    def set_text(x, y, styled)
+      col = x + @origin.x
+      row = y + @origin.y
+      return @backend.set_text(col, row, styled.under_bg(@bg_color)) if @clip.nil?
+      return unless clipped_row?(row)
+
+      write_clipped_text(col, row, styled)
+    end
+
+    # {#set_text}'s single-grapheme counterpart.
+    # @param x [Integer] column, relative to {#origin}.
+    # @param y [Integer] row, relative to {#origin}.
+    # @param grapheme [String] one grapheme cluster.
+    # @param style [StyledString::Style] its `bg`, when set, wins over {#bg_color}.
+    # @return [void]
+    def set_char(x, y, grapheme, style = StyledString::Style::DEFAULT)
+      style = style.merge(bg: @bg_color) if @bg_color && style.bg.nil?
+      col = x + @origin.x
+      row = y + @origin.y
+      return @backend.set_char(col, row, grapheme, style) if @clip.nil?
+      return unless clipped_row?(row)
+
+      # A zero-width cluster still lands in one cell, and that cell is what the
+      # clip judges.
+      width = [Buffer.display_width(grapheme), 1].max
+      from = [col, @clip.left].max
+      to = [col + width, @clip.left + @clip.width].min
+      return if to <= from
+
+      # Half of a wide glyph is unrenderable, so the columns the clip keeps are
+      # blanked instead — {Buffer#put_char}'s own policy at the terminal's edge.
+      return @backend.fill(Rect.new(from, row, to - from, 1), @blank_style) if to - from < width
+
+      @backend.set_char(col, row, grapheme, style)
+    end
+
+    # Blanks `area` to {#bg_color}.
+    #
+    # Only for cells nothing is about to paint over: {Buffer::Cell#set} dirties
+    # on a real change, so blanking a cell that is then redrawn re-emits it.
+    # @param area [Rect] relative to {#origin} — {Component#local_rect} for the
+    #   whole of a component, never its {Component#rect}.
+    # @return [void]
+    def fill(area)
+      # The early-out {#set_text} gets from `clipped_row?`: an empty clip keeps
+      # no cell at all, so neither rectangle below is worth building.
+      return if @clip && @clip.empty?
+
+      area = area.moved_by(@origin)
+      @backend.fill(@clip.nil? ? area : area.intersect(@clip), @blank_style)
+    end
+
+    private
+
+    # @param row [Integer] a row in backend coordinates.
+    # @return [Boolean] whether {#clip} keeps it. Callers have already checked
+    #   that there *is* a clip.
+    def clipped_row?(row) = row >= @clip.top && row < @clip.top + @clip.height
+
+    # {#set_text} for the case that has to think: cut `styled` to the clip's
+    # columns and write what survived where it really belongs.
+    #
+    # {StyledString#slice} **drops** a cluster the boundary falls inside rather
+    # than splitting one, at the start as readily as at the end — so the kept
+    # text can begin a column later than the cut asked for, and the write
+    # position is derived from it rather than assumed. The column a dropped
+    # cluster half-covered is blanked (`D_clip`).
+    # @param col [Integer] starting column, in backend coordinates.
+    # @param row [Integer] row, likewise; the caller has checked the clip keeps it.
+    # @param styled [StyledString] the text of one row, uncoloured as handed in.
+    # @return [void]
+    def write_clipped_text(col, row, styled)
+      right = @clip.left + @clip.width
+      width = styled.display_width
+      from = [col, @clip.left].max
+      to = [col + width, right].min
+      return if to <= from
+
+      kept = col < @clip.left ? styled.slice(@clip.left - col, width) : styled
+      start = col + width - kept.display_width
+      kept = kept.slice(0, right - start) if start + kept.display_width > right
+      stop = start + kept.display_width
+
+      @backend.fill(Rect.new(from, row, start - from, 1), @blank_style) if start > from
+      @backend.fill(Rect.new(stop, row, to - stop, 1), @blank_style) if to > stop
+      @backend.set_text(start, row, kept.under_bg(@bg_color)) unless kept.empty?
+    end
+  end
+end

data/lib/tuile/color.rb

@@ -122,6 +122,27 @@ module Tuile
     # @return [Symbol, Integer, Array<Integer>]
     attr_reader :value
 
+    # This color's red, green and blue, for an app doing color math — a
+    # contrast check, a tint derived from {Screen#background_color}:
+    #
+    #   Color.hex("#ff6400").rgb   # => [255, 100, 0]
+    #   Color::DEEP_SKY_BLUE1.rgb  # => [0, 175, 255], palette cell 39
+    #   Color::MAGENTA.rgb         # => nil, the terminal's scheme decides
+    #   Color.palette(5).rgb       # => nil, likewise
+    #
+    # `nil` for the 16 named colors, in either spelling, because the scheme
+    # remaps them and any answer would be a guess. Indices 16..255 answer
+    # xterm's cube and grey ramp: a terminal *may* redefine those too (OSC 4),
+    # but in practice none does.
+    #
+    # @return [Array<Integer>, nil] frozen, each channel 0..255.
+    def rgb
+      case @value
+      when Array then @value
+      when Integer then PALETTE_RGB[@value]
+      end
+    end
+
     # SGR parameter codes for emitting this color as either a foreground
     # (`target: :fg`) or background (`target: :bg`). Returned as an array so
     # callers can splice them into a multi-attribute SGR (e.g. bold + color).
@@ -214,17 +235,12 @@ module Tuile
 
     private
 
-    # This color's RGB — the palette cell's own coordinates when the value is
-    # an index. Only ever asked of a non-Symbol value; a named color has no
-    # RGB of its own, since the terminal's scheme decides what it looks like.
+    # {#rgb}, except an index 0..15 answers xterm's default for it — the guess
+    # `:ansi16` quantization needs something to match against, and {#rgb}
+    # must not hand out. Only ever asked of a non-Symbol value.
     # @return [Array<Integer>] red, green and blue, each 0..255.
     def rgb_triple
-      return @value if @value.is_a?(Array)
-      return ANSI16_RGB[@value] if @value < 16
-      return [8 + (10 * (@value - 232))] * 3 if @value >= 232
-
-      cube = @value - 16
-      [CUBE_LEVELS[cube / 36], CUBE_LEVELS[(cube / 6) % 6], CUBE_LEVELS[cube % 6]]
+      rgb || ANSI16_RGB[@value]
     end
 
     # Written flat — destructured rather than splatted, `x * x` rather than
@@ -293,6 +309,19 @@ module Tuile
     CUBE_INDEX = Array.new(256) { |c| (0...6).min_by { |i| (CUBE_LEVELS[i] - c).abs } }.freeze
     private_constant :CUBE_INDEX
 
+    # Palette index 0..255 → its RGB, frozen, or nil for 0..15 — what {#rgb}
+    # answers for an index, precomputed so it allocates nothing.
+    # @return [Array<Array<Integer>, nil>]
+    PALETTE_RGB = Array.new(256) do |index|
+      if index < 16 then nil
+      elsif index >= 232 then ([8 + (10 * (index - 232))] * 3).freeze
+      else
+        cube = index - 16
+        [CUBE_LEVELS[cube / 36], CUBE_LEVELS[(cube / 6) % 6], CUBE_LEVELS[cube % 6]].freeze
+      end
+    end.freeze
+    private_constant :PALETTE_RGB
+
     # xterm's default RGB for each of the 16 named colors, in {COLOR_SYMBOLS}
     # order — what `:ansi16` quantization matches against. A terminal scheme
     # may redefine these; see {#quantize}.