@ledgerhq/lumen-ui-rnative 0.1.47 → 0.1.48

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

@@ -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.

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

@@ -14,6 +14,7 @@ import { Spot } from '../Spot';
 import { Tag } from '../Tag/Tag';
 import { Box, Text } from '../Utility';
 import {
+  createOptionList,
   OptionList,
   OptionListContent,
   OptionListEmptyState,
@@ -1008,3 +1009,65 @@ export const WithDefaultValue: Story = {
     </Box>
   ),
 };
+
+type TypedNetwork = 'eth' | 'sol' | 'btc';
+type TypedNetworkMeta = { ticker: string; ledgerId: string };
+const NetworkList = createOptionList<TypedNetwork, TypedNetworkMeta>();
+
+const TYPED_NETWORKS: OptionListItemData<TypedNetwork, TypedNetworkMeta>[] = [
+  {
+    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' },
+  },
+];
+
+export const TypesafeFactory: Story = {
+  render: () => {
+    const [value, setValue] = useState<TypedNetwork | null>('eth');
+
+    return (
+      <Box lx={{ width: 's320' }}>
+        <NetworkList.OptionList
+          items={TYPED_NETWORKS}
+          value={value}
+          onValueChange={setValue}
+        >
+          <NetworkList.OptionListContent
+            renderItem={({ value, label, meta }) =>
+              meta ? (
+                <NetworkList.OptionListItem value={value}>
+                  <NetworkList.OptionListItemLeading>
+                    <CryptoIcon
+                      ledgerId={meta.ledgerId}
+                      ticker={meta.ticker}
+                      size={32}
+                    />
+                  </NetworkList.OptionListItemLeading>
+                  <NetworkList.OptionListItemContent>
+                    <NetworkList.OptionListItemText>
+                      {label}
+                    </NetworkList.OptionListItemText>
+                    <NetworkList.OptionListItemDescription>
+                      {meta.ticker}
+                    </NetworkList.OptionListItemDescription>
+                  </NetworkList.OptionListItemContent>
+                </NetworkList.OptionListItem>
+              ) : null
+            }
+          />
+        </NetworkList.OptionList>
+      </Box>
+    );
+  },
+};

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

@@ -15,6 +15,7 @@ import {
   OptionListEmptyState,
   OptionListSearch,
   OptionListTrigger,
+  createOptionList,
 } from './OptionList';
 import type { OptionListItemData } from './types';
 
@@ -552,4 +553,43 @@ describe('OptionList', () => {
       expect(queryByText('Selected value')).toBeTruthy();
     });
   });
+
+  describe('createOptionList', () => {
+    it('returns typed components that render and select', () => {
+      type Value = 'a' | 'b' | 'c';
+      const typedItems: OptionListItemData<Value>[] = [
+        { value: 'a', label: 'Alpha' },
+        { value: 'b', label: 'Beta' },
+        { value: 'c', label: 'Gamma' },
+      ];
+      const {
+        OptionList: TypedList,
+        OptionListContent: TypedContent,
+        OptionListItem: TypedItem,
+        OptionListItemContent: TypedItemContent,
+        OptionListItemText: TypedItemText,
+      } = createOptionList<Value>();
+      const onValueChange = jest.fn();
+
+      const { getByText } = render(
+        <TestWrapper>
+          <TypedList items={typedItems} onValueChange={onValueChange}>
+            <TypedContent
+              renderItem={(item) => (
+                <TypedItem value={item.value}>
+                  <TypedItemContent>
+                    <TypedItemText>{item.label}</TypedItemText>
+                  </TypedItemContent>
+                </TypedItem>
+              )}
+            />
+          </TypedList>
+        </TestWrapper>,
+      );
+
+      fireEvent.press(getByText('Beta'));
+
+      expect(onValueChange).toHaveBeenCalledWith('b');
+    });
+  });
 });

package/src/lib/Components/OptionList/OptionList.tsx

@@ -3,7 +3,7 @@ import {
   useDisabledContext,
   DisabledProvider,
 } from '@ledgerhq/lumen-utils-shared';
-import { Fragment, type ReactNode } from 'react';
+import { Fragment, type ReactElement, type ReactNode } from 'react';
 import { StyleSheet, View } from 'react-native';
 import { useStyleSheet } from '../../../styles';
 import { Check, ChevronDown } from '../../Symbols';
@@ -27,13 +27,17 @@ import type {
   OptionListSearchProps,
   OptionListTriggerProps,
   OptionListLabelProps,
+  OptionListValue,
 } from './types';
 import { useOptionListItems } from './useOptionList/useOptionListItems';
 
 const [OptionListProvider, useOptionListContext] =
   createSafeContext<OptionListContextValue>('OptionList');
 
-export const OptionList = <TMeta extends MetaShape = MetaShape>({
+export const OptionList = <
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+>({
   items,
   value,
   defaultValue,
@@ -45,7 +49,7 @@ export const OptionList = <TMeta extends MetaShape = MetaShape>({
   defaultSearchValue,
   onSearchValueChange,
   children,
-}: OptionListProps<TMeta>) => {
+}: OptionListProps<T, TMeta>) => {
   const disabled = useDisabledContext({
     consumerName: 'OptionList',
     mergeWith: { disabled: disabledProp },
@@ -55,7 +59,7 @@ export const OptionList = <TMeta extends MetaShape = MetaShape>({
     {
       prop: value,
       defaultProp: defaultValue ?? null,
-      onChange: onValueChange,
+      onChange: (next: string | null) => onValueChange?.(next as T | null),
     },
   );
 
@@ -65,7 +69,7 @@ export const OptionList = <TMeta extends MetaShape = MetaShape>({
     flatItems,
     resolvedSearchValue,
     handleSearchValueChange,
-  } = useOptionListItems<TMeta>({
+  } = useOptionListItems<T, TMeta>({
     items,
     filter,
     filteredItems,
@@ -93,20 +97,26 @@ export const OptionList = <TMeta extends MetaShape = MetaShape>({
   );
 };
 
-export const OptionListContent = <TMeta extends MetaShape = MetaShape>({
+export const OptionListContent = <
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+>({
   renderItem,
   lx,
   style,
   ref,
   ...props
-}: OptionListContentProps<TMeta>) => {
+}: OptionListContentProps<T, TMeta>) => {
   const { selectedValue, isGrouped, groups, flatItems } = useOptionListContext({
     consumerName: 'OptionListContent',
     contextRequired: true,
   });
 
   const renderItemWithState = (item: OptionListItemData) =>
-    renderItem(item as OptionListItemData<TMeta>, selectedValue === item.value);
+    renderItem(
+      item as OptionListItemData<T, TMeta>,
+      selectedValue === item.value,
+    );
 
   if (isGrouped) {
     return (
@@ -161,7 +171,7 @@ const useItemStyles = ({
   );
 };
 
-export const OptionListItem = ({
+export const OptionListItem = <T extends OptionListValue = OptionListValue>({
   value,
   disabled: disabledProp = false,
   children,
@@ -169,7 +179,7 @@ export const OptionListItem = ({
   style,
   ref,
   ...props
-}: OptionListItemProps) => {
+}: OptionListItemProps<T>) => {
   const { selectedValue, onValueChange } = useOptionListContext({
     consumerName: 'OptionListItem',
     contextRequired: true,
@@ -576,3 +586,40 @@ export const OptionListTrigger = ({
     </Pressable>
   );
 };
+
+export function createOptionList<
+  T extends OptionListValue = never,
+  TMeta extends MetaShape = MetaShape,
+>(): {
+  OptionList: (props: OptionListProps<T, TMeta>) => ReactElement;
+  OptionListContent: (props: OptionListContentProps<T, TMeta>) => ReactElement;
+  OptionListItem: (props: OptionListItemProps<T>) => ReactElement;
+  OptionListItemText: (props: OptionListItemTextProps) => ReactElement;
+  OptionListItemDescription: (
+    props: OptionListItemDescriptionProps,
+  ) => ReactElement;
+  OptionListItemContent: (props: OptionListItemContentProps) => ReactElement;
+  OptionListItemContentRow: (
+    props: OptionListItemContentRowProps,
+  ) => ReactElement;
+  OptionListItemLeading: (props: OptionListItemLeadingProps) => ReactElement;
+  OptionListSearch: (props: OptionListSearchProps) => ReactElement;
+  OptionListEmptyState: (
+    props: OptionListEmptyStateProps,
+  ) => ReactElement | null;
+  OptionListTrigger: (props: OptionListTriggerProps) => ReactElement;
+} {
+  return {
+    OptionList,
+    OptionListContent,
+    OptionListItem,
+    OptionListItemText,
+    OptionListItemDescription,
+    OptionListItemContent,
+    OptionListItemContentRow,
+    OptionListItemLeading,
+    OptionListSearch,
+    OptionListEmptyState,
+    OptionListTrigger,
+  };
+}

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

@@ -8,9 +8,14 @@ import type { SearchInputProps } from '../SearchInput';
 
 export type MetaShape = Record<string, unknown>;
 
-export type OptionListItemData<TMeta extends MetaShape = MetaShape> = {
+export type OptionListValue = string;
+
+export type OptionListItemData<
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+> = {
   /** Unique string identifier for this item, used for selection tracking. */
-  value: string;
+  value: T;
   /** Display text. */
   label: string;
   /** Secondary text displayed below the label inside the item. */
@@ -43,29 +48,35 @@ export type OptionListContextValue = {
 };
 
 /** Internal type -- consumers never construct this directly. */
-export type OptionListItemGroup<TMeta extends MetaShape = MetaShape> = {
+export type OptionListItemGroup<
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+> = {
   label: string;
-  items: OptionListItemData<TMeta>[];
+  items: OptionListItemData<T, TMeta>[];
 };
 
-export type OptionListProps<TMeta extends MetaShape = MetaShape> = {
+export type OptionListProps<
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+> = {
   /**
    * Flat array of items.
    * Use the `group` field on each item for automatic grouping.
    */
-  items: OptionListItemData<TMeta>[];
+  items: OptionListItemData<T, TMeta>[];
   /**
    * The controlled selected value.
    */
-  value?: string | null;
+  value?: T | null;
   /**
    * The default selected value (uncontrolled)
    */
-  defaultValue?: string | null;
+  defaultValue?: T | null;
   /**
    * Called when the selected value changes.
    */
-  onValueChange?: (value: string | null) => void;
+  onValueChange?: (value: T | null) => void;
   /**
    * When true, prevents interaction with the entire list.
    */
@@ -74,12 +85,14 @@ export type OptionListProps<TMeta extends MetaShape = MetaShape> = {
    * Custom item/query matcher.
    * Defaults to case-insensitive label match; `null` disables filtering.
    */
-  filter?: null | ((item: OptionListItemData<TMeta>, query: string) => boolean);
+  filter?:
+    | null
+    | ((item: OptionListItemData<T, TMeta>, query: string) => boolean);
   /**
    * Pre-filtered items for async/remote search.
    * Bypasses internal filtering.
    */
-  filteredItems?: OptionListItemData<TMeta>[];
+  filteredItems?: OptionListItemData<T, TMeta>[];
   /**
    * Controlled search input value.
    */
@@ -95,14 +108,20 @@ export type OptionListProps<TMeta extends MetaShape = MetaShape> = {
   children: ReactNode;
 };
 
-export type OptionListContentProps<TMeta extends MetaShape = MetaShape> = {
+export type OptionListContentProps<
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+> = {
   /** Render function called for each item. Receives the item data and selection/disabled state. */
-  renderItem: (item: OptionListItemData<TMeta>, selected: boolean) => ReactNode;
+  renderItem: (
+    item: OptionListItemData<T, TMeta>,
+    selected: boolean,
+  ) => ReactNode;
 } & Omit<StyledViewProps, 'children'>;
 
-export type OptionListItemProps = {
+export type OptionListItemProps<T extends OptionListValue = OptionListValue> = {
   /** The value associated with this item, used for selection matching. */
-  value: string;
+  value: T;
   /** Whether the item is disabled. */
   disabled?: boolean;
   children: ReactNode;

package/src/lib/Components/OptionList/useOptionList/useOptionListItems.ts

@@ -4,13 +4,17 @@ import type {
   MetaShape,
   OptionListItemData,
   OptionListItemGroup,
+  OptionListValue,
 } from '../types';
 
-const groupByField = <TMeta extends MetaShape = MetaShape>(
-  items: OptionListItemData<TMeta>[],
-): OptionListItemGroup<TMeta>[] => {
+const groupByField = <
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+>(
+  items: OptionListItemData<T, TMeta>[],
+): OptionListItemGroup<T, TMeta>[] => {
   const order: string[] = [];
-  const map: Record<string, OptionListItemData<TMeta>[]> = {};
+  const map: Record<string, OptionListItemData<T, TMeta>[]> = {};
   for (const item of items) {
     const key = item.group ?? '';
     if (!map[key]) {
@@ -30,31 +34,42 @@ export const defaultLabelFilter = (
   query: string,
 ): boolean => item.label.toLowerCase().includes(query.toLowerCase());
 
-type UseOptionListItemsParams<TMeta extends MetaShape = MetaShape> = {
-  items: OptionListItemData<TMeta>[];
-  filter?: null | ((item: OptionListItemData<TMeta>, query: string) => boolean);
-  filteredItems?: OptionListItemData<TMeta>[];
+type UseOptionListItemsParams<
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+> = {
+  items: OptionListItemData<T, TMeta>[];
+  filter?:
+    | null
+    | ((item: OptionListItemData<T, TMeta>, query: string) => boolean);
+  filteredItems?: OptionListItemData<T, TMeta>[];
   searchValue?: string;
   defaultSearchValue?: string;
   onSearchValueChange?: (value: string) => void;
 };
 
-type UseOptionListItemsResult<TMeta extends MetaShape = MetaShape> = {
+type UseOptionListItemsResult<
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+> = {
   isGrouped: boolean;
-  groups: OptionListItemGroup<TMeta>[];
-  flatItems: OptionListItemData<TMeta>[];
+  groups: OptionListItemGroup<T, TMeta>[];
+  flatItems: OptionListItemData<T, TMeta>[];
   resolvedSearchValue: string;
   handleSearchValueChange: (val: string) => void;
 };
 
-export const useOptionListItems = <TMeta extends MetaShape = MetaShape>({
+export const useOptionListItems = <
+  T extends OptionListValue = OptionListValue,
+  TMeta extends MetaShape = MetaShape,
+>({
   items,
   filter,
   filteredItems,
   searchValue: searchValueProp,
   defaultSearchValue,
   onSearchValueChange,
-}: UseOptionListItemsParams<TMeta>): UseOptionListItemsResult<TMeta> => {
+}: UseOptionListItemsParams<T, TMeta>): UseOptionListItemsResult<T, TMeta> => {
   const [searchValue, handleSearchValueChange] = useControllableState<string>({
     prop: searchValueProp,
     defaultProp: defaultSearchValue ?? '',

package/src/lib/Components/SegmentedControl/SegmentedControl.mdx

@@ -67,6 +67,8 @@ Use the library as part of `@ledgerhq/lumen-ui-rnative`. See the [Setup Guide
 
 Control selected value in state at the top level and pass it to SegmentedControl. Buttons use value to identify themselves; selected state is derived from context.
 
+> **Recommended:** prefer the [type-safe variant](#type-safe-variant) below. It shares a single literal union across the root and every button.
+
 ```tsx
 import { SegmentedControl, SegmentedControlButton } from '@ledgerhq/lumen-ui-rnative';
 
@@ -87,6 +89,32 @@ export default function Example() {
 }
 ```
 
+## Type-safe variant
+
+`SegmentedControl` and `SegmentedControlButton` communicate via context, so TypeScript cannot connect the root's `selectedValue` to each button's `value` on its own. A typo compiles, and the pill silently never moves to that segment.
+
+`createSegmentedControl<T>()` ties both components to one literal union. Call it once at module scope; the returned pair are typed against your `T`.
+
+```tsx
+import { createSegmentedControl } from '@ledgerhq/lumen-ui-rnative';
+
+type View = 'preview' | 'raw' | 'blame';
+
+const { SegmentedControl, SegmentedControlButton } = createSegmentedControl<View>();
+
+function Example() {
+  const [view, setView] = React.useState<View>('preview');
+
+  return (
+    <SegmentedControl selectedValue={view} onSelectedChange={setView}>
+      <SegmentedControlButton value='preview'>Preview</SegmentedControlButton>
+      <SegmentedControlButton value='raw'>Raw</SegmentedControlButton>
+      <SegmentedControlButton value='blame'>Blame</SegmentedControlButton>
+    </SegmentedControl>
+  );
+}
+```
+
 ## With trailing content
 
 Pass any node via `trailingContent` to render it to the right of the label. Use it for badges like `DotCount` to surface counts per segment.

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

@@ -3,7 +3,11 @@ import { useState } from 'react';
 import { Coins, Nft, TransferHorizontal } from '../../Symbols';
 import { DotCount } from '../DotCount';
 import { Box } from '../Utility';
-import { SegmentedControl, SegmentedControlButton } from './SegmentedControl';
+import {
+  createSegmentedControl,
+  SegmentedControl,
+  SegmentedControlButton,
+} from './SegmentedControl';
 
 const meta = {
   id: 'rnative-segmentedcontrol',
@@ -171,3 +175,32 @@ export const WithTrailingContent: Story = {
     );
   },
 };
+
+type View = 'preview' | 'raw' | 'blame';
+const TypedSegmentedControl = createSegmentedControl<View>();
+
+export const TypesafeFactory: Story = {
+  args: {} as React.ComponentProps<typeof SegmentedControl>,
+  render: (args) => {
+    const [view, setView] = useState<View>('preview');
+
+    return (
+      <TypedSegmentedControl.SegmentedControl
+        {...args}
+        selectedValue={view}
+        onSelectedChange={setView}
+        accessibilityLabel='File view'
+      >
+        <TypedSegmentedControl.SegmentedControlButton value='preview'>
+          Preview
+        </TypedSegmentedControl.SegmentedControlButton>
+        <TypedSegmentedControl.SegmentedControlButton value='raw'>
+          Raw
+        </TypedSegmentedControl.SegmentedControlButton>
+        <TypedSegmentedControl.SegmentedControlButton value='blame'>
+          Blame
+        </TypedSegmentedControl.SegmentedControlButton>
+      </TypedSegmentedControl.SegmentedControl>
+    );
+  },
+};

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

@@ -3,7 +3,11 @@ import { ledgerLiveThemes } from '@ledgerhq/lumen-design-core';
 import { render, fireEvent } from '@testing-library/react-native';
 import { DotCount } from '../DotCount';
 import { ThemeProvider } from '../ThemeProvider/ThemeProvider';
-import { SegmentedControl, SegmentedControlButton } from './SegmentedControl';
+import {
+  SegmentedControl,
+  SegmentedControlButton,
+  createSegmentedControl,
+} from './SegmentedControl';
 
 const TestWrapper = ({ children }: { children: React.ReactNode }) => (
   <ThemeProvider themes={ledgerLiveThemes} colorScheme='dark' locale='en'>
@@ -172,4 +176,31 @@ describe('SegmentedControl', () => {
       expect(onSelectedChange).toHaveBeenCalledWith('preview');
     });
   });
+
+  describe('createSegmentedControl', () => {
+    it('returns typed components that render and select like the originals', () => {
+      const {
+        SegmentedControl: TypedControl,
+        SegmentedControlButton: TypedButton,
+      } = createSegmentedControl<'send' | 'receive'>();
+      const onSelectedChange = jest.fn();
+
+      const { getByText } = render(
+        <TestWrapper>
+          <TypedControl
+            selectedValue='send'
+            onSelectedChange={onSelectedChange}
+            accessibilityLabel='Transaction type'
+          >
+            <TypedButton value='send'>Send</TypedButton>
+            <TypedButton value='receive'>Receive</TypedButton>
+          </TypedControl>
+        </TestWrapper>,
+      );
+
+      fireEvent.press(getByText('Receive'));
+
+      expect(onSelectedChange).toHaveBeenCalledWith('receive');
+    });
+  });
 });