@xsolla/xui-stepper 0.150.0 → 0.151.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +129 -197
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,246 +1,178 @@
1
1
  # Stepper
2
2
 
3
- > **Deprecated.** For B2B surfaces, use [`@xsolla/xui-b2b-stepper`](./b2b-stepper.md) which implements the current Figma design. This package remains available for existing consumers of `@xsolla/xui-display` and will be removed in a future release.
3
+ A cross-platform stepper that displays progress through a sequence of steps in horizontal or vertical layouts; ships alongside `ProgressStep` and `ProgressStepItem` for compact arrow-style indicators.
4
4
 
5
- A cross-platform React stepper component that displays progress through a sequence of steps, supporting horizontal and vertical layouts with multiple step states.
5
+ > [!NOTE]
6
+ > Deprecated for B2B surfaces — use [`@xsolla/xui-b2b-stepper`](./b2b-stepper.md), which implements the current Figma design. This package remains available for existing consumers and will be removed in a future release.
6
7
 
7
8
  ## Installation
8
9
 
9
10
  ```bash
10
11
  npm install @xsolla/xui-stepper
11
- # or
12
- yarn add @xsolla/xui-stepper
13
12
  ```
14
13
 
15
- ## Demo
16
-
17
- ### Basic Stepper
14
+ ## Imports
18
15
 
19
16
  ```tsx
20
- import * as React from 'react';
21
- import { Stepper } from '@xsolla/xui-stepper';
22
-
23
- export default function BasicStepper() {
24
- const steps = [
25
- { title: 'Account', state: 'complete' as const },
26
- { title: 'Payment', state: 'current' as const },
27
- { title: 'Review', state: 'incomplete' as const },
28
- ];
29
-
30
- return <Stepper steps={steps} />;
31
- }
17
+ import {
18
+ Stepper,
19
+ Step,
20
+ ProgressStep,
21
+ ProgressStepItem,
22
+ } from '@xsolla/xui-stepper';
23
+ import type {
24
+ StepperProps,
25
+ StepType,
26
+ StepStateType,
27
+ StepperDirectionType,
28
+ StepperUIVariantType,
29
+ StepperPaletteType,
30
+ StepperSize,
31
+ StepClickType,
32
+ ProgressStepProps,
33
+ ProgressStepItemProps,
34
+ ProgressStepItemState,
35
+ ProgressStepSize,
36
+ } from '@xsolla/xui-stepper';
32
37
  ```
33
38
 
34
- ### Vertical Stepper
39
+ ## Quick start
35
40
 
36
41
  ```tsx
37
- import * as React from 'react';
38
- import { Stepper } from '@xsolla/xui-stepper';
39
-
40
- export default function VerticalStepper() {
41
- const steps = [
42
- { title: 'Step 1', description: 'Account details', state: 'complete' as const },
43
- { title: 'Step 2', description: 'Payment method', state: 'current' as const },
44
- { title: 'Step 3', description: 'Order review', state: 'incomplete' as const },
45
- ];
46
-
47
- return <Stepper steps={steps} direction="vertical" />;
48
- }
49
- ```
50
-
51
- ### With States
42
+ const steps = [
43
+ { title: 'Account', state: 'complete' as const },
44
+ { title: 'Payment', state: 'current' as const },
45
+ { title: 'Review', state: 'incomplete' as const },
46
+ ];
52
47
 
53
- ```tsx
54
- import * as React from 'react';
55
- import { Stepper } from '@xsolla/xui-stepper';
56
-
57
- export default function StepStates() {
58
- const steps = [
59
- { title: 'Complete', state: 'complete' as const },
60
- { title: 'Warning', state: 'warning' as const },
61
- { title: 'Alert', state: 'alert' as const },
62
- { title: 'Loading', state: 'loading' as const },
63
- { title: 'Current', state: 'current' as const },
64
- { title: 'Incomplete', state: 'incomplete' as const },
65
- ];
66
-
67
- return <Stepper steps={steps} />;
68
- }
48
+ <Stepper steps={steps} />;
69
49
  ```
70
50
 
71
- ## Anatomy
72
-
73
- ```jsx
74
- import { Stepper } from '@xsolla/xui-stepper';
75
-
76
- <Stepper
77
- steps={steps} // Array of step objects
78
- direction="horizontal" // horizontal or vertical
79
- size="md" // s or m
80
- variantUI="current" // current or simple
81
- palette="brand" // brand or brandSecondary
82
- tail={false} // Show connecting line (simple variant)
83
- onClick={handleClick} // Step click handler
84
- aria-label="Checkout" // Accessible label
85
- />
86
- ```
87
-
88
- ## Examples
89
-
90
- ### Checkout Flow
91
-
92
- ```tsx
93
- import * as React from 'react';
94
- import { Stepper } from '@xsolla/xui-stepper';
95
-
96
- export default function CheckoutFlow() {
97
- const [currentStep, setCurrentStep] = React.useState(1);
98
-
99
- const steps = [
100
- { title: 'Cart', state: currentStep > 0 ? 'complete' as const : 'incomplete' as const },
101
- { title: 'Shipping', state: currentStep === 1 ? 'current' as const : currentStep > 1 ? 'complete' as const : 'incomplete' as const },
102
- { title: 'Payment', state: currentStep === 2 ? 'current' as const : currentStep > 2 ? 'complete' as const : 'incomplete' as const },
103
- { title: 'Confirm', state: currentStep === 3 ? 'current' as const : 'incomplete' as const },
104
- ];
105
-
106
- return (
107
- <div>
108
- <Stepper
109
- steps={steps}
110
- onClick={({ number }) => setCurrentStep(number)}
111
- />
112
- <div style={{ marginTop: 24 }}>
113
- <button onClick={() => setCurrentStep(Math.max(0, currentStep - 1))}>Back</button>
114
- <button onClick={() => setCurrentStep(Math.min(3, currentStep + 1))}>Next</button>
115
- </div>
116
- </div>
117
- );
118
- }
119
- ```
120
-
121
- ### Registration Steps
51
+ ## API Reference
122
52
 
123
- ```tsx
124
- import * as React from 'react';
125
- import { Stepper } from '@xsolla/xui-stepper';
126
-
127
- export default function RegistrationSteps() {
128
- const steps = [
129
- { title: 'Email', description: 'Verify your email', state: 'complete' as const },
130
- { title: 'Profile', description: 'Set up your profile', state: 'current' as const },
131
- { title: 'Preferences', description: 'Customize settings', state: 'incomplete' as const },
132
- ];
133
-
134
- return (
135
- <Stepper
136
- steps={steps}
137
- direction="vertical"
138
- variantUI="current"
139
- size="md"
140
- />
141
- );
142
- }
143
- ```
53
+ ### `<Stepper>`
144
54
 
145
- ### Simple Variant with Tail
55
+ | Prop | Type | Default | Description |
56
+ | --- | --- | --- | --- |
57
+ | `steps` | `StepType[]` | — | Step definitions. |
58
+ | `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
59
+ | `size` | `'sm' \| 'md'` | `'md'` | Step size. |
60
+ | `variantUI` | `'current' \| 'simple'` | `'current'` | Visual variant. |
61
+ | `palette` | `'brand' \| 'brandSecondary'` | `'brand'` | Colour palette. |
62
+ | `tail` | `boolean` | `false` | Show connecting lines (simple variant). |
63
+ | `onClick` | `StepClickType` | — | Fired when a step is clicked. |
64
+ | `className` | `string` | — | Class applied to the root container; `customClass` is also accepted and concatenated for backwards compatibility. |
65
+ | `aria-label` | `string` | — | Accessible label for the stepper. |
146
66
 
147
- ```tsx
148
- import * as React from 'react';
149
- import { Stepper } from '@xsolla/xui-stepper';
67
+ `Stepper` also accepts standard `BoxProps` (excluding `onClick`).
150
68
 
151
- export default function SimpleStepper() {
152
- const steps = [
153
- { title: 'Step 1', state: 'complete' as const },
154
- { title: 'Step 2', state: 'current' as const },
155
- { title: 'Step 3', state: 'incomplete' as const },
156
- ];
69
+ Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
157
70
 
158
- return <Stepper steps={steps} variantUI="simple" tail />;
159
- }
160
- ```
71
+ ### `<ProgressStep>`
161
72
 
162
- ### Order Tracking
73
+ A compact arrow-style progress indicator.
163
74
 
164
- ```tsx
165
- import * as React from 'react';
166
- import { Stepper } from '@xsolla/xui-stepper';
167
-
168
- export default function OrderTracking() {
169
- const steps = [
170
- { title: 'Order Placed', description: 'Jan 20, 2024', state: 'complete' as const },
171
- { title: 'Processing', description: 'Jan 21, 2024', state: 'complete' as const },
172
- { title: 'Shipped', description: 'In transit', state: 'loading' as const },
173
- { title: 'Delivered', state: 'incomplete' as const },
174
- ];
175
-
176
- return (
177
- <Stepper
178
- steps={steps}
179
- direction="vertical"
180
- palette="brand"
181
- />
182
- );
183
- }
184
- ```
75
+ | Prop | Type | Default | Description |
76
+ | --- | --- | --- | --- |
77
+ | `count` | `number` | — | Total number of steps. |
78
+ | `activeStep` | `number` | — | Zero-based active step index. |
79
+ | `size` | `'sm' \| 'md'` | `'md'` | Indicator size. |
80
+ | `arrows` | `boolean` | `true` | Show prev/next arrow buttons. |
81
+ | `onStepPress` | `(step: number) => void` | — | Fired when navigation moves to a step. |
82
+ | `className` | `string` | — | Class on the root container. |
185
83
 
186
- ## API Reference
84
+ Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
187
85
 
188
- ### Stepper
86
+ ### `<ProgressStepItem>`
189
87
 
190
- **StepperProps:**
88
+ Single dot used by `ProgressStep`; can be composed manually.
191
89
 
192
90
  | Prop | Type | Default | Description |
193
- | :--- | :--- | :------ | :---------- |
194
- | steps | `StepType[]` | - | Array of step definitions. |
195
- | direction | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction. |
196
- | size | `"sm" \| "md"` | `"md"` | Step size. |
197
- | variantUI | `"current" \| "simple"` | `"current"` | Visual variant. |
198
- | palette | `"brand" \| "brandSecondary"` | `"brand"` | Color palette. |
199
- | tail | `boolean` | `false` | Show connecting lines (simple variant). |
200
- | onClick | `StepClickType` | - | Step click handler. |
201
- | aria-label | `string` | - | Accessible label for stepper. |
202
-
203
- **StepType:**
204
-
205
- ```typescript
91
+ | --- | --- | --- | --- |
92
+ | `state` | `'active' \| 'default' \| 'hover'` | `'default'` | Visual state. |
93
+ | `size` | `'sm' \| 'md'` | `'md'` | Dot size. |
94
+ | `onPress` | `() => void` | — | Press handler. |
95
+ | `onMouseEnter` | `() => void` | — | Mouse-enter handler. |
96
+ | `onMouseLeave` | `() => void` | — | Mouse-leave handler. |
97
+ | `className` | `string` | — | Custom class. |
98
+
99
+ ### `<Step>`
100
+
101
+ Internal step renderer used by `Stepper`; exported for advanced layouts. Props mirror `StepType` (see Types below) plus the layout context props the parent `Stepper` injects (`size`, `direction`, `variantUI`, `palette`, `stepNumber`, `tail`, `isLast`, `onClick`).
102
+
103
+ ### Types
104
+
105
+ ```ts
106
+ type StepperDirectionType = 'horizontal' | 'vertical';
107
+ type StepperUIVariantType = 'current' | 'simple';
108
+ type StepperPaletteType = 'brand' | 'brandSecondary';
109
+ type StepperSize = 'sm' | 'md';
110
+ type StepStateType =
111
+ | 'current'
112
+ | 'incomplete'
113
+ | 'loading'
114
+ | 'complete'
115
+ | 'alert'
116
+ | 'warning';
117
+ type StepClickType = (args: { number: number; step: StepType }) => void;
118
+
206
119
  interface StepType {
207
120
  title: string | ReactElement;
208
121
  description?: string | ReactElement;
209
- state?: "current" | "incomplete" | "loading" | "complete" | "alert" | "warning";
122
+ state?: StepStateType;
210
123
  disabled?: boolean;
211
124
  key?: string;
212
125
  noClick?: boolean;
213
126
  }
214
127
  ```
215
128
 
216
- **StepClickType:**
129
+ ## Examples
130
+
131
+ ### Vertical with descriptions
217
132
 
218
- ```typescript
219
- type StepClickType = ({ number, step }: { number: number; step: StepType }) => void;
133
+ ```tsx
134
+ <Stepper
135
+ direction="vertical"
136
+ steps={[
137
+ { title: 'Email', description: 'Verify your email', state: 'complete' },
138
+ { title: 'Profile', description: 'Set up your profile', state: 'current' },
139
+ { title: 'Preferences', description: 'Customise settings', state: 'incomplete' },
140
+ ]}
141
+ />
220
142
  ```
221
143
 
222
- ## Step States
144
+ ### Step states
223
145
 
224
- | State | Description |
225
- | :---- | :---------- |
226
- | `current` | Active step, highlighted with brand color |
227
- | `complete` | Finished step with checkmark |
228
- | `incomplete` | Future step, muted appearance |
229
- | `loading` | Step in progress with spinner |
230
- | `alert` | Error state with alert color |
231
- | `warning` | Warning state with warning color |
146
+ ```tsx
147
+ <Stepper
148
+ steps={[
149
+ { title: 'Complete', state: 'complete' },
150
+ { title: 'Warning', state: 'warning' },
151
+ { title: 'Alert', state: 'alert' },
152
+ { title: 'Loading', state: 'loading' },
153
+ { title: 'Current', state: 'current' },
154
+ { title: 'Incomplete', state: 'incomplete' },
155
+ ]}
156
+ />
157
+ ```
232
158
 
233
- ## UI Variants
159
+ ### Simple variant with tail
234
160
 
235
- | Variant | Description |
236
- | :------ | :---------- |
237
- | `current` | Traditional stepper with step indicators and border line |
238
- | `simple` | Minimalist stepper with optional connecting tail |
161
+ ```tsx
162
+ <Stepper variantUI="simple" tail steps={steps} />
163
+ ```
164
+
165
+ ### Progress step
166
+
167
+ ```tsx
168
+ const [step, setStep] = useState(0);
169
+
170
+ <ProgressStep count={5} activeStep={step} onStepPress={setStep} />;
171
+ ```
239
172
 
240
173
  ## Accessibility
241
174
 
242
- - Stepper uses `role="navigation"` for semantic meaning
243
- - Each step is keyboard accessible when clickable
244
- - `aria-label` provides context for screen readers
245
- - Step states are conveyed through visual and accessible means
246
- - Disabled steps are properly announced
175
+ - Root uses `role="navigation"` for semantic meaning.
176
+ - Steps are keyboard accessible when clickable; disabled steps are announced.
177
+ - `aria-label` on the stepper provides context for assistive technology.
178
+ - Step state is conveyed both visually and via accessible names.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xsolla/xui-stepper",
3
- "version": "0.150.0",
3
+ "version": "0.151.0",
4
4
  "deprecated": "Use @xsolla/xui-b2b-stepper for B2B surfaces. This package will be removed in a future release.",
5
5
  "main": "./web/index.js",
6
6
  "module": "./web/index.mjs",
@@ -15,9 +15,9 @@
15
15
  "test:coverage": "vitest run --coverage"
16
16
  },
17
17
  "dependencies": {
18
- "@xsolla/xui-core": "0.150.0",
19
- "@xsolla/xui-icons": "0.150.0",
20
- "@xsolla/xui-primitives-core": "0.150.0"
18
+ "@xsolla/xui-core": "0.151.0",
19
+ "@xsolla/xui-icons": "0.151.0",
20
+ "@xsolla/xui-primitives-core": "0.151.0"
21
21
  },
22
22
  "peerDependencies": {
23
23
  "react": ">=16.8.0",