Class: Charming::Components::ActivityIndicator

Inherits:
Charming::Component show all
Defined in:
lib/charming/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
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) ⇒ 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.

Raises:

  • (ArgumentError) 


46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/charming/components/activity_indicator.rb', line 46

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

Instance Attribute Details

#chars ⇒ Object (readonly)

Returns the value of attribute chars.



36
37
38
 
# File 'lib/charming/components/activity_indicator.rb', line 36

def chars
  @chars
end

#gradient ⇒ Object (readonly)

Returns the value of attribute gradient.



36
37
38
 
# File 'lib/charming/components/activity_indicator.rb', line 36

def gradient
  @gradient
end

#index ⇒ Object (readonly)

Returns the value of attribute index.



36
37
38
 
# File 'lib/charming/components/activity_indicator.rb', line 36

def index
  @index
end

#label ⇒ Object (readonly)

Returns the value of attribute label.



36
37
38
 
# File 'lib/charming/components/activity_indicator.rb', line 36

def label
  @label
end

#label_style ⇒ Object (readonly)

Returns the value of attribute label_style.



36
37
38
 
# File 'lib/charming/components/activity_indicator.rb', line 36

def label_style
  @label_style
end

#seed ⇒ Object (readonly)

Returns the value of attribute seed.



36
37
38
 
# File 'lib/charming/components/activity_indicator.rb', line 36

def seed
  @seed
end

#width ⇒ Object (readonly)

Returns the value of attribute width.



36
37
38
 
# File 'lib/charming/components/activity_indicator.rb', line 36

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.



70
71
72
73
74
 
# File 'lib/charming/components/activity_indicator.rb', line 70

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.



62
63
64
65
 
# File 'lib/charming/components/activity_indicator.rb', line 62

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