From 246f8b77b6ba4efa1da5d7bf10a41949ba2ebfd6 Mon Sep 17 00:00:00 2001 From: Ji Won Shin Date: Thu, 17 Aug 2017 09:49:43 -0700 Subject: [PATCH 1/2] Documentation for stepper --- src/lib/stepper/stepper.md | 128 +++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 src/lib/stepper/stepper.md diff --git a/src/lib/stepper/stepper.md b/src/lib/stepper/stepper.md new file mode 100644 index 000000000000..1860938055d0 --- /dev/null +++ b/src/lib/stepper/stepper.md @@ -0,0 +1,128 @@ +Angular Material stepper walks users through multi-step processes by breaking them up +into multiple logical and numbered steps. It displays progress through a sequence of steps +and can also be used for navigation between different steps. + +Material stepper builds on the foundation of the CDK stepper that is responsible for the logic +that drives a stepped workflow. Material stepper extends the CDK stepper and has Material Design +styling. + +There are two stepper components: `md-horizontal-stepper` and `md-vertical-stepper`. They +can be used the same way. The only difference is the orientation of stepper. +`md-horizontal-stepper` selector can be used to create a horizontal stepper, and +`md-vertical-stepper` can be used to create a vertical stepper. `md-step` components need to be +placed inside either one of the two stepper components. + + +### Event +The `selectionChange` output event is emitted when the selected step changes. + +### Labels +If a step's label is only text then `label` attribute can be used. +```html + + + Content 1 + + + Content 2 + + +``` + +For more complex labels, add a template with the `mdStepLabel` directive inside the +`md-step`. +```html + + + ... + ... + + +``` + +### Stepper buttons +There are two button directives to support navigation between different steps: +`mdStepperPrevious` and `mdStepperNext`. +```html + + + ... +
+ + +
+ + +``` + +### Linear stepper +`linear` attribute can be set on `md-horizontal-stepper` and `md-vertical-stepper` to create +a linear stepper that requires the user to complete previous steps before proceeding +to following steps. For each `md-step`, `stepControl` attribute can be set to the top level +`AbstractControl` that is used to check the validity of the step. + +There are two possible approaches. One is using a single form for stepper, and the other is +using a different form for each step. + +#### Using a single form +When using a single form for the stepper, `mdStepperPrevious` and `mdStepperNext` has to be +set to `type="button"` in order to prevent submission of the form before all steps +are completed. + +```html +
+ + + ... +
+ +
+ + + ... +
+ + +
+ + ... + +
+``` + +#### Using a different form for each step +```html + + +
+ ... +
+ + +
+ ... +
+ + +``` +### Types of steps + +#### Optional step +If completion of a step in linear stepper is not required, then `optional` attribute can be set +on `md-step`. + +#### Editable step +By default, steps are editable, which means users can return to previously completed steps and +edit their responses. `editable="true"` can be set on `md-step` to change the default + +#### Completed step +By default, `completed` attribute of a step returns `true` if the step is valid (in case of +linear stepper) and the user has interacted with the step. The user, however, can also override +this default `completed` behavior by setting the `completed` attribute as needed. + +### Keyboard interaction +- LEFT_ARROW: Focuses the previous step header +- RIGHT_ARROW: Focuses the next step header +- ENTER, SPACE: Selects the step that the focus is currently on +- TAB: Focuses the next tabbable element +- TAB+SHIFT: Focuses the previous tabbable element \ No newline at end of file From db22cc2a1d2c4f7ed956505da55b28b7e8637098 Mon Sep 17 00:00:00 2001 From: Ji Won Shin Date: Fri, 18 Aug 2017 10:23:38 -0700 Subject: [PATCH 2/2] Revision based on review + add accessibility section --- src/lib/stepper/stepper.md | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/src/lib/stepper/stepper.md b/src/lib/stepper/stepper.md index 1860938055d0..54e273068cf5 100644 --- a/src/lib/stepper/stepper.md +++ b/src/lib/stepper/stepper.md @@ -1,23 +1,18 @@ -Angular Material stepper walks users through multi-step processes by breaking them up -into multiple logical and numbered steps. It displays progress through a sequence of steps -and can also be used for navigation between different steps. +Angular Material's stepper provides a wizard-like workflow by dividing content into logical steps. Material stepper builds on the foundation of the CDK stepper that is responsible for the logic that drives a stepped workflow. Material stepper extends the CDK stepper and has Material Design styling. +### Stepper variants There are two stepper components: `md-horizontal-stepper` and `md-vertical-stepper`. They can be used the same way. The only difference is the orientation of stepper. `md-horizontal-stepper` selector can be used to create a horizontal stepper, and `md-vertical-stepper` can be used to create a vertical stepper. `md-step` components need to be placed inside either one of the two stepper components. - -### Event -The `selectionChange` output event is emitted when the selected step changes. - ### Labels -If a step's label is only text then `label` attribute can be used. +If a step's label is only text, then the `label` attribute can be used. ```html @@ -56,16 +51,16 @@ There are two button directives to support navigation between different steps: ``` ### Linear stepper -`linear` attribute can be set on `md-horizontal-stepper` and `md-vertical-stepper` to create +The `linear` attribute can be set on `md-horizontal-stepper` and `md-vertical-stepper` to create a linear stepper that requires the user to complete previous steps before proceeding -to following steps. For each `md-step`, `stepControl` attribute can be set to the top level +to following steps. For each `md-step`, the `stepControl` attribute can be set to the top level `AbstractControl` that is used to check the validity of the step. There are two possible approaches. One is using a single form for stepper, and the other is using a different form for each step. #### Using a single form -When using a single form for the stepper, `mdStepperPrevious` and `mdStepperNext` has to be +When using a single form for the stepper, `mdStepperPrevious` and `mdStepperNext` have to be set to `type="button"` in order to prevent submission of the form before all steps are completed. @@ -108,15 +103,15 @@ are completed. ### Types of steps #### Optional step -If completion of a step in linear stepper is not required, then `optional` attribute can be set +If completion of a step in linear stepper is not required, then the `optional` attribute can be set on `md-step`. #### Editable step By default, steps are editable, which means users can return to previously completed steps and -edit their responses. `editable="true"` can be set on `md-step` to change the default +edit their responses. `editable="true"` can be set on `md-step` to change the default. #### Completed step -By default, `completed` attribute of a step returns `true` if the step is valid (in case of +By default, the `completed` attribute of a step returns `true` if the step is valid (in case of linear stepper) and the user has interacted with the step. The user, however, can also override this default `completed` behavior by setting the `completed` attribute as needed. @@ -125,4 +120,13 @@ this default `completed` behavior by setting the `completed` attribute as needed - RIGHT_ARROW: Focuses the next step header - ENTER, SPACE: Selects the step that the focus is currently on - TAB: Focuses the next tabbable element -- TAB+SHIFT: Focuses the previous tabbable element \ No newline at end of file +- TAB+SHIFT: Focuses the previous tabbable element + +### Accessibility +The stepper is treated as a tabbed view for accessibility purposes, so it is given +`role="tablist"` by default. The header of step that can be clicked to select the step +is given `role="tab"`, and the content that can be expanded upon selection is given +`role="tabpanel"`. `aria-selected` attribute of step header and `aria-expanded` attribute of +step content is automatically set based on step selection change. + +The stepper and each step should be given a meaningful label via `aria-label` or `aria-labelledby`. \ No newline at end of file