@ledgerhq/lumen-ui-rnative 0.1.7 → 0.1.9

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

@@ -0,0 +1,438 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as BannerStories from './Banner.stories';
+import { Banner } from './Banner';
+import { Box } from '../Utility';
+import { CustomTabs, Tab } from '../../../../.storybook/components';
+import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
+import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
+
+<Meta title='Components/Banner' of={BannerStories} />
+
+# 🃏 Banner
+
+<CustomTabs>
+  <Tab label="Overview">
+
+## Introduction
+
+Banners are prominent message containers used to communicate system status, alerts, or informational notices to users. They support different appearance types to indicate the severity or type of message and can include optional descriptions, action buttons, and a dismissal option.
+
+> View in [Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=85-227&p=f&m=dev).
+
+## Anatomy
+
+<Canvas of={BannerStories.WithFullFeatures} />
+
+- **Icon**: Automatically displays based on appearance (info, success, warning, error)
+- **Title**: The main message or heading (required)
+- **Description (optional)**: Additional details or explanation
+- **Actions (optional)**: Primary and/or secondary buttons for user interaction. Pass Button components as React nodes (e.g. `primaryAction={<Button appearance="transparent" size="sm" onPress={() => {}}>Action</Button>}`).
+- **Close (optional)**: Button to dismiss the banner. Use the `onClose` prop with a callback function and optionally `closeAriaLabel` for accessibility.
+
+## Properties
+
+### Overview
+
+<Canvas of={BannerStories.Base} />
+<Controls of={BannerStories.Base} />
+
+### Appearance
+
+Banners have four appearances to convey different types of messages:
+
+- **info** (default): General information
+- **success**: Positive outcomes or confirmations
+- **warning**: Caution or important notices
+- **error**: Problems or failures
+
+<Canvas of={BannerStories.AppearanceShowcase} />
+
+### Content Variations
+
+Banners support various content configurations:
+
+- **Title only**: Basic message
+- **Title + Description**: Detailed information
+- **With Actions**: Includes primary and/or secondary buttons
+- **With Close**: Dismissible banner
+- **Complete**: All elements combined
+
+<Canvas of={BannerStories.ContentVariations} />
+
+> **Note**: The title is required. Description, actions, and close are optional and can be combined as needed. Actions should be passed as Button components with their own styling and click handlers.
+
+### Width Behavior
+
+Banners naturally flow within their containers and take the full width by default:
+
+<Canvas of={BannerStories.NaturalWidth} />
+
+### Responsive Layout
+
+Banners adapt to their container constraints:
+
+<Canvas of={BannerStories.ResponsiveLayout} />
+
+> **Key behaviors:**
+>
+> - Banners flow naturally to fill their parent container width
+> - Container elements control the banner width, not the banner itself
+> - Title limited to 2 lines, description to 5 lines with truncation
+> - Icons and buttons maintain consistent sizing
+
+## Accessibility
+
+To be implemented:
+
+- **Color contrast**: Ensure readable text on all background colors
+- **Text zoom**: Maintain layout integrity
+- **Keyboard navigation**: Tab order for actions and close
+- **Semantic labeling**: Proper ARIA roles for alerts
+- **Focus management**: Visible focus indicators on interactive elements
+
+</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 { Banner } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  return (
+    <Banner
+      title='Information'
+      description='This is an informational message for the user'
+      appearance='info'
+    />
+  );
+}
+```
+
+### Banner Appearances
+
+The Banner component supports four different appearances, each with its own semantic meaning and visual styling:
+
+```tsx
+import { Banner, Box } from '@ledgerhq/lumen-ui-rnative';
+
+function NotificationSystem() {
+  return (
+    <Box lx={{ flexDirection: 'column', gap: 's16' }}>
+      {/* Info - Default informational messages */}
+      <Banner
+        appearance='info'
+        title='Information'
+        description='General information or tips'
+      />
+
+      {/* Success - Positive feedback or completion */}
+      <Banner
+        appearance='success'
+        title='Success'
+        description='Action completed successfully'
+      />
+
+      {/* Warning - Caution or important notices */}
+      <Banner
+        appearance='warning'
+        title='Warning'
+        description='Please review this important information'
+      />
+
+      {/* Error - Error states or critical issues */}
+      <Banner
+        appearance='error'
+        title='Error'
+        description='Something went wrong, please try again'
+      />
+    </Box>
+  );
+}
+```
+
+### With Action Buttons
+
+Banners can include primary and secondary action buttons to allow user interaction:
+
+```tsx
+import { Banner, Button } from '@ledgerhq/lumen-ui-rnative';
+
+function ActionableBanner() {
+  const handleAccept = () => {
+    console.log('User accepted');
+  };
+
+  const handleDecline = () => {
+    console.log('User declined');
+  };
+
+  return (
+    <Banner
+      appearance='warning'
+      title='Terms of Service Updated'
+      description='Please review and accept the updated terms of service to continue using our platform'
+      primaryAction={
+        <Button appearance='transparent' size='sm' onPress={handleAccept}>
+          Accept
+        </Button>
+      }
+      secondaryAction={
+        <Button appearance='no-background' size='sm' onPress={handleDecline}>
+          Review Later
+        </Button>
+      }
+    />
+  );
+}
+```
+
+### Dismissible Banner
+
+Add a close button to make banners dismissible by the user:
+
+```tsx
+import { Banner } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+function DismissibleBanner() {
+  const [isVisible, setIsVisible] = useState(true);
+
+  if (!isVisible) return null;
+
+  return (
+    <Banner
+      appearance='info'
+      title='Welcome!'
+      description='Thanks for joining our platform. Here are some tips to get started.'
+      onClose={() => setIsVisible(false)}
+      closeAriaLabel='Close welcome banner'
+    />
+  );
+}
+```
+
+### Natural Width Behavior
+
+Banners automatically flow to fill their parent container width. No additional props are needed:
+
+```tsx
+<Banner
+  title='System Maintenance'
+  description='Scheduled maintenance will occur tonight from 2:00 AM to 4:00 AM EST'
+  appearance='warning'
+  onClose={() => handleDismiss()}
+  closeAriaLabel='Dismiss'
+/>
+```
+
+To control banner width, use container elements with the `lx` prop:
+
+```tsx
+import { Banner, Box } from '@ledgerhq/lumen-ui-rnative';
+
+{/* Full viewport width */}
+<Banner
+  title='Full Width'
+  description='This banner fills the viewport width'
+/>
+
+{/* Constrained width */}
+<Box lx={{ maxWidth: 's400' }}>
+  <Banner
+    title='Constrained'
+    description='This banner is limited by its container'
+  />
+</Box>
+
+{/* With margin */}
+<Banner
+  title='With Layout Adjustment'
+  description='Use lx prop for layout adjustments'
+  lx={{ marginTop: 's16' }}
+/>
+```
+
+### Complete Example
+
+Here's a comprehensive example showing all Banner features:
+
+```tsx
+import { Banner, Button, Box } from '@ledgerhq/lumen-ui-rnative';
+import { useState } from 'react';
+
+function NotificationCenter() {
+  const [notifications, setNotifications] = useState([
+    {
+      id: '1',
+      type: 'success',
+      title: 'Payment Processed',
+      description: 'Your payment of $299.99 has been successfully processed.',
+      dismissible: true,
+    },
+    {
+      id: '2',
+      type: 'warning',
+      title: 'Verification Required',
+      description:
+        'Please verify your email address to continue using all features.',
+      dismissible: true,
+      actions: true,
+    },
+  ]);
+
+  const dismissNotification = (id: string) => {
+    setNotifications((prev) => prev.filter((n) => n.id !== id));
+  };
+
+  const handleVerify = () => {
+    console.log('Redirecting to verification...');
+  };
+
+  const handleLater = () => {
+    console.log('Remind me later');
+  };
+
+  return (
+    <Box lx={{ flexDirection: 'column', gap: 's16' }}>
+      {notifications.map((notification) => (
+        <Banner
+          key={notification.id}
+          appearance={notification.type as any}
+          title={notification.title}
+          description={notification.description}
+          onClose={
+            notification.dismissible
+              ? () => dismissNotification(notification.id)
+              : undefined
+          }
+          closeAriaLabel='Close notification'
+          primaryAction={
+            notification.actions ? (
+              <Button appearance='transparent' size='sm' onPress={handleVerify}>
+                Verify Now
+              </Button>
+            ) : undefined
+          }
+          secondaryAction={
+            notification.actions ? (
+              <Button
+                appearance='no-background'
+                size='sm'
+                onPress={handleLater}
+              >
+                Later
+              </Button>
+            ) : undefined
+          }
+        />
+      ))}
+    </Box>
+  );
+}
+```
+
+### Layout Adjustments with lx
+
+Use the `lx` prop for layout adjustments like margins or positioning:
+
+```tsx
+<Banner
+  title='With Margin'
+  description='This banner has a top margin'
+  lx={{ marginTop: 's16', marginBottom: 's8' }}
+  appearance='info'
+/>
+```
+
+## Do's and Don'ts
+
+The following guidelines ensure consistent usage of the Banner component and maintain design system principles.
+
+<Box lx={{ flexDirection: 'column', gap: 's16' }}>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Use lx for layout adjustments only'
+      description='Use the lx prop for margins, positioning, and other layout adjustments'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Banner
+  title='System Notice'
+  description='Maintenance scheduled for tonight'
+  lx={{ marginTop: 's16' }}
+  appearance='warning'
+/>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't use lx for appearance changes"
+      description='Avoid using lx to modify colors, padding, or other core appearance styles'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Banner
+  title='System Notice'
+  description='Maintenance scheduled for tonight'
+  lx={{ backgroundColor: 'accent', padding: 's24' }}
+  appearance='warning'
+/>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Pass complete Button components with proper styling'
+      description='Always provide fully styled Button components with appearance and size props for actions'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Banner
+  title='Confirm Action'
+  description='This action cannot be undone'
+  primaryAction={
+    <Button appearance='transparent' size='sm' onPress={handleConfirm}>
+      Confirm
+    </Button>
+  }
+  appearance='warning'
+/>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't pass incomplete or unstyled buttons"
+      description='Avoid passing Button components without proper appearance and size props'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Banner
+  title='Broken Action'
+  description="This won't work properly"
+  primaryAction={<Button onPress={handleSubmit}>Submit</Button>}
+  appearance='warning'
+/>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <CommonRulesDoAndDont />
+</Box>
+
+</Tab>
+</CustomTabs>