@ledgerhq/lumen-ui-rnative 0.0.71 → 0.0.72

package/src/lib/Components/Stepper/Stepper.mdx

@@ -0,0 +1,217 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import { CustomTabs, Tab } from '../../../../.storybook/components';
+import * as StepperStories from './Stepper.stories';
+import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
+import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
+import { Box } from '../Utility/Box';
+import { Text } from '../Utility/Text';
+
+<Meta title='Communication/Stepper/Docs' of={StepperStories} />
+
+# 🔄 Stepper
+
+<CustomTabs>
+  <Tab label="Overview">
+
+The Stepper component provides visual feedback for multi-step processes and workflows. It displays progress as a circular indicator showing the current step out of total steps, helping users understand where they are in a sequence.
+
+## Figma Library
+
+All stepper designs are created and managed in our components library. This ensures consistency across all platforms and use cases.
+
+- 🔗 **[Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=11977-94&m=dev)**
+
+## Interactive Example
+
+<Canvas of={StepperStories.Base} />
+<Controls of={StepperStories.Base} />
+
+## 🎯 Anatomy
+
+The Stepper consists of:
+- **Track Circle**: A muted circular background showing the full progress path
+- **Progress Arc**: A colored arc that fills clockwise from the top, representing completed progress
+- **Label**: Centered text showing "current/total" steps (e.g., "2/4")
+
+The progress arc starts at the top (12 o'clock position) and fills clockwise. When at 0% progress, a small dot appears at the top instead of an empty arc.
+
+---
+
+## 🏷️ Labels
+
+**Default label**: The default label is "currentStep/totalSteps" (e.g., "2/4").
+
+
+### Step Ranges
+- **`totalSteps`** must be between **2** and **9**
+- **`currentStep`** must be between **0** and **`totalSteps`**
+- Use `currentStep={0}` to show the initial state (minimal dot before starting)
+
+> ⚠️ Using more than **9** total steps or exceeding the valid range may cause the UI to break and text to be truncated inside the circular indicator.
+
+> ⚠️ Values outside valid ranges are automatically clamped: **`currentStep`** is kept between **0** and **`totalSteps`**.
+
+## 🎨 Disabled State
+
+The Stepper supports a disabled state that changes the progress arc to a muted appearance:
+
+<Canvas of={StepperStories.DisabledShowcase} />
+
+
+## Custom Labels
+
+By default, the stepper displays "currentStep/totalSteps" (e.g., "2/4"). You can provide a custom label for special cases:
+
+<Canvas of={StepperStories.WithCustomLabel} />
+
+> ⚠️ **Note**: The label and step counts are automatically truncated if they overflow the circular indicator. Keep custom labels short to ensure readability within the 48px circle.
+
+---
+
+## Usage Guidelines
+
+### Best Practices
+
+- Keep step counts reasonable (typically 3-7 steps)
+- Use descriptive labels when the numeric format isn't clear
+- Combine with textual step indicators for better context
+- Use disabled for paused or inactive steppers
+
+</Tab>
+<Tab label="Implementation">
+
+## Installation
+
+Install and set up the library with our [Setup Guide →](?path=/docs/getting-started-setup--docs).
+
+### Basic Usage
+
+Import and use the Stepper component:
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { Stepper } from '@ledgerhq/lumen-ui-rnative';
+
+function OnboardingFlow() {
+  const [currentStep, setCurrentStep] = useState(0);
+  const totalSteps = 4;
+
+  return (
+    <View>
+      <Stepper currentStep={currentStep} totalSteps={totalSteps} />
+      {/* Your step content */}
+    </View>
+  );
+}
+```
+
+### With Disabled State
+
+Control the visual state based on step completion:
+
+```tsx
+import React from 'react';
+import { Box, Stepper } from '@ledgerhq/lumen-ui-rnative';
+
+function MultiStepForm() {
+  return (
+    <Box lx={{ flexDirection: 'row', gap: 's16' }}>
+      <Stepper currentStep={1} totalSteps={3} />
+      <Stepper currentStep={2} totalSteps={3} />
+      <Stepper currentStep={0} totalSteps={3} disabled />
+    </Box>
+  );
+}
+```
+
+### Custom Labels
+
+Provide custom labels for localized or descriptive text:
+
+```tsx
+import React from 'react';
+import { Stepper } from '@ledgerhq/lumen-ui-rnative';
+
+function LocalizedStepper() {
+  const currentStep = 3;
+  const totalSteps = 5;
+  
+  return (
+    <Stepper 
+      currentStep={currentStep} 
+      totalSteps={totalSteps}
+      label={`Étape ${currentStep} sur ${totalSteps}`}
+    />
+  );
+}
+```
+
+## Do's and Don'ts
+
+<Box lx={{ gap: 's24' }}>
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Provide meaningful step counts'
+      description='Use realistic total steps that match your flow'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Stepper currentStep={3} totalSteps={5} />
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't use for single-step processes"
+      description='Steppers are for multi-step workflows only'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Stepper currentStep={1} totalSteps={1} />
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use disabled for paused steppers'
+      description='Reserve disabled for steppers that are not actively progressing'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Stepper 
+  currentStep={2} 
+  totalSteps={4} 
+  disabled 
+/>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't disable active steps"
+      description='Active steps in progress should not be disabled'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Stepper 
+  currentStep={2} 
+  totalSteps={4} 
+  disabled // Wrong for active step
+/>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <CommonRulesDoAndDont />
+</Box>
+
+</Tab>
+</CustomTabs>

package/src/lib/Components/Stepper/Stepper.stories.tsx

@@ -0,0 +1,62 @@
+import { Meta, StoryObj } from '@storybook/react-native-web-vite';
+import { Box } from '../Utility/Box';
+import { Text } from '../Utility/Text';
+import { Stepper } from './Stepper';
+
+const meta: Meta<typeof Stepper> = {
+  title: 'Communication/Stepper',
+  component: Stepper,
+  parameters: {
+    actions: { disable: true },
+  },
+  argTypes: {
+    currentStep: { control: 'number' },
+    totalSteps: { control: 'number' },
+    disabled: { control: 'boolean' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Stepper>;
+
+export const Base: Story = {
+  args: {
+    currentStep: 2,
+    totalSteps: 4,
+  },
+  render: (args) => <Stepper {...args} />,
+};
+
+export const DisabledShowcase: Story = {
+  render: () => (
+    <Box lx={{ gap: 's32', alignItems: 'center' }}>
+      <Box lx={{ alignItems: 'center', gap: 's8' }}>
+        <Text typography='body3' lx={{ color: 'muted' }}>
+          Default (2/4)
+        </Text>
+        <Stepper currentStep={2} totalSteps={4} />
+      </Box>
+      <Box lx={{ alignItems: 'center', gap: 's8' }}>
+        <Text typography='body3' lx={{ color: 'muted' }}>
+          Disabled (2/4)
+        </Text>
+        <Stepper currentStep={2} totalSteps={4} disabled />
+      </Box>
+      <Box lx={{ alignItems: 'center', gap: 's8' }}>
+        <Text typography='body3' lx={{ color: 'muted' }}>
+          Unstarted (0/9)
+        </Text>
+        <Stepper currentStep={0} totalSteps={9} />
+      </Box>
+    </Box>
+  ),
+};
+
+export const WithCustomLabel: Story = {
+  args: {
+    currentStep: 5,
+    totalSteps: 5,
+    label: '🎉',
+  },
+  render: (args) => <Stepper {...args} />,
+};

package/src/lib/Components/Stepper/Stepper.test.tsx

@@ -0,0 +1,132 @@
+import { describe, it, expect } from '@jest/globals';
+import { ledgerLiveThemes } from '@ledgerhq/lumen-design-core';
+import { render } from '@testing-library/react-native';
+import React from 'react';
+import { ThemeProvider } from '../ThemeProvider/ThemeProvider';
+import { Stepper } from './Stepper';
+
+const TestWrapper = ({ children }: { children: React.ReactNode }) => (
+  <ThemeProvider themes={ledgerLiveThemes} colorScheme='dark' locale='en'>
+    {children}
+  </ThemeProvider>
+);
+
+describe('Stepper Component', () => {
+  it('should render with i18n accessibility label', async () => {
+    const { findByLabelText } = render(
+      <TestWrapper>
+        <Stepper currentStep={2} totalSteps={4} />
+      </TestWrapper>,
+    );
+    const stepper = await findByLabelText('Step 2 of 4');
+    expect(stepper).toBeTruthy();
+    expect(stepper.props.accessibilityRole).toBe('progressbar');
+    expect(stepper.props.accessibilityValue).toEqual(
+      expect.objectContaining({
+        now: 2,
+        min: 1,
+        max: 4,
+        text: '2/4',
+      }),
+    );
+  });
+
+  it('should render with custom label', () => {
+    const { getByLabelText } = render(
+      <TestWrapper>
+        <Stepper currentStep={3} totalSteps={5} label='Step 3 of 5' />
+      </TestWrapper>,
+    );
+    const stepper = getByLabelText('Step 3 of 5');
+    expect(stepper).toBeTruthy();
+  });
+
+  it('should render active border color by default', () => {
+    const { getByTestId } = render(
+      <TestWrapper>
+        <Stepper currentStep={1} totalSteps={4} testID='stepper' />
+      </TestWrapper>,
+    );
+    const stepper = getByTestId('stepper');
+    expect(stepper).toBeTruthy();
+  });
+
+  it('should render disabled style when disabled', () => {
+    const { getByTestId } = render(
+      <TestWrapper>
+        <Stepper currentStep={2} totalSteps={4} disabled testID='stepper' />
+      </TestWrapper>,
+    );
+    const stepper = getByTestId('stepper');
+    expect(stepper).toBeTruthy();
+  });
+
+  it('should clamp currentStep to totalSteps in display', () => {
+    const { getByText } = render(
+      <TestWrapper>
+        <Stepper currentStep={10} totalSteps={4} />
+      </TestWrapper>,
+    );
+    expect(getByText('4')).toBeTruthy();
+    expect(getByText('/4')).toBeTruthy();
+  });
+
+  it('should handle zero totalSteps gracefully', async () => {
+    const { findByLabelText } = render(
+      <TestWrapper>
+        <Stepper currentStep={1} totalSteps={0} />
+      </TestWrapper>,
+    );
+    const stepper = await findByLabelText('Step 0 of 0');
+    expect(stepper).toBeTruthy();
+  });
+
+  it('should handle currentStep <= 0 (minimal dot)', async () => {
+    const { findByLabelText } = render(
+      <TestWrapper>
+        <Stepper currentStep={0} totalSteps={4} />
+      </TestWrapper>,
+    );
+    const stepper = await findByLabelText('Step 0 of 4');
+    expect(stepper).toBeTruthy();
+  });
+
+  it('should clamp negative currentStep to 0', async () => {
+    const { findByLabelText, getByText } = render(
+      <TestWrapper>
+        <Stepper currentStep={-3} totalSteps={4} />
+      </TestWrapper>,
+    );
+    const stepper = await findByLabelText('Step 0 of 4');
+    expect(stepper).toBeTruthy();
+    expect(stepper.props.accessibilityValue).toEqual(
+      expect.objectContaining({
+        now: -3,
+        min: 1,
+        max: 4,
+        text: '0/4',
+      }),
+    );
+    expect(getByText('0')).toBeTruthy();
+    expect(getByText('/4')).toBeTruthy();
+  });
+
+  it('should apply custom lx props', () => {
+    const { getByTestId } = render(
+      <TestWrapper>
+        <Stepper
+          currentStep={2}
+          totalSteps={4}
+          testID='stepper'
+          lx={{ marginTop: 's8' }}
+        />
+      </TestWrapper>,
+    );
+    const stepper = getByTestId('stepper');
+    const style = stepper.props.style;
+    const flatStyle = Array.isArray(style)
+      ? Object.assign({}, ...style)
+      : style;
+    expect(flatStyle.marginTop).toBe(8);
+  });
+});

package/src/lib/Components/Stepper/Stepper.tsx

@@ -0,0 +1,159 @@
+import { getStepperCalculations } from '@ledgerhq/lumen-utils-shared';
+import { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import Svg, { Circle } from 'react-native-svg';
+import { useCommonTranslation } from '../../../i18n';
+import { useTheme } from '../../../styles';
+import { Box } from '../Utility/Box';
+import { Text } from '../Utility/Text';
+import { StepperProps } from './types';
+
+const SIZE = 48;
+const STROKE_WIDTH = 4;
+
+const AnimatedCircle = Animated.createAnimatedComponent(Circle);
+
+/**
+ * A circular stepper component showing progress as current step out of total steps.
+ * Renders a track arc with a progress arc and a center label.
+ *
+ * @see [Figma – Stepper](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=11977-94&m=dev)
+ *
+ * @example
+ * <Stepper currentStep={1} totalSteps={4} />
+ * <Stepper currentStep={0} totalSteps={9} disabled /> // Shows minimal dot, disabled style
+ */
+export const Stepper = ({
+  lx = {},
+  currentStep,
+  totalSteps,
+  disabled = false,
+  label,
+  ref,
+  ...props
+}: StepperProps) => {
+  const { t } = useCommonTranslation();
+  const { theme } = useTheme();
+
+  const {
+    displayLabel,
+    r,
+    cx,
+    cy,
+    trackDashArray,
+    progressDashArray,
+    progressDashOffset,
+  } = getStepperCalculations({
+    currentStep,
+    totalSteps,
+    size: SIZE,
+    label,
+    strokeWidth: STROKE_WIDTH,
+  });
+
+  const animatedOffset = useRef(new Animated.Value(progressDashOffset)).current;
+
+  useEffect(() => {
+    const animation = Animated.timing(animatedOffset, {
+      toValue: progressDashOffset,
+      duration: 300,
+      easing: Easing.inOut(Easing.ease),
+      useNativeDriver: false,
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [progressDashOffset, animatedOffset]);
+
+  return (
+    <Box
+      ref={ref}
+      accessibilityRole='progressbar'
+      accessibilityValue={{
+        now: currentStep,
+        min: 1,
+        max: totalSteps,
+        text: displayLabel,
+      }}
+      accessibilityLabel={
+        label ??
+        t('components.stepper.progressAriaLabel', {
+          currentStep: Math.min(Math.max(currentStep, 0), totalSteps),
+          totalSteps,
+        })
+      }
+      lx={{
+        width: 's48',
+        height: 's48',
+        flexShrink: 0,
+        alignItems: 'center',
+        justifyContent: 'center',
+        borderRadius: 'full',
+        ...lx,
+      }}
+      {...props}
+    >
+      <Svg
+        width={SIZE}
+        height={SIZE}
+        viewBox={`0 0 ${SIZE} ${SIZE}`}
+        style={{ transform: [{ rotate: '135deg' }] }}
+      >
+        <Circle
+          cx={cx}
+          cy={cy}
+          r={r}
+          fill='none'
+          stroke={theme.colors.border.mutedSubtle}
+          strokeLinecap='round'
+          strokeWidth={STROKE_WIDTH}
+          strokeDasharray={trackDashArray}
+          strokeDashoffset={0}
+        />
+        <AnimatedCircle
+          cx={cx}
+          cy={cy}
+          r={r}
+          fill='none'
+          stroke={
+            disabled
+              ? theme.colors.border.mutedSubtleHover
+              : theme.colors.border.active
+          }
+          strokeLinecap='round'
+          strokeWidth={STROKE_WIDTH}
+          strokeDasharray={progressDashArray}
+          strokeDashoffset={animatedOffset}
+        />
+      </Svg>
+      <Box
+        lx={{
+          position: 'absolute',
+          alignItems: 'center',
+          justifyContent: 'center',
+          flexDirection: 'row',
+          top: 's0',
+          left: 's0',
+          right: 's0',
+          bottom: 's0',
+        }}
+      >
+        {label ? (
+          <Text typography='body2SemiBold' lx={{ color: 'base' }}>
+            {label}
+          </Text>
+        ) : (
+          <>
+            <Text typography='body1SemiBold' lx={{ color: 'base' }}>
+              {Math.min(Math.max(currentStep, 0), totalSteps)}
+            </Text>
+            <Text typography='body2SemiBold' lx={{ color: 'muted' }}>
+              /{totalSteps}
+            </Text>
+          </>
+        )}
+      </Box>
+    </Box>
+  );
+};
+
+Stepper.displayName = 'Stepper';

package/src/lib/Components/Stepper/index.ts

@@ -0,0 +1,2 @@
+export * from './Stepper';
+export * from './types';

package/src/lib/Components/Stepper/types.ts

@@ -0,0 +1,21 @@
+import { StyledViewProps } from '../../../styles';
+
+export type StepperProps = {
+  /**
+   * Current step number (1-based). Use 0 or negative to show minimal dot (before starting).
+   */
+  currentStep: number;
+  /**
+   * Total number of steps.
+   */
+  totalSteps: number;
+  /**
+   * Whether the stepper is disabled. Changes the progress arc to a muted style.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Optional custom label. Defaults to "{currentStep}/{totalSteps}".
+   */
+  label?: string;
+} & Omit<StyledViewProps, 'children'>;

package/src/lib/Components/index.ts

@@ -17,7 +17,10 @@ export * from './NavBar';
 export * from './PageIndicator';
 export * from './SearchInput';
 export * from './Select';
+export * from './Skeleton';
+export * from './Spinner';
 export * from './Spot';
+export * from './Stepper';
 export * from './Subheader';
 export * from './Switch';
 export * from './TabBar';