feat(stepper): added stepper component

packages/react-components/src/components/Stepper/Stepper.module.scss

@@ -0,0 +1,29 @@
+$base-class: 'stepper';
+
+.#{$base-class} {
+  &__counter {
+    margin-bottom: var(--spacing-2);
+    color: var(--content-basic-disabled);
+    font-weight: var(--font-weight-medium);
+  }
+
+  &__steps__container {
+    display: flex;
+    flex-flow: row nowrap;
+  }
+
+  &__step {
+    margin-right: var(--spacing-1);
+    border-radius: var(--radius-1);
+    width: 22px;
+    height: 4px;
+
+    &--completed {
+      background-color: var(--content-basic-primary);
+    }
+
+    &--active {
+      background-color: var(--surface-tertiary-hover);
+    }
+  }
+}

packages/react-components/src/components/Stepper/Stepper.spec.tsx

@@ -0,0 +1,80 @@
+import { render, screen } from '@testing-library/react';
+
+import { Stepper } from './Stepper';
+
+describe('Stepper', () => {
+  it('displays correct number of steps', () => {
+    render(<Stepper activeStep={2} steps={4} />);
+
+    const stepsContainer = screen.getByTestId('stepper-container');
+
+    expect(stepsContainer?.children.length).toBe(4);
+  });
+
+  it('marks steps as completed and active correctly', () => {
+    render(<Stepper activeStep={2} steps={3} />);
+
+    const steps = screen.getByTestId('stepper-container').children;
+
+    expect(steps[0].className).toContain('completed');
+    expect(steps[1].className).toContain('completed');
+    expect(steps[2].className).toContain('active');
+  });
+
+  it('accepts and applies custom className', () => {
+    const customClass = 'custom-class';
+    render(<Stepper activeStep={1} steps={3} className={customClass} />);
+
+    expect(screen.getByTestId('stepper')).toHaveClass(customClass);
+  });
+  it('passes additional props to the main div', () => {
+    render(<Stepper activeStep={1} steps={3} aria-label="progress" />);
+
+    expect(screen.getByTestId('stepper')).toHaveAttribute(
+      'aria-label',
+      'progress'
+    );
+  });
+  describe('boundary values and normalization', () => {
+    it('should set minimum steps value to 1 when negative value is provided', () => {
+      render(<Stepper steps={-5} activeStep={1} />);
+
+      expect(screen.getByTestId('stepper')).toHaveTextContent('1/1');
+    });
+
+    it('should set minimum steps value to 1 when zero is provided', () => {
+      render(<Stepper steps={0} activeStep={1} />);
+
+      expect(screen.getByTestId('stepper')).toHaveTextContent('1/1');
+    });
+
+    it('should normalize activeStep to 1 when negative value is provided', () => {
+      render(<Stepper steps={5} activeStep={-3} />);
+
+      expect(screen.getByTestId('stepper')).toHaveTextContent('1/5');
+    });
+
+    it('should normalize activeStep to steps value when exceeding number of steps', () => {
+      render(<Stepper steps={3} activeStep={10} />);
+
+      expect(screen.getByTestId('stepper')).toHaveTextContent('3/3');
+    });
+
+    it('should properly normalize both steps and activeStep', () => {
+      render(<Stepper steps={-2} activeStep={-3} />);
+
+      expect(screen.getByTestId('stepper')).toHaveTextContent('1/1');
+    });
+
+    it('should normalize activeStep to steps value when activeStep is a float', () => {
+      render(<Stepper steps={5} activeStep={1.5} />);
+
+      expect(screen.getByTestId('stepper')).toHaveTextContent('2/5');
+    });
+    it('should normalize steps to 1 when steps is a float', () => {
+      render(<Stepper steps={1.5} activeStep={1} />);
+
+      expect(screen.getByTestId('stepper')).toHaveTextContent('1/2');
+    });
+  });
+});

packages/react-components/src/components/Stepper/Stepper.stories.tsx

@@ -0,0 +1,36 @@
+import { type Meta, type StoryObj } from '@storybook/react';
+
+import { Stepper } from './Stepper';
+
+const meta: Meta<typeof Stepper> = {
+  title: 'Components/Stepper',
+  component: Stepper,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Stepper>;
+
+export const Default: Story = {
+  args: {
+    activeStep: 1,
+    steps: 6,
+  },
+};
+
+export const MiddleProgress: Story = {
+  args: {
+    activeStep: 3,
+    steps: 6,
+  },
+};
+
+export const Completed: Story = {
+  args: {
+    activeStep: 6,
+    steps: 6,
+  },
+};

packages/react-components/src/components/Stepper/Stepper.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react';
+
+import cx from 'clsx';
+
+import { Text } from '../Typography';
+
+import { StepperProps } from './types';
+
+import styles from './Stepper.module.scss';
+
+const baseClass = 'stepper';
+
+export const Stepper: React.FC<StepperProps> = ({
+  activeStep,
+  steps,
+  className,
+  'data-testid': dataTestId = 'stepper',
+  ...divProps
+}) => {
+  const normalizedSteps = Math.round(Math.max(1, steps));
+
+  const normalizedActiveStep = Math.round(
+    Math.min(Math.max(1, activeStep), normalizedSteps)
+  );
+
+  const mergedClassNames = cx(styles[baseClass], className);
+
+  return (
+    <div className={mergedClassNames} data-testid={dataTestId} {...divProps}>
+      <Text size="sm" className={styles[`${baseClass}__counter`]}>
+        {normalizedActiveStep}/{normalizedSteps}
+      </Text>
+      <div
+        className={styles[`${baseClass}__steps__container`]}
+        data-testid={`${dataTestId}-container`}
+      >
+        {Array.from({ length: normalizedSteps }, (_, index) => {
+          const stepNumber = index + 1;
+          const isCompleted = stepNumber <= normalizedActiveStep;
+          const isActive = stepNumber > normalizedActiveStep;
+
+          return (
+            <div
+              key={stepNumber}
+              className={cx(styles[`${baseClass}__step`], {
+                [styles[`${baseClass}__step--completed`]]: isCompleted,
+                [styles[`${baseClass}__step--active`]]: isActive,
+              })}
+            />
+          );
+        })}
+      </div>
+    </div>
+  );
+};

packages/react-components/src/components/Stepper/index.ts

@@ -0,0 +1,2 @@
+export { Stepper } from './Stepper';
+export type { StepperProps } from './types';

packages/react-components/src/components/Stepper/types.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+
+export interface StepperProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Current active step (1-based)
+   */
+  activeStep: number;
+  /**
+   * Total number of steps
+   */
+  steps: number;
+  /**
+   * Custom class name
+   */
+  className?: string;
+  /**
+   * Optional test id for testing
+   */
+  'data-testid'?: string;
+}

packages/react-components/src/index.ts

@@ -62,3 +62,4 @@ export * from './components/UpdateBadge';
 export * from './components/FileUploadProgress';
 export * from './components/UploadBar';
 export * from './components/FloatingPortal';
+export * from './components/Stepper';