Add Stepper component documentation

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`