Rating Specification
Team: Codex
Radoslav Karaivanov
Stefan Ivanov
- Developer | Date:
- Design Manager: Svilen Dimchevsky | Date:
- Product Owner: Radoslav Mirchev | Date: 11-Aug-2022
- Platform Architect: Radoslav Karaivanov | Date:
| Version | Users | Date | Notes |
|---|---|---|---|
| 1 | Radoslav Karaivanov | 17-Nov-2021 | First draft version |
| 2 | Radoslav Karaivanov | 2-Dec-2021 | Updated specification |
| 3 | Radoslav Karaivanov | 21-Dec-2021 | Updated specification |
| 4 | Radoslav Karaivanov | 27-Jan-2022 | Updated specification |
| 5 | Radoslav Karaivanov | 14-Feb-2022 | Revised specification |
| 6 | Simeon Simeonoff | 15-Jul-2022 | Revised specification |
| 7 | Radoslav Karaivanov | 06-Jan-2024 | Revised specification |
Rating provides insight regarding others' opinions and experiences, and can allow the user to submit a rating of their own.
- The component should be identifiable via an attribute, like name.
- The component should represent a unit of information, like value.
- The component should provide a way to specify the maximum value that is possible to set.
- The component should provide a way to set a precision modifier to enable fraction values (e.g. 4.5 of 5).
- The component should provide a way to set the visual selection mode to single.
- The component should provide a way to customize the visual representation of the elements corresponding to rated states.
- The component should provide a way to be disabled.
- The component should provide a way to add a corresponding label.
- The component should be interacted via mouse/touch.
- The component should be interacted via keyboard.
- The component should be accessible.
- The component should abide by LTR/RTL layouts.
- The component should emit an event when its value changes.
- The component should emit an event for the currently hovered symbol when hover is enabled.
- The component should be able to be set to a "read-only" state, that gives rate information but does not allow interaction.
Developer stories:
- Story 1: As a developer, I want to define a rating component with a certain max value, so that users can choose from a controlled set of values.
- Story 2: As a developer, I want to have precision on the value, so that I can show aggregate values e.g. 4.5 of 5.
- Story 3: As a developer, I want to set the rating element visual, so that I can create various rating shapes e.g. stars, emojis, etc..
End-user stories:
- Story 1: As an end-user, I want to click on a rating element, so that I can provide a value e.g. have 5 stars and click on 4th one, to have the first four light up.
- Story 2: As an end-user, I want to click a second time on the end value of the rating, so that I can clear my choice.
- Story 3: As an end-user, I want to have a value label, so that I can read the exact value of the rating.
- Story 4: As an end-user, I want to hit the up/right or down/left arrows on my keyboard (directions are LTR), so that I can respectively increase or decrease the value.
The rating component should come in a default size where each of its elements will be 24x24 px (medium) with 2 px padding around it. It should be easy to change that element size e.g. to 18x18 px (small) or 36x36 px (large) in order to make it smaller or larger. The rating component supports label above the graphics and value label adjacent to the graphics, both of these are text elements.
Single-Selection
In this scenario, the component should react as a radio group, where only one of the icons/elements can be selected and reflect the feedback given by the end-user. There should be a possibility for the icons/elements to differ visually one from another so that they indicate the value they represent.
Continuous Selection
The end-user can select all icons/elements (1 to 5) and by that provide insight about the experience. In case the user selects icon/element 4, that should set all the previous icons/elements (1 to 3) to the selected mode as well. "Continuous Selection" allows the end-user to select a fraction of the icon/element.
allow-reset behavior
When allow-reset is set on the component, clicking on the same value will reset the current selection (i.e. set value to 0).
In case a value label is displayed, the default value should be a numeric rate (1 to 5), equal to the value of the component. The value label should be able to be set to a custom text, e.g "good", "bad", "excellent" and so on.
<igc-rating max="10" value="3" label="Movie rating" hover-preview></igc-rating>Rating provides insight regarding others' opinions and experiences, and can allow the user to submit a rating of their own
Mixins: SizableMixin, EventEmitterMixin
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
allowReset |
allow-reset |
boolean |
false | Whether to reset the rating when the user selects the same value. |
disabled |
disabled |
boolean |
false | Sets the disabled state of the component |
hoverPreview |
hover-preview |
boolean |
false | Sets hover preview behavior for the component |
label |
label |
string |
The label of the control. | |
max |
max |
number |
5 | The maximum value for the rating |
name |
name |
string |
The name attribute of the control | |
readonly |
readonly |
boolean |
false | Sets the readonly state of the component |
size |
size |
"small" | "medium" | "large" |
"medium" | Determines the size of the component. |
step |
step |
number |
1 | The minimum value change allowed. |
single |
single |
boolean |
false | Enables single selection mode and sets the step to 1. |
value |
value |
number |
0 | The current value of the component |
valueFormat |
value-format |
string |
A format string which sets aria-valuetext. All instances of '{0}' will be replaced with the current value of the control. Important for screen-readers and useful for localization. |
| Method | Type | Description |
|---|---|---|
stepDown |
(n?: number): void |
Decrements the value of the control by n steps multiplied bythe step factor. |
stepUp |
(n?: number): void |
Increments the value of the control by n steps multiplied by thestep factor. |
| Event | Description |
|---|---|
igcChange |
Emitted when the value of the control changes. |
igcHover |
Emitted when hover is enabled and the user mouses over a symbol of the rating. |
| Part | Description |
|---|---|
base |
The main wrapper which holds all of the rating elements. |
symbols |
The main wrapper which holds all individual symbol elements. |
symbol |
The symbol element. |
full |
The full symbol element. |
empty |
The full symbol element. |
label |
The label element. |
value-label |
The value label element. |
| Name | Description |
|---|---|
| Default slot for projected symbols/icons. | |
value-label |
Slot for value-label. |
Used when a custom icon/symbol/element needs to be passed to the igc-rating component.
| Name | Description |
|---|---|
| Default slot for projected full symbols/icons. | |
empty |
Default slot for projected empty symbols/icons. |
When custom content is provided by projecting it through the igc-rating-symbol, the max property of the rating component is set to follow the number of the declared rating symbols children.
The igc-rating-symbol expects two icons/symbols - one for the full(filled) state and one for the empty state.
<igc-rating-symbol>
<igc-icon collection="internal" name="star"></igc-icon>
<igc-icon collection="internal" name="star_border" slot="empty"></igc-icon>
</igc-rating-symbol>Thus changing it programmatically has not effect.
The max property will update automatically when igc-rating-symbols are added/removed from the DOM.
- The component is successfully initialized with default property values.
- The component is initialized successfully with passed property values.
- The component handles gracefully invalid values (negative numbers, out-of-bounds numbers).
- Fractional values are reflected properly with not fully filled symbol.
- Value is properly changed via mouse click.
- Value is increased by one via arrow up and arrow right keys.
- Value is decreased by one via arrow down and arrow left keys.
- Pressing the Home key changes the value to min value.
- Pressing the End key changes the value to max value.
- Changing the value via mouse and keyboard fires the
igcChangeevent. - Changing the value via the
valueproperty doesn't fire theigcChangeevent. - Setting the
readonlyattribute disables value changes via keyboard and mouse. - Setting the
disabledattribute disables value changes via keyboard and mouse & changes the component's look & feel. - The number of symbols shown is controlled by the
maxproperty. - Setting the
hoverPreviewproperty to true enables preview behavior on mouse over. - The
sizeproperty successfully changes icons' sizes and spacing between them. - The component supports setting a different symbol at each position.
- The component supports single selection mode.
- The component is included in IgcFormComponent's _controlsWithValue list.
- The aria-labelledby, aria-valuemin, aria-valuemax and aria-valuenow aria attributes are properly initialized.
- role - slider
- aria-labelledby
- aria-valuemin
- aria-valuemax
- aria-valuenow