Class: Charming::Components::ActivityIndicator

Inherits:
Charming::Component show all
Defined in:
lib/charming/presentation/components/activity_indicator.rb

Overview

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.

Constant Summary collapse

DEFAULT_CHARS =

Default character pool used for generating each position’s character via stable hashing.

"0123456789abcdefABCDEF~!@#$%^&*+=_".chars.freeze
DEFAULT_GRADIENT =

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.

["#ff0000", "#6FD0E3"].freeze
DEFAULT_LABEL_COLOR =

The default label color for ellipsis and text portions when no custom label_style is provided.

"#cccccc"
ELLIPSIS_FRAMES =

Ellipsis frame sequence: four states cycle through “., ”..“, ”…“, and ”“ (empty).

[".", "..", "...", ""].freeze
MIN_FITTED_INDICATOR_WIDTH =

Minimum bar width reserved when deciding whether a long label can fit before falling back.

4
FRAME_COUNT =

Number of frames in the animation cycle before the indicator pattern repeats.

10
FNV_OFFSET =

FNV-1a variant constants used by stable_hash for reproducible character selection per position.

2_166_136_261
FNV_PRIME = 
16_777_619
FNV_MASK = 
0xffffffff

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from View

#focused?, #layout_assigns

Constructor Details

#initialize(width: 10, label: nil, index: 0, seed: 0, chars: DEFAULT_CHARS, gradient: DEFAULT_GRADIENT, label_style: nil, max_width: nil, fallback_label: nil) ⇒ ActivityIndicator

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.

Raises:

  • (ArgumentError) 


51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 51

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

Instance Attribute Details

#chars ⇒ Object (readonly)

Returns the value of attribute chars.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def chars
  @chars
end

#fallback_label ⇒ Object (readonly)

Returns the value of attribute fallback_label.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def fallback_label
  @fallback_label
end

#gradient ⇒ Object (readonly)

Returns the value of attribute gradient.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def gradient
  @gradient
end

#index ⇒ Object (readonly)

Returns the value of attribute index.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def index
  @index
end

#label ⇒ Object (readonly)

Returns the value of attribute label.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def label
  @label
end

#label_style ⇒ Object (readonly)

Returns the value of attribute label_style.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def label_style
  @label_style
end

#max_width ⇒ Object (readonly)

Returns the value of attribute max_width.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def max_width
  @max_width
end

#seed ⇒ Object (readonly)

Returns the value of attribute seed.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def seed
  @seed
end

#width ⇒ Object (readonly)

Returns the value of attribute width.



39
40
41
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 39

def width
  @width
end

Instance Method Details

#render ⇒ Object

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.



77
78
79
80
81
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 77

def render
  return indicator unless label

  "#{indicator} #{styled_label}#{styled_ellipsis}"
end

#tick(count = 1) ⇒ Object

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.



69
70
71
72
 
# File 'lib/charming/presentation/components/activity_indicator.rb', line 69

def tick(count = 1)
  @index += count.to_i
  self
end