Rating Specification

Rating Specification

• Rating Specification
  • Owned by
  • Requires approval from
  • Signed off by
  • Revision History
  • Overview
    • Acceptance criteria
  • User Stories
  • Functionality
    • End-User Experience
    • Developer Experience
  • API
• igc-rating
  • Properties
  • Events
    • Methods
    • Slots
    • CSS Parts
  • Assumptions and limitations
  • Test Scenarios
    • Automation
  • Accessibility

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: 16-May-2022
• Platform Architect: Damyan Petev | 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	Finalized 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 precision modifier to enable fraction values (e.g. 4.5 of 5).
5. The component should provide a way to customize the visual representation of the elements corresponding to rated states.
6. The component should provide a way to be disabled.
7. The component should provide a way to add a corresponding label.
8. The component should be interacted via mouse/touch.
9. The component should be interacted via keyboard.
10. The component should be accessible.
11. The component should abide by LTR/RTL layouts.
12. The component should emit an event when its value changes.
13. The component should emit an event for the currently hovered symbol when hover is enabled.

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

End-User Experience

The rating component should come in a default size where each of its elements will be 24x24 px with padding around it shown on the image below and the provided link. It should be easy to change that element size e.g. to 18x18 or 36x36 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.

It should be possible to set an individual value to every rating element to achieve scenarios like in the following feedback form of the App Builder

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
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"	"large"	Determines the size of the component.
step	step	number	1	The minimum value change allowed.
symbol	symbol	string	"⭐"	The symbol which the rating will display.
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.

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 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. 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 is included in IgcFormComponent's _controlsWithValue list.
• The aria-labelledby, aria-valuemin, aria-valuemax and aria-valuenow aria attributes are properly initialized.

Accessibility

• role - slider
• aria-labelledby
• aria-valuemin
• aria-valuemax
• aria-valuenow