@ledgerhq/lumen-ui-rnative 0.0.70 → 0.0.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ledgerhq/lumen-ui-rnative",
-  "version": "0.0.70",
+  "version": "0.0.71",
   "license": "Apache-2.0",
   "keywords": [
     "react-native",
@@ -27,7 +27,7 @@
     "./styles": "./src/styles/index.ts"
   },
   "dependencies": {
-    "@ledgerhq/lumen-utils-shared": "0.0.18",
+    "@ledgerhq/lumen-utils-shared": "0.0.19",
     "i18next": "^23.7.0",
     "react-i18next": "^14.0.0"
   },
@@ -37,8 +37,8 @@
   "peerDependencies": {
     "@types/react": "^19.0.0",
     "@gorhom/bottom-sheet": "^5.0.0",
-    "@ledgerhq/lumen-design-core": "0.0.51",
-    "react": "19.0.0",
+    "@ledgerhq/lumen-design-core": "0.0.52",
+    "react": "^19.0.0",
     "react-native": "~0.79.7",
     "react-native-reanimated": "^3.0.0",
     "react-native-safe-area-context": "^4.0.0 || ^5.0.0",

package/src/index.ts

@@ -1,3 +1,4 @@
 export { type SupportedLocale, Languages } from './i18n';
 export * from './lib/Components';
 export * from './lib/Patterns';
+export * from './lib/Animations';

package/src/lib/Animations/Pulse/Pulse.mdx

@@ -0,0 +1,86 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as PulseStories from './Pulse.stories';
+import { Pulse } from './Pulse';
+import {
+  CustomTabs,
+  Tab,
+} from '../../../../.storybook/components';
+import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
+
+<Meta title='Animations/Pulse' of={PulseStories} />
+
+# ⚡ Pulse
+
+<CustomTabs>
+  <Tab label="Overview">
+
+## Introduction
+
+The Pulse animation creates a smooth opacity fade in/out effect, commonly used for loading states and skeleton screens. It provides visual feedback that content is being processed or loaded.
+
+## Anatomy
+
+<Canvas of={PulseStories.Base} />
+
+- **Children**: The content to animate with opacity changes
+- **Duration**: Complete cycle duration (fade out + fade in)
+- **Animate**: Controls whether the animation is active
+
+## Properties
+
+### Overview
+
+<Canvas of={PulseStories.Base} />
+<Controls of={PulseStories.Base} />
+
+### Duration
+
+The duration prop controls how long a complete pulse cycle takes (fade out to fade in). Shorter durations create faster, more noticeable pulses, while longer durations provide subtle, gentle feedback.
+
+<Canvas of={PulseStories.DurationShowcase} />
+
+### Practical Usage
+
+The Pulse animation is commonly used with components like AmountDisplay to indicate that data is being fetched or updated.
+
+<Canvas of={PulseStories.WithAmountDisplay} />
+
+## Accessibility
+
+- Does not rely on animation alone to convey information
+- Maintains readable opacity range (0.35 to 1.0)
+
+</Tab>
+<Tab label="Implementation">
+
+## Installation
+
+```bash
+npm install @ledgerhq/lumen-ui-rnative
+```
+
+> **Note**: `@ledgerhq/lumen-design-core` and other peer dependencies (`react`, `react-native`, etc.) are required. See our Setup Guide for complete installation.
+
+## Basic Usage
+
+```tsx
+import { Pulse } from '@ledgerhq/lumen-ui-rnative';
+import { View } from 'react-native';
+
+function LoadingCard() {
+  return (
+    <Pulse animate={true}>
+      <View style={{ width: 200, height: 100, backgroundColor: '#E0E0E0' }} />
+    </Pulse>
+  );
+}
+```
+
+## Performance Considerations
+
+- The Pulse component uses `useNativeDriver` for optimal performance on native platforms
+- Animation cleanup is handled automatically on unmount
+- Consider using different duration values for multiple skeleton elements to create a more natural loading pattern
+
+</Tab>
+</CustomTabs>

package/src/lib/Animations/Pulse/Pulse.stories.tsx

@@ -0,0 +1,90 @@
+import type { Meta, StoryObj } from '@storybook/react-native-web-vite';
+import { View } from 'react-native';
+import { AmountDisplay } from '../../Components/AmountDisplay';
+import { type FormattedValue } from '../../Components/AmountDisplay/types';
+import { Box, Text } from '../../Components/Utility';
+import { Pulse } from './Pulse';
+
+const usdFormatter = (value: number): FormattedValue => {
+  const [integerPart, decimalPart] = value.toFixed(2).split(/\.|,/);
+
+  return {
+    integerPart,
+    decimalPart,
+    currencyText: '$',
+    decimalSeparator: '.',
+    currencyPosition: 'start',
+  };
+};
+
+const meta: Meta<typeof Pulse> = {
+  title: 'Animations/Pulse',
+  component: Pulse,
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof Pulse>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Base: Story = {
+  args: {
+    duration: 2000,
+    animate: true,
+    children: (
+      <Box lx={{ width: 's48', height: 's48', backgroundColor: 'accent' }} />
+    ),
+  },
+};
+
+export const DurationShowcase: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 24, alignItems: 'center' }}>
+      <View style={{ alignItems: 'center', gap: 8 }}>
+        <Pulse duration={1000} animate={true}>
+          <Box
+            lx={{ width: 's48', height: 's48', backgroundColor: 'accent' }}
+          />
+        </Pulse>
+        <Text typography='body4' lx={{ color: 'muted' }}>
+          1000ms
+        </Text>
+      </View>
+      <View style={{ alignItems: 'center', gap: 8 }}>
+        <Pulse duration={2000} animate={true}>
+          <Box
+            lx={{ width: 's48', height: 's48', backgroundColor: 'accent' }}
+          />
+        </Pulse>
+        <Text typography='body4' lx={{ color: 'muted' }}>
+          2000ms
+        </Text>
+      </View>
+      <View style={{ alignItems: 'center', gap: 8 }}>
+        <Pulse duration={3000} animate={true}>
+          <Box
+            lx={{ width: 's48', height: 's48', backgroundColor: 'accent' }}
+          />
+        </Pulse>
+        <Text typography='body4' lx={{ color: 'muted' }}>
+          3000ms
+        </Text>
+      </View>
+    </View>
+  ),
+};
+
+export const WithAmountDisplay: Story = {
+  render: () => {
+    return (
+      <View style={{ flexDirection: 'column', alignItems: 'center', gap: 16 }}>
+        <AmountDisplay
+          formatter={usdFormatter}
+          value={1234.56}
+          loading={true}
+        />
+      </View>
+    );
+  },
+};

package/src/lib/Animations/Pulse/Pulse.tsx

@@ -0,0 +1,55 @@
+import { useRef, useEffect, memo } from 'react';
+import { Animated, Easing } from 'react-native';
+import { RuntimeConstants } from '../../utils';
+import { PulseProps } from './types';
+
+export const Pulse = memo(
+  ({ children, duration = 2000, animate }: PulseProps) => {
+    const pulseAnim = useRef(new Animated.Value(1)).current;
+    const animationRef = useRef<Animated.CompositeAnimation | null>(null);
+
+    useEffect(() => {
+      if (animate) {
+        const animation = Animated.loop(
+          Animated.sequence([
+            Animated.timing(pulseAnim, {
+              toValue: 0,
+              duration: duration / 2,
+              easing: Easing.linear,
+              useNativeDriver: RuntimeConstants.isNative,
+            }),
+            Animated.timing(pulseAnim, {
+              toValue: 1,
+              duration: duration / 2,
+              easing: Easing.linear,
+              useNativeDriver: RuntimeConstants.isNative,
+            }),
+          ]),
+        );
+
+        animationRef.current = animation;
+        animation.start();
+      } else {
+        animationRef.current?.stop();
+        Animated.timing(pulseAnim, {
+          toValue: 1,
+          duration: 200,
+          easing: Easing.out(Easing.ease),
+          useNativeDriver: RuntimeConstants.isNative,
+        }).start();
+      }
+
+      return () => {
+        animationRef.current?.stop();
+      };
+    }, [pulseAnim, duration, animate]);
+
+    const pulse = pulseAnim.interpolate({
+      inputRange: [0, 1],
+      outputRange: [0.35, 1],
+    });
+
+    return <Animated.View style={{ opacity: pulse }}>{children}</Animated.View>;
+  },
+);
+Pulse.displayName = 'Pulse';

package/src/lib/Animations/Pulse/index.ts

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

package/src/lib/Animations/Pulse/types.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+import { Duration } from '../types';
+
+export type PulseProps = {
+  /**
+   * The content to animate
+   */
+  children: ReactNode;
+  /**
+   * Duration of one complete pulse in milliseconds
+   * @default 2000
+   */
+  duration?: Duration;
+  /**
+   * Whether the pulse animation should play
+   */
+  animate?: boolean;
+};

package/src/lib/Animations/Spin/Spin.mdx

@@ -0,0 +1,85 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as SpinStories from './Spin.stories';
+import { Spin } from './Spin';
+import {
+  CustomTabs,
+  Tab,
+} from '../../../../.storybook/components';
+import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
+
+<Meta title='Animations/Spin' of={SpinStories} />
+
+# 🔄 Spin
+
+<CustomTabs>
+  <Tab label="Overview">
+
+## Introduction
+
+The Spin animation creates a continuous rotation effect, commonly used for loading indicators and progress spinners. It provides visual feedback that a process is ongoing or content is being loaded.
+
+## Anatomy
+
+<Canvas of={SpinStories.Base} />
+
+- **Children**: The content to rotate continuously
+- **Duration**: Time for one complete 360° rotation
+
+## Properties
+
+### Overview
+
+<Canvas of={SpinStories.Base} />
+<Controls of={SpinStories.Base} />
+
+### Duration
+
+The duration prop controls how long one complete rotation takes. Shorter durations create faster spins, while longer durations provide slower, more subtle rotation.
+
+<Canvas of={SpinStories.DurationShowcase} />
+
+### Practical Usage
+
+The Spin animation is commonly used with the Spinner component to create loading indicators throughout the application.
+
+<Canvas of={SpinStories.WithSpinner} />
+
+## Accessibility
+
+- Does not rely on animation alone to convey information
+- Should be paired with appropriate loading labels for screen readers
+
+</Tab>
+<Tab label="Implementation">
+
+## Installation
+
+```bash
+npm install @ledgerhq/lumen-ui-rnative
+```
+
+> **Note**: `@ledgerhq/lumen-design-core` and other peer dependencies (`react`, `react-native`, etc.) are required. See our Setup Guide for complete installation.
+
+## Basic Usage
+
+```tsx
+import { Spin } from '@ledgerhq/lumen-ui-rnative';
+import { View } from 'react-native';
+
+function LoadingIcon() {
+  return (
+    <Spin>
+      <View style={{ width: 40, height: 40, backgroundColor: '#007AFF' }} />
+    </Spin>
+  );
+}
+```
+
+## Performance Considerations
+
+- The Spin component uses `useNativeDriver` for optimal performance on native platforms
+- Rotation animation runs continuously until component unmounts
+- Animation cleanup is handled automatically on unmount
+
+</Tab>
+</CustomTabs>

package/src/lib/Animations/Spin/Spin.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from '@storybook/react-native-web-vite';
+import { View } from 'react-native';
+import { Spinner } from '../../Components/Spinner';
+import { Box, Text } from '../../Components/Utility';
+import { Spin } from './Spin';
+
+const meta: Meta<typeof Spin> = {
+  title: 'Animations/Spin',
+  component: Spin,
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof Spin>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Base: Story = {
+  args: {
+    duration: 1000,
+    children: (
+      <Box lx={{ width: 's48', height: 's48', backgroundColor: 'accent' }} />
+    ),
+  },
+};
+
+export const DurationShowcase: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 24, alignItems: 'center' }}>
+      <View style={{ alignItems: 'center', gap: 8 }}>
+        <Spin duration={500}>
+          <Box
+            lx={{ width: 's48', height: 's48', backgroundColor: 'accent' }}
+          />
+        </Spin>
+        <Text typography='body4' lx={{ color: 'muted' }}>
+          500ms
+        </Text>
+      </View>
+      <View style={{ alignItems: 'center', gap: 8 }}>
+        <Spin duration={1000}>
+          <Box
+            lx={{ width: 's48', height: 's48', backgroundColor: 'accent' }}
+          />
+        </Spin>
+        <Text typography='body4' lx={{ color: 'muted' }}>
+          1000ms
+        </Text>
+      </View>
+      <View style={{ alignItems: 'center', gap: 8 }}>
+        <Spin duration={2000}>
+          <Box
+            lx={{ width: 's48', height: 's48', backgroundColor: 'accent' }}
+          />
+        </Spin>
+        <Text typography='body4' lx={{ color: 'muted' }}>
+          2000ms
+        </Text>
+      </View>
+    </View>
+  ),
+};
+
+export const WithSpinner: Story = {
+  render: () => {
+    return (
+      <View style={{ flexDirection: 'column', alignItems: 'center', gap: 16 }}>
+        <Spinner size={40} />
+      </View>
+    );
+  },
+};

package/src/lib/Animations/Spin/Spin.tsx

@@ -0,0 +1,34 @@
+import { memo, useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { RuntimeConstants } from '../../utils';
+import { SpinProps } from './types';
+
+export const Spin = memo(({ children, duration = 1000 }: SpinProps) => {
+  const spinValue = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    const animation = Animated.loop(
+      Animated.timing(spinValue, {
+        toValue: 1,
+        duration: duration,
+        easing: Easing.linear,
+        useNativeDriver: RuntimeConstants.isNative,
+      }),
+    );
+    animation.start();
+
+    return () => animation.stop();
+  }, [spinValue, duration]);
+
+  const spin = spinValue.interpolate({
+    inputRange: [0, 1],
+    outputRange: ['0deg', '360deg'],
+  });
+
+  return (
+    <Animated.View style={{ transform: [{ rotate: spin }] }}>
+      {children}
+    </Animated.View>
+  );
+});
+Spin.displayName = 'Spin';

package/src/lib/Animations/Spin/index.ts

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

package/src/lib/Animations/Spin/types.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { Duration } from '../types';
+
+export type SpinProps = {
+  /**
+   * The content to animate
+   */
+  children: ReactNode;
+  /**
+   * Duration of one complete rotation in milliseconds
+   * @default 1000
+   */
+  duration?: Duration;
+};

package/src/lib/Animations/index.ts

@@ -0,0 +1,3 @@
+export * from './Spin';
+export * from './Pulse';
+export * from './types';

package/src/lib/Animations/types.ts

@@ -0,0 +1,11 @@
+export type Duration =
+  | 75
+  | 100
+  | 150
+  | 200
+  | 300
+  | 500
+  | 700
+  | 1000
+  | 2000
+  | 3000;

package/src/lib/Components/AmountDisplay/AmountDisplay.mdx

@@ -45,6 +45,12 @@ The `hidden` prop allows you to toggle amount visibility for privacy-sensitive a
 
 <Canvas of={AmountDisplayStories.WithHideButton} />
 
+### Loading State
+
+The `loading` prop displays a pulse animation around the amount to indicate that data is being fetched or updated. When set to `true`, the component applies a subtle pulsing effect while maintaining the displayed value. This is useful for showing users that the amount is being refreshed in the background.
+
+<Canvas of={AmountDisplayStories.Loading} />
+
 ## Accessibility
 
 - Uses semantic components for proper screen reader support

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

@@ -126,3 +126,15 @@ export const WithHideButton: Story = {
     );
   },
 };
+
+export const Loading: Story = {
+  render: (props) => {
+    return (
+      <AmountDisplay
+        formatter={props.formatter}
+        value={1234.56}
+        loading={true}
+      />
+    );
+  },
+};

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

@@ -178,4 +178,17 @@ describe('AmountDisplay', () => {
     expect(screen.getByText('••••')).toBeTruthy();
     expect(screen.queryByText('.56')).toBeNull();
   });
+
+  it('renders correctly when loading is true', () => {
+    const formatter = createFormatter();
+    render(
+      <TestWrapper>
+        <AmountDisplay value={1234.56} formatter={formatter} loading={true} />
+      </TestWrapper>,
+    );
+
+    expect(screen.getByText('USD')).toBeTruthy();
+    expect(screen.getByText('1234')).toBeTruthy();
+    expect(screen.getByText('.56')).toBeTruthy();
+  });
 });

package/src/lib/Components/AmountDisplay/AmountDisplay.tsx

@@ -1,7 +1,7 @@
-import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
+import { View, Text } from 'react-native';
 import { useStyleSheet } from '../../../styles';
-import { ViewRef } from '../../types';
+import { Pulse } from '../../Animations/Pulse';
+import { Box } from '../Utility';
 import { AmountDisplayProps } from './types';
 
 const useStyles = () => {
@@ -71,39 +71,43 @@ const useStyles = () => {
  * <AmountDisplay value={1234.56} formatter={usdFormatter} hidden={true} />
  * ```
  */
-export const AmountDisplay = React.forwardRef<ViewRef, AmountDisplayProps>(
-  ({ value, formatter, hidden = false, style, ...props }, ref) => {
-    const styles = useStyles();
-    const parts = formatter(value);
+export const AmountDisplay = ({
+  value,
+  formatter,
+  hidden = false,
+  loading = false,
+  ...props
+}: AmountDisplayProps) => {
+  const styles = useStyles();
+  const parts = formatter(value);
 
-    return (
-      <View
-        ref={ref}
-        style={StyleSheet.flatten([styles.container, style])}
-        {...props}
-      >
-        {(parts.currencyPosition === undefined ||
-          parts.currencyPosition === 'start') && (
-          <Text style={[styles.currencyStartText, styles.spacingStart]}>
-            {parts.currencyText}
+  return (
+    <Box {...props}>
+      <Pulse animate={loading}>
+        <View style={styles.container}>
+          {(parts.currencyPosition === undefined ||
+            parts.currencyPosition === 'start') && (
+            <Text style={[styles.currencyStartText, styles.spacingStart]}>
+              {parts.currencyText}
+            </Text>
+          )}
+          <Text style={styles.integerText}>
+            {hidden ? '••••' : parts.integerPart}
           </Text>
-        )}
-        <Text style={styles.integerText}>
-          {hidden ? '••••' : parts.integerPart}
-        </Text>
-        {parts.decimalPart && !hidden && (
-          <Text style={styles.decimalText}>
-            {(parts.decimalSeparator || '.') + parts.decimalPart}
-          </Text>
-        )}
-        {parts.currencyPosition === 'end' && (
-          <Text style={[styles.currencyEndText, styles.spacingEnd]}>
-            {parts.currencyText}
-          </Text>
-        )}
-      </View>
-    );
-  },
-);
+          {parts.decimalPart && !hidden && (
+            <Text style={styles.decimalText}>
+              {(parts.decimalSeparator || '.') + parts.decimalPart}
+            </Text>
+          )}
+          {parts.currencyPosition === 'end' && (
+            <Text style={[styles.currencyEndText, styles.spacingEnd]}>
+              {parts.currencyText}
+            </Text>
+          )}
+        </View>
+      </Pulse>
+    </Box>
+  );
+};
 
 AmountDisplay.displayName = 'AmountDisplay';

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

@@ -1,4 +1,5 @@
 import { ViewProps } from 'react-native';
+import { StyledViewProps } from '../../../styles';
 
 export type FormattedValue = {
   /**
@@ -45,4 +46,9 @@ export type AmountDisplayProps = ViewProps & {
    * @default false
    */
   hidden?: boolean;
-};
+  /**
+   * When true, applies a pulse animation to indicate the amount is being fetched or updated.
+   * @default false
+   */
+  loading?: boolean;
+} & Omit<StyledViewProps, 'children'>;