@xsolla/xui-stepper 0.149.1 → 0.151.0

package/README.md

@@ -1,246 +1,178 @@
 # Stepper
 
-> **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.
+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.
 
-A cross-platform React stepper component that displays progress through a sequence of steps, supporting horizontal and vertical layouts with multiple step states.
+> [!NOTE]
+> 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.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-stepper
-# or
-yarn add @xsolla/xui-stepper
 ```
 
-## Demo
-
-### Basic Stepper
+## Imports
 
 ```tsx
-import * as React from 'react';
-import { Stepper } from '@xsolla/xui-stepper';
-
-export default function BasicStepper() {
-  const steps = [
-    { title: 'Account', state: 'complete' as const },
-    { title: 'Payment', state: 'current' as const },
-    { title: 'Review', state: 'incomplete' as const },
-  ];
-
-  return <Stepper steps={steps} />;
-}
+import {
+  Stepper,
+  Step,
+  ProgressStep,
+  ProgressStepItem,
+} from '@xsolla/xui-stepper';
+import type {
+  StepperProps,
+  StepType,
+  StepStateType,
+  StepperDirectionType,
+  StepperUIVariantType,
+  StepperPaletteType,
+  StepperSize,
+  StepClickType,
+  ProgressStepProps,
+  ProgressStepItemProps,
+  ProgressStepItemState,
+  ProgressStepSize,
+} from '@xsolla/xui-stepper';
 ```
 
-### Vertical Stepper
+## Quick start
 
 ```tsx
-import * as React from 'react';
-import { Stepper } from '@xsolla/xui-stepper';
-
-export default function VerticalStepper() {
-  const steps = [
-    { title: 'Step 1', description: 'Account details', state: 'complete' as const },
-    { title: 'Step 2', description: 'Payment method', state: 'current' as const },
-    { title: 'Step 3', description: 'Order review', state: 'incomplete' as const },
-  ];
-
-  return <Stepper steps={steps} direction="vertical" />;
-}
-```
-
-### With States
+const steps = [
+  { title: 'Account', state: 'complete' as const },
+  { title: 'Payment', state: 'current' as const },
+  { title: 'Review', state: 'incomplete' as const },
+];
 
-```tsx
-import * as React from 'react';
-import { Stepper } from '@xsolla/xui-stepper';
-
-export default function StepStates() {
-  const steps = [
-    { title: 'Complete', state: 'complete' as const },
-    { title: 'Warning', state: 'warning' as const },
-    { title: 'Alert', state: 'alert' as const },
-    { title: 'Loading', state: 'loading' as const },
-    { title: 'Current', state: 'current' as const },
-    { title: 'Incomplete', state: 'incomplete' as const },
-  ];
-
-  return <Stepper steps={steps} />;
-}
+<Stepper steps={steps} />;
 ```
 
-## Anatomy
-
-```jsx
-import { Stepper } from '@xsolla/xui-stepper';
-
-<Stepper
-  steps={steps}              // Array of step objects
-  direction="horizontal"     // horizontal or vertical
-  size="md"                   // s or m
-  variantUI="current"        // current or simple
-  palette="brand"            // brand or brandSecondary
-  tail={false}               // Show connecting line (simple variant)
-  onClick={handleClick}      // Step click handler
-  aria-label="Checkout"      // Accessible label
-/>
-```
-
-## Examples
-
-### Checkout Flow
-
-```tsx
-import * as React from 'react';
-import { Stepper } from '@xsolla/xui-stepper';
-
-export default function CheckoutFlow() {
-  const [currentStep, setCurrentStep] = React.useState(1);
-
-  const steps = [
-    { title: 'Cart', state: currentStep > 0 ? 'complete' as const : 'incomplete' as const },
-    { title: 'Shipping', state: currentStep === 1 ? 'current' as const : currentStep > 1 ? 'complete' as const : 'incomplete' as const },
-    { title: 'Payment', state: currentStep === 2 ? 'current' as const : currentStep > 2 ? 'complete' as const : 'incomplete' as const },
-    { title: 'Confirm', state: currentStep === 3 ? 'current' as const : 'incomplete' as const },
-  ];
-
-  return (
-    <div>
-      <Stepper
-        steps={steps}
-        onClick={({ number }) => setCurrentStep(number)}
-      />
-      <div style={{ marginTop: 24 }}>
-        <button onClick={() => setCurrentStep(Math.max(0, currentStep - 1))}>Back</button>
-        <button onClick={() => setCurrentStep(Math.min(3, currentStep + 1))}>Next</button>
-      </div>
-    </div>
-  );
-}
-```
-
-### Registration Steps
+## API Reference
 
-```tsx
-import * as React from 'react';
-import { Stepper } from '@xsolla/xui-stepper';
-
-export default function RegistrationSteps() {
-  const steps = [
-    { title: 'Email', description: 'Verify your email', state: 'complete' as const },
-    { title: 'Profile', description: 'Set up your profile', state: 'current' as const },
-    { title: 'Preferences', description: 'Customize settings', state: 'incomplete' as const },
-  ];
-
-  return (
-    <Stepper
-      steps={steps}
-      direction="vertical"
-      variantUI="current"
-      size="md"
-    />
-  );
-}
-```
+### `<Stepper>`
 
-### Simple Variant with Tail
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `steps` | `StepType[]` | — | Step definitions. |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
+| `size` | `'sm' \| 'md'` | `'md'` | Step size. |
+| `variantUI` | `'current' \| 'simple'` | `'current'` | Visual variant. |
+| `palette` | `'brand' \| 'brandSecondary'` | `'brand'` | Colour palette. |
+| `tail` | `boolean` | `false` | Show connecting lines (simple variant). |
+| `onClick` | `StepClickType` | — | Fired when a step is clicked. |
+| `className` | `string` | — | Class applied to the root container; `customClass` is also accepted and concatenated for backwards compatibility. |
+| `aria-label` | `string` | — | Accessible label for the stepper. |
 
-```tsx
-import * as React from 'react';
-import { Stepper } from '@xsolla/xui-stepper';
+`Stepper` also accepts standard `BoxProps` (excluding `onClick`).
 
-export default function SimpleStepper() {
-  const steps = [
-    { title: 'Step 1', state: 'complete' as const },
-    { title: 'Step 2', state: 'current' as const },
-    { title: 'Step 3', state: 'incomplete' as const },
-  ];
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
-  return <Stepper steps={steps} variantUI="simple" tail />;
-}
-```
+### `<ProgressStep>`
 
-### Order Tracking
+A compact arrow-style progress indicator.
 
-```tsx
-import * as React from 'react';
-import { Stepper } from '@xsolla/xui-stepper';
-
-export default function OrderTracking() {
-  const steps = [
-    { title: 'Order Placed', description: 'Jan 20, 2024', state: 'complete' as const },
-    { title: 'Processing', description: 'Jan 21, 2024', state: 'complete' as const },
-    { title: 'Shipped', description: 'In transit', state: 'loading' as const },
-    { title: 'Delivered', state: 'incomplete' as const },
-  ];
-
-  return (
-    <Stepper
-      steps={steps}
-      direction="vertical"
-      palette="brand"
-    />
-  );
-}
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `count` | `number` | — | Total number of steps. |
+| `activeStep` | `number` | — | Zero-based active step index. |
+| `size` | `'sm' \| 'md'` | `'md'` | Indicator size. |
+| `arrows` | `boolean` | `true` | Show prev/next arrow buttons. |
+| `onStepPress` | `(step: number) => void` | — | Fired when navigation moves to a step. |
+| `className` | `string` | — | Class on the root container. |
 
-## API Reference
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
-### Stepper
+### `<ProgressStepItem>`
 
-**StepperProps:**
+Single dot used by `ProgressStep`; can be composed manually.
 
 | Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| steps | `StepType[]` | - | Array of step definitions. |
-| direction | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction. |
-| size | `"sm" \| "md"` | `"md"` | Step size. |
-| variantUI | `"current" \| "simple"` | `"current"` | Visual variant. |
-| palette | `"brand" \| "brandSecondary"` | `"brand"` | Color palette. |
-| tail | `boolean` | `false` | Show connecting lines (simple variant). |
-| onClick | `StepClickType` | - | Step click handler. |
-| aria-label | `string` | - | Accessible label for stepper. |
-
-**StepType:**
-
-```typescript
+| --- | --- | --- | --- |
+| `state` | `'active' \| 'default' \| 'hover'` | `'default'` | Visual state. |
+| `size` | `'sm' \| 'md'` | `'md'` | Dot size. |
+| `onPress` | `() => void` | — | Press handler. |
+| `onMouseEnter` | `() => void` | — | Mouse-enter handler. |
+| `onMouseLeave` | `() => void` | — | Mouse-leave handler. |
+| `className` | `string` | — | Custom class. |
+
+### `<Step>`
+
+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`).
+
+### Types
+
+```ts
+type StepperDirectionType = 'horizontal' | 'vertical';
+type StepperUIVariantType = 'current' | 'simple';
+type StepperPaletteType = 'brand' | 'brandSecondary';
+type StepperSize = 'sm' | 'md';
+type StepStateType =
+  | 'current'
+  | 'incomplete'
+  | 'loading'
+  | 'complete'
+  | 'alert'
+  | 'warning';
+type StepClickType = (args: { number: number; step: StepType }) => void;
+
 interface StepType {
   title: string | ReactElement;
   description?: string | ReactElement;
-  state?: "current" | "incomplete" | "loading" | "complete" | "alert" | "warning";
+  state?: StepStateType;
   disabled?: boolean;
   key?: string;
   noClick?: boolean;
 }
 ```
 
-**StepClickType:**
+## Examples
+
+### Vertical with descriptions
 
-```typescript
-type StepClickType = ({ number, step }: { number: number; step: StepType }) => void;
+```tsx
+<Stepper
+  direction="vertical"
+  steps={[
+    { title: 'Email', description: 'Verify your email', state: 'complete' },
+    { title: 'Profile', description: 'Set up your profile', state: 'current' },
+    { title: 'Preferences', description: 'Customise settings', state: 'incomplete' },
+  ]}
+/>
 ```
 
-## Step States
+### Step states
 
-| State | Description |
-| :---- | :---------- |
-| `current` | Active step, highlighted with brand color |
-| `complete` | Finished step with checkmark |
-| `incomplete` | Future step, muted appearance |
-| `loading` | Step in progress with spinner |
-| `alert` | Error state with alert color |
-| `warning` | Warning state with warning color |
+```tsx
+<Stepper
+  steps={[
+    { title: 'Complete', state: 'complete' },
+    { title: 'Warning', state: 'warning' },
+    { title: 'Alert', state: 'alert' },
+    { title: 'Loading', state: 'loading' },
+    { title: 'Current', state: 'current' },
+    { title: 'Incomplete', state: 'incomplete' },
+  ]}
+/>
+```
 
-## UI Variants
+### Simple variant with tail
 
-| Variant | Description |
-| :------ | :---------- |
-| `current` | Traditional stepper with step indicators and border line |
-| `simple` | Minimalist stepper with optional connecting tail |
+```tsx
+<Stepper variantUI="simple" tail steps={steps} />
+```
+
+### Progress step
+
+```tsx
+const [step, setStep] = useState(0);
+
+<ProgressStep count={5} activeStep={step} onStepPress={setStep} />;
+```
 
 ## Accessibility
 
-- Stepper uses `role="navigation"` for semantic meaning
-- Each step is keyboard accessible when clickable
-- `aria-label` provides context for screen readers
-- Step states are conveyed through visual and accessible means
-- Disabled steps are properly announced
+- Root uses `role="navigation"` for semantic meaning.
+- Steps are keyboard accessible when clickable; disabled steps are announced.
+- `aria-label` on the stepper provides context for assistive technology.
+- Step state is conveyed both visually and via accessible names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-stepper",
-  "version": "0.149.1",
+  "version": "0.151.0",
   "deprecated": "Use @xsolla/xui-b2b-stepper for B2B surfaces. This package will be removed in a future release.",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
@@ -15,9 +15,9 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.149.1",
-    "@xsolla/xui-icons": "0.149.1",
-    "@xsolla/xui-primitives-core": "0.149.1"
+    "@xsolla/xui-core": "0.151.0",
+    "@xsolla/xui-icons": "0.151.0",
+    "@xsolla/xui-primitives-core": "0.151.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",