From 14e61630d7d6edfc5c53bb939b0e9a00e17ff196 Mon Sep 17 00:00:00 2001 From: Artur Signell Date: Tue, 26 Aug 2025 10:12:26 +0300 Subject: [PATCH] Add Stepper component documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive documentation for the Stepper component including: - Usage examples for TypeScript, Flow, and React frameworks - Step states (inactive, active, completed, error) documentation - Horizontal and vertical orientation options - Navigation and router integration documentation - Size variants and styling customization - Accessibility and keyboard usage guidelines - Best practices and related components - Complete demo files for all frameworks 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- articles/components/stepper/index.adoc | 388 ++++++++++++++++++ articles/components/stepper/stepper.png | 0 articles/components/stepper/styling.adoc | 239 +++++++++++ .../component/stepper/react/stepper-basic.tsx | 15 + .../stepper/react/stepper-custom.tsx | 29 ++ .../stepper/react/stepper-disabled.tsx | 26 ++ .../stepper/react/stepper-navigation.tsx | 29 ++ .../stepper/react/stepper-orientation.tsx | 15 + .../component/stepper/react/stepper-sizes.tsx | 15 + .../stepper/react/stepper-states.tsx | 15 + .../component/stepper/react/stepper-steps.tsx | 29 ++ .../demo/component/stepper/stepper-basic.ts | 30 ++ .../demo/component/stepper/stepper-custom.ts | 41 ++ .../component/stepper/stepper-disabled.ts | 27 ++ .../component/stepper/stepper-navigation.ts | 27 ++ .../component/stepper/stepper-orientation.ts | 27 ++ .../demo/component/stepper/stepper-sizes.ts | 27 ++ .../demo/component/stepper/stepper-states.ts | 27 ++ .../demo/component/stepper/stepper-steps.ts | 29 ++ .../demo/component/stepper/StepperBasic.java | 29 ++ .../demo/component/stepper/StepperCustom.java | 41 ++ .../component/stepper/StepperDisabled.java | 33 ++ .../component/stepper/StepperNavigation.java | 34 ++ .../component/stepper/StepperOrientation.java | 36 ++ .../demo/component/stepper/StepperRouter.java | 47 +++ .../demo/component/stepper/StepperSizes.java | 36 ++ .../demo/component/stepper/StepperStates.java | 35 ++ .../demo/component/stepper/StepperSteps.java | 34 ++ 28 files changed, 1360 insertions(+) create mode 100644 articles/components/stepper/index.adoc create mode 100644 articles/components/stepper/stepper.png create mode 100644 articles/components/stepper/styling.adoc create mode 100644 frontend/demo/component/stepper/react/stepper-basic.tsx create mode 100644 frontend/demo/component/stepper/react/stepper-custom.tsx create mode 100644 frontend/demo/component/stepper/react/stepper-disabled.tsx create mode 100644 frontend/demo/component/stepper/react/stepper-navigation.tsx create mode 100644 frontend/demo/component/stepper/react/stepper-orientation.tsx create mode 100644 frontend/demo/component/stepper/react/stepper-sizes.tsx create mode 100644 frontend/demo/component/stepper/react/stepper-states.tsx create mode 100644 frontend/demo/component/stepper/react/stepper-steps.tsx create mode 100644 frontend/demo/component/stepper/stepper-basic.ts create mode 100644 frontend/demo/component/stepper/stepper-custom.ts create mode 100644 frontend/demo/component/stepper/stepper-disabled.ts create mode 100644 frontend/demo/component/stepper/stepper-navigation.ts create mode 100644 frontend/demo/component/stepper/stepper-orientation.ts create mode 100644 frontend/demo/component/stepper/stepper-sizes.ts create mode 100644 frontend/demo/component/stepper/stepper-states.ts create mode 100644 frontend/demo/component/stepper/stepper-steps.ts create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperBasic.java create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperCustom.java create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperDisabled.java create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperNavigation.java create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperOrientation.java create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperRouter.java create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperSizes.java create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperStates.java create mode 100644 src/main/java/com/vaadin/demo/component/stepper/StepperSteps.java diff --git a/articles/components/stepper/index.adoc b/articles/components/stepper/index.adoc new file mode 100644 index 0000000000..e045dd7bbc --- /dev/null +++ b/articles/components/stepper/index.adoc @@ -0,0 +1,388 @@ +--- +tab-title: Usage +layout: tabbed-page +title: Stepper +page-title: Stepper Component | Vaadin components +description: Stepper is a navigation component that displays progress through a sequence of logical steps, guiding users through multi-step processes. +meta-description: Use Vaadin's Stepper component to display progress through a sequence of steps and provide navigation through multi-step processes. +page-links: + - 'API: https://cdn.vaadin.com/vaadin-web-components/{moduleNpmVersion:@vaadin/stepper}/#/elements/vaadin-stepper[TypeScript] / https://vaadin.com/api/platform/{moduleMavenVersion:com.vaadin:vaadin}/com/vaadin/flow/component/stepper/Stepper.html[Java]' + - 'Source: https://github.com/vaadin/web-components/tree/v{moduleNpmVersion:@vaadin/stepper}/packages/stepper[TypeScript] / https://github.com/vaadin/flow-components/tree/{moduleMavenVersion:com.vaadin:vaadin}/vaadin-stepper-flow-parent[Java]' +--- + += Stepper +:toclevels: 2 +:experimental: + +// tag::description[] +Stepper is a navigation component that displays progress through a sequence of logical steps, guiding users through multi-step processes. +// end::description[] + +[.example] +-- + +ifdef::lit[] +[source,html] +---- +include::{root}/frontend/demo/component/stepper/stepper-basic.ts[render,tags=snippet,indent=0,group=Lit] +---- +endif::[] + +ifdef::flow[] +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperBasic.java[render,tags=snippet,indent=0,group=Flow] +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- +include::{root}/frontend/demo/component/stepper/react/stepper-basic.tsx[render,tags=snippet,indent=0,group=React] +---- +endif::[] + +-- + +Use Stepper when you want to break a complex process into smaller, manageable steps and show the user their progress through the process. The component is particularly useful in wizards, multi-step forms, and guided workflows. + + +== Adding Steps + +Steps can be added individually or in bulk. Each step represents a stage in the process and can contain a label, description, and optional navigation link. + +[.example] +-- + +ifdef::lit[] +[source,html] +---- +include::{root}/frontend/demo/component/stepper/stepper-steps.ts[render,tags=snippet,indent=0,group=Lit] +---- +endif::[] + +ifdef::flow[] +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperSteps.java[render,tags=snippet,indent=0,group=Flow] +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- +include::{root}/frontend/demo/component/stepper/react/stepper-steps.tsx[render,tags=snippet,indent=0,group=React] +---- +endif::[] + +-- + + +== Orientation + +Stepper supports both vertical (default) and horizontal orientations. Choose the orientation based on your layout requirements and available space. + +[.example] +-- + +ifdef::lit[] +[source,html] +---- +include::{root}/frontend/demo/component/stepper/stepper-orientation.ts[render,tags=snippet,indent=0,group=Lit] +---- +endif::[] + +ifdef::flow[] +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperOrientation.java[render,tags=snippet,indent=0,group=Flow] +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- +include::{root}/frontend/demo/component/stepper/react/stepper-orientation.tsx[render,tags=snippet,indent=0,group=React] +---- +endif::[] + +-- + +[cols="1,3",grid=rows] +|=== +|Orientation |Usage Recommendation + +|Vertical +|Default orientation. Best for sidebars or when steps have longer labels and descriptions. + +|Horizontal +|Suitable for top navigation or when space is limited vertically. Works well with short labels. +|=== + + +== Step States + +Steps can have different states to indicate their status in the process. + +[.example] +-- + +ifdef::lit[] +[source,html] +---- +include::{root}/frontend/demo/component/stepper/stepper-states.ts[render,tags=snippet,indent=0,group=Lit] +---- +endif::[] + +ifdef::flow[] +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperStates.java[render,tags=snippet,indent=0,group=Flow] +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- +include::{root}/frontend/demo/component/stepper/react/stepper-states.tsx[render,tags=snippet,indent=0,group=React] +---- +endif::[] + +-- + +[cols="1,3",grid=rows] +|=== +|State |Description + +|Inactive +|Default state. The step has not been reached yet. + +|Active +|The current step the user is on. + +|Completed +|The step has been successfully completed. + +|Error +|The step contains an error or validation issue that needs to be resolved. +|=== + + +== Navigation + +Steps can be configured with links to enable navigation between different stages of the process. + +[.example] +-- + +ifdef::lit[] +[source,html] +---- +include::{root}/frontend/demo/component/stepper/stepper-navigation.ts[render,tags=snippet,indent=0,group=Lit] +---- +endif::[] + +ifdef::flow[] +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperNavigation.java[render,tags=snippet,indent=0,group=Flow] +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- +include::{root}/frontend/demo/component/stepper/react/stepper-navigation.tsx[render,tags=snippet,indent=0,group=React] +---- +endif::[] + +-- + +ifdef::flow[] +=== Router Integration + +In Flow applications, steps can be integrated with Vaadin Router for type-safe navigation to specific views. + +[.example] +-- + +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperRouter.java[render,tags=snippet,indent=0,group=Flow] +---- + +-- +endif::[] + + +== Disabled Steps + +Individual steps can be disabled to prevent navigation to them. + +[.example] +-- + +ifdef::lit[] +[source,html] +---- +include::{root}/frontend/demo/component/stepper/stepper-disabled.ts[render,tags=snippet,indent=0,group=Lit] +---- +endif::[] + +ifdef::flow[] +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperDisabled.java[render,tags=snippet,indent=0,group=Flow] +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- +include::{root}/frontend/demo/component/stepper/react/stepper-disabled.tsx[render,tags=snippet,indent=0,group=React] +---- +endif::[] + +-- + + +== Size Variants + +Stepper supports different size variants to fit various layout requirements. + +[.example] +-- + +ifdef::lit[] +[source,html] +---- +include::{root}/frontend/demo/component/stepper/stepper-sizes.ts[render,tags=snippet,indent=0,group=Lit] +---- +endif::[] + +ifdef::flow[] +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperSizes.java[render,tags=snippet,indent=0,group=Flow] +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- +include::{root}/frontend/demo/component/stepper/react/stepper-sizes.tsx[render,tags=snippet,indent=0,group=React] +---- +endif::[] + +-- + +[cols="1,3",grid=rows] +|=== +|Variant |Usage Recommendation + +|Normal +|Default size. Suitable for most use cases. + +|Small +|Compact option for dense layouts or when space is limited. +|=== + + +== Custom Content + +Steps can contain custom components in addition to or instead of plain text. + +[.example] +-- + +ifdef::lit[] +[source,html] +---- +include::{root}/frontend/demo/component/stepper/stepper-custom.ts[render,tags=snippet,indent=0,group=Lit] +---- +endif::[] + +ifdef::flow[] +[source,java] +---- +include::{root}/src/main/java/com/vaadin/demo/component/stepper/StepperCustom.java[render,tags=snippet,indent=0,group=Flow] +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- +include::{root}/frontend/demo/component/stepper/react/stepper-custom.tsx[render,tags=snippet,indent=0,group=React] +---- +endif::[] + +-- + + +== Best Practices + +=== Clear Step Labels + +Use clear, concise labels that accurately describe each step. Include descriptions for additional context when needed. + + +=== Logical Progression + +Arrange steps in a logical order that makes sense to users. Each step should build upon the previous one. + + +=== Visual Feedback + +Always indicate the current step clearly and show which steps have been completed. Use error states to highlight steps that need attention. + + +=== Validation + +Consider validating each step before allowing users to proceed to the next one. This prevents errors and ensures data completeness. + + +=== Mobile Considerations + +On smaller screens, consider using the vertical orientation or implementing a collapsible stepper pattern to save space. + + +== Keyboard Usage + +Users can navigate through clickable steps using the following keyboard shortcuts: + +- kbd:[Tab] / kbd:[Shift+Tab]: Move focus between steps +- kbd:[Enter] / kbd:[Space]: Activate the focused step (if it has a link) +- kbd:[Arrow keys]: Navigate between steps (when focused) + + +== Accessibility + +Stepper automatically includes proper ARIA attributes for screen readers: + +- The component has `role="navigation"` and appropriate ARIA labels +- Steps indicate their current state (active, completed, error) to assistive technologies +- Disabled steps are properly communicated to screen readers +- The step number and total count are announced for context + + +== Related Components + +[cols="1,2"] +|=== +|Component |Usage Recommendation + +|<<../tabs#,Tabs>> +|For switching between different views or sections within the same page. + +|<<../progress-bar#,Progress Bar>> +|For showing simple progress without navigation capabilities. + +|<<../breadcrumb#,Breadcrumb>> +|For showing hierarchical navigation path rather than process steps. + +|<<../side-nav#,Side Navigation>> +|For permanent navigation in application sidebars. +|=== + + +[discussion-id]`STEPPER-COMPONENT-DISCUSSION` \ No newline at end of file diff --git a/articles/components/stepper/stepper.png b/articles/components/stepper/stepper.png new file mode 100644 index 0000000000..e69de29bb2 diff --git a/articles/components/stepper/styling.adoc b/articles/components/stepper/styling.adoc new file mode 100644 index 0000000000..e0857b4e22 --- /dev/null +++ b/articles/components/stepper/styling.adoc @@ -0,0 +1,239 @@ +--- +tab-title: Styling +layout: tabbed-page +title: Stepper +page-title: Stepper component styling | Vaadin components +--- + += Styling + +include::../../_styling-section-intros.adoc[tag=selectors] + + +== Parts + +[.table-wrap] +[cols="1,1,2"] +|=== +|Part name |Element |Description + +|`nav` +|`