@ledgerhq/lumen-ui-rnative 0.1.47 → 0.1.49

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/PageIndicator/PageIndicator.figma.tsx

@@ -0,0 +1,11 @@
+import figma from '@figma/code-connect';
+import { PageIndicator } from './PageIndicator';
+
+figma.connect(
+  PageIndicator,
+  'https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7?node-id=11768-12849',
+  {
+    imports: ["import { PageIndicator } from '@ledgerhq/lumen-ui-rnative'"],
+    example: () => <PageIndicator currentPage={2} totalPages={5} />,
+  },
+);

package/src/lib/Components/PageIndicator/PageIndicator.mdx

@@ -2,7 +2,6 @@ import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as PageIndicatorStories from './PageIndicator.stories';
 import { PageIndicator } from './PageIndicator';
 import { CustomTabs, Tab } from '../../../../.storybook/components';
-import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
 <Meta title='Core/PageIndicator' of={PageIndicatorStories} />
 
@@ -118,7 +117,6 @@ function MyComponent() {
 }
 ```
 
-<CommonRulesDoAndDont />
 
 </Tab>
 </CustomTabs>

package/src/lib/Components/SearchInput/SearchInput.figma.tsx

@@ -0,0 +1,34 @@
+import figma from '@figma/code-connect';
+import { SearchInput } from './SearchInput';
+
+figma.connect(
+  SearchInput,
+  'https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7?node-id=2248%3A3468',
+  {
+    imports: ["import { SearchInput } from '@ledgerhq/lumen-ui-rnative'"],
+    props: {
+      appearance: figma.enum('appearance', {
+        plain: 'plain',
+        transparent: 'transparent',
+      }),
+      placeholder: figma.enum('search-state', {
+        placeholder: figma.string('placeholder'),
+      }),
+      value: figma.enum('search-state', {
+        typing: figma.string('value'),
+      }),
+      disabled: figma.enum('state', {
+        disabled: true,
+      }),
+    },
+    example: (props) => (
+      <SearchInput
+        appearance={props.appearance}
+        placeholder={props.placeholder}
+        value={props.value}
+        disabled={props.disabled}
+        onChangeText={() => {}}
+      />
+    ),
+  },
+);

package/src/lib/Components/SearchInput/SearchInput.mdx

@@ -2,8 +2,6 @@ import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as SearchInputStories from './SearchInput.stories';
 import { SearchInput } from './SearchInput';
 import { CustomTabs, Tab } from '../../../../.storybook/components';
-import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
-import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 
 <Meta title='Core/SearchInput' of={SearchInputStories} />
 
@@ -326,203 +324,6 @@ function MyComponent() {
 }
 ```
 
-## Do's and Don'ts
-
-The following guidelines ensure consistent usage of the SearchInput component and maintain design system principles.
-
-<div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
-  <DoVsDontRow>
-    <DoBlockItem
-      title='Use placeholder text'
-      description='SearchInput uses placeholder text instead of labels for optimal search UX'
-    >
-
-{/* prettier-ignore */}
-```tsx
-<SearchInput
-  placeholder='Search by name or email'
-  value={query}
-  onChangeText={setQuery}
-/>
-```
-
-    </DoBlockItem>
-    <DontBlockItem
-      title="Don't use label prop"
-      description='SearchInput component does not support labels as they are not suitable for search UX patterns'
-    >
-
-{/* prettier-ignore */}
-```tsx
-<SearchInput
-  label='Search' // Not supported, will cause error
-  placeholder='Search by name or email'
-  value={query}
-/>
-```
-
-    </DontBlockItem>
-
-  </DoVsDontRow>
-
-  <DoVsDontRow>
-    <DoBlockItem
-      title='Use the built-in search icon'
-      description='The search icon is automatically included and cannot be changed'
-    >
-
-{/* prettier-ignore */}
-```tsx
-<SearchInput
-  placeholder='Search products'
-  value={query}
-  onChangeText={handleChange}
-/>
-```
-
-    </DoBlockItem>
-    <DontBlockItem
-      title="Don't override the search icon"
-      description='The prefix prop is not available on SearchInput component'
-    >
-
-{/* prettier-ignore */}
-```tsx
-<SearchInput
-  prefix={<CustomIcon />} // Not supported, will cause error
-  placeholder='Search products'
-/>
-```
-
-    </DontBlockItem>
-
-  </DoVsDontRow>
-
-  <DoVsDontRow>
-    <DoBlockItem
-      title='Use onClear for custom logic only'
-      description='Let the component handle clearing automatically, add onClear only for additional logic'
-    >
-
-{/* prettier-ignore */}
-```tsx
-<SearchInput
-  placeholder='Search'
-  value={query}
-  onChangeText={setQuery}
-  onClear={() => {
-    // Default clearing happens automatically
-    analytics.track('search_cleared');
-  }}
-/>
-```
-
-    </DoBlockItem>
-    <DontBlockItem
-      title="Don't manually clear in onClear"
-      description='Value clearing happens automatically - no need to call setQuery'
-    >
-
-{/* prettier-ignore */}
-```tsx
-<SearchInput
-  placeholder='Search'
-  value={query}
-  onChangeText={setQuery}
-  onClear={() => setQuery('')}
-/>
-```
-
-    </DontBlockItem>
-
-  </DoVsDontRow>
-
-  <DoVsDontRow>
-    <DoBlockItem
-      title='Debounce expensive search operations'
-      description='Use debouncing for API calls or expensive filtering to improve performance'
-    >
-
-{/* prettier-ignore */}
-```tsx
-const debouncedSearch = useCallback(
-  debounce((text: string) => performSearch(text), 500),
-  []
-);
-
-<SearchInput
-  placeholder='Search'
-  value={query}
-  onChangeText={(text) => {
-    setQuery(text);
-    debouncedSearch(text);
-  }}
-/>
-```
-
-    </DoBlockItem>
-    <DontBlockItem
-      title="Don't perform expensive operations on every keystroke"
-      description='Avoid running expensive operations on every input change without debouncing'
-    >
-
-{/* prettier-ignore */}
-```tsx
-const debouncedSearch = useCallback(
-  debounce((text: string) => performSearch(text), 500),
-  []
-);
-
-<SearchInput
-  placeholder='Search'
-  value={query}
-  onChangeText={(text) => {
-    setQuery(text);
-    performExpensiveAPICall(text); // Should be debounced
-  }}
-/>
-```
-
-    </DontBlockItem>
-
-  </DoVsDontRow>
-
-  <DoVsDontRow>
-    <DoBlockItem
-      title='Provide descriptive placeholder text'
-      description='Use clear, specific placeholder text that describes what users can search for'
-    >
-
-{/* prettier-ignore */}
-```tsx
-<SearchInput
-  placeholder='Search by name or email'
-  value={query}
-  onChangeText={setQuery}
-/>
-```
-
-    </DoBlockItem>
-    <DontBlockItem
-      title="Don't use vague placeholder text"
-      description='Avoid generic or unclear placeholder text that does not help users'
-    >
-
-{/* prettier-ignore */}
-```tsx
-<SearchInput
-  placeholder='Type here'
-  value={query}
-  onChangeText={setQuery}
-/>
-```
-
-    </DontBlockItem>
-
-  </DoVsDontRow>
-
-  <CommonRulesDoAndDont />
-</div>
 
 ## Platform Considerations
 

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

@@ -0,0 +1,34 @@
+import figma from '@figma/code-connect';
+import { SegmentedControl, SegmentedControlButton } from './SegmentedControl';
+
+figma.connect(
+  SegmentedControl,
+  'https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7?node-id=1170-2345',
+  {
+    imports: [
+      "import { SegmentedControl, SegmentedControlButton } from '@ledgerhq/lumen-ui-rnative'",
+    ],
+    props: {
+      appearance: figma.enum('appearance', {
+        background: 'background',
+        'no-background': 'no-background',
+      }),
+      tabLayout: figma.enum('tab-width', {
+        fixed: 'fixed',
+        hug: 'fit',
+      }),
+    },
+    example: (props) => (
+      <SegmentedControl
+        selectedValue='tab1'
+        onSelectedChange={() => {}}
+        appearance={props.appearance}
+        tabLayout={props.tabLayout}
+      >
+        <SegmentedControlButton value='tab1'>Tab 1</SegmentedControlButton>
+        <SegmentedControlButton value='tab2'>Tab 2</SegmentedControlButton>
+        <SegmentedControlButton value='tab3'>Tab 3</SegmentedControlButton>
+      </SegmentedControl>
+    ),
+  },
+);

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

@@ -2,7 +2,6 @@ import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as SegmentedControlStories from './SegmentedControl.stories';
 import { SegmentedControl } from './SegmentedControl';
 import { CustomTabs, Tab } from '../../../../.storybook/components';
-import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
 import { Box } from '../Utility';
 
 <Meta title='Core/SegmentedControl' of={SegmentedControlStories} />
@@ -67,6 +66,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 +88,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.