@ledgerhq/lumen-ui-rnative 0.0.42

package/src/lib/Components/Slot/Slot.tsx

@@ -0,0 +1,201 @@
+import * as React from 'react';
+import {
+  View,
+  Pressable,
+  Text,
+  Image,
+  PressableProps,
+  ViewProps,
+  TextProps,
+  ImageProps,
+  StyleProp,
+  StyleSheet,
+  PressableStateCallbackType,
+  ImageStyle as RNImageStyle,
+} from 'react-native';
+
+const SlotPressable = React.forwardRef<
+  React.ElementRef<typeof Pressable>,
+  PressableProps
+>((props, forwardedRef) => {
+  const { children, ...pressableSlotProps } = props;
+
+  if (!React.isValidElement(children)) {
+    console.error('Slot.Pressable - Invalid asChild element', children);
+    return null;
+  }
+
+  return React.cloneElement<
+    React.ComponentPropsWithoutRef<typeof Pressable>,
+    React.ElementRef<typeof Pressable>
+  >(isTextChildren(children) ? <></> : children, {
+    ...mergeProps(pressableSlotProps, children.props as AnyProps),
+    ref: forwardedRef
+      ? composeRefs(forwardedRef, (children as any).ref)
+      : (children as any).ref,
+  });
+});
+
+SlotPressable.displayName = 'SlotPressable';
+
+const SlotView = React.forwardRef<React.ElementRef<typeof View>, ViewProps>(
+  (props, forwardedRef) => {
+    const { children, ...viewSlotProps } = props;
+
+    if (!React.isValidElement(children)) {
+      console.error('Slot.View - Invalid asChild element', children);
+      return null;
+    }
+
+    return React.cloneElement<
+      React.ComponentPropsWithoutRef<typeof View>,
+      React.ElementRef<typeof View>
+    >(isTextChildren(children) ? <></> : children, {
+      ...mergeProps(viewSlotProps, children.props as AnyProps),
+      ref: forwardedRef
+        ? composeRefs(forwardedRef, (children as any).ref)
+        : (children as any).ref,
+    });
+  },
+);
+
+SlotView.displayName = 'SlotView';
+
+const SlotText = React.forwardRef<React.ElementRef<typeof Text>, TextProps>(
+  (props, forwardedRef) => {
+    const { children, ...textSlotProps } = props;
+
+    if (!React.isValidElement(children)) {
+      console.error('Slot.Text - Invalid asChild element', children);
+      return null;
+    }
+
+    return React.cloneElement<
+      React.ComponentPropsWithoutRef<typeof Text>,
+      React.ElementRef<typeof Text>
+    >(isTextChildren(children) ? <></> : children, {
+      ...mergeProps(textSlotProps, children.props as AnyProps),
+      ref: forwardedRef
+        ? composeRefs(forwardedRef, (children as any).ref)
+        : (children as any).ref,
+    });
+  },
+);
+
+SlotText.displayName = 'SlotText';
+
+type SlotImageSlotProps = ImageProps & {
+  children?: React.ReactNode;
+};
+
+const SlotImage = React.forwardRef<
+  React.ElementRef<typeof Image>,
+  SlotImageSlotProps
+>((props, forwardedRef) => {
+  const { children, ...imageSlotProps } = props;
+
+  if (!React.isValidElement(children)) {
+    console.error('Slot.Image - Invalid asChild element', children);
+    return null;
+  }
+
+  return React.cloneElement<
+    React.ComponentPropsWithoutRef<typeof Image>,
+    React.ElementRef<typeof Image>
+  >(isTextChildren(children) ? <></> : children, {
+    ...mergeProps(imageSlotProps, children.props as AnyProps),
+    ref: forwardedRef
+      ? composeRefs(forwardedRef, (children as any).ref)
+      : (children as any).ref,
+  });
+});
+
+SlotImage.displayName = 'SlotImage';
+
+function composeRefs<T>(...refs: (React.Ref<T> | undefined)[]) {
+  return (node: T) =>
+    refs.forEach((ref) => {
+      if (typeof ref === 'function') {
+        ref(node);
+      } else if (ref != null) {
+        (ref as React.MutableRefObject<T>).current = node;
+      }
+    });
+}
+
+type AnyProps = Record<string, any>;
+
+function mergeProps(slotProps: AnyProps, childProps: AnyProps) {
+  // all child props should override
+  const overrideProps = { ...childProps };
+
+  for (const propName in childProps) {
+    const slotPropValue = slotProps[propName];
+    const childPropValue = childProps[propName];
+
+    const isHandler = /^on[A-Z]/.test(propName);
+    if (isHandler) {
+      // if the handler exists on both, we compose them
+      if (slotPropValue && childPropValue) {
+        overrideProps[propName] = (...args: unknown[]) => {
+          childPropValue(...args);
+          slotPropValue(...args);
+        };
+      }
+      // but if it exists only on the slot, we use only this one
+      else if (slotPropValue) {
+        overrideProps[propName] = slotPropValue;
+      }
+    }
+    // if it's `style`, we merge them
+    else if (propName === 'style') {
+      overrideProps[propName] = combineStyles(slotPropValue, childPropValue);
+    } else if (propName === 'className') {
+      overrideProps[propName] = [slotPropValue, childPropValue]
+        .filter(Boolean)
+        .join(' ');
+    }
+  }
+
+  return { ...slotProps, ...overrideProps };
+}
+
+type PressableStyle = PressableProps['style'];
+type ImageStyle = StyleProp<RNImageStyle>;
+type Style = PressableStyle | ImageStyle;
+
+function combineStyles(slotStyle?: Style, childValue?: Style) {
+  if (typeof slotStyle === 'function' && typeof childValue === 'function') {
+    return (state: PressableStateCallbackType) => {
+      return StyleSheet.flatten([slotStyle(state), childValue(state)]);
+    };
+  }
+  if (typeof slotStyle === 'function') {
+    return (state: PressableStateCallbackType) => {
+      return childValue
+        ? StyleSheet.flatten([slotStyle(state), childValue])
+        : slotStyle(state);
+    };
+  }
+  if (typeof childValue === 'function') {
+    return (state: PressableStateCallbackType) => {
+      return slotStyle
+        ? StyleSheet.flatten([slotStyle, childValue(state)])
+        : childValue(state);
+    };
+  }
+
+  return StyleSheet.flatten([slotStyle, childValue].filter(Boolean));
+}
+
+export function isTextChildren(
+  children:
+    | React.ReactNode
+    | ((state: PressableStateCallbackType) => React.ReactNode),
+) {
+  return Array.isArray(children)
+    ? children.every((child) => typeof child === 'string')
+    : typeof children === 'string';
+}
+
+export { SlotImage, SlotPressable, SlotText, SlotView };

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

@@ -0,0 +1 @@
+export * from './Slot';

package/src/lib/Components/Spinner/Spinner.mdx

@@ -0,0 +1,227 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import { CustomTabs, Tab } from '../../../../.storybook/components';
+import * as SpinnerStories from './Spinner.stories';
+import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
+import CommonRulesDoAndDont from '../../../../.storybook/docs/CommonRulesDoAndDont.mdx';
+
+<Meta title='Communication/Spinner/Docs' of={SpinnerStories} />
+
+# 🌀 Spinner
+
+<CustomTabs>
+  <Tab label="Overview">
+
+The Spinner component provides visual feedback for loading states and background processes. It's a crucial element for maintaining user engagement during asynchronous operations and preventing perceived delays.
+
+## Figma Library
+
+All spinner designs are created and managed in our components library. This ensures consistency across all platforms and use cases.
+
+- 🔗 **[Figma - Components Library](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=9023-3681&m=dev)**
+
+## Interactive Example
+
+<Canvas of={SpinnerStories.Base} />
+<Controls of={SpinnerStories.Base} />
+
+## 🎨 Appearances
+
+The Spinner component is designed to inherit text color from its parent, making it especially versatile when used inside a button, it will automatically match the button's label color for seamless integration. By default, it adopts the primary text color (`text-base`), but you can easily emphasize it using accent colors (such as `text-interactive`).
+
+Additionally, you can customize the spinner's appearance by applying your own styles with the `className` prop, allowing for further flexibility to match any specific design requirement.
+
+---
+
+## 📏 Sizing
+
+Our spinners are designed to be scalable and available in 7 standard sizes to fit various contexts within the UI, matching our icon sizing system for consistency. The available sizes are: **12, 16, 20, 24, 40, 48** and **56** pixels.
+
+<Canvas of={SpinnerStories.Sizes} />
+
+---
+
+## Usage Guidelines
+
+### When to Use
+
+- **Loading States**: During data fetching, form submissions, or content loading
+- **Background Processes**: When operations take longer than 1-2 seconds
+- **Screen Transitions**: During navigation between views or routes
+- **Button Actions**: Within buttons to indicate processing
+
+### When Not to Use
+
+- **Very Quick Operations**: For processes under 1 second
+- **Static Content**: Don't use spinners for content that's already loaded
+
+</Tab>
+<Tab label="Implementation">
+
+## Installation
+
+Install the packages and their peer dependencies:
+
+```bash
+# Install the UI Kit
+npm install @ledgerhq/lumen-ui-rnative @ledgerhq/lumen-design-core
+
+# Install peer dependencies
+npm install react@~18.3.1 react-native@~0.77.3 react-native-svg@^15.0.0 nativewind@^4.1.23
+```
+
+### NativeWind Configuration
+
+To use Spinner components with our custom NativeWind preset, you need to configure your `tailwind.config.ts`:
+
+```typescript
+import type { Config } from 'tailwindcss';
+import { ledgerLivePreset } from '@ledgerhq/lumen-design-core';
+
+const config = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}', // Your project's files
+    './node_modules/@ledgerhq/lumen-ui-rnative/src/**/*.{js,ts,jsx,tsx}', // Ledger UI Kit components
+  ],
+  presets: [ledgerLivePreset], // the installed tailwind preset
+} satisfies Config;
+
+export default config;
+```
+
+### Basic Usage
+
+Import and use the Spinner component:
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { Spinner } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  const [isLoading, setIsLoading] = useState(false);
+
+  return <View>{isLoading && <Spinner />}</View>;
+}
+```
+
+### Size Variants
+
+Spinners support predefined size variants that ensure consistent visual hierarchy:
+
+```tsx
+import React from 'react';
+import { View } from 'react-native';
+import { Spinner } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  return (
+    <View className='flex flex-row items-center gap-4'>
+      <Spinner size={12} />
+      <Spinner size={16} />
+      <Spinner size={20} />
+    </View>
+  );
+}
+```
+
+## Do's and Don'ts
+
+<div className='flex flex-col gap-24'>
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Match spinner size to context'
+      description='Use appropriate spinner sizes based on the context and prominence'
+    >
+
+{/* prettier-ignore */}
+```tsx
+// Small inline loading
+<Spinner size={12} />
+
+// Prominent loading state
+<Spinner size={40} />
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't override spinner size"
+      description='Avoid using className or additional props to override spinner dimensions'
+    >
+
+{/* prettier-ignore */}
+```tsx
+// Small inline loading
+<Spinner size={12} className='w-6 h-6' />
+
+// Prominent loading state
+<Spinner size={40} width={32} height={32} />
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Provide context with descriptive text'
+      description='Pair spinners with text to give users context about what is loading'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<View className='flex flex-row items-center gap-2'>
+  <Spinner size={16} />
+  <Text>Syncing wallet...</Text>
+</View>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't show spinners without context"
+      description='Avoid showing spinners alone without descriptive text'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<View className='flex flex-row items-center gap-2'>
+  <Spinner size={16} />
+</View>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use standard sizes from the design system'
+      description='Stick to predefined size values like 12, 16, 20, 24, 40'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Spinner size={16} />
+<Spinner size={24} />
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't use non-standard sizes"
+      description='Avoid arbitrary size values that are not part of the design system'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Spinner size={22} />
+<Spinner size={35} />
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <CommonRulesDoAndDont />
+</div>
+
+</Tab>
+</CustomTabs>

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

@@ -0,0 +1,70 @@
+import { Meta, StoryObj } from '@storybook/react-native-web-vite';
+import { Spinner } from './Spinner';
+
+const meta: Meta<typeof Spinner> = {
+  title: 'Communication/Spinner',
+  component: Spinner,
+  parameters: {
+    actions: { disable: true },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: [12, 16, 20, 24, 40, 48, 56],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Spinner>;
+
+export const Base: Story = {
+  args: {
+    size: 40,
+  },
+  render: ({ size }) => (
+    <div className='flex items-center justify-center'>
+      <Spinner size={size} />
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  argTypes: {
+    size: {
+      control: false,
+    },
+  },
+  render: () => (
+    <div className='flex items-center justify-center gap-32'>
+      <div className='flex flex-col items-center gap-4'>
+        <Spinner size={12} />
+        <span className='text-muted body-4'>12</span>
+      </div>
+      <div className='flex flex-col items-center gap-4'>
+        <Spinner size={16} />
+        <span className='text-muted body-4'>16</span>
+      </div>
+      <div className='flex flex-col items-center gap-4'>
+        <Spinner size={20} />
+        <span className='text-muted body-4'>20</span>
+      </div>
+      <div className='flex flex-col items-center gap-4'>
+        <Spinner size={24} />
+        <span className='text-muted body-4'>24</span>
+      </div>
+      <div className='flex flex-col items-center gap-4'>
+        <Spinner size={40} />
+        <span className='text-muted body-4'>40</span>
+      </div>
+      <div className='flex flex-col items-center gap-4'>
+        <Spinner size={48} />
+        <span className='text-muted body-4'>48</span>
+      </div>
+      <div className='flex flex-col items-center gap-4'>
+        <Spinner size={56} />
+        <span className='text-muted body-4'>56</span>
+      </div>
+    </div>
+  ),
+};

package/src/lib/Components/Spinner/Spinner.tsx

@@ -0,0 +1,47 @@
+import { cn } from '@ledgerhq/lumen-utils-shared';
+import { forwardRef } from 'react';
+import { View } from 'react-native';
+import Svg, { Path, type SvgProps } from 'react-native-svg';
+import { useCommonTranslation } from '../../../i18n';
+import { IconSize } from '../../Components/Icon/Icon.types';
+
+export type SpinnerProps = SvgProps & {
+  /**
+   * The size of the spinner icon in pixels.
+   * @default 16
+   */
+  size?: IconSize;
+};
+
+/**
+ * A basic spinner component for loading states.
+ *
+ * @example
+ * <Spinner />
+ */
+export const Spinner = forwardRef<Svg, SpinnerProps>(
+  ({ className, size = 16, ...props }, ref) => {
+    const { t } = useCommonTranslation();
+    return (
+      <View className='shrink-0 animate-spin'>
+        <Svg
+          className={cn('text-base', className)}
+          width={size}
+          height={size}
+          viewBox='0 0 16 16'
+          fill='none'
+          accessibilityLabel={t('components.spinner.loadingAriaLabel')}
+          ref={ref}
+          {...props}
+        >
+          <Path
+            d='M8 1.5C11.5899 1.5 14.5 4.41015 14.5 8C14.5 11.5899 11.5899 14.5 8 14.5C4.41015 14.5 1.5 11.5899 1.5 8'
+            stroke='currentColor'
+            strokeWidth='1.5'
+            strokeLinecap='round'
+          />
+        </Svg>
+      </View>
+    );
+  },
+);

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

@@ -0,0 +1 @@
+export * from './Spinner';