Skip to content

Circular Progress Indicator Specification

Jump to bottom
Teodosia Hristodorova edited this page Jan 19, 2022 · 22 revisions

Circular Progress Indicator Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Accessibility
  6. Assumptions and Limitations
  7. References

Owned by

Team Name: Astrea

Developer Name:

Designer Name:

Requires approval from

  • Peer Developer Name | Date:
  • Design Manager Name | Date:

Signed off by

  • Radoslav Mirchev| Date:
  • Radoslav Karaivanov | Date:

Revision History

Version Users Date Notes
1

1. Overview

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 bar 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.

Objectives

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.

Acceptance criteria

  • 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 indicator's value and max value must be configurable through the API.
  • The indicator's text which shows its progress should be able to change its state to hidden.
  • The circular progress indicator should provide an indeterminate mode to indicate an operation that is not clear how long will be needed until completion.

2. User Stories

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.
  • 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.
<igc-circular-progress-indicator indeterminate>   
</igc-circular-progress-indicator>

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.

3. Functionality

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

3.1. End-User Experience The circular progress indicator should always fill from 0% to 100% in a clockwise direction and never decrease in value.

3.2. Developer Experience

  • Developers are able to specify the value and max value of the circular progress indicator via the exposed value and max properties.
  • Developers could show/hide the text displayed inside of the indicator via the textVisibility property.

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

The end-user must not be able to change the circular progress bar value, max and size.

3.5. API

IgcCircularProgressIndicatorComponent Properties

Name Description Type Default value Reflected
value Get/Set the value that indicates the completed indicator position. Should be positive number in the range min - max. number true
max Get/Set the maximum fill range of the progress indicator. number 100 true
text Get/Set the text to be displayed inside the indicator. string false
textVisibility Determines whether the text should be displayed inside of the progress indicator. boolean false true
valueInPercent Get/Set the value converted into percentage based on max value. number true
indeterminate Determines whether the progress indicator is in indeterminate state i.e. an infinitely looping loading progress. boolean false true
size The size of the progress indicator. small | medium | large small true

Methods

Name Description Return type Parameters
convertInPercentage Converts value into percentage based on passed number and max value. number value: number, max: number

Events

Name Description Cancelable Parameters
igcProgressChanged An event, which is triggered after a progress is changed. false {currentValue: number, previousValue: number}

Slots

Name Description
(default) Renders the progress indicator content.

CSS Parts

Name Description

4. Test Scenarios

  • 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 not change the value if the max value is updated.
  • Should update the value when we try to decrease it.
  • Should not update the value if we try to set not a valid number.
  • When passing string as value it should be parsed correctly.
  • The update step should be 1% of the maximum value in order to prevent slow updates with big numbers.
  • Value should not exceed the lower limit (0).
  • Value should not exceed the max limit.
  • Should follow the value representation if the update step is bigger than passed value the progress indicator.
  • Value should not be updated if the progress indicator mode is indeterminate.

5. Accessibility

ARIA Support

The circular bar has the progressbar role - https://www.w3.org/TR/wai-aria-1.1/#progressbar

RTL Support

6. Assumptions and Limitations

7. References

Clone this wiki locally