@ledgerhq/lumen-ui-rnative 0.0.42

package/src/lib/Components/Button/Button.mdx

@@ -0,0 +1,363 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as ButtonStories from './Button.stories';
+import { Button } from './Button';
+import { CustomTabs, Tab } from '../../../../.storybook/components';
+import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
+import CommonRulesDoAndDont from '../../../../.storybook/docs/CommonRulesDoAndDont.mdx';
+
+<Meta title='Action/Button' of={ButtonStories} />
+
+# 🔘 Button
+
+<CustomTabs>
+  <Tab label="Overview ">
+
+## Introduction
+
+Buttons are key interactive elements that trigger actions and guide users through the interface. They come in various styles and states to reflect hierarchy, intent, and context. This React Native implementation ensures consistent behavior across mobile platforms while maintaining design system coherence.
+
+> View in [Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=9-28&m=dev).
+
+## Anatomy
+
+<Canvas of={ButtonStories.IconText} />
+
+- **Label**: describes the action that occurs when the button is tapped
+- **Icon (optional)**: visually communicate the button's action, and helps draw attention
+
+## Properties
+
+### Overview
+
+<Canvas of={ButtonStories.Base} />
+<Controls of={ButtonStories.Base} />
+
+### Appearance
+
+There are six button appearances, which indicate its emphasis. From strongest to weakest:
+
+- accent
+- base (default)
+- gray
+- transparent
+- no-background
+- red
+
+<Canvas of={ButtonStories.AppearanceShowcase} />
+
+### Content
+
+Buttons' contents can be of two types:
+
+- text (default)
+- icon-text
+
+> Note: For `icon-only` buttons, use the [IconButton](https://ldls.vercel.app/?path=/docs/action-iconbutton--docs) component instead. It's specifically designed for icon-only interactions with proper accessibility support.
+
+<Canvas of={ButtonStories.ContentTypesShowcase} />
+
+### Size
+
+Buttons come in four different sizes:
+
+- S (**40 px** tall)
+- M (default, **48 px** tall)
+- L (**56 px** tall)
+
+> Note: For XS size (32 px tall), use the [IconButton](/docs/action-iconbutton--docs) component instead.
+
+<Canvas of={ButtonStories.SizesShowcase} />
+
+> **⚠️ Important**: Icon sizes are automatically managed by the Button component based on the selected size. Never override the icon size using className or style props, as this will break the visual consistency of the design system. The Button component ensures proper scaling and alignment of icons across all sizes.
+>
+> ```tsx
+> // ✅ Correct: Let Button handle icon sizing
+> <Button size="sm" icon={Settings} accessibilityLabel="Settings">Settings</Button>
+>
+> // ❌ Wrong: Don't override icon size [it's not gonna work even if you try]
+> <Button size="sm" icon={Settings} className="w-6 h-6" accessibilityLabel="Settings">Settings</Button>
+> ```
+
+### States
+
+<Canvas of={ButtonStories.StatesShowcase} />
+
+## Responsive Layout
+
+Buttons dynamically adapt their width to the size of their content, while keeping the default paddings:
+
+<Canvas of={ButtonStories.ResponsiveLayout} />
+
+When a label is too long, it's truncated to 2 lines, with a maximum width of the button's container:
+
+<Canvas of={ButtonStories.ResponsiveLayout2} />
+
+> The Button must dynamically resize to its container constraints.
+
+## Accessibility
+
+To be implemented:
+
+- Color contrast
+- Text zoom
+- Touch target sizing (minimum 44px)
+- Screen reader compatibility
+- Semantic labeling
+
+### Interactive States
+
+<Canvas of={ButtonStories.InteractiveLoadingStates} />
+
+</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 { Button } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  return (
+    <Button size='md' appearance='base' onPress={() => console.log('Pressed!')}>
+      Click me
+    </Button>
+  );
+}
+```
+
+### Custom Styling
+
+While the component comes with predefined styles, you can extend them using NativeWind classes:
+
+```tsx
+<Button
+  size='md'
+  appearance='base'
+  className='mt-4' // Custom margin top
+  onPress={() => {}}
+>
+  Custom Button
+</Button>
+```
+
+### With Icons
+
+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='md' appearance='base' icon={ArrowRight} onPress={() => {}}>
+      Continue
+    </Button>
+  );
+}
+```
+
+### Full Width
+
+Use the `isFull` prop to make the button take the full width of its container:
+
+```tsx
+<Button size='md' appearance='base' isFull onPress={() => {}}>
+  Full Width Button
+</Button>
+```
+
+### Loading State
+
+Use the `loading` prop to show a spinner and disable interaction:
+
+```tsx
+<Button
+  size='md'
+  appearance='base'
+  loading={isLoading}
+  disabled={isLoading}
+  onPress={() => {}}
+>
+  {isLoading ? 'Loading...' : 'Submit'}
+</Button>
+```
+
+### Pressable Integration
+
+The Button component is built on React Native's `Pressable` and accepts all its props:
+
+```tsx
+<Button
+  size='md'
+  appearance='base'
+  onPress={() => console.log('Pressed!')}
+  onPressIn={() => console.log('Press started')}
+  onPressOut={() => console.log('Press ended')}
+  disabled={false}
+>
+  Interactive Button
+</Button>
+```
+
+## Do's and Don'ts
+
+The following guidelines are based on our [Button Component API Design ADR](https://ledgerhq.atlassian.net/wiki/spaces/DLS/pages/6003949581/ADR-001+Button+Component+API+Design). These decisions were made to ensure consistency, maintainability, and proper implementation of our design system principles.
+
+<div className='flex flex-col gap-24'>
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use icon prop'
+      description='Pass icon as a component reference for proper sizing and alignment'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { Plus } from '@ledgerhq/lumen-ui-rnative/symbols';
+
+<Button icon={Plus} onPress={() => {}}>
+  Add Item
+</Button>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't include icon in children"
+      description='Avoid placing icons inside children as this breaks automatic sizing'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { Plus } from '@ledgerhq/lumen-ui-rnative/symbols';
+
+<Button onPress={() => {}}>
+  <Plus /> Add Item
+</Button>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Let Button handle icon sizing'
+      description='Icon size adjusts automatically based on button size'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { Settings } from '@ledgerhq/lumen-ui-rnative/symbols';
+
+<Button icon={Settings} size='sm' onPress={() => {}}>
+  Settings
+</Button>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't modify icon size directly"
+      description='Avoid overriding icon dimensions in children'
+    >
+
+{/* prettier-ignore */}
+```tsx
+import { Settings } from '@ledgerhq/lumen-ui-rnative/symbols';
+
+<Button size='sm' onPress={() => {}}>
+  <Settings size={24} /> Settings
+</Button>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use isFull for width'
+      description='Use the isFull prop for full-width buttons'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Button isFull onPress={() => {}}>
+  Full Width
+</Button>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't use className for width"
+      description='Avoid using className to control button width'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Button className='w-full' onPress={() => {}}>
+  Full Width
+</Button>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Provide proper onPress handlers'
+      description='Always provide an onPress handler for interactive buttons'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Button onPress={() => navigation.navigate('Details')}>
+  View Details
+</Button>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't omit onPress"
+      description='Avoid creating buttons without onPress handlers'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Button>
+  Clickable Looking Button
+</Button>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <CommonRulesDoAndDont />
+</div>
+
+## Platform Considerations
+
+### iOS Specific
+
+- Buttons automatically adapt to iOS design guidelines
+- Touch feedback uses appropriate opacity transitions
+- Respects iOS accessibility settings like reduced motion
+
+### Android Specific
+
+- Material Design touch ripples are supported through React Native
+- Handles Android back button interactions appropriately
+- Respects Android accessibility services
+
+### Cross-Platform
+
+- Consistent visual appearance across platforms
+- Platform-appropriate touch feedback
+- Unified API regardless of platform
+
+</Tab>
+</CustomTabs>

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

@@ -0,0 +1,267 @@
+import type { Meta, StoryObj } from '@storybook/react-native-web-vite';
+import React from 'react';
+import { Plus, Settings } from '../../Symbols';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  title: 'Action/Button',
+  parameters: {
+    docs: {
+      source: {
+        language: 'tsx',
+        format: true,
+        type: 'code',
+      },
+    },
+  },
+  argTypes: {
+    appearance: {
+      control: 'select',
+      options: [
+        'base',
+        'gray',
+        'accent',
+        'transparent',
+        'no-background',
+        'red',
+      ],
+      description: 'The visual style appearance of the button',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'The size of the button',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the button is disabled',
+    },
+    loading: {
+      control: 'boolean',
+      description: 'Whether the button is in loading state',
+    },
+    icon: {
+      control: 'select',
+      description: 'Optional icon component to display',
+      options: ['None', 'Plus', 'Settings'],
+      mapping: {
+        None: undefined,
+        Plus: Plus,
+        Settings: Settings,
+      },
+    },
+    children: {
+      control: 'text',
+      description: 'The content to be displayed inside the button',
+    },
+    isFull: {
+      control: 'boolean',
+      description: 'Whether the button is full width',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+type ButtonAppearance =
+  | 'base'
+  | 'gray'
+  | 'accent'
+  | 'transparent'
+  | 'no-background'
+  | 'red';
+
+export const Base: Story = {
+  args: {
+    appearance: 'base',
+    children: 'Base Button',
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `
+<Button appearance="base">
+  Base Button
+</Button>
+`,
+      },
+    },
+  },
+};
+
+export const IconText: Story = {
+  args: {
+    appearance: 'base',
+    children: 'Add Item',
+    icon: Plus,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `
+<Button
+  appearance="base"
+  icon={Plus}
+>
+  Add Item
+</Button>
+`,
+      },
+    },
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    appearance: 'base',
+    children: 'Loading...',
+    loading: true,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `
+<Button
+  appearance="base"
+  loading
+>
+  Loading...
+</Button>
+`,
+      },
+    },
+  },
+};
+
+export const AppearanceShowcase: Story = {
+  render: () => {
+    const appearances: Array<{ name: string; appearance: ButtonAppearance }> = [
+      { name: 'Accent', appearance: 'accent' },
+      { name: 'Base', appearance: 'base' },
+      { name: 'Gray', appearance: 'gray' },
+      { name: 'Transparent', appearance: 'transparent' },
+      { name: 'No Background', appearance: 'no-background' },
+      { name: 'Red', appearance: 'red' },
+    ];
+
+    return (
+      <div className='flex gap-16 p-8'>
+        {appearances.map(({ name, appearance }) => (
+          <Button key={appearance} appearance={appearance}>
+            {name}
+          </Button>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const ContentTypesShowcase: Story = {
+  render: () => (
+    <div className='flex items-center gap-4'>
+      <Button appearance='base'>Text Only</Button>
+      <Button appearance='base' icon={Plus}>
+        With Icon
+      </Button>
+    </div>
+  ),
+};
+
+export const SizesShowcase: Story = {
+  render: () => (
+    <div className='flex items-center gap-4'>
+      <Button appearance='base' size='sm'>
+        Small
+      </Button>
+      <Button appearance='base' size='md'>
+        Medium
+      </Button>
+      <Button appearance='base' size='lg' icon={Settings}>
+        Large
+      </Button>
+    </div>
+  ),
+};
+
+export const StatesShowcase: Story = {
+  render: () => (
+    <div className='flex items-center gap-4'>
+      <Button appearance='base'>Default</Button>
+      <Button appearance='base' disabled>
+        Disabled
+      </Button>
+      <Button appearance='base' loading>
+        Loading
+      </Button>
+    </div>
+  ),
+};
+
+export const ResponsiveLayout: Story = {
+  render: () => (
+    <div className='flex flex-col gap-8 p-8'>
+      <Button appearance='base'>Short</Button>
+      <Button appearance='base'>Medium length button</Button>
+      <Button appearance='base' icon={Plus}>
+        This is a longer button text to show dynamic width
+      </Button>
+    </div>
+  ),
+};
+
+export const ResponsiveLayout2: Story = {
+  render: () => (
+    <>
+      <p className='text-muted body-4-semi-bold'>
+        This container has a fixed width.
+      </p>
+      <div className='w-400 bg-muted-pressed p-16'>
+        <Button icon={Plus}>
+          This Base button has a fixed width container that should fit the
+          content width.
+        </Button>
+      </div>
+    </>
+  ),
+};
+
+export const InteractiveLoadingStates: Story = {
+  render: () => {
+    const [states, setStates] = React.useState<
+      Record<'text' | 'withIcon' | 'iconOnly', 'idle' | 'loading' | 'red'>
+    >({
+      text: 'idle',
+      withIcon: 'idle',
+      iconOnly: 'idle',
+    });
+
+    const handleClick = async (key: keyof typeof states) => {
+      setStates((prev) => ({ ...prev, [key]: 'loading' }));
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      setStates((prev) => ({ ...prev, [key]: 'red' }));
+      setTimeout(() => setStates((prev) => ({ ...prev, [key]: 'idle' })), 2000);
+    };
+
+    return (
+      <div className='flex items-center gap-4'>
+        <Button
+          appearance='red'
+          loading={states.text === 'loading'}
+          onPress={() => handleClick('text')}
+        >
+          {states.text === 'red' ? 'Error!' : 'Text Only'}
+        </Button>
+
+        <Button
+          appearance='base'
+          loading={states.withIcon === 'loading'}
+          onPress={() => handleClick('withIcon')}
+          icon={Settings}
+        >
+          {states.withIcon === 'red' ? 'Settings Error!' : 'With Icon'}
+        </Button>
+      </div>
+    );
+  },
+};

package/src/lib/Components/Button/Button.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { Pressable } from 'react-native';
+import { BaseButton } from './BaseButton';
+import { BaseButtonProps } from './BaseButton.types';
+
+export type ButtonProps = {
+  /**
+   * The content to display inside the button.
+   */
+  children: React.ReactNode;
+} & BaseButtonProps;
+
+/**
+ * A customizable button component that supports various appearances, sizes, full-width mode, loading states, and optional icons.
+ *
+ * When in loading state, it displays a spinner. If an icon is provided without children, it renders as an icon-only button.
+ *
+ * @see {@link https://ldls.vercel.app/?path=/docs/react-native_action-button--docs Storybook}
+ * @see {@link https://ldls.vercel.app/?path=/docs/react-native_action-button--docs#dos-and-donts Guidelines}
+ *
+ * @example
+ * // Basic primary button
+ * import { Button } from '@ledgerhq/lumen-ui-rnative';
+ *
+ * <Button appearance="base" size="md" onPress={() => console.log('Clicked!')}>
+ *   Click Me
+ * </Button>
+ *
+ * // Full-width button with custom class
+ * <Button appearance="accent" isFull={true} className="my-custom-class">
+ *   Submit
+ * </Button>
+ */
+export const Button = React.forwardRef<
+  React.ElementRef<typeof Pressable>,
+  ButtonProps
+>((props, ref) => {
+  return <BaseButton ref={ref} {...props} />;
+});
+Button.displayName = 'Button';

package/src/lib/Components/Button/index.ts

@@ -0,0 +1,2 @@
+export * from './Button';
+export * from './BaseButton.types';