Stepper Specification

Stepper Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. Test Scenarios
5. Accessibility
6. Assumptions and Limitations
7. References

Owned by

Astrea

Developer Name: Martin Evtimov, Viktor Kombov

Designer Name

Requires approval from

• Peer Developer: Monika Kirkova | Date: 23-Aug-22
• Design Manager: Svilen Dimchevski | Date: 23-Aug-22

Signed off by

• Product Owner: Radoslav Mirchev | Date: 22-Aug-22
• Platform Architect Damyan Petev | Date: 25-Aug-22

Revision History

Version	Users	Date	Notes
1	Teodosia Hristodorova	Date 19-July-2022	Names of Developers and Designers
1.01	Teodosia Hristodorova	Date 19-July-2022	Initial specification version
2	Bozhidara Pachilova	Date 26-March-2024	Update according to issue #1112

1. Overview

Objectives

The stepper conveys the progression of a sequence of individual steps indicating how much of a workflow has been completed and how much is left. It usually shows as a vertical or horizontal line with connected, numbered elements indicating the individual steps. Another commonly used name for a stepper component is wizard.

Provide igc-stepper component that supports the following features:

• inform the user about the history of actions.
• inform the user about the current progress.
• inform the user about which and how many steps remain.
• show the direction of movement.
• support an arbitrary number of steps, usually, 3-5 are optimal.
• support numbering as a way to show the order of steps.
• support icons and visuals to better describe each individual step.
• support a horizontal layout for desktop and vertical for mobile.

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

• Sign off
• Available prototypes and Figma designs
• Created file structure in Indigo_Platform

2. User Stories

Elaborate more on the multi-facetted use cases

Developer stories:

• Story 1: As a developer, I want to be able to choose the stepper layout, so that I can show a horizontal one on desktop and a vertical one on smartphone screens.
• Story 2: As a developer, I want to be able to choose whether steps are mandatory or optional, so that I can have proper validation at the end of the flow.
• Story 3: As a developer, I want to be able to define arbitrary layout as the content for a step, so that I can create progressive forms and onboarding flows without being constrained.
• Story 4: As a developer, I want to be able to define the position of the title for step, so that I can place it before, after, above or below the visual indication.
• Story 5: As a developer, I want to be able to customize the visual step element, so that I can add a graphic element in it.
• Story 6: As a developer, I want to be able to choose the type of line that connects the steps. Possible options are dashed, solid and doted.
• Story 7: As a developer, I want to be able to define the stepper as strictly linear (gated mode vs. ungated mode where you navigate steps freely), so that I don't let users to move to the next step unless everything up to it has been completed.

End-user stories:

• Story 1: As an end-user, I want to have a clear visual indication of what I should expect from each step, so that I know which ones are relevant/important to me.
• Story 2: As an end-user, I want to have a clear visual indication for the step I am currently at, so that I know approximately how much is left.
• Story 3: As an end-user, I want to have a clear visual indication for completed and uncompleted steps, so that I can finish what is left.
• Story 4: As an end-user, I want to have a clear visual indication for optional steps, so that I can skip them if they are not relevant.
• Story 5: As an end-user, I want to navigate between the steps with the keyboard one at a time, so that I can fill a progressive form more quickly.
• Story 6: As an end-user, I want to observe the progress of a multistep process, so that I can e.g. track the delivery of an order.

3. Functionality

3.1. End-User Experience

The stepper is a collection of step header elements that let you navigate to different pieces of details for each step and the details view itself.

Nesting steppers into each other is frustrating and destroys the UX.

Design Handoff- https://www.figma.com/file/iBiSKAZJ56Z3Pd0zertjHb/Stepper-Design-Handoff?node-id=0%3A1

3.2. Developer Experience

• The developer should be able to add multiple steps.
• The developer should be able to customize the indicator of the steps.
• The developer should be able to customize the title of the steps.
• The developer should be able to customize the subtitle of the steps.
• The developer should be able to customize the content of the steps.

<igc-stepper>
    <igc-step>
       <div slot="indicator"></div>
       <p slot="title">Home</p>
       <p slot="subtitle">Home Sub Title</p>
       <div>
          ...
       </div
    </igc-step>
</igc-stepper>

• The developer should be able to customize the active, invalid and completed indicator state.

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Keys	Description
Arrow Up	Focuses the previous step in a vertical stepper.
Arrow Down	Focuses the next step in a vertical stepper.
Arrow Left	Focuses the previous step in a horizontal stepper.
Arrow Right	Focuses the next step in a horizontal stepper.
Home	Focuses the first step of the stepper.
End	Focuses the last step of the stepper.
Enter / Space	Activates the currently focused step.
Tab	Moves the focus to the next tabbable element.
Shift + Tab	Moves the focus to the previous tabbable element.

Note:

• By design when the user presses the Tab key over the step header the focus will move to the step content container. In case the container should be skipped the developer should set the content container tabInex to -1.

3.5. API

IgcStepperComponent

Options

Name	Description	Type	Default value	Reflected
steps	Gets the steps that are rendered in the stepper.	IgcStepComponent[]		false
orientation	Gets/sets the orientation of the stepper.	horizontal | vertical	horizontal	true
stepType	Gets/sets the type of the steps in the stepper.	indicator | title | full	full	true
titlePosition	Gets/sets the position of the titles in the stepper. Default behavior is bottom when the stepper is horizontally orientated and end when the layout is set to vertical.	bottom | top | end | start	N/A	false
linear	Whether the validity of previous steps should be checked and only in case, it's valid to be able to move forward or not.	boolean	false	false
contentTop	Whether the content of the steps should be displayed above the steps header when the stepper orientation is Horizontal.	boolean	false	true

Methods

Name	Description	Return type	Parameters
navigateTo	Activates the step given by index.	void	index: number
next	Activates the next enabled step.	void	N/A
prev	Activates the previous enabled step.	void	N/A
reset	Resets the stepper to its initial state.	void	N/A

Events

Name	Description	Cancelable	Parameters
igcActiveStepChanging	Emitted when the active step is about to change.	true	{ oldIndex: number, newIndex: number }
igcActiveStepChanged	Emitted when the active step is changed.	false	{ index: number }

IgcStepComponent

Options

Name	Description	Type	Default value	Reflected
invalid	Gets/sets whether the step is invalid.	boolean	false	true
active	Gets/sets whether the step is activе.	boolean	false	true
optional	Gets/sets whether the step is optional.	boolean	false	false
disabled	Gets/sets whether the step is interactable.	boolean	false	true
complete	Gets/sets whether the step is completed.	boolean	false	true

Slots

Name	Description
default	The content of the step.
indicator	Renders the indicator of the step. By default, it displays the step index + 1.
title	Renders the title of the step.
subtitle	Renders the subtitle of the step.

CSS Parts

Part	Description
header-container	Wrapper of the step's header and its separators.
disabled	Indicates a disabled state. Applies to header-container.
complete-start	Indicates a complete state of the current step. Applies to header-container.
complete-end	Indicates a complete state of the previous step. Applies to header-container.
optional	Indicates an optional state. Applies to header-container.
invalid	Indicates an invalid state. Applies to header-container.
top	Indicates that the title should be above the indicator. Applies to header-container.
bottom	Indicates that the title should be below the indicator. Applies to header-container.
start	Indicates that the title should be before the indicator. Applies to header-container.
end	Indicates that the title should be after the indicator. Applies to header-container.
header	Wrapper of the step's indicator and text.
indicator	The indicator of the step.
text	Wrapper of the step's title and subtitle.
empty	Indicates that no title and subtitle has been provided to the step. Applies to text.
title	The title of the step.
subtitle	The subtitle of the step.
body	Wrapper of the step's content.
content	The steps content.

4. Test Scenarios

Basic

• Should render a horizontal stepper containing a sequence of steps
• Should expand a step through API by activating it
• Should expand a step through UI by activating it
• Should not allow activating a step with the next/prev methods when disabled is set to true
• Should do nothing when all steps are not accessible and next/prev methods are called
• Should not allow activating more than one step at a time
• Should not change the active step when the navigateTo method is called with a mismatched index
• Should properly set the active state of the steps when the active step is removed dynamically
• Should activate a step when it is set to be active and disabled initially
• Should properly set the active step of the stepper when an active step is added dynamically
• Should emit ing and ed events when a step is activated through UI
• Should not emit events when a step is activated through API
• Should be able to cancel the igcActiveStepChanging event
• Should not mark a step as visited if it has not been activated before
• Should determine the steps that are marked as visited based on the active step in linear mode
• Should activate the first accessible step and clear the visited steps collection when the stepper is reset
• Should determine the steps that are disabled in linear mode based on the validity of the active step
• Should not allow moving forward to the next step in linear mode if the previous step is invalid
• Should set a step to be accessible in linear mode if the previous accessible step is being disabled
• Should set a step to be not accessible in linear mode if before it is inserted a new invalid step
• Should properly set the linear disabled steps when the active step is removed from the DOM
• Should set a step to be accessible if the previous one is being removed from the DOM and was accessible before that
• Should set a newly added step to be accessible if is inserted before the active step
• Should not set previous steps to be accessible if a linear disabled step's invalid or disabled states are changed through API
• Should set a step to be accessible in linear mode if the previous one is accessible and optional

Appearance

• Should apply the appropriate attribute to a stepper in a horizontal and vertical orientation
• Should properly render the step's layout
• Should apply the appropriate part to the header container of a step that is disabled or linear disabled
• Should indicate that a step is completed
• Should properly indicate where a completed step starts and ends
• Should apply the appropriate part to the header container of an optional step
• Should indicate that a step is invalid
• Should apply the appropriate part to the header container of an invalid step
• Should apply the appropriate part to the header container of a step that has no title and subtitle
• Should indicate which is the currently active step
• Should place the title in the step element according to the specified titlePosition when stepType is set to "full"
• Should render the visual step element according to the specified stepType
• Should indicate each step with a corresponding number when the steps' indicators are not specified and stepType is either “indicator” or “full”
• Should be able to display the steps' content above the steps headers when the stepper is horizontally orientated
• Should properly render the step's content in a vertical orientation when contentTop is set to true

Keyboard Navigation

• Should navigate to the first/last step on Home/End key press
• Should activate the currently focused step on Enter/Space key press
• Should navigate to the next/previous step in horizontal orientation on Arrow Right/Left key press
• Should navigate to the next/previous step in a vertical orientation on Arrow Down/Up key press
• Should not navigate to the next/previous step in horizontal orientation on Arrow Down/Up key press
• Should specify tabIndex="0" for the active step header and tabIndex="-1" for the other steps

Aria

• Should render proper role and orientation attributes for the stepper
• Should render proper aria attributes for each step

5. Accessibility

ARIA Support

• The HTML stepper element has an implicit role tablist.
• If the stepper element is vertically oriented, it has the property aria-orientation set to vertical. The default value of aria-orientation for a stepper element is horizontal.
• Each step element within the stepper element has a role tab.
• The content panel for each step element has a role tabpanel.
• Each step element has aria-controls property referring to its associated stepper element.
• The active step element has the state aria-selected set to true and all other step elements have it set to false.

RTL Support

6. Assumptions and Limitations

Assumptions	Limitation Notes

7. References

Specify all referenced external sources