fix: clamp ProgressBar barLength to non-negative value to avoid crash

[ErwanLegrand]

A negative progress value (e.g. from a race in progress events) would produce a negative barLength and crash inside String(repeating:count:). Wrap the computed length in max(0, ...) and add a regression test that calls set(size: -10) and exercises draw(state:detail:).

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

This fixes an Apple container crash

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

[jglogan]

@dkovba I'd welcome suggestions on how to make this more readable. The clamp makes sense in terms of preventing a negative bar length, but the way it's written, it's pretty complicated to reason about.

There is no need to include the entire thing in the clamp since remainingWidth is already guaranteed to be greater than 1.

The value Int(Int64(remainingWidth) * value / total)) should be extracted to its own let assignment with a constant name that makes sense.

This would make more sense to me if we did something like:

// reserve spaces between components, plus 45 for components rendered after the bar (size, speed, time, etc.)
let reservedWidth = (useColor ? joinedComponents.visibleLength : joinedComponents.count) + 45
let completedBarWidth = max(config.width - usedWidth, 1)
let progressWidth = max(0, Int(Int64(completedBarWidth) * value / total))
let currentBarWidth: Int
if state.finished {
    currentBarWidth = completedBarWidth
} else {
    currentBarWidth = min(completedBarWidth, progressWidth)
}

[jglogan]

Fix looks good but let's make the logic a little more readable. Thanks!

[github-actions]

Code Coverage

Tier	Line Coverage
Unit	33.3%
Integration	20.43%
Combined	53.15%