Skip to content

Carousel specification [Draft]

Jump to bottom
Radoslav Karaivanov edited this page Jun 10, 2024 · 1 revision

Carousel specification

Owned By

Team Name: Astrea + Design and Web Development

Developer name: TBD

Designer name: TBD

Requires approval from:

  • Damyan Petev
  • Svilen Dimchevski

Signed off by:

  • Simeon Simeonov
  • Radoslav Mirchev

Revision history

Version Author Date Notes
- Radoslav Karaivanov 2024-06-10 Initial draft - user stories and API

Overview

An igc-carousel component presents a set of items, referred to as slides, by sequentially displaying a subset of one or more slides. Typically, one slide is displayed at a time, and users can activate a next or previous slide control that hides the current slide and "rotates" the next or previous slide into view. While a slide may contain any type of content, image carousels where each slide contains nothing more than a single image are common.

Terms

The following terms are used to describe components of a carousel.

Slide A single content container within a set of containers that the content to be presented by the carousel. In the current implementation, that role is fulfilled by the igc-carousel-slide component.

Rotation Control An interactive element that stops and starts automatic slide rotation.

Next Slide Control An interactive element, often styled as an arrow, that displays the next slide in the rotation sequence.

Previous Slide Control An interactive element, often styled as an arrow, that displays the previous slide in the rotation sequence.

Slide Picker Controls A group of elements, often styled as small dots, that enable the user to pick a specific slide in the rotation sequence to display.

Acceptance criteria

The igc-carousel must:

  • show a set of igc-carousel-slide components one at a time.
  • render controls for navigating the its slides.
  • render a rotation control to stop, pause or resume automatic slide rotation.
  • expose a way to change the current "active" (shown) slide.
  • be WAI-ARIA compliant.

User stories

End-user stories

As an end-user I expect to be able to:

  • pause/resume automatic rotation of the slides in the carousel.
  • navigate through the set of slides via the renderer slides controls.
  • navigate through the set of slides via keyboard interaction.
  • have an indication of the current active slide.

Developer stories

As a developer I expect to be able to:

  • declaratively provide the slides which will be displayed in the carousel component.
  • declaratively provide the content of the slides.
  • have default navigation controls as well as the ability to hide said controls.
  • show additional slide picker control (dots) where the user can pick and show a specific slide from the set.
  • control the default time interval between switching the current active slide.
  • enable/disable looping of the slides.
  • utilize additional keyboard navigation behavior?
  • utilize gestures navigation behavior?
  • set initial active slide.
  • programmatically control which slide should be shown.
  • programmatically control the state of the carousel (playing/paused/stopped).
  • customize the look and feel of the navigation buttons and the slides picker control?

Functionality

End-user experience

[Design Handoff]

Behaviors

TBD

Developer experience

TBD

Localization

TBD

Keyboard navigation

TBD

API

IgcCarouselComponent

Properties

Property Attribute Reflected Type Default Description
skipLoop skip-loop Yes Boolean false Whether the carousel should skip rotating to the first slide after it reaches the last.
skipPauseOnInteraction skip-pause-on-interaction Yes Boolean false Whether the carousel should ignore use interactions and not pause on them.
interval interval No number - The duration in milliseconds between changing the active slide.
skipNavigation ? skip-navigation Yes Boolean false Whether the carousel should skip rendering of the default navigation buttons.
withPicker ? with-picker Yes Boolean false Whether the carousel should render the picker controls (dots).
total - No number - The total number of slides.
current - No number - The index of the current active slide.
slides - No Array [] The slides of the carousel.
isPlaying - No Boolean false Whether the carousel is in playing state.
isPaused - No Boolean false Whether the carousel in in paused state.
isStopped - No Boolean false Whether the carousel is in stopped state.

Methods

Name Type signature Description
play (): void Resumes playing of the carousel slides.
pause (): void Pauses the carousel rotation of slides.
stop (): void Stops the carousel rotation of slides.
next (): Promise<boolean> Switches to the next slide running any animations and returns if the operation was a success.
prev (): Promise<boolean> Switches to the previous slide running any animations and returns if the operation was a success.
select? (slide: IgcCarouselSlide, direction?: unknown): Promise<boolean> Switches the passed in slide running any animations and returns if the operation was a success.

Events

Name Cancellable Description
igcSlideChanged No Emitted when the current active slide is changed either by user interaction or by the interval callback.
igcPlaying No Emitted when the carousel enters playing state by a user interaction.
igcPaused No Emitted when the carousel enters paused state by a user interaction.
igcStopped No Emitted when the carousel enters stopped state by a user interaction.

Slots

Name Description
default Default slot for the carousel. Any projected igc-carousel-slide components should be projected here.

CSS Shadow Parts

Part Description

IgcCarouselSlide

Properties

Property Attribute Reflected Type Default Description
active active Yes Boolean false The current active slide for the carousel component.

Note

If there are multiple active slides on initial rendering or subsequent updates, only the last one will be taken into account.

Methods

None applicable.

Events

None applicable.

Slots

Name Description
default Default slot for the carousel slide.

CSS Shadow Parts

Part Description

Test scenarios

Automation

Rendering and initialization

TBD

Attributes and properties

TBD

Behaviors

TBD

Accessibility

ARIA

TBD

References

https://www.w3.org/WAI/ARIA/apg/patterns/carousel/examples/carousel-1-prev-next/

https://www.w3.org/WAI/ARIA/apg/patterns/carousel/examples/carousel-2-tablist/?moreaccessible=false

RTL

The component should work in a Right-To-Left context without additional setup or configuration.

Assumptions and limitations

TBD

Clone this wiki locally