Carousel Specification

Revision History
Objectives
User Stories
Acceptance criteria
Functionality
API
Accessibility
Internationalization
Test plan

Konstantin Dinev | Date:
Radoslav Mirchev | Date: Feb 17, 2021
Simeon Simeonov | Date:

1. Revision History

Version	User	Date	Notes
0.1	Stanka Bozalieva	Oct 5, 2018	Initial draft
0.2	Stefan Ivanov	Oct 9, 2019	Update - in progress
1.0	Zdravko Kolev	Nov 7, 2019	Add Test plan
2.0	Zdravko Kolev	Feb 1, 2021	Update Accessibility section
3.0	Riva Ivanova	Nov 19, 2024	Update Option, Events, Keyboard navigation

A carousel component is used to browse a collection of slides like galleries of images, cards, on-boarding tutorials or page-based interfaces. It can be used as a separate full – screen element or inside another component

2. Objectives

igx-carousel can be used as standalone component in order to show a set of slides. It should be highly customizable, providing capabilities like slide transitions and animations, hide\show navigation buttons, dynamically load images, i18n and accessibility support.

3. User Stories

End user

As end user I would like to:

Be able to navigate through a set of slides.
Be able to navigate the slides via Next and Previous soft buttons.
Be able to navigate the slides via the keyboard arrows.
Be able to select and show a particular slide from the collection through pager/thumbs.
Be able to interact with the slide so that it would open other relevant content.
Have an indication about the current slide in the context of the collection.

Developer

As a developer I want to:

Be able to provide the slides to be displayed using ngFor directive.

<igx-carousel [interval]="interval" [pause]="pause" [loop]="loop">
     <igx-slide *ngFor="let slide of slides;" [active]="slide.active">
         <img [src]="slide.image">
     </igx-slide>
</igx-carousel>

Be able to provide the slides to be displayed through pure markup

<igx-carousel [interval]="interval" [pause]="pause" [loop]="loop">
    <igx-slide [active]="slide.active">
        <img [src]="...">
    </igx-slide>
    <igx-slide>
        <img [src]="...">
    </igx-slide>
</igx-carousel>

I expect to have buttons for moving to the Next/Previous slide.
I expect to have templatable indicators that support precise navigation, show the current status/active slide and progress. Such a template can be created for gots (Page indicators - iOS), a small thumb for every slide, or another custom layout.
I want to create slide templates that can trigger an action that would take the user to a news article for example
I want to be able a threshold for the number of slides (5 by default) within which navigation indicators are shown e.g. dots
The indication area is to be replaced with informative text, e.g. “3 of 6”, when there would be more than the max number of navigable slides.
I want to utilize touch gestures on the carousel such as:
- Flick left or right to change the active slide
- Pan left/right to peek to the next/previous slide without changing the active slide unless panning beyond a certain threshold and lifting your finger
I want to show more than one slide at a time (similar to coverflow on MacOS)
I want to be disable navigation of the carousel which would hide dots/thumbnail indicators and navigation buttons but also disables all gestures and interactions for the carousel
Height ( % ) vertical direction
Width ( % ) horizontal direction
I want to be able to make the carousel slides loop (false by default allowing the first slide can only go forward/ last slide can only go backwards)
I want to configure the carousel to auto-play on every 3 seconds or another arbitrary amount of time (auto-play is disabled by default)
- On touch devices auto-play pauses when a long press is performed on the current slide
- On desktop devices auto-play pauses on mouse enter on the carousel and un-pauses on mouse leave after a 2 second timeout or another arbitrary amount of time
I want to be able to set active slide shown by default when the page loads
I want to set the active slide programmatically
I expect to have default slide in and slide out animations for a slide that are applied when transition occurs. I also need to be able to tweak or override them.

4. Acceptance criteria

Have carousel that shows image/set of images.
Have carousel that should navigation button and image indicators.
Have the ability to stop, pause or play the image transition.
Have the ability to change current active slide.

5. Functionality

End User Experience

igx-carousel should always display initial image and navigation buttons or image indicators.

Developer Experience

igx-carousel should provide properties, events and methods what will manage carousel configuration and behaviors.

User Interface

The end user interface consists of:

Navigation buttons
Slide indicators
Slides container

6. API

Options

loop - Should the carousel wrap back to the first slide after it reaches the last. Defaults to true.
pause - Should the carousel stop playing on user interaction. Defaults to true.
interval - The amount of time in milliseconds between slides transition.
navigation - Controls should the carousel render the left/right navigation buttons. Defaults to true.
indicators - Controls whether the carousel should render the indicators. Defaults to true.
vertical - Controls whether the carousel has vertical alignment. Defaults to false.
total - The number of slides the carousel currently has.
current - The index of the slide currently showing.
isPlaying - Returns whether the carousel is paused/playing.
isDestroyed - If the carousel is destroyed (ngOnDestroy was called).
maximumIndicatorsCount - Controls the maximum indexes that can be shown. Default value is 10.
indicatorsOrientation - Gets/sets the display mode of carousel indicators. Type CarouselIndicatorsOrientation. It can be start or end. Default value is end.
animationType - Gets/sets the animation type of carousel. Type CarouselAnimationType. Default value is slide.

Events

slideChanged - Emitted on slide change.
slideAdded - Emitted when a slide is being added to the carousel.
slideRemoved - Emitted whe a slide is being removed from the carousel.
carouselPaused - Emitted when the carousel is pausing.
carouselPlaying - Emitted when the carousel starts/resumes playing.

Methods

play() - Emits carouselPlaying event and starts the transition between slides.
stop() - Emits carouselPaused event and stops the transition between slides.
prev() - Switches to the previous slide. Emits slideChanged event.
next() - Switches to the next slide. Emits slideChanged event.
add(slide: IgxSlide) - Adds a slide to the carousel. Emits slideAdded event.
remove(slide: IgxSlide) - Removes an existing slide from the carousel. Emits slideRemoved event.
get(index: Number) - Returns the slide with the given index or null.
select(slide: IgxSlide, direction: Direction) - Selects the slide and the direction to transition to. Emits slideChanged event.

7. Accessibility

WAI-ARIA Roles, States, and Properties

The Carousel base element role is region - section containing content that is relevant to specific purpose and users will likely want to be able to navigate easily.
Carousel indicators are with role tab - grouping label providing a mechanism for selecting the tab content that is to be rendered to the user
The element that serves as the container for the set of tabs (carousel indicators) role is set to tablist.
Each slide element is set with role tabpanel.
The element that serves as the container for the set of igx-slides is set with aria-live="polite". Both options are
- off: if the carousel is automatically rotating.
- polite: if the carousel is NOT automatically rotating.

7.1 ARIA support

Carousel component

`Roles`:

`Attributes`:

aria-roledescription='carousel'
aria-selected="slide.active"
aria-controls="'panel-' + slide.index"
aria-live="!interval || stoppedByInteraction ? 'polite' : 'off'"
aria-label="carousel"
aria-label="setAriaLabel(slide)" - slide based
aria-label (buttons)
- aria-label="resourceStrings.igx_carousel_previous_slide" (keydown.enter)="prev()"
- aria-label="resourceStrings.igx_carousel_next_slide" (keydown.enter)="next()"

Slide component

`Roles`:

attr.role="tabpanel" - container for the resources associated with a tab, where each tab is contained in a tablist.

`Attributes`:

id="panel-${this.index}"
aria-labelledby="tab-${this.index}-${this.total}"
aria-selected="active" active slide - class.igx-slide--current

7.2 Keyboard navigation

Navigation buttons

Key	Result
`Space`/`Enter`	Navigates to the next/previous slide.

Indicators

Key	Result
`Arrow Right`	Navigates to the next indicator and sets the active slide to its index.
`Arrow Left`	Navigates to the previous indicator and sets the active slide to its index.
`Home`	Navigates to the first indicator and sets the the first slide to active.
`End`	Navigates to the last indicator and sets the the last slide to active.

8. Internationalization

8.1 RTL support

Indicators

Key	Result
`Arrow Right`	Navigates to the previous indicator and sets the active slide to its index.
`Arrow Left`	Navigates to the next indicator and sets the active slide to its index.
`Home`	Navigates to the lest indicator and sets the the first slide to active.
`End`	Navigates to the first indicator and sets the the last slide to active.

8.2 Localizable strings

The informative text for the indication area that reads e.g. "3 of 6" should have a localizable string for the "of" text.

9. Test plan

Automation

Base tests

Test first slide active state on initial loading. The slide should be focused on the initial load of the carousel.
If a slide element is set as [active]=”true”, it should be with the active state on initial load of the carousel
Test input [navigation]. When it set to false the arrow buttons should be hidden. When [navigation] is set to “true” the arrow buttons should be visible.
Test input [keyboardSupport]. When it’s set to “false” you cannot change slides with arrow keys.
Test slides changing with keyboard actions arrowLeft, arrowRight, home and end keys. Event slideChanged should be fired.
Test slides changing with indicators. Event onSlideChanged should be fired.
Test slides changing with navigation keys (ui buttons). Event slideChanged should be fired.
Test input [loop]. Test navigation from the first and last slide.
Test input [maximumIndicatorsCount]. The indicators should be visible only when the slides count is less than the [maximumIndicatorsCount]. Test showing of indicators labels.
Test input [indicatorsOrientation]. When it is set to top/bottom the indicators should be previewed on top/bottom location of the slide.
Test setting of [indicatorTemplate].
Test that when slides collection is change and a slide is added/removed the Carousel slides collection should be changed and events slideAdded and slideRemoved should be fired.
Test that when all slides are removed the navigation buttons and indicators won’t be shown.
Test inputs [interval] and [pause].
Test setting of [animationType] (no visual testing)
Test that when [interval] is set and hover carousel the playing should be paused and then started on mouse unhover. Events carouselPaused and carouselPlaying should be fired.

API

Test methods select(), next() and prev()
Test methods total(), get() and current()
Test methods add() and remove(). The slides should be added/removed in the carousel.
Test methods play(), stop() and isPlaying()

Manual

Visually verify that fadeIn animation is applied as enterAnimation for fade CarouselAnimationType
Visually verify that slide animation is applied as enterAnimation for slide CarouselAnimationType, and slide for leaveAnimation