tuile 0.13.0 → 0.14.0

data/lib/tuile/color.rb

@@ -144,6 +144,47 @@ module Tuile
       end
     end
 
+    # This color as the nearest one `depth` can actually show — the
+    # degradation {Buffer#flush} applies to every color on its way to the wire:
+    #
+    #   Color.rgb(100, 100, 100).quantize(:palette256)  # => Color.palette(241)
+    #   Color.rgb(255, 0, 0).quantize(:ansi16)          # => Color::BRIGHT_RED
+    #   Color.rgb(255, 0, 0).quantize(:truecolor)       # => itself, unchanged
+    #
+    # Returns **the same instance** whenever `depth` shows this color as-is —
+    # every named color at every depth, a palette index anywhere but
+    # `:ansi16`, RGB at `:truecolor` — so `color.quantize(depth).equal?(color)`
+    # *is* the "needs no translating" predicate, and the common path
+    # allocates nothing.
+    #
+    # == Implementation details
+    #
+    # RGB picks whichever is nearer in squared-RGB distance: the 6×6×6 cube
+    # (16..231, its per-channel nearest levels being the nearest cell outright
+    # — the axes are independent) or the 24-step grey ramp (232..255, whose
+    # nearest step is the one nearest the channel mean).
+    #
+    # Under `:ansi16` a color goes *direct* to the nearest of the 16, never
+    # via the 256-palette — two steps would compound the rounding — and the
+    # result is a *named* color, which keeps respecting the user's terminal
+    # scheme. Matching is against xterm's default RGBs for the 16, which that
+    # scheme may itself redefine: the one mapping here that can be honestly
+    # wrong.
+    #
+    # @param depth [Symbol] one of {ColorDepth::DEPTHS}.
+    # @return [Color]
+    # @raise [ArgumentError] when `depth` is not a known depth.
+    def quantize(depth)
+      case depth
+      when :truecolor then self
+      when :palette256
+        @value.is_a?(Array) ? PALETTE_COLORS[nearest_palette(@value)] : self
+      when :ansi16
+        @value.is_a?(Symbol) ? self : ANSI16_COLORS[nearest_ansi16(rgb_triple)]
+      else raise ArgumentError, "invalid color depth: #{depth.inspect}"
+      end
+    end
+
     # Full SGR escape sequence for this color (e.g. `"\e[31m"`). Useful for
     # `print`-style direct emission; for composing with other attributes use
     # {#sgr_codes} instead.
@@ -171,10 +212,112 @@ module Tuile
       "#<#{self.class.name} #{@value.inspect}>"
     end
 
+    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.
+    # @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]]
+    end
+
+    # Written flat — destructured rather than splatted, `x * x` rather than
+    # `x**2`, no distance helper — because it runs per style transition in
+    # {Buffer#flush}, and the tidy shape measures ~2x slower (see
+    # `benchmark/quantize.rb`).
+    #
+    # @param rgb [Array<Integer>] red, green and blue, each 0..255.
+    # @return [Integer] palette index, 16..255 — the nearer of this color's
+    #   cube cell and its grey-ramp step. A tie goes to the cube, which spans
+    #   the whole space where the ramp only covers the diagonal.
+    def nearest_palette(rgb)
+      red, green, blue = rgb
+      ri = CUBE_INDEX[red]
+      gi = CUBE_INDEX[green]
+      bi = CUBE_INDEX[blue]
+      dr = CUBE_LEVELS[ri] - red
+      dg = CUBE_LEVELS[gi] - green
+      db = CUBE_LEVELS[bi] - blue
+      cube = (dr * dr) + (dg * dg) + (db * db)
+      # The grey minimizing the distance sits at the channel mean, so the best
+      # ramp step is the one nearest it; floor division rounds it half-up.
+      step = ((((red + green + blue) / 3) - 3) / 10).clamp(0, 23)
+      level = 8 + (10 * step)
+      gr = level - red
+      gg = level - green
+      gb = level - blue
+      grey = (gr * gr) + (gg * gg) + (gb * gb)
+      cube <= grey ? 16 + (36 * ri) + (6 * gi) + bi : 232 + step
+    end
+
+    # @param rgb [Array<Integer>] red, green and blue, each 0..255.
+    # @return [Integer] index into {COLOR_SYMBOLS} of the nearest of the 16.
+    def nearest_ansi16(rgb)
+      red, green, blue = rgb
+      best = 0
+      best_distance = nil
+      index = 0
+      while index < 16
+        candidate = ANSI16_RGB[index]
+        dr = candidate[0] - red
+        dg = candidate[1] - green
+        db = candidate[2] - blue
+        distance = (dr * dr) + (dg * dg) + (db * db)
+        if best_distance.nil? || distance < best_distance
+          best = index
+          best_distance = distance
+        end
+        index += 1
+      end
+      best
+    end
+
     COLOR_SYMBOLS.each do |sym|
       const_set(sym.upcase, new(sym))
     end
 
+    # The channel values the 6×6×6 cube (palette 16..231) samples.
+    # @return [Array<Integer>]
+    CUBE_LEVELS = [0, 95, 135, 175, 215, 255].freeze
+    private_constant :CUBE_LEVELS
+
+    # Channel value 0..255 → index into {CUBE_LEVELS} of the nearest level,
+    # so quantizing a channel is one array read rather than six compares.
+    # @return [Array<Integer>]
+    CUBE_INDEX = Array.new(256) { |c| (0...6).min_by { |i| (CUBE_LEVELS[i] - c).abs } }.freeze
+    private_constant :CUBE_INDEX
+
+    # 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}.
+    # @return [Array<Array<Integer>>]
+    ANSI16_RGB = [
+      [0, 0, 0], [128, 0, 0], [0, 128, 0], [128, 128, 0],
+      [0, 0, 128], [128, 0, 128], [0, 128, 128], [192, 192, 192],
+      [128, 128, 128], [255, 0, 0], [0, 255, 0], [255, 255, 0],
+      [0, 0, 255], [255, 0, 255], [0, 255, 255], [255, 255, 255]
+    ].freeze
+    private_constant :ANSI16_RGB
+
+    # Every named color, in {COLOR_SYMBOLS} order — the shared instances
+    # `:ansi16` quantization returns.
+    # @return [Array<Color>]
+    ANSI16_COLORS = COLOR_SYMBOLS.map { |sym| const_get(sym.upcase) }.freeze
+    private_constant :ANSI16_COLORS
+
+    # Every palette cell 0..255 as a {Color}, so quantizing to the palette
+    # allocates nothing and lands on a shared instance. Distinct from the
+    # {PALETTE_NAMES} constants, which cover only the *named* cells.
+    # @return [Array<Color>]
+    PALETTE_COLORS = Array.new(256) { |index| new(index) }.freeze
+    private_constant :PALETTE_COLORS
+
     # Names for the 256-color palette indices 16..255, from the standard
     # xterm chart (<https://www.ditig.com/256-colors-cheat-sheet>). A constant
     # per entry is pre-defined, an exact palette cell — no quantization:

data/lib/tuile/color_depth.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Tuile
+  # How many colors the terminal on the other end can actually show — the
+  # depth {Color#quantize} degrades a color to:
+  #
+  #   ColorDepth.detect                                        # => :truecolor
+  #   ColorDepth.detect(env: { "TERM" => "xterm-256color" })   # => :palette256
+  #   ColorDepth.detect(env: {})                               # => :ansi16
+  #
+  # Env-only: no terminal round-trip, so unlike {TerminalBackground.detect}
+  # there is no stdin timing to respect, and the answer cannot go stale
+  # mid-session the way a background color can.
+  #
+  # Terminals lie in both directions — `COLORTERM` frequently doesn't survive
+  # ssh (it isn't in the default `SendEnv` set) or tmux — so {OVERRIDE_ENV}
+  # beats every other signal, the escape hatch for a terminal detected wrong.
+  # Misdetection otherwise lands *conservatively*: a truecolor tmux
+  # advertising only `tmux-256color` reads as `:palette256`, which renders
+  # coarser but never mangled.
+  #
+  # == Implementation details
+  #
+  # Terminfo is deliberately not consulted — its `RGB` boolean and
+  # `colors#0x1000000` would mean shelling out to `tput`/`infocmp` at every
+  # startup, and the env ladder plus the override already covers the real
+  # terminal matrix.
+  module ColorDepth
+    # The depths, most capable first: 24-bit RGB, the 256-color palette, and
+    # the 16 named ANSI colors.
+    # @return [Array<Symbol>]
+    DEPTHS = %i[truecolor palette256 ansi16].freeze
+
+    # Environment variable that overrides detection outright; holds one of
+    # {DEPTHS}. Empty counts as unset.
+    # @return [String]
+    OVERRIDE_ENV = "TUILE_COLOR_DEPTH"
+
+    # `COLORTERM` values that promise 24-bit color.
+    # @return [Array<String>]
+    TRUECOLOR_COLORTERM = %w[truecolor 24bit].freeze
+
+    class << self
+      # The terminal's color depth, from {OVERRIDE_ENV}, else `COLORTERM`,
+      # else `TERM` (a `-direct` entry means 24-bit, a `256color` one the
+      # palette), else the 16-color floor.
+      #
+      # @param env [Hash{String => String}] environment to read; defaults to
+      #   `ENV` (which duck-types the `[]` lookup).
+      # @return [Symbol] one of {DEPTHS}.
+      # @raise [ArgumentError] when {OVERRIDE_ENV} holds an unknown value. It
+      #   is only ever set deliberately, so a typo in it is worth failing at
+      #   startup over — ignoring it silently means a whole session of
+      #   debugging the wrong colors.
+      def detect(env: ENV)
+        override = env[OVERRIDE_ENV].to_s
+        return parse_override(override) unless override.empty?
+
+        term = env["TERM"].to_s
+        return :truecolor if TRUECOLOR_COLORTERM.include?(env["COLORTERM"].to_s.downcase) ||
+                             term.include?("-direct")
+        return :palette256 if term.include?("256color")
+
+        :ansi16
+      end
+
+      private
+
+      # @param value [String] the raw {OVERRIDE_ENV} value.
+      # @return [Symbol]
+      def parse_override(value)
+        depth = value.strip.downcase.to_sym
+        return depth if DEPTHS.include?(depth)
+
+        raise ArgumentError,
+              "invalid #{OVERRIDE_ENV}: #{value.inspect} (expected one of #{DEPTHS.join(", ")})"
+      end
+    end
+  end
+end

data/lib/tuile/component/button.rb

@@ -55,8 +55,8 @@ module Tuile
       # 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)
+      # @return [Size]
+      def extent = Size.new([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.
@@ -64,7 +64,7 @@ module Tuile
       # @return [void]
       def handle_mouse(event)
         super
-        return unless event.button == :left && extent.contains?(event.point)
+        return unless event.button == :left && extent_rect.contains?(event.point)
 
         @on_click&.call
       end

data/lib/tuile/component/checkbox.rb

@@ -95,8 +95,8 @@ module Tuile
       # The extent ignores {Component#bg_color}: an inherited tint paints the dead
       # tail, but a hit test that silently widened with a background would be a
       # mode switch invisible in the code and untestable by inspection.
-      # @return [Rect]
-      def extent = Rect.new(rect.left, rect.top, [caption.display_width + 4, rect.width].min, 1)
+      # @return [Size]
+      def extent = Size.new([caption.display_width + 4, rect.width].min, 1)
 
       # Toggles on Space or Enter. Every other key is left unhandled so it bubbles
       # to an ancestor.
@@ -115,7 +115,7 @@ module Tuile
       # @return [void]
       def handle_mouse(event)
         super
-        return unless event.button == :left && extent.contains?(event.point)
+        return unless event.button == :left && extent_rect.contains?(event.point)
 
         toggle
       end

data/lib/tuile/component/combo_box.rb

@@ -14,7 +14,7 @@ module Tuile
     #   combo.value = some_user                       # selects it; field shows its label
     #
     # It's the assembly you'd otherwise wire by hand — a {TextField} plus a
-    # non-modal {Popup} over a {List} — promoted to one component. Give it a
+    # an {Overlay} over a {List} — promoted to one component. Give it a
     # single-row {#rect}; it paints the field across that row with a `▾` in the
     # last column and floats the dropdown above or below.
     #
@@ -147,6 +147,13 @@ module Tuile
         draw_char(rect.left + rect.width - 1, rect.top, "▾", StyledString::Style::DEFAULT.with(bg: well))
       end
 
+      # The one row this combo paints — the full width, at the top of {#rect}.
+      # A single-slot container hands its content the whole inner rect, so a
+      # ComboBox is routinely assigned more height than it uses; the dropdown
+      # hangs under this rather than under the unused space below it.
+      # @return [Size]
+      def extent = Size.new(rect.width, 1)
+
       protected
 
       # Field spans the row bar the last column, which the `▾` occupies
@@ -262,7 +269,7 @@ module Tuile
       # labels, which ellipsize a column earlier once the list scrolls. That is
       # the trade a measuring driver ({Select}) makes the other way.
       # @return [void]
-      def anchor = @overlay.anchor_to(rect, rows: @filtered.size)
+      def anchor = @overlay.anchor_to(extent_rect, rows: @filtered.size)
     end
   end
 end