tuile 0.5.0 → 0.6.0

data/lib/tuile/sizing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A sizing policy for a slot whose position is managed by a parent
+  # component (e.g. {Component::Window#footer}). Resolves one dimension at a
+  # time via {#resolve}, so the same value works for widths and heights.
+  #
+  # Three policies exist:
+  #
+  # - {FILL} — take everything the slot offers;
+  # - {WRAP_CONTENT} — take the component's natural extent (its
+  #   {Component#content_size}), clamped to the slot;
+  # - {.fixed} — take exactly the given number of cells, clamped to the slot.
+  #
+  # Note that {WRAP_CONTENT} only makes sense for components that report a
+  # natural {Component#content_size} ({Component::Label}, {Component::Button},
+  # {Component::List}, …). Input components ({Component::TextField} et al.)
+  # report {Size::ZERO}, so a wrap-content slot collapses to zero width —
+  # i.e. the component becomes invisible. Use {.fixed} or {FILL} for those.
+  #
+  # @!attribute [r] mode
+  #   @return [Symbol] `:fill`, `:wrap_content` or `:fixed`.
+  # @!attribute [r] amount
+  #   @return [Integer, nil] the cell count for `:fixed`; `nil` otherwise.
+  class Sizing < Data.define(:mode, :amount)
+    # @param amount [Integer] the number of cells to occupy; 0 or greater.
+    # @return [Sizing] a fixed-size policy.
+    def self.fixed(amount)
+      raise TypeError, "expected Integer, got #{amount.inspect}" unless amount.is_a?(Integer)
+      raise ArgumentError, "amount must not be negative, got #{amount}" if amount.negative?
+
+      new(mode: :fixed, amount: amount)
+    end
+
+    # Resolves one dimension of a slot.
+    # @param available [Integer] cells the slot offers; 0 or greater.
+    # @param content [Integer] the component's natural extent on this axis
+    #   (one dimension of its {Component#content_size}).
+    # @return [Integer] the resolved extent, always in `0..available`.
+    def resolve(available, content)
+      case mode
+      when :fill then available
+      when :fixed then amount.clamp(0, available)
+      when :wrap_content then content.clamp(0, available)
+      else raise ArgumentError, "unknown mode #{mode.inspect}"
+      end
+    end
+
+    # Occupy everything the slot offers.
+    # @return [Sizing]
+    FILL = new(mode: :fill, amount: nil)
+
+    # Occupy the component's natural {Component#content_size}, clamped to the
+    # slot. Components reporting {Size::ZERO} collapse to invisibility — see
+    # the class doc.
+    # @return [Sizing]
+    WRAP_CONTENT = new(mode: :wrap_content, amount: nil)
+  end
+end

data/lib/tuile/terminal_background.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Detects whether the terminal background is light or dark, so {Screen}
+  # can pick {Theme::LIGHT} or {Theme::DARK} automatically at startup.
+  #
+  # Two mechanisms, in order of reliability:
+  #
+  # 1. **OSC 11 query** — writes `ESC ] 11 ; ? BEL` to the terminal; modern
+  #    terminals (xterm, kitty, alacritty, wezterm, iTerm2, GNOME Terminal,
+  #    Windows Terminal) reply on stdin with the background color
+  #    (`\e]11;rgb:RRRR/GGGG/BBBB` + BEL or ST). The color's relative
+  #    luminance against a 0.5 threshold decides light vs dark. Terminals
+  #    that don't support the query simply never reply, so the read is
+  #    bounded by a short timeout.
+  # 2. **`COLORFGBG` env var** — rxvt/konsole export `"fg;bg"` ANSI palette
+  #    indices. Less reliable (stale across SSH/tmux, often unset); used
+  #    only when OSC 11 yields nothing.
+  #
+  # **Timing matters**: the OSC 11 reply arrives on stdin, so the query
+  # must complete before {EventQueue#start_key_thread} owns stdin —
+  # otherwise the reply bytes get consumed as garbage keystrokes. {Screen}
+  # calls {.detect} from its constructor, which apps run before
+  # {Screen#run_event_loop}; don't call this after the event loop started.
+  module TerminalBackground
+    # How long to wait for the OSC 11 reply. Generous for a local
+    # terminal; bounded so unsupporting terminals (which never reply)
+    # don't stall startup.
+    # @return [Float] seconds.
+    QUERY_TIMEOUT = 0.1
+
+    # The OSC 11 background-color query, BEL-terminated.
+    # @return [String]
+    QUERY = "\e]11;?\a"
+
+    # Matches the OSC 11 reply. Components are 1–4 hex digits each
+    # (terminals vary); `rgba:` (4 components) also matches — the alpha
+    # tail is ignored.
+    # @return [Regexp]
+    REPLY = %r{\e\]11;rgba?:(\h{1,4})/(\h{1,4})/(\h{1,4})}
+
+    # Enables mode 2031: the terminal pushes a color-scheme report
+    # (`\e[?997;1n` dark / `\e[?997;2n` light) whenever the OS appearance
+    # flips — see {EventQueue::ColorSchemeEvent}. Terminals without
+    # support ignore the sequence. Written by {Screen#run_event_loop}.
+    # @return [String]
+    NOTIFY_ON = "\e[?2031h"
+
+    # Disables mode 2031 again; written when the event loop exits.
+    # @return [String]
+    NOTIFY_OFF = "\e[?2031l"
+
+    class << self
+      # Detects the terminal background. Queries OSC 11 when both `input`
+      # and `output` are TTYs, falling back to `COLORFGBG`.
+      #
+      # @param input [IO] where the OSC 11 reply arrives (the TTY input).
+      # @param output [IO] where the query is written (the TTY output).
+      # @param env [Hash{String => String}] environment for the `COLORFGBG`
+      #   fallback; defaults to `ENV` (which duck-types the `[]` lookup).
+      # @param timeout [Numeric] max seconds to wait for the OSC 11 reply.
+      # @return [Symbol, nil] `:light`, `:dark`, or nil when undetectable.
+      def detect(input: $stdin, output: $stdout, env: ENV, timeout: QUERY_TIMEOUT)
+        osc = query_osc11(input, output, timeout) if input.tty? && output.tty?
+        osc || from_colorfgbg(env["COLORFGBG"])
+      end
+
+      private
+
+      # Writes the OSC 11 query and classifies the reply. The whole
+      # exchange runs with `input` in raw mode: the reply has no trailing
+      # newline, so a canonical-mode read would block past the timeout,
+      # and echo would smear the reply bytes onto the screen.
+      # @param input [IO]
+      # @param output [IO]
+      # @param timeout [Numeric]
+      # @return [Symbol, nil]
+      def query_osc11(input, output, timeout)
+        reply = input.raw do
+          output.write(QUERY)
+          output.flush
+          read_reply(input, timeout)
+        end
+        match = REPLY.match(reply)
+        match && classify(match.captures)
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      # Accumulates reply bytes until a BEL/ST terminator or the deadline.
+      # Terminals that don't support OSC 11 never reply — returning
+      # whatever arrived (usually nothing) lets the caller fail soft.
+      # @param input [IO]
+      # @param timeout [Numeric]
+      # @return [String]
+      def read_reply(input, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        buffer = +""
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return buffer if remaining <= 0 || IO.select([input], nil, nil, remaining).nil?
+
+          buffer << input.readpartial(256)
+          return buffer if buffer.include?("\a") || buffer.include?("\e\\")
+        end
+      rescue EOFError
+        buffer
+      end
+
+      # Relative luminance of the reported background, scaled per
+      # component hex width (xterm replies 4 digits per channel, others 2).
+      # @param components [Array<String>] three hex strings.
+      # @return [Symbol] `:light` or `:dark`.
+      def classify(components)
+        r, g, b = components.map { |c| c.to_i(16).fdiv((16**c.length) - 1) }
+        luminance = (0.2126 * r) + (0.7152 * g) + (0.0722 * b)
+        luminance > 0.5 ? :light : :dark
+      end
+
+      # `COLORFGBG` is `"fg;bg"` (rxvt sometimes `"fg;default;bg"`) with
+      # ANSI palette indices. White-ish backgrounds — 7 (white) and the
+      # bright range 9–15 — read as light; 0–6 and 8 as dark; anything
+      # else (missing, `"default"`, out of range) is inconclusive.
+      # @param value [String, nil]
+      # @return [Symbol, nil]
+      def from_colorfgbg(value)
+        bg = value&.split(";")&.last
+        return nil unless bg&.match?(/\A\d+\z/)
+
+        case bg.to_i
+        when 0..6, 8 then :dark
+        when 7, 9..15 then :light
+        end
+      end
+    end
+  end
+end

data/lib/tuile/theme.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A set of semantic colors the built-in components read when painting.
+  # The current theme lives at {Screen#theme}; components must look it up
+  # at paint time (inside `repaint`) rather than caching values, so that
+  # assigning {Screen#theme=} restyles everything via a single
+  # invalidate-everything pass.
+  #
+  # The primary API is the rendering helpers — {#active_bg},
+  # {#active_border}, {#input_bg}, {#hint} — which wrap a plain string in
+  # the token's SGR color (on the channel appropriate for the token's
+  # role) and reset:
+  #
+  #   screen.theme.active_bg("[ Ok ]")   # => "\e[48;5;59m[ Ok ]\e[0m"
+  #   screen.theme.hint("quit")          # => "\e[38;5;109mquit\e[0m"
+  #
+  # The helpers pass content through verbatim, so input may carry other
+  # escape sequences (e.g. {Component::Window} feeds its border string,
+  # cursor moves included). For span-aware styling — applying a token to a
+  # {StyledString} while preserving per-span colors — use the `*_color`
+  # readers instead (e.g. {Component::List} highlights its cursor row via
+  # `with_bg(theme.active_bg_color)`). Rule of thumb: plain chrome text →
+  # helper; structured text → `*_color` reader + {StyledString}.
+  #
+  # Two built-in themes are provided: {DARK} (the default; the colors Tuile
+  # has always used) and {LIGHT} (counterparts legible on light terminal
+  # backgrounds). A custom theme is one `with` away:
+  #
+  #   screen.theme = Theme::DARK.with(active_border_color: Color::CYAN)
+  #
+  # Tokens deliberately cover only the *accents* Tuile paints. Everything
+  # else inherits the terminal's own default foreground/background, which
+  # already matches the user's terminal theme perfectly — that's why there
+  # is no global `bg`/`fg` token.
+  #
+  # Every token is a {Color} — and must be passed as one. Unlike the
+  # lenient {Color.coerce} call sites elsewhere in the framework, a theme
+  # is declared once per app, so it takes only {Color} instances: at a
+  # declaration site `Color.palette(130)` documents itself in a way the
+  # bare `130` does not (palette index? RGB channel?) — and the named
+  # palette constants (`Color::DARK_ORANGE3` *is* 130; see
+  # {Color::PALETTE_NAMES}) go one step further.
+  #
+  # ## App-specific tokens
+  #
+  # Beyond the built-in tokens, an app can carry its own colors in
+  # {#custom} — a frozen `Hash{Symbol => Color}` member. Look them up with
+  # {#[]} (fail-fast: a typo raises `KeyError`) and render with the
+  # generic {#fg} / {#bg} helpers:
+  #
+  #   theme = Theme::DARK.with(custom: { accent: Color::DARK_ORANGE })
+  #   theme[:accent]              # => Color, e.g. for StyledString#with_fg
+  #   theme.fg(:accent, "NEW")    # => "\e[38;5;208mNEW\e[0m"
+  #
+  # Apps wanting semantic readers can subclass — `Data#with` preserves the
+  # subclass, so an `AppTheme` stays an `AppTheme` through `with`:
+  #
+  #   class AppTheme < Tuile::Theme
+  #     def accent(text) = fg(:accent, text)
+  #   end
+  #
+  # Pair the dark and light variants in a {ThemeDef} and hand it to
+  # {Screen#theme_def=} so OS appearance flips pick the right one.
+  #
+  # @!attribute [r] active_bg_color
+  #   Background highlight of the component the user is interacting with:
+  #   the {Component::List} cursor row, the focused {Component::TextField} /
+  #   {Component::TextArea} well, the focused {Component::Button}. "Active"
+  #   matches the {Component#active?} focus-chain flag — this is the
+  #   focus/selection highlight in conventional UI terms.
+  #   @return [Color]
+  # @!attribute [r] active_border_color
+  #   Foreground of a {Component::Window} border when the window is on the
+  #   active (focus) chain.
+  #   @return [Color]
+  # @!attribute [r] input_bg_color
+  #   Resting background "well" of {Component::TextField} /
+  #   {Component::TextArea} when *not* active — visibly a field, but
+  #   distinctly subtler than {#active_bg_color}.
+  #   @return [Color]
+  # @!attribute [r] hint_color
+  #   Foreground of keyboard-shortcut captions in status-bar hints (the
+  #   "quit" in "q quit") — see {#hint}.
+  #   @return [Color]
+  # @!attribute [r] custom
+  #   App-specific color tokens; empty in the built-in themes. Frozen —
+  #   build a changed theme via `with(custom: ...)`. Prefer {#[]} for
+  #   lookups (it fail-fasts on typos); read this directly to enumerate
+  #   the tokens.
+  #   @return [Hash{Symbol => Color}]
+  class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color, :hint_color, :custom)
+    # @param active_bg_color [Color]
+    # @param active_border_color [Color]
+    # @param input_bg_color [Color]
+    # @param hint_color [Color]
+    # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
+    # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
+    #   `Hash{Symbol => Color}`.
+    def initialize(active_bg_color:, active_border_color:, input_bg_color:, hint_color:, custom: {})
+      { active_bg_color:, active_border_color:, input_bg_color:, hint_color: }.each do |name, value|
+        raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
+      end
+      raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)
+
+      custom.each do |key, value|
+        raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
+        raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
+      end
+      super(active_bg_color:, active_border_color:, input_bg_color:, hint_color:, custom: custom.dup.freeze)
+    end
+
+    # Looks up an app-specific token from {#custom}.
+    # @param token [Symbol]
+    # @return [Color]
+    # @raise [KeyError] when the token is not present — a typo should fail
+    #   loudly, not paint in a default.
+    def [](token) = custom.fetch(token)
+
+    # Renders `text` in the foreground color of the app-specific `token`
+    # — the generic counterpart of {#hint} for {#custom} tokens.
+    # @param token [Symbol]
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    # @raise [KeyError] when the token is not present.
+    def fg(token, text) = wrap(text, self[token], :fg)
+
+    # Renders `text` on the background color of the app-specific `token`
+    # — the generic counterpart of {#active_bg} for {#custom} tokens.
+    # @param token [Symbol]
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    # @raise [KeyError] when the token is not present.
+    def bg(token, text) = wrap(text, self[token], :bg)
+
+    # Renders `text` on the {#active_bg_color} background.
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    def active_bg(text) = wrap(text, active_bg_color, :bg)
+
+    # Renders `text` in the {#active_border_color} foreground. Content
+    # passes through verbatim, so it may embed non-SGR escapes (cursor
+    # moves in a border string).
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    def active_border(text) = wrap(text, active_border_color, :fg)
+
+    # Renders `text` on the {#input_bg_color} background.
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    def input_bg(text) = wrap(text, input_bg_color, :bg)
+
+    # Renders `text` in the {#hint_color} foreground, for status-bar hints,
+    # e.g. `"q #{screen.theme.hint("quit")}"`. The color is baked into the
+    # returned String, so strings built this way do *not* restyle when the
+    # theme changes — rebuild them instead (the framework's own call sites
+    # rebuild on every status-bar refresh).
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    def hint(text) = wrap(text, hint_color, :fg)
+
+    # The colors Tuile used before themes existed, tuned for dark terminal
+    # backgrounds. GREY37 (palette 59) is what Rainbow emits for
+    # `:darkslategray`, LIGHT_SKY_BLUE3 (109) for `:cadetblue`; GREY27
+    # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
+    # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
+    # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
+    # darker than the active highlight at 59 (~#5f5f5f).
+    # @return [Theme]
+    DARK = new(active_bg_color: Color::GREY37,
+               active_border_color: Color::GREEN,
+               input_bg_color: Color::GREY27,
+               hint_color: Color::LIGHT_SKY_BLUE3)
+
+    # Counterparts legible on light terminal backgrounds: grayscale-ramp
+    # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
+    # ~#dadada — dark enough to read as a "well" against white, one step
+    # lighter than the active highlight) and a dark teal (TURQUOISE4 = 30,
+    # ~#008787) keeping the hint hue. `active_border_color` stays the
+    # named green — named ANSI colors are remapped by the terminal's own
+    # palette, so the theme picks a light-appropriate green for us.
+    # @return [Theme]
+    LIGHT = new(active_bg_color: Color::GREY82,
+                active_border_color: Color::GREEN,
+                input_bg_color: Color::GREY85,
+                hint_color: Color::TURQUOISE4)
+
+    private
+
+    # The single sanctioned place for verbatim SGR wrapping: `text` is not
+    # parsed or validated, so callers may embed non-SGR escapes. Emits the
+    # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
+    # text.
+    # @param text [String]
+    # @param color [Color]
+    # @param target [Symbol] `:fg` or `:bg`.
+    # @return [String]
+    def wrap(text, color, target)
+      "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
+    end
+  end
+end

data/lib/tuile/theme_def.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Tuile
+  # An app's theme definition: the {Theme} pair covering both terminal
+  # appearances. {Screen} keeps one at {Screen#theme_def} (defaulting to
+  # {DEFAULT}) and picks the member matching the detected background at
+  # startup and on every OS appearance flip (mode 2031) — so a custom
+  # definition survives the user toggling light/dark, where a bare
+  # {Screen#theme=} assignment would be replaced.
+  #
+  #   APP_THEME = Tuile::ThemeDef.new(
+  #     dark:  Tuile::Theme::DARK.with(custom: { accent: Color::DARK_ORANGE }),
+  #     light: Tuile::Theme::LIGHT.with(custom: { accent: Color::DARK_ORANGE3 })
+  #   )
+  #   screen.theme_def = APP_THEME
+  #
+  # Both members must declare the same {Theme#custom} key set. Without
+  # that, a token present only in one member would raise `KeyError` at
+  # the unpredictable moment the user flips OS appearance; checking here
+  # turns it into an immediate construction-time failure.
+  #
+  # @!attribute [r] dark
+  #   The theme applied on dark terminal backgrounds.
+  #   @return [Theme]
+  # @!attribute [r] light
+  #   The theme applied on light terminal backgrounds.
+  #   @return [Theme]
+  class ThemeDef < Data.define(:dark, :light)
+    # @param dark [Theme]
+    # @param light [Theme]
+    # @raise [TypeError] when a member is not a {Theme}.
+    # @raise [ArgumentError] when the members' {Theme#custom} key sets differ.
+    def initialize(dark:, light:)
+      raise TypeError, "dark must be a Tuile::Theme, got #{dark.inspect}" unless dark.is_a?(Theme)
+      raise TypeError, "light must be a Tuile::Theme, got #{light.inspect}" unless light.is_a?(Theme)
+
+      if dark.custom.keys.sort != light.custom.keys.sort
+        raise ArgumentError,
+              "dark and light must declare the same custom tokens; " \
+              "dark has #{dark.custom.keys.sort.inspect}, light has #{light.custom.keys.sort.inspect}"
+      end
+
+      super
+    end
+
+    # The member for the given color scheme. Anything other than `:light`
+    # selects {#dark}, matching {TerminalBackground.detect}'s
+    # inconclusive-means-dark policy.
+    # @param scheme [Symbol] `:dark` or `:light`.
+    # @return [Theme]
+    def for(scheme) = scheme == :light ? light : dark
+
+    # The built-in pair: {Theme::DARK} / {Theme::LIGHT}.
+    # @return [ThemeDef]
+    DEFAULT = new(dark: Theme::DARK, light: Theme::LIGHT)
+
+    class << self
+      # The definition newly-constructed {Screen}s start from (see
+      # {Screen#theme_def}); initially {DEFAULT}. Reassigning affects
+      # future screens only — an already-constructed screen keeps its
+      # definition until {Screen#theme_def=}.
+      #
+      # Intended for test suites: production apps assign
+      # {Screen#theme_def=} once at startup, but component specs build a
+      # fresh {FakeScreen} per example, and a component reading a custom
+      # token (`theme[:accent]`) would `KeyError` against the built-in
+      # default. Point this at the app's definition once and every
+      # {Screen.fake} carries it:
+      #
+      #   Tuile::ThemeDef.default = APP_THEME   # spec_helper.rb, once
+      #   before { Screen.fake }                # theme[:accent] resolves
+      # @return [ThemeDef]
+      attr_reader :default
+
+      # @param theme_def [ThemeDef]
+      # @raise [TypeError] when not a {ThemeDef}.
+      def default=(theme_def)
+        raise TypeError, "expected ThemeDef, got #{theme_def.inspect}" unless theme_def.is_a?(ThemeDef)
+
+        @default = theme_def
+      end
+    end
+    @default = DEFAULT
+  end
+end

data/lib/tuile/version.rb

@@ -2,5 +2,5 @@
 
 module Tuile
   # @return [String]
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/tuile.rb

@@ -3,7 +3,6 @@
 require "concurrent"
 require "io/console"
 require "logger"
-require "rainbow"
 require "singleton"
 require "strscan"
 require "tty-cursor"