Function progressBar

Remarks

Behavior

• progress is clamped to [0, 1].
• Filled length = round(width * progress), remainder is unfilled.
• If gradient (≥ 2 stops) is provided, it colors the filled portion; otherwise color (if present) colors it uniformly. The unfilled portion is colored using ProgressBarOptions.bgColor (foreground on the emptyChar), which is usually invisible for spaces (see note in ProgressBarOptions.bgColor).
• If border is true, wraps the bar in [...].
• If showPercent is true, appends a space + Math.round(progress*100) + %.
• If label is provided, prefixes label + " " before the bar.

Unicode & width caveats

• The default "█" comes from Block Elements and generally renders as one cell, but fonts/terminals vary. :contentReference[oaicite:4]{index=4}
• Width and slicing are based on JavaScript code units. Grapheme clusters (emoji/ZWJ) or East Asian wide characters can misalign bars; for pixel-perfect alignment, segment by grapheme and compute display width with a wcwidth-style approach. :contentReference[oaicite:5]{index=5}

UX notes

• Showing percent improves perceived progress and reduces uncertainty; reserve spinners for unknown durations and short tasks (<~3s). :contentReference[oaicite:6]{index=6}

ANSI support

• Colors rely on SGR; truecolor uses ESC[38;2;r;g;bm/ESC[48;2;r;g;bm on supporting terminals. :contentReference[oaicite:7]{index=7}