-
Notifications
You must be signed in to change notification settings - Fork 4
Circular Progress Indicator Specification
Radoslav Karaivanov edited this page Mar 7, 2022
·
22 revisions
- Overview
- User Stories
- Functionality
- Test Scenarios
- Accessibility
- Assumptions and Limitations
- References
Team Name: Astrea
Developer Name: Martin Evtimov
Designer Name:
- Peer Developer Name | Date:
- Design Manager Stefan Ivanov| Date:
- Radoslav Mirchev| Date:
- Radoslav Karaivanov | Date: 2022-03-07
| Version | Users | Date | Notes |
|---|---|---|---|
| 1 |
The Circular Progress Indicator component provides the ability to display a round progress indicator and its state changes. The value property determines the load state. The size of the filled-in part is calculated as a percentage based on the current value vs the max value property. The default max value is 100. The circular progress indicator shows percentage value, does not interact with the end-user and is read-only, i.e. the user could not change its state or value.
The Circular Progress Indicator component is providing minimal API for the most common use cases, leaving maximum flexibility in the developer's hands. It shows the progression of a system operation such as downloading, uploading, processing, etc. in a visual way and can represent determinate or indeterminate progress.
- Have a determinate circular progress indicator that shows only increasing action.
- Have a circular progressive indicator that only increases in the clockwise direction starting from the position of 12 o’clock.
- The progress indicator must have a variant (Primary, Warning, Danger, Info, Success) changing its background color.
- The progress indicator must indicate the current state as a percentage and display it as such or any other way.
- The indicator's value and max value must be configurable through the API.
- The indicator's text which shows its progress should be templatable.
- The circular progress indicator should provide an indeterminate mode to indicate an operation that is not clear how long will be needed until completion.
Elaborate more on the multi-facetted use cases
Developer stories:
- Story 1: As a developer, I want to be able to display an infinitely looping loading progress for an action whose completion is unknown. This mode is achievable by a property on the Circular Progress Indicator and visually matches the Material Guidelines' indeterminate state.
<igc-circular-progress indeterminate> </igc-circular-progress>- Story 2: As a developer, I want to be able to display certain progress for a concrete action so that the end-users know how much of a task has been completed.
- Story 3: As a developer, I want to be able to implement determinate circular progress indicator visual styles so that I can integrate it better with the overall look and feel of the application.
- Story 4: As a developer, I want to be able to implement a circular progress indicator with starting position at 12 o’clock that increases in a clockwise direction.
- Story 5: As a developer, I would like to be able to change the duration of the progress animation.
- Story 6: As a developer, I would like to be able to define the indicator color as a gradient.
<igc-circular-progress>
<igc-circular-gradient slot="gradient" offset="0%" color="#ff9a40" opacity="0.5"></igc-circular-gradient>
<igc-circular-gradient slot="gradient" offset="50%" color="#1eccd4"></igc-circular-gradient>
<igc-circular-gradient slot="gradient" offset="100%" color="#ff0079"></igc-circular-gradient>
</igc-circular-progress>End-user stories:
- Story 1: As an end-user, I want to be given an indication for any process that is taking place behind the scenes and prevents me from making further actions until complete e.g. a remote data that is being loaded to populate the UI.
- Story 2: As an end-user, I want to be given a visual representation of how much a task or an action has been completed, so that I can be better informed about its state.
- Story 3: As an end-user, I want to have a circular progress indicator, so that it matches the overall look and feel of the application.
Describe behavior, design, look and feel of the implemented feature. Always include a visual mock-up
The circular progress indicator should always fill from 0% to 100% in a clockwise direction and never decrease in value.
- Developers are able to specify the value and max value of the circular progress indicator via the exposed
valueandmaxproperties.- Developers could re-template, show/hide the label of the indicator via the exposed
labelFormatandhideLabelproperties.- Developers are able to specify the progress type via the exposed
variantproperty.- Developers are able to specify the duration of the progress animation via the exposed
animationDurationproperty.- Developers are able to specify the progress as determinate or indeterminate via the exposed
indeterminateproperty.- Developers are able to specify the progress indicator color via the exposed gradient slot.
N/A
N/A
A circular progress indicator used to express unspecified wait time or display the length of a process.
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
animationDuration |
animation-duration |
number |
500 | Animation duration in milliseconds. |
hideLabel |
hide-label |
boolean |
false | Shows/hides the label of the control. |
indeterminate |
indeterminate |
boolean |
false | The indeterminate state of the control. |
labelFormat |
label-format |
string |
Format string for the default label of the control. Placeholders: {0} - current value of the control. {1} - max value of the control. |
|
max |
max |
number |
100 | Maximum value of the control. |
value |
value |
number |
0 | The value of the control. |
variant |
variant |
"primary" | "info" | "success" | "warning" | "danger" |
"primary" | The variant of the control. |
| Name | Description |
|---|---|
| (default) | The text area container. |
| gradient | Customize the progress bar in order to use a color gradient instead of a solid color. Accepts igc-circular-gradient elements. |
| Name | Description |
|---|---|
| svg | The progress SVG element. |
| gradient_start | The progress linear-gradient start color. |
| gradient_end | The progress linear-gradient end color. |
| track | The progress ring's track area. |
| fill | The progress indicator area. |
| label | The progress label. |
| value | The progress label value. |
| indeterminate | The progress indeterminate state. |
| primary | The progress indicator primary state. |
| danger | The progress indicator error state. |
| warning | The progress indicator warning state. |
| info | The progress indicator info state. |
| success | The progress indicator success state. |
Used for defining gradient stops in the igc-circular-progress.
For each igc-circular-gradient defined as gradient slot of igc-circular-progress element would be created a SVG stop element. The values passed as color, offset and opacity would be set as stop-color, offset and stop-opacity of the SVG element without further validations.
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
color |
color |
string |
"black" | Defines the color of the gradient stop. |
offset |
offset |
string |
"0%" | Defines where the gradient stop is placed along the gradient vector. |
opacity |
opacity |
number |
1 | Defines the opacity of the gradient stop. |
- The Circular Progress Indicator should be initialized correctly with default values.
- Should respond to passed values correctly.
- Should set the value to 0 for negative numbers.
- Should set the value to the maximum (default or custom max) if we try passing a value higher than the max.
- Should change the value to max if the max value is updated to a lower (or equal) value.
- Should not change the value if the max value is increased.
- Should update the value when we increase/decrease it.
- If the progress indicator mode is indeterminate and the value is updated, it should be displayed correctly when the mode is switched to determinate.
- Should handle animations correctly when toggling indeterminate mode.
- Should hide the default label when in indeterminate mode.
- Should show/hide the default label depending on the hideLabel property.
- The slotted label should not be affected by indeterminate and hideLabel properties.
- Should display the value properly depending on the labelFormat. If it is not set, the value should be displayed in percent.
- Should be able to define a gradient color using the igc-circular-gradient elements instead of solid via the exposed gradient slot.
- Animations should respect RTL mode.
- Should render proper aria attributes.
- Should respond to passed color, offset and opacity correctly.
- The SVG stop elements should have the same order as the defined igc-circular-gradient elements.
- The opacity should accept a number value. By default, its value is 1.
- The color and offset properties should accept string values.
- The update step should be 1% of the maximum value.
- Should correctly display the progress fill background based on the variant property.
ARIA Support
The circular indicator has the progress bar role - https://www.w3.org/TR/wai-aria-1.1/#progressbar
RTL Support The component should support and respond to RTL layout.