@ledgerhq/lumen-ui-rnative 0.1.37 → 0.1.38

package/src/lib/Components/Select/Select.mdx

@@ -1,596 +0,0 @@
-import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
-import * as SelectStories from './Select.stories.tsx';
-import { Select } from './Select';
-import { CustomTabs, Tab } from '../../../../.storybook/components';
-
-<Meta title='Selection/Select' of={SelectStories} />
-
-# Select
-
-<CustomTabs>
-  <Tab label="Overview">
-
-## Introduction
-
-The Select component provides a dropdown interface for choosing from a list of options using a native bottom sheet. Built specifically for React Native, it offers excellent accessibility, touch-friendly interactions, and a modern floating label design that matches our BaseInput component.
-
-> View in [Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=6397-463&m=dev).
-
-> ⚠️ **Note on Web Preview:** The Storybook preview below may display visual inconsistencies as certain React Native APIs (such as Reanimated animations) cannot be fully translated to web environments. While the component's functionality should accurately represent the native implementation, it may not render as intended. For the complete native experience, please refer to the component on an actual iOS or Android device.
-
-<Canvas of={SelectStories.Base} />
-<Controls of={SelectStories.Base} />
-
-## Anatomy
-
-> **Layout:** The Select component takes the full width of its container by default. You can control the width directly using `lx` prop or by wrapping in a container.
-
-The Select component consists of several sub-components:
-
-- **Select**: The root component that manages the select's state
-- **SelectTrigger**: The clickable element that opens the bottom sheet with floating label support
-- **SelectValue**: Displays the currently selected value
-- **SelectContent**: Container for select items (not rendered directly, used for structure)
-- **SelectItem**: Individual selectable options
-- **SelectItemText**: The text content of an item
-- **SelectGroup**: Optional grouping of related items
-- **SelectLabel**: Labels for groups
-- **SelectSeparator**: Visual dividers between groups or items
-
-### Bottom Sheet Architecture
-
-Unlike web implementations, the React Native Select uses a bottom sheet for displaying options. This provides a native mobile experience with smooth animations and proper handling of keyboard and screen size.
-
-The bottom sheet requires `ThemeProvider` and `BottomSheetModalProvider` at your app's root level. See the [Implementation tab](#implementation) for setup.
-
-### Floating Label
-
-The label text automatically floats above the input when a value is selected, providing a clean and modern interface that saves vertical space.
-
-### Disabled State
-
-The select can be disabled to prevent user interaction, with visual feedback indicating the disabled state.
-
-## Properties
-
-### Grouped Options
-
-Organize options with groups, labels, and separators:
-
-<Canvas of={SelectStories.WithGroups} />
-
-### Disabled Items
-
-Individual items can be disabled while keeping the select interactive:
-
-<Canvas of={SelectStories.WithDisabledItems} />
-
-### Disabled Select
-
-The entire select can be disabled:
-
-<Canvas of={SelectStories.DisabledSelect} />
-
-### With Callbacks
-
-Listen to value changes and open/close events:
-
-<Canvas of={SelectStories.WithChangeCallback} />
-
-## Controlled vs Uncontrolled
-
-The Select component supports both controlled and uncontrolled usage.
-
-### Uncontrolled (with defaultValue)
-
-Use `defaultValue` when you don't need to track the select's value in state. The component manages its own internal state.
-
-### Controlled (with value and onValueChange)
-
-Use `value` and `onValueChange` when you want full control of the select's state from your component logic.
-
-## Accessibility
-
-The Select component follows accessibility best practices:
-
-- Supports screen reader navigation
-- Labels are properly associated with selects
-- Touch target sizes meet minimum requirements (48px height)
-- Proper focus management with bottom sheet
-- Check icon indicates selected state
-- Disabled items are properly announced
-
-## Best Practices
-
-**Labels**: Always provide clear, descriptive labels
-
-**Grouping**: Use groups and separators for long lists with related items
-
-**Default Values**: Consider providing sensible defaults when appropriate
-
-**Disabled State**: Use `disabled` on both the Select and individual items when needed
-
-**Value Management**: Always provide both `value` and `onValueChange` for controlled usage
-
-</Tab>
-<Tab label="Implementation">
-
-## Setup
-
-Install and set up the library with our [Setup Guide →](?path=/docs/getting-started-setup--docs).
-
-### Provider Setup
-
-Select uses a bottom sheet that requires specific providers. `BottomSheetModalProvider` must be **inside** `GestureHandlerRootView`:
-
-```tsx
-import { ThemeProvider, BottomSheetModalProvider, GlobalSelectBottomSheet } from '@ledgerhq/lumen-ui-rnative';
-import { GestureHandlerRootView } from 'react-native-gesture-handler';
-
-function App() {
-  return (
-    <ThemeProvider themes={yourThemes} colorScheme="light">
-      <GestureHandlerRootView style={{ flex: 1 }}>
-        <BottomSheetModalProvider>
-          <YourAppContent />
-          <GlobalSelectBottomSheet />
-        </BottomSheetModalProvider>
-      </GestureHandlerRootView>
-    </ThemeProvider>
-  );
-}
-```
-
-### Basic Usage
-
-```tsx
-import {
-  Select,
-  SelectTrigger,
-  SelectValue,
-  SelectContent,
-  SelectItem,
-  SelectItemText,
-} from '@ledgerhq/lumen-ui-rnative';
-import { useState } from 'react';
-
-function MyComponent() {
-  const [value, setValue] = useState('');
-
-  return (
-    <Select value={value} onValueChange={setValue}>
-      <SelectTrigger label='Choose an option'>
-        <SelectValue />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectItem value='option1'>
-          <SelectItemText>Option 1</SelectItemText>
-        </SelectItem>
-        <SelectItem value='option2'>
-          <SelectItemText>Option 2</SelectItemText>
-        </SelectItem>
-        <SelectItem value='option3'>
-          <SelectItemText>Option 3</SelectItemText>
-        </SelectItem>
-      </SelectContent>
-    </Select>
-  );
-}
-```
-
-> **Note:** `SelectValue` must be explicitly included in `SelectTrigger` to display the selected value.
-
-### With Groups and Separators
-
-Organize related options using groups with labels and separators:
-
-```tsx
-import {
-  Select,
-  SelectTrigger,
-  SelectValue,
-  SelectContent,
-  SelectGroup,
-  SelectLabel,
-  SelectItem,
-  SelectItemText,
-  SelectSeparator,
-} from '@ledgerhq/lumen-ui-rnative';
-import { useState } from 'react';
-
-function MyComponent() {
-  const [value, setValue] = useState('');
-
-  return (
-    <Select value={value} onValueChange={setValue}>
-      <SelectTrigger label='Category'>
-        <SelectValue />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectGroup>
-          <SelectLabel>Fruits</SelectLabel>
-          <SelectItem value='apple'>
-            <SelectItemText>Apple</SelectItemText>
-          </SelectItem>
-          <SelectItem value='banana'>
-            <SelectItemText>Banana</SelectItemText>
-          </SelectItem>
-        </SelectGroup>
-        <SelectSeparator />
-        <SelectGroup>
-          <SelectLabel>Vegetables</SelectLabel>
-          <SelectItem value='carrot'>
-            <SelectItemText>Carrot</SelectItemText>
-          </SelectItem>
-          <SelectItem value='broccoli'>
-            <SelectItemText>Broccoli</SelectItemText>
-          </SelectItem>
-        </SelectGroup>
-      </SelectContent>
-    </Select>
-  );
-}
-```
-
-### With Default Value
-
-Provide an initial value using the `defaultValue` prop for uncontrolled usage:
-
-```tsx
-<Select defaultValue='option1' onValueChange={(value) => console.log(value)}>
-  <SelectTrigger label='Choose an option'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-    <SelectItem value='option2'>
-      <SelectItemText>Option 2</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-```
-
-### Disabled State
-
-Use the `disabled` prop to prevent user interaction:
-
-```tsx
-// Disable entire select
-<Select value={value} onValueChange={setValue} disabled>
-  <SelectTrigger label='Choose an option'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-
-// Disable individual items
-<SelectContent>
-  <SelectItem value='option1'>
-    <SelectItemText>Option 1</SelectItemText>
-  </SelectItem>
-  <SelectItem value='option2' disabled>
-    <SelectItemText>Option 2 (Disabled)</SelectItemText>
-  </SelectItem>
-</SelectContent>
-```
-
-### With Custom Styling
-
-While the component comes with predefined styles, you can extend them using the `lx` prop:
-
-```tsx
-import { Box } from '@ledgerhq/lumen-ui-rnative';
-
-<Box lx={{ maxWidth: 's320' }}>
-  <Select value={value} onValueChange={setValue}>
-    <SelectTrigger label='Choose an option'>
-      <SelectValue />
-    </SelectTrigger>
-    <SelectContent>
-      <SelectItem value='option1'>
-        <SelectItemText>Option 1</SelectItemText>
-      </SelectItem>
-    </SelectContent>
-  </Select>
-</Box>
-```
-
-## Do's and Don'ts
-
-The following guidelines ensure consistent usage of the Select component and maintain design system principles.
-
-### Component Structure
-
-✅ **Do**
-
-```tsx
-// Always use the complete component structure
-<Select value={value} onValueChange={setValue}>
-  <SelectTrigger label='Choose option'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-
-// Use groups and labels for organized lists
-<Select value={value} onValueChange={setValue}>
-  <SelectTrigger label='Category'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectGroup>
-      <SelectLabel>Group Title</SelectLabel>
-      <SelectItem value='item1'>
-        <SelectItemText>Item 1</SelectItemText>
-      </SelectItem>
-    </SelectGroup>
-  </SelectContent>
-</Select>
-
-// Always wrap SelectItemText in SelectItem
-<SelectItem value='option1'>
-  <SelectItemText>Option 1</SelectItemText>
-</SelectItem>
-```
-
-❌ **Don't**
-
-```tsx
-// Don't omit SelectValue from SelectTrigger
-<SelectTrigger label='Choose option' />
-
-// Don't use raw text in SelectItem without SelectItemText
-<SelectItem value='option1'>Option 1</SelectItem>
-
-// Don't skip required components
-<Select value={value}>
-  <SelectTrigger label='Choose option' />
-</Select>
-```
-
-### Value Management
-
-✅ **Do**
-
-```tsx
-// Use controlled pattern with both value and onValueChange
-const [value, setValue] = useState('');
-<Select value={value} onValueChange={setValue}>
-  <SelectTrigger label='Option'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-
-// Or use uncontrolled pattern with defaultValue
-<Select defaultValue='option1' onValueChange={(value) => console.log(value)}>
-  <SelectTrigger label='Option'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-```
-
-❌ **Don't**
-
-```tsx
-// Don't mix controlled and uncontrolled patterns
-<Select value={value} defaultValue='option1' onValueChange={setValue}>
-  <SelectTrigger label='Option'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-
-// Don't forget onValueChange in controlled mode
-<Select value={value}>
-  <SelectTrigger label='Option'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-```
-
-### Layout and Styling
-
-The Select component takes the **full width** of its parent container by default. You can control the width using `lx` prop or wrapper containers:
-
-✅ **Do**
-
-```tsx
-// Preferred: Direct width control with lx
-<Select value={value} onValueChange={setValue}>
-  <SelectTrigger label='Option' lx={{ maxWidth: 's320' }}>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-
-// Use lx for margins and positioning
-<Select value={value} onValueChange={setValue}>
-  <SelectTrigger label='Option' lx={{ marginTop: 's16', marginHorizontal: 'auto' }}>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-
-// Alternative: Container wrapper
-<Box lx={{ maxWidth: 's320' }}>
-  <Select value={value} onValueChange={setValue}>
-    <SelectTrigger label='Option'>
-      <SelectValue />
-    </SelectTrigger>
-    <SelectContent>
-      <SelectItem value='option1'>
-        <SelectItemText>Option 1</SelectItemText>
-      </SelectItem>
-    </SelectContent>
-  </Select>
-</Box>
-```
-
-❌ **Don't**
-
-```tsx
-// Don't use style prop for token-based values (use lx instead)
-<SelectTrigger label='Option' style={{ maxWidth: 320 }}>
-  <SelectValue />
-</SelectTrigger>
-```
-
-### Accessibility and Labels
-
-✅ **Do**
-
-```tsx
-// Always provide labels
-<Select value={value} onValueChange={setValue}>
-  <SelectTrigger label='Choose category'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-
-// Labels automatically float when a value is selected
-<Select value={value} onValueChange={setValue}>
-  <SelectTrigger label='Important'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-```
-
-❌ **Don't**
-
-```tsx
-// Don't omit labels
-<Select value={value} onValueChange={setValue}>
-  <SelectTrigger>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>
-
-// Don't use style prop to modify core appearance
-<SelectTrigger label='Option' style={{ backgroundColor: 'red' }}>
-  <SelectValue />
-</SelectTrigger>
-```
-
-### Performance Considerations
-
-✅ **Do**
-
-```tsx
-// Use stable callbacks with useCallback
-const handleValueChange = useCallback((newValue: string) => {
-  setValue(newValue);
-}, []);
-
-<Select value={value} onValueChange={handleValueChange}>
-  <SelectTrigger label='Option'>
-    <SelectValue />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value='option1'>
-      <SelectItemText>Option 1</SelectItemText>
-    </SelectItem>
-  </SelectContent>
-</Select>;
-```
-
-❌ **Don't**
-
-```tsx
-// Don't create new functions in render for frequently re-rendered components
-<FlatList
-  data={items}
-  renderItem={({ item }) => (
-    <Select
-      value={item.value}
-      onValueChange={(value) => handleChange(item.id, value)}
-    >
-      <SelectTrigger label='Option'>
-        <SelectValue />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectItem value='option1'>
-          <SelectItemText>Option 1</SelectItemText>
-        </SelectItem>
-      </SelectContent>
-    </Select>
-  )}
-/>
-```
-
-## Platform Considerations
-
-### iOS Specific
-
-- Bottom sheet automatically adapts to iOS design guidelines
-- Respects iOS safe area insets
-- Supports iOS accessibility settings like Dynamic Type
-- Native-feeling bottom sheet animations
-
-### Android Specific
-
-- Supports Android back button to close bottom sheet
-- Handles Android system gestures appropriately
-- Respects Android accessibility services
-- Material Design-inspired animations
-
-### Cross-Platform
-
-- Consistent visual appearance across platforms
-- Platform-appropriate touch feedback
-- Unified API regardless of platform
-- Animated floating labels work seamlessly on both platforms
-
-</Tab>
-</CustomTabs>