@adobe/react-native-aepmessaging 7.3.0 → 7.4.0

package/tutorials/ContentCardCustomizationGuide.md

@@ -0,0 +1,661 @@
+# Content Card Customization Guide
+
+## Overview
+
+The Adobe Experience Platform (AEP) React Native Messaging SDK provides a comprehensive and flexible content card system with multiple levels of customization. This guide explains how to customize content cards using the three-tier hierarchy: **Theme → Style Overrides → Props**.
+
+## Table of Contents
+
+1. [Customization Hierarchy](#customization-hierarchy)
+2. [Theme System](#theme-system)
+3. [Style Overrides](#style-overrides)
+4. [Component Props](#component-props)
+5. [Practical Example](#practical-example)
+6. [Best Practices](#best-practices)
+7. [Troubleshooting](#troubleshooting)
+
+## Customization Hierarchy
+
+The content card customization follows a clear hierarchy where each level can override the previous one:
+
+```
+Theme (Global) → Style Overrides (Component-specific) → Props (Element-specific)
+```
+
+### Priority Order (Highest to Lowest)
+1. **Props** - Most specific, overrides everything
+2. **Style Overrides** - Component-level customization
+3. **Theme** - Global application-wide styling
+4. **Default Styles** - Built-in component styles
+
+### How the Hierarchy Works
+
+Each level in the hierarchy can override properties from levels below it:
+
+```typescript
+// Example: Text color resolution
+const finalTextColor = 
+  titleProps?.style?.color ||           // 1. Props (highest priority)
+  styleOverrides?.title?.color ||       // 2. Style Overrides  
+  theme.colors.textPrimary ||           // 3. Theme
+  defaultStyles.title.color;            // 4. Default (lowest priority)
+```
+
+This means you can set a global brand color in your theme, override it for specific components with style overrides, and further customize individual elements with props when needed.
+
+## Theme System
+
+### Basic Theme Setup
+
+The theme system provides global styling for all content cards with automatic light/dark mode support.
+
+```typescript
+import { ThemeProvider, Themes } from '@adobe/react-native-aepmessaging';
+
+const customThemes: Themes = {
+  light: {
+    colors: {
+      primary: '#007AFF',        // Brand primary color
+      secondary: '#5856D6',      // Secondary accent color  
+      background: '#FFFFFF',     // Card background
+      textPrimary: '#000000',    // Main text color
+      textSecondary: '#8E8E93',  // Secondary text color
+      imagePlaceholder: '#C7C7CC', // Image loading placeholder
+      buttonTextColor: 'dodgerblue'   // Button text color
+    }
+  },
+  dark: {
+    colors: {
+      primary: '#0A84FF',
+      secondary: '#5E5CE6', 
+      background: '#262626',
+      textPrimary: '#FFFFFF',
+      textSecondary: '#8E8E93',
+      imagePlaceholder: '#48484A',
+      buttonTextColor: 'dodgerblue'
+    }
+  }
+};
+
+function App() {
+  return (
+    <ThemeProvider customThemes={customThemes}>
+      {/* Your app content */}
+    </ThemeProvider>
+  );
+}
+```
+
+### Available Theme Colors
+
+The following colors can be customized in your theme:
+
+| Color Property | Description | Usage |
+|----------------|-------------|--------|
+| `background` | Card background color | All card templates |
+| `textPrimary` | Main text content | Title and body text |
+| `imagePlaceholder` | Image loading state | Placeholder while images load |
+| `buttonTextColor` | Button text color | Action button text |
+
+**Example:**
+```typescript
+const myBrandTheme = {
+  light: {
+    colors: {
+      background: '#FFFFFF',
+      textPrimary: '#1A1A1A',
+      imagePlaceholder: '#E5E5E5',
+      buttonTextColor: '#007AFF'
+    }
+  }
+};
+```
+
+## Style Overrides
+
+Style overrides provide component-level customization for each template type. They follow React Native's `StyleSheet` patterns.
+
+### SmallImageCard Style Overrides
+
+```typescript
+import { SmallImageContentStyle } from '@adobe/react-native-aepmessaging';
+
+const smallImageStyleOverrides: SmallImageContentStyle = {
+  // Root card container
+  card: {
+    borderRadius: 16,
+    margin: 20,
+    backgroundColor: '#f8f9fa',
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+    elevation: 3
+  },
+  
+  // Inner container
+  container: {
+    padding: 16,
+    flexDirection: 'row'
+  },
+  
+  // Image container
+  imageContainer: {
+    borderRadius: 12,
+    overflow: 'hidden',
+    marginRight: 12
+  },
+  
+  // Image styling
+  image: {
+    width: 80,
+    height: 80
+  },
+  
+  // Content area
+  contentContainer: {
+    flex: 1,
+    justifyContent: 'space-between'
+  },
+  
+  // Text styling (applies to both title and body)
+  text: {
+    fontFamily: 'YourCustomFont-Regular'
+  },
+  
+  // Title-specific styling
+  title: {
+    fontSize: 18,
+    fontWeight: '700',
+    color: '#1a1a1a',
+    marginBottom: 4
+  },
+  
+  // Body text styling
+  body: {
+    fontSize: 14,
+    lineHeight: 20,
+    color: '#666666'
+  },
+  
+  // Button container
+  buttonContainer: {
+    flexDirection: 'row',
+    marginTop: 12,
+    gap: 8
+  },
+  
+  // Individual button styling
+  button: {
+    backgroundColor: '#007AFF',
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+    borderRadius: 8
+  },
+  
+  // Button text styling
+  buttonText: {
+    color: '#FFFFFF',
+    fontWeight: '600'
+  },
+  
+  // Dismiss button styling
+  dismissButton: {
+    backgroundColor: 'rgba(0,0,0,0.1)',
+    width: 24,
+    height: 24,
+    borderRadius: 12
+  }
+};
+```
+
+### LargeImageCard Style Overrides
+
+```typescript
+import { LargeImageContentStyle } from '@adobe/react-native-aepmessaging';
+
+const largeImageStyleOverrides: LargeImageContentStyle = {
+  // Root card container
+  card: {
+    borderRadius: 20,
+    margin: 16,
+    backgroundColor: '#ffffff',
+    overflow: 'hidden'
+  },
+  
+  // Main container
+  container: {
+    flexDirection: 'column'
+  },
+  
+  // Image container (top section)
+  imageContainer: {
+    height: 200,
+    position: 'relative'
+  },
+  
+  // Image styling
+  image: {
+    width: '100%',
+    height: '100%',
+    resizeMode: 'cover'
+  },
+  
+  // Content area (below image)
+  contentContainer: {
+    padding: 20
+  },
+  
+  // Text content wrapper
+  textContent: {
+    marginBottom: 16
+  },
+  
+  // Title styling
+  title: {
+    fontSize: 24,
+    fontWeight: '800',
+    color: '#1a1a1a',
+    marginBottom: 8
+  },
+  
+  // Body text styling
+  body: {
+    fontSize: 16,
+    lineHeight: 24,
+    color: '#4a4a4a'
+  },
+  
+  // Button container
+  buttonContainer: {
+    flexDirection: 'row',
+    justifyContent: 'space-between'
+  },
+  
+  // Button styling
+  button: {
+    flex: 1,
+    backgroundColor: '#007AFF',
+    paddingVertical: 12,
+    borderRadius: 12,
+    marginHorizontal: 4
+  },
+  
+  // Button text
+  buttonText: {
+    color: '#FFFFFF',
+    fontSize: 16,
+    fontWeight: '600',
+    textAlign: 'center'
+  }
+};
+```
+
+### ImageOnlyCard Style Overrides
+
+```typescript
+import { ImageOnlyContentStyle } from '@adobe/react-native-aepmessaging';
+
+const imageOnlyStyleOverrides: ImageOnlyContentStyle = {
+  // Root card container
+  card: {
+    borderRadius: 16,
+    margin: 12,
+    overflow: 'hidden'
+  },
+  
+  // Image container
+  imageContainer: {
+    backgroundColor: '#f0f0f0',
+    position: 'relative'
+  },
+  
+  // Image styling
+  image: {
+    width: '100%',
+    height: 300,
+    resizeMode: 'cover'
+  },
+  
+  // Dismiss button (overlaid on image)
+  dismissButton: {
+    position: 'absolute',
+    top: 8,
+    right: 8,
+    backgroundColor: 'rgba(0,0,0,0.5)',
+    width: 28,
+    height: 28,
+    borderRadius: 14
+  }
+};
+```
+
+## Component Props
+
+For advanced customization, some components accept additional props that provide element-level control.
+
+### SmallImageCard Props
+
+The `SmallImageCard` component extends React Native's `PressableProps` and supports the following specific props:
+
+```typescript
+import { SmallImageCard } from '@adobe/react-native-aepmessaging';
+
+<SmallImageCard
+  content={contentData}
+  imageUri={imageUrl}
+  height={120}  // Optional: Custom height for the card
+  styleOverrides={smallImageStyleOverrides}
+  onPress={handlePress}
+  onDismiss={handleDismiss}
+  
+  // Standard PressableProps are also supported
+  accessibilityLabel="Product promotion card"
+  accessibilityRole="button"
+  accessibilityHint="Double tap to view product details"
+  disabled={false}
+  hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}
+  
+  // Custom style function for press states
+  style={({ pressed }) => [
+    baseCardStyle,
+    pressed && { opacity: 0.8 }
+  ]}
+/>
+```
+
+**Note**: `SmallImageCard` supports granular component props (like `ImageProps`, `TextProps`, `ButtonProps`) via the `ComponentOverrideProps` interface, similar to `LargeImageCard` and `ImageOnlyCard`. You can use both these props and `styleOverrides` for comprehensive customization.
+
+#### SmallImageCard Advanced Props Example
+
+```typescript
+import { SmallImageCard } from '@adobe/react-native-aepmessaging';
+
+<SmallImageCard
+  content={contentData}
+  imageUri={imageUrl}
+  height={120}
+  styleOverrides={smallImageStyleOverrides}
+  onPress={handlePress}
+  onDismiss={handleDismiss}
+  
+  // Advanced component props
+  ContainerProps={{
+    accessibilityLabel: 'Product promotion card'
+  }}
+  
+  ImageContainerProps={{
+    accessibilityRole: 'image'
+  }}
+  
+  ImageProps={{
+    accessibilityLabel: 'Product image',
+    resizeMode: 'cover'
+  }}
+  
+  TextProps={{
+    accessibilityRole: 'text',
+    maxFontSizeMultiplier: 1.2
+  }}
+  
+  TitleProps={{
+    numberOfLines: 1,
+    ellipsizeMode: 'tail'
+  }}
+  
+  BodyProps={{
+    numberOfLines: 2,
+    ellipsizeMode: 'tail'
+  }}
+  
+  ButtonContainerProps={{
+    accessibilityRole: 'button'
+  }}
+  
+  ButtonProps={{
+    accessibilityHint: 'Double tap to learn more'
+  }}
+  
+  DismissButtonProps={{
+    accessibilityLabel: 'Dismiss this card',
+    accessibilityHint: 'Double tap to close'
+  }}
+  
+  // Standard PressableProps are also supported
+  accessibilityLabel="Product promotion card"
+  accessibilityRole="button"
+  disabled={false}
+  hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}
+  
+  // Custom style function for press states
+  style={({ pressed }) => [
+    baseCardStyle,
+    pressed && { opacity: 0.8 }
+  ]}
+/>
+```
+
+### LargeImageCard Advanced Props
+
+```typescript
+import { LargeImageCard } from '@adobe/react-native-aepmessaging';
+
+<LargeImageCard
+  content={contentData}
+  imageUri={imageUrl}
+  styleOverrides={largeImageStyleOverrides}
+  onPress={handlePress}
+  onDismiss={handleDismiss}
+  
+  // Advanced component props
+  ContainerProps={{
+    accessibilityLabel: 'Product promotion card'
+  }}
+  
+  ImageContainerProps={{
+    accessibilityRole: 'image'
+  }}
+  
+  ImageProps={{
+    accessibilityLabel: 'Product image',
+    resizeMode: 'cover'
+  }}
+  
+  TextProps={{
+    accessibilityRole: 'text',
+    maxFontSizeMultiplier: 1.2
+  }}
+  
+  TitleProps={{
+    numberOfLines: 2,
+    ellipsizeMode: 'tail'
+  }}
+  
+  BodyProps={{
+    numberOfLines: 3,
+    ellipsizeMode: 'tail'
+  }}
+  
+  ButtonContainerProps={{
+    accessibilityRole: 'button'
+  }}
+  
+  ButtonProps={{
+    accessibilityHint: 'Double tap to learn more'
+  }}
+  
+  DismissButtonProps={{
+    accessibilityLabel: 'Dismiss this card',
+    accessibilityHint: 'Double tap to close'
+  }}
+/>
+```
+
+### ImageOnlyCard Advanced Props
+
+```typescript
+import { ImageOnlyCard } from '@adobe/react-native-aepmessaging';
+
+<ImageOnlyCard
+  content={contentData}
+  imageUri={imageUrl}
+  styleOverrides={imageOnlyStyleOverrides}
+  onPress={handlePress}
+  onDismiss={handleDismiss}
+  
+  // Advanced component props
+  ContainerProps={{
+    accessibilityLabel: 'Featured image card'
+  }}
+  
+  ImageContainerProps={{
+    accessibilityRole: 'image'
+  }}
+  
+  ImageProps={{
+    accessibilityLabel: 'Featured content image',
+    resizeMode: 'contain'
+  }}
+  
+  DismissButtonProps={{
+    accessibilityLabel: 'Close image',
+    accessibilityHint: 'Double tap to dismiss'
+  }}
+/>
+```
+
+## Practical Example
+
+### E-commerce Product Card
+
+```typescript
+import React from 'react';
+import { ContentCardView, ThemeProvider } from '@adobe/react-native-aepmessaging';
+
+// Custom theme for e-commerce
+const ecommerceTheme = {
+  light: {
+    colors: {
+      primary: '#FF6B35',
+      secondary: '#004E89', 
+      background: '#FFFFFF',
+      textPrimary: '#1A1A1A',
+      textSecondary: '#666666',
+      imagePlaceholder: '#E5E5E5',
+      buttonTextColor: '#FFFFFF'
+    }
+  },
+  dark: {
+    colors: {
+      primary: '#FF8A5B',
+      secondary: '#0066CC',
+      background: '#1A1A1A', 
+      textPrimary: '#FFFFFF',
+      textSecondary: '#CCCCCC',
+      imagePlaceholder: '#333333',
+      buttonTextColor: 'dodgerblue'
+    }
+  }
+};
+
+// Product card style overrides
+const productCardStyles = {
+  smallImageStyle: {
+    card: {
+      borderRadius: 12,
+      backgroundColor: '#FFFFFF',
+      borderWidth: 1,
+      borderColor: '#E0E0E0',
+      margin: 16,
+      shadowColor: '#000',
+      shadowOffset: { width: 0, height: 2 },
+      shadowOpacity: 0.1,
+      shadowRadius: 4,
+      elevation: 3
+    },
+    image: {
+      borderRadius: 8
+    },
+    title: {
+      fontSize: 16,
+      fontWeight: '600',
+      color: '#1A1A1A'
+    },
+    body: {
+      fontSize: 14,
+      color: '#666666',
+      marginTop: 4
+    },
+    button: {
+      backgroundColor: '#FF6B35',
+      paddingHorizontal: 20,
+      paddingVertical: 10,
+      borderRadius: 25
+    },
+    buttonText: {
+      color: '#FFFFFF',
+      fontWeight: '600',
+      fontSize: 14
+    }
+  }
+};
+
+function ProductCard({ template }) {
+  const handleInteraction = (event, data) => {
+    console.log('Product card interaction:', event, data);
+  };
+
+  return (
+    <ThemeProvider customThemes={ecommerceTheme}>
+      <ContentCardView
+        template={template}
+        styleOverrides={productCardStyles}
+        listener={handleInteraction}
+      />
+    </ThemeProvider>
+  );
+}
+```
+
+## Best Practices
+
+### 1. Hierarchy Best Practices
+```typescript
+// Good: Use hierarchy effectively
+const styles = {
+  card: {
+    // Base card styling
+    backgroundColor: theme.colors.background, // Theme value
+    padding: 16, // Component-specific override
+  }
+};
+
+// Good: Specific overrides
+<SmallImageCard 
+  styleOverrides={{
+    title: { fontSize: 18 }, // Override specific element
+    button: { backgroundColor: '#FF6B35' } // Brand-specific button color
+  }}
+/>
+
+// Avoid: Over-styling at theme level
+const badTheme = {
+  colors: {
+    buttonSpecificBackgroundForProductCards: '#FF6B35' // Too specific for theme
+  }
+};
+```
+
+### 2. Consistent Theming
+- Use the theme system for colors that should be consistent across all content cards
+- Always provide both light and dark theme variants
+- Test your themes in both color schemes
+
+### 3. Responsive Design
+- Use flexible layouts and relative sizing
+- Test on different screen sizes and orientations
+- Consider accessibility font scaling
+
+---
+
+This guide provides a comprehensive overview of the Content Card customization system. With the three-tier customization hierarchy (Theme → Style Overrides → Props), you can create beautiful, branded content cards that fit seamlessly into your app's design system.