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 Charming::Component

#captures_text?

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