# xpl-progress-bar

The `xpl-progress-bar` component displays the progress of an operation, such as file uploads, form completion, or loading states. It supports multiple visual variants including default, success, error, and indeterminate states, with optional label and helper text.

## Usage

### Basic progress bar

```html
<xpl-progress-bar label="Uploading..." value="45"></xpl-progress-bar>
```

### With helper text

```html
<xpl-progress-bar
    label="Uploading file..."
    value="65"
    helper-text="2.4 MB of 5 MB">
</xpl-progress-bar>
```

### Error state

```html
<xpl-progress-bar
    label="Upload failed"
    value="30"
    variant="error"
    helper-text="Network error. Please check your connection.">
</xpl-progress-bar>
```

### Indeterminate loading

```html
<xpl-progress-bar label="Processing..." variant="indeterminate"></xpl-progress-bar>
```

### Small size

```html
<xpl-progress-bar value="60" size="sm"></xpl-progress-bar>
```

### Custom max value

```html
<xpl-progress-bar value="75" max="150" label="75 of 150 items"></xpl-progress-bar>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Standard progress bar with accent color fill. Shows a checkmark icon when value reaches max. |
| `success` | Explicit success state with positive color. Shows a checkmark icon. |
| `error` | Error state with negative color. Shows an error (x-mark) icon. Helper text is recommended for this state. |
| `indeterminate` | Used when the progress duration is unknown. Displays an animated sliding bar instead of a fill percentage. |

## Sizes

- `lg` (default): 6px height
- `sm`: 4px height

## Icon Mapping

The component automatically renders status icons based on the variant or completion state:

| State | xpl-icon name |
|-------|---------------|
| Complete (default variant when value equals max) | `circle-check-1` |
| Success variant | `circle-check-1` |
| Error variant | `circle-xmark-1` |

## Design Tokens

The following Apollo Foundation tokens are used by this component:

### Background Colors (Fill)
- `--xpl-background-accent-default` - Default variant fill
- `--xpl-background-accent-positive-bold` - Success/complete fill
- `--xpl-background-accent-negative-bold` - Error fill
- `--xpl-background-accent-neutral` - Track background

### Icon Colors
- `--xpl-icon-positive` - Success/complete icon
- `--xpl-icon-negative` - Error icon

### Text Colors
- `--xpl-text-default` - Label text
- `--xpl-text-subdued` - Helper text
- `--xpl-text-negative` - Error helper text

### Typography
- `--xpl-font-size-callout` - Label font size
- `--xpl-font-size-caption` - Helper text font size
- `--xpl-font-weight-normal` - Label and helper font weight

### Spacing & Sizing
- `--xpl-space-8` - Gap between elements
- `--xpl-size-025` (4px) - Small bar height
- `--xpl-size-0375` (6px) - Large bar height
- `--xpl-border-radius-full` - Bar border radius

## Accessibility

- **Determinate variants** (default, success, error) use the native HTML `<progress>` element, which provides:
  - Native `role="progressbar"` semantics
  - Automatic `aria-valuenow`, `aria-valuemin`, `aria-valuemax` handling
  - Native value/max API with built-in clamping
- **Indeterminate variant** uses a custom `<div role="progressbar">` since native `<progress>` indeterminate state cannot be styled cross-browser
- The `aria-label` is set from the `label` prop, or falls back to `'Progress'` when no label is provided

<!-- Auto Generated Below -->


## Properties

| Property     | Attribute     | Description                                                                    | Type                                                   | Default     |
| ------------ | ------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ | ----------- |
| `helperText` | `helper-text` | The helper text displayed below the progress bar (recommended for error state) | `string`                                               | `undefined` |
| `label`      | `label`       | The label text displayed above the progress bar                                | `string`                                               | `undefined` |
| `max`        | `max`         | The maximum value of the progress (mirrors native <progress> max attribute)    | `number`                                               | `100`       |
| `size`       | `size`        | The size of the progress bar height: sm = 4px, lg = 6px                        | `"lg" \| "sm"`                                         | `'lg'`      |
| `value`      | `value`       | The current value of the progress (mirrors native <progress> value attribute)  | `number`                                               | `0`         |
| `variant`    | `variant`     | The visual variant of the progress bar                                         | `"default" \| "error" \| "indeterminate" \| "success"` | `'default'` |


## Dependencies

### Depends on

- [xpl-icon](../xpl-icon)

### Graph
```mermaid
graph TD;
  xpl-progress-bar --> xpl-icon
  style xpl-progress-bar fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*