@ledgerhq/lumen-ui-rnative 0.1.34 → 0.1.36

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

@@ -1,8 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { FC } from 'react';
 import { useState } from 'react';
 import { Button } from '../Button';
 import { SearchInput } from '../SearchInput';
-import { Box, Text } from '../Utility';
+import { Spot } from '../Spot';
+import { Box, RadialGradient, Text } from '../Utility';
 import { BottomSheet } from './BottomSheet';
 import { BottomSheetHeader } from './BottomSheetHeader';
 import {
@@ -11,6 +13,7 @@ import {
   BottomSheetView,
   BottomSheetVirtualizedList,
 } from './Scrollables';
+import type { BottomSheetBackgroundProps } from './types';
 import { useBottomSheetRef } from './useBottomSheetRef';
 
 const meta = {
@@ -654,3 +657,173 @@ export const VirtualizedList: Story = {
     );
   },
 };
+
+type StrongBackgroundColor = 'errorStrong' | 'successStrong' | 'mutedStrong';
+
+const createGradientBackground =
+  (color: StrongBackgroundColor): FC<BottomSheetBackgroundProps> =>
+  ({ style }) => (
+    <Box
+      style={style}
+      lx={{ backgroundColor: 'canvasSheet', overflow: 'hidden' }}
+    >
+      <RadialGradient
+        center={{ x: 0.5, y: 0 }}
+        stops={[
+          { color, offset: 0, opacity: 0.3 },
+          { color, offset: 1, opacity: 0 },
+        ]}
+        lx={{
+          position: 'absolute',
+          top: 's0',
+          left: 's0',
+          right: 's0',
+          height: 's320',
+        }}
+      />
+    </Box>
+  );
+
+const ErrorBackground = createGradientBackground('errorStrong');
+const SuccessBackground = createGradientBackground('successStrong');
+const MutedBackground = createGradientBackground('mutedStrong');
+
+export const InfoStateVariants: Story = {
+  args: {
+    snapPoints: 'full',
+    hideCloseButton: false,
+    onBack: undefined,
+    onClose: undefined,
+    enableHandlePanningGesture: true,
+    enablePanDownToClose: true,
+    enableBlurKeyboardOnGesture: true,
+    enableDynamicSizing: false,
+    detached: false,
+    backdropPressBehavior: 'close',
+    hideHandle: true,
+  },
+  render: (args) => {
+    const errorBottomSheetRef = useBottomSheetRef();
+    const successBottomSheetRef = useBottomSheetRef();
+    const mutedBottomSheetRef = useBottomSheetRef();
+
+    return (
+      <Box
+        lx={{
+          height: 's320',
+          width: 'full',
+          alignItems: 'center',
+          justifyContent: 'center',
+          paddingTop: 's32',
+          gap: 's12',
+        }}
+      >
+        <Button
+          size='sm'
+          onPress={() => errorBottomSheetRef.current?.present()}
+        >
+          Error
+        </Button>
+        <Button
+          size='sm'
+          onPress={() => successBottomSheetRef.current?.present()}
+        >
+          Success
+        </Button>
+        <Button
+          size='sm'
+          onPress={() => mutedBottomSheetRef.current?.present()}
+        >
+          Muted
+        </Button>
+
+        <BottomSheet
+          {...args}
+          ref={errorBottomSheetRef}
+          backgroundComponent={ErrorBackground}
+        >
+          <BottomSheetView>
+            <BottomSheetHeader density='compact' />
+            <Box lx={{ alignItems: 'center', gap: 's24' }}>
+              <Spot appearance='error' size={72} />
+              <Box lx={{ alignItems: 'center', gap: 's12' }}>
+                <Text typography='heading4SemiBold' lx={{ color: 'base' }}>
+                  Title
+                </Text>
+                <Text
+                  typography='body2'
+                  lx={{ color: 'muted', textAlign: 'center' }}
+                >
+                  Description
+                </Text>
+              </Box>
+            </Box>
+            <Box lx={{ marginTop: 's24' }}>
+              <Button appearance='base' size='lg' isFull>
+                Label
+              </Button>
+            </Box>
+          </BottomSheetView>
+        </BottomSheet>
+
+        <BottomSheet
+          {...args}
+          ref={successBottomSheetRef}
+          backgroundComponent={SuccessBackground}
+        >
+          <BottomSheetView>
+            <BottomSheetHeader density='compact' />
+            <Box lx={{ alignItems: 'center', gap: 's24' }}>
+              <Spot appearance='check' size={72} />
+              <Box lx={{ alignItems: 'center', gap: 's12' }}>
+                <Text typography='heading4SemiBold' lx={{ color: 'base' }}>
+                  Title
+                </Text>
+                <Text
+                  typography='body2'
+                  lx={{ color: 'muted', textAlign: 'center' }}
+                >
+                  Description
+                </Text>
+              </Box>
+            </Box>
+            <Box lx={{ marginTop: 's24' }}>
+              <Button appearance='base' size='lg' isFull>
+                Label
+              </Button>
+            </Box>
+          </BottomSheetView>
+        </BottomSheet>
+
+        <BottomSheet
+          {...args}
+          ref={mutedBottomSheetRef}
+          backgroundComponent={MutedBackground}
+        >
+          <BottomSheetView>
+            <BottomSheetHeader density='compact' />
+            <Box lx={{ alignItems: 'center', gap: 's24' }}>
+              <Spot appearance='info' size={72} />
+              <Box lx={{ alignItems: 'center', gap: 's12' }}>
+                <Text typography='heading4SemiBold' lx={{ color: 'base' }}>
+                  Title
+                </Text>
+                <Text
+                  typography='body2'
+                  lx={{ color: 'muted', textAlign: 'center' }}
+                >
+                  Description
+                </Text>
+              </Box>
+            </Box>
+            <Box lx={{ marginTop: 's24' }}>
+              <Button appearance='base' size='lg' isFull>
+                Label
+              </Button>
+            </Box>
+          </BottomSheetView>
+        </BottomSheet>
+      </Box>
+    );
+  },
+};

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

@@ -184,6 +184,65 @@ describe('BottomSheet', () => {
       expect(element.props['data-detached']).toBe('true');
     });
 
+    it('uses default background style when no backgroundComponent is provided', () => {
+      const { BottomSheet } = require('./BottomSheet');
+      const { getByTestId } = renderWithTheme(
+        <BottomSheet testID='bottom-sheet'>
+          <Text>Content</Text>
+        </BottomSheet>,
+      );
+
+      const element = getByTestId('bottom-sheet');
+      expect(element.props['data-has-background-component']).toBe('false');
+      expect(element.props['data-has-background-style']).toBe('true');
+    });
+
+    it('renders the default handle when hideHandle is not set', () => {
+      const { BottomSheet } = require('./BottomSheet');
+      const { getByTestId, queryByTestId } = renderWithTheme(
+        <BottomSheet testID='bottom-sheet'>
+          <Text>Content</Text>
+        </BottomSheet>,
+      );
+
+      expect(getByTestId('bottom-sheet-handle')).toBeTruthy();
+      expect(queryByTestId('bottom-sheet-handle-hidden')).toBeNull();
+    });
+
+    it('renders the hidden handle placeholder when hideHandle is true', () => {
+      const { BottomSheet } = require('./BottomSheet');
+      const { getByTestId, queryByTestId } = renderWithTheme(
+        <BottomSheet hideHandle testID='bottom-sheet'>
+          <Text>Content</Text>
+        </BottomSheet>,
+      );
+
+      expect(getByTestId('bottom-sheet-handle-hidden')).toBeTruthy();
+      expect(queryByTestId('bottom-sheet-handle')).toBeNull();
+    });
+
+    it('forwards backgroundComponent and skips default background style', () => {
+      const { BottomSheet } = require('./BottomSheet');
+      const CustomBackground = () => (
+        <View testID='custom-bg'>
+          <Text>BG</Text>
+        </View>
+      );
+      const { getByTestId } = renderWithTheme(
+        <BottomSheet
+          backgroundComponent={CustomBackground}
+          testID='bottom-sheet'
+        >
+          <Text>Content</Text>
+        </BottomSheet>,
+      );
+
+      const element = getByTestId('bottom-sheet');
+      expect(element.props['data-has-background-component']).toBe('true');
+      expect(element.props['data-has-background-style']).toBe('false');
+      expect(getByTestId('custom-bg')).toBeTruthy();
+    });
+
     it('respects enableHandlePanningGesture prop', () => {
       const { BottomSheet } = require('./BottomSheet');
       const { getByTestId } = renderWithTheme(

package/src/lib/Components/BottomSheet/BottomSheet.tsx

@@ -6,7 +6,7 @@ import { StyleSheet } from 'react-native';
 import { useStyleSheet } from '../../../styles';
 import { RuntimeConstants } from '../../utils';
 import { CustomBackdrop } from './CustomBackdrop';
-import { CustomHandle } from './CustomHandle';
+import { CustomHandle, HiddenHandle } from './CustomHandle';
 import type { BottomSheetProps } from './types';
 
 const OFFSET_TOP = 25;
@@ -25,7 +25,13 @@ const MAX_DYNAMIC_CONTENT_SIZE = {
   fullWithOffset: FULL_WITH_OFFSET,
 };
 
-const useStyles = ({ shadow }: { shadow: boolean }) => {
+const useStyles = ({
+  shadow,
+  hasCustomBackground,
+}: {
+  shadow: boolean;
+  hasCustomBackground: boolean;
+}) => {
   return useStyleSheet(
     (t) => ({
       root: StyleSheet.flatten([
@@ -35,7 +41,7 @@ const useStyles = ({ shadow }: { shadow: boolean }) => {
           flex: 1,
           borderTopLeftRadius: t.borderRadius.xl,
           borderTopRightRadius: t.borderRadius.xl,
-          backgroundColor: t.colors.bg.canvasSheet,
+          overflow: 'hidden',
         },
         shadow && {
           boxShadow: t.shadows.lg,
@@ -46,7 +52,7 @@ const useStyles = ({ shadow }: { shadow: boolean }) => {
         backgroundColor: t.colors.bg.canvasSheet,
       },
     }),
-    [shadow],
+    [shadow, hasCustomBackground],
   );
 };
 
@@ -74,6 +80,8 @@ export const BottomSheet = ({
   onBackdropPress,
   onChange,
   snapPoints = 'fullWithOffset',
+  backgroundComponent,
+  hideHandle = false,
   ref,
   ...props
 }: BottomSheetProps) => {
@@ -82,7 +90,10 @@ export const BottomSheet = ({
   const mergedRefs = useMergedRef<GorhomBottomSheetModal>(ref, innerRef);
   const [isOpen, setIsOpen] = useState(false);
 
-  const styles = useStyles({ shadow: hideBackdrop && isOpen });
+  const styles = useStyles({
+    shadow: hideBackdrop && isOpen,
+    hasCustomBackground: Boolean(backgroundComponent),
+  });
 
   /**
    * Match the snap points to the preset or the custom snap points array
@@ -163,7 +174,8 @@ export const BottomSheet = ({
       {...props}
       ref={mergedRefs}
       style={styles.root}
-      backgroundStyle={styles.background}
+      backgroundStyle={backgroundComponent ? undefined : styles.background}
+      backgroundComponent={backgroundComponent}
       onChange={handleChange}
       onAnimate={handleAnimate}
       /**
@@ -188,7 +200,7 @@ export const BottomSheet = ({
       /**
        * Components
        */
-      handleComponent={CustomHandle}
+      handleComponent={hideHandle ? HiddenHandle : CustomHandle}
       backdropComponent={hideBackdrop ? undefined : renderBackdrop}
     >
       <BottomSheetProvider value={{ onBack, hideCloseButton }}>

package/src/lib/Components/BottomSheet/BottomSheetHeader.tsx

@@ -28,7 +28,7 @@ const useStyles = ({
         {
           position: 'relative',
           zIndex: Z_INDEX_DIALOG_CONTENT,
-          backgroundColor: t.colors.bg.canvasSheet,
+          backgroundColor: 'transparent',
           paddingBottom: t.spacings.s12,
         },
         spacing && {

package/src/lib/Components/BottomSheet/CustomHandle.tsx

@@ -1,5 +1,5 @@
 import type { BottomSheetVariables } from '@gorhom/bottom-sheet/lib/typescript/types';
-import type { Ref } from 'react';
+import type { ComponentRef, Ref } from 'react';
 import { View } from 'react-native';
 import { useStyleSheet } from '../../../styles';
 
@@ -12,13 +12,13 @@ const useStyles = () => {
         alignItems: 'center',
         justifyContent: 'center',
         alignSelf: 'center',
-        backgroundColor: t.colors.bg.canvasSheet,
+        backgroundColor: 'transparent',
       },
       handle: {
         height: t.spacings.s4,
         width: t.sizes.s36,
         borderRadius: t.borderRadius.full,
-        backgroundColor: t.colors.bg.mutedPressed,
+        backgroundColor: t.colors.bg.mutedTransparentPressed,
       },
     }),
     [],
@@ -28,12 +28,33 @@ const useStyles = () => {
 export const CustomHandle = ({
   ref,
   ...props
-}: BottomSheetVariables & { ref?: Ref<React.ElementRef<typeof View>> }) => {
+}: BottomSheetVariables & { ref?: Ref<ComponentRef<typeof View>> }) => {
   const styles = useStyles();
 
   return (
-    <View {...props} ref={ref} style={styles.container}>
+    <View
+      {...props}
+      ref={ref}
+      style={styles.container}
+      testID='bottom-sheet-handle'
+    >
       <View style={styles.handle} />
     </View>
   );
 };
+
+export const HiddenHandle = ({
+  ref,
+  ...props
+}: BottomSheetVariables & { ref?: Ref<ComponentRef<typeof View>> }) => {
+  const styles = useStyles();
+
+  return (
+    <View
+      {...props}
+      ref={ref}
+      style={styles.container}
+      testID='bottom-sheet-handle-hidden'
+    />
+  );
+};

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

@@ -5,16 +5,23 @@ import type {
   BottomSheetSectionList as GorhomBottomSheetSectionList,
   BottomSheetScrollView as GorhomBottomSheetScrollView,
   BottomSheetVirtualizedList as GorhomBottomSheetVirtualizedList,
+  BottomSheetBackgroundProps,
 } from '@gorhom/bottom-sheet';
-
 import type { Density } from '@ledgerhq/lumen-utils-shared';
-import type { PropsWithChildren, ReactNode, Ref } from 'react';
+import type {
+  ComponentRef,
+  FC,
+  PropsWithChildren,
+  ReactNode,
+  Ref,
+} from 'react';
+
 import type { StyledViewProps } from '../../../styles';
 export type BottomSheetProps = PropsWithChildren & {
   /**
    * Ref to the bottom sheet component.
    */
-  ref?: Ref<React.ElementRef<typeof GorhomBottomSheetModal>>;
+  ref?: Ref<ComponentRef<typeof GorhomBottomSheetModal>>;
   /**
    * Used to locate this view in end-to-end tests.
    */
@@ -131,8 +138,22 @@ export type BottomSheetProps = PropsWithChildren & {
    * @default true
    */
   enableBlurKeyboardOnGesture?: boolean;
+  /**
+   * Custom background component rendered behind the sheet content and handle.
+   * Use to render gradients or other effects that should span the full sheet area,
+   * including the handle strip. When provided, the default sheet background is removed.
+   * @default undefined
+   */
+  backgroundComponent?: FC<BottomSheetBackgroundProps> | null;
+  /**
+   * If true, the drag handle (grabber) at the top of the sheet is hidden.
+   * @default false
+   */
+  hideHandle?: boolean;
 };
 
+export type { BottomSheetBackgroundProps };
+
 export type BottomSheetHeaderProps = {
   /**
    * The density of the header.

package/src/lib/Components/Card/Card.tsx

@@ -3,7 +3,7 @@ import {
   DisabledProvider,
   isTextChildren,
 } from '@ledgerhq/lumen-utils-shared';
-import type { ReactNode, Ref } from 'react';
+import type { ComponentRef, ReactNode, Ref } from 'react';
 import { useCallback, useEffect, useMemo } from 'react';
 import type { LayoutChangeEvent, ViewStyle } from 'react-native';
 import { StyleSheet, View } from 'react-native';
@@ -486,7 +486,7 @@ export const CardContentTitle = ({
   if (isTextChildren(children)) {
     return (
       <Text
-        ref={ref as Ref<React.ElementRef<typeof Text>>}
+        ref={ref as Ref<ComponentRef<typeof Text>>}
         lx={lx}
         style={StyleSheet.flatten([styles.asText, style])}
         numberOfLines={1}
@@ -553,7 +553,7 @@ export const CardContentDescription = ({
   if (isTextChildren(children)) {
     return (
       <Text
-        ref={ref as Ref<React.ElementRef<typeof Text>>}
+        ref={ref as Ref<ComponentRef<typeof Text>>}
         lx={lx}
         style={StyleSheet.flatten([styles.asText, style])}
         numberOfLines={1}

package/src/lib/Components/DescriptionItem/DescriptionItem.mdx

@@ -0,0 +1,139 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as DescriptionItemStories from './DescriptionItem.stories';
+import { CustomTabs, Tab } from '../../../../.storybook/components';
+
+<Meta title='Containment/DescriptionItem' of={DescriptionItemStories} />
+
+# DescriptionItem
+
+> View in [Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=10311-11837&m=dev).
+
+<CustomTabs>
+  <Tab label="Overview">
+
+## Introduction
+
+DescriptionItem is a compound component for displaying key-value rows — typically used inside a summary panel, transaction detail, or settings screen. It composes a leading label side and a trailing value side, with the trailing always taking priority over the leading when space is constrained.
+
+## Anatomy
+
+<Canvas of={DescriptionItemStories.Base} />
+
+- **DescriptionItem**: Root row container. Accepts an optional `size` prop (`md` | `sm`).
+- **DescriptionItemLeading**: Left section holding the label and any optional sibling (e.g. a tooltip icon).
+- **DescriptionItemLabel**: Muted text label. Wraps to a second line before truncating (`numberOfLines={2}`).
+- **DescriptionItemTrailing**: Right section holding the value or any inline element (Tag, Link, etc.). Never shrinks — always has layout priority.
+- **DescriptionItemValue**: Semi-bold value text. Truncates to a single line (`numberOfLines={1}`).
+
+## Properties
+
+<Canvas of={DescriptionItemStories.Base} />
+<Controls of={DescriptionItemStories.Base} />
+
+### Trailing variants
+
+The trailing section accepts any content — a plain value, a `Tag`, multiple `Tag`s, or a custom element. Use `DescriptionItemValue` for plain text; place other components directly in `DescriptionItemTrailing`.
+
+<Canvas of={DescriptionItemStories.TrailingVariants} />
+
+### Size
+
+Two sizes are available — `md` (default) and `sm`.
+
+- The size of `DescriptionItemValue` is inherited from the parent `DescriptionItem`.
+- The size of additional trailing content (e.g. `Tag`) needs to be set explicitly.
+
+<Canvas of={DescriptionItemStories.SizeShowcase} />
+
+### With info tooltip
+
+Pair a `Tooltip` with an info icon inside `DescriptionItemLeading` to surface additional context without cluttering the label.
+
+<Canvas of={DescriptionItemStories.WithInfoIcon} />
+
+### Truncation
+
+The label can wrap to two lines before truncating. The trailing value truncates after one line. When both sides have long content, the trailing always gets layout priority.
+
+<Canvas of={DescriptionItemStories.TruncationBehavior} />
+
+</Tab>
+<Tab label="Implementation">
+
+## Setup
+
+Install and set up the library with our [Setup Guide →](?path=/docs/getting-started-setup--docs).
+
+## Basic Usage
+
+```tsx
+import {
+  DescriptionItem,
+  DescriptionItemLabel,
+  DescriptionItemLeading,
+  DescriptionItemTrailing,
+  DescriptionItemValue,
+} from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  return (
+    <DescriptionItem size='md'>
+      <DescriptionItemLeading>
+        <DescriptionItemLabel>Fees</DescriptionItemLabel>
+      </DescriptionItemLeading>
+      <DescriptionItemTrailing>
+        <DescriptionItemValue>0.001 BTC</DescriptionItemValue>
+      </DescriptionItemTrailing>
+    </DescriptionItem>
+  );
+}
+```
+
+### With info tooltip
+
+Use a `Tooltip` alongside the label to add contextual information:
+
+```tsx
+import {
+  DescriptionItem,
+  DescriptionItemLabel,
+  DescriptionItemLeading,
+  DescriptionItemTrailing,
+  DescriptionItemValue,
+  InteractiveIcon,
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+} from '@ledgerhq/lumen-ui-rnative';
+import { Information } from '@ledgerhq/lumen-ui-rnative/symbols';
+import { Text } from 'react-native';
+
+function MyComponent() {
+  return (
+    <DescriptionItem>
+      <DescriptionItemLeading>
+        <DescriptionItemLabel>Fees</DescriptionItemLabel>
+        <Tooltip>
+          <TooltipTrigger>
+            <InteractiveIcon
+              icon={Information}
+              size={16}
+              iconType='stroked'
+              accessibilityLabel='More information'
+            />
+          </TooltipTrigger>
+          <TooltipContent
+            content={<Text>Network fee paid to miners</Text>}
+          />
+        </Tooltip>
+      </DescriptionItemLeading>
+      <DescriptionItemTrailing>
+        <DescriptionItemValue>0.001 BTC</DescriptionItemValue>
+      </DescriptionItemTrailing>
+    </DescriptionItem>
+  );
+}
+```
+
+</Tab>
+</CustomTabs>