# ch-progress

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Use when](#use-when)
- [Do not use when](#do-not-use-when)
- [Accessibility](#accessibility)
- [Usage](./usage.md)
- [Properties](#properties)
- [Slots](#slots)
- [Styling](./styling.md)

<!-- Auto Generated Below -->

## Overview

The `ch-progress` component displays the progress status for long-running tasks, supporting both determinate and indeterminate modes

## Features
 - Determinate mode with explicit `min`, `max`, and `value`
 - Indeterminate mode for activities whose duration is unknown
 - Full WAI-ARIA `progressbar` pattern (`role`, `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`)
 - Validates accessible name via `accessibleName` or external `<label>`
 - Automatic `aria-busy` and `aria-describedby` management on a referenced loading region
 - Fully customizable rendering through `renderType` (default `"custom"` projects the slot with built-in accessibility)

## Use when
 - You need progress bars, loading spinners, or any indicator that represents ongoing work with measurable progress
 - An operation takes more than ~5 seconds and progress can be measured or approximated
 - Showing upload, download, file transfer, or installation progress

## Do not use when
 - You need a simple loading indicator without numeric progress (e.g., a spinner on a button) -- prefer `ch-status` instead
 - The operation completes in under 5 seconds — prefer a spinner (`ch-status`) instead
 - A determinate bar is used when actual progress cannot be calculated — it misleads users
 - Step-by-step wizard progress is needed — use a stepper/progress-indicator pattern instead

## Accessibility
 - `role="progressbar"` is set on the host element in `connectedCallback`
 - `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext` are managed dynamically on every render based on the current `min`, `max`, `value`, and `indeterminate` properties
 - In indeterminate mode, ALL `aria-value*` attributes are omitted per the ARIA specification
 - Resolves its accessible name from an external `<label>` element or the `accessibleName` property
 - `aria-busy` and `aria-describedby` are set on the `loadingRegionRef` element while the progress is active, and cleaned up when complete or disconnected
 - No keyboard interaction — the component is a passive indicator, not an interactive control

## Properties

| Property              | Attribute               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Type          | Default     |
| --------------------- | ----------------------- |   | ------------- | ----------- |
| `accessibleName`      | `accessible-name`       | Specifies a short string, typically 1 to 3 words, that authors associate with an element to provide users of assistive technologies with a label for the element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `string`      | `undefined` |
| `accessibleValueText` | `accessible-value-text` | Assistive technologies often present the `value` as a percentage. If this would not be accurate use this property to make the progress bar value understandable.  The string must contain literal token placeholders (`{{PROGRESS_VALUE}}`, `{{PROGRESS_MAX_VALUE}}`, `{{PROGRESS_MIN_VALUE}}`) — these are replaced at render time. Do NOT use JavaScript template literals; pass a plain string with the token text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `string`      | `undefined` |
| `indeterminate`       | `indeterminate`         | Specifies whether the progress is indeterminate or not. In other words, it indicates that an activity is ongoing with no indication of how long it is expected to take.  If `true`, the `max`, `min` and `value` properties won't be taken into account. All `aria-value*` attributes (`aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`) are omitted from the host element, and the component is always considered "in progress" regardless of `value`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `boolean`     | `false`     |
| `loadingRegionRef`    | --                      | If the control is describing the loading progress of a particular region of a page, set this property with the reference of the loading region. This will set the `aria-describedby` and `aria-busy` attributes on the loading region to improve the accessibility while the control is in progress.  When the control detects that is no longer in progress (aka it is removed from the DOM or value === maxValue with indeterminate === false), it will remove the `aria-busy` attribute and update (or remove if necessary) the `aria-describedby` attribute.  If an ID is set prior to the control's first render, the control will use this ID for the `aria-describedby`. Otherwise, the control will compute a unique ID for this matter.  **Important**: If you are using Shadow DOM, take into account that the `loadingRegionRef` must be in the same Shadow Tree as this control. Otherwise, the `aria-describedby` binding won't work, since the control ID is not visible for the `loadingRegionRef`. | `HTMLElement` | `undefined` |
| `max`                 | `max`                   | Specifies the maximum value of progress. In other words, how much work the task indicated by the progress component requires.  Internally, `Math.max(min, max)` is applied so that `max >= min` is always enforced.  This property is not used if indeterminate === true.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `number`      | `100`       |
| `min`                 | `min`                   | Specifies the minimum value of progress.  This property is not used if indeterminate === true.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `number`      | `0`         |
| `renderType`          | `render-type`           | This property specifies how the progress will be rendered.  - `"custom"`: Useful for making custom renders of the progress. The    control doesn't render anything and only projects the content of the    default slot. Besides that, all specified properties are still used to    implement the control's accessibility.  Unknown values silently fall back to `"custom"` (default slot projection). This serves as an extension point for future render types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `string`      | `"custom"`  |
| `value`               | `value`                 | Specifies the current value of the component. In other words, how much of the task that has been completed.  The value is clamped between `min` and `max` for both display and ARIA purposes.  This property is not used if indeterminate === true.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `number`      | `0`         |

## Slots

| Slot | Description                                                                                                                                                                                  |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      | Default slot. Projected when `renderType === "custom"`. Use it to provide a fully custom visual representation of the progress while the component handles all ARIA semantics automatically. |

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


