Skip to content

Rating Specification

Radoslav Karaivanov edited this page Jan 5, 2024 · 39 revisions

Rating Specification

Owned by

Team: Codex

Radoslav Karaivanov

Stefan Ivanov

Requires approval from

  • Developer | Date:
  • Design Manager: Svilen Dimchevsky | Date:

Signed off by

  • Product Owner: Radoslav Mirchev | Date: 11-Aug-2022
  • Platform Architect: Radoslav Karaivanov | Date:

Revision History

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

Overview

Rating provides insight regarding others' opinions and experiences, and can allow the user to submit a rating of their own.

Acceptance criteria

  1. The component should be identifiable via an attribute, like name.
  2. The component should represent a unit of information, like value.
  3. The component should provide a way to specify the maximum value that is possible to set.
  4. The component should provide a way to set a precision modifier to enable fraction values (e.g. 4.5 of 5).
  5. The component should provide a way to set the visual selection mode to single.
  6. The component should provide a way to customize the visual representation of the elements corresponding to rated states.
  7. The component should provide a way to be disabled.
  8. The component should provide a way to add a corresponding label.
  9. The component should be interacted via mouse/touch.
  10. The component should be interacted via keyboard.
  11. The component should be accessible.
  12. The component should abide by LTR/RTL layouts.
  13. The component should emit an event when its value changes.
  14. The component should emit an event for the currently hovered symbol when hover is enabled.
  15. The component should be able to be set to a "read-only" state, that gives rate information but does not allow interaction.

User Stories

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.

Functionality

Figma file

Size

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.

Selection

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

Value Label

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.

Developer Experience

<igc-rating max="10" value="3" label="Movie rating" hover-preview></igc-rating>

API

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

Properties

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.

Methods

Method Type Description
stepDown (n?: number): void Decrements the value of the control by n steps multiplied by
the step factor.
stepUp (n?: number): void Increments the value of the control by n steps multiplied by the
step factor.

Events

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.

CSS Shadow Parts

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.

Slots

Name Description
Default slot for projected symbols/icons.
value-label Slot for value-label.

igc-rating-symbol

Used when a custom icon/symbol/element needs to be passed to the igc-rating component.

Slots

Name Description
Default slot for projected full symbols/icons.
empty Default slot for projected empty symbols/icons.

Assumptions and limitations

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.

Test Scenarios

Automation

  • 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 igcChange event.
  • Changing the value via the value property doesn't fire the igcChange event.
  • Setting the readonly attribute disables value changes via keyboard and mouse.
  • Setting the disabled attribute disables value changes via keyboard and mouse & changes the component's look & feel.
  • The number of symbols shown is controlled by the max property.
  • Setting the hoverPreview property to true enables preview behavior on mouse over.
  • The size property 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.

Accessibility

Clone this wiki locally