Stepper Specification

Owned by

Astrea

Martin Evtimov

Stefan Ivanov

Requires approval from

Peer Developer Name | Date:
Simeon Simeonov | Date: 19-Oct-21

Signed off by

Product Owner: Radoslav Mirchev | Date: 19-Oct-21
Platform Architect Name: Konstantin Dinev | Date: 22-Oct-21

Revision History

Version	Users	Date	Notes
0.1	Vasya Kacheshmarova	10/22/2021	Add revision history section
1.0	Teodosia Hristodorova	05/29/2023	Rename subtitle directive

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.

Acceptance criteria

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

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

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.
Story 8: As a developer, I want to be able to choose the animations applied to the stepper when the active step is changing.

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 re-template the indicator of the steps.
The developer should be able to re-template the title of the steps.
The developer should be able to re-template the subtitle of the steps.
The developer should be able to re-template the content of the steps.

<igx-stepper>
    <igx-step>
       <igx-icon igxStepIndicator>home</igx-icon>
       <p igxStepTitle>Home</p>
       <p igxStepSubtitle>Home Sub Title</p>
       <div igxStepContent>
          ...
       </div
    </igx-step>
</igx-stepper>

The developer should be able to re-template the active, invalid and completed indicator state.

<igx-stepper>
    <ng-template igxStepActiveIndicator>
       <igx-icon>edit</igx-icon>
    </ng-template>

    <ng-template igxStepInvalidIndicator>
       <igx-icon>error</igx-icon>
    </ng-template>

    <ng-template igxStepCompletedIndicator>
       <igx-icon>check</igx-icon>
    </ng-template>
    ...
</igx-stepper>

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

IgxStepperComponent

Accessors

Name	Description	Type
steps	Gets the steps that are rendered in the stepper.	`IgxStepComponent[]`

Options

Name	Description	Type	Default value	Valid values
id	The id of the stepper. Bound to attr.id	`string`	'stepper-${iter}'	`-`
orientation	Gets/sets the orientation of the stepper.	`IgxStepperOrientation`	`horizontal`	`horizontal \| vertical`
stepType	Gets/sets the type of the steps in the stepper.	`IgxStepType`	`full`	`indicator \| title \| full`
titlePosition	Gets/sets the position of the titles in the stepper.Default value is `bottom` when the stepper is horizontally orientated and `end` when the layout is set to vertical.	`IgxStepperTitlePosition`	`bottom`	`bottom \| top \| end \| start`
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`	`-`
contentTop	Whether the steps content should be displayed above the steps header when the stepper orientation is Horizontal.	`boolean`	`false`	`-`
verticalAnimationType	Gets/sets the animation type of the stepper when the orientation direction is vertical.	`VerticalAnimationType \| string`	`grow`	`grow \| fade \| none`
horizontalAnimationType	Gets/sets the animation type of the stepper when the orientation direction is horizontal.	`HorizontalAnimationType \| string`	`slide`	`slide \| fade \| none`
animationDuration	Gets/sets the duration of the animation.	`number`	320	`-`

Methods

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

Events

Name	Description	Cancelable	Parameters
activeStepChanging	Emitted when the active step is about to change.	yes	`{ oldIndex: number, newIndex: number, owner: IgxStepperComponent, cancel: boolean }`
activeStepChanged	Emitted when the active step is changed.	no	`{ index: number, owner: IgxStepperComponent}`

IgxStepComponent

Accessors

Name	Description	Type
index	Gets the step index inside of the stepper.	`number`

Options

Name	Description	Type	Default value
id	The id of the step. Bound to attr.id	`string`	'step-${iter}'
isValid	Gets/sets whether the step is valid.	`boolean`	`true`
active	Gets/sets whether the step is activе. Two-way data binding.	`boolean`	`false`
optional	Gets/sets whether the step is optional.	`boolean`	`false`
disabled	Gets/sets whether the step is interactable.	`boolean`	`false`
complete	Gets/sets whether the step is completed.	`boolean`	`false`

Methods

Name	Description	Return type	Parameters

Events

Name	Description	Cancelable	Parameters
activeChange	Emitted when the step's active property changes	no	`boolean`

4. Test Scenarios

Basic

Should render a stepper containing a sequence of steps
Should not allow activating a step with the next/prev methods when disabled is set to true
Should not allow moving forward to the next step in linear mode if the previous step is invalid
Should emit ing and ed events when a step is activated
Should be able to cancel the activeStepChanging event
A step should emit activeChange event when its active property changes

Appearance

Should apply the appropriate class to a stepper in horizontal mode
Should indicate the currently active step
Should indicate that a step is completed
Should indicate that a step is invalid
Should render the visual step element according to the specified stepType
Should place the title in the step element according to the specified title position when stepType is set to “full”
Should indicate each step with a corresponding number when igxStepIndicator is not specified in the step template 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 render step indicator and title when such are defined in the template
Should allow overriding the default invalid, completed and active indicators
Should allow overriding animationSettings that are used for transitioning between steps
Should render dynamically added step and properly set the linear disabled steps with its addition
Should activate the first accessible step and clear the visited steps collection when the stepper is reset
Should properly collapse the previously active step in horizontal orientation and horizontalAnimationType of type ‘fade’

Keyboard Navigation

Should navigate to the stepper (if the focus is before stepper) on TAB key press
Should navigate to the stepper (if the focus is after stepper) on SHIFT + TAB key press
Should navigate to the next step in vertical orientation on Arrow Down key press
Should navigate to the previous step in vertical orientation on Arrow Up key press
Should navigate to the next step in horizontal orientation on Arrow Right key press
Should navigate to the previous step in horizontal orientation on Arrow Left key press
Should navigate to first step on Home key press
Should navigate to last step on End key press
Should activate the currently focused step on Enter/Space key press
Should specify tabIndex=”0” for the active step 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

Stepper Service Unit Tests

Should properly register the specified stepper
Should expand a step by activating it and firing the step's activeChange event
Should expand a step through API by activating it and firing the step's activeChange event
Should collapse the currently active step and fire the change event
Should determine the steps that are marked as visited based on the active step
Should determine the steps that are disabled in linear mode based on the validity of the active step
Should emit activating event