Stepper Specification

Owned by

Astrea

Martin Evtimov

Stefan Ivanov

Requires approval from

Peer Developer Name | Date:
Simeon Simeonov | Date:

Signed off by

Product Owner Name | Date:
Platform Architect Name | Date:

Revision History

Version	Users	Date	Notes
1	Names of Developers and Designers	Date

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

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

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. stepper design handoff

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

References for well-designed and functional steppers:

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`	`indicator`	`indicator \| title \| full`
horizontalTitlePosition	Gets/sets the position of the titles in the stepper when the orientation direction is horizontal.	`IgxStepperTitlePosition`	`bottom`	`bottom \| top \| end \| start`
verticalTitlePosition	Gets/sets the position of the titles in the stepper when the orientation direction is vertical.	`IgxStepperTitlePosition`	`end`	`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.	`IgxStepperVerticalAnimationType \| string`	`grow`	`grow \| fade \| none`
horizontalAnimationType	Gets/sets the animation type of the stepper when the orientation direction is horizontal.	`CarouselAnimationType \| 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 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 render the stepper according to the specified orientation (vertical/horizontal)
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

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