@billdog.io/react-native 1.0.0-beta.2

package/src/LocalizationResolver.ts

@@ -0,0 +1,311 @@
+import { Platform, NativeModules } from 'react-native';
+import { PaywallConfiguration, PaywallComponent } from './types';
+import { BillDogConfiguration } from './BillDogConfiguration';
+
+/**
+ * Properties that can be localized
+ */
+const LOCALIZABLE_PROPERTIES = new Set([
+  'text', 'title', 'subtitle', 'label', 'placeholder',
+  'buttonText', 'ctaText', 'description', 'content',
+  'headerText', 'footerText', 'disclaimer'
+]);
+
+/**
+ * Right-to-left languages. CLDR-aligned 11-code set — kept identical to
+ * iOS `PaywallRenderer.swift rtlLocales` and Android
+ * `PaywallScreen.kt rtlLocales` so layout direction is consistent across
+ * every platform.
+ */
+const RTL_LOCALES = new Set([
+  'ar', 'he', 'fa', 'ur', 'ps', 'sd', 'yi', 'ku', 'ckb', 'dv', 'ug',
+]);
+
+/**
+ * Client-side localization resolver for React Native SDK
+ * Resolves localized text based on device locale with fallback to baseLocale
+ */
+export class LocalizationResolver {
+  private localizations?: Record<string, Record<string, string>>;
+  private baseLocale: string;
+  private selectedLocale: string;
+
+  constructor(
+    localizations?: Record<string, Record<string, string>>,
+    baseLocale: string = 'en',
+    explicitLocale?: string
+  ) {
+    this.localizations = localizations;
+    this.baseLocale = baseLocale;
+    // Priority: explicit locale > global config override > device locale
+    this.selectedLocale = explicitLocale ?? this.getEffectiveLocale();
+  }
+
+  /**
+   * Get the effective locale. Precedence mirrors Android
+   * `BillDogConfig.getEffectiveLocale` (BillDogConfig.kt:150-152):
+   *   runtime locale override > device locale > "en".
+   *
+   * Public + static so callers (e.g. WebViewPaywall's locale bridge) can
+   * resolve the active locale without constructing a resolver.
+   */
+  static getEffectiveLocale(): string {
+    const configOverride = BillDogConfiguration.getLocaleOverride();
+    if (configOverride && configOverride.trim()) {
+      return configOverride;
+    }
+    return LocalizationResolver.detectDeviceLocale();
+  }
+
+  /** Instance accessor — defers to the canonical static resolver. */
+  private getEffectiveLocale(): string {
+    return LocalizationResolver.getEffectiveLocale();
+  }
+
+  /**
+   * Returns true when `locale`'s language belongs to a right-to-left
+   * script. Matches against the language portion only (e.g. `ar-EG` → `ar`),
+   * mirroring Android `PaywallScreen.kt:431-458`.
+   */
+  static isRtlLocale(locale: string | null | undefined): boolean {
+    if (!locale) return false;
+    const language = locale.split(/[-_]/)[0]?.toLowerCase() ?? '';
+    return RTL_LOCALES.has(language);
+  }
+
+  /** Detect the device locale from the platform native modules. */
+  static detectDeviceLocale(): string {
+    try {
+      if (Platform.OS === 'ios') {
+        return (
+          NativeModules.SettingsManager?.settings?.AppleLocale?.split('_')[0] ||
+          NativeModules.SettingsManager?.settings?.AppleLanguages?.[0]?.split('-')[0] ||
+          'en'
+        );
+      } else if (Platform.OS === 'android') {
+        return NativeModules.I18nManager?.localeIdentifier?.split('_')[0] || 'en';
+      }
+    } catch {
+      // Fall through to default.
+    }
+    return 'en';
+  }
+
+  /**
+   * Set the active locale for resolution
+   */
+  setLocale(locale: string): void {
+    this.selectedLocale = locale;
+  }
+
+  /**
+   * Get the currently selected locale
+   */
+  getSelectedLocale(): string {
+    return this.selectedLocale;
+  }
+
+  /**
+   * Get the base locale (source language)
+   */
+  getBaseLocale(): string {
+    return this.baseLocale;
+  }
+
+  /**
+   * Find the matching locale key using the canonical 4-step matcher.
+   * Mirrors Android `LocalizationResolver.findLocaleKey` (LocalizationResolver.kt:50-86)
+   * and iOS `LocalizationResolver.findLocaleKey` exactly:
+   *   1. exact match
+   *   2. case-insensitive match
+   *   3. separator-normalized match (en-US ↔ en_US)
+   *   4. language-only fallback (en-US → en, or en → first en-* regional)
+   */
+  private findLocaleKey(locale: string): string | undefined {
+    if (!this.localizations || !locale) return undefined;
+    const keys = Object.keys(this.localizations);
+
+    // Step 1: exact match
+    if (this.localizations[locale]) return locale;
+
+    // Step 2: case-insensitive match
+    const lower = locale.toLowerCase();
+    const ciMatch = keys.find(k => k.toLowerCase() === lower);
+    if (ciMatch) return ciMatch;
+
+    // Step 3: separator-normalized match
+    const alt = locale.includes('-')
+      ? locale.replace(/-/g, '_')
+      : locale.replace(/_/g, '-');
+    if (alt !== locale) {
+      if (this.localizations[alt]) return alt;
+      const altLower = alt.toLowerCase();
+      const altMatch = keys.find(k => k.toLowerCase() === altLower);
+      if (altMatch) return altMatch;
+    }
+
+    // Step 4: language-only fallback
+    const languageOnly = locale.split(/[-_]/)[0] ?? '';
+    if (languageOnly) {
+      const langLower = languageOnly.toLowerCase();
+      // Prefer an exact-language key (e.g. "en") over a regional variant
+      const exactLang = keys.find(k => k.toLowerCase() === langLower);
+      if (exactLang) return exactLang;
+      // Otherwise any regional variant matching the language
+      const regional = keys.find(
+        k => (k.split(/[-_]/)[0] ?? '').toLowerCase() === langLower
+      );
+      if (regional) return regional;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Check if current locale is the base locale
+   */
+  isBaseLocale(): boolean {
+    return this.selectedLocale.toLowerCase() === this.baseLocale.toLowerCase();
+  }
+
+  /**
+   * Get available locales from the localization data
+   */
+  getAvailableLocales(): Set<string> {
+    const locales = new Set<string>([this.baseLocale]);
+    if (this.localizations) {
+      Object.keys(this.localizations).forEach(key => locales.add(key));
+    }
+    return locales;
+  }
+
+  /**
+   * Resolve a localization key to its translated value
+   * Falls back to defaultValue if translation not found
+   */
+  resolve(key: string, defaultValue: string): string {
+    // If selected locale is base locale, return default (original) value
+    if (this.isBaseLocale()) {
+      return defaultValue;
+    }
+
+    // Try to find translation for selected locale (case-insensitive)
+    const matchedKey = this.findLocaleKey(this.selectedLocale);
+    const translations = matchedKey ? this.localizations![matchedKey] : undefined;
+    const translated = translations?.[key];
+
+    if (translated !== undefined) {
+      return translated;
+    }
+
+    // Log missing translation for debugging
+    console.debug(
+      `[LocalizationResolver] Translation not found for key '${key}' in locale '${this.selectedLocale}', using default`
+    );
+    return defaultValue;
+  }
+
+  /**
+   * Resolve a variable value with localization support
+   * Variable keys are prefixed with locale for lookup
+   */
+  resolveVariable(variableKey: string, defaultValue: string): string {
+    if (this.isBaseLocale()) {
+      return defaultValue;
+    }
+
+    // Try locale-prefixed key first (e.g., "es.headline" for Spanish)
+    const localizedKey = `${this.selectedLocale}.${variableKey}`;
+    const matchedKey = this.findLocaleKey(this.selectedLocale);
+    const translations = matchedKey ? this.localizations![matchedKey] : undefined;
+
+    return (
+      translations?.[localizedKey] ??
+      translations?.[variableKey] ??
+      defaultValue
+    );
+  }
+
+  /**
+   * Resolve all localizable properties in a component.
+   *
+   * Lookup keys are componentId-prefixed (`<componentId>.<propertyName>`),
+   * matching the shape the dashboard `LocalizationPanel` writes and the
+   * Android `VariableResolver.resolveComponent` runtime path
+   * (VariableResolver.kt:124-156) + iOS `LocalizationResolver.swift:194-198`.
+   * Previously this looked up the source string itself as the key, which
+   * never matched the dashboard-authored translation maps.
+   */
+  resolveComponent(component: PaywallComponent): PaywallComponent {
+    const resolvedProperties: Record<string, any> = {};
+    const componentId = component.id ?? '';
+
+    for (const [key, value] of Object.entries(component.properties || {})) {
+      if (typeof value === 'string' && LOCALIZABLE_PROPERTIES.has(key)) {
+        const localizationKey = componentId ? `${componentId}.${key}` : key;
+        resolvedProperties[key] = this.resolve(localizationKey, value);
+      } else {
+        resolvedProperties[key] = value;
+      }
+    }
+
+    // Recursively resolve children
+    const resolvedChildren = component.children?.map(child =>
+      this.resolveComponent(child)
+    );
+
+    return {
+      ...component,
+      properties: resolvedProperties,
+      children: resolvedChildren,
+    };
+  }
+
+  /**
+   * Resolve all components in a configuration
+   */
+  resolveConfiguration(config: PaywallConfiguration): PaywallConfiguration {
+    return {
+      ...config,
+      components: config.components.map(c => this.resolveComponent(c)),
+    };
+  }
+
+  // Factory Methods
+
+  /**
+   * Create resolver from PaywallConfiguration
+   * Respects global locale override from BillDogConfiguration
+   */
+  static fromConfiguration(config: PaywallConfiguration): LocalizationResolver {
+    return new LocalizationResolver(
+      config.localizations,
+      config.baseLocale ?? 'en'
+    );
+  }
+
+  /**
+   * Create resolver with device locale auto-detected
+   * Respects global locale override from BillDogConfiguration
+   */
+  static withDeviceLocale(config: PaywallConfiguration): LocalizationResolver {
+    return new LocalizationResolver(
+      config.localizations,
+      config.baseLocale ?? 'en'
+    );
+  }
+
+  /**
+   * Create resolver with specific locale (overrides global config)
+   */
+  static withLocale(
+    config: PaywallConfiguration,
+    locale: string
+  ): LocalizationResolver {
+    return new LocalizationResolver(
+      config.localizations,
+      config.baseLocale ?? 'en',
+      locale
+    );
+  }
+}

package/src/NativePaywallView.tsx

@@ -0,0 +1,132 @@
+/**
+ * NativePaywallView — renders a BillDog paywall by embedding the NATIVE paywall view
+ * (SwiftUI/UIKit on iOS, Jetpack Compose on Android) via a legacy (Paper) native
+ * component (`BDPaywallView`). This is the thin-bridge "Option 2" inline path: the
+ * native BillDog SDK renders the paywall and handles purchases; this component only
+ * hosts it and forwards its events.
+ *
+ * The pure-JS `PaywallView`/`ComponentRenderer` and `WebViewPaywall` remain available
+ * as alternative rendering strategies (e.g. for environments without the native module).
+ */
+import React from 'react';
+import {
+  requireNativeComponent,
+  UIManager,
+  StyleSheet,
+  View,
+  Text,
+  Platform,
+  type NativeSyntheticEvent,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+const COMPONENT_NAME = 'BDPaywallView';
+
+/** True only when the native view manager is actually registered on this platform. */
+const isNativeComponentAvailable =
+  UIManager.getViewManagerConfig?.(COMPONENT_NAME) != null;
+
+type PurchaseEvent = { productId: string; data?: Record<string, unknown> };
+type ErrorEvent = { message: string };
+type OpenUrlEvent = { url: string };
+type TrackEvent = { event: string; data?: Record<string, unknown> };
+
+interface NativeProps {
+  paywallIdentifier: string;
+  style?: StyleProp<ViewStyle>;
+  onLoaded?: (e: NativeSyntheticEvent<Record<string, never>>) => void;
+  onError?: (e: NativeSyntheticEvent<ErrorEvent>) => void;
+  onPurchase?: (e: NativeSyntheticEvent<PurchaseEvent>) => void;
+  onDismiss?: (e: NativeSyntheticEvent<Record<string, never>>) => void;
+  onRestore?: (e: NativeSyntheticEvent<Record<string, never>>) => void;
+  onOpenUrl?: (e: NativeSyntheticEvent<OpenUrlEvent>) => void;
+  onTrackEvent?: (e: NativeSyntheticEvent<TrackEvent>) => void;
+}
+
+// Only bind the native component when it exists — requireNativeComponent otherwise
+// logs a hard error on some RN versions.
+const BDPaywallViewNative = isNativeComponentAvailable
+  ? requireNativeComponent<NativeProps>(COMPONENT_NAME)
+  : null;
+
+export interface NativePaywallViewProps {
+  /** Placement / paywall identifier to load. */
+  identifier: string;
+  style?: ViewStyle;
+  /** Fired after a completed purchase (productId + native result fields). */
+  onPurchase?: (productId: string, data?: Record<string, unknown>) => void;
+  onDismiss?: () => void;
+  onRestore?: () => void;
+  onOpenUrl?: (url: string) => void;
+  onTrackEvent?: (event: string, data?: Record<string, unknown>) => void;
+  onLoaded?: () => void;
+  onError?: (message: string) => void;
+  /** Rendered when the native paywall component is unavailable on this platform. */
+  fallback?: React.ReactNode;
+}
+
+/**
+ * Inline native paywall. Requires the `BDPaywallView` native component (iOS
+ * `BillDogPaywallViewManager`, Android `BillDogPaywallViewManager`). When it is not
+ * registered, renders `fallback` (or nothing) instead of crashing.
+ */
+export function NativePaywallView(props: NativePaywallViewProps): React.ReactElement | null {
+  const {
+    identifier,
+    style,
+    onPurchase,
+    onDismiss,
+    onRestore,
+    onOpenUrl,
+    onTrackEvent,
+    onLoaded,
+    onError,
+    fallback,
+  } = props;
+
+  if (BDPaywallViewNative == null) {
+    if (fallback != null) return <>{fallback}</>;
+    if (__DEV__) {
+      return (
+        <View style={[styles.fill, styles.center, style]}>
+          <Text style={styles.warn}>
+            BillDog: native paywall component &quot;{COMPONENT_NAME}&quot; is not registered
+            on {Platform.OS}. Ensure the native SDK is linked, or use PaywallView /
+            WebViewPaywall.
+          </Text>
+        </View>
+      );
+    }
+    return null;
+  }
+
+  return (
+    <BDPaywallViewNative
+      paywallIdentifier={identifier}
+      style={[styles.fill, style]}
+      onLoaded={() => onLoaded?.()}
+      onError={(e) => onError?.(e.nativeEvent?.message ?? 'Unknown paywall error')}
+      onPurchase={(e) =>
+        onPurchase?.(e.nativeEvent?.productId ?? '', e.nativeEvent?.data)
+      }
+      onDismiss={() => onDismiss?.()}
+      onRestore={() => onRestore?.()}
+      onOpenUrl={(e) => onOpenUrl?.(e.nativeEvent?.url ?? '')}
+      onTrackEvent={(e) =>
+        onTrackEvent?.(e.nativeEvent?.event ?? '', e.nativeEvent?.data)
+      }
+    />
+  );
+}
+
+/** Whether the native paywall component is available on the current platform. */
+export const isNativePaywallAvailable = isNativeComponentAvailable;
+
+const styles = StyleSheet.create({
+  fill: { flex: 1 },
+  center: { alignItems: 'center', justifyContent: 'center', padding: 16 },
+  warn: { color: '#B00020', textAlign: 'center', fontSize: 13 },
+});
+
+export default NativePaywallView;