@ledgerhq/lumen-ui-rnative 0.1.36 → 0.1.37

package/src/lib/Components/DotSymbol/DotSymbol.mdx

@@ -4,14 +4,17 @@ import { CustomTabs, Tab } from '../../../../.storybook/components';
 
 <Meta title='Communication/DotSymbol' of={DotSymbolStories} />
 
+# DotSymbol
+
 <CustomTabs>
   <Tab label="Overview">
-# DotSymbol
 
 ## Introduction
 
 DotSymbol positions a small image indicator at a configurable corner of a child element such as MediaImage or Spot. It is commonly used to show a network badge or secondary icon overlapping a primary symbol.
 
+> View in [Figma](https://www.figma.com/design/zSkvGGiqcnhywp2l3HTHxA/1.-Symbol-Library?node-id=8602-380&m=dev).
+
 ## Anatomy
 
 <Canvas of={DotSymbolStories.Base} />
@@ -46,9 +49,83 @@ The dot size is driven by the parent MediaImage or Spot size via the mapping hel
 
 <Canvas of={DotSymbolStories.SizeShowcase} />
 
+### Disabled
+
+Only set `disabled` on `DotSymbol`. The state is propagated to the child via context. Passing it to both stacks the opacity overlay.
+
+<Canvas of={DotSymbolStories.DisabledShowcase} />
+
 ## Accessibility
 
 - Always provide a meaningful `alt` prop on the DotSymbol so the indicator image is announced by screen readers.
 - The child element should carry its own accessibility label independently.
+
+</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 { DotSymbol, MediaImage } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  return (
+    <DotSymbol src='https://example.com/btc.png' alt='Bitcoin network'>
+      <MediaImage src='https://example.com/ada.png' alt='Cardano' size={48} />
+    </DotSymbol>
+  );
+}
+```
+
+### Pin Placement
+
+Position the dot at any of the four corners of the child:
+
+```tsx
+<DotSymbol src='https://example.com/btc.png' alt='Bitcoin' pin='top-end'>
+  <MediaImage src='https://example.com/ada.png' alt='Cardano' size={48} />
+</DotSymbol>
+```
+
+### Shapes
+
+Use `shape='square'` to match a square child element:
+
+```tsx
+<DotSymbol src='https://example.com/btc.png' alt='Bitcoin' shape='square'>
+  <MediaImage src='https://example.com/ada.png' alt='Cardano' size={48} shape='square' />
+</DotSymbol>
+```
+
+### Sizing
+
+The dot size is driven by the parent's size via the mapping helpers:
+
+```tsx
+import { DotSymbol, mediaImageDotSizeMap, MediaImage } from '@ledgerhq/lumen-ui-rnative';
+
+<DotSymbol
+  src='https://example.com/btc.png'
+  alt='Bitcoin'
+  size={mediaImageDotSizeMap[48]}
+>
+  <MediaImage src='https://example.com/ada.png' alt='Cardano' size={48} />
+</DotSymbol>;
+```
+
+### Disabled State
+
+Only set `disabled` on `DotSymbol`. The state is propagated to the child via context. Passing it to both stacks the opacity overlay.
+
+```tsx
+<DotSymbol src='https://example.com/btc.png' alt='Bitcoin' disabled>
+  <MediaImage src='https://example.com/ada.png' alt='Cardano' size={48} />
+</DotSymbol>
+```
+
 </Tab>
-</CustomTabs>
+</CustomTabs>

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

@@ -92,6 +92,23 @@ export const ShapeShowcase: Story = {
   ),
 };
 
+export const DisabledShowcase: Story = {
+  args: { src: dotSrc, alt: 'Disabled showcase' },
+  render: () => (
+    <Box lx={{ flexDirection: 'row', alignItems: 'center', gap: 's32' }}>
+      <DotSymbol src={dotSrc} pin='bottom-end' disabled>
+        <MediaImage src={parentSrc} size={48} shape='circle' />
+      </DotSymbol>
+      <DotSymbol src={dotSrc} pin='bottom-end' shape='square' disabled>
+        <MediaImage src={parentSrc} size={48} shape='square' />
+      </DotSymbol>
+      <DotSymbol src={dotSrc} pin='bottom-end' disabled>
+        <Spot appearance='icon' icon={CoinAlert} />
+      </DotSymbol>
+    </Box>
+  ),
+};
+
 export const SizeShowcase: Story = {
   args: { src: dotSrc, alt: 'Size showcase' },
   render: () => (

package/src/lib/Components/DotSymbol/DotSymbol.tsx

@@ -1,5 +1,9 @@
+import {
+  DisabledProvider,
+  useDisabledContext,
+} from '@ledgerhq/lumen-utils-shared';
 import { useEffect, useState } from 'react';
-import { Image, StyleSheet } from 'react-native';
+import { Image } from 'react-native';
 import { useStyleSheet } from '../../../styles';
 import type { MediaImageSize } from '../MediaImage';
 import type { SpotSize } from '../Spot';
@@ -65,10 +69,12 @@ const useStyles = ({
   size,
   shape,
   pin,
+  disabled,
 }: {
   size: DotSymbolSize;
   shape: 'square' | 'circle';
   pin: DotSymbolPin;
+  disabled: boolean;
 }) => {
   return useStyleSheet(
     (t) => {
@@ -78,6 +84,10 @@ const useStyles = ({
       const pinOffset = getPinOffset(pin, size);
 
       return {
+        root: {
+          position: 'relative',
+          ...(disabled && { opacity: 0.3 }),
+        },
         dot: {
           position: 'absolute',
           zIndex: 10,
@@ -96,7 +106,7 @@ const useStyles = ({
         },
       };
     },
-    [size, shape, pin],
+    [size, shape, pin, disabled],
   );
 };
 
@@ -118,42 +128,50 @@ export const DotSymbol = ({
   pin = 'bottom-end',
   size = 20,
   shape = 'circle',
+  disabled: disabledProp = false,
   lx = {},
   style,
   ref,
   ...rest
 }: DotSymbolProps) => {
-  const styles = useStyles({ size, shape, pin });
   const [error, setError] = useState(false);
+  const disabled = useDisabledContext({
+    consumerName: 'DotSymbol',
+    mergeWith: { disabled: disabledProp },
+  });
+  const styles = useStyles({ size, shape, pin, disabled });
 
   useEffect(() => {
     setError(false);
   }, [src]);
 
   return (
-    <Box
-      ref={ref}
-      lx={lx}
-      style={StyleSheet.flatten([{ position: 'relative' }, style])}
-      accessibilityRole='image'
-      accessibilityLabel={alt}
-      {...rest}
-    >
-      <Box style={{ alignSelf: 'flex-start', position: 'relative' }}>
-        {children}
-        <Box style={styles.dot}>
-          {!error && (
-            <Image
-              source={{ uri: src }}
-              style={styles.image}
-              accessible={false}
-              onError={() => setError(true)}
-              testID='dot-symbol-img'
-            />
-          )}
+    <DisabledProvider value={{ disabled: false }}>
+      <Box
+        ref={ref}
+        lx={lx}
+        style={[styles.root, style]}
+        accessibilityRole='image'
+        accessibilityLabel={alt}
+        accessibilityState={{ disabled }}
+        {...rest}
+      >
+        <Box style={{ alignSelf: 'flex-start', position: 'relative' }}>
+          {children}
+          <Box style={styles.dot}>
+            {!error && (
+              <Image
+                source={{ uri: src }}
+                style={styles.image}
+                accessible={false}
+                onError={() => setError(true)}
+                testID='dot-symbol-img'
+              />
+            )}
+          </Box>
         </Box>
       </Box>
-    </Box>
+    </DisabledProvider>
   );
 };
 

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

@@ -33,6 +33,12 @@ export type DotSymbolProps = {
    * @default 'circle'
    */
   shape?: 'square' | 'circle';
+  /**
+   * Shows a disabled appearance.
+   * @optional
+   * @default false
+   */
+  disabled?: boolean;
   /**
    * The wrapped component (e.g. MediaImage or Spot).
    */

package/src/lib/Components/IconButton/IconButton.mdx

@@ -8,7 +8,7 @@ import { Box } from '../Utility';
 
 <Meta title='Action/IconButton' of={IconButtonStories} />
 
-# 🔘 IconButton
+# IconButton
 
 <CustomTabs>
   <Tab label="Overview">

package/src/lib/Components/InteractiveIcon/InteractiveIcon.mdx

@@ -8,7 +8,7 @@ import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/Com
 
 <Meta title='Components/InteractiveIcon' of={InteractiveIconStories} />
 
-# 🎯 InteractiveIcon
+# InteractiveIcon
 
 <CustomTabs>
   <Tab label="Overview">

package/src/lib/Components/Link/Link.mdx

@@ -8,7 +8,7 @@ import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/Com
 
 <Meta title='Components/Link' of={LinkStories} />
 
-# 🔗 Link
+# Link
 
 <CustomTabs>
   <Tab label="Overview">

package/src/lib/Components/MediaBanner/MediaBanner.mdx

@@ -12,7 +12,7 @@ import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/Com
 
 <Meta title='Components/MediaBanner' of={MediaBannerStories} />
 
-# 🖼️ MediaBanner
+# MediaBanner
 
 <CustomTabs>
   <Tab label="Overview">

package/src/lib/Components/MediaButton/MediaButton.mdx

@@ -32,13 +32,13 @@ Three appearances are available: `gray` (default), `transparent`, and `no-backgr
 
 <Canvas of={MediaButtonStories.SizeShowcase} />
 
-## Icon Types
+## Leading Content Shapes
 
-The `iconType` prop controls the padding scheme based on the leading icon's shape:
+The `leadingContentShape` prop controls the padding scheme based on the leading content's shape:
 
 - **`flat`**: Standard padding for interface icons (line icons without background).
 - **`rounded`**: Tighter left padding for circular icons with their own background (e.g., crypto icons).
 
-<Canvas of={MediaButtonStories.IconTypeShowcase} />
+<Canvas of={MediaButtonStories.LeadingContentShapeShowcase} />
 </Tab>
 </CustomTabs>

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

@@ -44,30 +44,40 @@ export const Base: Story = {
 export const SizeShowcase: Story = {
   render: () => (
     <Box lx={{ flexDirection: 'row', alignItems: 'center', gap: 's16' }}>
-      <MediaButton size='sm' icon={<Star size={20} />} iconType='flat'>
+      <MediaButton
+        size='sm'
+        leadingContent={<Star size={20} />}
+        leadingContentShape='flat'
+      >
         Small
       </MediaButton>
-      <MediaButton size='md' icon={<Star size={20} />} iconType='flat'>
+      <MediaButton
+        size='md'
+        leadingContent={<Star size={20} />}
+        leadingContentShape='flat'
+      >
         Medium
       </MediaButton>
     </Box>
   ),
 };
 
-export const IconTypeShowcase: Story = {
+export const LeadingContentShapeShowcase: Story = {
   render: () => (
     <Box lx={{ flexDirection: 'column', gap: 's16' }}>
       <Box lx={{ flexDirection: 'row', alignItems: 'center', gap: 's16' }}>
         <MediaButton
-          icon={<Settings size={20} />}
-          iconType='flat'
+          leadingContent={<Settings size={20} />}
+          leadingContentShape='flat'
           appearance='gray'
         >
           Flat icon (md)
         </MediaButton>
         <MediaButton
-          icon={<CryptoIcon ledgerId='bitcoin' ticker='BTC' size={32} />}
-          iconType='rounded'
+          leadingContent={
+            <CryptoIcon ledgerId='bitcoin' ticker='BTC' size={32} />
+          }
+          leadingContentShape='rounded'
           appearance='gray'
         >
           Rounded icon (md)
@@ -76,16 +86,18 @@ export const IconTypeShowcase: Story = {
       </Box>
       <Box lx={{ flexDirection: 'row', alignItems: 'center', gap: 's16' }}>
         <MediaButton
-          icon={<Settings size={20} />}
-          iconType='flat'
+          leadingContent={<Settings size={20} />}
+          leadingContentShape='flat'
           appearance='gray'
           size='sm'
         >
           Flat icon (sm)
         </MediaButton>
         <MediaButton
-          icon={<CryptoIcon ledgerId='bitcoin' ticker='BTC' size={24} />}
-          iconType='rounded'
+          leadingContent={
+            <CryptoIcon ledgerId='bitcoin' ticker='BTC' size={24} />
+          }
+          leadingContentShape='rounded'
           appearance='gray'
           size='sm'
         >
@@ -112,15 +124,17 @@ export const AppearanceShowcase: Story = {
             <MediaButton appearance={appearance}>{appearance}</MediaButton>
             <MediaButton
               appearance={appearance}
-              icon={<Settings size={20} />}
-              iconType='flat'
+              leadingContent={<Settings size={20} />}
+              leadingContentShape='flat'
             >
               {appearance}
             </MediaButton>
             <MediaButton
               appearance={appearance}
-              icon={<CryptoIcon ledgerId='bitcoin' ticker='BTC' size={32} />}
-              iconType='rounded'
+              leadingContent={
+                <CryptoIcon ledgerId='bitcoin' ticker='BTC' size={32} />
+              }
+              leadingContentShape='rounded'
             >
               {appearance}
             </MediaButton>

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

@@ -64,8 +64,8 @@ describe('MediaButton', () => {
       renderWithProvider(
         <MediaButton
           testID='trigger'
-          icon={<Settings size={20} testID='icon' />}
-          iconType='flat'
+          leadingContent={<Settings size={20} testID='icon' />}
+          leadingContentShape='flat'
         >
           Network
         </MediaButton>,
@@ -78,8 +78,8 @@ describe('MediaButton', () => {
       renderWithProvider(
         <MediaButton
           testID='trigger'
-          icon={<View testID='crypto-icon' />}
-          iconType='rounded'
+          leadingContent={<View testID='crypto-icon' />}
+          leadingContentShape='rounded'
         >
           Bitcoin
         </MediaButton>,

package/src/lib/Components/MediaButton/MediaButton.tsx

@@ -7,20 +7,20 @@ import type { MediaButtonProps } from './types';
 
 type Appearance = NonNullable<MediaButtonProps['appearance']>;
 type Size = NonNullable<MediaButtonProps['size']>;
-type IconType = 'flat' | 'rounded' | 'none';
+type LeadingContentShape = 'flat' | 'rounded' | 'none';
 
 const useStyles = ({
   appearance,
   size,
   disabled,
   pressed,
-  iconType,
+  leadingContentShape,
 }: {
   appearance: Appearance;
   size: Size;
   disabled: boolean;
   pressed: boolean;
-  iconType: IconType;
+  leadingContentShape: LeadingContentShape;
 }) => {
   return useStyleSheet(
     (t) => {
@@ -45,7 +45,10 @@ const useStyles = ({
         paddingRight: number;
       };
 
-      const paddingMap: Record<Size, Record<IconType, PaddingStyle>> = {
+      const paddingMap: Record<
+        Size,
+        Record<LeadingContentShape, PaddingStyle>
+      > = {
         md: {
           flat: {
             paddingTop: t.spacings.s12,
@@ -97,7 +100,7 @@ const useStyles = ({
             backgroundColor: bgColors[appearance],
             gap: t.spacings.s8,
           },
-          paddingMap[size][iconType],
+          paddingMap[size][leadingContentShape],
           pressed && { backgroundColor: pressedBgColors[appearance] },
           disabled && { backgroundColor: t.colors.bg.disabled },
           appearance === 'no-background' &&
@@ -115,7 +118,7 @@ const useStyles = ({
           alignItems: 'center',
           gap: t.spacings.s2,
         },
-        icon: {
+        leadingContent: {
           flexShrink: 0,
         },
         chevron: {
@@ -124,13 +127,13 @@ const useStyles = ({
         },
       };
     },
-    [appearance, size, disabled, pressed, iconType],
+    [appearance, size, disabled, pressed, leadingContentShape],
   );
 };
 
 /**
  * Media button for select/dropdown components. Displays a label with an optional
- * leading icon and a trailing chevron indicator.
+ * leading content and a trailing chevron indicator.
  *
  * This component is intended to be used exclusively as the trigger inside a Select or
  * dropdown pattern. It should not be used as a standalone action button — use `Button`
@@ -142,7 +145,7 @@ const useStyles = ({
  * import { MediaButton } from '@ledgerhq/lumen-ui-rnative';
  * import { Settings } from '@ledgerhq/lumen-ui-rnative/symbols';
  *
- * <MediaButton icon={<Settings size={20} />} iconType="flat">
+ * <MediaButton leadingContent={<Settings size={20} />} leadingContentShape="flat">
  *   Network
  * </MediaButton>
  *
@@ -154,14 +157,16 @@ export const MediaButton = ({
   appearance = 'gray',
   size = 'md',
   disabled = false,
-  icon,
-  iconType = 'flat',
+  leadingContent,
+  leadingContentShape = 'flat',
   hideChevron = false,
   children: label,
   ref,
   ...props
 }: MediaButtonProps) => {
-  const effectiveIconType: IconType = icon ? iconType : 'none';
+  const effectiveLeadingContentShape: LeadingContentShape = leadingContent
+    ? leadingContentShape
+    : 'none';
 
   return (
     <Pressable
@@ -179,8 +184,8 @@ export const MediaButton = ({
           size={size}
           disabled={disabled}
           pressed={pressed}
-          iconType={effectiveIconType}
-          icon={icon}
+          leadingContent={leadingContent}
+          leadingContentShape={effectiveLeadingContentShape}
           hideChevron={hideChevron}
         >
           {label}
@@ -195,8 +200,8 @@ type MediaButtonContentProps = PropsWithChildren<{
   size: Size;
   disabled: boolean;
   pressed: boolean;
-  iconType: IconType;
-  icon?: MediaButtonProps['icon'];
+  leadingContent?: MediaButtonProps['leadingContent'];
+  leadingContentShape: LeadingContentShape;
   hideChevron: boolean;
 }>;
 
@@ -205,16 +210,24 @@ const MediaButtonContent = ({
   size,
   disabled,
   pressed,
-  iconType,
-  icon,
+  leadingContent,
+  leadingContentShape,
   hideChevron,
   children,
 }: MediaButtonContentProps) => {
-  const styles = useStyles({ appearance, size, disabled, pressed, iconType });
+  const styles = useStyles({
+    appearance,
+    size,
+    disabled,
+    pressed,
+    leadingContentShape,
+  });
 
   return (
     <View style={styles.container} testID='button-trigger-content'>
-      {icon && <View style={styles.icon}>{icon}</View>}
+      {leadingContent && (
+        <View style={styles.leadingContent}>{leadingContent}</View>
+      )}
       <View style={styles.labelWrapper}>
         <Text style={styles.label} numberOfLines={1} ellipsizeMode='tail'>
           {children}

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

@@ -13,19 +13,19 @@ export type MediaButtonProps = {
    */
   size?: 'sm' | 'md';
   /**
-   * An optional pre-rendered icon element to display as leading content.
-   * Consumer is responsible for sizing the icon.
+   * An optional leading content, usually a pre-rendered icon.
+   * Consumer is responsible for sizing the icon (typically 20px).
    */
-  icon?: ReactNode;
+  leadingContent?: ReactNode;
   /**
-   * Determines the padding scheme when an icon is present.
+   * Determines the padding scheme when `leadingContent` is present.
    * - `'flat'`: Standard padding for line/interface icons.
    * - `'rounded'`: Tighter left padding for circular icons with their own background (e.g., crypto icons).
    *
-   * Only relevant when `icon` is provided.
+   * Only relevant when `leadingContent` is provided.
    * @default 'flat'
    */
-  iconType?: 'flat' | 'rounded';
+  leadingContentShape?: 'flat' | 'rounded';
   /**
    * When true, hides the trailing chevron indicator.
    * @default false

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

@@ -86,3 +86,21 @@ export const LoadingShowcase: Story = {
     </Box>
   ),
 };
+
+export const DisabledShowcase: Story = {
+  render: () => (
+    <Box lx={{ flexDirection: 'row', alignItems: 'flex-end', gap: 's16' }}>
+      <MediaImage src={exampleSrc} alt='Cardano' size={32} disabled />
+      <MediaImage src={exampleSrc} alt='Cardano' size={48} disabled />
+      <MediaImage
+        src={exampleSrc}
+        alt='Cardano'
+        size={48}
+        shape='circle'
+        disabled
+      />
+      <MediaImage fallback='Bitcoin' alt='Bitcoin' size={48} disabled />
+      <MediaImage alt='Empty' size={48} disabled />
+    </Box>
+  ),
+};