Class: Tuile::Theme

Inherits:
Object
  • Object
show all
Defined in:
lib/tuile/theme.rb,
sig/tuile.rbs

Overview

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 a Screen#theme= restyles everything via one invalidate-everything pass. Book ch6 is the concept in full (why accents-only, dark/light, live OS flips).

The rendering helpers — #active_bg, #active_border, #input_bg, #hint — 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"

Content passes through verbatim (so it may carry other escapes). For span-aware styling — a token applied to a StyledString without flattening its per-span colors — use the *_color readers instead (with_bg(theme.active_bg_color)). Rule of thumb: plain chrome → helper; structured text → *_color reader + StyledString.

Two built-in themes ship: DARK (default) and LIGHT. A custom one is one with away, and every token must be a Color instance — not the lenient Color.coerce forms, since a theme is declared once so the verbosity self-documents:

screen.theme = Theme::DARK.with(active_border_color: Color::CYAN)

App-specific tokens

An app carries its own colors in #custom (frozen Hash{Symbol => Color}). Look them up with #[] (fail-fast on typos) and render with the generic #fg / #bg helpers; subclass for semantic readers (Data#with keeps the subclass). Pair dark/light variants in a ThemeDef for Screen#theme_def=.

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"

class AppTheme < Tuile::Theme
def accent(text) = fg(:accent, text)
end

For a color slot resolved live at paint — currently Component#bg_color= — assign a Ref instead of reading + rebuilding the token in Component#on_theme_changed; it tracks theme swaps on its own. Baked content colors (Component::Label text and friends) can't: they live in a frozen StyledString and still need the hook.

Defined Under Namespace

Classes: Ref

Constant Summary collapse

CHROME_TOKENS =

The built-in chrome color tokens — every Data member bar #custom. A Ref resolves a name in this set as the chrome color; anything else as a #custom token.

Returns:

  • (Array<Symbol>) 
(members - %i[custom]).freeze
DARK =

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).

Returns:

new(active_bg_color: Color::GREY37,
active_border_color: Color::GREEN,
input_bg_color: Color::GREY27,
hint_color: Color::LIGHT_SKY_BLUE3)
LIGHT =

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.

Returns:

new(active_bg_color: Color::GREY82,
active_border_color: Color::GREEN,
input_bg_color: Color::GREY85,
hint_color: Color::TURQUOISE4)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(active_bg_color:, active_border_color:, input_bg_color:, hint_color:, custom: {}) ⇒ Object

@param active_bg_color

@param active_border_color

@param input_bg_color

@param hint_color

@param custom — app-specific tokens, see #custom.



85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/tuile/theme.rb', line 85

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

Instance Attribute Details

#active_bg_color ⇒ Color (readonly)

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.

Returns:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/tuile/theme.rb', line 77

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)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#on_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # 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

#active_border_color ⇒ Color (readonly)

Foreground of a Component::Window border when the window is on the active (focus) chain.

Returns:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/tuile/theme.rb', line 77

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)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#on_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # 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

#custom ⇒ ::Hash[Symbol, Color] (readonly)

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.

Returns:

  • (::Hash[Symbol, Color]) 


77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/tuile/theme.rb', line 77

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)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#on_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # 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

#hint_color ⇒ Color (readonly)

Foreground of keyboard-shortcut captions in status-bar hints (the "quit" in "q quit") — see #hint.

Returns:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/tuile/theme.rb', line 77

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)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#on_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # 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

#input_bg_color ⇒ Color (readonly)

Resting background "well" of Component::TextField / Component::TextArea when not active — visibly a field, but distinctly subtler than #active_bg_color.

Returns:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/tuile/theme.rb', line 77

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)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#on_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # 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

Class Method Details

.chrome_token?(name) ⇒ Boolean

@param name — a token name.

@return — true iff name is a built-in chrome token (see CHROME_TOKENS) rather than a #custom one.

Parameters:

  • name (Symbol)

Returns:

  • (Boolean) 


114
 
# File 'lib/tuile/theme.rb', line 114

def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

.ref(name) ⇒ Ref

Builds a Ref — a live theme reference for a late-resolved color slot like Component#bg_color=. Sugar for Theme::Ref.new(name).

@param name — a built-in chrome token (#input_bg_color etc.) or a #custom token name.

Parameters:

  • name (Symbol)

Returns:



121
 
# File 'lib/tuile/theme.rb', line 121

def self.ref(name) = Ref.new(name)

Instance Method Details

#[](token) ⇒ Color

Looks up an app-specific token from #custom.

@param token

Parameters:

  • token (Symbol)

Returns:



103
 
# File 'lib/tuile/theme.rb', line 103

def [](token) = custom.fetch(token)

#active_bg(text) ⇒ String

Renders text on the #active_bg_color background.

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • text (String)

Returns:

  • (String) 


176
 
# File 'lib/tuile/theme.rb', line 176

def active_bg(text) = wrap(text, active_bg_color, :bg)

#active_border(text) ⇒ String

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

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • text (String)

Returns:

  • (String) 


183
 
# File 'lib/tuile/theme.rb', line 183

def active_border(text) = wrap(text, active_border_color, :fg)

#bg(token, text) ⇒ String

Renders text on the background color of the app-specific token — the generic counterpart of #active_bg for #custom tokens.

@param token

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • token (Symbol)
  • text (String)

Returns:

  • (String) 


171
 
# File 'lib/tuile/theme.rb', line 171

def bg(token, text) = wrap(text, self[token], :bg)

#fg(token, text) ⇒ String

Renders text in the foreground color of the app-specific token — the generic counterpart of #hint for #custom tokens.

@param token

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • token (Symbol)
  • text (String)

Returns:

  • (String) 


163
 
# File 'lib/tuile/theme.rb', line 163

def fg(token, text) = wrap(text, self[token], :fg)

#hint(text) ⇒ String

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

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • text (String)

Returns:

  • (String) 


197
 
# File 'lib/tuile/theme.rb', line 197

def hint(text) = wrap(text, hint_color, :fg)

#input_bg(text) ⇒ String

Renders text on the #input_bg_color background.

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • text (String)

Returns:

  • (String) 


188
 
# File 'lib/tuile/theme.rb', line 188

def input_bg(text) = wrap(text, input_bg_color, :bg)

#wrap(text, color, target) ⇒ String

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

@param color

@param target — :fg or :bg.

Parameters:

  • text (String)
  • color (Color)
  • target (Symbol)

Returns:

  • (String) 


235
236
237
 
# File 'lib/tuile/theme.rb', line 235

def wrap(text, color, target)
  "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
end