@ledgerhq/lumen-ui-rnative 0.1.7 → 0.1.9

package/dist/module/lib/Components/AddressInput/AddressInput.mdx

@@ -0,0 +1,706 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as AddressInputStories from './AddressInput.stories';
+import { AddressInput } from './AddressInput';
+import { CustomTabs, Tab } from '../../../../.storybook/components';
+import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
+import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
+
+<Meta title='Input/AddressInput' of={AddressInputStories} />
+
+# ⌨️ AddressInput
+
+<CustomTabs>
+  <Tab label="Overview" path='Input/AddressInput'>
+
+## Introduction
+
+The AddressInput component provides a specialized input field for entering cryptocurrency addresses or ENS names. Built on top of BaseInput, it features a customizable prefix label (defaults to "To:") and context-aware suffix icons for an optimized mobile experience.
+
+> View in [Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=6375-6974&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={AddressInputStories.Base} />
+<Controls of={AddressInputStories.Base} />
+
+## Anatomy
+
+> **Layout:** The AddressInput component takes the full width of its container by default. You can control the width by using the `style` prop or by wrapping in a container.
+
+### Customizable Prefix
+
+The component displays "To:" as the default prefix text, but this can be customized via the `prefix` prop for different use cases like "From:", "Withdraw to:", etc.
+
+<Canvas of={AddressInputStories.WithCustomPrefix} />
+
+### QR Code Scanner
+
+When `onQrCodeClick` is provided, a QR code scanner icon appears when the input is empty, allowing users to scan addresses directly. Without `onQrCodeClick`, no QR code icon appears.
+
+<Canvas of={AddressInputStories.WithoutQrCode} />
+
+### Clear Button
+
+A clear button appears **automatically** when input has content, replacing the QR code scanner icon (if present).
+
+<Canvas of={AddressInputStories.WithContent} />
+
+> **Note:** The clear button only clears the input content/value. It does not clear error states - you must handle error state clearing separately in your component logic.
+
+#### **Hiding the Clear Button**
+
+Use `hideClearButton` to prevent the clear button from appearing.
+
+<Canvas of={AddressInputStories.WithHiddenClearButton} />
+
+### Error State
+
+The input supports error handling through `errorMessage` which displays an error message below the input with error styling including a red border and text color.
+
+<Canvas of={AddressInputStories.WithError} />
+
+The error message will be automatically:
+
+- Connected to the input
+- Displayed with a warning icon
+- Styled in the error color
+- Announced by screen readers
+
+### Disabled State
+
+The input can be disabled using the `editable` prop set to `false`.
+
+<Canvas of={AddressInputStories.DisabledAddressInput} />
+
+## Controlled vs Uncontrolled
+
+The AddressInput component supports both controlled and uncontrolled usage.
+
+### Uncontrolled (with defaultValue)
+
+Use defaultValue when you don't need to track the input's value in state. The component manages its own internal state.
+
+### Controlled (with value and onChangeText)
+
+Use `value` and `onChangeText` when you want full control of the input's state from your component logic.
+
+## Input Types
+
+The component supports various React Native TextInput content types:
+
+- default (text)
+- email-address
+- url
+
+Set these using the `keyboardType` prop.
+
+## Accessibility
+
+The AddressInput component follows accessibility best practices:
+
+- Supports screen reader navigation
+- Prefix labels are properly associated with inputs
+- Error messages are properly announced
+- QR code scanner button has an accessible label
+- Clear button has an accessible label
+- Touch target sizes meet minimum requirements (48px height)
+
+## Best Practices
+
+**Prefix**: Keep prefix text short and descriptive ("To:", "From:", etc.)
+
+**QR Code Scanner**: Always provide onQrCodeClick to enable easy address scanning
+
+**Error Messages**: Make error messages helpful and actionable (e.g., "Invalid address format")
+
+**Validation**: Validate on blur or submit, not on every keystroke
+
+**Clear Button**: Appears automatically when there's content - use hideClearButton only when necessary
+
+</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 { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [address, setAddress] = useState('');
+
+  return (
+    <AddressInput
+      placeholder='Enter address or ENS'
+      value={address}
+      onChangeText={setAddress}
+      onQrCodeClick={() => openQrScanner()}
+    />
+  );
+}
+```
+
+> **Note:** Clear button appears automatically when input has content. QR code scanner appears when input is empty (if onQrCodeClick is provided). Use `hideClearButton` to hide the clear button.
+
+### With Custom Prefix
+
+Customize the prefix text for different contexts:
+
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+// Default "To:" prefix
+<AddressInput
+  placeholder="Enter address or ENS"
+  value={address}
+  onChangeText={setAddress}
+/>
+
+// Custom "From:" prefix for sender address input
+<AddressInput
+  prefix="From:"
+  placeholder="Enter address or ENS"
+  value={address}
+  onChangeText={setAddress}
+/>
+
+// Custom prefix for other contexts
+<AddressInput
+  prefix="Withdraw to:"
+  placeholder="Enter withdrawal address"
+  value={address}
+  onChangeText={setAddress}
+/>
+```
+
+### Without QR Code Scanner
+
+When `onQrCodeClick` is not provided, no QR code icon appears:
+
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [address, setAddress] = useState('');
+
+  // No onQrCodeClick - no QR code scanner icon
+  return (
+    <AddressInput
+      placeholder='Enter address or ENS'
+      value={address}
+      onChangeText={setAddress}
+    />
+  );
+}
+```
+
+#### **Hiding the Clear Button**
+
+Use `hideClearButton` to prevent the clear button from appearing:
+
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [address, setAddress] = useState('');
+
+  return (
+    <AddressInput
+      placeholder='Enter address or ENS'
+      value={address}
+      onChangeText={setAddress}
+      onQrCodeClick={() => openQrScanner()}
+      hideClearButton // Clear button will not appear
+    />
+  );
+}
+```
+
+#### **Extending the Clear Behavior**
+
+Provide `onClear` to extend the default clear behavior with additional logic:
+
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [address, setAddress] = useState('');
+  const [error, setError] = useState('');
+
+  return (
+    <AddressInput
+      placeholder='Enter address or ENS'
+      value={address}
+      onChangeText={setAddress}
+      errorMessage={error}
+      onClear={() => {
+        // Default clearing happens automatically
+        // Add your custom logic here
+        setError(''); // Clear error state
+        analytics.track('address_cleared');
+      }}
+    />
+  );
+}
+```
+
+### With Error State
+
+The AddressInput component supports error states and messages:
+
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [address, setAddress] = useState('');
+  const [error, setError] = useState('');
+
+  const handleChange = (text: string) => {
+    setAddress(text);
+
+    if (text.length > 0) {
+      const isValidEthereumAddress =
+        text.startsWith('0x') && text.length === 42;
+      const isValidENS = text.endsWith('.eth');
+
+      if (!isValidEthereumAddress && !isValidENS) {
+        setError('Please enter a valid Ethereum address or ENS name');
+      } else {
+        setError('');
+      }
+    }
+  };
+
+  return (
+    <AddressInput
+      placeholder='Enter address or ENS'
+      value={address}
+      onChangeText={handleChange}
+      errorMessage={error}
+      onQrCodeClick={() => openQrScanner()}
+    />
+  );
+}
+```
+
+> **Note:** Error messages are optional. Use `errorMessage` to display an error message below the input.
+
+### With Custom Styling
+
+While the component comes with predefined styles, you can extend them using the `style` prop:
+
+```tsx
+<AddressInput
+  placeholder='Enter address or ENS'
+  value={address}
+  onChangeText={setAddress}
+  style={{ maxWidth: 320 }} // Control width
+  onQrCodeClick={() => openQrScanner()}
+/>
+```
+
+### With Different Keyboard Types
+
+Use the `keyboardType` prop to show the appropriate keyboard:
+
+```tsx
+// Default keyboard (recommended for addresses)
+<AddressInput
+  placeholder="Enter address or ENS"
+  value={address}
+  onChangeText={setAddress}
+  onQrCodeClick={() => openQrScanner()}
+/>
+
+// URL keyboard (alternative for ENS names)
+<AddressInput
+  placeholder="Enter ENS name"
+  value={address}
+  onChangeText={setAddress}
+  keyboardType="url"
+  onQrCodeClick={() => openQrScanner()}
+/>
+```
+
+### Disabled State
+
+Use the `editable` prop to disable the input:
+
+```tsx
+<AddressInput
+  placeholder='Enter address or ENS'
+  value='0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb27'
+  editable={false}
+/>
+```
+
+### QR Code Integration
+
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [address, setAddress] = useState('');
+  const [error, setError] = useState('');
+
+  const handleQrScan = async () => {
+    try {
+      // Open QR scanner modal/camera
+      const scannedAddress = await openQrScanner();
+      setAddress(scannedAddress);
+      validateAddress(scannedAddress);
+    } catch (error) {
+      console.error('QR scan failed:', error);
+      setError('Failed to scan QR code');
+    }
+  };
+
+  return (
+    <AddressInput
+      placeholder='Enter address or ENS'
+      value={address}
+      onChangeText={setAddress}
+      onQrCodeClick={handleQrScan}
+      errorMessage={error}
+    />
+  );
+}
+```
+
+## Common Patterns
+
+### Transaction Forms
+
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { View } from 'react-native';
+import { useState } from 'react';
+
+function TransactionForm() {
+  const [recipientAddress, setRecipientAddress] = useState('');
+  const [addressError, setAddressError] = useState('');
+
+  return (
+    <View>
+      <AddressInput
+        placeholder='Enter address or ENS'
+        value={recipientAddress}
+        onChangeText={setRecipientAddress}
+        errorMessage={addressError}
+        onQrCodeClick={() => openQrScanner()}
+        style={{ maxWidth: 320 }}
+      />
+      {/* Other transaction fields */}
+    </View>
+  );
+}
+```
+
+### Sender and Recipient Addresses
+
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { View } from 'react-native';
+import { useState } from 'react';
+
+function AddressForm() {
+  const [fromAddress, setFromAddress] = useState('');
+  const [toAddress, setToAddress] = useState('');
+
+  return (
+    <View>
+      <AddressInput
+        prefix='From:'
+        placeholder='Enter sender address'
+        value={fromAddress}
+        onChangeText={setFromAddress}
+        onQrCodeClick={() => openQrScanner('from')}
+      />
+
+      <AddressInput
+        prefix='To:'
+        placeholder='Enter recipient address'
+        value={toAddress}
+        onChangeText={setToAddress}
+        onQrCodeClick={() => openQrScanner('to')}
+      />
+    </View>
+  );
+}
+```
+
+## Do's and Don'ts
+
+<div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use controlled input pattern'
+      description='Use value and onChangeText props for controlled input state management'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+const [address, setAddress] = useState('');
+
+<AddressInput
+  placeholder='Enter address or ENS'
+  value={address}
+  onChangeText={setAddress}
+  onQrCodeClick={() => openQrScanner()}
+/>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't mix controlled and uncontrolled patterns"
+      description='Avoid using both value and defaultValue props together'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+const [address, setAddress] = useState('');
+
+<AddressInput
+  placeholder='Enter address or ENS'
+  value={address}
+  defaultValue='initial'
+  onChangeText={setAddress}
+/>
+```
+
+    </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
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+const [address, setAddress] = useState('');
+const [error, setError] = useState('');
+
+<AddressInput
+  placeholder='Enter address or ENS'
+  value={address}
+  onChangeText={setAddress}
+  onClear={() => {
+    // Default clearing happens automatically
+    setError(''); // Clear error state
+  }}
+/>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't manually clear value in onClear"
+      description='Value clearing happens automatically - no need to call setAddress'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+const [address, setAddress] = useState('');
+const [error, setError] = useState('');
+
+<AddressInput
+  placeholder='Enter address or ENS'
+  value={address}
+  onChangeText={setAddress}
+  onClear={() => setAddress('')}
+/>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use short, descriptive prefixes'
+      description='Keep prefix text concise - typically 1-3 words'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+
+<AddressInput
+  prefix='To:'
+  placeholder='Enter recipient'
+  value={address}
+  onChangeText={setAddress}
+/>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't use overly long prefixes"
+      description='Long prefixes take up too much space and reduce usability'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+
+<AddressInput
+  prefix="Please enter the recipient's wallet address:"
+  placeholder='Enter recipient'
+  value={address}
+  onChangeText={setAddress}
+/>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Always provide onQrCodeClick for QR scanning'
+      description='Enable QR code scanning to improve user experience'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+
+<AddressInput
+  placeholder='Enter address or ENS'
+  value={address}
+  onChangeText={setAddress}
+  onQrCodeClick={() => openQrScanner()}
+/>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't omit QR scanning capability"
+      description='Users should not have to manually type long addresses'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { AddressInput } from '@ledgerhq/lumen-ui-rnative';
+
+<AddressInput
+  placeholder='Enter address or ENS'
+  value={address}
+  onChangeText={setAddress}
+/>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <CommonRulesDoAndDont />
+</div>
+
+## Platform Considerations
+
+### iOS Specific
+
+- Input automatically adapts to iOS design guidelines
+- Keyboard automatically handles safe area insets
+- Respects iOS accessibility settings like Dynamic Type
+- QR code scanner integrates with iOS camera permissions
+
+### Android Specific
+
+- Supports Android keyboard types and input methods
+- Handles Android back button interactions appropriately
+- Respects Android accessibility services
+- QR code scanner integrates with Android camera permissions
+
+### Cross-Platform
+
+- Consistent visual appearance across platforms
+- Platform-appropriate keyboard behavior
+- Unified API regardless of platform
+- QR code scanner works seamlessly on both platforms
+- Context-aware suffix icons (QR code ↔ clear button) work consistently
+
+## Address Validation Best Practices
+
+### Ethereum Addresses
+
+```tsx
+const validateEthereumAddress = (address: string): boolean => {
+  // Basic validation
+  return address.startsWith('0x') && address.length === 42;
+};
+
+// In your component
+const handleChange = (text: string) => {
+  setAddress(text);
+
+  if (
+    text.length > 0 &&
+    !validateEthereumAddress(text) &&
+    !text.endsWith('.eth')
+  ) {
+    setError('Please enter a valid Ethereum address or ENS name');
+  } else {
+    setError('');
+  }
+};
+```
+
+### ENS Names
+
+```tsx
+const validateENS = (address: string): boolean => {
+  return address.endsWith('.eth') && address.length > 4;
+};
+```
+
+### Debounced Validation
+
+```tsx
+import { useCallback } from 'react';
+import { debounce } from 'lodash';
+
+const debouncedValidate = useCallback(
+  debounce((address: string) => {
+    validateAddress(address);
+  }, 500),
+  [],
+);
+
+<AddressInput
+  placeholder='Enter address or ENS'
+  value={address}
+  onChangeText={(text) => {
+    setAddress(text);
+    debouncedValidate(text);
+  }}
+/>;
+```
+
+</Tab>
+</CustomTabs>