charming 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bc5c3942786d07631d42361391e76f4f42275cc472c8ff7e37669880263b978
-  data.tar.gz: b6dc9eef28cf8eb6849a9ae34a4af8e6902a0e263529762cce9a3e591ed06396
+  metadata.gz: dc7f17fae2c6012942e00a20986ee7928b3f1a71e9d6fcb4a9855439e1281fd3
+  data.tar.gz: 63d288c1cbecc5830b2c1d3cfece4d0a15a58241ee9b6e130d6ea13c9256767f
 SHA512:
-  metadata.gz: e772a624b0f4a51d722ed40863bfae85161ac9bc1b508d7accb6cc7a4fc8f30352a79b66a9d42416992d38477c145f5ecc55c953b77aca1cf787a03a5f2f0e64
-  data.tar.gz: 61dc03c8e8ade6e62fbc86c6f76e382063cc13aa1f60cc8afa161f6a646d1e4836483f9ca9a2e8446881f5b5a65d4b8e5107e39300c5844034dbbcb33f37a47f
+  metadata.gz: 374717171efb3639c11cd96748fb41e02a9bff74ec3c7e2325770d90f5b5db193df8c7ebaca1e73dffcf597f1e14fc3af6971d8cf9780026dbe5b3db6513cebd
+  data.tar.gz: 1870fb231844e57394d0412de0a752d1927a8bf6c4347daff86d26bed96c4226744f9cc26a9fe8ce0992b7bb604e87a4763b3747ad0ea58a56876cf59f2692bf

data/lib/charming/application.rb

@@ -37,9 +37,9 @@ module Charming
         raise ArgumentError, "theme expects either from: or built_in:, not both" if from && built_in
 
         themes[name.to_sym] = if built_in
-          Presentation::UI::Theme.load_builtin(built_in)
+          UI::Theme.load_builtin(built_in)
         else
-          Presentation::UI::Theme.load_file(resolve_theme_path(from))
+          UI::Theme.load_file(resolve_theme_path(from))
         end
       end
 
@@ -60,7 +60,7 @@ module Charming
       # built-in theme if no name is given and no default is registered.
       def theme_for(name = nil)
         theme_name = name || default_theme
-        return Presentation::UI::Theme.default unless theme_name
+        return UI::Theme.default unless theme_name
 
         themes.fetch(theme_name.to_sym)
       end

data/lib/charming/controller/class_methods.rb

@@ -19,7 +19,7 @@ module Charming
       # Adds a CommandPalette entry with the given *label*. *action* is a method name to send on
       # the controller, or a block to instance_exec when selected.
       def command(label, action = nil, &block)
-        command_bindings << Presentation::Components::CommandPalette::Command.new(label: label, value: block || action)
+        command_bindings << Components::CommandPalette::Command.new(label: label, value: block || action)
       end
 
       # Declares a timer that fires every *every* seconds and dispatches *action* on the controller.
@@ -49,7 +49,7 @@ module Charming
       end
 
       # Sets or returns the controller's layout. Pass a layout class (instantiated per request),
-      # a String/Symbol template name (resolved through Presentation::Templates), or `false` to
+      # a String/Symbol template name (resolved through Templates), or `false` to
       # disable inherited layout wrapping. Called with no arguments returns the resolved layout.
       def layout(layout_class = :__charming_layout_reader__)
         return resolved_layout if layout_class == :__charming_layout_reader__

data/lib/charming/controller/command_palette.rb

@@ -70,7 +70,7 @@ module Charming
 
       # Constructs the CommandPalette widget with a *commands* list and persisted *state* hash.
       def build_command_palette_with_state(commands, state, placeholder: "Search commands", height: nil)
-        Presentation::Components::CommandPalette.new(
+        Components::CommandPalette.new(
           commands: commands,
           placeholder: placeholder,
           height: height,
@@ -112,7 +112,7 @@ module Charming
       # Returns the theme-switching commands used by the theme picker palette.
       def theme_commands
         application.class.themes.keys.map do |name|
-          Presentation::Components::CommandPalette::Command.new(label: theme_label(name), value: -> { use_theme(name) })
+          Components::CommandPalette::Command.new(label: theme_label(name), value: -> { use_theme(name) })
         end
       end
 

data/lib/charming/controller/rendering.rb

@@ -55,12 +55,12 @@ module Charming
 
       # Resolves a template by *name* and returns a TemplateView bound to the application's namespace.
       def template_body(name, **assigns)
-        Presentation::TemplateView.new(template: resolve_template(name), namespace: template_namespace, **template_assigns(assigns))
+        TemplateView.new(template: resolve_template(name), namespace: template_namespace, **template_assigns(assigns))
       end
 
       # Looks up the template file under `app/views` relative to the application root.
       def resolve_template(name)
-        Presentation::Templates.resolve(name, root: application.class.root)
+        Templates.resolve(name, root: application.class.root)
       end
 
       # Returns the assigns hash passed to templates: `screen:`, `controller:`, `theme:` plus user *assigns*.

data/lib/charming/controller/session_state.rb

@@ -25,7 +25,7 @@ module Charming
       def form(name, &block)
         session[:forms] ||= {}
         form_state = session[:forms][name.to_sym] ||= {}
-        builder = Presentation::Components::Form::Builder.new(theme: theme)
+        builder = Components::Form::Builder.new(theme: theme)
         block.arity.zero? ? builder.instance_eval(&block) : block.call(builder)
         builder.build(state: form_state, theme: theme)
       end

data/lib/charming/generators/component_generator.rb

@@ -3,7 +3,7 @@
 module Charming
   module Generators
     # ComponentGenerator implements `charming generate component NAME`. Writes a
-    # `Charming::Presentation::Component` subclass to `app/components/<name>_component.rb`.
+    # `Charming::Component` subclass to `app/components/<name>_component.rb`.
     class ComponentGenerator < AppFileGenerator
       # Writes the component file to the standard `app/components` path.
       def generate

data/lib/charming/generators/templates/app/application.template

@@ -4,7 +4,7 @@ module __APP_CLASS__
   class Application < Charming::Application
     root File.expand_path("../..", __dir__)
 
-    Charming::Presentation::UI::Theme.built_in_names.each do |theme_name|
+    Charming::UI::Theme.built_in_names.each do |theme_name|
       theme theme_name.to_sym, built_in: theme_name
     end
 

data/lib/charming/generators/templates/app/layout.template

@@ -2,7 +2,7 @@
 
 module __APP_CLASS__
   module Layouts
-    class ApplicationLayout < Charming::Presentation::View
+    class ApplicationLayout < Charming::View
       def render
         screen_layout(background: theme.background) do
           split(narrow? ? :vertical : :horizontal, gap: 1) do
@@ -54,7 +54,7 @@ module __APP_CLASS__
       def nav_item_label(route, index)
         cursor = (sidebar_focused? && index == sidebar_index) ? ">" : " "
         active = current_route?(route) ? "\u{25cf}" : " "
-        "\#{cursor} \#{active} \#{route.title}"
+        "#{cursor} #{active} #{route.title}"
       end
 
       def nav_item_style(route, index)
@@ -84,11 +84,8 @@ module __APP_CLASS__
       def command_palette_modal
         return unless palette_component
 
-        render_component Charming::Presentation::Components::Modal.new(
+        render_component Charming::Components::CommandPaletteModal.new(
           content: palette_component,
-          title: "Command palette",
-          help: "Type to filter. Enter selects. Escape closes.",
-          width: 52,
           theme: theme
         )
       end

data/lib/charming/generators/templates/app/view.template

@@ -2,7 +2,7 @@
 
 module __APP_CLASS__
   module Home
-    class ShowView < Charming::Presentation::View
+    class ShowView < Charming::View
       def render
         column(title_line, help_line, gap: 1)
       end

data/lib/charming/generators/templates/component/component.rb.template

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module __APP_CLASS__
-  class __COMPONENT_CLASS__ < Charming::Presentation::Component
+  class __COMPONENT_CLASS__ < Charming::Component
     def render
       text "__RESOURCE_NAME__"
     end

data/lib/charming/generators/templates/screen/view.rb.template

@@ -2,7 +2,7 @@
 
 module __APP_CLASS__
   module __RESOURCE_MODULE__
-    class ShowView < Charming::Presentation::View
+    class ShowView < Charming::View
       def render
         __SCREEN_NAME__.title
       end

data/lib/charming/generators/templates/view/view.rb.template

@@ -2,7 +2,7 @@
 
 module __APP_CLASS__
   module __RESOURCE_MODULE__
-    class __ACTION_VIEW_CLASS__View < Charming::Presentation::View
+    class __ACTION_VIEW_CLASS__View < Charming::View
       def render
         "__RESOURCE_NAME__"
       end

data/lib/charming/internal/renderer/differential.rb

@@ -27,6 +27,12 @@ module Charming
           render_changes(frame)
         end
 
+        # Discards the cached previous frame so the next render performs a full repaint.
+        # Call this when the screen contents are no longer trustworthy (e.g. terminal resize).
+        def invalidate
+          @previous_frame = nil
+        end
+
         private
 
         # Performs the initial full repaint and records the first frame.
@@ -35,7 +41,7 @@ module Charming
           @previous_frame = frame
         end
 
-        # Computes the per-line diff against the previous frame, writes the changed lines,
+        # Computes the per-line diff against the previous frame, writes only changed lines,
         # and records the new frame. Falls back to a full repaint when the output backend
         # doesn't support partial writes.
         def render_changes(frame)
@@ -50,15 +56,17 @@ module Charming
           @previous_frame = frame
         end
 
-        # Returns an array of [1-based-row, line] tuples covering the larger of the two
-        # frames' line counts, with empty strings padding the shorter frame.
+        # Returns an array of [1-based-row, line] tuples for rows whose content changed.
+        # Empty strings clear rows that existed in the previous frame but not the new one.
         def changed_lines(previous_frame, frame)
           previous_lines = previous_frame.lines(chomp: true)
           lines = frame.lines(chomp: true)
           line_count = [previous_lines.length, lines.length].max
 
-          line_count.times.map do |index|
-            [index + 1, lines[index] || ""]
+          line_count.times.filter_map do |index|
+            line = lines[index] || ""
+            previous_line = previous_lines[index] || ""
+            [index + 1, line] unless line == previous_line
           end
         end
       end

data/lib/charming/internal/terminal/tty_backend.rb

@@ -51,6 +51,20 @@ module Charming
           nil
         end
 
+        # Keeps terminal input in raw/no-echo mode for the duration of a TUI run. Reading a
+        # single keypress in raw mode is not enough: keys pressed while rendering or dispatching
+        # events can otherwise be echoed into the alternate screen before the next read.
+        def with_raw_input
+          return yield unless @input.respond_to?(:tty?) && @input.tty?
+          return yield unless @input.respond_to?(:raw) && @input.respond_to?(:noecho)
+
+          @input.raw do
+            @input.noecho do
+              yield
+            end
+          end
+        end
+
         # Installs a SIGWINCH handler that sets the internal `@resized` flag, returning
         # the previous handler so it can be restored on teardown.
         def install_resize_handler
@@ -120,7 +134,7 @@ module Charming
         # Writes a partial frame composed of [row, line] tuples (1-based rows).
         def write_lines(line_changes, **)
           without_auto_wrap do
-            write_control(line_changes.map { |row, line| "\e[#{row};1H\e[2K#{line}" }.join)
+            write_control(line_changes.map { |row, line| positioned_line(row, line) }.join)
           end
         end
 
@@ -180,7 +194,13 @@ module Charming
         # Writes *lines* one row at a time, with each line preceded by an ANSI cursor
         # position and a clear-to-end-of-line sequence.
         def write_positioned_lines(lines)
-          write_control(lines.each_with_index.map { |line, index| "\e[#{index + 1};1H\e[2K#{line}" }.join)
+          write_control(lines.each_with_index.map { |line, index| positioned_line(index + 1, line) }.join)
+        end
+
+        # Resets SGR before and after each row so partial repaint rows cannot inherit
+        # colors/backgrounds from the previous physical terminal line.
+        def positioned_line(row, line)
+          "\e[0m\e[#{row};1H\e[2K#{line}\e[0m"
         end
 
         # Disables auto-wrap, yields, then re-enables it and flushes the output.

data/lib/charming/presentation/component.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    # Component is the base class for all reusable terminal widgets. It inherits from View to gain assigns,
-    # helper methods (text, box, row, column, etc.), and rendering via render.
-    class Component < View
-    end
+  # Component is the base class for all reusable terminal widgets. It inherits from View to gain assigns,
+  # helper methods (text, box, row, column, etc.), and rendering via render.
+  class Component < View
   end
 end

data/lib/charming/presentation/components/activity_indicator.rb

@@ -1,158 +1,197 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      # ActivityIndicator renders a color-gradient progress or loading indicator
-      # as styled text. It produces a fixed-width row of characters whose colors
-      # interpolate between two gradient endpoints (or cycle through a single
-      # color). A label can be appended after the bar and an ellipsis that cycles
-      # through frames, useful for "loading" state display. Call `tick` to advance
-      # the frame counter, and call `render` to produce the styled output string.
-      class ActivityIndicator < Component
-        # Default character pool used for generating each position's character via stable hashing.
-        DEFAULT_CHARS = "0123456789abcdefABCDEF~!@#$%^&*+=_".chars.freeze
-
-        # The default two-color gradient applied across the bar width (red to cyan).
-        # The cyan endpoint mirrors the Phosphor theme palette's "cyan" token so the bar
-        # remains legible on Phosphor's dark navy background; gradient: accepts raw hex,
-        # so callers using a different theme should pass their own endpoints.
-        DEFAULT_GRADIENT = ["#ff0000", "#6FD0E3"].freeze
-
-        # The default label color for ellipsis and text portions when no custom
-        # label_style is provided.
-        DEFAULT_LABEL_COLOR = "#cccccc"
-
-        # Ellipsis frame sequence: four states cycle through "., "..", "...", and "" (empty).
-        ELLIPSIS_FRAMES = [".", "..", "...", ""].freeze
-
-        # Number of frames in the animation cycle before the indicator pattern repeats.
-        FRAME_COUNT = 10
-
-        # FNV-1a variant constants used by stable_hash for reproducible character selection per position.
-        FNV_OFFSET = 2_166_136_261
-        FNV_PRIME = 16_777_619
-        FNV_MASK = 0xffffffff
-
-        attr_reader :width, :label, :index, :seed, :chars, :gradient, :label_style
-
-        # Initializes a new ActivityIndicator with configurable visual parameters.
-        # width       — Display width of the gradient bar in characters (minimum 1). Default: 10.
-        # label       — Optional text label shown adjacent to the indicator.
-        # index       — Initial frame index for the ellipsis/frame animations. Default: 0.
-        # seed        — Hash seed that determines which characters appear at each position.
-        # chars       — Character pool to draw from (default is DEFAULT_CHARS).
-        # gradient    — Two-element array of hex color strings ["#rrggbb", "#rrggbb"] for interpolation.
-        # label_style — A Style object to use for rendering the label text; falls back to a gray foreground.
-        def initialize(width: 10, label: nil, index: 0, seed: 0, chars: DEFAULT_CHARS,
-          gradient: DEFAULT_GRADIENT, label_style: nil)
-          super()
-          raise ArgumentError, "chars cannot be empty" if chars.empty?
-
-          @width = [width.to_i, 1].max
-          @label = label
-          @index = index.to_i
-          @seed = seed
-          @chars = chars.map(&:to_s)
-          @gradient = gradient
-          @label_style = label_style
-        end
+  module Components
+    # ActivityIndicator renders a color-gradient progress or loading indicator
+    # as styled text. It produces a fixed-width row of characters whose colors
+    # interpolate between two gradient endpoints (or cycle through a single
+    # color). A label can be appended after the bar and an ellipsis that cycles
+    # through frames, useful for "loading" state display. Call `tick` to advance
+    # the frame counter, and call `render` to produce the styled output string.
+    class ActivityIndicator < Component
+      # Default character pool used for generating each position's character via stable hashing.
+      DEFAULT_CHARS = "0123456789abcdefABCDEF~!@#$%^&*+=_".chars.freeze
+
+      # The default two-color gradient applied across the bar width (red to cyan).
+      # The cyan endpoint mirrors the Phosphor theme palette's "cyan" token so the bar
+      # remains legible on Phosphor's dark navy background; gradient: accepts raw hex,
+      # so callers using a different theme should pass their own endpoints.
+      DEFAULT_GRADIENT = ["#ff0000", "#6FD0E3"].freeze
+
+      # The default label color for ellipsis and text portions when no custom
+      # label_style is provided.
+      DEFAULT_LABEL_COLOR = "#cccccc"
+
+      # Ellipsis frame sequence: four states cycle through "., "..", "...", and "" (empty).
+      ELLIPSIS_FRAMES = [".", "..", "...", ""].freeze
+
+      # Minimum bar width reserved when deciding whether a long label can fit before falling back.
+      MIN_FITTED_INDICATOR_WIDTH = 4
+
+      # Number of frames in the animation cycle before the indicator pattern repeats.
+      FRAME_COUNT = 10
+
+      # FNV-1a variant constants used by stable_hash for reproducible character selection per position.
+      FNV_OFFSET = 2_166_136_261
+      FNV_PRIME = 16_777_619
+      FNV_MASK = 0xffffffff
+
+      attr_reader :width, :label, :index, :seed, :chars, :gradient, :label_style, :max_width, :fallback_label
+
+      # Initializes a new ActivityIndicator with configurable visual parameters.
+      # width       — Display width of the gradient bar in characters (minimum 1). Default: 10.
+      # label       — Optional text label shown adjacent to the indicator.
+      # index       — Initial frame index for the ellipsis/frame animations. Default: 0.
+      # seed        — Hash seed that determines which characters appear at each position.
+      # chars       — Character pool to draw from (default is DEFAULT_CHARS).
+      # gradient    — Two-element array of hex color strings ["#rrggbb", "#rrggbb"] for interpolation.
+      # label_style    — A Style object to use for rendering the label text; falls back to a gray foreground.
+      # max_width      — Optional total display width cap for the indicator, label, and ellipsis.
+      # fallback_label — Optional shorter label used when the primary label cannot fit within max_width.
+      def initialize(width: 10, label: nil, index: 0, seed: 0, chars: DEFAULT_CHARS,
+        gradient: DEFAULT_GRADIENT, label_style: nil, max_width: nil, fallback_label: nil)
+        super()
+        raise ArgumentError, "chars cannot be empty" if chars.empty?
+
+        @width = [width.to_i, 1].max
+        @label = label
+        @index = index.to_i
+        @seed = seed
+        @chars = chars.map(&:to_s)
+        @gradient = gradient
+        @label_style = label_style
+        @max_width = max_width&.to_i
+        @fallback_label = fallback_label
+      end
 
-        # Advances the frame counter forward by +count+ steps, allowing the displayed pattern to change.
-        # Accepts an integer count (converted via +to_i+). Returns self for chaining.
-        def tick(count = 1)
-          @index += count.to_i
-          self
-        end
+      # Advances the frame counter forward by +count+ steps, allowing the displayed pattern to change.
+      # Accepts an integer count (converted via +to_i+). Returns self for chaining.
+      def tick(count = 1)
+        @index += count.to_i
+        self
+      end
 
-        # Renders the activity indicator as a styled string. If a label was provided,
-        # produces "bar ellipsis" alongside it; otherwise produces only the gradient bar.
-        # Returns a formatted string suitable for terminal rendering.
-        def render
-          return indicator unless label
+      # Renders the activity indicator as a styled string. If a label was provided,
+      # produces "bar ellipsis" alongside it; otherwise produces only the gradient bar.
+      # Returns a formatted string suitable for terminal rendering.
+      def render
+        return indicator unless label
 
-          "#{indicator} #{styled_label}#{styled_ellipsis}"
-        end
+        "#{indicator} #{styled_label}#{styled_ellipsis}"
+      end
 
-        private
+      private
 
-        # Renders the full gradient bar as an array of styled characters joined into a single string.
-        # Each character at +position+ is selected by hashing together seed, frame, and position —
-        # making the pattern stable across renders — then styled with the interpolated gradient color
-        # at that position.
-        def indicator
-          Array.new(width) { |position| styled_char(position) }.join
-        end
+      # Renders the full gradient bar as an array of styled characters joined into a single string.
+      # Each character at +position+ is selected by hashing together seed, frame, and position —
+      # making the pattern stable across renders — then styled with the interpolated gradient color
+      # at that position.
+      def indicator
+        Array.new(indicator_width) { |position| styled_char(position) }.join
+      end
 
-        # Selects a character for the bar at the given +position+, styles it with the gradient color
-        # interpolated for that position, and returns the result as a formatted string via +render+.
-        def styled_char(position)
-          style.foreground(color_at(position)).render(char_at(position))
-        end
+      # Selects a character for the bar at the given +position+, styles it with the gradient color
+      # interpolated for that position, and returns the result as a formatted string via +render+.
+      def styled_char(position)
+        style.foreground(color_at(position)).render(char_at(position))
+      end
 
-        # Chooses a character from self.chars by hashing seed:frame:position together with a stable
-        # FNV-1a hash. The resulting index is modulated against the character pool length, ensuring
-        # reproducible output across renders.
-        def char_at(position)
-          chars.fetch(stable_hash("#{seed}:#{frame}:#{position}") % chars.length)
-        end
+      # Chooses a character from self.chars by hashing seed:frame:position together with a stable
+      # FNV-1a hash. The resulting index is modulated against the character pool length, ensuring
+      # reproducible output across renders.
+      def char_at(position)
+        chars.fetch(stable_hash("#{seed}:#{frame}:#{position}") % chars.length)
+      end
 
-        # Renders the label text in its own style (or fallback gray color) via a Style renderer call.
-        def styled_label
-          label_style_or_default.render(label.to_s)
-        end
+      # Renders the label text in its own style (or fallback gray color) via a Style renderer call.
+      def styled_label
+        label_style_or_default.render(label_text)
+      end
 
-        # Renders an ellipsis frame (".", "..", "...", or empty) based on (index / 4) mod 4, styled with the label style.
-        def styled_ellipsis
-          label_style_or_default.render(ellipsis_frame)
-        end
+      # Renders an ellipsis frame (".", "..", "...", or empty) based on (index / 4) mod 4, styled with the label style.
+      def styled_ellipsis
+        label_style_or_default.render(ellipsis_frame)
+      end
 
-        # Returns the current ellipsis frame string: one of ".", "..", "...", "". Cycles through four frames per tick.
-        def ellipsis_frame
-          ELLIPSIS_FRAMES.fetch((index / 4) % ELLIPSIS_FRAMES.length)
-        end
+      # Returns the current ellipsis frame string: one of ".", "..", "...", "". Cycles through four frames per tick.
+      def ellipsis_frame
+        ELLIPSIS_FRAMES.fetch((index / 4) % ELLIPSIS_FRAMES.length)
+      end
 
-        # Returns the label style if set, otherwise produces a gray foreground style for fallback rendering.
-        def label_style_or_default
-          label_style || style.foreground(DEFAULT_LABEL_COLOR)
-        end
+      # Returns the label style if set, otherwise produces a gray foreground style for fallback rendering.
+      def label_style_or_default
+        label_style || style.foreground(DEFAULT_LABEL_COLOR)
+      end
 
-        # Interpolates between gradient[0] and gradient[1] at the fractional +position+ (0.0 to 1.0).
-        # Returns the first gradient color if width is 1; otherwise returns a blended hex string based on position.
-        def color_at(position)
-          return gradient.first unless width > 1
+      # Returns the label to render, using fallback_label when the primary label cannot fit
+      # alongside a minimal indicator and the widest ellipsis frame.
+      def label_text
+        return label.to_s unless use_fallback_label?
 
-          blend(gradient.first, gradient.last, position / (width - 1).to_f)
-        end
+        fallback_label.to_s
+      end
 
-        # Blends two hex colors by interpolating their red/green/blue components at fractional +amount+.
-        # Accepts strings like "#ff0000" and produces a new "#rrggbb" string.
-        def blend(start_hex, end_hex, amount)
-          start_rgb = rgb(start_hex)
-          end_rgb = rgb(end_hex)
-          mixed = start_rgb.zip(end_rgb).map { |from, to| (from + ((to - from) * amount)).round }
-          "#%02x%02x%02x" % mixed
-        end
+      # True when the primary label cannot fit within max_width even with a compact indicator.
+      def use_fallback_label?
+        return false unless max_width && fallback_label
 
-        # Decomposes a hex color string ("#rrggbb") into an array of three integers [r, g, b].
-        def rgb(hex)
-          value = hex.to_s.delete_prefix("#")
-          raise ArgumentError, "gradient colors must be #rrggbb" unless value.match?(/\A[0-9a-fA-F]{6}\z/)
+        fitted_width(label.to_s, MIN_FITTED_INDICATOR_WIDTH) > max_width
+      end
 
-          [value[0..1], value[2..3], value[4..5]].map { |part| part.to_i(16) }
-        end
+      # Returns the fitted indicator width after reserving room for label text and the widest ellipsis.
+      def indicator_width
+        return width unless max_width && label
 
-        # Advances the animation frame counter, wrapping around after +FRAME_COUNT+ (10) steps.
-        def frame
-          index % FRAME_COUNT
-        end
+        (max_width - label_width - 1 - widest_ellipsis_width).clamp(1, width)
+      end
+
+      def label_width
+        UI::Width.measure(label_text)
+      end
+
+      def fitted_width(text, indicator_width)
+        indicator_width + 1 + UI::Width.measure(text) + widest_ellipsis_width
+      end
+
+      def widest_ellipsis_width
+        @widest_ellipsis_width ||= ELLIPSIS_FRAMES.map { |frame| UI::Width.measure(frame) }.max
+      end
+
+      # Interpolates between gradient[0] and gradient[1] at the fractional +position+ (0.0 to 1.0).
+      # Returns the first gradient color if width is 1; otherwise returns a blended hex string based on position.
+      def color_at(position)
+        return gradient.first unless indicator_width > 1
+
+        blend(gradient.first, gradient.last, position / (indicator_width - 1).to_f)
+      end
+
+      # Blends two hex colors by interpolating their red/green/blue components at fractional +amount+.
+      # Accepts strings like "#ff0000" and produces a new "#rrggbb" string.
+      def blend(start_hex, end_hex, amount)
+        start_rgb = rgb(start_hex)
+        end_rgb = rgb(end_hex)
+        mixed = start_rgb.zip(end_rgb).map { |from, to| (from + ((to - from) * amount)).round }
+        "#%02x%02x%02x" % mixed
+      end
+
+      # Decomposes a hex color string ("#rrggbb") into an array of three integers [r, g, b].
+      def rgb(hex)
+        value = hex.to_s.delete_prefix("#")
+        raise ArgumentError, "gradient colors must be #rrggbb" unless value.match?(/\A[0-9a-fA-F]{6}\z/)
+
+        [value[0..1], value[2..3], value[4..5]].map { |part| part.to_i(16) }
+      end
+
+      # Advances the animation frame counter, wrapping around after +FRAME_COUNT+ (10) steps.
+      def frame
+        index % FRAME_COUNT
+      end
 
-        # Produces a deterministic integer hash from the input string using FNV-1a hashing, ensuring the same
-        # characters appear at the same positions across multiple renderings of this indicator.
-        def stable_hash(value)
-          value.bytes.reduce(FNV_OFFSET) do |hash, byte|
-            ((hash ^ byte) * FNV_PRIME) & FNV_MASK
-          end
+      # Produces a deterministic integer hash from the input string using FNV-1a hashing, ensuring the same
+      # characters appear at the same positions across multiple renderings of this indicator.
+      def stable_hash(value)
+        value.bytes.reduce(FNV_OFFSET) do |hash, byte|
+          ((hash ^ byte) * FNV_PRIME) & FNV_MASK
         end
       end
     end