@octopus-community/react-native 1.0.0 → 1.0.3

package/README.md

@@ -49,7 +49,18 @@ Due to a bug in XCode 15, you might need to set `ENABLE_USER_SCRIPT_SANDBOXING`
 
 ### Expo
 
-An expo plugin will be available shortly.
+Configure `use_frameworks` (static or dynamic) with `expo-build-properties`:
+
+```json
+[
+  "expo-build-properties",
+  {
+    "ios": {
+      "useFrameworks": "static"
+    }
+  }
+]
+```
 
 ## Usage
 
@@ -89,12 +100,23 @@ import {
   closeUI,
 } from '@octopus-community/react-native';
 
-// Initialize with SSO mode
+// Initialize with SSO mode and custom theme
 await initialize({
   apiKey: 'YOUR_OCTOPUS_API_KEY',
   connectionMode: {
     type: 'sso',
     appManagedFields: ['username', 'profilePicture', 'biography']
+  },
+  theme: {
+    colors: {
+      primary: '#FF6B35', // Your brand's primary color
+      primaryLowContrast: '#FF8C69', // Lighter variation
+      primaryHighContrast: '#CC4A1A', // Darker variation
+      onPrimary: '#FFFFFF', // Text color on primary background
+    },
+    logo: {
+      image: Image.resolveAssetSource(require('./assets/logo.png')), // Your custom logo
+    },
   }
 });
 
@@ -144,13 +166,296 @@ Show the Octopus home screen with the [`openUI()`](./docs/api/functions/openUI.m
 
 Future versions of this React Native module will let you show the UI in your React components. Please reach out if you need this prioritized.
 
+### Theme Customization
+
+The Octopus SDK provides comprehensive theming capabilities to match your app's branding. You can customize colors, fonts, and logo, with full support for both light and dark modes.
+
+#### Basic Theme Setup
+
+```ts
+import { Image } from 'react-native';
+
+await initialize({
+  apiKey: 'YOUR_OCTOPUS_API_KEY',
+  connectionMode: { type: 'octopus' },
+  theme: {
+    colors: {
+      primary: '#FF6B35', // Main brand color
+      primaryLowContrast: '#FF8C69', // Lighter variation of primary
+      primaryHighContrast: '#CC4A1A', // Darker variation for high contrast
+      onPrimary: '#FFFFFF', // Text color on primary background
+    },
+    logo: {
+      image: Image.resolveAssetSource(require('./assets/logo.png')),
+    },
+  }
+});
+```
+
+#### Dark/Light Mode Management
+
+The SDK automatically handles system appearance changes, but you can also force specific modes:
+
+##### System Mode (Default)
+```ts
+// The SDK automatically follows the system appearance
+// No additional configuration needed
+await initialize({
+  apiKey: 'YOUR_OCTOPUS_API_KEY',
+  connectionMode: { type: 'octopus' },
+  theme: { /* your theme */ }
+});
+```
+
+##### Forced Light Mode
+```ts
+import { Appearance } from 'react-native';
+
+// Force light mode for your entire app
+Appearance.setColorScheme('light');
+
+await initialize({
+  apiKey: 'YOUR_OCTOPUS_API_KEY',
+  connectionMode: { type: 'octopus' },
+  theme: { /* your theme */ }
+});
+```
+
+##### Forced Dark Mode
+```ts
+import { Appearance } from 'react-native';
+
+// Force dark mode for your entire app
+Appearance.setColorScheme('dark');
+
+await initialize({
+  apiKey: 'YOUR_OCTOPUS_API_KEY',
+  connectionMode: { type: 'octopus' },
+  theme: { /* your theme */ }
+});
+```
+
+#### Dual-Mode Color Themes
+
+For enhanced theming, you can provide separate color sets for light and dark modes:
+
+```ts
+await initialize({
+  apiKey: 'YOUR_OCTOPUS_API_KEY',
+  connectionMode: { type: 'octopus' },
+  theme: {
+    colors: {
+      light: {
+        primary: '#3B82F6', // Blue for light mode
+        primaryLowContrast: '#60A5FA',
+        primaryHighContrast: '#1D4ED8',
+        onPrimary: '#FFFFFF',
+      },
+      dark: {
+        primary: '#60A5FA', // Lighter blue for dark mode
+        primaryLowContrast: '#93C5FD',
+        primaryHighContrast: '#3B82F6',
+        onPrimary: '#000000',
+      },
+    },
+  }
+});
+```
+
+#### Font Customization
+
+Customize typography with text styles and font sizes:
+
+```ts
+await initialize({
+  apiKey: 'YOUR_OCTOPUS_API_KEY',
+  connectionMode: { type: 'octopus' },
+  theme: {
+    fonts: {
+      textStyles: {
+        title1: {
+          fontType: 'serif', // serif, monospace, or default
+          fontSize: { size: 28 }
+        },
+        title2: {
+          fontType: 'serif',
+          fontSize: { size: 22 }
+        },
+        body1: {
+          fontType: 'default', // Uses system default
+          fontSize: { size: 16 }
+        },
+        body2: {
+          fontSize: { size: 14 } // Only size, uses default font type
+        },
+        caption1: {
+          fontType: 'monospace',
+          fontSize: { size: 12 }
+        },
+        caption2: {
+          fontSize: { size: 10 }
+        },
+      }
+    }
+  }
+});
+```
+
+#### Theme Application
+
+Themes are applied when the Octopus UI is opened. The SDK automatically detects the current system appearance (light/dark mode) and applies the appropriate theme configuration.
+
+#### Complete Theme Example
+
+Here's a comprehensive example showing all theming options:
+
+```ts
+import { Image, Appearance } from 'react-native';
+import { initialize } from '@octopus-community/react-native';
+
+// Force dark mode (optional)
+Appearance.setColorScheme('dark');
+
+await initialize({
+  apiKey: 'YOUR_OCTOPUS_API_KEY',
+  connectionMode: {
+    type: 'sso',
+    appManagedFields: ['username', 'profilePicture']
+  },
+  theme: {
+    // Dual-mode colors
+    colors: {
+      light: {
+        primary: '#8B5CF6',
+        primaryLowContrast: '#A78BFA',
+        primaryHighContrast: '#7C3AED',
+        onPrimary: '#FFFFFF',
+      },
+      dark: {
+        primary: '#A78BFA',
+        primaryLowContrast: '#C4B5FD',
+        primaryHighContrast: '#8B5CF6',
+        onPrimary: '#000000',
+      },
+    },
+    // Custom fonts
+    fonts: {
+      textStyles: {
+        title1: { fontType: 'serif', fontSize: { size: 28 } },
+        title2: { fontType: 'serif', fontSize: { size: 22 } },
+        body1: { fontSize: { size: 16 } },
+        body2: { fontSize: { size: 14 } },
+        caption1: { fontType: 'monospace', fontSize: { size: 12 } },
+        caption2: { fontSize: { size: 10 } },
+      }
+    },
+    // Custom logo
+    logo: {
+      image: Image.resolveAssetSource(require('./assets/logo.png')),
+    },
+  }
+});
+```
+
+#### Dynamic Theme Switching
+
+To change themes in your app, you need to re-initialize the SDK with the new theme configuration:
+
+```ts
+// Example: Switch between different theme sets
+const switchToGreenTheme = async () => {
+  await initialize({
+    apiKey: 'YOUR_OCTOPUS_API_KEY',
+    connectionMode: { type: 'sso', appManagedFields: ['username'] },
+    theme: {
+      colors: {
+        light: {
+          primary: '#10B981',
+          primaryLowContrast: '#34D399',
+          primaryHighContrast: '#059669',
+          onPrimary: '#FFFFFF',
+        },
+        dark: {
+          primary: '#34D399',
+          primaryLowContrast: '#6EE7B7',
+          primaryHighContrast: '#10B981',
+          onPrimary: '#000000',
+        },
+      }
+    }
+  });
+};
+```
+
+#### Theme Configuration Reference
+
+**Color Properties:**
+- `primary`: Main brand color (hex format: `#FF6B35` or `FF6B35`)
+- `primaryLowContrast`: Lighter variation for subtle elements
+- `primaryHighContrast`: Darker variation for high contrast needs
+- `onPrimary`: Text color displayed over primary background
+
+**Font Types:**
+- `default`: System default font
+- `serif`: Serif font family
+- `monospace`: Monospace font family
+
+**Text Styles:**
+- `title1`: Large titles (default: 28pt)
+- `title2`: Medium titles (default: 22pt)
+- `body1`: Primary body text (default: 16pt)
+- `body2`: Secondary body text (default: 14pt)
+- `caption1`: Small captions (default: 12pt)
+- `caption2`: Extra small captions (default: 10pt)
+
+   
+
+**Supported Formats:**
+- **Colors**: 3-digit (`#F63`), 6-digit (`#FF6633`), 8-digit (`#FF6633FF`) hex codes
+- **Images**: Use `Image.resolveAssetSource(require('./path/to/image.png'))` for bundled assets
+- **Fonts**: Choose between `serif`, `monospace`, or `default` font types
+
+**Platform Behavior:**
+- **iOS**: Uses adaptive colors that automatically respond to system appearance changes
+- **Android**: Theme is applied when the UI opens and reflects the current system appearance
+- **Theme Changes**: Require re-initializing the SDK with new theme configuration
+- **System Mode**: Automatically follows device light/dark mode settings
+- **Forced Mode**: Use `Appearance.setColorScheme('light'|'dark')` to override system settings
+
+**Note**: All theme properties are optional. If not provided, the default Octopus theme will be used.
+
+For more detailed theming information and advanced customization options, see the [Octopus Community iOS SDK theming documentation](https://doc.octopuscommunity.com/SDK/sso/ios#modify-the-theme).
+
 ### API docs
 
 For details about the Typescript API, head to the [API docs](./docs/api/README.md).
 
+#### Key Theming Functions
+
+- **`initialize(params)`**: Initialize the SDK with theme configuration
+- **`Appearance.setColorScheme(mode)`**: Force light/dark mode (React Native API)
+- **`openUI()`**: Open the Octopus UI with the current theme applied
+
 ### Example app
 
-Take a look at our [example app](./example/src/App.tsx).
+Take a look at our [example app](./example/src/App.tsx) which demonstrates:
+
+- **Complete theming system** with multiple color themes and font customizations
+- **Dark/Light mode management** with system detection and forced modes
+- **Dual-mode color themes** with separate light and dark color sets
+- **Font customization** with different font types (serif, monospace, default) and sizes
+- **Theme switching** by re-initializing the SDK with new configurations
+- **Logo customization** with bundled image assets
+- **Interactive theme controls** to test different configurations
+
+The example app includes a comprehensive theme selector interface that lets you:
+- Switch between system, light, and dark modes
+- Choose from multiple pre-defined color themes (Theme 1, 2, 3, or None)
+- Customize font types (default, serif, monospace) and sizes (small, default, large)
+- Toggle custom logo display
+- See theme changes applied when the UI reopens
+
+This is the perfect starting point to understand how to implement theming in your own React Native app.
 
 ## Troubleshooting
 

package/android/src/main/java/com/octopuscommunity/octopusreactnativesdk/OctopusReactNativeSdkModule.kt

@@ -63,6 +63,88 @@ class OctopusReactNativeSdkModule(reactContext: ReactApplicationContext) :
     eventEmitter.removeListeners(count)
   }
 
+  @ReactMethod
+  fun updateColorScheme(colorScheme: String?, promise: Promise) {
+    // Update the theme config with the new color scheme
+    val currentThemeConfig = OctopusThemeManager.getThemeConfig()
+    if (currentThemeConfig != null) {
+      val updatedThemeConfig = currentThemeConfig.copy(colorScheme = colorScheme)
+      OctopusThemeManager.setThemeConfig(updatedThemeConfig)
+    }
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  fun updateTheme(themeOptions: ReadableMap, promise: Promise) {
+    try {
+      // Parse theme using the standard initializer
+      val themeConfig = sdkInitializer.parseThemeConfig(themeOptions)
+      OctopusThemeManager.setThemeConfig(themeConfig)
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("UPDATE_THEME_ERROR", "Failed to update theme", e)
+    }
+  }
+  
+  private fun parseColor(colorString: String?): String? {
+    if (colorString == null) return null
+    
+    return try {
+      // Validate that the color string is a valid hex color
+      android.graphics.Color.parseColor(colorString)
+      // Return the original string if parsing succeeds
+      colorString
+    } catch (e: IllegalArgumentException) {
+      // Invalid color format - return null to skip this color
+      null
+    }
+  }
+  
+  private fun parseFontsConfig(fontsMap: ReadableMap): OctopusFontsConfig? {
+    // Use pre-processed configuration from TypeScript layer
+    val parsedConfig = fontsMap.getMap("parsedConfig")
+    if (parsedConfig != null) {
+      return parsePreProcessedFontsConfig(parsedConfig)
+    }
+    
+    return null
+  }
+  
+  private fun parsePreProcessedFontsConfig(parsedConfig: ReadableMap): OctopusFontsConfig? {
+    val textStylesMap = parsedConfig.getMap("textStyles")
+    val textStyles = mutableMapOf<String, OctopusTextStyleConfig>()
+    
+    // Parse pre-processed font configuration from TypeScript layer
+    textStylesMap?.let { textStylesMap ->
+      val textStyleKeys = arrayOf("title1", "title2", "body1", "body2", "caption1", "caption2")
+      
+      textStyleKeys.forEach { key ->
+        val textStyleMap = textStylesMap.getMap(key)
+        textStyleMap?.let { style ->
+          val fontType = style.getString("fontType")
+          val fontSize = if (style.hasKey("fontSize")) style.getDouble("fontSize") else Double.NaN
+          
+          if (fontType != null || (!fontSize.isNaN() && fontSize > 0)) {
+            textStyles[key] = OctopusTextStyleConfig(
+              fontType = fontType,
+              fontSize = if (fontSize.isNaN() || fontSize <= 0) null else fontSize
+            )
+          }
+        }
+      }
+    }
+    
+    // Only create fonts config if we have text styles
+    if (textStyles.isNotEmpty()) {
+      return OctopusFontsConfig(
+        textStyles = textStyles
+      )
+    }
+    
+    return null
+  }
+
+
   companion object {
     const val NAME = "OctopusReactNativeSdk"
   }

package/android/src/main/java/com/octopuscommunity/octopusreactnativesdk/OctopusSDKInitializer.kt

@@ -5,6 +5,7 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableMap
 import com.octopuscommunity.sdk.OctopusSDK
 import com.octopuscommunity.sdk.domain.model.ConnectionMode
+import android.graphics.Color
 
 class OctopusSDKInitializer {
 
@@ -17,6 +18,11 @@ class OctopusSDKInitializer {
 
     try {
       val connectionMode = parseConnectionMode(options)
+      
+      // Store theme configuration for later use in UI
+      val themeConfig = parseThemeConfig(options)
+      OctopusThemeManager.setThemeConfig(themeConfig)
+      
       OctopusSDK.initialize(
         context = context,
         apiKey = apiKey,
@@ -29,6 +35,148 @@ class OctopusSDKInitializer {
       promise.reject("INITIALIZE_ERROR", "Failed to initialize Octopus SDK", e)
     }
   }
+  
+  fun parseThemeConfig(options: ReadableMap): OctopusThemeConfig? {
+    
+    val themeMap = options.getMap("theme")
+    val colorScheme = options.getString("colorScheme") // Get colorScheme from React Native
+    
+    var primaryColor: String? = null
+    var primaryLowContrastColor: String? = null
+    var primaryHighContrastColor: String? = null
+    var onPrimaryColor: String? = null
+    var logoSource: ReadableMap? = null
+    var fontsConfig: OctopusFontsConfig? = null
+    
+    // Parse colors from theme if available
+    themeMap?.let { theme ->
+      val colorsMap = theme.getMap("colors")
+      colorsMap?.let { colors ->
+        // Check if this is a dual-mode theme (has light and dark properties)
+        val lightColors = colors.getMap("light")
+        val darkColors = colors.getMap("dark")
+        
+        if (lightColors != null && darkColors != null) {
+          // Dual-mode theme - select colors based on current color scheme
+          val selectedColors = if (colorScheme == "dark") darkColors else lightColors
+          primaryColor = parseColor(if (selectedColors.hasKey("primary")) selectedColors.getString("primary") else null)
+          primaryLowContrastColor = parseColor(if (selectedColors.hasKey("primaryLowContrast")) selectedColors.getString("primaryLowContrast") else null)
+          primaryHighContrastColor = parseColor(if (selectedColors.hasKey("primaryHighContrast")) selectedColors.getString("primaryHighContrast") else null)
+          onPrimaryColor = parseColor(if (selectedColors.hasKey("onPrimary")) selectedColors.getString("onPrimary") else null)
+        } else {
+          // Single-mode theme (backward compatibility)
+          primaryColor = parseColor(if (colors.hasKey("primary")) colors.getString("primary") else null)
+          primaryLowContrastColor = parseColor(if (colors.hasKey("primaryLowContrast")) colors.getString("primaryLowContrast") else null)
+          primaryHighContrastColor = parseColor(if (colors.hasKey("primaryHighContrast")) colors.getString("primaryHighContrast") else null)
+          onPrimaryColor = parseColor(if (colors.hasKey("onPrimary")) colors.getString("onPrimary") else null)
+        }
+      }
+      
+      // Handle logo from theme
+      val logoMap = theme.getMap("logo")
+      logoMap?.let { logo ->
+        val imageSource = logo.getMap("image")
+        if (imageSource != null) {
+          logoSource = imageSource
+        }
+      }
+      
+      // Handle fonts from theme - use pre-processed configuration from TypeScript layer
+      val fontsMap = theme.getMap("fonts")
+      fontsMap?.let { fonts ->
+        val parsedConfig = fonts.getMap("parsedConfig")
+        if (parsedConfig != null) {
+          fontsConfig = parsePreProcessedFontsConfig(parsedConfig)
+        }
+      }
+    }
+    
+    // Handle logo at root level (for backward compatibility)
+    if (logoSource == null) {
+      val rootLogoMap = options.getMap("logo")
+      rootLogoMap?.let { logo ->
+        val imageSource = logo.getMap("image")
+        if (imageSource != null) {
+          logoSource = imageSource
+        }
+      }
+    }
+    
+    // Only create theme config if we have at least one customization
+    if (primaryColor != null || logoSource != null || colorScheme != null || fontsConfig != null) {
+      return OctopusThemeConfig(
+        primaryColor = primaryColor,
+        primaryLowContrastColor = primaryLowContrastColor,
+        primaryHighContrastColor = primaryHighContrastColor,
+        onPrimaryColor = onPrimaryColor,
+        logoSource = logoSource,
+        colorScheme = colorScheme,
+        fonts = fontsConfig
+      )
+    }
+    
+    return null
+  }
+  
+  private fun parsePreProcessedFontsConfig(parsedConfig: ReadableMap): OctopusFontsConfig? {
+    val textStylesMap = parsedConfig.getMap("textStyles")
+    val textStyles = mutableMapOf<String, OctopusTextStyleConfig>()
+    
+    // Parse pre-processed font configuration from TypeScript layer
+    textStylesMap?.let { textStylesMap ->
+      val textStyleKeys = arrayOf("title1", "title2", "body1", "body2", "caption1", "caption2")
+      
+      textStyleKeys.forEach { key ->
+        val textStyleMap = textStylesMap.getMap(key)
+        textStyleMap?.let { style ->
+          val fontType = style.getString("fontType")
+          val fontSize = if (style.hasKey("fontSize")) style.getDouble("fontSize") else Double.NaN
+          
+          if (fontType != null || (!fontSize.isNaN() && fontSize > 0)) {
+            textStyles[key] = OctopusTextStyleConfig(
+              fontType = fontType,
+              fontSize = if (fontSize.isNaN() || fontSize <= 0) null else fontSize
+            )
+          }
+        }
+      }
+    }
+    
+    // Only create fonts config if we have text styles
+    if (textStyles.isNotEmpty()) {
+      return OctopusFontsConfig(
+        textStyles = textStyles
+      )
+    }
+    
+    return null
+  }
+
+  
+  private fun extractResourceNameFromUri(uri: String): String? {
+    // Extract resource name from React Native image URI
+    // Examples: "logo.png" -> "logo", "images/logo.png" -> "logo"
+    return try {
+      val fileName = uri.substringAfterLast("/")
+      fileName.substringBeforeLast(".")
+    } catch (e: Exception) {
+      null
+    }
+  }
+  
+  private fun parseColor(colorString: String?): String? {
+    if (colorString == null) return null
+    
+    return try {
+      // Validate that the color string is a valid hex color
+      Color.parseColor(colorString)
+      // Return the original string if parsing succeeds
+      colorString
+    } catch (e: IllegalArgumentException) {
+      // Invalid color format - return null to skip this color
+      null
+    }
+  }
 
   private fun parseConnectionMode(options: ReadableMap): ConnectionMode {
     val connectionModeMap = options.getMap("connectionMode")
@@ -36,7 +184,7 @@ class OctopusSDKInitializer {
       "sso" -> {
         ConnectionMode.SSO(
           appManagedFields = ProfileFieldMapper.fromReactNativeArray(
-            connectionModeMap.getArray("appManagedFields")
+            if (connectionModeMap.hasKey("appManagedFields")) connectionModeMap.getArray("appManagedFields") else null
           )
         )
       }

package/android/src/main/java/com/octopuscommunity/octopusreactnativesdk/OctopusThemeConfig.kt

@@ -0,0 +1,22 @@
+package com.octopuscommunity.octopusreactnativesdk
+
+import com.facebook.react.bridge.ReadableMap
+
+data class OctopusTextStyleConfig(
+  val fontType: String?, // "serif", "monospace", or "default"
+  val fontSize: Double? // Font size in points
+)
+
+data class OctopusFontsConfig(
+  val textStyles: Map<String, OctopusTextStyleConfig>?
+)
+
+data class OctopusThemeConfig(
+  val primaryColor: String?,
+  val primaryLowContrastColor: String?,
+  val primaryHighContrastColor: String?,
+  val onPrimaryColor: String?,
+  val logoSource: ReadableMap?,
+  val colorScheme: String?, // "light" or "dark"
+  val fonts: OctopusFontsConfig?
+)

package/android/src/main/java/com/octopuscommunity/octopusreactnativesdk/OctopusThemeManager.kt

@@ -0,0 +1,11 @@
+package com.octopuscommunity.octopusreactnativesdk
+
+object OctopusThemeManager {
+  private var themeConfig: OctopusThemeConfig? = null
+  
+  fun setThemeConfig(config: OctopusThemeConfig?) {
+    themeConfig = config
+  }
+  
+  fun getThemeConfig(): OctopusThemeConfig? = themeConfig
+}