@ledgerhq/lumen-ui-rnative 0.1.46 → 0.1.48

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

@@ -7,7 +7,8 @@ import { DotSymbol, mediaImageDotSizeMap } from './DotSymbol';
 
 const meta = {
   component: DotSymbol,
-  title: 'Communication/DotSymbol',
+  id: 'rnative-dotsymbol',
+  title: 'Core/DotSymbol',
   parameters: {
     docs: {
       source: {

package/src/lib/Components/Icon/Icon.mdx

@@ -0,0 +1,211 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as IconsStories from './Icon.stories';
+import { Box } from '../Utility';
+import { CustomTabs, Tab } from '../../../../.storybook/components';
+import {
+  DoVsDontRow,
+  DoBlockItem,
+  DontBlockItem,
+} from '../../../../.storybook/components/DoVsDont';
+import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
+
+<Meta title='Symbols/Interface Icons' of={IconsStories} />
+
+# Icons
+
+<CustomTabs>
+  <Tab label="Overview">
+
+Icons are essential elements that communicate meaning quickly and visually. They support navigation, clarify actions, and enhance the overall user experience. A well-designed icon set ensures clarity, consistency, and scalability across platforms.
+
+---
+
+## Figma Library
+
+All icons are designed and managed in our Figma Foundations library. This is the single source of truth for our icon set.
+
+- 🔗 **[Figma - Icons Library](https://www.figma.com/design/zSkvGGiqcnhywp2l3HTHxA/1.Symbol-Library?node-id=50-5110&m=dev)**
+
+---
+
+## Interactive Example
+
+<Canvas of={IconsStories.Base} />
+<Controls of={IconsStories.Base} />
+
+## 📏 Sizing
+
+Our icons are designed to be scalable and are available in 7 standard sizes to fit various contexts within the UI.
+
+The available sizes are: **16px, 20px, 24px, 32px, 40px, 48px, and 56px**
+
+The thickness of each icon is automatically managed by our token system when you apply a size variable, ensuring visual consistency at any scale.
+
+<Canvas of={IconsStories.Sizes} />
+
+---
+
+## Icon Gallery
+
+Here's a preview of all the icons available in our design system. To use an icon, just reference its name.
+
+<Canvas of={IconsStories.Gallery} />
+
+</Tab>
+<Tab label="Implementation">
+
+## Setup
+
+Install and set up the library with our [Setup Guide →](?path=/docs/getting-started-setup--docs).
+
+## Basic Usage
+
+Import and use specific icons from the symbols library:
+
+```tsx
+import { ArrowUp, Settings, Plus } from '@ledgerhq/lumen-ui-rnative/symbols';
+
+function MyComponent() {
+  return (
+    <Box lx={{ flexDirection: 'row', gap: 's8' }}>
+      <ArrowUp size={24} />
+      <Settings size={20} />
+      <Plus size={16} />
+    </Box>
+  );
+}
+```
+
+### Size Variants
+
+Icons support predefined size variants that ensure consistent visual hierarchy:
+
+```tsx
+import { ArrowUp } from '@ledgerhq/lumen-ui-rnative/symbols';
+
+function IconSizes() {
+  return (
+    <Box lx={{ flexDirection: 'row', alignItems: 'center', gap: 's8' }}>
+      <ArrowUp size={16} />
+      <ArrowUp size={20} />
+      <ArrowUp size={24} /> {/* Default size */}
+      <ArrowUp size={40} />
+      <ArrowUp size={48} />
+      <ArrowUp size={56} />
+    </Box>
+  );
+}
+```
+
+### Within Buttons
+
+The Button component supports icons with automatic size adjustment based on the button size:
+
+```tsx
+import { Button } from '@ledgerhq/lumen-ui-rnative';
+import { ArrowRight } from '@ledgerhq/lumen-ui-rnative/symbols';
+
+function MyComponent() {
+  return (
+    <Button size='m' appearance='base' icon={ArrowRight}>
+      Continue
+    </Button>
+  );
+}
+```
+
+### Accessibility
+
+Always provide proper accessibility attributes for interactive icons:
+
+```tsx
+import { Information } from '@ledgerhq/lumen-ui-rnative/symbols';
+
+function AccessibleIcon() {
+  return (
+    <Information size={20} accessibilityLabel='Account verification required' />
+  );
+}
+```
+
+### With Semantic Colors
+
+Icons inherit the current text color and can be styled with semantic color tokens:
+
+```tsx
+import {
+  CheckmarkCircle,
+  DeleteCircle,
+  Clock,
+} from '@ledgerhq/lumen-ui-rnative/symbols';
+
+function SemanticIcons() {
+  return (
+    <Box lx={{ flexDirection: 'row', gap: 's8' }}>
+      <CheckmarkCircle size={24} lx={{ color: 'success' }} />
+      <DeleteCircle size={24} lx={{ color: 'error' }} />
+      <Clock size={24} lx={{ color: 'warning' }} />
+    </Box>
+  );
+}
+```
+
+## Do's and Don'ts
+
+<Box lx={{ flexDirection: 'column', gap: 's24' }}>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use predefined size variants'
+      description='Standard sizes ensure consistent visual hierarchy'
+    >
+
+```tsx
+<ArrowUp size={24} />
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't use custom sizes"
+      description='Avoid non-standard sizes or arbitrary prop overrides'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<ArrowUp size={23} />
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use semantic colors for icons'
+      description='Use semantic color tokens and inherit text color'
+    >
+
+```tsx
+<ArrowUp lx={{ color: 'success' }} />
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't use arbitrary colors"
+      description='Avoid arbitrary color values or overriding currentColor unnecessarily'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<ArrowUp color='#ff0000' />
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <CommonRulesDoAndDont />
+</Box>
+
+</Tab>
+</CustomTabs>

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

@@ -7,6 +7,7 @@ import { Box, Text, Pressable } from '../Utility';
 import type { IconSize } from './types';
 
 const meta: Meta = {
+  id: 'rnative-icon',
   title: 'Symbols/Interface Icons',
 };
 
@@ -90,7 +91,7 @@ const IconCard = ({ name, size = 24, color }: IconCardProps) => {
   );
 };
 
-export const Icon: StoryObj<IconStoryProps> = {
+export const Base: StoryObj<IconStoryProps> = {
   args: {
     size: 24,
     name: 'Home',
@@ -139,7 +140,7 @@ export const Icon: StoryObj<IconStoryProps> = {
   },
 };
 
-export const IconSizes: StoryObj = {
+export const Sizes: StoryObj = {
   render: () => {
     const { theme } = useTheme();
 

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

@@ -6,7 +6,7 @@ import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 import { Box } from '../Utility';
 
-<Meta title='Action/IconButton' of={IconButtonStories} />
+<Meta title='Core/IconButton' of={IconButtonStories} />
 
 # IconButton
 

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

@@ -12,7 +12,8 @@ const iconMap = {
 } as const;
 
 const meta: Meta<typeof IconButton> = {
-  title: 'Action/IconButton',
+  id: 'rnative-iconbutton',
+  title: 'Core/IconButton',
   component: IconButton,
   argTypes: {
     icon: {

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

@@ -6,7 +6,7 @@ import { CustomTabs, Tab } from '../../../../.storybook/components';
 import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
-<Meta title='Components/InteractiveIcon' of={InteractiveIconStories} />
+<Meta title='Core/InteractiveIcon' of={InteractiveIconStories} />
 
 # InteractiveIcon
 

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

@@ -10,7 +10,8 @@ import { InteractiveIcon } from './InteractiveIcon';
 
 const meta: Meta<typeof InteractiveIcon> = {
   component: InteractiveIcon,
-  title: 'Action/InteractiveIcon',
+  id: 'rnative-interactiveicon',
+  title: 'Core/InteractiveIcon',
   parameters: {
     docs: {
       source: {

package/src/lib/Components/InteractiveIcon/InteractiveIcon.tsx

@@ -72,8 +72,7 @@ const useStyles = ({
  * The InteractiveIcon provides two visual styles - 'filled' and 'stroked' - optimized for different icon types and use cases.
  * It ensures proper pressed states and accessibility features while maintaining a minimal footprint.
  *
- * @see {@link https://ldls.vercel.app/?path=/docs/components-interactiveicon-overview--docs Storybook}
- * @see {@link https://ldls.vercel.app/?path=/docs/components-interactiveicon-implementation--docs#dos-and-donts Guidelines}
+ * @see {@link https://ldls-react-native.vercel.app/?path=/docs/rnative-interactiveicon--docs Guidelines}
  *
  * @component
  *

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

@@ -6,7 +6,7 @@ import { CustomTabs, Tab } from '../../../../.storybook/components';
 import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
-<Meta title='Components/Link' of={LinkStories} />
+<Meta title='Core/Link' of={LinkStories} />
 
 # Link
 

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

@@ -5,7 +5,8 @@ import { Link } from './Link';
 
 const meta: Meta<typeof Link> = {
   component: Link,
-  title: 'Action/Link',
+  id: 'rnative-link',
+  title: 'Core/Link',
   parameters: {
     docs: {
       source: {

package/src/lib/Components/Link/Link.tsx

@@ -73,8 +73,7 @@ const useStyles = ({ appearance, size, underline, pressed }: StyleParams) => {
  * A customizable link component that supports base and accent color appearances, optional underline, sizes, icons, and external link handling.
  * Opens URLs using React Native's Linking API.
  *
- * @see {@link https://ldls.vercel.app/?path=/docs/components-link-overview--docs Storybook}
- * @see {@link https://ldls.vercel.app/?path=/docs/components-link-implementation--docs#dos-and-donts Guidelines}
+ * @see {@link https://ldls-react-native.vercel.app/?path=/docs/rnative-link--docs Guidelines}
  *
  * @warning The `lx` prop should only be used for layout adjustments like margins or positioning.
  * Do not use it to modify the link's core appearance (colors, padding, etc). Use the `appearance` and `underline` props instead.

package/src/lib/Components/ListItem/ListItem.mdx

@@ -19,7 +19,7 @@ import {
 } from '../../../../.storybook/components';
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
-<Meta title='Components/ListItem' of={ListItemStories} />
+<Meta title='Core/ListItem' of={ListItemStories} />
 
 # ListItem
 

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

@@ -19,7 +19,8 @@ import {
 
 const meta = {
   component: ListItem,
-  title: 'Containment/ListItem',
+  id: 'rnative-listitem',
+  title: 'Core/ListItem',
   subcomponents: {
     ListItemLeading,
     ListItemContent,

package/src/lib/Components/ListItem/ListItem.tsx

@@ -57,8 +57,7 @@ const useRootStyles = ({
  * A flexible list item component that provides a composable structure for displaying
  * interactive list items with leading content, title, description, and trailing content.
  *
- * @see {@link https://ldls.vercel.app/?path=/docs/react-native_containment-listitem--docs Storybook}
- * @see {@link https://ldls.vercel.app/?path=/docs/react-native_containment-listitem--docs#dos-and-donts Guidelines}
+ * @see {@link https://ldls-react-native.vercel.app/?path=/docs/rnative-listitem--docs Guidelines}
  *
  * @warning The `lx` prop should only be used for layout adjustments like margins or positioning.
  * Do not use it to modify the list item's core appearance (colors, padding, etc).

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

@@ -10,7 +10,7 @@ import { CustomTabs, Tab } from '../../../../.storybook/components';
 import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
-<Meta title='Components/MediaBanner' of={MediaBannerStories} />
+<Meta title='Core/MediaBanner' of={MediaBannerStories} />
 
 # MediaBanner
 

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

@@ -13,7 +13,8 @@ const IMAGE_URL =
 
 const meta: Meta<typeof MediaBanner> = {
   component: MediaBanner,
-  title: 'Communication/MediaBanner',
+  id: 'rnative-mediabanner',
+  title: 'Core/MediaBanner',
   subcomponents: {
     MediaBannerTitle,
     MediaBannerDescription,

package/src/lib/Components/MediaBanner/MediaBanner.tsx

@@ -14,7 +14,7 @@ import type {
 /**
  * A promotional banner with a background image, title, description, and an optional close button.
  *
- * @see {@link https://ldls.vercel.app/?path=/docs/communication-mediabanner--docs Storybook}
+ * @see {@link https://ldls-react-native.vercel.app/?path=/docs/rnative-mediabanner--docs Storybook}
  */
 export function MediaBanner({
   lx,

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

@@ -2,7 +2,7 @@ import { CustomTabs, Tab } from '../../../../.storybook/components';
 import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as MediaButtonStories from './MediaButton.stories';
 
-<Meta title='Action/MediaButton' of={MediaButtonStories} />
+<Meta title='Core/MediaButton' of={MediaButtonStories} />
 
 <CustomTabs>
   <Tab label="Overview ">
@@ -15,7 +15,7 @@ A specialized media button designed exclusively for option list and dropdown pat
 
 > View in [Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=6389-45680&m=dev).
 
-> **Important**: This component should only be used as a trigger inside an OptionList or dropdown. For standalone actions, use [Button](/docs/action-button--docs) or [IconButton](/docs/action-iconbutton--docs) instead.
+> **Important**: This component should only be used as a trigger inside an OptionList or dropdown. For standalone actions, use [Button](/docs/rnative-button--docs) or [IconButton](/docs/rnative-iconbutton--docs) instead.
 
 ## Properties
 

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

@@ -6,7 +6,8 @@ import { MediaButton } from './MediaButton';
 
 const meta: Meta<typeof MediaButton> = {
   component: MediaButton,
-  title: 'Action/MediaButton',
+  id: 'rnative-mediabutton',
+  title: 'Core/MediaButton',
   parameters: {
     layout: 'centered',
     docs: {

package/src/lib/Components/MediaCard/MediaCard.mdx

@@ -3,7 +3,7 @@ import * as MediaCardStories from './MediaCard.stories';
 import { CustomTabs, Tab } from '../../../../.storybook/components';
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
-<Meta title='Communication/MediaCard' of={MediaCardStories} />
+<Meta title='Core/MediaCard' of={MediaCardStories} />
 
 # MediaCard
 

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

@@ -9,7 +9,8 @@ import { MediaCard, MediaCardTitle } from './MediaCard';
 const meta = {
   component: MediaCard,
   subcomponents: { MediaCardTitle },
-  title: 'Communication/MediaCard',
+  id: 'rnative-mediacard',
+  title: 'Core/MediaCard',
   parameters: {
     layout: 'centered',
     backgrounds: { default: 'light' },

package/src/lib/Components/MediaImage/MediaImage.mdx

@@ -5,7 +5,7 @@ import { CustomTabs, Tab } from '../../../../.storybook/components';
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
 
-<Meta title='Communication/MediaImage' of={MediaImageStories} />
+<Meta title='Core/MediaImage' of={MediaImageStories} />
 
 # MediaImage
 

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

@@ -4,7 +4,8 @@ import { MediaImage } from './MediaImage';
 
 const meta = {
   component: MediaImage,
-  title: 'Communication/MediaImage',
+  id: 'rnative-mediaimage',
+  title: 'Core/MediaImage',
   parameters: {
     docs: {
       source: {

package/src/lib/Components/MediaTag/MediaTag.mdx

@@ -5,7 +5,7 @@ import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 import { Box } from '../Utility/Box';
 
-<Meta title='Components/MediaTag' of={MediaTagStories} />
+<Meta title='Core/MediaTag' of={MediaTagStories} />
 
 # MediaTag
 
@@ -14,7 +14,7 @@ import { Box } from '../Utility/Box';
 
 ## Introduction
 
-MediaTag is a compact label used to categorize, classify, or highlight information alongside a required media element such as an image or crypto icon. Like [Tag](/docs/communication-tag--docs), it supports multiple appearances and sizes, but is designed for cases where the icon is richer than a Symbol.
+MediaTag is a compact label used to categorize, classify, or highlight information alongside a required media element such as an image or crypto icon. Like [Tag](/docs/rnative-tag--docs), it supports multiple appearances and sizes, but is designed for cases where the icon is richer than a Symbol.
 
 > View in [Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=16793-36383&m=dev).
 

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

@@ -14,7 +14,8 @@ const ETH_ICON = (
 
 const meta: Meta<typeof MediaTag> = {
   component: MediaTag,
-  title: 'Communication/MediaTag',
+  id: 'rnative-mediatag',
+  title: 'Core/MediaTag',
   argTypes: {
     appearance: {
       control: 'select',

package/src/lib/Components/MediaTag/MediaTag.tsx

@@ -6,8 +6,7 @@ import type { MediaTagProps } from './types';
  *
  * The appearance determines the color scheme used.
  *
- * @see {@link https://ldls.vercel.app/?path=/docs/communication-mediatag-overview--docs Storybook}
- * @see {@link https://ldls.vercel.app/?path=/docs/communication-mediatag-implementation--docs#dos-and-donts Guidelines}
+ * @see {@link https://ldls-react-native.vercel.app/?path=/docs/rnative-mediatag--docs Guidelines}
  *
  * @warning The `lx` prop should only be used for layout adjustments like margins or positioning.
  * Do not use it to modify the tag's core appearance (colors, padding, etc). Use the `appearance` prop instead.

package/src/lib/Components/NavBar/NavBar.mdx

@@ -5,7 +5,7 @@ import { NavBar, NavBarBackButton, NavBarContent } from './NavBar';
 import { CustomTabs, Tab } from '../../../../.storybook/components';
 import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
-<Meta title='Navigation/NavBar' of={NavBarStories} />
+<Meta title='Core/NavBar' of={NavBarStories} />
 
 # NavBar
 

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

@@ -14,7 +14,8 @@ import {
 
 const meta: Meta<typeof NavBar> = {
   component: NavBar,
-  title: 'Navigation/NavBar',
+  id: 'rnative-navbar',
+  title: 'Core/NavBar',
   subcomponents: {
     NavBarBackButton,
     NavBarContent,

package/src/lib/Components/OptionList/OptionList.mdx

@@ -8,7 +8,7 @@ import {
   DontBlockItem,
 } from '../../../../.storybook/components';
 
-<Meta title='Selection/OptionList' of={OptionListStories} />
+<Meta title='Core/OptionList' of={OptionListStories} />
 
 # OptionList
 
@@ -97,6 +97,8 @@ Install and set up the library with our [Setup Guide →](?path=/docs/getting-st
 
 ## Basic usage
 
+> **Recommended:** prefer the [type-safe variant](#type-safe-variant) below. It ties `value`, `items[].value`, `OptionListItem.value`, and the `renderItem(item).meta` shape to one literal union plus an optional `TMeta`, dropping the `as Meta` casts in `renderItem`.
+
 ```tsx
 import {
   OptionList,
@@ -130,6 +132,49 @@ function MyList() {
 }
 ```
 
+## Type-safe variant
+
+`OptionList` and its subcomponents communicate via context, so TypeScript cannot connect `value` / `items[].value` / `OptionListItem.value` on its own. A typo compiles. `createOptionList<T, TMeta>()` ties them together via one literal union (`T`) and an optional meta shape (`TMeta`) that flows into `renderItem(item)`, removing the `as` cast on `item.meta`.
+
+```tsx
+import { createOptionList } from '@ledgerhq/lumen-ui-rnative';
+import type { OptionListItemData } from '@ledgerhq/lumen-ui-rnative';
+
+type Network = 'eth' | 'sol' | 'btc';
+type NetworkMeta = { ticker: string; ledgerId: string };
+
+const NetworkList = createOptionList<Network, NetworkMeta>();
+
+const NETWORKS: OptionListItemData<Network, NetworkMeta>[] = [
+  { value: 'eth', label: 'Ethereum', meta: { ticker: 'ETH', ledgerId: 'ethereum' } },
+  { value: 'sol', label: 'Solana', meta: { ticker: 'SOL', ledgerId: 'solana' } },
+  { value: 'btc', label: 'Bitcoin', meta: { ticker: 'BTC', ledgerId: 'bitcoin' } },
+];
+
+function Example() {
+  const [value, setValue] = React.useState<Network | null>('eth');
+
+  return (
+    <NetworkList.OptionList items={NETWORKS} value={value} onValueChange={setValue}>
+      <NetworkList.OptionListContent
+        renderItem={({ value, label, meta }) =>
+          meta ? (
+            <NetworkList.OptionListItem value={value}>
+              <NetworkList.OptionListItemContent>
+                <NetworkList.OptionListItemText>{label}</NetworkList.OptionListItemText>
+                <NetworkList.OptionListItemDescription>
+                  {meta.ticker}
+                </NetworkList.OptionListItemDescription>
+              </NetworkList.OptionListItemContent>
+            </NetworkList.OptionListItem>
+          ) : null
+        }
+      />
+    </NetworkList.OptionList>
+  );
+}
+```
+
 ## Inside a BottomSheet
 
 Use `OptionListTrigger` as the input-style trigger — it provides a floating label that animates up when a value is selected, and a chevron indicator. Pass children only when a value is selected so the label stays centered when empty.