@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/presentation/components/paywall/PaywallModal.md

@@ -2,443 +2,93 @@
 
 Modal paywall component for subscription upgrade.
 
-## Import
+## Location
 
-```typescript
-import { PaywallModal } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Props
+**File**: `src/presentation/components/paywall/PaywallModal.tsx`
 
-```typescript
-interface PaywallModalProps {
-  isVisible: boolean;
-  onClose: () => void;
-  config?: PaywallConfig;
-  onPurchase?: (result: PurchaseResult) => void;
-  isLoading?: boolean;
-  translations?: PaywallTranslations;
-  theme?: 'light' | 'dark';
-}
-```
+**Type**: Component
 
-## Basic Usage
+## Strategy
 
-```typescript
-function PaywallExample() {
-  const [isVisible, setIsVisible] = useState(false);
+### Paywall Display Flow
 
-  return (
-    <>
-      <Button onPress={() => setIsVisible(true)} title="Show Paywall" />
+1. **Modal Visibility**: Control visibility via isVisible prop
+2. **Configuration**: Display features, pricing, and benefits
+3. **Package Display**: Show available subscription packages
+4. **Purchase Handling**: Handle purchase initiation and completion
+5. **Close Behavior**: Handle modal close/dismissal
+6. **Responsive Design**: Adapt to different screen sizes
 
-      <PaywallModal
-        isVisible={isVisible}
-        onClose={() => setIsVisible(false)}
-      />
-    </>
-  );
-}
-```
+### Integration Points
 
-## Configuration
+- **usePaywallVisibility**: For modal visibility control
+- **useSubscriptionPackages**: For available packages
+- **usePaywallOperations**: For purchase handling
+- **Analytics**: For tracking impressions and conversions
+- **Navigation**: For post-purchase navigation
 
-### Basic Config
+## Restrictions
 
-```typescript
-<PaywallModal
-  isVisible={isVisible}
-  onClose={handleClose}
-  config={{
-    title: 'Unlock Premium',
-    description: 'Get unlimited access to all features',
-    features: [
-      { icon: '⭐', text: 'Unlimited Access' },
-      { icon: '🚀', text: 'AI-Powered Tools' },
-      { icon: '🛡️', text: 'Ad-Free Experience' },
-    ],
-  }}
-/>
-```
+### REQUIRED
 
-### Advanced Config
+- **Visibility Control**: MUST control via isVisible prop
+- **Close Handler**: MUST provide onClose callback
+- **Purchase Handler**: MUST implement onPurchase callback
+- **Package Display**: MUST show available packages
 
-```typescript
-const paywallConfig: PaywallConfig = {
-  title: 'Go Premium',
-  description: 'Join thousands of premium users',
-  features: [
-    {
-      icon: '💎',
-      text: 'Premium Content',
-      description: 'Access exclusive articles and videos',
-      highlight: true,
-    },
-    {
-      icon: '⚡',
-      text: 'Faster Processing',
-      description: 'Get results in seconds, not minutes',
-    },
-    {
-      icon: '💬',
-      text: 'Priority Support',
-      description: '24/7 dedicated support team',
-    },
-    {
-      icon: '🎁',
-      text: 'Exclusive Features',
-      description: 'Early access to new features',
-    },
-  ],
-  theme: 'dark',
-  showCloseButton: true,
-  closeOnBackdropPress: false,
-};
+### PROHIBITED
 
-<PaywallModal
-  isVisible={isVisible}
-  onClose={handleClose}
-  config={paywallConfig}
-/>
-```
+- **NEVER** trap users without close option
+- **NEVER** show without user trigger or clear reason
+- **DO NOT** show too frequently
+- **DO NOT** hide pricing information
 
-## Purchase Handling
+### CRITICAL SAFETY
 
-### With Callback
+- **ALWAYS** provide clear close button
+- **NEVER** trap users in modal
+- **MUST** handle all purchase outcomes
+- **ALWAYS** show pricing clearly
 
-```typescript
-<PaywallModal
-  isVisible={isVisible}
-  onClose={handleClose}
-  onPurchase={(result) => {
-    if (result.success) {
-      Alert.alert('Success', 'Welcome to Premium!');
-      setIsVisible(false);
-    } else {
-      Alert.alert('Error', result.error?.message || 'Purchase failed');
-    }
-  }}
-/>
-```
+## AI Agent Guidelines
 
-### With Custom Handler
+### When Implementing Paywall Modals
 
-```typescript
-function PaywallWithHandler() {
-  const { handlePurchase, isLoading } = usePaywallActions();
+1. **Always** provide clear close button
+2. **Always** show pricing transparently
+3. **Always** handle all purchase outcomes
+4. **Always** track impressions and conversions
+5. **Never** trap users without exit
 
-  const onPurchase = async (pkg: Package) => {
-    const result = await handlePurchase(pkg);
+### Integration Checklist
 
-    if (result.success) {
-      // Analytics
-      analytics.track('purchase_completed', {
-        packageId: pkg.identifier,
-        revenue: pkg.product.price,
-      });
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Control visibility via isVisible prop
+- [ ] Implement onClose callback
+- [ ] Implement onPurchase callback
+- [ ] Configure features and benefits
+- [ ] Display package options
+- [ ] Handle loading states
+- [ ] Track analytics events
+- [ ] Test purchase flow
+- [ ] Test close behavior
+- [ ] Verify responsive design
 
-      // Navigation
-      navigation.goBack();
+### Common Patterns
 
-      // Success message
-      Toast.show({
-        type: 'success',
-        text1: 'Purchase Successful!',
-        text2: 'You are now a Premium user',
-      });
-    }
+1. **Manual Trigger**: Show on button press
+2. **Usage Limit**: Show after N free uses
+3. **Feature Gate**: Show when accessing premium feature
+4. **Time-based**: Show after certain time/usage
+5. **Event-driven**: Show on specific app events
+6. **A/B Testing**: Test different copy and layouts
 
-    return result;
-  };
+## Related Documentation
 
-  return (
-    <PaywallModal
-      isVisible={isVisible}
-      onClose={handleClose}
-      onPurchase={onPurchase}
-      isLoading={isLoading}
-    />
-  );
-}
-```
-
-## Customization
-
-### Custom Theme
-
-```typescript
-const customTheme = {
-  colors: {
-    primary: '#FF6B6B',
-    background: '#1a1a1a',
-    card: '#2d2d2d',
-    text: '#ffffff',
-    textSecondary: '#999999',
-    border: '#3d3d3d',
-  },
-  fonts: {
-    title: {
-      fontSize: 28,
-      fontWeight: 'bold',
-    },
-    body: {
-      fontSize: 16,
-    },
-  },
-  borderRadius: 16,
-};
-
-<PaywallModal
-  isVisible={isVisible}
-  onClose={handleClose}
-  theme={customTheme}
-/>
-```
-
-### Custom Package Display
-
-```typescript
-function CustomPaywall() {
-  const { packages } = useSubscriptionPackages();
-
-  return (
-    <PaywallModal
-      isVisible={isVisible}
-      onClose={handleClose}
-      config={{
-        title: 'Choose Your Plan',
-        packages: packages.map(pkg => ({
-          identifier: pkg.identifier,
-          title: pkg.product.title,
-          description: pkg.product.description,
-          price: pkg.product.priceString,
-          popular: pkg.identifier.includes('annual'),
-          savings: pkg.identifier.includes('annual')
-            ? 'Save 33%'
-            : undefined,
-        })),
-      }}
-    />
-  );
-}
-```
-
-## A/B Testing
-
-### Variant A
-
-```typescript
-const variantAConfig: PaywallConfig = {
-  title: 'Unlock Premium',
-  description: 'Get unlimited access',
-  features: [
-    { icon: '⭐', text: 'Unlimited Access' },
-    { icon: '🚀', text: 'AI Tools' },
-  ],
-};
-
-<PaywallModal
-  config={variantAConfig}
-  ...
-/>
-```
-
-### Variant B
-
-```typescript
-const variantBConfig: PaywallConfig = {
-  title: 'Join Premium Members',
-  description: 'Over 10,000 users',
-  features: [
-    { icon: '💎', text: 'Premium Content' },
-    { icon: '⚡', text: 'Priority Speed' },
-    { icon: '💬', text: 'VIP Support' },
-    { icon: '🎁', text: 'Exclusive Perks' },
-  ],
-};
-
-<PaywallModal
-  config={variantBConfig}
-  ...
-/>
-```
-
-## Translations
-
-### Multi-Language Support
-
-```typescript
-const translations = {
-  en: {
-    title: 'Unlock Premium',
-    subscribe: 'Subscribe Now',
-    features: 'Features',
-    restore: 'Restore Purchase',
-    close: 'Close',
-  },
-  tr: {
-    title: 'Premium\'e Geç',
-    subscribe: 'Şimdi Abone Ol',
-    features: 'Özellikler',
-    restore: 'Satın Almayı Geri Yükle',
-    close: 'Kapat',
-  },
-};
-
-<PaywallModal
-  translations={translations[userLanguage]}
-  ...
-/>
-```
-
-## Responsive Design
-
-The modal is responsive and adapts to:
-
-- **iPhone SE**: Compact layout
-- **iPhone 14 Pro**: Standard layout
-- **iPad**: Tablet-optimized layout
-- **Landscape**: Adjusted spacing
-
-## Performance
-
-### Lazy Loading
-
-```typescript
-function LazyPaywall() {
-  const [showPaywall, setShowPaywall] = useState(false);
-
-  return (
-    <>
-      <Button onPress={() => setShowPaywall(true)} />
-
-      {showPaywall && (
-        <PaywallModal
-          isVisible={showPaywall}
-          onClose={() => setShowPaywall(false)}
-        />
-      )}
-    </>
-  );
-}
-```
-
-### Preloading Packages
-
-```typescript
-function PreloadedPaywall() {
-  const { packages, isLoading } = useSubscriptionPackages({
-    staleTime: 5 * 60 * 1000, // 5 minutes
-  });
-
-  // Preload packages before showing paywall
-  useEffect(() => {
-    if (!packages.length) {
-      // Trigger background fetch
-      refetch();
-    }
-  }, []);
-
-  return (
-    <PaywallModal
-      isVisible={isVisible}
-      config={{ packages }}
-    />
-  );
-}
-```
-
-## Best Practices
-
-1. **Track impressions** - Log when paywall is shown
-2. **Track dismissals** - Log when and why users close
-3. **Test different copy** - A/B test titles and features
-4. **Use social proof** - Show user count or ratings
-5. **Highlight savings** - Show annual savings
-6. **Make it actionable** - Clear CTA buttons
-7. **Handle orientation** - Test in landscape and portrait
-
-## Complete Example
-
-```typescript
-function CompletePaywallFlow() {
-  const { isPremium } = usePremium();
-  const [isVisible, setIsVisible] = useState(false);
-  const [paywallShown, setPaywallShown] = useState(false);
-
-  // Auto-show after 3 actions
-  const { actionCount } = useActionCounter();
-  useEffect(() => {
-    if (!isPremium && actionCount >= 3 && !paywallShown) {
-      setIsVisible(true);
-      setPaywallShown(true);
-
-      analytics.track('auto_paywall_shown', {
-        trigger: 'action_limit',
-        actions: actionCount,
-      });
-    }
-  }, [actionCount, isPremium, paywallShown]);
-
-  const handlePurchase = async (result: PurchaseResult) => {
-    if (result.success) {
-      analytics.track('purchase_completed', {
-        packageId: result.packageId,
-        revenue: result.revenue,
-        trigger: 'auto_paywall',
-      });
-
-      setIsVisible(false);
-
-      Alert.alert(
-        'Welcome to Premium!',
-        'Thank you for subscribing.'
-      );
-    } else {
-      analytics.track('purchase_failed', {
-        error: result.error?.message,
-        trigger: 'auto_paywall',
-      });
-    }
-  };
-
-  const handleClose = () => {
-    const duration = Date.now() - paywallShownAt;
-    analytics.track('paywall_closed', {
-      duration,
-      trigger: 'auto_paywall',
-    });
-
-    setIsVisible(false);
-  };
-
-  return (
-    <PaywallModal
-      isVisible={isVisible}
-      onClose={handleClose}
-      onPurchase={handlePurchase}
-      config={{
-        title: 'You\'re Awesome! 🎉',
-        description: `${actionCount} actions completed. Upgrade for unlimited access!`,
-        features: [
-          { icon: '∞', text: 'Unlimited Actions', highlight: true },
-          { icon: '⚡', text: 'Lightning Fast' },
-          { icon: '🛡️', text: 'Ad-Free Experience' },
-        ],
-      }}
-    />
-  );
-}
-```
-
-## Related Components
-
-- **PaywallScreen** - Full-screen paywall
-- **PremiumDetailsCard** - Premium status card
-- **PaywallFeedbackModal** - Feedback collection
-
-## See Also
-
-- [Paywall Domain](../../../domains/paywall/README.md)
-- [usePaywall Hooks](../../hooks/usePaywall.md)
-- [Paywall README](../feedback/README.md)
+- **usePaywall**: Paywall state management
+- **usePaywallOperations**: Purchase operations
+- **usePaywallVisibility**: Visibility control
+- **PaywallDomain**: `../../../domains/paywall/README.md`
+- **Paywall README**: `./README.md`